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 模式 + 排除项;避免包含密钥。
黄金路径(快速且可靠)
- 选择精准的文件集(包含事实的最少文件)。
- 预览您要发送的内容(必要时使用
--dry-run+--files-report)。 - 在浏览器模式下运行,使用常用的 GPT‑5.5 Pro ChatGPT 工作流;仅在明确需要时使用 API。
- 如果运行断开/超时:重新连接到已存储的会话(不要重新运行)。
命令(推荐)
-
显示帮助(每个会话一次):
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-prooracle --preflight --models gpt-5.4,gemini-3-prooracle --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 buildnode ~/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、密钥文件、认证令牌)。积极隐去;只分享必要的信息。 - 优先“恰到好处的上下文”:更少的文件 + 更好的提示词胜过整个仓库的转储。