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 / 蓝=完成 / 灰=已读空闲 / 红=停滞）

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

完成态 已读态

✨ 特性

| | 特性 | 说明 |
|---|---|---|
| 🎯 | 树形层级图 | 以主 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