Skip to content
Merged
95 changes: 95 additions & 0 deletions docs/tasks/T-1200/T-1242-instabox-core/brief.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
## 运行环境(云沙箱,必读)
- 开工先在 worktree 根目录运行 依赖准备脚本(镜像自带,把预装依赖链进 node_modules),之后 `pnpm exec vitest` / `pnpm exec tsc` 才可用。
- 这里**没有** systemd、Docker,说明里出现的 `systemd-run --scope ... --` 前缀一律去掉直接运行;机器 8G/4 核,一次只跑一个测试文件。
- 若本轮沙箱已放开(能联网、能监听端口),交回前必须把改动相关的测试全部跑过,包括需要端口的 e2e;涉及的 e2e 连跑 3 次都要过。跑不了的写明原因。
- 报告只写三样:改了什么(文件列表与 git status 一致)、为什么、测试命令与结果摘要。不要写长篇分析;完整输出放 verification 文本文件即可。
- 不提交 git。

# T-1242 云电脑①:核心客户端、开机/挂起、后端切换接线

(本任务是 T-1239 的第 1 块,与 ②③④ 并行开发。下面「共同约定」必须遵守。)

## 本任务负责的文件(只改这些;别的任务的文件不要碰)
- 新建:`server/instabox/machine.ts`(共享契约,按约定原样)、`server/instabox/client.ts`、`server/instabox/machines.ts`、`server/instabox/power.ts`、`server/instabox/key.ts`,以及它们的测试和你自己的假服务 `server/testing/fake-instabox-core.ts`。
- 修改:`shared/wire.ts:62`(按约定原样改那一行)、`server/config.ts`(加 `instabox?: { apiKey?: string }`,余量 10 行)、`server/store.ts:336`(允许 `cloudBackend: "instabox"`)、`server/routes/bot-patch.ts:389-390`(接受 instabox,错误文案改为 box, vps or instabox)、`server/cloud-backend.ts`(集中放后端判断小函数)、`server/index.ts`(余量约 110 行,你最多用 80 行,给 ⑤ 留 30 行)。

## 要做
1. `client.ts`:`createInstaboxRequest(apiKey: string, baseUrl = "https://api.instabox.sh"): InstaboxRequest`。带 X-API-Key;`idempotent: true` 时加随机 Idempotency-Key;非 2xx 抛带状态码和 错误码的错误(不得把钥匙写进错误或日志)。另导出 `waitOperation(request, opId, timeoutMs)`:`?wait=25s` 长轮询到 succeeded/failed。
2. `key.ts`:`instaboxApiKey(cfg)`:环境变量 `INSTABOX_API_KEY` 优先,否则 `cfg.instabox?.apiKey`,空串当未配置。`instaboxConfigured(cfg)`。
3. `machines.ts`:`createInstaboxMachines(request: InstaboxRequest): InstaboxMachines`,完整实现契约:
- 机器名 `crybot-<botId 前 12 位>`,metadata `{app:"crybot",botId}`;`find` 按名字查(`deleted` 视为没有)。
- `ensureRunning`:没有就建(linux→`agent-browser`,android→`android`,4 核 8G,autoSuspend 600);`suspended` 就 resume;`stopped` 就 start;`error` 抛错;中间态等到稳定;然后 `POST /desktop {"action":"start","width":1280,"height":800}`(桌面已在跑时接口返回的情况要容错)。同一 botId 并发调用只发一次创建(进程内单飞)。
- `suspend`、`remove`(带 X-Confirm-Delete)、`exec`(409 machine_not_running 时先 resume 再重试一次)、`readFile`、`writeFile`、`vncUpstream`(返回 `wss://api.instabox.sh/v1/machines/{id}/vnc` 和含钥匙的头;基址跟随 client 的 baseUrl,http→ws、https→wss,便于测试)。
4. `power.ts`:智能体回合结束、空闲时挂起机器(自身的 600 秒自动挂起是兜底,不必另写定时器的话可以只在删智能体/切走后端时处理);删除智能体时删除其机器;把智能体的后端从 instabox 切走时挂起(不删,留着可切回)。说明清楚你的选择。
5. `server/index.ts` 接线(只做本任务的部分):
- 现在很多地方写的是 `bot.cloudBackend === "vps" ? "vps" : "box"`。在 `cloud-backend.ts` 加一个小函数(如 `cloudKindOf(bot)` 返回 `"box" | "vps" | "instabox"`),把 index.ts 里涉及「这个智能体用哪种云电脑」的判断(约 2518、2915、4617、5955-6043、7902-8243、14995-15111 这些位置)改成三分支:instabox 智能体不走 Boat、不走 VPS,云电脑请求走 `createInstaboxMachines(...).ensureRunning(botId)`。
- 钥匙没配置时,选 instabox 的智能体要明确报「钥匙未配置」,不能悄悄回退到 Boat。
- 共用电脑(team computer)、本地 VM、多屏路径一律不动:继承共用电脑的智能体照旧走 Boat。
- 状态接口(约 14995 行 `backend:` 字段)返回 `"instabox"`。
- 智能体操作电脑的工具、远程画面、快照路由由 ②③④ 实现、⑤ 接进来;你这里**不要**引用它们的文件,只保证 `InstaboxMachines` 实例能被拿到:在 index.ts 里留一个函数 `instaboxMachinesFor(cfg)`(钥匙变了要换新实例,未配置返回 null),⑤ 会用它。
6. 测试:假服务覆盖创建→等操作单→开桌面、挂起中 exec 先 resume、并发 ensureRunning 只建一次、删除带确认头、错误里不含钥匙;后端判断函数的单测;bot-patch 接受 instabox;store 读回 instabox 不被删。e2e(用假服务把一个 instabox 智能体从无到开机)连跑 3 次。

## 验收
按「共同约定 · 测试」执行;report.md 只写实际改过的文件,并单独列出你在 index.ts 用了多少行、`instaboxMachinesFor` 的签名、需要 ④ 加的文案键(中英文)。

---

# T-1239 云电脑后端:共同约定(4 个并行子任务都必须遵守)

## 目标与范围(用户已定)
- 新增云电脑后端 `instabox`,与 Boat(box)、VPS(vps)并列,供单个智能体使用自己的云电脑。范围:Linux 桌面 + Android 模板,不含苹果。
- 共用电脑(team computer / 部门桌面)、本地 VM 私有桌面、多屏都**不改**,仍走原来的路。
- 所有机器用同一把 钥匙:配置 `instabox.apiKey`,环境变量 `INSTABOX_API_KEY` 覆盖;钥匙只在服务端,绝不进入机器、前端、日志或智能体上下文。
- 本仓库是**公开仓库**:代码、测试、文档里不得出现内部域名、IP、邮箱、人名、真实钥匙。公共接口域名 `api.instabox.sh`、`connect.instabox.sh` 可以出现。

## 接口要点(实测)
- 基址 `https://api.instabox.sh`,请求头 `X-API-Key: <key>`。
- 生命周期调用(POST /v1/machines、PATCH、start/stop/suspend/resume/restore、POST snapshots、DELETE)**必须**带 `Idempotency-Key`;删机器另带 `X-Confirm-Delete: <id>`。都返回 202 + 操作单 `{id,machineId,type,state,phase,error}`,用 `GET /v1/operations/{id}?wait=25s` 长轮询到 succeeded/failed。
- 机器 state:creating、starting、running、stopping、stopped、suspending、suspended、resuming、deleting、deleted、error。
- 创建:`{"name","templateId":"agent-browser"|"android","spec":{"vcpus":4,"memoryGiB":8},"autoSuspendAfterSeconds":600,"metadata":{...}}`。按名字找回机器:`GET /v1/machines`(按 name 过滤)。
- 新建、冷启动、restore、从快照新建之后桌面不运行:必须 `POST /v1/machines/{id}/desktop {"action":"start","width":1280,"height":800}`。
- exec:`POST /v1/machines/{id}/exec {"cmd"|"argv","envs","cwd","stdin","timeoutSeconds":1..600}` → `{stdout,stderr,exitCode,timedOut,truncated,...}`;非流式输出各 1 MiB 截断。默认没有 DISPLAY,桌面在 `:1`(Boat 是 :0)。后台任务用 `nohup setsid ... >log 2>&1 </dev/null &`。
- 手动挂起的机器调 exec/文件返回 409 `machine_not_running`,要先 resume;空闲自动挂起的机器 exec 会自动唤醒。挂起中不能 stop。
- 文件:`PUT /v1/machines/{id}/files?path=&mode=0644&parents=true`(原始字节)上传;`GET /v1/machines/{id}/files/content?path=` 下载。
- VNC:`wss://api.instabox.sh/v1/machines/{id}/vnc`,服务端带 `X-API-Key` 头连接;RFB 3.8,安全类型 None(无密码)。
- 快照:`POST /v1/machines/{id}/snapshots {"name","description"}`(名字 a-z0-9-,1–63,不重名)→ 轮询 `GET /v1/snapshots/{id}` 到 ready;`GET /v1/snapshots`;`POST /v1/machines/{id}/restore {"snapshotId","desiredState":"running"}`;`DELETE /v1/snapshots/{id}`。
- 机器命名:`crybot-<botId 前 12 位>`,metadata 带 `{"app":"crybot","botId":...}`。

## 共享文件(各任务需要时原样创建,内容必须一字不差;已存在就不要改)
`server/instabox/machine.ts`:
```ts
/** cloud computer: the contract the four backend pieces share. */
export type InstaboxTemplate = "linux" | "android";
export type InstaboxMachineState = "creating" | "starting" | "running" | "stopping" | "stopped" | "suspending" | "suspended" | "resuming" | "deleting" | "deleted" | "error";

export interface InstaboxMachine { id: string; name: string; state: InstaboxMachineState; template: InstaboxTemplate }

export interface InstaboxExecRequest { cmd?: string; argv?: string[]; envs?: Record<string, string>; cwd?: string; stdin?: string; timeoutSeconds?: number }
export interface InstaboxExecResult { stdout: string; stderr: string; exitCode: number | null; timedOut: boolean; truncated: boolean }

/** One authenticated API call. `idempotent: true` adds an Idempotency-Key; lifecycle calls need it. */
export type InstaboxRequest = (method: string, path: string, opts?: { body?: unknown; raw?: Uint8Array; idempotent?: boolean; headers?: Record<string, string>; query?: Record<string, string> }) => Promise<Response>;

export interface InstaboxMachines {
find(botId: string): Promise<InstaboxMachine | null>;
/** Create, resume or start the bot's machine as needed, then make sure its desktop runs. */
ensureRunning(botId: string, opts?: { template?: InstaboxTemplate }): Promise<InstaboxMachine>;
suspend(botId: string): Promise<void>;
remove(botId: string): Promise<void>;
exec(machineId: string, req: InstaboxExecRequest): Promise<InstaboxExecResult>;
readFile(machineId: string, path: string): Promise<Uint8Array>;
writeFile(machineId: string, path: string, data: Uint8Array, opts?: { mode?: string }): Promise<void>;
/** Where the server connects for this machine's VNC (RFB, no password); headers carry the key and never leave the server. */
vncUpstream(machineId: string): Promise<{ url: string; headers: Record<string, string> }>;
}
```
`shared/wire.ts:62` 改成(原行上改,不增行;文件正好 1000 行,多一行会挂行数门禁):
`export type CloudBackend = "box" | "vps" | "instabox";`

## 行数门禁
`scripts/testing/file-size-ratchet.test.ts`:登记文件不许变长,未登记文件不许超过 1000 行。`server/index.ts` 四个任务合计只剩约 110 行余量(由任务①统一占用),`ComputerPanel.tsx` 余量 25、`config.ts` 10、`store.ts` 17、`boat.ts` 1。新逻辑一律放 `server/instabox/` 下的新文件。

## 测试
- 不连真实 。写 `server/testing/fake-instabox.ts` 风格的假服务(`createServer` 起本地 HTTP/WS,`vi.stubEnv` 或依赖注入指过去);各任务若都需要假服务,各自放在自己命名的文件里(如 `fake-instabox-power.ts`),避免同名冲突。
- 本轮沙箱已放开,可监听端口:改动相关的测试全部跑过,涉及的 e2e 连跑 3 次。另跑 `pnpm exec tsc -p tsconfig.server.json`、前端有改动时跑前端 tsc,对改动文件跑 `oxlint --deny-warnings`。
- 文案只加 `src/locales/zh.json` 和 `en.json`(且只有任务④加;其他任务需要文案时在报告里列出键名和中英文,由④统一加,代码里先用这些键)。
27 changes: 27 additions & 0 deletions docs/tasks/T-1200/T-1242-instabox-core/r2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
## 运行环境(云沙箱,必读)
- 开工先在 worktree 根目录运行 依赖准备脚本(镜像自带,把预装依赖链进 node_modules),之后 `pnpm exec vitest` / `pnpm exec tsc` 才可用。
- 这里**没有** systemd、Docker,说明里出现的 `systemd-run --scope ... --` 前缀一律去掉直接运行;机器 8G/4 核,一次只跑一个测试文件。
- 若本轮沙箱已放开(能联网、能监听端口),交回前必须把改动相关的测试全部跑过,包括需要端口的 e2e;涉及的 e2e 连跑 3 次都要过。跑不了的写明原因。
- 报告只写三样:改了什么(文件列表与 git status 一致)、为什么、测试命令与结果摘要。不要写长篇分析;完整输出放 verification 文本文件即可。
- 不提交 git。

# T-1242 第 2 轮:恢复 run_on=cloud 走 Boat、管理策略覆盖 instabox、删除路径不留孤儿也不被 卡住

原任务见本文件夹 brief.md(含共同约定),工作区里上一轮改动保留,在此基础上改。第 1 轮审核:需要返工;安全审查:1 个中危(与必改 2 是同一个问题)。

## 必改
1. server/index.ts:5958-5963、:7915:恢复 routine `run_on="cloud"` 固定走 Boat 的语义(turnProvider 首行、beginTurn 的 cloudBackend 都要),与 turnSurfacePlan:5949 的 `forcedBoat`、cloudRoutineReadiness:8971-8975 的文案一致。写法如 `cloudKindOf(bot, Boolean(teamComputer) || opts?.runOn === "cloud")`。补回归测试:VPS 智能体、instabox 智能体跑 run_on=cloud 时都走 box。
2. 管理策略不能被 instabox 绕过(安全中危):server/cloud-backend.ts:58-61 `cloudPolicyKindOf` 对 instabox 不能返回 undefined。策略判断时把 instabox 归到 "box"(ComputerKind 里 box 的文案就是 "cloud computers"),默认拒绝;提示词种类可继续返回 null。用到的地方 index.ts:6056(selectableComputers)、:7931-7932(beginTurn wantedKind)、:9984(群聊 roomKind)都要生效;并在 `requireInstabox(...).ensureRunning(...)` 之前先过 `computerPlaceRefusal`。补测试:策略禁 box 时 instabox 智能体被拒、不调 ensureRunning;CLOUD_HOME 不提供 cloud 时同样被拒。
3. server/index.ts:9095、:9105:删除智能体时 Boat 和 VPS 两份清单照常列、照常删本智能体名下机器(从 box/vps 切到 instabox 后再删不能留孤儿);instabox 只是额外再删 机器。补测试。
4. server/index.ts:9117-9119:不是 instabox 的智能体,`instabox.remove()` 失败只降级成 notice(参照 vpsLeftOn 的做法),不挡删除;只有 instabox 智能体删机器失败时才保留智能体并返回 503,报错文案说明是 那边失败。补测试(假服务返回 5xx/网络错误时,Boat 智能体照样删得掉)。

## 一起改
5. server/instabox/power.ts:273-281:PATCH 切走后端时的 suspend 改成后台执行,不阻塞响应;失败只记 notice。
6. server/instabox/machines.ts:125-130:`find` 除名字外核对 `metadata.botId` 与本智能体一致,不一致不认(防止前 12 位相同的 id 共用、误删)。
7. server/instabox/machines.ts:169-175:已有机器的模板与请求不一致时明确报错,不要悄悄返回别的模板的机器。
8. server/instabox/machines.ts:161、198:不读的响应体 `await response.body?.cancel()`,别占着连接。
9. server/index.ts:15016-15019:状态接口里 instaboxStatus 出错时与 Boat/VPS 分支对齐,返回 problem 字段,不抛 500。
10. 文档位置:report.md、verification.txt 挪到 docs/tasks/T-1200/T-1242-instabox-core/(与 brief.md 同处),删掉 docs/tasks/T-1242/;verification.txt 里的沙箱绝对路径一律改成仓库相对路径。

## 验收
改动相关测试逐文件跑(含 cloud-backend、bot-patch、server/instabox/*、新增回归测试),core e2e 连跑 3 次;`tsc -p tsconfig.server.json`、改动文件 `oxlint --deny-warnings`;文件行数门禁通过(index.ts 净增仍要尽量少,shared/wire.ts 不超 1000 行)。report.md 追加第 2 轮一节,只写实际改过的文件。
25 changes: 25 additions & 0 deletions docs/tasks/T-1200/T-1242-instabox-core/r3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
## 运行环境(云沙箱,必读)
- 开工先在 worktree 根目录运行 依赖准备脚本(镜像自带,把预装依赖链进 node_modules),之后 `pnpm exec vitest` / `pnpm exec tsc` 才可用。
- 这里**没有** systemd、Docker,说明里出现的 `systemd-run --scope ... --` 前缀一律去掉直接运行;机器 8G/4 核,一次只跑一个测试文件。
- 若本轮沙箱已放开(能联网、能监听端口),交回前必须把改动相关的测试全部跑过,包括需要端口的 e2e;涉及的 e2e 连跑 3 次都要过。跑不了的写明原因。
- 报告只写三样:改了什么(文件列表与 git status 一致)、为什么、测试命令与结果摘要。不要写长篇分析;完整输出放 verification 文本文件即可。
- 不提交 git。

# T-1242 第 3 轮:只修复审必改项

原任务见本文件夹 brief.md、r2.md,工作区里上一轮改动保留。第 2 轮复审:需要返工。本轮只做下面几条,别的不动。

## 必改
1. server/index.ts beginTurn 的策略判断(约 :7933):`wantedKind` 现在用 `cloudPolicyKindOf(bot, Boolean(teamComputer))`,漏了 run_on=cloud。VPS 智能体跑 run_on=cloud 时实际挂 Boat,却按 "vps" 判,策略「禁 box、允许 vps」可被绕过。改成从已算好的 `cloudBackend` 推出(或给 `cloudPolicyKindOf` 传 `Boolean(teamComputer) || opts?.runOn === "cloud"`),保证实际用哪种电脑就按哪种判。
2. 补齐 r2 第 1–4 条要求的回归测试(放在能驱动 turnProvider/beginTurn 和删除流程的 index 层或 e2e 测试里,不只测纯函数):
- VPS / instabox 智能体跑 run_on=cloud 时走 box,且策略按 box 判(覆盖上面第 1 条);
- 策略禁 box、CLOUD_HOME 不提供 cloud 时,instabox 智能体被拒,且不调 ensureRunning;
- 从 box/vps 切到 instabox 后删除智能体,Boat/VPS 上的机器照样被删;
- 假服务返回 5xx 或网络错误时,Boat 智能体照样能删并带 notice;instabox 智能体保留并返回 503。
3. docs/tasks/T-1200/T-1242-instabox-core/report.md 追加「第 2、3 轮」一节:只写实际改过的文件;文件清单去掉已删的旧目录;index.ts 行数按实际重算;文案键表删掉代码里已不用的 `computer.instabox.suspendFailed`。verification.txt 重新生成本轮测试结果(不要写 IP、内网地址、域名)。

## 顺手改
4. server/index.ts 约 :9125:instabox 智能体删机器失败时不要直接 `return deletionResponse(503, …)`,改为照原写法 `throw Object.assign(new Error(...), { status: 503 })`,让外层 catch 里的 browserCleanup.abort 照常执行。

## 验收
改动相关测试逐文件跑;`tsc -p tsconfig.server.json`、改动文件 `oxlint --deny-warnings`。
Loading
Loading