oracle 是做什么的？
Oracle 将提示词和选定文件打包，进行一次第二模型处理。输出结果仅供参考；请对照代码和测试自行验证。
主要路径
当前 CLI 默认模型：gpt-5.5-pro。浏览器引擎适用于长时间 ChatGPT Pro 运行；API 引擎适用于已配置 OPENAI_API_KEY 或 Azure 的情况。
推荐默认值：
- 先预览：
--dry-run summary --files-report - 浏览器长时间运行：
--engine browser --model gpt-5.5-pro - API 显式指定：
--engine api --model gpt-5.5
黄金路径
- 选择紧凑的文件集（包含真相所需的最少文件）。
- 预览负载和 Token 消耗（
--dry-run+--files-report）。 - 浏览器模式用于长时间 Pro 思考；API 模式用于显式 API 调用。
- 如果运行断开/超时：重新连接已存储的会话。不要盲目重新运行。
命令（推荐）
-
帮助：
oracle --help- 如果二进制未安装：
npx -y @steipete/oracle --help（此处避免使用pnpx；sqlite 绑定）。
-
预览（不消耗 Token）：
oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"oracle --dry-run full -p "<task>" --file "src/**"
-
Token 合理性检查：
oracle --dry-run summary --files-report -p "<task>" --file "src/**"
-
浏览器运行（主要路径；长时间运行是正常的）：
oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"
-
手动粘贴回退：
oracle --render --copy -p "<task>" --file "src/**"- 注意：
--copy是--copy-markdown的隐藏别名。
附加文件（--file）
--file 接受文件、目录和 glob 模式。可以多次传递；条目可以用逗号分隔。
-
包含：
--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（除非显式作为字面目录/文件传递，否则跳过）。 - 扩展 glob 时遵循
.gitignore。 - 不跟随符号链接。
- 点文件默认过滤，除非通过模式选择（例如
--file ".github/**"）。 - 拒绝大于 1 MB 的文件。
- 默认忽略的目录：
引擎（API 与浏览器）
- 自动选择：当设置了
OPENAI_API_KEY时选择api；否则选择browser。 - 浏览器仅支持 GPT + Gemini；使用
--engine api支持 Claude/Grok/Codex 或多模型运行。 - 浏览器附件：
--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覆盖）。 - 运行可能会断开或耗时较长（浏览器 + Pro 经常如此）。如果 CLI 超时：不要重新运行；重新连接。
- 列出：
oracle status --hours 72 - 连接：
oracle session <id> --render
- 列出：
- 使用
--slug "<3-5 words>"让会话 ID 更易读。 - 存在重复提示保护；只有当你确实想要全新运行时才使用
--force。
提示模板（高信号）
Oracle 从零项目知识开始。假设模型无法推断你的技术栈、构建工具、约定或“显而易见”的路径。需要包含：
- 项目简介（技术栈 + 构建/测试命令 + 平台约束）。
- “文件位置说明”（关键目录、入口点、配置文件、边界）。
- 精确问题 + 你尝试过的内容 + 错误文本（原样）。
- 约束（“不要更改 X”、“必须保持公共 API”等）。
- 期望输出（“返回补丁方案 + 测试”、“给出 3 个选项及权衡”）。
附件
- 除非用户要求包含，否则不要在附件中放入
.env、密钥文件和身份验证令牌。
“详尽提示”恢复模式
对于长期调查，编写一个独立的提示词 + 文件集，以便数天后重新运行：
- 6-30 句的项目简介 + 目标。
- 复现步骤 + 确切错误 + 你尝试过的内容。
- 附加所有需要的上下文文件（入口点、配置、关键模块、文档）。
Oracle 运行是一次性的；模型不会记住之前的运行。“恢复上下文”意味着用相同的提示词 + --file … 集重新运行（或重新连接仍在运行的已存储会话）。