daniel.w
/
LazyBoy2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
LazyBoy2/docs/SURFACES.md

7.1 KiB
Raw Blame History

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 相容 gateway，或 xAI 遠端瀏覽；xAI 回傳明確標記 model_rendered_web_content，不是原始 HTTP 內容
登入網頁 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）。一次一個 computerUse
瀏覽器資料 /home/box/chrome-profile，另有 box store 同步 /home/box/chrome-profile，grokboy-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 網站可能需要重新登入。相容模式 GROKBOY_BROWSER_SURFACE=local 才會使用原本的本地 Playwright／owner profile，且不會與 Docker 共用。Docker 不可用時不會偷偷切回本地。

遠端網頁設定

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

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

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

Gateway 需要提供 JSON Connect POST /aiserver.v1.AiService/RunWebSearch（searchTerm、explanation、modelId）與 RunWebFetch（url）。Search 回傳 answer／documents；Fetch 回傳 success.content 或 error。這不是普通 chat-completions endpoint。直接使用 Cursor 官方服務還需要它自己的登入與客戶端 headers；這裡沒有複製參考版的 account、checksum、privacy interceptor，不能把這個 adapter 當作已登入的 Cursor client。

來源：xAI 官方 Web Search 文件。自動測試只用 mock 與本地網站，未使用付費 API 驗證特定帳號的搜尋權限。

尚未等同參考版的部分

  • 參考版提供 per-agent monitor／desktop；此版仍是單一 Docker 桌面（DISPLAY=:1），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 grokboy-box:surface-test 建立測試映像。 tests/box_surface_flow.py 使用 grokboy-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 環境，並非另租的雲端主機；檔案與瀏覽器狀態隔離在 container／volume，但 CPU、磁碟與 Docker daemon 仍屬於本機。CLI 的設定、對話紀錄與模型/MCP 編排也仍在本地。

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