loop-sandbox 实战：用临时 git worktree 为 AI Agent 提供可审查的隔离执行环境

人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务【免费下载链接】loop-engineeringPractical 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.项目地址https://gitcode.com/gh_mirrors/lo/loop-engineering点击查看免费下载导读loop-sandbox是 loop-engineering 仓库中面向无人值守 AI 循环loop的隔离执行工具它把 Agent 的命令放进一个临时 git worktree 中运行自动把 Agent 的改动包括新增的未跟踪文件捕获成一份可审查的.patch文件然后立即销毁工作树让你的主工作区始终保持干净。本文以仓库中规划该工具进入 QUICKSTART 的 issue 文档为骨架完整覆盖安装、命令参数、Windows 兼容、多循环锁协作与源码级实现原理读完即可在任意 git 仓库中安全地让 Agent 动手改代码。关联文档scripts/issue-bodies/quickstart-loop-sandbox.md。该 issue 的验收标准是用一段话讲清临时 worktree 隔离、给出npx cobusgreyling/loop-sandbox run -- cmd及可选的--shell、说明 Windows 下 npm.cmd垫片遇到ENOENT会自动重试、并链接到补丁审查与安全文档——本文正是围绕这四条验收标准展开并下沉到源码。为什么需要 loop-sandbox无人值守 Agent 的直接风险直接在主工作树里运行无人值守的 AI Agent循环可能造成三类典型事故破坏主工作树——Agent 的失败尝试会留下半成品改动、冲突标记甚至损坏的文件覆盖未跟踪文件——Agent 可能对未纳入 git 管理的文件做出不可恢复的修改难以复盘——一次失败的执行尝试可能掺杂大量噪音改动事后很难把该保留的和该丢弃的拆开。loop-sandbox的核心解决思路是临时 worktree 隔离完整流程见 tools/loop-sandbox/README.md自动为 Agent 创建一个隔离的 git worktreeAgent 在其中运行命令像平时一样自然地操作代码库命令结束后自动把 Agent 的编辑包括新增的未跟踪文件捕获成一份干净的.patch文件销毁 worktree主仓库保持完全干净。随后由人工审查这份 patch一键git apply即可落地。正是这种先隔离、再捕获、后审查的顺序让它成为 L2 及以上自治循环的推荐执行底座——QUICKSTART 中把它编排在loop-worktree与安全工具之后而 loop-actionGitHub Composite Action也通过sandbox: true把 Agent 执行路由进 loop-sandbox说明它已被发布并被 loop-action 使用但新手往往只看到 audit/init——这正是关联文档要补强的入口。安装与前置条件安装npm install -g cobusgreyling/loop-sandbox # 或直接用 npx 运行无需全局安装 npx cobusgreyling/loop-sandbox run -- command从 tools/loop-sandbox/package.json 可以看到包以bin暴露loop-sandbox命令要求 Node.js18核心依赖是cobusgreyling/loop-worktree工作树创建、清单与锁的底层实现。前置条件必须在 git 仓库内运行runInSandbox的第一步就是isGitRepo(root)检查非仓库目录会直接抛出loop-sandbox must be run inside a git repository.见 src/sandbox.ts。必须配置.gitignore把以下两行加入项目.gitignore防止补丁文件与 worktree 清单被误提交.loop-sandbox/ .loop-worktrees/.loop-sandbox/存放生成的 patch位于.loop-sandbox/patches/.loop-worktrees/是 loop-worktree 维护 manifest 与工作树的目录。命令与参数参考loop-sandbox command [options]命令说明run [opts] -- cmd在隔离沙箱内运行一条 Agent 命令review/list列出已捕获、待人工审查的补丁run支持的选项均来自 src/cli.ts 的实际解析逻辑选项说明--shell强制以shell: true运行用于bash -c等 shell 内建场景。在 Windows 上npm 安装的.cmd垫片npx、tsc等遇到ENOENT时会自动通过 shell 重试因此这里很少需要手动指定--base branchworktree 基于的分支默认取当前HEAD所在分支--lock-paths globs逗号分隔的 glob在运行期间对loop-worktree的 advisory lock 持锁防止排程循环并发触碰相同路径。默认关闭--lock-owner name锁的所有者名默认取本次运行的生成 id--lock-ttl dur例如30m透传给loop-worktree的--ttl--lock-wait dur例如5m透传给loop-worktree的--wait注意run的子命令解析CLI 会先找到--分隔符src/cli.ts分隔符之前的参数按上表解析未知选项会报错退出分隔符之后才是真正要在沙箱里执行的命令。缺少--或缺少命令都会得到明确的错误提示。实战示例让 Agent 安全地运行你的工具# 放心让 Agent 跑 linter/formatter不会污染工作树 npx cobusgreyling/loop-sandbox run -- npx my-agent运行原始 shell 命令npx cobusgreyling/loop-sandbox run --shell -- bash -c echo hello test.txt与触碰相同文件的排程循环并行npx cobusgreyling/loop-sandbox run --lock-paths src/**,docs/** -- npx my-agent审查并应用补丁# 列出沙箱捕获的所有补丁 npx cobusgreyling/loop-sandbox review # 示例输出 # Loop Sandbox Patches # sandbox-82f1e394.patch (1.2 KB) # Apply: git apply .loop-sandbox/patches/sandbox-82f1e394.patch运行成功后 CLI 同样会打印两条指引npx cobusgreyling/loop-sandbox review用于审查git apply 相对路径用于立即应用见 src/cli.ts。若无改动则打印Run completed … No changes detected.并透传退出码。在git apply之前务必先人工审查补丁内容详见下文安全边界。Windows 兼容npm.cmd垫片的 ENOENT 自动重试关联文档的第三条验收标准专门强调这一点在 Windows 上npm 安装的 CLInpx、tsc等实际是.cmd/.bat垫片spawn无法直接 exec 它们会报ENOENT。loop-sandbox 的处理是只在出现该特定错误时自动通过 shell 重试一次src/sandbox.tsif (!useShell !options.shell process.platform win32 err.code ENOENT) { supersededByRetry true; attempt(true); return; }为什么要精确到错误码、而不是无条件加--shell因为强制shell: true会破坏依赖精确 argv 引用的命令例如node -e ...。自动重试还带有一个去竞态细节Windows 上失败的 spawn 会在error事件后几毫秒补发一个带合成退出码的close事件supersededByRetry标记让第一次非 shell尝试的过期事件变成 no-op避免它在resolve()竞态中赢过重试的真实结果。因此在 Windows 上跑npx不需要额外传--shell。源码级原理一次沙箱运行的生命周期runInSandbox(root, command, args, options)src/sandbox.ts的完整链路如下前置校验isGitRepo(root)确认在 git 仓库内生成运行 idsandbox-${crypto.randomBytes(4).toString(hex)}作为分支名、锁所有者名与 patch 文件名的唯一标识准备目录创建.loop-sandbox/patches/解析 base 分支options.base优先否则git rev-parse --abbrev-ref HEAD可选获取 advisory locklockPaths({ root, owner, paths, ttl, wait })锁在 worktree 创建之前获取运行结束之后释放创建 worktree调用cobusgreyling/loop-worktree的createWorktree从 base 分支开出新分支loop/${runId}并检出到.loop-worktrees/${runId}见 tools/loop-worktree/src/worktree.ts执行命令spawn(command, args, { cwd: worktreeAbsPath, stdio: inherit, shell })Agent 输出实时透传到终端捕获改动git add -A后检查git diff --cached --stat有改动则用git diff --cached --binary生成 patch 写入.loop-sandbox/patches/${runId}.patch——使用--binary是故意的测试 sandbox.test.mjs 验证了二进制文件如Buffer.from([0x00, 0xFF, ...])能精确捕获并git apply还原不会发生 UTF-8 破坏清理git worktree remove --force删除工作树、git branch -D loop/${runId}删除临时分支、再调用 loop-worktree 的gc对账孤儿工作树与清单。信号安全与清理的只执行一次清理逻辑值得单独说明。CtrlCSIGINT/SIGTERM在任何执行阶段都可能触发而清理必须在每条退出路径上都执行且只执行一次src/sandbox.ts。实现上用单一cleanupPromise共享给所有信号处理器这样即使信号重复触发连按两次 CtrlC后续信号也会等待同一份进行中的清理完成后再process.exit(1)而不会在慢速的git worktree remove中途抢先退出、把一把没有 TTL 的锁遗留在磁盘上。测试 sandbox.test.mjs 专门用双 SIGINT验证了清理必须完成、锁必须释放、.loop-worktrees下不得残留sandbox-*目录。清理顺序也有讲究先 kill 沙箱内的子进程防止它继续写入 worktree 或与受锁路径竞态再释放锁这是其他循环被阻塞的资源不应被慢速的 worktree 拆除拖累最后拆除工作树。补丁提取失败时的数据保护如果git add -A失败例如 worktree 元数据被破坏工具不会强行删除现场extractionFailed标记会让清理阶段跳过 worktree 拆除并打印警告把工作树与loop/${runId}分支留在磁盘上供人工恢复src/sandbox.ts。测试 sandbox.test.mjs 验证了这一行为。同时无论提取是否失败锁都会照常释放——锁的释放与补丁提取是否成功无关src/sandbox.ts 对应的测试。多循环安全--lock-paths 与 advisory lock单独的沙箱运行并不天然防止另一个排程循环同时编辑同一批文件。--lock-paths把本次运行接入loop-worktree的 advisory lock锁在 worktree 创建前获取、运行结束后释放一旦有碰撞的排程循环想对重叠路径持锁其lock调用会响亮地失败而不是静默竞态见 tools/loop-sandbox/README.md 与 docs/multi-loop.md。锁的底层实现在 tools/loop-worktree/src/lock.tspathsOverlap逐段比较两个 glob通配段*/**与任意内容兼容例如src/**能覆盖src/nested/foo.tslockPaths用跨进程互斥文件.mutex原子wx创建串行化检查-写入临界区支持--ttl过期与--wait等待等待中还会做死锁环检测。测试 sandbox.test.mjs 验证了三件事运行期间锁确实持有通过 marker 文件观察到运行中锁存在结束后确实释放另一 owner 持有重叠锁时runInSandbox直接拒绝locked by owner other-loop且不会误打印已释放消息从未获取过的锁不声称释放锁释放与 patch 提取成功与否无关。安全边界这不是容器隔离关联文档与 tools/loop-sandbox/README.md 都明确警告这不是容器化的气隙隔离air-gap。Agent 进程保留完整的文件系统与网络访问权它可以逃逸出 worktree例如../../而 worktree 之外或.gitignored文件的改动不会被捕获进 patch。因此该工具是对 docs/safety.md 的补充不能替代针对恶意代码的 OS 级沙箱始终先审查 patch 再git apply——这正是 QUICKSTART 中week one: report only纪律的延续若需要更高置信度可在此基础上叠加 loop-swarm多 Agent 共识连续在多个隔离 worktree 中运行同一命令仅当多数运行产出字节级一致的 patch 才写入consensus.patch。在 CI/CD 中集成loop-action 的 sandbox 开关loop-sandbox 已被 loop-actionGitHub Composite Action使用这也是关联文档点明包已发布并被使用、但新手只见 audit/init的原因。在 workflow 中开启临时 worktree 隔离- uses: cobusgreyling/loop-engineering/tools/loop-actionmain with: pattern: ci-sweeper level: L2 sandbox: true # 路由到 loop-sandbox临时 worktree 隔离 patch 捕获 sandbox-shell: false # loop-sandbox 兼容旋钮默认即可 command: | npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.mdcommand总是以bash -eo pipefail脚本形式执行无论是否沙箱化sandbox-shell只控制 loop-sandbox 内部是否再套一层--shell不影响你写管道和多行脚本。注意安全红线不要把 issue/PR 标题、分支名等外部不可信内容直接插值进command存在命令注入风险。与本地跑法的对应关系是sandbox: true≈npx cobusgreyling/loop-sandbox run -- bash -eo pipefail script。与其他工具的关系与定位loop-worktree底层的 worktree 生命周期与锁管理器manifest、分支、advisory lock、gcloop-sandbox 直接复用它创建/销毁工作树并参与多循环锁约定loop-audit / loop-init一个打分就绪度、一个脚手架属于评估与初始化环节loop-sandbox 属于执行隔离环节是新用户最容易忽略的 L2 安全组件loop-swarm基于 loop-sandbox 的升级形态用多 Agent 共识进一步过滤非确定性编辑loop-context熔断器决定是否继续loop-sandbox 决定在哪里执行。两者相互独立、可组合。对应关系可参考 QUICKSTART.md 中从 L1仅报告→ L2worktree 内的一次辅助修复→ L3无人值守的升级路径进入 L2 时loop-sandbox就是那个先隔离、后审查的执行闸门。小结一条可直接落地的使用清单确认在 git 仓库内且.gitignore包含.loop-sandbox/与.loop-worktrees/用npx cobusgreyling/loop-sandbox run -- cmd运行 AgentWindows 上npx无需--shell.cmd垫片遇ENOENT自动重试需要 shell 内建时加--shell需要并发保护时加--lock-paths配合--lock-owner/--lock-ttl/--lock-wait用loop-sandbox review列出 patch人工审查后再git apply牢记隔离边界不是容器worktree 之外与.gitignored文件不在保护范围内恶意代码请用 OS 级沙箱参见 docs/safety.md在 CI 中通过 loop-action 的sandbox: true复用同一套隔离机制。相关资源tools/loop-sandbox/README.md完整命令与示例、src/cli.ts参数解析、src/sandbox.ts核心实现、test/sandbox.test.mjs覆盖隔离、二进制 patch、锁、信号清理的测试、docs/multi-loop.md多循环锁约定。赞分享人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务【免费下载链接】loop-engineeringPractical 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.项目地址https://gitcode.com/gh_mirrors/lo/loop-engineering点击查看免费下载相关推荐ZenML Sandbox 组件实战在 Pipeline Step 内为 AI Agent 提供隔离代码执行环境ZenML Sandbox 组件实战在 Pipeline Step 内为 AI Agent 提供隔离代码执行环境 Sandbox沙箱是 ZenML 中一类MLOps机器学习后端工作流自动化AI AgentVoltAgent Blaxel 沙箱提供商用 voltagent/sandbox-blaxel 为 Agent 提供隔离的远程 Shell 执行环境VoltAgent Blaxel 沙箱提供商用 voltagent/sandbox blaxel 为 Agent 提供隔离的远程 Shell 执行环境 导读人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音ZenML Modal Sandbox 实战指南为 AI Agent 提供亚秒级冷启动的隔离代码执行环境ZenML Modal Sandbox 实战指南为 AI Agent 提供亚秒级冷启动的隔离代码执行环境 本文围绕 ZenML 的 Modal SandboxMLOps机器学习后端工作流自动化AI Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考