用途：Oracle 把提示词与选定文件打包成“一次性”请求，让另一个模型在真实仓库上下文下作答（API 或浏览器自动化）。输出仅为建议，需对照代码与测试核验。
主要能力与默认用法：常用路径是 --engine browser 搭配 GPT-5.2 Pro（ChatGPT），属“长思考”流程，约 10 分钟至 1 小时属正常，会保存可重新接入的会话。推荐默认：引擎 browser，模型 gpt-5.2-pro（或 "5.2 Pro"）。
基本流程：挑选最小但含关键事实的文件集；用 --dry-run 与 --files-report 预览载荷与 token 消耗；日常用 browser 模式，仅在明确需要时用 API；若运行分离或超时，应重新接入已保存会话而非重跑。
常用命令：oracle --help；未安装时用 npx -y @steipete/oracle --help（避免 pnpx）。预览：oracle --dry-run summary -p "<task>" --file "src/" --file "!/.test."；oracle --dry-run full -p "<task>" --file "src/"；token 检查：oracle --dry-run summary --files-report -p "<task>" --file "src/"。浏览器运行：oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/"。手动粘贴回退：oracle --render --copy -p "<task>" --file "src/"（--copy 是 --copy-markdown 的隐藏别名）。
文件附加：--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 的文件被拒绝。
引擎：设置 OPENAI_API_KEY 时自动选 api，否则选 browser。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/**"。
会话与 slug：存放于 ~/.oracle/sessions（可用 ORACLE_HOME_DIR 覆盖）。运行可能分离或耗时很长（browser 加 GPT-5.2 Pro 常见），CLI 超时时不要重跑，应重新接入。列出：oracle status --hours 72；接入：oracle session <id> --render；用 --slug "<3-5 words>" 让会话 ID 更可读。存在重复提示词防护，仅在确实需要新运行时用 --force。
提示词模板：Oracle 起初对项目零了解，需包含项目简报（技术栈、构建/测试命令、平台约束）、“关键内容位置”（关键目录、入口、配置文件、边界）、确切问题与已尝试内容及错误原文、约束（如“不要改动 X”“必须保留公开 API”）、期望输出（如“返回补丁计划加测试”“给出 3 个带权衡的方案”）。
安全：默认不要附加机密（.env、密钥文件、认证令牌），积极脱敏，只共享必要内容。
“详尽提示词”复原模式：为长期排查，编写独立的提示词与文件集以便数日后重跑：6–30 句项目简报加目标；复现步骤、确切错误、已尝试内容；附加所需全部上下文文件（入口、配置、关键模块、文档）。Oracle 运行是一次性的，模型不记得先前运行，“恢复上下文”指用相同提示词与 --file 集重跑，或重新接入仍在运行的已保存会话。