会话、沙箱与开发环境

模块职责

这个模块负责把一次“让后台 Agent 去改代码”的请求，落到一个可以实际工作的开发环境里。它不只创建一条会话记录，还要准备仓库、终端、端口、IDE、认证和实时连接。

在 Open-Inspect 里，一次典型任务会经历下面这些步骤：

1. 用户从 Web UI、Slack、GitHub PR、Linear 或 webhook 发起任务。
2. 控制平面创建会话，记录任务、用户、目标仓库和分支信息。
3. 系统为这次会话分配一个独立沙箱。
4. 沙箱启动后向控制平面注册，并拿到只属于当前会话的认证信息。
5. 沙箱通过 git credential helper 向控制平面请求短期 GitHub App installation token。
6. 沙箱克隆一个或多个仓库，准备工作区。
7. Agent 在沙箱里运行，可以执行命令、读写文件、启动服务、打开浏览器自动化、使用 VS Code。
8. 用户可以通过 WebSocket 观察日志、连接终端、转发端口、多人协作。
9. 任务完成后，系统提交代码并创建 PR。
10. 会话结束，沙箱可以保留一段时间用于复查，也可以被回收。

这个模块的边界很清楚：它负责“运行环境”，不决定 Agent 如何推理，也不决定 PR 文案怎么写。

---

会话生命周期

一次会话不是单纯的数据库行，而是控制平面和沙箱之间的一组状态流转。

常见状态可以理解为：

text📋 复制
created
  ↓
provisioning
  ↓
starting
  ↓
ready
  ↓
running
  ↓
completed / failed / stopped
  ↓
archived / cleaned

各状态的职责：

状态	发生了什么
created	用户提交任务，控制平面记录 prompt、仓库、触发来源、用户身份
provisioning	开始分配沙箱资源，例如容器、VM 或远程执行环境
starting	沙箱启动基础服务，包括 agent runtime、终端服务、端口代理等
ready	仓库已克隆，工作目录可用，终端和实时通道可以连接
running	Agent 正在执行任务，用户可以实时观察和介入
completed	Agent 完成任务，可能已经提交 commit、创建 PR
failed	沙箱启动失败、克隆失败、命令失败或 Agent 异常退出
stopped	用户手动停止
archived	会话只保留日志、diff、PR 链接等结果信息
cleaned	沙箱运行资源被释放

会话里通常会保存这些信息：

ts📋 复制
type Session = {
  id: string;
  userId: string;
  prompt: string;

  status:
    | "created"
    | "provisioning"
    | "starting"
    | "ready"
    | "running"
    | "completed"
    | "failed"
    | "stopped";

  repositories: RepositorySpec[];
  primaryRepository: string;

  sandboxId?: string;
  workspacePath?: string;

  createdAt: string;
  updatedAt: string;
  completedAt?: string;
};

实际项目里的字段名可能不同，但核心语义就是：会话负责把“用户任务”和“沙箱运行实例”绑定起来。

---

沙箱环境

沙箱是 Agent 真正工作的地方。它需要像一个完整开发机，而不是一个只能跑脚本的临时容器。

沙箱至少需要具备：

• Node.js / pnpm / npm / yarn
• Python / pip / uv
• git
• 浏览器自动化依赖，例如 Playwright 或 Chromium
• shell 终端
• 文件系统工作区
• 端口监听能力
• VS Code Server 或等价的远程 IDE 能力
• 与控制平面通信的网络能力

沙箱启动时，控制平面会给它一个只属于当前会话的 token。这个 token 不等于 GitHub token，它只用于沙箱向控制平面证明自己属于某个会话。

简化后的启动参数可以理解为：

bash📋 复制
SESSION_ID="sess_123"
SANDBOX_AUTH_TOKEN="sandbox_session_scoped_token"
CONTROL_PLANE_URL="https://inspect.example.com"
WORKSPACE_DIR="/workspace"

沙箱用这些参数完成注册：

http📋 复制
POST /api/sessions/sess_123/sandbox/heartbeat
Authorization: Bearer sandbox_session_scoped_token
Content-Type: application/json

{
  "status": "ready",
  "workspace": "/workspace",
  "capabilities": {
    "terminal": true,
    "ports": true,
    "vscode": true
  }
}

重点是：沙箱 token 是会话级别的，不应该跨会话复用。

---

仓库克隆与 GitHub 凭据

Open-Inspect 的 README 明确说明了它的安全模型：系统使用共享 GitHub App installation token 处理 git clone、fetch、push。

流程是：

text📋 复制
沙箱执行 git clone
  ↓
git credential helper 被触发
  ↓
credential helper 向控制平面请求 GitHub App token
  ↓
控制平面 mint 短期 installation token
  ↓
沙箱拿到 token，用于本次 git 操作

这样做的好处是沙箱里不需要长期保存 GitHub App 私钥，也不需要把组织级凭据写进镜像。

一个典型的 credential helper 行为可以抽象成：

bash📋 复制
git config --global credential.helper \
  "!/usr/local/bin/open-inspect-git-credential-helper"

当 git 需要凭据时，会向 helper 传入：

text📋 复制
protocol=https
host=github.com
path=org/repo.git

helper 再向控制平面请求短期凭据：

http📋 复制
POST /api/git/credentials
Authorization: Bearer sandbox_session_scoped_token
Content-Type: application/json

{
  "host": "github.com",
  "path": "org/repo.git",
  "operation": "clone"
}

控制平面返回：

json📋 复制
{
  "username": "x-access-token",
  "password": "ghs_short_lived_installation_token",
  "expiresAt": "2026-07-12T12:30:00.000Z"
}

沙箱拿到后只把它交给 git 当前操作使用，不应该落盘保存。

---

单仓库工作区

最常见的会话只绑定一个仓库。

工作区布局可以是：

text📋 复制
/workspace
└── repo
    ├── package.json
    ├── src
    └── tests

会话创建时通常会带上：

json📋 复制
{
  "prompt": "修复登录页在 Safari 下按钮错位的问题",
  "repositories": [
    {
      "owner": "acme",
      "repo": "web",
      "defaultBranch": "main",
      "checkoutBranch": "main"
    }
  ],
  "primaryRepository": "acme/web"
}

沙箱侧执行：

bash📋 复制
mkdir -p /workspace
cd /workspace

git clone https://github.com/acme/web.git repo
cd repo

git checkout main
git checkout -b inspect/sess_123-fix-safari-login-button

Agent 后续所有命令默认在 /workspace/repo 下执行。

---

多仓库工作区

Open-Inspect 支持多仓库环境。这个能力很重要，因为真实任务经常跨仓库：

• 前端仓库依赖后端 API 类型定义
• 应用仓库依赖内部 SDK
• monorepo 之外还有部署配置仓库
• Agent 需要同时修改服务端和客户端

多仓库工作区通常采用平铺目录：

text📋 复制
/workspace
├── web
├── api
└── sdk

会话请求可以理解为：

json📋 复制
{
  "prompt": "把新的 billing status 字段从 API 接到前端页面",
  "repositories": [
    {
      "owner": "acme",
      "repo": "api",
      "path": "api"
    },
    {
      "owner": "acme",
      "repo": "web",
      "path": "web"
    },
    {
      "owner": "acme",
      "repo": "sdk",
      "path": "sdk"
    }
  ],
  "primaryRepository": "acme/web"
}

沙箱准备工作区：

bash📋 复制
mkdir -p /workspace
cd /workspace

git clone https://github.com/acme/api.git api
git clone https://github.com/acme/web.git web
git clone https://github.com/acme/sdk.git sdk

推荐把“主仓库”单独标出来，因为最终 PR 往往只创建在一个仓库上。如果 Agent 修改了多个仓库，需要明确是：

• 创建多个 PR；
• 只允许修改主仓库；
• 或把其他仓库当只读依赖。

---

端口隧道

Agent 常常需要启动开发服务器，例如：

bash📋 复制
npm run dev

服务可能监听在沙箱内部的 localhost:3000。用户浏览器无法直接访问沙箱内部地址，所以需要端口隧道。

端口隧道的职责是把：

text📋 复制
sandbox:localhost:3000

映射成：

text📋 复制
https://sess-123-3000.inspect.example.com

或者：

text📋 复制
https://inspect.example.com/sessions/sess_123/ports/3000

一个端口记录可以抽象成：

ts📋 复制
type PortForward = {
  sessionId: string;
  port: number;
  protocol: "http" | "https" | "tcp";
  targetHost: "127.0.0.1";
  publicUrl: string;
  status: "opening" | "open" | "closed";
};

创建端口转发：

http📋 复制
POST /api/sessions/sess_123/ports
Authorization: Bearer websocket_or_user_token
Content-Type: application/json

{
  "port": 3000,
  "protocol": "http"
}

返回：

json📋 复制
{
  "port": 3000,
  "publicUrl": "https://sess-123-3000.inspect.example.com",
  "status": "open"
}

这个能力不仅给用户看页面，也给 Agent 做浏览器自动化用。例如 Agent 可以启动 Web 应用，然后用 Playwright 访问端口，验证 UI 是否修好。

---

终端能力

终端能力用于两件事：

1. Agent 自己执行命令。
2. 用户连接同一个会话，手动查看、干预、调试。

终端通常需要伪终端 PTY，而不是简单的 exec，因为很多开发命令依赖 TTY 行为：

• 彩色输出
• 交互式 prompt
• Ctrl-C
• shell history
• resize
• long-running process

一个终端连接可以理解为：

text📋 复制
Web UI
  ↓ WebSocket
控制平面
  ↓ session-scoped channel
沙箱 PTY

WebSocket 消息一般会包含几类：

json📋 复制
{ "type": "input", "data": "npm test\n" }

json📋 复制
{ "type": "output", "data": "PASS src/login.test.ts\n" }

json📋 复制
{ "type": "resize", "cols": 120, "rows": 40 }

json📋 复制
{ "type": "exit", "code": 0 }

终端和 Agent 命令执行可以共用同一个沙箱，但不要混用同一个 shell 会话。推荐：

• Agent 有自己的命令执行通道；
• 用户终端有独立 PTY；
• 长时间服务进程有独立 process group，方便停止。

---

VS Code 远程开发

VS Code 能力让用户直接进入沙箱工作区，查看 Agent 改动、运行测试、手动修复。

常见实现方式是：

• 沙箱内启动 code-server；
• 或启动 VS Code Server；
• 控制平面为当前会话生成短期访问 URL；
• 通过端口隧道暴露 IDE 服务。

工作流：

text📋 复制
用户点击 “Open in VS Code”
  ↓
控制平面校验用户是否可访问该 session
  ↓
生成一次性或短期 IDE token
  ↓
打开 https://sess-123-vscode.inspect.example.com
  ↓
VS Code 进入 /workspace/repo

IDE 入口可以抽象成：

http📋 复制
POST /api/sessions/sess_123/ide
Authorization: Bearer websocket_or_user_token
Content-Type: application/json

{
  "workspace": "/workspace/repo"
}

返回：

json📋 复制
{
  "url": "https://sess-123-vscode.inspect.example.com",
  "expiresAt": "2026-07-12T13:00:00.000Z"
}

VS Code 入口不要直接暴露沙箱裸端口，应该经过控制平面的鉴权或隧道鉴权。

---

关键代码/接口说明

创建会话

会话创建接口负责接收任务和仓库信息。

http📋 复制
POST /api/sessions
Content-Type: application/json
Authorization: Bearer user_token

{
  "prompt": "修复 checkout 页面 coupon 失效的问题",
  "repositories": [
    {
      "owner": "acme",
      "repo": "web",
      "branch": "main",
      "path": "web"
    }
  ],
  "primaryRepository": "acme/web"
}

返回值包含会话 ID：

json📋 复制
{
  "id": "sess_123",
  "status": "created"
}

创建后，后台 worker 会把会话推进到 provisioning。

---

分配沙箱

沙箱分配接口通常只在服务端内部调用。

ts📋 复制
type SandboxCreateInput = {
  sessionId: string;
  image: string;
  env: Record<string, string>;
  workspaceDir: string;
};

type SandboxCreateResult = {
  sandboxId: string;
  status: "starting";
};

示例：

ts📋 复制
await sandboxProvider.create({
  sessionId: "sess_123",
  image: "open-inspect/sandbox:latest",
  env: {
    SESSION_ID: "sess_123",
    CONTROL_PLANE_URL: "https://inspect.example.com",
    SANDBOX_AUTH_TOKEN: sandboxToken,
    WORKSPACE_DIR: "/workspace"
  },
  workspaceDir: "/workspace"
});

这里的 sandboxProvider 可以对应不同后端：本地 Docker、Kubernetes、Firecracker、云厂商 VM 等。模块上层不应该绑定某一种实现。

---

沙箱心跳

沙箱启动后需要持续告诉控制平面自己还活着。

http📋 复制
POST /api/sessions/sess_123/sandbox/heartbeat
Authorization: Bearer sandbox_session_scoped_token
Content-Type: application/json

{
  "sandboxId": "sbx_456",
  "status": "ready",
  "timestamp": "2026-07-12T12:00:00.000Z"
}

控制平面可以用心跳做：

• UI 在线状态；
• 自动重连；
• 判断会话是否卡死；
• 沙箱超时回收。

---

克隆仓库

仓库克隆最好由沙箱启动脚本统一完成，而不是让 Agent 第一步自己 clone。这样 Agent 进入时已经有稳定工作区。

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

mkdir -p "$WORKSPACE_DIR"
cd "$WORKSPACE_DIR"

for repo in "$@"; do
  # repo 格式示例：acme/web:web
  spec="${repo%%:*}"
  path="${repo##*:}"

  git clone "https://github.com/${spec}.git" "$path"
done

调用：

bash📋 复制
clone-repos.sh acme/web:web acme/api:api

生成：

text📋 复制
/workspace
├── web
└── api

---

创建端口隧道

端口隧道接口需要记录 session、端口和访问 URL。

ts📋 复制
type OpenPortInput = {
  sessionId: string;
  port: number;
  protocol: "http" | "https";
};

type OpenPortResult = {
  publicUrl: string;
  port: number;
};

示例：

ts📋 复制
const port = await portTunnel.open({
  sessionId: "sess_123",
  port: 3000,
  protocol: "http"
});

console.log(port.publicUrl);

---

打开终端

终端需要保持连接，所以一般用 WebSocket。

text📋 复制
GET /api/sessions/sess_123/terminal?token=ws_session_token

消息格式可以保持简单：

ts📋 复制
type TerminalMessage =
  | { type: "input"; data: string }
  | { type: "output"; data: string }
  | { type: "resize"; cols: number; rows: number }
  | { type: "exit"; code: number };

---

打开 VS Code

IDE 入口应该由服务端生成，而不是直接暴露沙箱内部 URL。

ts📋 复制
type CreateIdeUrlInput = {
  sessionId: string;
  workspacePath: string;
};

type CreateIdeUrlResult = {
  url: string;
  expiresAt: string;
};

示例：

ts📋 复制
const ide = await ideService.createUrl({
  sessionId: "sess_123",
  workspacePath: "/workspace/web"
});

return ide.url;

---

使用示例：本地模拟一个会话工作区

下面的示例不依赖 Open-Inspect 服务端，可以在本机直接运行。它模拟了一个沙箱会话会做的几件事：

• 创建 session 工作目录；
• 准备两个 git 仓库；
• 在主仓库里创建工作分支；
• 启动一个开发服务器；
• 生成“端口隧道 URL”的本地替代地址；
• 可选用 VS Code 打开工作区。

保存为 demo-session-sandbox.sh：

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

SESSION_ID="sess_demo_$(date +%s)"
ROOT_DIR="$(mktemp -d)"
WORKSPACE_DIR="$ROOT_DIR/workspace"

echo "Session: $SESSION_ID"
echo "Workspace: $WORKSPACE_DIR"

mkdir -p "$WORKSPACE_DIR"

echo
echo "==> 创建模拟远程仓库"

REMOTE_DIR="$ROOT_DIR/remotes"
mkdir -p "$REMOTE_DIR"

create_remote_repo() {
  local name="$1"
  local path="$REMOTE_DIR/$name"

  mkdir -p "$path"
  cd "$path"

  git init -q
  git config user.email "demo@example.com"
  git config user.name "Demo User"

  cat > README.md <<EOF
# $name

This is a demo repository for $SESSION_ID.
EOF

  git add README.md
  git commit -q -m "Initial commit"
}

create_remote_repo "web"
create_remote_repo "api"

echo
echo "==> 克隆多仓库到沙箱工作区"

cd "$WORKSPACE_DIR"
git clone -q "$REMOTE_DIR/web" web
git clone -q "$REMOTE_DIR/api" api

echo
echo "==> 在主仓库创建 Agent 工作分支"

cd "$WORKSPACE_DIR/web"
git checkout -q -b "inspect/$SESSION_ID-demo-change"

cat > index.html <<'EOF'
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Open-Inspect Sandbox Demo</title>
  </head>
  <body>
    <h1>Sandbox is running</h1>
    <p>This page is served from the session workspace.</p>
  </body>
</html>
EOF

git add index.html
git commit -q -m "Add demo page"

echo
echo "==> 启动开发服务器"

PORT="3000"
python3 -m http.server "$PORT" > "$ROOT_DIR/server.log" 2>&1 &
SERVER_PID="$!"

sleep 1

echo "Local dev server: http://127.0.0.1:$PORT"
echo "Tunnel-like URL:  http://localhost:$PORT"
echo "Server PID:       $SERVER_PID"
echo "Server log:       $ROOT_DIR/server.log"

echo
echo "==> 当前工作区布局"
find "$WORKSPACE_DIR" -maxdepth 2 -type d | sort

echo
echo "==> 主仓库 git 状态"
cd "$WORKSPACE_DIR/web"
git --no-pager log --oneline --decorate -3
git status --short

echo
echo "==> 如果安装了 VS Code，可以打开工作区"
if command -v code >/dev/null 2>&1; then
  echo "运行：code $WORKSPACE_DIR/web"
else
  echo "未找到 code 命令，跳过"
fi

echo
echo "==> 访问页面"
echo "curl http://127.0.0.1:$PORT"

echo
echo "==> 清理命令"
echo "kill $SERVER_PID"
echo "rm -rf $ROOT_DIR"

运行：

bash📋 复制
chmod +x demo-session-sandbox.sh
./demo-session-sandbox.sh

验证开发服务器：

bash📋 复制
curl http://127.0.0.1:3000

如果安装了 VS Code：

bash📋 复制
code /tmp/上面输出的目录/workspace/web

这个脚本展示的是“沙箱运行能力”的最小闭环。真实 Open-Inspect 部署里，mktemp 会替换成远程沙箱，localhost:3000 会替换成端口隧道 URL，git 本地路径会替换成 GitHub App token 认证的 HTTPS clone。

---

使用示例：多仓库任务的目录约定

下面的脚本演示 Agent 如何在多仓库环境中读取 API 仓库的信息，并修改 Web 仓库。

保存为 demo-multi-repo-task.sh：

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

ROOT_DIR="$(mktemp -d)"
WORKSPACE_DIR="$ROOT_DIR/workspace"

mkdir -p "$WORKSPACE_DIR/api" "$WORKSPACE_DIR/web"

cd "$WORKSPACE_DIR/api"
git init -q
git config user.email "demo@example.com"
git config user.name "Demo User"

cat > billing-status.json <<'EOF'
{
  "statuses": ["active", "past_due", "canceled"]
}
EOF

git add billing-status.json
git commit -q -m "Add billing status contract"

cd "$WORKSPACE_DIR/web"
git init -q
git config user.email "demo@example.com"
git config user.name "Demo User"

cat > render.js <<'EOF'
function renderBillingStatus(status) {
  return `Billing status: ${status}`;
}

module.exports = { renderBillingStatus };
EOF

git add render.js
git commit -q -m "Add billing renderer"

echo "==> Agent 读取 api 仓库 contract，并修改 web 仓库"

STATUSES="$(node -e "const s=require('$WORKSPACE_DIR/api/billing-status.json').statuses; console.log(s.join(', '))")"

cat > "$WORKSPACE_DIR/web/render.js" <<EOF
const knownStatuses = "$STATUSES".split(", ");

function renderBillingStatus(status) {
  if (!knownStatuses.includes(status)) {
    return "Billing status: unknown";
  }

  return \`Billing status: \${status}\`;
}

module.exports = { renderBillingStatus, knownStatuses };
EOF

cd "$WORKSPACE_DIR/web"
git diff -- render.js

echo
echo "Workspace: $WORKSPACE_DIR"
echo "Cleanup: rm -rf $ROOT_DIR"

运行：

bash📋 复制
chmod +x demo-multi-repo-task.sh
./demo-multi-repo-task.sh

这个例子对应真实场景：api 仓库提供契约，web 仓库消费契约。会话配置里应把 web 标为主仓库，避免 Agent 不小心在多个仓库里同时提交不可控变更。

---

注意边界

这是单租户系统，不要直接当 SaaS 用

README 已经明确说明：Open-Inspect 的安全模型是 single-tenant only。

原因是：

• 所有用户共享同一个 GitHub App installation；
• 系统不会在创建会话时逐个校验用户是否有目标仓库权限；
• 只要 GitHub App 能访问某个仓库，系统内可信用户理论上就能让沙箱 clone 它。

适合的部署方式：

• 公司内部；
• 同一组织成员都可信；
• 部署在 SSO、VPN 或内网后面；
• GitHub App 只安装到允许访问的仓库。

不适合：

• 多家公司共用一个实例；
• 公网开放注册；
• 需要严格按用户隔离仓库权限的场景。

---

Git clone 权限和 PR 创建权限不是一回事

Open-Inspect 的 token 架构里有两个关键凭据：

凭据	用途
GitHub App Token	clone、fetch、push 等 git 操作
User OAuth Token	创建 PR、用户信息、PR 归属

这意味着：

• 沙箱 clone 仓库依赖 GitHub App installation 范围；
• PR 创建优先使用用户 OAuth token；
• 如果用户不是 GitHub 登录，例如 Google 登录，PR 可能退回到 GitHub App bot 身份。

所以不要把“能 clone”理解成“用户本人有权限”。

---

多仓库要明确主仓库和可写范围

多仓库环境很方便，但也容易扩大变更范围。建议在会话配置里明确：

json📋 复制
{
  "primaryRepository": "acme/web",
  "repositories": [
    {
      "owner": "acme",
      "repo": "web",
      "path": "web",
      "writable": true
    },
    {
      "owner": "acme",
      "repo": "api",
      "path": "api",
      "writable": false
    }
  ]
}

如果项目暂时没有 writable 字段，也应该在 prompt 和系统约束里写清楚：

text📋 复制
api 仓库只用于读取接口定义，不要修改或提交 api 仓库。
只在 web 仓库创建 commit 和 PR。

---

端口隧道必须做鉴权

端口隧道暴露的是沙箱里运行的服务。开发服务器经常没有登录保护，甚至可能暴露调试页面、环境变量、内部接口。

因此端口隧道应该至少满足：

• 只有能访问该 session 的用户可以访问；
• URL 有过期时间；
• 不要把沙箱全部网络暴露出来，只转发指定端口；
• 默认只支持 HTTP，TCP 转发需要额外审查；
• 会话停止后关闭所有转发。

---

终端是高权限入口

终端等价于给用户一个沙箱 shell。即使沙箱是隔离环境，也要注意：

• 不要把长期 GitHub token 写入环境变量；
• 不要把 GitHub App 私钥放进沙箱；
• 终端输出可能包含 secrets，需要日志脱敏；
• 用户手动命令可能影响 Agent 正在运行的任务；
• 会话共享时，多人都能看到终端操作。

如果要支持多人协作，建议在日志里记录：

• 谁打开了终端；
• 谁输入了命令；
• 什么时候执行；
• 是否中断了 Agent 进程。

---

VS Code 入口不要绕过控制平面

VS Code 或 code-server 一旦暴露，就可以访问整个工作区文件。不要直接开放类似：

text📋 复制
http://sandbox-internal-ip:8080

更安全的做法是：

text📋 复制
用户 → 控制平面鉴权 → 短期 IDE URL → 端口隧道 → 沙箱 IDE 服务

并且：

• URL 设置过期时间；
• session 停止后立即失效；
• 不复用其他 session 的 IDE token；
• 尽量绑定当前用户或当前 session。

---

沙箱要能失败，也要能清理

实际运行里，下面情况都很常见：

• GitHub token 过期；
• 仓库 clone 到一半失败；
• npm install 卡住；
• dev server 占用端口；
• VS Code Server 启动失败；
• WebSocket 断开；
• Agent 进程失控；
• 沙箱所在节点重启。

模块实现时需要把失败作为正常路径处理：

• 每一步有超时；
• 状态可重试；
• 心跳丢失后标记 unhealthy；
• 停止会话时杀掉进程组；
• 回收端口隧道；
• 删除临时 token；
• 保留足够日志用于排查。

---

不要把沙箱当安全边界的全部

沙箱可以降低风险，但不能替代组织级访问控制。尤其在这个项目的单租户模型下，应同时做好：

• GitHub App 安装范围控制；
• 登录用户限制；
• SSO/VPN；
• 允许的邮箱域名或 GitHub org 限制；
• 日志审计；
• secret 注入最小化；
• 沙箱网络出口限制。

最重要的一条：GitHub App 不要安装到不希望 Agent 访问的仓库。