@huajiwuyan/hello 3.0.0

package/templates/codex/skills/references/functions/debug/condition-based-waiting.md

@@ -0,0 +1,151 @@
+# 条件等待技术
+
+## 概述
+
+不稳定的测试通常用任意延迟来猜测时序。这会产生竞态条件：测试在快速机器上通过，但在负载下或 CI 中失败。
+
+**核心原则:** 等待你真正关心的条件，而不是猜测需要多长时间。
+
+---
+
+## 适用场景
+
+**使用时机:**
+- 测试中有任意延迟（`setTimeout`、`sleep`、`time.sleep()`）
+- 测试不稳定（有时通过，负载下失败）
+- 并行运行时测试超时
+- 等待异步操作完成
+
+**不使用时机:**
+- 测试实际的时序行为（防抖、节流间隔）
+- 如果使用任意超时，必须注释说明原因
+
+**决策流程:**
+```
+测试使用 setTimeout/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 轮询一次
+  }
+}
+```
+
+**Python 版本:**
+```python
+import time
+
+def wait_for(condition, description, timeout_sec=5):
+    start_time = time.time()
+
+    while True:
+        result = condition()
+        if result:
+            return result
+
+        if time.time() - start_time > timeout_sec:
+            raise TimeoutError(f"等待 {description} 超时，已等待 {timeout_sec}s")
+
+        time.sleep(0.01)  # 每 10ms 轮询一次
+```
+
+---
+
+## 常见错误
+
+**❌ 轮询太快:** `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. 注释解释原因
+
+---
+
+## 实际影响
+
+来自调试会话:
+- 修复了 3 个文件中的 15 个不稳定测试
+- 通过率: 60% → 100%
+- 执行时间: 快 40%
+- 不再有竞态条件
+
+---
+
+## 检查清单
+
+重构异步测试时:
+
+- [ ] 用 `waitFor()` 替换 `setTimeout/sleep`
+- [ ] 条件检查在轮询中获取新鲜数据
+- [ ] 超时有清晰的错误信息
+- [ ] 如果保留任意延迟，注释说明原因
+- [ ] 测试在负载下运行稳定

package/templates/codex/skills/references/functions/debug/defense-in-depth.md

@@ -0,0 +1,147 @@
+# 纵深防御验证
+
+## 概述
+
+当你修复一个由无效数据引起的 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 绕过了业务逻辑检查
+- 不同平台的边界情况需要环境守卫
+- 调试日志识别了结构性误用
+
+**不要止步于一个验证点。** 在每层都添加检查。
+
+---
+
+## 检查清单
+
+修复 Bug 后，确认以下各层:
+
+- [ ] **第1层 - 入口验证:** 公共 API 是否验证了所有输入？
+- [ ] **第2层 - 业务验证:** 内部函数是否检查了前置条件？
+- [ ] **第3层 - 环境守卫:** 危险操作是否有上下文保护？
+- [ ] **第4层 - 调试诊断:** 关键操作前是否有日志记录？

package/templates/codex/skills/references/functions/debug/root-cause-tracing.md

@@ -0,0 +1,168 @@
+# 根因追踪技术
+
+## 概述
+
+Bug 通常在调用栈深处显现（git init 在错误目录执行、文件创建在错误位置、数据库使用错误路径打开）。你的直觉是在错误出现的地方修复，但那只是在治疗症状。
+
+**核心原则:** 沿调用链反向追踪，直到找到原始触发点，然后在源头修复。
+
+---
+
+## 适用场景
+
+**使用时机:**
+- 错误发生在执行深处（不在入口点）
+- 堆栈跟踪显示长调用链
+- 不清楚无效数据的来源
+- 需要找到哪个测试/代码触发了问题
+
+**决策流程:**
+```
+Bug在调用栈深处? → 能反向追踪? → 追踪到原始触发点 → 修复 + 添加纵深防御
+                         ↓ 否
+                    在症状点修复（不推荐）
+```
+
+---
+
+## 追踪流程
+
+### 1. 观察症状
+
+```
+错误: git init 在 /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'
+```
+
+**分析堆栈跟踪:**
+- 查找测试文件名
+- 找到触发调用的行号
+- 识别模式（同一个测试？同一个参数？）
+
+---
+
+## 找出哪个测试造成污染
+
+如果在测试期间出现问题但不知道是哪个测试：
+
+**二分法查找:**
+```bash
+# 逐个运行测试，找到第一个污染者
+npm test -- --testNamePattern="TestA" && check_pollution
+npm test -- --testNamePattern="TestB" && check_pollution
+# ...
+```
+
+---
+
+## 实际示例: 空 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 前的堆栈跟踪日志
+
+---
+
+## 核心原则
+
+```
+找到直接原因
+    ↓
+能向上追溯一层? → 是 → 反向追踪 → 是源头吗? → 是 → 在源头修复 → 每层添加验证 → Bug不可能发生
+    ↓ 否                           ↓ 否
+绝不只修复症状!                    继续追踪
+```
+
+**绝不只在错误出现的地方修复。** 反向追踪找到原始触发点。
+
+---
+
+## 堆栈跟踪技巧
+
+- **在测试中:** 使用 `console.error()` 而非 logger - logger 可能被抑制
+- **操作之前:** 在危险操作前记录日志，而非失败后
+- **包含上下文:** 目录、cwd、环境变量、时间戳
+- **捕获堆栈:** `new Error().stack` 显示完整调用链
+
+---
+
+## 实际影响
+
+来自调试会话:
+- 通过5层追踪找到根因
+- 在源头修复（getter 验证）
+- 添加4层防御
+- 1847个测试通过，零污染