background-agents：开源后台代理编码系统

这是什么

background-agents 是一个开源的背景编码代理系统，灵感源于 Ramp 内部的 Inspect 工具。它允许开发者在专注于其他工作的同时，让一个托管在云端的 AI 编码代理在后台自主完成代码任务。项目由 TypeScript 编写，在 GitHub 上已获得 2152 颗星，采用了 Cloudflare（控制面）与沙盒后端（数据面）分离的架构，并通过 Durable Objects、WebSocket、事件流等技术实现实时协作与状态持久化。系统支持多人同屏编辑、跨仓库操作、定时任务触发以及多种 AI 模型（Anthropic Claude、OpenAI Codex、OpenCode Zen）选择，强调单租户内部部署（Single-Tenant），适用于组织内所有成员互相信任、共享仓库的场景。

解决的问题

传统开发工作流中存在大量“等待”和“切换上下文”的低效环节：当开发者需要运行测试、修复一个已知 bug、或编写文档时，往往要停下当前工作，手动切换环境、克隆仓库、安装依赖、执行脚本。若遇到需要跨仓库修改、多人协作，协调成本更高。background-agents 解决了这些痛点：

• 消除阻塞：允许开发者提交任务后继续自己的工作，代理在后台独立运行，无需实时监督。
• 统一环境：代理拥有完整的 Node.js、Python、git、浏览器自动化、VS Code 等运行时，无需本地配置。
• 跨仓库协作：单个会话可同时操作多达 10 个仓库，并自动为每个仓库创建 PR。
• 自动化与集成：通过 cron、Sentry 告警、webhook 触发任务，减少人工介入。

核心功能

1. 后台自主编码：代理在隔离沙盒中运行，可完成修改代码、运行命令、提交 PR 等任务，用户无需等待。
2. 全功能开发环境：预装 Node.js 22、Python 3.12、Bun、Git、GitHub CLI、chromium-headless（用于截图/视觉 diff）、code-server（浏览器 VS Code）、ttyd 终端、端口隧道（支持同时暴露最多 10 个端口）。
3. 多客户端接入：支持 Web UI、Slack Bot、GitHub Bot（PR 评论触发）、Linear Bot、Webhook 等多种入口。
4. 实时多人协作：同一会话可多人同时加入，展示在线状态，提示归属到各自 git 作者信息，消息实时流式推送。
5. 多模型与推理控制：可选择 Anthropic Claude、OpenAI Codex（通过 ChatGPT OAuth 无需额外 API Key）、OpenCode Zen，且每个会话可独立设置推理力度。
6. 调度与自动化：支持 cron（5 字段+时区）、Sentry 告警自动预分类、webhook JSONPath 条件过滤，失败 3 次自动暂停，并有完整运行历史。
7. 快速启动与预热：多层预热机制——文件系统快照（下一次会话恢复而非重新克隆）、预构建镜像（每 30 分钟自动重建）、输入时提前启动沙盒，实现近乎零等待。
8. 环境与秘密管理：可保存命名环境（repository 集合 + 独立秘密作用域 + 可选预构建镜像），秘密存储在 D1 数据库，按仓库作用域隔离。
9. 跨仓库与子任务：一个会话可同时处理多个仓库，支持并行派生子任务（sub-tasks）在独立沙盒中运行。

亮点 / 与同类相比

与市面上常见的 AI 编码助手（如 Copilot Chat、Cline、Codex CLI）相比，background-agents 有几个显著差异：

• 始终在线、背景执行：多数工具要求用户与 AI 实时对话，而 background-agents 的任务在后台异步完成，用户可继续其他工作。
• 完整的沙盒控制平面：不仅是代码提示，而是拥有一套完整的“控制面（Durable Objects）+ 数据面（沙盒）”架构，支持会话持久化、跨仓库操作、定时任务和复杂自动化。
• 多用户实时协作：与 Ramp Inspect 类似，允许多个开发者“围观”或共同操作同一个代理会话，这在团队调试或代码审查场景中很实用。
• 模型选择灵活且低成本：OpenAI 模型可通过 ChatGPT 订阅 OAuth 直接使用，无需额外为 API 付费；同时支持 Anthropic 和社区模型。
• 围绕 GitHub 生态深度绑定：自动创建 PR 并正确归属作者（使用 OAuth token 或 GitHub App bot），集成 GitHub 和 Linear 的 issue/PR 触发机制，对使用 GitHub 的组织尤其友好。
• 单租户安全假设清晰：项目明确声明为单租户设计，所有用户共享一个 GitHub App 安装，不进行细粒度仓库权限验证（PR 时依赖用户 OAuth token）。这种设计在内部工程团队中非常高效，但若需要多租户则需自行扩展。

适合谁用 / 上手

目标用户：

• 内部使用 GitHub 的软件团队（Startup / Mid-size 公司），所有成员互相信任，可访问共享仓库。
• 需要自动化代码修复、跨仓库修改、定时任务的 DevOps 或 SRE 团队。
• 希望将 AI 代理集成到 Slack、GitHub PR、Linear 等日常工具中的工程组织。
• 不希望在多租户隔离上花费高昂基础设施成本，愿意接受“信任模型”的团队。

上手路径：

1. 本地快速体验：按照 docs/SETUP_GUIDE.md 进行本地配置（需要 Cloudflare 账户、GitHub App 安装、OAuth 配置）。
2. 部署到生产：参考 docs/GETTING_STARTED.md，在 Cloudflare Workers + Durable Objects + 沙盒后端上部署，并确保部署在组织 SSO/VPN 之后，限制 GitHub App 安装到指定仓库，并配置 ALLOWED_GITHUB_ORGS 等环境变量。
3. 配置集成：选择 Web UI、Slack、GitHub、Linear 或 Webhook 作为客户端，参考相应文档。
4. 运行第一个任务：创建新会话，选择仓库和 AI 模型，输入 prompt，观察代理在后台自主执行并输出结果。
5. 设置自动化：在 docs/AUTOMATIONS.md 中配置 cron 调度或 Sentry/webhook 触发，让代理定期执行预定义任务。