戰(zhàn)：用臨時(shí) git worktree 為 AI Agent 提供可審查的隔離執(zhí)行環(huán)境)
人工智能AI AgentAgent 工作流CLI研發(fā)協(xié)作AI 技能MCP 服務(wù)【免費(fèi)下載鏈接】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.項(xiàng)目地址https://gitcode.com/gh_mirrors/lo/loop-engineering點(diǎn)擊查看免費(fèi)下載導(dǎo)讀loop-sandbox是 loop-engineering 倉(cāng)庫(kù)中面向無人值守 AI 循環(huán)loop的隔離執(zhí)行工具它把 Agent 的命令放進(jìn)一個(gè)臨時(shí) git worktree 中運(yùn)行自動(dòng)把 Agent 的改動(dòng)包括新增的未跟蹤文件捕獲成一份可審查的.patch文件然后立即銷毀工作樹讓你的主工作區(qū)始終保持干凈。本文以倉(cāng)庫(kù)中規(guī)劃該工具進(jìn)入 QUICKSTART 的 issue 文檔為骨架完整覆蓋安裝、命令參數(shù)、Windows 兼容、多循環(huán)鎖協(xié)作與源碼級(jí)實(shí)現(xiàn)原理讀完即可在任意 git 倉(cāng)庫(kù)中安全地讓 Agent 動(dòng)手改代碼。關(guān)聯(lián)文檔scripts/issue-bodies/quickstart-loop-sandbox.md。該 issue 的驗(yàn)收標(biāo)準(zhǔn)是用一段話講清臨時(shí) worktree 隔離、給出npx cobusgreyling/loop-sandbox run -- cmd及可選的--shell、說明 Windows 下 npm.cmd墊片遇到ENOENT會(huì)自動(dòng)重試、并鏈接到補(bǔ)丁審查與安全文檔——本文正是圍繞這四條驗(yàn)收標(biāo)準(zhǔn)展開并下沉到源碼。為什么需要 loop-sandbox無人值守 Agent 的直接風(fēng)險(xiǎn)直接在主工作樹里運(yùn)行無人值守的 AI Agent循環(huán)可能造成三類典型事故破壞主工作樹——Agent 的失敗嘗試會(huì)留下半成品改動(dòng)、沖突標(biāo)記甚至損壞的文件覆蓋未跟蹤文件——Agent 可能對(duì)未納入 git 管理的文件做出不可恢復(fù)的修改難以復(fù)盤——一次失敗的執(zhí)行嘗試可能摻雜大量噪音改動(dòng)事后很難把該保留的和該丟棄的拆開。loop-sandbox的核心解決思路是臨時(shí) worktree 隔離完整流程見 tools/loop-sandbox/README.md自動(dòng)為 Agent 創(chuàng)建一個(gè)隔離的 git worktreeAgent 在其中運(yùn)行命令像平時(shí)一樣自然地操作代碼庫(kù)命令結(jié)束后自動(dòng)把 Agent 的編輯包括新增的未跟蹤文件捕獲成一份干凈的.patch文件銷毀 worktree主倉(cāng)庫(kù)保持完全干凈。隨后由人工審查這份 patch一鍵git apply即可落地。正是這種先隔離、再捕獲、后審查的順序讓它成為 L2 及以上自治循環(huán)的推薦執(zhí)行底座——QUICKSTART 中把它編排在loop-worktree與安全工具之后而 loop-actionGitHub Composite Action也通過sandbox: true把 Agent 執(zhí)行路由進(jìn) loop-sandbox說明它已被發(fā)布并被 loop-action 使用但新手往往只看到 audit/init——這正是關(guān)聯(lián)文檔要補(bǔ)強(qiáng)的入口。安裝與前置條件安裝npm install -g cobusgreyling/loop-sandbox # 或直接用 npx 運(yùn)行無需全局安裝 npx cobusgreyling/loop-sandbox run -- command從 tools/loop-sandbox/package.json 可以看到包以bin暴露loop-sandbox命令要求 Node.js18核心依賴是cobusgreyling/loop-worktree工作樹創(chuàng)建、清單與鎖的底層實(shí)現(xiàn)。前置條件必須在 git 倉(cāng)庫(kù)內(nèi)運(yùn)行runInSandbox的第一步就是isGitRepo(root)檢查非倉(cāng)庫(kù)目錄會(huì)直接拋出loop-sandbox must be run inside a git repository.見 src/sandbox.ts。必須配置.gitignore把以下兩行加入項(xiàng)目.gitignore防止補(bǔ)丁文件與 worktree 清單被誤提交.loop-sandbox/ .loop-worktrees/.loop-sandbox/存放生成的 patch位于.loop-sandbox/patches/.loop-worktrees/是 loop-worktree 維護(hù) manifest 與工作樹的目錄。命令與參數(shù)參考loop-sandbox command [options]命令說明run [opts] -- cmd在隔離沙箱內(nèi)運(yùn)行一條 Agent 命令review/list列出已捕獲、待人工審查的補(bǔ)丁run支持的選項(xiàng)均來自 src/cli.ts 的實(shí)際解析邏輯選項(xiàng)說明--shell強(qiáng)制以shell: true運(yùn)行用于bash -c等 shell 內(nèi)建場(chǎng)景。在 Windows 上npm 安裝的.cmd墊片npx、tsc等遇到ENOENT時(shí)會(huì)自動(dòng)通過 shell 重試因此這里很少需要手動(dòng)指定--base branchworktree 基于的分支默認(rèn)取當(dāng)前HEAD所在分支--lock-paths globs逗號(hào)分隔的 glob在運(yùn)行期間對(duì)loop-worktree的 advisory lock 持鎖防止排程循環(huán)并發(fā)觸碰相同路徑。默認(rèn)關(guān)閉--lock-owner name鎖的所有者名默認(rèn)取本次運(yùn)行的生成 id--lock-ttl dur例如30m透?jìng)鹘oloop-worktree的--ttl--lock-wait dur例如5m透?jìng)鹘oloop-worktree的--wait注意run的子命令解析CLI 會(huì)先找到--分隔符src/cli.ts分隔符之前的參數(shù)按上表解析未知選項(xiàng)會(huì)報(bào)錯(cuò)退出分隔符之后才是真正要在沙箱里執(zhí)行的命令。缺少--或缺少命令都會(huì)得到明確的錯(cuò)誤提示。實(shí)戰(zhàn)示例讓 Agent 安全地運(yùn)行你的工具# 放心讓 Agent 跑 linter/formatter不會(huì)污染工作樹 npx cobusgreyling/loop-sandbox run -- npx my-agent運(yùn)行原始 shell 命令npx cobusgreyling/loop-sandbox run --shell -- bash -c echo hello test.txt與觸碰相同文件的排程循環(huán)并行npx cobusgreyling/loop-sandbox run --lock-paths src/**,docs/** -- npx my-agent審查并應(yīng)用補(bǔ)丁# 列出沙箱捕獲的所有補(bǔ)丁 npx cobusgreyling/loop-sandbox review # 示例輸出 # Loop Sandbox Patches # sandbox-82f1e394.patch (1.2 KB) # Apply: git apply .loop-sandbox/patches/sandbox-82f1e394.patch運(yùn)行成功后 CLI 同樣會(huì)打印兩條指引npx cobusgreyling/loop-sandbox review用于審查git apply 相對(duì)路徑用于立即應(yīng)用見 src/cli.ts。若無改動(dòng)則打印Run completed … No changes detected.并透?jìng)魍顺龃a。在git apply之前務(wù)必先人工審查補(bǔ)丁內(nèi)容詳見下文安全邊界。Windows 兼容npm.cmd墊片的 ENOENT 自動(dòng)重試關(guān)聯(lián)文檔的第三條驗(yàn)收標(biāo)準(zhǔn)專門強(qiáng)調(diào)這一點(diǎn)在 Windows 上npm 安裝的 CLInpx、tsc等實(shí)際是.cmd/.bat墊片spawn無法直接 exec 它們會(huì)報(bào)ENOENT。loop-sandbox 的處理是只在出現(xiàn)該特定錯(cuò)誤時(shí)自動(dòng)通過 shell 重試一次src/sandbox.tsif (!useShell !options.shell process.platform win32 err.code ENOENT) { supersededByRetry true; attempt(true); return; }為什么要精確到錯(cuò)誤碼、而不是無條件加--shell因?yàn)閺?qiáng)制shell: true會(huì)破壞依賴精確 argv 引用的命令例如node -e ...。自動(dòng)重試還帶有一個(gè)去競(jìng)態(tài)細(xì)節(jié)Windows 上失敗的 spawn 會(huì)在error事件后幾毫秒補(bǔ)發(fā)一個(gè)帶合成退出碼的close事件supersededByRetry標(biāo)記讓第一次非 shell嘗試的過期事件變成 no-op避免它在resolve()競(jìng)態(tài)中贏過重試的真實(shí)結(jié)果。因此在 Windows 上跑npx不需要額外傳--shell。源碼級(jí)原理一次沙箱運(yùn)行的生命周期runInSandbox(root, command, args, options)src/sandbox.ts的完整鏈路如下前置校驗(yàn)isGitRepo(root)確認(rèn)在 git 倉(cāng)庫(kù)內(nèi)生成運(yùn)行 idsandbox-${crypto.randomBytes(4).toString(hex)}作為分支名、鎖所有者名與 patch 文件名的唯一標(biāo)識(shí)準(zhǔn)備目錄創(chuàng)建.loop-sandbox/patches/解析 base 分支options.base優(yōu)先否則git rev-parse --abbrev-ref HEAD可選獲取 advisory locklockPaths({ root, owner, paths, ttl, wait })鎖在 worktree 創(chuàng)建之前獲取運(yùn)行結(jié)束之后釋放創(chuàng)建 worktree調(diào)用cobusgreyling/loop-worktree的createWorktree從 base 分支開出新分支loop/${runId}并檢出到.loop-worktrees/${runId}見 tools/loop-worktree/src/worktree.ts執(zhí)行命令spawn(command, args, { cwd: worktreeAbsPath, stdio: inherit, shell })Agent 輸出實(shí)時(shí)透?jìng)鞯浇K端捕獲改動(dòng)git add -A后檢查git diff --cached --stat有改動(dòng)則用git diff --cached --binary生成 patch 寫入.loop-sandbox/patches/${runId}.patch——使用--binary是故意的測(cè)試 sandbox.test.mjs 驗(yàn)證了二進(jìn)制文件如Buffer.from([0x00, 0xFF, ...])能精確捕獲并git apply還原不會(huì)發(fā)生 UTF-8 破壞清理git worktree remove --force刪除工作樹、git branch -D loop/${runId}刪除臨時(shí)分支、再調(diào)用 loop-worktree 的gc對(duì)賬孤兒工作樹與清單。信號(hào)安全與清理的只執(zhí)行一次清理邏輯值得單獨(dú)說明。CtrlCSIGINT/SIGTERM在任何執(zhí)行階段都可能觸發(fā)而清理必須在每條退出路徑上都執(zhí)行且只執(zhí)行一次src/sandbox.ts。實(shí)現(xiàn)上用單一cleanupPromise共享給所有信號(hào)處理器這樣即使信號(hào)重復(fù)觸發(fā)連按兩次 CtrlC后續(xù)信號(hào)也會(huì)等待同一份進(jìn)行中的清理完成后再process.exit(1)而不會(huì)在慢速的git worktree remove中途搶先退出、把一把沒有 TTL 的鎖遺留在磁盤上。測(cè)試 sandbox.test.mjs 專門用雙 SIGINT驗(yàn)證了清理必須完成、鎖必須釋放、.loop-worktrees下不得殘留sandbox-*目錄。清理順序也有講究先 kill 沙箱內(nèi)的子進(jìn)程防止它繼續(xù)寫入 worktree 或與受鎖路徑競(jìng)態(tài)再釋放鎖這是其他循環(huán)被阻塞的資源不應(yīng)被慢速的 worktree 拆除拖累最后拆除工作樹。補(bǔ)丁提取失敗時(shí)的數(shù)據(jù)保護(hù)如果git add -A失敗例如 worktree 元數(shù)據(jù)被破壞工具不會(huì)強(qiáng)行刪除現(xiàn)場(chǎng)extractionFailed標(biāo)記會(huì)讓清理階段跳過 worktree 拆除并打印警告把工作樹與loop/${runId}分支留在磁盤上供人工恢復(fù)src/sandbox.ts。測(cè)試 sandbox.test.mjs 驗(yàn)證了這一行為。同時(shí)無論提取是否失敗鎖都會(huì)照常釋放——鎖的釋放與補(bǔ)丁提取是否成功無關(guān)src/sandbox.ts 對(duì)應(yīng)的測(cè)試。多循環(huán)安全--lock-paths 與 advisory lock單獨(dú)的沙箱運(yùn)行并不天然防止另一個(gè)排程循環(huán)同時(shí)編輯同一批文件。--lock-paths把本次運(yùn)行接入loop-worktree的 advisory lock鎖在 worktree 創(chuàng)建前獲取、運(yùn)行結(jié)束后釋放一旦有碰撞的排程循環(huán)想對(duì)重疊路徑持鎖其lock調(diào)用會(huì)響亮地失敗而不是靜默競(jìng)態(tài)見 tools/loop-sandbox/README.md 與 docs/multi-loop.md。鎖的底層實(shí)現(xiàn)在 tools/loop-worktree/src/lock.tspathsOverlap逐段比較兩個(gè) glob通配段*/**與任意內(nèi)容兼容例如src/**能覆蓋src/nested/foo.tslockPaths用跨進(jìn)程互斥文件.mutex原子wx創(chuàng)建串行化檢查-寫入臨界區(qū)支持--ttl過期與--wait等待等待中還會(huì)做死鎖環(huán)檢測(cè)。測(cè)試 sandbox.test.mjs 驗(yàn)證了三件事運(yùn)行期間鎖確實(shí)持有通過 marker 文件觀察到運(yùn)行中鎖存在結(jié)束后確實(shí)釋放另一 owner 持有重疊鎖時(shí)runInSandbox直接拒絕locked by owner other-loop且不會(huì)誤打印已釋放消息從未獲取過的鎖不聲稱釋放鎖釋放與 patch 提取成功與否無關(guān)。安全邊界這不是容器隔離關(guān)聯(lián)文檔與 tools/loop-sandbox/README.md 都明確警告這不是容器化的氣隙隔離air-gap。Agent 進(jìn)程保留完整的文件系統(tǒng)與網(wǎng)絡(luò)訪問權(quán)它可以逃逸出 worktree例如../../而 worktree 之外或.gitignored文件的改動(dòng)不會(huì)被捕獲進(jìn) patch。因此該工具是對(duì) docs/safety.md 的補(bǔ)充不能替代針對(duì)惡意代碼的 OS 級(jí)沙箱始終先審查 patch 再git apply——這正是 QUICKSTART 中week one: report only紀(jì)律的延續(xù)若需要更高置信度可在此基礎(chǔ)上疊加 loop-swarm多 Agent 共識(shí)連續(xù)在多個(gè)隔離 worktree 中運(yùn)行同一命令僅當(dāng)多數(shù)運(yùn)行產(chǎn)出字節(jié)級(jí)一致的 patch 才寫入consensus.patch。在 CI/CD 中集成loop-action 的 sandbox 開關(guān)loop-sandbox 已被 loop-actionGitHub Composite Action使用這也是關(guān)聯(lián)文檔點(diǎn)明包已發(fā)布并被使用、但新手只見 audit/init的原因。在 workflow 中開啟臨時(shí) worktree 隔離- uses: cobusgreyling/loop-engineering/tools/loop-actionmain with: pattern: ci-sweeper level: L2 sandbox: true # 路由到 loop-sandbox臨時(shí) worktree 隔離 patch 捕獲 sandbox-shell: false # loop-sandbox 兼容旋鈕默認(rèn)即可 command: | npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.mdcommand總是以bash -eo pipefail腳本形式執(zhí)行無論是否沙箱化sandbox-shell只控制 loop-sandbox 內(nèi)部是否再套一層--shell不影響你寫管道和多行腳本。注意安全紅線不要把 issue/PR 標(biāo)題、分支名等外部不可信內(nèi)容直接插值進(jìn)command存在命令注入風(fēng)險(xiǎn)。與本地跑法的對(duì)應(yīng)關(guān)系是sandbox: true≈npx cobusgreyling/loop-sandbox run -- bash -eo pipefail script。與其他工具的關(guān)系與定位loop-worktree底層的 worktree 生命周期與鎖管理器manifest、分支、advisory lock、gcloop-sandbox 直接復(fù)用它創(chuàng)建/銷毀工作樹并參與多循環(huán)鎖約定loop-audit / loop-init一個(gè)打分就緒度、一個(gè)腳手架屬于評(píng)估與初始化環(huán)節(jié)loop-sandbox 屬于執(zhí)行隔離環(huán)節(jié)是新用戶最容易忽略的 L2 安全組件loop-swarm基于 loop-sandbox 的升級(jí)形態(tài)用多 Agent 共識(shí)進(jìn)一步過濾非確定性編輯loop-context熔斷器決定是否繼續(xù)loop-sandbox 決定在哪里執(zhí)行。兩者相互獨(dú)立、可組合。對(duì)應(yīng)關(guān)系可參考 QUICKSTART.md 中從 L1僅報(bào)告→ L2worktree 內(nèi)的一次輔助修復(fù)→ L3無人值守的升級(jí)路徑進(jìn)入 L2 時(shí)loop-sandbox就是那個(gè)先隔離、后審查的執(zhí)行閘門。小結(jié)一條可直接落地的使用清單確認(rèn)在 git 倉(cāng)庫(kù)內(nèi)且.gitignore包含.loop-sandbox/與.loop-worktrees/用npx cobusgreyling/loop-sandbox run -- cmd運(yùn)行 AgentWindows 上npx無需--shell.cmd墊片遇ENOENT自動(dòng)重試需要 shell 內(nèi)建時(shí)加--shell需要并發(fā)保護(hù)時(shí)加--lock-paths配合--lock-owner/--lock-ttl/--lock-wait用loop-sandbox review列出 patch人工審查后再git apply牢記隔離邊界不是容器worktree 之外與.gitignored文件不在保護(hù)范圍內(nèi)惡意代碼請(qǐng)用 OS 級(jí)沙箱參見 docs/safety.md在 CI 中通過 loop-action 的sandbox: true復(fù)用同一套隔離機(jī)制。相關(guān)資源tools/loop-sandbox/README.md完整命令與示例、src/cli.ts參數(shù)解析、src/sandbox.ts核心實(shí)現(xiàn)、test/sandbox.test.mjs覆蓋隔離、二進(jìn)制 patch、鎖、信號(hào)清理的測(cè)試、docs/multi-loop.md多循環(huán)鎖約定。贊分享人工智能AI AgentAgent 工作流CLI研發(fā)協(xié)作AI 技能MCP 服務(wù)【免費(fèi)下載鏈接】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.項(xiàng)目地址https://gitcode.com/gh_mirrors/lo/loop-engineering點(diǎn)擊查看免費(fèi)下載相關(guān)推薦ZenML Sandbox 組件實(shí)戰(zhàn)在 Pipeline Step 內(nèi)為 AI Agent 提供隔離代碼執(zhí)行環(huán)境ZenML Sandbox 組件實(shí)戰(zhàn)在 Pipeline Step 內(nèi)為 AI Agent 提供隔離代碼執(zhí)行環(huán)境 Sandbox沙箱是 ZenML 中一類MLOps機(jī)器學(xué)習(xí)后端工作流自動(dòng)化AI AgentVoltAgent Blaxel 沙箱提供商用 voltagent/sandbox-blaxel 為 Agent 提供隔離的遠(yuǎn)程 Shell 執(zhí)行環(huán)境VoltAgent Blaxel 沙箱提供商用 voltagent/sandbox blaxel 為 Agent 提供隔離的遠(yuǎn)程 Shell 執(zhí)行環(huán)境 導(dǎo)讀人工智能AI AgentAgent 框架后端多智能體RAG工具調(diào)用Agent 記憶Agent 工作流AI 評(píng)測(cè)MCP 服務(wù)MCP Clients語音ZenML Modal Sandbox 實(shí)戰(zhàn)指南為 AI Agent 提供亞秒級(jí)冷啟動(dòng)的隔離代碼執(zhí)行環(huán)境ZenML Modal Sandbox 實(shí)戰(zhàn)指南為 AI Agent 提供亞秒級(jí)冷啟動(dòng)的隔離代碼執(zhí)行環(huán)境 本文圍繞 ZenML 的 Modal SandboxMLOps機(jī)器學(xué)習(xí)后端工作流自動(dòng)化AI Agent創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 loop-sandbox 實(shí)戰(zhàn)：用臨時(shí) git worktree 為 AI Agent 提供可審查的隔離執(zhí)行環(huán)境
人工智能AI AgentAgent 工作流CLI研發(fā)協(xié)作AI 技能MCP 服務(wù)【免費(fèi)下載鏈接】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.項(xiàng)目地址https://gitcode.com/gh_mirrors/lo/loop-engineering點(diǎn)擊查看免費(fèi)下載導(dǎo)讀loop-sandbox是 loop-engineering 倉(cāng)庫(kù)中面向無人值守 AI 循環(huán)loop的隔離執(zhí)行工具它把 Agent 的命令放進(jìn)一個(gè)臨時(shí) git worktree 中運(yùn)行自動(dòng)把 Agent 的改動(dòng)包括新增的未跟蹤文件捕獲成一份可審查的.patch文件然后立即銷毀工作樹讓你的主工作區(qū)始終保持干凈。本文以倉(cāng)庫(kù)中規(guī)劃該工具進(jìn)入 QUICKSTART 的 issue 文檔為骨架完整覆蓋安裝、命令參數(shù)、Windows 兼容、多循環(huán)鎖協(xié)作與源碼級(jí)實(shí)現(xiàn)原理讀完即可在任意 git 倉(cāng)庫(kù)中安全地讓 Agent 動(dòng)手改代碼。關(guān)聯(lián)文檔scripts/issue-bodies/quickstart-loop-sandbox.md。該 issue 的驗(yàn)收標(biāo)準(zhǔn)是用一段話講清臨時(shí) worktree 隔離、給出npx cobusgreyling/loop-sandbox run -- cmd及可選的--shell、說明 Windows 下 npm.cmd墊片遇到ENOENT會(huì)自動(dòng)重試、并鏈接到補(bǔ)丁審查與安全文檔——本文正是圍繞這四條驗(yàn)收標(biāo)準(zhǔn)展開并下沉到源碼。為什么需要 loop-sandbox無人值守 Agent 的直接風(fēng)險(xiǎn)直接在主工作樹里運(yùn)行無人值守的 AI Agent循環(huán)可能造成三類典型事故破壞主工作樹——Agent 的失敗嘗試會(huì)留下半成品改動(dòng)、沖突標(biāo)記甚至損壞的文件覆蓋未跟蹤文件——Agent 可能對(duì)未納入 git 管理的文件做出不可恢復(fù)的修改難以復(fù)盤——一次失敗的執(zhí)行嘗試可能摻雜大量噪音改動(dòng)事后很難把該保留的和該丟棄的拆開。loop-sandbox的核心解決思路是臨時(shí) worktree 隔離完整流程見 tools/loop-sandbox/README.md自動(dòng)為 Agent 創(chuàng)建一個(gè)隔離的 git worktreeAgent 在其中運(yùn)行命令像平時(shí)一樣自然地操作代碼庫(kù)命令結(jié)束后自動(dòng)把 Agent 的編輯包括新增的未跟蹤文件捕獲成一份干凈的.patch文件銷毀 worktree主倉(cāng)庫(kù)保持完全干凈。隨后由人工審查這份 patch一鍵git apply即可落地。正是這種先隔離、再捕獲、后審查的順序讓它成為 L2 及以上自治循環(huán)的推薦執(zhí)行底座——QUICKSTART 中把它編排在loop-worktree與安全工具之后而 loop-actionGitHub Composite Action也通過sandbox: true把 Agent 執(zhí)行路由進(jìn) loop-sandbox說明它已被發(fā)布并被 loop-action 使用但新手往往只看到 audit/init——這正是關(guān)聯(lián)文檔要補(bǔ)強(qiáng)的入口。安裝與前置條件安裝npm install -g cobusgreyling/loop-sandbox # 或直接用 npx 運(yùn)行無需全局安裝 npx cobusgreyling/loop-sandbox run -- command從 tools/loop-sandbox/package.json 可以看到包以bin暴露loop-sandbox命令要求 Node.js18核心依賴是cobusgreyling/loop-worktree工作樹創(chuàng)建、清單與鎖的底層實(shí)現(xiàn)。前置條件必須在 git 倉(cāng)庫(kù)內(nèi)運(yùn)行runInSandbox的第一步就是isGitRepo(root)檢查非倉(cāng)庫(kù)目錄會(huì)直接拋出loop-sandbox must be run inside a git repository.見 src/sandbox.ts。必須配置.gitignore把以下兩行加入項(xiàng)目.gitignore防止補(bǔ)丁文件與 worktree 清單被誤提交.loop-sandbox/ .loop-worktrees/.loop-sandbox/存放生成的 patch位于.loop-sandbox/patches/.loop-worktrees/是 loop-worktree 維護(hù) manifest 與工作樹的目錄。命令與參數(shù)參考loop-sandbox command [options]命令說明run [opts] -- cmd在隔離沙箱內(nèi)運(yùn)行一條 Agent 命令review/list列出已捕獲、待人工審查的補(bǔ)丁run支持的選項(xiàng)均來自 src/cli.ts 的實(shí)際解析邏輯選項(xiàng)說明--shell強(qiáng)制以shell: true運(yùn)行用于bash -c等 shell 內(nèi)建場(chǎng)景。在 Windows 上npm 安裝的.cmd墊片npx、tsc等遇到ENOENT時(shí)會(huì)自動(dòng)通過 shell 重試因此這里很少需要手動(dòng)指定--base branchworktree 基于的分支默認(rèn)取當(dāng)前HEAD所在分支--lock-paths globs逗號(hào)分隔的 glob在運(yùn)行期間對(duì)loop-worktree的 advisory lock 持鎖防止排程循環(huán)并發(fā)觸碰相同路徑。默認(rèn)關(guān)閉--lock-owner name鎖的所有者名默認(rèn)取本次運(yùn)行的生成 id--lock-ttl dur例如30m透?jìng)鹘oloop-worktree的--ttl--lock-wait dur例如5m透?jìng)鹘oloop-worktree的--wait注意run的子命令解析CLI 會(huì)先找到--分隔符src/cli.ts分隔符之前的參數(shù)按上表解析未知選項(xiàng)會(huì)報(bào)錯(cuò)退出分隔符之后才是真正要在沙箱里執(zhí)行的命令。缺少--或缺少命令都會(huì)得到明確的錯(cuò)誤提示。實(shí)戰(zhàn)示例讓 Agent 安全地運(yùn)行你的工具# 放心讓 Agent 跑 linter/formatter不會(huì)污染工作樹 npx cobusgreyling/loop-sandbox run -- npx my-agent運(yùn)行原始 shell 命令npx cobusgreyling/loop-sandbox run --shell -- bash -c echo hello test.txt與觸碰相同文件的排程循環(huán)并行npx cobusgreyling/loop-sandbox run --lock-paths src/**,docs/** -- npx my-agent審查并應(yīng)用補(bǔ)丁# 列出沙箱捕獲的所有補(bǔ)丁 npx cobusgreyling/loop-sandbox review # 示例輸出 # Loop Sandbox Patches # sandbox-82f1e394.patch (1.2 KB) # Apply: git apply .loop-sandbox/patches/sandbox-82f1e394.patch運(yùn)行成功后 CLI 同樣會(huì)打印兩條指引npx cobusgreyling/loop-sandbox review用于審查git apply 相對(duì)路徑用于立即應(yīng)用見 src/cli.ts。若無改動(dòng)則打印Run completed … No changes detected.并透?jìng)魍顺龃a。在git apply之前務(wù)必先人工審查補(bǔ)丁內(nèi)容詳見下文安全邊界。Windows 兼容npm.cmd墊片的 ENOENT 自動(dòng)重試關(guān)聯(lián)文檔的第三條驗(yàn)收標(biāo)準(zhǔn)專門強(qiáng)調(diào)這一點(diǎn)在 Windows 上npm 安裝的 CLInpx、tsc等實(shí)際是.cmd/.bat墊片spawn無法直接 exec 它們會(huì)報(bào)ENOENT。loop-sandbox 的處理是只在出現(xiàn)該特定錯(cuò)誤時(shí)自動(dòng)通過 shell 重試一次src/sandbox.tsif (!useShell !options.shell process.platform win32 err.code ENOENT) { supersededByRetry true; attempt(true); return; }為什么要精確到錯(cuò)誤碼、而不是無條件加--shell因?yàn)閺?qiáng)制shell: true會(huì)破壞依賴精確 argv 引用的命令例如node -e ...。自動(dòng)重試還帶有一個(gè)去競(jìng)態(tài)細(xì)節(jié)Windows 上失敗的 spawn 會(huì)在error事件后幾毫秒補(bǔ)發(fā)一個(gè)帶合成退出碼的close事件supersededByRetry標(biāo)記讓第一次非 shell嘗試的過期事件變成 no-op避免它在resolve()競(jìng)態(tài)中贏過重試的真實(shí)結(jié)果。因此在 Windows 上跑npx不需要額外傳--shell。源碼級(jí)原理一次沙箱運(yùn)行的生命周期runInSandbox(root, command, args, options)src/sandbox.ts的完整鏈路如下前置校驗(yàn)isGitRepo(root)確認(rèn)在 git 倉(cāng)庫(kù)內(nèi)生成運(yùn)行 idsandbox-${crypto.randomBytes(4).toString(hex)}作為分支名、鎖所有者名與 patch 文件名的唯一標(biāo)識(shí)準(zhǔn)備目錄創(chuàng)建.loop-sandbox/patches/解析 base 分支options.base優(yōu)先否則git rev-parse --abbrev-ref HEAD可選獲取 advisory locklockPaths({ root, owner, paths, ttl, wait })鎖在 worktree 創(chuàng)建之前獲取運(yùn)行結(jié)束之后釋放創(chuàng)建 worktree調(diào)用cobusgreyling/loop-worktree的createWorktree從 base 分支開出新分支loop/${runId}并檢出到.loop-worktrees/${runId}見 tools/loop-worktree/src/worktree.ts執(zhí)行命令spawn(command, args, { cwd: worktreeAbsPath, stdio: inherit, shell })Agent 輸出實(shí)時(shí)透?jìng)鞯浇K端捕獲改動(dòng)git add -A后檢查git diff --cached --stat有改動(dòng)則用git diff --cached --binary生成 patch 寫入.loop-sandbox/patches/${runId}.patch——使用--binary是故意的測(cè)試 sandbox.test.mjs 驗(yàn)證了二進(jìn)制文件如Buffer.from([0x00, 0xFF, ...])能精確捕獲并git apply還原不會(huì)發(fā)生 UTF-8 破壞清理git worktree remove --force刪除工作樹、git branch -D loop/${runId}刪除臨時(shí)分支、再調(diào)用 loop-worktree 的gc對(duì)賬孤兒工作樹與清單。信號(hào)安全與清理的只執(zhí)行一次清理邏輯值得單獨(dú)說明。CtrlCSIGINT/SIGTERM在任何執(zhí)行階段都可能觸發(fā)而清理必須在每條退出路徑上都執(zhí)行且只執(zhí)行一次src/sandbox.ts。實(shí)現(xiàn)上用單一cleanupPromise共享給所有信號(hào)處理器這樣即使信號(hào)重復(fù)觸發(fā)連按兩次 CtrlC后續(xù)信號(hào)也會(huì)等待同一份進(jìn)行中的清理完成后再process.exit(1)而不會(huì)在慢速的git worktree remove中途搶先退出、把一把沒有 TTL 的鎖遺留在磁盤上。測(cè)試 sandbox.test.mjs 專門用雙 SIGINT驗(yàn)證了清理必須完成、鎖必須釋放、.loop-worktrees下不得殘留sandbox-*目錄。清理順序也有講究先 kill 沙箱內(nèi)的子進(jìn)程防止它繼續(xù)寫入 worktree 或與受鎖路徑競(jìng)態(tài)再釋放鎖這是其他循環(huán)被阻塞的資源不應(yīng)被慢速的 worktree 拆除拖累最后拆除工作樹。補(bǔ)丁提取失敗時(shí)的數(shù)據(jù)保護(hù)如果git add -A失敗例如 worktree 元數(shù)據(jù)被破壞工具不會(huì)強(qiáng)行刪除現(xiàn)場(chǎng)extractionFailed標(biāo)記會(huì)讓清理階段跳過 worktree 拆除并打印警告把工作樹與loop/${runId}分支留在磁盤上供人工恢復(fù)src/sandbox.ts。測(cè)試 sandbox.test.mjs 驗(yàn)證了這一行為。同時(shí)無論提取是否失敗鎖都會(huì)照常釋放——鎖的釋放與補(bǔ)丁提取是否成功無關(guān)src/sandbox.ts 對(duì)應(yīng)的測(cè)試。多循環(huán)安全--lock-paths 與 advisory lock單獨(dú)的沙箱運(yùn)行并不天然防止另一個(gè)排程循環(huán)同時(shí)編輯同一批文件。--lock-paths把本次運(yùn)行接入loop-worktree的 advisory lock鎖在 worktree 創(chuàng)建前獲取、運(yùn)行結(jié)束后釋放一旦有碰撞的排程循環(huán)想對(duì)重疊路徑持鎖其lock調(diào)用會(huì)響亮地失敗而不是靜默競(jìng)態(tài)見 tools/loop-sandbox/README.md 與 docs/multi-loop.md。鎖的底層實(shí)現(xiàn)在 tools/loop-worktree/src/lock.tspathsOverlap逐段比較兩個(gè) glob通配段*/**與任意內(nèi)容兼容例如src/**能覆蓋src/nested/foo.tslockPaths用跨進(jìn)程互斥文件.mutex原子wx創(chuàng)建串行化檢查-寫入臨界區(qū)支持--ttl過期與--wait等待等待中還會(huì)做死鎖環(huán)檢測(cè)。測(cè)試 sandbox.test.mjs 驗(yàn)證了三件事運(yùn)行期間鎖確實(shí)持有通過 marker 文件觀察到運(yùn)行中鎖存在結(jié)束后確實(shí)釋放另一 owner 持有重疊鎖時(shí)runInSandbox直接拒絕locked by owner other-loop且不會(huì)誤打印已釋放消息從未獲取過的鎖不聲稱釋放鎖釋放與 patch 提取成功與否無關(guān)。安全邊界這不是容器隔離關(guān)聯(lián)文檔與 tools/loop-sandbox/README.md 都明確警告這不是容器化的氣隙隔離air-gap。Agent 進(jìn)程保留完整的文件系統(tǒng)與網(wǎng)絡(luò)訪問權(quán)它可以逃逸出 worktree例如../../而 worktree 之外或.gitignored文件的改動(dòng)不會(huì)被捕獲進(jìn) patch。因此該工具是對(duì) docs/safety.md 的補(bǔ)充不能替代針對(duì)惡意代碼的 OS 級(jí)沙箱始終先審查 patch 再git apply——這正是 QUICKSTART 中week one: report only紀(jì)律的延續(xù)若需要更高置信度可在此基礎(chǔ)上疊加 loop-swarm多 Agent 共識(shí)連續(xù)在多個(gè)隔離 worktree 中運(yùn)行同一命令僅當(dāng)多數(shù)運(yùn)行產(chǎn)出字節(jié)級(jí)一致的 patch 才寫入consensus.patch。在 CI/CD 中集成loop-action 的 sandbox 開關(guān)loop-sandbox 已被 loop-actionGitHub Composite Action使用這也是關(guān)聯(lián)文檔點(diǎn)明包已發(fā)布并被使用、但新手只見 audit/init的原因。在 workflow 中開啟臨時(shí) worktree 隔離- uses: cobusgreyling/loop-engineering/tools/loop-actionmain with: pattern: ci-sweeper level: L2 sandbox: true # 路由到 loop-sandbox臨時(shí) worktree 隔離 patch 捕獲 sandbox-shell: false # loop-sandbox 兼容旋鈕默認(rèn)即可 command: | npx grok-cli run --skill .grok/skills/ci-sweeper/SKILL.mdcommand總是以bash -eo pipefail腳本形式執(zhí)行無論是否沙箱化sandbox-shell只控制 loop-sandbox 內(nèi)部是否再套一層--shell不影響你寫管道和多行腳本。注意安全紅線不要把 issue/PR 標(biāo)題、分支名等外部不可信內(nèi)容直接插值進(jìn)command存在命令注入風(fēng)險(xiǎn)。與本地跑法的對(duì)應(yīng)關(guān)系是sandbox: true≈npx cobusgreyling/loop-sandbox run -- bash -eo pipefail script。與其他工具的關(guān)系與定位loop-worktree底層的 worktree 生命周期與鎖管理器manifest、分支、advisory lock、gcloop-sandbox 直接復(fù)用它創(chuàng)建/銷毀工作樹并參與多循環(huán)鎖約定loop-audit / loop-init一個(gè)打分就緒度、一個(gè)腳手架屬于評(píng)估與初始化環(huán)節(jié)loop-sandbox 屬于執(zhí)行隔離環(huán)節(jié)是新用戶最容易忽略的 L2 安全組件loop-swarm基于 loop-sandbox 的升級(jí)形態(tài)用多 Agent 共識(shí)進(jìn)一步過濾非確定性編輯loop-context熔斷器決定是否繼續(xù)loop-sandbox 決定在哪里執(zhí)行。兩者相互獨(dú)立、可組合。對(duì)應(yīng)關(guān)系可參考 QUICKSTART.md 中從 L1僅報(bào)告→ L2worktree 內(nèi)的一次輔助修復(fù)→ L3無人值守的升級(jí)路徑進(jìn)入 L2 時(shí)loop-sandbox就是那個(gè)先隔離、后審查的執(zhí)行閘門。小結(jié)一條可直接落地的使用清單確認(rèn)在 git 倉(cāng)庫(kù)內(nèi)且.gitignore包含.loop-sandbox/與.loop-worktrees/用npx cobusgreyling/loop-sandbox run -- cmd運(yùn)行 AgentWindows 上npx無需--shell.cmd墊片遇ENOENT自動(dòng)重試需要 shell 內(nèi)建時(shí)加--shell需要并發(fā)保護(hù)時(shí)加--lock-paths配合--lock-owner/--lock-ttl/--lock-wait用loop-sandbox review列出 patch人工審查后再git apply牢記隔離邊界不是容器worktree 之外與.gitignored文件不在保護(hù)范圍內(nèi)惡意代碼請(qǐng)用 OS 級(jí)沙箱參見 docs/safety.md在 CI 中通過 loop-action 的sandbox: true復(fù)用同一套隔離機(jī)制。相關(guān)資源tools/loop-sandbox/README.md完整命令與示例、src/cli.ts參數(shù)解析、src/sandbox.ts核心實(shí)現(xiàn)、test/sandbox.test.mjs覆蓋隔離、二進(jìn)制 patch、鎖、信號(hào)清理的測(cè)試、docs/multi-loop.md多循環(huán)鎖約定。贊分享人工智能AI AgentAgent 工作流CLI研發(fā)協(xié)作AI 技能MCP 服務(wù)【免費(fèi)下載鏈接】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.項(xiàng)目地址https://gitcode.com/gh_mirrors/lo/loop-engineering點(diǎn)擊查看免費(fèi)下載相關(guān)推薦ZenML Sandbox 組件實(shí)戰(zhàn)在 Pipeline Step 內(nèi)為 AI Agent 提供隔離代碼執(zhí)行環(huán)境ZenML Sandbox 組件實(shí)戰(zhàn)在 Pipeline Step 內(nèi)為 AI Agent 提供隔離代碼執(zhí)行環(huán)境 Sandbox沙箱是 ZenML 中一類MLOps機(jī)器學(xué)習(xí)后端工作流自動(dòng)化AI AgentVoltAgent Blaxel 沙箱提供商用 voltagent/sandbox-blaxel 為 Agent 提供隔離的遠(yuǎn)程 Shell 執(zhí)行環(huán)境VoltAgent Blaxel 沙箱提供商用 voltagent/sandbox blaxel 為 Agent 提供隔離的遠(yuǎn)程 Shell 執(zhí)行環(huán)境 導(dǎo)讀人工智能AI AgentAgent 框架后端多智能體RAG工具調(diào)用Agent 記憶Agent 工作流AI 評(píng)測(cè)MCP 服務(wù)MCP Clients語音ZenML Modal Sandbox 實(shí)戰(zhàn)指南為 AI Agent 提供亞秒級(jí)冷啟動(dòng)的隔離代碼執(zhí)行環(huán)境ZenML Modal Sandbox 實(shí)戰(zhàn)指南為 AI Agent 提供亞秒級(jí)冷啟動(dòng)的隔離代碼執(zhí)行環(huán)境 本文圍繞 ZenML 的 Modal SandboxMLOps機(jī)器學(xué)習(xí)后端工作流自動(dòng)化AI Agent創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考