5.3 KiB
通用 CLI 流程
本文描述原本的單 session 模式。多主 agent、背景任務、獨立聊天與常駐服務見 TEAM。
Codex 參考
2026-09-13 查阅使用者指定的 codex-rs：
- session/turn.rs：依後續工具工作與待處理輸入繼續回合，分開對待 commentary 與最後訊息，等待工具結果。
- plan_spec.rs：
update_plan的步驟與狀態，最多一步in_progress。 - request_user_input.rs：透過 session 請求使用者資訊並將答案交回工具流程。
- unified_exec.rs：命令執行與後續 stdin／增量輸出分開處理。
本專案採用這些控制概念，不依賴 Codex crate，也未複製完整 harness。瀏覽器擴充、literal search 與 unique text edit 是針對本專案需要的實作。main 連結會持續變動。
開場到交付
- 讀取 session、恢復缺少結果的工具紀錄、更新內建指令，加入使用者目標。先前未回答的問題在續跑時重新呈現。
- 長任務先簡述；文字與工具同一回覆時，先顯示文字再執行。
report_progress也可單獨發送進度並繼續；簡單問答不要求計畫。 - 複雜任务列三至五步。
update_plan保存pending / in_progress / completed；調整步驟文字／順序需解釋，最多一步進行中。 - 每個工具前保存意圖，執行後保存結果。讀取新結果與插話，再向模型請求下一步。已存在計畫與命令狀態以 runtime context 提供給模型。
report_blocked在有互動輸入時提供替代路線並等待選擇，回傳 replan 時繼續原 session；選擇停止或沒有互動輸入才結束為 blocked。完成工具必須獨立呼叫，存在未完成計畫／活動命令時要求模型修正；完成宣告仍需實際驗證證據。普通文字在已知工作尚未結束時不能直接結束回合。- 明確記錄最後 verdict 與訊息、保存 session，再由 CLI 輸出結果。
run與agent使用同一核心流程。
插話、人工作答與中斷
只有一個 stdin reader。閒置時排隊的輸入是各自的新任務；執行中輸入是補充；問題呈現後新輸入是答案。選項可輸入編號，也可自由回答。request_user_input、confirm 與 handoff 必須單獨成批，不會先執行尚未取得答案的後續操作。
插話不取消正在進行的工具；在該工具結果返回後，尚未執行的同批呼叫補上 skipped 結果，再加入新使用者訊息重新判斷。已執行的效果不撤回。
Ctrl-C 或 /stop 取消模型／工具／人工等待。命令以 process group 清理；瀏覽器請求被取消時關閉該 helper，下一次可重啟。REPL 保持可輸入，run 退出 130。強制中止程序後，checkpoint 中未完成的呼叫標示 unknown；代理必須觀察現況，不可假設失敗等於沒有發生，也不可自動重播。
停止與預算
| verdict | 意義 | run 退出碼 |
|---|---|---|
answer |
已給最後文字，可能是回答而非工作完成證明 | 0 |
done |
模型宣告已完成、沒有已知未完成計畫／活動命令 | 0 |
blocked |
回報阻礙或觸發無進展保護 | 1 |
budget_exhausted |
本回合模型請求上限用完，不能當成完成 | 1 |
failed |
API、回覆協定、context 或 runtime 錯誤 | 1 |
cancelled |
使用者停止本回合 | 130 |
預設最多 48 次模型請求，包含進度／計畫工具請求；每 12 輪顯示本機進度。只報進度或改計畫達三輪也會停止，避免「一直說會做卻沒做」。有新資料的輪詢可繼續；成功的 write_stdin、browser_wait 不受相同輸出三次的判定，但仍有期限與總請求上限。
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。網頁搜尋走既有瀏覽器，不增加服務金鑰。