oracle

oracle は何をしますか？

Oracleは、プロンプトと選択したファイルをバンドルし、セカンドモデルによる処理を1回実行します。出力は助言として扱い、コードとテストで検証してください。

メインパス

現在の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

黄金の道

1. 厳選されたファイルセットを選定する（真実を含む最小限のファイル）。
2. ペイロードとトークン消費をプレビューする（--dry-run + --files-report）。
3. 長時間のPro思考にはブラウザモード、明示的なAPI呼び出しにはAPIモードを使用する。
4. 実行がデタッチまたはタイムアウトした場合: 保存されたセッションに再アタッチする。盲目的に再実行しない。

コマンド（推奨）

• ヘルプ:

  • 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.5-pro -p "<task>" --file "src/**"

• 手動ペーストフォールバック:

  • oracle --render --copy -p "<task>" --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 のみサポート。Claude/Grok/Codex またはマルチモデル実行には --engine api を使用。
• ブラウザ添付ファイル:
  • --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語>" を使用するとセッションIDを読みやすくできます。
• 重複プロンプトガードが存在します。本当に新規実行が必要な場合のみ --force を使用してください。

プロンプトテンプレート（高シグナル）

Oracleはゼロのプロジェクト知識から開始します。モデルがスタック、ビルドツール、規約、または「自明な」パスを推測できないことを前提としてください。以下を含めてください:

• プロジェクト概要（スタック + ビルド/テストコマンド + プラットフォーム制約）。
• 「物の在処」（主要ディレクトリ、エントリポイント、設定ファイル、境界）。
• 正確な質問 + 試したこと + エラーテキスト（原文ママ）。
• 制約事項（「Xは変更しない」、「公開APIを維持すること」など）。
• 期待する出力（「パッチ計画とテストを返す」、「トレードオフを含む3つの選択肢を示す」）。

添付ファイル

• ユーザーが明示的に要求しない限り、.env、キーファイル、認証トークンを添付ファイルに含めないでください。

「網羅的プロンプト」復元パターン

長時間の調査では、後日再実行できるようにスタンドアロンのプロンプト + ファイルセットを作成してください:

• 6〜30文のプロジェクト概要 + 目標。
• 再現手順 + 正確なエラー + 試したこと。
• 必要なすべてのコンテキストファイルを添付（エントリポイント、設定、主要モジュール、ドキュメント）。

Oracleの実行はワンショットです。モデルは以前の実行を覚えていません。「コンテキストの復元」とは、同じプロンプト + --file … セットで再実行する（またはまだ実行中の保存セッションに再アタッチする）ことを意味します。