diff --git a/docs/zh-CN/commands/auto-update.md b/docs/zh-CN/commands/auto-update.md new file mode 100644 index 00000000..32812709 --- /dev/null +++ b/docs/zh-CN/commands/auto-update.md @@ -0,0 +1,28 @@ +--- +description: 拉取最新的ECC仓库更改并重新安装当前管理的目标。 +disable-model-invocation: true +--- + +# 自动更新 + +从其上游仓库更新 ECC，并使用原始的安装状态请求重新生成当前上下文的受管安装。 + +## 用法 + +```bash +# Preview the update without mutating anything +ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var r=(()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;for(var s of [['ecc'],['ecc@ecc'],['marketplace','ecc'],['everything-claude-code'],['everything-claude-code@everything-claude-code'],['marketplace','everything-claude-code']]){var l=p.join(d,'plugins',...s);if(f.existsSync(p.join(l,q)))return l}try{for(var g of ['ecc','everything-claude-code']){var b=p.join(d,'plugins','cache',g);for(var o of f.readdirSync(b,{withFileTypes:true})){if(!o.isDirectory())continue;for(var v of f.readdirSync(p.join(b,o.name),{withFileTypes:true})){if(!v.isDirectory())continue;var c=p.join(b,o.name,v.name);if(f.existsSync(p.join(c,q)))return c}}}}catch(x){}return d})();console.log(r)")}" +node "$ECC_ROOT/scripts/auto-update.js" --dry-run + +# Update only Cursor-managed files in the current project +node "$ECC_ROOT/scripts/auto-update.js" --target cursor + +# Override the ECC repo root explicitly +node "$ECC_ROOT/scripts/auto-update.js" --repo-root /path/to/everything-claude-code +``` + +## 说明 + +* 此命令使用记录的安装状态请求，在拉取最新仓库更改后重新运行 `install-apply.js`。 +* 重新安装是必要的：它能处理上游的重命名和删除操作，而 `repair.js` 无法仅通过过时的操作安全地重建这些更改。 +* 如需在修改前查看重建的重新安装计划，请先使用 `--dry-run`。 diff --git a/docs/zh-CN/commands/feature-dev.md b/docs/zh-CN/commands/feature-dev.md new file mode 100644 index 00000000..8dab5afb --- /dev/null +++ b/docs/zh-CN/commands/feature-dev.md @@ -0,0 +1,49 @@ +--- +description: 基于代码库理解和架构重点的引导式功能开发 +--- + +一种结构化的功能开发工作流程，强调在编写新代码之前先理解现有代码。 + +## 阶段 + +### 1. 发现 + +* 仔细阅读功能需求 +* 识别需求、约束和验收标准 +* 如果需求不明确，提出澄清性问题 + +### 2. 代码库探索 + +* 使用 `code-explorer` 分析相关的现有代码 +* 追踪执行路径和架构层次 +* 理解集成点和约定 + +### 3. 澄清性问题 + +* 展示探索过程中的发现 +* 提出有针对性的设计和边界情况问题 +* 等待用户回复后再继续 + +### 4. 架构设计 + +* 使用 `code-architect` 设计功能 +* 提供实现蓝图 +* 等待批准后再实施 + +### 5. 实现 + +* 按照批准的设计实现功能 +* 在适当的情况下优先采用 TDD +* 保持提交小而专注 + +### 6. 质量审查 + +* 使用 `code-reviewer` 审查实现 +* 处理关键和重要问题 +* 验证测试覆盖率 + +### 7. 总结 + +* 总结已构建的内容 +* 列出后续事项或限制 +* 提供测试说明 diff --git a/docs/zh-CN/commands/flutter-build.md b/docs/zh-CN/commands/flutter-build.md new file mode 100644 index 00000000..315f9e87 --- /dev/null +++ b/docs/zh-CN/commands/flutter-build.md @@ -0,0 +1,166 @@ +--- +description: 逐步修复 Dart 分析器错误和 Flutter 构建失败。调用 dart-build-resolver 代理进行最小化的精准修复。 +--- + +# Flutter 构建与修复 + +此命令调用 **dart-build-resolver** 代理，以最小改动增量修复 Dart/Flutter 构建错误。 + +## 命令功能 + +1. **运行诊断**：执行 `flutter analyze`、`flutter pub get` +2. **解析错误**：按文件分组并按严重性排序 +3. **增量修复**：每次修复一个错误 +4. **验证每次修复**：每次更改后重新运行分析 +5. **报告摘要**：显示已修复内容和剩余问题 + +## 使用时机 + +在以下情况使用 `/flutter-build`： + +* `flutter analyze` 报告错误 +* `flutter build` 在任何平台失败 +* `dart pub get` / `flutter pub get` 因版本冲突失败 +* `build_runner` 代码生成失败 +* 拉取更改后导致构建中断 + +## 运行的诊断命令 + +```bash +# Analysis +flutter analyze 2>&1 + +# Dependencies +flutter pub get 2>&1 + +# Code generation (if project uses build_runner) +dart run build_runner build --delete-conflicting-outputs 2>&1 + +# Platform builds +flutter build apk 2>&1 +flutter build web 2>&1 +``` + +## 示例会话 + +````text +用户：/flutter-build + +代理： +# Flutter 构建问题解决 + +## 初始诊断 + +``` +$ flutter analyze +分析项目中... + + error • lib/features/user/data/user_repository_impl.dart:34:16 • + 类型为 'String?' 的值无法赋值给类型为 'String' 的变量。 • + invalid_assignment + + error • lib/features/cart/presentation/cart_page.dart:58:5 • + 类型 'List' 未定义方法 'add'。 + 请尝试将名称更正为现有方法的名称，或定义名为 'add' 的方法。 • + undefined_method + +发现 2 个错误。 +``` + +## 修复 1：空安全 + +文件：lib/features/user/data/user_repository_impl.dart:34 +错误：类型为 'String?' 的值无法赋值给类型 'String' + +修改前： +```dart +final id = response.id; +``` +修改后： +```dart +final id = response.id ?? ''; +``` + +``` +$ flutter analyze +发现 1 个错误。 +``` + +## 修复 2：不可变列表 + +文件：lib/features/cart/presentation/cart_page.dart:58 +错误：类型 'List' 未定义方法 'add' +原因：状态持有不可修改的列表；变更通过 Cubit 进行 + +修改前： +```dart +state.items.add(item); +``` +修改后： +```dart +context.read().addItem(item); +// 注意：Cubit 暴露命名方法（addItem, removeItem）； +// .add(event) 是 BLoC 事件 API — 不要混淆使用。 +``` + +``` +$ flutter analyze +未发现问题！ +``` + +## 最终验证 + +``` +$ flutter test +所有测试通过。 +``` + +## 总结 + +| 指标 | 数量 | +|--------|-------| +| 分析错误修复 | 2 | +| 修改的文件 | 2 | +| 剩余问题 | 0 | + +构建状态：通过 ✓ +```` + +## 常见错误修复 + +| 错误 | 典型修复 | +|-------|-------------| +| `A value of type 'X?' can't be assigned to 'X'` | 添加 `?? default` 或空值保护 | +| `The name 'X' isn't defined` | 添加导入或修正拼写错误 | +| `Non-nullable instance field must be initialized` | 添加初始化器或 `late` | +| `Version solving failed` | 调整 pubspec.yaml 中的版本约束 | +| `Missing concrete implementation of 'X'` | 实现缺失的接口方法 | +| `build_runner: Part of X expected` | 删除过时的 `.g.dart` 并重建 | + +## 修复策略 + +1. **优先分析错误** — 代码必须无错误 +2. **其次处理警告** — 修复可能导致运行时错误的警告 +3. **第三解决 pub 冲突** — 修复依赖解析问题 +4. **每次修复一个** — 验证每次更改 +5. **最小改动** — 仅修复，不重构 + +## 停止条件 + +代理将在以下情况停止并报告： + +* 同一错误在 3 次尝试后仍然存在 +* 修复引入了更多错误 +* 需要架构变更 +* 包升级冲突需要用户决策 + +## 相关命令 + +* `/flutter-test` — 构建成功后运行测试 +* `/flutter-review` — 审查代码质量 +* `verification-loop` 技能 — 完整验证循环 + +## 相关信息 + +* 代理：`agents/dart-build-resolver.md` +* 技能：`skills/flutter-dart-code-review/` diff --git a/docs/zh-CN/commands/flutter-review.md b/docs/zh-CN/commands/flutter-review.md new file mode 100644 index 00000000..5fade692 --- /dev/null +++ b/docs/zh-CN/commands/flutter-review.md @@ -0,0 +1,118 @@ +--- +description: 审查 Flutter/Dart 代码，检查惯用模式、小部件最佳实践、状态管理、性能、可访问性和安全性。调用 flutter-reviewer 代理。 +--- + +# Flutter 代码审查 + +此命令调用 **flutter-reviewer** 智能体来审查 Flutter/Dart 代码变更。 + +## 此命令的功能 + +1. **收集上下文**：审查 `git diff --staged` 和 `git diff` +2. **检查项目**：检查 `pubspec.yaml`、`analysis_options.yaml`、状态管理方案 +3. **安全预扫描**：检查硬编码密钥和关键安全问题 +4. **全面审查**：应用完整的审查清单 +5. **报告发现**：按严重程度分组输出问题，并附带修复指导 + +## 前置条件 + +在运行 `/flutter-review` 之前，请确保： + +1. **构建通过** — 先运行 `/flutter-build`；对损坏的代码进行审查是不完整的 +2. **测试通过** — 运行 `/flutter-test` 以确认没有回归问题 +3. **无合并冲突** — 解决所有冲突，使差异仅反映有意的更改 +4. **`flutter analyze` 干净** — 在审查前修复分析器警告 + +## 使用时机 + +在以下情况下使用 `/flutter-review`： + +* 提交包含 Flutter/Dart 变更的 PR 之前（在构建和测试通过后） +* 实现新功能后，尽早发现问题 +* 审查他人的 Flutter 代码时 +* 审计 widget、状态管理组件或服务类时 +* 生产发布之前 + +## 审查领域 + +| 领域 | 严重程度 | +|------|----------| +| 硬编码密钥、明文 HTTP | 严重 | +| 架构违规、状态管理反模式 | 严重 | +| Widget 重建问题、资源泄漏 | 高 | +| `dispose()`、`BuildContext` 后缺少 await | 高 | +| Dart 空安全、缺少错误/加载状态 | 高 | +| Const 传播、Widget 组合 | 高 | +| 性能：`build()` 中的耗时操作 | 高 | +| 无障碍、语义标签 | 中 | +| 缺少状态转换测试 | 高 | +| 硬编码字符串（l10n） | 中 | +| Pub 依赖卫生 | 低 | + +## 示例会话 + +```text +用户：/flutter-review + +代理： +# Flutter 代码审查 + +## 上下文 + +变更文件： +- lib/features/auth/presentation/login_page.dart +- lib/features/auth/data/auth_repository_impl.dart + +状态管理：Riverpod（从 pubspec.yaml 检测到） +架构：功能优先 + +## 安全预扫描 + +✓ 未检测到硬编码密钥 +✓ 未检测到明文 HTTP 调用 + +## 审查发现 + +[高] 异步间隙后使用 BuildContext 但未进行 mounted 检查 +文件：lib/features/auth/presentation/login_page.dart:67 +问题：`context.go('/home')` 在 `await auth.login(...)` 之后调用，但未进行 `mounted` 检查。 +修复：在所有 await 之后的导航前添加 `if (!context.mounted) return;`（Flutter 3.7+）。 + +[高] AsyncValue 错误状态未处理 +文件：lib/features/auth/presentation/login_page.dart:42 +问题：`ref.watch(authProvider)` 在 switch 中处理了 loading/data 状态，但没有 `error` 分支。 +修复：在 switch 表达式或 `when()` 调用中添加错误情况，以显示面向用户的错误消息。 + +[中] 硬编码字符串未本地化 +文件：lib/features/auth/presentation/login_page.dart:89 +问题：`Text('Login')` — 用户可见字符串未使用本地化系统。 +修复：使用项目的 l10n 访问器：`Text(context.l10n.loginButton)`。 + +## 审查总结 + +| 严重程度 | 数量 | 状态 | +|----------|------|------| +| 严重 | 0 | 通过 | +| 高 | 2 | 阻塞 | +| 中 | 1 | 信息 | +| 低 | 0 | 备注 | + +结论：阻塞 — 高严重性问题必须在合并前修复。 +``` + +## 批准标准 + +* **批准**：无严重或高等级问题 +* **阻止**：任何严重或高等级问题必须在合并前修复 + +## 相关命令 + +* `/flutter-build` — 先修复构建错误 +* `/flutter-test` — 审查前运行测试 +* `/code-review` — 通用代码审查（语言无关） + +## 相关 + +* 智能体：`agents/flutter-reviewer.md` +* 技能：`skills/flutter-dart-code-review/` +* 规则：`rules/dart/` diff --git a/docs/zh-CN/commands/flutter-test.md b/docs/zh-CN/commands/flutter-test.md new file mode 100644 index 00000000..76bbc63e --- /dev/null +++ b/docs/zh-CN/commands/flutter-test.md @@ -0,0 +1,145 @@ +--- +description: 运行Flutter/Dart测试，报告失败，并逐步修复测试问题。涵盖单元测试、组件测试、黄金测试和集成测试。 +--- + +# Flutter 测试 + +此命令运行 Flutter 测试套件并报告结果。当出现失败时，会逐步诊断并修复问题。 + +## 此命令的功能 + +1. **运行测试**：执行 `flutter test`（或限定范围至已更改文件） +2. **解析失败项**：按类型和原因识别失败测试 +3. **逐步修复**：尽可能每次只修复一个失败项 +4. **验证**：每次修复后重新运行 +5. **报告**：显示覆盖率摘要和剩余失败项 + +## 使用时机 + +在以下情况使用 `/flutter-test`： + +* 实现功能后验证未破坏现有功能 +* 运行 `/flutter-build` 后确保测试通过 +* 检查新代码的测试覆盖率 +* 特定测试文件失败时 +* 提交 PR 前 + +## 执行的命令 + +```bash +# Run all tests +flutter test 2>&1 + +# Run with coverage +flutter test --coverage 2>&1 + +# Run specific test file +flutter test test/unit/domain/usecases/get_user_test.dart 2>&1 + +# Run tests matching a name pattern +flutter test --name "CartBloc" 2>&1 + +# Run integration tests (requires device/emulator) +flutter test integration_test/ 2>&1 + +# Update golden files when intentional visual changes are made +flutter test --update-goldens 2>&1 +``` + +## 示例会话 + +````text +用户：/flutter-test + +代理： +# Flutter 测试运行 + +## 测试执行 + +``` +$ flutter test +00:05 +42 -2: 部分测试失败。 + +失败：test/unit/data/user_repository_test.dart + UserRepository getById + 当用户未找到时返回 null + 期望：null + 实际：User(id: 'test-id', name: 'Test User') + +失败：test/widget/cart_page_test.dart + CartPage + 购物车为空时显示空状态 + 期望：恰好一个包含文本 'Your cart is empty' 的组件 + 找到：没有包含文本 'Your cart is empty' 的组件 +``` + +## 修复 1：仓库测试 + +文件：test/unit/data/user_repository_test.dart +失败：`getById` 在应返回 null 时返回了一个用户（针对缺失的 ID） + +根本原因：测试设置添加了一个 ID 为 'test-id' 的用户，但查询时使用了 'missing-id'。 +修复：更新测试以查询 'missing-id' —— 设置是正确的，查询是错误的。 + +``` +$ flutter test test/unit/data/user_repository_test.dart +1 个测试通过。 +``` + +## 修复 2：组件测试 + +文件：test/widget/cart_page_test.dart +失败：未找到空状态文本组件 + +根本原因：组件中的空状态消息已从 'Your cart is empty' 重命名为 'Cart is empty'。 +修复：更新测试字符串以匹配当前组件文案。 + +``` +$ flutter test test/widget/cart_page_test.dart +1 个测试通过。 +``` + +## 最终运行 + +``` +$ flutter test --coverage +全部 44 个测试通过。 +覆盖率：84.2%（目标：80%） +``` + +## 总结 + +| 指标 | 值 | +|--------|-------| +| 总测试数 | 44 | +| 通过 | 44 | +| 失败 | 0 | +| 覆盖率 | 84.2% | + +测试状态：通过 ✓ +```` + +## 常见测试失败项 + +| 失败类型 | 典型修复方法 | +|---------|-------------| +| `Expected: Actual: ` | 更新断言或修复实现 | +| `Widget not found` | 修复查找器选择器或组件重命名后更新测试 | +| `Golden file not found` | 运行 `flutter test --update-goldens` 生成 | +| `Golden mismatch` | 检查差异；若变更有意则运行 `--update-goldens` | +| `MissingPluginException` | 在测试设置中模拟平台通道 | +| `LateInitializationError` | 在 `setUp()` 中初始化 `late` 字段 | +| `pumpAndSettle timed out` | 替换为显式 `pump(Duration)` 调用 | + +## 相关命令 + +* `/flutter-build` — 运行测试前修复构建错误 +* `/flutter-review` — 测试通过后审查代码 +* `tdd-workflow` 技能 — 测试驱动开发工作流 + +## 相关内容 + +* 代理：`agents/flutter-reviewer.md` +* 代理：`agents/dart-build-resolver.md` +* 技能：`skills/flutter-dart-code-review/` +* 规则：`rules/dart/testing.md` diff --git a/docs/zh-CN/commands/gan-build.md b/docs/zh-CN/commands/gan-build.md new file mode 100644 index 00000000..311ecd00 --- /dev/null +++ b/docs/zh-CN/commands/gan-build.md @@ -0,0 +1,109 @@ +--- +description: 运行生成器/评估器构建循环，用于实现任务，具有有限迭代和评分。 +--- + +从 $ARGUMENTS 中解析以下内容： + +1. `brief` — 用户对构建内容的一行描述 +2. `--max-iterations N` — （可选，默认15）最大生成器-评估器循环次数 +3. `--pass-threshold N` — （可选，默认7.0）通过所需的加权分数 +4. `--skip-planner` — （可选）跳过规划器，假设 spec.md 已存在 +5. `--eval-mode MODE` — （可选，默认"playwright"）可选值：playwright、screenshot、code-only + +## GAN 风格构建框架 + +该命令协调一个受 Anthropic 2026年3月框架设计论文启发的三智能体构建循环。 + +### 阶段0：设置 + +1. 在项目根目录创建 `gan-harness/` 目录 +2. 创建子目录：`gan-harness/feedback/`、`gan-harness/screenshots/` +3. 如果尚未初始化 git，则进行初始化 +4. 记录开始时间和配置 + +### 阶段1：规划（规划器智能体） + +除非设置了 `--skip-planner`： + +1. 通过任务工具启动 `gan-planner` 智能体，并传入用户的简要说明 +2. 等待其生成 `gan-harness/spec.md` 和 `gan-harness/eval-rubric.md` +3. 向用户显示规范摘要 +4. 进入阶段2 + +### 阶段2：生成器-评估器循环 + +``` +iteration = 1 +while iteration <= max_iterations: + + # 生成 + 通过 Task 工具启动 gan-generator agent： + - 读取 spec.md + - 如果 iteration > 1：读取 feedback/feedback-{iteration-1}.md + - 构建/改进应用程序 + - 确保开发服务器正在运行 + - 提交更改 + + # 等待生成器完成 + + # 评估 + 通过 Task 工具启动 gan-evaluator agent： + - 读取 eval-rubric.md 和 spec.md + - 测试正在运行的应用程序（模式：playwright/screenshot/code-only） + - 根据评分标准打分 + - 将反馈写入 feedback/feedback-{iteration}.md + + # 等待评估器完成 + + # 检查分数 + 读取 feedback/feedback-{iteration}.md + 提取加权总分 + + if score >= pass_threshold: + 记录 "在第 {iteration} 次迭代中通过，分数为 {score}" + 跳出循环 + + if iteration >= 3 且最近 2 次迭代分数未提升: + 记录 "检测到平台期 — 提前停止" + 跳出循环 + + iteration += 1 +``` + +### 阶段3：总结 + +1. 读取所有反馈文件 +2. 显示最终分数和迭代历史 +3. 展示分数进展：`iteration 1: 4.2 → iteration 2: 5.8 → ... → iteration N: 7.5` +4. 列出最终评估中遗留的任何问题 +5. 报告总时间和预估成本 + +### 输出 + +```markdown +## GAN 框架构建报告 + +**简述：** [原始提示] +**结果：** 通过/失败 +**迭代次数：** N / 最大次数 +**最终得分：** X.X / 10 + +### 得分进展 +| 迭代 | 设计 | 原创性 | 工艺 | 功能性 | 总分 | +|------|------|--------|------|--------|------| +| 1 | ... | ... | ... | ... | X.X | +| 2 | ... | ... | ... | ... | X.X | +| N | ... | ... | ... | ... | X.X | + +### 剩余问题 +- [最终评估中的任何问题] + +### 已创建文件 +- gan-harness/spec.md +- gan-harness/eval-rubric.md +- gan-harness/feedback/feedback-001.md 至 feedback-NNN.md +- gan-harness/generator-state.md +- gan-harness/build-report.md +``` + +将完整报告写入 `gan-harness/build-report.md`。 diff --git a/docs/zh-CN/commands/gan-design.md b/docs/zh-CN/commands/gan-design.md new file mode 100644 index 00000000..72e6c493 --- /dev/null +++ b/docs/zh-CN/commands/gan-design.md @@ -0,0 +1,45 @@ +--- +description: 运行一个生成器/评估器设计循环，用于前端或视觉工作，具有有限迭代和评分。 +--- + +从 $ARGUMENTS 中解析以下内容： + +1. `brief` — 用户对要创建设计的描述 +2. `--max-iterations N` — （可选，默认10）最大设计-评估循环次数 +3. `--pass-threshold N` — （可选，默认7.5）通过所需的加权分数（设计模式默认值更高） + +## GAN 风格设计框架 + +一个专注于前端设计质量的双代理循环（生成器 + 评估器）。无规划器——需求说明即规范。 + +这与 Anthropic 用于前端设计实验的模式相同，他们在实验中取得了创意突破，例如使用 CSS 透视和门廊导航的 3D 荷兰艺术博物馆。 + +### 设置 + +1. 创建 `gan-harness/` 目录 +2. 直接将需求说明写入 `gan-harness/spec.md` +3. 编写一个专注于设计的 `gan-harness/eval-rubric.md`，并额外加重设计质量和原创性的权重 + +### 设计专用评估标准 + +```markdown +### 设计质量（权重：0.35） +### 原创性（权重：0.30） +### 工艺水平（权重：0.25） +### 功能性（权重：0.10） +``` + +注意：原创性权重更高（0.30 vs 0.20）以推动创意突破。功能性权重较低，因为设计模式侧重于视觉质量。 + +### 循环 + +与 `/project:gan-build` 阶段 2 相同，但： + +* 跳过规划器 +* 使用设计专用评估标准 +* 生成器提示强调视觉质量而非功能完整性 +* 评估器提示强调"这个设计能赢得设计奖吗？"而非"所有功能都正常吗？" + +### 与 gan-build 的关键区别 + +生成器被告知："你的首要目标是视觉卓越。一个惊艳的半成品应用胜过功能齐全但丑陋的应用。推动创意飞跃——不寻常的布局、自定义动画、独特的色彩搭配。" diff --git a/docs/zh-CN/commands/hookify-configure.md b/docs/zh-CN/commands/hookify-configure.md new file mode 100644 index 00000000..82aa5fb2 --- /dev/null +++ b/docs/zh-CN/commands/hookify-configure.md @@ -0,0 +1,14 @@ +--- +description: 交互式启用或禁用 hookify 规则 +--- + +交互式启用或禁用现有的 hookify 规则。 + +## 步骤 + +1. 查找所有 `.claude/hookify.*.local.md` 文件 +2. 读取每条规则的当前状态 +3. 展示列表，包含每条规则的当前启用/禁用状态 +4. 询问需要切换哪些规则 +5. 更新所选规则文件中的 `enabled:` 字段 +6. 确认更改 diff --git a/docs/zh-CN/commands/hookify-help.md b/docs/zh-CN/commands/hookify-help.md new file mode 100644 index 00000000..582591ad --- /dev/null +++ b/docs/zh-CN/commands/hookify-help.md @@ -0,0 +1,46 @@ +--- +description: 获取关于hookify系统的帮助 +--- + +显示完整的 hookify 文档。 + +## Hook 系统概述 + +Hookify 创建与 Claude Code 的 hook 系统集成的规则文件，以防止不必要的行为。 + +### 事件类型 + +* `bash`：在 Bash 工具使用时触发，匹配命令模式 +* `file`：在写入/编辑工具使用时触发，匹配文件路径 +* `stop`：在会话结束时触发 +* `prompt`：在用户消息提交时触发，匹配输入模式 +* `all`：在所有事件上触发 + +### 规则文件格式 + +文件存储为 `.claude/hookify.{name}.local.md`： + +```yaml +--- +name: descriptive-name +enabled: true +event: bash|file|stop|prompt|all +action: block|warn +pattern: "regex pattern to match" +--- +Message to display when rule triggers. +Supports multiple lines. +``` + +### 命令 + +* `/hookify [description]` 创建新规则，并在未提供描述时自动分析对话 +* `/hookify-list` 列出已配置的规则 +* `/hookify-configure` 启用或禁用规则 + +### 模式提示 + +* 使用正则表达式语法 +* 对于 `bash`，匹配完整的命令字符串 +* 对于 `file`，匹配文件路径 +* 在部署前测试模式 diff --git a/docs/zh-CN/commands/hookify-list.md b/docs/zh-CN/commands/hookify-list.md new file mode 100644 index 00000000..03471be1 --- /dev/null +++ b/docs/zh-CN/commands/hookify-list.md @@ -0,0 +1,21 @@ +--- +description: 列出所有已配置的 hookify 规则 +--- + +查找并以格式化表格显示所有 hookify 规则。 + +## 步骤 + +1. 查找所有 `.claude/hookify.*.local.md` 文件 +2. 读取每个文件的前置元数据： + * `name` + * `enabled` + * `event` + * `action` + * `pattern` +3. 以表格形式显示： + +| 规则 | 启用状态 | 事件 | 模式 | 文件 | +|------|---------|-------|---------|------| + +4. 显示规则数量，并提醒用户 `/hookify-configure` 后续可更改状态。 diff --git a/docs/zh-CN/commands/hookify.md b/docs/zh-CN/commands/hookify.md new file mode 100644 index 00000000..dd478b32 --- /dev/null +++ b/docs/zh-CN/commands/hookify.md @@ -0,0 +1,50 @@ +--- +description: 创建钩子以防止对话分析或明确指令产生的不当行为 +--- + +创建钩子规则，通过分析对话模式或明确的用户指令，防止 Claude Code 出现不期望的行为。 + +## 用法 + +`/hookify [description of behavior to prevent]` + +如果不提供参数，则分析当前对话以找出值得阻止的行为。 + +## 工作流程 + +### 第一步：收集行为信息 + +* 带参数：解析用户对不期望行为的描述 +* 不带参数：使用 `conversation-analyzer` 智能体查找： + * 明确的纠正 + * 对重复错误的沮丧反应 + * 被撤销的更改 + * 反复出现的类似问题 + +### 第二步：展示发现 + +向用户展示： + +* 行为描述 +* 建议的事件类型 +* 建议的模式或匹配器 +* 建议的操作 + +### 第三步：生成规则文件 + +为每个批准的规则，在 `.claude/hookify.{name}.local.md` 创建文件： + +```yaml +--- +name: rule-name +enabled: true +event: bash|file|stop|prompt|all +action: block|warn +pattern: "regex pattern" +--- +Message shown when rule triggers. +``` + +### 第四步：确认 + +报告已创建的规则，以及如何使用 `/hookify-list` 和 `/hookify-configure` 管理这些规则。 diff --git a/docs/zh-CN/commands/jira.md b/docs/zh-CN/commands/jira.md new file mode 100644 index 00000000..750e8b7c --- /dev/null +++ b/docs/zh-CN/commands/jira.md @@ -0,0 +1,108 @@ +--- +description: 检索Jira工单，分析需求，更新状态或添加评论。使用jira-integration技能和MCP或REST API。 +--- + +# Jira 命令 + +直接从工作流中与 Jira 工单交互——获取工单、分析需求、添加评论以及变更状态。 + +## 用法 + +``` +/jira get # 获取并分析工单 +/jira comment # 添加进度评论 +/jira transition # 更改工单状态 +/jira search # 使用JQL搜索问题 +``` + +## 此命令的功能 + +1. **获取与分析** — 获取 Jira 工单并提取需求、验收标准、测试场景和依赖项 +2. **评论** — 向工单添加结构化的进度更新 +3. **状态变更** — 在工作流状态间移动工单（待办 → 进行中 → 已完成） +4. **搜索** — 使用 JQL 查询查找问题 + +## 工作原理 + +### `/jira get ` + +1. 从 Jira 获取工单（通过 MCP `jira_get_issue` 或 REST API） +2. 提取所有字段：摘要、描述、验收标准、优先级、标签、关联问题 +3. 可选地获取评论以获取更多上下文 +4. 生成结构化分析： + +``` +Ticket: PROJ-1234 +Summary: [标题] +Status: [状态] +Priority: [优先级] +Type: [故事/缺陷/任务] + +Requirements: +1. [提取的需求] +2. [提取的需求] + +Acceptance Criteria: +- [ ] [工单中的验收标准] + +Test Scenarios: +- Happy Path: [描述] +- Error Case: [描述] +- Edge Case: [描述] + +Dependencies: +- [关联的问题、API、服务] + +Recommended Next Steps: +- /plan 创建实施计划 +- `tdd-workflow` 技能以测试驱动开发方式实现 +``` + +### `/jira comment ` + +1. 总结当前会话进度（已构建、已测试、已提交的内容） +2. 格式化为结构化评论 +3. 发布到 Jira 工单 + +### `/jira transition ` + +1. 获取工单的可用状态变更 +2. 向用户显示选项 +3. 执行所选的状态变更 + +### `/jira search ` + +1. 对 Jira 执行 JQL 查询 +2. 返回匹配问题的摘要表格 + +## 前提条件 + +此命令需要 Jira 凭据。请选择以下方式之一： + +**选项 A — MCP 服务器（推荐）：** +将 `jira` 添加到您的 `mcpServers` 配置中（请参阅 `mcp-configs/mcp-servers.json` 获取模板）。 + +**选项 B — 环境变量：** + +```bash +export JIRA_URL="https://yourorg.atlassian.net" +export JIRA_EMAIL="your.email@example.com" +export JIRA_API_TOKEN="your-api-token" +``` + +如果缺少凭据，请停止并引导用户进行设置。 + +## 与其他命令的集成 + +分析工单后： + +* 使用 `/plan` 根据需求创建实施计划 +* 使用 `tdd-workflow` 技能进行测试驱动开发实施 +* 实施后使用 `/code-review` +* 使用 `/jira comment` 将进度发布回工单 +* 工作完成后使用 `/jira transition` 移动工单 + +## 相关 + +* **技能：** `skills/jira-integration/` +* **MCP 配置：** `mcp-configs/mcp-servers.json` → `jira` diff --git a/docs/zh-CN/commands/prp-commit.md b/docs/zh-CN/commands/prp-commit.md new file mode 100644 index 00000000..b9840562 --- /dev/null +++ b/docs/zh-CN/commands/prp-commit.md @@ -0,0 +1,115 @@ +--- +description: "使用自然语言文件定位快速提交 — 用简单的英语描述要提交的内容" +argument-hint: "[target description] (blank = all changes)" +--- + +# 智能提交 + +> 改编自 Wirasm 的 PRPs-agentic-eng。属于 PRP 工作流系列。 + +**输入**：$ARGUMENTS + +*** + +## 阶段 1 — 评估 + +```bash +git status --short +``` + +如果输出为空 → 停止："没有可提交的内容。" + +向用户展示变更摘要（新增、修改、删除、未跟踪）。 + +*** + +## 阶段 2 — 解析与暂存 + +解析 `$ARGUMENTS` 以确定暂存内容： + +| 输入 | 解析结果 | Git 命令 | +|---|---|---| +| *(空白/空)* | 暂存所有内容 | `git add -A` | +| `staged` | 使用已暂存的内容 | *(不执行 git add)* | +| `*.ts` 或 `*.py` 等 | 暂存匹配的 glob 模式 | `git add '*.ts'` | +| `except tests` | 暂存所有内容，然后取消暂存测试文件 | `git add -A && git reset -- '**/*.test.*' '**/*.spec.*' '**/test_*' 2>/dev/null \|\| true` | +| `only new files` | 仅暂存未跟踪文件 | `git ls-files --others --exclude-standard \| grep . && git ls-files --others --exclude-standard \| xargs git add` | +| `the auth changes` | 从状态/差异中解析 — 查找与认证相关的文件 | `git add ` | +| 具体文件名 | 暂存这些文件 | `git add ` | + +对于自然语言输入（如"认证相关的变更"），交叉引用 `git status` 输出和 `git diff` 以识别相关文件。向用户展示你暂存了哪些文件及其原因。 + +```bash +git add +``` + +暂存后，验证： + +```bash +git diff --cached --stat +``` + +如果未暂存任何内容，停止："没有文件匹配你的描述。" + +*** + +## 阶段 3 — 提交 + +使用祈使语气编写单行提交信息： + +``` +{type}: {description} +``` + +类型： + +* `feat` — 新功能或能力 +* `fix` — 错误修复 +* `refactor` — 代码重构，行为不变 +* `docs` — 文档变更 +* `test` — 添加或更新测试 +* `chore` — 构建、配置、依赖项 +* `perf` — 性能改进 +* `ci` — CI/CD 变更 + +规则： + +* 祈使语气（"添加功能"而非"已添加功能"） +* 类型前缀后使用小写 +* 末尾不加句号 +* 不超过 72 个字符 +* 描述变更内容，而非方式 + +```bash +git commit -m "{type}: {description}" +``` + +*** + +## 阶段 4 — 输出 + +向用户报告： + +``` +Committed: {hash_short} +Message: {type}: {description} +Files: {count} 个文件已更改 + +下一步： + - git push → 推送到远程 + - /prp-pr → 创建拉取请求 + - /code-review → 推送前进行代码审查 +``` + +*** + +## 示例 + +| 你说 | 执行结果 | +|---|---| +| `/prp-commit` | 暂存所有内容，自动生成信息 | +| `/prp-commit staged` | 仅提交已暂存的内容 | +| `/prp-commit *.ts` | 暂存所有 TypeScript 文件，然后提交 | +| `/prp-commit except tests` | 暂存除测试文件外的所有内容 | +| `/prp-commit the database migration` | 从状态中查找数据库迁移文件，暂存它们 | +| `/prp-commit only new files` | 仅暂存未跟踪文件 | diff --git a/docs/zh-CN/commands/prp-implement.md b/docs/zh-CN/commands/prp-implement.md new file mode 100644 index 00000000..27a67590 --- /dev/null +++ b/docs/zh-CN/commands/prp-implement.md @@ -0,0 +1,394 @@ +--- +description: 执行带有严格验证循环的实施计划 +argument-hint: +--- + +> 改编自 Wirasm 的 PRPs-agentic-eng。属于 PRP 工作流系列。 + +# PRP 实施 + +按步骤执行计划文件，并进行持续验证。每次更改后立即验证——绝不累积损坏状态。 + +**核心理念**：验证循环能及早发现错误。每次更改后都运行检查。立即修复问题。 + +**黄金法则**：如果验证失败，先修复再继续。绝不累积损坏状态。 + +*** + +## 阶段 0 — 检测 + +### 包管理器检测 + +| 文件存在 | 包管理器 | 运行器 | +|---|---|---| +| `bun.lockb` | bun | `bun run` | +| `pnpm-lock.yaml` | pnpm | `pnpm run` | +| `yarn.lock` | yarn | `yarn` | +| `package-lock.json` | npm | `npm run` | +| `pyproject.toml` 或 `requirements.txt` | uv / pip | `uv run` 或 `python -m` | +| `Cargo.toml` | cargo | `cargo` | +| `go.mod` | go | `go` | + +### 验证脚本 + +检查 `package.json`（或等效文件）中可用的脚本： + +```bash +# For Node.js projects +cat package.json | grep -A 20 '"scripts"' +``` + +记录可用的命令：类型检查、代码检查、测试、构建。 + +*** + +## 阶段 1 — 加载 + +读取计划文件： + +```bash +cat "$ARGUMENTS" +``` + +从计划中提取以下部分： + +* **摘要** — 正在构建什么 +* **要镜像的模式** — 要遵循的代码约定 +* **要更改的文件** — 要创建或修改的内容 +* **逐步任务** — 实施顺序 +* **验证命令** — 如何验证正确性 +* **验收标准** — 完成的定义 + +如果文件不存在或不是有效的计划： + +``` +错误：计划文件未找到或无效。 +请先运行 /prp-plan <功能描述> 来创建计划。 +``` + +**检查点**：计划已加载。所有部分已识别。任务已提取。 + +*** + +## 阶段 2 — 准备 + +### Git 状态 + +```bash +git branch --show-current +git status --porcelain +``` + +### 分支决策 + +| 当前状态 | 操作 | +|---|---| +| 在功能分支上 | 使用当前分支 | +| 在主分支上，工作区干净 | 创建功能分支：`git checkout -b feat/{plan-name}` | +| 在主分支上，工作区有未暂存更改 | **停止** — 要求用户先暂存或提交 | +| 在此功能的 git 工作树中 | 使用该工作树 | + +### 同步远程 + +```bash +git pull --rebase origin $(git branch --show-current) 2>/dev/null || true +``` + +**检查点**：位于正确分支。工作区已就绪。远程已同步。 + +*** + +## 阶段 3 — 执行 + +按顺序处理计划中的每个任务。 + +### 每个任务的循环 + +对于**逐步任务**中的每个任务： + +1. **读取 MIRROR 参考** — 打开任务 MIRROR 字段中引用的模式文件。在编写代码前理解约定。 + +2. **实施** — 严格按照模式编写代码。应用 GOTCHA 警告。使用指定的 IMPORTS。 + +3. **立即验证** — 每次文件更改后： + ```bash + # 运行类型检查（根据项目调整命令） + [阶段 0 中的类型检查命令] + ``` + 如果类型检查失败 → 在移动到下一个文件之前修复错误。 + +4. **跟踪进度** — 记录：`[done] Task N: [task name] — complete` + +### 处理偏差 + +如果实施必须偏离计划： + +* 记录**什么**发生了变化 +* 记录**为什么**发生变化 +* 使用修正后的方法继续 +* 这些偏差将在报告中捕获 + +**检查点**：所有任务已执行。偏差已记录。 + +*** + +## 阶段 4 — 验证 + +运行计划中的所有验证级别。在继续之前修复每个级别的问题。 + +### 级别 1：静态分析 + +```bash +# Type checking — zero errors required +[project type-check command] + +# Linting — fix automatically where possible +[project lint command] +[project lint-fix command] +``` + +如果自动修复后仍有代码检查错误，请手动修复。 + +### 级别 2：单元测试 + +为每个新函数编写测试（如计划中的测试策略所指定）。 + +```bash +[project test command for affected area] +``` + +* 每个函数至少需要一个测试 +* 覆盖计划中列出的边缘情况 +* 如果测试失败 → 修复实现（而不是测试，除非测试本身有误） + +### 级别 3：构建检查 + +```bash +[project build command] +``` + +构建必须成功，零错误。 + +### 级别 4：集成测试（如适用） + +```bash +# Start server, run tests, stop server +[project dev server command] & +SERVER_PID=$! + +# Wait for server to be ready (adjust port as needed) +SERVER_READY=0 +for i in $(seq 1 30); do + if curl -sf http://localhost:PORT/health >/dev/null 2>&1; then + SERVER_READY=1 + break + fi + sleep 1 +done + +if [ "$SERVER_READY" -ne 1 ]; then + kill "$SERVER_PID" 2>/dev/null || true + echo "ERROR: Server failed to start within 30s" >&2 + exit 1 +fi + +[integration test command] +TEST_EXIT=$? + +kill "$SERVER_PID" 2>/dev/null || true +wait "$SERVER_PID" 2>/dev/null || true + +exit "$TEST_EXIT" +``` + +### 级别 5：边缘情况测试 + +运行计划测试策略清单中的边缘情况。 + +**检查点**：所有 5 个验证级别均通过。零错误。 + +*** + +## 阶段 5 — 报告 + +### 创建实施报告 + +```bash +mkdir -p .claude/PRPs/reports +``` + +将报告写入 `.claude/PRPs/reports/{plan-name}-report.md`： + +```markdown +# 实现报告：[功能名称] + +## 摘要 +[已实现的内容] + +## 评估与实际对比 + +| 指标 | 预测（计划） | 实际 | +|---|---|---| +| 复杂度 | [来自计划] | [实际] | +| 信心指数 | [来自计划] | [实际] | +| 变更文件数 | [来自计划] | [实际数量] | + +## 已完成任务 + +| # | 任务 | 状态 | 备注 | +|---|---|---|---| +| 1 | [任务名称] | [已完成] 完成 | | +| 2 | [任务名称] | [已完成] 完成 | 存在偏差 — [原因] | + +## 验证结果 + +| 级别 | 状态 | 备注 | +|---|---|---| +| 静态分析 | [已完成] 通过 | | +| 单元测试 | [已完成] 通过 | 编写了 N 个测试 | +| 构建 | [已完成] 通过 | | +| 集成测试 | [已完成] 通过 | 或不适用 | +| 边界情况 | [已完成] 通过 | | + +## 变更文件 + +| 文件 | 操作 | 行数 | +|---|---|---| +| `path/to/file` | 新建 | +N | +| `path/to/file` | 更新 | +N / -M | + +## 与计划的偏差 +[列出所有偏差及其原因，或填写"无"] + +## 遇到的问题 +[列出所有问题及解决方案，或填写"无"] + +## 编写的测试 + +| 测试文件 | 测试数量 | 覆盖范围 | +|---|---|---| +| `path/to/test` | N 个测试 | [覆盖区域] | + +## 后续步骤 +- [ ] 通过 `/code-review` 进行代码审查 +- [ ] 通过 `/prp-pr` 创建拉取请求 +``` + +### 更新 PRD（如适用） + +如果此实施是针对 PRD 阶段的： + +1. 将阶段状态从 `in-progress` 更新为 `complete` +2. 添加报告路径作为参考 + +### 归档计划 + +```bash +mkdir -p .claude/PRPs/plans/completed +mv "$ARGUMENTS" .claude/PRPs/plans/completed/ +``` + +**检查点**：报告已创建。PRD 已更新。计划已归档。 + +*** + +## 阶段 6 — 输出 + +向用户报告： + +``` +## 实现完成 + +- **计划**: [计划文件路径] → 已归档至 completed/ +- **分支**: [当前分支名称] +- **状态**: [完成] 所有任务已完成 + +### 验证摘要 + +| 检查项 | 状态 | +|---|---| +| 类型检查 | [完成] | +| 代码检查 | [完成] | +| 测试 | [完成] (已编写 N 个) | +| 构建 | [完成] | +| 集成测试 | [完成] 或 不适用 | + +### 文件变更 +- 创建了 [N] 个文件，更新了 [M] 个文件 + +### 偏差 +[摘要 或 "无 — 完全按计划执行"] + +### 产物 +- 报告: `.claude/PRPs/reports/{名称}-report.md` +- 已归档计划: `.claude/PRPs/plans/completed/{名称}.plan.md` + +### PRD 进度（如适用） +| 阶段 | 状态 | +|---|---| +| 阶段 1 | [完成] 已完成 | +| 阶段 2 | [下一步] | +| ... | ... | + +> 下一步：运行 `/prp-pr` 创建拉取请求，或先运行 `/code-review` 审查更改。 +``` + +*** + +## 处理失败 + +### 类型检查失败 + +1. 仔细阅读错误信息 +2. 在源文件中修复类型错误 +3. 重新运行类型检查 +4. 仅在干净后继续 + +### 测试失败 + +1. 确定错误是在实现中还是在测试中 +2. 修复根本原因（通常是实现） +3. 重新运行测试 +4. 仅在全部通过后继续 + +### 代码检查失败 + +1. 首先运行自动修复 +2. 如果仍有错误，手动修复 +3. 重新运行代码检查 +4. 仅在干净后继续 + +### 构建失败 + +1. 通常是类型或导入问题 — 检查错误信息 +2. 修复有问题的文件 +3. 重新运行构建 +4. 仅在成功后继续 + +### 集成测试失败 + +1. 检查服务器是否正确启动 +2. 验证端点/路由是否存在 +3. 检查请求格式是否与预期匹配 +4. 修复并重新运行 + +*** + +## 成功标准 + +* **TASKS\_COMPLETE**：计划中的所有任务均已执行 +* **TYPES\_PASS**：零类型错误 +* **LINT\_PASS**：零代码检查错误 +* **TESTS\_PASS**：所有测试通过，已编写新测试 +* **BUILD\_PASS**：构建成功 +* **REPORT\_CREATED**：实施报告已保存 +* **PLAN\_ARCHIVED**：计划已移至 `completed/` + +*** + +## 后续步骤 + +* 运行 `/code-review` 在提交前审查更改 +* 运行 `/prp-commit` 使用描述性消息提交 +* 运行 `/prp-pr` 创建拉取请求 +* 如果 PRD 有更多阶段，运行 `/prp-plan ` diff --git a/docs/zh-CN/commands/prp-plan.md b/docs/zh-CN/commands/prp-plan.md new file mode 100644 index 00000000..8775c789 --- /dev/null +++ b/docs/zh-CN/commands/prp-plan.md @@ -0,0 +1,506 @@ +--- +description: 创建全面的功能实现计划，包括代码库分析和模式提取 +argument-hint: +--- + +> 改编自 Wirasm 的 PRPs-agentic-eng。属于 PRP 工作流系列。 + +# PRP 计划 + +创建一个详细、自包含的实现计划，该计划捕获所有代码库模式、约定和上下文，以便一次性实现一个功能。 + +**核心理念**：一个优秀的计划包含实现所需的一切，无需再提出其他问题。每个模式、每个约定、每个陷阱——一次性捕获，并在整个过程中引用。 + +**黄金法则**：如果在实现过程中需要搜索代码库，请立即将该知识捕获到计划中。 + +*** + +## 阶段 0 — 检测 + +根据 `$ARGUMENTS` 确定输入类型： + +| 输入模式 | 检测 | 操作 | +|---|---|---| +| 以 `.prd.md` 结尾的路径 | PRD 文件路径 | 解析 PRD，查找下一个待处理阶段 | +| 包含“实施阶段”的 `.md` 路径 | 类似 PRD 的文档 | 解析阶段，查找下一个待处理阶段 | +| 任何其他文件的路径 | 参考文件 | 读取文件以获取上下文，视为自由格式 | +| 自由格式文本 | 功能描述 | 直接进入阶段 1 | +| 空/空白 | 无输入 | 询问用户要规划什么功能 | + +### PRD 解析（当输入为 PRD 时） + +1. 使用 `cat "$PRD_PATH"` 读取 PRD 文件 +2. 解析 **实施阶段** 部分 +3. 根据状态查找阶段： + * 查找 `pending` 阶段 + * 检查依赖链（一个阶段可能依赖于先前阶段为 `complete`） + * 选择 **下一个符合条件的待处理阶段** +4. 从所选阶段中提取： + * 阶段名称和描述 + * 验收标准 + * 对先前阶段的依赖 + * 任何范围说明或约束 +5. 将阶段描述用作要规划的功能 + +如果没有剩余待处理阶段，则报告所有阶段已完成。 + +*** + +## 阶段 1 — 解析 + +提取并阐明功能需求。 + +### 功能理解 + +从输入（PRD 阶段或自由格式描述）中，识别： + +* **构建什么**（具体可交付成果） +* **为什么重要**（用户价值） +* **谁使用它**（目标用户/系统） +* **它适合哪里**（代码库的哪个部分） + +### 用户故事 + +格式化为： + +``` +作为[用户类型]， +我希望[能力]， +以便[收益]。 +``` + +### 复杂度评估 + +| 级别 | 指标 | 典型范围 | +|---|---|---| +| **小** | 单个文件、隔离更改、无新依赖 | 1-3 个文件，<100 行 | +| **中** | 多个文件、遵循现有模式、少量新概念 | 3-10 个文件，100-500 行 | +| **大** | 横切关注点、新模式、外部集成 | 10+ 个文件，500+ 行 | +| **超大** | 架构更改、新子系统、需要迁移 | 20+ 个文件，考虑拆分 | + +### 歧义门控 + +如果以下任何一项不明确，**停止并向用户提问**，然后再继续： + +* 核心可交付成果模糊 +* 成功标准未定义 +* 存在多种有效解释 +* 技术方法存在重大未知数 + +不要猜测。要提问。基于假设的计划会在实施过程中失败。 + +*** + +## 阶段 2 — 探索 + +收集深入的代码库情报。直接针对以下每个类别搜索代码库。 + +### 代码库搜索（8 个类别） + +对于每个类别，使用 grep、find 和文件读取进行搜索： + +1. **类似实现** — 查找与计划功能相似的现有功能。寻找类似的模式、端点、组件或模块。 + +2. **命名约定** — 识别代码库相关区域中文件、函数、变量、类和导出的命名方式。 + +3. **错误处理** — 查找在类似代码路径中如何捕获、传播、记录错误并将其返回给用户。 + +4. **日志记录模式** — 识别记录什么内容、在什么级别以及以什么格式记录。 + +5. **类型定义** — 查找相关类型、接口、模式及其组织方式。 + +6. **测试模式** — 查找类似功能的测试方式。注意测试文件位置、命名、设置/拆卸模式以及断言风格。 + +7. **配置** — 查找相关配置文件、环境变量和功能标志。 + +8. **依赖项** — 识别类似功能使用的包、导入和内部模块。 + +### 代码库分析（5 个追踪） + +读取相关文件以追踪： + +1. **入口点** — 请求/操作如何进入系统并到达您正在修改的区域？ +2. **数据流** — 数据如何在相关代码路径中移动？ +3. **状态更改** — 修改了哪些状态以及在哪里修改？ +4. **契约** — 必须遵守哪些接口、API 或协议？ +5. **模式** — 使用了哪些架构模式（仓库、服务、控制器等）？ + +### 统一发现表 + +将发现结果编译到单个参考中： + +| 类别 | 文件:行 | 模式 | 关键片段 | +|---|---|---|---| +| 命名 | `src/services/userService.ts:1-5` | 服务使用 camelCase，类型使用 PascalCase | `export class UserService` | +| 错误 | `src/middleware/errorHandler.ts:10-25` | 自定义 AppError 类 | `throw new AppError(...)` | +| ... | ... | ... | ... | + +*** + +## 阶段 3 — 研究 + +如果功能涉及外部库、API 或不熟悉的技术： + +1. 搜索网络以获取官方文档 +2. 查找使用示例和最佳实践 +3. 识别特定版本的陷阱 + +将每个发现格式化为： + +``` +KEY_INSIGHT: [你学到的内容] +APPLIES_TO: [这影响计划的哪个部分] +GOTCHA: [任何警告或版本特定问题] +``` + +如果功能仅使用已充分理解的内部模式，则跳过此阶段并注明：“无需外部研究——功能使用已建立的内部模式。” + +*** + +## 阶段 4 — 设计 + +### 用户体验转换（如果适用） + +记录前后用户体验： + +**之前：** + +``` +┌─────────────────────────────┐ +│ [当前用户体验] │ +│ 展示当前流程， │ +│ 用户所见/所操作的内容 │ +└─────────────────────────────┘ +``` + +**之后：** + +``` +┌─────────────────────────────┐ +│ [新用户体验] │ +│ 展示改进后的流程， │ +│ 用户会看到哪些变化 │ +└─────────────────────────────┘ +``` + +### 交互更改 + +| 接触点 | 之前 | 之后 | 备注 | +|---|---|---|---| +| ... | ... | ... | ... | + +如果功能纯粹是后端/内部且没有用户体验更改，则注明：“内部更改——无面向用户的用户体验转换。” + +*** + +## 阶段 5 — 架构 + +### 策略设计 + +定义实施方法： + +* **方法**：高级策略（例如，“按照现有仓库模式添加新的服务层”） +* **考虑的替代方案**：评估了哪些其他方法以及为何被拒绝 +* **范围**：将要构建的具体边界 +* **不构建**：明确列出超出范围的内容（防止实施期间范围蔓延） + +*** + +## 阶段 6 — 生成 + +使用下面的模板编写完整的计划文档。保存到 `.claude/PRPs/plans/{kebab-case-feature-name}.plan.md`。 + +如果目录不存在，则创建它： + +```bash +mkdir -p .claude/PRPs/plans +``` + +### 计划模板 + +````markdown +# 计划：[功能名称] + +## 摘要 +[2-3句概述] + +## 用户故事 +作为[用户]，我希望[能力]，以便[收益]。 + +## 问题 → 解决方案 +[当前状态] → [期望状态] + +## 元数据 +- **复杂度**：[小 | 中 | 大 | 超大] +- **来源PRD**：[路径或“N/A”] +- **PRD阶段**：[阶段名称或“N/A”] +- **预估文件数**：[数量] + +--- + +## UX设计 + +### 之前 +[ASCII图表或“N/A — 内部变更”] + +### 之后 +[ASCII图表或“N/A — 内部变更”] + +### 交互变更 +| 接触点 | 之前 | 之后 | 备注 | +|---|---|---|---| + +--- + +## 必读文件 + +实现前必须阅读的文件： + +| 优先级 | 文件 | 行号 | 原因 | +|---|---|---|---| +| P0（关键） | `path/to/file` | 1-50 | 需遵循的核心模式 | +| P1（重要） | `path/to/file` | 10-30 | 相关类型 | +| P2（参考） | `path/to/file` | 全部 | 类似实现 | + +## 外部文档 + +| 主题 | 来源 | 关键要点 | +|---|---|---| +| ... | ... | ... | + +--- + +## 需镜像的模式 + +在代码库中发现的代码模式。请严格遵循。 + +### 命名约定 +// 来源：[文件:行号] +[展示命名模式的实际代码片段] + +### 错误处理 +// 来源：[文件:行号] +[展示错误处理的实际代码片段] + +### 日志记录模式 +// 来源：[文件:行号] +[展示日志记录的实际代码片段] + +### 仓库模式 +// 来源：[文件:行号] +[展示数据访问的实际代码片段] + +### 服务模式 +// 来源：[文件:行号] +[展示服务层的实际代码片段] + +### 测试结构 +// 来源：[文件:行号] +[展示测试设置的实际代码片段] + +--- + +## 需变更的文件 + +| 文件 | 操作 | 理由 | +|---|---|---| +| `path/to/file.ts` | 创建 | 功能的新服务 | +| `path/to/existing.ts` | 更新 | 添加新方法 | + +## 不构建的内容 + +- [明确不在范围内的第1项] +- [明确不在范围内的第2项] + +--- + +## 分步任务 + +### 任务1：[名称] +- **操作**：[要做什么] +- **实现**：[要编写的具体代码/逻辑] +- **镜像**：[需遵循的“需镜像的模式”部分中的模式] +- **导入**：[所需的导入] +- **陷阱**：[需避免的已知陷阱] +- **验证**：[如何验证此任务正确] + +### 任务2：[名称] +- **操作**：... +- **实现**：... +- **镜像**：... +- **导入**：... +- **陷阱**：... +- **验证**：... + +[继续所有任务...] + +--- + +## 测试策略 + +### 单元测试 + +| 测试 | 输入 | 预期输出 | 边界情况？ | +|---|---|---|---| +| ... | ... | ... | ... | + +### 边界情况检查清单 +- [ ] 空输入 +- [ ] 最大尺寸输入 +- [ ] 无效类型 +- [ ] 并发访问 +- [ ] 网络故障（如适用） +- [ ] 权限被拒绝 + +--- + +## 验证命令 + +### 静态分析 +```bash +# Run type checker +[project-specific type check command] +``` +预期：零类型错误 + +### 单元测试 +```bash +# Run tests for affected area +[project-specific test command] +``` +预期：所有测试通过 + +### 完整测试套件 +```bash +# Run complete test suite +[project-specific full test command] +``` +预期：无回归 + +### 数据库验证（如适用） +```bash +# Verify schema/migrations +[project-specific db command] +``` +预期：Schema 为最新 + +### 浏览器验证（如适用） +```bash +# Start dev server and verify +[project-specific dev server command] +``` +预期：功能按设计工作 + +### 手动验证 +- [ ] [逐步手动验证检查清单] + +--- + +## 验收标准 +- [ ] 所有任务完成 +- [ ] 所有验证命令通过 +- [ ] 测试已编写并通过 +- [ ] 无类型错误 +- [ ] 无 lint 错误 +- [ ] 符合 UX 设计（如适用） + +## 完成检查清单 +- [ ] 代码遵循发现的模式 +- [ ] 错误处理符合代码库风格 +- [ ] 日志记录遵循代码库约定 +- [ ] 测试遵循测试模式 +- [ ] 无硬编码值 +- [ ] 文档已更新（如需要） +- [ ] 无不必要的范围扩展 +- [ ] 自包含 — 实现期间无需提问 + +## 风险 +| 风险 | 可能性 | 影响 | 缓解措施 | +|---|---|---|---| +| ... | ... | ... | ... | + +## 备注 +[任何额外的上下文、决策或观察] +``` + +--- + +## Output + +### Save the Plan + +Write the generated plan to: +``` +.claude/PRPs/plans/{kebab-case-feature-name}.plan.md +``` + +### Update PRD (if input was a PRD) + +If this plan was generated from a PRD phase: +1. Update the phase status from `pending` to `in-progress` +2. Add the plan file path as a reference in the phase + +### Report to User + +``` +## 计划已创建 + +- **文件**：.claude/PRPs/plans/{kebab-case-feature-name}.plan.md +- **来源PRD**：[路径或“N/A”] +- **阶段**：[阶段名称或“独立”] +- **复杂度**：[级别] +- **范围**：[N个文件，M个任务] +- **关键模式**：[前3个发现的模式] +- **外部研究**：[研究的主题或“无需”] +- **风险**：[主要风险或“未识别”] +- **置信度评分**：[1-10] — 单次实现成功的可能性 + +> 下一步：运行 `/prp-implement .claude/PRPs/plans/{name}.plan.md` 来执行此计划。 +``` + +--- + +## 验证 + +在最终确定之前，请根据以下检查清单验证计划： + +### 上下文完整性 +- [ ] 所有相关文件已发现并记录 +- [ ] 命名约定已通过示例捕获 +- [ ] 错误处理模式已记录 +- [ ] 测试模式已识别 +- [ ] 依赖项已列出 + +### 实现就绪性 +- [ ] 每个任务都有操作、实现、镜像和验证 +- [ ] 没有任务需要额外的代码库搜索 +- [ ] 导入路径已指定 +- [ ] 陷阱已在适用处记录 + +### 模式忠实度 +- [ ] 代码片段是实际的代码库示例（非虚构） +- [ ] 来源引用指向真实文件和行号 +- [ ] 模式涵盖命名、错误、日志记录、数据访问和测试 +- [ ] 新代码将与现有代码无法区分 + +### 验证覆盖范围 +- [ ] 静态分析命令已指定 +- [ ] 测试命令已指定 +- [ ] 构建验证已包含 + +### UX清晰度 +- [ ] 之前/之后的状态已记录（或标记为N/A） +- [ ] 交互变更已列出 +- [ ] UX的边界情况已识别 + +### 无先验知识测试 +不熟悉此代码库的开发人员应能仅使用此计划实现该功能，无需搜索代码库或提问。如果不能，请添加缺失的上下文。 + +--- + +## 后续步骤 + +- 运行 `/prp-implement ` 来执行此计划 +- 运行 `/plan` 进行快速对话式规划（无需产物） +- 如果范围不明确，运行 `/prp-prd` 先创建PRD +```` diff --git a/docs/zh-CN/commands/prp-pr.md b/docs/zh-CN/commands/prp-pr.md new file mode 100644 index 00000000..80752518 --- /dev/null +++ b/docs/zh-CN/commands/prp-pr.md @@ -0,0 +1,188 @@ +--- +description: "从当前分支创建包含未推送提交的 GitHub PR — 发现模板、分析更改、推送" +argument-hint: "[base-branch] (default: main)" +--- + +# 创建拉取请求 + +> 改编自 Wirasm 的 PRPs-agentic-eng。属于 PRP 工作流系列的一部分。 + +**输入**：`$ARGUMENTS` — 可选，可包含基础分支名称和/或标志（例如 `--draft`）。 + +**解析 `$ARGUMENTS`**： + +* 提取所有可识别的标志（`--draft`） +* 将剩余的非标志文本视为基础分支名称 +* 若未指定，默认基础分支为 `main` + +*** + +## 阶段 1 — 验证 + +检查前置条件： + +```bash +git branch --show-current +git status --short +git log origin/..HEAD --oneline +``` + +| 检查项 | 条件 | 失败时的操作 | +|---|---|---| +| 不在基础分支上 | 当前分支 ≠ 基础分支 | 停止："请先切换到功能分支。" | +| 工作目录干净 | 无未提交的更改 | 警告："存在未提交的更改。请先提交或暂存。使用 `/prp-commit` 提交。" | +| 存在领先提交 | `git log origin/..HEAD` 不为空 | 停止："`` 前无提交。无需创建 PR。" | +| 无现有 PR | `gh pr list --head --json number` 为空 | 停止："PR 已存在：#<编号>。使用 `gh pr view --web` 打开。" | + +若所有检查通过，继续执行。 + +*** + +## 阶段 2 — 发现 + +### PR 模板 + +按顺序搜索 PR 模板： + +1. `.github/PULL_REQUEST_TEMPLATE/` 目录 — 若存在，列出文件并让用户选择（或使用 `default.md`） +2. `.github/PULL_REQUEST_TEMPLATE.md` +3. `.github/pull_request_template.md` +4. `docs/pull_request_template.md` + +若找到，读取并使用其结构作为 PR 正文。 + +### 提交分析 + +```bash +git log origin/..HEAD --format="%h %s" --reverse +``` + +分析提交以确定： + +* **PR 标题**：使用带类型前缀的常规提交格式 — `feat: ...`、`fix: ...` 等。 + * 若存在多种类型，使用主导类型 + * 若为单个提交，直接使用其消息 +* **变更摘要**：按类型/领域对提交进行分组 + +### 文件分析 + +```bash +git diff origin/..HEAD --stat +git diff origin/..HEAD --name-only +``` + +对变更文件进行分类：源代码、测试、文档、配置、迁移。 + +### PRP 工件 + +检查相关的 PRP 工件： + +* `.claude/PRPs/reports/` — 实现报告 +* `.claude/PRPs/plans/` — 已执行的计划 +* `.claude/PRPs/prds/` — 相关 PRD + +若存在，在 PR 正文中引用它们。 + +*** + +## 阶段 3 — 推送 + +```bash +git push -u origin HEAD +``` + +若推送因分歧失败： + +```bash +git fetch origin +git rebase origin/ +git push -u origin HEAD +``` + +若变基发生冲突，停止并通知用户。 + +*** + +## 阶段 4 — 创建 + +### 使用模板 + +若在阶段 2 中找到 PR 模板，使用提交和文件分析填充每个部分。保留所有模板部分 — 若不适用，将部分留为"不适用"而非删除。 + +### 无模板 + +使用以下默认格式： + +```markdown +## 摘要 + +<用1-2句话描述此PR的功能及原因> + +## 变更内容 + + + +## 文件变更 + + + +## 测试说明 + +<描述变更的测试方式，或填写"需要测试"> + +## 相关问题 + +<关联问题，使用Closes/Fixes/Relates to #N格式，或填写"无"> +``` + +### 创建 PR + +```bash +gh pr create \ + --title "" \ + --base \ + --body "" + # Add --draft if the --draft flag was parsed from $ARGUMENTS +``` + +*** + +## 阶段 5 — 验证 + +```bash +gh pr view --json number,url,title,state,baseRefName,headRefName,additions,deletions,changedFiles +gh pr checks --json name,status,conclusion 2>/dev/null || true +``` + +*** + +## 阶段 6 — 输出 + +向用户报告： + +``` +PR #: <标题> +URL: <网址> +分支: <源分支> → <目标分支> +变更: 共<文件数>个文件，新增<添加行数>行，删除<删除行数>行 + +CI 检查: <状态摘要 或 "待处理" 或 "未配置"> + +引用的构建产物: + - + +后续步骤: + - gh pr view <编号> --web → 在浏览器中打开 + - /code-review <编号> → 审查该 PR + - gh pr merge <编号> → 准备就绪后合并 +``` + +*** + +## 边界情况 + +* **无 `gh` CLI**：停止并提示："需要 GitHub CLI（`gh`）。安装地址：" +* **未认证**：停止并提示："请先运行 `gh auth login`。" +* **需要强制推送**：若远程已分歧且已完成变基，使用 `git push --force-with-lease`（切勿使用 `--force`）。 +* **多个 PR 模板**：若 `.github/PULL_REQUEST_TEMPLATE/` 包含多个文件，列出并让用户选择。 +* **大型 PR（超过 20 个文件）**：警告 PR 规模。若变更逻辑上可分离，建议拆分。 diff --git a/docs/zh-CN/commands/prp-prd.md b/docs/zh-CN/commands/prp-prd.md new file mode 100644 index 00000000..fb1412e3 --- /dev/null +++ b/docs/zh-CN/commands/prp-prd.md @@ -0,0 +1,453 @@ +--- +description: "交互式PRD生成器 - 问题优先、假设驱动的产品规格，通过来回提问进行" +argument-hint: "[feature/product idea] (blank = start with questions)" +--- + +# 产品需求文档生成器 + +> 改编自 Wirasm 的 PRPs-agentic-eng。属于 PRP 工作流系列的一部分。 + +**输入**：$ARGUMENTS + +*** + +## 你的角色 + +你是一位敏锐的产品经理，需要做到： + +* 从**问题**出发，而非解决方案 +* 在构建之前要求提供证据 +* 以假设而非规格说明来思考 +* 在假设之前先提出澄清性问题 +* 诚实地承认不确定性 + +**反模式**：不要用空话填充章节。如果信息缺失，请写“待定 - 需要研究”，而不是编造听起来合理的需求。 + +*** + +## 流程概览 + +``` +问题集1 → 基础 → 问题集2 → 研究 → 问题集3 → 生成 +``` + +每组问题都建立在前一组答案的基础上。验证阶段用于确认假设。 + +*** + +## 阶段 1：启动 - 核心问题 + +**如果未提供输入**，请询问： + +> **你想构建什么？** +> 用几句话描述产品、功能或能力。 + +**如果提供了输入**，通过复述来确认理解： + +> 我理解你想构建：{复述的理解} +> 这是否正确，或者我是否需要调整理解？ + +**关卡**：等待用户回复后再继续。 + +*** + +## 阶段 2：基础 - 问题发现 + +提出以下问题（一次性全部呈现，用户可以一起回答）： + +> **基础问题：** +> +> 1. **谁**有这个问题？要具体——不仅仅是“用户”，而是什么类型的人/角色？ +> +> 2. 他们面临什么**问题**？描述可观察到的痛点，而不是假设的需求。 +> +> 3. **为什么**他们今天无法解决？存在哪些替代方案，它们为何失败？ +> +> 4. **为什么是现在？** 发生了什么变化，使得这件事值得构建？ +> +> 5. 你如何**知道**你已经解决了问题？成功会是什么样子？ + +**关卡**：等待用户回复后再继续。 + +*** + +## 阶段 3：验证 - 市场与背景研究 + +在获得基础答案后，进行研究： + +**研究市场背景：** + +1. 寻找市场上类似的产品/功能 +2. 识别竞争对手如何解决这个问题 +3. 注意常见的模式和反模式 +4. 检查该领域近期的趋势或变化 + +整理发现，包括直接链接、关键见解以及可用信息中的任何空白。 + +**如果存在代码库，则并行探索：** + +1. 查找与产品/功能想法相关的现有功能 +2. 识别可以借鉴的模式 +3. 注意技术约束或机会 + +记录观察到的文件位置、代码模式和约定。 + +**向用户总结发现：** + +> **我的发现：** +> +> * {市场洞察 1} +> * {竞争对手的方法} +> * {代码库中的相关模式（如果适用）} +> +> 这是否改变或完善了你的想法？ + +**关卡**：短暂暂停以等待用户输入（可以是“继续”或调整）。 + +*** + +## 阶段 4：深入探讨 - 愿景与用户 + +基于基础和研究，提出： + +> **愿景与用户：** +> +> 1. **愿景**：用一句话描述，如果这件事取得巨大成功，理想的最终状态是什么？ +> +> 2. **主要用户**：描述你最重要的用户——他们的角色、背景以及触发他们需求的因素。 +> +> 3. **待完成的工作**：完成这句话：“当\[情境]时，我想要\[动机]，以便我能\[结果]。” +> +> 4. **非用户**：明确谁不是目标用户？我们应该忽略谁？ +> +> 5. **约束条件**：存在哪些限制？（时间、预算、技术、法规） + +**关卡**：等待用户回复后再继续。 + +*** + +## 阶段 5：验证 - 技术可行性 + +**如果存在代码库，则进行两项并行调查：** + +调查 1 — 探索可行性： + +1. 识别可以借鉴的现有基础设施 +2. 查找已实现的类似模式 +3. 映射集成点和依赖关系 +4. 定位相关的配置和类型定义 + +记录观察到的文件位置、代码模式和约定。 + +调查 2 — 分析约束条件： + +1. 追踪现有相关功能的端到端实现方式 +2. 映射通过潜在集成点的数据流 +3. 识别架构模式和边界 +4. 基于类似功能估算复杂度 + +记录存在的内容，并附上精确的文件:行号引用。不要提建议。 + +**如果没有代码库，则研究技术方法：** + +1. 查找其他人使用过的技术方法 +2. 识别常见的实现模式 +3. 注意已知的技术挑战和陷阱 + +整理发现，并附上引用和差距分析。 + +**向用户总结：** + +> **技术背景：** +> +> * 可行性：{高/中/低}，因为{原因} +> * 可以借鉴：{现有模式/基础设施} +> * 关键技术风险：{主要关注点} +> +> 我是否应该了解任何技术约束？ + +**关卡**：短暂暂停以等待用户输入。 + +*** + +## 阶段 6：决策 - 范围与方法 + +提出最终的澄清性问题： + +> **范围与方法：** +> +> 1. **MVP 定义**：测试此功能是否有效所需的最小功能是什么？ +> +> 2. **必须拥有 vs 锦上添花**：v1 中必须包含哪 2-3 项？哪些可以等待？ +> +> 3. **关键假设**：完成这句话：“我们相信\[能力]将为\[用户]\[解决问题]。当\[可衡量的结果]时，我们将知道我们是对的。” +> +> 4. **范围之外**：你明确不构建什么（即使用户要求）？ +> +> 5. **未解决的问题**：哪些不确定性可能会改变方法？ + +**关卡**：等待用户回复后再生成。 + +*** + +## 阶段 7：生成 - 编写 PRD + +**输出路径**：`.claude/PRPs/prds/{kebab-case-name}.prd.md` + +如果需要，创建目录：`mkdir -p .claude/PRPs/prds` + +### PRD 模板 + +```markdown +# {产品/功能名称} + +## 问题陈述 + +{2-3句话：谁遇到了什么问题，不解决会带来什么代价？} + +## 证据 + +- {用户原话、数据点或观察结果，证明该问题确实存在} +- {另一条证据} +- {若无证据："假设——需通过[方法]进行验证"} + +## 拟议解决方案 + +{一段话：我们要构建什么，以及为什么选择此方案而非其他替代方案} + +## 关键假设 + +我们相信{能力}将为{用户}解决{问题}。 +当{可衡量的结果}出现时，我们就知道方向正确。 + +## 我们不会构建的内容 + +- {范围外事项1} - {原因} +- {范围外事项2} - {原因} + +## 成功指标 + +| 指标 | 目标 | 衡量方式 | +|------|------|----------| +| {主要指标} | {具体数值} | {方法} | +| {次要指标} | {具体数值} | {方法} | + +## 待解决问题 + +- [ ] {未解决的问题1} +- [ ] {未解决的问题2} + +--- + +## 用户与场景 + +**主要用户** +- **身份**：{具体描述} +- **当前行为**：{他们目前的做法} +- **触发时机**：{什么时刻触发需求} +- **成功状态**：{"完成"的具体表现} + +**待完成的任务** +当{情境}时，我想要{动机}，以便实现{结果}。 + +**非目标用户** +{本方案不针对哪些用户及原因} + +--- + +## 解决方案详情 + +### 核心能力（MoSCoW优先级） + +| 优先级 | 能力 | 理由 | +|--------|------|------| +| 必须有 | {功能} | {为何必不可少} | +| 必须有 | {功能} | {为何必不可少} | +| 应该有 | {功能} | {为何重要但不阻塞} | +| 可以有 | {功能} | {锦上添花} | +| 不会有 | {功能} | {明确推迟及原因} | + +### MVP范围 + +{验证假设所需的最小功能集} + +### 用户流程 + +{关键路径——到达价值的最短旅程} + +--- + +## 技术方案 + +**可行性**：{高/中/低} + +**架构说明** +- {关键技术决策及原因} +- {依赖项或集成点} + +**技术风险** + +| 风险 | 可能性 | 应对措施 | +|------|--------|----------| +| {风险} | {高/中/低} | {如何处理} | + +--- + +## 实施阶段 + + + +| # | 阶段 | 描述 | 状态 | 并行 | 依赖 | PRP计划 | +|---|------|------|------|------|------|---------| +| 1 | {阶段名称} | {本阶段交付内容} | 待定 | - | - | - | +| 2 | {阶段名称} | {本阶段交付内容} | 待定 | - | 1 | - | +| 3 | {阶段名称} | {本阶段交付内容} | 待定 | 与4并行 | 2 | - | +| 4 | {阶段名称} | {本阶段交付内容} | 待定 | 与3并行 | 2 | - | +| 5 | {阶段名称} | {本阶段交付内容} | 待定 | - | 3, 4 | - | + +### 阶段详情 + +**阶段1：{名称}** +- **目标**：{我们要达成的目标} +- **范围**：{明确的交付物} +- **成功信号**：{如何判断完成} + +**阶段2：{名称}** +- **目标**：{我们要达成的目标} +- **范围**：{明确的交付物} +- **成功信号**：{如何判断完成} + +{继续为每个阶段填写...} + +### 并行说明 + +{解释哪些阶段可以并行执行及原因} + +--- + +## 决策记录 + +| 决策 | 选择 | 备选方案 | 理由 | +|------|------|----------|------| +| {决策} | {选择} | {考虑过的选项} | {为何选择此项} | + +--- + +## 研究总结 + +**市场背景** +{市场研究的关键发现} + +**技术背景** +{技术探索的关键发现} + +--- + +*生成时间：{时间戳}* +*状态：草稿——需验证* +``` + +*** + +## 阶段 8：输出 - 总结 + +生成后，报告： + +```markdown +## PRD 已创建 + +**文件**：`.claude/PRPs/prds/{name}.prd.md` + +### 摘要 + +**问题**：{一行描述} +**解决方案**：{一行描述} +**关键指标**：{主要成功指标} + +### 验证状态 + +| 章节 | 状态 | +|---------|--------| +| 问题陈述 | {已验证/假设} | +| 用户研究 | {已完成/需要} | +| 技术可行性 | {已评估/待定} | +| 成功指标 | {已定义/需完善} | + +### 待解决问题（{数量}） + +{列出需要回答的待解决问题} + +### 建议的下一步 + +{用户研究、技术攻关、原型设计、利益相关者评审等之一} + +### 实施阶段 + +| # | 阶段 | 状态 | 可并行 | +|---|-------|--------|--------------| +{PRD 中的阶段表格} + +### 开始实施 + +运行：`/prp-plan .claude/PRPs/prds/{name}.prd.md` + +这将自动选择下一个待处理阶段并创建实施计划。 +``` + +*** + +## 问题流程总结 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 启动："你想构建什么？" │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 基础：谁、什么、为什么、为什么现在、如何衡量 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 落地：市场调研、竞品分析 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 深潜：愿景、主要用户、JTBD、约束条件 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 落地：技术可行性、代码库探索 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 决策：MVP、必须功能、假设、范围外 │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ 生成：将PRD写入.claude/PRPs/prds/ │ +└─────────────────────────────────────────────────────────┘ +``` + +*** + +## 与 ECC 的集成 + +在 PRD 生成之后： + +* 使用 `/prp-plan` 根据 PRD 阶段创建实施计划 +* 使用 `/plan` 进行无需 PRD 结构的更简单规划 +* 使用 `/save-session` 跨会话保留 PRD 上下文 + +## 成功标准 + +* **问题已验证**：问题是具体且有证据的（或标记为假设） +* **用户已定义**：主要用户是具体的，而非泛泛的 +* **假设清晰**：具有可衡量结果的可测试假设 +* **范围已界定**：明确的必须拥有项和明确的范围外项 +* **问题已确认**：不确定性已列出，而非隐藏 +* **可操作**：怀疑论者也能理解为什么这件事值得构建 diff --git a/docs/zh-CN/commands/review-pr.md b/docs/zh-CN/commands/review-pr.md new file mode 100644 index 00000000..87761aa3 --- /dev/null +++ b/docs/zh-CN/commands/review-pr.md @@ -0,0 +1,37 @@ +--- +description: 使用专门代理进行全面的PR审查 +--- + +对拉取请求进行全面的多视角审查。 + +## 用法 + +`/review-pr [PR-number-or-URL] [--focus=comments|tests|errors|types|code|simplify]` + +如果未指定 PR，则审查当前分支的 PR。如果未指定关注点，则运行完整的审查堆栈。 + +## 步骤 + +1. 识别 PR： + * 使用 `gh pr view` 获取 PR 详情、变更文件及差异 +2. 查找项目指南： + * 寻找 `CLAUDE.md`、lint 配置、TypeScript 配置、仓库约定 +3. 运行专项审查代理： + * `code-reviewer` + * `comment-analyzer` + * `pr-test-analyzer` + * `silent-failure-hunter` + * `type-design-analyzer` + * `code-simplifier` +4. 汇总结果： + * 去重重叠发现 + * 按严重程度排序 +5. 按严重程度分组报告发现 + +## 置信度规则 + +仅报告置信度 >= 80 的问题： + +* 严重：错误、安全、数据丢失 +* 重要：缺少测试、质量问题、风格违规 +* 建议：仅在明确要求时提供建议 diff --git a/docs/zh-CN/commands/santa-loop.md b/docs/zh-CN/commands/santa-loop.md new file mode 100644 index 00000000..adafef45 --- /dev/null +++ b/docs/zh-CN/commands/santa-loop.md @@ -0,0 +1,180 @@ +--- +description: 对抗性双审收敛循环——两个独立模型审查者均需批准后方可发布代码。 +--- + +# 圣诞老人循环 + +使用圣诞老人方法技能的对立双审收敛循环。两个独立的评审者——不同模型，无共享上下文——必须都返回 NICE 后代码才能发布。 + +## 目的 + +针对当前任务输出，运行两个独立的评审者（Claude Opus + 一个外部模型）。两者都必须返回 NICE 后才能推送代码。如果任一返回 NAUGHTY，则修复所有标记的问题，提交，并重新运行全新的评审者——最多 3 轮。 + +## 用法 + +``` +/santa-loop [file-or-glob | description] +``` + +## 工作流程 + +### 步骤 1：确定审查范围 + +从 `$ARGUMENTS` 确定范围，或回退到未提交的更改： + +```bash +git diff --name-only HEAD +``` + +读取所有已更改的文件以构建完整的审查上下文。如果 `$ARGUMENTS` 指定了路径、文件或描述，则改用该范围。 + +### 步骤 2：构建评分标准 + +根据被审查的文件类型构建合适的评分标准。每个标准必须有一个客观的 PASS/FAIL 条件。至少包括： + +| 标准 | 通过条件 | +|-----------|---------------| +| 正确性 | 逻辑正确，无错误，处理边界情况 | +| 安全性 | 无秘密、注入、XSS 或 OWASP Top 10 问题 | +| 错误处理 | 显式处理错误，无静默吞没 | +| 完整性 | 所有需求均已满足，无遗漏情况 | +| 内部一致性 | 文件或章节之间无矛盾 | +| 无回归 | 更改不破坏现有行为 | + +根据文件类型添加领域特定标准（例如，TypeScript 的类型安全，Rust 的内存安全，SQL 的迁移安全）。 + +### 步骤 3：双独立审查 + +使用 Agent 工具**并行**启动两个评审者（两者在单条消息中以便并发执行）。两者都必须完成才能进入裁决门。 + +每个评审者评估每个评分标准为 PASS 或 FAIL，然后返回结构化 JSON： + +```json +{ + "verdict": "PASS" | "FAIL", + "checks": [ + {"criterion": "...", "result": "PASS|FAIL", "detail": "..."} + ], + "critical_issues": ["..."], + "suggestions": ["..."] +} +``` + +裁决门（步骤 4）将这些映射为 NICE/NAUGHTY：两者都 PASS → NICE，任一 FAIL → NAUGHTY。 + +#### 评审者 A：Claude Agent（始终运行） + +启动一个 Agent（subagent\_type: `code-reviewer`，model: `opus`），包含完整的评分标准 + 所有被审查的文件。提示必须包括： + +* 完整的评分标准 +* 所有被审查的文件内容 +* "你是一个独立的质量评审者。你没有看到任何其他评审。你的工作是发现问题，而不是批准。" +* 返回上述结构化 JSON 裁决 + +#### 评审者 B：外部模型（仅当未安装外部 CLI 时回退到 Claude） + +首先，检测哪些 CLI 可用： + +```bash +command -v codex >/dev/null 2>&1 && echo "codex" || true +command -v gemini >/dev/null 2>&1 && echo "gemini" || true +``` + +构建评审者提示（与评审者 A 相同的评分标准和说明）并将其写入唯一的临时文件： + +```bash +PROMPT_FILE=$(mktemp /tmp/santa-reviewer-b-XXXXXX.txt) +cat > "$PROMPT_FILE" << 'EOF' +... full rubric + file contents + reviewer instructions ... +EOF +``` + +使用第一个可用的 CLI： + +**Codex CLI**（如果已安装） + +```bash +codex exec --sandbox read-only -m gpt-5.4 -C "$(pwd)" - < "$PROMPT_FILE" +rm -f "$PROMPT_FILE" +``` + +**Gemini CLI**（如果已安装且 codex 未安装） + +```bash +gemini -p "$(cat "$PROMPT_FILE")" -m gemini-2.5-pro +rm -f "$PROMPT_FILE" +``` + +**Claude Agent 回退**（仅当 `codex` 和 `gemini` 均未安装时） +启动第二个 Claude Agent（subagent\_type: `code-reviewer`，model: `opus`）。记录一条警告，说明两个评审者共享相同的模型家族——未实现真正的模型多样性，但上下文隔离仍然得到强制执行。 + +在所有情况下，评审者必须返回与评审者 A 相同的结构化 JSON 裁决。 + +### 步骤 4：裁决门 + +* **两者都 PASS** → **NICE** — 继续执行步骤 6（推送） +* **任一 FAIL** → **NAUGHTY** — 合并两个评审者的所有关键问题，去重，继续执行步骤 5 + +### 步骤 5：修复循环（NAUGHTY 路径） + +1. 显示两个评审者的所有关键问题 +2. 修复每个标记的问题——仅更改被标记的内容，不进行附带重构 +3. 将所有修复提交到单个提交中： + ``` + fix: 解决圣诞老人循环审查发现的问题（第 N 轮） + ``` +4. 使用**全新的评审者**（无先前轮次的记忆）重新运行步骤 3 +5. 重复直到两者都返回 PASS + +**最多 3 次迭代。** 如果 3 轮后仍为 NAUGHTY，则停止并呈现剩余问题： + +``` +圣诞循环升级（超过3次迭代） + +3轮后仍存在的问题： +- [列出两位评审员所有未解决的关键问题] + +继续前需进行人工审核。 +``` + +不要推送。 + +### 步骤 6：推送（NICE 路径） + +当两个评审者都返回 PASS 时： + +```bash +git push -u origin HEAD +``` + +### 步骤 7：最终报告 + +打印输出报告（参见下面的输出部分）。 + +## 输出 + +``` +SANTA VERDICT: [NICE / NAUGHTY (escalated)] + +Reviewer A (Claude Opus): [PASS/FAIL] +Reviewer B ([model used]): [PASS/FAIL] + +Agreement: + Both flagged: [issues caught by both] + Reviewer A only: [issues only A caught] + Reviewer B only: [issues only B caught] + +Iterations: [N]/3 +Result: [PUSHED / ESCALATED TO USER] +``` + +## 备注 + +* 评审者 A（Claude Opus）始终运行——无论工具如何，保证至少有一个强大的评审者。 +* 模型多样性是评审者 B 的目标。GPT-5.4 或 Gemini 2.5 Pro 提供真正的独立性——不同的训练数据、不同的偏见、不同的盲点。仅 Claude 的回退通过上下文隔离仍然提供价值，但失去了模型多样性。 +* 使用最强可用模型：Opus 用于评审者 A，GPT-5.4 或 Gemini 2.5 Pro 用于评审者 B。 +* 外部评审者使用 `--sandbox read-only`（Codex）运行，以防止审查期间仓库发生变异。 +* 每轮使用全新的评审者可以防止先前发现导致的锚定偏差。 +* 评分标准是最重要的输入。如果评审者盖章通过或标记主观风格问题，请收紧评分标准。 +* 在 NAUGHTY 轮次进行提交，以便即使循环被中断，修复也能被保留。 +* 仅在 NICE 后推送——绝不在循环中间推送。