oracle

• 您想要向大型 AI 模型（GPT‑5.2 Pro、Gemini、Claude 等）詢問有關程式碼庫的深度問題，並需要模型看到相關的原始檔案，而不只是片段。
• 您需要執行「長時間思考」任務——這類任務需要 10 分鐘到一小時——並希望儲存工作階段，以便在 CLI 逾時時可以重新連接。
• 您需要精確控制哪些檔案會被打包（透過 glob、排除規則以及 .gitignore 感知），以確保 token 花費可預測。
• 您希望在將任何內容傳送至模型之前，使用 --dry-run 預覽完整的酬載內容與 token 費用。

• 您需要跨越多次來回交流的即時多輪對話情境 — oracle 每次執行皆為一次性；若未重新附加已儲存的工作階段，先前的執行結果將不會被記憶。
• 您想透過瀏覽器引擎使用 GPT 或 Gemini 以外的模型 — 那些模型需要使用 --engine api（Claude、Grok、Codex 等）。
• 您的情境檔案各自超過 1 MB — oracle 會拒絕超過該限制的檔案。

oracle 將您的提示與任意數量的檔案、目錄或 glob 模式合併成單一請求內容。多次傳遞 --file 參數，混合使用包含規則與以 ! 為前綴的排除規則，oracle 會自動智慧略過 node_modules、dist、.git 及其他雜訊目錄。

--engine browser 模式可直接在瀏覽器工作階段中驅動 ChatGPT 或 Gemini，非常適合僅能透過網頁介面存取的模型。它會根據內容大小自動決定要以內嵌方式貼上內容，還是上傳附件（內嵌上限約 60,000 個字元，超過則改為上傳檔案）。

所有執行紀錄都儲存在 ~/.oracle/sessions 目錄下。如果瀏覽器長時間執行後中斷連線或逾時，可使用 oracle status --hours 72 列出最近的會話，並使用 oracle session <id> --render 重新連接——無需重新執行或再次消耗 token。

執行 --dry-run summary 或 --dry-run full，並搭配 --files-report 選項，即可在實際送出請求之前，精確檢視將傳送的內容並預估 token 費用。這能有效避免在大型程式碼庫中發生意外的用量超支。

當 OPENAI_API_KEY 已設定（或明確指定 --engine api）時，oracle 會透過 API 進行路由，而非使用瀏覽器。這將解鎖瀏覽器引擎不支援的 Claude、Grok、Codex 及多模型工作流程。

在遠端機器上使用 oracle serve --host 0.0.0.0 --port 9473 --token <secret> 啟動瀏覽器自動化主機，然後將任意 oracle 用戶端連線至該主機。適合將長時間運行的瀏覽器工作階段卸載至伺服器執行。

一位開發者將相關的 src/** 檔案與詳細的提示詞打包在一起，提示詞中描述了錯誤、錯誤訊息及相關限制條件，然後執行 oracle --engine browser --model gpt-5.2-pro。模型接收完整的上下文後，回傳一份修補方案。若工作階段在 20 分鐘後中斷，開發者會選擇重新連接，而非重新執行指令。

在投入昂貴的執行之前，開發者先執行 oracle --dry-run summary --files-report -p "<task>" --file "src/**"，以查看哪些檔案會被納入、將消耗多少 token，然後在正式執行前縮減檔案集合。

當瀏覽器引擎不適用時，開發者可使用 oracle --render --copy -p "<task>" --file "src/**" 將完整打包的提示詞渲染並複製到剪貼簿，然後手動貼上至任何聊天介面。

在複雜的多日除錯工作中，開發者會撰寫一個獨立的提示檔案，內含 6 至 30 句的專案說明、重現步驟以及確切的錯誤訊息，並附上所有相關的設定檔與進入點檔案。此提示具有完整的自我描述性，因此數日後仍可使用相同的 oracle 指令重新執行，並保有完全一致的上下文。