dsh-superpower 6.3.0

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: systematic-debugging
+description: "遇到缺陷、测试失败或异常行为时使用，要求先完成根因分析再提出修复，确保系统化调试"
+---
+
+# 系统化调试
+
+## 概览
+
+**核心原则：** 始终先找到根因，再尝试修复。只修表象即是失败。
+
+**违背该流程的字面要求，即是违背调试的精神。**
+
+## 铁律
+
+```
+未完成根因调查前，禁止提出任何修复方案
+```
+
+若尚未完成阶段一，则不得提出修复建议。
+
+## 适用场景
+
+适用于任何技术问题：
+- 测试失败
+- 生产环境缺陷
+- 异常行为
+- 性能问题
+- 构建失败
+- 集成问题
+
+**尤其应在以下情况使用：**
+- 时间紧迫时（紧急情况下最容易产生侥幸猜测）
+- 看似有“显而易见的快速修复”时
+- 已尝试过多种修复方案时
+- 此前修复未生效时
+- 尚未完全理解问题时
+
+**以下情况也不要跳过：**
+- 问题看似简单时（简单缺陷同样有根因）
+- 时间仓促时（仓促必定导致返工）
+- 管理者要求立刻修复时（系统化比盲目试错更快）
+
+## 四个阶段
+
+必须按顺序完成每个阶段，方可进入下一阶段。
+
+### 阶段一：根因调查
+
+**在尝试任何修复之前：**
+
+1. **仔细阅读错误信息**
+    - 不要跳过错误或警告
+    - 其中往往包含精确的解决线索
+    - 完整阅读堆栈跟踪
+    - 记录行号、文件路径、错误码
+
+2. **稳定复现**
+    - 能否稳定触发？
+    - 精确的复现步骤是什么？
+    - 是否每次都会出现？
+    - 若无法复现 → 先补充数据，切勿猜测
+
+3. **检查近期变更**
+    - 哪些变更可能引发该问题？
+    - 查看 git diff、近期提交
+    - 新增依赖、配置变更
+    - 环境差异
+
+4. **在多组件系统中收集证据**
+
+    **当系统包含多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：**
+
+    **在提出修复前，先添加诊断探针：**
+    ```
+    对于每个组件边界：
+      - 记录进入组件的数据
+      - 记录离开组件的数据
+      - 验证环境/配置是否正确传递
+      - 检查每一层的实际状态
+
+    运行一次以收集“在哪一层断裂”的证据
+    然后分析证据以定位故障组件
+    再针对该组件深入调查
+    ```
+
+    **示例（多层系统）：**
+    ```bash
+    # Layer 1: Workflow
+    echo "=== Secrets available in workflow: ==="
+    echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+    # Layer 2: Build script
+    echo "=== Env vars in build script: ==="
+    env | grep IDENTITY || echo "IDENTITY not in environment"
+
+    # Layer 3: Signing script
+    echo "=== Keychain state: ==="
+    security list-keychains
+    security find-identity -v
+
+    # Layer 4: Actual signing
+    codesign --sign "$IDENTITY" --verbose=4 "$APP"
+    ```
+
+    **由此可得：** 哪一层失败（secrets → workflow ✓，workflow → build ✗）
+
+5. **追踪数据流**
+
+    **当错误位于调用栈深处时：**
+
+    完整的回溯追踪技巧见本目录下的 `root-cause-tracing.md`。
+
+    **精简版：**
+    - 异常值从何而来？
+    - 是谁以错误值调用了此处？
+    - 持续向上回溯，直至找到源头
+    - 在源头修复，而非在表象处打补丁
+
+### 阶段二：模式分析
+
+**先找到规律，再动手修复：**
+
+1. **寻找可用的参照**
+    - 在同一代码库中定位相似且正常工作的代码
+    - 有哪些与故障相似但能正常工作的用例？
+
+2. **对照参考实现**
+    - 若要套用某种模式，请完整阅读参考实现
+    - 不要走马观花——逐行阅读
+    - 在套用前彻底理解该模式
+
+3. **识别差异**
+    - 正常与异常之间有何不同？
+    - 列出每一个差异，哪怕再细微
+    - 不要想当然地认为“这点不可能有影响”
+
+4. **理解依赖**
+    - 该功能还依赖哪些组件？
+    - 需要哪些设置、配置、环境？
+    - 它做了哪些隐含假设？
+
+### 阶段三：假设与验证
+
+**用科学方法推进：**
+
+1. **提出单一假设**
+    - 清晰表述：“我认为根因是 X，理由是 Y”
+    - 落到纸面
+    - 要具体，避免含糊
+
+2. **最小化验证**
+    - 为验证假设做最小幅度的改动
+    - 一次只改变一个变量
+    - 不要同时修复多个问题
+
+3. **验证后再继续**
+    - 生效了吗？是 → 进入阶段四
+    - 未生效？提出新的假设
+    - 不要在原有改动之上继续叠加修复
+
+4. **当你不确定时**
+    - 直言“我不理解 X”
+    - 不要不懂装懂
+    - 寻求帮助
+    - 进一步研究
+
+### 阶段四：实现
+
+**修复根因，而非表象：**
+
+1. **创建失败用例**
+    - 用最简方式复现问题
+    - 如有测试框架则编写自动化测试
+    - 若无框架则编写一次性复现脚本
+    - 修复前必须具备该用例
+    - 编写规范的失败测试请使用 `superpowers:test-driven-development` 技能
+
+2. **实施单一修复**
+    - 针对已确认的根因
+    - 一次只做一处改动
+    - 不要顺手“顺便优化”
+    - 不要打包重构
+
+3. **验证修复**
+    - 用例现在通过了吗？
+    - 是否破坏了其他测试？
+    - 问题是否真正解决？
+    - 在宣称成功前，请使用 `superpowers:verification-before-completion` 技能进行校验
+
+4. **若修复未生效**
+    - 停下来
+    - 计数：已尝试几次修复？
+    - 若 < 3 次：回到阶段一，结合新信息重新分析
+    - **若 ≥ 3 次：停下来，质疑架构（见下方第 5 步）**
+    - 在未进行架构讨论前，不要尝试第 4 次修复
+
+5. **若 3 次以上修复均失败：质疑架构**
+
+    **指向架构问题的信号：**
+    - 每次修复都在不同位置暴露出新的共享状态/耦合/问题
+    - 修复需要“大规模重构”才能落地
+    - 每次修复都在别处引发新症状
+
+    **停下来，质疑根本：**
+    - 该模式本身是否合理？
+    - 是否只是“靠惯性硬撑”？
+    - 应该重构架构，还是继续修补表象？
+
+    **在尝试更多修复前，先与人类协作伙伴讨论**
+
+    这不是假设失败——这是架构错误。
+
+## 危险信号——停下来并回归流程
+
+若你发现自己出现以下想法：
+- “先快速修一下，之后再调查”
+- “先试着改一下 X 看看是否有效”
+- “多改几处，一起跑测试”
+- “跳过测试，我手动验证就行”
+- “大概是 X，我直接修掉”
+- “还没完全搞懂，但这个改法也许能行”
+- “规范要求是 X，但我换种方式适配一下”
+- “主要问题有这些：[未做调查就直接列出修复清单]”
+- 在追踪数据流之前就提出解决方案
+- **“再试一次修复”（已尝试 2 次以上时）**
+- **每次修复都在不同位置暴露新问题**
+
+**以上全部意味着：停下来，回到阶段一。**
+
+**若已失败 3 次以上：** 质疑架构（见阶段四第 5 步）
+
+## 人类协作伙伴提示你做错了的信号
+
+**留意这些提醒：**
+- “这不是没生效吗？”——你在未验证的情况下做了假设
+- “它会告诉我们……吗？”——你本应补充证据收集
+- “别猜了”——你在未理解问题前就提出修复
+- “深入思考一下”——需要质疑根本假设，而非只修表象
+- “我们是不是卡住了？”（带有挫败感）——你的方法行不通
+
+**出现这些信号时：** 停下来，回到阶段一。
+
+## 常见借口
+
+| 借口 | 实际情况 |
+|--------|---------|
+| “问题很简单，不需要走流程” | 简单问题同样有根因。走流程对简单缺陷反而更快。 |
+| “紧急情况，没时间走流程” | 系统化调试比猜测试错更快。 |
+| “先试一下，之后再调查” | 第一次修复就定下了基调。从一开始就做对。 |
+| “确认修复有效后再补测试” | 未经测试的修复不可靠。先写测试才能证明有效。 |
+| “一次多修几处更省时间” | 无法定位哪一处真正生效，还会引入新缺陷。 |
+| “参考实现太长，我按自己的理解适配一下” | 一知半解必然导致缺陷。必须完整阅读。 |
+| “我已经看到问题了，直接修就行” | 看到表象 ≠ 理解根因。 |
+| “再试一次修复”（已失败 2 次以上） | 失败 3 次以上即为架构问题。应质疑模式本身，而非再次修补。 |
+
+## 快速参考
+
+| 阶段 | 关键活动 | 成功标准 |
+|-------|---------------|------------------|
+| **1. 根因** | 阅读错误、复现、检查变更、收集证据 | 明确是什么、为什么 |
+| **2. 模式** | 寻找可用参照、对照比较 | 识别差异 |
+| **3. 假设** | 提出假设、最小化验证 | 假设被证实或被推翻并形成新假设 |
+| **4. 实现** | 编写用例、修复、验证 | 缺陷已解决、测试通过 |
+
+## 当流程揭示“无根因”时
+
+若系统化调查表明问题确实源于环境、时序或外部因素：
+
+1. 流程已走完
+2. 记录已调查的内容
+3. 实施相应的容错处理（重试、超时、错误提示）
+4. 补充监控/日志以便后续调查
+
+**但是：** 95% 所谓“无根因”的情况，都是调查不充分。
+
+## 辅助技巧
+
+本目录下提供以下系统化调试的配套技巧：
+
+- **`root-cause-tracing.md`** - 沿调用栈回溯追踪，直至找到最初触发点
+- **`defense-in-depth.md`** - 找到根因后在多层添加校验
+- **`condition-based-waiting.md`** - 用条件轮询替代固定时延等待

package/skills/systematic-debugging/condition-based-waiting-example.ts

@@ -0,0 +1,158 @@
+// Complete implementation of condition-based waiting utilities
+// From: Lace test infrastructure improvements (2025-10-03)
+// Context: Fixed 15 flaky tests by replacing arbitrary timeouts
+
+import type { ThreadManager } from '~/threads/thread-manager';
+import type { LaceEvent, LaceEventType } from '~/threads/types';
+
+/**
+ * Wait for a specific event type to appear in thread
+ *
+ * @param threadManager - The thread manager to query
+ * @param threadId - Thread to check for events
+ * @param eventType - Type of event to wait for
+ * @param timeoutMs - Maximum time to wait (default 5000ms)
+ * @returns Promise resolving to the first matching event
+ *
+ * Example:
+ *   await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
+ */
+export function waitForEvent(
+  threadManager: ThreadManager,
+  threadId: string,
+  eventType: LaceEventType,
+  timeoutMs = 5000
+): Promise<LaceEvent> {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+
+    const check = () => {
+      const events = threadManager.getEvents(threadId);
+      const event = events.find((e) => e.type === eventType);
+
+      if (event) {
+        resolve(event);
+      } else if (Date.now() - startTime > timeoutMs) {
+        reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
+      } else {
+        setTimeout(check, 10); // Poll every 10ms for efficiency
+      }
+    };
+
+    check();
+  });
+}
+
+/**
+ * Wait for a specific number of events of a given type
+ *
+ * @param threadManager - The thread manager to query
+ * @param threadId - Thread to check for events
+ * @param eventType - Type of event to wait for
+ * @param count - Number of events to wait for
+ * @param timeoutMs - Maximum time to wait (default 5000ms)
+ * @returns Promise resolving to all matching events once count is reached
+ *
+ * Example:
+ *   // Wait for 2 AGENT_MESSAGE events (initial response + continuation)
+ *   await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
+ */
+export function waitForEventCount(
+  threadManager: ThreadManager,
+  threadId: string,
+  eventType: LaceEventType,
+  count: number,
+  timeoutMs = 5000
+): Promise<LaceEvent[]> {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+
+    const check = () => {
+      const events = threadManager.getEvents(threadId);
+      const matchingEvents = events.filter((e) => e.type === eventType);
+
+      if (matchingEvents.length >= count) {
+        resolve(matchingEvents);
+      } else if (Date.now() - startTime > timeoutMs) {
+        reject(
+          new Error(
+            `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`
+          )
+        );
+      } else {
+        setTimeout(check, 10);
+      }
+    };
+
+    check();
+  });
+}
+
+/**
+ * Wait for an event matching a custom predicate
+ * Useful when you need to check event data, not just type
+ *
+ * @param threadManager - The thread manager to query
+ * @param threadId - Thread to check for events
+ * @param predicate - Function that returns true when event matches
+ * @param description - Human-readable description for error messages
+ * @param timeoutMs - Maximum time to wait (default 5000ms)
+ * @returns Promise resolving to the first matching event
+ *
+ * Example:
+ *   // Wait for TOOL_RESULT with specific ID
+ *   await waitForEventMatch(
+ *     threadManager,
+ *     agentThreadId,
+ *     (e) => e.type === 'TOOL_RESULT' && e.data.id === 'call_123',
+ *     'TOOL_RESULT with id=call_123'
+ *   );
+ */
+export function waitForEventMatch(
+  threadManager: ThreadManager,
+  threadId: string,
+  predicate: (event: LaceEvent) => boolean,
+  description: string,
+  timeoutMs = 5000
+): Promise<LaceEvent> {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+
+    const check = () => {
+      const events = threadManager.getEvents(threadId);
+      const event = events.find(predicate);
+
+      if (event) {
+        resolve(event);
+      } else if (Date.now() - startTime > timeoutMs) {
+        reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
+      } else {
+        setTimeout(check, 10);
+      }
+    };
+
+    check();
+  });
+}
+
+// Usage example from actual debugging session:
+//
+// BEFORE (flaky):
+// ---------------
+// const messagePromise = agent.sendMessage('Execute tools');
+// await new Promise(r => setTimeout(r, 300)); // Hope tools start in 300ms
+// agent.abort();
+// await messagePromise;
+// await new Promise(r => setTimeout(r, 50));  // Hope results arrive in 50ms
+// expect(toolResults.length).toBe(2);         // Fails randomly
+//
+// AFTER (reliable):
+// ----------------
+// const messagePromise = agent.sendMessage('Execute tools');
+// await waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2); // Wait for tools to start
+// agent.abort();
+// await messagePromise;
+// await waitForEventCount(threadManager, threadId, 'TOOL_RESULT', 2); // Wait for results
+// expect(toolResults.length).toBe(2); // Always succeeds
+//
+// Result: 60% pass rate → 100%, 40% faster execution

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

@@ -0,0 +1,116 @@
+# 基于条件的等待
+
+## 概述
+
+不稳定的测试往往依赖任意延时来猜测时机。这会引发竞态条件，导致测试在本地快速机器上通过，却在高负载或 CI 环境下失败。
+
+**核心原则：** 等待你真正关心的条件满足，而不是猜测它需要多长时间。
+
+## 适用场景
+
+```dot
+digraph when_to_use {
+    "Test uses setTimeout/sleep?" [shape=diamond];
+    "Testing timing behavior?" [shape=diamond];
+    "Document WHY timeout needed" [shape=box];
+    "Use condition-based waiting" [shape=box];
+
+    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
+    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
+    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
+}
+```
+
+**适用于：**
+- 测试中存在任意延时（`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(`Timeout waiting for ${description} after ${timeoutMs}ms`);
+    }
+
+    await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
+  }
+}
+```
+
+完整实现及领域专用辅助函数（`waitForEvent`、`waitForEventCount`、`waitForEventMatch`）请参阅本目录下的 `condition-based-waiting-example.ts`，均来自真实调试过程。
+
+## 常见错误
+
+**❌ 轮询过快：** `setTimeout(check, 1)` - 浪费 CPU
+**✅ 修正：** 每 10ms 轮询一次
+
+**❌ 无超时：** 条件始终不满足时会无限循环
+**✅ 修正：** 始终设置超时，并给出清晰的错误信息
+
+**❌ 数据过期：** 在循环前缓存状态
+**✅ 修正：** 在循环内调用 getter 获取最新数据
+
+## 何时应该使用任意延时
+
+```typescript
+// 工具每 100ms 触发一次 — 需要 2 次触发来验证部分输出
+await waitForEvent(manager, 'TOOL_STARTED'); // 第一步：等待条件满足
+await new Promise(r => setTimeout(r, 200));   // 第二步：等待时序行为
+// 200ms = 按 100ms 间隔计算的 2 次触发 — 已说明理由并加注注释
+```
+
+**要求：**
+1. 先等待触发条件满足
+2. 基于已知的时序（而非猜测）
+3. 注释说明原因
+
+## 实际效果
+
+来自调试实践（2025-10-03）：
+- 横跨 3 个文件修复了 15 个不稳定测试
+- 通过率：60% → 100%
+- 执行时间：快 40%
+- 彻底消除竞态条件

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

@@ -0,0 +1,122 @@
+# 纵深防御校验
+
+## 概述
+
+当你修复由非法数据引发的缺陷时，往往觉得在一个地方加校验就够了。但单点校验很容易被不同的代码路径、重构或 Mock 绕过。
+
+**核心原则：** 在数据经过的每一层都做校验，让缺陷在结构上不可能发生。
+
+## 为什么需要多层校验
+
+单点校验：“我们修掉了这个缺陷”
+多层校验：“我们让这类缺陷不可能发生”
+
+不同层级捕获的问题不同：
+- 入口校验能拦截大多数缺陷
+- 业务逻辑校验能兜住边界情况
+- 环境防护能避免特定上下文下的危险操作
+- 调试日志能在其他层级失效时提供排查线索
+
+## 四层模型
+
+### 第一层：入口校验
+**目的：** 在 API 边界拒绝明显非法的输入
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### 第二层：业务逻辑校验
+**目的：** 确保数据在当前业务操作中是合理的
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### 第三层：环境防护
+**目的：** 在特定上下文中阻止危险操作
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### 第四层：调试埋点
+**目的：** 记录上下文，便于事后排查
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## 应用方法
+
+当发现缺陷时：
+
+1. **追踪数据流** - 非法值从哪里来？在哪里被使用？
+2. **梳理所有检查点** - 列出数据经过的每一个关卡
+3. **在每一层补充校验** - 入口、业务、环境、调试逐层加固
+4. **逐层验证** - 尝试绕过第一层，确认第二层能否兜住
+
+## 实战示例
+
+缺陷：空的 `projectDir` 导致在源码目录下执行了 `git init`
+
+**数据流：**
+1. 测试初始化 → 空字符串
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` 在 `process.cwd()` 下执行
+
+**补充的四层防护：**
+- 第一层：`Project.create()` 校验非空、存在且可写
+- 第二层：`WorkspaceManager` 校验 projectDir 非空
+- 第三层：`WorktreeManager` 在测试环境下拒绝在 tmpdir 之外执行 git init
+- 第四层：在 git init 前记录堆栈日志
+
+**结果：** 1847 项测试全部通过，缺陷无法复现
+
+## 核心洞察
+
+四层缺一不可。在测试过程中，每一层都捕获了其他层级遗漏的问题：
+- 不同的代码路径绕过了入口校验
+- Mock 绕过了业务逻辑检查
+- 不同平台的边界情况需要环境防护来兜底
+- 调试日志帮助定位了结构性误用
+
+**不要只在一个点做校验。** 在每一层都加上检查。