elias/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-05-14 02:10:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: salvage zh-CN command translations

Browse Source 
Port the current-source-safe command documentation subset from stale PR #1687.\n\nEach copied command page maps to an English source file unchanged since the stale PR base; fastapi-review remains deferred because #1687 did not include a matching zh-CN translation.
This commit is contained in:
Affaan Mustafa 2026-05-11 13:47:40 -04:00 committed by Affaan Mustafa
parent 922e058e68
commit 6556f20af7
19 changed files with 2772 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/zh-CN/commands/auto-update.md Normal file
View File

@ -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`。

49
docs/zh-CN/commands/feature-dev.md Normal file
View File

@ -0,0 +1,49 @@
---
description: 基于代码库理解和架构重点的引导式功能开发
---
一种结构化的功能开发工作流程，强调在编写新代码之前先理解现有代码。
## 阶段
### 1. 发现
* 仔细阅读功能需求
* 识别需求、约束和验收标准
* 如果需求不明确，提出澄清性问题
### 2. 代码库探索
* 使用 `code-explorer` 分析相关的现有代码
* 追踪执行路径和架构层次
* 理解集成点和约定
### 3. 澄清性问题
* 展示探索过程中的发现
* 提出有针对性的设计和边界情况问题
* 等待用户回复后再继续
### 4. 架构设计
* 使用 `code-architect` 设计功能
* 提供实现蓝图
* 等待批准后再实施
### 5. 实现
* 按照批准的设计实现功能
* 在适当的情况下优先采用 TDD
* 保持提交小而专注
### 6. 质量审查
* 使用 `code-reviewer` 审查实现
* 处理关键和重要问题
* 验证测试覆盖率
### 7. 总结
* 总结已构建的内容
* 列出后续事项或限制
* 提供测试说明

166
docs/zh-CN/commands/flutter-build.md Normal file
View File

@ -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/`

118
docs/zh-CN/commands/flutter-review.md Normal file
View File

@ -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/`

145
docs/zh-CN/commands/flutter-test.md Normal file
View File

@ -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`

109
docs/zh-CN/commands/gan-build.md Normal file
View File

@ -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`。

45
docs/zh-CN/commands/gan-design.md Normal file
View File

@ -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 的关键区别
生成器被告知："你的首要目标是视觉卓越。一个惊艳的半成品应用胜过功能齐全但丑陋的应用。推动创意飞跃——不寻常的布局、自定义动画、独特的色彩搭配。"

14
docs/zh-CN/commands/hookify-configure.md Normal file
View File

@ -0,0 +1,14 @@
---
description: 交互式启用或禁用 hookify 规则
---
交互式启用或禁用现有的 hookify 规则。
## 步骤
1. 查找所有 `.claude/hookify.*.local.md` 文件
2. 读取每条规则的当前状态
3. 展示列表，包含每条规则的当前启用/禁用状态
4. 询问需要切换哪些规则
5. 更新所选规则文件中的 `enabled:` 字段
6. 确认更改

46
docs/zh-CN/commands/hookify-help.md Normal file
View File

@ -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`，匹配文件路径
* 在部署前测试模式

21
docs/zh-CN/commands/hookify-list.md Normal file
View File

@ -0,0 +1,21 @@
---
description: 列出所有已配置的 hookify 规则
---
查找并以格式化表格显示所有 hookify 规则。
## 步骤
1. 查找所有 `.claude/hookify.*.local.md` 文件
2. 读取每个文件的前置元数据：
* `name`
* `enabled`
* `event`
* `action`
* `pattern`
3. 以表格形式显示：
| 规则 | 启用状态 | 事件 | 模式 | 文件 |
|------|---------|-------|---------|------|
4. 显示规则数量，并提醒用户 `/hookify-configure` 后续可更改状态。

50
docs/zh-CN/commands/hookify.md Normal file
View File

@ -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` 管理这些规则。

108
docs/zh-CN/commands/jira.md Normal file
View File

@ -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="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`

115
docs/zh-CN/commands/prp-commit.md Normal file
View File

@ -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` | 仅暂存未跟踪文件 |

394
docs/zh-CN/commands/prp-implement.md Normal file
View File

@ -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>`

506
docs/zh-CN/commands/prp-plan.md Normal file
View File

@ -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
````

188
docs/zh-CN/commands/prp-pr.md Normal file
View File

@ -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 规模。若变更逻辑上可分离，建议拆分。

453
docs/zh-CN/commands/prp-prd.md Normal file
View File

@ -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 上下文
## 成功标准
* **问题已验证**：问题是具体且有证据的（或标记为假设）
* **用户已定义**：主要用户是具体的，而非泛泛的
* **假设清晰**：具有可衡量结果的可测试假设
* **范围已界定**：明确的必须拥有项和明确的范围外项
* **问题已确认**：不确定性已列出，而非隐藏
* **可操作**：怀疑论者也能理解为什么这件事值得构建

37
docs/zh-CN/commands/review-pr.md Normal file
View File

@ -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 的问题：
* 严重：错误、安全、数据丢失
* 重要：缺少测试、质量问题、风格违规
* 建议：仅在明确要求时提供建议

180
docs/zh-CN/commands/santa-loop.md Normal file
View File

@ -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 后推送——绝不在循环中间推送。