AnyBot/docs/plan-2026-11-computer-use.md

# 規劃：Computer-Use 順暢度優化 ＋ Docker 登入資訊持久化（2026-11）

> 狀態：**僅規劃，未動工**。依據：對本 repo（`src/cloudbox.rs`、`src/computer.rs`、`src/agent.rs`、`src/browser.rs`、`src/vnc.rs`、`box/*`、`deploy/`、`install.sh`、`BUGS.md`）的程式碼研究，與 2026-11 的網路調查。
> 行號以 2026-11-06 的程式碼為準。

---

## 一、現況盤點（從程式碼看到的）

### 1. 三條 computer-use 路徑

| 目標 | 派發點 | 執行端 | 截圖來源 |
|---|---|---|---|
| Box（Bot 的電腦，Docker 容器） | `src/agent.rs:1114` → `cloudbox::computer_run` | 一步一條 `docker exec` 內跑 xdotool（`src/cloudbox.rs:1223-1227`） | 容器內 ImageMagick `import -window root`（`src/cloudbox.rs:1249`） |
| 地端本機（Mac / Linux 桌面） | `src/agent.rs:1122` → `computer::run_by` | Mac：CGEvent＋`screencapture`（`src/computer.rs:915-931,1100-1137`）；Linux：X11 XTEST / wlr 協定 / Portal（`src/x11.rs`、`src/wl.rs`、`src/portal.rs`） | `screencapture` / X11 GetImage / wlr-screencopy |
| 帳號內其他電腦（手腳/螢幕） | `src/agent.rs:1106` → `remote::run_on_device`（`src/remote.rs:1146-1169`） | 對端本機執行，JSON＋base64 JPEG 原路回傳（`src/remote.rs:645-647`） | 對端本機截圖 |

工具規格統一為 9 個 `computer_use_*`（`src/computer.rs:15,250-282`）＋ `hand_over_computer`；瀏覽器走 CDP 的 18 個 `browser_*`（`src/browser.rs:314-333`）。編號截圖（set-of-mark）由 AT-SPI 控件編號（`src/marks.rs`、`box/a11y`）與網頁端注入 JS 編號（`src/browser.rs:103-179`）實作，方向與業界 2026 主流一致。

### 2. Box 每一步的延遲預算（估，待 Phase 0 量測確認）

| 階段 | 估計 | 來源 |
|---|---|---|
| 模型回合（TTFT＋生成） | 2000–8000 ms | 瓶頸主因，非程式碼可消 |
| `docker exec` 進程生成＋RPC | 50–200 ms | 程式註解自估（`src/cloudbox.rs:1225-1226`），遠端 Docker host 更高 |
| 動作（xdotool） | 10–100 ms | 按鍵 delay 8ms～click repeat 80ms（`src/cloudbox.rs:90-91`） |
| 固定 SETTLE | 500 ms | `src/computer.rs:18`、`src/cloudbox.rs:1414` |
| 截圖 `import`（1280x800→JPEG） | 100–400 ms | ImageMagick 每次冷啟動，CPU 编码 |
| AT-SPI 讀取 | 0–3000 ms（預算制） | `--budget 3`（`src/cloudbox.rs:1501`），Chromium 常接近頂 |
| 編號繪製＋回傳 | 10–50 ms | `src/computer.rs:284-325` |

結論：**模型回合佔 6–8 成**，環境端開銷約 0.7–3.5 秒/步。因此「減少模型回合數」（批次動作）比「壓榨環境延遲」的性價比更高；兩者都做，順序見後。

### 3. 已知痛點（BUGS.md ＋ 程式註解）

- 多 Bot 共用 box 無隔離、VNC 無密碼（B18，已修）；修飾鍵卡死（B19，已修）；取消指令留孤兒進程（B24，已修，用 `ANYBOT_JOB` 標記）。
- box 15 分鐘休眠凍死 noVNC（N3，已修：大腦端不休眠 `src/cloudbox.rs:753-776`）。
- 舊 box 兩套 Chromium profile 登入互不相通（`box/browser:11-21`，已合併為 `anybot-profile` symlink）。
- `mousemove --sync` 會永久阻塞（`src/cloudbox.rs:1305-1306`）；大截圖塞爆 pipe（`src/cloudbox.rs:461-463`）。
- VNC 即時畫面走 `docker exec python3` 橋接容器內 5900（`src/vnc.rs:27-39`）：橋接每字節多一层 exec 管線，人在遠端看 box 畫面卡。
- `keep_to_chosen` 以關鍵字改寫 `computer` 參數可被注入（B26，設計弱點，已收窄）。
- 無每步計時遥測：順暢度只能靠感覺，無法歸因。

### 4. 登入資訊現況（持久化）

- Chromium profile：容器內 `/home/bot/.config/anybot-profile` → symlink 到 `.config/chromium`（`box/browser:18-25`），`--password-store=basic`（cookie 以本機金鑰加密存檔，容器內可解密，跨重建有效）。
- 持久化：`/home/bot` 掛 named volume `anybot-box-home`（`src/cloudbox.rs:60,612,617`）。
- 三種重建（`src/cloudbox.rs:1009-1057`）：
  - **Update（含自動版本更新）**：先存快照 → `docker rm -f` 容器 → 重開，**volume 不動，登入保留** ✅
  - **Reset**：`docker volume rm -f anybot-box-home` → 登入全消失 ⚠️
  - **Restore**：先殺 volume，從本機快照 `snapshot.tar.gz` 還原
- 快照：`docker exec tar` 打包整個 `/home/bot`（排除各快取目錄，`src/cloudbox.rs:839-844`），存到 AnyBot 資料夾；每日＋閒置 900 秒自動存（`src/cloudbox.rs:82-85,778-782`）。
- 伺服器部署：box 與 volume 在大腦容器的宿主 Docker 上（`deploy/server/docker-compose.yml`，大腦掛 `/var/run/docker.sock`）；快照存進 `anybot-data` volume——**與 box volume 同一顆碟**（同一故障域）。
- 全 repo 沒有任何 `docker volume rm`（除 Reset/Restore）、`down -v`、`prune`：更新流程本身不會清登入 ✅

---

## 二、網路調查摘要（2026-11，可用什麼）

### 1. 模型／框架層（少數可直接借鏡的點）

| 專案/文件 | 要點 | 對 AnyBot 的用法 |
|---|---|---|
| Anthropic computer-use 官方文件＋2026-05 最佳實務文（`computer_toolset_20260801`） | **Batch actions**：模型一次回傳一串動作依序執行，批次結尾自動附截圖省一個回合；官方明言批次適用「填多欄表、串捷徑」，不適用探索/失誤恢復；系統提示要模型「每批以截圖結尾」「一句話驗證畫面」 | 高價值，直接對應瓶頸（模型回合數）。做成 `computer_use_batch` 工具（見 Phase 1） |
| Anthropic harness 設計三原則（2026-04） | 用模型已熟的工具、砍掉多餘 scaffolding、邊界給模型 | 檢查 9+18+11 個工具是否可收斂，工具描述精簡＝省 token＝省 TTFT |
| cua-speedrun（arXiv 2609.40284） | 速度瓶頸主要在 harness/模型選擇與推理預算；「環境 I/O 變快有時整體反而變慢」；統一量測很重要 | 佐證：先做遥測與批次（回合數），再做環境微優化；KasmVNC 類優化排後面 |
| OSWorld-Human（MLSys 2026） | 現有最佳 agent 步數遠多於人類，效率（WES）是新賽點 | 支持「批次＋經驗庫（示範重播）」降步數 |
| Agent S4（Simular，OSWorld 2.0 開源 SOTA） | 讓 agent 從任務經驗中「演化自己的工具介面」；經驗庫（experience retrieval） | 對應現有 `teach`（示範錄影）：進階成「示範→可重播巨集→檢索重用」 |
| UI-TARS-2 / OpenCUA | 開源 GUI 模型族（7B–72B，OSWorld-Verified 27–45%），UI-TARS Desktop 是最完整開源桌面 agent app | 作為離線/本機模型（Ollama 路徑）的未來選項；短期不整合 |
| browser-use（含 Browser Harness）、Stagehand、Playwright MCP、chrome-devtools-mcp、agent-browser（Vercel）、Skyvern | 瀏覽器 agent 分三條跑道：全權 agent / 純工具層（MCP）/ 工作流產品；CDP＋a11y 樹是主流讀頁方式；Playwright MCP 的 AX snapshot 吃 token 兇（4.4M/任務 vs Harness 2.1M） | 我們的 `browser_*`（CDP＋ref 編號）已是主流形態；借鏡：snapshot 壓縮、只回傳變化部分；偵測牆重的站點才考慮雲端 stealth 層 |

### 2. 雲端沙箱／瀏覽器服務（對應「雲端電腦」）

| 服務 | 形態 | 適配評估 |
|---|---|---|
| **E2B Desktop** | Firecracker microVM 桌面沙箱，pause/autopause、持久 FS、BYOC/自架 runtime 開源（Apache-2.0） | 語意最接近 box 的雲端替代品。適合做 `cloudbox provider` 適配器 spike（Phase 4），保留快照/喚醒語意，隔離比容器強（microVM） |
| Daytona | 桌面 VM 沙箱（含 Windows/macOS），snapshot API，<90ms 冷起；2026-06 起核心閉源 | 需要 Windows/macOS 雲端手腳時再評估 |
| Modal / Novita / Vercel Sandbox / Cloudflare Sandbox / Blaxel | 通用 code sandbox（gVisor/容器） | 偏程式執行，非 GUI；不是 box 的替代品 |
| **Steel**（開源可自架）、Browserbase、Kernel、Hyperbrowser、Browser Use Cloud、Anchor、Browserless | 雲端瀏覽器即服務（session 持久化、stealth、CAPTCHA、Kernel 有 auth vault 代管登入） | 是「瀏覽器層」的雲端延伸，不是整台電腦。AnyBot 本地優先＋自架哲學 → 若做，先 spike **Steel 自架**（Apache/MIT，可跑在自己伺服器），當 `browser` 的第二後端；登入代管需求強再看 Kernel |
| Kasm Workspaces／kasmweb 映像、linuxserver Webtop、accetto ubuntu-vnc-xfce-g3、testcontainers all-in-one-sandbox | 容器化桌面＋串流的現成做法 | 印證 box 架構是業界常規；Kasm 系列的亮點在串流引擎（下條） |

### 3. 串流/畫面順暢度（人看 box 的 VNC）

| 方案 | 重點 | 評估 |
|---|---|---|
| **KasmVNC**（開源） | 脫離 RFB 規格：WebP/JPX 自適應壓縮、多執行緒編碼、WebCodecs H.264/AV1、WebRTC UDP、內建 web client、多語系鍵盤轉譯 | 人機畫面體驗的天花板；**代價大**：現有 `src/vnc.rs` 的 RFB 代理與「人操作偵測」失效，需改用其 web client＋整合 hand_over 流程 → 做實驗性 box flavor，不全面替换 |
| TurboVNC / TigerVNC 調參（UltraZoom、品質、縮色） | 保留 RFB，改編碼參數即可 | 便宜的中間方案：viewer 端參數先調（`-Scale`、`-Quality`、`CompressLevel`），零架構風險 |
| 直接把 noVNC 走已發布的 loopback 埠（16080） | 本地 Docker 時現行 exec 橋接可整個繞過（`src/vnc.rs` 只在遠端/中繼需要） | 快速獲益：本地看 box 畫面立刻順（Phase 2） |
| Sunshine/Moonlight、Looking Glass | WebRTC 遊戲級串流，需 GPU | 無頭容器不適用 |

### 4. 持久化/備份（對應「登入資訊不丟」）

| 做法 | 來源 | 適用 |
|---|---|---|
| named volume 跨容器重建保留（現行做法） | Docker 官方 volumes 文件 | ✅ 已做，Update 重建安全 |
| `docker run --rm --volumes-from <box> -v $PWD:/backup alpine tar czf ...` 離 volume 備份 | Docker 官方「back up/restore volumes」 | 現行快照（`docker exec tar`）等效且更好（在 Mac 端落地）；重點是**多代＋離機** |
| 「持久 ≠ 備份」：volume 擋得住容器重建，擋不住磁碟損壞、`volume prune`、Docker Desktop「Clean/Purge data」、整機遺失 | Docker Desktop backup/restore 文件；多篇 2026 自架備份指南 | 見第三章風險清單 |
| restic/borg 加密增量備份到物件儲存/另一台機 | 自架備份指南（2026-08） | data_dir（含快照、secrets）的離機備份正解；relay 已有**加密備份**通道可先复用 |
| 瀏覽器登入本身的過期問題（伺服器端 session、2FA、IP 跳變風控） | browser infra 各家（Kernel 的 vault 賣點就是這個） | volume 救不了過期：需要「登入健康檢查＋通知接手」與穩定出口 IP（egress via Mac 已有此雛形） |

---

## 三、登入資訊持久化：風險清單與方案

### 現行已安全的情境

| 情境 | 結果 |
|---|---|
| AnyBot 升級、box 自動/手動「重建電腦」（Update） | 登入保留（volume 不動）✅ |
| 容器崩潰、`docker rm`、Docker 引擎重啟 | 登入保留 ✅ |
| Chromium 被 kill -9 | SingletonLock 有清（`box/browser:40`）、crash-bubble 已藏 ✅ |

### 會丢登入的情境（依風險排序）

1. **Reset／Restore 重建**：直接 `docker volume rm -f`（`src/cloudbox.rs:1036,1047`）。Restore 有快照墊底，**Reset 目前無任何补救**。
2. **快照只有一代**：`snapshot.tar.gz` 每日覆蓋（`src/cloudbox.rs:395-397`）。快照裡登入了過期 cookie、或存到一半被污染，後代無法回退。
3. **同一故障域**：伺服器部署時快照在 `anybot-data`、volume 在同機 Docker 儲存——整機/磁碟遺失或 Docker Desktop「Clean/Purge data」、重裝 Docker，全沒。
4. **`docker volume prune` / `system prune --volumes`**（使用者手動）：box 被 `rm -f` 後、重開前的空檔，volume 是 dangling 狀態，prune 會殺；`ANYBOT_BOX_NAME` 改名後舊 volume 也成 dangling。
5. **切換 `docker_host`**（`src/cloudbox.rs:292-307`）：新 host 上 box 從無到有，volume 是全新的——登入看起來「消失」。
6. **登入自然過期／風控**：cookie 在 volume 裡好好活著，但伺服器端 session 失效、2FA 要求、IP 大跳（雲端 host）被要求重登。

### 方案（P1 先做 1–4，P2 做 5–7）

| # | 項目 | 內容 | 落點 |
|---|---|---|---|
| L1 | 快照多代輪替 | `snapshot-YYYYMMDD-HHMM.tar.gz`，保留最近 7 日＋4 週，`save_snapshot` 寫新檔、清舊檔；UI 顯示代數與時間 | `src/cloudbox.rs:395-397,835-880` ＋ 設定頁 |
| L2 | 殺 volume 前強制快照 | `run_rebuild(Reset/Restore)` 進入 `cleaning-up` 前，若 box 在跑必先 `save_snapshot`（標記 `pre-reset`），失敗即中止重建 | `src/cloudbox.rs:1032-1056` |
| L3 | 新 volume 自動回灌 | `create_container` 偵測 volume 為空且快照存在 → 自動 `copy_in_snapshot`（開機即回登入住家）；UI 可開關「自動回灌」 | `src/cloudbox.rs:605-618` |
| L4 | 防 prune 網 | 容器被殺後的空檔用「無特權佔位容器」掛住 volume（`docker run -d --name anybot-box-home-holder -v anybot-box-home:/h busybox sleep infinity`）；`make doctor` 加 volume 健康檢查 | `src/cloudbox.rs` ＋ `Makefile` |
| L5 | 快照離機備份 | 復用 relay 的**加密備份**通道把 snapshot 推到帳號伺服器（伺服器打不开）；或一鍵「匯出快照」成檔給使用者自管（Time Machine/rclone/restic 都吃得下）；文件寫明「持久≠備份」 | `src/remote.rs`＋快照 UI＋README |
| L6 | 切 docker_host 帶家走 | `set_docker_host` 前：舊 host 存快照 → 新 host 建 box 後自動回灌；失敗時明確告知「登入在舊主機快照裡」 | `src/cloudbox.rs:292-307` |
| L7 | 登入健康檢查 | 排程（每週）用 CDP 開 2–3 個常用站查登入態標記；掉登入→通知＋`hand_over_computer` 請人重新登入（登入動作本來就該人做）。配合 egress-via-Mac 保持出口 IP 穩定 | 排程器＋`botbrowser`/`browser` 層 |

配套原則（不動程式也要守的慣例）：
- 更新伺服器只用 `docker compose up -d --build`，絕不用 `down -v`；文档註明。
- 永不在 box 所在 host 跑 `docker system prune --volumes`。
- 快照內容＝登入住家：檔案權限 600（現行已做），含快照的備份視為敏感資料。

---

## 四、Computer-Use 順暢度優化方案（依投資報酬排序）

### Phase 0：先量測（半週）
- 每步分段計時（exec spawn／動作／settle／截圖／a11y／編碼／模型 TTFT）寫入現有 build-activity log 與使用統計；設定頁加「電腦卡」顯示每步中位數。
- 準則依據（cua-speedrun）：先歸因再優化。驗收：能回答「一步的 2.5 秒花在哪」。

### Phase 1：減少模型回合＋環境微優化（box 優先，1–2 週）
1. **`computer_use_batch` 工具**：一次工具呼叫依序跑 `[{click|type|key|scroll...}...]`，結尾自動附一張截圖＋控件清單。對照 Anthropic 官方語意（依序執行、失敗即停並回報未執行項、批次適用表單/捷徑、探索任務不用）。與 `HELD_BY_PERSON`/重複攔截（`src/agent.rs:492-509`）整合：每個子動作前檢查人接管。
2. **長駐 daemon 取代 per-step `docker exec`**：box 內跑一個 Python 常駐服務（unix socket，經一條持久 `docker exec` 橋接），處理 xdotool 序列＋`import` 截圖＋AT-SPI 快取。每步省 50–200 ms 與進程冷啟動；遠端 docker host 情境受益最大。
3. **自適應 settle**：500ms 固定等待改為「動作後輪詢 X 畫面差（daemon 內 XShmGetImage 縮圖 diff），穩定即截」（上限仍 500ms、下限 80ms）。靜態頁面省下 ~400ms/步。
4. **截圖換引擎**：daemon 內直接 XShm 取 framebuffer（免 ImageMagick 冷啟動），Rust 端统一 JPEG（現成 `src/computer.rs:284-325` 管線）。a11y 讀取與截圖併發。
5. **Prompt 微調**（零風險，先行）：依 Anthropic 2026-05 文：加「用一句話說明截圖顯示了什麼、步驟是否成功」「可批次時優先批次」；保留現有「畫面沒變就換方法」與 ref 制。
6. （地端 Mac 同步受益）`computer_use_batch` 在 `computer::run_by` 實作同一工具面，三條路徑語意一致。

驗收：表單類任務步數 -30% 以上；box 每步環境時間中位數 -30%（以 Phase 0 基線計）；無新增 B 級 bug。

### Phase 2：人機畫面體驗（3–5 天）
1. 本地 Docker 時 viewer 直連已發布的 `127.0.0.1:16080`（跳過 exec 橋接）；遠端情境保留 vnc.rs/relay 路徑。
2. TigerVNC 端編碼調參（Tight/UltraZoom 品質、允許 32bpp）＋noVNC 端 `quality`/`compression` 參數化進設定頁。
3. （實驗）KasmVNC box flavor 原型：一個分支用 KasmVNC 取代 TigerVNC+noVNC，iframe 掛其 web client，評估 fps/延遲/整合成本，量化後再決定是否併入 `vnc.rs` 協議層。**不動主線**。

驗收：本地看 box 畫面可互動不卡；遠端情境有 A/B 數據。

### Phase 3：持久化落地（1 週）
- 实施 L1–L4（P1），接著 L5–L7（P2）。
- 驗收：情境演練——(a) Reset 後能从 `pre-reset` 快照救回；(b) 手動 `docker volume rm` 後重開 box 自動回灌登入；(c) 模擬快照全丢，能從 relay 加密備份還原；(d) doctor 能報出 volume 缺失。

### Phase 4：雲端選項研究（spike，各 2–3 天，不進主線）
1. **E2B Desktop spike**：實作一個 `cloudbox` provider 介面（create/pause/snapshot/exec/截圖），跑通 E2B Desktop 模板→同一組 `computer_use_*` 工具打雲端 microVM；記錄延遲、成本、快照語意差异（E2B 快照＝檔案+記憶體態，比 tar 快照更完整）。
2. **Steel 自架 spike**：在自家伺服器跑 Steel（開源），把 `browser_*` 的 CDP 端點指過去（CDP 相容＝改 URL 即可），驗證雲端瀏覽器 session（登入持久化由服務端 vault 管）與成本。
3. 產出比較表（本機 box vs E2B vs Steel）後再開立項討論。

### 後續候選（不排程，記錄方向）
- **示範→巨集重播**（接 `teach` 錄影，Agent S 式經驗庫）：把成功軌跡壓成可重放的 ref 序列，重複性任務直接重播，是最徹底的降步數手段。
- 模型端：OpenCUA/UI-TARS 開源模型作為 Ollama 路的 computer-use 專用小模型。
- box 多 Bot 隔離升級（B18 群）：每 Bot 一個 box（volume 每 Bot 一份，登入也每 Bot 一份）——順帶解決「登入互相踩」的問題。

---

## 五、執行順序總覽

| 週 | 內容 | 風險 |
|---|---|---|
| W1 | Phase 0 遥測；Prompt 微調；L1/L2/L3/L4（持久化四件套） | 低 |
| W2–3 | Phase 1（batch 工具→daemon→settle→截圖引擎，逐項上線逐項量） | 中（daemon 是新常駐面，需守 person-takeover/取消/逾時） |
| W4 | Phase 2（viewer 直連＋調參；KasmVNC 原型）；L5/L6 | 低–中 |
| W5 | L7 登入健康檢查；Phase 4 spikes；開會決定雲端路線 | — |

## 六、主要參考（2026-11-06 查證）

- Anthropic：Computer use tool 文件（batch actions、`computer_toolset_20260801`）、Best practices for computer and browser use（2026-05，computer_batch/browser_batch）、Agent harness design（2026-04）。
- 研究：cua-speedrun（arXiv:2609.40284，速度瓶頸歸因）、OSWorld-Human（MLSys 2026，步數效率）、OSWorld 2.0。
- 開源框架：Agent S（simular-ai，S4）、UI-TARS Desktop / Agent TARS（bytedance）、OpenCUA（xlang.ai）、Cua（trycua）。
- 瀏覽器：browser-use／Browser Harness、Stagehand（Browserbase）、Playwright MCP（Microsoft）、chrome-devtools-mcp、agent-browser（Vercel）、Skyvern。
- 串流：KasmVNC（kasmtech，WebP/WebRTC/多緒編碼）、kasmweb 映像庫、accetto ubuntu-vnc-xfce-g3、TigerVNC 調參指南（2026-02）。
- 雲端沙箱：E2B（含 Desktop、自架 runtime）、Daytona（2026-06 起閉源）、Modal、Novita、Vercel Sandbox；雲端瀏覽器：Steel（開源自架）、Browserbase、Kernel（auth vault）、Hyperbrowser、Browser Use Cloud。
- 持久化：Docker volumes 官方文件（back up/restore/migrate）、Docker Desktop backup-and-restore、「持久≠備份」自架備份架構指南（2026-08，restic/borg）。