version: "1.0.0" name: oracle description: "Oracle second-model review: bundle prompts/files, debug, refactor, design."

Oracle (CLI) — best use

0919v1 可移植打包版：源自本机 0910v1，移除个人路径和固定模型偏好；不覆盖本机现用 Skill。

Oracle bundles a prompt and selected files into a one-shot request so another model can answer with real repository context through the API or browser. A prompt is required; attach files only when they add necessary context. Treat responses as advisory and verify them against the codebase and tests.

Local compatibility and defaults

This portable package does not contain credentials or saved model preferences. Check the installed CLI version and Node engine requirements before use. Oracle 0.21.1 was verified for this package and requires Node >=24; do not assume that the recipient's default Node or CLI is compatible.

Prefer an existing compatible Oracle installation. Do not install a second copy or change global Node links automatically. Respect the current user's engine, model and saved preference. If none exists, ask before a quota-consuming call; never invent a model or silently change browser mode to a paid API.

Check oracle --version, oracle --help --verbose and the installed package's Node requirement after an upgrade. Parameter resolution is not proof that a request was submitted or that the requested model ran. Keep submission evidence.

User governance

• Escalate automatically only when multiple agents have a substantive disagreement that local evidence or a minimal test cannot resolve.
• Run --dry-run summary --files-report first. Before the model call, make the engine, model, subscription/quota or API cost, and attachment scope clear. Reuse existing authorization covering those details; ask only when authorization is missing or the scope changes.
• Oracle is advisory; source files, logs, tests, and the user's final decision remain authoritative.

Golden path

1. Pick the smallest file set that still contains the truth.
2. Preview the bundle with --dry-run and --files-report.
3. Use browser mode and the user's selected model; use API only when explicitly requested.
4. If a run detaches or times out, reattach to the stored session instead of

starting a duplicate.

Commands

• Show help:
• oracle --help

• Preview without calling a model:
• oracle --engine browser --retain-hours 0 --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
• oracle --engine browser --retain-hours 0 --dry-run full -p "<task>" --file "src/**"

• Inspect token usage:
• oracle --engine browser --retain-hours 0 --dry-run summary --files-report -p "<task>" --file "src/**"

• Browser run:
• oracle --engine browser -p "<task>" --file "src/**"

• Manual paste fallback:
• oracle --render-markdown --copy-markdown -p "<task>" --file "src/**"
• --render is an alias for --render-markdown.

• Performance trace:
• oracle --engine browser --retain-hours 0 --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"

Attaching files

--file accepts files, directories, and globs. Pass it multiple times or use comma-separated entries.

• Include: --file "src/**", --file src/index.ts, --file docs --file README.md
• Exclude: prefix a pattern with !, for example --file "!src/**/*.test.ts"
• Default ignored directories: node_modules, dist, coverage, .git,

.turbo, .next, build, and tmp

• Globs honor .gitignore and do not follow symlinks.
• Dotfiles require an explicit dot-segment in the pattern, such as

--file ".github/**".

• Files over 1 MB are rejected by default; configure

ORACLE_MAX_FILE_SIZE_BYTES or maxFileSizeBytes when necessary.

Keep total input under roughly 196k tokens. Use --files-report or --dry-run json to identify oversized inputs. Never attach .env files, private keys, auth tokens, or other secrets unless they have been redacted and are essential to the question.

Engines and browser controls

• Auto-selection uses API when OPENAI_API_KEY is set and browser otherwise.
• Browser supports GPT models through ChatGPT and Gemini models through Gemini

web. API-only models include gpt-5.1-codex.

• Model families and aliases depend on the installed version, engine and provider; inspect them only when needed for the requested model.
• API runs require explicit authorization covering their usage cost.
• Browser runs use the signed-in account and its subscription/message quota; apply the authorization rule above without asking twice for the same call.
• Browser attachments use --browser-attachments auto|never|always.
• For many files, add --browser-bundle-files --browser-bundle-format auto|zip.
• Reuse an existing Chrome session with --browser-tab <ref>,

--browser-attach-running, or --remote-chrome <host:port>.

• Use --browser-model-strategy select|current|ignore to control picker

behavior.

• Use --browser-follow-up "<prompt>" for another turn in the same browser

conversation, or --followup <sessionId|responseId> for a stored run.

• Use --browser-research deep only when Deep Research is explicitly wanted.

API preflight (only when requested)

Before an API run, check provider readiness without printing secrets:

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

Use --provider openai or --no-azure when first-party OpenAI routing is required. For multi-model panels where partial success is useful, use --allow-partial --write-output <path> so successful outputs and the manifest can be recovered.

Set an explicit deadline for automation, for example --timeout 10m; Oracle derives the HTTP timeout unless --http-timeout is supplied.

Sessions and recovery

• Sessions are stored under ~/.oracle/sessions; override with

ORACLE_HOME_DIR.

• Browser artifacts include transcript.md and, when available, research

reports and generated images.

• List recent sessions with oracle status --hours 72.
• Attach with oracle session <id> --render.
• Use --slug "<3-5 words>" for readable session IDs.
• If a run times out, reattach; do not re-run it. Use --force only when a

genuinely new identical run is intended.

• Successful non-project browser one-shots are archived automatically by

default; override with --browser-archive never|always.

Prompt template

Oracle starts with zero project knowledge. Include:

• Project briefing: stack, services, build/test commands, and platform constraints
• Where things live: entrypoints, configs, key modules, and dependency boundaries
• Exact question, prior attempts, and verbatim error text
• Constraints such as API compatibility, performance budgets, and files not to change
• Desired output such as a patch plan, tests, risk list, or tradeoff comparison

For a long investigation, make the prompt restorable: put a 6–30 sentence briefing at the top, concrete reproduction and errors in the middle, and attach all context files required by a fresh model at the bottom. Oracle runs are one-shot; the model does not remember prior runs.