【免费下载链接】sandcastleOrchestrate sandboxed coding agents in TypeScript with sandcastle.run()项目地址https://gitcode.com/gh_mirrors/sandcastl/sandcastle点击查看免费下载本文以 Sandcastle 仓库内置模板sequential-reviewer的实现阶段提示词 implement-prompt.md 为骨架结合其编排代码 main.mts、审查提示词 review-prompt.md 与核心运行时 run.ts完整讲解如何在沙箱中驱动一个名为 RALPH 的自主编码 Agent按优先级逐个处理 issue、以 RGR 红绿重构循环产出可验证提交、再由第二个 Agent 在同一分支上做代码审查。读完本文你将掌握该模板提示词的每一段设计意图、底层占位符与完成信号的实现机制并能据此定制自己的 issue 攻坚 Agent。模板定位实现与审查分离的两阶段循环sequential-reviewer是 Sandcastle 提供的五种初始化模板之一见 README 的模板对照表定位是逐个实现 issue并在每个 issue 之后附加一次代码审查的中间复杂度方案——介于无审查门槛的simple-loop与带规划阶段、并发执行的parallel-planner之间。其元数据定义在 template.jsonImplements issues one by one, with a code review step after each。模板的驱动代码 main.mts 把每个 issue 拆成两个阶段阶段一Implement一个 sonnet 模型 Agent 挑选下一个开放 issue在独立分支上实现并提交输出promiseCOMPLETE/promise完成信号阶段二Review第二个 sonnet Agent 审查同一分支的 diff要么批准要么直接在分支上做修正并提交。两阶段共享同一个由sandcastle.createSandbox({ branch, ... })创建的沙箱因此实现者与审查者操作的是同一个显式命名的分支main.mts。外层for循环最多重复MAX_ITERATIONS默认 10次每次只处理一个 issue当实现阶段没有产生任何提交implement.commits.length 0时提前退出表示积压问题已清空或全部被阻塞main.mts。for (let iteration 1; iteration MAX_ITERATIONS; iteration) { const branch sandcastle/sequential-reviewer/${Date.now()}; const sandbox await sandcastle.createSandbox({ branch, sandbox: docker(), hooks, // onSandboxReady: npm install copyToWorktree, // [node_modules] }); try { const implement await sandbox.run({ name: implementer, maxIterations: 1, // 一次只实现一个 issue交给审查者 agent: sandcastle.claudeCode(claude-sonnet-4-6), promptFile: ./.sandcastle/implement-prompt.md, // 本文主角 }); if (!implement.commits.length) { /* 停止 */ break; } await sandbox.run({ name: reviewer, maxIterations: 1, agent: sandcastle.claudeCode(claude-sonnet-4-6), promptFile: ./.sandcastle/review-prompt.md, promptArgs: { BRANCH: branch }, // 告诉审查者要看哪个分支 }); } finally { await sandbox.close(); } }提示词三段式结构Context → Task → Doneimplement-prompt.md 采用与 Sandcastle 提示词骨架templates.ts 中的SKELETON_PROMPT一致的上下文 → 任务 → 完成三段式结构整份文件仅 53 行却同时承载了动态数据注入、Agent 角色定义、行为约束与停机协议四重职责。Context动态上下文与唯一事实来源提示词开头的Context段落包含两个动态注入块开放问题列表!{{LIST_TASKS_COMMAND}}。以反引号包裹的 shell 表达式会在沙箱内、每次迭代开始时被执行求值README 在 promptArgs 一节 与 simple-loop 模板注释中均有说明把执行结果直接嵌入提示词。提示词随后强调这个列表已经过过滤仅包含可以开工的 issue是工作存在的唯一事实来源sole source of truth——明确禁止 Agent 自行运行未过滤的查询去寻找更多 issue列表为空就是没有可做的事。这一约束防止了 Agent 偏离积压清单、自行扩大工作范围。最近 RALPH 提交!git log --oneline --grepRALPH -10。列出最近 10 条以RALPH为前缀的提交为 Agent 提供项目历史与提交风格参考也为下面的提交消息必须以RALPH:开头规则提供可见的样例。Task角色、优先级与工作流Task段落把 Agent 人格化为RALPH——一个逐 issue 工作的自主编码 Agent。这一定义与 main.mts 注释中Phase 1 (Implement)的描述完全对应。优先级顺序是本提示词最核心的业务规则四档依次递减Bug fixes——影响用户的损坏行为Tracer bullets——证明方案可行的薄端到端切片Polish——改进既有功能错误消息、UX、文档Refactors——无用户可见变化的内部清理规则要求挑选优先级最高且不被其他开放 issue 阻塞的那个 issue。工作流定义了六步形成完整闭环Explore——仔细阅读 issue如有引用则拉取父级 PRD写任何代码之前先读相关源码与测试Plan——决定改什么、为什么改并尽量缩小改动面Execute——使用RGRRed → Green → Repeat → Refactor先写一个失败的测试再写实现让它通过Verify——提交前必须运行npm run typecheck与npm run test先修复一切失败再继续Commit——打一个单独的 git 提交提交消息必须以RALPH:前缀开头包含完成的任务与任何 PRD 引用列出关键决策列出变更的文件注明下一迭代的阻塞项Close——用{{CLOSE_TASK_COMMAND}}关闭 issue 并说明所做的工作。Rules防止越界的三条铁律一次迭代只做一个 issue不得在一次迭代中尝试多个 issue未提交修复并通过测试之前不得关闭 issue已提交代码中不得残留注释掉的代码或 TODO 注释若被阻塞缺少上下文、无法修复的失败测试、外部依赖在 issue 上留言并继续不要关闭它。Done完成信号协议提示词结尾定义停机协议当所有可处理的 issue 都完成或全部被阻塞或提示词顶部的开放问题块为空时输出完成信号promiseCOMPLETE/promise完成信号的底层机制promiseCOMPLETE/promise并非提示词的自定义发明而是 Sandcastle 运行时的默认完成信号。在 Orchestrator.ts 中定义DEFAULT_COMPLETION_SIGNAL promiseCOMPLETE/promiserun()的completionSignal选项缺省时即使用它run.ts。机制是运行时会持续累积 Agent 输出当检测到该信号字符串时提前结束迭代循环RunResult.completionSignal返回实际命中的信号run.ts。配套机制是completion timeout默认 60 秒见 run.tsAgent 输出信号后若因其衍生的gh/git 子进程或长驻 MCP 服务器占住 stdout 而迟迟不退出Sandcastle 会在宽限窗口结束后仍以成功解析运行result.commits与result.completionSignal照常填充README 的 Hanging processes after the completion signal 一节详述了该设计。这正是 main.mts 中实现 Agent 通过promiseCOMPLETE/promise报告完成这一注释的运行时依据。另一个关键点是main.mts 判断有没有活儿看的不是完成信号而是implement.commits.length。即使 Agent 正常结束只要没有产生提交外层循环就认为积压已清空或全部被阻塞并终止。这与提示词中列表为空就没有可做的事相互印证形成提示词与编排代码之间的契约提示词负责让 Agent 不虚报完成编排代码负责以提交产物为准决定是否继续。占位符与动态注入{{...}} 与 !...的两种展开提示词中的{{LIST_TASKS_COMMAND}}、{{CLOSE_TASK_COMMAND}}属于promptArgs 占位符替换由promptArgs选项提供键值映射run.ts。运行时在把提示词交给 Agent 之前用substitutePromptArgs把所有{{KEY}}替换为对应值缺少匹配值的占位符是错误多余的参数则产生警告PromptArgumentSubstitution.ts 与 README promptArgs 一节。这两个占位符的真实值由初始化流程按所选 issue tracker 注入。在 InitService.ts 的 issue tracker 注册表中GitHub Issuesgithub-issuesLIST_TASKS_COMMAND为gh issue list --state open --label Sandcastle --limit 100 --json number,title,body,labels,comments --jq ...CLOSE_TASK_COMMAND为gh issue close ID --comment Completed by SandcastleBeadsbeads分别为bd ready --json与bd close ID --reasonCompleted by SandcastleCustom初始为刻意坏掉的哨兵值echo No issue tracker configured... 2; exit 1由配置 Agent 就地替换。!command则是**shell 表达式展开**在沙箱内、每次迭代开始时执行结果嵌入提示词README [promptArgs 一节](https://link.gitcode.com/i/a8bec93c4b4bba96cd71ac614f95cdbf) 还指出只对提示词文件中书写的 shell 块执行展开经 promptArgs 传入的文本即使形似!... 也按惰性文本处理从而安全地透传 issue 标题、PR 描述等用户内容。这两套机制共同支撑了提示词每次迭代看到最新数据的能力。review-prompt.md中还有一个值得注意的用法{{BRANCH}}由 main.mts 通过promptArgs: { BRANCH: branch }传入审查者据此对指定分支执行git diff {{TARGET_BRANCH}}...{{BRANCH}}与git log {{TARGET_BRANCH}}..{{BRANCH}} --oneline。其中{{TARGET_BRANCH}}是运行时自动注入的两个内置占位符之一另一个是{{SOURCE_BRANCH}}见 run.ts 与 README Built-in prompt arguments开发者禁止在promptArgs中覆盖它们。审查阶段如何与实现阶段衔接实现 Agent 提交后审查者 Agent 收到 review-prompt.md其审查标准与 implement-prompt 的产出规范形成闭环理解变更先读 diff 与提交理解意图分析改进点降低不必要的复杂度与嵌套、消除冗余代码与抽象、改善命名、合并相关逻辑、删除描述显而易见代码的注释、避免嵌套三元优先 switch 或 if/else 链、选择清晰胜过简短检查正确性实现是否匹配意图、边界情况是否处理、新行为是否被测试覆盖、是否存在不安全 cast /any/ 未校验假设、是否引入注入漏洞、凭据泄露等安全问题保持平衡避免过度简化损害可读性、避免过于取巧的方案、避免把过多关注点塞进单个函数遵循项目规范通过.sandcastle/CODING_STANDARDS.md引用加载编码规范——模板自带的 CODING_STANDARDS.md 是带注释的占位文件注释明确说明该文件由审查 Agent 在审查期间加载以强制执行规范不消耗实现阶段的 token。这解释了为何实现提示词本身不内嵌编码规范而把它留给审查阶段保持功能不变只改怎么做不改做什么。审查者若发现可改进之处直接在分支上修改、运行测试与类型检查、提交并描述改进若代码已足够干净则什么都不做最后同样输出promiseCOMPLETE/promisereview-prompt.md 的 EXECUTION 段。与相邻模板的对比定位与取舍理解这个提示词最好的参照系是它的两个邻居README 模板表simple-loop的 prompt.md 与 implement-prompt.md 几乎逐字相同同样的 RALPH 人格、同样的优先级四档、同样的六步工作流与RALPH:提交前缀——区别在于它没有独立的审查阶段编排代码直接await run({...})循环处理 issue见 simple-loop/main.mts。sequential-reviewer 之所以把这份提示词冠以implement-前缀正是因为同样的实现提示词被复用在带审查的流水线中需要与review-prompt.md配对。parallel-planner则把提示词拆分得更细plan / implement / merge 三份并发执行多个实现 Agent每份 implement-prompt 通过promptArgs注入TASK_ID、ISSUE_TITLE、BRANCH三个占位符parallel-planner/main.mts其实现提示词并不包含优先级排序——那是规划阶段的职责。换言之implement-prompt.md 的逐个 issue、优先级排序、RGR、单提交、RALPH:前缀是一套可复用的实现阶段行为契约模板之间通过编排代码要不要审查、要不要规划、要不要并发彼此区分。实操把这份提示词用起来按照仓库约定sandcastle init会为你搭建.sandcastle/目录把模板文件含 implement-prompt.md拷贝进去README 模板选择 与 文件约定 说明模板通过promptFile: .sandcastle/prompt.md显式引用并非自动回退。运行方式npx tsx .sandcastle/main.mts # 或把脚本写进 package.jsonsandcastle: npx tsx .sandcastle/main.mts实际运行时你需要准备可用的沙箱提供方模板默认使用docker()也可换 Podman、Vercel 或 no-sandboxREADME SandboxProvider 表已配置的 issue tracker确保LIST_TASKS_COMMAND/CLOSE_TASK_COMMAND指向真实命令GitHub 需配置GH_TOKEN等环境变量见 InitService.ts 的 envExample 说明模型密钥与依赖沙箱onSandboxReady钩子会先执行npm installcopyToWorktree: [node_modules]则把宿主依赖预拷贝进工作树以加速启动main.mts。自定义提示词时保持三段式骨架与两条协议不变即可平滑对接运行时动态上下文用!cmd与{{KEY}}注入收尾用promiseCOMPLETE/promise停机提交用RALPH:前缀记账产物以commits为准。这样无论你如何调整优先级、工作流或规则Agent 的行为都会被沙箱、测试门禁与完成信号完整约束在可控范围内。赞分享【免费下载链接】sandcastleOrchestrate sandboxed coding agents in TypeScript with sandcastle.run()项目地址https://gitcode.com/gh_mirrors/sandcastl/sandcastle点击查看免费下载相关推荐Sandcastle sequential-reviewer 模板解析基于 review-prompt.md 的代码评审 Agent 设计Sandcastle sequential reviewer 模板解析基于 review prompt.md 的代码评审 Agent 设计 导读 本文以 saPlate 如何把 CSV 数据转换为编辑器中的表格Plate 如何把 CSV 数据转换为编辑器中的表格 如果你手上有 CSV 格式的文本比如导出的报表、带表头的结构化数据想在 Plate 富文本编辑器中在 Sandcastle 的 Sequential Reviewer 模板中配置编码标准让审查 Agent 自动执行项目规范在 Sandcastle 的 Sequential Reviewer 模板中配置编码标准让审查 Agent 自动执行项目规范 本指南围绕 Sandcastle上一篇Windows上安装APK的终极指南告别模拟器5步实现安卓应用无缝运行下一篇TV Bro浏览器3天让您的Android电视变身全能上网终端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
