wenhao4126/dsh-herdr

dsh-herdr

将 Herdr 的 workspace、tab、pane 和 coding agent 操作暴露为 DeepSeek Harness（DSH）工具。

安装后可以直接在 DSH 对话中创建 Herdr 工作区和 pane、运行命令、启动 coding agent、等待任务完成并读取结果。

安装

前置条件

- 已安装 DeepSeek Harness（DSH）。
- 已安装 herdr，并且 herdr 命令位于运行 DSH 的 PATH 中。
- Herdr server 正在运行；通常在另一个终端执行 herdr 并保持 TUI 运行。

从 GitHub 安装

dsh plugin --profile web add github:wenhao4126/dsh-herdr

安装完成后重启 DSH，或者重新打开 DSH Web GUI。插件声明了 dsh.bundle.patch，会自动加入 web profile 的 bundle 列表。

固定到某个提交：

dsh plugin --profile web add github:wenhao4126/dsh-herdr#

从本地目录安装

git clone https://github.com/wenhao4126/dsh-herdr.git
cd dsh-herdr
dsh plugin --profile web add .

仓库已提交编译后的 lib/，普通安装不需要 TypeScript 或 DSH 源码 checkout。

lockfile 供应链策略报错

如果安装时报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，并且错误列出的是 profile 中原本已安装的其他插件，说明 pnpm 正在用新的 minimumReleaseAge 策略追溯检查旧 lockfile，并不代表 dsh-herdr 本身验证失败。

确认现有 DSH profile lockfile 来源可信后，可以只对这次安装信任已有 lockfile：

dsh plugin --profile web add github:wenhao4126/dsh-herdr --trust-lockfile

不要为了安装插件而全局关闭 minimumReleaseAge；如果 lockfile 来源不可信，应先审查或重建 lockfile。

更新与卸载

dsh plugin --profile web update @dsh-external/dsh-herdr-toolkit
dsh plugin --profile web remove @dsh-external/dsh-herdr-toolkit

直接使用

在 DSH 对话中可以输入：

列出 Herdr 当前所有 workspace、tab、pane 和 agent，只执行读取操作。

在 Herdr workspace w1 中创建一个 tab，工作目录为 /home/wen/projects/example，标签为 review，不要切换用户焦点。

把 w1:p1 向右拆分，在新 pane 中启动名为 reviewer 的 Codex agent。让它审查当前 Git diff，等待最多 120 秒，然后读取并总结结果。

在 w1:p2 运行 just test，等待输出中出现 test result，最多等待 2 分钟，然后读取最近 100 行。

工具返回 Herdr CLI 的结构化 JSON。创建结果中的 workspace、tab、pane ID 应作为后续操作的显式目标。

工具

Workspace

| 工具 | 用途 |
| --- | --- |
| _dsh_herdr_workspace_list | 列出 workspaces |
| _dsh_herdr_workspace_get | 查询指定 workspace |
| _dsh_herdr_workspace_create | 创建 workspace，强制不抢焦点 |

Tab

| 工具 | 用途 |
| --- | --- |
| _dsh_herdr_tab_list | 列出 tabs，可按 workspace 过滤 |
| _dsh_herdr_tab_get | 查询指定 tab |
| _dsh_herdr_tab_create | 在指定 workspace 创建 tab，强制不抢焦点 |

Pane

| 工具 | 用途 |
| --- | --- |
| _dsh_herdr_pane_list | 列出 panes，可按 workspace 过滤 |
| _dsh_herdr_pane_get | 查询指定 pane |
| _dsh_herdr_pane_layout | 读取 pane 布局几何 |
| _dsh_herdr_pane_process_info | 查看 pane 进程信息 |
| _dsh_herdr_pane_edges | 读取 pane 边/邻接关系 |
| _dsh_herdr_pane_read | 读取 pane 输出 |
| _dsh_herdr_pane_split | 将指定 pane 向右或向下拆分，强制不抢焦点 |
| _dsh_herdr_pane_run | 在指定空闲 shell pane 中运行命令并发送 Enter |
| _dsh_herdr_pane_wait_output | 等待 pane 中出现文本或正则匹配 |
| _dsh_herdr_pane_send_text | 向指定 pane 发送原始文本，不发送 Enter |

Agent

| 工具 | 用途 |
| --- | --- |
| _dsh_herdr_agent_list | 列出已识别 agents |
| _dsh_herdr_agent_get | 查询指定 agent |
| _dsh_herdr_agent_read | 读取 agent 输出 |
| _dsh_herdr_agent_start | 在指定空闲 pane 启动命名 agent |
| _dsh_herdr_agent_wait | 等待 agent 到达稳定或指定状态 |
| _dsh_herdr_agent_prompt | 发送 prompt 并等待稳定状态 |
| _dsh_herdr_agent_explain | 解释 agent 检测状态，排查未识别/误识别 |

支持的 agent kind 取自当前 Herdr CLI，包括 codex、claude、opencode、gemini、kimi、wen、ocr 等。

诊断

| 工具 | 用途 |
| --- | --- |
| _dsh_herdr_doctor | 只读健康检查：herdr 版本、status、session、workspace、agent |

安全边界

- 所有 pane 和 agent 控制操作都要求显式 ID 或唯一 agent 名称。
- workspace、tab 和 pane 创建始终传入 --no-focus，不会抢走用户焦点。
- 不暴露 workspace/tab/pane 的 close、move、swap、focus 等破坏性或干扰性操作。
- 不提供任意 herdr  通用入口，只开放经过审查的命令集合。
- Node.js 通过 execFile 调用 herdr，参数不会交给本机 shell 解析。
- _dsh_herdr_pane_run、_dsh_herdr_agent_start、_dsh_herdr_agent_prompt 支持 preview: true，只返回结构化预览而不执行。
- 设置 DSH_HERDR_PREVIEW_REQUIRED=1 后，上述 R2 工具必须先执行预览，否则返回 preview_required。
- _dsh_herdr_pane_run 会在目标终端执行用户或模型提供的 shell 命令；使用前应确认目标 pane 和命令。
- 插件不会启动或停止 Herdr server。Herdr TUI/server 的生命周期仍由用户管理。

返回值

每个工具返回：

{
"ok": true,
"command": "herdr pane split",
"exitCode": 0,
"data": {}
}

Herdr CLI 失败会作为结构化结果返回，而不会导致 DSH 工具层崩溃。失败时 stderr 中的 JSON 会一并解析进 data，因此可直接读取 data.error.code（例如 server_not_running）：

{
"ok": false,
"command": "herdr workspace list",
"exitCode": 1,
"errorCode": "server_not_running",
"stderr": "...server_not_running..."
}

项目文档

- 项目导航：智能体和开发者接手入口。
- 产品说明书：目标用户、产品范围、成功指标和优先级。
- 架构说明书：运行链路、模块职责、安全和故障模型。
- 可交互架构图：带源码证据的完整系统图。
- 工具契约：24 个工具的输入、行为和风险。
- 功能扩展指南：添加新功能的标准流程。
- 测试与发布：验证分层、发布检查和回滚。
- 运维与故障排查：安装、socket、peer 和 agent 问题。
- 路线图 与 架构决策。
- CHANGELOG：版本变化。

开发与构建

源码位于 src/index.ts。开始修改前先阅读 AGENTS.md 和 项目导航。构建需要完整 DSH 源码 checkout：

DSH_CHECKOUT=/path/to/deepseek-harness bash scripts/build.sh
npm run typecheck
npm test
npm pack

可选环境变量：

- DSH_HERDR_CLI_TIMEOUT_MS（毫秒）：为 herdr 子进程设置硬超时兜底。
- DSH_HERDR_PREVIEW_REQUIRED=1：要求 R2 工具先 preview=true 再执行。

workspace create、tab create、pane split 支持 env 数组（如 ["A=1", "B=2"]），会映射为重复的 --env KEY=VALUE。

兼容性

当前版本依据 Herdr 的 workspace、tab、pane、agent CLI 命令实现，并面向 DSH 0.1.0-rc 系列。@deepseek-ai/dsh-tools 由 DSH host 在运行时提供，因此声明为 optional peer。

License

BSD-3-Clause