# Hosted Agents

> 在沙盒环境中构建后台智能体。适用于托管编码智能体、沙盒虚拟机、Modal 沙盒和远程编码环境。

- Skill: `kscz0000/hosted-agents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/hosted-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/hosted-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/hosted-agents

---


# 托管智能体基础设施

托管智能体在远程沙盒环境中运行，而非本地机器。设计得当的话，它们提供无限并发、一致的执行环境和多人协作。关键洞察是会话速度应仅受模型提供商首令牌时间限制，所有基础设施设置应在用户开始会话前完成。

## 何时使用
以下场景激活此技能：
- 构建独立于用户设备运行的后台编码智能体
- 为智能体工作负载设计沙盒执行环境
- 实现具有共享状态的多智能体会话
- 创建多客户端智能体界面（Slack、Web、Chrome 扩展）
- 扩展超越本地机器约束的智能体基础设施
- 构建智能体派生子智能体进行并行工作的系统

## 核心概念

托管智能体解决了本地智能体执行的根本局限：资源竞争、环境不一致和单用户约束。通过将智能体执行移至远程沙盒环境，团队获得无限并发、可复现环境和协作工作流。

架构由三层组成：用于隔离执行的沙盒基础设施、用于状态管理和客户端协调的 API 层，以及用于跨平台用户交互的客户端界面。每层都有特定的设计要求，使系统能够扩展。

## 详细主题

### 沙盒基础设施

**核心挑战**
快速启动完整开发环境是主要技术挑战。用户期望近乎即时的会话启动，但开发环境需要克隆仓库、安装依赖和运行构建步骤。

**镜像注册表模式**
定期预构建环境镜像（每 30 分钟效果很好）。每个镜像包含：
- 已知提交处的克隆仓库
- 所有运行时依赖已安装
- 初始设置和构建命令已完成
- 运行应用和测试套件一次的缓存文件

启动会话时，从最新镜像启动沙盒。仓库最多落后 30 分钟，使与最新代码的同步更快。

**快照与恢复**
在关键点拍摄文件系统快照：
- 初始镜像构建后（基础快照）
- 智能体完成更改时（会话快照）
- 沙盒退出前以便后续跟进

这使后续提示的即时恢复成为可能，无需重新运行设置。

**后台智能体的 Git 配置**
由于镜像构建期间 git 操作不绑定特定用户：
- 克隆期间生成 GitHub 应用安装令牌用于仓库访问
- 提交和推送更改时更新 git 配置的 `user.name` 和 `user.email`
- 使用提示用户的身份提交，而非应用身份

**预热池策略**
为高流量仓库维护预热沙盒池：
- 用户开始会话前沙盒已就绪
- 新镜像构建完成时过期并重建池条目
- 用户开始输入时即开始预热沙盒（预测性预热）

### 智能体框架选择

**服务器优先架构**
选择首先构建为服务器的智能体框架，TUI 和桌面应用作为客户端。这使：
- 多个自定义客户端无需重复智能体逻辑
- 所有交互面行为一致
- 扩展功能的插件系统
- 实时更新的事件驱动架构

**代码作为事实来源**
选择智能体可以读取自己源代码以理解行为的框架。这在 AI 开发中被低估：以代码为事实来源防止对智能体自身能力的幻觉。

**插件系统要求**
框架应支持以下插件：
- 监听工具执行事件（如 `tool.execute.before`）
- 有条件阻止或修改工具调用
- 运行时注入上下文或状态

### 速度优化

**预测性预热**
用户开始输入提示时即开始预热沙盒：
- 与用户输入并行克隆最新更改
- 用户按回车前运行初始设置
- 对于快速启动，沙盒可在用户完成输入前就绪

**并行文件读取**
允许智能体立即开始读取文件，即使来自最新基础分支的同步未完成：
- 大型仓库中，传入提示很少修改最近更改的文件
- 智能体可立即研究而无需等待 git 同步
- 同步完成前阻止文件编辑（非读取）

**最大化构建时工作**
将一切可能移至镜像构建步骤：
- 完整依赖安装
- 数据库模式设置
- 初始应用和测试套件运行（填充缓存）
- 构建时长对用户不可见

### 自派生智能体

**智能体派生会话**
创建允许智能体派生新会话的工具：
- 跨不同仓库的研究任务
- 大型更改的并行子任务执行
- 从一个主要任务产生多个较小 PR

前沿模型能够自我包含。工具应：
- 以指定参数启动新会话
- 读取任何会话状态（签到能力）
- 子会话并行运行时继续主工作

**自派生的提示工程**
工程化提示以指导智能体何时派生子会话：
- 需要跨仓库探索的研究任务
- 将单体更改拆分为较小 PR
- 并行探索不同方法

### API 层

**每会话状态隔离**
每个会话需要自己的隔离状态存储：
- 每会话专用数据库（每会话 SQLite 效果很好）
- 无会话可影响另一会话的性能
- 处理数百个并发会话

**实时流式传输**
智能体工作涉及高频更新：
- 来自模型提供商的令牌流
- 工具执行状态更新
- 文件更改通知

具有休眠 API 的 WebSocket 连接在空闲期间减少计算成本，同时保持开放连接。

**跨客户端同步**
构建单一状态系统，跨以下同步：
- 聊天界面
- Slack 机器人
- Chrome 扩展
- Web 界面
- VS Code 实例

所有更改同步到会话状态，实现无缝客户端切换。

### 多人支持

**为什么多人很重要**
多人支持使：
- 教导非工程师有效使用 AI
- 多团队成员实时问答会话
- 即时更改的实时 PR 审查
- 协作调试会话

**实现要求**
- 数据模型不得将会话绑定到单一作者
- 向每个提示传递作者信息
- 将代码更改归属于提示用户
- 共享会话链接实现即时协作

通过适当的同步架构，多人支持几乎免费添加。

### 认证与授权

**基于用户的提交**
使用 GitHub 认证：
- 获取用户令牌用于 PR 创建
- 代表用户（而非应用）打开 PR
- 防止用户批准自己的更改

**沙盒到 API 流程**
1. 沙盒推送更改（更新 git 用户配置）
2. 沙盒向 API 发送带有分支名和会话 ID 的事件
3. API 使用用户的 GitHub 令牌创建 PR
4. GitHub webhook 通知 API PR 事件

### 客户端实现

**Slack 集成**
内部采用最有效的分发渠道：
- 团队成员看到他人使用时产生病毒式传播循环
- 无需语法，自然聊天界面
- 从消息、线程上下文和频道名分类仓库

构建分类器确定在哪个仓库工作：
- 带有可用仓库描述的快速模型
- 包含常用仓库提示
- 对模糊情况允许"未知"选项

**Web 界面**
核心功能：
- 桌面和移动端可用
- 智能体工作实时流式传输
- 沙盒内运行的托管 VS Code 实例
- 流式桌面视图用于视觉验证
- PR 的前后截图

统计页面显示：
- 导致合并 PR 的会话（主要指标）
- 随时间使用情况
- 实时"人类提示"计数（最近 5 分钟内的提示）

**Chrome 扩展**
面向非工程用户：
- 带截图工具的侧边栏聊天界面
- DOM 和 React 内部提取而非原始图像
- 减少令牌使用同时保持精度
- 通过托管设备策略分发（绕过 Chrome Web Store）

## 实用指导

### 后续消息处理

决定如何处理执行期间发送的消息：
- **队列方式**：消息等待当前提示完成
- **插入方式**：消息立即处理

队列更易管理，让用户在智能体工作时发送下一步想法。构建机制在需要时停止智能体执行。

### 重要指标

追踪表明真实价值的指标：
- 导致合并 PR 的会话（主要成功指标）
- 从会话开始到首次模型响应的时间
- PR 批准率和修订次数
- 跨仓库的智能体编写代码百分比

### 采用策略

有效的内部采用模式：
- 在公共空间（Slack 频道）工作以获得可见性
- 让产品创造病毒式传播循环
- 不要强制替代现有工具
- 为人们的需求构建，而非假设性需求

## 指导原则

1. 定期预构建环境镜像（30 分钟是好的默认值）
2. 用户开始输入时预热沙盒，而非提交时
3. 在 git 同步完成前允许文件读取；仅阻止写入
4. 将智能体框架构建为服务器优先，客户端作为薄包装
5. 每会话隔离状态以防止跨会话干扰
6. 将提交归属于提示用户，而非应用
7. 追踪合并 PR 作为主要成功指标
8. 从一开始就为多人构建；通过适当的同步架构几乎免费

## 集成

此技能建立在多智能体模式的智能体协调和工具设计的智能体-工具接口之上。它连接到：

- multi-agent-patterns - 自派生智能体遵循监督者模式
- tool-design - 为智能体派生和状态检查构建工具
- context-optimization - 跨分布式会话管理上下文
- filesystem-context - 使用文件系统存储会话状态和产物

## 参考资料

内部参考：
- Infrastructure Patterns - 详细实现模式

此集合中的相关技能：
- multi-agent-patterns - 自派生智能体的协调模式
- tool-design - 为托管环境设计工具
- context-optimization - 分布式系统中的上下文管理

外部资源：
- [Ramp](https://builders.ramp.com/post/why-we-built-our-background-agent) - Why We Built Our Own Background Agent
- [Modal Sandboxes](https://modal.com/docs/guide/sandbox) - Cloud sandbox infrastructure
- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/) - Per-session state management
- [OpenCode](https://github.com/sst/opencode) - Server-first agent framework

---

## 技能元数据

**创建时间**：2026-01-12
**最后更新**：2026-01-12
**作者**：Agent Skills for Context Engineering Contributors
**版本**：1.0.0

## 何时使用
本技能适用于执行概述中描述的工作流程或操作。

## 局限性
- 仅当任务明确匹配上述范围时使用本技能。
- 不要将输出替代特定环境的验证、测试或专家审查。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。