name: oracle description: 使用oracle CLI的最佳实践（提示+文件捆绑、引擎、会话和文件附件模式）。 homepage: https://askoracle.dev metadata: { “otto”: { “emoji”: “🧿”, “requires”: { “bins”: [“oracle”] }, “install”: [ { “id”: “node”, “kind”: “node”, “package”: “@steipete/oracle”, “bins”: [“oracle”], “label”: “安装oracle（node）”, }, ], }, }
oracle — 最佳使用
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或--model "5.2 Pro"）
黄金路径
- 选择紧凑的文件集（包含真相的最少文件）。
- 预览负载+令牌花费（
--dry-run+--files-report）。 - 对于常见的GPT‑5.2 Pro工作流程使用浏览器模式；仅在您明确需要时使用API。
- 如果运行断开/超时：重新附加到存储的会话（不要重新运行）。
命令（首选）
-
帮助：
oracle --help- 如果二进制文件未安装：
npx -y @steipete/oracle --help（避免pnpx；sqlite绑定）。
-
预览（无令牌）：
oracle --dry-run summary -p "<任务>" --file "src/**" --file "!**/*.test.*"oracle --dry-run full -p "<任务>" --file "src/**"
-
令牌合理性：
oracle --dry-run summary --files-report -p "<任务>" --file "src/**"
-
浏览器运行（主要路径；长时间运行是正常的）：
oracle --engine browser --model gpt-5.2-pro -p "<任务>" --file "src/**"
-
手动粘贴回退：
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。 - 不跟随符号链接。
- 点文件默认过滤，除非通过模式选择加入（例如
--file ".github/**"）。 - 文件大于1 MB被拒绝。
- 默认忽略的目录：
引擎（API vs 浏览器）
- 自动选择：当设置
OPENAI_API_KEY时为api；否则为browser。 - 浏览器仅支持GPT + Gemini；使用
--engine api进行Claude/Grok/Codex或多模型运行。 - 浏览器附件：
--browser-attachments auto|never|always（自动内联粘贴最多约60k字符，然后上传）。
- 远程浏览器主机：
- 主机：
oracle serve --host 0.0.0.0 --port 9473 --token <secret> - 客户端：
oracle --engine browser --remote-host <host:port> --remote-token <secret> -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个选项及权衡”）。
安全
- 默认不要附加秘密（
.env、密钥文件、认证令牌）。积极编辑；仅分享所需内容。
“详尽提示”恢复模式
对于长期调查，编写一个独立的提示 + 文件集，以便几天后重新运行：
- 6–30句项目简介 + 目标。
- 重现步骤 + 确切错误 + 您尝试了什么。
- 附加所有需要的上下文文件（入口点、配置、关键模块、文档）。
Oracle运行是一次性的；模型不记得先前的运行。“恢复上下文”意味着用相同的提示 + --file …集重新运行（或重新附加仍在运行的存储会话）。