multi-cli-review-action

Multi-CLI Review Action

版本历史

• v2.4：将配对接收措辞调整为由协调者分配基于字母的 reviewer-id 槽位，并将记录在 source-cli 中的 CLI 身份单独列出
• v2.3：将此技能定位为与工作流无关的操作侧配对契约，并将审查者数量默认值从核心契约中移出
• v2.2：增加明确的「不得引入新问题」采纳门槛，并围绕不会导致回归的修复统一工作流措辞
• v2.1：收紧报告接收规则、安全门槛，以及与共享配对契约的技能规范对齐

用途

multi-cli-review-action 是与 multi-cli-review 配对的操作侧技能。

当前 CLI 使用它来处理由配对技能生成的审查报告。它有意设计为与工作流无关：任何工作流、命令包或人工协调者都可以使用，只要审查报告符合配对契约。

它只负责安全地完成一项工作：

1. 收集审查报告
2. 对发现的问题去重并分类
3. 根据本地代码和项目规则重新检查每个候选项
4. 在修改前征求确认
5. 只应用已确认且符合范围的修复
6. 记录决策和验证结果

何时使用

符合以下任一情况时，使用此技能：

• 其他 CLI 实例已编写一份或多份 multi-cli-review 报告
• 用户要求「汇总这些审查报告」
• 用户要求「处理 multi-cli-review 输出」
• 用户要求「按 reviewer 建议执行修复」
• 当前 CLI 必须先协调多位审查者的意见，再修改文件

何时不使用

• 你只需要生成审查发现，而不需要应用修复：使用 multi-cli-review
• 你正在执行普通实现任务，没有多审查者交接
• 报告仍是未经确认的假设，且用户尚未同意修复计划

核心规则

1. 只由一方修复：审查者 CLI 只生成报告；此技能绝不将编辑工作委派回审查者。
2. 报告是证据，不是真相：采纳任何发现前，都必须根据本地代码库、任务范围和项目规则重新检查。
3. 不得擅自修改：完成摘要和决策后，当前 CLI 必须先获得用户确认，才能实际修改文件。
4. 不得扩大范围：只修复属于当前任务的问题；不得顺带进行重构、新增功能或大范围清理。
5. 不得自动解决冲突：互斥或高风险建议需要人工判断。
6. 由协调者负责编排：审查者数量默认值、轮次规划和审查者命令打包由上游协调者、工作流或命令包负责；此技能只处理最终生成的报告集。
7. 修复不得引入回归：如果当前 CLI 无法说明某项修复为何不太可能引入新缺陷、回归或比原问题更广泛的风险，就不得采纳。
8. 必须进行验证：修改后，运行相关验证命令，再声称任务已完成。
9. 按项目根目录解析路径：相对路径以当前项目根目录为基准解析，绝不以系统 /tmp 或工具安装目录为基准。

协议

协议	状态	使用场景
action-v2	当前	显式指定 --task-dir 的任务级多审查者工作流
action-v1	仅用于兼容	旧版单报告工作流

协议选择

1. 如果存在 --task-dir，使用 action-v2。
2. 如果提供了单个旧版报告路径，使用 action-v1。
3. 新任务应优先使用 action-v2。

输入

action-v2

参数	必需	含义
--task-dir	是	任务目录，例如 tmp/multi-cli-review/<task-id>
--round	否	要处理的评审轮次；默认为最新的可用轮次
--force	否	重新处理已列入 .processed.json 的报告
--dry-run	否	仅生成决策；不编辑文件，也不将报告标记为已处理

action-v1 兼容模式

参数	必需	含义
<report-path>	是	旧版 cur_defect.md 路径或等效的单份报告
<plan-path>	否	可选的现有优化／操作草案

路径规则

相对路径必须以当前项目根目录为基准解析。

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

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

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

报告接收规范

对于 action-v2，仅处理满足以下所有条件的文件：

1. 文件位于 {task-dir}/review-round-{N}/ 下
2. 文件名（不含扩展名）恰好为 <reviewer-id>.md
3. Frontmatter 包含：
   • task-id
   • round
   • reviewer-id
   • source-cli
   • protocol: task-level
4. Frontmatter 值与目录和文件名相符
5. 文件不属于以下情况：
   • summary-*.md
   • action.md
   • 临时笔记、草稿文档或人工决策备忘录

如果文件含糊、格式错误或不符合规范，请停止并要求清理，不要贸然处理。

报告集规则

• 本技能会处理所选轮次中存在的有效 multi-cli-review 报告；它不规定默认应启动多少位评审者。
• 有效报告数量为 0 时，视为错误。
• 如果协调器、工作流或命令包定义了评审者数量的默认值或上限，应将其视为上游策略，不要在此重新定义。
• 在当前的任务级轮次中，reviewer-id 应解读为协调器分配的评审者槽位 ID（a / b / c / d），而 source-cli 则标识实际使用的评审 CLI。

决策状态

每项候选发现必须且只能归入以下一种状态：

• adopted：已根据代码／规范／任务边界确认，并获准执行
• ignored：因具体原因被驳回
• manual-decision：存在冲突、歧义或风险，需要人工输入
• blocked：无法继续执行或验证

工作流

第 1 步：确定模式和输入

1. 确定这是 action-v2 还是旧版兼容模式。
2. 以当前项目根目录为基准解析所有相对路径。
3. 如果存在 .processed.json，则加载它。

第 2 步：收集候选报告

对于 action-v2：

1. 仅读取目标 review-round-{N} 目录。
2. 按照报告接收规范筛选文件。
3. 拒绝格式错误或不匹配的文件。
4. 除非设置了 --force，否则跳过先前已处理的报告。

停止条件：

• 没有有效报告文件
• 所有有效报告均已处理，且未设置 --force

第 3 步：将报告转换为候选发现

1. 根据位置和含义合并发现，而不仅仅依据文件名。
2. 保留每项合并后发现的所有来源评审者。
3. 保留彼此冲突的修复方向，不要将其合并抹平。

第 4 步：在本地重新检查每项候选发现

在将任何发现标记为 adopted 之前，当前 CLI 必须验证：

1. 当前代码中仍存在该问题
2. 该问题属于当前任务边界
3. 提议的修复不会与项目规则或现有抽象相矛盾
4. 提议的修复所需代价小于其所能避免的损害
5. 计划的更改不太可能在相关行为中引入新 Bug、回归或更高成本的副作用

如果任何一项检查未通过，请将该发现标记为 ignored 或 manual-decision；不要自动采纳。

第 5 步：做出决定

使用以下决策策略：

• adopted：具体、在范围内、已在本地验证且可安全更改
• ignored：过时、重复、不正确、价值不足或已修复
• manual-decision：建议相互冲突、所有权不明确、副作用风险较高、边界问题尚未解决，或没有明确且低回归风险的修复方案

每个未采纳的项目都必须附上足够具体的理由，以避免下一轮再次对同一报告重新讨论。

第 6 步：先编写摘要

在编辑任何文件之前，先编写 summary-round-{N}.md。

摘要必须记录：

• 已审阅的文件
• 去重前后的发现总数
• 冲突
• 完整的决策列表
• 忽略项目的理由
• 仍需用户输入的 manual-decision 项目

第 7 步：编辑前请求确认

摘要完成后，向用户说明修复计划并等待确认。

出现以下情况时，不要编辑文件：

• 用户尚未确认执行
• 任何 manual-decision 项目阻碍安全推进
• 剩余计划会扩大范围
• 当前 CLI 无法证明计划中的修复不会造成新问题或回归

第 8 步：只执行已确认的修复

在普通模式下：

1. 只为 adopted 项目修改文件
2. 将更改限制在已确认的范围内
3. 在 action.md 中记录更改内容及原因

在 --dry-run 模式下：

1. 不修改源文件
2. 不将报告标记为已处理
3. 只写入明确标注为预览的决策产物

第 9 步：完成前进行验证

编辑后，运行能够证明修复没有引入新问题的最小命令集：

• 相关时运行 lint 或格式检查
• 相关时运行类型检查
• 运行测试或针对性回归命令（如果相关）

只记录实际结果：pass、fail 或 not run。

第 10 步：完成状态更新

1. 更新 action.md
2. 仅在非 dry-run 执行中，对实际处理的报告更新 .processed.json
3. 保留被阻止的项目或待人工处理的项目，供下一步人工决策

输出文件

summary-round-{N}.md

最低内容要求：

• 任务 ID 和轮次
• 审阅来源列表
• 去重后的发现表
• 冲突表
• 决策摘要
• 忽略项目的理由
• 待处理的人工决策

action.md

最低内容要求：

• 执行模式：normal 或 dry-run
• 实际应用的已采纳更改
• 忽略的项目及理由
• 被阻止的项目或待人工决策的项目
• 验证命令及结果

.processed.json

仅将其用作内部处理状态。

规则：

• 不要在 --dry-run 期间更新它
• 不要将格式错误或跳过的报告标记为已处理
• 不要用它代替 action.md

冲突处理

审阅者对以下任一事项意见不一致时，将该发现视为存在冲突：

• 是否确实需要更改
• 要更改的文件或位置
• 实现方向
• 风险或严重性（若因此改变建议采取的行动）

冲突处理策略：

1. 保留所有备选方案，确保其清晰可见
2. 不要自动选择
3. 向用户明确指出具体冲突

示例提示：

⚠️ 需要人工介入

冲突问题：src/c.py:30
- reviewer-a：重构整个函数
- reviewer-b：仅修正返回值

请选择：
1. 采纳 reviewer-a
2. 采纳 reviewer-b
3. 自定义方案
4. 忽略该问题

必须停止的情况

出现以下任一情况时，停止并请求人工输入：

• 建议之间的冲突仍未解决
• 某项发现超出任务范围
• 建议的修复会违反项目惯例或安全预期
• 无法将建议的修复缩减为有充分理由支撑、低回归风险的更改
• 验证失败
• 报告集格式错误或不完整
• 已达到约定轮数上限，但仍有未解决的项目

错误处理

情况	所需行为
任务目录缺失	停止并要求提供有效路径
没有有效报告	停止并报告本轮为空
所有报告均已处理	停止，除非设置了 --force
报告元数据格式错误	拒绝该报告并要求清理
执行失败	将条目标记为 blocked，记录原因，仅在安全时继续
验证失败	如实记录失败，不得声称修复已完成

常见错误

• 将审查者的输出视为事实：采纳前务必在本地重新检查。
• 处理轮次目录中的所有 .md 文件：只接受符合报告约定的文件。
• 在此技能中重新定义审查者默认值：默认数量由上游协调器或命令界面决定。
• 超出范围进行修复：不要夹带重构或相关功能工作。
• 解决一个问题却引发另一个问题：如果计划中的修复存在不明确的回归或副作用风险，请停止并将其移至 manual-decision，不要强行采纳。
• 跳过确认：先总结，再确认，最后编辑。
• 跳过验证：未经验证的文件改动可能在解决旧问题时引发新问题。

示例

示例 1：当前协议

用户：/multi-cli-review-action --task-dir tmp/multi-cli-review/skill-review --round 1

CLI：
1. 读取 round-1 下已有的 reviewer 报告
2. 校验 frontmatter 与文件名一致
3. 合并并去重
4. 对每个候选问题重新核对本地代码和任务边界
5. 排除会明显引入新问题或回归的修复方案
6. 输出 summary-round-1.md
7. 等待用户确认
8. 执行已确认修复
9. 运行验证命令
10. 写入 action.md 和 .processed.json

示例 2：试运行

用户：/multi-cli-review-action --task-dir tmp/multi-cli-review/skill-review --round 2 --dry-run

CLI：
1. 读取 round-2 报告
2. 输出决策和冲突
3. 生成预览版 summary / action
4. 不改源码
5. 不更新 .processed.json

相关技能

• multi-cli-review：生成审查者一侧的报告
• verification-before-completion：变更后的验证规范
• brainstorm：在接受高风险修复前明确边界

兼容性说明

• 单报告的旧版用法仍可进入 action-v1，但必须遵循相同的安全关卡：在本地重新检查、编辑前先询问，并在之后验证。
• 新的任务级用法应始终优先使用带有显式 --task-dir 的 action-v2。