cx-viewer 1.0.0

package/concepts/pl/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — Najlepsza Maszyna Spełniająca Życzenia
+
+## Czym jest UltraPlan
+
+UltraPlan to **zlokalizowana implementacja** natywnego polecenia `/ultraplan` Claude Code przez cc-viewer. Pozwala na korzystanie z pełnych możliwości `/ultraplan` w lokalnym środowisku **bez konieczności uruchamiania oficjalnej zdalnej usługi Claude**, kierując Claude Code do realizacji złożonych zadań planowania i implementacji przy użyciu **współpracy wielu agentów**.
+
+W porównaniu ze zwykłym trybem Plan lub Agent Team, UltraPlan potrafi:
+- Automatycznie oceniać złożoność zadania i wybierać optymalną strategię planowania
+- Wdrażać wielu równoległych agentów do eksploracji bazy kodu z różnych wymiarów
+- Włączać badania zewnętrzne (webSearch) w celu poznania najlepszych praktyk branżowych
+- Automatycznie tworzyć Zespół Code Review po wykonaniu planu w celu przeglądu kodu
+- Tworzyć kompletną zamkniętą pętlę **Plan → Wykonanie → Przegląd → Naprawa**
+
+---
+
+## Ważne uwagi
+
+### 1. UltraPlan nie jest wszechmocny
+UltraPlan to potężniejsza maszyna spełniająca życzenia, ale to nie znaczy, że każde życzenie może być spełnione. Jest potężniejszy niż Plan i Agent Team, ale nie może bezpośrednio „zarabiać pieniędzy". Rozważ rozsądną granulację zadań — dziel duże cele na wykonalne średniej wielkości zadania zamiast próbować osiągnąć wszystko za jednym razem.
+
+### 2. Obecnie najskuteczniejszy dla projektów programistycznych
+Szablony i przepływy pracy UltraPlan są głęboko zoptymalizowane dla projektów programistycznych. Inne scenariusze (dokumentacja, analiza danych itp.) można wypróbować, ale warto poczekać na przyszłe wersje z odpowiednimi adaptacjami.
+
+### 3. Czas wykonania i wymagania okna kontekstu
+- Pomyślne uruchomienie UltraPlan zazwyczaj trwa **30 minut lub więcej**
+- Wymaga, aby MainAgent posiadał duże okno kontekstu (zalecany model Opus z kontekstem 1M)
+- Jeśli masz tylko model 200K, **upewnij się, że wykonasz `/clear` kontekstu przed uruchomieniem**
+- Polecenie `/compact` Claude Code działa słabo, gdy okno kontekstu jest niewystarczające — unikaj wyczerpania miejsca
+- Utrzymanie wystarczającej przestrzeni kontekstu jest kluczowym warunkiem pomyślnego wykonania UltraPlan
+
+Jeśli masz jakiekolwiek pytania lub sugestie dotyczące zlokalizowanego UltraPlan, zapraszamy do otwarcia [Issues na GitHub](https://github.com/anthropics/claude-code/issues), aby dyskutować i współpracować.
+
+---
+
+## Jak to działa
+
+UltraPlan oferuje dwa tryby działania:
+
+### Tryb Automatyczny
+Automatycznie analizuje złożoność zadania (wynik 4-12) i kieruje do różnych strategii:
+
+| Trasa | Wynik | Strategia |
+|-------|-------|-----------|
+| Trasa A | 4-6 | Lekkie planowanie z bezpośrednią eksploracją kodu |
+| Trasa B | 7-9 | Planowanie z diagramami strukturalnymi (Mermaid / ASCII) |
+| Trasa C | 10-12 | Eksploracja wieloagentowa + zamknięta pętla przeglądu |
+
+### Tryb Wymuszony
+Bezpośrednio aktywuje pełny wieloagentowy przepływ pracy Trasy C:
+1. Wdrożenie do 5 równoległych agentów do jednoczesnej eksploracji bazy kodu (architektura, identyfikacja plików, ocena ryzyka itp.)
+2. Opcjonalne wdrożenie agenta badawczego do zbadania rozwiązań branżowych przez webSearch
+3. Synteza wszystkich odkryć agentów w szczegółowy plan implementacji
+4. Wdrożenie agenta przeglądowego do dokładnego zbadania planu z wielu perspektyw
+5. Wykonanie planu po zatwierdzeniu
+6. Automatyczne utworzenie Zespołu Code Review w celu walidacji jakości kodu po implementacji

package/concepts/pt-BR/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (Comparação Incremental do Corpo da Requisição)
+
+## Contexto
+
+O MainAgent do Claude Code utiliza um mecanismo de envio de contexto completo — cada requisição carrega o histórico completo da conversa, system prompt, definições de ferramentas, etc. Isso significa que, conforme a conversa avança, o corpo da requisição se torna cada vez maior, e visualizar o Body bruto dificulta identificar rapidamente "o que foi adicionado nesta rodada".
+
+O Body Diff JSON foi criado exatamente para resolver esse problema: ele compara automaticamente os bodies de duas requisições MainAgent consecutivas, extraindo a parte incremental, permitindo que você veja claramente o conteúdo efetivamente adicionado nesta requisição.
+
+## Como Funciona
+
+1. **Identificar requisições MainAgent consecutivas**: A requisição atual deve ser do tipo MainAgent, e deve existir uma requisição MainAgent anterior
+2. **Comparação campo a campo**: Percorre todos os campos de nível superior do corpo da requisição, ignorando propriedades internas com prefixo `_`
+3. **Extração inteligente de diferenças**:
+   - Campos adicionados: exibidos diretamente
+   - Campos removidos: não exibidos (geralmente não afetam a compreensão)
+   - Campos alterados: exibe o valor atual
+   - Tratamento especial do array `messages`: exibe apenas as mensagens adicionadas (pois em conversa normal o modo é de adição, as mensagens de prefixo não mudam)
+4. **Detecção de redução do corpo**: Se o corpo da requisição atual for menor que o anterior, indica truncamento de contexto ou reset de sessão, e nesse caso uma mensagem informativa é exibida em vez do diff
+
+## Cenário Típico
+
+Em uma rodada normal de conversa, o Body Diff JSON geralmente contém apenas:
+- `messages`: 1~2 mensagens adicionadas (a entrada do usuário + a resposta do assistente da rodada anterior)
+
+Se você vir alterações em campos como `system`, `tools`, `model` no diff, significa que houve mudança de configuração nesta rodada, o que frequentemente também é a causa da reconstrução de cache.
+
+## Como Usar
+
+- O Body Diff JSON é exibido no painel de detalhes da requisição MainAgent
+- Clique no título para expandir/recolher
+- Suporta dois modos de visualização: JSON e Text, além de cópia com um clique
+- No canto superior esquerdo em **CC-Viewer → Configurações Globais**, é possível configurar "Expandir Body Diff JSON por padrão"

package/concepts/pt-BR/BodyFields.md

@@ -0,0 +1,42 @@
+# Descrição dos campos do Request Body
+
+Descrição dos campos de nível superior do corpo da requisição da API Claude `/v1/messages`.
+
+## Lista de campos
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| **model** | string | Nome do modelo utilizado, como `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Histórico de mensagens da conversa. Cada mensagem contém `role` (user/assistant) e `content` (um array de blocos: texto, imagens, tool_use, tool_result etc.) |
+| **system** | array | System prompt. Contém as instruções principais do Codex, instruções de uso de ferramentas, informações do ambiente, conteúdo do CLAUDE.md etc. Blocos com `cache_control` são armazenados em cache através do prompt caching |
+| **tools** | array | Lista de definições de ferramentas disponíveis. Cada ferramenta contém `name`, `description` e `input_schema` (JSON Schema). O MainAgent tipicamente possui 20+ ferramentas, enquanto SubAgents possuem apenas algumas |
+| **metadata** | object | Metadados da requisição, tipicamente contém `user_id` para identificação do usuário |
+| **max_tokens** | number | Número máximo de tokens por resposta do modelo, como `16000`, `64000` |
+| **thinking** | object | Configuração do pensamento estendido. `type: "enabled"` ativa o modo de pensamento, `budget_tokens` controla o limite de tokens para o pensamento |
+| **context_management** | object | Configuração do gerenciamento de contexto. `truncation: "auto"` permite que o Codex trunque automaticamente históricos de mensagens muito longos |
+| **output_config** | object | Configuração de saída, como configurações de `format` |
+| **stream** | boolean | Se as respostas em streaming estão habilitadas. O Codex sempre utiliza `true` |
+
+## Estrutura de messages
+
+O `content` de cada mensagem é um array de blocos com os seguintes tipos comuns:
+
+- **text**: Conteúdo de texto normal
+- **tool_use**: O modelo invoca uma ferramenta (contém `name`, `input`)
+- **tool_result**: Resultado da execução da ferramenta (contém `tool_use_id`, `content`)
+- **image**: Conteúdo de imagem (base64 ou URL)
+- **thinking**: Processo de pensamento do modelo (modo de pensamento estendido)
+
+## Estrutura de system
+
+O array do system prompt tipicamente contém:
+
+1. **Instruções principais do agent** ("You are Codex...")
+2. **Especificações de uso de ferramentas**
+3. **Conteúdo do CLAUDE.md** (instruções em nível de projeto)
+4. **Lembretes de skills** (skills reminder)
+5. **Informações do ambiente** (OS, shell, status do git etc.) — Na verdade, o Codex depende fortemente do git. Se existir um repositório git no projeto, o Codex consegue demonstrar uma compreensão melhor do projeto, incluindo a capacidade de buscar alterações remotas e históricos de commits para auxiliar na análise
+
+Blocos marcados com `cache_control: { type: "ephemeral" }` são armazenados em cache pela API da Anthropic por 5 minutos. Quando o cache é utilizado, a cobrança é feita por `cache_read_input_tokens` (muito inferior a `input_tokens`).
+
+> **Nota**: Para clientes especiais como o Codex, o servidor da Anthropic na verdade não depende completamente do atributo `cache_control` na requisição para determinar o comportamento de cache. O servidor executa automaticamente estratégias de cache para campos específicos (como system prompt e definições de ferramentas), mesmo quando a requisição não contém explicitamente o marcador `cache_control`. Portanto, quando você não encontrar esse atributo no corpo da requisição, não há motivo para estranhamento — o servidor já realizou as operações de cache nos bastidores, sem expor essa informação ao cliente. Isso é uma espécie de entendimento tácito entre o Codex e a API da Anthropic.

package/concepts/pt-BR/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (Reconstrução de Cache)
+
+## Contexto
+
+O mecanismo de prompt caching da Anthropic concatena sequencialmente system → tools → messages (até o cache breakpoint) da requisição para formar a chave de cache. Quando a chave de cache é idêntica à da requisição anterior, a API retorna `cache_read_input_tokens` (acerto de cache); quando a chave de cache muda, a API recria o cache e retorna uma grande quantidade de `cache_creation_input_tokens`, ou seja, reconstrução de cache.
+
+A reconstrução de cache implica cobrança adicional de tokens (o preço de cache creation é maior que o de cache read), portanto identificar a causa da reconstrução tem valor direto para otimização de custos.
+
+## Classificação das Causas de Reconstrução de Cache
+
+O cc-viewer determina com precisão a causa da reconstrução de cache comparando os bodies de duas requisições MainAgent consecutivas:
+
+| reason | Significado | Método de Determinação |
+|--------|------|----------|
+| `ttl` | Cache expirado | Mais de 5 minutos desde a última requisição MainAgent |
+| `system_change` | Alteração do system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Alteração das definições de ferramentas | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Troca de modelo | `prev.model !== curr.model` |
+| `msg_truncated` | Pilha de mensagens truncada | O número de mensagens da requisição atual é menor que o da anterior, geralmente causado por truncamento devido ao estouro da janela de contexto |
+| `msg_modified` | Mensagens históricas modificadas | Conteúdo das mensagens de prefixo inconsistente (em adição normal, o prefixo deve ser idêntico) |
+| `key_change` | Alteração de chave desconhecida | Fallback quando nenhuma das condições acima é correspondida |
+
+## Prioridade de Determinação
+
+1. Primeiro verifica o intervalo de tempo — se ultrapassar 5 minutos, determina diretamente como `ttl`, sem comparação de body
+2. Em seguida verifica sequencialmente model, system, tools, messages
+3. Uma requisição pode corresponder a múltiplas causas simultaneamente (ex: troca de modelo + alteração de system prompt), nesse caso o array `reasons` contém todos os itens correspondentes, e o tooltip exibe em linhas separadas
+
+## Cenários Comuns
+
+- **`ttl`**: O usuário pausou a operação por mais de 5 minutos e depois continuou, o cache expirou naturalmente
+- **`system_change`**: O Claude Code atualizou o system prompt (ex: carregou novo CLAUDE.md, alteração nas project instructions)
+- **`tools_change`**: Conexão/desconexão de MCP server causou alteração na lista de ferramentas disponíveis
+- **`model_change`**: O usuário trocou o modelo através do comando `/model`
+- **`msg_truncated`**: Conversa muito longa acionou o gerenciamento da janela de contexto, o Claude Code truncou mensagens anteriores
+- **`msg_modified`**: O Claude Code editou mensagens históricas (ex: `/compact` substituiu mensagens originais por resumo compactado)

package/concepts/pt-BR/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/pt-BR/KVCacheContent.md

@@ -0,0 +1,49 @@
+# Conteudo do KV-Cache
+
+## O que e Prompt Caching?
+
+Quando voce conversa com o Claude, cada requisicao da API envia o contexto completo da conversa (system prompt + definicoes de ferramentas + historico de mensagens). O mecanismo de prompt caching da Anthropic armazena no servidor o conteudo do prefixo ja calculado. Se requisicoes subsequentes tiverem o mesmo prefixo, os resultados armazenados sao reutilizados diretamente, pulando calculos redundantes e reduzindo significativamente a latencia e os custos.
+
+No cc-viewer, esse mecanismo e chamado de "KV-Cache" e corresponde ao prompt caching no nivel da API da Anthropic, nao ao key-value cache interno das camadas de atencao do transformer do LLM.
+
+## Como o caching funciona
+
+O prompt caching da Anthropic constroi a chave de cache em uma ordem fixa:
+
+```
+Tools → System Prompt → Messages (ate o cache breakpoint)
+```
+
+Desde que esse prefixo corresponda exatamente a uma requisicao anterior dentro da janela de TTL, a API retornara um cache hit (`cache_read_input_tokens`) em vez de recalcular (`cache_creation_input_tokens`).
+
+> **O Claude Code nao depende estritamente do atributo `cache_control`. O servidor remove parcialmente esses atributos, mas ainda consegue criar o cache de forma eficaz. Portanto, a ausencia do atributo `cache_control` nao significa que o conteudo nao foi armazenado em cache.**
+>
+> Para clientes especiais como o Claude Code, o servidor da Anthropic nao depende completamente do atributo `cache_control` na requisicao para determinar o comportamento do cache. O servidor executa automaticamente estrategias de cache para campos especificos (como system prompt e definicoes de ferramentas), mesmo quando a requisicao nao contem marcadores `cache_control` explicitos. Portanto, se voce nao vir esse atributo no corpo da requisicao, nao ha motivo para confusao — o servidor ja completou a operacao de cache nos bastidores, simplesmente nao expoe essa informacao ao cliente. Isso e um entendimento tacito entre o Claude Code e a API da Anthropic.
+
+## O que e o "conteudo atual do KV-Cache"?
+
+O "conteudo atual do KV-Cache" exibido no cc-viewer e extraido da ultima requisicao do MainAgent e inclui o conteudo anterior ao limite do cache (cache breakpoint). Especificamente, ele compreende:
+
+- **System Prompt**: as instrucoes de sistema do Claude Code, incluindo instrucoes principais do agent, especificacoes de uso de ferramentas, instrucoes do projeto CLAUDE.md, informacoes do ambiente, etc.
+- **Tools**: a lista de definicoes de ferramentas atualmente disponiveis (como Read, Write, Bash, Agent, ferramentas MCP, etc.)
+- **Messages**: a parte armazenada do historico da conversa (tipicamente mensagens mais antigas, ate o ultimo marcador `cache_control`)
+
+## Por que visualizar o conteudo do cache?
+
+1. **Entender o contexto**: descubra quais conteudos o Claude tem atualmente "em memoria" para avaliar se seu comportamento corresponde as expectativas
+2. **Otimizacao de custos**: cache hits custam muito menos do que recalculos. Visualizar o conteudo do cache ajuda a entender por que certas requisicoes acionaram uma reconstrucao do cache (cache rebuild)
+3. **Debug de conversas**: quando as respostas do Claude nao correspondem as expectativas, verificar o conteudo do cache permite confirmar se o system prompt e o historico de mensagens estao corretos
+4. **Monitoramento da qualidade do contexto**: durante o debug, alteracao de configuracoes ou ajuste de prompts, o KV-Cache-Text oferece uma visao centralizada que ajuda a verificar rapidamente se o contexto principal se degradou ou foi contaminado por conteudo inesperado — sem precisar percorrer manualmente cada mensagem original
+
+## Estrategia de cache multinivel
+
+O KV-Cache do Claude Code nao e composto por um unico cache. O servidor gera caches separados para Tools e System Prompt, independentes do cache de Messages. A vantagem desse design e que quando a pilha de mensagens apresenta problemas (como truncamento de contexto, alteracoes de mensagens, etc.) e precisa ser reconstruida, os caches de Tools e System Prompt nao sao invalidados junto, evitando um recalculo completo.
+
+Esta e uma estrategia de otimizacao atual do servidor — como as definicoes de ferramentas e o system prompt sao relativamente estaveis durante o uso normal e raramente mudam, armazena-los separadamente em cache minimiza o overhead de reconstrucoes desnecessarias. Ao observar o cache, voce percebera que, alem da reconstrucao de Tools (que exige a atualizacao completa do cache), alteracoes no System Prompt e nas Messages ainda possuem caches herdaveis disponiveis.
+
+## Ciclo de vida do cache
+
+- **Criacao**: na primeira requisicao ou apos a invalidacao do cache, a API cria um novo cache (`cache_creation_input_tokens`)
+- **Hit**: requisicoes subsequentes com prefixo identico reutilizam o cache (`cache_read_input_tokens`)
+- **Expiracao**: o cache tem um TTL (Time to Live) de 5 minutos e expira automaticamente apos esse periodo
+- **Reconstrucao**: quando o system prompt, a lista de ferramentas, o modelo ou o conteudo das mensagens mudam, a chave de cache nao corresponde mais e aciona uma reconstrucao do cache no nivel correspondente

package/concepts/pt-BR/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Definição
+
+MainAgent é a cadeia de requisições principal do Claude Code quando não está no modo agent team. Cada interação do usuário com o Claude Code gera uma série de requisições à API, e as requisições do MainAgent formam a cadeia de diálogo central — elas carregam o system prompt completo, definições de ferramentas e histórico de mensagens.
+
+## Como Identificar
+
+No cc-viewer, o MainAgent é identificado por `req.mainAgent === true`, marcado automaticamente pelo `interceptor.js` durante a captura da requisição.
+
+Condições de identificação (todas devem ser atendidas):
+- O corpo da requisição contém o campo `system` (system prompt)
+- O corpo da requisição contém o array `tools` (definições de ferramentas)
+- O system prompt contém texto característico de "Claude Code"
+
+## Diferença em Relação ao SubAgent
+
+| Característica | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | Prompt principal completo do Claude Code | Prompt simplificado específico para a tarefa |
+| array tools | Contém todas as ferramentas disponíveis | Geralmente contém apenas as poucas ferramentas necessárias para a tarefa |
+| Histórico de mensagens | Acumula o contexto completo da conversa | Contém apenas mensagens relacionadas à subtarefa |
+| Comportamento de cache | Possui prompt caching (TTL de 5 minutos) | Geralmente sem cache ou com cache menor |

package/concepts/pt-BR/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/pt-BR/QRCode.md

@@ -0,0 +1,25 @@
+# Acesso móvel por QR code
+
+## Como funciona
+
+CC Viewer inicia um servidor HTTP e gera um **endereço LAN** (ex: `http://192.168.1.100:7008`). Escaneie o QR code para acessar o Claude Code do seu celular pela mesma rede WiFi.
+
+## Por que não consigo conectar?
+
+1. **Não está na mesma rede** — Celular e computador devem estar no mesmo WiFi (mesmo roteador/mesmo nome de rede)
+2. **Bloqueio do firewall** — O firewall do sistema pode bloquear conexões de entrada
+3. **Isolamento de rede corporativa** — O isolamento AP pode impedir a comunicação entre dispositivos
+4. **Interferência VPN** — Uma VPN pode interromper a rota de rede
+
+## Aviso de segurança
+
+> ⚠️ O serviço LAN do CC Viewer é acessível a todos os dispositivos na mesma rede.
+
+- Cuidado em **WiFi público**
+- CC Viewer usa **autenticação por token** para proteger o acesso LAN
+- Recomendado para uso em redes confiáveis
+
+## Além da LAN
+
+- **Ferramentas de tunelamento** — frp, ngrok, Tailscale, etc.
+- **Plugins CC Viewer** — Configure um proxy middleware pelo sistema de plugins

package/concepts/pt-BR/ResponseFields.md

@@ -0,0 +1,50 @@
+# Descrição dos campos do Response Body
+
+Descrição dos campos do corpo de resposta da API Claude `/v1/messages`.
+
+## Campos de nível superior
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| **model** | string | Nome do modelo efetivamente utilizado, ex.: `claude-opus-4-6` |
+| **id** | string | Identificador único desta resposta, ex.: `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Sempre `"message"` |
+| **role** | string | Sempre `"assistant"` |
+| **content** | array | Array de blocos de conteúdo produzidos pelo modelo, incluindo texto, chamadas de ferramentas, processo de raciocínio, etc. |
+| **stop_reason** | string | Motivo da parada: `"end_turn"` (conclusão normal), `"tool_use"` (necessária execução de ferramenta), `"max_tokens"` (limite de tokens atingido) |
+| **stop_sequence** | string/null | A sequência que acionou a parada, geralmente `null` |
+| **usage** | object | Estatísticas de uso de tokens (veja abaixo) |
+
+## Tipos de bloco content
+
+| Tipo | Descrição |
+|------|-----------|
+| **text** | Resposta em texto do modelo, contém o campo `text` |
+| **tool_use** | Requisição de chamada de ferramenta, contém `name` (nome da ferramenta), `input` (parâmetros), `id` (ID da chamada, usado para associar ao tool_result) |
+| **thinking** | Conteúdo do raciocínio estendido (aparece apenas com o modo thinking ativado), contém o campo `thinking` |
+
+## Detalhamento dos campos usage
+
+| Campo | Descrição |
+|-------|-----------|
+| **input_tokens** | Número de tokens de entrada não encontrados no cache (cobrados pelo preço integral) |
+| **cache_creation_input_tokens** | Número de tokens para os quais um novo cache foi criado nesta requisição (escrita em cache, custo superior à entrada normal) |
+| **cache_read_input_tokens** | Número de tokens lidos do cache (leitura de cache, custo muito inferior à entrada normal) |
+| **output_tokens** | Número de tokens produzidos pelo modelo |
+| **service_tier** | Nível de serviço, ex.: `"standard"` |
+| **inference_geo** | Região de inferência, ex.: `"not_available"` indica que a informação de região não está disponível |
+
+## Subcampos de cache_creation
+
+| Campo | Descrição |
+|-------|-----------|
+| **ephemeral_5m_input_tokens** | Número de tokens para criação de cache de curto prazo com TTL de 5 minutos |
+| **ephemeral_1h_input_tokens** | Número de tokens para criação de cache de longo prazo com TTL de 1 hora |
+
+> **Sobre a tarifação do cache**: O preço unitário de `cache_read_input_tokens` é muito inferior ao de `input_tokens`, enquanto o preço unitário de `cache_creation_input_tokens` é ligeiramente superior ao da entrada normal. Portanto, manter uma alta taxa de acerto de cache em conversas contínuas pode reduzir significativamente os custos. Através da métrica "taxa de acerto" do cc-viewer é possível monitorar visualmente essa proporção.
+
+## Significado de stop_reason
+
+- **end_turn**: O modelo concluiu a resposta normalmente
+- **tool_use**: O modelo precisa chamar uma ferramenta; content conterá um bloco `tool_use`. Na próxima requisição é necessário adicionar um `tool_result` em messages para continuar a conversa
+- **max_tokens**: O limite `max_tokens` foi atingido, a resposta foi truncada e pode estar incompleta

package/concepts/pt-BR/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Definição
+
+Search é um tipo de sub-agent gerado pelo agente principal do Claude Code para realizar buscas na base de código. Ele executa buscas direcionadas de arquivos e conteúdo usando ferramentas como Glob, Grep e Read, e então retorna os resultados ao agente pai.
+
+## Comportamento
+
+- Gerado automaticamente quando o agente principal precisa buscar ou explorar a base de código
+- Executa em um contexto isolado com acesso somente leitura
+- Usa Glob para correspondência de padrões de arquivos, Grep para busca de conteúdo e Read para inspeção de arquivos
+- Retorna resultados de busca ao agente pai para processamento adicional
+
+## Quando aparece
+
+Sub-agents Search tipicamente aparecem quando:
+
+1. O agente principal precisa encontrar arquivos, funções ou padrões de código específicos
+2. Uma exploração ampla da base de código é solicitada pelo usuário
+3. O agente está investigando dependências, referências ou padrões de uso

package/concepts/pt-BR/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## Definicao
+
+Um Teammate e um agent colaborativo no modo Team do Claude Code Agent. Quando o agent principal cria um time com `TeamCreate` e gera teammates usando a ferramenta `Agent`, cada teammate e executado como um processo agent independente, com sua propria janela de contexto e conjunto de ferramentas, comunicando-se com os membros do time atraves de `SendMessage`.
+
+## Diferencas em relacao ao SubAgent
+
+| Caracteristica | Teammate | SubAgent |
+|----------------|----------|----------|
+| Ciclo de vida | Persiste, pode receber multiplas mensagens | Tarefa unica, destruido ao concluir |
+| Comunicacao | SendMessage mensagens bidirecionais | Chamada unidirecional pai->filho, retorna resultado |
+| Contexto | Contexto completo independente, mantido entre turnos | Contexto de tarefa isolado |
+| Modo de colaboracao | Colaboracao em equipe, comunicacao mutua possivel | Estrutura hierarquica, interacao apenas com o agent pai |
+| Tipo de tarefa | Tarefas complexas de multiplas etapas | Tarefas unicas como busca, exploracao |
+
+## Comportamento
+
+- Criado pelo agent principal (team lead) atraves da ferramenta `Agent` e atribuido a um `team_name`
+- Compartilha a lista de tarefas via `TaskList` / `TaskGet` / `TaskUpdate`
+- Entra em estado idle apos cada turno de execucao, aguardando novas mensagens para reativacao
+- Pode ser encerrado de forma ordenada via `shutdown_request`
+
+## Descricao do painel de estatisticas
+
+O painel de estatisticas do Teammate exibe o numero de chamadas de API para cada teammate. A coluna `Name` contem o nome do teammate (ex.: `reviewer-security`, `reviewer-pipeline`), a coluna `Contagem` indica o numero total de requisicoes de API geradas por aquele teammate.