名称： oracle
描述： 使用 @steipete/oracle CLI 将提示词与相关文件打包，通过第二模型（API 或浏览器）进行审查，适用于调试、重构、设计检查或交叉验证。

Oracle (CLI) — 最佳实践

Oracle 将您的提示词与选定的文件打包成一个“一次性”请求，以便另一个模型能够基于真实的仓库上下文（通过 API 或浏览器自动化）给出回答。请将输出视为建议性内容，务必对照代码库和测试进行验证。

主要用例（浏览器模式，GPT‑5.2 Pro）

这里的默认工作流是：在 ChatGPT 中使用 --engine browser 配合 GPT‑5.2 Pro。这是“人在回路”的路径：可能需要约 10 分钟到 1 小时；预期会生成一个可重新连接的存储会话。

推荐默认设置：
- 引擎：浏览器 (--engine browser)
- 模型：GPT‑5.2 Pro（可使用 --model gpt-5.2-pro 或 ChatGPT 选择器标签如 --model "5.2 Pro"）
- 附件：目录/通配符路径 + 排除项；避免包含密钥。

黄金路径（快速可靠）

1. 选择紧凑的文件集（包含必要信息的最少文件）。
2. 预览即将发送的内容（必要时使用 --dry-run 和 --files-report）。
3. 在浏览器模式下运行，使用常规的 GPT‑5.2 Pro ChatGPT 工作流；仅在明确需要时才使用 API 模式。
4. 如果运行断开连接或超时：重新连接到存储的会话（不要重新运行）。

常用命令（推荐）

• 显示帮助（每个会话一次）：

• npx -y @steipete/oracle --help

• 预览（不消耗令牌）：

• npx -y @steipete/oracle --dry-run summary -p "<任务>" --file "src/**" --file "!**/*.test.*"

• npx -y @steipete/oracle --dry-run full -p "<任务>" --file "src/**"

• 令牌/成本检查：

• npx -y @steipete/oracle --dry-run summary --files-report -p "<任务>" --file "src/**"

• 浏览器运行（主要路径；长时间运行是正常的）：

• npx -y @steipete/oracle --engine browser --model gpt-5.2-pro -p "<任务>" --file "src/**"

• 手动粘贴后备方案（组装包并复制到剪贴板）：

• npx -y @steipete/oracle --render --copy -p "<任务>" --file "src/**"
• 注意：--copy 是 --copy-markdown 的隐藏别名。

附加文件 (--file)

--file 接受文件、目录和通配符路径。可以多次传递该参数；条目可以用逗号分隔。

• 包含：
• --file "src/**"（目录通配符）
• --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（除非您明确将它们作为具体目录/文件传递，否则会被跳过）。
• 展开通配符时遵循 .gitignore。
• 不跟随符号链接（通配符展开使用 followSymbolicLinks: false）。
• 点文件默认被过滤，除非您明确使用包含点段的模式选择加入（例如 --file ".github/**"）。
• 硬性限制：大于 1 MB 的文件会被拒绝（请拆分文件或缩小匹配范围）。

预算与可观测性

• 目标：保持总输入低于约 196k 个令牌。
• 使用 --files-report（和/或 --dry-run json）在消耗令牌前识别占用大户。
• 如果需要隐藏/高级选项：npx -y @steipete/oracle --help --verbose。

引擎（API 与浏览器）

• 自动选择：当设置了 OPENAI_API_KEY 时使用 api，否则使用 browser。
• 浏览器引擎仅支持 GPT 和 Gemini；如需使用 Claude/Grok/Codex 或多模型运行，请使用 --engine api。
• API 运行在开始前需要明确的用户同意，因为它们会产生使用成本。
• 浏览器附件：
• --browser-attachments auto|never|always（auto 模式会在约 6 万字符内联粘贴，超出则上传）。
• 远程浏览器主机（已登录的机器运行自动化）：
• 主机端：oracle serve --host 0.0.0.0 --port 9473 --token <密钥>
• 客户端：oracle --engine browser --remote-host <主机:端口> --remote-token <密钥> -p "<任务>" --file "src/**"

会话与标识符（避免丢失工作）

• 存储在 ~/.oracle/sessions 下（可通过 ORACLE_HOME_DIR 覆盖）。
• 运行可能会断开连接或耗时很长（浏览器 + GPT‑5.2 Pro 经常如此）。如果 CLI 超时：不要重新运行；重新连接。
• 列出会话：oracle status --hours 72
• 连接会话：oracle session <id> --render
• 使用 --slug "<3-5个单词>" 使会话 ID 更易读。
• 存在重复提示词防护；仅在确实需要全新运行时才使用 --force。

提示词模板（高信息量）

Oracle 从零项目知识开始。假设模型无法推断您的技术栈、构建工具、约定或“显而易见”的路径。请包含：
- 项目简介（技术栈 + 构建/测试命令 + 平台限制）。
- “文件位置”（关键目录、入口点、配置文件、依赖边界）。
- 确切问题 + 已尝试的方法 + 错误文本（原文）。
- 约束条件（“不要更改 X”、“必须保持公共 API”、“性能预算”等）。
- 期望的输出（“返回补丁计划 + 测试”、“列出有风险的假设”、“提供 3 个选项及其权衡”）。

“详尽提示词”模式（便于后续恢复）

当您知道这将是一个长期的调查时，请编写一个日后可以独立使用的提示词：
- 顶部：6–30 句的项目简介 + 当前目标。
- 中部：具体的重现步骤 + 确切错误 + 您已尝试的方法。
- 底部：附加所有必要的上下文文件，以便新模型能够完全理解（入口点、配置、关键模块、文档）。

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

安全性

• 默认不要附加密钥（.env、密钥文件、身份验证令牌）。积极进行脱敏处理；仅分享必需的内容。
• 优先选择“恰到好处的上下文”：更少的文件 + 更好的提示词胜过整个仓库的转储。