hosted-agents

托管式 Agent 基础设施

托管式 Agent 在远程沙盒环境中运行，而不是在本地计算机上运行。设计得当时，它们可以提供无限并发、一致的执行环境和多人协作。关键在于，会话速度应仅受模型提供商的首个 Token 响应时间限制；所有基础设施设置都应在用户开始会话前完成。

何时启用

在以下情况下启用此技能：

• 构建可独立于用户设备运行的后台编码 Agent
• 为 Agent 工作负载设计沙盒执行环境
• 实现具有共享状态的多人 Agent 会话
• 创建多客户端 Agent 界面（Slack、Web、Chrome 扩展）
• 将 Agent 基础设施扩展到本地计算机的限制之外
• 构建 Agent 可生成子 Agent 并行工作的系统

对于由其他技能负责的相关工作，不要启用此技能：

• 设计自主研究循环、新颖性门控、回滚策略或合并边界：harness-engineering。
• 在不涉及托管基础设施的情况下选择监督者、集群或交接拓扑：multi-agent-patterns。
• 设计托管式 Agent 使用的工具，例如生成/状态工具或 PR 工具：tool-design。
• 管理会话内的文件持久化状态，而不是托管运行时本身：filesystem-context。

核心概念

将 Agent 执行迁移到远程沙盒环境，以消除本地执行的根本限制：资源争用、环境不一致和单用户约束。远程沙盒可以实现无限并发、可复现的环境和协作式工作流，因为每个会话都拥有独立的计算资源和已验证可用的环境映像。

将架构设计为三个层次，因为每一层都可以独立扩展。构建用于隔离执行的沙盒基础设施、用于状态管理和客户端协调的 API 层，以及用于跨平台用户交互的客户端界面。保持这些层清晰分离，避免沙盒变更波及客户端。

详细主题

沙箱基础设施

核心挑战 消除沙箱启动延迟，因为用户会觉得任何超过几秒的等待都像是系统故障。开发环境需要克隆代码仓库、安装依赖项并运行构建步骤——这些工作都应在用户提交提示词之前完成。

镜像注册表模式 定期预构建环境镜像（每 30 分钟一次效果不错），这样与最新代码同步时只需快速应用增量，而不必完整克隆。每个镜像应包含：

• 克隆到已知提交版本的代码仓库
• 已安装的所有运行时依赖项
• 已完成的初始设置和构建命令
• 已运行一次的应用和测试套件缓存文件

启动会话时，从最新镜像启动沙箱。代码仓库最多落后 30 分钟，因此剩余的 Git 同步很快。

快照与恢复 在关键节点创建文件系统快照，以便后续提示词能立即恢复环境，而无需重新运行设置：

• 初始镜像构建完成后（基础快照）
• Agent 完成更改后（会话快照）
• 沙箱退出前，以备后续使用

后台 Agent 的 Git 配置 在每个沙箱中显式配置 Git 身份，因为后台 Agent 在构建镜像期间并不绑定到特定用户：

• 在克隆期间生成 GitHub 应用安装令牌，以访问代码仓库
• 提交和推送更改时设置 Git 配置 user.name 和 user.email
• 提交时使用发起提示词的用户身份，而非应用身份

预热池策略 对于高流量代码仓库，维护一个预热沙箱池，因为冷启动是用户最主要的不满来源：

• 在用户开始会话前准备好沙箱
• 新镜像构建完成后，使池中的条目过期并重新创建
• 用户一开始输入，就启动沙箱预热（预测性预热）

Agent 框架选择

服务端优先架构 首先将 Agent 框架设计为服务，再将 TUI 和桌面应用作为轻量客户端，因为这样可以避免在不同交互界面中重复实现 Agent 逻辑：

• 多个自定义客户端共用一个 Agent 后端
• 在所有交互界面中保持行为一致
• 插件系统可在不更改客户端的情况下扩展功能
• 事件驱动架构可向任何已连接的客户端提供实时更新

代码作为事实来源 选择能让 Agent 读取自身源代码以了解其行为的框架。应优先考虑这一点，因为以代码为事实来源可以防止 Agent 对自身能力产生幻觉——这是 AI 开发中一个常被低估的故障模式。

插件系统要求 要求插件系统支持运行时拦截，因为这样无需修改 Agent 核心逻辑，就能实现安全控制和可观测性：

• 监听工具执行事件（例如，tool.execute.before）
• 有条件地阻止或修改工具调用
• 在运行时注入上下文或状态

速度优化

预测性预热 用户开始输入提示词时就开始预热沙盒，而不是等到用户提交后，因为输入间隔（5-30 秒）足以完成大部分设置：

• 在用户输入时并行克隆最新更改
• 在用户按下回车前完成初始设置
• 快速启动时，沙盒可以在用户输入完成前就绪

并行读取文件 即使与最新基础分支的同步尚未完成，也允许 Agent 立即开始读取文件，因为在大型代码仓库中，收到的提示词很少涉及最近更改过的文件：

• Agent 无需等待 Git 同步即可立即开始调研
• 在同步完成前阻止编辑文件（但不阻止读取）
• 这种分离方式是安全的，因为读取时数据有 30 分钟的过时情况对调研通常无关紧要

最大化构建时工作 尽可能将所有工作移到镜像构建步骤，因为用户无法感知构建耗时：

• 完整安装依赖项
• 设置数据库架构
• 初次运行应用和测试套件（填充缓存）

自启动 Agent

由 Agent 启动的会话 构建允许 Agent 启动新会话的工具，因为前沿模型有能力拆解工作并协调子任务：

• 跨不同代码仓库开展调研
• 并行执行大型更改中的子任务
• 从一项主要任务拆分出多个较小的 PR

提供三项基本操作：使用指定参数启动新会话、读取任意会话的状态（具备签到能力），以及在子会话并行运行时继续主要工作。

自启动提示词工程 设计提示词，引导 Agent 判断何时应启动子会话，而不是直接在当前会话中执行工作：

• 需要跨代码仓库探索的调研任务
• 将整体性更改拆分为较小 PR
• 并行探索不同方案

API 层

按会话隔离状态 按会话隔离状态（每个会话使用一个 SQLite 效果很好），因为跨会话干扰是一种隐蔽且难以调试的故障模式：

• 每个会话使用专用数据库
• 会话之间不会相互影响性能
• 架构可处理数百个并发会话

实时流式传输 实时传输 Agent 的所有工作，因为高频反馈对建立用户信任至关重要：

• 从模型提供方流式传输 Token
• 工具执行状态更新
• 文件更改通知

使用 WebSocket 连接和休眠 API，在保持连接开放的同时降低空闲时段的计算成本。

跨客户端同步 构建一个可在所有客户端（聊天界面、Slack 机器人、Chrome 扩展程序、Web 界面、VS Code 实例）之间同步的统一状态系统，因为用户经常切换使用界面，并期望体验连贯。所有更改都会同步到会话状态，从而实现客户端之间的无缝切换。

多人协作支持

多人协作为何重要 从一开始就为多人协作进行设计，因为采用适当的同步架构后，添加此功能几乎不费成本，而且还能解锁高价值工作流：

• 教非工程师有效使用 AI
• 多名团队成员参与实时 QA 会话
• 实时 PR 审查并立即应用更改
• 协作调试会话

实现要求 构建数据模型时，不要将会话绑定到单个作者，因为如果作者信息被硬编码，多人协作可能会在不报错的情况下失效：

• 将作者信息传递给每条提示词
• 将代码更改归属于发出提示词的用户
• 分享会话链接以便立即协作

身份验证与授权

基于用户的提交 使用 GitHub 身份验证，以用户（而非应用）的名义创建 PR，因为这样可以保留审计轨迹，并防止用户批准自己由 AI 生成的更改：

• 获取用户令牌以创建 PR
• PR 显示为由人类而非机器人创建

沙箱到 API 的流程 遵循以下顺序，因为这样既能最大限度地减少沙箱权限，又能让 API 处理敏感操作：

1. 沙箱推送更改（更新 git 用户配置）
2. 沙箱向 API 发送事件，其中包含分支名称和会话 ID
3. API 使用用户的 GitHub 令牌创建 PR
4. GitHub webhook 向 API 通知 PR 事件

客户端实现

Slack 集成 优先将 Slack 作为内部推广的首个分发渠道，因为团队成员看到其他人使用后会形成病毒式传播循环：

• 无需特定语法，可使用自然聊天界面
• 构建分类器（使用仓库描述的快速模型），以确定要在哪个仓库中工作
• 为常用仓库提供提示；遇到模糊情况时允许选择“unknown”

Web 界面 构建具备以下功能的 Web 界面，因为它是高级用户的主要操作界面：

• 在桌面和移动设备上实时流式展示 Agent 的工作过程
• 在沙箱内运行托管的 VS Code 实例
• 提供流式桌面视图以进行视觉验证
• 提供 PR 的前后截图
• 统计页面：最终合并 PR 的会话数（主要指标）、随时间变化的使用情况、实时“正在编写提示词的人数”

Chrome 扩展 为非工程类用户构建 Chrome 扩展，因为提取 DOM 和 React 内部信息比原始截图精度更高、令牌成本更低：

• 带截图工具的侧边栏聊天界面
• 提取 DOM/React 内部信息，而不是原始图像
• 通过托管设备策略分发（绕过 Chrome Web Store）

实用指南

托管 Agent 设计检查清单

在构建系统之前，明确决定以下基础设施属性：

1. 沙箱生命周期：会话如何启动、快照、恢复、超时和终止。
2. 镜像与预热池策略：镜像多久重建一次、预先计算哪些缓存，以及预热沙箱何时过期。
3. 读写同步：Agent 是否可以在仓库同步完成前读取，以及哪些事件会解除写入阻塞。
4. 每个会话的状态隔离：哪些存储属于单个会话、哪些共享，以及如何防止跨会话干扰。
5. 身份验证与提交身份：哪些操作使用应用令牌，哪些使用用户令牌，以及如何标记提交的来源。
6. 输出提取：分支、PR、文件、日志、截图和会话摘要如何从沙箱中导出。
7. 预算与清理：最长运行时间、成本上限、空闲策略和强制清理行为。

后续消息处理

选择对执行期间发送的后续消息进行排队还是插入。优先选择排队，因为管理起来更简单，也便于用户在 Agent 工作时发送关于下一步的想法。构建一个机制，以便在需要时中途停止 Agent；否则用户会感到受困。

重要指标

跟踪以下指标，因为它们能体现实际价值，而非虚荣性使用数据：

• 最终合并 PR 的会话数（主要成功指标）
• 从会话开始到首次模型响应的耗时
• PR 批准率和修订次数
• 各仓库中由 Agent 编写的代码占比

推广策略

通过提高可见度而非强制要求来推动内部采用，因为强制使用会引发反感：

• 在公开空间（Slack 频道）中工作以提高可见度
• 让产品形成病毒式传播循环
• 不要强制用户放弃现有工具
• 根据人们的实际需求构建，而非臆想的要求

示例

示例 1：后台编码会话生命周期

user prompt
-> API allocates warm sandbox from current image
-> sandbox syncs latest branch delta
-> reads allowed immediately, writes blocked until sync completes
-> agent edits and tests inside isolated workspace
-> sandbox snapshots final filesystem
-> branch is pushed
-> API creates PR using user token
-> session summary, logs, and PR URL are returned to clients

此流程将准备工作安排在用户可见流程之外，同时确保操作可审计，并由用户掌控代码变更。

示例 2：边界判定

如果任务是“让 Agent 循环运行数天，并使用锁定的评分标准和 PR 审批”，请使用 harness-engineering。如果任务是“在远程沙箱中运行该循环，并使用预热资源池、会话快照、流式客户端和用户编写的 PR”，请使用此技能。

指南

1. 定期预构建环境镜像（默认每 30 分钟一次是不错的选择）
2. 用户开始输入时就开始预热沙箱，而不是等他们提交
3. 在 Git 同步完成前允许读取文件；仅阻止写入
4. 将 Agent 框架设计为以服务端为先，客户端仅作为轻量封装
5. 按会话隔离状态，防止会话间相互干扰
6. 将提交归属到发起请求的用户，而不是应用
7. 将已合并的 PR 作为主要成功指标
8. 从一开始就支持多人协作；采用合适的同步架构后，几乎不增加成本

注意事项

1. 冷启动延迟：首次启动沙箱需要 30-60 秒，用户会以为系统出了问题。使用预热资源池，并根据按键操作预测性预热，消除用户感知到的等待时间。
2. 镜像过时：不频繁重建镜像会导致 Agent 使用过时的依赖项或代码。将重建周期设为 30 分钟，监控镜像版本；如果构建无声失败，则发出警报。
3. 沙箱成本失控：没有超时或预算上限的长时间运行 Agent 会累积意外成本。设置硬性超时限制（默认 4 小时）和单次会话成本上限。
4. 会话期间身份验证令牌过期：GitHub 令牌在任务中途过期会导致长时间任务失败。实现令牌刷新逻辑，并在创建 PR 等敏感操作前检查令牌是否有效。
5. 沙箱中的 Git 配置：缺少 user.name 或 user.email 会导致后台 Agent 提交失败。在配置沙箱时始终明确设置 Git 身份，不要假设镜像中已有这些配置。
6. 沙箱回收时状态丢失：如果沙箱在提取结果前被回收或超时，Agent 会丢失已完成的工作。始终在终止前创建快照，并在沙箱关闭前提取工件（分支、PR、文件）。
7. 预热资源池超额配置：在流量较低时维持过多预热沙箱会浪费资金。根据流量模式和时段调整资源池规模；使用自动扩缩容，而不是固定资源池规模。
8. 未提取输出：Agent 在沙箱中完成工作，但结果始终没有交付给用户。将明确的提取步骤（推送分支、创建 PR、返回文件内容）纳入会话拆除流程。

集成

此技能负责托管运行时基础设施。相邻技能负责控制系统、拓扑结构和工具契约：

• harness-engineering：治理、锁定的评估器、回滚、新颖性门槛，以及围绕自主工作的人工审批边界。
• multi-agent-patterns：托管基础设施就绪后的自我生成和监督模式。
• tool-design：向 Agent 提供的启动、状态、拆除和 PR 工具。
• context-optimization：管理分布式托管会话中的上下文。
• filesystem-context：使用沙箱文件系统持久保存会话状态和工件。

参考资料

内部参考：

• 基础设施模式 - 阅读时机：首次实现沙箱生命周期、镜像构建或预热池逻辑时

此合集中的相关技能：

• multi-agent-patterns - 阅读时机：设计自行生成或主管协调模式时
• tool-design - 阅读时机：构建用于 Agent 会话管理或状态检查的工具时
• context-optimization - 阅读时机：分布式 Agent 会话中的上下文窗口被填满时

外部资源：

• Ramp - 阅读时机：评估是自行构建还是购买后台 Agent 基础设施时
• Modal Sandboxes - 阅读时机：选择云沙箱提供商或比较隔离模型时
• Cloudflare Durable Objects - 阅读时机：设计基于 WebSocket 休眠机制的单会话状态管理时
• OpenCode - 阅读时机：选择服务端优先的 Agent 框架或研究插件架构时

---

技能元数据

创建时间：2026-01-12 上次更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：1.2.0