# 通用 CLI 流程

> 瀏覽器工作面更新：預設改為 Docker 共用 Chromium；以下 owner-local profile 說明僅適用 `GROKBOY_BROWSER_SURFACE=local`。目前路由與差異見 [SURFACES.md](SURFACES.md)。

本文描述原本的單 session 模式。多主 agent、背景任務、獨立聊天與常駐服務見 [TEAM](TEAM.md)。

## Codex 參考

2026-09-13 查阅使用者指定的 [codex-rs](https://github.com/openai/codex/tree/main/codex-rs)：

- [session/turn.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/session/turn.rs)：依後續工具工作與待處理輸入繼續回合，分開對待 commentary 與最後訊息，等待工具結果。
- [plan_spec.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/plan_spec.rs)：`update_plan` 的步驟與狀態，最多一步 `in_progress`。
- [request_user_input.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/request_user_input.rs)：透過 session 請求使用者資訊並將答案交回工具流程。
- [unified_exec.rs](https://github.com/openai/codex/blob/main/codex-rs/core/src/tools/handlers/unified_exec.rs)：命令執行與後續 stdin／增量輸出分開處理。

本專案採用這些控制概念，不依賴 Codex crate，也未複製完整 harness。瀏覽器擴充、literal search 與 unique text edit 是針對本專案需要的實作。`main` 連結會持續變動。

## 開場到交付

1. 讀取 session、恢復缺少結果的工具紀錄、更新內建指令，加入使用者目標。先前未回答的問題在續跑時重新呈現。
2. 長任務先簡述；文字與工具同一回覆時，先顯示文字再執行。`report_progress` 也可單獨發送進度並繼續；簡單問答不要求計畫。
3. 複雜任务列三至五步。`update_plan` 保存 `pending / in_progress / completed`；調整步驟文字／順序需解釋，最多一步進行中。
4. 每個工具前保存意圖，執行後保存結果。讀取新結果與插話，再向模型請求下一步。已存在計畫與命令狀態以 runtime context 提供給模型。
5. `report_blocked` 在有互動輸入時提供替代路線並等待選擇，回傳 replan 時繼續原 session；選擇停止或沒有互動輸入才結束為 blocked。完成工具必須獨立呼叫，存在未完成計畫／活動命令時要求模型修正；完成宣告仍需實際驗證證據。普通文字在已知工作尚未結束時不能直接結束回合。
6. 明確記錄最後 verdict 與訊息、保存 session，再由 CLI 輸出結果。`run` 與 `agent` 使用同一核心流程。

## 插話、人工作答與中斷

只有一個 stdin reader。閒置時排隊的輸入是各自的新任務；執行中輸入是補充；問題呈現後新輸入是答案。選項可輸入編號，也可自由回答。`request_user_input`、confirm 與 handoff 必須單獨成批，不會先執行尚未取得答案的後續操作。

插話不取消正在進行的工具；在該工具結果返回後，尚未執行的同批呼叫補上 skipped 結果，再加入新使用者訊息重新判斷。已執行的效果不撤回。

Ctrl-C 或 `/stop` 取消模型／工具／人工等待。命令以 process group 清理；瀏覽器請求被取消時關閉該 helper，下一次可重啟。REPL 保持可輸入，`run` 退出 130。強制中止程序後，checkpoint 中未完成的呼叫標示 unknown；代理必須觀察現況，不可假設失敗等於沒有發生，也不可自動重播。

## 停止與預算

回合模型對齊 Grok Bot：`send_message` 是唯一對使用者的聲音；普通 assistant 文字是內心獨白。有工具就繼續；**沒有 tool call 就結束**（`answer`）。`report_done` 仍可選、仍會停止。問人的工具必須單獨一批。

| verdict | 意義 | `run` 退出碼 |
| --- | --- | --- |
| `answer` | 無工具回應；內容以最後一次 `send_message` 為準 | 0 |
| `waiting` | 等你下一句話，或背景工作完成後喚醒 | 0 |
| `done` | 模型呼叫了可選的 `report_done` | 0 |
| `blocked` | `report_blocked` 或相同工具＋結果重複三次 | 1 |
| `budget_exhausted` | 本回合模型步數上限用完，不能當成完成 | 1 |
| `failed` | API、回覆協定、context 或 runtime 錯誤 | 1 |
| `cancelled` | 使用者停止本回合 | 130 |

預設最多 5000 步；每 12 步顯示本機進度。相同工具與結果第 2 次先提醒，第 3 次 `blocked`。成功的 `write_stdin` / `await_command` / `browser_wait` 重置該判定。`exec_command` 預設等待 30 秒後背景化。空模型回覆最多重試 3 次。做了事卻沒有 `send_message` 會先提醒再結束。

`grokboy web` 在 `:8787`（`GROKBOY_WEB_PORT`）提供 Grok Bot 風格對話網頁與 PWA。手機與電腦同一 Wi-Fi 時，用終端機印出的 LAN URL 開啟，Safari／Chrome「加入主畫面」即可全螢幕當 app。`/novnc` 同源代理 Docker 桌面，所以手機不必直連 6080。

`spawn_subagent` 立刻返回。父回合若在子 agent 或背景命令仍在跑時以無工具結束，runtime 會等它完成、灌入 revival 訊息、再請模型繼續；不要用 `check_subagent` 輪詢完成。子 agent 不能再派子 agent。`GROKBOY_SUBAGENT_MAX_ROUNDS` 預設 128。`kind=computerUse` 把桌面點擊交給子 agent（`computer`：screenshot/click/move/drag/type/key/scroll/wait，xdotool `DISPLAY=:1`）；同一時間只能有一個 computerUse。父層只有唯讀 `screenshot`。人類登入仍走 `request_box_help`。

HTTP 連線期限 15 秒、單次請求 180 秒；helper 回應期限 60 秒；網頁條件等待最多 30 秒；命令預設最多十分鐘，legacy shell 為 30 秒。等待時每 20 秒顯示實際階段與經過時間，不呼叫模型製造更新。

## 保存與工具邊界

Session 使用新增欄位的 serde defaults 相容舊資料。計畫、待回答問題、活動命令與瀏覽器 URL 均進入 checkpoint。單一 session 模式使用自己的 browser profile；named-agent 模式改用任務 owner 的固定 profile 與獨占使用權，正常工具回覆後保存登入狀態；重啟後重新觀察 DOM。操作中途崩潰可能留下未知外部狀態，不能保證逐操作原子性。

大型工具回覆與完整命令 stdout/stderr 放在工作區 `.grokboy-output/`；模型看到片段與讀取路徑。`read_file` 以行分段。Context 裁切只處理請求副本，不刪磁碟對話；保留所有使用者限制和系統指令，超出上限時清楚停止。這不是模型式語意壓縮。

檔案與上下載工具檢查工作區和 symlink；`edit_file` 要求唯一 exact match。Shell 仍有本機使用者權限，沒有 OS sandbox；目前命令 I/O 是 pipe，沒有 PTY。網頁搜尋走既有瀏覽器，不增加服務金鑰。