dsh-agent-board

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

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

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

✨ 特性

🧩 解决的问题

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 新增）

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

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 分钟、空白会话不显示、归档级联隐藏

⚙️ 配置

环境变量覆盖：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

📄 License

BSD-3-Clause