@dsh-external/dsh-herdr-toolkit

Readme

# dsh-herdr

将 [Herdr](https://github.com/herdrdev/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 安装

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

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

固定到某个提交：

```bash
dsh plugin --profile web add github:wenhao4126/dsh-herdr#<commit-sha>
```

### 从本地目录安装

```bash
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：

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

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

### 更新与卸载

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

## 直接使用

在 DSH 对话中可以输入：

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

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

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

```text
在 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 的生命周期仍由用户管理。

## 返回值

每个工具返回：

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

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

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

## 项目文档

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

## 开发与构建

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

```bash
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](LICENSE)