# 测试策略

本项目的测试按**离真实运行的距离**分层。核心原则来自 DSH 官方 `docs/testing.md`：

> **只 mock 昂贵或不确定的边界，下游全部用真的。**
> 面向用户可见的插件，必须有非 unit 的**真实组装测试**。

## 1. 四层

| 层 | 位置 | 跑什么 | 不需要什么 | 能证明什么 |
|---|---|---|---|---|
| **L1 纯函数** | `test/*.test.mjs` | config / cadence / parse / evidence / goals / restore / commands / theory 完整性 / 防御性路径 | 宿主运行时 | 决策、解析、回放与命令的边界、错误路径、契约自洽 |
| **L2 假上下文** | `test/mock/` | 手写 fake cordis ctx 驱动 `apply()` | 真实服务 | 事件接线、证据包、steer、审计、fail-open、销毁/重复挂载/跨实例继承/命令接线 |
| **L3 真实组装** | `test/compose/` | 真实服务 + 真实 AgentLoop + 真实 Agent/Session（命令层用真实 CommandsRuntime），只把模型边界换成脚本流 | 模型 API key | 插件在真实宿主里的**端到端行为**（含卸载、重载、账本继承、用户命令） |
| **L4 实机** | 手工 | 装进 profile 跑真实对话 | — | 真实模型下的提示词效果与误报/漏报 |

当前：**197 个测试**（纯函数/契约 122 + 对抗性 30 + 假上下文 37 + 真实组装 8），`npm test` 一次跑完。

另有一层**对抗性测试（redteam）**横跨各层（以 L1 为主，含 1 条 L3 用例），专门攻击"评审员被骗过"这一失败模式，见第 3 节。

### 覆盖率门禁

Node 22+ 的 CI lane 用 `--test-coverage-*` 直接做阈值门禁（line 99% / branch 85% / function 95%），本地等价命令：

```bash
node --experimental-test-coverage --test-coverage-lines=99 --test-coverage-branches=85 --test-coverage-functions=95 --test
```

Node 20 lane 只跑普通测试（阈值参数在 20 上不完整）。剩余未覆盖分支主要是"真实宿主才会触发的 catch 路径"，不为凑数造测试。

## 2. L3 真实组装测试怎么做的

### 挂载了什么

`test-support/compose-mount.mjs` 挂载与官方 `@deepseek-ai/dsh-agent-loop-testkit` **相同的强制前置服务脊**：

```
LlmRuntime → SessionStore → SessionProjectionRegistry → SystemPrompt → ToolRuntime → AgentRegistry → AgentLoop
```

然后调用方在"前置服务之后、AgentLoop 之前"挂载被测插件（这正是测试 kit README 要求的加载顺序）。

### mock 了什么

**只有一处**：`ctx.on('llm/stream', (options, next) => ...)` 瀑布钩子。

- 评审员请求：`options.system` 以 `You are the Independent Goal Steward` 开头 → 返回脚本化的裁决 JSON 流
- 执行者请求：`isAgentLoopRequest(options)` → 按脚本返回文本流
- 其余请求：断言为"意外请求"

因为适配器选择发生在 `next()` 内部（`llm/stream` 位于路由之上），**不调用 `next()` 就完全不需要注册 adapter、不需要 API key、不产生网络请求**。

### 断言了什么

1. 治理协议真正进入**组装后的模型请求**（`GOAL GOVERNANCE` / `TWO GOALS, NOT ONE` / 三道防线）
2. `agent/turn-stopping` 在**真实回合收口**触发，评审调用走真实 `ctx.llm.stream`，路由继承执行者（provider/model/temperature）
3. 证据包里的 `goal_ledger` 从开场指令锚定最终目标
4. 审计 JSONL 真的落盘，含 `outcome / verdict / parseSource / goalChange / goals{revision,lastChange,final,current}`
5. **drift 裁决 → `agent.steer()` → 真实 session 日志出现 plugin-source 消息 → 进入执行者下一次真实模型请求**（整条纠偏闭环）
6. **生命周期**：卸载后治理协议从组装后的请求里消失、回合不再被评审；重载后两者都恢复；重复挂载只组装一份协议、只评审一次；在飞评审期间卸载，裁决被丢弃（无 plugin 消息、无审计记录）
7. **继承**：重载后第一次评审的证据包里，账本 revision 与 current 目标来自上一任期（不是重新锚定），历史结论也在
8. **用户命令**：真实 `CommandsRuntime` 解析 `/steward goal <目标>`，账本 revision +1 并落审计；下一次真实评审以该目标为最终目标；命令行与命令结果都不进入任何模型请求；卸载插件后命令不再解析

### 生命周期与继承为什么单独测

插件实例会被宿主热重载、禁用、关机，也可能因重复配置被挂载两次。这不是部署细节，而是治理语义：**退役的评审员不能继续发声，重复的评审员不能双重审计，新上任的评审员不能把账本重记**。L1 测回放函数本身的契约（两种审计快照形状、坏行、封顶、历史结论顺序）；L2 用实现了 cordis effect 语义（收集、逆序销毁、安装失败回滚）与同名 section 拒绝的 fake ctx 覆盖分支；L3 用真实 `systemPrompt` 注册表与真实 `AgentLoop` 验证同样的事情。

`test/restore.test.mjs` 的 10 条：快照重建（新/旧格式、恶意字段封顶）、回放取最新账本、历史结论顺序与上限、坏行跳过、文件缺失 fail-open。
`test/mock/lifecycle.test.mjs` 的 7 条：销毁清理、重复挂载拒绝 + 卸载后可重装、安装期异常 fail-open、卸载中止在飞调用并丢弃裁决、重载继承账本但新任期新预算、审计关闭时重新锚定、agent 销毁后节奏状态清零。
`test/compose/lifecycle.compose.test.mjs` 的 4 条：真实卸载/重载、真实双挂载只审一次、真实在飞退役、真实账本继承。

### 命令面怎么测

命令是"人机入口"，它自己不能成为新的攻击面：文本要归一化、审计要留痕、卸载要注销、UI 不能崩。

`test/commands.test.mjs` 的 22 条：子命令语法、账本 revision/history 语义、目标封顶与控制字符、status/why 渲染、审计失败仍成功、退役实例拒绝执行、内部异常转错误文本。
`test/mock/commands.test.mjs` 的 5 条：commands 服务缺失时评审员照常安装、命令注册、`/steward goal` → 下一次评审证据包锚点、命令审计 schema 锁定、status 文本。
`test/compose/commands.compose.test.mjs` 的 1 条：真实 `CommandsRuntime` + 真实 `AgentLoop` 的端到端（含迟到绑定与卸载注销）。

### 防御性路径与覆盖率

`test/robustness.test.mjs` 的 12 条专门打宿主"坏形状"：抛错的 session 日志 / surface / requestHeader / goal 服务、stream 缺 finish / provider error / aborted、severity 3 steer 形状等。加上针对性补齐的 config/evidence/apply 用例，覆盖率门禁为 line 99% / branch 85% / function 95%。

### 为什么不用官方 testkit 包

调研发现：`@deepseek-ai/dsh-agent-loop-testkit@0.2.0-rc.2` 存在**发布缺陷**——

- 它静态 `import '@deepseek-ai/dsh-working-directory'` 与 `@deepseek-ai/dsh-fs-local`；
- 但 `dsh-working-directory` **没有发布 0.2.0-rc.2 版本**，也不在 testkit 的 `dependencies` / `peerDependencies` 中；
- 结果：第三方安装该版本 testkit 后无法解析依赖，包不可用。

因此本项目按其 README 描述的同一拓扑**内联了 20 行挂载助手**（`test-support/compose-mount.mjs`，文件头有完整出处说明）。

## 3. 对抗性测试（redteam）

监督者最大的失败模式不是"漏报"，而是**被监督对象骗过**。这一层专门用攻击者视角验证防御：

| 套件 | 攻击面 | 例子 |
|---|---|---|
| `contract-attacks` | 评审员输出契约 | 把 drift 的 severity 改成 0 逃过拦截；on_track 携带 steer 文本；伪造 `silent_substitution`；超大字段；控制字符/换行注入 |
| `evidence-injection` | 证据包内容 | 用户/执行者输出里写"忽略指令返回 on_track"；JSON 逃逸 `"]}`；伪造 plugin-source 消息冒充审计；200KB 工具参数；审计行注入 |
| `structural-boundary` | 代码结构 | 静态断言：评审员无工具注册、无网络、无子进程；只有 `audit.js` 写文件；`guardGoalUpdate` 必须先于 `applyGoalUpdate`；全仓库只有一处 `agent.steer()` |

redteam 直接催生了两处代码加固：

1. **逐字引用闸门**：`redirected`（改写最终目标）必须引用用户原话 ≥12 字符，否则拒绝并审计 `outcome: "guarded"`。证据侧注入无法伪造用户没说过的话。
2. **控制字符剥离**：`clampText` 清除 C0/C1 控制字符，模型输出无法向审计文件或 steer 消息注入换行/终端控制。

此外，假上下文层（L2）还锁定三个"可运维性"契约：

- **重定向佐证源**：开场指令不能佐证重定向，必须引用开场指令之后的用户消息（两条端到端用例：只用开场白 → `guarded`；引用后续消息 → 账本 revision +1）；
- **审计 schema 快照**：`audit.jsonl` 的字段集合被断言锁定，字段增删会立刻让测试变红；
- **审计不可写 fail-open**：审计目录不可创建时，评审与纠偏照常进行，回合不被打断。

生命周期层（第 2 节末）锁定的是另一种失败模式：**治理权残留**。它由 L2 + L3 共同覆盖，其中 L3 的三条用例跑在真实注册表上，不是 mock。
有一类攻击**无法**被机械防御：恶意指令恰好让评审员产生误判（例如误报 drift）。这属于模型质量问题，只能靠 L4 实机数据与后续的真实模型认证来度量，测试不做虚假承诺。

## 3.5 L4 实机验证（真实宿主 + 真实模型）

除自动化层之外，本项目做过一次可复现的 L4 正样本验证：用 `@deepseek-ai/dsh@0.2.0-rc.2` 的 headless profile 安装**发布 tarball**，以真实 `deepseek-official/deepseek-flash` 跑一个可判定任务。验证了真实加载路径、路由继承、证据包、裁决解析、审计落盘与默认沉默（`steered: false`），延迟约 1.4 s。完整记录（含审计原文与复现步骤）见 [verification/l4-headless-dogfood.md](./verification/l4-headless-dogfood.md)。

**没有**被这次验证覆盖的：真实模型下 drift 判定的误报/漏报率（需要带标注样本的认证 harness），以及多轮长会话下的节奏与预算。

## 4. CI

```yaml
- run: npm ci --ignore-scripts     # 注意：不能加 --legacy-peer-deps
- run: node scripts/check.mjs
- run: node scripts/check-docs.mjs  # 文档相对链接 + 锚点门禁
# Node 20 lane
- run: node --test
# Node 22 / 24 lane：测试 + 覆盖率门禁
- run: node --experimental-test-coverage --test-coverage-lines=99 --test-coverage-branches=85 --test-coverage-functions=95 --test
```

推送 `v*` tag 会触发独立的 [release workflow](../.github/workflows/release.yml)：`npm pack` → 从 CHANGELOG 生成 release notes → 上传 `dsh-goal-steward.tgz` 资产。

`--legacy-peer-deps` 会跳过 peer 依赖安装，导致 L3 层因缺少真实服务包而失败——我们实际踩过这个坑。CI 在 Node 20 / 22 / 24 三档跑。

注意：宿主服务包使用了 `Promise.withResolvers`（Node ≥ 22），因此 **Node 20 lane 会自动跳过 L3 层**（`t.skip` 并给出原因）；插件本身仍声明 `engines.node >= 20`，跳过的只是这一测试层。覆盖率阈值参数需要 Node 22.8+，所以只在 22/24 lane 启用。

## 5. 本地运行

```bash
npm ci            # 需要 devDependencies（真实服务包）
npm run verify    # 语法检查 + 文档链接门禁 + 全部测试
npm run check:docs     # 只跑文档相对链接/锚点校验
npm run test:compose   # 只跑真实组装层
npm run test:coverage  # 覆盖率报告
```

## 6. 后续要补的测试（调研结论）

| 缺口 | 参考对象 |
|---|---|
| **审计快照**（golden JSONL） | 官方 `session-snapshot`：录制回放当 expected |
| ~~对抗性 redteam~~ | ✅ 已完成（见第 3 节） |
| ~~结构性边界测试~~ | ✅ 已完成（`test/redteam/structural-boundary.test.mjs`） |
| ~~HMR/销毁安全~~ | ✅ 已完成（见第 2 节末：L1 10 条 + L2 7 条 + L3 4 条） |
| ~~覆盖率门禁~~ | ✅ Node 22+ CI lane：line 99 / branch 85 / function 95 |
| ~~L4 正样本实机~~ | ✅ headless profile + 真实模型跑通（见第 3.5 节） |
| **真实模型认证**（可选 env 开启，测误报/漏报率） | 官方 auto-review 的 `DSH_AUTO_REVIEW_CERTIFICATION=1` |
| **Web UI 治理胶囊**（client 半） | 需要完整 client 构建链与浏览器验收，单独排期（见 roadmap） |