技能使用指南

oracle（OracleCLI使用技能Skill）Skill 是什么？怎么用？

OracleCLI使用技能Skill（oracle）能把提示与选定代码文件打包成一次性请求，交给外部模型在真实仓库上下文中长思考作答。支持 dry-run 令牌预览、浏览器与 API 双引擎、会话重新附加与远程主机，帮你省去手工复制粘贴的重复劳动。本文详解安装验证、黄金路径、文件排除规则与竞品对比，附高频 FAQ，助你快速上手。

OracleCLI使用技能Skilloracle
8 个章节 约 16 分钟阅读 AI 智能生成

OracleCLI使用技能Skill：把提示与代码文件打包成一次性请求，让另一个模型在真实仓库里给出深度建议

  • 它解决的是"上下文搬运"问题：OracleCLI使用技能Skill（英文名 oracle）把一条提示加上你挑选的代码文件，捆绑成一个"一次性"请求，交给另一个模型在真实仓库上下文中回答，免去手工复制粘贴几十个文件的痛苦。
  • 默认主力路径是浏览器模式 + GPT‑5.2 Pro：属于"长思考"路线，一次运行通常需要约 10 分钟到 1 小时，超时断开是正常现象，正确做法是"重新附加会话"而不是重跑。
  • 有明确的"黄金路径"：先挑最小文件集 → 用 --dry-run 和 --files-report 预览负载与令牌花费 → 再正式运行。
  • 会话可恢复、可追溯：所有会话存储在本地目录，用 oracle status 和 oracle session 就能找回仍在运行的会话。
  • 输出是建议而非结论：官方明确提示要把结果对照代码与测试进行验证。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 OracleCLI使用技能Skill
技能英文名 oracle
技能ID 13573
官方主页 https://askoracle.dev
运行依赖 需要系统内存在 oracle 可执行文件

它解决什么问题

日常开发中最常见的一个卡点是：当你遇到一个跨文件、跨模块的疑难问题时，网页版 AI 对话窗口拿不到你的仓库全貌，只能靠你一段一段贴代码，既费时间又容易丢关键上下文。OracleCLI使用技能Skill 的思路是把"提示 + 选定文件"捆绑成一个一次性请求，让另一个模型在真实仓库上下文中作答——你可以把它理解为"给外部模型做一次带完整上下文的会诊"。

它同时提供两种通道：API 模式与浏览器自动化模式。浏览器模式主要用于 ChatGPT 中的长思考工作流；API 模式则用于 Claude、Grok、Codex 或多模型对比等场景。

一键安装的思路与步骤

  1. 确认前提：该技能依赖 Node 环境运行，安装完成后系统需要有 oracle 命令可用。
  2. 执行安装：技能详情中给出的安装方式是 Node 类型的包安装，包名为 @steipete/oracle，安装后提供的可执行文件为 oracle，界面标签为"安装oracle（node）"。具体安装入口以你所使用的 AI 技能客户端或官方说明为准。
  3. 不安装也能临时用：详情明确给出免安装路径 npx -y @steipete/oracle --help。同时特别提醒避免使用 pnpx，原因是 sqlite 绑定相关问题。
  4. 验证是否生效：运行 oracle --help，如果能正常输出帮助信息，说明二进制文件已就绪；如果提示找不到命令，就用上面的 npx -y 方式回退。

一句话总结安装价值：一次装好，之后所有"需要外部模型看整个仓库"的任务，都变成一条命令行的事。

2. 该技能的主要功能和特点

  • 提示 + 文件捆绑：--file 参数支持文件、目录和通配符，可多次传递，条目之间还能用逗号分隔，一条命令就能把关键上下文打包干净。
  • 智能排除机制：默认忽略 node_modules、dist、coverage、.git、.turbo、.next、build、tmp 等目录；扩展通配符时遵循 .gitignore；不跟随符号链接；点文件默认被过滤（需要显式加入，如 --file ".github/**"）；超过 1 MB 的文件会被拒绝。这些默认值让"打包"不会意外膨胀成几万令牌。
  • 运行前预览，不花令牌：--dry-run summary 和 --dry-run full 可以在不消耗令牌的情况下查看将要发送的负载；配合 --files-report 还能看文件级别的体积与令牌合理性。
  • 双引擎设计：设置了 OPENAI_API_KEY 时自动选择 api，否则走 browser。浏览器模式仅支持 GPT 与 Gemini，Claude／Grok／Codex 或多模型运行必须显式使用 --engine api。
  • 浏览器附件策略可控：--browser-attachments auto|never|always 控制附件如何进入浏览器，自动模式会先内联粘贴约 6 万字符，超出后再改为上传。
  • 远程浏览器主机：服务端 oracle serve --host 0.0.0.0 --port 9473 --token <secret>，客户端用 --remote-host 与 --remote-token 连接，适合把长跑任务放到一台常开的机器上。
  • 会话存储与重新附加：会话落在 ~/.oracle/sessions（可用 ORACLE_HOME_DIR 覆盖），支持列出、附加、重新渲染；--slug 能让会话 ID 更可读，--force 用于在你确实想要新运行时绕过重复提示保护。
  • 手动粘贴回退：oracle --render --copy 把打包结果渲染成 Markdown 并复制到剪贴板（--copy 是 --copy-markdown 的隐藏别名），适合完全不想走自动化通道的场景。
  • 安全默认值：官方建议默认不要附加 .env、密钥文件、认证令牌等秘密内容，需要积极编辑后只分享必要部分。

和"手动复制粘贴到网页对话框"相比，它强在可复现、可预览、可排除、可恢复：同一组文件与提示可以几天后原样重跑，令牌成本在发送前就能看清。

3. 如何使用该技能？

官方给出的"黄金路径"共四步，这里展开成可操作的流程。

第 1 步：挑选紧凑的文件集

原则是"包含真相的最少文件"。不要整仓打包，而是把入口点、配置文件、出错模块、相关文档挑出来。

oracle --dry-run summary -p "<任务>" --file "src/**" --file "!**/*.test.*"

第 2 步：预览负载与令牌花费

oracle --dry-run summary --files-report -p "<任务>" --file "src/**"

如果只是想看完整渲染结果而不发请求，用 oracle --dry-run full -p "<任务>" --file "src/**"。

第 3 步：正式运行

浏览器模式（主要路径，做好长跑准备）：

oracle --engine browser --model gpt-5.2-pro -p "<任务>" --file "src/**"

也可以写成 --model "5.2 Pro"。只有在明确需要时才改用 API 模式。

第 4 步：断了就重新附加，不要重跑

oracle status --hours 72
oracle session <id> --render

如果想让人一眼看懂会话，加上 --slug "<3-5个词>"。

文件选择示例

# 包含多个来源
--file "src/**" --file src/index.ts --file docs --file README.md

# 排除测试与快照
--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

提示该怎么写（高信号模板）

Oracle 从零项目知识开始，不能假设模型能推断你的技术栈、构建工具或约定俗成的路径。一条好提示应包含：

  1. 项目简介：技术栈 + 构建/测试命令 + 平台约束；
  2. “事物所在位置”：关键目录、入口点、配置文件、边界；
  3. 确切问题 + 你尝试过什么 + 逐字复制的错误文本；
  4. 约束条件，例如"不要更改 X"“必须保持公共 API”；
  5. 期望输出，例如"返回补丁计划 + 测试"或"给出 3 个选项及权衡"。

手动粘贴回退

oracle --render --copy -p "<任务>" --file "src/**"

渲染后直接粘贴到任意对话窗口即可。

长期调查的"详尽提示"恢复模式

Oracle 的运行是一次性的，模型不记得之前的运行。若一个调查要持续几天，请写一份可独立成立的提示（6–30 句项目简介 + 目标 + 重现步骤 + 确切错误 + 尝试过的方案）并固定同一组 --file，之后"恢复上下文"就是原样重跑，或重新附加仍在运行的存储会话。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
OracleCLI使用技能Skill（oracle） 命令行上下文打包 + 外部模型长思考 提示与文件捆绑、dry-run 预览、浏览器/API 双引擎、会话恢复、远程主机 需 Node 环境与 oracle 可执行文件，可用 npx -y @steipete/oracle 临时运行 跨模块疑难排查、需要 GPT‑5.2 Pro 级别长思考的仓库级问题 优势：可预览令牌、可排除噪声、会话可重附加、可复现；不足：浏览器模式长跑（10 分钟至 1 小时）需要耐心，且输出需自行验证
网页版 AI 对话手工粘贴 通用聊天式问答 多轮对话、文件上传 零安装 单文件、小片段问题 优势：上手最快；不足：上下文靠手工拼、难以复现、大仓库几乎不可行、无令牌预估
IDE 内置 AI 助手 编辑器内补全与局部改写 行内补全、局部重构、单测生成 装插件即可 日常写码、局部修改 优势：闭环在编辑器内；不足：跨文件全局推理与"长思考"深度有限，难以指定外部强模型
代码打包工具 + 通用大模型 先把仓库压成单个上下文文件，再交给模型 目录聚合、忽略规则、令牌统计 需自行组合两步流程 需要把仓库喂给任意模型的场景 优势：灵活、模型自由；不足：缺少会话管理、运行中断恢复与浏览器自动化通道，流程需手工串联

从对比可以看出，OracleCLI使用技能Skill 的差异点不在"能不能把文件给模型"，而在把整套工作流做成可预览、可恢复、可复现的 CLI 协议。

5. 该技能的典型应用场景与实际体验情况

场景一：跨模块疑难 Bug 排查（后端工程师）

痛点：错误只在特定调用链上出现，涉及 5–8 个文件，网页对话贴不全。做法：把入口点、相关服务模块、配置和逐字错误文本一起打包，用 --engine browser --model gpt-5.2-pro 发起长思考。实际体验：上手难度中等，关键在提示质量——把"技术栈 + 构建测试命令 + 约束"写清楚后，回答的针对性明显提升；注意首次运行别急着中断，长跑是正常现象。

场景二：遗留系统改造方案评估（技术负责人）

痛点：需要外部视角给出多套改造路径与权衡。做法：提示中明确要求"给出 3 个选项及权衡"，并附上关键目录与公共 API 边界文件。实际体验：效果取决于上下文精度；建议先用 --dry-run summary --files-report 看令牌分布，把测试快照、构建产物排除掉，避免把预算浪费在噪声上。

场景三：CI 环境中的自动化会诊（平台/工具链团队）

痛点：本地机器不能常开，长任务容易被中断。做法：在常开机器上 oracle serve --host 0.0.0.0 --port 9473 --token <secret>，客户端用 --remote-host 与 --remote-token 连接。实际体验：需要一定的网络与令牌管理意识；务必不要在上传文件中夹带 .env 或认证令牌。

场景四：完全离线的手动通道（对自动化有顾虑的团队）

痛点：不希望 CLI 直接驱动浏览器。做法：oracle --render --copy 生成 Markdown 并复制，粘贴到任意对话框。实际体验：最简单、最可控，但失去了会话恢复能力。

通用注意事项：所有运行结果都应视为建议性内容，必须对照代码与测试进行验证；浏览器模式只支持 GPT 与 Gemini，需要 Claude／Grok／Codex 时请显式加 --engine api。

6. 该技能能为用户带来的价值

  • 效率提升：把"翻文件、复制、粘贴、补上下文"的重复劳动压缩成一条命令，长思考型问题的准备时间从几十分钟降到几分钟。
  • 成本可控：--dry-run 与 --files-report 让你在发送前就看到负载与令牌花费，避免"发出去才发现超预算"。默认忽略 node_modules、dist、.git 等目录，以及 1 MB 单文件上限，从机制上防止上下文爆炸。
  • 门槛降低：不需要自己写打包脚本，--file 的通配符、排除语法、.gitignore 跟随已经覆盖大多数仓库结构。
  • 过程可复现：会话存储在 ~/.oracle/sessions，oracle status 可列、oracle session 可附加；配合 --slug 与固定的提示 + 文件集，"几天后重现同一问题"成为可执行操作，而不是凭记忆重来。
  • 长期价值：把"向外部强模型请教仓库级问题"沉淀为团队可共享的命令行习惯与提示模板，形成可复用的工程资产。

7. 常见问题 FAQ

Q1：怎么安装？装不上怎么办？

该技能是 Node 类型的包安装，包名为 @steipete/oracle，安装后提供 oracle 可执行文件。如果暂时不想安装，可直接用 npx -y @steipete/oracle --help。注意官方明确提醒避免使用 pnpx，与 sqlite 绑定有关。具体安装入口与命令细节以官方说明为准。

Q2：收费吗？

OracleCLI使用技能Skill 本身是一个命令行工具，它的运行通道分为 API 与浏览器自动化两种。API 模式与模型调用相关的费用取决于你所使用的模型服务商，浏览器模式则依赖你已登录的浏览器会话。具体的计费规则请以官方说明为准。

Q3：运行了很久没反应，是不是挂了？

大概率没挂。浏览器模式配合 GPT‑5.2 Pro 属于"长思考"路径，通常需要约 10 分钟到 1 小时。如果 CLI 超时或连接断开，不要重新运行，先用 oracle status --hours 72 查看会话，再用 oracle session <id> --render 重新附加。

Q4：为什么我的 Claude／Grok 跑不起来？

浏览器模式仅支持 GPT 与 Gemini。要使用 Claude、Grok、Codex 或做多模型对比，必须显式指定 --engine api。另外，如果环境中设置了 OPENAI_API_KEY，引擎会自动选择 api。

Q5：适合谁用？和同类方案怎么选？

适合需要把真实仓库上下文交给强模型做深度分析的后端工程师、技术负责人和工具链团队。如果只是改一两个函数，用 IDE 内置助手更快；如果只想把仓库丢给任意模型，用代码打包工具加通用对话即可；如果你需要运行前预估令牌、运行中断可恢复、提示与文件集可复现，那么 OracleCLI使用技能Skill 更合适。最后提醒：任何输出都应视为建议，请对照代码与测试验证，且默认不要附加 .env、密钥文件或认证令牌。