oracle

Oracle（CLI）——最佳实践

Oracle 会将你的提示词与所选文件打包成一个“一次性”请求，让另一个模型能够基于真实的代码仓库上下文作答（可通过 API 或浏览器自动化）。请将输出视为参考建议：务必对照代码库和测试进行验证。

主要用例（浏览器、GPT‑5.5 Pro）

这里的默认工作流是：在 ChatGPT 中使用 GPT‑5.5 Pro，并设置 --engine browser。这是“人在环路中”的使用方式：可能需要约 10 分钟到 1 小时；请做好之后重新连接已存储会话的准备。

推荐默认设置：

• 引擎：浏览器（--engine browser）
• 模型：GPT‑5.5 Pro（使用 --model gpt-5.5-pro，或 ChatGPT 选择器中的标签，例如 --model "5.5 Pro"）
• 附件：目录/Glob 模式，并设置排除项；避免包含机密信息。

黄金路径（快速且可靠）

1. 选择精简的文件集（在仍能提供准确信息的前提下，尽量减少文件数量）。
2. 预览即将发送的内容（必要时使用 --dry-run 和 --files-report）。
3. 对于常规的 GPT‑5.5 Pro ChatGPT 工作流，请使用浏览器模式；只有在明确需要时才使用 API。
4. 如果运行中断或超时，请重新连接已存储的会话（不要重新运行）。

命令（推荐）

• 显示帮助（每个会话一次）：

  • npx -y @steipete/oracle --help

• 预览（不消耗 Token）：

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

• 检查 Token/成本：

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

• 启动/性能跟踪：

  • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"
  • 如果 CLI 启动或首次输出耗时较长，请使用此命令；检查 first-output 和 exit。

• 浏览器运行（主要路径；长时间运行属正常情况）：

  • npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"

• 手动粘贴备用方案（组装内容包并复制到剪贴板）：

  • npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"
  • 注意：--copy 是隐藏别名，等同于 --copy-markdown。

附加文件（--file）

--file 支持文件、目录和 Glob 模式。可以多次传入；各条目也可以用逗号分隔。

• 包含：

  • --file "src/**"（目录 Glob 模式）
  • --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。
  • 不跟随符号链接（Glob 展开使用 followSymbolicLinks: false）。
  • 默认过滤点文件，除非使用包含点路径段的模式明确选择它们（例如 --file ".github/**"）。
  • 默认上限：大于 1 MB 的文件会被拒绝，除非提高 ~/.oracle/config.json 中的 ORACLE_MAX_FILE_SIZE_BYTES 或 maxFileSizeBytes。

预算与可观测性

• 目标：将总输入量控制在约 196k Token 以内。
• 使用 --files-report（和/或 --dry-run json）在花费前找出 Token 占用较高的文件。
• 使用 --perf-trace / ORACLE_PERF_TRACE=1 测量启动和首次输出耗时。跟踪记录会隐去提示词、Token、密钥、Cookie 和内联 Cookie 负载；已分离的 API 子进程会写入带会话后缀的旁路跟踪文件。
• 如果需要使用隐藏的高级选项：npx -y @steipete/oracle --help --verbose。

引擎（API 与浏览器）

• 自动选择：如果设置了 OPENAI_API_KEY，则使用 api；否则使用 browser。
• 浏览器引擎仅支持 GPT 和 Gemini；若要使用 Claude/Grok/Codex 或运行多模型任务，请使用 --engine api。
• API 运行前必须征得用户明确同意，因为这会产生使用费用。
• 浏览器附件：
  • --browser-attachments auto|never|always（auto 会先以内联方式粘贴最多约 60k 个字符，然后上传）。
  • 添加 --browser-bundle-files --browser-bundle-format zip，即可将多个文本文件打包为一个 ZIP 上传，同时保留文件名。
• 远程浏览器主机（在已登录的机器上运行自动化）：
  • 主机：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/**"

API 预检

• 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。这样可防止导出的 Azure 环境变量/配置劫持路由：
  • oracle --provider openai --engine api --model gpt-5.5-pro ...
• 对于允许部分成功、且部分结果也有用的咨询型多模型评审，请使用 --allow-partial --write-output <path>，以便轻松找回成功生成的模型文件和 <stem>.oracle.json 清单：
  • oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<task>"
• --timeout 10m 是面向用户的常规 API 截止时间；除非明确设置 --http-timeout，否则 Oracle 会据此推导 HTTP 传输超时时间。
• 如果导出的 OPENAI_API_KEY 无效，而用户希望使用自己的 OpenAI 密钥，请在一个持久运行的 tmux 会话中使用 $one-password。已知条目：API Key - OpenAI - Personal，字段 api_key。仅将密钥注入单条 Oracle 命令；绝不要打印密钥：
  • OPENAI_API_KEY="$(op item get 'API Key - OpenAI - Personal' --account my.1password.com --fields label=api_key --reveal)" oracle --provider openai --engine api --model gpt-5.5-pro ...
• 如需调试 Oracle 本身，优先使用拉取到本地的代码库 ~/Projects/oracle：
  • pnpm -C ~/Projects/oracle run build
  • node ~/Projects/oracle/dist/scripts/run-cli.js ...

会话与 slug（避免丢失工作）

• 存储在 ~/.oracle/sessions 下（可通过 ORACLE_HOME_DIR 覆盖）。
• 浏览器运行会在 ~/.oracle/sessions/<id>/artifacts/ 下保存持久文件，包括 transcript.md、Deep Research 报告，以及可用时下载的 ChatGPT 生成图片。
• 运行可能会分离或耗时较长（浏览器/API + GPT‑5.5 Pro 通常如此）。如果 CLI 超时，请勿重新运行；应重新连接。
  • 列出：oracle status --hours 72
  • 重新连接：oracle session <id> --render
• 使用 --slug "<3-5 words>"，让会话 ID 更易读。
• 系统设有重复提示词保护；只有确实要重新运行时才使用 --force。
• CLI 防护措施：以 root 身份运行且未提供提示词时会以非零状态码退出；--dry-run 与 --render / --render-markdown 冲突；在前台运行的 API 任务按 Ctrl-C 会以代码 130 退出，而浏览器清理/重新连接仍会继续。

提示词模板（高信号）

Oracle 启动时对项目的了解为零。请假设模型无法推断你的技术栈、构建工具、约定或“显而易见”的路径。请包含：

• 项目简介（技术栈 + 构建/测试命令 + 平台限制）。
• “文件所在位置”（关键目录、入口点、配置文件、依赖边界）。
• 确切问题 + 你尝试过的操作 + 错误文本（原文）。
• 限制条件（“不要更改 X”“必须保留公共 API”“性能预算”等）。
• 期望的输出（“返回补丁计划 + 测试”“列出风险较高的假设”“给出 3 个并说明权衡的选项”）。

“详尽提示词”模式（用于后续恢复）

如果你知道这将是一项耗时较长的调查，请编写一份日后可独立使用的提示词：

• 顶部：6–30 句的项目简介 + 当前目标。
• 中间：具体的复现步骤 + 完整错误信息 + 你已经尝试过的内容。
• 底部：附上新模型充分理解所需的所有上下文文件（入口点、配置、关键模块、文档）。

如果需要稍后复现相同的上下文，请使用相同的提示词和 --file … 集合重新运行（Oracle 运行是一次性的；模型不会记住之前的运行）。

安全

• 默认不要附上机密（.env、密钥文件、身份验证令牌）。请严格删去敏感信息，只分享必要内容。
• 优先提供“恰到好处的上下文”：更少的文件 + 更好的提示词，胜过导出整个代码库。