Communitygithub.com

Clean-Sweep — 自主多智能体问题清扫

公共智能体技能,基于 agentskills.io 规范构建 — 从 terminal-poster(5-集群可复用信息图系统)开始。

Clean-Sweep — 自主多智能体问题清扫 是什么?

Clean-Sweep 是一个自主的多智能体技能,专为在仓库中查找、确认并合并每个真实问题的修复而设计。它作为 Orca 运行时之上的策略层运行,完全依赖 Orca 的协调能力来生成工人、分配任务和管理状态机。该技能通过精确的、基于文件的分类账跟踪进度,确保即使在协调器上下文丢失后也能恢复。它适用于需要全面问题清扫的场景,例如“清扫所有问题”或“查找并修复每个真实 bug 并保持绿色”,但不适用于单次修复或只读审查。

兼容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add ravidsrk/agent-skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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/)可以携带;机制需要重新实现。

⚙️ 运行前 — 向用户提出的三个一次性请求(这些可以避免数小时的手动中途监护)

提前一次性提出这些请求,以免运行稍后停滞:

  1. 授权舰队。 工人以沙盒/批准关闭状态生成(请参阅 工人清单 中的确切标志)。在自动权限模式下,第一个这样的生成会被阻止。让用户授权它(添加 Bash 权限规则,或在自动模式外运行)在你生成之前 — 不要以撞墙的方式发现这个问题。
  2. 为本次运行关闭 PR 审查机器人的 Autofix。 如果仓库有带 Autofix 设置的机器人(例如 Cursor BugBot),让用户将其设置为 仅评论/关闭 并在之后重新启用。推送提交的 Autofix 是 非收敛的(请参阅 references/learnings.md #24、#34) — 保持开启会将每个 PR 变成多轮争斗,是手动协调员干预的最大来源。仅评论的发现同样有用,且分支保持稳定。
  3. 本次运行不需要实时密钥 — 拒绝用户提供的任何密钥。 工人仅对代码、测试和本地一次性数据库进行操作。如果用户粘贴 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/check JSON(按顶级 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 — 审查/盘点 → 质疑分类 → 冻结

  1. 盘点 发现。如果用户向你提供了审计/审查文档,那就是你的真相来源 — 阅读它。否则,跨维度派遣审查工人(可靠性、并发、安全、授权、多租户隔离、数据模型、成本/滥用、耦合、操作盲点、依赖卫生、死代码、弱测试、密钥泄露、可访问性、关键路径)以生成它。
  2. 质疑分类 每个发现:它是 真实的 且是 根本原因(而不是症状)吗?分类到 车道(如下)。丢弃同义反复或已修复的项目。
  3. 冻结 发现列表为不可变文档(例如 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)。每个阶段都是一个 新工人 — 构建者不能是审查者(构建盲审是全部意义所在):

  1. 构建 — 一个 codex 构建者在专用的工作树/分支上实现修复(从 {{BASE}} 分叉),添加一个 真正的回归测试(一个在修复被撤销时失败的测试),以 {{MAINTAINER}} 身份提交。使用 assets/builder_preamble.txt。
  2. 打开 PR + 机器人协调 — 一个全新的 claude 整合者打开针对 {{BASE}} 的 PR,等待 {{BOT}}(有限轮询:下限 3 分钟,上限 10 分钟),然后 协调 机器人:接受有效的发现,规范化任何机器人推送的提交 回 {{MAINTAINER}} + 剥离尾随信息(绝不压缩),用理由驳回误报。仅限于分支差异的密钥扫描(如果 gitleaks 在 PATH 上 — 兼容性列表将其标记为可选)。使用 assets/integrator_preamble.txt。
  3. 构建盲审 — 一个 不同的 全新 claude 审查者,从未见过构建者的对话,对差异 对照冻结发现的接受标准 评分,主动尝试 FAIL 它(根本原因?回归?密钥泄露?测试是真实的还是同义反复?),并投票 PASS/FAIL。使用 assets/reviewer_preamble.txt。协调员记录审查的头 SHA — 这是合并工人的 {{REVIEWED_SHA}} 不变性。
  4. 合并 — 在通过时,一个全新的 claude 整合者执行 冲突感知、保留提交的合并 到 {{BASE}}(gh pr merge --merge --delete-branch;如果落后,基于 BASE 变基 + 解决;标准化自动

…

[为翻译截断]

相关技能