Oracle (CLI) — 最佳用法

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

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

此处的默认工作流：--engine browser在 ChatGPT 中使用 GPT‑5.2 Pro。这是“人在回路”的路径：可能需要大约 10 分钟到 1 小时；预期会有一个可以重新连接的已存储会话。

推荐的默认设置：

• 引擎：browser (--engine browser)
• 模型：GPT‑5.2 Pro（可以是--model gpt-5.2-pro或 ChatGPT 选择器标签，例如--model "5.2 Pro")
• 附件：目录/通配符 + 排除项；避免包含机密信息。

黄金路径（快速且可靠）

1. 选择一个紧凑的文件集合（包含所需真相的最少文件）。
2. 预览您即将发送的内容（--dry-run+--files-report在需要时）。
3. 以浏览器模式运行，采用常规的 GPT‑5.2 Pro ChatGPT 工作流；仅在明确需要时使用 API。
4. 如果运行分离/超时：重新附加到已存储的会话（不要重新运行）。

命令（首选）

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

  • npx -y @steipete/oracle --help

• 预览（不计令牌）：

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

• 令牌/成本检查：

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

• 浏览器运行（主要路径；长时间运行是正常的）：

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

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

  • npx -y @steipete/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规则。
  • 不追踪符号链接（通配符扩展使用followSymbolicLinks: false）。
  • 点文件会被过滤，除非你明确通过包含点段的模式选择加入（例如--file ".github/**"）。
  • 硬性限制：大于 1 MB 的文件会被拒绝（请拆分文件或缩小匹配范围）。

预算 + 可观测性

• 目标：保持总输入在约 196k 个令牌以内。
• 使用--files-report（和/或--dry-run json）在消耗令牌前识别占用大户。
• 如果你需要隐藏/高级选项：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 模式下，内联粘贴约 6 万字符以内的内容，超出则上传）。
• 远程浏览器主机（已登录的机器运行自动化）：
  • 主机：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/**"

会话 + 标识符（避免丢失工作）

• 存储于~/.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”、“性能预算”等）。
• 期望的输出（“返回补丁计划 + 测试”、“列出有风险的假设”、“给出三个选项及其权衡”）。

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

当你知道这将是一项长期调查时，写一个稍后可以独立使用的提示：

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

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

安全

• 默认情况下不要附加机密信息（.env、密钥文件、认证令牌）。积极进行脱敏处理；只分享必需的内容。
• 倾向于“恰到好处的上下文”：更少的文件 + 更好的提示胜过整个仓库的转储。