# dsh-herdr 工具契约

本文把 `src/index.ts` 的 24 个工具整理成产品和智能体可读的契约。源码中的 `defineTool` schema 是运行时权威；本文用于理解、设计 prompt 和做变更审查。

## 通用规则

- 所有工具返回 `ok / command / exitCode`，并按需返回 `errorCode / data / stdout / stderr`。
- `ok: false` 是可处理的业务结果，不等于 DSH 插件崩溃。
- ID 必须来自最近一次 Herdr list/get/create/split 返回，不得猜测。
- 所有 timeout 单位是毫秒。
- `source` 取值必须使用工具 schema 给出的枚举。
- `pane_run` 的 `command` 在目标 pane 中执行并发送 Enter；它不是 Node.js 本地执行。

## 风险等级

- **R0 只读**：不会改变 Herdr 状态。
- **R1 创建/输入**：会创建对象或向目标终端发送内容，必须显式目标。
- **R2 执行命令/启动 agent**：可能改变代码或消耗资源，必须在用户意图明确时调用。

## Workspace 工具

| 工具 | 风险 | 必填参数 | 行为 | 后续动作 |
| --- | --- | --- | --- | --- |
| `_dsh_herdr_workspace_list` | R0 | 无 | 调用 `herdr workspace list` | 读取真实 workspace ID |
| `_dsh_herdr_workspace_get` | R0 | `workspace` | 调用 `herdr workspace get <id>` | 确认 workspace 结构 |
| `_dsh_herdr_workspace_create` | R1 | `cwd` | `herdr workspace create --cwd ... [--label ...] [--env ...] --no-focus` | 保存返回 workspace/tab/pane ID |

产品语义：创建 workspace 是为隔离任务建立新的 Herdr 容器，不应默认为用户切换焦点。

## Tab 工具

| 工具 | 风险 | 必填参数 | 行为 |
| --- | --- | --- | --- |
| `_dsh_herdr_tab_list` | R0 | 无 | `workspace` 可选，调用 `herdr tab list` |
| `_dsh_herdr_tab_get` | R0 | `tab` | 调用 `herdr tab get <id>` |
| `_dsh_herdr_tab_create` | R1 | `workspace`, `cwd` | 指定 workspace/cwd 创建 tab，支持 `env`，固定 `--no-focus` |

创建 tab 前应优先确认目标 workspace 存在；跨 workspace 创建不应依赖当前焦点。

## Pane 工具

| 工具 | 风险 | 必填参数 | 行为 |
| --- | --- | --- | --- |
| `_dsh_herdr_pane_list` | R0 | 无 | 按 workspace 可选过滤 |
| `_dsh_herdr_pane_get` | R0 | `pane` | 查询一个 pane |
| `_dsh_herdr_pane_layout` | R0 | `pane` | 查询布局几何与关系 |
| `_dsh_herdr_pane_process_info` | R0 | `pane` | 查看 pane 进程信息，判断是否空闲 |
| `_dsh_herdr_pane_edges` | R0 | `pane` | 查询 pane 边/邻接关系 |
| `_dsh_herdr_pane_read` | R0 | `pane` | 读取 visible/recent/recent-unwrapped/detection |
| `_dsh_herdr_pane_split` | R1 | `pane`, `direction` | right/down 拆分，支持 `ratio/cwd/env`，固定 `--no-focus` |
| `_dsh_herdr_pane_run` | R2 | `pane`, `command` | 在目标 pane 运行命令并发送 Enter；支持 `preview` |
| `_dsh_herdr_pane_wait_output` | R0 | `pane`, `pattern` | 按文本或 regex 等待输出，可设置 source/lines/timeout |
| `_dsh_herdr_pane_send_text` | R1 | `pane`, `text` | 发送原始文本，不发送 Enter |

### `pane_read` source

- `visible`：当前可见屏幕。
- `recent`：近期输出，保留软换行。
- `recent-unwrapped`：近期输出，适合日志和 agent 结果。
- `detection`：agent 检测底部缓冲区；是否可用于普通 pane read 以当前 Herdr CLI 为准。

### R2 preview 与强制预览

`pane_run`、`agent_start`、`agent_prompt` 都接受 `preview: true`：不会调用 Herdr，而是返回 `data.preview: true`、`data.action` 和脱敏 `data.target`（不包含命令正文、prompt 或 native args）。

设置环境变量 `DSH_HERDR_PREVIEW_REQUIRED=1` 后，未带 `preview: true` 的 R2 调用会返回 `ok: false`、`errorCode: preview_required`，避免模型或自动化流程直接执行高影响操作。

### `pane_run` 使用规则

1. 必须先确认 pane 是可用 shell，而不是正在运行 agent 或交互式程序。
2. 命令应由用户明确提出，或由已批准的工作流生成。
3. 运行后用 `pane_wait_output` 或 `pane_read` 获取结果。
4. 不要在一个 pane 中并发发送多个命令。
5. 需要 Enter 的场景用 `pane_run`；只填写输入用 `pane_send_text`。

## Agent 工具

| 工具 | 风险 | 必填参数 | 行为 |
| --- | --- | --- | --- |
| `_dsh_herdr_agent_list` | R0 | 无 | 列出 Herdr 识别到的 agent |
| `_dsh_herdr_agent_get` | R0 | `agent` | 按唯一名称或 pane ID 查询 |
| `_dsh_herdr_agent_read` | R0 | `agent` | 读取 recent-unwrapped 输出 |
| `_dsh_herdr_agent_start` | R2 | `name`, `kind`, `pane` | 在明确 pane 启动 agent，可传 native args；支持 `preview` |
| `_dsh_herdr_agent_wait` | R0 | `agent` | 等待默认或指定状态 |
| `_dsh_herdr_agent_prompt` | R2 | `agent`, `prompt` | 发送任务并等待稳定状态；支持 `preview` |
| `_dsh_herdr_agent_explain` | R0 | `agent` | 返回 agent 检测状态 JSON |
| `_dsh_herdr_doctor` | R0 | 无 | 汇总版本/session/workspace/agent 健康检查 |

支持的 `kind` 应以当前 Herdr CLI 为准，当前 schema 包含：

```text
pi claude codex gemini cursor devin agy cline omp mastracode opencode
copilot kimi kiro droid amp grok hermes kilo qodercli maki wen ocr
```

## 推荐编排

```text
1. workspace_list / tab_list / pane_list / agent_list
2. 选择真实目标 ID
3. pane_split 或 workspace/tab_create
4. 读取创建结果中的新 ID
5. agent_start（如需要）
6. agent_prompt
7. agent_wait
8. agent_read / pane_read
```

不要跳过第 1、2 步，也不要根据列表顺序自行构造 ID。

## 错误处理

Herdr CLI 把 API 错误输出到 stderr（JSON）并返回非零退出码；插件会将该 JSON 解析进 `data`，因此可直接读取 `data.error.code`（例如 `server_not_running`）。

智能体遇到失败应按以下顺序处理：

1. 检查 `ok`、`exitCode`、`errorCode` 和 `stderr/data.error`。
2. 如果是 `server_not_running`，提示用户启动 Herdr，不要循环重试。
3. 如果是目标不存在，重新 list 并要求用户确认目标。
4. 如果是 timeout，先 get/read 再决定延长等待。
5. 如果是参数错误，修正调用，不要重试同一 argv。
6. 记录失败命令类别，不在报告中复制敏感 prompt 或命令正文。

## 变更契约

增加工具时必须同步：

- `src/index.ts` 的 schema 和 argv 映射。
- `README.md` 工具表。
- 本文工具表和风险等级。
- [架构说明书](./02-架构说明书.md) 的边界或流量变化。
- mock argv 验证。
- 版本号和 CHANGELOG（若为用户可见能力）。
- 如扩大破坏性权限，新增 ADR。