Oracle 是一个命令行工具(CLI),用于把提示词与选定的文件打包成一次性的“one-shot”请求,让另一个模型在具备真实仓库上下文的情况下作答(可通过 API 或浏览器自动化)。其输出应视为建议性内容,需结合代码与测试进行验证。
用途
Oracle 的核心用途是把提示词与选定的文件打包成一次请求,使另一个模型能够基于真实的仓库上下文作答。主要使用场景为浏览器模式配合 GPT-5.2 Pro(在 ChatGPT 中),这是常见的“长时间思考”路径,运行约 10 分钟到 1 小时属正常,并会保存可重新接入的会话。
主要能力
- 文件打包:--file 接受文件、目录和 glob,可多次传入,条目也可用逗号分隔。
- 包含与排除:支持包含模式(如 --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 等目录(除非显式作为字面目录/文件传入);展开 glob 时遵循 .gitignore;不跟随符号链接;除非通过模式显式启用(如 --file ".github/**"),否则过滤点文件;大于 1 MB 的文件会被拒绝。
- 预览与 token 检查:--dry-run summary / --dry-run full 可在不消耗 token 的情况下预览载荷;--files-report 用于检查 token 消耗。
- 引擎选择:当设置了 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 <secret>;客户端 oracle --engine browser --remote-host host:port --remote-token <secret> -p "<task>" --file "src/**"。
- 会话与 slug:会话存储在 ~/.oracle/sessions(可用 ORACLE_HOME_DIR 覆盖)。运行可能分离或耗时很长(浏览器 + GPT-5.2 Pro 常见)。若 CLI 超时,不要重跑,应重新接入。列出:oracle status --hours 72;接入:oracle session <id> --render;使用 --slug "<3-5 words>" 保持会话 ID 可读。存在重复提示词防护;仅在确实需要全新运行时使用 --force。
使用方式
推荐默认值:引擎 browser(--engine browser),模型 GPT-5.2 Pro(--model gpt-5.2-pro 或 --model "5.2 Pro")。
黄金路径:
- 选择紧凑的文件集(包含真相的最少文件)。
- 预览载荷与 token 消耗(--dry-run + --files-report)。
- 常规 GPT-5.2 Pro 工作流使用浏览器模式;仅在明确需要时使用 API。
- 若运行分离/超时:重新接入已存储的会话(不要重跑)。
常用命令:
- 帮助:oracle --help;若二进制未安装:npx -y @steipete/oracle --help(此处避免使用 pnpx;涉及 sqlite 绑定)。
- 预览(不消耗 token):oracle --dry-run summary -p "<task>" --file "src/" --file "!/.test.";oracle --dry-run full -p "<task>" --file "src/**"。
- Token 检查:oracle --dry-run summary --files-report -p "<task>" --file "src/**"。
- 浏览器运行(主路径;长时间运行属正常):oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"。
- 手动粘贴回退:oracle --render --copy -p "<task>" --file "src/**"(注意:--copy 是 --copy-markdown 的隐藏别名)。
提示词模板(高信号)
Oracle 初始对项目零知识。假设模型无法推断你的技术栈、构建工具、约定或“显而易见”的路径。应包含:
- 项目简报(技术栈 + 构建/测试命令 + 平台约束)。
- “东西在哪里”(关键目录、入口点、配置文件、边界)。
- 确切问题 + 你尝试过的内容 + 错误文本(逐字)。
- 约束(“不要改 X”、“必须保留公共 API”等)。
- 期望输出(“返回补丁计划 + 测试”、“给出 3 个带权衡的选项”)。
适用场景
适用于需要让另一个模型基于真实仓库上下文进行长时间思考、代码审查或问题诊断的场景,尤其是使用浏览器模式配合 GPT-5.2 Pro 的常规工作流。也适用于需要远程浏览器主机、会话重新接入或手动粘贴回退的情况。
限制
- 浏览器模式仅支持 GPT 与 Gemini;Claude/Grok/Codex 或多模型运行需使用 API 引擎。
- 文件大于 1 MB 会被拒绝;不跟随符号链接;默认过滤点文件;默认忽略若干目录。
- Oracle 运行为一次性;模型不会记住之前的运行。“恢复上下文”意味着用相同的提示词 + --file 集合重新运行(或重新接入仍在运行的已存储会话)。
- 安全:默认不要附加机密(.env、密钥文件、认证令牌)。应积极脱敏;只分享必需内容。
- 输出为建议性,需结合代码与测试验证。
“详尽提示词”恢复模式
对于长时间调查,编写独立的提示词 + 文件集,以便数天后重跑:6–30 句项目简报 + 目标;复现步骤 + 确切错误 + 你尝试过的内容;附加所有需要的上下文文件(入口点、配置、关键模块、文档)。