oracle

Oracle (CLI) — 最佳使用方式

Oracle 会将提示词和选定文件打包成一次性请求，让另一个模型通过 API 或浏览器结合真实的代码库上下文作答。提示词为必填项；仅在文件能提供必要上下文时才附加。请将回复视为参考，并根据代码库和测试进行核实。

主要使用场景（浏览器，GPT-5.6）

如果 ChatGPT 账户提供 GPT-5.6，请使用浏览器模式。GPT-5.6 Sol 和 GPT-5.6 Sol Pro 是不同的目标：基础版 Sol 使用 Extra High 推理强度设置，而 Pro 是单独的选择器目标，适用于困难或耗时较长的任务。

推荐默认设置：

• 引擎：浏览器（--engine browser）
• 基础版 Sol：--model gpt-5.6-sol
• 基础版 Sol 的最高推理强度：--browser-thinking-time extra-high（Extra High）
• 在 GPT-5.6 Sol 上显式启用 Pro 推理强度：--browser-thinking-time pro（如果无法确认 Pro，则安全失败）
• 浏览器 GPT-5.5 搭配 Pro 推理强度：--model gpt-5.5 --browser-thinking-time pro
• API Pro 最高推理强度：--model gpt-5.6-sol --reasoning-mode pro --reasoning-effort max
• 回退方案：GPT-5.6 不可用时，显式使用 --model gpt-5.5-pro
• 附件：目录/通配模式，并设置排除项；默认绝不附加机密信息

GPT-5.6 是否可用取决于账户。请确认选择器中是否有基础版 Sol，并保留模型选择证据。选择器中单独出现 Pro 标签只能证明选择器已选中该目标，本身并不能证明服务器端使用了 Pro 生成。

GPT-5.6 模型选择

此版本在两个界面上都支持 GPT-5.6，但 Pro 的选择方式有所不同：

• gpt-5.6：遵循 GPT-5.6 系列的默认设置
• gpt-5.6-sol：固定使用 ChatGPT 的 GPT-5.6 Sol 条目
• 浏览器：gpt-5-pro 会选择 ChatGPT 的 Pro 目标
• API：--reasoning-mode pro 会在 gpt-5.6-sol 上启用 Pro 执行；搭配 --reasoning-effort max 可获得最高推理强度

使用基础版 Sol 时，请使用：

oracle --engine browser --browser-manual-login --model gpt-5.6-sol \
  --browser-thinking-time extra-high \
  -p "<task>" --file "src/**"

通过 Responses API 使用 GPT-5.6 Sol Pro 时，请使用：

oracle --engine api --model gpt-5.6-sol \
  --reasoning-mode pro \
  --reasoning-effort max \
  -p "<task>" --file "src/**"

不要使用 --model "GPT-5.6 Sol Pro"。Pro 被有意设置为浏览器选择器目标和 API 推理模式。浏览器标签验证会拒绝 gpt-5.6-luna 等未知的未来变体，而不会静默回退到 Sol；API 运行则会原样保留此类提供方模型 ID。

浏览器模式会将这些别名映射到 ChatGPT 的 Sol 选择器。API 和多模型运行会保留相应的 OpenAI 官方模型 ID；带提供方前缀的 ID 和无关的自定义 ID 则会原样传递。

GPT-5.6 的浏览器支持依赖统一的 Intelligence 选择器。它可以识别当前的英文和中文推理强度标签，避免将 高 匹配到 极高 中，并会在 React 替换组合框中的提示条后重新查询，以确保选择验证不会依赖已脱离文档的旧节点。

与 npm 0.15.2 的兼容性

不要将 gpt-5.6 或 gpt-5.6-sol 传给未经修补的 npm 0.15.2 安装版本。该版本可能会将这些标签规范化为 gpt-5.2。请使用显式回退方案：

npx -y @steipete/[email protected] --engine browser --model gpt-5.5-pro \
  -p "<task>" --file "src/**"

升级到包含 GPT-5.6 模型选择和统一选择器更新的版本后，在移除回退说明之前，请确认以下所有事项：--help --verbose 会显示新增选项；浏览器试运行会将两个别名解析为 GPT-5.6 Sol；API 路由会选择 OpenAI 官方模型；并且实时浏览器运行会记录严格的 GPT-5.6 选择证据。

标准流程

1. 选择能够完整呈现真实情况的最小文件集。
2. 使用 --dry-run 和 --files-report 预览打包内容。
3. GPT-5.6 使用浏览器模式；仅在明确需要时使用 API。
4. 如果运行中断连接或超时，请重新连接到已存储的会话，而不要重复启动。

命令

• 显示帮助：

  • npx -y @steipete/oracle --help --verbose

• 预览，不调用模型：

  • npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
  • npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"

• 检查令牌用量：

  • npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"

• 浏览器运行：

  • oracle --engine browser --browser-manual-login --model gpt-5.6-sol --browser-thinking-time extra-high -p "<task>" --file "src/**"

• 手动粘贴备用方案：

  • npx -y @steipete/oracle --render-markdown --copy-markdown -p "<task>" --file "src/**"
  • --render 是 --render-markdown 的别名。

• 性能跟踪：

  • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"

附加文件

--file 接受文件、目录和 glob。可多次传入，也可使用逗号分隔的条目。

• 包含：--file "src/**"、--file src/index.ts、--file docs --file README.md
• 排除：在模式前加 !，例如 --file "!src/**/*.test.ts"
• 默认忽略的目录：node_modules、dist、coverage、.git、 .turbo、.next、build 和 tmp
• Glob 遵循 .gitignore，且不会跟随符号链接。
• 点文件需要在模式中显式指定点号路径段，例如 --file ".github/**"。
• 默认不接受超过 1 MB 的文件；必要时配置 ORACLE_MAX_FILE_SIZE_BYTES 或 maxFileSizeBytes。

总输入量应控制在约 196k 个令牌以内。使用 --files-report 或 --dry-run json 找出过大的输入。除非已脱敏且对问题至关重要，否则切勿附加 .env 文件、 私钥、身份验证令牌或其他机密信息。

引擎和浏览器控制

• 如果设置了 OPENAI_API_KEY，自动选择会使用 API；否则使用浏览器。
• 浏览器支持通过 ChatGPT 使用 GPT 模型，通过 Gemini 网页版使用 Gemini 模型。仅限 API 的模型包括 gpt-5.1-codex。
• 当前模型系列包括 GPT-5.5/5.4/5.2/5.1、Gemini 3.x 和 Claude 4.x；是否可用取决于引擎和提供方。
• API 运行需要获得用户明确同意，因为可能产生使用费用。
• 浏览器附件可使用 --browser-attachments auto|never|always。
• 浏览器上传时，单个文本/源文件会以原生文件形式保留，多个 文本/源文件则会打包。仅上传文本文件时，auto 会保留扁平文本；如需文件系统树，请使用 --browser-bundle-format zip，或使用 --browser-bundle-files 强制将所有解析后的附件打包到一个文件中。
• 使用 --browser-tab <ref>、--browser-attach-running 或 --remote-chrome <host:port> 复用现有 Chrome 会话。
• 添加 --browser-no-focus（配置项 browser.noFocus），让 Chrome 在启动、打开新标签页和发送内容时保持在后台。如果 可以模拟焦点，普通运行不会抢占键盘焦点或切换 macOS Spaces；如果无法启用此功能，Oracle 会尝试在点击前将 Chrome 切换到前台。重新附加时如果退回到重启 Chrome，仍可能激活它。
• 使用 --browser-model-strategy select|current|ignore 控制选择器 的行为。
• 使用 --browser-follow-up "<prompt>" 在同一浏览器 会话中继续一轮，或使用 --followup <sessionId|responseId> 继续已存储的运行。
• 仅在明确需要深度研究时，才使用 --browser-research deep。

API 预检

运行 API 前，检查提供方是否就绪，但不要输出机密信息：

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

需要使用 OpenAI 第一方路由时，请使用 --provider openai 或 --no-azure。对于部分成功也有用的多模型面板，请使用 --allow-partial --write-output <path>，以便恢复成功的输出和清单。

为自动化设置明确的截止时间，例如 --timeout 10m；除非提供了 --http-timeout，否则 Oracle 会据此推导 HTTP 超时。

会话与恢复

• 会话存储在 ~/.oracle/sessions 下；可通过 ORACLE_HOME_DIR 覆盖。
• 浏览器产物包括 transcript.md，以及（如果有）研究报告和生成的图像。
• 使用 oracle status --hours 72 列出近期会话。
• 使用 oracle session <id> --render 接续会话。
• 使用 --slug "<3-5 words>" 创建易读的会话 ID。
• 如果运行超时，请接续会话；不要重新运行。只有确实要启动一个新的相同运行时，才使用 --force。
• 默认情况下，成功的非项目浏览器单次运行会自动归档；可通过 --browser-archive never|always 覆盖。

提示词模板

Oracle 启动时对项目一无所知。请包含：

• 项目简介：技术栈、服务、构建／测试命令和平台限制
• 文件位置：入口点、配置、关键模块和依赖边界
• 具体问题、之前的尝试以及逐字错误文本
• API 兼容性、性能预算和不得修改的文件等约束
• 期望的输出，例如补丁计划、测试、风险清单或权衡比较

对于长时间调查，请确保提示词可供恢复：在顶部放置 6–30 句的简介，在中间给出具体复现步骤和错误，并在底部附上新模型所需的所有上下文文件。Oracle 每次运行都是单次的；模型不会记住之前的运行。