cc-viewer 1.2.1 → 1.2.3

package/concepts/uk/Tool-TaskList.md

@@ -0,0 +1,36 @@
+# TaskList
+
+## Визначення
+
+Перелічує всі завдання у списку завдань, переглядає загальний прогрес та доступну роботу.
+
+## Параметри
+
+Без параметрів.
+
+## Вміст відповіді
+
+Зведена інформація по кожному завданню:
+- `id` — Ідентифікатор завдання
+- `subject` — Короткий опис
+- `status` — Статус: `pending`, `in_progress` або `completed`
+- `owner` — Відповідальний (agent ID), порожнє означає не призначено
+- `blockedBy` — Список ID незавершених завдань, що блокують це завдання
+
+## Сценарії використання
+
+**Підходить для:**
+- Перегляд доступних завдань (статус pending, без owner, не заблоковані)
+- Перевірка загального прогресу проєкту
+- Пошук заблокованих завдань
+- Пошук наступного завдання після завершення поточного
+
+## Примітки
+
+- Надавайте перевагу обробці завдань у порядку ID (найменший ID першим), оскільки ранні завдання зазвичай надають контекст для наступних
+- Завдання з `blockedBy` не можна брати до зняття залежності
+- Використовуйте TaskGet для отримання повних деталей конкретного завдання
+
+## Значення в cc-viewer
+
+TaskList — це внутрішня операція управління завданнями, яка не генерує окремого API-запиту.

package/concepts/uk/Tool-TaskOutput.md

@@ -0,0 +1,34 @@
+# TaskOutput
+
+## Визначення
+
+Отримує вивід фонового завдання, що виконується або завершилося. Підходить для фонових shell, асинхронних агентів та віддалених сесій.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `task_id` | string | Так | ID завдання |
+| `block` | boolean | Так | Чи блокувати очікування завершення завдання, за замовчуванням `true` |
+| `timeout` | number | Так | Максимальний час очікування (мілісекунди), за замовчуванням 30000, максимум 600000 |
+
+## Сценарії використання
+
+**Підходить для:**
+- Перевірка прогресу фонового агента, запущеного через Task (`run_in_background: true`)
+- Отримання результату виконання фонової команди Bash
+- Очікування завершення асинхронного завдання та отримання виводу
+
+**Не підходить для:**
+- Завдання переднього плану — вони повертають результат безпосередньо, цей інструмент не потрібен
+
+## Примітки
+
+- `block: true` блокує до завершення завдання або тайм-ауту
+- `block: false` використовується для неблокуючої перевірки поточного стану
+- ID завдання можна знайти через команду `/tasks`
+- Підходить для всіх типів завдань: фоновий shell, асинхронний агент, віддалена сесія
+
+## Значення в cc-viewer
+
+Виклик TaskOutput сам по собі не генерує API-запиту; це внутрішня операція управління завданнями Claude Code, яка не з'являється в журналі запитів.

package/concepts/uk/Tool-TaskStop.md

@@ -0,0 +1,27 @@
+# TaskStop
+
+## Визначення
+
+Зупиняє фонове завдання, що виконується.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `task_id` | string | Ні | ID фонового завдання для зупинки |
+| `shell_id` | string | Ні | Застаріло, використовуйте `task_id` |
+
+## Сценарії використання
+
+**Підходить для:**
+- Завершення довготривалих завдань, які більше не потрібні
+- Скасування помилково запущених фонових завдань
+
+## Примітки
+
+- Повертає статус успіху або невдачі
+- Параметр `shell_id` застарів, слід використовувати `task_id`
+
+## Значення в cc-viewer
+
+Виклик TaskStop сам по собі не генерує API-запиту; це внутрішня операція управління завданнями Claude Code.

package/concepts/uk/Tool-TaskUpdate.md

@@ -0,0 +1,49 @@
+# TaskUpdate
+
+## Визначення
+
+Оновлює статус, вміст або залежності завдання у списку завдань.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `taskId` | string | Так | ID завдання для оновлення |
+| `status` | enum | Ні | Новий статус: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | Ні | Новий заголовок |
+| `description` | string | Ні | Новий опис |
+| `activeForm` | string | Ні | Текст у теперішньому тривалому часі, що відображається під час виконання |
+| `owner` | string | Ні | Новий відповідальний за завдання (ім'я агента) |
+| `metadata` | object | Ні | Метадані для об'єднання (встановлення null видаляє ключ) |
+| `addBlocks` | string[] | Ні | Список ID завдань, заблокованих цим завданням |
+| `addBlockedBy` | string[] | Ні | Список ID попередніх завдань, що блокують це завдання |
+
+## Перехід статусів
+
+```
+pending → in_progress → completed
+```
+
+`deleted` можна перейти з будь-якого статусу, завдання видаляється назавжди.
+
+## Сценарії використання
+
+**Підходить для:**
+- Позначення завдання як `in_progress` при початку роботи
+- Позначення завдання як `completed` після завершення роботи
+- Встановлення залежностей між завданнями
+- Оновлення вмісту завдання при зміні вимог
+
+**Важливі правила:**
+- Позначайте як `completed` лише коли завдання повністю виконано
+- При виникненні помилок або блокування залишайте `in_progress`
+- Не позначайте як `completed` при невдалих тестах, неповній реалізації або невирішених помилках
+
+## Примітки
+
+- Перед оновленням отримайте актуальний стан завдання через TaskGet, щоб уникнути застарілих даних
+- Після завершення завдання використовуйте TaskList для пошуку наступного доступного завдання
+
+## Значення в cc-viewer
+
+TaskUpdate — це внутрішня операція управління завданнями, яка не генерує окремого API-запиту.

package/concepts/uk/Tool-WebFetch.md

@@ -0,0 +1,36 @@
+# WebFetch
+
+## Визначення
+
+Отримує вміст веб-сторінки за вказаним URL, конвертує HTML у markdown та обробляє вміст за допомогою AI-моделі відповідно до prompt.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `url` | string (URI) | Так | Повний URL для отримання |
+| `prompt` | string | Так | Описує, яку інформацію потрібно витягти зі сторінки |
+
+## Сценарії використання
+
+**Підходить для:**
+- Отримання вмісту публічних веб-сторінок
+- Перегляд онлайн-документації
+- Витягування конкретної інформації з веб-сторінки
+
+**Не підходить для:**
+- URL, що потребують автентифікації (Google Docs, Confluence, Jira, GitHub тощо) — спочатку шукайте спеціалізований MCP-інструмент
+- URL GitHub — пріоритетно використовуйте `gh` CLI
+
+## Примітки
+
+- URL повинен бути повним дійсним URL
+- HTTP автоматично оновлюється до HTTPS
+- При занадто великому вмісті результати можуть бути зведені
+- Містить 15-хвилинний кеш з автоочищенням
+- Коли URL перенаправляє на інший хост, інструмент повертає URL перенаправлення, і потрібно зробити новий запит з новим URL
+- Якщо доступний MCP-інструмент web fetch, надавайте йому перевагу
+
+## Значення в cc-viewer
+
+Виклики WebFetch відображаються в журналі запитів як пара content block `tool_use` / `tool_result`. `tool_result` містить зведення вмісту веб-сторінки, обробленого AI.

package/concepts/uk/Tool-WebSearch.md

@@ -0,0 +1,32 @@
+# WebSearch
+
+## Визначення
+
+Виконує запит до пошукової системи та повертає результати пошуку для отримання актуальної інформації.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `query` | string | Так | Пошуковий запит (мінімум 2 символи) |
+| `allowed_domains` | string[] | Ні | Включати результати лише з цих доменів |
+| `blocked_domains` | string[] | Ні | Виключити результати з цих доменів |
+
+## Сценарії використання
+
+**Підходить для:**
+- Отримання актуальної інформації, що виходить за межі дати відсічення знань моделі
+- Пошук поточних подій та найновіших даних
+- Пошук найактуальнішої технічної документації
+
+## Примітки
+
+- Результати пошуку повертаються у форматі markdown-гіперпосилань
+- Після використання обов'язково додайте розділ "Sources:" в кінці відповіді зі списком відповідних URL
+- Підтримує фільтрацію за доменами (включення/виключення)
+- У пошуковому запиті слід використовувати поточний рік
+- Доступний лише в США
+
+## Значення в cc-viewer
+
+Виклики WebSearch відображаються в журналі запитів як пара content block `tool_use` / `tool_result`. `tool_result` містить список результатів пошуку.

package/concepts/uk/Tool-Write.md

@@ -0,0 +1,32 @@
+# Write
+
+## Визначення
+
+Записує вміст у локальну файлову систему. Якщо файл вже існує, перезаписує його.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `file_path` | string | Так | Абсолютний шлях до файлу (повинен бути абсолютним) |
+| `content` | string | Так | Вміст для запису |
+
+## Сценарії використання
+
+**Підходить для:**
+- Створення нових файлів
+- Коли потрібно повністю переписати вміст файлу
+
+**Не підходить для:**
+- Зміна локальної частини файлу — слід використовувати Edit
+- Не слід проактивно створювати файли документації (*.md) або README, якщо користувач явно не просить
+
+## Примітки
+
+- Якщо цільовий файл вже існує, його потрібно спочатку прочитати через Read, інакше буде помилка
+- Перезаписує весь вміст існуючого файлу
+- Надавайте перевагу Edit для редагування існуючих файлів; Write використовується лише для створення нових файлів або повного перезапису
+
+## Значення в cc-viewer
+
+Виклики Write відображаються в журналі запитів як `tool_use` content block, де `input.content` містить повний записаний вміст.

package/concepts/uk/Tool-executeCode.md

@@ -0,0 +1,33 @@
+# executeCode (mcp__ide__executeCode)
+
+## Визначення
+
+Виконує Python-код у Jupyter kernel поточного файлу notebook.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `code` | string | Так | Python-код для виконання |
+
+## Сценарії використання
+
+**Підходить для:**
+- Виконання коду в середовищі Jupyter notebook
+- Тестування фрагментів коду
+- Аналіз даних та обчислення
+
+**Не підходить для:**
+- Виконання коду поза середовищем Jupyter — слід використовувати Bash
+- Зміна файлів — слід використовувати Edit або Write
+
+## Примітки
+
+- Це MCP (Model Context Protocol) інструмент, наданий інтеграцією з IDE
+- Код виконується в поточному Jupyter kernel, стан зберігається між викликами
+- Якщо користувач явно не просить, уникайте оголошення змінних або зміни стану kernel
+- Після перезапуску kernel стан втрачається
+
+## Значення в cc-viewer
+
+executeCode — це MCP-інструмент, який з'являється в масиві `tools` журналу запитів під назвою `mcp__ide__executeCode`. Його виклики та повернення відповідають стандартному шаблону `tool_use` / `tool_result`. Додавання або видалення MCP-інструментів призводить до зміни масиву tools, що може спричинити перебудову кешу.

package/concepts/uk/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Визначення
+
+Отримує діагностичну інформацію мови з VS Code, включаючи синтаксичні помилки, помилки типів, попередження lint тощо.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `uri` | string | Ні | URI файлу. Якщо не вказано, отримує діагностику для всіх файлів |
+
+## Сценарії використання
+
+**Підходить для:**
+- Перевірка синтаксичних, типових, lint та інших семантичних проблем коду
+- Перевірка після редагування коду, чи не з'явилися нові помилки
+- Заміна команд Bash для перевірки якості коду
+
+**Не підходить для:**
+- Запуск тестів — слід використовувати Bash
+- Перевірка помилок виконання — слід використовувати Bash для виконання коду
+
+## Примітки
+
+- Це MCP (Model Context Protocol) інструмент, наданий інтеграцією з IDE
+- Доступний лише в середовищі VS Code / IDE
+- Надавайте перевагу цьому інструменту замість команд Bash для перевірки проблем коду
+
+## Значення в cc-viewer
+
+getDiagnostics — це MCP-інструмент, який з'являється в масиві `tools` журналу запитів під назвою `mcp__ide__getDiagnostics`. Його виклики та повернення відповідають стандартному шаблону `tool_use` / `tool_result`. Додавання або видалення MCP-інструментів призводить до зміни масиву tools, що може спричинити перебудову кешу.

package/concepts/uk/Tools.md

@@ -0,0 +1,73 @@
+# Перелік інструментів Claude Code
+
+Claude Code надає моделі набір вбудованих інструментів через механізм tool_use API Anthropic. Масив `tools` кожного запиту MainAgent містить повні визначення JSON Schema цих інструментів, і модель викликає їх через `tool_use` content block у відповіді.
+
+Нижче наведено категоризований індекс усіх інструментів.
+
+## Система агентів
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Task](Tool-Task.md) | Запуск підагента (SubAgent) для обробки складних багатокрокових завдань |
+| [TaskOutput](Tool-TaskOutput.md) | Отримання виводу фонового завдання |
+| [TaskStop](Tool-TaskStop.md) | Зупинка запущеного фонового завдання |
+| [TaskCreate](Tool-TaskCreate.md) | Створення запису структурованого списку завдань |
+| [TaskGet](Tool-TaskGet.md) | Отримання деталей завдання |
+| [TaskUpdate](Tool-TaskUpdate.md) | Оновлення статусу завдання, залежностей тощо |
+| [TaskList](Tool-TaskList.md) | Перелік усіх завдань |
+
+## Операції з файлами
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Read](Tool-Read.md) | Читання вмісту файлу (підтримка тексту, зображень, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Редагування файлу через точну заміну рядків |
+| [Write](Tool-Write.md) | Запис або перезапис файлу |
+| [NotebookEdit](Tool-NotebookEdit.md) | Редагування комірки Jupyter notebook |
+
+## Пошук
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Glob](Tool-Glob.md) | Пошук файлів за шаблоном імені файлу |
+| [Grep](Tool-Grep.md) | Пошук вмісту файлів на основі ripgrep |
+
+## Термінал
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Bash](Tool-Bash.md) | Виконання shell-команд |
+
+## Web
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [WebFetch](Tool-WebFetch.md) | Отримання вмісту веб-сторінки та обробка за допомогою AI |
+| [WebSearch](Tool-WebSearch.md) | Запит до пошукової системи |
+
+## Планування та взаємодія
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Вхід у режим планування, проєктування плану реалізації |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Вихід з режиму планування та подання плану на затвердження користувачем |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Запитання користувачу для уточнення або прийняття рішення |
+
+## Розширення
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [Skill](Tool-Skill.md) | Виконання навички (slash command) |
+
+## Інтеграція з IDE
+
+| Інструмент | Призначення |
+|------------|-------------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Отримання діагностичної інформації мови VS Code |
+| [executeCode](Tool-executeCode.md) | Виконання коду в Jupyter kernel |
+
+## Значення в cc-viewer
+
+Виклики інструментів є одними з найважливіших спостережуваних даних у журналах запитів Claude Code. Масив `tools` кожного запиту MainAgent визначає набір інструментів, доступних моделі, а `tool_use` / `tool_result` content block у відповіді фіксують фактичні виклики інструментів та їх результати. cc-viewer аналізує ці дані для відновлення повного ланцюга викликів інструментів у Chat Mode.
+
+Зміни у визначеннях інструментів (наприклад, додавання/видалення інструментів через підключення/відключення MCP server) спричиняють перебудову кешу, детальніше див. [CacheRebuild](CacheRebuild.md).

package/concepts/uk/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Забруднення контексту в Translate API
+
+## Передумови
+
+CC-Viewer містить вбудовану функцію перекладу (`POST /api/translate`), що працює на основі Anthropic Messages API. У ранній реалізації запити на переклад повторно використовували кешовані облікові дані автентифікації із сесії Claude Code — включаючи заголовки `x-api-key` та `authorization`. Це спричинило непомітну, але серйозну проблему: результати перекладу часто повертали нерелевантний вміст.
+
+## Кореневе причина
+
+### Фундаментальна різниця між двома методами автентифікації
+
+Anthropic API підтримує два методи автентифікації:
+
+| Метод | Заголовок | Типове джерело | Характеристики |
+|-------|-----------|----------------|----------------|
+| API-ключ | `x-api-key: sk-ant-...` | Змінна середовища / Console | Без стану, кожен запит незалежний |
+| OAuth-токен | `authorization: Bearer sessionToken` | Вхід за підпискою Claude Code | Прив'язаний до сесії, сервер підтримує асоціацію контексту |
+
+Ключова різниця: **API-ключі не зберігають стан** — кожен запит повністю незалежний; тоді як **OAuth-токени сесії зберігають стан** — сервер Anthropic асоціює запити з однаковим токеном з одним і тим самим контекстом сесії.
+
+### Ланцюг забруднення
+
+Коли Claude Code використовує OAuth-вхід за підпискою, потік автентифікації виглядає так:
+
+```
+Основна розмова Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                        ↑
+Запит перекладу CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Оскільки запити на переклад повторно використовували той самий токен сесії, сервер Anthropic може асоціювати запити на переклад із контекстом основної розмови Claude Code. Це призводить до:
+
+1. **Результати перекладу під впливом контексту основної розмови**: Системний промпт запиту на переклад — «ви перекладач», але серверний контекст все ще містить історію розмов Claude Code, що потенційно може впливати на модель
+2. **Основна розмова порушується запитами на переклад**: Вміст запитів на переклад (фрагменти тексту UI) може бути впроваджений у контекст основної розмови, спричиняючи відхилення у відповідях Claude Code
+3. **Непередбачувана поведінка**: Оскільки забруднення контексту — це поведінка на стороні сервера, клієнт не може її виявити або контролювати
+
+## Отримані уроки
+
+- **OAuth-токени сесії — це не «просто ще один API-ключ»** — вони несуть серверний стан, і їх повторне використання означає спільне використання контексту
+- **Внутрішні виклики сервісів повинні використовувати незалежну автентифікацію без стану**, щоб уникнути асоціації з користувацькими сесіями
+
+## Посилання
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)

package/concepts/zh/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（请求体增量对比）
+
+## 背景
+
+Claude Code 的 MainAgent 采用全量上下文发送机制——每次请求都会携带完整的对话历史、system prompt、工具定义等内容。这意味着随着对话推进，请求体会越来越庞大，直接查看原始 Body 很难快速定位"这一轮到底新增了什么"。
+
+Body Diff JSON 正是为了解决这个问题：它自动对比前后两个 MainAgent 请求的 body，提炼出增量部分，让你一眼看清本次请求实际新增的内容。
+
+## 工作原理
+
+1. **识别连续的 MainAgent 请求**：当前请求必须是 MainAgent 类型，且存在上一个 MainAgent 请求
+2. **逐字段对比**：遍历请求体的所有顶层字段，跳过 `_` 前缀的内部属性
+3. **智能差异提取**：
+   - 新增的字段：直接展示
+   - 删除的字段：不显示（通常不影响理解）
+   - 变更的字段：展示当前值
+   - `messages` 数组特殊处理：只展示新增的消息（因为正常对话是追加模式，前缀消息不变）
+4. **请求体缩小检测**：如果当前请求体比上一个更小，说明发生了上下文截断或会话重置，此时会显示提示信息而非 diff
+
+## 典型场景
+
+在一轮正常对话中，Body Diff JSON 通常只包含：
+- `messages`：新增的 1~2 条消息（用户的输入 + 上一轮助手的回复）
+
+如果你看到 diff 中出现了 `system`、`tools`、`model` 等字段的变更，说明本轮请求发生了配置变化，这往往也是缓存重建的原因。
+
+## 使用方式
+
+- Body Diff JSON 显示在 MainAgent 请求的详情面板中
+- 点击标题可展开/收起
+- 支持 JSON 和 Text 两种查看模式，以及一键复制
+- 在左上角 **CC-Viewer → 全局设置** 中，可以设置"默认展开 Body Diff JSON"

package/concepts/zh/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild（缓存重建）
+
+## 背景
+
+Anthropic 的 prompt caching 机制会将请求中的 system → tools → messages（到 cache breakpoint）按顺序拼接为缓存键。当缓存键与上一次请求完全一致时，API 返回 `cache_read_input_tokens`（缓存命中）；当缓存键发生变化，API 会重新创建缓存，返回大量 `cache_creation_input_tokens`，即缓存重建。
+
+缓存重建意味着额外的 token 计费（cache creation 的价格高于 cache read），因此识别重建原因对费用优化有直接价值。
+
+## 缓存重建原因分类
+
+cc-viewer 通过对比前后两个 MainAgent 请求的 body，精确判断缓存重建的原因：
+
+| reason | 含义 | 判断方式 |
+|--------|------|----------|
+| `ttl` | 缓存过期 | 距上一个 MainAgent 请求超过 5 分钟 |
+| `system_change` | system prompt 变更 | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | 工具定义变更 | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | 模型切换 | `prev.model !== curr.model` |
+| `msg_truncated` | 消息栈被截断 | 当前请求的 messages 数量少于上一个请求，通常因上下文窗口溢出触发截断 |
+| `msg_modified` | 历史消息修改 | 前缀消息内容不一致（正常追加时前缀应完全相同） |
+| `key_change` | 未知键变更 | 以上条件均不匹配时的 fallback |
+
+## 判断优先级
+
+1. 首先检查时间间隔——超过 5 分钟直接判定为 `ttl`，不再做 body 对比
+2. 然后依次检查 model、system、tools、messages
+3. 一个请求可能同时命中多个原因（如模型切换 + system prompt 变更），此时 `reasons` 数组包含所有匹配项，tooltip 换行显示
+
+## 常见场景
+
+- **`ttl`**：用户暂停操作超过 5 分钟后继续，缓存自然过期
+- **`system_change`**：Claude Code 更新了 system prompt（如加载新的 CLAUDE.md、project instructions 变化）
+- **`tools_change`**：MCP server 连接/断开导致可用工具列表变化
+- **`model_change`**：用户通过 `/model` 命令切换模型
+- **`msg_truncated`**：对话过长触发上下文窗口管理，Claude Code 截断早期消息
+- **`msg_modified`**：Claude Code 对历史消息做了编辑（如 `/compact` 压缩摘要替换原始消息）
+
+## 在 cc-viewer 中的展示
+
+请求列表中，缓存重建的请求会在 cache 行显示红色圆点指示器。鼠标悬停显示 tooltip，包含具体的重建原因描述（支持 18 种语言）。

package/concepts/zh/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## 定义
+
+MainAgent 是 Claude Code 在非 agent team 状态下的主干请求链路。每一次用户与 Claude Code 的交互，都会产生一系列 API 请求，其中 MainAgent 请求构成了核心对话链路——它们携带完整的 system prompt、工具定义和消息历史。
+
+## 识别方式
+
+在 cc-viewer 中，MainAgent 通过 `req.mainAgent === true` 标识，由 `interceptor.js` 在请求捕获时自动标记。
+
+判定条件（满足全部）：
+- 请求体包含 `system` 字段（system prompt）
+- 请求体包含 `tools` 数组（工具定义）
+- system prompt 中包含 "Claude Code" 特征文本
+
+## 与 SubAgent 的区别
+
+| 特征 | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | 完整的 Claude Code 主 prompt | 精简的任务专用 prompt |
+| tools 数组 | 包含全部可用工具 | 通常只包含任务所需的少量工具 |
+| 消息历史 | 累积完整对话上下文 | 仅包含子任务相关消息 |
+| 缓存行为 | 有 prompt caching（5 分钟 TTL） | 通常无缓存或缓存较小 |
+
+## 在 cc-viewer 中的意义
+
+- **缓存追踪**：MainAgent 请求的 prompt caching 状态直接影响费用。通过监控 `cache_creation_input_tokens` 与 `cache_read_input_tokens` 的比例，可以判断缓存命中率
+- **缓存丢失分析**：当 MainAgent 请求出现大量 cache creation（而非 cache read），说明缓存丢失并被重建，cc-viewer 会通过红色圆点指示器标记这些请求
+- **主链路分析**：MainAgent 请求序列反映了用户与 Claude Code 的完整交互过程，是分析会话行为的核心数据
+- **会话重建**：cc-viewer 通过 MainAgent 请求的消息历史重建对话视图（Chat Mode）

package/concepts/zh/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## 定义
+
+在执行过程中向用户提问，用于获取澄清、验证假设或请求决策。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `questions` | array | 是 | 问题列表（1-4 个问题） |
+| `answers` | object | 否 | 用户收集的答案 |
+| `annotations` | object | 否 | 每个问题的注释（如预览选择的备注） |
+| `metadata` | object | 否 | 跟踪和分析用的元数据 |
+
+每个 `question` 对象：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `question` | string | 是 | 完整的问题文本，应以问号结尾 |
+| `header` | string | 是 | 短标签（最多 12 字符），显示为标签芯片 |
+| `options` | array | 是 | 2-4 个选项 |
+| `multiSelect` | boolean | 是 | 是否允许多选 |
+
+每个 `option` 对象：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `label` | string | 是 | 选项显示文本（1-5 个词） |
+| `description` | string | 是 | 选项说明 |
+| `markdown` | string | 否 | 预览内容（用于 ASCII 布局、代码片段等的可视化对比） |
+
+## 使用场景
+
+**适合使用：**
+- 收集用户偏好或需求
+- 澄清模糊的指令
+- 在实施过程中获取决策
+- 向用户提供方向选择
+
+**不适合使用：**
+- 问"方案可以吗？"——应使用 ExitPlanMode
+
+## 注意事项
+
+- 用户始终可以选择 "Other" 提供自定义输入
+- 推荐选项放在第一位，并在 label 末尾加 "(Recommended)"
+- `markdown` 预览仅支持单选问题
+- 有 `markdown` 的选项会切换为左右并排布局
+- 在规划模式中，用于在确定方案前澄清需求
+
+## 在 cc-viewer 中的意义
+
+AskUserQuestion 调用在请求日志中表现为 `tool_use` content block，包含问题和选项定义。用户的回答会出现在后续请求的消息历史中。