介绍
# Oracle (CLI) — best use
Oracle 将你的提示词 + 选定的文件打包成一个“单次”请求，以便另一个模型可以利用真实的代码库上下文（API 或浏览器自动化）来回答。将输出视为建议：请对照代码库和测试进行验证。
## 主要用例（浏览器，GPT‑5.2 Pro）
此处的默认工作流：在 ChatGPT 中使用 GPT‑5.2 Pro 并设置 `--engine browser`。这是“人在回路”的路径：可能耗时约 10 分钟到 1 小时；预期会生成一个你可以重新连接的已存储会话。
推荐的默认设置： - 引擎：browser (`--engine browser`) - 模型：GPT‑5.2 Pro（使用 `--model gpt-5.2-pro` 或 ChatGPT 的选择器标签，如 `--model "5.2 Pro"`） - 附件：目录/glob 模式 + 排除项；避免包含密钥。
## 黄金路径（快速 + 可靠）
1. 选取紧凑的文件集（包含真实信息的最少文件）。 2. 预览你即将发送的内容（必要时使用 `--dry-run` + `--files-report`）。 3. 在浏览器模式下运行，以执行常规的 GPT‑5.2 Pro ChatGPT 工作流；仅在明确需要时使用 API。 4. 如果运行断开连接或超时：重新连接到已存储的会话（不要重新运行）。
## 命令（推荐）
- 显示帮助（每次/每会话一次）： - `npx -y @steipete/oracle --help`
- 预览（不消耗 token）： - `npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"` - `npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"`
- Token/成本检查： - `npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"`
- 浏览器运行（主要路径；长时间运行是正常的）： - `npx -y @steipete/oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`
- 手动粘贴回退（组装 bundle，复制到剪贴板）： - `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 的文件将被拒绝（拆分文件或缩小匹配范围）。
## 预算 + 可观测性
- 目标：将总输入保持在约 196k token 以下。 - 在花费之前使用 `--files-report`（和/或 `--dry-run json`）来发现 token 消耗大户。 - 如果你需要隐藏/高级选项：`npx -y @steipete/oracle --help --verbose`。
## 引擎（API vs 浏览器）
- 自动选择：当设置了 `OPENAI_API_KEY` 时使用 `api`，否则使用 `browser`。 - 浏览器引擎仅支持 GPT 和 Gemini；针对 Claude/Grok/Codex 或多模型运行，请使用 `--engine api`。 - **API 运行在开始前需要明确的用户同意**，因为它们会产生使用费用。 - 浏览器附件： - `--browser-attachments auto|never|always`（auto 会内联粘贴最多约 60k 字符，然后上传）。 - 远程浏览器主机（登录的机器运行自动化）： - 主机：`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/**"`
## 会话 + 简称（不要丢失工作）
- 存储在 `~/.oracle/sessions` 下（可通过 `ORACLE_HOME_DIR` 覆盖）。 - 运行可能会断开连接或需要很长时间（浏览器 + GPT‑5.2 Pro 经常如此）。如果 CLI 超时：不要重新运行；重新连接。 - 列表：`oracle status --hours 72` - 连接：`oracle session <id> --render` - 使用 `--slug "<3-5 words>"` 让会话 ID 保持可读性。 - 存在重复提示词保护；仅在你确实想要全新运行时使用 `--force`。
## 提示词模板（高信噪比）
Oracle 从**零**项目知识开始。假设模型无法推断你的技术栈、构建工具、约定或“显而易见”的路径。包括： - 项目简介（技术栈 + 构建/测试命令 + 平台限制）。 - “事物的位置”（关键目录、入口点、配置文件、依赖边界）。 - 准确的问题 + 你尝试过的方法 + 错误文本（逐字逐句）。 - 约束（“不要更改 X”、“必须保持公共 API”、“性能预算”等）。 - 期望的输出（“返回补丁计划 + 测试”、“列出有风险的假设”、“给出 3 个选项及其权衡”）。
### “详尽提示词”模式（用于后续恢复）
当你知道这将是一次长时间的调查时，编写一个以后可以独立存在的提示词： - 顶部：6–30 句的项目简介 + 当前目标。 - 中部：具体的复现步骤 + 准确的错误 + 你已经尝试过的内容。 - 底部：附加*所有*所需的上下文文件，以便新模型能够完全理解（入口点、配置、关键模块、文档）。
如果你需要在以后重现相同的上下文，请使用相同的提示词 + `--file …` 集合重新运行（Oracle 运行是单次的；模型不记得之前的运行）。
## 安全性
- 默认情况下不要附加密钥（`.env`、密钥文件、auth 令牌）。积极进行编辑；仅分享必要的内容。 - 优先使用“恰到好处的上下文”：较少的文件 + 更好的提示词胜过整个代码库的倾倒。