The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: salvage zh-CN command translations
Affaan Mustafa6556f20af7c9
diff --git a/docs/zh-CN/commands/auto-update.md b/docs/zh-CN/commands/auto-update.mdnew file mode 100644index 000000000..328127092--- /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.mdnew file mode 100644index 000000000..8dab5afb5--- /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.mdnew file mode 100644index 000000000..315f9e875--- /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<Item>' 未定义方法 '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<Item>' 未定义方法 'add'+原因:状态持有不可修改的列表;变更通过 Cubit 进行++修改前:+```dart+state.items.add(item);+```+修改后:+```dart+context.read<CartCubit>().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.mdnew file mode 100644index 000000000..5fade6921--- /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.mdnew file mode 100644index 000000000..76bbc63e7--- /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: <X> Actual: <Y>` | 更新断言或修复实现 |+| `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.mdnew file mode 100644index 000000000..311ecd00d--- /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.mdnew file mode 100644index 000000000..72e6c4930--- /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.mdnew file mode 100644index 000000000..82aa5fb21--- /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.mdnew file mode 100644index 000000000..582591ade--- /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.mdnew file mode 100644index 000000000..03471be1a--- /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.mdnew file mode 100644index 000000000..dd478b32a--- /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.mdnew file mode 100644index 000000000..750e8b7cb--- /dev/null+++ b/docs/zh-CN/commands/jira.md@@ -0,0 +1,108 @@+---+description: 检索Jira工单,分析需求,更新状态或添加评论。使用jira-integration技能和MCP或REST API。+---++# Jira 命令++直接从工作流中与 Jira 工单交互——获取工单、分析需求、添加评论以及变更状态。++## 用法++```+/jira get <TICKET-KEY> # 获取并分析工单+/jira comment <TICKET-KEY> # 添加进度评论+/jira transition <TICKET-KEY> # 更改工单状态+/jira search <JQL> # 使用JQL搜索问题+```++## 此命令的功能++1. **获取与分析** — 获取 Jira 工单并提取需求、验收标准、测试场景和依赖项+2. **评论** — 向工单添加结构化的进度更新+3. **状态变更** — 在工作流状态间移动工单(待办 → 进行中 → 已完成)+4. **搜索** — 使用 JQL 查询查找问题++## 工作原理++### `/jira get <TICKET-KEY>`++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 <TICKET-KEY>`++1. 总结当前会话进度(已构建、已测试、已提交的内容)+2. 格式化为结构化评论+3. 发布到 Jira 工单++### `/jira transition <TICKET-KEY>`++1. 获取工单的可用状态变更+2. 向用户显示选项+3. 执行所选的状态变更++### `/jira search <JQL>`++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="[email protected]"+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.mdnew file mode 100644index 000000000..b98405625--- /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 <matched files>` |+| 具体文件名 | 暂存这些文件 | `git add <files>` |++对于自然语言输入(如"认证相关的变更"),交叉引用 `git status` 输出和 `git diff` 以识别相关文件。向用户展示你暂存了哪些文件及其原因。++```bash+git add <determined files>+```++暂存后,验证:++```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.mdnew file mode 100644index 000000000..27a675904--- /dev/null+++ b/docs/zh-CN/commands/prp-implement.md@@ -0,0 +1,394 @@+---+description: 执行带有严格验证循环的实施计划+argument-hint: <path/to/plan.md>+---++> 改编自 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 <next-phase>`diff --git a/docs/zh-CN/commands/prp-plan.md b/docs/zh-CN/commands/prp-plan.mdnew file mode 100644index 000000000..8775c7890--- /dev/null+++ b/docs/zh-CN/commands/prp-plan.md@@ -0,0 +1,506 @@+---+description: 创建全面的功能实现计划,包括代码库分析和模式提取+argument-hint: <feature description | path/to/prd.md>+---++> 改编自 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-path>` 来执行此计划+- 运行 `/plan` 进行快速对话式规划(无需产物)+- 如果范围不明确,运行 `/prp-prd` 先创建PRD+````diff --git a/docs/zh-CN/commands/prp-pr.md b/docs/zh-CN/commands/prp-pr.mdnew file mode 100644index 000000000..80752518a--- /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/<base>..HEAD --oneline+```++| 检查项 | 条件 | 失败时的操作 |+|---|---|---|+| 不在基础分支上 | 当前分支 ≠ 基础分支 | 停止:"请先切换到功能分支。" |+| 工作目录干净 | 无未提交的更改 | 警告:"存在未提交的更改。请先提交或暂存。使用 `/prp-commit` 提交。" |+| 存在领先提交 | `git log origin/<base>..HEAD` 不为空 | 停止:"`<base>` 前无提交。无需创建 PR。" |+| 无现有 PR | `gh pr list --head <branch> --json number` 为空 | 停止:"PR 已存在:#<编号>。使用 `gh pr view <number> --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/<base>..HEAD --format="%h %s" --reverse+```++分析提交以确定:++* **PR 标题**:使用带类型前缀的常规提交格式 — `feat: ...`、`fix: ...` 等。+ * 若存在多种类型,使用主导类型+ * 若为单个提交,直接使用其消息+* **变更摘要**:按类型/领域对提交进行分组++### 文件分析++```bash+git diff origin/<base>..HEAD --stat+git diff origin/<base>..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/<base>+git push -u origin HEAD+```++若变基发生冲突,停止并通知用户。++***++## 阶段 4 — 创建++### 使用模板++若在阶段 2 中找到 PR 模板,使用提交和文件分析填充每个部分。保留所有模板部分 — 若不适用,将部分留为"不适用"而非删除。++### 无模板++使用以下默认格式:++```markdown+## 摘要++<用1-2句话描述此PR的功能及原因>++## 变更内容++<bulleted list of changes grouped by area>++## 文件变更++<table or list of changed files with change type: Added/Modified/Deleted>++## 测试说明++<描述变更的测试方式,或填写"需要测试">++## 相关问题++<关联问题,使用Closes/Fixes/Relates to #N格式,或填写"无">+```++### 创建 PR++```bash+gh pr create \+ --title "<PR title>" \+ --base <base-branch> \+ --body "<PR 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 #<number>: <标题>+URL: <网址>+分支: <源分支> → <目标分支>+变更: 共<文件数>个文件,新增<添加行数>行,删除<删除行数>行++CI 检查: <状态摘要 或 "待处理" 或 "未配置">++引用的构建产物:+ - <PR 正文中链接的任何 PRP 报告/计划>++后续步骤:+ - gh pr view <编号> --web → 在浏览器中打开+ - /code-review <编号> → 审查该 PR+ - gh pr merge <编号> → 准备就绪后合并+```++***++## 边界情况++* **无 `gh` CLI**:停止并提示:"需要 GitHub CLI(`gh`)。安装地址:<https://cli.github.com/>"+* **未认证**:停止并提示:"请先运行 `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.mdnew file mode 100644index 000000000..fb1412e3f--- /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范围++{验证假设所需的最小功能集}++### 用户流程++{关键路径——到达价值的最短旅程}++---++## 技术方案++**可行性**:{高/中/低}++**架构说明**+- {关键技术决策及原因}+- {依赖项或集成点}++**技术风险**++| 风险 | 可能性 | 应对措施 |+|------|--------|----------|+| {风险} | {高/中/低} | {如何处理} |++---++## 实施阶段++<!--+ STATUS: pending | in-progress | complete+ PARALLEL: phases that can run concurrently (e.g., "with 3" or "-")+ DEPENDS: phases that must complete first (e.g., "1, 2" or "-")+ PRP: link to generated plan file once created+-->++| # | 阶段 | 描述 | 状态 | 并行 | 依赖 | 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.mdnew file mode 100644index 000000000..87761aa37--- /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.mdnew file mode 100644index 000000000..adafef45d--- /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 后推送——绝不在循环中间推送。