| 名称 | review-cycle |
| 描述 | 统一的多维度代码审查，带有自动化修复编排。支持基于会话（git更改）和基于模块（路径模式）的审查模式，具有7维度并行分析、迭代深度分析和自动化修复管道。触发方式：“workflow:review-cycle”、“workflow:review-session-cycle”、“workflow:review-module-cycle”、“workflow:review-cycle-fix”。 allowed-tools: spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep |
审查周期
统一的多维度代码审查编排器，具有双模式（会话/模块）文件发现、7维度并行分析、关键发现的迭代深度分析，以及可选的自动化修复管道，具有智能批处理和并行规划。
架构概述
┌──────────────────────────────────────────────────────────────────────┐
│ 审查周期编排器（SKILL.md） │
│ → 纯协调器：模式检测、阶段调度、状态跟踪 │
└───────────────────────────────┬──────────────────────────────────────┘
│
┌─────────────────────────────┼─────────────────────────────────┐
│ 审查管道（阶段1-5） │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ │ 阶段1 │→ │ 阶段2 │→ │ 阶段3 │→ │ 阶段4 │→ │ 阶段5 │
│ │发现与初始化│ │并行审查 │ │聚合分析 │ │深度分析 │ │完成审查 │
│ │ │ │ │ │ │ │（条件） │ │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
│ 会话|模块 7个代理 严重性计算 N个代理 最终化
│ ↕ 循环
└────────────────────────────────────────────────────────────────┘
│
（可选的--fix）
│
┌─────────────────────────────┼─────────────────────────────────┐
│ 修复管道（阶段6-9） │
│ │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌─────────┐
│ │ 阶段6 │→ │ 阶段7 │→ │ 阶段7.5 │→ │ 阶段8 │→ │ 阶段9 │
│ │发现与批处理│ │并行规划 │ │导出到任务JSON│ │执行编排│ │完成修复 │
│ │ │ │ │ │ │ │ │ │ │
│ └─────────┘ └─────────┘ └──────────┘ └─────────┘ └─────────┘
│ 分组+批处理 N个代理 修复计划→ M个代理 聚合+总结
└────────────────────────────────────────────────────────────────────┘
关键设计原则
- 双模式审查：基于会话（git更改）和基于模块（路径模式）共享相同的审查管道（阶段2-5），仅在文件发现（阶段1）上不同。
- 纯编排器：按顺序执行阶段，解析输出，在阶段间传递上下文。
- 渐进式阶段加载：阶段文档在执行时按需读取，而不是一次性全部读取。
- 自动继续：所有阶段在阶段间无需用户干预自动运行。
- 子代理生命周期管理：通过spawn_agent → wait → close_agent进行明确的生命周期管理。
- 角色路径加载：子代理角色通过MANDATORY FIRST STEPS中的路径引用加载。
- 可选的修复管道：阶段6-9仅由明确的
--fix标志或在阶段5后用户确认触发。 - 内容保留：所有代理提示、代码、模式从源命令中逐字保留。
使用方法
# 审查管道（阶段1-5）
review-cycle <路径模式> # 模块模式
review-cycle [会话ID] # 会话模式
review-cycle [会话ID|路径模式] [标志] # 带标志
# 修复管道（阶段6-9）
review-cycle --fix <审查目录|导出文件> # 修复模式
review-cycle --fix <审查目录> [标志] # 修复带标志
# 标志
--dimensions=维度1,维度2,... 自定义维度（默认：所有7个）
--max-iterations=N 最大深度分析迭代次数（默认：3）
--fix 在审查后或独立进入修复管道
--resume 恢复中断的修复会话
--batch-size=N 每批规划发现数（默认：5，仅修复模式）
--export-tasks 导出修复计划发现到.task/FIX-*.json（自动启用--fix）
# 示例
review-cycle src/auth/** # 模块：审查auth
review-cycle src/auth/**,src/payment/** # 模块：多个路径
review-cycle src/auth/** --dimensions=security,architecture # 模块：自定义维度
review-cycle WFS-payment-integration # 会话：特定
review-cycle # 会话：自动检测
review-cycle --fix ${projectRoot}/.workflow/active/WFS-123/.review/ # 修复：从审查目录
review-cycle --fix --resume # 修复：恢复会话
模式检测
// 输入解析逻辑（编排器责任）
function detectMode(args) {
if (args.includes('--fix')) return 'fix';
if (args.match(/\*|\.ts|\.js|\.py|src\/|lib\//)) return 'module'; // 通配符/路径模式
if (args.match(/^WFS-/) || args.trim() === '') return 'session'; // 会话ID或空
return 'session'; // 默认
}
| 输入模式 | 检测模式 | 阶段入口 |
|---|---|---|
src/auth/** |
module |
阶段1（模块分支） |
WFS-payment-integration |
session |
阶段1（会话分支） |
| (空) | session |
阶段1（会话分支，自动检测） |
--fix .review/ |
fix |
阶段6 |
--fix --resume |
fix |
阶段6（恢复） |
执行流程
输入解析：
└─ 检测模式（会话|模块|修复） → 路由到相应阶段入口
审查管道（会话或模块模式）：
阶段1：发现与初始化
└─ 参考：phases/01-discovery-initialization.md
├─ 会话模式：会话发现 → git更改文件 → 解析
├─ 模块模式：路径模式 → 通配符扩展 → 解析
└─ 通用：创建会话、输出目录、review-state.json、review-progress.json
阶段2：并行审查协调
└─ 参考：phases/02-parallel-review.md
├─ 启动7个cli-explore-agent实例（深度扫描模式）
├─ 每个产生dimensions/{维度}.json + reports/{维度}-analysis.md
├─ 生命周期：spawn_agent → 批量等待 → close_agent
└─ CLI回退链：Gemini → Qwen → Codex
阶段3：聚合分析
└─ 参考：phases/03-aggregation.md
├─ 加载维度JSON，计算严重性分布
├─ 识别交叉关注点（在3+个维度中的文件）
└─ 决策：关键 > 0 OR 高 > 5 OR 关键文件 → 阶段4
否则 → 阶段5
阶段4：迭代深度分析（条件性）
└─ 参考：phases/04-iterative-deep-dive.md
├─ 选择关键发现（每次迭代最多5个）
├─ 启动深度分析代理进行根本原因分析
├─ 重新评估严重性 → 循环回阶段3聚合
└─ 退出条件：无关键发现 OR 达到最大迭代次数
阶段5：审查完成
└─ 参考：phases/05-review-completion.md
├─ 最终化review-state.json + review-progress.json
├─ 提示用户："运行自动化修复？[Y/n]"
└─ 如果是 → 继续到阶段6
修复管道（--fix模式或在阶段5后）：
阶段6：修复发现与批处理
└─ 参考：phases/06-fix-discovery-batching.md
├─ 验证导出文件，创建修复会话
└─ 智能按文件+维度相似性分组 → 批次
阶段7：修复并行规划
└─ 参考：phases/07-fix-parallel-planning.md
├─ 启动N个cli-planning-agent实例（≤10并行）
├─ 每个输出partial-plan-{批次ID}.json
├─ 生命周期：spawn_agent → 批量等待 → close_agent
└─ 编排器聚合 → fix-plan.json
阶段7.5：导出到任务JSON（自动--fix，或显式--export-tasks）
└─ 转换fix-plan.json发现 → .task/FIX-{序列}.json
├─ 对于每个发现：
│ ├─ 发现.file → files[].path（动作："modify"）
│ ├─ 发现.severity → 优先级（critical|high|medium|low）
│ ├─ 发现.fix_description → 描述
│ ├─ 发现.dimension → 范围
│ ├─ 发现.verification → convergence.verification
│ ├─ 发现.changes[] → convergence.criteria[]
│ └─ 发现.fix_steps[] → implementation[]
├─ 输出路径：{projectRoot}/.workflow/active/WFS-{id}/.review/.task/FIX-{seq}.json
├─ 每个文件遵循task-schema.json（IDENTITY + CONVERGENCE + FILES必需）
└─ source.tool = "review-cycle", source.session_id = WFS-{id}
│
├─ 生成plan.json（plan-overview-fix-schema）在FIX任务导出后：
│ ```javascript
│ const fixTaskFiles = Glob(`${reviewDir}/.task/FIX-*.json`)
│ const taskIds = fixTaskFiles.map(f => JSON.parse(Read(f)).id).sort()
│
│ // 守卫：如果没有生成修复任务，跳过plan.json
│ if (taskIds.length === 0) {
│ console.warn('未生成修复任务；跳过plan.json')
│ } else {
│
│ const planOverview = {
│ summary: `修复计划来自审查周期：${reviewSummary}`,
│ approach: "审查驱动的修复管道",
│ task_ids: taskIds,
│ task_count: taskIds.length,
│ complexity: taskIds.length > 5 ? "高" : taskIds.length > 2 ? "中" : "低",
│ fix_context: {
│ root_cause: "多个审查发现",
│ strategy: "全面修复",
│ severity: aggregatedFindings.maxSeverity || "中", // 来自最大发现严重性
│ risk_level: aggregatedFindings.overallRisk || "中" // 来自组合风险评估
│ },
│ test_strategy: {
│ scope: "单元",
│ specific_tests: [],
│ manual_verification: ["验证所有审查发现已处理"]
│ },
│ _metadata: {
│ timestamp: getUtc8ISOString(),
│ source: "review-cycle-agent",
│ planning_mode: "基于代理",
│ plan_type: "修复",
│ schema_version: "2.0"
│ }
│ }
│ Write(`${reviewDir}/plan.json`, JSON.stringify(planOverview, null, 2))
│
│ } // 结束守卫
│ ```
└─ 输出路径：{reviewDir}/plan.json
阶段8：修复执行
└─ 参考：phases/08-fix-execution.md
├─ 基于阶段的执行按聚合时间线
├─ 每组：分析 → 修复 → 测试 → 提交/回滚
├─ 生命周期：spawn_agent → wait → close_agent每组
└─ 需要100%测试通过率
阶段9：修复完成
└─ 参考：phases/09-fix-completion.md
├─ 聚合结果 → fix-summary.md
└─ 可选：如果所有修复成功，完成工作流会话
完成：审查报告 + 可选的修复结果
阶段参考文档（在执行时按需读取）：
| 阶段 | 文档 | 加载时机 | 源 |
|---|---|---|---|
| 1 | phases/01-discovery-initialization.md | 审查/修复开始 | review-session-cycle + review-module-cycle 阶段1（融合） |
| 2 | phases/02-parallel-review.md | 阶段1完成 | 共享自两个审查命令阶段2 |
| 3 | phases/03-aggregation.md | 阶段2完成 | 共享自两个审查命令阶段3 |
| 4 | phases/04-iterative-deep-dive.md | 聚合触发迭代 | 共享自两个审查命令阶段4 |
| 5 | phases/05-review-completion.md | 无需更多迭代 | 共享自两个审查命令阶段5 |
| 6 | phases/06-fix-discovery-batching.md | 修复模式入口 | review-cycle-fix 阶段1 + 1.5 |
| 7 | phases/07-fix-parallel-planning.md | 阶段6完成 | review-cycle-fix 阶段2 |
| 7.5 | (SKILL.md内联) | 阶段7完成 | 导出修复计划发现到.task/FIX-*.json |
| 8 | phases/08-fix-execution.md | 阶段7.5完成 | review-cycle-fix 阶段3 |
| 9 | phases/09-fix-completion.md | 阶段8完成 | review-cycle-fix 阶段4 + 5 |
核心规则
- 立即开始：第一个动作是进度跟踪初始化，第二个动作是阶段1执行。
- 模式检测优先：在阶段1前解析输入以确定会话/模块/修复模式。
- 解析每个输出：从每个阶段提取所需数据用于下一个阶段。
- 自动继续：检查进度状态以自动执行下一个待处理阶段。
- 渐进式阶段加载：仅当阶段即将执行时读取阶段文档。
- 不要停止：连续多阶段工作流，直到所有适用阶段完成。
- 条件性阶段4：仅当聚合触发迭代时执行（关键 > 0 OR 高 > 5 OR 关键文件）。
- 修复管道可选：阶段6-9仅由显式–fix标志或用户确认执行。
- 明确生命周期：在wait完成后始终close_agent以释放资源。
数据流
用户输入（路径模式 | 会话ID | --fix 导出文件）
↓
[模式检测：会话 | 模块 | 修复]
↓
阶段1：发现与初始化
↓ 输出：sessionId, reviewId, resolvedFiles, reviewMode, outputDir
↓ review-state.json, review-progress.json
阶段2：并行审查协调
↓ 输出：dimensions/*.json, reports/*-analysis.md
阶段3：聚合分析
↓ 输出：severityDistribution, criticalFiles, deepDiveFindings
↓ 决策：迭代？ → 阶段4 : 阶段5
阶段4：迭代深度分析（条件性，与阶段3循环）
↓ 输出：iterations/*.json, reports/deep-dive-*.md
↓ 循环：重新聚合 → 检查标准 → 迭代或退出
阶段5：审查完成
↓ 输出：最终 review-state.json, review-progress.json
↓ 决策：修复？ → 阶段6 : 结束
阶段6：修复发现与批处理
↓ 输出：发现批次（内存中）
阶段7：修复并行规划
↓ 输出：partial-plan-*.json → fix-plan.json（聚合）
阶段7.5：导出到任务JSON
↓ 输出：.task/FIX-{序列}.json（每个发现，遵循task-schema.json）
阶段8：修复执行
↓ 输出：fix-progress-*.json, git提交
阶段9：修复完成
↓ 输出：fix-summary.md, fix-history.json
子代理API参考
spawn_agent
创建新子代理并分配任务。
const agentId = spawn_agent({
message: `
## 任务分配
### 强制第一步（代理执行）
1. **读取角色定义**：~/.codex/agents/{代理类型}.md（必须先读）
2. 读取：${projectRoot}/.workflow/project-tech.json
3. 读取：${projectRoot}/.workflow/project-guidelines.json
---
## 任务上下文
${taskContext}
## 交付物
${deliverables}
`
})
wait
从子代理获取结果（唯一检索结果的方式）。
const result = wait({
ids: [agentId],
timeout_ms: 600000 // 10分钟
})
if (result.timed_out) {
// 处理超时 - 可以继续等待或send_input以提示完成
}
// 检查完成状态
if (result.status[agentId].completed) {
const output = result.status[agentId].completed;
}
send_input
与活动子代理继续交互（用于澄清或后续）。
send_input({
id: agentId,
message: `
## 澄清答案
${answers}
## 下一步
继续分析生成。
`
})
close_agent
清理子代理资源（不可逆）。
close_agent({ id: agentId })
进度跟踪模式
审查管道初始化：
阶段1：发现与初始化 → 待处理
阶段2：并行审查（7维度） → 待处理
阶段3：聚合分析 → 待处理
阶段4：深度分析（条件性） → 待处理
阶段5：审查完成 → 待处理
在阶段2期间（每个维度的子任务）：
→ 安全审查 → 进行中 / 完成
→ 架构审查 → 进行中 / 完成
→ 质量审查 → 进行中 / 完成
... 其他维度
修复管道（如果在阶段5后触发）：
阶段6：修复发现与批处理 → 待处理
阶段7：并行规划 → 待处理
阶段7.5：导出到任务JSON → 待处理
阶段8：执行 → 待处理
阶段9：修复完成 → 待处理
错误处理
审查管道错误
| 阶段 | 错误 | 阻塞？ | 行动 |
|---|---|---|---|
| 阶段1 | 未找到会话（会话模式） | 是 | 错误并退出 |
| 阶段1 | 无更改文件（会话模式） | 是 | 错误并退出 |
| 阶段1 | 无效路径模式（模块模式） | 是 | 错误并退出 |
| 阶段1 | 无匹配文件（模块模式） | 是 | 错误并退出 |
| 阶段2 | 单维度失败 | 否 | 记录警告，继续其他维度 |
| 阶段2 | 所有维度失败 | 是 | 错误并退出 |
| 阶段3 | 缺少维度JSON | 否 | 在聚合中跳过，记录警告 |
| 阶段4 | 深度分析代理失败 | 否 | 跳过发现，继续其他 |
| 阶段4 | 达到最大迭代次数 | 否 | 生成部分报告 |
修复管道错误
| 阶段 | 错误 | 阻塞？ | 行动 |
|---|---|---|---|
| 阶段6 | 无效导出文件 | 是 | 中止并错误 |
| 阶段6 | 空批次 | 否 | 警告并跳过空 |
| 阶段7 | 规划代理超时 | 否 | 标记批次失败，继续其他 |
| 阶段7 | 所有代理失败 | 是 | 中止修复会话 |
| 阶段8 | 修复后测试失败 | 否 | 回滚，重试至最大迭代 |
| 阶段8 | Git操作失败 | 是 | 中止，保留状态 |
| 阶段9 | 聚合错误 | 否 | 生成部分总结 |
CLI回退链
Gemini → Qwen → Codex → 降级模式
回退触发条件：HTTP 429/5xx、连接超时、无效JSON输出、低置信度 < 0.4、分析太简短（< 100字）
输出文件结构
{projectRoot}/.workflow/active/WFS-{会话-id}/.review/
├── review-state.json # 编排器状态机
├── review-progress.json # 实时进度
├── dimensions/ # 每维度结果（阶段2）
│ ├── security.json
│ ├── architecture.json
│ ├── quality.json
│ ├── action-items.json
│ ├── performance.json
│ ├── maintainability.json
│ └── best-practices.json
├── iterations/ # 深度分析结果（阶段4）
│ ├── iteration-1-finding-{uuid}.json
│ └── iteration-2-finding-{uuid}.json
├── reports/ # 可读报告
│ ├── security-analysis.md
│ ├── security-cli-output.txt
│ ├── deep-dive-1-{uuid}.md
│ └── ...
├── .task/ # 任务JSON导出（阶段7.5）
│ ├── FIX-001.json # 每发现任务（task-schema.json）
│ ├── FIX-002.json
│ └── ...
├── plan.json # 计划概览（plan-overview-fix-schema，阶段7.5）
└── fixes/{修复会话-id}/ # 修复结果（阶段6-9）
├── partial-plan-*.json
├── fix-plan.json
├── fix-progress-*.json
├── fix-summary.md
├── active-fix-session.json
└── fix-history.json
相关命令
查看进度
ccw view
工作流管道
# 步骤1：审查（此技能）
review-cycle src/auth/**
# 步骤2：修复（继续或独立）
review-cycle --fix ${projectRoot}/.workflow/active/WFS-{会话-id}/.review/