SuperAPI AI 工具集

oracle

编程与开发

查看项目

更新于 10-16 06:56

技能介绍

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")。

黄金路径:

  1. 选择紧凑的文件集(包含真相的最少文件)。
  2. 预览载荷与 token 消耗(--dry-run + --files-report)。
  3. 常规 GPT-5.2 Pro 工作流使用浏览器模式;仅在明确需要时使用 API。
  4. 若运行分离/超时:重新接入已存储的会话(不要重跑)。

常用命令:

  • 帮助: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 句项目简报 + 目标;复现步骤 + 确切错误 + 你尝试过的内容;附加所有需要的上下文文件(入口点、配置、关键模块、文档)。