dsh-agent-board

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

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

---

✨ 特性

	特性	说明
🎯	树形层级图	以主 agent（实心圆）为根、子代理（空心圆）为分支的层级森林；多主会话并排显示；四色状态语义：🟢绿=working（在跑）/ 🔵蓝=完成（未查看）/ ⚪灰=空闲（完成且已打开过，已读弱化）/ 🔴红=停滞
⚡	SSE 实时推送	数据变化事件级推送，看板即时刷新；断线自动回退轮询兜底
🚦	三态生命周期	working（在跑）→ 完成（settle 后弱化保留 30 分钟，每根最多 12 条防堆积）→ 超时消失；有在跑子代理的根自动展开，子代理立即可见
🔔	停滞自动告警	子代理静默超过阈值（默认 10 分钟）→ 自动向父会话注入 notice 提醒（GUI 可见、不唤醒模型、不耗 API 额度）——不再需要手动轮询 list_agents 催进度
📝	进展一目了然	每个节点同行显示：当前动作（正在执行的命令 ⚙ / 输出中 ✍）+ 最新答复节选 + 状态；工具与文本都是实时信号
🖱️	单击直达，行首折叠	单击任意节点打开会话；展开/折叠只走行首 ▸/▾（有子节点的根）；打开 = 已读：完成节点由蓝变灰（空闲），跨刷新持久（localStorage）；当前会话带「当前」标记
💾	跨重启持久	完成态存档落盘（~/.dsh/agent-board-archive.json），重启后不丢；会话标题/名字自动恢复
🪟	常驻悬浮窗	可拖拽、折叠、隐藏（右下角召唤）；侧边栏「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 看板」悬浮窗

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

⚙️ 配置

参数	默认	说明
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 可见、不唤醒模型）；
3. 完成存档：子代理 settle 时把最终信息（创建名/答复/父会话）存档并落盘——完成态弱化保留 30 分钟（每根最多展示 12 条防堆积）；
4. 实时推送：数据变化（任何相关事件，500ms 节流合并）→ SSE 推送 changed 信号 → 浏览器立即拉快照；2s 轮询作兜底；
5. 树形组装：快照返回所有 live 顶层会话（roots）+ 子代理（rows），浏览器按 parentSession 血缘组装成森林，每个主 agent 一棵树。

状态模型

working ──完成──▶ 完成（蓝，弱化保留 30 分钟）──超时──▶ 消失
 绿                    │
                      └─ 有在跑子代理的根默认展开；整行点击折叠/展开，⤢ 打开会话

🗂️ 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