nicobailon/pi-interview-tool

解決する問題

エージェントがユーザーに明確化を求める場合、インラインで質問することが多く、これは扱いにくい場合があります。このツールはそれを専用のインタラクティブなフォームに変えます。エージェントがリッチなコンテキストで構造化された質問を提示し、ユーザー自身のペースで回答を収集し、構造化された結果を受け取ることができます。中断を優雅に処理し、進行状況を自動保存し、放棄またはタイムアウトしたセッションをユーザーが回復できるようにします。

仕組み

エージェントは interview() 関数を介してツールを呼び出し、質問を定義する JSON ファイルを渡します。ツールはローカルサーバーを起動し、macOS ではネイティブの Glimpse ウィンドウ（他の場所ではブラウザタブ）でフォームを開きます。ユーザーはフォームに記入し、localStorage に自動保存され、アクティビティがあるとリセットされるカウントダウンタイマーがあります。ユーザーが送信すると、応答はエージェントに返されます。キャンセルまたはタイムアウトした場合、エージェントは null を受け取ります。このツールは複数の同時インタビューもサポートしています。最初のものだけが自動的にウィンドウを開き、他はフォーカスを奪わないようにキューに入れられます。セッションがリモート（ssh/mosh）の場合、ツールはローカルウィンドウを開く代わりに、フォーム URL とアクセスヒントを出力します。タイムアウトまたは放棄されたインタビューは、後で再試行できるようにリカバリディレクトリに質問を保存します。

対象者

pi-agent を使用する開発者とユーザーで、ライブユーザーから構造化されたインタラクティブなフィードバックを収集する必要がある人。例えば、プロジェクト要件の明確化、好みの収集、エージェント駆動のワークフロー中のオプションのレビューなどです。エージェントがコードスニペット、図、テーブルなどのリッチなコンテキストを持つ一連の質問をする必要がある場合に特に役立ちます。

ハイライト

• 単一選択、複数選択、テキスト、画像アップロード、情報パネルをサポート—全体でキーボードナビゲーション対応
• 質問にリッチメディアを直接埋め込む：画像、Chart.js チャート、Mermaid 図、テーブル、生の HTML
• 決定を導くための設定可能な確信度（強い/弱い）と視覚的重み（重要/軽微）を持つレコメンデーション
• localStorage への自動保存と警告オーバーレイ付きのセッションタイムアウト；進行状況が誤って失われることはありません
• セッションリカバリ：放棄またはタイムアウトしたインタビューはリカバリフォルダに保存され、後で再試行できます
• マルチエージェントサポート：同時インタビューはウィンドウを奪い合う代わりにキューに入り、キューされたセッション用のトーストスイッチャーがあります
• LLM 搭載の「さらに生成」と「オプションをレビュー」ボタンで、新しい選択肢を作成したり、明確にするために質問を書き換えたりできます
• 「オプションについて質問」は、プロンプトチップと自由形式のフォローアップ質問を備えたインラインアシスタントパネルを開きます
• カスタマイズ可能なテーマ（ダーク/ライト/オート）とユーザー定義の CSS オーバーライド、トグルホットキー
• ランチャー選択：Glimpse、ブラウザタブ、または Orca 管理のブラウザタブでフォームを開く

仕組み

フローの簡単な概要は次のとおりです（詳細は README にあります）：

1. エージェントは質問 JSON ファイルを指定して interview() を呼び出します。
2. ローカルサーバーが起動し、選択したランチャー（Glimpse、ブラウザ、または Orca）でフォームが開きます。
3. ユーザーは自分のペースで回答します。すべての変更は自動保存され、タイムアウトをリセットします。
4. 送信時に、応答はエージェントに送り返されます。キャンセルまたはタイムアウト時には、エージェントは null を受け取ります（または、ツールは非同期配信のためにインタビュー ID を返すことができます）。
5. セッションがリモート（ssh/mosh）の場合、ツールはローカルウィンドウを開く代わりに、フォーム URL とアクセスヒントを出力します。

ライフサイクル

• 送信（⌘+Enter）：応答がエージェントに返されます。
• タイムアウト：カウントダウンバッジはアクティビティがあるとリセットされます。期限が切れると、警告オーバーレイが表示され、ユーザーは続行または閉じることができます。
• Escape × 2：クイックキャンセル。

セッションリカバリ

インタビューがタイムアウトまたは放棄された場合（タブが閉じられた、接続が失われた）、質問は ~/.pi/interview-recovery/ に 2026-01-02_093000_myproject_main_65bec3f4.json のようなファイル名で保存されます。後でそのファイルを interview() に渡すことで再試行できます。7 日以上経過したファイルは自動的にクリーンアップされます。

マルチエージェント動作

複数のエージェントが同時にインタビューを実行する場合、最初のものだけが自動的にウィンドウを開きます。後続のインタビューはキューに入れられ、ツール出力に URL として表示されます。アクティブなインタビューを送信すると、自動的に次のキューされたインタビューにリダイレクトされます。右上のトーストにドロップダウンがあり、キューされたセッションを開くことができます。セッションステータスバーには、識別用にプロジェクトパス、git ブランチ、セッション ID が表示されます。

タイムアウト動作

カウントダウン（隅に表示）は、タイピング、クリック、マウスの動きなど、アクティビティがあるとリセットされます。期限が切れると、ユーザーに続行の機会を与えるオーバーレイが表示されます。localStorage の自動保存により、進行状況が失われることはありません。

対象者

インタラクティブなユーザー入力を必要とする pi-agent ワークフローを構築または使用する開発者。エージェントがプロジェクトの詳細、好み、設計上の決定、その他のパラメータについて明確化する必要がある状況に最適です。また、構造化されたフォームが自由形式のチャットよりも信頼性が高い場合にも適しています。フィードバックを一貫して収集し、中断から回復する必要があるチームにも役立ちます。

ハイライト

• リッチな質問タイプ：単一選択、複数選択、テキスト入力、画像アップロード/カメラキャプチャ、情報パネル。
• 埋め込みメディア：質問内の画像、Chart.js チャート、Mermaid 図、テーブル、HTML。
• 確信度と重み付きレコメンデーション：オプションの提案の強さと視覚的な目立ち方を制御します。
• 自動保存とタイムアウトリカバリ：応答は localStorage に保存されます。放棄/タイムアウトしたインタビューは回復可能です。
• マルチエージェントサポート：同時インタビューはフォーカスを奪う代わりにキューに入り、トーストスイッチャーがあります。
• LLM 搭載ヘルパー：設定可能なモデルで、より多くのオプションを生成したり、質問をレビュー/書き換えたりできます。
• オプションについて質問：プロンプトチップと自由形式のフォローアップ質問を備えたインラインアシスタントパネル。
• テーマ：ダーク/ライト/オートテーマに加え、カスタム CSS オーバーライドとトグルホットキー。
• ランチャーオプション：フォームを表示するために Glimpse、ブラウザ、または Orca を選択します。
• キーボードナビゲーション：ナビゲーション、選択、送信のショートカットを含む完全なキーボードサポート。