セッション Recap の設計

ユーザーがアイドル状態のセッションに戻った際、オンデマンド（/recap）またはターミナルが 5 分以上フォーカスを失った（blurred）後に、作業の続きを把握するための簡潔な要約（1〜2 文）を表示する機能。

概要

ユーザーが数日ぶりに古いセッションを /resume した際、何をやっていたか、次は何をすべきかを思い出すために長い履歴をスクロールするのは大きな摩擦ポイントとなる。単にメッセージを再読み込みするだけでは、この UX 上の課題は解決できない。

ユーザーが戻ってきた際に、簡潔な 1〜2 文の要約を積極的に表示することを目的とする：

• 高レベルのタスク（何をしているか）→ 次のステップ（次に何をすべきか）。
• アシスタントの実際の返信とは視覚的に区別し、新しいモデル出力と誤認されないようにする。
• ベストエフォート型：失敗時は静かに処理し、メインのフローを絶対に中断させない。

トリガー

両方のパスは単一の関数 generateSessionRecap() に集約され、同一の動作を保証する。自動トリガーは general.showSessionRecap 設定によって制御される（デフォルト: 無効 — 明示的なオプトインが必要。これにより、待機中の LLM 呼び出しがユーザーの請求に静かに追加されることを防ぐ）。手動コマンドはこの設定を無視する。

Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                          AppContainer.tsx                              │
│   isFocused = useFocus()                                               │
│   isIdle = streamingState === Idle                                     │
│       │                                                                │
│       ├─→ useAwaySummary({enabled, config, isFocused, isIdle,          │
│       │       │             addItem})                                  │
│       │       └─→ 5 min blur timer + idle/dedupe gates                 │
│       │              │                                                 │
│       │              ↓                                                 │
│       └─→ recapCommand (slash) ─→ generateSessionRecap(config, signal) │
│                                          │                             │
│                                          ↓                             │
│                              ┌─────────────────────────┐               │
│                              │ packages/core/services/ │               │
│                              │   sessionRecap.ts       │               │
│                              └─────────────────────────┘               │
│                                          │                             │
│                                          ↓                             │
│                              GeminiClient.generateContent              │
│                              (fastModel + tools:[])                    │
│                                                                        │
│   addItem({type: 'away_recap', text}) ─→ HistoryItemDisplay            │
│       └─ AwayRecapMessage rendered inline like any other history       │
│         item (※ + bold "recap: " + italic content, all dim);           │
│         scrolls naturally with the conversation. Mirrors Claude        │
│         Code's away_summary system message.                            │
└────────────────────────────────────────────────────────────────────────┘

ファイル

プロンプト設計

システムプロンプト

generationConfig.systemInstruction がこの 1 回の呼び出しでメインエージェントのシステムプロンプトを上書きするため、モデルはコーディングアシスタントではなく要約ジェネレーターとしてのみ動作する。

なお、GeminiClient.generateContent() は内部的にプロンプトを getCustomSystemPrompt() に通し、ユーザーのメモリ（QWEN.md / 管理対象自動メモリ）をサフィックスとして追加する。最終的なシステムプロンプトは 要約用プロンプト + ユーザーメモリ となり、要約にとって有用なプロジェクトコンテキストとなる（情報漏洩ではない）。

以下の箇条書きは RECAP_SYSTEM_PROMPT と 1:1 で対応している：

• 40 語以内、1〜2 文の平文（マークダウン / リスト / 見出しなし）。中国語の場合は、合計約 80 文字を上限とする。
• 1 文目：高レベルのタスク。2 文目：具体的な次のステップ。
• 明示的に禁止：実施内容の列挙、ツール呼び出しの羅列、ステータス報告。
• 会話の主要言語（英語または中国語）に合わせる。
• 出力を <recap>...</recap> で囲む。タグの外に何も出力しない。

構造化出力と抽出

モデルには、回答を <recap>...</recap> で囲むよう指示する：

<recap>Refactoring loopDetectionService.ts to address long-session OOM. Next step is to implement option B.</recap>

理由：一部のモデル（GLM ファミリー、推論モデル）は最終回答の前に「思考」段落を出力する。生のテキストをそのまま返すと、その推論過程が UI に漏れてしまう。

extractRecap() には 3 つのフォールバック階層がある：

1. 両方のタグが存在する場合：<recap>...</recap> の間のテキストを取得（推奨）。
2. 開始タグのみ存在する場合（例：maxOutputTokens により終了タグが切り捨てられた）：開始タグ以降のすべてを取得。
3. タグが完全に欠落している場合：空文字列を返す → サービスが null を返す → UI は何もレンダリングしない。

第 3 階層は「間違ったものを表示するより、表示しない方がまし」という方針に基づいている。モデルの推論前置きを表面化させることは、要約を一切表示しないよりも悪影響が大きい。

呼び出しパラメータ

履歴フィルタリング

geminiClient.getChat().getHistory() は以下の要素を含む Content[] を返す：

• user / model のテキストメッセージ
• model の functionCall パート
• user の functionResponse パート（ファイル全体の内容を含む場合あり）
• model の思考パート（part.thought / part.thoughtSignature、モデルの隠れた推論）

filterToDialog() は、テキストが空でなく、かつ思考パートではない user / model パートのみを保持する。理由は 2 つある：

• ツール呼び出し / 応答：1 つの functionResponse が 10K トークンを超える場合がある。このようなメッセージが 30 件あると、要約用 LLM が無関係な詳細に埋もれ、トークンの無駄遣いになるだけでなく、「Y ファイルを読み取るために X ツールを呼び出した」といった実装ノイズに要約が偏ってしまう。
• 思考パート：モデルの内部推論を保持する。これを含めると、隠れた思考連鎖を対話として扱い、要約テキストに表面化させてしまうリスクがある。

空のメッセージを除外した後、takeRecentDialog は直近 30 メッセージにスライスし、未完了のモデル/ツール応答が境界に来る位置からスライスを開始することを拒否する。

同時実行とエッジケース

自動トリガーフックのステートマシン

useAwaySummary は 3 つの ref を保持する：

useEffect の依存配列：[enabled, config, isFocused, isIdle, addItem, thresholdMs]。

.then コールバック内で isIdleRef.current を再チェックする：LLM 実行中にユーザーが新しいターンを開始していた場合、遅れて到着した要約は破棄され、ターン途中への挿入を防ぐ。

.finally は recapPendingRef をクリアし、inFlightRef.current === controller の場合のみ inFlightRef をクリアする（これにより、新しいコントローラーを上書きしないようにする）。

2 つ目の useEffect は、アンマウント時に実行中のコントローラーを中止する。

/recap のゲート処理

CommandContext.ui.isIdleRef は現在のストリーム状態を公開する（既存の btwAbortControllerRef パターンに準拠）。インタラクティブモードでは、!isIdleRef.current または pendingItem !== null の場合、recapCommand は実行を拒否する。pendingItem だけでは不十分である。通常のモデル返信は streamingState === Responding かつ pendingItem が null の状態で実行されるためである。

設定とモデル選択

ユーザー向け設定項目

モデルのフォールバック

config.getFastModel() ?? config.getModel() の動作：

• ユーザーが fastModel を設定しており、現在の認証タイプで有効な場合 → fastModel を使用。
• それ以外の場合 → メインセッションモデルにフォールバック（動作はするが、コストが高く速度も遅い）。

観測性（Observability）

createDebugLogger('SESSION_RECAP') は以下を出力する：

• 要約パスでキャッチされた例外（debugLogger.warn）。

すべての失敗はユーザーに対して完全に透過的である。要約は補助機能であり、UI に例外をスローすることはない。開発者はデバッグログファイル内の [SESSION_RECAP] タグを grep できる：デフォルトでは ~/.qwen/debug/<sessionId>.txt に書き込まれる（latest.txt は現在のセッションへのシンボリックリンク）。QWEN_DEBUG_LOG_FILE=0 で無効化可能。

スコープ外