specops 0.2.2 → 0.2.4

package/.opencode/skills/systematic-debugging/condition-based-waiting.md

@@ -0,0 +1,115 @@
+# 基于条件的等待
+
+## 概述
+
+不稳定的测试通常用任意延迟来猜测时序。这会产生竞态条件：在快机器上通过，在负载下或 CI 中失败。
+
+**核心原则：** 等待你真正关心的条件，而不是猜测它需要多长时间。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "测试使用了 setTimeout/sleep？" [shape=diamond];
+    "在测试时序行为？" [shape=diamond];
+    "记录为什么需要超时" [shape=box];
+    "使用基于条件的等待" [shape=box];
+
+    "测试使用了 setTimeout/sleep？" -> "在测试时序行为？" [label="是"];
+    "在测试时序行为？" -> "记录为什么需要超时" [label="是"];
+    "在测试时序行为？" -> "使用基于条件的等待" [label="否"];
+}
+```
+
+**使用场景：**
+- 测试有任意延迟（`setTimeout`、`sleep`、`time.sleep()`）
+- 测试不稳定（有时通过，负载下失败）
+- 测试并行运行时超时
+- 等待异步操作完成
+
+**不要使用：**
+- 测试实际的时序行为（防抖、节流间隔）
+- 如果使用任意超时，始终记录原因
+
+## 核心模式
+
+```typescript
+// ❌ 之前：猜测时序
+await new Promise(r => setTimeout(r, 50));
+const result = getResult();
+expect(result).toBeDefined();
+
+// ✅ 之后：等待条件
+await waitFor(() => getResult() !== undefined);
+const result = getResult();
+expect(result).toBeDefined();
+```
+
+## 快速模式
+
+| 场景 | 模式 |
+|------|------|
+| 等待事件 | `waitFor(() => events.find(e => e.type === 'DONE'))` |
+| 等待状态 | `waitFor(() => machine.state === 'ready')` |
+| 等待数量 | `waitFor(() => items.length >= 5)` |
+| 等待文件 | `waitFor(() => fs.existsSync(path))` |
+| 复合条件 | `waitFor(() => obj.ready && obj.value > 10)` |
+
+## 实现
+
+通用轮询函数：
+```typescript
+async function waitFor<T>(
+  condition: () => T | undefined | null | false,
+  description: string,
+  timeoutMs = 5000
+): Promise<T> {
+  const startTime = Date.now();
+
+  while (true) {
+    const result = condition();
+    if (result) return result;
+
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`等待 ${description} 超时，已等待 ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // 每 10ms 轮询一次
+  }
+}
+```
+
+参见本目录中的 `condition-based-waiting-example.ts` 了解完整实现，包含领域特定的辅助函数（`waitForEvent`、`waitForEventCount`、`waitForEventMatch`），来自实际调试实践。
+
+## 常见错误
+
+**❌ 轮询太快：** `setTimeout(check, 1)` - 浪费 CPU
+**✅ 修复：** 每 10ms 轮询一次
+
+**❌ 没有超时：** 条件永远不满足时无限循环
+**✅ 修复：** 始终包含超时和清晰的错误信息
+
+**❌ 过期数据：** 在循环之前缓存了状态
+**✅ 修复：** 在循环内调用 getter 获取最新数据
+
+## 什么时候任意超时是正确的
+
+```typescript
+// 工具每 100ms tick 一次，需要 2 次 tick 来验证部分输出
+await waitForEvent(manager, 'TOOL_STARTED'); // 首先：等待条件
+await new Promise(r => setTimeout(r, 200));   // 然后：等待时序行为
+// 200ms = 100ms 间隔的 2 次 tick，有文档记录且有理由
+```
+
+**要求：**
+1. 先等待触发条件
+2. 基于已知时序（不是猜测）
+3. 注释说明原因
+
+## 真实世界的影响
+
+来自调试实践（2025-10-03）：
+- 修复了 3 个文件中的 15 个不稳定测试
+- 通过率：60% → 100%
+- 执行时间：快了 40%
+- 不再有竞态条件

package/.opencode/skills/systematic-debugging/defense-in-depth.md

@@ -0,0 +1,122 @@
+# 纵深防御验证
+
+## 概述
+
+当你修复了一个由无效数据导致的 bug，在一个地方添加验证感觉够了。但那个单一检查可能被不同的代码路径、重构或 mock 绕过。
+
+**核心原则：** 在数据经过的每一层都添加验证。让 bug 在结构上不可能发生。
+
+## 为什么需要多层
+
+单层验证："我们修了这个 bug"
+多层验证："我们让这个 bug 不可能发生"
+
+不同层捕获不同情况：
+- 入口验证捕获大多数 bug
+- 业务逻辑捕获边界情况
+- 环境守卫防止特定上下文的危险
+- 调试日志在其他层失效时提供帮助
+
+## 四个层次
+
+### 第 1 层：入口点验证
+**目的：** 在 API 边界拒绝明显无效的输入
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory 不能为空');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory 不存在: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory 不是目录: ${workingDirectory}`);
+  }
+  // ... 继续
+}
+```
+
+### 第 2 层：业务逻辑验证
+**目的：** 确保数据对当前操作有意义
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('工作空间初始化需要 projectDir');
+  }
+  // ... 继续
+}
+```
+
+### 第 3 层：环境守卫
+**目的：** 在特定上下文中防止危险操作
+
+```typescript
+async function gitInit(directory: string) {
+  // 在测试中，拒绝在临时目录之外执行 git init
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `测试期间拒绝在临时目录之外执行 git init: ${directory}`
+      );
+    }
+  }
+  // ... 继续
+}
+```
+
+### 第 4 层：调试埋点
+**目的：** 为事后分析捕获上下文
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('即将执行 git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... 继续
+}
+```
+
+## 应用模式
+
+当你发现一个 bug：
+
+1. **追踪数据流** - 错误值从哪里来？在哪里被使用？
+2. **映射所有检查点** - 列出数据经过的每一个点
+3. **在每一层添加验证** - 入口、业务、环境、调试
+4. **测试每一层** - 尝试绕过第 1 层，验证第 2 层能捕获
+
+## 实践示例
+
+Bug：空的 `projectDir` 导致 `git init` 在源代码目录中执行
+
+**数据流：**
+1. 测试准备 → 空字符串
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` 在 `process.cwd()` 中运行
+
+**添加的四个层次：**
+- 第 1 层：`Project.create()` 验证非空/存在/可写
+- 第 2 层：`WorkspaceManager` 验证 projectDir 非空
+- 第 3 层：`WorktreeManager` 在测试中拒绝在 tmpdir 之外执行 git init
+- 第 4 层：git init 之前的堆栈跟踪日志
+
+**结果：** 全部 1847 个测试通过，bug 不可能复现
+
+## 核心洞察
+
+四个层次全部必要。在测试过程中，每一层都捕获了其他层遗漏的 bug：
+- 不同代码路径绕过了入口验证
+- Mock 绕过了业务逻辑检查
+- 不同平台的边界情况需要环境守卫
+- 调试日志识别了结构性误用
+
+**不要在一个验证点就停下来。** 在每一层都添加检查。

package/.opencode/skills/systematic-debugging/root-cause-tracing.md

@@ -0,0 +1,169 @@
+# 根因追踪
+
+## 概述
+
+Bug 通常在调用栈深处表现出来（git init 在错误目录、文件创建在错误位置、数据库用了错误路径）。你的本能是在错误出现的地方修复，但那是在治标。
+
+**核心原则：** 沿着调用链反向追踪，直到找到原始触发点，然后在源头修复。
+
+## 何时使用
+
+```dot
+digraph when_to_use {
+    "Bug 出现在栈深处？" [shape=diamond];
+    "能反向追踪？" [shape=diamond];
+    "在症状处修复" [shape=box];
+    "追踪到原始触发点" [shape=box];
+    "更好：同时添加纵深防御" [shape=box];
+
+    "Bug 出现在栈深处？" -> "能反向追踪？" [label="是"];
+    "能反向追踪？" -> "追踪到原始触发点" [label="是"];
+    "能反向追踪？" -> "在症状处修复" [label="否 - 死胡同"];
+    "追踪到原始触发点" -> "更好：同时添加纵深防御";
+}
+```
+
+**使用场景：**
+- 错误发生在执行深处（不是入口点）
+- 堆栈跟踪显示长调用链
+- 不清楚无效数据从哪里来
+- 需要找到哪个测试/代码触发了问题
+
+## 追踪流程
+
+### 1. 观察症状
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. 找到直接原因
+**什么代码直接导致了这个？**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. 问：谁调用了这里？
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → 被 Session.initializeWorkspace() 调用
+  → 被 Session.create() 调用
+  → 被 Project.create() 的测试调用
+```
+
+### 4. 继续向上追踪
+**传了什么值？**
+- `projectDir = ''`（空字符串！）
+- 空字符串作为 `cwd` 会解析为 `process.cwd()`
+- 那就是源代码目录！
+
+### 5. 找到原始触发点
+**空字符串从哪来？**
+```typescript
+const context = setupCoreTest(); // 返回 { tempDir: '' }
+Project.create('name', context.tempDir); // 在 beforeEach 之前就访问了！
+```
+
+## 添加堆栈跟踪
+
+当你无法手动追踪时，添加埋点：
+
+```typescript
+// 在有问题的操作之前
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**关键：** 在测试中使用 `console.error()`（不是 logger，可能不会显示）
+
+**运行并捕获：**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**分析堆栈跟踪：**
+- 查找测试文件名
+- 找到触发调用的行号
+- 识别模式（同一个测试？同一个参数？）
+
+## 找到哪个测试造成了污染
+
+如果某些东西在测试期间出现但你不知道是哪个测试：
+
+使用本目录中的二分脚本 `find-polluter.sh`：
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+逐个运行测试，在第一个污染者处停止。用法见脚本。
+
+## 真实示例：空 projectDir
+
+**症状：** `.git` 被创建在 `packages/core/`（源代码目录）
+
+**追踪链：**
+1. `git init` 在 `process.cwd()` 中运行 ← 空的 cwd 参数
+2. WorktreeManager 被传入空的 projectDir
+3. Session.create() 传了空字符串
+4. 测试在 beforeEach 之前访问了 `context.tempDir`
+5. setupCoreTest() 初始时返回 `{ tempDir: '' }`
+
+**根因：** 顶层变量初始化访问了空值
+
+**修复：** 把 tempDir 改成 getter，在 beforeEach 之前访问会抛异常
+
+**同时添加了纵深防御：**
+- 第 1 层：Project.create() 验证目录
+- 第 2 层：WorkspaceManager 验证非空
+- 第 3 层：NODE_ENV 守卫拒绝在 tmpdir 之外执行 git init
+- 第 4 层：git init 之前的堆栈跟踪日志
+
+## 核心原则
+
+```dot
+digraph principle {
+    "找到直接原因" [shape=ellipse];
+    "能向上追踪一层？" [shape=diamond];
+    "反向追踪" [shape=box];
+    "这是源头吗？" [shape=diamond];
+    "在源头修复" [shape=box];
+    "在每一层添加验证" [shape=box];
+    "Bug 不可能再发生" [shape=doublecircle];
+    "绝不只修复症状" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "找到直接原因" -> "能向上追踪一层？";
+    "能向上追踪一层？" -> "反向追踪" [label="是"];
+    "能向上追踪一层？" -> "绝不只修复症状" [label="否"];
+    "反向追踪" -> "这是源头吗？";
+    "这是源头吗？" -> "反向追踪" [label="否 - 继续"];
+    "这是源头吗？" -> "在源头修复" [label="是"];
+    "在源头修复" -> "在每一层添加验证";
+    "在每一层添加验证" -> "Bug 不可能再发生";
+}
+```
+
+**绝不只在错误出现的地方修复。** 反向追踪找到原始触发点。
+
+## 堆栈跟踪技巧
+
+**在测试中：** 使用 `console.error()` 而不是 logger，logger 可能被抑制
+**在操作之前：** 在危险操作之前记录日志，不是在它失败之后
+**包含上下文：** 目录、cwd、环境变量、时间戳
+**捕获堆栈：** `new Error().stack` 显示完整调用链
+
+## 真实世界的影响
+
+来自调试实践（2025-10-03）：
+- 通过 5 层追踪找到根因
+- 在源头修复（getter 验证）
+- 添加了 4 层防御
+- 1847 个测试通过，零污染