ask-ui

Ask UI

Ask UI をプレゼンテーションおよび永続化アダプターとして使用します。質問の生成と推論は、呼び出し元のワークフローで行います。

UI を使用するかどうかを判断する

現在のラウンドに、ユーザーが今すぐ回答できる独立した質問が 2 つ以上ある場合は、UI を使用します。依存関係のある質問は、後のラウンドに回します。質問が 1 つだけの場合は、会話内で直接尋ねます。

1 ラウンドに質問が 2 つを超える grill-me、grill-with-docs、ブレインストーミング、その他の確認・質問収集ワークフローでは、必ず UI を使用します。

ローカルサーバーまたはブラウザーを起動できない場合は、呼び出し元のワークフローで通常使用するテキスト形式に切り替えます。

質問をして、回答を待つ

1. この SKILL.md が格納されているディレクトリを ASK_UI_SKILL_DIR として解決します。

2. JSON を作成する前に、references/schema.md を読みます。

3. QuestionSet JSON ファイルを作成します。新しいタスクでは sessionId を省略し、フォローアップのラウンドではアクティブな sessionId を再利用し、basedOnRound を設定します。

4. フォアグラウンドコマンドを実行し、終了するまでツール呼び出しをアクティブなままにします。

   node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
   

5. このコマンドは準備状況の詳細とローカル URL を stderr に出力し、フォームを開いて待機します。Agent のターンを終了したり、ユーザーに「已提交」と返信するよう求めたりしないでください。

6. ユーザーが送信したら、stdout に出力された単一の JSON 結果を解析し、元のワークフローをすぐに続行します。

7. さらに独立した質問が必要な場合は、同じ sessionId を指定し、返されたラウンドを basedOnRound に設定して、再度 ask を呼び出します。追加の質問がなくなったら、セッションを完了します。

最初の直接ラウンドではブラウザーが開きます。同じ Session のフォローアップラウンドでは、永続サーバー、固定 URL、既存のブラウザーページが再利用されます。ページが新しい Round を検出し、自動的に選択します。ユーザーがそのページを閉じた場合は、--open を一度指定して再度開きます。

ブラウザーを別途開く場合に限り、--no-open を使用します。固定のローカルホストポートが必要な場合に限り、--port <number> を使用します。

手動でのフォールバックと復旧

フォアグラウンドのツール呼び出しをアクティブなままにできない場合、一時サーバーにローカルブラウザーからアクセスできない場合、または中断した直接ラウンドを復旧する場合は、デタッチされたワークフローを使用します。

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>

返された JSON を解析します。会話内に URL と視認できるマーカーを含めます。

ask-ui-session: <sessionId>

フォームを送信したら「已提交」とだけ返信するよう、ユーザーに伝えます。create コマンドはデタッチされたローカルホストサーバーを起動または再利用し、すぐに戻ります。

ユーザーが「已提交」、「提交好了」、または「答完了」と言ったら：

1. この会話内の最新の ask-ui-session マーカーから sessionId を取得します。

2. 次を実行します。

   node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs resume --session <sessionId>
   

3. 結果が submitted の場合は、その質問と回答を使用して元のワークフローを続行します。

4. さらに独立した質問が必要な場合は、sessionId を再利用し、処理済みのラウンドを basedOnRound に設定して、フォアグラウンドの ask コマンドに戻る方法を優先します。直接待機を引き続き利用できない場合に限り、再度 create を使用します。

5. 追加の質問がない場合は、次を実行します。

   node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>
   

会話内のマーカーを利用できない場合は、--session を指定せずに resume を実行します。候補が複数返された場合は、現在のトピック、ワークスペース、タイトル、送信時刻から最適な候補を推定します。本当に判別が難しい場合に限り、ユーザーに尋ねます。

「已提交」というメッセージが繰り返されても、重複するラウンドを作成してはいけません。新しいラウンドを作成できるのは、submitted のラウンドを正常に読み取った後だけです。

セッションの継続性を維持する

• 1 つのタスクを 1 つの Session とします。
• 質問の各セットを 1 つの Round とします。
• 同じタスクのすべてのラウンドで sessionId を再利用します。
• 送信済みの質問や回答を上書きしてはいけません。
• 修正と追加の確認は、新しい Round に含めます。
• 新しいタスク、完了済みのタスク、または明示的な再開の場合に限り、新しい Session を開始します。

オプションのアクティブな起動

Ask UI は、Claude Code と Codex App Server 向けのオプションの起動メタデータをサポートしています。これは必須ではなく、機能強化として扱ってください。

• 自動起動は、ユーザーの同意がある場合にのみ有効にしてください。
• Claude Code には、記録済みのセッション ID が必要です。
• Codex には、ホストから提供されるスレッド ID が必要です。Codex のスレッド ID を推測してはいけません。
• アダプターが失敗した場合は、回答を保持し、手動の「已提交」ワークフローに戻してください。
• 直接の ask モードでは、待機中のプロセスがすでに応答経路となっているため、起動アダプターは呼び出されません。

便利なコマンド

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs status --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs serve
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/self-test.mjs