SuperAPI AI 工具集

oracle

编程与开发

查看项目

更新于 10-16 07:11

技能介绍

Oracle(CLI)是一个命令行工具,用于将提示词与选定文件打包成一次性的请求,交给另一个模型进行审查,以获得带有真实仓库上下文的回答。其输出应视为建议性内容,需要结合代码库和测试进行验证。

主要用途

Oracle 的核心用途是二次模型审查,适用于调试、重构、设计检查等场景。默认工作流是使用浏览器引擎配合 ChatGPT 中的 GPT-5.2 Pro,属于“人在回路”的路径,运行时间可能从约 10 分钟到 1 小时不等,并会存储会话以便重新连接。

推荐默认设置

引擎:浏览器(--engine browser) 模型:GPT-5.2 Pro(--model gpt-5.2-pro 或 ChatGPT 选择器标签如 --model "5.2 Pro") 附件:目录/glob 模式加排除项;避免包含机密信息。

快速可靠的使用路径

  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 "<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 --engine browser --model gpt-5.2-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;不跟随符号链接;点文件会被过滤,除非显式使用包含点段的模式(如 --file ".github/**");硬性上限:大于 1 MB 的文件会被拒绝。

预算与可观测性

目标是将总输入保持在约 196k token 以下。使用 --files-report 和/或 --dry-run json 在消耗前发现 token 占用大的文件。如需隐藏或高级选项,可使用 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 字符,然后上传)。 远程浏览器主机(已登录机器运行自动化):主机端 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。

提示词模板(高信号)

Oracle 开始时对项目零知识。假设模型无法推断你的技术栈、构建工具、约定或“显而易见”的路径。应包含:项目简报(技术栈、构建/测试命令、平台约束);“东西在哪里”(关键目录、入口点、配置文件、依赖边界);确切问题、已尝试内容和错误文本(逐字);约束条件(“不要改 X”、“必须保持公共 API”、“性能预算”等);期望输出(“返回补丁计划加测试”、“列出风险假设”、“给出 3 个带权衡的选项”)。

“详尽提示词”模式(用于后续恢复)

当你知道这将是一次长时间调查时,编写一个可以独立存在的提示词:顶部为 6-30 句的项目简报加当前目标;中间为具体复现步骤、确切错误和已尝试内容;底部附加所有上下文文件,以便新模型能完全理解(入口点、配置、关键模块、文档)。如果需要稍后重现相同上下文,使用相同提示词和 --file 集合重新运行(Oracle 运行是一次性的,模型不会记住之前的运行)。

安全

默认不要附加机密信息(.env、密钥文件、认证令牌)。积极脱敏,只分享必要内容。优先“刚好足够的上下文”:更少的文件加更好的提示词胜过整个仓库的转储。