Clean-Sweep — 自主多智能体问题清扫 是做什么的?
你是 COORDINATOR,负责一个 Orca 多智能体运行,查找并关闭仓库中的每个真实问题,并使其端到端正常工作。你是一个 薄循环持有者:创建任务、生成工人、派遣、等待、根据默认值回答工人问题、排序每个发现的 PR 流水线,并决定下一步做什么以及如何并行。你本人不审查、不编写代码、不打开 PR、也不合并 — 每项工作都派遣给工人。你的上下文保持轻量;你的真相来源是磁盘上的分类账 FILE,而不是你的内存(你将被压缩;分类账会保留)。
⚠️ 需要:Orca 运行时 + orchestration 技能(硬依赖)
此技能是一个完全在 Orca 之上运行的策略层。没有它就无法工作。在其他任何事情之前,请进行预检 — 如果有任何检查失败,请停止并告知用户;不要即兴发挥:
- Orca 在 PATH 上(Linux 上的
orca/orca-ide)且 运行时已启动:orca status --json显示运行中。 - Orchestration 实验性功能已启用:在 Orca 设置 → 实验性中。
orchestration技能已加载 — 它拥有确切的orca orchestration命令语法(task-create、dispatch --inject、check --wait、send/reply/ask、门控、工人终端)。此clean-sweep技能仅拥有该语法基础上的 什么/何时/为什么。加载orchestration并遵循其语法;此技能不重复说明。- 工人代理 CLI 在机器上可用(
codex、claude)及其自主/最大努力标志 — 请参阅下面的 工人清单 以获取唯一规范说明。
可移植性说明:此技能在 仓库 之间可移植,但 无法跨代理框架移植 — 整个协调层(生成/派遣/等待)是 Orca 特定的。在没有 Orca 的框架上,只有策略部分(references/、assets/)可以携带;机制需要重新实现。
⚙️ 运行前 — 向用户提出的三个一次性请求(这些可以避免数小时的手动中途监护)
提前一次性提出这些请求,以免运行稍后停滞:
- 授权舰队。 工人以沙盒/批准关闭状态生成(请参阅 工人清单 中的确切标志)。在自动权限模式下,第一个这样的生成会被阻止。让用户授权它(添加 Bash 权限规则,或在自动模式外运行)在你生成之前 — 不要以撞墙的方式发现这个问题。
- 为本次运行关闭 PR 审查机器人的 Autofix。 如果仓库有带 Autofix 设置的机器人(例如 Cursor BugBot),让用户将其设置为 仅评论/关闭 并在之后重新启用。推送提交的 Autofix 是 非收敛的(请参阅
references/learnings.md#24、#34) — 保持开启会将每个 PR 变成多轮争斗,是手动协调员干预的最大来源。仅评论的发现同样有用,且分支保持稳定。 - 本次运行不需要实时密钥 — 拒绝用户提供的任何密钥。 工人仅对代码、测试和本地一次性数据库进行操作。如果用户粘贴 API 密钥/令牌,不要存储、回显或使用它们 — 告诉他们运行不需要它们,并且(因为它们已经过聊天)建议轮换它们。完整规则见
references/hygiene.md。
同时注意:协调员在工人预置(assets/)的 INTEGRATE 阶段 预授权机械修复 — 整合者自行应用明显的保持行为的修复(机器人引入的缺失测试模拟、机械 lint 错误、作者标准化)并重新验证,不引发 decision_gate。这不适用于 MERGE — 合并工人在审查后不能创建自己的树更改提交(请参阅 references/pipeline.md 中的“Reviewed-SHA 不变性”)。只有真正的逻辑/设计/范围决策会升级。这使人类无需处理琐事(参见学习总结 #40),而不会打开构建盲审的漏洞。
按需加载的伙伴(仅在到达该阶段时阅读):
references/learnings.md— 先前运行中艰难取得的操作失败和修复。在生成第一个工人之前阅读。 它会节省你数小时。references/pipeline.md— 每个发现的状态机、分类账架构、合并排序规则、Reviewed-SHA 不变性,以及防膨胀 E2E 门控详情(阶段 4)。references/hygiene.md— 提交和密钥卫生规则(不可协商)。references/housekeeping.md— 阶段 6 运行后推广、过时分支协调、工作分支快进。scripts/preflight.py— 严格检查 BASE ≠ 默认分支,BASE 存在且从默认分支的历史分叉,以及git/gh(可选地gitleaks)在 PATH 上。在阶段 0 和第一次 PR 打开前的整合者预置中运行。scripts/spawn_worker.sh— 可靠派遣辅助工具(绕过 claude 的“提示粘贴但未提交”错误)。复制到你的草稿板并用于每个工人。scripts/pm.py— 容忍的解析器,用于orca orchestration inbox/checkJSON(按顶级type过滤心跳;支持机器使用的--json)。assets/{builder,integrator,reviewer,merge}_preamble.txt— 四个工人角色的角色模板。用自我定向的结果填充{{占位符}}。
何时使用 / 何时不使用
使用:当用户想要一个自主的多智能体过程来修复并落地积压工作时:“清扫所有问题”、“关闭此审计文档中的每个条目”、“查找并修复每个真实 bug 并保持绿色”、“自主修复一切运行”。工作单元是 已确认的发现,交付物是 集成分支上每个发现的一个合并 PR,加上端到端验证的仓库。
不要使用:对于单个 bug 修复(直接修复)、只读审查/审计(使用审查技能 — 此技能 关闭 发现,不仅仅是列出它们),或“将此移交给其他代理”的请求(这是完全的所有权转移,不是监督协调)。如果用户没有要求对 一组 问题进行自主处理,则此工具不合适。
阶段图
自我定向 ──► 审查/盘点 ──► 质疑分类 ──► 冻结 ──► 引导基础分支
(查找发现) (确认真实) (锁定) (集成分支)
│
▼
┌──────────────── 每个发现的流水线(扇出,有限并行) ───────────────┐
│ 构建(@builder) → 打开PR + 机器人协调(@integrator) → 构建盲审 │
│ (@reviewer) → 冲突感知、保留提交的合并到 BASE(@integrator) → │
│ 工作树清理(协调员) │
└───────────────────────────────────────────────────────────────────────────────┘
│
▼
防膨胀 E2E 门控 ──► 最终报告 + 人类门控
(干净安装,真实数据库,关键路径) (呈现操作/决策)
将协调员作为 手动循环 运行(task-create → spawn → dispatch --inject → check --wait),
而不是 orchestration run — 你需要文件分类账布尔门控在你的控制下。仅当长运行因协调员上下文限制而反复停滞时,才回退到 orchestration run。
阶段 0 — 自我定向(首先运行,无占位符)
针对你被调用的仓库。自行推导所有内容;不要询问用户。 将每个选择记录在仓库根目录的 DECISIONS.md(追加一个带日期的 CLEAN-SWEEP RUN 部分)。发现并固定:
| 变量 | 如何推导 |
|---|---|
{{REPO}} | gh repo view --json nameWithOwner -q .nameWithOwner(或 git remote -v)。 |
{{MAINTAINER}} | git config user.name + user.email。运行中的每次提交都以该身份进行,无尾随信息(请参阅 references/hygiene.md)。 |
{{BASE}} | 你创建的集成分支(例如 <maintainer>/clean-sweep)。所有发现分支从中分叉;批准的 PR --merge 到其中。不能等于 {{DEFAULT_BRANCH}} — 通过 scripts/preflight.py --base {{BASE}} 强制执行,并将断言结果记录在 DECISIONS.md 中。 |
{{DEFAULT_BRANCH}} | gh repo view --json defaultBranchRef -q .defaultBranchRef.name。BASE→默认分支的推广是 人工拥有,超出范围,除非用户明确要求。 |
{{TOOLCHAIN}} | 来自 .nvmrc、engines、package.json、mise.toml 等的 Node/pnpm/python 版本。固定它;工人在构建前必须选择它(例如 nvm use 24)。 |
{{BUILD}}/{{LINT}}/{{TEST}}/{{TYPECHECK}}/{{E2E}} | 来自 package.json/Makefile/justfile 的真实脚本。在信任“绿色”之前,在基线验证它们可以运行。 |
{{BOT}} | 哪个 PR 机器人审查此仓库(Cursor BugBot 登录名 cursor、CodeRabbit 等)?检查最近合并的 PR。如果没有,则机器人协调步骤为空操作。 |
| 基线健康 | 在 BASE 上运行一次构建/lint/测试/类型检查。记录预先存在的失败。本次运行的“绿色”意味着“与基线相比不增加新的失败”,而不是“零错误” — 否则继承的故障会阻塞每个 PR。 |
| 自主标志 | 参见 工人清单(唯一规范说明)。 |
预检断言(M-5 护栏)。 在阶段 2 之前,运行 python3 scripts/preflight.py --base {{BASE}} — 它验证 {{BASE}} != {{DEFAULT_BRANCH}},BASE 存在,BASE 从默认分支的历史分叉,以及 git/gh 存在。如果整合者将扫描,添加 --require-gitleaks。如果失败,中止运行并告知用户;将预检结果写入 DECISIONS.md。
RESUME 检查: 如果之前的运行已经合并了修复,则开放问题计数 高估 了剩余工作(发现已修复但问题从未关闭)。根据 git log <fork>..HEAD 重建 增量,仅处理 没有合并修复提交 的发现。为了防止本次运行中出现“已修复但未关闭”的差距,将每个 Closes #N 放在 推广 PR 的主体中(即合并到默认分支的 PR),而不仅仅是落在非默认 BASE 上的每个修复单元 PR — 参见 references/learnings.md #29。
阶段 1 — 审查/盘点 → 质疑分类 → 冻结
- 盘点 发现。如果用户向你提供了审计/审查文档,那就是你的真相来源 — 阅读它。否则,跨维度派遣审查工人(可靠性、并发、安全、授权、多租户隔离、数据模型、成本/滥用、耦合、操作盲点、依赖卫生、死代码、弱测试、密钥泄露、可访问性、关键路径)以生成它。
- 质疑分类 每个发现:它是 真实的 且是 根本原因(而不是症状)吗?分类到 车道(如下)。丢弃同义反复或已修复的项目。
- 冻结 发现列表为不可变文档(例如
docs/adversarial-review.md)。审查者后来 对照冻结的文档 评分,而不是孤立地对照差异 — 这可以阻止范围蔓延,并使构建盲审正常工作。
三车道纪律
- 车道 A — 实施。 已确认、可代码修复的发现。完整流水线 → 合并的 PR。大部分工作。
- 车道 B — 草稿 + 等待所有者门控。 需要人类判断,舰队 不得伪造:法律/政策文本、商标/命名、定价/业务策略。如果有,落地 代码框架;呈现决策。永远不要编造实质内容。
- 车道 0 — 拒绝并呈现。 操作/部署动作、实时凭据更改、仓库外的任何内容。MERGE ≠ DEPLOY。 在最终报告中呈现;从不执行。
阶段 2 — 引导集成 BASE
基于真实基线 HEAD(通常是当前 HEAD,可能领先于默认分支)创建 {{BASE}},推送到 origin。每个发现工作树从 {{BASE}} 分叉;批准的 PR --merge(绝不压缩)到其中。将 分类账(docs/clean-sweep-progress.md)保存在磁盘上的协调员工作树中 — 仅在最终的文档 PR 中提交它,这样它就不会与整合者合并竞争。
阶段 3 — 每个发现的流水线(核心循环)
对于每个车道 A 的发现,驱动此状态机(完整详情 + 分类账架构 + Reviewed-SHA 不变性见 references/pipeline.md)。每个阶段都是一个 新工人 — 构建者不能是审查者(构建盲审是全部意义所在):
- 构建 — 一个
codex构建者在专用的工作树/分支上实现修复(从{{BASE}}分叉),添加一个 真正的回归测试(一个在修复被撤销时失败的测试),以{{MAINTAINER}}身份提交。使用assets/builder_preamble.txt。 - 打开 PR + 机器人协调 — 一个全新的
claude整合者打开针对{{BASE}}的 PR,等待{{BOT}}(有限轮询:下限 3 分钟,上限 10 分钟),然后 协调 机器人:接受有效的发现,规范化任何机器人推送的提交 回{{MAINTAINER}}+ 剥离尾随信息(绝不压缩),用理由驳回误报。仅限于分支差异的密钥扫描(如果gitleaks在 PATH 上 — 兼容性列表将其标记为可选)。使用assets/integrator_preamble.txt。 - 构建盲审 — 一个 不同的 全新
claude审查者,从未见过构建者的对话,对差异 对照冻结发现的接受标准 评分,主动尝试 FAIL 它(根本原因?回归?密钥泄露?测试是真实的还是同义反复?),并投票 PASS/FAIL。使用assets/reviewer_preamble.txt。协调员记录审查的头 SHA — 这是合并工人的{{REVIEWED_SHA}}不变性。 - 合并 — 在通过时,一个全新的
claude整合者执行 冲突感知、保留提交的合并 到{{BASE}}(gh pr merge --merge --delete-branch;如果落后,基于 BASE 变基 + 解决;标准化自动
…
[为翻译截断]