cx-viewer 1.0.0

package/concepts/es/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (Comparación incremental del cuerpo de la solicitud)
+
+## Contexto
+
+El MainAgent de Claude Code utiliza un mecanismo de envío de contexto completo: cada solicitud incluye el historial completo de la conversación, el system prompt, las definiciones de herramientas, etc. Esto significa que a medida que avanza la conversación, el cuerpo de la solicitud se vuelve cada vez más grande, y es difícil identificar rápidamente "qué se agregó en esta ronda" al ver el Body sin procesar.
+
+Body Diff JSON resuelve exactamente este problema: compara automáticamente los cuerpos de dos solicitudes MainAgent consecutivas, extrae la parte incremental y te permite ver de un vistazo el contenido realmente nuevo en esta solicitud.
+
+## Cómo funciona
+
+1. **Identificar solicitudes MainAgent consecutivas**: La solicitud actual debe ser de tipo MainAgent y debe existir una solicitud MainAgent anterior
+2. **Comparación campo por campo**: Recorre todos los campos de nivel superior del cuerpo de la solicitud, omitiendo las propiedades internas con prefijo `_`
+3. **Extracción inteligente de diferencias**:
+   - Campos nuevos: Se muestran directamente
+   - Campos eliminados: No se muestran (generalmente no afectan la comprensión)
+   - Campos modificados: Se muestra el valor actual
+   - Tratamiento especial del array `messages`: Solo se muestran los mensajes nuevos (ya que en una conversación normal se usa el modo de adición, los mensajes previos no cambian)
+4. **Detección de reducción del cuerpo**: Si el cuerpo actual es más pequeño que el anterior, indica un truncamiento de contexto o reinicio de sesión, y se muestra un mensaje informativo en lugar del diff
+
+## Escenarios típicos
+
+En una ronda normal de conversación, el Body Diff JSON generalmente solo contiene:
+- `messages`: 1~2 mensajes nuevos (la entrada del usuario + la respuesta del asistente de la ronda anterior)
+
+Si ves cambios en `system`, `tools`, `model` u otros campos en el diff, significa que hubo un cambio de configuración en esta ronda, lo cual suele ser también la causa de la reconstrucción de caché.
+
+## Cómo usarlo
+
+- El Body Diff JSON se muestra en el panel de detalles de la solicitud MainAgent
+- Haz clic en el título para expandir/contraer
+- Soporta dos modos de visualización: JSON y Text, además de copiar con un clic
+- En **CC-Viewer → Configuración global** (esquina superior izquierda), puedes configurar "Expandir Body Diff JSON por defecto"

package/concepts/es/BodyFields.md

@@ -0,0 +1,42 @@
+# Campos del cuerpo de la solicitud (Request Body)
+
+Descripción de los campos de nivel superior del cuerpo de la solicitud `/v1/messages` de la API de Claude.
+
+## Lista de campos
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| **model** | string | Nombre del modelo a utilizar, por ejemplo `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Historial de mensajes de la conversación. Cada mensaje contiene `role` (user/assistant) y `content` (un array de bloques como texto, imagen, tool_use, tool_result, etc.) |
+| **system** | array | System prompt. Contiene las instrucciones principales de Codex, directrices de uso de herramientas, información del entorno, contenido de CLAUDE.md, etc. Los bloques con `cache_control` están sujetos a prompt caching |
+| **tools** | array | Lista de definiciones de herramientas disponibles. Cada herramienta contiene `name`, `description` e `input_schema` (JSON Schema). MainAgent normalmente tiene más de 20 herramientas, mientras que SubAgent solo tiene unas pocas |
+| **metadata** | object | Metadatos de la solicitud, generalmente contiene `user_id` para identificar al usuario |
+| **max_tokens** | number | Número máximo de tokens para una respuesta individual del modelo, por ejemplo `16000`, `64000` |
+| **thinking** | object | Configuración de pensamiento extendido. `type: "enabled"` activa el modo de pensamiento, `budget_tokens` controla el límite de tokens de pensamiento |
+| **context_management** | object | Configuración de gestión de contexto. `truncation: "auto"` permite que Codex trunque automáticamente historiales de mensajes demasiado largos |
+| **output_config** | object | Configuración de salida, como ajustes de `format` |
+| **stream** | boolean | Si se habilitan las respuestas en streaming. Codex siempre usa `true` |
+
+## Estructura de messages
+
+El `content` de cada mensaje es un array de bloques. Los tipos comunes incluyen:
+
+- **text**: Contenido de texto plano
+- **tool_use**: Invocación de herramienta por el modelo (contiene `name`, `input`)
+- **tool_result**: Resultado de la ejecución de la herramienta (contiene `tool_use_id`, `content`)
+- **image**: Contenido de imagen (base64 o URL)
+- **thinking**: Proceso de pensamiento del modelo (modo de pensamiento extendido)
+
+## Estructura de system
+
+El array del system prompt normalmente contiene:
+
+1. **Instrucciones principales del agente** ("You are Codex...")
+2. **Directrices de uso de herramientas**
+3. **Contenido de CLAUDE.md** (instrucciones a nivel de proyecto)
+4. **Recordatorios de habilidades** (skills reminder)
+5. **Información del entorno** (SO, shell, estado de git, etc.) — De hecho, Codex depende en gran medida de git. Si un proyecto tiene un repositorio git, Codex demuestra una mejor comprensión del proyecto, incluyendo la capacidad de obtener cambios remotos e historial de commits para asistir en el análisis
+
+Los bloques marcados con `cache_control: { type: "ephemeral" }` son almacenados en caché por la API de Anthropic durante 5 minutos. Cuando se producen aciertos de caché, se facturan como `cache_read_input_tokens` (significativamente más barato que `input_tokens`).
+
+> **Nota**: Para clientes especiales como Codex, el servidor de Anthropic no depende completamente del atributo `cache_control` en la solicitud para determinar el comportamiento de caché. El servidor aplica automáticamente estrategias de caché a campos específicos (como el system prompt y las definiciones de tools), incluso cuando la solicitud no incluye explícitamente marcadores `cache_control`. Por lo tanto, no se sorprenda si no ve este atributo en el cuerpo de la solicitud — el servidor ya ha realizado el almacenamiento en caché entre bastidores, simplemente no expone esta información al cliente. Este es un entendimiento tácito entre Codex y la API de Anthropic.

package/concepts/es/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (Reconstrucción de caché)
+
+## Contexto
+
+El mecanismo de prompt caching de Anthropic concatena secuencialmente system → tools → messages (hasta el cache breakpoint) de la solicitud para formar la clave de caché. Cuando la clave de caché coincide exactamente con la solicitud anterior, la API devuelve `cache_read_input_tokens` (acierto de caché); cuando la clave de caché cambia, la API recrea la caché y devuelve una gran cantidad de `cache_creation_input_tokens`, es decir, una reconstrucción de caché.
+
+La reconstrucción de caché implica facturación adicional de tokens (el precio de cache creation es mayor que el de cache read), por lo que identificar la causa de la reconstrucción tiene valor directo para la optimización de costos.
+
+## Clasificación de causas de reconstrucción de caché
+
+cc-viewer compara los cuerpos de dos solicitudes MainAgent consecutivas para determinar con precisión la causa de la reconstrucción de caché:
+
+| reason | Significado | Método de determinación |
+|--------|-------------|------------------------|
+| `ttl` | Caché expirada | Han pasado más de 5 minutos desde la última solicitud MainAgent |
+| `system_change` | Cambio en el system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Cambio en las definiciones de herramientas | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Cambio de modelo | `prev.model !== curr.model` |
+| `msg_truncated` | Pila de mensajes truncada | La solicitud actual tiene menos mensajes que la anterior, generalmente por truncamiento al desbordar la ventana de contexto |
+| `msg_modified` | Mensajes históricos modificados | El contenido de los mensajes prefijo no coincide (en adición normal, el prefijo debería ser idéntico) |
+| `key_change` | Cambio de clave desconocido | Fallback cuando ninguna de las condiciones anteriores coincide |
+
+## Prioridad de determinación
+
+1. Primero se verifica el intervalo de tiempo — si supera los 5 minutos, se determina directamente como `ttl`, sin comparar el body
+2. Luego se verifican secuencialmente model, system, tools, messages
+3. Una solicitud puede coincidir con múltiples causas simultáneamente (por ejemplo, cambio de modelo + cambio de system prompt), en cuyo caso el array `reasons` contiene todos los elementos coincidentes y el tooltip los muestra en líneas separadas
+
+## Escenarios comunes
+
+- **`ttl`**: El usuario pausó la operación por más de 5 minutos y luego continuó, la caché expiró naturalmente
+- **`system_change`**: Claude Code actualizó el system prompt (por ejemplo, cargó un nuevo CLAUDE.md, cambios en project instructions)
+- **`tools_change`**: La conexión/desconexión de un MCP server causó cambios en la lista de herramientas disponibles
+- **`model_change`**: El usuario cambió de modelo mediante el comando `/model`
+- **`msg_truncated`**: Una conversación larga activó la gestión de la ventana de contexto, Claude Code truncó los mensajes anteriores
+- **`msg_modified`**: Claude Code editó mensajes históricos (por ejemplo, `/compact` reemplazó mensajes originales con resúmenes comprimidos)

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

@@ -0,0 +1,49 @@
+# Contenido de la Caché KV
+
+## ¿Qué es el Prompt Caching?
+
+Cuando conversas con Claude, cada solicitud de API envía el contexto completo de la conversación (prompt del sistema + definiciones de herramientas + mensajes históricos). El mecanismo de prompt caching de Anthropic almacena en caché el contenido del prefijo previamente calculado en el lado del servidor. Si el prefijo de una solicitud posterior coincide, el resultado en caché se reutiliza directamente, omitiendo cálculos redundantes y reduciendo significativamente la latencia y los costos.
+
+En cc-viewer, este mecanismo se denomina "KV-Cache", que corresponde al prompt caching a nivel de API de Anthropic, no a la caché key-value dentro de las capas de atención del transformer del propio LLM.
+
+## Cómo funciona la caché
+
+El prompt caching de Anthropic concatena las claves de caché en un orden fijo:
+
+```
+Herramientas → Prompt del sistema → Mensajes (hasta el punto de ruptura de caché)
+```
+
+Mientras este prefijo coincida exactamente con cualquier solicitud dentro de la ventana TTL, la API accede a la caché (devuelve `cache_read_input_tokens`) en lugar de recalcular (`cache_creation_input_tokens`).
+
+> **Claude Code no depende estrictamente del atributo `cache_control`. El servidor eliminará algunos de estos atributos según corresponda, pero el almacenamiento en caché sigue funcionando correctamente. Por lo tanto, no ver `cache_control` no significa que el contenido no esté en caché.**
+>
+> Para clientes especiales como Claude Code, el servidor de Anthropic no depende completamente del atributo `cache_control` en las solicitudes para determinar el comportamiento de la caché. El servidor aplica automáticamente políticas de caché a campos específicos (como el prompt del sistema y las definiciones de herramientas), incluso cuando la solicitud no incluye explícitamente marcadores `cache_control`. Por lo tanto, cuando no veas este atributo en el cuerpo de la solicitud, no te confundas — el servidor ya ha realizado la operación de caché entre bastidores, simplemente no ha expuesto esta información al cliente. Este es un entendimiento tácito entre Claude Code y la API de Anthropic.
+
+## ¿Qué es el "contenido actual de la caché KV"?
+
+El "contenido actual de la caché KV" mostrado en cc-viewer se extrae de la última solicitud de MainAgent, específicamente el contenido antes del límite de caché (cache breakpoint). Incluye:
+
+- **Prompt del sistema**: Las instrucciones del sistema de Claude Code, incluyendo directivas centrales del agente, especificaciones de uso de herramientas, instrucciones del proyecto CLAUDE.md, información del entorno, etc.
+- **Herramientas**: La lista actual de definiciones de herramientas disponibles (como Read, Write, Bash, Agent, herramientas MCP, etc.)
+- **Mensajes**: La parte del historial de conversación que está almacenada en caché (generalmente mensajes anteriores, hasta el último marcador `cache_control`)
+
+## ¿Por qué consultar el contenido de la caché?
+
+1. **Entender el contexto**: Ver qué contenidos "recuerda" Claude actualmente para evaluar si su comportamiento cumple las expectativas
+2. **Optimización de costos**: Los accesos a caché cuestan mucho menos que el recálculo. Consultar el contenido de la caché te ayuda a entender por qué ciertas solicitudes desencadenaron una reconstrucción de caché
+3. **Depuración de conversaciones**: Cuando las respuestas de Claude no son las esperadas, verificar el contenido de la caché permite confirmar que el prompt del sistema y los mensajes históricos son correctos
+4. **Monitoreo de la calidad del contexto**: Durante la depuración, cambios de configuración o ajustes de prompts, KV-Cache-Text proporciona una vista centralizada para confirmar rápidamente si el contexto principal se ha degradado o ha sido contaminado inesperadamente, sin necesidad de revisar los mensajes brutos uno por uno
+
+## Estrategia de caché multinivel
+
+La KV-Cache correspondiente a Claude Code no es una sola caché. El servidor genera cachés separadas para las Herramientas y el Prompt del sistema, independientes de la caché de Mensajes. La ventaja de este diseño es: cuando la pila de mensajes se corrompe (por ejemplo, truncamiento de contexto, modificación de mensajes) y necesita reconstruirse, no invalida las cachés de Herramientas y Prompt del sistema junto con ella, evitando un recálculo completo.
+
+Esta es una estrategia de optimización actual del lado del servidor, ya que las definiciones de herramientas y el prompt del sistema permanecen relativamente estables durante el uso normal y rara vez cambian. Almacenarlos en caché por separado minimiza la sobrecarga de reconstrucción innecesaria. Por eso, cuando observes la caché, notarás que aparte de las reconstrucciones de herramientas que requieren una actualización completa de la caché, las interrupciones en el prompt del sistema y los mensajes aún tienen cachés heredables disponibles.
+
+## Ciclo de vida de la caché
+
+- **Creación**: En la primera solicitud o después de la expiración de la caché, la API crea una nueva caché (`cache_creation_input_tokens`)
+- **Acceso**: En solicitudes posteriores con un prefijo coincidente, se reutiliza la caché (`cache_read_input_tokens`)
+- **Expiración**: La caché tiene un TTL (tiempo de vida) de 5 minutos y expira automáticamente después de ese tiempo
+- **Reconstrucción**: Cuando el prompt del sistema, la lista de herramientas, el modelo o el contenido de los mensajes cambian, la clave de caché no coincide y desencadena una reconstrucción en el nivel correspondiente

package/concepts/es/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Definición
+
+MainAgent es la cadena de solicitudes principal de Claude Code en estado no agent team. Cada interacción del usuario con Claude Code produce una serie de solicitudes API, donde las solicitudes MainAgent constituyen la cadena de conversación central — llevan el system prompt completo, las definiciones de herramientas y el historial de mensajes.
+
+## Método de identificación
+
+En cc-viewer, MainAgent se identifica mediante `req.mainAgent === true`, marcado automáticamente por `interceptor.js` durante la captura de la solicitud.
+
+Condiciones de determinación (deben cumplirse todas):
+- El cuerpo de la solicitud contiene el campo `system` (system prompt)
+- El cuerpo de la solicitud contiene el array `tools` (definiciones de herramientas)
+- El system prompt contiene texto característico de "Claude Code"
+
+## Diferencias con SubAgent
+
+| Característica | MainAgent | SubAgent |
+|----------------|-----------|----------|
+| system prompt | Prompt principal completo de Claude Code | Prompt simplificado específico para la tarea |
+| Array tools | Contiene todas las herramientas disponibles | Generalmente solo contiene las pocas herramientas necesarias para la tarea |
+| Historial de mensajes | Acumula el contexto completo de la conversación | Solo contiene mensajes relacionados con la subtarea |
+| Comportamiento de caché | Tiene prompt caching (TTL de 5 minutos) | Generalmente sin caché o con caché pequeña |

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

@@ -0,0 +1,25 @@
+# Acceso móvil por código QR
+
+## Cómo funciona
+
+CC Viewer inicia un servidor HTTP y genera una **dirección LAN** (ej: `http://192.168.1.100:7008`). Escanea el código QR para acceder a Claude Code desde tu móvil a través de la misma red WiFi.
+
+## ¿Por qué no puedo conectar?
+
+1. **No están en la misma red** — El móvil y el ordenador deben estar en el mismo WiFi (mismo router/mismo nombre de red)
+2. **Bloqueo del firewall** — El firewall del sistema puede bloquear conexiones entrantes
+3. **Aislamiento de red corporativa** — El aislamiento AP puede impedir la comunicación entre dispositivos
+4. **Interferencia VPN** — Una VPN puede interrumpir la ruta de red
+
+## Aviso de seguridad
+
+> ⚠️ El servicio LAN de CC Viewer es accesible para todos los dispositivos en la misma red.
+
+- Ten cuidado en **WiFi público**
+- CC Viewer usa **autenticación por token** para proteger el acceso LAN
+- Se recomienda usar en redes de confianza
+
+## Más allá de la LAN
+
+- **Herramientas de túnel** — frp, ngrok, Tailscale, etc.
+- **Plugins de CC Viewer** — Configura un proxy middleware mediante el sistema de plugins

package/concepts/es/ResponseFields.md

@@ -0,0 +1,50 @@
+# Referencia de campos del cuerpo de respuesta
+
+Referencia de campos del cuerpo de respuesta de la API de Claude `/v1/messages`.
+
+## Campos de nivel superior
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| **model** | string | Nombre del modelo realmente utilizado, p. ej. `claude-opus-4-6` |
+| **id** | string | Identificador único de esta respuesta, p. ej. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Siempre `"message"` |
+| **role** | string | Siempre `"assistant"` |
+| **content** | array | Array de bloques de contenido generados por el modelo, que incluyen texto, llamadas a herramientas, proceso de pensamiento, etc. |
+| **stop_reason** | string | Razón de la detención: `"end_turn"` (finalización normal), `"tool_use"` (se necesita ejecutar una herramienta), `"max_tokens"` (se alcanzó el límite de tokens) |
+| **stop_sequence** | string/null | La secuencia que provocó la detención, generalmente `null` |
+| **usage** | object | Estadísticas de uso de tokens (ver más abajo) |
+
+## Tipos de bloques de content
+
+| Tipo | Descripción |
+|------|-------------|
+| **text** | Respuesta de texto del modelo, contiene un campo `text` |
+| **tool_use** | Solicitud de llamada a herramienta, contiene `name` (nombre de la herramienta), `input` (parámetros), `id` (ID de la llamada, usado para asociar con tool_result) |
+| **thinking** | Contenido de pensamiento extendido (solo aparece cuando el modo de pensamiento está activado), contiene un campo `thinking` |
+
+## Detalle de campos de usage
+
+| Campo | Descripción |
+|-------|-------------|
+| **input_tokens** | Número de tokens de entrada que no alcanzaron la caché (facturados a precio completo) |
+| **cache_creation_input_tokens** | Número de tokens de nuevas entradas de caché creadas (escritura en caché, facturación superior a la entrada normal) |
+| **cache_read_input_tokens** | Número de tokens que alcanzaron la caché (lectura de caché, facturación mucho menor que la entrada normal) |
+| **output_tokens** | Número de tokens generados por el modelo |
+| **service_tier** | Nivel de servicio, p. ej. `"standard"` |
+| **inference_geo** | Geografía de inferencia, p. ej. `"not_available"` indica que no se proporcionó información geográfica |
+
+## Subcampos de cache_creation
+
+| Campo | Descripción |
+|-------|-------------|
+| **ephemeral_5m_input_tokens** | Número de tokens de creación de caché a corto plazo con TTL de 5 minutos |
+| **ephemeral_1h_input_tokens** | Número de tokens de creación de caché a largo plazo con TTL de 1 hora |
+
+> **Sobre la facturación de caché**: El precio unitario de `cache_read_input_tokens` es mucho menor que el de `input_tokens`, mientras que el precio unitario de `cache_creation_input_tokens` es ligeramente superior al de la entrada normal. Por lo tanto, mantener una alta tasa de aciertos de caché en conversaciones continuas puede reducir significativamente los costos. Puede monitorear visualmente esta proporción a través de la métrica "Tasa de aciertos" en cc-viewer.
+
+## Significado de stop_reason
+
+- **end_turn**: El modelo completó su respuesta normalmente
+- **tool_use**: El modelo necesita llamar a una herramienta; el contenido incluirá un bloque `tool_use`. La siguiente solicitud debe añadir un `tool_result` en los mensajes para continuar la conversación
+- **max_tokens**: La respuesta fue truncada al alcanzar el límite de `max_tokens` y puede estar incompleta

package/concepts/es/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Definición
+
+Search es un tipo de sub-agente generado por el agente principal de Claude Code para realizar búsquedas en el código fuente. Ejecuta búsquedas dirigidas de archivos y contenido usando herramientas como Glob, Grep y Read, y luego devuelve los resultados al agente padre.
+
+## Comportamiento
+
+- Se genera automáticamente cuando el agente principal necesita buscar o explorar el código fuente
+- Se ejecuta en un contexto aislado con acceso de solo lectura
+- Usa Glob para coincidencia de patrones de archivos, Grep para búsqueda de contenido y Read para inspección de archivos
+- Devuelve los resultados de búsqueda al agente padre para su posterior procesamiento
+
+## Cuando aparece
+
+Los sub-agentes Search aparecen típicamente cuando:
+
+1. El agente principal necesita encontrar archivos, funciones o patrones de código específicos
+2. El usuario solicita una exploración amplia del código fuente
+3. El agente investiga dependencias, referencias o patrones de uso

package/concepts/es/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## Definicion
+
+Un Teammate es un agente colaborativo en el modo de equipo de Claude Code Agent. Cuando el agente principal crea un equipo mediante `TeamCreate` y genera teammates usando la herramienta `Agent`, cada teammate se ejecuta como un proceso de agente independiente con su propia ventana de contexto y conjunto de herramientas, comunicandose con los miembros del equipo a traves de `SendMessage`.
+
+## Diferencias con SubAgent
+
+| Caracteristica | Teammate | SubAgent |
+|----------------|----------|----------|
+| Ciclo de vida | Persistente, puede recibir multiples mensajes | Tarea unica, se destruye al completarse |
+| Comunicacion | Mensajeria bidireccional con SendMessage | Llamada unidireccional padre→hijo, devuelve resultado |
+| Contexto | Contexto completo independiente, se conserva entre turnos | Contexto de tarea aislado |
+| Colaboracion | Colaboracion en equipo, pueden comunicarse entre si | Estructura jerarquica, solo interactua con el agente padre |
+| Tipo de tarea | Tareas complejas de multiples pasos | Tareas individuales como busqueda y exploracion |
+
+## Comportamiento
+
+- Creado por el agente principal (team lead) mediante la herramienta `Agent` y asignado a un `team_name`
+- Comparte listas de tareas a traves de `TaskList` / `TaskGet` / `TaskUpdate`
+- Entra en estado idle despues de cada turno, esperando ser activado por un nuevo mensaje
+- Puede ser terminado de forma elegante mediante `shutdown_request`
+
+## Descripcion del panel de estadisticas
+
+El panel de estadisticas de Teammate muestra el numero de llamadas API de cada teammate. La columna `Name` muestra el nombre del teammate (por ejemplo, `reviewer-security`, `reviewer-pipeline`), y la columna `Count` muestra el numero total de solicitudes API generadas por ese teammate.