# Pi 用プランモード > 🌐 他の言語： [English](../README.md) | [Español](README.es.md) | [Français](README.fr.md) | [Português](README.pt.md) | [简体中文](README.zh-CN.md)。 Pi-agent v1 or later に対話型プランニングを追加する TypeScript 拡張です。プロジェクトの調査、決定事項の明確化、有用な改善の提案、そして実装前のプラン提示を行います。パッケージ：`pi-plan-claude-codex`、バージョン `0.1.2`。 ワークフローは [Codex planning](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) と [Claude Code のプランレビューと承認](https://code.claude.com/docs/en/permission-modes#review-and-approve-a-plan) を参考にしています。実装は Pi-agent v1 or later の公開拡張 API を対象としています。検証済みの基準バージョンは Pi **1.0.4** です。すべての過去および将来のバージョンとの互換性を保証するものではありません。 ## インストールと使い方 パッケージを一度インストールします： ```sh pi install npm:pi-plan-claude-codex ``` その後、任意のプロジェクトから通常どおり Pi を起動します： ```sh pi ``` 会話の中でモードを有効化します： ```text /plan ``` TUI では、固定ショートカット **Ctrl+Alt+P**（macOS では **Ctrl+Option+P**）でも、引数なしの `/plan` と同じようにモードを切り替えられます。エディターの下書きと現在の提案を保持し、モデルにリクエストを送信せず、**プランの承認や実行は一切行いません**。無効化すると以前のツールが復元されます。ターンの実行中は警告を表示するだけで、作業を中断したり、後で切り替える予約をしたりしません。 macOS では、必要に応じてターミナルが Option を Alt/Meta として送信するよう設定してください。Pi のネイティブダイアログはキーボードのフォーカスを保持します。このショートカットはグローバルではありません。ターミナル、OS、または別のショートカットにキー操作が捕捉される場合は、代わりに `/plan` を使ってください。 あとは通常のメッセージで目標を説明してください。例：「カタログ検索を追加したい。仕組みを調査し、決定前に改善案を提案してほしい。」 インストールにより、パッケージは Pi の個人設定に登録されます。次回以降の起動時に自動で読み込まれ、`/plan` が利用可能になります。そのコマンドまたはキーボードショートカットでモードを有効化します。起動時にパスやフラグは不要です。`/plan ` というショートカットもサポートされています。 ローカルのチェックアウトをインストールする場合（npm 初回公開前を含む）は、以下を実行します： ```sh pi install /absolute/path/to/pi-plan-claude-codex ``` その後は同じ `pi` → `/plan` の流れで使用します。 Pi-agent v1 or later と Node.js `>=22.19.0` が必要です。Pi は TypeScript を事前コンパイルなしで直接読み込み、`peerDependencies` で宣言された依存関係を提供します。 ## ワークフロー 1. **調査する（Investigate）。** プロジェクトの指示を読み、実装を探索します。まずエージェント自身で発見できる事実を探します。 2. **議論する（Discuss）。** 目標・スコープ・制約・成功条件を明確化します。UX・シンプルさ・動作に関する有用な改善を提案し、トレードオフを説明して、含めるかどうかを確認します。 3. **決定を確定する（Resolve decisions）。** インターフェース、手法、エラー、互換性、検証を確定します。インタビューはタスクに応じて適応します。通常は 1 問につき 1 決定、最大 3 件の関連質問、最小ラウンド数や埋め合わせの質問はありません。 4. **レビューする（Review）。** 受け入れられた決定、検証可能な手順、テスト、前提を含む完全な Markdown プランを提示します。ユーザーが次の動作を選択します。 質問では、トレードオフと推奨を含む選択肢や、自由回答が可能です。キャンセルすると決定は未回答のままとなり、ターンは停止します。モデルは以前の決定を保持し、承認なくスコープを拡大しないよう指示されています。インタビューの品質とプランの完全性は、選択したモデルにも依存します。 プランが提示されると、以下のアクションが利用できます： - **計画を続ける（Continue planning）：** 保留中の提案と読み取り専用制限を維持します。 - **プランを洗練する（Refine the plan）：** フィードバックを求め、新しいリビジョンを生成します。 - **この会話で実行する（Execute in this conversation）：** 以前のツールを復元し、承認されたプランで実装を開始します。 - **クリーンなセッションで実行する（Execute in a clean session）：** インタビュー履歴なしのセッションを作成し、完全なプラン、その来歴、モデル、推論レベル、以前のツールを渡します。 レビューをキャンセルしてもモードは有効なままです。承認はその提案とそのセッションにのみ適用されます。新しい情報は以前の提案を無効化します。無効化されたダイアログへの遅延応答で実行を開始することはできません。クリーンなセッションの作成がキャンセルされた場合は、計画に戻ります。 ## コマンド | コマンド | 結果 | | --- | --- | | `/plan` | プランモードの切り替え。 | | Ctrl+Alt+P（macOS: Ctrl+Option+P） | TUI で `/plan` と同じ切り替えを行う。 | | `/plan ` | モードを有効化し、そのリクエストの計画を開始する。 | | `/plan on` | モデルへのリクエスト送信なしで有効化する。 | | `/plan off` | モードを無効化し、以前のツールを復元する。 | | `/plan status` | モード、リビジョン、状態、Markdown ファイルを表示する。 | | `/plan review` | 提案とセレクターを再表示する。失敗したエクスポートを再試行する。 | | `/plan execute` | 同じレビューセレクターを開く。アクションの選択が必須。 | | `/plan refine [comments]` | コメント付きで提案を洗練する。または入力プロンプトを開く。 | | `--plan` | ブランチに保存済み状態がない場合、プランモードで開始する。 | モード変更はエージェントがアイドル状態のときに行われます。「プランを実装して」と通常メッセージで書いても、エージェントは計画モードのままです。コマンドまたは明示的な実行選択で遷移してください。`/plan off` はモード制限を終了しますが、実装を自動開始しません。 ## 許可される探索 有効中は `read`、`grep`、`find`、`ls` と 3 つの組み込みツールが有効になります： | ツール | 目的 | | --- | --- | | `plan_ask` | 選択肢または自由回答で質問する。 | | `plan_submit` | 提案を保存して提示する。実行の承認ではない。 | | `plan_inspect` | 固定の Git クエリ：`status`、`diff`、`log`、`show`。 | 事前に有効だった外部ツールは、`readOnlyHint: true` を宣言し、`destructiveHint: true` を宣言していない場合、引き続き利用できることがあります。不明または変更を伴うツールは、ネストされた呼び出しを含めブロックされます。`bash`、`powershell`、`codemode`、`write`、`edit`、ユーザーの `!`/`!!` コマンドも同様です。 `plan_inspect` は直接引数、シェルなし、固定操作、検証済み参照、外部 diff と textconv を無効化するオプション、10 秒タイムアウト、制限付き出力を使用します。テスト、ビルド、スクリプト、インストールは承認済み実行まで待機しなければなりません。これらの操作に依存する証拠がプランに必要な場合、その制限を認めなければなりません。 これは OS のサンドボックスではなく、Pi 内部のポリシーです。外部ツールのアノテーションはその作者による宣言です。他の拡張は Pi の権限でコードを実行します。モード自身の書き込みはセッションスナップショットと提案エクスポートに限定されます。 ## 状態とファイル 状態と最新の提案は、**現在のセッションブランチ**上のカスタムエントリとして保存されます。再開、再読み込み、セッション切り替え、ツリー移動時に復元されます。新しいブランチは祖先に存在するスナップショットのみを継承します。 各提案は、以前のリビジョンを上書きせず、プロジェクト内に個別の `.pi/plans/.md` ファイルを作成します。セッションが信頼できる情報源です。エクスポートされた Markdown を編集しても提案は変更されず、自動承認もされません。変更の取り込みには `/plan refine` を使用してください。`.pi/plans/` はこのリポジトリでは Git の対象外です。 エクスポートに失敗した場合、提案はセッションに残り、実行セレクターは開かず、`/plan review` で再試行できます。`.pi` および `plans` ディレクトリはシンボリックリンクにできません。ファイルはサポート対象システム上で `0600` 権限で排他的に作成されます。`--no-session` ではプロセス中の状態のみ保持され、Markdown ファイルはディスクに残ります。 ## TUI、RPC、print、JSON TUI はネイティブダイアログとモードインジケーターを使用します。`regular` と `fullscreen`、Unicode、狭い端末へのリサイズがテスト済みです。 RPC はネイティブの `extension_ui_request` リクエスト（`select` と `input`）、テキストウィジェット、通知を使用します。クライアントは提案を表示し、`extension_ui_response` でダイアログに応答するか、キャンセルしなければなりません。タイムアウトから応答や承認を推測することはありません。実装は計画ターン終了後に開始します。 Print/text と JSON は、ダイアログや自動実行なしで制限を維持します。保留中の質問は最終応答に含まれます。プランが完成するとエクスポートされ、モデルは最終応答にその Markdown を含めなければなりません。JSON/RPC では stdout はプロトコル専用に保たれます。 ```sh pi --plan -p 'Plan a catalog search' pi --plan --mode json -p 'Plan a catalog search' pi --mode rpc ``` ## 開発と検証 公開せずにチェックアウトをテストするには、`pi install /absolute/path/to/pi-plan-claude-codex` でパスをインストールします。その後は npm パッケージと同様に `pi` と `/plan` を使用します。1 回の開発呼び出しでのみ読み込むには、`pi -e /absolute/path/to/pi-plan-claude-codex` を使用します。 ```sh npm run check npm test npm pack --dry-run --ignore-scripts ``` チェッカーは Pi インストールの依存関係を再利用します。配布テストでは、この拡張をパッケージ化し、ローカル npm レジストリから tarball を提供し、一時プロファイルで `pi install npm:pi-plan-claude-codex` を実行します。その後、引数なしで `pi` を起動し、実際の端末で `/plan` を有効化します。ユーザーの個人設定は変更せず、サードパーティ依存もダウンロードしません。 `check` には PATH 上の `tsc` が必要です。`PI_PLAN_HOST_ROOT`（Pi パッケージのルート）と `PI_PLAN_TSC`（チェッカー実行ファイル）を指定できます。テストは Node のネイティブ型 stripping を使用し、Node `24.18.0` で検証済みです。Unix 端末テストには Python 3 が必要で、Windows ではスキップされます。 スイートは、インストールと自動読み込み、ツールポリシー、ブランチスナップショット、エクスポート、エラーとキャンセル、両セッションでの承認、モデル／推論の保持、ダイアログ無効化、洗練、リロード、履歴分離、ネスト呼び出し、非 UI モード、実端末を検査します。インストール済み Pi ランタイムと決定的プロバイダーを使用し、モデル呼び出しや実際の認証情報は使いません。Fixture は配布パッケージに含まれません。 これらのテストは仕組みとプロトコル動作を検証します。実モデルとの対話評価でも、特定 RPC クライアントの検証でもありません。