ColeMurray/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 或 webhook - 实现多人协作会话，让多人可以实时协作 - 创建具有适当提交归属权的 PR，归因于发起提示的用户 - 按计划运行 — cron 作业、Sentry 警报和 webhook 触发的自动化 - 启动并行子任务，同时在独立的沙箱中工作 - 使用您选择的 AI 模型 — Anthropic Claude、OpenAI Codex（通过 ChatGPT 订阅）或 OpenCode Zen ## 安全模型（仅限单租户） ### 工作原理 系统使用共享的 GitHub App 安装来进行 git 操作（clone、fetch、push）。控制 平面在服务器端生成短期安装 token，并根据需要通过 git credential helper 将它们代理给沙箱。这意味着： - **所有用户共享相同的 GitHub App 凭据** - GitHub App 必须安装在您 组织的仓库中，并且系统的任何用户都可以访问该 App 有权访问的任何 repo - **无基于用户的仓库访问验证** - 系统不会在创建会话前验证 用户是否有权访问特定仓库 - **GitHub 用户的 OAuth token 用于创建 PR** - 对于 GitHub 登录，使用 用户的 GitHub OAuth token 创建 PR，确保正确的归属权，并且他们只能在 拥有写入权限的 repo 上创建 PR。通过其他方式（例如 Google）登录的用户没有 SCM token， 因此他们的 PR 会回退到共享的 GitHub App bot ### Token 架构 | Token 类型 | 用途 | 范围 | | ------------------ | -------------------------------------- | -------------------------------- | | GitHub App Token | 代理的 git clone/fetch/push 授权 | 安装了 App 的所有 repo | | User OAuth Token | 创建 PR，用户信息 | 用户有权访问的 repo | | Sandbox Auth Token | 沙箱到控制平面的会话调用 | 单个会话 | | WebSocket Token | 实时会话授权 | 单个会话 | ### 为什么仅限单租户 此架构遵循 [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 的仓库选择功能** - 安装 App 时，选择特定的仓库 而不是“所有仓库” ## 架构 ``` ┌──────────────────┐ │ Clients │ │ ┌──────────────┐ │ │ │ Web / Slack │ │ │ │ GitHub / Lin.│ │ │ │ Webhooks │ │ │ └──────────────┘ │ └────────┬─────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ Control Plane (Cloudflare) │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Durable Objects (per session) │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────────┐ │ │ │ │ │ SQLite │ │WebSocket│ │ Event │ │ GitHub │ │ │ │ │ │ DB │ │ Hub │ │ Stream │ │ Integration │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └───────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ D1 Database (repo-scoped secrets) │ │ │ └──────────────────────────────────────────────────────────────┘ │ └────────────────────────────────┬───────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ Data Plane (Sandbox Backend) │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Session Sandbox │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │ Supervisor│──│ OpenCode │──│ Bridge │─────────────────┼──┼──▶ Control Plane │ │ └───────────┘ └───────────┘ └───────────┘ │ │ │ │ │ │ │ │ │ Full Dev Environment │ │ │ │ (Node.js, Python, git, agent-browser) │ │ │ └──────────────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────────┘ ``` ## 包 | 包 | 描述 | | ------------------------------------------------- | ------------------------------------------- | | [control-plane](packages/control-plane) | Cloudflare Workers + Durable Objects | | [web](packages/web) | Next.js Web 客户端 | | [sandbox-runtime](packages/sandbox-runtime) | 共享的沙箱内 agent 运行时 | | [modal-infra](packages/modal-infra) | Modal 沙箱基础设施 | | [daytona-infra](packages/daytona-infra) | Daytona 快照基础设施 | | [opencomputer-infra](packages/opencomputer-infra) | OpenComputer 模板基础设施 | | [slack-bot](packages/slack-bot) | Slack 集成（从消息创建会话） | | [github-bot](packages/github-bot) | GitHub 集成（自动审查、@mention） | | [linear-bot](packages/linear-bot) | Linear 集成（issue → 编码会话） | | [shared](packages/shared) | 共享的类型和实用工具 | ## 快速入门 有关实用的设置指南（本地 + 贡献者 + 部署路径），请从 **[docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md)** 开始。 请参阅 **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** 获取部署说明。 要了解架构和核心概念，请阅读 **[docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**。 要设置定期计划任务，请参阅 **[docs/AUTOMATIONS.md](docs/AUTOMATIONS.md)**。 ## 核心功能 ### 快速启动 通过多层预热，会话几乎可以立即启动： ### 多人会话 多个用户可以在同一个会话中进行协作： - 在线状态指示器显示谁处于活跃状态 - 提示在 git 提交中归属于其作者 - 向所有连接的客户端进行实时流式传输 ### 提交归属权 提交归属于发送提示的用户： ``` // Configure git identity per prompt await configureGitIdentity({ name: author.scmName, email: author.scmEmail, }); ``` ### 客户端集成 从您的团队已经工作的任何地方与 agent 交互： - **Web UI** — 完整的会话管理，具备实时流式传输、模型/推理选择器、终端 面板和多人在线状态 - **Slack Bot** — @mention 或 DM 以启动会话；回复以结果的形式串联回来。通过 App Home 实现 基于用户的模型和分支偏好。请参阅 [Slack 集成](docs/integrations/SLACK.md) - **GitHub Bot** — 在 PR 打开时自动审查，或响应 PR 评论中的 @mention。支持按 repo 配置。请参阅 [GitHub 集成](docs/integrations/GITHUB.md) - **Linear Bot** — 在 issue 上提及或分配 agent 以启动编码会话，发布进度 活动，并链接生成的 PR。请参阅 [Linear 集成](docs/integrations/LINEAR.md) - **Webhooks** — 通过经过身份验证的 HTTP POST 从任何外部系统触发会话 ### 自动化 安排定期任务或响应外部事件 — 无需人工干预： 有关设置说明，请参阅 **[docs/AUTOMATIONS.md](docs/AUTOMATIONS.md)**。 ### 沙箱环境 每个会话都在具有完整开发环境的独立沙箱后端中运行： - **预装：** Node.js 22、Python 3.12、Bun、git、GitHub CLI、build-essential - **浏览器自动化：** agent-browser CLI 搭配 headless Chromium，用于屏幕截图、视觉 diff 和 UI 验证 - **Code-server：** 连接到会话工作区的可选基于浏览器的 VS Code - **Web 终端：** 可从会话 UI 访问的由 ttyd 提供支持的终端 - **端口隧道：** 通过加密隧道暴露最多 10 个开发服务器端口。URL 可以在 `.openinspect/start.sh` 运行之前的沙箱内 `/workspace/.tunnels.env` 获取 （[详情](docs/HOW_IT_WORKS.md#tunnel-urls-inside-the-sandbox)） - **仓库机密：** AES-256-GCM 加密，按 repo 或全局划分范围，在 生成时作为环境变量注入。支持批量 `.env` 粘贴导入 ### 子任务生成 Agent 可以将工作分解为并行的子会话： - `spawn-task` 在自己的沙箱中创建一个子会话并立即返回 - 父任务继续工作，同时子任务在单独的分支上并行运行 - `get-task-status` 和 `cancel-task` 用于协调 - 强制执行深度限制和每个 repo 的防护机制 ### 仓库生命周期脚本 仓库可以在 `.openinspect/` 下定义两个可选的启动脚本： ``` # .openinspect/setup.sh（provisioning） #!/bin/bash npm install pip install -r requirements.txt ``` ``` # .openinspect/start.sh（runtime startup） #!/bin/bash docker compose up -d postgres redis ``` - `setup.sh` 在镜像构建和全新会话时运行 - 对于 repo-image 和 snapshot-restore 启动，会跳过 `setup.sh` - `setup.sh` 失败对于全新会话是非致命的，但在镜像构建模式下是致命的 - `start.sh` 在每次非构建会话启动时运行（fresh、repo-image、snapshot-restore） - `start.sh` 失败是严格的：如果它存在并且失败，则会话启动失败 - 默认超时： - `SETUP_TIMEOUT_SECONDS`（默认为 `300`） - `START_TIMEOUT_SECONDS`（默认为 `120`） - 两个 hook 都会接收 `OPENINSPECT_BOOT_MODE`（`build`、`fresh`、`repo_image`、`snapshot_restore`） - 当共享安装具有访问权限时，hook 中的 git 操作可以对配置的 SCM 主机上的 其他私有 repo 进行身份验证 ## 许可证 MIT

标签：MITM代理, 程序员工具, 自动化攻击, 逆向工具