oracle

oracle

Oracle 会将 Prompt 与选定的文件打包成上下文，提交给第二模型（Second-Model）进行单次分析。请将输出结果视为参考建议，务必结合实际代码和测试用例进行验证。

常用路径

目前 CLI 默认模型为 gpt-5.5-pro。浏览器引擎适合处理耗时较长、需要深度推理的 ChatGPT Pro 任务；而在设置了 OPENAI_API_KEY 或 Azure 凭证时，使用 API 引擎更加高效。

推荐默认用法：

• 先做预检：--dry-run summary --files-report
• 浏览器长流程运行：--engine browser --model gpt-5.5-pro
• 明确指定 API：--engine api --model gpt-5.5

黄金路径（最佳实践）

1. 筛选精简的文件集（尽量精简，但包含完整真相）。
2. 提前预览 Payload 及 Token 消耗（--dry-run + --files-report）。
3. 耗时较长的 Pro 推理选择浏览器模式；明确的 API 调用选择 API 模式。
4. 若运行脱机或超时：直接重新连接 (reattach) 到已保存的会话，不要盲目重新运行。

常用命令

• 查看帮助：

  • 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.5-pro -p "<task>" --file "src/**"

• 手动复制备用方案：

  • oracle --render --copy -p "<task>" --file "src/**"
  • 注意：--copy 是 --copy-markdown 的隐藏别名。

附加文件 (--file)

--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 配置。
  • 不跟踪软链接 (symlink)。
  • 默认过滤点开头隐藏文件 (Dotfiles)，除非在模式中显式声明（如 --file ".github/**"）。
  • 拒绝超过 1 MB 的单文件。

引擎选择（API vs 浏览器模式）

• 自动选择机制：设置了 OPENAI_API_KEY 时自动选择 api，否则切换为 browser。
• 浏览器模式仅支持 GPT 与 Gemini 模型；如需使用 Claude/Grok/Codex 或多模型联动，请指定 --engine api。
• 浏览器附件上传策略：
  • --browser-attachments auto|never|always（auto 模式下 ~60k 字符以内以内联形式粘贴，超过则上传为文件）。
• 远程浏览器 Host 设置：
  • 服务端：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 覆盖）。
• 运行可能发生脱机或耗时极长（浏览器模式结合 Pro 模型经常如此）。如果 CLI 超时：请勿重新运行，直接重新连接 (reattach)。
  • 列出会话：oracle status --hours 72
  • 连接会话：oracle session <id> --render
• 使用 --slug "<3-5个词的描述>" 保持会话 ID 的易读性。
• 具备重复 Prompt 防误触保护；只有在确定需要全新运行一次时才使用 --force。

高信息量 Prompt 撰写指南

Oracle 启动时对项目处于零认知状态。切勿假定模型能自动推断出你的技术栈、构建工具、代码规范或“理所应当”的路径。建议包含：

• 项目背景简报（技术栈 + 构建/测试命令 + 平台限制）。
• 文件分布结构（核心目录、入口点、配置文件、模块边界）。
• 具体的待解决问题 + 已尝试的步骤 + 原样报错日志。
• 明确的约束条件（如“不要更改 X 模块”、“必须保持公共 API 兼容”等）。
• 期望的输出形式（如“给出补丁计划与测试用例”、“提供 3 种方案及其优劣势对比”）。

安全防范

• 默认不要包含敏感信息（.env、密钥文件、Auth Token 等）。请做脱敏处理，只提供诊断所必需的内容。

“自包含 Prompt”复原模式

对于深度的排查任务，建议编写一份独立的 Prompt 配合文件集合，以便日后重新触发运行：

• 6–30 句话的项目背景与核心目标描述。
• 复现步骤 + 原样报错信息 + 已尝试的方法。
• 附带全部必要的上下文文件（入口点、配置、核心模块、文档）。

Oracle 的每次运行都是单次独立的 (one-shot)，模型不会记忆过去的历史。所谓“复原上下文”，就是用相同的 Prompt + --file … 参数重新执行一遍（或者重新连接到之前仍在运行的会话）。