oracle

oracle

Oracle 会将提示词和选定文件打包在一起，供第二模型执行一次处理。请将输出视为参考建议；对照代码和测试进行验证。

主路径

当前 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. 预览载荷和词元用量（--dry-run + --files-report）。
3. 长时间的 Pro 推理使用浏览器模式；显式 API 调用使用 API 模式。
4. 如果运行分离或超时：请重新连接到已存储的会话。不要盲目重新运行。

命令（首选）

• 帮助：

  • 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/**"

• 词元用量检查：

  • 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 接受文件、目录和通配模式。可多次传入；各条目可用逗号分隔。

• 包含：

  • --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（除非明确以字面目录或文件形式传入，否则会跳过）。
  • 展开通配模式时遵循 .gitignore。
  • 不跟随符号链接。
  • 除非通过模式显式选择包含（例如 --file ".github/**"），否则会过滤以点开头的文件。
  • 拒绝大于 1 MB 的文件。

引擎（API 与浏览器）

• 自动选择：设置 OPENAI_API_KEY 时使用 api；否则使用 browser。
• 浏览器仅支持 GPT 和 Gemini；处理 Claude/Grok/Codex 或多模型运行时，请使用 --engine api。
• 浏览器附件：
  • --browser-attachments auto|never|always（自动模式会先以内联方式粘贴最多约 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 覆盖）。
• 运行可能会分离或耗时较长（浏览器 + Pro 运行时通常如此）。如果 CLI 超时：不要重新运行；请重新连接。
  • 列出：oracle status --hours 72
  • 附加：oracle session <id> --render
• 使用 --slug "<3-5 words>" 让会话 ID 更易读。
• 存在重复提示词防护；仅当确实需要全新运行时才使用 --force。

提示词模板（高信噪比）

Oracle 起初对项目的了解为零。假设模型无法推断你的技术栈、构建工具、规范或“显而易见”的路径。请包括：

• 项目简介（技术栈、构建和测试命令、平台限制）。
• “各部分所在位置”（关键目录、入口点、配置文件、边界）。
• 准确的问题、你尝试过的方法以及错误文本（原文）。
• 约束条件（“不要修改 X”、“必须保持公共 API”等）。
• 期望输出（“返回补丁方案和测试”、“给出 3 个选项及其权衡取舍”）。

附件

除非用户要求包含，否则不要将 .env、密钥文件和认证令牌放入附件中。

“详尽提示词”恢复模式

对于长期调查，请编写一个独立提示词和文件集，以便数天后重新运行：

• 用 6-30 句话概述项目并说明目标。
• 复现步骤、确切错误以及你已经尝试过的方法。
• 附加所需的所有上下文文件（入口点、配置、关键模块、文档）。

Oracle 运行是一次性的；模型不会记住之前的运行。“恢复上下文”是指使用相同的提示词和 --file … 文件集重新运行（或重新附加仍在运行的已存储会话）。