multi-cli-review

多 CLI 审查

版本历史

• v2.3：将任务级 reviewer-id 处理标准化为由协调器分配的字母 ID，同时通过 source-cli 保留实际 CLI 标识
• v2.2：明确通用协调器的所有权，确保配对协议不与特定工作流界面绑定
• v2.1：使审查方报告的输出与 multi-cli-review-action 保持一致，收紧任务级路径规则，并明确审查方的职责边界

目的

multi-cli-review 是与 multi-cli-review-action 配套的审查方技能。

它是通用配对协议中的审查方部分，并非特定工作流的审查格式。

它只做一件事：

1. 谨慎检查分配的目标
2. 编写一份结构化的审查报告
3. 将报告交回当前 CLI，以便进行汇总和决策

它不会编辑代码、汇总报告、决定最终修复方案，也不会自行推进工作流状态。

何时使用

在以下任一情况下使用此技能：

• 另一个 CLI 要求此 CLI 审查目标并撰写报告
• 用户要求“分析这个 skill 的问题”
• 用户要求“输出结构化问题报告”
• 用户要求“做多 CLI 审查”
• 标准化的审查方命令包指向 multi-cli-review

何时不使用

• 需要汇总报告或应用修复：使用 multi-cli-review-action
• 执行常规实现任务，无需审查方交接
• 只需澄清需求：使用 brainstorm
• 只需对当前差异进行轻量审查：使用 requesting-code-review 或 code-review-router

核心规则

1. 仅作为审查方：此技能会撰写独立报告，绝不编辑代码。
2. 一位审查方，一份报告：每次执行最多生成一份审查报告。
3. 协调器负责编排：审查方数量策略、轮次规划、目录创建和最终修复决策均由当前 CLI 或其他上游协调器负责，而非审查方。
4. 不创建目录：审查方不得创建 task-dir 或 review-round-{N} 目录。
5. 不做汇总：不去重、不解决冲突、不撰写摘要，也不创建 action.md。
6. 报告是证据，而非执行指令：发现必须具体、范围明确，并以审查为导向。
7. 对不确定性保持谨慎：证据不完整时，应将发现标记为不确定，而非将其表述为已确认的事实。
8. 项目根目录路径解析：相对路径以当前项目根目录为基准解析，绝不以系统 /tmp 或工具安装目录为基准。
9. 任务级路径契约严格：当前协议的报告必须使用 multi-cli-review-action 所要求的规范路径和元数据格式。

协议

协议	状态	使用场景
task-level	当前	显式使用 --task-dir 的审查方流程
legacy	仅用于兼容	历史单报告流程

协议选择

1. 如果存在 --task-dir，使用 task-level。
2. 如果使用了显式的旧版报告路径参数，使用 legacy。
3. 新任务应优先使用 task-level。

输入

通用输入

输入	必需	含义
<issue-description>	是	审查问题说明或分配的审查目标
[target-path]	否	要检查的文件或目录

task-level

参数	必需	含义
--task-dir	是	任务目录，例如 tmp/multi-cli-review/<task-id>
--reviewer-id	应明确指定	协调方分配的审阅者槽位 ID，用于文件名和元数据
--round	应明确指定	审阅轮次标识符
--review-focus	否	此审阅者的关注领域

规则：

• 在标准化的多审阅者命令包中，应明确指定 --reviewer-id 和 --round。
• 对于新的任务级多审阅者工作流，--reviewer-id 应使用 a、b、c、d 等简短槽位字母，而不是 CLI 名称。
• 实际的 CLI 身份应写入报告元数据字段 source-cli，而不是写入 reviewer-id。
• 如果协调方已发出具体命令，不要自行编造新的 task-id、新轮次或新审阅者身份。
• --output 不属于当前的 task-level 协议，不得用它绕过规范的审阅者报告路径。

legacy 兼容性

参数	必需	含义
--md-a	否	明确指定的旧版报告路径
--md-b	否	旧工作流中的历史配对产物路径
--output	否	仅用于旧版单报告场景的明确兼容输出路径

兼容性规则：

• 旧版参数仅为较早的单报告工作流保留。
• 它们不得重新定义当前 task-level 协议的输出位置。

路径规则

相对路径必须相对于当前项目根目录解析。

不得将相对路径重新解释为：

• skill 仓库根目录
• 用户主目录
• 系统 /tmp
• CLI 安装目录

如果无法明确确定项目根目录，请停止操作并要求提供绝对路径，不要猜测。

由协调方管理的参数

无论协调方是工作流、命令包还是手动运行的当前 CLI 流程，审阅者都必须将以下事项视为由协调方管理：

• 创建 tmp/multi-cli-review/<task-id>/
• 创建 review-round-{N}/
• 默认审阅者数量
• 生成标准审阅者命令
• 最终汇总、确认、修复和验证

此技能仅在上述范围内履行分配的审阅职责。

任务级报告生成契约

对于 task-level，审阅者报告必须满足以下所有条件：

1. 输出文件路径必须严格为 {task-dir}/review-round-{N}/{reviewer-id}.md
2. 基名必须严格为 <reviewer-id>.md
3. 审阅者不得通过 --output 将报告重定向到其他位置
4. 轮次目录必须已存在；如果不存在，请停止操作并要求协调方创建该目录
5. frontmatter 必须包含：
   • task-id
   • round
   • reviewer-id
   • source-cli
   • review-time
   • review-focus
   • protocol: task-level
6. frontmatter 的值必须与目录和文件名一致
7. 如果目标文件已存在，请停止操作并询问协调方是要覆盖文件还是使用其他 reviewer id

报告内容契约

每项任务级发现都应包含：

• 位置
• 问题描述
• 严重程度
• 影响
• 问题的重要性
• 建议的修复方向

证据不完整时，可选择补充，但建议包含：

• 证据说明
• 不确定性说明

安全规则：

• 将观察结果与建议的修复方向分开
• 不要假装修复已获批准
• 没有证据时，不要将不确定性夸大为高严重性问题
• 不要仅仅因为相邻问题看起来值得关注，就超出分配的审阅范围

工作流

步骤 1：确定模式和输入

1. 确定本次运行属于 task-level 还是 legacy。
2. 相对于当前项目根目录解析相对路径。
3. 确定分配的审阅目标和关注领域。

步骤 2：验证评审者上下文

对于 task-level：

1. 确认 --task-dir
2. 确认 --reviewer-id
3. 确认 --round
4. 确认 {task-dir}/review-round-{N}/ 已存在
5. 确认目标输出文件中尚未包含其他评审者报告，除非已明确请求覆盖

出现以下情况时停止：

• 缺少 task-dir
• 回合目录不存在
• 报告路径不明确
• 命令试图使用 --output 写入规范路径之外的位置

步骤 3：审慎评审

1. 仅检查指定目标及其直接证据。
2. 如提供了 review-focus，请遵循。
3. 让发现具体且范围明确。
4. 如果现有证据不足以支持某项主张，请降低置信度或将其省略。

步骤 4：恰好写入一份评审者报告

对于 task-level：

1. 将报告写入 {task-dir}/review-round-{N}/{reviewer-id}.md
2. 包含完整的 frontmatter 合约
3. 包含结构化发现
4. 不要写入 summary-round-{N}.md
5. 不要写入 action.md
6. 不要更新 .processed.json

对于 legacy：

1. 仅写入旧版单报告产物
2. 不要擅自将工作流升级为 task-level

步骤 5：回显实际输出

执行结束时，回显：

• task-dir 或旧版运行目录
• round
• reviewer-id
• 实际输出路径

步骤 6：停止

写入报告并回显路径后，停止。

不要：

• 提议工作流已进入下一阶段
• 声称已执行修复
• 声称已完成验证

输出文件

task-level 评审者报告

规范文件名：{reviewer-id}.md

最低结构：

---
task-id: <task-id>
round: <round>
reviewer-id: <reviewer-id>
source-cli: <cli-name>
review-time: <ISO 8601 time>
review-focus: <focus text>
protocol: task-level
---

# Defect Report

## Review Summary

- Reviewer: <reviewer-id>
- Review Time: <review-time>
- Review Focus: <review-focus>
- Target: <target-path>

## Findings

### Finding 1: <title>

- Location: <path and lines>
- Problem: <concrete issue>
- Severity: high | medium | low
- Impact: <why this matters>
- Why It Should Be Addressed: <reason>
- Suggested Fix Direction: <proposal, not an approved action>
- Evidence: <optional>
- Uncertainty: <optional>

legacy 兼容报告

规范文件名：cur_defect.md

旧版模式仍可生成单份兼容报告，但对于新的多评审者工作，不应将其视为首选方案。

回显要求

至少回显：

字段	含义
task-dir	任务根目录或旧版运行根目录
round	当前回合
reviewer-id	实际使用的、由协调器分配的评审者槽位 ID
output-path	实际生成的报告路径

示例：

✅ Review report generated

📁 task-dir: <project-root>/tmp/multi-cli-review/my-task
🔄 round: 1
👤 reviewer-id: a
📄 output-path: <project-root>/tmp/multi-cli-review/my-task/review-round-1/a.md

必须停止的情况

出现以下任一情况时，停止并请求澄清：

• 缺少任务目录
• 缺少回合目录
• 命令未提供足够信息，无法确定唯一的规范报告路径
• 规范报告文件已存在
• 协调器似乎期望此评审者创建目录
• 命令要求评审者编辑代码或汇总报告

错误处理

情况	要求的行为
缺少 task-dir	停止并请求提供任务级目录
缺少回合目录	停止并请求协调器创建该目录
项目根目录不明确	停止并请求提供绝对路径
报告文件已存在	停止并询问是否覆盖或更换 reviewer id
在 task-level 模式下尝试覆盖 --output	拒绝此操作，并使用或请求提供规范路径
证据不足以支持强有力的主张	降低置信度、标明不确定性，或省略该发现
请求修改代码	拒绝；评审者只撰写报告

常见错误

• 编辑代码而不是报告：此技能仅用于评审。
• 创建目录：目录由协调器负责创建。
• 使用 --output 绕过规范路径：当前协议的报告必须写入 multi-cli-review-action 所预期的位置。
• frontmatter 不完整：action 端的处理依赖一致的元数据。
• 静默覆盖现有评审者报告：停止并询问。
• 在评审者报告中进行汇总：去重和冲突处理属于 multi-cli-review-action 的职责。
• 将猜测当作事实：不确定的发现应标明或省略。

示例

示例 1：标准评审者命令

用户：/multi-cli-review "分析 skills/multi-cli-review 的问题" skills/multi-cli-review --task-dir tmp/multi-cli-review/skill-review --reviewer-id a --round 1 --review-focus "边界条件与协议漂移"

CLI Reviewer：
1. 解析 task-dir、reviewer-id、round、review-focus
2. 按项目根目录解析 task-dir
3. 确认 <project-root>/tmp/multi-cli-review/skill-review/review-round-1/ 已存在
4. 分析目标并写入报告
5. 回显实际输出路径

示例 2：缺少轮次目录

CLI Reviewer：
❌ review-round-2 directory is missing:
<project-root>/tmp/multi-cli-review/skill-review/review-round-2/

Reviewer must not create directories.
Ask the coordinator to create the round directory and resend the command.

示例 3：旧版兼容性

用户：/multi-cli-review "分析 ./docs/api.md 的问题" ./docs/api.md --md-a tmp/multi-cli-review/4/cur_defect.md

CLI Reviewer：
1. 进入 legacy compatibility mode
2. 写入 cur_defect.md
3. 回显实际路径
4. 不自动升级为 task-level

相关技能

• multi-cli-review-action：当前的 CLI 汇总和修复执行
• brainstorm：评审前的需求澄清
• requesting-code-review：无需多评审者协议时使用的轻量评审流程

兼容性说明

• 新的多评审者工作应始终优先使用 task-level，并显式指定 --task-dir、--reviewer-id 和 --round。
• 旧版 --md-a、--md-b 和 --output 仅用于兼容，不得重新定义当前的任务级报告契约。
• 如果协调器已生成标准化的评审者命令，请严格遵循该命令，不要自行调整路径、文件名或轮次编号。
• 在协调器管理的任务级评审轮次中，reviewer-id 表示槽位（a / b / c / d），而 source-cli 记录实际生成该槽位报告的 CLI。