Oracle 把提示词与选定文件打包成一次性请求，交给另一个模型基于真实仓库上下文作答，输出仅供参考，需用代码与测试验证。
主要用途：默认工作流是 --engine browser 配合 ChatGPT 中的 GPT-5.2 Pro，属于“长时间思考”路径，约 10 分钟到 1 小时属正常，会保存可重连的会话。
推荐默认：引擎 browser（--engine browser），模型 GPT-5.2 Pro（--model gpt-5.2-pro 或 --model "5.2 Pro"）。
基本流程：挑选最小但包含真相的文件集；用 --dry-run 与 --files-report 预览载荷与 token 消耗；常规用浏览器模式，仅在明确需要时用 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/"。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。浏览器仅支持 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 覆盖）。列出：oracle status --hours 72；附加：oracle session <id> --render；用 --slug "<3-5 words>" 保持会话 ID 可读。存在重复提示词防护，仅在确实想全新运行时用 --force。
提示词模板：Oracle 初始无项目知识，需包含项目简介（技术栈、构建/测试命令、平台约束）、“东西在哪”（关键目录、入口、配置文件、边界）、确切问题与已尝试内容及原始错误文本、约束（如“不要改 X”“必须保留公共 API”）、期望输出（如“返回补丁计划 + 测试”“给出 3 个带权衡的选项”）。
安全：默认不要附加机密（.env、密钥文件、认证令牌），积极脱敏，只分享必要内容。
“详尽提示词”恢复模式：为长期调查编写独立提示词与文件集，便于数天后重跑：6–30 句项目简介加目标；复现步骤、确切错误与已尝试内容；附加所有需要的上下文文件（入口、配置、关键模块、文档）。Oracle 运行是一次性的，模型不记得先前运行；“恢复上下文”意味着用相同提示词与 --file 集重跑，或重连仍在运行的已存会话。