# dsh-herdr 测试与发布

## 1. 测试分层

### L1 静态一致性

目标：在不运行 DSH/Herdr 的情况下发现文档、包和格式问题。

仓库已提供 `.github/workflows/ci.yml`：`verify` job 运行核心单元测试与 `npm pack` 内容检查；`full-build` job 固定 DeepSeek Harness checkout，执行 host 构建、插件 typecheck/build、全量测试与 package 检查。

```bash
npm test
```

```bash
git diff --check
git status --short --branch
npm pack --dry-run --json
```

检查：

- 包版本、main、types、bundle patch 正确。
- tarball 包含 `lib/index.js`、类型声明、README、LICENSE、`cordis.patch.yml`。
- 不包含 `node_modules`、本机绝对链接、token 或临时文件。
- README 和工具契约列出的工具与源码一致。

### L2 构建与类型

构建依赖完整 DSH checkout：

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

成功标准：

- TypeScript 无错误。
- `lib/index.js`、source map 和声明文件更新。
- 生成 JS 不引用仅编译期、不应存在的 runtime peer。

不要手工编辑 `lib/`。

### L3 工具注册

用最小假 Context 调用 `apply`：

- 注册工具数符合预期。
- 工具名唯一。
- 每个 schema 能被 `defineTool` 构造。
- effect 注册函数可返回 dispose。

当前基线是 24 个工具（见 `test/registration.test.mjs`）。

### L4 argv 映射

仓库内 `test/argv.test.mjs` 与 `test/runtime.test.mjs` 已覆盖运行时归一化和 argv 生成；可用 `npm test` 运行。

在临时 PATH 放置 mock `herdr`，让它输出 `process.argv.slice(2)`。至少验证：

- workspace/tab/pane 创建固定 `--no-focus`。
- pane/agent 操作使用显式目标。
- optional 参数只在存在时传递。
- agent native args 出现在 `--` 之后。
- prompt/command 文本作为单一 argv 元素，不被 shell 拆分。
- agent prompt 固定 `--wait`。

测试后删除 mock 文件和临时目录。

### L5 真实 Herdr 集成

必须使用隔离 named session，不操作用户默认 session。

安全步骤：

1. 确认测试环境位于 Herdr 管理 pane 内。
2. 创建唯一临时 session，例如 `repro-dsh-herdr-<timestamp>`。
3. 显式设置 `HERDR_SESSION`，清除继承 socket 和 pane ID。
4. 读取真实 workspace/pane ID。
5. 依次验证 create/split/run/wait/read。
6. agent 测试只有在用户同意消耗模型资源时运行。
7. 停止并删除唯一临时 session，确认无残留。

若当前环境不在 Herdr pane 内，不能为了测试控制默认 session；应报告真实集成未验证，并完成 L1-L4。

### L6 DSH profile 安装

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

验证：

```bash
cd ~/.dsh/profiles/web
pnpm list @dsh-external/dsh-herdr-toolkit --depth 0
pnpm peers check
```

还应从安装目录 import `lib/index.js`，确认版本和工具数。

## 2. 失败路径测试

至少覆盖：

| 场景 | 预期 |
| --- | --- |
| PATH 中无 `herdr` | `ok: false`，stderr 包含进程错误 |
| Herdr server 未运行 | `server_not_running` 结构化错误 |
| workspace/pane/agent 不存在 | Herdr API 错误，不崩溃 |
| wait timeout | 有界返回 timeout，不永久挂起 |
| stdout 非 JSON | 保留 stdout，无 `data` |
| stdout 空 | 不写入 `data/stdout: undefined` |
| CLI 非零且 stderr 为空 | 仍返回 `ok: false` 和退出码 |

## 3. 版本与变更记录

### Patch

- Bug 修复。
- 文档和安装修复。
- Herdr CLI 兼容性修复，但不改变模型可见契约。

### Minor

- 新工具。
- 新可选参数。
- 新 agent kind。
- 保持旧调用有效的返回增强。

### Major

- 工具重命名或删除。
- 参数含义改变。
- 返回结构不兼容。
- 安全默认值改变。

建议新增 `CHANGELOG.md` 后采用 Keep a Changelog 风格，记录用户可见变化和升级注意事项。

## 4. 发布检查表

### 代码

- [ ] 工作区只包含本次改动。
- [ ] `src/` 与 `lib/` 同步。
- [ ] 版本号正确。
- [ ] 无调试 mock、临时 tgz 或本机路径进入 Git。

### 契约

- [ ] 所有工具名唯一。
- [ ] 可选参数未写 `required: false`。
- [ ] enum 与当前 Herdr CLI 一致。
- [ ] 创建操作固定 `--no-focus`。
- [ ] 返回不含 `undefined`。

### 文档

- [ ] README 更新。
- [ ] 工具契约更新。
- [ ] 新架构边界已更新架构图。
- [ ] 安全变化有 ADR。
- [ ] 路线图状态已更新。

### 验证

- [ ] 构建通过。
- [ ] `npm test` 通过。
- [ ] npm pack dry-run 通过。
- [ ] 工具注册验证通过。
- [ ] argv mock 验证通过。
- [ ] 真实 Herdr 隔离测试通过，或明确记录未验证原因。
- [ ] GitHub/profile 安装通过。
- [ ] peer dependency 无本插件问题。

### GitHub

- [ ] commit 使用清晰的 conventional commit。
- [ ] push 后远端 main 指向预期提交。
- [ ] GitHub 源码 package.json 版本正确。
- [ ] 固定 commit 安装命令可用。

## 5. 回滚

GitHub 安装可以固定到已知提交：

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

回滚后检查：

- profile `package.json` specifier。
- `pnpm-lock.yaml` tarball commit。
- 安装目录 package version。
- 重启 DSH 后 loader entry 和工具目录。

不要通过手工修改 `node_modules` 回滚。