21hbguo / dsh-agent-board

dsh-agent-board

DSH（DeepSeek Harness）Agent 实时看板 —— 主 agent 与子代理的树形层级监控，停滞自动告警，点击直达会话。老板视角，一眼看清谁在跑、干到哪、卡没卡。

◉ 当前 主代理轮询与进度监控   ⚙ bash: npm run build …
 ┣━ ● 子代理1-调研DSH API面   调研完成，方案已定稿…
 ┃   ┗━ ● 子代理1-验证实现    完成
 ┣━ ● 子代理2-实现看板悬浮窗  ✍ 输出中…
 ┗━ ● 子代理3-写测试          ⚙ bash: pytest -x …

---

生命周期演示：子代理运行中（绿）→ 完成（蓝）→ 双击打开后转空闲（灰）

✨ 特性

	特性	说明
🎯	树形层级图	以主 agent（实心圆）为根、子代理（空心圆）为分支的层级森林；多主会话并排显示；五色状态语义：🟢绿=working（在跑）/ 🟡黄=等你判断（ask/审批挂起）/ 🔵蓝=完成（未查看）/ ⚪灰=空闲（完成且已打开过，已读弱化）/ 🔴红=停滞
⚡	SSE 实时推送	数据变化事件级推送，看板即时刷新；断线自动回退轮询兜底
🚦	三态生命周期	working（在跑）→ 完成（子代理弱化保留 5 分钟、主 agent 完成标蓝 60 分钟，点开变灰；每根最多 12 条防堆积）→ 超时消失；有在跑子代理的根自动展开
🔔	停滞自动告警	子代理静默超过阈值（默认 10 分钟）→ 自动向父会话注入 notice 提醒（GUI 可见、不唤醒模型、不耗 API 额度）——不再需要手动轮询 list_agents 催进度
📝	进展一目了然	每个节点同行显示：当前动作（正在执行的命令 ⚙ / 输出中 ✍）+ 最新答复节选 + 状态；工具与文本都是实时信号
🖱️	单击直达，行首折叠	单击任意节点打开会话；展开/折叠只走行首 ▸/▾（有子节点的根）；打开 = 已读：完成节点由蓝变灰（空闲），跨刷新持久（localStorage）；当前会话带「当前」标记
💾	跨重启持久	完成态存档落盘（~/.dsh/agent-board-archive.json），重启后不丢；会话标题/名字自动恢复
🪟	双形态看板	悬浮窗（右上角可拖拽移动、四角拖拽调大小、折叠、隐藏，位置/尺寸持久化）+ 停靠右侧面板（AionUi 文件插件风格：右侧常驻一列、内容左移不遮挡，拖拽把手调宽 220–520px、双击复位，标题点击折叠为 0 宽、右侧展开按钮）
🔀	形态切换/并存	▦ 菜单（悬浮窗 / 停靠右侧面板 / 两者并存 / 隐藏）随时切换；设置 → 常规 → Agent 看板下拉同效；侧边栏 foot「Agent 看板」按钮 = 显示/隐藏总开关；× 只关当前形态（并存时保留另一个）；全部状态持久化
🔤	字号调节	悬浮窗/停靠面板标题栏 − / + 连续调节字号（9–16px，每击 1px），双形态同步，刷新持久
📑	会话页「子代理」tab	与「对话」「轨迹」同级：左主右子分屏（左 = 主 agent 对话，右 = 子代理对话页，分隔条可拖），每容器底部输入框可直接给该子代理发消息（subagent.prompt），ask/审批挂起时卡片内原地应答
🗑️	智能过滤	空白会话（无对话）不显示；归档的主 agent 连同整棵子代理树一起隐藏

🧩 解决的问题

DSH 的后台子代理卡住时（工具死等、LLM 挂起、自循环），父会话收不到任何信号：

• subagent-settled 通知只在子代理真正结束时才投递——而卡住的 agent 可以永远不 settle；
• list_agents 只有 running/idle/ready，没有活动时间戳——"running" ≠ "活着"；
• 宿主没有 turn 级超时兜底。

dsh-agent-board 补齐这个洞：以 session 事件流为精确活动信号（毫秒级时间戳，最后一条 chunk/工具事件即"活着"），看板 + 自动告警双通道，老板不再需要轮询。

📦 安装

DSH 插件（host + client），本地构建注入即可，无需 npm 发布：

# 1. 构建（依赖 DSH checkout，自动探测 DSH_CHECKOUT）
bash scripts/build.sh          # 或 DSH 的 dev_build_plugin

# 2. 注入运行中的实例
#    使用 DSH 的 dev_inject_plugin / dev_install_package
#    注入后刷新浏览器页面，右上角出现「Agent 看板」悬浮窗（默认形态）
#    想要停靠右侧面板：悬浮窗标题栏 ▦ → 「停靠右侧面板」，或 设置 → 常规 → Agent 看板

重启后自动恢复：注入 registry + junction 持久装配（dev_inject_plugin 标准机制）。

🖥️ 显示形态（v0.2.0 新增）

形态	说明
悬浮窗（默认）	右上角常驻浮窗：拖动标题移动、点击标题折叠为单行条、× 隐藏（右下角召唤按钮恢复）
停靠右侧面板	AionUi 文件插件同款：在 shell 网格右侧追加一列轨道，聊天区自动左移不遮挡；拖左侧把手调宽（220–520px，双击复位 300px）；点击标题折叠为 0 宽，右侧出现 ◉ 展开按钮；与 aionui-panel 并存时自动共存（各自独立轨道）
两者并存	悬浮窗 + 停靠面板同时显示
隐藏	全部收起，右下角「◉ Agent 看板」召唤按钮

切换入口（任意一处切换全局生效、跨刷新持久）：

1. 悬浮窗/停靠面板标题栏的 ▦ 菜单；
2. 设置 → 常规 → Agent 看板 下拉（悬浮窗 / 停靠右侧面板 / 两者并存 / 隐藏）；
3. 侧边栏 foot 「Agent 看板」按钮：显示/隐藏总开关。

📑 会话页「子代理」tab（v0.3.0）

进入任意主 agent 会话后，tab 栏出现第三个 tab 「子代理」（与「对话」「轨迹」同级，仅会话页渲染）：

[对话] [轨迹] [子代理]
├────────────────────────────┬───────────────────────────┐
│ 主 agent 对话（markdown）    │ ● 子代理1  标题…  [跳转]    │
│                             │   ┌────────────────────┐  │
│                             │   │ 子代理对话页         │  │
│                             │   │ （气泡+markdown）    │  │
│                             │   └────────────────────┘  │
│                             │  [ 输入框…… ] (Enter 发送) │
│   ← 可拖拽分隔条 →           ├───────────────────────────┤
│                             │ ● 子代理2 …              │
└────────────────────────────┴───────────────────────────┘

• 左主右子分屏：左 = 主 agent 完整对话流；右 = 该会话的直属子代理（depth 1）列表，每容器 = 完整对话页（用户右对齐气泡 / 助手 markdown 代码块 / 工具调用摘要）；中间分隔条拖拽调左右比例（rAF 丝滑、持久化）
• 每容器底部输入框：点击容器即激活其输入框，Enter/按钮发送 → 直接给该子代理发消息（宿主正牌 subagent.prompt 通道），子代理回复自动刷新显示
• 提问/审批原地应答：子代理 ask 挂起（waiting 黄卡）时，卡片内出现提问卡（选项单选/多选/自由文本 + 提交/取消）或审批卡（允许一次/拒绝）——不切 tab 直接应答（mux WebSocket + /api/respond）
• 筛选规则与看板一致：running 恒显、完成态 5 分钟、空白会话不显示、归档级联隐藏

⚙️ 配置

参数	默认	说明
scanIntervalMs	60000	停滞扫描周期
stallThresholdMs	600000	静默多久算停滞（10 分钟）
remindIntervalMs	600000	同一子代理两次提醒最小间隔

环境变量覆盖：DSH_AGENT_BOARD_SCAN_MS / DSH_AGENT_BOARD_STALL_MS / DSH_AGENT_BOARD_REMIND_MS（毫秒，重启或重载后生效）。

🔧 工作原理

1. 活动记账：监听全局 session/event（每个事件自带毫秒时间戳），维护每个会话的「最后活动时间」「最新答复节选」「当前动作」——工具执行中最后事件是 tool/call（含命令），流式输出中最后事件是 assistant/chunk，天然可推断"正在做什么"；
2. 停滞检测：定时扫描 running 子代理，静默超阈值 → 向父会话注入 {kind:'plugin', form:'notice'}（GUI 可见、不唤醒模型）； 2b. 等待人工检测：ask 类工具（工具名以 ask 开头）tool/call 后无 tool/result、或 approval/asked 审批挂起 → 标 waiting（黄色圈 + 🔔 等你判断），应答/决定后自动清除；
3. 完成存档：子代理 settle 时把最终信息（创建名/答复/父会话）存档并落盘——完成态弱化保留 5 分钟（每根最多展示 12 条防堆积）；主 agent 每轮 turn 结束标完成（蓝），保留 60 分钟，点开已读转灰；
4. 实时推送：数据变化（任何相关事件，500ms 节流合并）→ SSE 推送 changed 信号 → 浏览器立即拉快照；2s 轮询作兜底；
5. 树形组装：快照返回所有 live 顶层会话（roots）+ 子代理（rows），浏览器按 parentSession 血缘组装成森林，每个主 agent 一棵树。

状态模型

working ──完成──▶ 完成（子代理蓝 5 分钟 / 主 agent 蓝 60 分钟）──点开──▶ 灰（已读）──超时──▶ 消失
 绿                    │
等待人工（ask/审批挂起）──应答──▶ 恢复原状态（黄色）
停滞（静默超阈值）──活动恢复──▶ 绿
 红

有在跑子代理的根默认展开；行首 ▸/▾ 折叠；单击任意节点打开会话（打开 = 已读）。

🗂️ API

端点	说明
GET /api/agent-board/agents	JSON 快照（roots + rows + label/action/reply/status）
GET /api/agent-board/stream	SSE 数据变化信号（data: changed）

📄 License

BSD-3-Clause