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#<commit-sha>

从本地目录安装

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 <args> 通用入口，只开放经过审查的命令集合。
• 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