oracle

Oracle (CLI) — 最適な使い方

Oracle はプロンプトと選択したファイルをまとめて 1 回限りのリクエストを作成し、API またはブラウザーを通じて、別のモデルが実際のリポジトリのコンテキストを使って回答できるようにします。プロンプトは必須です。必要なコンテキストを補う場合にのみファイルを添付してください。回答は参考情報として扱い、コードベースとテストに照らして検証してください。

主なユースケース（ブラウザー、GPT-5.6）

ChatGPT アカウントで GPT-5.6 を利用できる場合は、ブラウザーモードを使用してください。GPT-5.6 Sol と GPT-5.6 Sol Pro は別々のターゲットです。ベースの Sol では Extra High の推論強度設定を使用し、Pro は難しいタスクや実行時間の長いタスク向けの独立したピッカーターゲットです。

推奨されるデフォルト設定：

• エンジン：browser（--engine browser）
• ベースの Sol：--model gpt-5.6-sol
• ベースの Sol の最大推論：--browser-thinking-time extra-high（Extra High）
• GPT-5.6 Sol で Pro の推論強度を明示的に指定：--browser-thinking-time pro（Pro を確認できない場合はフェイルクローズ）
• Pro の推論強度を指定したブラウザー版 GPT-5.5：--model gpt-5.5 --browser-thinking-time pro
• API の Pro による最大推論：--model gpt-5.6-sol --reasoning-mode pro --reasoning-effort max
• フォールバック：GPT-5.6 を利用できない場合は、--model gpt-5.5-pro を明示的に使用
• 添付ファイル：ディレクトリ／グロブと除外設定を使用し、デフォルトではシークレットを決して添付しない

GPT-5.6 を利用できるかどうかはアカウントによって異なります。ベースの Sol がピッカーに表示されることを確認し、モデル選択の証拠を保持してください。ピッカーに Pro と表示されていることは、ピッカーで選択した証拠にはなりますが、それだけではサーバー側で Pro が生成された証拠にはなりません。

GPT-5.6 のモデル選択

このバージョンでは、どちらの実行環境でも GPT-5.6 をサポートしていますが、Pro の選択方法は異なります。

• gpt-5.6：GPT-5.6 ファミリーのデフォルト設定に従います
• gpt-5.6-sol：ChatGPT の GPT-5.6 Sol エントリーを固定します
• ブラウザー：gpt-5-pro は ChatGPT の Pro ターゲットを選択します
• API：--reasoning-mode pro は gpt-5.6-sol で Pro 実行を有効にします。最大限の推論を行うには --reasoning-effort max と組み合わせてください

ベースの Sol には、次を使用してください。

oracle --engine browser --browser-manual-login --model gpt-5.6-sol \
  --browser-thinking-time extra-high \
  -p "<task>" --file "src/**"

Responses API 経由で GPT-5.6 Sol Pro を使用するには、次を使用してください。

oracle --engine api --model gpt-5.6-sol \
  --reasoning-mode pro \
  --reasoning-effort max \
  -p "<task>" --file "src/**"

--model "GPT-5.6 Sol Pro" は使用しないでください。Pro は意図的に、ブラウザーのピッカーターゲットと API の推論モードとして扱われます。ブラウザーのラベル検証では、gpt-5.6-luna など未知の将来のバリアントを、Sol に暗黙的にフォールバックするのではなく拒否します。API 実行では、そのようなプロバイダーモデル ID が変更されずに保持されます。

ブラウザーモードでは、これらのエイリアスが ChatGPT の Sol ピッカーに対応します。API とマルチモデルの実行では、対応するファーストパーティの OpenAI モデル ID が保持されます。プロバイダー修飾付きの ID と無関係なカスタム ID は、そのまま受け渡されます。

GPT-5.6 のブラウザーサポートは、統合された Intelligence ピッカーに依存します。現在の英語と中国語の推論強度ラベルを認識し、极高 内の 高 に一致するのを避け、React がコンポーザーピルを置き換えた後に再取得します。そのため、選択の検証が、切り離された古いノードに依存することはありません。

npm 0.15.2 との互換性

パッチ未適用の npm 0.15.2 インストールには、gpt-5.6 または gpt-5.6-sol を渡さないでください。このリリースでは、これらのラベルが gpt-5.2 に正規化されることがあります。明示的なフォールバックを使用してください。

npx -y @steipete/[email protected] --engine browser --model gpt-5.5-pro \
  -p "<task>" --file "src/**"

GPT-5.6 のモデル選択と統合ピッカーの変更を含むリリースにアップグレードした後、フォールバックに関する案内を削除する前に、次のすべてを確認してください。--help --verbose に新しいオプションが表示されること、ブラウザーのドライランで両方のエイリアスが GPT-5.6 Sol に解決されること、API ルーティングでファーストパーティの OpenAI が選択されること、ライブのブラウザー実行で厳密な GPT-5.6 選択の証拠が記録されること。

推奨手順

1. 必要な情報が残る範囲で、最小限のファイルセットを選びます。
2. --dry-run と --files-report を使ってバンドルをプレビューします。
3. GPT-5.6 にはブラウザーモードを使用します。API は明示的に使う意図がある場合にのみ使用します。
4. 実行が切断されたりタイムアウトしたりした場合は、重複して開始するのではなく、保存済みのセッションに再接続します。

コマンド

• ヘルプを表示：

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

• モデルを呼び出さずにプレビュー：

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

• トークン使用量を確認：

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

• ブラウザーで実行：

  • oracle --engine browser --browser-manual-login --model gpt-5.6-sol --browser-thinking-time extra-high -p "<task>" --file "src/**"

• 手動貼り付けの代替手段：

  • npx -y @steipete/oracle --render-markdown --copy-markdown -p "<task>" --file "src/**"
  • --render は --render-markdown のエイリアスです。

• パフォーマンストレース：

  • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"

ファイルの添付

--file はファイル、ディレクトリ、グロブを受け付けます。複数回指定するか、 カンマ区切りのエントリーを使用します。

• 含める：--file "src/**"、--file src/index.ts、--file docs --file README.md
• 除外する：パターンの先頭に ! を付けます。例：--file "!src/**/*.test.ts"
• デフォルトで無視されるディレクトリ：node_modules、dist、coverage、.git、 .turbo、.next、build、tmp
• グロブは .gitignore に従い、シンボリックリンクをたどりません。
• ドットファイルを指定するには、--file ".github/**" のようにパターン内で ドットセグメントを明示する必要があります。
• 1 MB を超えるファイルはデフォルトで拒否されます。必要に応じて ORACLE_MAX_FILE_SIZE_BYTES または maxFileSizeBytes を設定してください。

入力全体は、およそ 196k トークン未満にしてください。サイズの大きな入力を特定するには、 --files-report または --dry-run json を使用します。.env ファイル、 秘密鍵、認証トークンなどの秘密情報は、マスキング済みで質問に不可欠な場合を除き、 決して添付しないでください。

エンジンとブラウザーの制御

• OPENAI_API_KEY が設定されている場合は API が、それ以外の場合はブラウザーが自動選択されます。
• ブラウザーでは ChatGPT 経由で GPT モデルを、Gemini のウェブ版経由で Gemini モデルを利用できます。API 専用モデルには gpt-5.1-codex があります。
• 現在のモデルファミリーには GPT-5.5/5.4/5.2/5.1、Gemini 3.x、Claude 4.x があります。利用可否はエンジンとプロバイダーによって異なります。
• API の実行には、利用料金が発生する可能性があるため、ユーザーによる明示的な同意が必要です。
• ブラウザーの添付ファイルは --browser-attachments auto|never|always で制御できます。
• ブラウザーへのアップロードでは、テキスト／ソースファイルが 1 つの場合はそのまま添付し、複数の場合はまとめてバンドルします。テキストのみをアップロードする場合、auto はテキストをフラット化した状態に保ちます。ファイルシステムツリーを保持するには --browser-bundle-format zip を使用します。または、解決されたすべての添付ファイルを 1 つのバンドルにまとめるには --browser-bundle-files を使用します。
• --browser-tab <ref>、--browser-attach-running、または --remote-chrome <host:port> を使用して、既存の Chrome セッションを再利用できます。
• 起動時、新しいタブを開くとき、送信時に Chrome をバックグラウンドに保つには、--browser-no-focus（設定項目 browser.noFocus）を追加します。フォーカスのエミュレーションが利用可能な場合、通常の実行ではキーボードフォーカスを奪ったり、macOS の Spaces を切り替えたりしません。有効にできない場合、Oracle はクリック前に Chrome を前面に出そうとします。再接続時に再起動へ切り替わると、Chrome がアクティブになることがあります。
• モデル選択ピッカーの動作は --browser-model-strategy select|current|ignore で制御できます。
• 同じブラウザーの会話で続けてやり取りするには --browser-follow-up "<prompt>" を、保存済みの実行を対象にするには --followup <sessionId|responseId> を使用します。
• Deep Research を明示的に利用する場合に限り、--browser-research deep を使用します。

API の事前確認

API の実行前に、秘密情報を表示せずにプロバイダーの準備状況を確認します。

oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro
oracle --preflight --models gpt-5.4,gemini-3-pro
oracle --route --model gpt-5.4

ファーストパーティの OpenAI ルーティングが必要な場合は、--provider openai または --no-azure を使用します。部分的な成功も役立つマルチモデルパネルでは、--allow-partial --write-output <path> を使用すると、成功した出力とマニフェストを復元できます。

自動化では、たとえば --timeout 10m のように明示的な期限を設定してください。--http-timeout が指定されていない場合、Oracle は HTTP タイムアウトをそこから設定します。

セッションと復旧

• セッションは ~/.oracle/sessions に保存されます。ORACLE_HOME_DIR で上書きできます。
• ブラウザーの生成物には transcript.md のほか、利用可能な場合は調査レポートや生成画像が含まれます。
• oracle status --hours 72 で最近のセッションを一覧表示します。
• oracle session <id> --render でセッションに再接続します。
• 読みやすいセッション ID にするには、--slug "<3-5 words>" を使用します。
• 実行がタイムアウトした場合は、再接続してください。再実行はしないでください。まったく同じ新しい実行を意図している場合に限り、--force を使用します。
• プロジェクトに属さないブラウザーの単発実行が成功すると、デフォルトで自動的にアーカイブされます。--browser-archive never|always で上書きできます。

プロンプトのテンプレート

Oracle はプロジェクトに関する知識がない状態で開始します。以下を含めてください。

• プロジェクトの概要：スタック、サービス、ビルド／テストコマンド、プラットフォームの制約
• ファイルの場所：エントリーポイント、設定ファイル、主要モジュール、依存関係の境界
• 正確な質問、これまでの試行、エラーの原文
• API 互換性、パフォーマンス予算、変更してはならないファイルなどの制約
• パッチ計画、テスト、リスク一覧、トレードオフの比較など、希望する出力

長時間の調査では、プロンプトを復元可能な形式にしてください。冒頭に 6～30 文の概要を置き、中ほどに具体的な再現手順とエラーを記載し、末尾に新しいモデルで必要となるすべてのコンテキストファイルを添付します。Oracle の実行は単発で、モデルは以前の実行を記憶しません。