Oracle 是做什麼的？
Oracle 將提示與一組選定檔案打包，進行一次第二模型傳遞。請將輸出視為建議，並務必透過程式碼與測試進行驗證。
主要路徑
目前 CLI 預設模型：gpt-5.5-pro。瀏覽器引擎適用於長時間的 ChatGPT Pro 執行；API 引擎則適合已準備好 OPENAI_API_KEY 或 Azure 配置的情境。
建議的預設值：
- 先預覽：
--dry-run summary --files-report - 瀏覽器長時間執行：
--engine browser --model gpt-5.5-pro - API 明確指定：
--engine api --model gpt-5.5
黃金路徑
- 挑選精簡的檔案集合（最少但包含所有必要資訊的檔案）。
- 預覽酬載與令牌花費（使用
--dry-run+--files-report）。 - 長時間 Pro 思考使用瀏覽器模式；明確的 API 呼叫使用 API 模式。
- 若執行中斷或超時：重新連接到已儲存的會話，不要盲目重新執行。
指令（建議使用）
-
說明：
oracle --help- 若二進位檔案未安裝：
npx -y @steipete/oracle --help（避免使用pnpx；牽涉 sqlite 繫結）。
-
預覽（不消耗令牌）：
oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"oracle --dry-run full -p "<task>" --file "src/**"
-
令牌合理性檢查：
oracle --dry-run summary --files-report -p "<task>" --file "src/**"
-
瀏覽器執行（主要路徑；長時間執行為正常現象）：
oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"
-
手動貼上備用方案：
oracle --render --copy -p "<task>" --file "src/**"- 注意：
--copy是--copy-markdown的隱藏別名。
附加檔案（--file）
--file 接受檔案、目錄與 glob 模式。可以多次傳遞；項目可以用逗號分隔。
-
包含：
--file "src/**"--file src/index.ts--file docs --file README.md
-
排除：
--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
-
預設行為：
- 預設忽略的目錄：
node_modules、dist、coverage、.git、.turbo、.next、build、tmp（除非明確指定為文字路徑／檔案，否則會跳過）。 - 展開 glob 時會遵循
.gitignore。 - 不跟隨符號連結。
- 除非透過模式選擇（例如
--file ".github/**"），否則會過濾掉點檔案。 - 拒絕大於 1 MB 的檔案。
- 預設忽略的目錄：
引擎（API vs 瀏覽器）
- 自動選擇：當設定了
OPENAI_API_KEY時使用api，否則使用browser。 - 瀏覽器僅支援 GPT + Gemini；若要使用 Claude/Grok/Codex 或多模型執行，請使用
--engine api。 - 瀏覽器附加檔案：
--browser-attachments auto|never|always（auto會內嵌貼上最多約 60k 字元，其餘則上傳）。
- 遠端瀏覽器主機：
- 主機端：
oracle serve --host 0.0.0.0 --port 9473 --token <secret> - 客戶端：
oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"
- 主機端：
會話與識別碼
- 儲存在
~/.oracle/sessions下（可透過ORACLE_HOME_DIR覆蓋）。 - 執行可能會中斷或花費很長時間（瀏覽器 + Pro 模式經常如此）。若 CLI 超時：不要重新執行，請重新連接。
- 列出：
oracle status --hours 72 - 連接：
oracle session <id> --render
- 列出：
- 使用
--slug "<3-5 個單字>"讓會話 ID 更容易閱讀。 - 存在重複提示保護機制；只有當你確實需要全新執行時，才使用
--force。
提示範本（高信號）
Oracle 初始時對專案毫無知識。請假設模型無法推斷你的技術棧、建置工具、慣例或「顯而易見」的路徑。請包含：
- 專案簡報（技術棧 + 建置／測試指令 + 平台限制）。
- 「東西在哪裡」（關鍵目錄、進入點、配置檔、邊界）。
- 確切的問題 + 你嘗試過的方法 + 錯誤文字（原文）。
- 限制條件（「不要改變 X」、「必須保持公開 API」等）。
- 期望的輸出（「回傳修補計畫 + 測試」、「給出 3 個選項及其取捨」）。
附加檔案注意事項
- 除非使用者要求，否則請將
.env、金鑰檔案和驗證令牌排除在附加檔案之外。
「詳盡提示」恢復模式
對於長時間的調查，請撰寫一個獨立的提示與檔案集，以便幾天後可以重新執行：
- 6-30 句的專案簡報 + 目標。
- 重現步驟 + 確切錯誤 + 你嘗試過的方法。
- 附加所有所需的上下文檔案（進入點、配置、關鍵模組、文件）。
Oracle 執行是一次性的；模型不會記住先前的執行。「恢復上下文」意味著使用相同的提示與 --file … 集合重新執行（或重新連接到仍在執行的已儲存會話）。