Background Agents: Open-Inspect 是一个开源的后台编码 Agent 系统，项目地址为 ColeMurray/background-agents，当前约 2.1k Stars。它的目标不是做一个普通聊天式代码助手，而是提供一个可以长期运行、接入真实开发环境、自动完成工程任务的后台编码平台。
它的设计灵感来自 Ramp 的 Inspect：用户提交一个编码任务后，可以先去做别的事情，Agent 在隔离的开发环境中拉取代码、修改文件、运行测试、打开浏览器调试，最后产出提交或 Pull Request。
本模块负责说明 Open-Inspect 的整体定位、核心能力、典型场景和功能边界，适合作为阅读项目源码或部署系统前的入口文档。
传统代码助手通常依赖用户当前的编辑器上下文，适合补全、解释、局部修改。Open-Inspect 更偏向“后台工程执行器”，适合这类任务：
它的核心差异是：Agent 拿到的是完整开发环境，而不是一段代码片段。
一次典型任务可以理解为下面的流程：
text用户 / 系统触发任务 │ ▼ 创建后台 Session │ ▼ 为 Session 分配 Sandbox │ ▼ Sandbox 拉取仓库代码 │ ▼ Agent 执行任务： - 阅读代码 - 修改文件 - 运行测试 - 使用浏览器自动化 - 调用模型推理 │ ▼ 生成提交 / PR / 任务结果 │ ▼ 用户在 Web UI、Slack、GitHub 等入口查看和继续协作
Open-Inspect 的重点不是只“回答怎么改”，而是让 Agent 在后台真正进入工程环境执行修改。
| 能力 | 说明 | 典型场景 |
|---|---|---|
| 后台执行任务 | Agent 可以在后台持续工作，用户不需要一直盯着窗口 | 提交一个 bug 修复任务后去开会 |
| 完整开发环境 | Sandbox 内可使用 Node.js、Python、git、浏览器自动化、VS Code 等工具 | 跑测试、调试前端页面、执行脚本 |
| 多入口接入 | 支持从 Web UI、Slack、GitHub PR、Linear Issue、Webhook 等入口触发 | 从 Slack 发一句“修复这个报错” |
| 实时协作 | 多人可以进入同一个 Session 查看和协作 | 后端和前端一起跟进同一个修复 |
| 自动创建 PR | Agent 完成修改后可以创建 Pull Request | 从 Issue 到 PR 的自动流转 |
| 正确提交归因 | 使用 GitHub 登录时，PR 创建可使用用户 OAuth Token | PR 显示由真实发起人创建 |
| 定时任务 | 支持 cron、Sentry 告警、Webhook 自动触发 | 每周自动升级依赖 |
| 并行子任务 | 一个大任务可拆分为多个子任务，在独立 Sandbox 中并行执行 | 同时尝试三种修复方案 |
| 多模型选择 | 可使用 Anthropic Claude、OpenAI Codex、OpenCode Zen 等 | 按成本、效果或企业策略选择模型 |
Open-Inspect 可以按下面几个角色理解：
text┌──────────────────────┐ │ Clients │ │ Web / Slack / GitHub │ │ Linear / Webhooks │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ Control Plane │ │ Session 管理 │ │ 用户认证 │ │ Token 分发 │ │ 实时状态同步 │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ Sandbox │ │ git / Node / Python │ │ browser / VS Code │ │ Agent runtime │ └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ GitHub / 模型 / 外部系统 │ └──────────────────────┘
客户端是任务的发起和协作入口，包括：
这些入口的共同目标是创建或推进一个后台 Session。
Control Plane 负责管理后台任务，而不是直接写代码。它通常处理：
Sandbox 是 Agent 真正工作的地方。它拥有完整开发环境，可以：
git clone / fetch / push每个任务或子任务通常运行在隔离 Sandbox 中，避免相互污染。
系统使用共享 GitHub App Installation Token 来完成 git 操作，例如：
这意味着 GitHub App 安装到哪些仓库，系统就有能力访问哪些仓库。
对于使用 GitHub 登录的用户，系统在创建 Pull Request 时可以使用用户 OAuth Token。
这样带来的结果是：
本模块对应的是项目的产品与架构入口，主要由 README 中的系统能力、部署模型和安全模型定义。它不是单个函数或类，而是一组跨模块约定。
Open-Inspect 支持多种任务来源。虽然不同入口的实现不同，但它们最终都应转换成类似的后台任务描述：
json{
"repository": "org/example-repo",
"branch": "main",
"task": "修复登录页在 Safari 下按钮错位的问题",
"source": "slack",
"requestedBy": "alice@example.com",
"metadata": {
"channel": "#frontend",
"priority": "normal"
}
}关键字段通常包括：
| 字段 | 含义 |
|---|---|
repository |
Agent 要操作的目标仓库 |
branch |
基准分支 |
task |
用户给 Agent 的自然语言任务 |
source |
任务来源，例如 web、slack、github、linear、webhook |
requestedBy |
发起人，用于审计、协作和 PR 归因 |
metadata |
外部系统上下文，例如 Issue URL、Sentry Event ID、Slack Channel |
Session 是后台任务的运行单元。
一个 Session 通常包含：
json{
"sessionId": "sess_123",
"repository": "org/example-repo",
"status": "running",
"sandboxId": "sbx_456",
"createdBy": "alice@example.com",
"createdAt": "2026-07-12T10:00:00Z"
}常见状态可以包括：
| 状态 | 说明 |
|---|---|
queued |
已创建，等待分配执行资源 |
running |
Agent 正在执行 |
waiting_for_input |
等待用户补充信息 |
failed |
执行失败 |
completed |
任务完成 |
pr_created |
已创建 Pull Request |
Open-Inspect 的安全模型里有几类重要 Token：
| Token 类型 | 用途 | 范围 |
|---|---|---|
| GitHub App Token | 提供 git clone、fetch、push 权限 | GitHub App 已安装的仓库 |
| User OAuth Token | 创建 PR、读取用户信息 | 用户本人有权限的仓库 |
| Sandbox Auth Token | Sandbox 调用 Control Plane 的认证 | 单个 Session |
| WebSocket Token | 实时会话认证 | 单个 Session |
README 中提到可选择不同模型后端：
从能力层看，模型接口需要满足：
场景：客服反馈支付页面在移动端白屏，研发在 Slack 中直接发起后台任务。
任务描述可以是：
text请检查 org/web-app 仓库中移动端支付页面白屏问题。 上下文： - 用户反馈 iPhone Safari 打开 /checkout 后白屏 - 最近合并过 payment-sdk 升级 - 请先复现，再修复，最后创建 PR
Agent 后台会：
org/web-app场景：生产环境出现高频异常，Sentry Webhook 触发后台 Agent。
任务描述可以包含：
textSentry 事件：TypeError: Cannot read properties of undefined 路由：/settings/billing 版本：2026.07.12-1 请定位原因，补充测试，并提交修复 PR。
Agent 可以根据异常堆栈、版本和仓库上下文定位问题。
场景：每周一早上自动检查依赖升级。
任务描述可以是：
text请升级 Node.js 项目的 patch/minor 依赖版本。 要求： - 不升级 major 版本 - 运行测试 - 如果有 breaking change，停止并说明原因 - 成功后创建 PR
适合用 cron 定时触发。
场景：一个性能问题可能有多种解决路径。
可以拆成多个子任务：
text主任务：优化报表页面首屏加载时间。 子任务 A：检查接口聚合和缓存策略。 子任务 B：检查前端 bundle 和懒加载。 子任务 C：检查数据库查询和索引。
每个子任务在独立 Sandbox 中运行，互不影响。最后由用户或系统选择最佳方案合并。
下面示例不依赖项目运行环境，可以直接在本地运行，用于把常见事件转换成适合 Open-Inspect 后台 Agent 消费的任务描述。
保存为 create-agent-task.mjs：
js#!/usr/bin/env node
const event = {
source: "sentry",
repository: "acme/web-app",
branch: "main",
requestedBy: "oncall@acme.com",
issueUrl: "https://sentry.example.com/issues/123",
error: "TypeError: Cannot read properties of undefined (reading 'plan')",
route: "/settings/billing",
environment: "production",
release: "2026.07.12-1"
};
function createTaskPayload(event) {
if (!event.repository) {
throw new Error("repository is required");
}
if (!event.requestedBy) {
throw new Error("requestedBy is required");
}
return {
repository: event.repository,
branch: event.branch || "main",
source: event.source || "webhook",
requestedBy: event.requestedBy,
task: [
`请修复生产环境异常：${event.error}`,
"",
"上下文：",
`- 路由：${event.route}`,
`- 环境：${event.environment}`,
`- Release：${event.release}`,
`- Sentry：${event.issueUrl}`,
"",
"要求：",
"1. 拉取目标仓库并定位异常原因",
"2. 补充或更新测试",
"3. 运行相关测试",
"4. 如果可以安全修复，请创建 Pull Request",
"5. 如果信息不足，请说明还需要什么上下文"
].join("\n"),
metadata: {
issueUrl: event.issueUrl,
route: event.route,
environment: event.environment,
release: event.release
}
};
}
const payload = createTaskPayload(event);
console.log(JSON.stringify(payload, null, 2));运行：
bashnode create-agent-task.mjs
输出示例：
json{
"repository": "acme/web-app",
"branch": "main",
"source": "sentry",
"requestedBy": "oncall@acme.com",
"task": "请修复生产环境异常：TypeError: Cannot read properties of undefined (reading 'plan')\n\n上下文：\n- 路由：/settings/billing\n- 环境：production\n- Release：2026.07.12-1\n- Sentry：https://sentry.example.com/issues/123\n\n要求：\n1. 拉取目标仓库并定位异常原因\n2. 补充或更新测试\n3. 运行相关测试\n4. 如果可以安全修复，请创建 Pull Request\n5. 如果信息不足，请说明还需要什么上下文",
"metadata": {
"issueUrl": "https://sentry.example.com/issues/123",
"route": "/settings/billing",
"environment": "production",
"release": "2026.07.12-1"
}
}部署 Open-Inspect 后，可以把这类 JSON 负载接入 Webhook、Slack Command、Sentry Alert 或内部自动化系统。
保存为 split-agent-subtasks.mjs：
js#!/usr/bin/env node
const mainTask = {
repository: "acme/analytics",
branch: "main",
requestedBy: "data-platform@acme.com",
title: "优化报表页面首屏加载时间",
context: [
"页面：/reports/dashboard",
"当前 P95 首屏时间约 8s",
"目标：降低到 3s 以内",
"请尽量避免大规模重构"
]
};
const subtasks = [
{
name: "frontend-bundle",
focus: "检查前端 bundle、懒加载、无用依赖和渲染阻塞资源"
},
{
name: "api-latency",
focus: "检查接口调用链、聚合接口、缓存和 N+1 请求"
},
{
name: "database-query",
focus: "检查数据库慢查询、索引和分页策略"
}
];
function createSubtaskPayloads(mainTask, subtasks) {
return subtasks.map((subtask) => ({
repository: mainTask.repository,
branch: mainTask.branch,
source: "parallel-subtask",
requestedBy: mainTask.requestedBy,
sandboxHint: subtask.name,
task: [
`主任务：${mainTask.title}`,
"",
"背景：",
...mainTask.context.map((line) => `- ${line}`),
"",
`本子任务关注点：${subtask.focus}`,
"",
"要求：",
"1. 只在当前关注点范围内分析和修改",
"2. 记录关键发现",
"3. 运行能覆盖本修改的测试或检查命令",
"4. 输出是否建议合并该方案",
"5. 如需改动，请保持变更尽量小"
].join("\n"),
metadata: {
parentTask: mainTask.title,
subtask: subtask.name
}
}));
}
console.log(JSON.stringify(createSubtaskPayloads(mainTask, subtasks), null, 2));运行：
bashnode split-agent-subtasks.mjs
这个示例会输出三个可独立投递的任务负载，适合映射到 Open-Inspect 的并行 Sandbox 能力。
如果你的 Open-Inspect 部署已经暴露了内部 Webhook，可以将上面生成的 JSON 投递过去。
示例脚本保存为 send-agent-task.sh：
bash#!/usr/bin/env bash
set -euo pipefail
: "${OPEN_INSPECT_WEBHOOK_URL:?Please set OPEN_INSPECT_WEBHOOK_URL}"
: "${OPEN_INSPECT_WEBHOOK_TOKEN:?Please set OPEN_INSPECT_WEBHOOK_TOKEN}"
payload="$(
node create-agent-task.mjs
)"
curl -sS \
-X POST "$OPEN_INSPECT_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPEN_INSPECT_WEBHOOK_TOKEN" \
--data "$payload"运行：
bashchmod +x send-agent-task.sh
export OPEN_INSPECT_WEBHOOK_URL="https://inspect.internal.example.com/webhooks/agent-task"
export OPEN_INSPECT_WEBHOOK_TOKEN="replace-with-your-token"
./send-agent-task.sh实际路径、鉴权头和字段名应以你的部署配置为准。这个示例的重点是展示事件如何转换为后台编码任务。
Open-Inspect 明确设计为 single-tenant deployment only，也就是单租户部署。
适合的环境是：
不适合的环境是：
系统使用共享 GitHub App installation 进行 git 操作。
这意味着：
因此，GitHub App 的安装范围非常关键。
推荐做法：
All repositories如果用户通过 GitHub 登录：
如果用户通过其他方式登录，例如 Google：
生产环境部署时建议同时做这些限制：
| 建议 | 目的 |
|---|---|
| 放在公司 SSO/VPN 后面 | 避免非组织成员访问系统 |
| 限制 GitHub 登录用户 | 只允许可信用户进入系统 |
| 配置允许的邮箱域名 | 防止外部账号注册 |
配置 ALLOWED_GITHUB_ORGS |
只允许指定 GitHub 组织成员访问 |
| GitHub App 只安装到指定仓库 | 缩小代码访问范围 |
| 审计 Session 创建记录 | 追踪谁触发了什么任务 |
| 审计 PR 创建记录 | 追踪最终代码变更来源 |
当前安全模型没有提供完整的多租户隔离能力。如果要做多租户，需要额外设计：
系统用户能让 Agent 操作哪些仓库，主要取决于 GitHub App 安装范围。安装范围过大时，风险会被放大。
多个 Sandbox 并行修改同一仓库时，可能出现：
建议在主任务中明确：
cron 或告警触发类任务可能重复执行。建议任务描述中加入限制：
Sandbox 适合开发、测试和调试，但不应默认拥有生产权限。
应避免：
不同模型在代码理解、长上下文、工具调用稳定性和成本上差异明显。建议按任务类型选择：
| 任务类型 | 模型选择建议 |
|---|---|
| 小型修复 | 成本较低、响应快的模型 |
| 大型重构 | 长上下文和推理能力更强的模型 |
| 自动化批处理 | 稳定性和成本优先 |
| 高风险代码变更 | 更强模型 + 人工 Review |
Open-Inspect 可以帮助完成大量机械性工程工作，但不应跳过代码审查。尤其是：
建议把 Agent PR 当作普通工程师提交的 PR 处理，继续走测试、Review 和 CI 流程。