Дизайн Session Recap

Краткое резюме (1–2 предложения) «на чём я остановился», которое появляется, когда пользователь возвращается к неактивной сессии: по запросу (/recap) или после того, как терминал потерял фокус (blur) более чем на 5 минут.

Обзор

Когда пользователь через несколько дней вызывает /resume для старой сессии, прокрутка страниц истории, чтобы вспомнить, чем он занимался и что должно быть дальше, становится серьёзным препятствием. Простая перезагрузка сообщений не решает эту проблему UX.

Цель — заранее показывать краткое резюме из 1–2 предложений при возвращении пользователя:

• Задача высокого уровня (чем занимается) → следующий шаг (что делать дальше).
• Визуально отличается от обычных ответов ассистента, чтобы его никогда не спутали с новым выводом модели.
• Best-effort: ошибки должны обрабатываться молча и никогда не прерывать основной поток.

Триггеры

Оба пути сводятся к одной функции — generateSessionRecap() — для гарантии идентичного поведения. Автоматический триггер управляется настройкой general.showSessionRecap (по умолчанию: выключено — явное включение, чтобы фоновые вызовы LLM никогда не добавлялись в счёт пользователя незаметно); ручная команда игнорирует эту настройку.

Архитектура

┌────────────────────────────────────────────────────────────────────────┐
│                          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 заменяет системный промпт основного агента для этого единственного вызова, поэтому модель ведёт себя исключительно как генератор резюме, а не как ассистент по написанию кода.

Обратите внимание, что GeminiClient.generateContent() внутренне пропускает промпт через getCustomSystemPrompt(), которая добавляет память пользователя (QWEN.md / управляемая автопамять) в качестве суффикса. Итоговый системный промпт выглядит как промпт резюме + память пользователя — это полезный контекст проекта для резюме, а не утечка.

Пункты ниже соответствуют 1:1 RECAP_SYSTEM_PROMPT:

• Менее 40 слов, 1–2 простых предложения (без markdown / списков / заголовков). Для китайского языка лимит составляет примерно 80 символов.
• Первое предложение: задача высокого уровня. Затем: конкретный следующий шаг.
• Явный запрет: перечисление выполненных действий, цитирование вызовов инструментов, отчёты о статусе.
• Соответствовать основному языку разговора (английский или китайский).
• Обернуть вывод в <recap>...</recap>; ничего за пределами тегов.

Структурированный вывод + извлечение

Модели предписывается оборачивать ответ в <recap>...</recap>:

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

Причина: некоторые модели (семейство GLM, модели рассуждений) пишут абзац «размышлений» перед финальным ответом. Возврат сырого текста приведёт к утечке этих рассуждений в UI.

Функция extractRecap() имеет три уровня fallback:

1. Оба тега присутствуют: берётся содержимое между <recap>...</recap> (предпочтительно).
2. Только открывающий тег (например, maxOutputTokens обрезал закрывающий): берётся всё после открывающего тега.
3. Тег полностью отсутствует: возвращается пустая строка → сервис возвращает null → UI ничего не рендерит.

Третий уровень работает по принципу «лучше пропустить, чем показать неверное» — вывод преамбулы рассуждений модели хуже, чем полное отсутствие резюме.

Параметры вызова

Фильтрация истории

geminiClient.getChat().getHistory() возвращает Content[], который включает:

• текстовые сообщения user / model
• части functionCall от model
• части functionResponse от user (могут содержать полное содержимое файлов)
• части thought от model (part.thought / part.thoughtSignature, скрытые рассуждения модели)

filterToDialog() сохраняет только части user / model с непустым текстом, которые не являются рассуждениями. Две причины:

• Вызовы инструментов / ответы: один functionResponse может занимать 10K+ токенов. 30 таких сообщений погрузят LLM для резюме в нерелевантные детали, что приведёт к трате токенов и смещению фокуса резюме на технический шум вроде «вызван инструмент X для чтения файла Y».
• Части рассуждений: содержат внутренние рассуждения модели. Их включение создаёт риск восприятия скрытой цепочки рассуждений как диалога и вывода их в тексте резюме.

После удаления пустых сообщений takeRecentDialog обрезает историю до последних 30 сообщений и отказывается начинать срез с незавершённого ответа модели/инструмента.

Параллелизм и граничные случаи

Машина состояний хука автоматического триггера

useAwaySummary хранит три рефа:

Зависимости useEffect: [enabled, config, isFocused, isIdle, addItem, thresholdMs].

Колбэк .then повторно проверяет isIdleRef.current: если пользователь начал новый ход, пока LLM выполнялся, запоздалое резюме отбрасывается, чтобы не вставлять его в середине хода.

Блок .finally очищает recapPendingRef и очищает inFlightRef только если inFlightRef.current === controller (чтобы не перезаписать более новый контроллер).

Второй useEffect прерывает активный контроллер при размонтировании.

Ограничения /recap

CommandContext.ui.isIdleRef предоставляет текущее состояние потока (по аналогии с существующим паттерном btwAbortControllerRef). В интерактивном режиме recapCommand отклоняет выполнение, если !isIdleRef.current или pendingItem !== null. Одного pendingItem недостаточно, так как обычный ответ модели выполняется при streamingState === Responding и pendingItem === null.

Конфигурация и выбор модели

Пользовательские параметры

Fallback модели

config.getFastModel() ?? config.getModel():

• У пользователя задан fastModel и он валиден для текущего типа авторизации → используется fastModel.
• В противном случае → fallback на основную модель сессии (работает, но дороже и медленнее).

Наблюдаемость (Observability)

createDebugLogger('SESSION_RECAP') выводит:

• пойманные исключения из пути резюме (debugLogger.warn).

Все ошибки полностью прозрачны для пользователя — резюме является вспомогательной функцией и никогда не выбрасывает исключения в UI. Разработчики могут выполнить grep по тегу [SESSION_RECAP] в файле отладочного лога: по умолчанию записывается в ~/.qwen/debug/<sessionId>.txt (latest.txt — симлинк на текущую сессию); отключается через QWEN_DEBUG_LOG_FILE=0.

Вне области применения (Out of Scope)