把云端编码 Agent 接进现有仓库：Hoplite 的 Sandbox、审批与 PR 交付链路
把编码 Agent 放到云端，最容易被忽略的问题并不是“它能不能改代码”，而是它如何获得可运行的项目环境、如何在改动发生前停下来等待人确认，以及如何把一次对话收束为可审查的 Pull Request。若这些环节没有明确边界，Agent 很可能只能给出 diff，或在无法复现本地依赖、环境变量和启动方式的沙箱里反复失败。
Hoplite 是一套面向 GitHub 仓库的云端编码 Agent 平台。它把工作单元拆成 workspace、project、thread、run 与 sandbox：workspace 承载团队成员和账单；project 绑定一个仓库及其基准分支；thread 是围绕该项目的一次持续对话；每条消息产生一个 run；每个 thread 则拥有独立 sandbox、diff 和 PR。这个拆分的价值在于：仓库配置可复用，任务上下文和运行环境却不会彼此混在一起。
本文不把它当作“自动写代码”的黑盒，而是从交付链路看它适合解决什么问题、需要哪些仓库准备，以及如何避免把云端 Agent 变成权限过大的远程脚本。
先把问题定义成一条可验证的交付链
一个可靠的云端任务应能回答四个问题：Agent 从哪一个分支开始？它用什么命令安装依赖并启动服务？哪些操作必须由人批准？最终怎样回到 GitHub 的代码审查流程？
Hoplite 的基本路径是：安装 GitHub App 并选择仓库，创建 project；在 project 中新建 thread 并描述任务；平台在从仓库克隆出来的隔离 sandbox 中执行 Agent；Agent 读取、编辑代码，运行测试或开发服务器，并可在内置浏览器中检查预览；完成后创建 draft 或 ready PR。因为 thread 对应独立 sandbox，所以一次修复登录表单的任务，不会天然继承另一个重构任务的未提交工作区。
这里的关键不是“隔离”这个词本身，而是隔离环境仍要能够运行项目。只给 Agent 源码而没有依赖安装命令、端口和检查命令，通常只会让它在猜测中消耗上下文。因此，先把项目最小可运行路径写进仓库，比把提示词写得更长更重要。
用 .hoplite/settings.json 让环境可重复
Hoplite 文档建议在仓库中提交 .hoplite/settings.json。其中的 setup 在克隆后、Agent 开始工作前运行；run 在预览启动时运行；check 可作为测试或类型检查命令；diagnostics 则可在每次编辑后运行，并用 {FILE} 接收刚编辑的文件路径。
下面是一个 Node 服务加前端开发服务器的示例。命令只是示范，应该替换为项目已经在 CI 或本地验证过的命令：
{
"version": 1,
"ports": {
"preview": 3000,
"additional": { "api": 8787 }
},
"scripts": {
"setup": {
"enabled": true,
"command": "pnpm install --frozen-lockfile && pnpm db:migrate"
},
"run": {
"enabled": true,
"command": "pnpm dev"
},
"check": {
"enabled": true,
"command": "pnpm test && pnpm typecheck"
},
"diagnostics": {
"enabled": true,
"command": "pnpm eslint {FILE}"
}
},
"mcpServers": []
}
不要把这里当成新的部署配置层。它更像 Agent 沙箱的运行契约：setup 应是非交互式、可重复的；运行时、包管理器和数据库依赖应由锁文件、版本文件或 setup 命令明确声明。文档还说明 project 可以在平台侧设置覆盖项；平台覆盖优先于仓库文件，仓库文件再优先于默认值。团队应把“哪些设置必须随代码审查”放在仓库里，把短期实验或项目级例外留在平台侧，并定期比对两者，避免同一任务在不同入口得到不同环境。
机密能注入，不等于可以忽略最小权限
project 可配置环境变量，Hoplite 会将其注入该 sandbox 中 Agent 执行的 setup、测试、开发服务器和临时 shell 命令。平台文档称变量值会加密存储，保存后界面不会再次展示具体值；这意味着它适合放测试数据库地址、功能开关或访问测试服务的 API key，却不意味着任何密钥都应被交给 Agent。
一个实用做法是建立专用的最小权限凭据：只允许访问测试环境，限制数据库账号的写权限，避免放入生产云账号、组织级 token 或可发布软件包的凭据。需要查看某个已保存值时，文档建议轮换而不是尝试读回；这也促使团队把密钥恢复流程设计成可轮换的流程。对 Agent 来说，能运行测试所需的权限与能部署生产环境的权限应当是两套东西。
审批不是事后审计，而是执行前的控制面
在 thread 的活动时间线中，文件读写、编辑、shell 命令、浏览器动作和 GitHub 操作会实时出现。Hoplite 会对文件写入与编辑、patch、shell 命令、终止进程、重启或缩小 sandbox，以及创建、评论、合并 PR 等会改变 GitHub 状态的动作请求批准。人可以批准或拒绝单个动作；任务运行中发出的后续消息会按顺序排队，也可以用 /stop 中止当前 run。
这使审批更适合放在高风险边界，而不是要求人逐行确认每一个普通读操作。例如，允许 Agent 读取仓库、运行静态检查和生成 diff；要求确认涉及依赖升级、迁移脚本、外部网络调用或 PR 写入的操作。审批规则如果过宽，自动化失去价值；如果过松，审查就退化为事后发现问题。较好的起点是先对写入、shell 与 GitHub 变更保持严格控制，在项目的 setup 与 check 稳定后再逐步调整。
从本地会话接力，而不是复制粘贴上下文
对于已经在本地用 Claude Code、Codex 或 OpenCode 开始的任务，Hoplite CLI 提供 onboard 与 handoff。官方文档给出的 Linux/macOS 安装路径之一是：
curl -fsSL https://hoplite.sh/install.sh | sh hoplite onboard
onboard 会扫描支持工具的本地会话历史并让用户选择导入。完成认证后，在目标仓库中运行：
hoplite handoff
它会选择该仓库最近活跃的本地会话，把用户与助手对话作为附件交给云端 thread，并在当前分支上开始云端任务。官方明确说明，工具输出与隐藏推理保持在本地；若本地存在未提交或未推送内容，默认不会自动带到云端。只有显式使用 --autopush，才会提交并推送本地改动。因此，接力前应先检查 git status、确认分支和远端可见性；不要把 handoff 误解为复制完整本地工作目录。
失败模式：先诊断环境，再修改业务代码
云端 Agent 最常见的低质量循环，是在依赖安装失败、迁移未执行、预览端口错误或缺少测试变量时，连续修改业务逻辑来“修复”一个根本不是业务代码的问题。为此可以把任务拆成两个验收阶段：第一阶段只确认 setup、run 和 check 是否在空白 sandbox 成功；第二阶段才允许实现需求并创建 PR。若第一阶段失败，要求 Agent 输出失败命令、日志位置和最小复现条件，而不是继续扩散改动。
也应避免把诊断命令写成会改变共享状态的脚本。迁移、种子数据、外部 API 调用和缓存清理最好使用测试环境、幂等命令或显式的 mock 开关。这样即使 Agent 因审批被中断、thread 需要重试，团队也能区分“代码变更造成的问题”和“环境准备不一致造成的问题”。可复现的失败报告往往比一次勉强通过的预览更有价值：它能被维护者在本地和 CI 中验证，并沉淀为下一次 sandbox 配置的修复项。
把 PR 当作交付物，而不是运行结束的副产品
Agent 完成一轮 run 并不代表变更可以合并。Hoplite 的 PR rail 将分支、状态检查、审查意见和未解决评论聚合在 thread 旁；审查意见可被带回对话，作为下一轮修复的上下文。GitHub App 负责仓库访问、分支、提交、PR 与 review webhook，而 PR 创建、评论、合并等改变远端状态的操作仍需要审批。
因此，一条更稳妥的团队流程是：先让 Agent 在 thread 中完成最小改动和 check；确认 diff 与预览；创建 draft PR；让常规 CI 和人工 reviewer 进入流程；把失败检查或评论作为下一次 thread 输入；最后再批准合并。这样云端 Agent 负责缩短“从任务到可审查改动”的时间，而现有的 CI、分支保护和代码审查仍然是质量门。
适用边界：把它用于可复现工程，不用于模糊授权
Hoplite 适合已有 GitHub 工作流、可通过脚本启动和验证、且愿意把 Agent 行为纳入审批与 PR 审查的团队。它尤其适合依赖更新、缺陷修复、测试补充、例行排查和按 webhook 或定时触发的维护任务。自动化任务会按预设 prompt 在项目中启动新的 Agent run，因此 prompt 应明确目标、约束和“完成”的判据；例如测试失败时停止并报告，而不是强行修改到测试通过。
它不适合拿来绕过仓库权限、代替生产变更审批，或在没有可运行环境的项目中期待一次性解决全部构建问题。真正决定效果的仍是仓库契约：可重复 setup、明确 check、最小化密钥、可审查 diff，以及不会把“Agent 已结束”误认为“代码已经安全交付”。