oracle

• 您想向大型 AI 模型（GPT‑5.2 Pro、Gemini、Claude 等）提问有关代码库的深层问题，并需要让模型看到相关源文件，而不仅仅是一段代码片段。
• 您需要执行"长时间思考"任务——耗时 10 分钟到 1 小时不等——并希望保存会话，以便在 CLI 超时后可以重新连接。
• 您需要精确控制哪些文件被打包（通过 glob 模式、排除规则以及 .gitignore 感知），以保持 token 消耗的可预测性。
• 您希望在向模型发送任何内容之前，使用 --dry-run 预览完整的请求内容和 token 费用。

• 您需要跨多次来回交流的实时多轮对话上下文——oracle 的每次运行都是一次性的；如果不重新附加已存储的会话，之前的运行内容将不会被记住。
• 您希望通过浏览器引擎使用 GPT 或 Gemini 以外的模型——这些模型需要使用 --engine api（如 Claude、Grok、Codex 等）。
• 您的上下文文件每个超过 1 MB——oracle 会拒绝超过该限制的文件。

oracle 将您的提示与任意数量的文件、目录或通配符合并为单个请求载荷。多次传递 --file 参数，混合使用包含规则和以 ! 为前缀的排除规则，oracle 会自动智能跳过 node_modules、dist、.git 及其他无关目录。

--engine browser 模式可直接在浏览器会话中驱动 ChatGPT 或 Gemini，非常适合仅能通过 Web 界面访问的模型。它会根据内容大小自动决定是内联粘贴还是上传附件（内联最多约 60,000 个字符，超出则切换为文件上传）。

所有运行记录都存储在 ~/.oracle/sessions 目录下。如果一个长时间的浏览器运行意外断开或超时，可以使用 oracle status --hours 72 列出最近的会话，并使用 oracle session <id> --render 重新附加——无需重新运行或再次消耗 token。

运行 --dry-run summary 或 --dry-run full，并结合 --files-report 选项，可在发出任何真实请求之前，精确查看将要发送的内容并估算令牌成本。这有助于防止在大型代码库中出现意外的用量超支。

当 OPENAI_API_KEY 已设置（或明确指定 --engine api）时，oracle 将通过 API 进行路由，而非使用浏览器。这将解锁 Claude、Grok、Codex 以及浏览器引擎不支持的多模型工作流。

在远程机器上通过 oracle serve --host 0.0.0.0 --port 9473 --token <secret> 启动浏览器自动化主机，然后将任意 oracle 客户端连接到该主机。适用于将长时间运行的浏览器会话卸载到服务器上。

一位开发者将相关的 src/** 文件与详细的提示词打包在一起，提示词中描述了 Bug、错误信息及相关约束条件，然后运行 oracle --engine browser --model gpt-5.2-pro。模型接收完整上下文后返回一份补丁方案。如果会话在 20 分钟后断开，开发者会重新连接，而不是重新运行命令。

在提交一次高成本运行之前，开发者先执行 oracle --dry-run summary --files-report -p "<task>" --file "src/**" 来查看哪些文件会被纳入以及它们将消耗多少令牌，然后在正式运行前对文件集进行裁剪。

当浏览器引擎不适用时，开发者使用 oracle --render --copy -p "<task>" --file "src/**" 将完整的打包提示词渲染到剪贴板，然后手动将其粘贴到任意聊天界面中。

在一项复杂的、跨越数天的调试工作中，开发者编写一个独立的提示文件，其中包含6至30句话的项目背景说明、复现步骤以及具体的错误信息，并附上所有相关的配置文件和入口文件。该提示文件完全自包含，因此相同的 oracle 命令可在数天后以完全相同的上下文重新运行。