Oracle (CLI) — 最佳用法
Oracle 將您的提示詞 + 選定檔案打包成一個「一次性」請求,讓另一個模型能以真實的儲存庫背景(API 或瀏覽器自動化)來回答。請將輸出視為建議:務必對照程式碼與測試進行驗證。
主要使用案例(瀏覽器、GPT‑5.5 Pro)
這裡的預設工作流程:--engine browser 搭配 ChatGPT 中的 GPT‑5.5 Pro。這是「人在迴圈中」的路徑:可能需要約 10 分鐘到 1 小時;預期會有一個您可以重新連線的儲存會話。
建議的預設值:
- 引擎:瀏覽器 (
--engine browser) - 模型:GPT‑5.5 Pro(可以是
--model gpt-5.5-pro或 ChatGPT 的選擇器標籤,如--model "5.5 Pro") - 附件:目錄/萬用字元 + 排除規則;避免機密。
黃金路徑(快速 + 可靠)
- 選取一個精簡的檔案集合(包含真相所需的最少檔案)。
- 預覽您即將傳送的內容(需要時使用
--dry-run+--files-report)。 - 以瀏覽器模式執行,進行一般的 GPT‑5.5 Pro ChatGPT 工作流程;只有當您明確想要時才使用 API。
- 如果執行中斷/逾時:重新連線到已儲存的會話(不要重新執行)。
指令(建議使用)
-
顯示幫助(每個會話一次):
npx -y @steipete/oracle --help
-
預覽(不消耗 token):
npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"
-
Token/成本檢查:
npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"
-
啟動/效能追蹤:
npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"- 當 CLI 啟動或首次輸出時間感覺緩慢時使用;檢查
first-output和exit。
-
瀏覽器執行(主要路徑;長時間執行是正常的):
npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"
-
手動貼上備用方案(組合套件,複製到剪貼簿):
npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"- 注意:
--copy是--copy-markdown的隱藏別名。
附加檔案 (--file)
--file 接受檔案、目錄和萬用字元。您可以多次傳遞它;條目可以用逗號分隔。
-
包含:
--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(除非您明確將它們作為文字目錄/檔案傳遞,否則會跳過)。 - 展開萬用字元時會遵守
.gitignore。 - 不跟隨符號連結(萬用字元展開使用
followSymbolicLinks: false)。 - 點檔案會被過濾掉,除非您明確使用包含點區段的模式(例如
--file ".github/**")來選擇加入。 - 預設上限:大於 1 MB 的檔案會被拒絕,除非您在
~/.oracle/config.json中提高ORACLE_MAX_FILE_SIZE_BYTES或maxFileSizeBytes。
- 預設忽略的目錄:
預算 + 可觀測性
- 目標:保持總輸入在約 196k tokens 以下。
- 使用
--files-report(和/或--dry-run json)在花費前找出 token 消耗大戶。 - 使用
--perf-trace/ORACLE_PERF_TRACE=1來進行啟動和首次輸出時間的計時。追蹤會編輯提示詞、tokens、金鑰、cookies 和內嵌 cookie 負載;分離的 API 子程序會寫入一個帶有會話後綴的 sidecar 追蹤檔案。 - 如果您需要隱藏/進階選項:
npx -y @steipete/oracle --help --verbose。
引擎(API vs 瀏覽器)
- 自動選擇:當設定
OPENAI_API_KEY時使用api,否則使用browser。 - 瀏覽器引擎僅支援 GPT + Gemini;請對 Claude/Grok/Codex 或多模型執行使用
--engine api。 - API 執行在開始前需要明確的使用者同意,因為它們會產生使用成本。
- 瀏覽器附件:
--browser-attachments auto|never|always(自動內嵌最多約 60k 字元,然後上傳)。- 新增
--browser-bundle-files --browser-bundle-format zip將許多文字檔案上傳為一個 ZIP,同時保留檔名。
- 遠端瀏覽器主機(已登入的機器執行自動化):
- 主機端:
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/**"
- 主機端:
API 執行前檢查
- API 執行需要明確的使用者同意,並且需要花費金錢。
- 在 API 執行前,檢查提供者狀態,但不顯示機密:
oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-prooracle --preflight --models gpt-5.4,gemini-3-prooracle --route --model gpt-5.4
- 如果使用者想要第一方的 OpenAI,請傳遞
--provider openai或--no-azure。這可以防止匯出的 Azure 環境變數/設定劫持路由:oracle --provider openai --engine api --model gpt-5.5-pro ...
- 對於部分成功仍有用的顧問型多模型面板,請使用
--allow-partial --write-output <path>,這樣成功的模型檔案和<stem>.oracle.json清單就容易復原:oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<task>"
--timeout 10m是正常的使用者端 API 截止時間;Oracle 會推導出 HTTP 傳輸逾時,除非明確設定了--http-timeout。- 如果匯出的
OPENAI_API_KEY無效,且使用者想要他們個人的 OpenAI 金鑰,請在一個持久的 tmux 會話中使用$one-password。已知項目:API Key - OpenAI - Personal,欄位api_key。僅將其注入到單一 Oracle 指令中;絕不列印金鑰:OPENAI_API_KEY="$(op item get 'API Key - OpenAI - Personal' --account my.1password.com --fields label=api_key --reveal)" oracle --provider openai --engine api --model gpt-5.5-pro ...
- 為了偵錯 Oracle 本身,請在拉取
~/Projects/oracle後偏好使用本地端檢出:pnpm -C ~/Projects/oracle run buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
會話 + 別名(別遺失工作)
- 儲存在
~/.oracle/sessions下(使用ORACLE_HOME_DIR覆寫)。 - 瀏覽器執行會將持久的檔案儲存在
~/.oracle/sessions/<id>/artifacts/下,包括transcript.md、Deep Research 報告,以及可用的下載 ChatGPT 生成圖片。 - 執行可能會中斷或花費很長時間(瀏覽器/API + GPT‑5.5 Pro 經常如此)。如果 CLI 逾時:不要重新執行;請重新連線。
- 列出:
oracle status --hours 72 - 連線:
oracle session <id> --render
- 列出:
- 使用
--slug "<3-5 個單詞>"讓會話 ID 更容易閱讀。 - 存在重複提示詞防護;只有當您真的想要一個全新的執行時才使用
--force。 - CLI 護欄:沒有提示詞的根執行會以非零退出;
--dry-run與--render/--render-markdown衝突;Ctrl-C 會以前景 API 執行退出碼 130 退出,同時瀏覽器清理/重新連線仍會執行。
提示詞模板(高信噪比)
Oracle 從零專案知識開始。假設模型無法推斷您的技術棧、建置工具、慣例或「顯而易見」的路徑。請包含:
- 專案簡報(技術棧 + 建置/測試指令 + 平台限制)。
- 「東西放在哪裡」(關鍵目錄、進入點、設定檔、依賴邊界)。
- 確切的問題 + 您嘗試過的方法 + 錯誤文字(逐字)。
- 限制條件(「不要改變 X」、「必須保持公開 API」、「效能預算」等)。
- 期望的輸出(「返回修補計畫 + 測試」、「列出有風險的假設」、「提供 3 個選項及其權衡」)。
「詳盡提示詞」模式(供後續恢復使用)
當您知道這將是一個長時間的調查時,請撰寫一個日後可以獨立存在的提示詞:
- 頂部:6–30 句的專案簡報 + 當前目標。
- 中間:具體的重現步驟 + 確切的錯誤 + 您已經嘗試過的內容。
- 底部:附上所有所需的背景檔案,以便全新的模型能夠完全理解(進入點、設定檔、關鍵模組、文件)。
如果您日後需要重現相同的背景,請使用相同的提示詞 + --file … 集合重新執行(Oracle 執行是一次性的;模型不會記住先前的執行)。
安全性
- 預設不要附加機密(
.env、金鑰檔案、驗證令牌)。積極地編輯;只分享必要的內容。 - 偏好「剛好的背景」:較少的檔案 + 更好的提示詞勝過整個儲存庫的傾印。