oracle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

oracle — best use

Oracle — 最佳使用方式

Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat output as advisory: verify against code + tests.

Oracle会将你的提示词+选定文件打包成一个“一次性”请求，以便其他模型结合真实代码库上下文（API或浏览器自动化）给出回答。请将输出仅作为参考：务必结合代码和测试进行验证。

Main use case (browser, GPT‑5.2 Pro)

主要使用场景（浏览器端，GPT‑5.2 Pro）

Default workflow here:

--engine browser

with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.

Recommended defaults:

Engine: browser (
```
--engine browser
```
)
Model: GPT‑5.2 Pro (
```
--model gpt-5.2-pro
```
or
```
--model "5.2 Pro"
```
)

此处默认工作流：在ChatGPT中使用

--engine browser

搭配GPT‑5.2 Pro。这是常见的“深度思考”流程：耗时通常在10分钟到1小时之间；会生成可重新连接的存储会话。

推荐默认配置：

引擎：browser（
```
--engine browser
```
）
模型：GPT‑5.2 Pro（
```
--model gpt-5.2-pro
```
或
```
--model "5.2 Pro"
```
）

Golden path

黄金流程

Pick a tight file set (fewest files that still contain the truth).
Preview payload + token spend (
```
--dry-run
```
+
```
--files-report
```
).
Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
If the run detaches/timeouts: reattach to the stored session (don’t re-run).

选择精简的文件集（包含必要信息的最少文件数量）。
预览请求载荷和令牌消耗（
```
--dry-run
```
+
```
--files-report
```
）。
常规GPT‑5.2 Pro工作流使用浏览器模式；仅当明确需要时才使用API模式。
如果运行中断/超时：重新连接到存储的会话（不要重新运行）。

Commands (preferred)

推荐命令

Help:
- ```
oracle --help
```
- If the binary isn’t installed:
```
npx -y @steipete/oracle --help
```
  (avoid
```
pnpx
```
  here; sqlite bindings).

Preview (no tokens):

oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"

oracle --dry-run full -p "<task>" --file "src/**"

Token sanity:

oracle --dry-run summary --files-report -p "<task>" --file "src/**"

Browser run (main path; long-running is normal):

oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"

Manual paste fallback:

oracle --render --copy -p "<task>" --file "src/**"

Note:
```
--copy
```
is a hidden alias for
```
--copy-markdown
```
.

帮助：
- ```
oracle --help
```
- 若未安装二进制文件：
```
npx -y @steipete/oracle --help
```
  （此处避免使用
```
pnpx
```
  ；存在sqlite绑定问题）。

预览（不消耗令牌）：

oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"

oracle --dry-run full -p "<task>" --file "src/**"

令牌合理性检查：

oracle --dry-run summary --files-report -p "<task>" --file "src/**"

浏览器端运行（主要流程；长时间运行属于正常情况）：
- ```
oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"
```

手动粘贴备选方案：

oracle --render --copy -p "<task>" --file "src/**"

注意：
```
--copy
```
是
```
--copy-markdown
```
的隐藏别名。

Attaching files (

--file

)

文件附加（

--file

）

--file

accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.

Include:

```
--file "src/**"
```
```
--file src/index.ts
```
```
--file docs --file README.md
```

Exclude:

--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"

Defaults (implementation behavior):
- Default-ignored dirs:
```
node_modules
```
  ,
```
dist
```
  ,
```
coverage
```
  ,
```
.git
```
  ,
```
.turbo
```
  ,
```
.next
```
  ,
```
build
```
  ,
```
tmp
```
  (skipped unless explicitly passed as literal dirs/files).
- Honors
```
.gitignore
```
  when expanding globs.
- Does not follow symlinks.
- Dotfiles filtered unless opted in via pattern (e.g.
```
--file ".github/**"
```
  ).
- Files > 1 MB rejected.

--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的文件会被拒绝。

Engines (API vs browser)

引擎（API vs 浏览器）

Auto-pick:
```
api
```
when
```
OPENAI_API_KEY
```
is set; otherwise
```
browser
```
.
Browser supports GPT + Gemini only; use
```
--engine api
```
for Claude/Grok/Codex or multi-model runs.
Browser attachments:
- ```
--browser-attachments auto|never|always
```
  (auto pastes inline up to ~60k chars then uploads).

Remote browser host:

Host:

oracle serve --host 0.0.0.0 --port 9473 --token <secret>

Client:

oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"

自动选择：当设置了
```
OPENAI_API_KEY
```
时使用
```
api
```
；否则使用
```
browser
```
。
浏览器模式仅支持GPT + Gemini；若要使用Claude/Grok/Codex或多模型运行，请使用
```
--engine api
```
。
浏览器端附件：
- ```
--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 "<task>" --file "src/**"

Sessions + slugs

会话与标识（slugs）

Stored under
```
~/.oracle/sessions
```
(override with
```
ORACLE_HOME_DIR
```
).
Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach.
- List:
```
oracle status --hours 72
```
- Attach:
```
oracle session <id> --render
```
Use
```
--slug "<3-5 words>"
```
to keep session IDs readable.
Duplicate prompt guard exists; use
```
--force
```
only when you truly want a fresh run.

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

Prompt template (high signal)

高信息密度提示词模板

Oracle starts with zero project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:

Project briefing (stack + build/test commands + platform constraints).
“Where things live” (key directories, entrypoints, config files, boundaries).
Exact question + what you tried + the error text (verbatim).
Constraints (“don’t change X”, “must keep public API”, etc).
Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).

Oracle初始状态下完全不了解你的项目。请假设模型无法推断你的技术栈、构建工具、约定或“显而易见”的路径。请包含以下内容：

项目简介（技术栈+构建/测试命令+平台约束）。
“关键内容位置”（核心目录、入口文件、配置文件、边界划分）。
具体问题+你已尝试的操作+错误文本（原文）。
约束条件（“不要修改X”、“必须保留公共API”等）。
期望输出（“返回补丁方案+测试用例”、“给出3种带权衡的方案”）。

Safety

安全注意事项

Don’t attach secrets by default (
```
.env
```
, key files, auth tokens). Redact aggressively; share only what’s required.

默认不要附加敏感信息（
```
.env
```
、密钥文件、认证令牌）。务必严格脱敏；仅分享必要内容。

“Exhaustive prompt” restoration pattern

“详尽提示词”恢复模式

For long investigations, write a standalone prompt + file set so you can rerun days later:

6–30 sentence project briefing + the goal.
Repro steps + exact errors + what you tried.
Attach all context files needed (entrypoints, configs, key modules, docs).

Oracle runs are one-shot; the model doesn’t remember prior runs. “Restoring context” means re-running with the same prompt +

--file …

set (or reattaching a still-running stored session).

对于长时间的排查工作，请编写独立的提示词+文件集，以便数日后仍可重新运行：

6-30句话的项目简介+目标。
复现步骤+具体错误+你已尝试的操作。
附加所有必要的上下文文件（入口文件、配置、核心模块、文档）。

Oracle运行是一次性的；模型不会记住之前的运行记录。“恢复上下文”意味着使用相同的提示词+

--file …

集重新运行（或重新连接仍在运行的存储会话）。

oracle

Original

Translation

oracle — best use

Oracle — 最佳使用方式

Main use case (browser, GPT‑5.2 Pro)

主要使用场景（浏览器端，GPT‑5.2 Pro）

Golden path

黄金流程

Commands (preferred)

推荐命令

Attaching files (
`--file`
)

文件附加（
`--file`
）

Engines (API vs browser)

引擎（API vs 浏览器）

Sessions + slugs

会话与标识（slugs）

Prompt template (high signal)

高信息密度提示词模板

Safety

安全注意事项

“Exhaustive prompt” restoration pattern

“详尽提示词”恢复模式

oracle

Original

Translation

oracle — best use

Oracle — 最佳使用方式

Main use case (browser, GPT‑5.2 Pro)

主要使用场景（浏览器端，GPT‑5.2 Pro）

Golden path

黄金流程

Commands (preferred)

推荐命令

Attaching files (--file)

文件附加（--file）

Engines (API vs browser)

引擎（API vs 浏览器）

Sessions + slugs

会话与标识（slugs）

Prompt template (high signal)

高信息密度提示词模板

Safety

安全注意事项

“Exhaustive prompt” restoration pattern

“详尽提示词”恢复模式

Attaching files (
`--file`
)

文件附加（
`--file`
）