ColeMurray/background-agents

来源：https://github.com/ColeMurray/background-agents

Background Agents: Open-Inspect

一个开源的背景代理编码系统，灵感来源于 Ramp 的 Inspect (https://builders.ramp.com/post/why-we-built-our-background-agent)。

概述

Open-Inspect 提供一个托管的背景编码代理，能够：

• 在后台处理任务，让你可以专注于其他事情
• 访问完整的开发环境（Node.js、Python、git、浏览器自动化、VS Code）
• 从任何地方连接——Web UI、Slack、GitHub PR、Linear issue 或 webhooks
• 支持多人实时协作的多人会话
• 创建带有正确提交归属的 PR，归属于发起提示的用户
• 按计划运行——cron 任务、Sentry 警报以及 webhook 触发的自动化操作
• 生成并行子任务，在独立的沙箱中同时工作
• 使用你选择的 AI 模型——Anthropic Claude、OpenAI Codex（通过 ChatGPT 订阅）或 OpenCode Zen

安全模型（仅单租户）

重要：本系统设计为仅单租户部署，所有用户都是同一组织内的受信任成员，且可访问相同的仓库。

工作原理

系统使用共享的 GitHub App 安装来进行 git 操作（克隆、获取、推送）。控制平面在服务端生成短期安装令牌，并通过 git 凭据助手按需将其分发给沙箱。这意味着：

• 所有用户共享相同的 GitHub App 凭据——GitHub App 必须安装在组织的仓库上，系统的任何用户都可以访问该 App 有权访问的任何仓库
• 没有按用户的仓库访问验证——系统在创建会话前不会验证用户是否有权限访问特定仓库
• GitHub 用户的 OAuth 令牌用于创建 PR——对于 GitHub 登录，PR 使用用户的 GitHub OAuth 令牌创建，确保正确归属，并且用户只能在其有写入权限的仓库上创建 PR。通过其他方式（如 Google）登录的用户没有 SCM 令牌，因此他们的 PR 会回退到共享的 GitHub App 机器人

令牌架构

为什么仅限单租户

此架构遵循 Ramp 的 Inspect 设计 (https://builders.ramp.com/post/why-we-built-our-background-agent)，该设计是为内部使用而构建的，所有员工都是受信任的且可访问公司仓库。

对于多租户部署，你需要：

• 每个租户独立的 GitHub App 安装
• 在创建会话时进行访问验证
• 数据模型中的租户隔离

部署建议

1. 部署在你的组织 SSO/VPN 之后——确保只有授权员工才能访问 Web 界面
2. 仅在目标仓库上安装 GitHub App——App 的安装范围定义了系统可以访问的内容
3. 限制登录——配置允许的 GitHub 用户、电子邮件域名或活跃的 GitHub 组织成员资格 (ALLOWED_GITHUB_ORGS)
4. 使用 GitHub 的仓库选择——安装时选择特定仓库，而不是“所有仓库”

架构

                                    ┌──────────────────┐
                                    │     客户端       │
                                    │ ┌──────────────┐ │
                                    │ │  Web / Slack  │ │
                                    │ │ GitHub / Lin. │ │
                                    │ │   Webhooks    │ │
                                    │ └──────────────┘ │
                                    └────────┬─────────┘
                                             │
                                             ▼
┌────────────────────────────────────────────────────────────────────┐
│                     控制平面 (Cloudflare)                          │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │               Durable Objects (每个会话)                     │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────────────┐  │  │
│  │  │ SQLite  │  │WebSocket│  │  事件   │  │   GitHub      │  │  │
│  │  │   DB    │  │   中心   │  │  流     │  │  集成         │  │  │
│  │  └─────────┘  └─────────┘  └─────────┘  └───────────────┘  │  │
│  └──────────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │              D1 数据库 (仓库作用域的秘密)                     │  │
│  └──────────────────────────────────────────────────────────────┘  │
└────────────────────────────────┬───────────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────────┐
│                     数据平面 (沙箱后端)                            │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                     会话沙箱                                  │  │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐                 │  │
│  │  │ Supervisor│──│  OpenCode  │──│   Bridge  │─────────────┼──┼──▶ 控制平面
│  │  └───────────┘  └───────────┘  └───────────┘                 │  │
│  │                      │                                       │  │
│  │             完整开发环境                                      │  │
│  │      (Node.js, Python, git, agent-browser)                   │  │
│  └──────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘

包

快速开始

有关实际设置指南（本地开发、贡献者、部署路径），请从 docs/SETUP_GUIDE.md 开始。

部署说明请参阅 docs/GETTING_STARTED.md。

要了解架构和核心概念，请阅读 docs/HOW_IT_WORKS.md。

要设置定期计划任务，请参阅 docs/AUTOMATIONS.md。

主要特性

快速启动

会话通过多层预热近乎瞬时启动：

• 文件系统快照——每次提示后，沙箱状态被保存；后续会话恢复而非重新克隆
• 预构建镜像——可按仓库（设置 > 镜像）或按环境（设置 > 环境）切换；每 30 分钟用最新提交和依赖重新构建
• 主动预热——在开始键入时沙箱即开始启动，无需等待按回车

多仓库会话与环境

一个会话可以在单个沙箱中跨多个仓库工作：

• 临时集合——在新会话选择器中最多选择 10 个仓库；每个仓库被并行克隆，代理可以协调更改并为每个仓库创建一个 PR
• 环境——将仓库集合保存为命名环境，拥有自己的秘密作用域和可选的预构建镜像，然后像任何仓库一样从选择器启动
• 参见 docs/HOW_IT_WORKS.md 了解模型，以及 docs/IMAGE_PREBUILD.md 了解环境预构建

多人会话

多个用户可以在同一会话中协作：

• 存在指示器显示谁在线
• 提示归属于其作者，并在 git 提交中体现
• 实时流式传输到所有连接的客户端

提交归属

提交归属于发送提示的用户：

// 为每个提示配置 git 身份
await configureGitIdentity({
  name: author.scmName,
  email: author.scmEmail,
});

多提供商模型支持

选择适合你任务的 AI 模型，并支持按会话控制推理努力程度：

OpenAI 模型通过 OAuth 使用你现有的 ChatGPT 订阅即可工作——无需单独的 API 密钥。 完整模型列表请参见 docs/AVAILABLE_MODELS.md， OpenAI 设置说明请参见 docs/OPENAI_MODELS.md。

客户端集成

从你的团队已经工作的任何地方与代理交互：

• Web UI——完整的会话管理，支持实时流式传输、模型/推理选择器、终端面板和多人存在
• Slack 机器人——@提及或私信以启动会话；回复以线程方式返回结果。通过 App Home 设置每个用户的模型和分支偏好。参见 Slack 集成
• GitHub 机器人——PR 打开时自动审查，或在 PR 评论中响应 @提及。可针对每个仓库配置。参见 GitHub 集成
• Linear 机器人——在 issue 上提及或分配代理以启动编码会话，发布进度活动，并链接结果 PR。参见 Linear 集成
• Webhooks——通过认证的 HTTP POST 从任何外部系统触发会话

自动化

安排重复任务或响应外部事件——无需人工干预：

• Cron 调度——每小时、每天、每周、每月或自定义 5 字段 cron，支持时区
• Sentry 警报——自动分类新错误、回归或关键指标警报
• 入站 Webhook——JSONPath 条件过滤器，用于决定哪些有效负载生成会话
• 多仓库扇出——一次计划自动化可以跨最多 10 个仓库运行，为每个仓库打开单独的会话和拉取请求
• 连续 3 次失败后自动暂停，手动触发按钮，完整运行历史

设置说明请参见 docs/AUTOMATIONS.md。

沙箱环境

每个会话在隔离的沙箱后端中运行，具有完整的开发环境：

• 预装软件： Node.js 22, Python 3.12, Bun, git, GitHub CLI, build-essential
• 浏览器自动化： 带有无头 Chromium 的 agent-browser CLI，用于截图、视觉差异和 UI 验证
• Code-server： 可选的基于浏览器的 VS Code，连接到会话工作区
• Web 终端： 由 ttyd 驱动的终端，可从会话 UI 访问
• 端口隧道： 通过加密隧道暴露最多 10 个开发服务器端口。URL 在沙箱内的 /workspace/.tunnels.env 中可用，在 .openinspect/start.sh 运行之前 (详情)
• 秘密： AES-256-GCM 加密，作用域为全局、每个仓库或每个环境，在启动时作为环境变量注入。支持批量 .env 粘贴导入

子任务生成

代理可以将工作分解为并行的子会话：

• spawn-task 创建一个子会话，位于自己的沙箱中，并立即返回
• 父进程继续工作，而子进程在独立分支上并行运行
• get-task-status 和 cancel-task 用于协调
• 强制执行深度限制和每个仓库的护栏

仓库生命周期脚本

仓库可以在 .openinspect/ 目录下定义两个可选的启动脚本：

# .openinspect/setup.sh (配置)
#!/bin/bash
npm install
pip install -r requirements.txt

# .openinspect/start.sh (运行时启动)
#!/bin/bash
docker compose up -d postgres redis

• setup.sh 在镜像构建和新会话时运行
• setup.sh 在预构建镜像和快照恢复启动时跳过
• setup.sh 失败对于新会话是非致命的，但在镜像构建模式下是致命的
• start.sh 在每个非构建会话启动时运行（新会话、预构建镜像、快照恢复）
• start.sh 失败是严格的：如果存在且失败，会话启动失败
• 默认超时：
  • SETUP_TIMEOUT_SECONDS (默认 300)
  • START_TIMEOUT_SECONDS (默认 120)
• 两个钩子都会收到 OPENINSPECT_BOOT_MODE (build, fresh, repo_image, snapshot_restore)
• 当共享安装有访问权限时，钩子中的 git 操作可以在配置的 SCM 主机上认证其他私有仓库

许可

MIT

致谢

灵感来源于 Ramp 的 Inspect (https://builders.ramp.com/post/why-we-built-our-background-agent)， 并基于以下技术构建：

• Modal (https://modal.com) - 云沙箱基础设施
• Daytona (https://www.daytona.io) - 云开发沙箱
• Vercel Sandbox (https://vercel.com/docs/vercel-sandbox) - 云沙箱基础设施
• OpenComputer (https://www.opencomputer.dev) - 云沙箱基础设施
• Cloudflare Workers (https://workers.cloudflare.com) - 边缘计算
• OpenCode (https://opencode.ai) - 编码代理运行时
• Next.js (https://nextjs.org) - Web 框架