# dsh-bulwark 测试说明（卡 8）

卡 1-7 的验证都是一次性脚本，跑完即弃。本文件配套 `tests/e2e.test.ts`，把这些验证固化成可重复运行的回归测试。

---

## 1. 怎么跑

```bash
cd "/Users/liuzhaoyang/Documents/untitled folder/dsh-fortress"
pnpm test:e2e
# 等价于：node --experimental-strip-types tests/e2e.test.ts
```

- **环境**：Node ≥ 22.6（本机 v26.10.0；该版本已默认擦除类型，`--experimental-strip-types` 保留为显式写法）。零第三方依赖，只用 `node:assert` / `node:fs` / `node:os` / `node:path`。
- **退出码**：0 = 23 条全过；非 0 = 有失败，末尾打印失败明细和原因。
- **不依赖 DSH 运行时**：测试动态 import 真实源码 `src/index.ts`（它只运行 `node:fs` / `node:path`，对 cordis 是 `import type`，纯 Node 可直接加载），再用一个假 ctx 调真实 `apply()`，抓出真实的 `tools.guard` 回调，最后用真实的 exec 形状 `{ name, arguments }` 驱动它。**没有任何一份复制的判定逻辑。**
- **与 `pnpm test` 的关系**：`pnpm test` 是 vitest，include 只有 `src/**/*.test.ts` 和 `src/**/__tests__/**/*.test.ts`，因此**不会**收录根目录这份 e2e —— 这是刻意的：e2e 需要真实文件系统和真实配置路径，不适合放进 vitest 的环境矩阵。两条线互不干扰。
- **副作用**：只在系统临时目录建一个 `dsh-fortress-e2e-*` 目录，结束时递归删除；对真实 `config.json` 只读不写，不启动任何 DSH 进程。

---

## 2. 每条测试覆盖什么

### 2.1 配置读取（1、2、3、4、4b）

| 编号 | 场景 | 驱动方式 | 期望 |
| --- | --- | --- | --- |
| 1 | 没有 config.json | `loadConfig(临时目录里不存在的路径)` | 走 `readFileSync` 的 catch 分支，整体等于 `DEFAULT_CONFIG`（守则文本为默认值） |
| 2 | config.json 带自定义 rulesText | 临时 `config.json`，三个字段都给自定义值 | `rulesText` / `protectedPaths` / `protectedRemovalPatterns` 全部采用自定义值 |
| 3 | config.json 是坏 JSON | 临时文件写半个 JSON | `JSON.parse` 抛错被 catch，整体回退 `DEFAULT_CONFIG` |
| 4 | config.json 缺 rulesText | 临时文件只给 `protectedPaths` | 逐字段回退：`rulesText` 用默认值，`protectedPaths` 仍是自定义值，规则用默认值 |
| 4b | 配置真的驱动了 systemPrompt 段 | 假 ctx 捕获 `systemPrompt.section(...)` | 段文本 === 真实 `config.json` 的 `rulesText`，且 `order` 是数字（锚点解析成功） |

> 1-4 用 `loadConfig(path)` 的可选参数注入临时路径，好处是不用改写用户真实配置就能覆盖四种分支；4b 再用真实 `CONFIG_PATH` 把「配置文件 → 系统提示段」这条线接上。

### 2.2 删除语义识别（5-10）

驱动方式：**双路**。既断言导出的 `isProtectedRemoval()`，也把同一条命令喂给从 `apply()` 抓到的真实 guard，检查拦截文案。

| 编号 | 输入 | 期望 |
| --- | --- | --- |
| 5 | `dsh plugin --profile web remove dsh-bulwark` | 拦，文案 `blocked: protected tool removal` |
| 6 | `dsh plugin --profile web list` | 放行 |
| 7 | `pnpm remove dsh-bulwark` | 拦 |
| 8 | `npm uninstall dsh-bulwark` | 拦 |
| 9 | `pnpm install dsh-bulwark` | 放行（缺 remove 关键词） |
| 10 | 空字符串 | 放行（不抛错） |

> 命名说明（卡 8 改名后）：这几条的命令字符串在 `tests/e2e.test.ts` 里**保持旧包名
> `dsh-fortress` 不变**（硬约束：不动断言期望值），因为它们靠本机
> `~/dsh-fortress-dev/config.json` 里未改动的 `protectedRemovalPatterns` 生效。
> 上表按项目新名书写；把新名写进 `protectedRemovalPatterns` 之后，同样会按预期拦截
> （见 MIGRATION.md 第 4 节）。

### 2.3 路径保护 · bash 命令级（11-15）

驱动方式：断言 `isProtectedPathModification()` + 真实 guard。

| 编号 | 输入 | 期望 |
| --- | --- | --- |
| 11 | `rm -rf /Users/liuzhaoyang/dsh-fortress-dev/foo` | 拦，文案 `blocked: protected path modification` |
| 12 | `cp /tmp/x /Users/liuzhaoyang/dsh-fortress-dev/y` | 拦（cp 只看最后一个操作数＝写入目标） |
| 13 | `cp /Users/liuzhaoyang/dsh-fortress-dev/x /tmp/y` | 放行（源在保护区、目标是 /tmp，属读取语义） |
| 14 | `ls /Users/liuzhaoyang/dsh-fortress-dev` | 放行（无变更动词） |
| 15 | `cat /Users/liuzhaoyang/dsh-fortress-dev/config.json` | 放行（同上） |

### 2.4 路径保护 · 文件工具（16-19）

| 编号 | 输入 | 期望 |
| --- | --- | --- |
| 16 | `write` → `…/dsh-fortress-dev/foo.txt` | 拦；同时 `isProtectedPath()` 为 true |
| 17 | `write` → `/tmp/foo.txt` | 放行；`isProtectedPath()` 为 false |
| 18 | `read` → `…/dsh-fortress-dev/config.json` | 放行。**注意**：该路径 `isProtectedPath()` 仍为 true，guard 只管 `write` / `edit` / `str_replace_editor`，`read` 不在管辖内 —— 这正是「读放行、写拦截」的语义分界 |
| 19 | `edit` → `…/dsh-fortress-dev/foo.txt` | 拦 |

### 2.5 畸形输入（20-22）

| 编号 | 输入 | 期望 |
| --- | --- | --- |
| 20 | `exec = undefined` | 放行且不抛错 |
| 21 | exec 缺 arguments | 放行且不抛错 |
| 22 | command 不是字符串 | 放行且不抛错（非字符串不参与判定） |

---

## 3. 为了让测试能 import 真实逻辑，对 index.ts 做了什么

只加 `export` 和给 `loadConfig` 加默认参数，**业务逻辑一行没动**：

| 位置 | 改动 |
| --- | --- |
| `CONFIG_PATH` | 加 `export`（测试要知道真实配置在哪） |
| `FortressConfig` | 加 `export`（接口，仅类型） |
| `DEFAULT_CONFIG` | 加 `export`（测试拿它做期望值） |
| `loadConfig` | 签名改为 `loadConfig(configPath: string = CONFIG_PATH)`，函数体内 `readFileSync(CONFIG_PATH)` → `readFileSync(configPath)`。默认参数，运行时行为完全不变（模块加载处仍是 `const CONFIG = loadConfig()`） |
| `isProtectedRemoval` | 加 `export` |
| `isProtectedPath` | 加 `export` |
| `isProtectedPathModification` | 加 `export` |

运行时的 `CONFIG`、`PROTECTED_PATHS`、`RULES_TEXT`、guard 注册方式、拦截文案都没有变化。

---

## 4. 手动跑一次真实端到端（headless）

自动化测试走的是**源码**；下面的 headless 验证走的是**真实 DSH 启动链路**（cordis.yml 按包名加载 → dist），所以先 build。改过源码后不 build 的话，headless 里跑的还是旧产物。

```bash
cd "/Users/liuzhaoyang/Documents/untitled folder/dsh-fortress"
pnpm build
```

**① 只验插件真的叠进了 headless 启动栈（不调用模型，最快）**

```bash
dsh --profile headless --patch cordis.yml --dump-config | grep -n -B2 -A2 dsh-bulwark
```

期望：能看到 `# == …/dsh-fortress/cordis.yml` 这一段，以及两条带 `DSH_FORTRESS_DISABLE` 的 `disabled: !!js …` 表达式。（这条已实测，退出码 0。）

**② 应被拦：删除插件**

```bash
dsh --profile headless --patch cordis.yml "用 bash 工具原样执行这条命令：dsh plugin --profile web remove dsh-bulwark。无论结果是成功还是失败都如实回报，不要换别的手段绕过。"
```

期望：模型回报被拦（`blocked: protected tool removal`），stderr 里能看到 `[dsh-bulwark:guard] bash command: …` 日志；插件仍然装着（`dsh plugin --profile web list` 里还在）。

**③ 应被拦：写受保护目录**

```bash
dsh --profile headless --patch cordis.yml "用 write 工具把 hello 写入 /Users/liuzhaoyang/dsh-fortress-dev/guard-probe.txt"
ls /Users/liuzhaoyang/dsh-fortress-dev/guard-probe.txt   # 期望：No such file
```

期望：write 被拦（`blocked: protected path modification`），文件不存在。

**④ 应放行：读受保护目录（读取语义）**

```bash
dsh --profile headless --patch cordis.yml "用 read 工具读 /Users/liuzhaoyang/dsh-fortress-dev/config.json，只回报 rulesText 字段的值"
```

期望：正常读出内容，不被拦。

**⑤ 逃生通道验证（卡 7）**

```bash
DSH_FORTRESS_DISABLE=1 dsh --profile headless --patch cordis.yml "用 write 工具把 hello 写入 /Users/liuzhaoyang/dsh-fortress-dev/guard-probe.txt，然后回报是否成功"
ls -l /Users/liuzhaoyang/dsh-fortress-dev/guard-probe.txt   # 期望：文件存在（逃生生效＝不再拦）
rm /Users/liuzhaoyang/dsh-fortress-dev/guard-probe.txt      # 清理探针
```

期望：同样的写入动作不再被拦，说明插件整体没被加载。完整逃生/恢复说明见 `DISASTER-RECOVERY.md`。

---

## 5. 排错

- **第 5-19 条失败**：先看 `/Users/liuzhaoyang/dsh-fortress-dev/config.json` —— 这几条依赖 `protectedPaths` 含 `/Users/liuzhaoyang/dsh-fortress-dev`、`protectedRemovalPatterns` 含 5 条默认规则。恢复默认见 `CONFIG.md` 里的示例 config.json。注意 `CONFIG` 是模块加载时算一次的，改完配置文件要重跑测试（DSH 里则要重启进程）。
- **第 1-4 条失败**：它们只碰临时目录，失败基本就是 `loadConfig` 的回退分支被改坏了。
- **报「apply() 没有注册 tools.guard 回调」**：假 ctx 形状过时了。对照 `index.ts` 里 `apply()` 用到的 ctx API（`get` / `effect` / `tools.guard` / `systemPrompt.getSectionOrder` / `systemPrompt.section`），同步补到测试的 `fakeContext()`。
- **类型检查**：`tsconfig.json` 的 include 只有 `src/**/*.ts`，且 exclude 了 `**/*.test.ts`，所以这份 e2e 不参与 `pnpm typecheck`；它靠 Node 的类型擦除运行，不靠 tsc。

---

## 6. 相关文件

| 文件 | 作用 |
| --- | --- |
| `tests/e2e.test.ts` | 本说明对应的自动化测试（23 条） |
| `src/index.ts` | 被测源码（守则段 + tools.guard） |
| `CONFIG.md` | config.json 字段说明与示例 |
| `DISASTER-RECOVERY.md` | 逃生通道与恢复流程 |