cc-viewer 1.2.1 → 1.2.2

package/concepts/pt-BR/Tool-TaskStop.md

@@ -0,0 +1,27 @@
+# TaskStop
+
+## Definição
+
+Para uma tarefa em segundo plano que está em execução.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `task_id` | string | Não | ID da tarefa em segundo plano a parar |
+| `shell_id` | string | Não | Descontinuado, use `task_id` em vez disso |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Encerrar tarefas de longa duração que não são mais necessárias
+- Cancelar tarefas em segundo plano iniciadas por engano
+
+## Observações
+
+- Retorna status de sucesso ou falha
+- O parâmetro `shell_id` está descontinuado, deve-se usar `task_id`
+
+## Significado no cc-viewer
+
+A chamada TaskStop em si não gera requisições API, é uma operação interna de gerenciamento de tarefas do Claude Code.

package/concepts/pt-BR/Tool-TaskUpdate.md

@@ -0,0 +1,49 @@
+# TaskUpdate
+
+## Definição
+
+Atualiza o status, conteúdo ou dependências de uma tarefa na lista de tarefas.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `taskId` | string | Sim | ID da tarefa a atualizar |
+| `status` | enum | Não | Novo status: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | Não | Novo título |
+| `description` | string | Não | Nova descrição |
+| `activeForm` | string | Não | Texto no gerúndio exibido quando em andamento |
+| `owner` | string | Não | Novo responsável pela tarefa (nome do agent) |
+| `metadata` | object | Não | Metadados a mesclar (definir como null para excluir chave) |
+| `addBlocks` | string[] | Não | Lista de IDs de tarefas bloqueadas por esta tarefa |
+| `addBlockedBy` | string[] | Não | Lista de IDs de tarefas pré-requisito que bloqueiam esta tarefa |
+
+## Fluxo de Status
+
+```
+pending → in_progress → completed
+```
+
+`deleted` pode ser atingido a partir de qualquer status, removendo permanentemente a tarefa.
+
+## Cenários de Uso
+
+**Adequado para:**
+- Marcar tarefa como `in_progress` ao iniciar o trabalho
+- Marcar tarefa como `completed` após concluir o trabalho
+- Definir dependências entre tarefas
+- Atualizar conteúdo da tarefa quando requisitos mudam
+
+**Regras importantes:**
+- Só marcar como `completed` quando a tarefa estiver totalmente concluída
+- Manter como `in_progress` ao encontrar erros ou bloqueios
+- Não marcar como `completed` quando testes falham, implementação está incompleta ou há erros não resolvidos
+
+## Observações
+
+- Antes de atualizar, deve-se obter o status mais recente da tarefa via TaskGet para evitar dados desatualizados
+- Após concluir uma tarefa, chamar TaskList para encontrar a próxima tarefa disponível
+
+## Significado no cc-viewer
+
+TaskUpdate é uma operação interna de gerenciamento de tarefas, não gera requisições API independentes.

package/concepts/pt-BR/Tool-WebFetch.md

@@ -0,0 +1,36 @@
+# WebFetch
+
+## Definição
+
+Busca o conteúdo de uma URL especificada, converte HTML para markdown e processa o conteúdo usando um modelo de IA com base no prompt.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `url` | string (URI) | Sim | URL completa a ser buscada |
+| `prompt` | string | Sim | Descreve que informação extrair da página |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Obter conteúdo de páginas web públicas
+- Consultar documentação online
+- Extrair informações específicas de páginas web
+
+**Não adequado para:**
+- URLs que requerem autenticação (Google Docs, Confluence, Jira, GitHub, etc.) — deve primeiro procurar ferramentas MCP dedicadas
+- URLs do GitHub — prefira usar o CLI `gh`
+
+## Observações
+
+- A URL deve ser uma URL válida completa
+- HTTP é automaticamente atualizado para HTTPS
+- Resultados podem ser resumidos quando o conteúdo é muito grande
+- Inclui cache com auto-limpeza de 15 minutos
+- Quando a URL redireciona para um host diferente, a ferramenta retorna a URL de redirecionamento, sendo necessário fazer nova requisição com a nova URL
+- Se houver uma ferramenta web fetch fornecida por MCP disponível, prefira usá-la
+
+## Significado no cc-viewer
+
+As chamadas WebFetch aparecem nos logs de requisição como pares de content blocks `tool_use` / `tool_result`. O `tool_result` contém o resumo do conteúdo da página web processado por IA.

package/concepts/pt-BR/Tool-WebSearch.md

@@ -0,0 +1,32 @@
+# WebSearch
+
+## Definição
+
+Executa consultas em mecanismo de busca, retornando resultados de pesquisa para obter informações atualizadas.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `query` | string | Sim | Consulta de busca (mínimo 2 caracteres) |
+| `allowed_domains` | string[] | Não | Incluir apenas resultados destes domínios |
+| `blocked_domains` | string[] | Não | Excluir resultados destes domínios |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Obter informações atualizadas além da data de corte do conhecimento do modelo
+- Buscar eventos atuais e dados recentes
+- Pesquisar documentação técnica mais recente
+
+## Observações
+
+- Os resultados de busca são retornados em formato de hyperlinks markdown
+- Após o uso, é obrigatório incluir uma seção "Sources:" no final da resposta, listando as URLs relevantes
+- Suporta filtragem de domínios (inclusão/exclusão)
+- A consulta de busca deve usar o ano atual
+- Disponível apenas nos EUA
+
+## Significado no cc-viewer
+
+As chamadas WebSearch aparecem nos logs de requisição como pares de content blocks `tool_use` / `tool_result`. O `tool_result` contém a lista de resultados da busca.

package/concepts/pt-BR/Tool-Write.md

@@ -0,0 +1,32 @@
+# Write
+
+## Definição
+
+Escreve conteúdo no sistema de arquivos local. Se o arquivo já existir, será sobrescrito.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `file_path` | string | Sim | Caminho absoluto do arquivo (deve ser caminho absoluto) |
+| `content` | string | Sim | Conteúdo a ser escrito |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Criar novos arquivos
+- Quando é necessário reescrever completamente o conteúdo do arquivo
+
+**Não adequado para:**
+- Modificar conteúdo parcial de um arquivo — deve usar Edit
+- Não deve criar proativamente arquivos de documentação (*.md) ou README, a menos que o usuário solicite explicitamente
+
+## Observações
+
+- Se o arquivo de destino já existir, é obrigatório lê-lo primeiro via Read, caso contrário falhará
+- Sobrescreve todo o conteúdo do arquivo existente
+- Prefira usar Edit para editar arquivos existentes; Write é apenas para criar novos arquivos ou reescrita completa
+
+## Significado no cc-viewer
+
+A chamada Write aparece nos logs de requisição como um content block `tool_use`, cujo `input.content` contém o conteúdo completo escrito.

package/concepts/pt-BR/Tool-executeCode.md

@@ -0,0 +1,33 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definição
+
+Executa código Python no kernel Jupyter do arquivo notebook atual.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `code` | string | Sim | Código Python a ser executado |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Executar código em ambiente Jupyter notebook
+- Testar trechos de código
+- Análise de dados e cálculos
+
+**Não adequado para:**
+- Execução de código fora do ambiente Jupyter — deve usar Bash
+- Modificar arquivos — deve usar Edit ou Write
+
+## Observações
+
+- Esta é uma ferramenta MCP (Model Context Protocol), fornecida pela integração com IDE
+- O código é executado no kernel Jupyter atual, o estado persiste entre chamadas
+- A menos que o usuário solicite explicitamente, deve-se evitar declarar variáveis ou modificar o estado do kernel
+- O estado é perdido após reiniciar o kernel
+
+## Significado no cc-viewer
+
+executeCode é uma ferramenta MCP, aparece no array `tools` dos logs de requisição com o nome `mcp__ide__executeCode`. Suas chamadas e retornos seguem o padrão `tool_use` / `tool_result`. A adição/remoção de ferramentas MCP causa alterações no array tools, podendo acionar reconstrução de cache.

package/concepts/pt-BR/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definição
+
+Obtém informações de diagnóstico de linguagem do VS Code, incluindo erros de sintaxe, erros de tipo, avisos de lint, etc.
+
+## Parâmetros
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|------|------|------|------|
+| `uri` | string | Não | URI do arquivo. Se não fornecido, obtém diagnósticos de todos os arquivos |
+
+## Cenários de Uso
+
+**Adequado para:**
+- Verificar problemas semânticos como sintaxe, tipos e lint no código
+- Verificar se novas edições introduziram erros
+- Substituir comandos Bash para verificar qualidade do código
+
+**Não adequado para:**
+- Executar testes — deve usar Bash
+- Verificar erros de runtime — deve usar Bash para executar o código
+
+## Observações
+
+- Esta é uma ferramenta MCP (Model Context Protocol), fornecida pela integração com IDE
+- Disponível apenas em ambiente VS Code / IDE
+- Prefira usar esta ferramenta em vez de comandos Bash para verificar problemas no código
+
+## Significado no cc-viewer
+
+getDiagnostics é uma ferramenta MCP, aparece no array `tools` dos logs de requisição com o nome `mcp__ide__getDiagnostics`. Suas chamadas e retornos seguem o padrão `tool_use` / `tool_result`. A adição/remoção de ferramentas MCP causa alterações no array tools, podendo acionar reconstrução de cache.

package/concepts/pt-BR/Tools.md

@@ -0,0 +1,73 @@
+# Visão Geral das Ferramentas do Claude Code
+
+O Claude Code fornece ao modelo um conjunto de ferramentas integradas através do mecanismo tool_use da API da Anthropic. O array `tools` de cada requisição MainAgent contém as definições completas em JSON Schema dessas ferramentas, e o modelo as invoca através de content blocks `tool_use` na resposta.
+
+A seguir está o índice categorizado de todas as ferramentas.
+
+## Sistema de Agents
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Task](Tool-Task.md) | Iniciar um sub-agent (SubAgent) para processar tarefas complexas de múltiplas etapas |
+| [TaskOutput](Tool-TaskOutput.md) | Obter a saída de tarefas em segundo plano |
+| [TaskStop](Tool-TaskStop.md) | Parar uma tarefa em segundo plano em execução |
+| [TaskCreate](Tool-TaskCreate.md) | Criar uma entrada na lista de tarefas estruturada |
+| [TaskGet](Tool-TaskGet.md) | Obter detalhes de uma tarefa |
+| [TaskUpdate](Tool-TaskUpdate.md) | Atualizar status, dependências, etc. de uma tarefa |
+| [TaskList](Tool-TaskList.md) | Listar todas as tarefas |
+
+## Operações de Arquivo
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Read](Tool-Read.md) | Ler conteúdo de arquivo (suporta texto, imagens, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Editar arquivo através de substituição exata de string |
+| [Write](Tool-Write.md) | Escrever ou sobrescrever arquivo |
+| [NotebookEdit](Tool-NotebookEdit.md) | Editar células de Jupyter notebook |
+
+## Busca
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Glob](Tool-Glob.md) | Buscar arquivos por padrão de nome de arquivo |
+| [Grep](Tool-Grep.md) | Busca de conteúdo de arquivo baseada em ripgrep |
+
+## Terminal
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Bash](Tool-Bash.md) | Executar comandos shell |
+
+## Web
+
+| Ferramenta | Finalidade |
+|------|------|
+| [WebFetch](Tool-WebFetch.md) | Buscar conteúdo de página web e processar com IA |
+| [WebSearch](Tool-WebSearch.md) | Consulta em mecanismo de busca |
+
+## Planejamento e Interação
+
+| Ferramenta | Finalidade |
+|------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Entrar no modo de planejamento para projetar plano de implementação |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Sair do modo de planejamento e submeter plano para aprovação do usuário |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Fazer perguntas ao usuário para obter esclarecimentos ou decisões |
+
+## Extensões
+
+| Ferramenta | Finalidade |
+|------|------|
+| [Skill](Tool-Skill.md) | Executar skill (slash command) |
+
+## Integração com IDE
+
+| Ferramenta | Finalidade |
+|------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Obter informações de diagnóstico de linguagem do VS Code |
+| [executeCode](Tool-executeCode.md) | Executar código no kernel Jupyter |
+
+## Significado no cc-viewer
+
+As chamadas de ferramentas são um dos dados observáveis mais importantes nos logs de requisição do Claude Code. O array `tools` de cada requisição MainAgent define o conjunto de ferramentas disponíveis para o modelo, enquanto os content blocks `tool_use` / `tool_result` na resposta registram as chamadas e retornos reais das ferramentas. O cc-viewer reconstrói a cadeia completa de chamadas de ferramentas no Chat Mode analisando esses dados.
+
+Alterações nas definições de ferramentas (como adição/remoção de ferramentas devido à conexão/desconexão de MCP server) acionam a reconstrução de cache, veja [CacheRebuild](CacheRebuild.md).

package/concepts/pt-BR/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Poluição de Contexto na Translate API
+
+## Contexto
+
+O CC-Viewer inclui um recurso de tradução integrado (`POST /api/translate`) alimentado pela Anthropic Messages API. Na implementação inicial, as requisições de tradução reutilizavam credenciais de autenticação em cache da sessão do Claude Code — incluindo os cabeçalhos `x-api-key` e `authorization`. Isso causou um problema sutil, mas grave: os resultados da tradução frequentemente retornavam conteúdo irrelevante.
+
+## Causa Raiz
+
+### Diferença fundamental entre dois métodos de autenticação
+
+A Anthropic API suporta dois métodos de autenticação:
+
+| Método | Cabeçalho | Origem típica | Características |
+|--------|-----------|---------------|-----------------|
+| Chave de API | `x-api-key: sk-ant-...` | Variável de ambiente / Console | Sem estado, cada requisição é independente |
+| Token OAuth | `authorization: Bearer sessionToken` | Login por assinatura do Claude Code | Vinculado à sessão, o servidor mantém associação de contexto |
+
+A diferença fundamental: **Chaves de API são sem estado** — cada requisição é completamente independente; enquanto **tokens de sessão OAuth são com estado** — o servidor da Anthropic associa requisições que usam o mesmo token ao mesmo contexto de sessão.
+
+### Cadeia de poluição
+
+Quando o Claude Code usa login OAuth por assinatura, o fluxo de autenticação é assim:
+
+```
+Conversa principal do Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                              ↑
+Requisição de tradução do CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Como as requisições de tradução reutilizavam o mesmo token de sessão, o servidor da Anthropic pode associar as requisições de tradução ao contexto da conversa principal do Claude Code. Isso causa:
+
+1. **Resultados de tradução influenciados pelo contexto da conversa principal**: O prompt de sistema da requisição de tradução é "você é um tradutor", mas o contexto do servidor ainda contém o histórico de conversas do Claude Code, potencialmente interferindo no modelo
+2. **Conversa principal perturbada pelas requisições de tradução**: O conteúdo das requisições de tradução (fragmentos de texto da UI) pode ser injetado no contexto da conversa principal, fazendo com que as respostas do Claude Code desviem
+3. **Comportamento imprevisível**: Como a poluição de contexto é um comportamento do lado do servidor, o cliente não pode detectá-la ou controlá-la
+
+## Lições Aprendidas
+
+- **Tokens de sessão OAuth não são "apenas mais uma chave de API"** — eles carregam estado do lado do servidor, e reutilizá-los significa compartilhar contexto
+- **Chamadas internas de serviço devem usar autenticação independente e sem estado** para evitar associação com sessões de usuários
+
+## Referências
+
+- [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/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/CacheRebuild.md

@@ -0,0 +1,40 @@
+# 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` заменил оригинальные сообщения сжатым резюме)
+
+## Отображение в cc-viewer
+
+В списке запросов запросы с пересборкой кеша отмечены красным точечным индикатором в строке cache. При наведении мыши отображается tooltip с конкретным описанием причины пересборки (поддержка 18 языков).

package/concepts/ru/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 | Полный основной prompt Claude Code | Упрощённый prompt, специализированный для задачи |
+| массив tools | Содержит все доступные инструменты | Обычно содержит только несколько инструментов, необходимых для задачи |
+| история сообщений | Накапливает полный контекст диалога | Содержит только сообщения, связанные с подзадачей |
+| поведение кеша | Prompt caching (5 минут TTL) | Обычно без кеша или с небольшим кешем |
+
+## Значение в cc-viewer
+
+- **Отслеживание кеша**: состояние prompt caching запросов MainAgent напрямую влияет на затраты. Мониторинг соотношения `cache_creation_input_tokens` и `cache_read_input_tokens` позволяет оценить коэффициент попаданий в кеш
+- **Анализ потери кеша**: когда запрос MainAgent показывает большое количество cache creation (вместо cache read), это означает потерю и пересборку кеша — cc-viewer отмечает такие запросы красным точечным индикатором
+- **Анализ основной цепочки**: последовательность запросов MainAgent отражает полный процесс взаимодействия пользователя с Claude Code и является ключевыми данными для анализа поведения сессии
+- **Реконструкция сессии**: cc-viewer реконструирует представление диалога (Chat Mode) на основе истории сообщений из запросов MainAgent

package/concepts/ru/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" и предоставить собственный ввод
+- Рекомендуемый вариант должен быть первым, с "(Recommended)" в конце метки
+- Предпросмотр `markdown` поддерживается только для вопросов с одиночным выбором
+- Варианты с `markdown` переключаются на расположение бок о бок (лево-право)
+- В режиме планирования используется для уточнения требований перед определением плана
+
+## Значение в cc-viewer
+
+Вызов AskUserQuestion в логах запросов отображается как блок content `tool_use`, содержащий определения вопросов и вариантов. Ответ пользователя появляется в истории сообщений последующих запросов.

package/concepts/ru/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## Определение
+
+Выполняет команды shell с опциональной настройкой тайм-аута. Рабочий каталог сохраняется между командами, но состояние shell (переменные окружения и т.д.) не сохраняется.
+
+## Параметры
+
+| Параметр | Тип | Обязательный | Описание |
+|------|------|------|------|
+| `command` | string | Да | Команда bash для выполнения |
+| `description` | string | Нет | Краткое описание команды |
+| `timeout` | number | Нет | Тайм-аут (миллисекунды), макс. 600000, по умолчанию 120000 |
+| `run_in_background` | boolean | Нет | Запускать ли в фоновом режиме |
+
+## Сценарии использования
+
+**Подходящее применение:**
+- Операции git (commit, push, branch и т.д.)
+- Команды менеджеров пакетов npm/yarn
+- Операции docker
+- Команды компиляции и сборки
+- Просмотр содержимого каталогов (`ls`)
+- Другие системные команды, требующие выполнения в shell
+
+**Неподходящее применение:**
+- Чтение файлов — следует использовать Read
+- Поиск имён файлов — следует использовать Glob
+- Поиск содержимого файлов — следует использовать Grep
+- Редактирование файлов — следует использовать Edit
+- Запись файлов — следует использовать Write
+- Вывод информации пользователю — непосредственно в тексте ответа
+- Долго работающие процессы (dev server, режим watch) — рекомендуется ручной запуск пользователем
+
+## Примечания
+
+- Пути, содержащие пробелы, должны быть заключены в двойные кавычки
+- Вывод, превышающий 30000 символов, будет обрезан
+- Результаты команд, запущенных в фоне, получают через TaskOutput
+- Следует использовать абсолютные пути, избегать `cd`
+- Независимые команды могут вызываться параллельно в нескольких Bash
+- Команды с зависимостями связываются через `&&`
+- Среда shell инициализируется из профиля пользователя (bash или zsh)
+
+## Значение в cc-viewer
+
+Вызовы Bash в логах запросов отображаются как пары блоков content `tool_use` (содержащие команду) и `tool_result` (содержащие вывод). Вывод выполнения команды может использоваться для анализа поведения модели.

package/concepts/ru/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## Определение
+
+Редактирует файл через точную замену строк. Заменяет `old_string` в файле на `new_string`.
+
+## Параметры
+
+| Параметр | Тип | Обязательный | Описание |
+|------|------|------|------|
+| `file_path` | string | Да | Абсолютный путь к файлу для модификации |
+| `old_string` | string | Да | Исходный текст для замены |
+| `new_string` | string | Да | Новый текст после замены (должен отличаться от old_string) |
+| `replace_all` | boolean | Нет | Заменять ли все вхождения, по умолчанию `false` |
+
+## Сценарии использования
+
+**Подходящее применение:**
+- Модификация определённых фрагментов кода в существующих файлах
+- Исправление ошибок, обновление логики
+- Переименование переменных (в сочетании с `replace_all: true`)
+- Любой сценарий, требующий точной модификации содержимого файла
+
+**Неподходящее применение:**
+- Создание новых файлов — следует использовать Write
+- Масштабное переписывание — может потребоваться Write для перезаписи всего файла
+
+## Примечания
+
+- Перед использованием необходимо сначала прочитать файл через Read, иначе возникнет ошибка
+- `old_string` должен быть уникальным в файле, иначе редактирование не удастся. Если не уникален, нужно предоставить больше контекста или использовать `replace_all`
+- При редактировании текста необходимо сохранять оригинальные отступы (tab/пробелы), не включать префиксы номеров строк из вывода Read
+- Предпочтительно редактировать существующие файлы, а не создавать новые
+- `new_string` должен отличаться от `old_string`
+
+## Значение в cc-viewer
+
+Вызов Edit в логах запросов отображается как блок content `tool_use`, чей `input` содержит `old_string` и `new_string`, что позволяет отслеживать, какие модификации модель внесла в файл.