oracle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Oracle (CLI) — best use

Oracle（CLI）——最佳使用方式

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 outputs as advisory: verify against the codebase + 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 “human in the loop” path: it can take ~10 minutes to ~1 hour; expect a stored session you can reattach to.

Recommended defaults:

Engine: browser (
```
--engine browser
```
)
Model: GPT‑5.2 Pro (either
```
--model gpt-5.2-pro
```
or a ChatGPT picker label like
```
--model "5.2 Pro"
```
)
Attachments: directories/globs + excludes; avoid secrets.

默认工作流：使用

--engine browser

搭配ChatGPT中的GPT‑5.2 Pro。这是“人工参与”的流程：耗时约10分钟至1小时，生成的会话可重新连接。

推荐默认配置：

引擎：browser（
```
--engine browser
```
）
模型：GPT‑5.2 Pro（可使用
```
--model gpt-5.2-pro
```
或ChatGPT选择器标签如
```
--model "5.2 Pro"
```
）
附件：目录/通配符 + 排除项；避免包含敏感信息。

Golden path (fast + reliable)

黄金流程（快速可靠）

Pick a tight file set (fewest files that still contain the truth).
Preview what you’re about to send (
```
--dry-run
```
+
```
--files-report
```
when needed).
Run in browser mode for the usual GPT‑5.2 Pro ChatGPT 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 ChatGPT工作流；仅在明确需要时使用API模式。
若运行中断/超时：重新连接到已存储的会话（不要重新运行）。

Commands (preferred)

推荐命令

Show help (once/session):
- ```
npx -y @steipete/oracle --help
```

Preview (no tokens):

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/cost sanity:

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

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

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

Manual paste fallback (assemble bundle, copy to clipboard):

npx -y @steipete/oracle --render --copy -p "<task>" --file "src/**"

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

查看帮助（每次会话一次）：
- ```
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
```
  的隐藏别名。

Attaching files (

--file

)

附加文件（

--file

）

--file

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

Include:
- ```
--file "src/**"
```
  (directory glob)
- ```
--file src/index.ts
```
  (literal file)
- ```
--file docs --file README.md
```
  (literal directory + file)

Exclude (prefix with

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

Defaults (important behavior from the implementation):
- Default-ignored dirs:
```
node_modules
```
  ,
```
dist
```
  ,
```
coverage
```
  ,
```
.git
```
  ,
```
.turbo
```
  ,
```
.next
```
  ,
```
build
```
  ,
```
tmp
```
  (skipped unless you explicitly pass them as literal dirs/files).
- Honors
```
.gitignore
```
  when expanding globs.
- Does not follow symlinks (glob expansion uses
```
followSymbolicLinks: false
```
  ).
- Dotfiles are filtered unless you explicitly opt in with a pattern that includes a dot-segment (e.g.
```
--file ".github/**"
```
  ).
- Hard cap: files > 1 MB are rejected (split files or narrow the match).

--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的文件会被拒绝（需拆分文件或缩小匹配范围）。

Budget + observability

预算与可观测性

Target: keep total input under ~196k tokens.
Use
```
--files-report
```
(and/or
```
--dry-run json
```
) to spot the token hogs before spending.

If you need hidden/advanced knobs:

npx -y @steipete/oracle --help --verbose

目标：将总输入控制在约196k令牌以内。
使用
```
--files-report
```
（和/或
```
--dry-run json
```
）在消耗令牌前找出占用令牌较多的文件。
若需要隐藏/高级配置项：执行
```
npx -y @steipete/oracle --help --verbose
```
。

Engines (API vs browser)

引擎类型（API vs 浏览器）

Auto-pick: uses
```
api
```
when
```
OPENAI_API_KEY
```
is set, otherwise
```
browser
```
.
Browser engine supports GPT + Gemini only; use
```
--engine api
```
for Claude/Grok/Codex or multi-model runs.
API runs require explicit user consent before starting because they incur usage costs.
Browser attachments:
- ```
--browser-attachments auto|never|always
```
  (auto pastes inline up to ~60k chars then uploads).

Remote browser host (signed-in machine runs automation):

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
```
。
API运行需要用户明确同意后才会启动，因为会产生使用费用。
浏览器附件配置：
- ```
--browser-attachments auto|never|always
```
  （自动内联粘贴最多约60k字符，超出则上传）。

远程浏览器主机（已登录机器运行自动化）：

主机端：

oracle serve --host 0.0.0.0 --port 9473 --token <密钥>

客户端：

oracle --engine browser --remote-host <host:port> --remote-token <密钥> -p "<任务>" --file "src/**"

Sessions + slugs (don’t lose work)

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

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, dependency boundaries).
Exact question + what you tried + the error text (verbatim).
Constraints (“don’t change X”, “must keep public API”, “perf budget”, etc).
Desired output (“return patch plan + tests”, “list risky assumptions”, “give 3 options with tradeoffs”).

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

项目简介（技术栈 + 构建/测试命令 + 平台限制）。
“文件位置说明”（关键目录、入口文件、配置文件、依赖边界）。
具体问题 + 已尝试的方案 + 错误文本（原文）。
约束条件（“不要修改X”、“必须保留公开API”、“性能预算”等）。
期望输出（“返回补丁方案 + 测试用例”、“列出风险假设”、“给出3种带权衡的方案”）。

“Exhaustive prompt” pattern (for later restoration)

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

When you know this will be a long investigation, write a prompt that can stand alone later:

Top: 6–30 sentence project briefing + current goal.
Middle: concrete repro steps + exact errors + what you already tried.
Bottom: attach all context files needed so a fresh model can fully understand (entrypoints, configs, key modules, docs).

If you need to reproduce the same context later, re-run with the same prompt +

--file …

set (Oracle runs are one-shot; the model doesn’t remember prior runs).

当你知道这将是一次长时间的调查时，请编写一个可独立使用的提示词：

顶部：6-30句的项目简介 + 当前目标。
中间：具体复现步骤 + 准确错误信息 + 已尝试的操作。
底部：附加所有必要的上下文文件，让新模型能完全理解（入口文件、配置、关键模块、文档）。

若后续需要重现相同上下文，使用相同提示词 +

--file …

参数重新运行即可（Oracle运行是一次性的；模型不会记住之前的运行记录）。

Safety

安全注意事项

Don’t attach secrets by default (
```
.env
```
, key files, auth tokens). Redact aggressively; share only what’s required.
Prefer “just enough context”: fewer files + better prompt beats whole-repo dumps.

默认不要附加敏感信息（
```
.env
```
、密钥文件、认证令牌）。需严格脱敏，仅分享必要内容。
优先选择“刚好足够的上下文”：更少的文件 + 更优质的提示词，远胜于整个仓库的内容转储。

oracle

Original

Translation

Oracle (CLI) — best use

Oracle（CLI）——最佳使用方式

Main use case (browser, GPT‑5.2 Pro)

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

Golden path (fast + reliable)

黄金流程（快速可靠）

Commands (preferred)

推荐命令

Attaching files (
`--file`
)

附加文件（
`--file`
）

Budget + observability

预算与可观测性

Engines (API vs browser)

引擎类型（API vs 浏览器）

Sessions + slugs (don’t lose work)

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

Prompt template (high signal)

高信息密度提示词模板

“Exhaustive prompt” pattern (for later restoration)

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

Safety

安全注意事项

oracle

Original

Translation

Oracle (CLI) — best use

Oracle（CLI）——最佳使用方式

Main use case (browser, GPT‑5.2 Pro)

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

Golden path (fast + reliable)

黄金流程（快速可靠）

Commands (preferred)

推荐命令

Attaching files (--file)

附加文件（--file）

Budget + observability

预算与可观测性

Engines (API vs browser)

引擎类型（API vs 浏览器）

Sessions + slugs (don’t lose work)

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

Prompt template (high signal)

高信息密度提示词模板

“Exhaustive prompt” pattern (for later restoration)

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

Safety

安全注意事项

Attaching files (
`--file`
)

附加文件（
`--file`
）