cx-viewer 1.0.0

package/concepts/pt-BR/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — A Máquina de Desejos Definitiva
+
+## O que é UltraPlan
+
+UltraPlan é a **implementação localizada** do cc-viewer para o comando nativo `/ultraplan` do Claude Code. Ele permite que você use todas as capacidades do `/ultraplan` em seu ambiente local **sem precisar iniciar o serviço remoto oficial do Claude**, guiando o Claude Code para realizar tarefas complexas de planejamento e implementação usando **colaboração multiagente**.
+
+Comparado ao modo Plan regular ou Agent Team, o UltraPlan pode:
+- Avaliar automaticamente a complexidade da tarefa e selecionar a estratégia de planejamento ideal
+- Implantar múltiplos agentes paralelos para explorar a base de código a partir de diferentes dimensões
+- Incorporar pesquisa externa (webSearch) para melhores práticas do setor
+- Montar automaticamente uma Equipe de Code Review após a execução do plano para revisão de código
+- Formar um ciclo fechado completo **Planejar → Executar → Revisar → Corrigir**
+
+---
+
+## Notas importantes
+
+### 1. UltraPlan não é onipotente
+O UltraPlan é uma máquina de desejos mais poderosa, mas isso não significa que todo desejo pode ser realizado. Ele é mais poderoso que o Plan e o Agent Team, mas não pode diretamente "fazer você ganhar dinheiro". Considere uma granularidade de tarefas razoável — divida grandes objetivos em tarefas de tamanho médio executáveis em vez de tentar realizar tudo de uma vez.
+
+### 2. Atualmente mais eficaz para projetos de programação
+Os modelos e fluxos de trabalho do UltraPlan são profundamente otimizados para projetos de programação. Outros cenários (documentação, análise de dados, etc.) podem ser tentados, mas você pode querer aguardar adaptações em versões futuras.
+
+### 3. Tempo de execução e requisitos de janela de contexto
+- Uma execução bem-sucedida do UltraPlan normalmente leva **30 minutos ou mais**
+- Requer que o MainAgent tenha uma janela de contexto grande (modelo Opus com contexto 1M recomendado)
+- Se você tem apenas um modelo de 200K, **certifique-se de executar `/clear` no contexto antes de rodar**
+- O `/compact` do Claude Code tem desempenho ruim quando a janela de contexto é insuficiente — evite ficar sem espaço
+- Manter espaço de contexto suficiente é um pré-requisito crítico para a execução bem-sucedida do UltraPlan
+
+Se você tiver dúvidas ou sugestões sobre o UltraPlan localizado, fique à vontade para abrir [Issues no GitHub](https://github.com/anthropics/claude-code/issues) para discutir e colaborar.
+
+---
+
+## Como funciona
+
+O UltraPlan oferece dois modos de operação:
+
+### Modo Automático
+Analisa automaticamente a complexidade da tarefa (pontuação 4-12) e direciona para diferentes estratégias:
+
+| Rota | Pontuação | Estratégia |
+|------|-----------|------------|
+| Rota A | 4-6 | Planejamento leve com exploração direta de código |
+| Rota B | 7-9 | Planejamento com diagramas estruturais (Mermaid / ASCII) |
+| Rota C | 10-12 | Exploração multiagente + ciclo fechado de revisão |
+
+### Modo Forçado
+Ativa diretamente o fluxo de trabalho multiagente completo da Rota C:
+1. Implantar até 5 agentes paralelos para explorar a base de código simultaneamente (arquitetura, identificação de arquivos, avaliação de riscos, etc.)
+2. Opcionalmente implantar um agente de pesquisa para investigar soluções do setor via webSearch
+3. Sintetizar todas as descobertas dos agentes em um plano de implementação detalhado
+4. Implantar um agente de revisão para examinar o plano de múltiplas perspectivas
+5. Executar o plano após aprovação
+6. Montar automaticamente uma Equipe de Code Review para validar a qualidade do código após a implementação

package/concepts/ru/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (инкрементное сравнение тела запроса)
+
+## Контекст
+
+MainAgent в Claude Code использует механизм отправки полного контекста — каждый запрос содержит полную историю диалога, system prompt, определения инструментов и т.д. Это означает, что по мере продвижения диалога тело запроса становится всё больше, и при просмотре сырого Body сложно быстро определить, «что именно было добавлено в этом раунде».
+
+Body Diff JSON решает именно эту проблему: он автоматически сравнивает тела двух последовательных запросов MainAgent, извлекает инкрементную часть и позволяет сразу увидеть, что фактически было добавлено в текущем запросе.
+
+## Принцип работы
+
+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/ru/BodyFields.md

@@ -0,0 +1,42 @@
+# Описание полей Request Body
+
+Описание полей верхнего уровня тела запроса Claude API `/v1/messages`.
+
+## Список полей
+
+| Поле | Тип | Описание |
+|------|------|------|
+| **model** | string | Название используемой модели, например `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | История сообщений диалога. Каждое сообщение содержит `role` (user/assistant) и `content` (массив блоков: текст, изображения, tool_use, tool_result и др.) |
+| **system** | array | System prompt. Содержит основные инструкции Codex, описание использования инструментов, информацию об окружении, содержимое CLAUDE.md и т.д. Блоки с `cache_control` кэшируются через prompt caching |
+| **tools** | array | Список определений доступных инструментов. Каждый инструмент содержит `name`, `description` и `input_schema` (JSON Schema). MainAgent обычно имеет более 20 инструментов, SubAgent — лишь несколько |
+| **metadata** | object | Метаданные запроса, обычно содержащие `user_id` для идентификации пользователя |
+| **max_tokens** | number | Максимальное количество токенов в одном ответе модели, например `16000`, `64000` |
+| **thinking** | object | Конфигурация расширенного мышления. `type: "enabled"` включает режим мышления, `budget_tokens` управляет верхним пределом токенов мышления |
+| **context_management** | object | Конфигурация управления контекстом. `truncation: "auto"` позволяет Codex автоматически усекать слишком длинную историю сообщений |
+| **output_config** | object | Конфигурация вывода, например настройка `format` |
+| **stream** | boolean | Включить ли потоковый ответ. Codex всегда использует `true` |
+
+## Структура messages
+
+`content` каждого сообщения — это массив блоков, распространённые типы:
+
+- **text**: обычное текстовое содержимое
+- **tool_use**: вызов инструмента моделью (содержит `name`, `input`)
+- **tool_result**: результат выполнения инструмента (содержит `tool_use_id`, `content`)
+- **image**: изображение (base64 или URL)
+- **thinking**: процесс мышления модели (режим расширенного мышления)
+
+## Структура system
+
+Массив system prompt обычно содержит:
+
+1. **Основные инструкции агента** ("You are Codex...")
+2. **Правила использования инструментов**
+3. **Содержимое CLAUDE.md** (инструкции на уровне проекта)
+4. **Подсказки навыков** (skills reminder)
+5. **Информация об окружении** (ОС, shell, статус git и т.д.) — фактически Codex сильно зависит от git. Если в проекте есть git-репозиторий, Codex демонстрирует лучшее понимание проекта, включая возможность извлекать удалённые изменения и историю коммитов для вспомогательного анализа
+
+Блоки, помеченные `cache_control: { type: "ephemeral" }`, кэшируются Anthropic API на 5 минут; при попадании в кэш тарификация идёт по `cache_read_input_tokens` (значительно дешевле, чем `input_tokens`).
+
+> **Примечание**: для таких специальных клиентов, как Codex, серверная сторона Anthropic фактически не полностью полагается на атрибут `cache_control` в запросе для определения поведения кэширования. Сервер автоматически применяет политику кэширования к определённым полям (таким как system prompt, определения инструментов), даже если запрос не содержит явной метки `cache_control`. Поэтому, если вы не видите этот атрибут в теле запроса, не стоит удивляться — сервер уже выполнил кэширование за кулисами, просто не раскрывая эту информацию клиенту. Это своего рода негласное соглашение между Codex и Anthropic API.

package/concepts/ru/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (пересборка кеша)
+
+## Контекст
+
+Механизм prompt caching Anthropic объединяет system → tools → messages (до точки разрыва кеша) в ключ кеша. Когда ключ кеша совпадает с предыдущим запросом, API возвращает `cache_read_input_tokens` (попадание в кеш); когда ключ кеша изменяется, API создаёт кеш заново, возвращая большое количество `cache_creation_input_tokens`, то есть происходит пересборка кеша.
+
+Пересборка кеша означает дополнительные расходы на токены (цена cache creation выше, чем cache read), поэтому определение причин пересборки имеет прямую ценность для оптимизации затрат.
+
+## Классификация причин пересборки кеша
+
+cc-viewer сравнивает тела двух последовательных запросов MainAgent для точного определения причины пересборки кеша:
+
+| 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` | Обрезка стека сообщений | В текущем запросе меньше сообщений, чем в предыдущем, обычно из-за обрезки при переполнении контекстного окна |
+| `msg_modified` | Изменение истории сообщений | Содержимое префиксных сообщений не совпадает (при нормальном добавлении префикс должен быть идентичным) |
+| `key_change` | Неизвестное изменение ключа | Fallback, когда ни одно из вышеуказанных условий не совпало |
+
+## Приоритет определения
+
+1. Сначала проверяется временной интервал — более 5 минут означает `ttl`, без сравнения тел
+2. Затем последовательно проверяются: model, system, tools, messages
+3. Один запрос может одновременно соответствовать нескольким причинам (например, смена модели + изменение system prompt), тогда массив `reasons` содержит все совпавшие элементы, а tooltip отображает их построчно
+
+## Типичные сценарии
+
+- **`ttl`**: пользователь приостановил работу более чем на 5 минут, кеш естественно истёк
+- **`system_change`**: Claude Code обновил system prompt (например, загрузка нового CLAUDE.md, изменение инструкций проекта)
+- **`tools_change`**: подключение/отключение MCP-сервера привело к изменению списка доступных инструментов
+- **`model_change`**: пользователь переключил модель командой `/model`
+- **`msg_truncated`**: слишком длинный диалог вызвал управление контекстным окном, Claude Code обрезал ранние сообщения
+- **`msg_modified`**: Claude Code отредактировал исторические сообщения (например, `/compact` заменил оригинальные сообщения сжатым резюме)

package/concepts/ru/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CC-Viewer 全局配置参考
+
+## 一、全局设置面板（UI）
+
+通过左上角菜单 → "全局设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 过滤无关请求 | 开关 | 开 | 隐藏心跳、count_tokens、子代理等非主代理请求 |
+| 默认展开 Body Diff JSON | 开关 | 关 | 请求详情面板中的 Body Diff 区域默认展开 |
+| 日志目录设置 | 文本输入 | `~/.claude/cc-viewer` | 项目日志的读写根目录，支持 `~/` 展开。修改后回车或失焦保存，立即生效 |
+
+## 二、显示设置面板（UI）
+
+通过左上角菜单 → "显示设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
+| 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
+
+## 三、偏好设置文件
+
+所有 UI 设置持久化到 `<日志目录>/preferences.json`，通过 `/api/preferences` 接口读写。
+
+```json
+{
+  "lang": "zh",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.claude/cc-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `lang` | string | 界面语言（zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk） |
+| `filterIrrelevant` | boolean | 过滤无关请求 |
+| `expandDiff` | boolean | 默认展开 Body Diff JSON |
+| `collapseToolResults` | boolean | 折叠工具结果 |
+| `expandThinking` | boolean | 展开思考过程 |
+| `showFullToolContent` | boolean | 完整展示内容 |
+| `logDir` | string | 日志目录路径 |
+| `resumeAutoChoice` | null / "continue" / "new" | 自动恢复会话选择 |
+| `disabledPlugins` | string[] | 已禁用的插件文件名列表 |
+| `presetShortcuts` | array | Agent Team 快捷指令预设 |
+
+## 四、环境变量
+
+### CC-Viewer 专有
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | 日志存储根目录。特殊值：`tmp`/`temp` 使用系统临时目录 |
+| `CCV_CLI_MODE` | 未设置 | `=1` 启用 CLI 模式（PTY 终端） |
+| `CCV_SDK_MODE` | 未设置 | `=1` 启用 Agent SDK 模式（无终端） |
+| `CCV_WORKSPACE_MODE` | 未设置 | `=1` 启用工作空间选择模式 |
+| `CCV_PROJECT_DIR` | `process.cwd()` | 项目工作目录，用于文件操作和 Git 命令 |
+| `CCV_PROXY_PORT` | 未设置 | 本地 MITM 代理端口 |
+| `CCV_BYPASS_PERMISSIONS` | 未设置 | `=1` 跳过工具权限审批（配合 `--dangerously-skip-permissions`） |
+| `CCV_DISABLE_DELTA` | 未设置 | `=1` 禁用增量日志存储，每次写入完整消息 |
+| `CCV_DEBUG` | 未设置 | `=1` 启用 HTTP 代理调试日志 |
+| `CCV_DEBUG_PLUGINS` | 未设置 | `=1` 启用插件加载调试日志 |
+
+### 内部 IPC
+
+| 变量名 | 说明 |
+|--------|------|
+| `CCVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
+| `CCV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+
+### 外部变量（读取）
+
+| 变量名 | 说明 |
+|--------|------|
+| `ANTHROPIC_BASE_URL` | 自定义 Anthropic API 地址 |
+| `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
+| `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
+
+## 五、CLI 命令参数
+
+```
+ccv [选项] [claude 参数...]
+```
+
+### CC-Viewer 专有选项
+
+| 参数 | 说明 |
+|------|------|
+| `-logger` | 安装/修复 Claude Code hooks |
+| `--uninstall` / `-uninstall` | 卸载所有 CC-Viewer 集成 |
+| `--help` / `-h` / `help` | 显示帮助信息 |
+| `--version` / `-v` | 显示版本号 |
+| `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
+| `--d` | `--dangerously-skip-permissions` 简写 |
+| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
+| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+
+### Claude 透传参数（常用）
+
+| 参数 | 说明 |
+|------|------|
+| `-c` / `--continue` | 继续上一次会话 |
+| `-r` / `--resume` | 恢复指定会话 |
+| `-p` / `--print` | 非交互式输出 |
+| `--model` | 指定模型 |
+| `--permission-mode` | 权限模式 |
+| `--system-prompt` | 自定义系统提示词 |
+| `--max-budget-usd` | 最大预算 |
+
+## 六、Hook 配置
+
+CC-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+
+### 1. AskUserQuestion 桥接
+- **匹配器**: `"AskUserQuestion"`
+- **命令**: `node <安装目录>/lib/ask-bridge.js`
+- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+
+### 2. 权限审批桥接
+- **匹配器**: `""` (空 = 匹配所有工具)
+- **命令**: `node <安装目录>/lib/perm-bridge.js`
+- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+
+## 七、Shell 集成
+
+CC-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+
+```bash
+# >>> CC-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CC-Viewer Auto-Inject <<<
+```
+
+所有 `claude` 命令自动通过 CC-Viewer 代理，实现日志捕获和 Web UI 功能。
+
+卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+
+## 八、代理配置（Proxy Profile）
+
+存储在 `<日志目录>/profile.json`，通过 UI 的"代理切换"面板管理。
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "自定义", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `active` | 当前激活的配置 ID（`"max"` = 直连，无代理） |
+| `id` | 唯一标识 |
+| `name` | 显示名称 |
+| `baseURL` | 代理 API 地址（替换请求 origin） |
+| `apiKey` | 代理 API 密钥（替换认证头） |
+| `models` | 可用模型列表 |
+| `activeModel` | 当前选中的模型 |
+
+## 九、插件系统
+
+插件目录：`<日志目录>/plugins/`
+
+### 支持的 Hook 类型
+
+| Hook | 类型 | 说明 |
+|------|------|------|
+| `httpsOptions` | 瀑布 | 提供 HTTPS 证书（返回 `{ cert, key }` 或 `{ pfx }`） |
+| `localUrl` | 瀑布 | 修改本地访问 URL |
+| `serverStarted` | 并行 | 服务器启动通知 |
+| `serverStopping` | 并行 | 服务器停止通知 |
+| `onNewEntry` | 并行 | 新日志条目写入通知 |
+
+插件启用/禁用通过 `preferences.json` 的 `disabledPlugins` 数组管理。
+
+## 十、目录结构
+
+```
+~/.claude/cc-viewer/               # 日志根目录
+├── preferences.json               # 用户偏好设置
+├── workspaces.json                # 工作空间注册表
+├── profile.json                   # 代理配置
+├── plugins/                       # 插件目录
+│   └── my-plugin.js
+├── <项目名>/                       # 每个项目的日志目录
+│   ├── <项目名>_20260404_123456.jsonl  # JSONL 日志文件
+│   ├── <项目名>.json              # 统计数据（后台生成）
+│   └── images/                    # 上传图片的持久副本
+└── ...
+
+/tmp/cc-viewer-uploads/            # 临时上传文件目录
+```
+
+## 十一、服务器配置
+
+| 配置 | 值 | 说明 |
+|------|-----|------|
+| 端口范围 | 7008-7099 | 自动扫描可用端口 |
+| 绑定地址 | 0.0.0.0 | 所有网络接口 |
+| 访问令牌 | 随机 16 字节 hex | 局域网访问需要 `?token=xxx`，本机免认证 |
+| HTTPS | 仅通过插件 | 需要插件提供 `httpsOptions` hook |
+| CORS | `*` | 允许所有来源 |
+| 上传限制 | 50MB | 单文件最大上传大小 |
+
+## 十二、URL 参数
+
+| 参数 | 说明 |
+|------|------|
+| `?token=xxx` | 局域网访问认证令牌 |
+| `?logfile=path` | 打开指定历史日志文件（只读模式） |
+
+## 十三、localStorage 配置
+
+| 键 | 说明 |
+|-----|------|
+| `cxv_cacheExpireAt` | 缓存倒计时到期时间 |
+| `cxv_cacheType` | 缓存类型标签 |
+| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
+| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
+| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cc-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/ru/KVCacheContent.md

@@ -0,0 +1,49 @@
+# Содержимое KV-Cache
+
+## Что такое Prompt Caching?
+
+Когда вы общаетесь с Claude, каждый API-запрос отправляет полный контекст диалога (системный промпт + определения инструментов + история сообщений). Механизм prompt caching от Anthropic кэширует уже вычисленное содержимое префикса на стороне сервера, и если префикс последующих запросов совпадает, результат кэша используется повторно, минуя повторные вычисления, что значительно снижает задержку и стоимость.
+
+В cc-viewer этот механизм называется "KV-Cache", и он соответствует prompt caching на уровне Anthropic API, а не key-value cache в слоях внимания transformer внутри LLM.
+
+## Как работает кэширование
+
+Prompt caching от Anthropic объединяет ключи кэша в фиксированном порядке:
+
+```
+Tools → System Prompt → Messages (до точки разрыва кэша)
+```
+
+Если этот префикс полностью совпадает с любым запросом в окне TTL, API попадает в кэш (возвращая `cache_read_input_tokens`), а не выполняет повторное вычисление (`cache_creation_input_tokens`).
+
+> **Claude Code не зависит жёстко от атрибута `cache_control`, серверная сторона удаляет часть этих атрибутов, но по-прежнему успешно создаёт кэш, поэтому отсутствие атрибута `cache_control` не означает, что кэширование не работает**
+>
+> Для специальных клиентов, таких как Claude Code, серверная сторона Anthropic не полностью полагается на атрибут `cache_control` в запросе для определения поведения кэширования. Сервер автоматически выполняет стратегию кэширования для определённых полей (таких как системный промпт, определения инструментов), даже если в запросе явно не указана метка `cache_control`. Поэтому, когда вы не видите этот атрибут в теле запроса, не стоит удивляться — сервер уже выполнил операцию кэширования за кулисами, просто не раскрывая эту информацию клиенту. Это негласное соглашение между Claude Code и Anthropic API.
+
+## Что такое "Текущее содержимое KV-Cache"?
+
+"Текущее содержимое KV-Cache", отображаемое в cc-viewer, извлекается из последнего запроса MainAgent и представляет содержимое, расположенное перед границей кэша (cache breakpoint). Конкретно включает:
+
+- **System Prompt**: Системные инструкции Claude Code, включая основные инструкции агента, правила использования инструментов, инструкции проекта CLAUDE.md, информацию об окружении и т.д.
+- **Tools**: Список определений доступных инструментов (таких как Read, Write, Bash, Agent, MCP-инструменты и т.д.)
+- **Messages**: Часть истории диалога, которая находится в кэше (обычно более ранние сообщения, до последней метки `cache_control`)
+
+## Зачем просматривать содержимое кэша?
+
+1. **Понимание контекста**: Узнайте, какое содержимое Claude "помнит" в данный момент, помогая вам определить, соответствует ли его поведение ожиданиям
+2. **Оптимизация затрат**: При попадании в кэш стоимость намного ниже, чем при пересчёте. Просмотр содержимого кэша помогает понять, почему определённые запросы вызвали перестроение кэша (cache rebuild)
+3. **Отладка диалога**: Когда ответ Claude не соответствует ожиданиям, проверка содержимого кэша подтверждает, правильны ли системный промпт и история сообщений
+4. **Мониторинг качества контекста**: В процессе отладки, изменения конфигурации или настройки промптов KV-Cache-Text предоставляет централизованное представление, помогая вам быстро подтвердить, не произошла ли деградация основного контекста или загрязнение неожиданным содержимым — без необходимости просматривать исходные сообщения по одному
+
+## Многоуровневая стратегия кэширования
+
+KV-Cache, соответствующий Claude Code, не является единственным. Серверная сторона генерирует отдельные кэши для Tools и System Prompt, независимые от кэша Messages. Преимущество такого дизайна в том, что когда стек messages нарушается (обрезка контекста, изменение сообщений и т.д.) и требуется перестроение, кэши Tools и System Prompt не инвалидируются вместе с ним, что позволяет избежать полного пересчёта.
+
+Это оптимизационная стратегия серверной стороны на текущем этапе — поскольку определения Tools и System Prompt при нормальном использовании относительно стабильны и редко меняются, раздельное кэширование позволяет максимально сократить ненужные затраты на перестроение. Поэтому при наблюдении за Cache вы обнаружите, что помимо перестроения Tools, которое требует полного обновления всех кэшей, нарушение System Prompt и Messages по-прежнему оставляет доступные унаследованные кэши.
+
+## Жизненный цикл кэша
+
+- **Создание**: При первом запросе или после инвалидации кэша API создаёт новый кэш (`cache_creation_input_tokens`)
+- **Попадание**: При последующих запросах с идентичным префиксом кэш повторно используется (`cache_read_input_tokens`)
+- **Истечение**: Кэш имеет TTL (время жизни) 5 минут и автоматически истекает по окончании этого периода
+- **Перестроение**: Когда системный промпт, список инструментов, модель или содержимое сообщений изменяются, ключ кэша не совпадает, вызывая перестроение соответствующего уровня кэша

package/concepts/ru/MainAgent.md

@@ -0,0 +1,23 @@
+# 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 | Полный основной prompt Claude Code | Упрощённый prompt, специализированный для задачи |
+| массив tools | Содержит все доступные инструменты | Обычно содержит только несколько инструментов, необходимых для задачи |
+| история сообщений | Накапливает полный контекст диалога | Содержит только сообщения, связанные с подзадачей |
+| поведение кеша | Prompt caching (5 минут TTL) | Обычно без кеша или с небольшим кешем |

package/concepts/ru/ProxySwitch.md

@@ -0,0 +1,50 @@
+# Hot-Switch Proxy
+
+## Overview
+
+Hot-Switch Proxy lets you dynamically redirect API requests to a different endpoint without restarting Claude Code. This is useful when using third-party API proxy services.
+
+> ⚠️ Do not use this feature if you are a Claude Max subscriber.
+
+## Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Name** | ✅ | Display name for this proxy, used to identify it |
+| **Base URL** | ✅ | Base URL of the API service (e.g. `https://api.example.com`). The original request origin will be replaced |
+| **API Key** | ✅ | API key for the proxy service, replaces the original authentication |
+| **Models** | ❌ | Comma-separated list of models supported by this proxy (e.g. `model-a, model-b`) |
+| **Active Model** | ❌ | Select the active model from the list. The `model` field in requests will be replaced |
+
+## How It Works
+
+When a proxy is active, `interceptor.js` performs the following before each API request:
+
+1. **URL Rewrite** — Replaces the request origin with the proxy's Base URL
+2. **Auth Replace** — Replaces `x-api-key` or `Authorization` header with the proxy's API Key
+3. **Model Replace** — If an active model is set, replaces the `model` field in the request body
+
+## Config File
+
+Configuration is stored at `~/.claude/cc-viewer/profile.json`. Click the folder icon in the title to open the directory:
+
+```json
+{
+  "active": "my-proxy",
+  "profiles": [
+    { "id": "max", "name": "Max" },
+    {
+      "id": "my-proxy",
+      "name": "My Proxy",
+      "baseURL": "https://api.example.com",
+      "apiKey": "sk-xxx",
+      "models": ["model-a", "model-b"],
+      "activeModel": "model-a"
+    }
+  ]
+}
+```
+
+- `active` — ID of the current profile. Set to `"max"` for direct connection (no proxy)
+- `profiles` — Profile list. `id: "max"` is built-in and cannot be deleted
+- Changes take effect within ~1.5 seconds (monitored via `fs.watchFile`), no restart needed

package/concepts/ru/QRCode.md

@@ -0,0 +1,25 @@
+# Мобильный доступ по QR-коду
+
+## Как это работает
+
+CC Viewer запускает HTTP-сервер и генерирует **адрес в локальной сети** (например, `http://192.168.1.100:7008`). Отсканируйте QR-код, чтобы получить доступ к Claude Code с телефона через ту же сеть WiFi.
+
+## Почему не удаётся подключиться?
+
+1. **Не в одной сети** — Телефон и компьютер должны быть подключены к одному WiFi (один роутер/одно имя сети)
+2. **Блокировка файрвола** — Файрвол системы может блокировать входящие соединения
+3. **Изоляция корпоративной сети** — Изоляция AP может препятствовать связи между устройствами
+4. **Помехи VPN** — VPN может нарушить сетевой маршрут
+
+## Уведомление о безопасности
+
+> ⚠️ LAN-сервис CC Viewer доступен всем устройствам в одной сети.
+
+- Будьте осторожны в **публичных WiFi**
+- CC Viewer использует **аутентификацию по токену** для защиты LAN-доступа
+- Рекомендуется использовать в доверенных сетях
+
+## За пределами LAN
+
+- **Инструменты туннелирования** — frp, ngrok, Tailscale и др.
+- **Плагины CC Viewer** — Настройте прокси-сервер через систему плагинов

package/concepts/ru/ResponseFields.md

@@ -0,0 +1,50 @@
+# Описание полей Response Body
+
+Описание полей тела ответа Claude API `/v1/messages`.
+
+## Поля верхнего уровня
+
+| Поле | Тип | Описание |
+|------|------|------|
+| **model** | string | Фактически используемое имя модели, например `claude-opus-4-6` |
+| **id** | string | Уникальный идентификатор данного ответа, например `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Фиксированное значение `"message"` |
+| **role** | string | Фиксированное значение `"assistant"` |
+| **content** | array | Массив блоков контента, выданных моделью, включая текст, вызовы инструментов, процесс рассуждения и т.д. |
+| **stop_reason** | string | Причина остановки: `"end_turn"` (нормальное завершение), `"tool_use"` (требуется выполнение инструмента), `"max_tokens"` (достигнут лимит токенов) |
+| **stop_sequence** | string/null | Последовательность, вызвавшая остановку, обычно `null` |
+| **usage** | object | Статистика использования токенов (подробнее см. ниже) |
+
+## Типы блоков content
+
+| Тип | Описание |
+|------|------|
+| **text** | Текстовый ответ модели, содержит поле `text` |
+| **tool_use** | Запрос на вызов инструмента, содержит `name` (имя инструмента), `input` (параметры), `id` (ID вызова, используется для сопоставления с tool_result) |
+| **thinking** | Содержимое расширенного мышления (появляется только при включённом режиме thinking), содержит поле `thinking` |
+
+## Подробное описание полей usage
+
+| Поле | Описание |
+|------|------|
+| **input_tokens** | Количество входных токенов, не попавших в кэш (тарифицируются по полной стоимости) |
+| **cache_creation_input_tokens** | Количество токенов для вновь созданного кэша (запись в кэш, стоимость выше обычного ввода) |
+| **cache_read_input_tokens** | Количество токенов, попавших в кэш (чтение из кэша, стоимость значительно ниже обычного ввода) |
+| **output_tokens** | Количество выходных токенов модели |
+| **service_tier** | Уровень обслуживания, например `"standard"` |
+| **inference_geo** | Регион инференса, например `"not_available"` означает, что информация о регионе не предоставлена |
+
+## Подполя cache_creation
+
+| Поле | Описание |
+|------|------|
+| **ephemeral_5m_input_tokens** | Количество токенов для создания краткосрочного кэша с TTL 5 минут |
+| **ephemeral_1h_input_tokens** | Количество токенов для создания долгосрочного кэша с TTL 1 час |
+
+> **О тарификации кэша**: стоимость единицы `cache_read_input_tokens` значительно ниже, чем `input_tokens`, а стоимость единицы `cache_creation_input_tokens` немного выше обычного ввода. Поэтому поддержание высокого процента попаданий в кэш при продолжительном диалоге позволяет существенно снизить расходы. С помощью показателя "процент попаданий" в cc-viewer можно наглядно отслеживать это соотношение.
+
+## Значения stop_reason
+
+- **end_turn**: модель нормально завершила ответ
+- **tool_use**: модели необходимо вызвать инструмент, в content будет содержаться блок `tool_use`. В следующем запросе необходимо добавить `tool_result` в messages для продолжения диалога
+- **max_tokens**: достигнут лимит `max_tokens`, ответ был обрезан и может быть неполным

package/concepts/ru/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Определение
+
+Search — это тип под-агента, запускаемого главным агентом Claude Code для выполнения поиска по кодовой базе. Он выполняет целенаправленный поиск файлов и содержимого с помощью таких инструментов, как Glob, Grep и Read, а затем возвращает результаты родительскому агенту.
+
+## Поведение
+
+- Запускается автоматически, когда главному агенту необходимо выполнить поиск или исследовать кодовую базу
+- Работает в изолированном контексте с доступом только для чтения
+- Использует Glob для сопоставления шаблонов файлов, Grep для поиска по содержимому и Read для инспекции файлов
+- Возвращает результаты поиска родительскому агенту для дальнейшей обработки
+
+## Когда появляется
+
+Под-агенты Search обычно появляются когда:
+
+1. Главному агенту необходимо найти конкретные файлы, функции или паттерны кода
+2. Пользователь запрашивает широкое исследование кодовой базы
+3. Агент изучает зависимости, ссылки или паттерны использования