高级能力与最佳实践

模块职责

“高级能力与最佳实践”不是单个运行时功能，而是一组让 Background Agents 在真实团队里跑得更快、更稳、更安全的工程约定，主要覆盖这些场景：

• 镜像预构建：把 Node.js、Python、浏览器、VS Code、常用 CLI、Agent 运行时等慢变化依赖提前打进镜像，减少每次任务启动成本。
• 快照加速：把“仓库已克隆、依赖已安装、初始化脚本已跑完”的工作目录保存为快照，新会话直接恢复。
• 子任务并行：一个主任务拆成多个独立 sandbox 同时执行，例如“前端改 UI、后端补接口、测试补覆盖率”并行推进。
• 仓库生命周期脚本：允许每个仓库定义自己的初始化、依赖安装、任务前检查、任务后清理逻辑。
• Secrets 管理：控制 GitHub App Token、用户 OAuth Token、Sandbox Token、API Key 等敏感信息的注入范围和生命周期。
• 生产使用建议：围绕单租户安全模型、GitHub App 安装范围、SSO/VPN、审计、资源清理做部署约束。

这些能力通常一起使用：先用预构建镜像提供稳定基础环境，再用仓库快照减少重复安装成本，任务运行时按需拆分子任务，所有环境准备动作通过生命周期脚本统一管理，Secrets 只在运行时按作用域注入。

---

镜像预构建把基础环境提前准备好

预构建镜像适合放入变化慢、体积大、安装耗时长的内容，例如：

• Node.js / pnpm / npm / yarn
• Python / uv / pip / poetry
• Playwright、Chromium、Firefox
• git、gh、ripgrep、jq、curl
• VS Code Server 或远程开发组件
• Agent 运行时依赖
• 组织内部常用 CLI

不适合放入：

• 明文 Secrets
• 用户个人配置
• 会频繁变化的业务代码
• 临时构建产物
• 带有仓库凭证的 .git 目录

推荐把镜像分成两层：

text📋 复制
base image
  ├─ OS 工具
  ├─ Node.js / Python / git / browser
  └─ Agent 运行时

repo image / snapshot
  ├─ 仓库代码
  ├─ node_modules / venv / build cache
  └─ 生命周期脚本执行结果

典型接口可以抽象成：

ts📋 复制
type PrebuildRequest = {
  repository: string
  ref?: string
  dockerfile?: string
  context?: string
  imageTag?: string
  buildArgs?: Record<string, string>
  secrets?: string[]
}

type PrebuildResult = {
  image: string
  digest: string
  cacheKey: string
  logsUrl?: string
}

缓存 key 一般至少包含：

text📋 复制
base image digest
+ Dockerfile 内容
+ package-lock.json / pnpm-lock.yaml / poetry.lock / requirements.txt
+ 生命周期脚本内容
+ 运行时版本

如果需要在构建阶段访问私有包 registry，应使用 BuildKit secret mount，避免通过 ARG 或 ENV 把 token 固化进镜像层。

---

快照保存“已经热身过”的仓库状态

快照适合解决这类启动慢的问题：

text📋 复制
clone repo        5s ~ 60s
install deps      30s ~ 10min
install browser   1min ~ 5min
generate cache    10s ~ 3min

快照保存的是一个可恢复的工作目录模板。新 session 创建时，不需要重新执行完整初始化，而是：

text📋 复制
restore snapshot
→ git fetch
→ checkout target ref
→ run pre-task hooks
→ start agent

推荐快照 key 包含：

text📋 复制
repo identifier
+ target base ref
+ prebuild image digest
+ lockfiles
+ .background-agents/hooks/*
+ package manager version
+ runtime version

伪接口：

ts📋 复制
type SnapshotKey = string

type CreateSnapshotRequest = {
  repository: string
  ref: string
  imageDigest: string
  setupCommands?: string[]
  lifecycleScriptsHash?: string
}

type Snapshot = {
  id: string
  key: SnapshotKey
  createdAt: string
  sizeBytes: number
}

type RestoreSnapshotRequest = {
  snapshotId: string
  sessionId: string
  targetRef: string
}

快照恢复后仍应执行一次轻量同步：

bash📋 复制
git fetch origin
git checkout "$TARGET_REF"
git reset --hard "origin/$TARGET_REF"

这样可以避免快照太旧导致代码基线偏移。

---

子任务并行使用独立 sandbox

Background Agents 支持把一个复杂任务拆成多个并行子任务。每个子任务应该运行在独立 sandbox 中，拥有自己的：

• 工作目录
• 进程空间
• Sandbox Auth Token
• WebSocket Token
• 日志流
• 分支或 patch 输出

主任务只负责任务拆解和结果汇总，不应该让多个子任务直接写同一个目录。

建议的子任务接口：

ts📋 复制
type CreateSubtaskRequest = {
  parentSessionId: string
  title: string
  prompt: string
  baseRef?: string
  files?: string[]
  model?: string
}

type CreateSubtaskResult = {
  childSessionId: string
  sandboxId: string
  status: "queued" | "running"
}

典型拆分方式：

text📋 复制
主任务：给订单页增加退款能力

子任务 A：后端增加 refund API
子任务 B：前端订单详情页增加退款入口
子任务 C：补充单元测试和 e2e 用例
子任务 D：更新文档和变更日志

最后由主任务汇总：

text📋 复制
collect child results
→ review patches
→ resolve conflicts
→ run test suite
→ create PR

---

仓库生命周期脚本让初始化逻辑留在仓库里

建议每个仓库把 Background Agents 相关脚本放在固定目录，例如：

text📋 复制
.background-agents/
  Dockerfile
  hooks/
    post-clone.sh
    pre-install.sh
    post-install.sh
    pre-task.sh
    post-task.sh

推荐语义：

脚本	执行时机	适合做什么
post-clone.sh	仓库 clone 后	设置 git hooks、初始化子模块
pre-install.sh	安装依赖前	配置 registry、检查 runtime
post-install.sh	安装依赖后	生成 ORM client、安装浏览器
pre-task.sh	Agent 开始任务前	打印项目信息、检查工作区
post-task.sh	Agent 结束任务后	清理临时文件、导出报告

建议注入的环境变量：

bash📋 复制
BA_REPO_DIR=/workspace/repo
BA_SESSION_ID=session_123
BA_TASK_ID=task_456
BA_BASE_REF=main
BA_HEAD_REF=agent/task-456
BA_IS_SUBTASK=false
BA_SANDBOX_TOKEN=...

脚本要求：

• 必须可重复执行。
• 不能依赖交互式输入。
• 应设置超时时间。
• 输出日志时不要打印 Secrets。
• 失败时返回非零退出码。

一个安全的脚本模板：

bash📋 复制
#!/usr/bin/env bash
set -euo pipefail

cd "${BA_REPO_DIR:?BA_REPO_DIR is required}"

echo "repo: $(basename "$BA_REPO_DIR")"
echo "session: ${BA_SESSION_ID:-unknown}"
echo "base ref: ${BA_BASE_REF:-unknown}"

if [ -f package.json ]; then
  echo "node project detected"
fi

---

Secrets 只在运行时按作用域注入

README 中的 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

生产环境建议按作用域管理 Secrets：

text📋 复制
org secret       组织级，例如内部 npm registry token
repo secret      仓库级，例如部署测试环境 key
session secret   单次任务级，例如临时云服务凭证

注入方式优先级：

text📋 复制
短生命周期 token > 文件挂载 > 环境变量 > 构建参数

避免：

dockerfile📋 复制
# 不推荐：token 会留在镜像层历史里
ARG NPM_TOKEN
RUN npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN

推荐使用运行时注入或 BuildKit secret：

dockerfile📋 复制
# 推荐：secret 不进入镜像层
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN="$(cat /run/secrets/npm_token)" && \
    npm config set //registry.npmjs.org/:_authToken="$NPM_TOKEN" && \
    npm ci

日志侧需要做 masking：

text📋 复制
sk-live-abc123 → ****
ghp_xxx        → ****

---

可运行示例：预构建一个带 Node 依赖的镜像

这个例子演示把依赖安装进镜像层。需要本机安装 Docker。

bash📋 复制
mkdir -p /tmp/ba-prebuild-demo
cd /tmp/ba-prebuild-demo

cat > package.json <<'EOF'
{
  "name": "ba-prebuild-demo",
  "version": "1.0.0",
  "dependencies": {
    "left-pad": "1.3.0"
  }
}
EOF

cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1.7
FROM node:20-alpine

WORKDIR /workspace

RUN node -v > /opt/prebuilt-node-version

COPY package.json ./

RUN --mount=type=cache,target=/root/.npm \
    npm install --package-lock=false --ignore-scripts

CMD ["sh", "-lc", "cat /opt/prebuilt-node-version && node -e \"console.log(require('left-pad')('ok', 4, '.'))\""]
EOF

DOCKER_BUILDKIT=1 docker build -t ba-prebuild-demo:dev .
docker run --rm ba-prebuild-demo:dev

预期输出类似：

text📋 复制
v20.x.x
..ok

在真实 Background Agents 部署中，这个镜像可以作为某类 Node 仓库的基础镜像，后续 session 直接从该镜像启动，避免重复安装通用依赖。

---

可运行示例：用 tar 模拟仓库快照恢复

这个例子不依赖 Docker，用本地目录和 tar 模拟快照创建与恢复。

bash📋 复制
cat > /tmp/ba-snapshot-demo.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

ROOT=/tmp/ba-snapshot-demo
REPO="$ROOT/repo"
CACHE="$ROOT/cache"
SANDBOX="$ROOT/sandbox"

rm -rf "$ROOT"
mkdir -p "$REPO/.background-agents/hooks" "$CACHE"

cat > "$REPO/package.json" <<'EOF'
{
  "name": "snapshot-demo",
  "version": "1.0.0"
}
EOF

cat > "$REPO/.background-agents/hooks/post-install.sh" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
echo "warming dependencies..."
mkdir -p .cache
date > .cache/deps-ready.txt
EOF
chmod +x "$REPO/.background-agents/hooks/post-install.sh"

hash_stdin() {
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum | awk '{print $1}'
  else
    shasum -a 256 | awk '{print $1}'
  fi
}

KEY="$(
  {
    cat "$REPO/package.json"
    cat "$REPO/.background-agents/hooks/post-install.sh"
  } | hash_stdin
)"

SNAPSHOT="$CACHE/$KEY.tar.gz"

if [ ! -f "$SNAPSHOT" ]; then
  echo "snapshot miss: $KEY"
  (
    cd "$REPO"
    ./.background-agents/hooks/post-install.sh
  )
  tar -C "$REPO" -czf "$SNAPSHOT" .
else
  echo "snapshot hit: $KEY"
fi

mkdir -p "$SANDBOX"
tar -C "$SANDBOX" -xzf "$SNAPSHOT"

echo "restored files:"
find "$SANDBOX" -maxdepth 3 -type f | sort

echo
echo "cache content:"
cat "$SANDBOX/.cache/deps-ready.txt"
SH

bash /tmp/ba-snapshot-demo.sh
bash /tmp/ba-snapshot-demo.sh

第一次运行会看到 snapshot miss，第二次运行会看到 snapshot hit。

---

可运行示例：并行子任务写入独立 sandbox

这个例子用 Python 模拟 3 个子任务并行执行，每个任务都有自己的工作目录，最后主任务汇总结果。

bash📋 复制
cat > /tmp/ba-subtasks-demo.py <<'PY'
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path
import shutil
import time

root = Path("/tmp/ba-subtasks-demo")
repo = root / "repo"
sandboxes = root / "sandboxes"

if root.exists():
    shutil.rmtree(root)

repo.mkdir(parents=True)
(repo / "README.md").write_text("# demo repo\n", encoding="utf-8")

tasks = [
    ("backend", "add refund API"),
    ("frontend", "add refund button"),
    ("tests", "add refund test cases"),
]

def run_subtask(name: str, goal: str):
    sandbox = sandboxes / name
    shutil.copytree(repo, sandbox)

    time.sleep(1)

    result = sandbox / f"{name}.md"
    result.write_text(
        f"# {name}\n\nGoal: {goal}\nSandbox: {sandbox}\n",
        encoding="utf-8",
    )

    return name, result.read_text(encoding="utf-8")

with ThreadPoolExecutor(max_workers=3) as pool:
    futures = [pool.submit(run_subtask, name, goal) for name, goal in tasks]

    for future in as_completed(futures):
        name, output = future.result()
        print(f"=== subtask finished: {name} ===")
        print(output)

print("all subtasks done")
PY

python3 /tmp/ba-subtasks-demo.py

重点是：子任务只共享初始仓库状态，不共享可写工作目录。真实系统里，每个子任务对应一个独立 sandbox 和独立 session token。

---

可运行示例：生命周期脚本和 Secrets masking

这个例子演示运行 pre-task.sh 时注入 secret，并在日志里做脱敏。

bash📋 复制
cat > /tmp/ba-lifecycle-secrets-demo.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail

ROOT=/tmp/ba-lifecycle-secrets-demo
REPO="$ROOT/repo"

rm -rf "$ROOT"
mkdir -p "$REPO/.background-agents/hooks"

cat > "$REPO/.background-agents/hooks/pre-task.sh" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

cd "${BA_REPO_DIR:?BA_REPO_DIR is required}"

echo "running pre-task hook"
echo "session: ${BA_SESSION_ID:-unknown}"

# 真实脚本里不应该打印 secret；这里故意打印，用来演示日志脱敏。
echo "using token: ${SECRET_API_TOKEN:?SECRET_API_TOKEN is required}"
EOF

chmod +x "$REPO/.background-agents/hooks/pre-task.sh"

export BA_REPO_DIR="$REPO"
export BA_SESSION_ID="session_demo_123"
export SECRET_API_TOKEN="sk_demo_should_be_masked"

LOG="$("$REPO/.background-agents/hooks/pre-task.sh" 2>&1 || true)"
MASKED_LOG="${LOG//$SECRET_API_TOKEN/****}"

echo "$MASKED_LOG"
SH

bash /tmp/ba-lifecycle-secrets-demo.sh

预期输出：

text📋 复制
running pre-task hook
session: session_demo_123
using token: ****

真实环境中应尽量避免打印 secret，masking 是最后一道防线，不是主要防线。

---

生产部署要按单租户模型收口权限

Background Agents 的安全模型是单租户。也就是说，系统假设所有用户都是同一组织内可信成员，并且对组织仓库有相近的访问范围。

需要重点注意：

• GitHub App Token 用于 clone / fetch / push，范围是 GitHub App 安装过的仓库。
• 系统不在创建 session 时做严格的逐用户仓库权限校验。
• GitHub 用户 OAuth Token 主要用于创建 PR，从而保证 PR 归属到真实用户。
• 非 GitHub 登录用户创建 PR 时可能退回到 GitHub App bot 身份。

生产建议：

text📋 复制
Web UI 放在 SSO / VPN 后面
GitHub App 只安装到明确需要的仓库
配置 ALLOWED_GITHUB_ORGS 限制组织成员
安装 GitHub App 时选择 specific repositories
记录 session、repo、actor、token mint、PR creation 审计日志

如果要做多租户，需要额外实现：

text📋 复制
per-tenant GitHub App installation
session 创建时的仓库访问校验
租户隔离的数据模型
Secrets 按租户隔离
sandbox 网络隔离
审计日志按租户隔离

---

注意边界

镜像预构建

• 不要把 Secrets 写进 Dockerfile、镜像层、构建日志。
• 不要用 ARG TOKEN=... 传敏感信息。
• 尽量 pin 镜像 digest，避免基础镜像漂移。
• 定期扫描镜像漏洞。
• 区分 CPU 架构，例如 linux/amd64 和 linux/arm64 的原生依赖不能混用。
• 预构建镜像适合放通用依赖，不适合放频繁变化的业务代码。

快照

• 快照 key 必须包含 lockfile、生命周期脚本和基础镜像 digest。
• 快照恢复后仍要 git fetch 并 reset 到目标 ref。
• 不要把 .git-credentials、SSH key、token 文件打进快照。
• 原生依赖、浏览器缓存、大型构建产物可能让快照体积膨胀。
• 快照过期策略要明确，例如按最近使用时间清理。
• 如果依赖安装脚本不具备幂等性，快照恢复可能放大问题。

子任务并行

• 每个子任务必须使用独立 sandbox。
• 子任务并行会放大 API rate limit、CI 资源和模型调用成本。
• 多个子任务修改同一文件时，最终合并仍可能冲突。
• 子任务访问外部系统时要保证幂等，避免重复写入测试环境。
• 主任务需要有明确的汇总策略，不能只把多个 patch 机械拼接。

生命周期脚本

• 脚本必须非交互式。
• 必须设置超时，避免 session 卡死。
• 不要在脚本里输出 Secrets。
• 不要依赖本机绝对路径。
• 推荐使用 set -euo pipefail。
• 失败时应返回非零退出码，而不是吞掉错误。
• 对破坏性命令加保护，例如 rm -rf "$DIR" 前确认变量非空。

Secrets

• Secrets 应只在运行时注入，不应进入镜像和快照。
• 优先使用短生命周期 token。
• 按 org / repo / session 分层授权。
• 日志、PR 描述、patch、artifact 都要避免泄漏。
• 注意环境变量可能被子进程继承。
• 对外部命令开启 debug 模式前要确认不会打印环境变量。
• token 轮换和吊销流程要提前准备好。

单租户生产环境

• 不要直接暴露到公网给未知用户使用。
• 必须放在 SSO、VPN 或组织身份系统后面。
• GitHub App 安装范围就是系统可访问范围，要尽量小。
• 使用 ALLOWED_GITHUB_ORGS 或等价机制限制登录来源。
• 记录关键审计事件：谁创建了 session、访问了哪个 repo、创建了哪个 PR。
• 为 sandbox 设置 CPU、内存、磁盘、运行时长限制。
• 定期清理停止的 sandbox、旧快照和过期日志。