background-agents
后台编码代理系统，受Ramp Inspect启发，让AI代理在后台并行执行编码任务，支持GitHub PR、Slack、Linear等多渠道触发和协作。亮点是接近实时的启动速度（文件快照+预构建镜像+预热）、多仓库多模型支持、以及子任务并行分拆。单租户设计，适合组织内部部署，需通过SSO/VPN限制访问。
README
Background Agents: Open-Inspect
一个受 Ramp 的 Inspect 启发而开发的开源后台智能体（background agent）编码系统。
概述
Open-Inspect 提供了一个托管的后台编码智能体（background coding agent），能够：
- 在后台处理任务，同时你可以专注于其他事情
- 访问完整的开发环境（Node.js、Python、git、浏览器自动化、VS Code）
- 通过任意方式连接——Web UI、Slack、GitHub PR、Linear issue 或 webhooks
- 支持多人协作会话，多人可实时协同工作
- 创建带有正确提交归属（attribution）的 PR，归属于触发操作的用户
- 按计划运行——cron 任务、Sentry 警报、webhook 触发的自动化
- 并行生成子任务，在不同的隔离环境（sandbox）中同时工作
- 使用你选择的 AI 模型——Anthropic Claude、OpenAI Codex（通过 ChatGPT 订阅）或 OpenCode Zen
安全模型（仅单租户）
重要：本系统设计为仅单租户部署，所有用户均为同一组织中受信任的成员，可访问相同的仓库。
工作原理
系统使用一个共享的 GitHub App 安装来进行 git 操作（clone、fetch、push）。控制平面（control plane）在服务端生成短期安装令牌（short-lived installation token），并通过 git 凭证助手（git credential helper）按需将这些令牌分发给隔离环境。这意味着：
- 所有用户共享同一 GitHub App 凭证——GitHub App 必须安装在你组织的仓库上，系统的任何用户都可以访问该 App 有权限的任何仓库
- 没有基于用户的仓库访问权限验证——系统不会在创建会话前验证用户是否有权限访问特定仓库
- GitHub 用户的 OAuth 令牌用于创建 PR——对于 GitHub 登录，PR 使用用户的 GitHub OAuth 令牌创建，确保正确的归属，并且用户只能在其有写入权限的仓库上创建 PR。通过其他方式（如 Google）登录的用户没有 SCM 令牌，因此他们的 PR 会回退到共享的 GitHub App 机器人
令牌架构
| 令牌类型 | 目的 | 范围 |
|---|---|---|
| GitHub App 令牌 | 用于 git clone/fetch/push 的身份验证 | App 已安装的所有仓库 |
| 用户 OAuth 令牌 | 创建 PR、获取用户信息 | 用户有权限的仓库 |
| 隔离环境认证令牌 | 隔离环境到控制平面的会话调用 | 单个会话 |
| WebSocket 令牌 | 实时会话认证 | 单个会话 |
为何仅限单租户
此架构遵循 Ramp 的 Inspect 设计，该设计用于内部使用，所有员工均受信任且可访问公司仓库。
如需多租户部署，你需要：
- 每个租户独立的 GitHub App 安装
- 在会话创建时进行访问权限验证
- 数据模型中的租户隔离
部署建议
- 在你的组织 SSO/VPN 之后部署——确保只有授权员工能访问 Web 界面
- 仅将 GitHub App 安装在预期的仓库上——App 的安装范围定义了系统可访问的内容
- 限制登录方式——配置允许的 GitHub 用户、电子邮件域名或活跃的 GitHub 组织成员身份（
ALLOWED_GITHUB_ORGS） - 使用 GitHub 的仓库选择功能——安装 App 时，选择特定仓库而非“所有仓库”
架构
┌──────────────────┐
│ 客户端 │
│ ┌──────────────┐ │
│ │ Web / Slack │ │
│ │ GitHub / Lin.│ │
│ │ Webhooks │ │
│ └──────────────┘ │
└────────┬─────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ 控制平面 (Cloudflare) │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 持久化对象 (每会话一个) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────────┐ │ │
│ │ │ SQLite │ │WebSocket│ │ 事件流 │ │ GitHub │ │ │
│ │ │ 数据库 │ │ 中枢 │ │ Stream │ │ 集成 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └───────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ D1 数据库 (仓库级别的密钥) │ │
│ └──────────────────────────────────────────────────────────────┘ │
└────────────────────────────────┬───────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────┐
│ 数据平面 (隔离环境后端) │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 会话隔离环境 │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ Supervisor│──│ OpenCode │──│ Bridge │────────────────┼──┼──▶ 控制平面
│ │ └───────────┘ └───────────┘ └───────────┘ │ │
│ │ │ │ │
│ │ 完整开发环境 │ │
│ │ (Node.js、Python、git、agent-browser) │ │
│ └──────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘
包
| 包 | 描述 |
|---|---|
| control-plane | Cloudflare Workers + 持久化对象 |
| web | Next.js Web 客户端 |
| sandbox-runtime | 共享的隔离环境内智能体运行时 |
| modal-infra | Modal 隔离环境基础设施 |
| daytona-infra | Daytona 快照基础设施 |
| opencomputer-infra | OpenComputer 模板基础设施 |
| slack-bot | Slack 集成（从消息创建会话） |
| github-bot | GitHub 集成（自动审查、@提及） |
| linear-bot | Linear 集成（issue → 编码会话） |
| shared | 共享类型与工具函数 |
快速开始
关于实用的设置指南（本地开发 + 贡献者 + 部署路径），请从 docs/SETUP_GUIDE.md 开始。
部署说明请参阅 docs/GETTING_STARTED.md。
要了解架构和核心概念，请阅读 docs/HOW_IT_WORKS.md。
要设置定期计划任务，请参阅 docs/AUTOMATIONS.md。
关键特性
快速启动
会话几乎瞬间启动，得益于多层的预热机制：
- 文件系统快照 — 每次提示后，隔离环境状态会被保存；后续会话会直接恢复而非重新克隆
- 预构建镜像 — 按仓库（Settings > Images）或按环境（Settings > Environments）切换；每 30 分钟根据最新提交和依赖重新构建
- 主动预热 — 在您开始输入时就启动隔离环境，无需等待回车键
多仓库会话与环境
一个会话可以在同一隔离环境中同时处理多个仓库：
- 临时组合 — 在新会话选择器中最多选择 10 个仓库；每个仓库被并排克隆，智能体可以跨仓库进行协调修改并在每个仓库上创建 PR
- 环境 — 将一组仓库保存为命名环境，附带独立的密钥作用域和可选的预构建镜像，然后像普通仓库一样从选择器启动
- 模型说明见 docs/HOW_IT_WORKS.md，环境预构建见 docs/IMAGE_PREBUILD.md
多人会话
多个用户可以在同一会话中协作：
- 状态指示器显示谁正在活跃
- 提示信息在 git 提交中归属于其作者
- 实时流式传输到所有连接的客户端
提交归属
提交归属于发送提示的用户：
// Configure git identity per prompt
await configureGitIdentity({
name: author.scmName,
email: author.scmEmail,
});
多提供商模型支持
选择适合任务的 AI 模型，并支持每会话的推理努力程度（reasoning effort）控制：
| 提供商 | 模型 |
|---|---|
| Anthropic | Claude Haiku 4.5, Sonnet 4.5/4.6, Opus 4.5/4.6/4.7/4.8, Fable 5 |
| OpenAI | GPT 5.4, GPT 5.5, 5.3 Codex, 5.3 Codex Spark |
| OpenCode Zen | Kimi K2.5/K2.6, MiniMax M2.5, Qwen3.7 Max, GLM 5/5.1 (opt-in) |
| Z.AI Coding Plan | GLM 5.2 (opt-in) |
OpenAI 模型可以通过 OAuth 使用您现有的 ChatGPT 订阅——无需单独的 API 密钥。完整模型列表请参阅 docs/AVAILABLE_MODELS.md，OpenAI 设置说明请参阅 docs/OPENAI_MODELS.md。
客户端集成
在您团队已经使用的平台上与智能体交互：
- Web UI — 完整的会话管理，包含实时流式传输、模型/推理努力选择器、终端面板和多人状态
- Slack Bot — 通过 @提及或私信启动会话；回复以线程形式返回结果。通过 App Home 设置每个用户的模型和分支偏好。参见 Slack 集成
- GitHub Bot — 在 PR 打开时自动审查，或响应 PR 评论中的 @提及。可按仓库配置。参见 GitHub 集成
- Linear Bot — 在 issue 中提及或分配给智能体，以启动编码会话、发布进度活动并链接生成的 PR。参见 Linear 集成
- Webhooks — 通过经过身份验证的 HTTP POST 从任何外部系统触发会话
自动化
定时执行重复任务或响应外部事件——无需人工介入：
- Cron 计划 — 每小时、每天、每周、每月或自定义 5 字段 cron，支持时区
- Sentry 警报 — 在出现新错误、回归或关键指标警报时自动分诊
- 入站 Webhooks — JSONPath 条件过滤器，用于决定哪些负载生成会话
- 多仓库分发 — 一个定时自动化可以同时运行在最多 10 个仓库上，为每个仓库打开单独的会话和拉取请求
- 连续 3 次失败后自动暂停，手动触发按钮，完整运行历史
设置说明请参阅 docs/AUTOMATIONS.md。
隔离环境
每个会话在隔离的后端环境中运行，包含完整的开发环境：
- 预装： Node.js 22、Python 3.12、Bun、git、GitHub CLI、build-essential
- 浏览器自动化： agent-browser CLI 配合 headless Chromium，用于截图、视觉差异和 UI 验证
- Code-server： 连接到会话工作区的可选浏览器版 VS Code
- Web 终端： 基于 ttyd 的终端，可通过会话 UI 访问
- 端口隧道： 通过加密隧道暴露最多 10 个开发服务器端口。在
.openinspect/start.sh运行之前，可在隔离环境内的/workspace/.tunnels.env获取 URL（详情） - 密钥： 使用 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，并使用了以下技术构建：
- Modal — 云隔离环境基础设施
- Daytona — 云端开发隔离环境
- Vercel Sandbox — 云隔离环境基础设施
- OpenComputer — 云隔离环境基础设施
- Cloudflare Workers — 边缘计算
- OpenCode — 编码智能体运行时
- Next.js — Web 框架