Oracle 的用途是把提示词与选定文件打包成一次性的 one-shot 请求，让另一个模型带着真实仓库上下文回答。输出仅作参考，需结合代码与测试验证。
主要用法与能力：
- 默认工作流为浏览器模式搭配 GPT-5.2 Pro（ChatGPT），属于“长时间思考”路径，耗时约 10 分钟到 1 小时属正常，建议保留会话以便重新接管。
- 推荐默认：引擎 browser（--engine browser），模型 GPT-5.2 Pro（--model gpt-5.2-pro 或 --model "5.2 Pro"）。
- 先挑选最小必要文件集，再预览载荷与 token 消耗（--dry-run + --files-report），浏览器模式为主，API 仅在明确需要时使用。
- 若运行分离或超时，应重新接管已存储会话，而非重跑。
常用命令：
- 查看帮助：oracle --help；未安装时可运行 npx -y @steipete/oracle --help（此处避免 pnpx，因 sqlite 绑定问题）。
- 预览（不消耗 token）：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，可多次传入，也可逗号分隔。默认忽略 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 覆盖）。运行可能分离或耗时很长，若 CLI 超时不要重跑，应重新接管。列表：oracle status --hours 72；接管：oracle session <id> --render；可用 --slug "<3-5 words>" 让会话 ID 更易读。存在重复提示词防护，只有确实想全新运行时才用 --force。
提示词模板：Oracle 初始无项目知识，要假设模型无法推断技术栈、构建工具、约定或“显而易见”的路径。应包含项目简介（技术栈+构建/测试命令+平台约束）、“东西在哪”（关键目录、入口、配置文件、边界）、确切问题+已尝试内容+错误原文、约束（“不要改 X”“必须保留公共 API”）、期望输出（“返回补丁计划+测试”“给出 3 个方案与取舍”）。
安全：默认不要附加机密（.env、密钥文件、认证令牌），应尽量脱敏，只共享必要内容。
“详尽提示词”恢复模式：对长时间调查，可写独立提示词+文件集以便数日后重跑，包括 6–30 句项目简介+目标、复现步骤+确切错误+已尝试内容、所有必要上下文文件。Oracle 运行是一次性的，模型不记得此前运行；“恢复上下文”意味着用相同提示词与 --file 集合重跑，或重新接管仍在运行的已存储会话。