oracle — 最佳用法

Oracle 将您的提示词 + 选定的文件打包成一个“一次性”请求，以便另一个模型能在真实的仓库上下文中进行回答（通过 API 或浏览器自动化）。请将输出视为建议性内容：务必对照代码和测试进行验证。

主要使用场景（浏览器，GPT‑5.2 Pro）

此处的默认工作流程是：使用 --engine browser 和在 ChatGPT 中的 GPT‑5.2 Pro。这是常见的“长时间思考”路径：等待 10 分钟到 1 小时是正常的；预计会有一个您可以重新连接的已存储会话。

推荐的默认设置：

• 引擎：浏览器 (--engine browser)
• 模型：GPT‑5.2 Pro (--model gpt-5.2-pro 或 --model "5.2 Pro")

黄金路径

1. 选择一个精简的文件集（包含真相所需的最少文件）。
2. 预览负载和令牌消耗 (--dry-run + --files-report)。
3. 对于常规的 GPT‑5.2 Pro 工作流，使用浏览器模式；仅在明确需要时才使用 API。
4. 如果运行中断/超时：重新连接到已存储的会话（不要重新运行）。

命令（推荐）

• 帮助：
  • oracle --help
  • 如果二进制文件未安装：npx -y @steipete/oracle --help（此处避免使用 pnpx；涉及 sqlite 绑定）。
• 预览（不消耗令牌）：
  • oracle --dry-run summary -p "<任务>" --file "src/**" --file "!**/*.test.*"
  • oracle --dry-run full -p "<任务>" --file "src/**"
• 令牌合理性检查：
  • oracle --dry-run summary --files-report -p "<任务>" --file "src/**"
• 浏览器运行（主要路径；长时间运行是正常的）：
  • oracle --engine browser --model gpt-5.2-pro -p "<任务>" --file "src/**"
• 手动粘贴备选方案：
  • oracle --render --copy -p "<任务>" --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（auto 模式会将最多约 60k 字符内联粘贴，超出部分上传）。
• 远程浏览器主机：
  • 服务端：oracle serve --host 0.0.0.0 --port 9473 --token <密钥>
  • 客户端：oracle --engine browser --remote-host <主机:端口> --remote-token <密钥> -p "<任务>" --file "src/**"

会话与标识符

• 会话存储在 ~/.oracle/sessions 下（可通过 ORACLE_HOME_DIR 覆盖）。
• 运行可能会断开或耗时较长（浏览器 + GPT‑5.2 Pro 经常如此）。如果 CLI 超时：不要重新运行；请重新连接。
  • 列出会话：oracle status --hours 72
  • 重新连接：oracle session <ID> --render
• 使用 --slug "<3-5个词>" 来让会话 ID 更具可读性。
• 存在重复提示防护；仅在确实需要全新运行时使用 --force。

提示词模板（高信息量）

Oracle 启动时完全没有项目相关知识。请假设模型无法推断您的技术栈、构建工具、约定或“显而易见”的路径。请包含：

• 项目简介（技术栈 + 构建/测试命令 + 平台约束）。
• “代码位置说明”（关键目录、入口点、配置文件、边界）。
• 明确的问题 + 您尝试过的内容 + 错误文本（逐字提供）。
• 约束条件（“不要修改 X”、“必须保持公共 API”等）。
• 期望的输出格式（“返回补丁方案 + 测试”、“给出 3 个选项及其权衡”）。

安全

• 默认不要附加敏感信息（.env、密钥文件、认证令牌）。务必进行修订；只分享必需的部分。

“详尽提示词”恢复模式

对于长时间的调查，编写一个独立的提示词 + 文件集，以便几天后可以重新运行：

• 6–30 句的项目简介 + 目标。
• 复现步骤 + 确切的错误信息 + 您尝试过的内容。
• 附加所有必要的上下文文件（入口点、配置、关键模块、文档）。

Oracle 运行是一次性的；模型不记得之前的运行。“恢复上下文”意味着使用相同的提示词 + --file … 集重新运行（或重新连接仍在运行的存储会话）。