Community编程与开发github.com

steipete/oracle

Oracle 第二模型审查:打包提示词和文件,进行调试、重构和设计。

oracle 是什么?

Oracle 是一款 CLI 工具,专门用于将开发者的工作上下文(提示词 + 选定的文件)打包成一个“一次性”请求,发送给另一个 AI 模型(如 GPT-5.5 Pro)进行审查。它通过浏览器自动化或 API 两种引擎运行,支持 `--engine browser`(人类在环路中)或 `--engine api`(直接调用)。其主要价值在于提供“第二模型”视角,帮助开发者发现代码中的问题、验证思路或进行架构评审,而无需在原本的开发环境中切换模型。Oracle 支持精细的文件包含/排除规则(支持 glob、.gitignore),并提供预算观测(`--files-report`)和性能追踪(`--perf-trace`)。输出结果以会话形式存储在本地,支持断线重连,避免重复运行损失进度。特别适用于需要远程协作者或替代模型快速理解复杂项目上下文的场景。

兼容平台✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/oracle

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Oracle (CLI) — 最佳用法

Oracle 将您的提示词和选定的文件打包成一个“一次性”请求,这样另一个模型就可以带着完整的仓库上下文(通过 API 或浏览器自动化)来回应。请将输出视为建议:务必对照代码库和测试进行验证。

主要用例(浏览器,GPT‑5.5 Pro)

默认工作流:使用 --engine browser 搭配 ChatGPT 中的 GPT‑5.5 Pro。这是“人机协作”路径:可能需要大约 10 分钟到 1 小时;期待一个可以重新连接的已存储会话。

推荐默认值:

  • 引擎:浏览器 (--engine browser)
  • 模型:GPT‑5.5 Pro(使用 --model gpt-5.5-pro 或 ChatGPT 选择器标签 --model "5.5 Pro")
  • 附件:目录/glob 模式 + 排除项;避免包含密钥。

黄金路径(快速且可靠)

  1. 选择精准的文件集(包含事实的最少文件)。
  2. 预览您要发送的内容(必要时使用 --dry-run + --files-report)。
  3. 在浏览器模式下运行,使用常用的 GPT‑5.5 Pro ChatGPT 工作流;仅在明确需要时使用 API。
  4. 如果运行断开/超时:重新连接到已存储的会话(不要重新运行)。

命令(推荐)

  • 显示帮助(每个会话一次):

    • npx -y @steipete/oracle --help
  • 预览(不消耗令牌):

    • npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
    • npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"
  • 令牌/成本合理性检查:

    • npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"
  • 启动/性能追踪:

    • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"
    • 当 CLI 启动或首次输出时间感觉缓慢时使用;检查 first-output 和 exit。
  • 浏览器运行(主要路径;长时间运行是正常的):

    • npx -y @steipete/oracle --engine browser --model gpt-5.5-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。
    • 不跟随符号链接(glob 扩展使用 followSymbolicLinks: false)。
    • 点文件会被过滤,除非您显式使用包含点段的模式(例如 --file ".github/**")。
    • 默认限制:超过 1 MB 的文件会被拒绝,除非您设置 ORACLE_MAX_FILE_SIZE_BYTES 或 ~/.oracle/config.json 中的 maxFileSizeBytes。

预算与可观测性

  • 目标:保持总输入在大约 196k 令牌以内。
  • 在花费之前使用 --files-report(和/或 --dry-run json)来发现令牌大户。
  • 使用 --perf-trace / ORACLE_PERF_TRACE=1 进行启动和首次输出计时。追踪会隐去提示词、令牌、密钥、cookie 和内联 cookie 负载;分离的 API 子进程会写入一个带有会话后缀的侧车追踪文件。
  • 如果您需要隐藏/高级选项:npx -y @steipete/oracle --help --verbose。

引擎(API vs 浏览器)

  • 自动选择:当设置了 OPENAI_API_KEY 时使用 api,否则使用 browser。
  • 浏览器引擎仅支持 GPT + Gemini;使用 --engine api 来支持 Claude/Grok/Codex 或多模型运行。
  • API 运行在开始前需要用户明确同意,因为会产生使用成本。
  • 浏览器附件:
    • --browser-attachments auto|never|always(自动内联粘贴最多约 60k 字符,然后上传)。
    • 添加 --browser-bundle-files --browser-bundle-format zip 将多个文本文件作为一个 ZIP 上传,同时保留文件名。
  • 远程浏览器主机(已登录的机器运行自动化):
    • 主机: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/**"

API 预检

  • API 运行需要用户明确同意并且需要花钱。
  • 在 API 运行之前,检查提供商就绪状态,不打印密钥:
    • oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
    • oracle --preflight --models gpt-5.4,gemini-3-pro
    • oracle --route --model gpt-5.4
  • 如果用户想要第一方 OpenAI,传递 --provider openai 或 --no-azure。这可以防止导出的 Azure 环境/配置劫持路由:
    • oracle --provider openai --engine api --model gpt-5.5-pro ...
  • 对于部分成功也有用的咨询性多模型面板,使用 --allow-partial --write-output <path>,这样成功的模型文件和 <stem>.oracle.json 清单容易恢复:
    • oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<task>"
  • --timeout 10m 是正常的用户端 API 截止时间;Oracle 会推导 HTTP 传输超时,除非明确设置了 --http-timeout。
  • 如果导出的 OPENAI_API_KEY 无效,并且用户想要他们个人的 OpenAI 密钥,请在一个持久的 tmux 会话中使用 $one-password。已知项目:API Key - OpenAI - Personal,字段 api_key。仅注入到单个 Oracle 命令中;切勿打印密钥:
    • OPENAI_API_KEY="$(op item get 'API Key - OpenAI - Personal' --account my.1password.com --fields label=api_key --reveal)" oracle --provider openai --engine api --model gpt-5.5-pro ...
  • 要调试 Oracle 本身,请在拉取 ~/Projects/oracle 后优先使用本地检出:
    • pnpm -C ~/Projects/oracle run build
    • node ~/Projects/oracle/dist/scripts/run-cli.js ...

会话与别名(不要丢失工作)

  • 存储在 ~/.oracle/sessions 下(使用 ORACLE_HOME_DIR 覆盖)。
  • 浏览器运行在 ~/.oracle/sessions/<id>/artifacts/ 下保存持久文件,包括 transcript.md、Deep Research 报告以及可用的下载的 ChatGPT 生成的图像。
  • 运行可能会断开或需要很长时间(浏览器/API + GPT‑5.5 Pro 经常如此)。如果 CLI 超时:不要重新运行;重新连接。
    • 列出:oracle status --hours 72
    • 连接:oracle session <id> --render
  • 使用 --slug "<3-5 words>" 来保持会话 ID 可读。
  • 存在重复提示防护;仅在确实需要全新运行时使用 --force。
  • CLI 护栏:无提示词的根运行以非零退出;--dry-run 与 --render / --render-markdown 冲突;Ctrl-C 以代码 130 退出前台 API 运行,同时浏览器清理/重新连接仍在运行。

提示词模板(高信号)

Oracle 开始时零项目知识。假设模型无法推断您的技术栈、构建工具、约定或“显而易见的”路径。包含:

  • 项目简报(技术栈 + 构建/测试命令 + 平台约束)。
  • “内容所在位置”(关键目录、入口点、配置文件、依赖边界)。
  • 确切问题 + 您尝试过的方法 + 错误文本(逐字)。
  • 约束条件(“不要更改 X”、“必须保持公共 API”、“性能预算”等)。
  • 期望输出(“返回补丁计划 + 测试”、“列出有风险的假设”、“提供 3 个选项及其权衡”)。

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

当您知道这将是一次长时间调查时,请编写一个以后可以独立使用的提示词:

  • 顶部:6–30 句的项目简报 + 当前目标。
  • 中间:具体的重现步骤 + 确切错误 + 您已经尝试过的方法。
  • 底部:附上所有需要的上下文文件,以便新模型能够完全理解(入口点、配置、关键模块、文档)。

如果您以后需要重现相同的上下文,请使用相同的提示词 + --file … 集重新运行(Oracle 运行是一次性的;模型不记得以前的运行)。

安全性

  • 默认情况下不要附加密钥(.env、密钥文件、认证令牌)。积极隐去;只分享必要的信息。
  • 优先“恰到好处的上下文”:更少的文件 + 更好的提示词胜过整个仓库的转储。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

相关技能