# dsh-herdr 功能扩展指南

本文面向准备添加功能的开发者和 coding agent。目标是让新能力保持可解释、安全、可测试，并与 Herdr CLI 的真实契约一致。

## 1. 开始前回答五个问题

1. 用户要完成的任务是什么？不要用“增加某条 CLI”代替用户目标。
2. 当前 Herdr 是否已有稳定公开命令？以当前源码和 `herdr <group> help` 为证据。
3. 操作是只读、创建、输入、执行还是破坏性？风险等级是什么？
4. 能否要求显式 workspace/tab/pane/agent 目标？
5. 失败时用户需要什么结构化信息才能恢复？

如果第 2 项为否，先推动 Herdr 提供中立的 server/API/CLI 能力，不要解析 TUI 屏幕来控制核心行为。

## 2. 功能分类

### A. 安全读取类

示例：process-info、layout、edges、agent explain。

通常可以直接增加，要求：

- schema 限制枚举和值类型。
- 明确 read source 和最大输出。
- 不改变焦点或已读状态。

### B. 创建与等待类

示例：创建 worktree workspace、等待进程退出、等待 agent 状态。

要求：

- 创建结果返回真实 ID。
- 默认 `--no-focus`。
- 等待必须支持 timeout。
- 文档说明后续如何使用返回对象。

### C. 终端输入与命令执行类

示例：send-text、pane run、agent prompt。

要求：

- 显式 pane/agent 目标。
- 不在 `command` 摘要回显正文。
- 说明 Enter、原始文本和 agent prompt 的区别。
- 测试不得在用户默认 session 执行有副作用命令。

### D. 破坏性或干扰类

示例：close、move、swap、focus、send-keys、server stop。

默认不加入。确有产品需求时必须：

- 新增 ADR。
- 设计 dry-run/preview 或明确确认。
- 限制对象范围，禁止隐式当前焦点。
- 提供恢复或后果说明。
- 增加隔离 session 的真实验收。

### E. UI 与持久状态类

示例：DSH Web 中展示 Herdr 拓扑、操作历史、任务看板。

不应继续塞进当前 toolkit 单文件。应升级为 hybrid 插件，拆分：

- host service：读取 Herdr、暴露 API、鉴权。
- client plugin：视图和交互。
- shared contracts：序列化数据结构。

先写架构 ADR 和 UI 产品说明。

## 3. 添加工具的标准步骤

### 第一步：核对 Herdr 契约

```bash
herdr --version
herdr <group> help
```

同时读取 Herdr 对应 CLI 源码，确认：

- 参数名和必填项。
- 默认值。
- 返回 JSON 形态。
- 是否使用焦点或调用 pane 上下文。
- timeout 单位和状态枚举。

### 第二步：定义产品语义

写清：

- 用户会怎样描述需求。
- 工具名称和一句话 description。
- 必填/可选参数。
- 风险等级。
- 成功和失败后的下一步。

工具 description 保持短小，详细解释放文档，减少 DSH 工具目录 token 成本。

### 第三步：设计 schema

规则：

- 必填字段使用 `required: true`。
- 可选字段省略 `required`，不要写 `required: false`。
- 有限选项使用 `enum`。
- 不接受可以由插件或 Herdr 推导的任意字符串 flags。
- 数字参数应在代码或 CLI 侧验证范围。
- 不把用户输入拼接成一个 shell 命令供本插件执行。

### 第四步：映射 argv

推荐：

```ts
(args) => runHerdr(argv.paneExample(args))
```

避免：

```ts
exec(`herdr pane example ${args.pane}`)
```

要求：

- group/action 固定在源码中。
- option 名固定在源码中。
- 用户值作为独立 argv 元素。
- 创建操作追加 `--no-focus`。

### 第五步：更新文档

至少更新：

- README 工具列表或使用示例。
- `docs/03-工具契约.md`。
- 产品范围或路线图。
- 若改变架构边界，更新架构图和 `docs/02-架构说明书.md`。
- 若改变安全决策，新增 ADR。

### 第六步：验证

1. TypeScript/DSH 构建。
2. 24+N 个工具名称唯一。
3. README 和契约覆盖全部工具。
4. mock `herdr` 验证 argv。
5. 隔离 Herdr named session 验证成功路径。
6. 失败路径：server 未运行、目标不存在、timeout。
7. GitHub 包 dry-run 包含 `lib/` 和 bundle patch。
8. profile 安装后 import 和 peer 检查。

## 4. 何时拆分 `src/index.ts`

当前单文件适合小型工具集。出现任一条件时应拆分：

- 工具超过约 25 个。
- 出现第二种执行后端，不再只有 Herdr CLI。
- 需要共享参数验证、确认策略或权限分类。
- 返回类型按 workspace/pane/agent 开始分化。
- 单个变更经常触碰整个文件并产生冲突。

建议目标结构：

```text
src/
  index.ts              # apply 与注册编排
  runtime.ts            # runHerdr / result normalization
  argv.ts               # 每个工具到 herdr argv 的确定性映射
  schemas.ts            # 公共 schema
  tools/
    workspace.ts
    tab.ts
    pane.ts
    agent.ts
  policy.ts             # 风险等级和确认策略
```

不要为了目录美观提前拆分；当职责和测试边界真实出现时再做。

## 5. 功能提案模板

```markdown
# 功能：<名称>

## 用户问题
<用户今天做不到或很麻烦的事情>

## 目标行为
<自然语言示例和预期工具链>

## Herdr 依据
- CLI：`herdr ...`
- 源码：`path:line`
- 返回结构：...

## 工具契约
- 名称：`_dsh_herdr_...`
- 参数：...
- 返回：...
- 风险：R0/R1/R2/破坏性

## 安全设计
- 显式目标：是/否
- 是否抢焦点：否
- timeout：...
- 确认或预览：...

## 验收
1. ...
2. ...

## 文档影响
README / 工具契约 / 架构 / ADR / 路线图
```

## 6. 代码审查清单

- 是否调用了当前 Herdr 支持的真实命令？
- 是否使用 `execFile` 和 argv 数组？
- 是否可能隐式命中用户焦点 pane？
- 是否遗漏 `--no-focus`？
- 是否允许无界等待或无限输出？
- 是否把敏感正文写入命令摘要？
- 是否将 `undefined` 放进结果对象？
- 是否在卸载/热重载时留下注册资源？
- 是否同步编译产物和文档？
- 是否在默认 Herdr session 做了有副作用测试？