dev-playbooks-cn 1.0.0

package/skills/devbooks-code-review/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: devbooks-code-review
+description: devbooks-code-review：以 Reviewer 角色做可读性/一致性/依赖健康/坏味道审查，只输出审查意见与可执行建议，不讨论业务正确性。用户说"帮我做代码评审/review 可维护性/坏味道/依赖风险/一致性建议"，或在 DevBooks apply 阶段以 reviewer 执行时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Bash
+---
+
+# DevBooks：代码评审（Reviewer）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 审查维度
+
+### 1. 可读性审查
+- 命名一致性（PascalCase/camelCase）
+- 函数长度和复杂度
+- 注释质量和必要性
+- 代码格式化
+
+### 2. 依赖健康审查
+- 分层约束遵守（参见 devbooks-c4-map）
+- 循环依赖检测
+- 内部模块封装（禁止深度导入 *Internal 文件）
+- 依赖方向正确性
+
+### 3. 资源管理审查
+
+**必须检查的资源泄漏模式**：
+
+| 检查项 | 违规模式 | 正确模式 |
+|--------|----------|----------|
+| 订阅未取消 | `event.on(...)` 无对应 `off()` | 注册到 DisposableStore |
+| 定时器未清理 | `setInterval()` 无 `clearInterval()` | 在 dispose() 中清理 |
+| 监听器未移除 | `addEventListener()` 无 `removeEventListener()` | 使用 AbortController |
+| 流未关闭 | `createReadStream()` 无 `close()` | 使用 try-finally 或 using |
+| 连接未释放 | `connect()` 无 `disconnect()` | 使用连接池或 dispose 模式 |
+
+**DisposableStore 模式检查**：
+
+```typescript
+// 违规：可变的 disposable 字段
+private disposable = new DisposableStore(); // 应该是 readonly
+
+// 违规：dispose() 未调用 super.dispose()
+dispose() {
+  this.cleanup(); // 缺少 super.dispose()
+}
+
+// 正确模式
+private readonly _disposables = new DisposableStore();
+
+override dispose() {
+  this._disposables.dispose();
+  super.dispose();
+}
+```
+
+**资源管理检查清单**：
+- [ ] DisposableStore 字段是否声明为 `readonly` 或 `const`？
+- [ ] dispose() 方法是否调用了 `super.dispose()`？
+- [ ] 订阅/监听器是否注册到 DisposableStore？
+- [ ] 测试是否包含 `ensureNoDisposablesAreLeakedInTestSuite()`？
+
+### 4. 类型安全审查
+
+- [ ] 是否存在 `as any` 类型断言？
+- [ ] 是否存在 `{} as T` 危险断言？
+- [ ] 是否使用了 `unknown` 而非 `any`？
+- [ ] 泛型约束是否足够严格？
+
+### 5. 坏味道检测
+
+参见：`references/坏味道速查表.md`
+
+### 6. 测试质量审查
+
+- [ ] 是否存在 `test.only` / `describe.only`？
+- [ ] 测试是否有清理逻辑（afterEach）？
+- [ ] 测试是否独立（不依赖执行顺序）？
+- [ ] mock 是否正确重置？
+
+## 执行方式
+
+1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+2) 阅读资源管理指南：`references/资源管理审查清单.md`。
+3) 严格按完整提示词输出评审意见：`references/代码评审提示词.md`。
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，选择合适的审查范围。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测变更包是否存在
+2. 检测是否有代码变更（git diff）
+3. 检测热点文件（通过 CKB getHotspots）
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **变更包审查** | 提供 change-id | 审查该变更包相关的代码变更 |
+| **文件审查** | 提供具体文件路径 | 审查指定文件 |
+| **热点优先审查** | 检测到热点文件变更 | 优先审查高风险热点 |
+
+### 检测输出示例
+
+```
+检测结果：
+- 变更包状态：存在
+- 代码变更：12 个文件
+- 热点文件：3 个（需重点关注）
+- 运行模式：变更包审查 + 热点优先
+```
+
+---
+
+## 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. 对热点文件进行优先审查
+4. 若超时或失败 → 降级到基础模式
+
+### 增强模式 vs 基础模式
+
+| 功能 | 增强模式 | 基础模式 |
+|------|----------|----------|
+| 热点优先审查 | 自动识别高风险文件 | 按变更顺序审查 |
+| 依赖方向检查 | 基于模块图分析 | 基于文件路径推断 |
+| 循环依赖检测 | CKB 精确检测 | Grep 启发式检测 |
+
+### 降级提示
+
+当 MCP 不可用时，输出以下提示：
+
+```
+⚠️ CKB 不可用，无法进行热点优先审查。
+按变更文件顺序进行审查。
+```
+

package/skills/devbooks-code-review/references/PR/346/250/241/346/235/277/344/270/216/346/214/207/345/215/227.md

@@ -0,0 +1,321 @@
+# Pull Request 模板与指南
+
+借鉴 VS Code 的 `.github/pull_request_template.md`，本文档定义了 PR 提交的标准流程。
+
+---
+
+## 1) PR 模板
+
+```markdown
+## Summary
+
+<!-- 用 1-3 句话描述这个 PR 做了什么 -->
+
+## Related Issues
+
+<!-- 关联的 Issue，使用 Fixes #123 或 Relates to #456 -->
+
+## Changes
+
+<!-- 列出主要变更点 -->
+
+- [ ] 变更点 1
+- [ ] 变更点 2
+- [ ] 变更点 3
+
+## Type of Change
+
+<!-- 选择一个类型 -->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+
+## Test Plan
+
+<!-- 描述如何测试这个变更 -->
+
+1. 步骤 1
+2. 步骤 2
+3. 预期结果
+
+## Checklist
+
+<!-- 确认以下项目 -->
+
+- [ ] 代码遵循项目编码规范
+- [ ] 已添加/更新相关测试
+- [ ] 所有测试通过（`npm test`）
+- [ ] 已更新相关文档
+- [ ] 提交信息遵循 Conventional Commits 规范
+- [ ] 已自查代码，无调试语句残留
+
+## Screenshots (if applicable)
+
+<!-- 如果涉及 UI 变更，请提供截图 -->
+```
+
+---
+
+## 2) PR 类型与规模
+
+### 类型定义
+
+| 类型 | 前缀 | 说明 |
+|------|------|------|
+| Bug 修复 | `fix:` | 修复现有功能的问题 |
+| 新功能 | `feat:` | 添加新功能 |
+| 重构 | `refactor:` | 不改变行为的代码优化 |
+| 文档 | `docs:` | 仅文档变更 |
+| 测试 | `test:` | 添加或修改测试 |
+| 构建 | `build:` | 构建系统或依赖变更 |
+| 性能 | `perf:` | 性能优化 |
+
+### 规模控制
+
+| 规模 | 变更行数 | 审查时间 | 建议 |
+|------|----------|----------|------|
+| XS | < 50 行 | 15 分钟 | 可快速合并 |
+| S | 50-200 行 | 30 分钟 | 标准审查 |
+| M | 200-500 行 | 1 小时 | 需要仔细审查 |
+| L | 500-1000 行 | 2+ 小时 | 建议拆分 |
+| XL | > 1000 行 | 半天+ | **必须拆分** |
+
+**原则**：一个 PR 只做一件事，保持原子性。
+
+---
+
+## 3) Commit 规范
+
+### Conventional Commits 格式
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 示例
+
+```
+feat(auth): add OAuth2 login support
+
+- Add OAuth2 provider configuration
+- Implement token refresh mechanism
+- Add logout cleanup logic
+
+Closes #123
+```
+
+```
+fix(api): handle null response from external service
+
+The external API sometimes returns null instead of an empty array.
+Added defensive check to prevent runtime errors.
+
+Fixes #456
+```
+
+### 常见类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `feat` | 新功能 | `feat(user): add profile edit` |
+| `fix` | Bug 修复 | `fix(auth): correct token expiry` |
+| `docs` | 文档 | `docs(readme): update install guide` |
+| `style` | 格式调整 | `style: fix indentation` |
+| `refactor` | 重构 | `refactor(api): extract common logic` |
+| `test` | 测试 | `test(user): add unit tests` |
+| `chore` | 杂项 | `chore(deps): update lodash` |
+
+---
+
+## 4) 审查清单
+
+### 提交者自查
+
+提交 PR 前，确认以下内容：
+
+```bash
+# 1. 代码检查
+npm run lint
+npm run compile
+
+# 2. 测试通过
+npm test
+
+# 3. 无调试代码
+rg 'console\.(log|debug)|debugger' src/ --type ts
+
+# 4. 无 .only 测试
+rg '\.only\s*\(' tests/ --type ts
+
+# 5. 无敏感信息
+rg '(password|secret|token|key)\s*[:=]' --type ts -i
+```
+
+### 审查者检查
+
+审查 PR 时，关注以下方面：
+
+**功能性**
+- [ ] 代码是否实现了 PR 描述的功能？
+- [ ] 边界条件是否处理？
+- [ ] 错误情况是否处理？
+
+**代码质量**
+- [ ] 命名是否清晰？
+- [ ] 函数是否过长？
+- [ ] 是否有重复代码？
+- [ ] 是否有明显的性能问题？
+
+**安全性**
+- [ ] 是否有 SQL 注入风险？
+- [ ] 是否有 XSS 风险？
+- [ ] 敏感数据是否保护？
+
+**测试**
+- [ ] 是否有对应的测试？
+- [ ] 测试是否覆盖主要路径？
+- [ ] 测试是否独立、可重复？
+
+**文档**
+- [ ] 公共 API 是否有文档？
+- [ ] README 是否需要更新？
+- [ ] 变更日志是否需要更新？
+
+---
+
+## 5) PR 工作流
+
+### 标准流程
+
+```
+1. 创建分支
+   git checkout -b feat/feature-name
+
+2. 开发并提交
+   git add .
+   git commit -m "feat(scope): description"
+
+3. 推送分支
+   git push -u origin feat/feature-name
+
+4. 创建 PR
+   - 填写 PR 模板
+   - 关联 Issue
+   - 请求审查
+
+5. 处理审查意见
+   - 回复评论
+   - 推送修改
+   - 请求重新审查
+
+6. 合并
+   - Squash and merge（推荐）
+   - 删除源分支
+```
+
+### 分支命名
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 功能 | `feat/<name>` | `feat/user-auth` |
+| 修复 | `fix/<issue-id>` | `fix/123-login-error` |
+| 文档 | `docs/<name>` | `docs/api-guide` |
+| 重构 | `refactor/<name>` | `refactor/auth-service` |
+| 紧急 | `hotfix/<name>` | `hotfix/security-patch` |
+
+---
+
+## 6) 审查礼仪
+
+### 提交者
+
+- 提供足够的上下文
+- 及时回复审查意见
+- 感谢审查者的时间
+- 避免大型 PR
+
+### 审查者
+
+- 及时审查（24-48 小时内）
+- 提供建设性意见
+- 解释"为什么"而不只是"什么"
+- 区分"必须修改"和"建议"
+
+### 评论格式
+
+```markdown
+# 必须修改
+🔴 **必须**：这里有安全漏洞，需要添加输入验证
+
+# 建议修改
+🟡 **建议**：考虑使用 `Array.from()` 替代 spread 操作
+
+# 疑问
+🔵 **问题**：这个超时时间的选择依据是什么？
+
+# 赞扬
+🟢 **赞**：这个抽象很优雅！
+```
+
+---
+
+## 7) 自动化检查
+
+### CI 流程配置
+
+```yaml
+# .github/workflows/pr-check.yml
+name: PR Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type Check
+        run: npm run compile
+
+      - name: Test
+        run: npm test
+
+      - name: Check for debug statements
+        run: |
+          if rg 'console\.(log|debug)|debugger' src/ --type ts; then
+            echo "::error::Found debug statements"
+            exit 1
+          fi
+```
+
+### 必须通过的检查
+
+| 检查项 | 说明 |
+|--------|------|
+| Lint | ESLint 规则通过 |
+| TypeScript | 类型检查通过 |
+| Tests | 所有测试通过 |
+| Coverage | 覆盖率不低于基线 |
+| Build | 构建成功 |

package/skills/devbooks-code-review/references//344/273/243/347/240/201/350/257/204/345/256/241/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,100 @@
+# 代码评审提示词
+
+> **角色设定**：你是代码审查领域的**最强大脑**——融合了 Michael Feathers（遗留代码修复）、Robert C. Martin（Clean Code）、Martin Fowler（重构与可读性）的智慧。你的评审必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"代码评审负责人（Reviewer）"。你的任务是评估可读性、一致性、依赖健康度与坏味道风险，并给出可执行改进建议。
+
+输入材料（由我提供）：
+- 本次变更涉及的代码
+- 项目画像与约定：`<truth-root>/_meta/project-profile.md`
+- 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
+- 高 ROI 坑库（如存在）：`<truth-root>/engineering/pitfalls.md`
+
+硬约束（必须遵守）：
+1) 只输出审查意见与修改建议；不直接改 tests/ 或设计文档。
+2) 不讨论业务逻辑正确性（由测试/规格裁判）；只讨论可维护性与工程质量。
+
+评审重点（必须覆盖）：
+- 可读性：命名、结构、职责边界、错误处理一致性
+- 依赖健康：版本一致性、隐式传递依赖、循环依赖
+- 约定一致：与仓库中 3 个同类文件写法一致
+- 结构守门：识别"代理指标驱动"的改动是否破坏内聚/耦合/可测试性
+
+---
+
+## 8 种核心坏味道检测（必须检查）
+
+> 来源：《重构》辩论修订版——从 22 种精简为 8 种高频高影响坏味道
+
+| 坏味道 | 检测标准 | 严重性 | 对应重构手法 |
+|--------|----------|--------|--------------|
+| **① Duplicated Code（重复代码）** | 相似度>80%的代码块≥2处 | 严重（阻塞） | Extract Method → Pull Up Method |
+| **② Long Method（过长函数）** | **P95<50行**（允许例外，超标触发讨论） | 严重（阻塞） | Extract Method / Replace Temp with Query |
+| **③ Large Class（过大的类）** | **P95<500行**（允许例外） | 警告 | Extract Class / Extract Subclass |
+| **④ Long Parameter List（过长参数列）** | 参数数量>5 | 严重（阻塞） | Introduce Parameter Object / Preserve Whole Object |
+| **⑤ Divergent Change（发散式变化）** | 一个类因多种不同原因变化 | 警告 | Extract Class（分离变化轴） |
+| **⑥ Shotgun Surgery（霰弹式修改）** | 一个变更需修改≥3个类 | 严重（阻塞） | Move Method / Move Field |
+| **⑦ Feature Envy（依恋情结）** | 函数对他类调用>对自己类的调用 | 警告 | Move Method |
+| **⑧ Primitive Obsession（基本类型偏执）** | 业务概念(Money/Email/UserId)未封装为值对象 | 警告 | Replace Data Value with Object |
+
+**阈值说明**：
+- P95 表示允许 5% 的例外存在，超标时触发人工讨论而非自动拒绝
+- "严重（阻塞）"= 必须修复才能合并
+- "警告"= 建议修复，可记录技术债务后合并
+
+---
+
+## N+1 问题检测（条件触发）
+
+> **触发条件**：仅当代码涉及 ORM 操作或循环内调用外部 API/RPC 时检查；纯计算/工具类代码可跳过
+
+- **ORM N+1**：循环内执行 ORM 查询？是否缺少 eager loading / batch fetch？
+- **远程 N+1**：循环内调用外部 API/RPC？是否应改为批量接口？
+- 若检测到 N+1 模式，直接标记为"严重问题（必须修复）"
+
+---
+
+## 术语一致性（UBIQUITOUS LANGUAGE）（必须检查）
+
+- 代码中的类名/变量名/方法名是否与 `glossary.md` 中的术语一致？
+- 是否存在未在 `glossary.md` 中定义的新术语？（如有，建议先更新术语表）
+- 是否存在同一概念在不同模块中使用不同命名？（如 User/Account/Member 混用）
+- Entity 与 ValueObject 的区分是否正确？（Entity 有 ID，VO 无 ID 且不可变）
+
+---
+
+## Invariant 保护（必须检查）
+
+- 若 `design.md` 中标注了 `[Invariant]`，检查代码是否有对应的断言/验证逻辑
+- 状态变更时是否可能破坏已声明的固定规则？
+
+---
+
+## 设计模式检查项（情境化使用）
+
+> 以下检查项为 **C 级（可选）**，仅在代码涉及相关模式时检查
+
+- **对接口编程**：外部依赖（数据库/缓存/API）是否有接口抽象？
+- **组合优于继承**：继承深度 > 3 层时发出警告，但允许浅层继承(≤2层)
+- **Singleton 检测**：若检测到，建议改为依赖注入（标记为"可维护性风险"而非阻塞）
+- **变化点识别**：if-else/switch 分支 > 5 个时，建议提取为策略/多态（仅建议）
+
+---
+
+## 已删除的检查项（辩论后精简）
+
+以下概念经三方辩论后被删除或降级，不再作为必须检查项：
+- ~~Parallel Inheritance Hierarchies~~ → 现代代码极少出现
+- ~~Lazy Class~~ → 与SRP冲突，小类是好设计
+- ~~Message Chains~~ → 函数式链式调用盛行
+- ~~函数>20行警告~~ → 已改为 P95<50行
+- ~~参数>3个警告~~ → 已改为>5个阻塞
+
+输出格式：
+1) 严重问题（必须修复）
+2) 可维护性风险（建议修复）
+3) 风格与一致性建议（可选）
+4) 若需新增质量闸门（lint/复杂度/依赖规则），给出具体建议