Herdr 状态上报 dsh-plugin-collection/dsh-herdr-site

dsh-herdr-site

把 dsh/cc-tui 的 agent 状态上报给 Herdr。

v0.1.0 · MIT · DSH profile 插件

这个插件做什么

Herdr 是面向 AI 编码 agent 的终端工作区管理器。它只认内置检测器识别出的 agent（opencode、claude、codex……），dsh/cc-tui 不在名单里，所以 dsh 面板在 Herdr 里只是一个普通终端进程——没有状态、没有面板跳转、不支持 --wait。

本插件通过 Herdr 官方的自定义集成协议（pane report-agent / pane release-agent）上报 dsh agent 的状态：

- 回合进行中上报 working
- 没有活跃 driver 时上报 idle
- 模型停在 ask_user_question 上等人回答时上报 blocked

dsh 本身只有 running/idle 两态，所以 blocked 是装这个插件的主要理由：模型
等你回答的那一刻会在 Herdr 里显示出来，而不是看起来像在忙。该状态从会话事件流（ask_user_question 的 tool/call / tool/result）推导，以 callId 关联，重放或乱序的事件流也能保持一致。

状态上报打通后，Herdr 的面板跳转和 --wait 对 dsh 面板同样生效。blocked 上报还可以附带可选的 blockMessage，说明等待原因。

实际效果

完整生命周期实录（asciinema 录制）：回合进行中面板显示 working，模型停在 ask_user_question 上时翻转为 blocked，回答后恢复。

生命周期录屏

状态映射

| dsh 信号 | Herdr 状态 |
| agent/status = running（回合进行中） | working |
| agent/status = idle（没有活跃 driver） | idle |
| ask_user_question 挂起（模型等待输入） | blocked |

上报方式

状态通过 Herdr 的自定义集成协议上报：

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
--source custom:dsh-herdr-site --agent cc-tui --state <working|idle|blocked> \
[--message …] [--seq N]

fiber 销毁时调用 pane release-agent，不会留下过期条目。上报携带单调递增的序号，重复状态会去重。在 Herdr 面板之外插件是 no-op：不产生任何进程，也不读取任何内容。

兼容性

- Herdr：遵循官方自定义集成协议（Integrate your own agent），已在 herdrdev/herdr v0.8.0 实测。
任何实现了 pane report-agent / pane release-agent 的版本都能用。
- DSH：cc-tui 与 dsh-tui 两个 profile 都能用——插件只挂接会话事件总线，不依赖具体 surface 实现。
- DSH 内核代次：peerDependencies 逐个枚举已验证的内核版本
（^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.1.2-rc.1）。2026-09-07 在隔离 home 中
对现用的两代内核实测：

| 内核 | host 入口加载 | apply 执行 | session/event + agent/status 注册 |
| 0.1.1-rc.2 | ✅ | ✅ | ✅ |
| 0.1.2-rc.1 | ✅ | ✅ | ✅ |

apply 是否执行由插入其中的打印探针确认——单看"没报错"不足证，bundle 的 patch 没进层叠栈时是被静默跳过的。代码无需改动：插件只用到 ctx.on(...)、
ctx.effect(...) 与 process.env，不碰任何单代独有 API。上游发新 rc 时
必须补进枚举：node-semver 默认不把预发布版算进任何范围，除非比较符带同一 [major,minor,patch] 元组，因此 ^0.1.1-rc.2 对 0.1.2-rc.1 求值为假（连 * 也是假）。缺项会让安装器在宿主那份之外再解析出一份同名包。

已知边界：

1. dsh-tui profile 没有装配 ask_user_question 工具，所以该 profile 下不会出现 blocked（working/idle 上报不受影响）。
2. 上报给 Herdr 的 agent 标签固定为 cc-tui。

安装

前提：已安装可用的 dsh，且带有 dsh-cc-tui/dsh-base profile。插件把 profile 自带的包（^4 的 @deepseek-ai/cordis，以及按已验证内核代次逐个枚举的 dsh-session、 dsh-agent——见兼容性）声明为 peer 依赖，由宿主 profile 提供。

npm 安装（推荐，预构建产物，无需授权）：

dsh plugin --profile cc-tui add dsh-herdr-site

或从 GitHub 安装：

dsh plugin --profile cc-tui add github:WuJiaoJue/dsh-herdr-site

包里声明了 dsh.bundle.patch 清单，安装器会自动把它加入 profile 的 bundle 层叠栈，cordis.patch.yml 会把插件插入该 profile 启动的所有 surface。其他在用的 profile 同样操作一遍即可（例如 dsh-tui）。

确认已生效：

dsh --profile cc-tui --dump-config | grep -A2 herdr-site

也可以从本地检出安装：dsh plugin --profile cc-tui add /path/to/dsh-herdr-site

配置

可选的 blockMessage，随 blocked 上报一并发送：

写在 profile 的 cordis.patch.yml，或通过 --patch overlay
- id: herdr-site
config:
blockMessage: '模型等待你的回答'

构建与测试

npm install # 开发依赖：@types/node
npm run build # 输出 lib/
npm test # 用桩 herdr CLI 做行为断言
npx tsc --noEmit # 类型检查

git 安装无需构建：lib/ 已提交入库。pnpm 默认拦截 prepare 构建脚本，
如果依赖安装期构建，开箱就会装坏。

test/smoke.mjs 在真实 cordis context 上跑编译产物的完整生命周期—— working/blocked/idle 转换、去重、seq 排序、无关 tool 结果、销毁时释放——并对照桩 herdr 二进制逐条断言发出的每一条 CLI 调用。

本地开发备注

用普通 file: 依赖对着真实 profile 开发有两个坑（都是实际踩过的）：

1. file: 依赖在安装时复制内容——每次重新构建后要在 profile 里重跑 pnpm install，否则 profile 一直跑的是旧副本。
2. 当依赖既作为 bundle 层安装、又手工写了 insert 行时，裸包名激活会被静默跳过；把 insert 行的 name: 指到绝对路径 lib/index.js 是可靠的开发期接线方式：

- insert:
- id: herdr-site
name: '/absolute/path/to/dsh-herdr-site/lib/index.js'
config: {}

走这条路的话，还要把包从 profile 的 dsh.profile.bundles 列表移除，避免两处 insert 冲突。

以上两条都不影响标准 dsh plugin add 流程，后者能正确解析自带 patch 里的裸包名。

已知限制

- Herdr 的自动进程检测依然不会把 dsh 进程识别为 agent（那需要更新 Herdr 内置的检测器）。本插件做的是通过自定义集成路径上报状态，没有检测器也能让 Herdr 正确显示 working/idle/blocked、面板跳转和 wait。
- 可选的 --agent-session-id 引用尚未接线，所以 Herdr 的 pane/agent API 暂时拿不到关联的 dsh 会话 id。自动会话恢复还要求 Herdr 知道如何启动 dsh，这不在本插件范围内。状态上报不受影响。

许可证

MIT