Oracle（CLI）——最佳实践

Oracle 将你的提示词（prompt）与所选文件打包为一个“单次请求”（one-shot request），供另一个模型在真实代码仓库上下文中作答（通过 API 或浏览器自动化）。请将输出视为**参考建议**：务必结合代码库和测试用例进行人工验证。

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

此处默认工作流为：--engine browser 搭配 ChatGPT 中的 GPT‑5.2 Pro。这是“人在环路中”（human in the loop）路径：单次运行耗时约为 10 分钟至 1 小时；运行过程会自动保存会话，你可随时重新接入。

推荐默认配置：

• 引擎（Engine）：浏览器（--engine browser）
• 模型（Model）：GPT‑5.2 Pro（可指定 --model gpt-5.2-pro，或使用 ChatGPT 界面中的选择器标签如 --model "5.2 Pro"）
• 附件（Attachments）：目录/通配符路径 + 排除规则；严禁包含敏感信息。

黄金路径（快速且可靠）

1. 精选最小必要文件集（仅包含问题真相所需的最少文件）。
2. 预览即将发送的内容（按需使用 --dry-run 和 --files-report）。
3. 优先采用浏览器模式运行，复用常规的 GPT‑5.2 Pro ChatGPT 工作流；仅在明确需要时才切换至 API 模式。
4. 若运行过程中断开连接或超时：请重新接入已保存的会话（切勿重复执行）。

常用命令（推荐）

• 查看帮助（每会话只需一次）：

  • npx -y @steipete/oracle --help

• 预览（不消耗 token）：

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

• 评估 token / 成本合理性：

  • 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 支持传入单个文件、目录或 glob 表达式。可多次使用该参数；多个值可用逗号分隔。

• 包含（Include）：

  • --file "src/**"（目录级 glob）
  • --file src/index.ts（精确文件路径）
  • --file docs --file README.md（精确目录 + 精确文件）

• 排除（Exclude，以 ! 开头）：

  • --file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

• 默认行为（实现层关键逻辑）：

  • 默认忽略的目录： node_modules、dist、coverage、.git、.turbo、.next、build、tmp（除非你显式将其作为字面量目录/文件传入，否则均被跳过）。
  • 展开 glob 时尊重 .gitignore 规则。
  • 不解析符号链接（glob 展开使用 followSymbolicLinks: false）。
  • 点文件（dotfiles）默认被过滤；如需包含，请显式使用含点段的匹配模式（例如 --file ".github/**"）。
  • 硬性限制：单文件体积 > 1 MB 将被拒绝（请拆分文件或缩小匹配范围）。

预算与可观测性

• 目标：总输入控制在约 196k token 以内。
• 使用 --files-report（或 --dry-run json）提前识别 token 占用大户，避免无效消耗。
• 如需隐藏/高级配置项，请运行：npx -y @steipete/oracle --help --verbose。

引擎选择（API vs 浏览器）

• 自动选择：当环境变量 OPENAI_API_KEY 已设置时使用 api 引擎，否则默认为 browser。
• 浏览器引擎仅支持 GPT 与 Gemini；如需调用 Claude/Grok/Codex 或执行多模型协同任务，请显式指定 --engine api。
• 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/**"

会话管理与 slug（防止工作丢失）

• 会话数据默认存储于 ~/.oracle/sessions（可通过 ORACLE_HOME_DIR 环境变量覆盖）。
• 运行可能中断或耗时较长（浏览器 + GPT‑5.2 Pro 场景尤为常见）。若 CLI 因超时退出：请勿重跑；应重新接入已有会话。
  • 列出近期会话：oracle status --hours 72
  • 重新接入指定会话：oracle session --render
• 使用 --slug "<3–5 words>" 为会话 ID 赋予可读性。
• 系统内置重复提示词防护机制；仅当你确实需要全新执行时，才使用 --force。

提示词模板（高信噪比）

Oracle 启动时对项目**零知识**。请勿假设模型能推断出你的技术栈、构建工具链、工程规范或所谓“显而易见”的路径。务必在 prompt 中明确包含以下要素：

• 项目概要（技术栈 + 构建/测试命令 + 平台约束）。
• “关键路径说明”（核心目录结构、入口文件、配置文件位置、依赖边界）。
• 具体问题描述 + 已尝试的操作 + 错误原文（逐字粘贴）。
• 约束条件（例如：“禁止修改 X”、“必须保持公共 API 兼容性”、“性能预算上限”等）。
• 期望输出格式（例如：“返回补丁方案与对应测试”、“列出所有高风险假设”、“提供 3 种可行方案及各自权衡”）。

“完备型提示词”模式（便于后续复现）

当你预判这将是一次长期调试/调查任务时，请撰写一份可独立复用的 prompt：

• 开头：6–30 句项目概要 + 当前目标。
• 中段：可复现的具体步骤 + 精确错误信息 + 已做排查动作。
• 末尾：附上**全部必要上下文文件**（入口文件、配置、核心模块、文档等），确保新模型无需历史记忆即可完整理解。

如需未来复现相同上下文，请使用完全一致的 prompt + 相同的 --file … 参数集重跑（Oracle 所有运行均为单次无状态请求，模型不会记住过往交互）。

安全须知

• 默认禁止附加任何密钥类文件（如 .env、私钥文件、认证 token）。请严格脱敏，仅共享解决问题所必需的最小信息集。
• 坚持“恰如其分的上下文”原则：更少的文件 + 更精准的 prompt，远优于全仓库 dump。