docs: 指定测试计划

docs/test-plans/10-fix-weak-tests.md

@@ -0,0 +1,361 @@
+# Plan 10 — 修复 WEAK 评分测试文件
+
+> 优先级：高 | 8 个文件 | 预估新增/修改 ~60 个测试用例
+
+本计划修复 testing-spec.md 中评定为 WEAK 的 8 个测试文件的断言缺陷和覆盖缺口。
+
+---
+
+## 10.1 `src/utils/__tests__/format.test.ts`
+
+**问题**：`formatNumber`、`formatTokens`、`formatRelativeTime` 使用 `toContain` 代替精确匹配，无法检测格式回归。
+
+### 修改清单
+
+#### formatNumber — toContain → toBe
+
+```typescript
+// 当前（弱）
+expect(formatNumber(1321)).toContain("k");
+expect(formatNumber(1500000)).toContain("m");
+
+// 修复为
+expect(formatNumber(1321)).toBe("1.3k");
+expect(formatNumber(1500000)).toBe("1.5m");
+```
+
+> 注意：`Intl.NumberFormat` 输出可能因 locale 不同。若 CI locale 不一致，改用 `toMatch(/^\d+(\.\d)?[km]$/)` 正则匹配。
+
+#### formatTokens — 补精确断言
+
+```typescript
+expect(formatTokens(1000)).toBe("1k");
+expect(formatTokens(1500)).toBe("1.5k");
+```
+
+#### formatRelativeTime — toContain → toBe
+
+```typescript
+// 当前（弱）
+expect(formatRelativeTime(diff, now)).toContain("30");
+expect(formatRelativeTime(diff, now)).toContain("ago");
+
+// 修复为
+expect(formatRelativeTime(diff, now)).toBe("30s ago");
+```
+
+#### 新增：formatDuration 进位边界
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| 59.5s 进位 | 59500ms | 至少含 `1m` |
+| 59m59s 进位 | 3599000ms | 至少含 `1h` |
+| sub-millisecond | 0.5ms | `"<1ms"` 或 `"0ms"` |
+
+#### 新增：未测试函数
+
+| 函数 | 最少用例 |
+|------|---------|
+| `formatRelativeTimeAgo` | 2（过去 / 未来） |
+| `formatLogMetadata` | 1（基本调用不抛错） |
+| `formatResetTime` | 2（有值 / null） |
+| `formatResetText` | 1（基本调用） |
+
+---
+
+## 10.2 `src/tools/shared/__tests__/gitOperationTracking.test.ts`
+
+**问题**：`detectGitOperation` 内部调用 `getCommitCounter()`、`getPrCounter()`、`logEvent()`，测试产生分析副作用。
+
+### 修改清单
+
+#### 添加 analytics mock
+
+在文件顶部添加 `mock.module`：
+
+```typescript
+import { mock, afterAll, afterEach, beforeEach } from "bun:test";
+
+mock.module("src/services/analytics/index.ts", () => ({
+  logEvent: mock(() => {}),
+}));
+
+mock.module("src/bootstrap/state.ts", () => ({
+  getCommitCounter: mock(() => ({ increment: mock(() => {}) })),
+  getPrCounter: mock(() => ({ increment: mock(() => {}) })),
+}));
+```
+
+> 需验证 `detectGitOperation` 的实际导入路径，按需调整 mock 目标。
+
+#### 新增：缺失的 GH PR actions
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| gh pr edit | `'gh pr edit 123 --title "fix"'` | `result.pr.number === 123` |
+| gh pr close | `'gh pr close 456'` | `result.pr.number === 456` |
+| gh pr ready | `'gh pr ready 789'` | `result.pr.number === 789` |
+| gh pr comment | `'gh pr comment 123 --body "done"'` | `result.pr.number === 123` |
+
+#### 新增：parseGitCommitId 边界
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| 完整 40 字符 SHA | `'[abcdef0123456789abcdef0123456789abcdef01] ...'` | 返回完整 40 字符 |
+| 畸形括号输出 | `'create mode 100644 file.txt'` | 返回 `null` |
+
+---
+
+## 10.3 `src/utils/permissions/__tests__/PermissionMode.test.ts`
+
+**问题**：`isExternalPermissionMode` 在非 ant 环境永远返回 true，false 路径从未执行；mode 覆盖不完整。
+
+### 修改清单
+
+#### 补全 mode 覆盖
+
+| 函数 | 缺失的 mode |
+|------|-------------|
+| `permissionModeTitle` | `bypassPermissions`, `dontAsk` |
+| `permissionModeShortTitle` | `dontAsk`, `acceptEdits` |
+| `getModeColor` | `dontAsk`, `acceptEdits`, `plan` |
+| `permissionModeFromString` | `acceptEdits`, `bypassPermissions` |
+| `toExternalPermissionMode` | `acceptEdits`, `bypassPermissions` |
+
+#### 修复 isExternalPermissionMode
+
+```typescript
+// 当前：只测了非 ant 环境（永远 true）
+// 需要新增 ant 环境测试
+describe("when USER_TYPE is 'ant'", () => {
+  beforeEach(() => {
+    process.env.USER_TYPE = "ant";
+  });
+  afterEach(() => {
+    delete process.env.USER_TYPE;
+  });
+
+  test("returns false for 'auto' in ant context", () => {
+    expect(isExternalPermissionMode("auto")).toBe(false);
+  });
+
+  test("returns false for 'bubble' in ant context", () => {
+    expect(isExternalPermissionMode("bubble")).toBe(false);
+  });
+
+  test("returns true for non-ant modes in ant context", () => {
+    expect(isExternalPermissionMode("plan")).toBe(true);
+  });
+});
+```
+
+#### 新增：permissionModeSchema
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| 有效 mode | `'plan'` | `success: true` |
+| 无效 mode | `'invalid'` | `success: false` |
+
+---
+
+## 10.4 `src/utils/permissions/__tests__/dangerousPatterns.test.ts`
+
+**问题**：纯数据 smoke test，无行为验证。
+
+### 修改清单
+
+#### 新增：重复值检查
+
+```typescript
+test("CROSS_PLATFORM_CODE_EXEC has no duplicates", () => {
+  const set = new Set(CROSS_PLATFORM_CODE_EXEC);
+  expect(set.size).toBe(CROSS_PLATFORM_CODE_EXEC.length);
+});
+
+test("DANGEROUS_BASH_PATTERNS has no duplicates", () => {
+  const set = new Set(DANGEROUS_BASH_PATTERNS);
+  expect(set.size).toBe(DANGEROUS_BASH_PATTERNS.length);
+});
+```
+
+#### 新增：全量成员断言（用 Set 确保精确）
+
+```typescript
+test("CROSS_PLATFORM_CODE_EXEC contains expected interpreters", () => {
+  const expected = ["node", "python", "python3", "ruby", "perl", "php",
+    "bun", "deno", "npx", "tsx"];
+  const set = new Set(CROSS_PLATFORM_CODE_EXEC);
+  for (const entry of expected) {
+    expect(set.has(entry)).toBe(true);
+  }
+});
+```
+
+#### 新增：空字符串不匹配
+
+```typescript
+test("empty string does not match any pattern", () => {
+  for (const pattern of DANGEROUS_BASH_PATTERNS) {
+    expect("".startsWith(pattern)).toBe(false);
+  }
+});
+```
+
+---
+
+## 10.5 `src/utils/__tests__/zodToJsonSchema.test.ts`
+
+**问题**：object 属性仅 `toBeDefined` 未验证类型结构；optional 字段未验证 absence。
+
+### 修改清单
+
+#### 修复 object schema 测试
+
+```typescript
+// 当前（弱）
+expect(schema.properties!.name).toBeDefined();
+expect(schema.properties!.age).toBeDefined();
+
+// 修复为
+expect(schema.properties!.name).toEqual({ type: "string" });
+expect(schema.properties!.age).toEqual({ type: "number" });
+```
+
+#### 修复 optional 字段测试
+
+```typescript
+test("optional field is not in required array", () => {
+  const schema = zodToJsonSchema(z.object({
+    required: z.string(),
+    optional: z.string().optional(),
+  }));
+  expect(schema.required).toEqual(["required"]);
+  expect(schema.required).not.toContain("optional");
+});
+```
+
+#### 新增：缺失的 schema 类型
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| `z.literal("foo")` | `z.literal("foo")` | `{ const: "foo" }` |
+| `z.null()` | `z.null()` | `{ type: "null" }` |
+| `z.union()` | `z.union([z.string(), z.number()])` | `{ anyOf: [...] }` |
+| `z.record()` | `z.record(z.string(), z.number())` | `{ type: "object", additionalProperties: { type: "number" } }` |
+| `z.tuple()` | `z.tuple([z.string(), z.number()])` | `{ type: "array", items: [...], additionalItems: false }` |
+| 嵌套 object | `z.object({ a: z.object({ b: z.string() }) })` | 验证嵌套属性结构 |
+
+---
+
+## 10.6 `src/utils/__tests__/envValidation.test.ts`
+
+**问题**：`validateBoundedIntEnvVar` lower bound=100 时 value=1 返回 `status: "valid"`，疑似源码 bug。
+
+### 修改清单
+
+#### 验证 lower bound 行为
+
+```typescript
+// 当前测试
+test("value of 1 with lower bound 100", () => {
+  const result = validateBoundedIntEnvVar("1", { defaultValue: 100, upperLimit: 1000, lowerLimit: 100 });
+  // 如果源码有 bug，这里应该暴露
+  expect(result.effective).toBeGreaterThanOrEqual(100);
+  expect(result.status).toBe(result.effective !== 100 ? "capped" : "valid");
+});
+```
+
+#### 新增边界用例
+
+| 用例 | value | lowerLimit | 期望 |
+|------|-------|------------|------|
+| 低于 lower bound | `"50"` | 100 | `effective: 100, status: "capped"` |
+| 等于 lower bound | `"100"` | 100 | `effective: 100, status: "valid"` |
+| 浮点截断 | `"50.7"` | 100 | `effective: 100`（parseInt 截断后 cap） |
+| 空白字符 | `" 500 "` | 1 | `effective: 500, status: "valid"` |
+| defaultValue 为 0 | `"0"` | 0 | 需确认 `parsed <= 0` 逻辑 |
+
+> **行动**：先确认 `validateBoundedIntEnvVar` 源码中 lower bound 的实际执行路径。如果确实不生效，需先修源码再补测试。
+
+---
+
+## 10.7 `src/utils/__tests__/file.test.ts`
+
+**问题**：`addLineNumbers` 仅 `toContain`，未验证完整格式。
+
+### 修改清单
+
+#### 修复 addLineNumbers 断言
+
+```typescript
+// 当前（弱）
+expect(result).toContain("1");
+expect(result).toContain("hello");
+
+// 修复为（需确定 isCompactLinePrefixEnabled 行为）
+// 假设 compact=false，格式为 "     1→hello"
+test("formats single line with tab prefix", () => {
+  // 先确认环境，如果 compact 模式不确定，用正则
+  expect(result).toMatch(/^\s*\d+[→\t]hello$/m);
+});
+```
+
+#### 新增：stripLineNumberPrefix 边界
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| 纯数字行 | `"123"` | `""` |
+| 无内容前缀 | `"→"` | `""` |
+| compact 格式 `"1\thello"` | `"1\thello"` | `"hello"` |
+
+#### 新增：pathsEqual 边界
+
+| 用例 | a | b | 期望 |
+|------|---|---|------|
+| 尾部斜杠差异 | `"/a/b"` | `"/a/b/"` | `false` |
+| `..` 段 | `"/a/../b"` | `"/b"` | 视实现而定 |
+
+---
+
+## 10.8 `src/utils/__tests__/notebook.test.ts`
+
+**问题**：`mapNotebookCellsToToolResult` 内容检查用 `toContain`，未验证 XML 格式。
+
+### 修改清单
+
+#### 修复 content 断言
+
+```typescript
+// 当前（弱）
+expect(result).toContain("cell-0");
+expect(result).toContain("print('hello')");
+
+// 修复为
+expect(result).toContain('<cell id="cell-0">');
+expect(result).toContain("</cell>");
+```
+
+#### 新增：parseCellId 边界
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| 负数 | `"cell--1"` | `null` |
+| 前导零 | `"cell-007"` | `7` |
+| 极大数 | `"cell-999999999"` | `999999999` |
+
+#### 新增：mapNotebookCellsToToolResult 边界
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| 空 data 数组 | `{ cells: [] }` | 空字符串或空结果 |
+| 无 cell_id | `{ cell_type: "code", source: "x" }` | fallback 到 `cell-${index}` |
+| error output | `{ output_type: "error", ename: "Error", evalue: "msg" }` | 包含 error 信息 |
+
+---
+
+## 验收标准
+
+- [ ] `bun test` 全部通过
+- [ ] 8 个文件评分从 WEAK 提升至 ACCEPTABLE 或 GOOD
+- [ ] `toContain` 仅用于警告文本等确实不确定精确值的场景
+- [ ] envValidation bug 确认并修复（或确认非 bug 并更新测试）

docs/test-plans/11-strengthen-acceptable-tests.md

@@ -0,0 +1,177 @@
+# Plan 11 — 加强 ACCEPTABLE 评分测试
+
+> 优先级：中 | ~15 个文件 | 预估新增 ~80 个测试用例
+
+本计划对 ACCEPTABLE 评分文件中的具体缺陷进行定向加强。每个条目只列出需要改动的部分，不做全量重写。
+
+---
+
+## 11.1 `src/utils/__tests__/diff.test.ts`
+
+| 改动 | 当前 | 改为 |
+|------|------|------|
+| `getPatchFromContents` 断言 | `hunks.length > 0` | 验证具体 `+`/`-` 行内容 |
+| `$` 字符转义 | 未测试 | 新增含 `$` 的内容测试 |
+| `ignoreWhitespace` 选项 | 未测试 | 新增 `ignoreWhitespace: true` 用例 |
+| 删除全部内容 | 未测试 | `newContent: ""` |
+| 多 hunk 偏移 | `adjustHunkLineNumbers` 仅单 hunk | 新增多 hunk 同数组测试 |
+
+---
+
+## 11.2 `src/utils/__tests__/path.test.ts`
+
+当前仅覆盖 2/5+ 导出函数。新增：
+
+| 函数 | 最少用例 | 关键边界 |
+|------|---------|---------|
+| `expandPath` | 6 | `~/` 展开、绝对路径直通、相对路径、空串、含 null 字节、`~user` 格式 |
+| `toRelativePath` | 3 | 同级文件、子目录、父目录 |
+| `sanitizePath` | 3 | 正常路径、含 `..` 段、空串 |
+
+`containsPathTraversal` 补充：
+- URL 编码 `%2e%2e%2f`（确认不匹配，记录为非需求）
+- 混合分隔符 `foo/..\bar`
+
+`normalizePathForConfigKey` 补充：
+- 混合分隔符 `foo/bar\baz`
+- 冗余分隔符 `foo//bar`
+- Windows 盘符 `C:\foo\bar`
+
+---
+
+## 11.3 `src/utils/__tests__/uuid.test.ts`
+
+| 改动 | 说明 |
+|------|------|
+| 大写测试断言强化 | `not.toBeNull()` → 验证标准化输出（小写+连字符格式） |
+| 新增 `createAgentId` | 3 用例：无 label / 有 label / 输出格式正则 `/^a[a-z]*-[a-f0-9]{16}$/` |
+| 前后空白 | `" 550e8400-...  "` 期望 `null` |
+
+---
+
+## 11.4 `src/utils/__tests__/semver.test.ts`
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| pre-release 比较 | `gt("1.0.0", "1.0.0-alpha")` | `true` |
+| pre-release 间比较 | `order("1.0.0-alpha", "1.0.0-beta")` | `-1` |
+| tilde range | `satisfies("1.2.5", "~1.2.3")` | `true` |
+| `*` 通配符 | `satisfies("2.0.0", "*")` | `true` |
+| 畸形版本 | `order("abc", "1.0.0")` | 确认不抛错 |
+| `0.0.0` | `gt("0.0.0", "0.0.0")` | `false` |
+
+---
+
+## 11.5 `src/utils/__tests__/hash.test.ts`
+
+| 改动 | 当前 | 改为 |
+|------|------|------|
+| djb2 32 位检查 | `hash \| 0`（恒 true） | `Number.isSafeInteger(hash) && Math.abs(hash) <= 0x7FFFFFFF` |
+| hashContent 空串 | 未测试 | 新增 |
+| hashContent 格式 | 未验证输出为数字串 | `toMatch(/^\d+$/)` |
+| hashPair 空串 | 未测试 | `hashPair("", "b")`, `hashPair("", "")` |
+| 已知答案 | 无 | 断言 `djb2Hash("hello")` 为特定值（需先在控制台运行一次确定） |
+
+---
+
+## 11.6 `src/utils/__tests__/claudemd.test.ts`
+
+当前仅覆盖 3 个辅助函数。新增：
+
+| 用例 | 函数 | 说明 |
+|------|------|------|
+| 未闭合注释 | `stripHtmlComments` | `"<!-- no close some text"` → 原样返回 |
+| 跨行注释 | `stripHtmlComments` | `"<!--\nmulti\nline\n-->text"` → `"text"` |
+| 同行注释+内容 | `stripHtmlComments` | `"<!-- note -->some text"` → `"some text"` |
+| 内联代码中的注释 | `stripHtmlComments` | `` `<!-- kept -->` `` → 保留 |
+| 大小写不敏感 | `isMemoryFilePath` | `"claude.md"`, `"CLAUDE.MD"` |
+| 非 .md 规则文件 | `isMemoryFilePath` | `.claude/rules/foo.txt` → `false` |
+| 空数组 | `getLargeMemoryFiles` | `[]` → `[]` |
+
+---
+
+## 11.7 `src/tools/FileEditTool/__tests__/utils.test.ts`
+
+| 函数 | 新增用例 |
+|------|---------|
+| `normalizeQuotes` | 混合引号 `"`she said 'hello'"` |
+| `stripTrailingWhitespace` | CR-only `\r`、无尾部换行、全空白串 |
+| `findActualString` | 空 content、Unicode content |
+| `preserveQuoteStyle` | 单引号、缩写中的撇号（如 `it's`）、空串 |
+| `applyEditToFile` | `replaceAll=true` 零匹配、`oldString` 无尾部 `\n`、多行内容 |
+
+---
+
+## 11.8 `src/utils/model/__tests__/providers.test.ts`
+
+| 改动 | 说明 |
+|------|------|
+| 删除 `originalEnv` | 未使用，消除死代码 |
+| env 恢复改为快照 | `beforeEach` 保存 `process.env`，`afterEach` 恢复 |
+| 新增三变量同时设置 | bedrock + vertex + foundry 全部为 `"1"`，验证优先级 |
+| 新增非 `"1"` 值 | `"true"`, `"0"`, `""` |
+| `isFirstPartyAnthropicBaseUrl` | URL 含路径 `/v1`、含尾斜杠、非 HTTPS |
+
+---
+
+## 11.9 `src/utils/__tests__/hyperlink.test.ts`
+
+| 用例 | 说明 |
+|------|------|
+| 空 URL | `createHyperlink("http://x.com", "", { supported: true })` 不抛错 |
+| undefined supportsHyperlinks | 选项未传时走默认检测 |
+| 非 ant staging URL | `USER_TYPE !== "ant"` 时 staging 返回 `false` |
+
+---
+
+## 11.10 `src/utils/__tests__/objectGroupBy.test.ts`
+
+| 用例 | 说明 |
+|------|------|
+| key 返回 undefined | `(_, i) => undefined` → 全部归入 `undefined` 组 |
+| key 为特殊字符 | `({ name }) => name` 含空格/中文 |
+
+---
+
+## 11.11 `src/utils/__tests__/CircularBuffer.test.ts`
+
+| 用例 | 说明 |
+|------|------|
+| capacity=1 | 添加 2 个元素，仅保留最后一个 |
+| 空 buffer 调用 getRecent | 返回空数组 |
+| getRecent(0) | 返回空数组 |
+
+---
+
+## 11.12 `src/utils/__tests__/contentArray.test.ts`
+
+| 用例 | 说明 |
+|------|------|
+| 混合交替 | `[tool_result, text, tool_result]` — 验证插入到正确位置 |
+
+---
+
+## 11.13 `src/utils/__tests__/argumentSubstitution.test.ts`
+
+| 用例 | 说明 |
+|------|------|
+| 转义引号 | `"he said \"hello\""` |
+| 越界索引 | `$ARGUMENTS[99]`（参数不够时） |
+| 多占位符 | `"cmd $0 $1 $0"` |
+
+---
+
+## 11.14 `src/utils/__tests__/messages.test.ts`
+
+| 改动 | 说明 |
+|------|------|
+| `normalizeMessages` 断言加强 | 验证拆分后的消息内容，不只是长度 |
+| `isNotEmptyMessage` 空白 | `[{ type: "text", text: "  " }]` |
+
+---
+
+## 验收标准
+
+- [ ] `bun test` 全部通过
+- [ ] 目标文件评分从 ACCEPTABLE 提升至 GOOD
+- [ ] 无 `toContain` 用于精确值检查的场景

docs/test-plans/12-mock-reliability.md

@@ -0,0 +1,145 @@
+# Plan 12 — Mock 可靠性修复
+
+> 优先级：高 | 影响 4 个测试文件 | 预估修改 ~15 处
+
+本计划修复测试中 mock 相关的副作用、状态泄漏和虚假测试。
+
+---
+
+## 12.1 `gitOperationTracking.test.ts` — 消除分析副作用
+
+**当前问题**：`detectGitOperation` 内部调用 `logEvent()`、`getCommitCounter().increment()`、`getPrCounter().increment()`，每次测试运行都触发真实分析代码。
+
+**修复步骤**：
+
+1. 读取 `src/tools/shared/gitOperationTracking.ts`，确认 analytics 导入路径
+2. 在测试文件顶部添加 `mock.module`：
+
+```typescript
+import { mock } from "bun:test";
+
+mock.module("src/services/analytics/index.ts", () => ({
+  logEvent: mock(() => {}),
+  // 按需补充其他导出
+}));
+```
+
+3. 如果 `getCommitCounter` / `getPrCounter` 来自 `src/bootstrap/state.ts`：
+
+```typescript
+mock.module("src/bootstrap/state.ts", () => ({
+  getCommitCounter: mock(() => ({ increment: mock(() => {}) })),
+  getPrCounter: mock(() => ({ increment: mock(() => {}) })),
+  // 保留其他被测函数实际需要的导出
+}));
+```
+
+4. 使用 `await import()` 模式加载被测模块
+5. 运行测试验证无副作用
+
+**风险**：`mock.module` 会替换整个模块。如果 `detectGitOperation` 还需要其他来自这些模块的导出，需在 mock 工厂中提供。
+
+---
+
+## 12.2 `PermissionMode.test.ts` — 修复 `isExternalPermissionMode` 虚假测试
+
+**当前问题**：`isExternalPermissionMode` 依赖 `process.env.USER_TYPE`。非 ant 环境下所有 mode 都返回 true，测试从未覆盖 false 分支。
+
+**修复步骤**：
+
+1. 新增 ant 环境测试组（见 Plan 10.3 详细用例）
+2. 使用 `beforeEach`/`afterEach` 管理 `process.env.USER_TYPE`
+
+```typescript
+describe("when USER_TYPE is 'ant'", () => {
+  const originalUserType = process.env.USER_TYPE;
+  beforeEach(() => { process.env.USER_TYPE = "ant"; });
+  afterEach(() => {
+    if (originalUserType !== undefined) {
+      process.env.USER_TYPE = originalUserType;
+    } else {
+      delete process.env.USER_TYPE;
+    }
+  });
+
+  test("returns false for 'auto'", () => {
+    expect(isExternalPermissionMode("auto")).toBe(false);
+  });
+  test("returns false for 'bubble'", () => {
+    expect(isExternalPermissionMode("bubble")).toBe(false);
+  });
+  test("returns true for 'plan'", () => {
+    expect(isExternalPermissionMode("plan")).toBe(true);
+  });
+});
+```
+
+3. 验证新增测试确实执行 false 路径
+
+---
+
+## 12.3 `providers.test.ts` — 环境变量快照恢复
+
+**当前问题**：
+- `originalEnv` 声明后未使用
+- `afterEach` 仅删除已知 3 个 key，如果源码新增 env var，测试间状态泄漏
+
+**修复步骤**：
+
+```typescript
+let savedEnv: Record<string, string | undefined>;
+
+beforeEach(() => {
+  savedEnv = {};
+  for (const key of Object.keys(process.env)) {
+    savedEnv[key] = process.env[key];
+  }
+});
+
+afterEach(() => {
+  // 删除所有当前 env，恢复快照
+  for (const key of Object.keys(process.env)) {
+    delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value !== undefined) {
+      process.env[key] = value;
+    }
+  }
+});
+```
+
+> 简化方案：只保存/恢复相关 key 列表 `["CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY", "ANTHROPIC_BASE_URL", "USER_TYPE"]`，但需注释说明新增 env var 时需同步更新。
+
+---
+
+## 12.4 `envUtils.test.ts` — 验证环境变量恢复完整性
+
+**当前状态**：已有 `afterEach` 恢复。需审查：
+
+1. 确认所有 `describe` 块中的 `afterEach` 都完整恢复了修改的 env var
+2. 确认 `process.argv` 修改也被恢复（`getClaudeConfigHomeDir` 测试修改了 argv）
+3. 新增：`afterEach` 中断言无意外 env 泄漏（可选，CI-only）
+
+---
+
+## 12.5 `sleep.test.ts` / `memoize.test.ts` — 时间敏感测试加固
+
+**当前状态**：已有合理 margin。可选加固：
+
+| 文件 | 用例 | 当前 | 加固 |
+|------|------|------|------|
+| `sleep.test.ts` | `resolves after timeout` | `sleep(50)`, check `>= 40ms` | 增大 margin：`sleep(50)`, check `>= 30ms` |
+| `memoize.test.ts` | stale serve & refresh | TTL=1ms, wait 10ms | 增大 margin：TTL=5ms, wait 50ms |
+
+> 仅在 CI 出现 flaky 时执行此加固。
+
+---
+
+## 验收标准
+
+- [ ] `gitOperationTracking.test.ts` 无分析副作用（可通过在 mock 中增加 `expect(logEvent).toHaveBeenCalledTimes(N)` 验证）
+- [ ] `PermissionMode.test.ts` 的 `isExternalPermissionMode` 覆盖 true + false 分支
+- [ ] `providers.test.ts` 的 `originalEnv` 死代码已删除
+- [ ] 所有修改 env 的测试文件恢复完整
+- [ ] `bun test` 全部通过

docs/test-plans/13-cjk-truncate-tests.md

@@ -0,0 +1,71 @@
+# Plan 13 — truncate CJK/Emoji 补充测试
+
+> 优先级：中 | 1 个文件 | 预估新增 ~15 个测试用例
+
+`truncate.ts` 使用 `stringWidth` 和 grapheme segmentation 实现宽度感知截断，但现有测试仅覆盖 ASCII。这是核心场景缺失。
+
+---
+
+## 被测函数
+
+- `truncateToWidth(text, maxWidth)` — 尾部截断加 `…`
+- `truncateStartToWidth(text, maxWidth)` — 头部截断加 `…`
+- `truncateToWidthNoEllipsis(text, maxWidth)` — 尾部截断无省略号
+- `truncatePathMiddle(path, maxLength)` — 路径中间截断
+- `wrapText(text, maxWidth)` — 按宽度换行
+
+---
+
+## 新增用例
+
+### CJK 全角字符
+
+| 用例 | 函数 | 输入 | maxWidth | 期望行为 |
+|------|------|------|----------|----------|
+| 纯中文截断 | `truncateToWidth` | `"你好世界"` | 4 | `"你好…"` (每个中文字占 2 宽度) |
+| 中英混合 | `truncateToWidth` | `"hello你好"` | 8 | `"hello你…"` |
+| 全角不截断 | `truncateToWidth` | `"你好"` | 4 | `"你好"` (恰好 4) |
+| emoji 单字符 | `truncateToWidth` | `"👋"` | 2 | `"👋"` (emoji 通常 2 宽度) |
+| emoji 截断 | `truncateToWidth` | `"hello 👋 world"` | 8 | 确认宽度计算正确 |
+| 头部中文 | `truncateStartToWidth` | `"你好世界"` | 4 | `"…界"` |
+| 无省略中文 | `truncateToWidthNoEllipsis` | `"你好世界"` | 4 | `"你好"` |
+
+> **注意**：`stringWidth` 对 CJK/emoji 的宽度计算取决于具体实现。先在 REPL 中运行确认实际宽度再写断言：
+> ```typescript
+> import { stringWidth } from "src/utils/truncate.ts";
+> console.log(stringWidth("你好")); // 确认是 4 还是 2
+> console.log(stringWidth("👋"));  // 确认 emoji 宽度
+> ```
+
+### 路径中间截断补充
+
+| 用例 | 输入 | maxLength | 期望 |
+|------|------|-----------|------|
+| 文件名超长 | `"/very/long/path/to/MyComponent.tsx"` | 10 | 含 `…` 且以 `.tsx` 结尾 |
+| 无斜杠短串 | `"abc"` | 1 | 确认行为不抛错 |
+| maxLength 极小 | `"/a/b"` | 1 | 确认不抛错 |
+| maxLength=4 | `"/a/b/c.ts"` | 4 | 确认行为 |
+
+### wrapText 补充
+
+| 用例 | 输入 | maxWidth | 期望 |
+|------|------|----------|------|
+| 含换行符 | `"hello\nworld"` | 10 | 保留原有换行 |
+| 宽度=0 | `"hello"` | 0 | 空串或原串（确认不抛错） |
+
+---
+
+## 实施步骤
+
+1. 在 REPL 中确认 `stringWidth` 对 CJK/emoji 的实际返回值
+2. 按实际值编写精确断言
+3. 如果 `stringWidth` 依赖 ICU 或平台特性，添加平台检查（`process.platform !== "win32"` 跳过条件）
+4. 运行测试
+
+---
+
+## 验收标准
+
+- [ ] 至少 5 个 CJK/emoji 相关测试通过
+- [ ] 断言基于实际 `stringWidth` 返回值，非猜测
+- [ ] `bun test` 全部通过

docs/test-plans/14-integration-tests.md

@@ -0,0 +1,191 @@
+# Plan 14 — 集成测试搭建
+
+> 优先级：中 | 新建 ~3 个测试文件 | 预估 ~30 个测试用例
+
+当前 `tests/integration/` 目录为空，spec 设计的三个集成测试均未创建。本计划搭建 mock 基础设施并实现核心集成测试。
+
+---
+
+## 14.1 搭建 `tests/mocks/` 基础设施
+
+### 文件结构
+
+```
+tests/
+├── mocks/
+│   ├── api-responses.ts       # Claude API mock 响应
+│   ├── file-system.ts         # 临时文件系统工具
+│   └── fixtures/
+│       ├── sample-claudemd.md # CLAUDE.md 样本
+│       └── sample-messages.json # 消息样本
+├── integration/
+│   ├── tool-chain.test.ts
+│   ├── context-build.test.ts
+│   └── message-pipeline.test.ts
+└── helpers/
+    └── setup.ts               # 共享 beforeAll/afterAll
+```
+
+### `tests/mocks/file-system.ts`
+
+```typescript
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export async function createTempDir(prefix = "claude-test-"): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), prefix));
+  return dir;
+}
+
+export async function cleanupTempDir(dir: string): Promise<void> {
+  await rm(dir, { recursive: true, force: true });
+}
+
+export async function writeTempFile(dir: string, name: string, content: string): Promise<string> {
+  const path = join(dir, name);
+  await writeFile(path, content, "utf-8");
+  return path;
+}
+```
+
+### `tests/mocks/fixtures/sample-claudemd.md`
+
+```markdown
+# Project Instructions
+
+This is a sample CLAUDE.md file for testing.
+```
+
+### `tests/mocks/api-responses.ts`
+
+```typescript
+export const mockStreamResponse = {
+  type: "message_start" as const,
+  message: {
+    id: "msg_mock_001",
+    type: "message" as const,
+    role: "assistant",
+    content: [],
+    model: "claude-sonnet-4-20250514",
+    stop_reason: null,
+    stop_sequence: null,
+    usage: { input_tokens: 100, output_tokens: 0 },
+  },
+};
+
+export const mockTextBlock = {
+  type: "content_block_start" as const,
+  index: 0,
+  content_block: { type: "text" as const, text: "Mock response" },
+};
+
+export const mockToolUseBlock = {
+  type: "content_block_start" as const,
+  index: 1,
+  content_block: {
+    type: "tool_use" as const,
+    id: "toolu_mock_001",
+    name: "Read",
+    input: { file_path: "/tmp/test.txt" },
+  },
+};
+
+export const mockEndEvent = {
+  type: "message_stop" as const,
+};
+```
+
+---
+
+## 14.2 `tests/integration/tool-chain.test.ts`
+
+**目标**：验证 Tool 注册 → 发现 → 权限检查链路。
+
+### 前置条件
+
+`src/tools.ts` 的 `getAllBaseTools` / `getTools` 导入链过重。策略：
+- 尝试直接 import 并 mock 最重依赖
+- 若不可行，改为测试 `src/Tool.ts` 的 `findToolByName` + 手动构造 tool 列表
+
+### 用例
+
+| # | 用例 | 验证点 |
+|---|------|--------|
+| 1 | `findToolByName("Bash")` 在已注册列表中查找 | 返回正确的 tool 定义 |
+| 2 | `findToolByName("NonExistent")` | 返回 `undefined` |
+| 3 | `findToolByName` 大小写不敏感 | `"bash"` 也能找到 |
+| 4 | `filterToolsByDenyRules` 拒绝特定工具 | 被拒绝工具不在结果中 |
+| 5 | `parseToolPreset("default")` 返回已知列表 | 包含核心 tools |
+| 6 | `buildTool` 构建的 tool 可被 `findToolByName` 发现 | 端到端验证 |
+
+> 如果 `getAllBaseTools` 确实不可导入，改用 mock tool list 替代。
+
+---
+
+## 14.3 `tests/integration/context-build.test.ts`
+
+**目标**：验证系统提示组装流程（CLAUDE.md 加载 + git status + 日期注入）。
+
+### 前置条件
+
+`src/context.ts` 依赖链极重。策略：
+- Mock `src/bootstrap/state.ts`（提供 cwd、projectRoot）
+- Mock `src/utils/git.ts`（提供 git status）
+- 使用真实 `src/utils/claudemd.ts` + 临时文件
+
+### 用例
+
+| # | 用例 | 验证点 |
+|---|------|--------|
+| 1 | 基本 context 构建 | 返回值包含系统提示字符串 |
+| 2 | CLAUDE.md 内容出现在 context 中 | `stripHtmlComments` 后的内容被包含 |
+| 3 | 多层目录 CLAUDE.md 合并 | 父目录 + 子目录 CLAUDE.md 都被加载 |
+| 4 | 无 CLAUDE.md 时不报错 | context 正常返回，无 crash |
+| 5 | git status 为 null | context 正常构建（测试环境中 git 不可用时） |
+
+> **风险评估**：如果 mock `context.ts` 的依赖链成本过高，退化为测试 `buildEffectiveSystemPrompt`（已在 systemPrompt.test.ts 中完成），记录为已知限制。
+
+---
+
+## 14.4 `tests/integration/message-pipeline.test.ts`
+
+**目标**：验证用户输入 → 消息格式化 → API 请求构建。
+
+### 前置条件
+
+`src/services/api/claude.ts` 构建最终 API 请求。策略：
+- Mock Anthropic SDK 的 streaming endpoint
+- 验证请求参数结构
+
+### 用例
+
+| # | 用例 | 验证点 |
+|---|------|--------|
+| 1 | 文本消息格式化 | `createUserMessage` 生成正确 role+content |
+| 2 | tool_result 消息格式化 | 包含 tool_use_id 和 content |
+| 3 | 多轮消息序列化 | messages 数组保持顺序 |
+| 4 | 系统提示注入到请求 | API 请求的 system 字段非空 |
+| 5 | 消息 normalize 后格式一致 | `normalizeMessages` 输出结构正确 |
+
+> **现实评估**：消息格式化的大部分已在 `messages.test.ts` 覆盖。API 请求构建需要 mock SDK，复杂度高。如果投入产出比低，仅实现用例 1-3 和 5，用例 4 标记为 stretch goal。
+
+---
+
+## 实施步骤
+
+1. 创建 `tests/mocks/` 目录和基础文件
+2. 实现 `tool-chain.test.ts`（最低风险，最高价值）
+3. 评估 `context-build.test.ts` 可行性，决定是否实施
+4. 实现 `message-pipeline.test.ts`（可降级为单元测试）
+5. 更新 `testing-spec.md` 状态
+
+---
+
+## 验收标准
+
+- [ ] `tests/mocks/` 基础设施可用
+- [ ] 至少 `tool-chain.test.ts` 实现并通过
+- [ ] 集成测试独立于单元测试运行：`bun test tests/integration/`
+- [ ] 所有集成测试使用 `createTempDir` + `cleanupTempDir`，不留文件系统残留
+- [ ] `bun test` 全部通过

docs/test-plans/15-cli-coverage-baseline.md

@@ -0,0 +1,67 @@
+# Plan 15 — CLI 参数测试 + 覆盖率基线
+
+> 优先级：低 | 预估 ~15 个测试用例
+
+---
+
+## 15.1 `src/main.tsx` CLI 参数测试
+
+**目标**：覆盖 Commander.js 配置的参数解析和模式切换。
+
+### 前置条件
+
+`src/main.tsx` 的 Commander 实例通常在模块顶层创建。测试策略：
+- 直接构造 Commander 实例或 mock `main.tsx` 的 program 导出
+- 使用 `parseArgs` 而非 `parse`（不触发 `process.exit`）
+
+### 用例
+
+| # | 用例 | 输入 | 期望 |
+|---|------|------|------|
+| 1 | 默认模式 | `[]` | 模式为 REPL |
+| 2 | pipe 模式 | `["-p"]` | 模式为 pipe |
+| 3 | pipe 带输入 | `["-p", "say hello"]` | 输入为 `"say hello"` |
+| 4 | print 模式 | `["--print", "hello"]` | 等效于 pipe |
+| 5 | verbose | `["-v"]` | verbose 标志为 true |
+| 6 | model 选择 | `["--model", "claude-opus-4-6"]` | model 值正确传递 |
+| 7 | system prompt | `["--system-prompt", "custom"]` | system prompt 被设置 |
+| 8 | help | `["--help"]` | 显示帮助信息，不报错 |
+| 9 | version | `["--version"]` | 显示版本号 |
+| 10 | unknown flag | `["--nonexistent"]` | 不报错（Commander 允许未知参数时） |
+
+> **风险**：`main.tsx` 可能执行初始化逻辑（auth、analytics），需要在 mock 环境中运行。如果复杂度过高，降级为只测试参数解析部分。
+
+---
+
+## 15.2 覆盖率基线
+
+### 运行命令
+
+```bash
+bun test --coverage 2>&1 | tail -50
+```
+
+### 记录内容
+
+| 模块 | 当前覆盖率 | 目标 |
+|------|-----------|------|
+| `src/utils/` | 待测量 | >= 80% |
+| `src/utils/permissions/` | 待测量 | >= 60% |
+| `src/utils/model/` | 待测量 | >= 60% |
+| `src/Tool.ts` + `src/tools.ts` | 待测量 | >= 80% |
+| `src/utils/claudemd.ts` | 待测量 | >= 40%（核心逻辑难测） |
+| 整体 | 待测量 | 不设强制指标 |
+
+### 后续行动
+
+- 将基线数据填入 `testing-spec.md` §4
+- 识别覆盖率最低的 10 个文件，排入后续测试计划
+- 如 `bun test --coverage` 输出不可用（Bun 版本限制），改用手动计算已测/总导出函数比
+
+---
+
+## 验收标准
+
+- [ ] CLI 参数至少覆盖 5 个核心 flag
+- [ ] 覆盖率基线数据记录到 testing-spec.md
+- [ ] `bun test` 全部通过