oracle 🧿 — 向硅基智者低语你的提示与文件

Oracle 会将你的提示和文件打包在一起，以便其他 AI 能够结合真实上下文作出回答。它支持 GPT-5.4 Pro（默认）、GPT-5.4、GPT-5.1 Pro、GPT-5.1 Codex（仅 API）、GPT-5.1、GPT-5.2、Gemini 3.1 Pro（仅 API）、Gemini 3 Pro、Claude Sonnet 4.5、Claude Opus 4.1 等多种模型，并且可以在一次运行中调用单个或多个模型。此外，还提供了浏览器自动化功能；使用 --browser-model-strategy current 可以保持当前 ChatGPT 的活跃模型（或使用 ignore 来跳过模型选择）。API 仍然是最可靠的途径，而 --copy 则是一个便捷的手动备用方案。

设置（macOS 浏览器模式）

在浏览器模式下，你无需任何 API 密钥即可使用 GPT-5.4 Pro——它会直接自动化你的 Chrome 浏览器。

首次登录

只需运行一次即可创建自动化配置并登录 ChatGPT。浏览器将保持打开状态，以便你完成登录过程：

oracle --engine browser --browser-manual-login \
  --browser-keep-browser --browser-input-timeout 120000 \
  -p "HI"

后续运行

登录完成后，自动化配置会被保存下来。后续的所有运行都可以使用以下命令：

oracle --engine browser --browser-manual-login \
  --browser-auto-reattach-delay 5s \
  --browser-auto-reattach-interval 3s \
  --browser-auto-reattach-timeout 60s \
  -p "你的提示"

为什么需要这些参数？

• --browser-manual-login — 跳过 macOS Keychain 的 Cookie 访问（避免重复的权限弹窗）
• --browser-auto-reattach-* — 在 ChatGPT 页面加载过程中发生重定向时自动重新连接（修复“被检查的目标已导航或关闭”错误）
• --browser-keep-browser — 第一次登录时保持浏览器打开（之后不需要）
• --browser-input-timeout 120000 — 给予你在首次运行时 2 分钟的时间完成登录

快速入门

全局安装：npm install -g @steipete/oracle Homebrew：brew install steipete/tap/oracle

需 Node 22+。或者使用 npx -y @steipete/oracle …（或 pnpx）。

# 打包内容并粘贴到 ChatGPT
npx -y @steipete/oracle --render --copy -p "审查 TS 数据层是否存在架构漂移" --file "src/**/*.ts,*/*.test.ts"

# 最小化 API 运行（需在环境变量中设置 OPENAI_API_KEY）
npx -y @steipete/oracle -p "为存储适配器撰写一份简洁的架构说明" --file src/storage/README.md

# 多模型 API 运行
npx -y @steipete/oracle -p "交叉核对数据层假设" --models gpt-5.1-pro,gemini-3-pro --file "src/**/*.ts"

# 基于现有 OpenAI/Azure 会话 ID 的后续处理
npx -y @steipete/oracle --engine api --model gpt-5.2-pro --followup release-readiness-audit --followup-model gpt-5.2-pro -p "结合新的上下文重新评估" --file "src/**/*.ts"

# 直接基于 OpenAI Responses API ID 的后续处理
npx -y @steipete/oracle --engine api --model gpt-5.2-pro --followup resp_abc1234567890 -p "从该响应继续" --file docs/notes.md

# 不消耗 Token 的预览
npx -y @steipete/oracle --dry-run summary -p "查看发布说明" --file docs/release-notes.md

# 浏览器运行（无需 API 密钥，会打开 ChatGPT）
npx -y @steipete/oracle --engine browser -p "走一遍 UI 烟囱测试" --file "src/**/*.ts"

# Gemini 浏览器模式（无需 API 密钥；使用 gemini.google.com 的 Chrome Cookie）
npx -y @steipete/oracle --engine browser --model gemini-3-pro --prompt "一只可爱的小机器人拿着香蕉" --generate-image out.jpg --aspect 1:1

# 会话管理（列出并回放）
npx -y @steipete/oracle status --hours 72
npx -y @steipete/oracle session <id> --render
npx -y @steipete/oracle restart <id>

# TUI（交互式，仅供人类使用）
npx -y @steipete/oracle tui

当设置了 OPENAI_API_KEY 时，引擎会自动选择 API 模式，否则将使用浏览器模式；浏览器模式在 macOS 上较为稳定，在 Linux 和 Windows 上也能运行。如果在 Linux 上检测失败，请使用 --browser-chrome-path/--browser-cookie-path；而在 Windows 上，则建议使用 --browser-manual-login 或内嵌 Cookie，以防解密受阻。

集成

CLI

• API 模式要求在环境变量中设置相应的 API 密钥：OPENAI_API_KEY（GPT-5.x）、GEMINI_API_KEY（Gemini 3.1 Pro / Gemini 3 Pro）、ANTHROPIC_API_KEY（Claude Sonnet 4.5 / Opus 4.1）。
• Gemini 浏览器模式则使用 Chrome Cookie 而非 API 密钥——只需在 Chrome 中登录 gemini.google.com 即可（无需 Python/venv）。
• 如果你的 Gemini 账户无法访问“Pro”版本，Oracle 会自动回退到支持的模型进行网页运行，并在详细模式下记录回退信息。
• 建议优先使用 API 模式或 --copy 加手动粘贴；浏览器自动化仍处于实验阶段。
• 浏览器支持：在 macOS 上稳定；在 Linux 上也可运行（必要时添加 --browser-chrome-path/--browser-cookie-path），而在 Windows 上则推荐使用手动登录或内嵌 Cookie，因为应用绑定的 Cookie 可能会阻止解密。
• 远程浏览器服务：在已登录主机上运行 oracle serve；客户端则使用 --remote-host/--remote-token。
• AGENTS.md/CLAUDE.md：

  - Oracle 会将提示与合适的文件打包在一起，供其他 AI（如 GPT 5 Pro 等）回答。适用于遇到瓶颈、调试或代码评审时。
  - 每次会话首次使用前，请运行一次 `npx -y @steipete/oracle --help`。
  

• 小贴士：在配置中设置 browser.chatgptUrl（或 --chatgpt-url），指向一个专门用于 ChatGPT 的项目文件夹，这样浏览器运行就不会污染你的主历史记录了。

Codex 技能

• 将此仓库中的 Oracle 技能复制到你的 Codex 技能文件夹：
  • mkdir -p ~/.codex/skills
  • cp -R skills/oracle ~/.codex/skills/oracle
• 然后在你的 AGENTS.md/CLAUDE.md 中引用它，以便 Codex 加载该技能。

MCP

• 通过 oracle-mcp 运行标准输入输出服务器。
• 使用 steipete/mcporter 或 .mcp.json 配置客户端；连接示例请参阅 docs/mcp.md。

npx -y @steipete/oracle oracle-mcp

• Cursor 设置（MCP）：在 .cursor/mcp.json 中添加如下配置，然后在 Cursor 的 MCP 源中选择 “oracle”。UI 步骤请参见 https://cursor.com/docs/context/mcp。

{
  "oracle": {
    "command": "oracle-mcp",
    "args": []
  }
}

亮点

• 打包一次，随处复用（API 或实验性浏览器）。
• 多模型 API 以聚合成本/用量运行，支持 OpenRouter ID 与第一方模型并存。
• 渲染/复制捆绑包，以便在自动化受限时手动粘贴到 ChatGPT 中。
• GPT‑5 Pro API 默认以分离模式运行；可通过 oracle session <id> / oracle status 重新连接，或使用 --wait 阻止连接。
• OpenAI/Azure 后续 API 调用可从 --followup <sessionId|responseId> 继续；对于多模型父级任务，需添加 --followup-model <model>。
• Azure 端点可通过 --azure-endpoint/--azure-deployment/--azure-api-version 或 AZURE_OPENAI_* 环境变量支持。
• 文件安全：支持通配符/排除规则、文件大小限制及 --files-report。
• 可回放的会话（oracle status、oracle session <id> --render）。
• 会话日志和捆绑包存储于 ~/.oracle/sessions 目录；可通过 ORACLE_HOME_DIR 覆盖路径。

后续调用与 lineage 关系

使用 --followup 可基于现有 OpenAI/Azure Responses API 运行继续，并附加上下文或文件：

oracle \
  --engine api \
  --model gpt-5.2-pro \
  --followup <现有会话 ID 或响应 ID> \
  --followup-model gpt-5.2-pro \
  --slug "my-followup-run" \
  --wait \
  -p "后续：结合附件文件重新评估之前的建议。" \
  --file "server/src/strategy/plan.ts" \
  --file "server/src/strategy/executor.ts"

当父级会话使用了 --models 参数时，--followup-model 用于指定从哪个模型的响应 ID 继续链式调用。 自定义 --base-url 提供者以及 Gemini/Claude API 调用在此处不适用，因为它们不会在 Oracle 中保留 previous_response_id。

oracle status 以树状结构展示父子 lineage 关系：

最近会话
状态    模型         模式    时间戳           字数    成本  标签
已完成  gpt-5.2-pro   api     2026年03月01日 上午09:00  1800  $2.110  architecture-review-parent
已完成  gpt-5.2-pro   api     2026年03月01日 上午09:14  2200  $2.980  ├─ architecture-review-followup
运行中   gpt-5.2-pro   api     2026年03月01日 上午09:22  1400       -  │  └─ architecture-review-implementation-pass
待处理  gpt-5.2-pro   api     2026年03月01日 上午09:25   900       -  └─ architecture-review-risk-check

浏览器自动重连（长时间 Pro 运行）

当浏览器运行超时时（常见于 GPT‑5.x Pro 的长响应），Oracle 可持续轮询当前 ChatGPT 标签页，捕获最终答案，而无需手动执行 oracle session <id> 命令。

通过设置非零间隔启用自动重连功能：

• --browser-auto-reattach-delay — 第一次重试前的等待时间（如 30s）
• --browser-auto-reattach-interval — 重试频率（如 2m）
• --browser-auto-reattach-timeout — 每次尝试的超时时间（默认 2m）

oracle --engine browser \
  --browser-timeout 6m \
  --browser-auto-reattach-delay 30s \
  --browser-auto-reattach-interval 2m \
  --browser-auto-reattach-timeout 2m \
  -p "执行长时间的 UI 审计" --file "src/**/*.ts"

你真正会用到的参数

标志	用途
-p, --prompt <text>	必需的提示文本。
-f, --file <paths...>	附加文件/目录（支持通配符及 ! 排除）。
-e, --engine <api|browser>	选择 API 或浏览器模式（浏览器模式为实验性功能）。
-m, --model <name>	内置模型（默认为 gpt-5.4-pro，还包括 gpt-5.4、gpt-5.1-pro、gpt-5-pro、gpt-5.1、gpt-5.1-codex、gpt-5.2、gpt-5.2-instant、gpt-5.2-pro、仅限 API 的 gemini-3.1-pro、gemini-3-pro、claude-4.5-sonnet、claude-4.1-opus）以及任意 OpenRouter 模型 ID（如 minimax/minimax-m2、openai/gpt-4o-mini）。
--models <list>	多模型运行时使用的以逗号分隔的 API 模型列表（可混合内置模型和 OpenRouter 模型 ID）。
--followup <sessionId|responseId>	从已保存的 Oracle 会话或 resp_... 响应 ID 继续 OpenAI/Azure Responses API 运行。
--followup-model <model>	对于多模型的 OpenAI/Azure 父级会话，选择从哪个模型的响应继续。
--base-url <url>	将 API 请求指向 LiteLLM、Azure、OpenRouter 等服务。
--chatgpt-url <url>	在浏览器模式下指定 ChatGPT 工作区或文件夹。
--browser-model-strategy <select|current|ignore>	控制浏览器模式下 ChatGPT 模型的选择策略（current 保持当前模型；ignore 跳过模型选择器）。
--browser-manual-login	跳过复制 Cookie 的步骤，直接使用持久化的自动化配置文件，并等待手动登录 ChatGPT。
--browser-thinking-time <light|standard|extended|heavy>	设置 ChatGPT 思考时间的强度（仅适用于浏览器模式下的 Thinking/Pro 模型）。
--browser-port <port>	固定 Chrome DevTools 的端口（用于 WSL 或 Windows 防火墙辅助工具）。
--browser-inline-cookies[(-file)] <payload | path>	在无需 Chrome 或 Keychain 的情况下提供 Cookie（浏览器模式）。
--browser-timeout, --browser-input-timeout	控制整体及输入操作的超时时间（支持小时、分钟、秒、毫秒单位）。
--browser-recheck-delay, --browser-recheck-timeout	针对长时间 Pro 模型运行的延迟重检机制：等待超时后再次尝试捕获结果（支持小时、分钟、秒、毫秒单位）。
--browser-reuse-wait	在启动并行浏览器任务前，等待共享的 Chrome 配置文件可用。
--browser-profile-lock-timeout	在发送请求之前，等待共享的手动登录配置文件解锁（用于序列化并行运行）。
--render, --copy	打印和/或复制生成的 Markdown 包。
--wait	阻塞等待后台 API 运行完成（例如 GPT‑5.1 Pro），而不是将其分离到后台执行。
--timeout <seconds|auto>	整体 API 的截止时间（auto 表示专业版为 60 分钟，其他情况为 120 秒）。
--background, --no-background	强制在 API 运行中启用 Responses API 的后台模式（创建 + 检索）。
--http-timeout <ms|s|m|h>	HTTP 客户端超时时间（默认 20 分钟）。
--zombie-timeout <ms|s|m|h>	覆盖 oracle status 使用的过期会话判定阈值。
--zombie-last-activity	使用最后的日志活动来检测过期会话。
--write-output <path>	只保存最终答案（多模型运行时会在文件名后添加 .<model> 后缀）。
--files-report	打印每个文件的 token 使用量。
--dry-run [summary|json|full]	预览运行结果，但不实际发送请求。
--remote-host, --remote-token	使用远程 oracle serve 主机（浏览器模式）。
--remote-chrome <host:port>	在浏览器模式下连接到现有的远程 Chrome 会话。
--youtube <url>	待分析的 YouTube 视频 URL（Gemini 浏览器模式）。
--generate-image <file>	生成图像并保存到文件（Gemini 浏览器模式）。
--edit-image <file>	使用 --output 编辑现有图像（Gemini 浏览器模式）。
--azure-endpoint, --azure-deployment, --azure-api-version	指定 Azure OpenAI 的端点（自动选择 Azure 客户端）。

配置

将默认配置放在 ~/.oracle/config.json 文件中（使用 JSON5 格式）。示例如下：

{
  model: "gpt-5.4-pro",
  engine: "api",
  filesReport: true,
  browser: {
    chatgptUrl: "https://chatgpt.com/g/g-p-691edc9fec088191b553a35093da1ea8-oracle/project",
  },
}

可以使用 browser.chatgptUrl（或旧版别名 browser.url）来指定浏览器自动化操作的目标 ChatGPT 工作区/文件夹。 有关优先级和完整配置模式，请参阅 docs/configuration.md。

高级标志

部分	标志
浏览器	--browser-manual-login, --browser-thinking-time, --browser-timeout, --browser-input-timeout, --browser-recheck-delay, --browser-recheck-timeout, --browser-reuse-wait, --browser-profile-lock-timeout, --browser-auto-reattach-delay, --browser-auto-reattach-interval, --browser-auto-reattach-timeout, --browser-cookie-wait, --browser-inline-cookies[(-file)], --browser-attachments, --browser-inline-files, --browser-bundle-files, --browser-keep-browser, --browser-headless, --browser-hide-window, --browser-no-cookie-sync, --browser-allow-cookie-errors, --browser-chrome-path, --browser-cookie-path, --chatgpt-url
运行控制	--background, --no-background, --http-timeout, --zombie-timeout, --zombie-last-activity
Azure/OpenAI	--azure-endpoint, --azure-deployment, --azure-api-version, --base-url

远程浏览器示例

# 主机（已登录的 Chrome）：启动服务
oracle serve --host 0.0.0.0:9473 --token secret123

# 客户端：连接到该主机
oracle --engine browser --remote-host 192.168.1.10:9473 --remote-token secret123 -p "运行 UI 烟囱测试" --file "src/**/*.ts"

# 如果无法同步 Cookie，可直接传递内联 Cookie（JSON 或 base64 格式）
oracle --engine browser --browser-inline-cookies-file ~/.oracle/cookies.json -p "运行 UI 烟囱测试" --file "src/**/*.ts"

会话管理

# 清理存储的会话（默认路径为 ~/.oracle/sessions；可通过 ORACLE_HOME_DIR 覆盖）
oracle status --clear --hours 168

更多文档

• 桥接（Windows 主机 → Linux 客户端）：docs/bridge.md
• 浏览器模式与分支：docs/browser-mode.md（包含 oracle serve 远程服务）、docs/chromium-forks.md、docs/linux.md
• MCP：docs/mcp.md
• OpenAI/Azure/OpenRouter 端点：docs/openai-endpoints.md、docs/openrouter.md
• 手动烟囱测试：docs/manual-tests.md
• 测试：docs/testing.md

如果您正在寻找更强大的上下文管理工具，请访问 https://repoprompt.com
灵感来源：https://ampcode.com/news/oracle

steipete 的更多免费工具

• ✂️ Trimmy — “粘贴一次，运行一次。” 将多行 Shell 片段简化为可直接粘贴并执行的形式。
• 🟦🟩 CodexBar — 在 macOS 菜单栏中始终显示 Codex 的令牌窗口。
• 🧳 MCPorter — 用于 Model Context Protocol 服务器的 TypeScript 工具包及 CLI。

Oracle 快速上手指南

Oracle 是一个强大的 CLI 工具，能够将你的提示词（Prompt）和代码文件打包，发送给多个主流 AI 模型（如 GPT-5.x 系列、Gemini、Claude 等）进行处理。它支持 API 调用和浏览器自动化两种模式，无需配置 API Key 即可通过浏览器直接使用 ChatGPT 或 Gemini。

环境准备

• 操作系统：macOS（推荐，浏览器模式最稳定）、Linux、Windows。
• Node.js：版本需为 22+。
• 浏览器：若使用浏览器模式（无 API Key），需安装 Google Chrome。
  • Linux 用户：可能需要手动指定 Chrome 路径。
  • Windows 用户：建议使用手动登录模式以避免 Cookie 解密问题。
• 账号要求：
  • API 模式：需在环境变量中配置对应的 API Key（OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY）。
  • 浏览器模式：需已在 Chrome 中登录 chatgpt.com 或 gemini.google.com。

安装步骤

你可以选择以下任意一种方式进行安装：

方式一：使用 npm 全局安装（推荐）

npm install -g @steipete/oracle

方式二：使用 Homebrew (macOS)

brew install steipete/tap/oracle

方式三：免安装直接使用 (npx) 无需安装，每次运行时自动获取最新版本：

npx -y @steipete/oracle --help

国内加速提示：如果 npm 下载缓慢，建议配置淘宝镜像源： npm config set registry https://registry.npmmirror.com

基本使用

Oracle 会自动检测环境变量：如果设置了 OPENAI_API_KEY 则默认使用 API 模式，否则尝试使用浏览器模式。

1. 最简单的 API 调用

假设你已设置 OPENAI_API_KEY，运行以下命令分析当前目录下的 TypeScript 文件：

npx -y @steipete/oracle -p "Review the TS data layer for schema drift" --file "src/**/*.ts"

2. 浏览器模式（无需 API Key）

如果没有 API Key，可以通过自动化浏览器直接使用 ChatGPT。首次运行需要保持浏览器打开以完成登录验证：

# 首次运行：启动浏览器并等待人工登录
npx -y @steipete/oracle --engine browser --browser-manual-login \
  --browser-keep-browser --browser-input-timeout 120000 \
  -p "HI"

登录成功后，后续运行可直接使用以下命令（增加了自动重连参数以防页面跳转中断）：

npx -y @steipete/oracle --engine browser --browser-manual-login \
  --browser-auto-reattach-delay 5s \
  --browser-auto-reattach-interval 3s \
  --browser-auto-reattach-timeout 60s \
  -p "Walk through the UI smoke test" --file "src/**/*.ts"

3. 多模型对比分析

一次性向多个模型发送请求并聚合结果：

npx -y @steipete/oracle -p "Cross-check the data layer assumptions" \
  --models gpt-5.1-pro,gemini-3-pro \
  --file "src/**/*.ts"

4. 预览模式（不消耗 Token）

仅查看将要发送的文件内容和提示词，用于检查上下文是否正确：

npx -y @steipete/oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md

5. 交互式终端界面 (TUI)

启动交互式界面进行对话：

npx -y @steipete/oracle tui