Sandcastle 是一個用於編排沙盒 AI 程式開發 Agent 的 TypeScript 函式庫

Sandcastle 是一個用於編排沙盒 AI 程式開發 Agent 的 TypeScript 函式庫。

Sandcastle 是一個專為解決 AI 程式開發 Agent 在隔離環境中平行執行困難而設計的 TypeScript 函式庫，透過 Docker 容器與 Git 工作樹 (worktree) 架構，實現了 100% 本地化的自動化開發流程。

核心架構與運作機制
Sandcastle 的設計核心在於簡化 Agent 的執行與管理，其運作機制如下：

• 工作樹架構：利用 Git 工作樹在主機上建立隔離環境，並透過 Docker 進行綁定掛載 (bind-mount)，讓 Agent 直接寫入主機檔案系統，無需額外的同步操作。
• 自動化合併：執行完成後，系統會自動將 Agent 在臨時分支上的提交合併回目標分支，並清理工作樹。
• 程式開發 Agent 支援：透過 sandcastle.run() 函數，使用者可以輕鬆呼叫 Agent，並設定 maxIterations（最大迭代次數）、model（模型選擇）及 hooks（生命週期鉤子）等參數。

靈活的提示詞系統
Sandcastle 提供了一套不預設工作流或任務管理的靈活提示詞系統，讓開發者能高度自訂 Agent 行為：

• 動態上下文：支援在提示詞中使用 !command 語法，在執行前透過 shell 指令動態獲取外部資訊（如 GitHub issues 或 Git log）。
• 參數注入：透過 {{KEY}} 佔位符注入自訂參數，並內建 {{SOURCE_BRANCH}} 與 {{TARGET_BRANCH}} 等變數，確保 Agent 在正確的分支環境下運作。
• 提前終止機制：支援設定 completionSignal，當 Agent 輸出特定字串（預設為 <promise>COMPLETE</promise>）時，即可提前結束迭代循環。

開發者體驗與配置
為了降低使用門檻，Sandcastle 提供了完整的 CLI 工具與模板系統：

• 初始化與模板：執行 sandcastle init 可快速建立 .sandcastle/ 配置目錄，並提供 blank、simple-loop、sequential-reviewer 及 parallel-planner 等四種預設模板，涵蓋從簡單任務到複雜程式碼審查的各類工作流。
• 環境隔離：透過自訂 .sandcastle/Dockerfile，開發者可以精確控制沙盒環境，確保 Agent 擁有執行任務所需的正確依賴與配置。
• 生命週期管理：支援 onSandboxReady 鉤子，允許在掛載後自動執行如 npm install 等初始化指令，確保環境準備就緒。