LazyBoy2/docs/SURFACES.md

# Box／本地工具與 profile 比對

比對日期：2026-09-14。參考來源為同層 `grok-bot-0.18-reconstructed` 原始碼；不是對原產品線上行為的保證。

| 用途 | 參考版 | LazyBoy2 調整後 |
|---|---|---|
| 一般工作／安裝／暫存 | Shell／Read → box | shell／read → Docker，預設工作面 |
| 使用者專案 | ExternalShell／ExternalRead → 本地執行代理 | external_exec_command／external_read_file／external_write_file／external_edit_file → 啟動端本地 |
| 跨機器檔案 | CopyToBox／CopyFromBox | copy_to_box／copy_from_box；不隱含掛載本地工作區 |
| 公開搜尋 | host → Cursor AiService.RunWebSearch | host → 相容 gateway；未指定 gateway 且模型設定為官方 xAI 時，host → xAI Responses web_search |
| 公開抓頁 | host → Cursor AiService.RunWebFetch | host 直接匿名 HTTP GET（HTML 轉文字、同 URL 十分鐘快取、redirect 重新檢查公開主機）；只有網站拒絕純 HTTP 時才退回 xAI 遠端瀏覽，並明確標記 model_rendered_web_content 與 fallback_reason |
| 登入網頁 | box Chrome | Docker Chromium，DOM helper 也在 Docker |
| 人工登入 | RequestBoxHelp → agent 桌面 | request_box_help／browser_handoff → 同一個 Docker Chromium |
| 桌面像素操作 | 父層 Screenshot；computerUse 子 agent 才有 Computer（click/type/…） | 父層 `screenshot` 唯讀；`spawn_subagent kind=computerUse` 才有 `computer`（xdotool `DISPLAY=:1`）。每個 named agent 一台 Docker 桌面；同一台電腦一次一個 computerUse |
| 瀏覽器資料 | /home/box/chrome-profile，另有 box store 同步 | /home/box/chrome-profile，lazyboy-box-home volume 持久保存 |

**WebSearch／WebFetch 不會讀取任何瀏覽器 profile 或 cookies。** 後端授權 token、模型 API key、網站登入 cookies 是三種不同資料。MCP 仍使用 connector 自己的授權，也不會自動取得 Chromium cookies。

自動操作與 noVNC 桌面連接同一個 Chromium。`browser_release` 只斷開 helper，保留桌面、頁籤及登入。Docker 正常停止時會先關閉 Chromium，讓 profile 落盤；強制 kill、當機或斷電不能保證最後一個操作已持久化。跨程序 helper 以 Docker 內 `flock` 排他使用瀏覽器，避免兩個任務同時操作。

本地一般 Chrome profile 不會自動匯入。先前 Docker Chromium 的 `/home/box/.config/chromium` 會以連結沿用；舊 Playwright owner profile 與 Firefox 資料均保留，不合併帳號；改用 Chromium 後，原 Firefox 網站可能需要重新登入。相容模式 `LAZYBOY_BROWSER_SURFACE=local` 才會使用原本的本地 Playwright／owner profile，且不會與 Docker 共用。Docker 不可用時不會偷偷切回本地。

## 遠端網頁設定

官方 xAI 模型設定可直接重用現有 API key。非官方相容代理需明確設 `LAZYBOY_WEB_PROVIDER=xai` 才會向該代理的 `/responses` 傳送原生搜尋請求；代理與模型必須真的支援這個介面。

要使用參考版的 web service contract，設定：

```sh
export LAZYBOY_WEB_BACKEND_URL='https://your-compatible-gateway.example'
# 服務需要驗證時，從本機環境／secret manager 設定 LAZYBOY_WEB_TOKEN。
```

Gateway 需要提供 JSON Connect `POST /aiserver.v1.AiService/RunWebSearch`（searchTerm、explanation、modelId），回傳 answer／documents。這不是普通 chat-completions endpoint。`web_fetch` 不經 gateway，一律由 host 直接 GET；先前每次抓頁都繞一趟模型推論（實測單頁 12 秒以上、每次約 US$0.01），改為直接 GET 後為次秒級。直接使用 Cursor 官方服務還需要它自己的登入與客戶端 headers；這裡沒有複製參考版的 account、checksum、privacy interceptor，不能把這個 adapter 當作已登入的 Cursor client。

來源：[xAI 官方 Web Search 文件](https://docs.x.ai/developers/tools/web-search)。自動測試只用 mock 與本地網站，未使用付費 API 驗證特定帳號的搜尋權限。

## 尚未等同參考版的部分

- 參考版在同一台 box 上分 per-agent monitor。此版改成每個 named agent 一個 Docker 容器（同一映像），各自 DISPLAY=:1、Chrome profile 與 `/workspace`。臨時 worker 用發起任務的 owner 座位。computerUse 按座位排他，不是全域一台螢幕。執行器仍是 xdotool，不是參考版 box 內的 protobuf ComputerUse executor / CUA。
- 參考版有 cloud box store／Chrome session snapshot，同步到遠端儲存；此版使用本機 Docker volume，未實作該雲端備份。
- 參考版 local-docker connector 可掛入 `.codex`／`.claude` 的唯讀 CLI 認證，並將 host runner 放進容器；此版 host/model/MCP 編排仍在本地，未自動掛入這些私人目錄。
- 本地工具沿用 LazyBoy2 既有工作區授權規則，沒有複製參考版每次 ExternalShell 的批准卡 UI。

## 原始碼依據

參考版根目錄下：

- `source/host/runner/system-prompt.ts`：Where you work、工作面選擇與 agent 桌面。
- `source/host/extensions/inference/production.ts`、`cursor-web-tools.ts`：Cursor 遠端搜尋／抓頁依賴。
- `source/packages/agent/tools/core/web-fetch.ts`：公開頁面、無認證、遠端服務限制。
- `source/host/extensions/box-store-sync/chrome-session-stage.ts`：Chromium cookies／storage snapshot 路徑。
- `source/electron-main/box/local-docker-host-connector.ts`：Docker host runner 與 CLI 認證 mounts。

## 驗證

`cargo test --workspace`、`cargo clippy --workspace --all-targets -- -D warnings`。
`box/build.sh lazyboy-box:surface-test` 建立測試映像。
`tests/box_surface_flow.py` 使用 `lazyboy-box:surface-test` 的獨立容器，檢查人工接手、helper 重連與 Docker 重啟的 profile 持久性；不使用正常工作容器。舊 `runtime_flow.py`／`team_flow.py` 的本地 fixture 測試明確指定 local 相容模式。

本次驗證：一般 Rust 測試 120 項通過；另以實際 Docker 通過 `computer_use_click_and_screenshot_on_box`（xdotool click + screenshot）。Clippy 通過。Box 映像 revision `computer-use-2` 含 xdotool 與 procps；`box-chrome` 以啟動鎖序列化 Chromium 冷啟動並清除跨 container 殘留的 `SingletonLock`，x11vnc 只監聽 localhost。

Box 執行期行為：截圖前會等 `SCREENSHOT_SETTLE_MS` 讓桌面重繪；每次截圖使用獨立的暫存檔，父 agent 的 `screenshot` 與 computerUse 子 agent 不會互相讀到對方的畫面。`shell` 輸出以 UTF-8 容錯讀取，超過上限時保留頭尾並在 `full_output` 給出可用 `read` 讀取的 `/tmp/gb-jobs/<id>/` 完整路徑。多個程序（CLI、browser helper、測試）同時初始化 box 時，以主機端 flock 序列化映像建置與 container 重建。

一般工具名 `shell`／`read`／`await_shell` 一律指向 box；`box_shell`／`box_read`／`box_await` 保留為舊 box 呼叫的別名。本地檔案與命令工具全部改成 `external_*`；舊模糊名稱如 `exec_command`／`read_file` 會報錯，不會隱含操作本地。Box 命令等待時間到後保留執行，以 `await_shell` 收取結果。關閉桌面瀏覽器不會阻止 shell/read 工作，下一次 browser 工具會重開原 profile。

此處的 box 是本機 Docker Linux 環境，並非另租的雲端主機；每個 named agent 的檔案與瀏覽器狀態隔離在自己的 container／volume，但 CPU、磁碟與 Docker daemon 仍屬於本機。開 agent 會啟動該座位並等到桌面就緒（或留下錯誤）；GET 狀態不會順便開機。CLI 的設定、對話紀錄與模型/MCP 編排也仍在本地。舊的 `lazyboy agent`／`run`／`computer` 仍使用全域 `lazyboy-box`。

CLI mock-provider 測試也已通過（包含串流工具呼叫、背景 subagent／external command 回覆與 session 恢復）。