- 人工智能
- AI Agent
- Agent 工作流
- CLI
- 研发协作
- AI 技能
- MCP 服务
【免费下载链接】loop-engineering
Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
本指南以 loop-engineering 仓库中
loop-swarm功能为绝对主体展开：先讲清它为何要解决"单个 AI 智能体运行结果不确定"这一 L3 高层级问题，再给出可直接复制的 CLI 命令与完整参数说明，最后深入到tools/loop-swarm的源码与测试，还原其"顺序多智能体运行 + 字节级一致多数共识"的底层实现。读完你既能立刻跑通npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>，也能理解共识阈值、退出码、失败淘汰与安全边界的设计取舍。
为什么需要"多智能体共识沙箱"：不确定输出的安全网
在 loop-engineering 的成熟度模型里，循环（loop）会从 L1（只报告）逐级升到 L2（在 worktree 中隔离修复）再到 L3（无人值守自动执行）。层级越高，一个错误判断被自动写入仓库的代价越大。而 AI 编码智能体（agent）有一个天然短板：即使给它完全相同的任务，两次运行也可能产出不同的结果——非确定性可能来自模型采样、工具调用顺序、环境噪声，甚至只是注释排版。
loop-swarm针对的正是这个缺口。按 tools/loop-swarm/README.md 的定位，它是"面向极高置信度循环操作的多智能体共识沙箱"：
loop-swarm在一个隔离的loop-sandboxworktree 中按顺序多次运行同一个智能体命令，然后提取每次运行产生的.patch文件、对其哈希，并自动判断是否达成了多数共识。
如果智能体产生了不确定的结果，loop-swarm就充当L3 安全网：只有被多次独立顺序运行一致验证过的变更，才会被提出。换句话说，它把"一次运行的结果"升级为"多次运行互相印证的结果"，用多数投票消化单次运行的不确定性。
需要强调的安全前提（README 中[!IMPORTANT]标注）：loop-swarm实现的是临时 git worktree 隔离这一安全边界，不是 OS 级沙箱或容器。完整威胁模型请阅读 docs/safety.md 中 "Worktree Isolation & Consensus Sandboxing" 一节。
快速上手：一条命令跑起共识验证
在任意 git 仓库根目录（无需克隆本仓库）直接通过 npx 运行：
npx @cobusgreyling/loop-swarm run --count 3 -- npx my-agent run --task "Refactor utils.ts"这是 docs/QUICKSTART.md "Multi-agent consensus sandboxing (loop-swarm)" 一节给出的标准形态，也是本功能在快速入门文档中要求保留的可复制示例：
# 在 3 个顺序沙箱中运行多智能体共识 npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>CLI 参数与语法
从 tools/loop-swarm/src/cli.ts 的参数解析可以看出完整的命令行约定：
| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
run | — | 必填 | 唯一的子命令；缺省或写错会报错退出（Missing or invalid subcommand. Must use "run".） |
--count, -n | -n | 3 | 顺序启动的智能体数量；必须为正整数，NaN或小于 1 会报错退出 |
--shell | — | false | 是否在 shell 中执行命令（如bash -c场景） |
--help, -h | -h | — | 打印帮助信息并退出 |
两个容易被忽略的语法点（来自 cli.ts 的实现）：
- 必须显式使用
--分隔符：loop-swarm run --count 3 -- echo "hello"。如果没有--、或--后面没有命令，CLI 会报Missing command. Use -- to separate options from the command.并以退出码 1 结束——这是为了把智能体命令原样透传，避免parseArgs吞掉 agent 自己的参数。 --count校验在启动前完成：parseInt(values.count, 10)后若isNaN(count) || count < 1，直接输出--count must be a positive integer.并退出，防止 0 或负数引发无意义的空跑。
依赖与运行环境（见 tools/loop-swarm/package.json）：Node.js>= 18，包为 ESM 模块，bin入口为loop-swarm，核心运行时依赖@cobusgreyling/loop-sandbox（以 file: 相对路径引用本仓库的tools/loop-sandbox）。
共识判定的工作流程：五步还原
按 tools/loop-swarm/README.md 的 "How it works"，以及 tools/loop-swarm/src/swarm.ts 中runSwarm的实际实现，一次完整的 swarm 运行是这样的：
- 顺序启动
N个loop-sandbox实例（默认N=3）。串行而非并行是为了防止 git worktree 和信号处理器竞争（serialized to prevent worktree races）。从源码看，runSwarm用一个for循环逐个await runInSandbox(...)，每个 agent 打印▶️ Agent i/N进度。 - 等待所有沙箱执行完智能体命令并提取 diff。任一智能体失败（非零退出码）会被取消投票资格——源码先按
exitCode === 0过滤出successfulRuns，统计failedRuns并打印⚠️ N agent(s) failed with non-zero exit codes. They are excluded from consensus voting.。 - 对每个
.patch文件的原始字节做 SHA-256 哈希。源码用createHash('sha256').update(buffer).digest('hex')，以哈希为 key 统计hashCounts。 - 判定严格多数：阈值是
Math.floor(N / 2) + 1（针对启动的总数N，不是成功数）。若达到阈值，把胜出补丁复制为.loop-sandbox/patches/consensus.patch。 - 清理所有临时 worktree（由每个
loop-sandbox的finally清理路径完成）。
一个重要的特例："无变更"共识
源码中，成功运行但!r.hasChanges || !r.patchFile的智能体被计为noChangeCount。如果noChangeCount >= threshold，则判定达成共识——共识内容是"无需任何变更"：
✅ Consensus reached! 2/3 agents produced NO changes (success).此时不生成consensus.patch（consensusPatchFile: null），但整体成功。这一点非常实用：对于"检查后确认无需修改"这类任务，多数智能体一致地"什么都没改"本身就是高置信度的安全结论，而不是失败。
多数补丁落盘与分歧补丁
当存在多数补丁时（源码 swarm.ts 的if (maxCount >= threshold && majorityHash)分支）：
✅ Consensus reached! 2/3 agents produced the exact same patch. 🎉 Consensus patch saved to: <root>/.loop-sandbox/patches/consensus.patch胜出补丁取自多数哈希中的第一个代表文件（hashCounts[majorityHash].files[0]），复制到同一patches目录下的consensus.patch。其余哈希对应的补丁作为divergentPatches返回，供审计参考。若maxCount未达阈值，则打印❌ Swarm failed to reach consensus. (Highest agreement: X/N)并判定失败。
退出码与行为约定
tools/loop-swarm/README.md 明确规定了两个退出码，与整个工具链（loop-context、loop-gate）的约定风格一致：
| 退出码 | 含义 |
|---|---|
0 | 达成共识——要么在某个补丁上达成，要么在"多数智能体成功且未产生补丁"即"无需变更"上达成 |
1 | 未达成共识，或工具内部失败（含 CLI 参数错误、命令缺失、异常抛出） |
实现上，cli.ts 依据runSwarm返回的result.reached决定process.exit(0)还是process.exit(1)。因此loop-swarm可以干净地嵌入 CI / 调度脚本：0放行，非0即中止并交人工处理——这正是 L3 自动化所需的机械判定。
底层隔离机制：依赖loop-sandbox的临时 worktree
loop-swarm本身不重复实现隔离，而是逐次调用@cobusgreyling/loop-sandbox的runInSandbox（见 tools/loop-sandbox/src/sandbox.ts）。每个沙箱执行：
- 校验当前目录是 git 仓库（
isGitRepo），生成运行 id（sandbox-<8位hex>）。 - 用
loop-worktree的createWorktree从当前 HEAD 创建临时分支与 worktree，进程cwd指向该隔离树。 - 以
stdio: 'inherit'spawn 用户命令；Windows 下若npx/tsc等.cmdshim 抛ENOENT，会自动通过 shell 重试一次（源码中的supersededByRetry机制，避免抢占真实结果）。 - 命令结束后
git add -A并git diff --cached --binary提取补丁（含未跟踪文件、支持二进制），写入.loop-sandbox/patches/<runId>.patch。 finally中统一清理：kill 残留子进程、释放可选 advisory lock、git worktree remove --force、删除loop/<runId>分支并 gc——保证主仓库保持干净。
这解释了loop-swarm的产物为什么是patch文件而非直接改代码：共识只决定"哪个补丁被选中"，应用与否仍由你（或后续 gate）决定。人工审查补丁的方式与单沙箱一致：
npx @cobusgreyling/loop-sandbox review git apply .loop-sandbox/patches/consensus.patch安全边界与已知限制（务必先读）
tools/loop-swarm/README.md 与 docs/QUICKSTART.md 同时强调以下限制，这也是设计文档要求"Notes limitations ... with a link to safety docs"的原因：
- 字节级一致共识：共识依赖补丁字节的精确 SHA-256 哈希。两个智能体产出语义相同但空白或注释顺序不同的代码，会被判定为分歧。这是当前实现最需要意识到的"假阴性"来源——安全优先于召回。
- 共享标准 IO：顺序执行的智能体共享父进程的标准输入输出，不适合需要独立交互式终端的命令。
- 时间代价：执行被串行化以维持 manifest 上的安全保证，
--count 3大约耗时单次运行的 3 倍（README 原话：roughly 3x as long）。 - SIGINT 处理：因为
loop-sandbox是进程内运行，其信号处理器会在收到SIGINT时退出整个进程；运行中收到信号会让整个 swarm 退出，而非交给 swarm 自己的清理流程。README 明确这是 v1 限制，留待后续子进程化实现。 - 不是 OS 沙箱：
loop-swarm提供的是 git worktree 隔离，进程仍保有 OS 级别的文件系统与网络访问能力，补丁也不会捕获 worktree 之外或.gitignore的改动（见 tools/loop-sandbox/README.md 的[!WARNING]）。完整威胁模型与防线请阅读 docs/safety.md（Path Denylist、Auto-Merge Policy、Human Gates 等章节），以及其中 "Worktree Isolation & Consensus Sandboxing" 一节对loop-swarm的定位。
测试如何验证共识逻辑
tools/loop-swarm/test/swarm.test.mjs 用真实的 git 仓库 + 临时目录跑通五条端到端用例，是理解共识语义最直接的样例：
- 确定性命令：
--count 2下两个 agent 写出相同内容 →Consensus reached! 2/2，并断言.loop-sandbox/patches/consensus.patch存在且非空。 - 分歧补丁：agent 写入
Math.random()产生的非确定内容 → CLI 非零退出，输出Swarm failed to reach consensus。 - 全部失败：agent
process.exit(1)→ 非零退出，输出3 agent(s) failed with non-zero exit codes与失败提示。 - 2/3 多数：第三个 agent 写入分歧内容 → 仍判定成功，输出
Consensus reached! 2/3且生成 consensus.patch。这正是"严格多数"（而非"全票一致"）的体现。 - 无变更多数：多数 agent 成功但什么都没写 → 输出
Consensus reached! 2/3 agents produced NO changes并成功退出。
这五条用例与 swarm.ts 的分支一一对应，可作为你理解（或复刻）共识语义的最小参考集。
在工具链与文档体系中的位置
- 快速入门入口：
loop-swarm是 docs/QUICKSTART.md 中 L2/L3 安全工具链的一节（紧随loop-worktree与loop-sandbox的 "Ephemeral worktree isolation" 之后），并在文末的 Copy-paste cheat sheet 中保留一行快捷命令：npx @cobusgreyling/loop-swarm run --count 3 -- <agent-cmd>。 - 安全文档：docs/safety.md 的 "Worktree Isolation & Consensus Sandboxing" 将
loop-sandbox（单 agent 临时 worktree 隔离）与loop-swarm（跨顺序运行要求字节一致共识）并列，构成 L2→L3 的递进防线。 - 与统一前端的关系：设计上
loop-swarm不重写统一的@cobusgreyling/loop前端入口，而是与loop-init、loop-audit、loop-sandbox等专用包一样保持独立、可单独调用。统一 CLI 的分层约定见 docs/cli-front-door.md。
实践建议：什么时候用、怎么用
- 用在 L3 无人值守改动之前：凡是智能体要自动产生代码变更、而错误代价高（比如涉及
docs/safety.md中 denylist 之外的业务代码）的操作，先套一层loop-swarm，把"一次猜"变成"多数印证"。 --count权衡：默认3是"严格多数 + 时间开销"的平衡点；任务越关键可上调，但要接受近线性的时间增长（串行执行）。--count 1在语义上退化为单次loop-sandbox运行，不构成共识。- 善用"无变更共识"：对于检查、triage 类任务，多数 agent 一致认为"无需改动"也是有效的高置信度结果（退出码 0），无需因此误报失败。
- 应用前必查
consensus.patch：共识只保证"多次运行一致"，不保证"改动正确"。在git apply .loop-sandbox/patches/consensus.patch前仍应按 docs/safety.md 的 Pre-Flight Safety Check 核对 denylist、auto-merge 策略与人工 gate。
一句话总结：loop-swarm用"顺序多跑几次 + 严格多数字节一致"把智能体的单次不确定输出，收敛为可机械判定、可审计、可放心进入下一步的高置信度补丁——它是 loop-engineering 从 L2 迈向 L3 无人值守时最直接的一道共识防线。
- 人工智能
- AI Agent
- Agent 工作流
- CLI
- 研发协作
- AI 技能
- MCP 服务
【免费下载链接】loop-engineering
Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
相关推荐
WebLLM 函数调用（Function Calling）实战指南：手动解析与 OpenAI 协议两种实现方案
WebLLM 函数调用（Function Calling）实战指南：手动解析与 OpenAI 协议两种实现方案 本指南以 examples/function c
人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务loop-engineering Dependency Sweeper Starter：用 L2 补丁级自动化与强验证门禁守护依赖面
loop engineering Dependency Sweeper Starter：用 L2 补丁级自动化与强验证门禁守护依赖面 Dependency Sw
人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务loop-engineering CI/CD部署指南：用GitHub Actions与loop-action实现Agent循环无人值守运行
loop engineering CI/CD部署指南：用GitHub Actions与loop action实现Agent循环无人值守运行 loop engin
人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
