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，設定：

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 文件。自動測試只用 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 映像 revision computer-use-6：對齊 lazyBoy image/computer 的瀏覽器環境，避免蝦皮等站直接判定為機器人。容器與 box-chrome 設 LANG/LC_ALL=zh_TW.UTF-8、LANGUAGE=zh_TW:zh:en、TZ=Asia/Taipei（locale-gen zh_TW/en_US、/etc/localtime 指向台北）；字型補 fonts-liberation、fonts-dejavu-core、fonts-noto-color-emoji；Chromium 旗標改用 lazyBoy 的 lazyboy-browser 組合（--lang=zh-TW --accept-lang=zh-TW,zh,en-US,en --start-maximized --test-type --disable-features=TranslateUI --disable-session-crashed-bubble --hide-crash-restore-bubble --disable-infobars），另加 --disable-blink-features=AutomationControlled；HOME=/home/box 讓 Chromium 設定與 Crash Reports 留在 volume。

Box 映像 revision computer-use-7：桌面改成 lazyBoy image/computer 的樣子並瘦身、加上元件級操控。

• 顯示層：一個 Xtigervnc :1（framebuffer + VNC 同一程序、事件驅動）取代 Xvfb + x11vnc + autocutsel；剪貼簿由 vncconfig -nowin 同步。noVNC/websockify、xdotool、import 截圖與 DESKTOP_PROBE（WM、5900、6080）不變，解析度仍 1280x720（可用 LAZYBOY_SCREEN_GEOMETRY 覆寫）。
• 桌面：不再跑 startxfce4（xfce4-session／xfsettingsd／Thunar／自動開終端機都拿掉），只起 xfconfd + xfwm4 --compositor=off + xfdesktop + xfce4-panel。外觀沿用 lazyBoy：Arc-Dark、Papirus-Dark、jf open 粉圓、底部中文面板（應用程式／瀏覽器／終端機啟動器／工作列／時鐘）、同一張桌布；XFCE 設定每次開機從 /usr/share/lazyboy/xfce-skel 重灌到 /home/box/.config。
• Chromium：只在 profile 第一次啟動時開 welcome 頁（之前 --restore-last-session 加 URL 會出現兩個相同分頁）；另加 --force-renderer-accessibility --disable-background-networking --disable-component-update --renderer-process-limit=4。
• 元件級操控：box-a11y（python3 + AT-SPI）列出畫面上元件的角色／名稱／值／中心座標；computer 工具新增 snapshot 動作（ComputerStep::A11ySnapshot），回傳 snapshot 文字並照常附截圖。computerUse 提示改為先 snapshot 再點列出的座標。docker exec 啟動的程序透過 /tmp/lazyboy/dbus.env 加入桌面的 session bus 才能看到同一個 AT-SPI registry；gsettings toolkit-accessibility=true（dconf 在 /home/box/.config）讓 Chromium 願意輸出無障礙樹。
• 量測：桌面＋Chromium 閒置約 400 MiB（原 486 MiB），box-a11y 對一個網頁約 0.2 秒。

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 恢復）。