Community程式設計與開發github.com

steipete/oracle

Oracle 第二模型審查:打包提示詞與檔案、除錯、重構、設計。

oracle 是什麼?

Oracle 是一款 CLI 工具,能將您的提示詞與選定檔案打包成單一「一次性」請求,讓另一個模型(如 GPT‑5.5 Pro)在擁有完整儲存庫背景的情況下進行分析、除錯、重構或設計。它支援瀏覽器自動化(預設)與 API 兩種引擎,並提供 `--dry-run`、`--files-report` 等預覽功能,協助控制 token 預算(建議低於 196k tokens)。Oracle 會話會儲存在 `~/.oracle/sessions`,支援長時間執行的瀏覽模式與自動重新連線,避免工作遺失。使用時應注意安全性,避免附帶機密檔案,並以「足夠的上下文」為原則,搭配良好的提示詞模板以獲得最佳結果。

相容平台✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/oracle

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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")
  • 附件:目錄/萬用字元 + 排除規則;避免機密。

黃金路徑(快速 + 可靠)

  1. 選取一個精簡的檔案集合(包含真相所需的最少檔案)。
  2. 預覽您即將傳送的內容(需要時使用 --dry-run + --files-report)。
  3. 以瀏覽器模式執行,進行一般的 GPT‑5.5 Pro ChatGPT 工作流程;只有當您明確想要時才使用 API。
  4. 如果執行中斷/逾時:重新連線到已儲存的會話(不要重新執行)。

指令(建議使用)

  • 顯示幫助(每個會話一次):

    • 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-pro
    • oracle --preflight --models gpt-5.4,gemini-3-pro
    • oracle --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 build
    • node ~/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、金鑰檔案、驗證令牌)。積極地編輯;只分享必要的內容。
  • 偏好「剛好的背景」:較少的檔案 + 更好的提示詞勝過整個儲存庫的傾印。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

相關技能