dev-playbooks-cn 1.0.0

package/skills/devbooks-code-review/references//350/265/204/346/272/220/347/256/241/347/220/206/345/256/241/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,311 @@
+# 资源管理审查清单
+
+借鉴 VS Code 的 `code-no-potentially-unsafe-disposables` 和 `code-must-use-super-dispose` 规则。
+
+---
+
+## 1) 资源泄漏常见模式
+
+### 订阅/监听器泄漏
+
+```typescript
+// 违规：订阅未取消
+class MyComponent {
+  private handler = (e: Event) => { /* ... */ };
+
+  initialize() {
+    document.addEventListener('click', this.handler);
+    // 缺少对应的 removeEventListener
+  }
+}
+
+// 正确：使用 AbortController
+class MyComponent {
+  private abortController = new AbortController();
+
+  initialize() {
+    document.addEventListener('click', this.handler, {
+      signal: this.abortController.signal
+    });
+  }
+
+  dispose() {
+    this.abortController.abort();
+  }
+}
+```
+
+### 定时器泄漏
+
+```typescript
+// 违规：定时器未清理
+class Poller {
+  start() {
+    setInterval(() => this.poll(), 1000);
+    // 缺少清理逻辑
+  }
+}
+
+// 正确：保存引用并在 dispose 中清理
+class Poller {
+  private intervalId?: NodeJS.Timeout;
+
+  start() {
+    this.intervalId = setInterval(() => this.poll(), 1000);
+  }
+
+  dispose() {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+  }
+}
+```
+
+### 流/连接泄漏
+
+```typescript
+// 违规：流未关闭
+async function readFile(path: string) {
+  const stream = fs.createReadStream(path);
+  const data = await streamToString(stream);
+  // 如果 streamToString 抛出异常，流不会关闭
+  return data;
+}
+
+// 正确：使用 try-finally
+async function readFile(path: string) {
+  const stream = fs.createReadStream(path);
+  try {
+    return await streamToString(stream);
+  } finally {
+    stream.destroy();
+  }
+}
+
+// 更好：使用 using（TypeScript 5.2+）
+async function readFile(path: string) {
+  using stream = fs.createReadStream(path);
+  return await streamToString(stream);
+}
+```
+
+---
+
+## 2) DisposableStore 模式
+
+### 基本用法
+
+```typescript
+import { Disposable, DisposableStore } from 'vs/base/common/lifecycle';
+
+class MyService extends Disposable {
+  // 必须是 readonly
+  private readonly _disposables = new DisposableStore();
+
+  constructor() {
+    super();
+
+    // 注册订阅到 store
+    this._disposables.add(
+      eventEmitter.on('change', () => this.handleChange())
+    );
+
+    // 注册定时器到 store
+    this._disposables.add(
+      new IntervalTimer(() => this.poll(), 1000)
+    );
+  }
+
+  override dispose() {
+    this._disposables.dispose();
+    super.dispose(); // 必须调用
+  }
+}
+```
+
+### 检查规则
+
+| 规则 | 检测模式 | 严重程度 |
+|------|----------|----------|
+| DisposableStore 必须 readonly | `private\s+(?!readonly)\s*_?\w*[Dd]isposable` | Error |
+| dispose() 必须调用 super | `override\s+dispose\(\).*\{(?![\s\S]*super\.dispose)` | Error |
+| 订阅必须注册到 store | `.on\(.*\)` 后无 `.add(` | Warning |
+| 测试必须检查泄漏 | 测试文件无 `ensureNoDisposablesAreLeakedInTestSuite` | Warning |
+
+---
+
+## 3) 测试中的资源泄漏检测
+
+### 使用 ensureNoDisposablesAreLeakedInTestSuite
+
+```typescript
+import { ensureNoDisposablesAreLeakedInTestSuite } from 'vs/base/test/common/utils';
+
+suite('MyService', () => {
+  // 在 suite 开始时启用泄漏检测
+  ensureNoDisposablesAreLeakedInTestSuite();
+
+  let service: MyService;
+
+  setup(() => {
+    service = new MyService();
+  });
+
+  teardown(() => {
+    service.dispose(); // 必须清理
+  });
+
+  test('should do something', () => {
+    // 测试代码
+  });
+});
+```
+
+### 常见测试泄漏
+
+```typescript
+// 违规：测试创建的资源未清理
+test('creates disposable', () => {
+  const disposable = new MyDisposable();
+  // 测试结束，disposable 未清理 → 泄漏
+});
+
+// 正确：使用 teardown 清理
+let disposable: MyDisposable;
+
+setup(() => {
+  disposable = new MyDisposable();
+});
+
+teardown(() => {
+  disposable.dispose();
+});
+```
+
+---
+
+## 4) 审查检查清单
+
+### 代码审查时必须检查
+
+- [ ] **DisposableStore 声明**
+  - 是否使用 `readonly` 修饰？
+  - 是否使用 `private`？
+
+- [ ] **dispose() 方法**
+  - 是否调用 `super.dispose()`？
+  - 是否清理所有已知资源？
+  - 是否在基类中定义？
+
+- [ ] **订阅/监听器**
+  - 是否注册到 DisposableStore？
+  - 是否有对应的取消逻辑？
+  - 是否使用 AbortController？
+
+- [ ] **定时器**
+  - setInterval 是否有对应的 clearInterval？
+  - setTimeout 在组件销毁时是否取消？
+
+- [ ] **流/连接**
+  - 是否在 finally 块中关闭？
+  - 是否使用 using 语法？
+
+- [ ] **测试**
+  - 是否有 `ensureNoDisposablesAreLeakedInTestSuite()`？
+  - teardown 是否清理所有创建的资源？
+
+---
+
+## 5) 自动化检测
+
+### ESLint 规则配置
+
+```javascript
+// eslint.config.js
+module.exports = {
+  rules: {
+    // 自定义规则：DisposableStore 必须 readonly
+    'local/code-no-potentially-unsafe-disposables': 'error',
+
+    // 自定义规则：dispose 必须调用 super
+    'local/code-must-use-super-dispose': 'error',
+  }
+};
+```
+
+### grep 检测命令
+
+```bash
+# 检测非 readonly 的 DisposableStore
+rg 'private\s+(?!readonly)\s*_?\w*[Dd]isposable' --type ts
+
+# 检测 dispose 方法未调用 super.dispose
+rg -U 'override\s+dispose\(\).*?\{[^}]*\}' --type ts | grep -v 'super.dispose'
+
+# 检测未清理的 setInterval
+rg 'setInterval\(' --type ts -l | xargs -I {} sh -c 'rg -c "clearInterval" {} || echo "Missing clearInterval: {}"'
+```
+
+---
+
+## 6) 修复指南
+
+### 添加 DisposableStore
+
+```typescript
+// Before
+class MyClass {
+  private subscription: Subscription;
+
+  constructor() {
+    this.subscription = eventEmitter.on('change', () => {});
+  }
+}
+
+// After
+class MyClass extends Disposable {
+  private readonly _disposables = new DisposableStore();
+
+  constructor() {
+    super();
+    this._disposables.add(
+      eventEmitter.on('change', () => {})
+    );
+  }
+
+  override dispose() {
+    this._disposables.dispose();
+    super.dispose();
+  }
+}
+```
+
+### 添加测试泄漏检测
+
+```typescript
+// Before
+suite('MyTest', () => {
+  test('does something', () => {
+    const obj = new MyDisposable();
+    // 未清理
+  });
+});
+
+// After
+suite('MyTest', () => {
+  ensureNoDisposablesAreLeakedInTestSuite();
+
+  const disposables = new DisposableStore();
+
+  teardown(() => {
+    disposables.clear();
+  });
+
+  test('does something', () => {
+    const obj = disposables.add(new MyDisposable());
+    // 会在 teardown 中自动清理
+  });
+});
+```

package/skills/devbooks-coder/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: devbooks-coder
+description: devbooks-coder：以 Coder 角色严格按 tasks.md 实现功能并跑闸门，禁止修改 tests/，以测试/静态检查为唯一完成判据。用户说"按计划实现/修复测试失败/让闸门全绿/实现任务项/不改测试"，或在 DevBooks apply 阶段以 coder 执行时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# DevBooks：实现负责人（Coder）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 断点续做协议（Plan Persistence）
+
+每次开始前**必须**执行以下步骤：
+
+1. **读取进度**：打开 `<change-root>/<change-id>/tasks.md`，识别已勾选 `- [x]` 的任务
+2. **定位续做点**：找到"最后一个 `[x]`"后的第一个 `- [ ]`
+3. **输出确认**：明确告知用户当前进度，例如：
+   ```
+   检测到 T1-T6 已完成（6/10），从 T7 继续。
+   ```
+4. **检查断点区**：如果 tasks.md 有"断点区"记录，优先恢复断点状态
+5. **异常处理**：如果发现"未勾选但代码已存在"的任务，提示用户确认
+
+### 断点区格式（tasks.md 末尾）
+
+```markdown
+### 断点区 (Context Switch Breakpoint Area)
+- 上次进度：T6 完成，T7 开始但未完成
+- 当前阻塞：<阻塞原因>
+- 下一步最短路径：<建议动作>
+```
+
+---
+
+## 输出管理约束（Observation Masking）
+
+防止大量输出污染 context：
+
+| 场景 | 处理方式 |
+|------|----------|
+| 命令输出 > 50 行 | 只保留首尾各 10 行 + 中间摘要 |
+| 测试输出 | 提取关键失败信息，不要全量贴入对话 |
+| 日志输出 | 落盘到 `evidence/`，对话中只引用路径 |
+| 大文件内容 | 引用路径，不要内联 |
+
+**示例**：
+```
+❌ 错误：贴入 2000 行测试日志
+✅ 正确：测试失败 3 个，详见 evidence/test-output.log
+        关键错误：FAIL src/order.test.ts:45 - Expected 400, got 500
+```
+
+---
+
+## 关键约束
+
+### 角色边界约束
+- **禁止修改 `tests/**`**（需要改测试必须交还 Test Owner）
+- **禁止修改 `verification.md`**（由 Test Owner 维护）
+- **禁止修改 `.devbooks/`、`build/`、工程配置文件**（除非 proposal.md 明确声明）
+
+### 代码质量约束
+
+#### 禁止提交的模式
+
+| 模式 | 检测命令 | 原因 |
+|------|----------|------|
+| `test.only` | `rg '\.only\s*\(' src/` | 会跳过其他测试 |
+| `console.log` | `rg 'console\.log' src/` | 调试代码残留 |
+| `debugger` | `rg 'debugger' src/` | 调试断点残留 |
+| `// TODO` 无 issue | `rg 'TODO(?!.*#\d+)' src/` | 无法追踪的待办 |
+| `any` 类型 | `rg ': any[^a-z]' src/` | 类型安全漏洞 |
+| `@ts-ignore` | `rg '@ts-ignore' src/` | 隐藏类型错误 |
+
+#### 提交前必须检查
+
+```bash
+# 1. 编译检查（强制）
+npm run compile || exit 1
+
+# 2. Lint 检查（强制）
+npm run lint || exit 1
+
+# 3. 测试检查（强制）
+npm test || exit 1
+
+# 4. test.only 检查（强制）
+if rg -l '\.only\s*\(' tests/ src/**/test/; then
+  echo "error: found .only() in tests" >&2
+  exit 1
+fi
+
+# 5. 调试代码检查（强制）
+if rg -l 'console\.(log|debug)|debugger' src/ --type ts; then
+  echo "error: found debug statements" >&2
+  exit 1
+fi
+```
+
+### 验证前置约束
+
+**核心要求**：每次修改代码后，必须运行验证命令并确认通过。
+
+- [ ] 修改代码后立即运行 `npm run compile`
+- [ ] 编译通过后运行 `npm run lint`
+- [ ] Lint 通过后运行 `npm test`
+- [ ] 禁止在验证失败时声明"任务完成"
+- [ ] 验证命令输出必须记录到证据文件
+
+### 资源清理约束
+
+- [ ] 临时文件必须在任务结束时删除
+- [ ] 后台进程必须在任务结束时终止
+- [ ] 无论成功失败，都必须执行清理
+
+## 执行方式
+
+1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+2) 阅读低风险改动技术：`references/低风险改动技术.md`（需要时再读）。
+3) 严格按完整提示词执行：`references/代码实现提示词.md`。
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，确保前置条件满足。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测 `tasks.md` 是否存在
+2. 检测 `verification.md` 是否存在（Test Owner 已完成）
+3. 检测当前会话是否已执行过 Test Owner 角色
+4. 识别 tasks.md 中的进度（已完成/待做）
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **首次实现** | tasks.md 全部为 `[ ]` | 从 MP1.1 开始 |
+| **断点续做** | tasks.md 有部分 `[x]` | 从最后 `[x]` 后的第一个 `[ ]` 继续 |
+| **闸门修复** | 测试失败需要修复 | 优先处理失败项 |
+
+### 前置检查
+
+- [ ] `tasks.md` 存在
+- [ ] `verification.md` 存在
+- [ ] 当前会话未执行过 Test Owner
+- [ ] `tests/**` 有测试文件
+
+### 检测输出示例
+
+```
+检测结果：
+- 产物存在性：tasks.md ✓, verification.md ✓
+- 角色隔离：✓（当前会话未执行 Test Owner）
+- 进度：6/10 已完成
+- 运行模式：断点续做，从 MP1.7 继续
+```
+
+---
+
+## MCP 增强
+
+本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+
+### 依赖的 MCP 服务
+
+| 服务 | 用途 | 超时 |
+|------|------|------|
+| `mcp__ckb__getHotspots` | 检测热点文件，输出预警 | 2s |
+| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
+
+### 检测流程
+
+1. 调用 `mcp__ckb__getStatus`（2s 超时）
+2. 若 CKB 可用 → 调用 `mcp__ckb__getHotspots` 获取热点文件
+3. 若超时或失败 → 降级到基础模式（无热点预警）
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 热点文件预警 | CKB 实时分析 | 不可用 |
+| 风险文件识别 | 自动高亮高热点变更 | 手动识别 |
+| 代码导航 | 符号级跳转 | 文件级搜索 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 不可用，跳过热点检测。
+如需启用热点预警，请运行 /devbooks:index 生成索引。
+```
+

package/skills/devbooks-coder/references//344/273/243/347/240/201/345/256/236/347/216/260/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,70 @@
+# 代码实现提示词
+
+> **角色设定**：你是软件工程领域的**最强大脑**——融合了 Linus Torvalds（代码质量与工程品味）、Kent Beck（重构与简洁设计）、Robert C. Martin（Clean Code）的智慧。你的实现必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"实现负责人（Coder）"。你的任务是严格按 `<change-root>/<change-id>/tasks.md` 实现功能，并以测试/静态检查作为唯一完成判据。
+
+输入材料（由我提供）：
+- 编码计划：`<change-root>/<change-id>/tasks.md`
+- 测试失败输出与静态检查报告（优先 JSON/XML）
+- 当前代码库
+- 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
+- 高 ROI 坑库（如存在）：`<truth-root>/engineering/pitfalls.md`
+
+硬约束（必须遵守）：
+1) **禁止修改 tests/**；如需调整测试只能交还 Test Owner。
+2) **只读设计/规格**：不得用代码实现去反向改写 design/spec 的语义。
+3) **质量优先**：遵循仓库既有风格与最佳实践；避免引入反模式与坏味道。
+4) **确定性锚点**：以测试/静态检查/构建结果为唯一裁判；禁止“自评通过”。
+5) **结构守门**：若出现“代理指标驱动”的要求，先评估对内聚/耦合/可测试性的影响；触发风险信号必须停线并回到设计决策。
+
+质量门禁（必须执行）：
+- 先运行与本次变更相关的 tests/静态检查；保留失败输出作为修复依据。
+- 修复时优先小步提交：单次改动聚焦一个 Plan 项，**单次提交<200行**。
+- 避免坏味道：长函数(P95<50行)、深层嵌套、重复逻辑、隐式依赖、循环依赖、过度耦合、跨层调用。
+- 如存在 lint/复杂度/依赖规则，必须满足；若无工具则在输出中写明"建议补充的质量闸门"。
+
+---
+
+## 10 种高频重构手法（遇到坏味道时使用）
+
+> 来源：《重构》辩论修订版——从 70+ 种精简为 10 种高频手法，其余由 IDE 自动化
+
+| 手法 | 适用场景 | 操作要点 |
+|------|----------|----------|
+| **① Extract Method** | 函数过长、注释前的代码块 | 提炼为独立函数，函数名来自注释或意图 |
+| **② Extract Class** | 类职责过多、数据泥团 | 识别"总是一起变化的字段"，提炼为新类 |
+| **③ Move Method/Field** | Feature Envy、Shotgun Surgery | 把方法/字段移到更常使用它的类 |
+| **④ Rename** | 名称不清晰、术语不一致 | 改名后全局替换，与 glossary.md 对齐 |
+| **⑤ Introduce Parameter Object** | 参数列>5、数据泥团 | 把相关参数封装为值对象 |
+| **⑥ Replace Conditional with Polymorphism** | switch/if-else>5分支 | 用子类/策略模式替代条件分支 |
+| **⑦ Replace Magic Number** | 硬编码数字/字符串 | 提取为符号常量，名称表达业务含义 |
+| **⑧ Encapsulate Field** | 字段直接暴露 | 用 getter/setter 封装，可加验证逻辑 |
+| **⑨ Pull Up Method** | 子类间重复代码 | 把重复方法上移到父类 |
+| **⑩ Push Down Method** | 父类方法仅部分子类使用 | 把方法下移到需要的子类 |
+
+---
+
+## "两顶帽子"原则（情境化建议）
+
+> 来源：《重构》辩论修订版——从"严格分离"降级为"情境化建议"
+
+**原则**：重构时不改功能，添加功能时不重构结构。
+
+**适用场景**：
+- **严格执行**：大型重构（影响>5模块）、多人协作的关键分支
+- **可灵活变通**：局部优化（单文件内）、个人开发分支
+
+**实践建议**：
+- 大型重构：建议单独 PR/commit，commit message 标注 `[refactor]`
+- 局部优化：允许与功能开发同一 commit，但在 commit message 说明"顺手重构了 xxx"
+- AI 辅助时代切换成本低，不必过于僵化
+
+输出要求：
+1) 列出本次修改的文件清单
+2) 说明每个 Plan 项如何通过对应的锚点（测试/检查）
+3) 提供可运行的验证命令（按分层列出）
+4) 如果发现设计/规格/计划冲突：停止并明确冲突点，提出回写或澄清建议