oracle¶

Skill 简介¶

oracle 是一个强大的开发者工具，旨在帮助开发者通过命令行界面（CLI）与先进的语言模型（如 GPT-5.2 Pro）进行高效交互。它将用户的提示（prompt）和选定的文件打包成一个请求，让模型能够基于真实的项目上下文进行推理和回答。无论是进行代码审查、生成代码片段，还是解决复杂的开发问题，oracle 都能提供有价值的建议。

oracle 的设计理念是“一次请求，多场景适用”，它不仅支持 API 调用，还能在浏览器模式下运行，以适应不同的使用需求。通过将项目文件与提示信息结合，oracle 能够为模型提供更丰富的上下文信息，从而生成更准确、更具针对性的回答。需要注意的是，oracle 的输出应被视为建议性内容，开发者仍需结合代码和测试进行验证，以确保其适用性和安全性。

主要功能¶

1. 文件捆绑与上下文传递
oracle 支持将多个文件和目录捆绑到一次请求中，帮助模型全面了解项目上下文。通过使用 --file 参数，开发者可以灵活地包含或排除特定的文件或目录。例如：

oracle --engine browser --model gpt-5.2-pro -p "修复 src/index.ts 中的错误" --file "src/**"

2. 多引擎支持
oracle 支持多种执行引擎，包括浏览器模式和 API 模式。默认情况下，当设置了 OPENAI_API_KEY 时，oracle 会自动选择 API 模式；否则，它会使用浏览器模式。浏览器模式支持 GPT 和 Gemini，而 API 模式则适用于 Claude、Grok、Codex 等模型，以及多模型并行运行的需求。

3. 会话管理与断点续传
oracle 会将每次运行的会话信息存储在 ~/.oracle/sessions 目录下，方便用户后续重新连接或查看运行状态。如果一次运行因超时或其他原因中断，用户可以使用 oracle status 命令查看会话列表，并通过 oracle session <id> 命令重新连接，而无需重新启动整个过程。

4. 高级提示模板
oracle 提供了高级提示模板功能，帮助用户构建结构化、高质量的提示信息。通过在提示中包含项目简介、关键目录、具体问题、已尝试的解决方法和期望的输出格式，开发者可以引导模型生成更符合需求的回答。

5. 文件大小与类型过滤
oracle 内置了文件大小和类型的过滤机制，默认忽略超过 1MB 的文件以及常见的构建目录（如 node_modules、dist 等）。用户可以通过参数调整这些默认值，以适应不同的项目需求。

6. 本地与远程运行模式
除了本地运行，oracle 还支持远程浏览器主机模式。开发者可以通过 oracle serve 命令启动一个远程主机，并通过 --remote-host 和 --remote-token 参数将 CLI 连接到远程主机，从而实现分布式计算和协作开发。

使用场景¶

1. 代码审查与优化
在大型项目中，代码审查可能耗时且容易遗漏细节。通过将项目文件与审查提示一起提交，oracle 可以帮助开发者快速识别潜在问题，并提供优化建议。

2. 自动化任务与脚本生成
开发者可以利用 oracle 生成自动化脚本或任务。例如，根据项目需求生成构建脚本、部署流程或测试用例，从而提高开发效率。

3. 错误排查与修复
当开发者遇到难以解决的错误时，可以将错误信息和相关代码提交给 oracle，获取详细的排查步骤和修复建议。

4. 文档生成与维护
oracle 可以帮助开发者快速生成项目文档，包括 README 文件、API 文档和使用指南等，确保文档的准确性和完整性。

5. 项目迁移与升级
在进行项目迁移或升级时，oracle 可以提供迁移路径建议，帮助开发者顺利完成版本更新或技术栈迁移。

如何使用¶

安装¶

oracle 可以通过 npm 进行安装。确保你的系统中已安装 Node.js 和 npm，然后运行以下命令：

npm install -g @steipete/oracle

配置¶

在使用 oracle 之前，建议设置 OPENAI_API_KEY 环境变量，以便 oracle 能够使用 API 模式进行调用。你可以通过以下命令设置环境变量：

export OPENAI_API_KEY=your_api_key_here

前置条件¶

• Node.js：确保已安装 Node.js（推荐版本 14.x 及以上）。
• 模型访问权限：根据所使用的模型，确保你有相应的访问权限和 API 密钥。

命令示例¶

• 查看帮助文档：
  bash oracle --help
• 预览文件捆绑情况：
  bash oracle --dry-run summary -p "修复 src/index.ts 中的错误" --file "src/**"
• 运行浏览器模式：
  bash oracle --engine browser --model gpt-5.2-pro -p "修复 src/index.ts 中的错误" --file "src/**"
• 重新连接会话：
  bash oracle session <session_id> --render

示例¶

示例 1：修复代码中的错误¶

假设你有一个名为 src/index.ts 的文件，其中包含一个需要修复的错误。你可以按照以下步骤使用 oracle：

oracle --engine browser --model gpt-5.2-pro -p "修复 src/index.ts 中的错误" --file "src/index.ts"

示例 2：生成项目文档¶

如果你想为你的项目生成一个 README 文件，可以运行以下命令：

oracle --engine browser --model gpt-5.2-pro -p "生成 README.md 文件，包含项目简介、安装步骤和使用示例" --file "src/**" --file "README.md"

总结¶

oracle 是一个功能强大的工具，能够帮助开发者更高效地与先进的语言模型进行交互。通过将项目文件与提示信息结合，oracle 能够提供更准确、更具针对性的建议，显著提高开发效率。无论是进行代码审查、生成自动化脚本，还是进行错误排查和文档生成，oracle 都能成为开发者的得力助手。

对于那些希望利用 AI 提升开发效率的开发者来说，oracle 是一个值得尝试的工具。它不仅简化了与语言模型的交互过程，还通过高级功能和灵活的参数设置，满足了不同开发场景的需求。