cx-viewer 1.0.0

package/concepts/es/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — La Maquina de Deseos Definitiva
+
+## Que es UltraPlan
+
+UltraPlan es la **implementacion localizada** de cc-viewer del comando nativo `/ultraplan` de Claude Code. Te permite usar las capacidades completas de `/ultraplan` en tu entorno local **sin necesidad de iniciar el servicio remoto oficial de Claude**, guiando a Claude Code para lograr tareas complejas de planificacion e implementacion mediante **colaboracion multi-agente**.
+
+En comparacion con el modo Plan regular o Agent Team, UltraPlan puede:
+- Evaluar automaticamente la complejidad de la tarea y seleccionar la estrategia de planificacion optima
+- Desplegar multiples agentes en paralelo para explorar la base de codigo desde diferentes dimensiones
+- Incorporar investigacion externa (webSearch) sobre mejores practicas de la industria
+- Ensamblar automaticamente un Code Review Team despues de la ejecucion del plan para revision de codigo
+- Formar un ciclo cerrado completo de **Plan → Execute → Review → Fix**
+
+---
+
+## Notas Importantes
+
+### 1. UltraPlan No Es Omnipotente
+UltraPlan es una maquina de deseos mas poderosa, pero eso no significa que cada deseo pueda cumplirse. Es mas poderoso que Plan y Agent Team, pero no puede directamente "hacerte ganar dinero". Considera una granularidad de tareas razonable — divide los grandes objetivos en tareas medianas ejecutables en lugar de intentar lograrlo todo de una sola vez.
+
+### 2. Actualmente Mas Efectivo para Proyectos de Programacion
+Las plantillas y flujos de trabajo de UltraPlan estan profundamente optimizados para proyectos de programacion. Otros escenarios (documentacion, analisis de datos, etc.) pueden intentarse, pero es recomendable esperar las adaptaciones en versiones futuras.
+
+### 3. Tiempo de Ejecucion y Requisitos de Ventana de Contexto
+- Una ejecucion exitosa de UltraPlan normalmente toma **30 minutos o mas**
+- Requiere que el MainAgent tenga una ventana de contexto grande (se recomienda el modelo Opus con 1M de contexto)
+- Si solo tienes un modelo de 200K, **asegurate de ejecutar `/clear` en el contexto antes de comenzar**
+- El `/compact` de Claude Code funciona mal cuando la ventana de contexto es insuficiente — evita quedarte sin espacio
+- Mantener suficiente espacio de contexto es un prerequisito critico para la ejecucion exitosa de UltraPlan
+
+Si tienes preguntas o sugerencias sobre el UltraPlan localizado, no dudes en abrir [Issues en GitHub](https://github.com/anthropics/claude-code/issues) para discutir y colaborar.
+
+---
+
+## Como Funciona
+
+UltraPlan ofrece dos modos de operacion:
+
+### Modo Automatico
+Analiza automaticamente la complejidad de la tarea (puntuacion 4-12) y enruta a diferentes estrategias:
+
+| Ruta | Puntuacion | Estrategia |
+|------|------------|------------|
+| Ruta A | 4-6 | Planificacion ligera con exploracion directa de codigo |
+| Ruta B | 7-9 | Planificacion con diagramas estructurales (Mermaid / ASCII) |
+| Ruta C | 10-12 | Exploracion multi-agente + ciclo cerrado de revision |
+
+### Modo Forzado
+Activa directamente el flujo de trabajo multi-agente completo de Ruta C:
+1. Desplegar hasta 5 agentes en paralelo para explorar la base de codigo simultaneamente (arquitectura, identificacion de archivos, evaluacion de riesgos, etc.)
+2. Opcionalmente desplegar un agente de investigacion para indagar soluciones de la industria mediante webSearch
+3. Sintetizar todos los hallazgos de los agentes en un plan de implementacion detallado
+4. Desplegar un agente de revision para examinar el plan desde multiples perspectivas
+5. Ejecutar el plan una vez aprobado
+6. Ensamblar automaticamente un Code Review Team para validar la calidad del codigo despues de la implementacion

package/concepts/fr/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (Comparaison incrémentale du corps de la requête)
+
+## Contexte
+
+Le MainAgent de Claude Code utilise un mécanisme d'envoi de contexte complet — chaque requête inclut l'historique complet de la conversation, le system prompt, les définitions d'outils, etc. Cela signifie qu'au fur et à mesure que la conversation progresse, le corps de la requête devient de plus en plus volumineux, et il est difficile d'identifier rapidement « ce qui a été ajouté dans ce tour » en regardant le Body brut.
+
+Body Diff JSON résout exactement ce problème : il compare automatiquement les corps de deux requêtes MainAgent consécutives, extrait la partie incrémentale et vous permet de voir d'un coup d'œil le contenu réellement nouveau dans cette requête.
+
+## Fonctionnement
+
+1. **Identifier les requêtes MainAgent consécutives** : La requête actuelle doit être de type MainAgent et une requête MainAgent précédente doit exister
+2. **Comparaison champ par champ** : Parcourt tous les champs de niveau supérieur du corps de la requête, en ignorant les propriétés internes préfixées par `_`
+3. **Extraction intelligente des différences** :
+   - Champs ajoutés : Affichés directement
+   - Champs supprimés : Non affichés (n'affectent généralement pas la compréhension)
+   - Champs modifiés : La valeur actuelle est affichée
+   - Traitement spécial du tableau `messages` : Seuls les nouveaux messages sont affichés (car en conversation normale, le mode est l'ajout, les messages précédents ne changent pas)
+4. **Détection de réduction du corps** : Si le corps actuel est plus petit que le précédent, cela indique une troncature de contexte ou une réinitialisation de session, et un message informatif est affiché au lieu du diff
+
+## Scénarios typiques
+
+Dans un tour de conversation normal, le Body Diff JSON ne contient généralement que :
+- `messages` : 1~2 nouveaux messages (l'entrée de l'utilisateur + la réponse de l'assistant du tour précédent)
+
+Si vous voyez des changements dans `system`, `tools`, `model` ou d'autres champs dans le diff, cela signifie qu'un changement de configuration a eu lieu dans ce tour, ce qui est souvent aussi la cause de la reconstruction du cache.
+
+## Utilisation
+
+- Le Body Diff JSON est affiché dans le panneau de détails de la requête MainAgent
+- Cliquez sur le titre pour développer/réduire
+- Prend en charge deux modes de visualisation : JSON et Text, ainsi que la copie en un clic
+- Dans **CC-Viewer → Paramètres globaux** (coin supérieur gauche), vous pouvez configurer « Développer le Body Diff JSON par défaut »

package/concepts/fr/BodyFields.md

@@ -0,0 +1,42 @@
+# Champs du corps de la requête (Request Body)
+
+Description des champs de niveau supérieur du corps de la requête `/v1/messages` de l'API Claude.
+
+## Liste des champs
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| **model** | string | Nom du modèle à utiliser, par exemple `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Historique des messages de la conversation. Chaque message contient `role` (user/assistant) et `content` (un tableau de blocs tels que texte, image, tool_use, tool_result, etc.) |
+| **system** | array | System prompt. Contient les instructions principales de Codex, les directives d'utilisation des outils, les informations d'environnement, le contenu de CLAUDE.md, etc. Les blocs avec `cache_control` sont soumis au prompt caching |
+| **tools** | array | Liste des définitions d'outils disponibles. Chaque outil contient `name`, `description` et `input_schema` (JSON Schema). MainAgent dispose généralement de plus de 20 outils, tandis que SubAgent n'en a que quelques-uns |
+| **metadata** | object | Métadonnées de la requête, contenant généralement `user_id` pour identifier l'utilisateur |
+| **max_tokens** | number | Nombre maximum de tokens pour une réponse unique du modèle, par exemple `16000`, `64000` |
+| **thinking** | object | Configuration de la réflexion étendue. `type: "enabled"` active le mode de réflexion, `budget_tokens` contrôle la limite de tokens de réflexion |
+| **context_management** | object | Configuration de la gestion du contexte. `truncation: "auto"` permet à Codex de tronquer automatiquement les historiques de messages trop longs |
+| **output_config** | object | Configuration de sortie, comme les paramètres de `format` |
+| **stream** | boolean | Indique si les réponses en streaming sont activées. Codex utilise toujours `true` |
+
+## Structure de messages
+
+Le `content` de chaque message est un tableau de blocs. Les types courants incluent :
+
+- **text** : Contenu en texte brut
+- **tool_use** : Invocation d'outil par le modèle (contient `name`, `input`)
+- **tool_result** : Résultat de l'exécution de l'outil (contient `tool_use_id`, `content`)
+- **image** : Contenu d'image (base64 ou URL)
+- **thinking** : Processus de réflexion du modèle (mode de réflexion étendue)
+
+## Structure de system
+
+Le tableau du system prompt contient généralement :
+
+1. **Instructions principales de l'agent** ("You are Codex...")
+2. **Directives d'utilisation des outils**
+3. **Contenu de CLAUDE.md** (instructions au niveau du projet)
+4. **Rappels de compétences** (skills reminder)
+5. **Informations d'environnement** (OS, shell, état git, etc.) — En fait, Codex dépend fortement de git. Si un projet dispose d'un dépôt git, Codex démontre une meilleure compréhension du projet, y compris la capacité de récupérer les modifications distantes et l'historique des commits pour assister l'analyse
+
+Les blocs marqués avec `cache_control: { type: "ephemeral" }` sont mis en cache par l'API Anthropic pendant 5 minutes. Lorsque le cache est atteint, la facturation se fait en `cache_read_input_tokens` (nettement moins cher que `input_tokens`).
+
+> **Remarque** : Pour les clients spéciaux comme Codex, le serveur Anthropic ne se base pas entièrement sur l'attribut `cache_control` de la requête pour déterminer le comportement de mise en cache. Le serveur applique automatiquement des stratégies de cache à des champs spécifiques (comme le system prompt et les définitions de tools), même lorsque la requête ne contient pas explicitement de marqueurs `cache_control`. Par conséquent, ne soyez pas surpris si vous ne voyez pas cet attribut dans le corps de la requête — le serveur a déjà effectué la mise en cache en coulisses, il n'expose simplement pas cette information au client. C'est un accord tacite entre Codex et l'API Anthropic.

package/concepts/fr/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (Reconstruction du cache)
+
+## Contexte
+
+Le mécanisme de prompt caching d'Anthropic concatène séquentiellement system → tools → messages (jusqu'au cache breakpoint) de la requête pour former la clé de cache. Lorsque la clé de cache correspond exactement à la requête précédente, l'API renvoie `cache_read_input_tokens` (hit de cache) ; lorsque la clé de cache change, l'API recrée le cache et renvoie une grande quantité de `cache_creation_input_tokens`, c'est-à-dire une reconstruction du cache.
+
+La reconstruction du cache implique une facturation supplémentaire de tokens (le prix du cache creation est supérieur à celui du cache read), donc identifier la cause de la reconstruction a une valeur directe pour l'optimisation des coûts.
+
+## Classification des causes de reconstruction du cache
+
+cc-viewer compare les corps de deux requêtes MainAgent consécutives pour déterminer précisément la cause de la reconstruction du cache :
+
+| reason | Signification | Méthode de détermination |
+|--------|---------------|--------------------------|
+| `ttl` | Cache expiré | Plus de 5 minutes depuis la dernière requête MainAgent |
+| `system_change` | Changement du system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Changement des définitions d'outils | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Changement de modèle | `prev.model !== curr.model` |
+| `msg_truncated` | Pile de messages tronquée | La requête actuelle a moins de messages que la précédente, généralement dû à une troncature lors du dépassement de la fenêtre de contexte |
+| `msg_modified` | Messages historiques modifiés | Le contenu des messages préfixe ne correspond pas (en ajout normal, le préfixe devrait être identique) |
+| `key_change` | Changement de clé inconnu | Fallback lorsqu'aucune des conditions ci-dessus ne correspond |
+
+## Priorité de détermination
+
+1. On vérifie d'abord l'intervalle de temps — s'il dépasse 5 minutes, on détermine directement `ttl`, sans comparer le body
+2. Ensuite on vérifie séquentiellement model, system, tools, messages
+3. Une requête peut correspondre à plusieurs causes simultanément (par exemple, changement de modèle + changement de system prompt), auquel cas le tableau `reasons` contient tous les éléments correspondants et le tooltip les affiche sur des lignes séparées
+
+## Scénarios courants
+
+- **`ttl`** : L'utilisateur a mis en pause l'opération pendant plus de 5 minutes puis a continué, le cache a expiré naturellement
+- **`system_change`** : Claude Code a mis à jour le system prompt (par exemple, chargement d'un nouveau CLAUDE.md, changements dans les project instructions)
+- **`tools_change`** : La connexion/déconnexion d'un MCP server a causé des changements dans la liste des outils disponibles
+- **`model_change`** : L'utilisateur a changé de modèle via la commande `/model`
+- **`msg_truncated`** : Une conversation longue a déclenché la gestion de la fenêtre de contexte, Claude Code a tronqué les messages antérieurs
+- **`msg_modified`** : Claude Code a édité des messages historiques (par exemple, `/compact` a remplacé les messages originaux par des résumés compressés)

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

@@ -0,0 +1,49 @@
+# Contenu du Cache KV
+
+## Qu'est-ce que le Prompt Caching ?
+
+Lorsque tu communiques avec Claude, chaque requete API envoie le contexte complet de la conversation (prompt systeme + definitions d'outils + messages historiques). Le mecanisme de prompt caching d'Anthropic met en cache le contenu du prefixe deja calcule cote serveur. Si le prefixe d'une requete ulterieure correspond, le resultat en cache est reutilise directement, evitant les calculs redondants et reduisant considerablement la latence et les couts.
+
+Dans cc-viewer, ce mecanisme est appele "KV-Cache", correspondant au prompt caching au niveau de l'API d'Anthropic, et non au cache key-value au sein des couches d'attention du transformer du LLM lui-meme.
+
+## Comment fonctionne le cache
+
+Le prompt caching d'Anthropic concatene les cles de cache dans un ordre fixe :
+
+```
+Outils → Prompt systeme → Messages (jusqu'au point de rupture du cache)
+```
+
+Tant que ce prefixe correspond exactement a n'importe quelle requete dans la fenetre TTL, l'API atteint le cache (retourne `cache_read_input_tokens`) au lieu de recalculer (`cache_creation_input_tokens`).
+
+> **Claude Code ne depend pas fortement de l'attribut `cache_control`. Le serveur supprimera certains de ces attributs en consequence, mais la mise en cache fonctionne toujours correctement. Donc ne pas voir `cache_control` ne signifie pas que le contenu n'est pas mis en cache.**
+>
+> Pour les clients speciaux comme Claude Code, le serveur d'Anthropic ne s'appuie pas entierement sur l'attribut `cache_control` dans les requetes pour determiner le comportement de la mise en cache. Le serveur applique automatiquement des politiques de cache a des champs specifiques (comme le prompt systeme et les definitions d'outils), meme lorsque la requete ne contient pas explicitement de marqueurs `cache_control`. Par consequent, lorsque tu ne vois pas cet attribut dans le corps de la requete, ne sois pas perplexe — le serveur a deja effectue l'operation de mise en cache en coulisses, il n'a simplement pas expose cette information au client. C'est une entente tacite entre Claude Code et l'API d'Anthropic.
+
+## Qu'est-ce que le "contenu actuel du cache KV" ?
+
+Le "contenu actuel du cache KV" affiche dans cc-viewer est extrait de la derniere requete MainAgent, specifiquement le contenu avant la limite du cache (cache breakpoint). Il comprend :
+
+- **Prompt systeme** : Les instructions systeme de Claude Code, incluant les directives centrales de l'agent, les specifications d'utilisation des outils, les instructions du projet CLAUDE.md, les informations d'environnement, etc.
+- **Outils** : La liste actuelle des definitions d'outils disponibles (comme Read, Write, Bash, Agent, outils MCP, etc.)
+- **Messages** : La partie mise en cache de l'historique de conversation (generalement les messages anterieurs, jusqu'au dernier marqueur `cache_control`)
+
+## Pourquoi consulter le contenu du cache ?
+
+1. **Comprendre le contexte** : Voir ce que Claude "se souvient" actuellement pour evaluer si son comportement correspond aux attentes
+2. **Optimisation des couts** : Les acces au cache coutent beaucoup moins cher que le recalcul. Consulter le contenu du cache t'aide a comprendre pourquoi certaines requetes ont declenche une reconstruction du cache
+3. **Debogage de conversations** : Quand les reponses de Claude ne correspondent pas aux attentes, verifier le contenu du cache permet de confirmer que le prompt systeme et les messages historiques sont corrects
+4. **Surveillance de la qualite du contexte** : Lors du debogage, des modifications de configuration ou des ajustements de prompt, KV-Cache-Text offre une vue centralisee pour confirmer rapidement si le contexte principal s'est degrade ou a ete pollue de maniere inattendue — sans avoir a examiner les messages bruts un par un
+
+## Strategie de cache multiniveau
+
+Le KV-Cache correspondant a Claude Code n'est pas un cache unique. Le serveur genere des caches separees pour les Outils et le Prompt systeme, independantes du cache des Messages. L'avantage de cette conception est : lorsque la pile de messages est corrompue (par exemple, troncature de contexte, modification de messages) et necessite une reconstruction, cela n'invalide pas les caches des Outils et du Prompt systeme en meme temps, evitant un recalcul complet.
+
+C'est une strategie d'optimisation actuelle cote serveur — car les definitions d'outils et le prompt systeme restent relativement stables pendant l'utilisation normale et changent rarement. Les mettre en cache separement minimise les frais de reconstruction inutiles. Ainsi, lorsque tu observes le cache, tu remarqueras qu'a part les reconstructions d'outils qui necessitent un rafraichissement complet du cache, les perturbations du prompt systeme et des messages disposent toujours de caches heritables disponibles.
+
+## Cycle de vie du cache
+
+- **Creation** : Lors de la premiere requete ou apres l'expiration du cache, l'API cree un nouveau cache (`cache_creation_input_tokens`)
+- **Acces** : Lors des requetes suivantes avec un prefixe correspondant, le cache est reutilise (`cache_read_input_tokens`)
+- **Expiration** : Le cache a une TTL (duree de vie) de 5 minutes et expire automatiquement apres ce delai
+- **Reconstruction** : Quand le prompt systeme, la liste des outils, le modele ou le contenu des messages changent, la cle du cache ne correspond plus et declenche une reconstruction au niveau correspondant

package/concepts/fr/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Définition
+
+MainAgent est la chaîne de requêtes principale de Claude Code en état non agent team. Chaque interaction de l'utilisateur avec Claude Code produit une série de requêtes API, où les requêtes MainAgent constituent la chaîne de conversation centrale — elles portent le system prompt complet, les définitions d'outils et l'historique des messages.
+
+## Méthode d'identification
+
+Dans cc-viewer, MainAgent est identifié par `req.mainAgent === true`, marqué automatiquement par `interceptor.js` lors de la capture de la requête.
+
+Conditions de détermination (toutes doivent être remplies) :
+- Le corps de la requête contient le champ `system` (system prompt)
+- Le corps de la requête contient le tableau `tools` (définitions d'outils)
+- Le system prompt contient le texte caractéristique « Claude Code »
+
+## Différences avec SubAgent
+
+| Caractéristique | MainAgent | SubAgent |
+|-----------------|-----------|----------|
+| system prompt | Prompt principal complet de Claude Code | Prompt simplifié spécifique à la tâche |
+| Tableau tools | Contient tous les outils disponibles | Ne contient généralement que les quelques outils nécessaires à la tâche |
+| Historique des messages | Accumule le contexte complet de la conversation | Ne contient que les messages liés à la sous-tâche |
+| Comportement de cache | A le prompt caching (TTL de 5 minutes) | Généralement sans cache ou avec un cache réduit |

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

@@ -0,0 +1,25 @@
+# Accès mobile par QR code
+
+## Fonctionnement
+
+CC Viewer démarre un serveur HTTP et génère une **adresse LAN** (ex : `http://192.168.1.100:7008`). Scannez le QR code pour accéder à Claude Code depuis votre mobile via le même réseau WiFi.
+
+## Pourquoi la connexion échoue ?
+
+1. **Pas sur le même réseau** — Le mobile et l'ordinateur doivent être sur le même WiFi (même routeur/même nom de réseau)
+2. **Blocage du pare-feu** — Le pare-feu du système peut bloquer les connexions entrantes
+3. **Isolation réseau d'entreprise** — L'isolation AP peut empêcher la communication entre appareils
+4. **Interférence VPN** — Un VPN peut perturber le chemin réseau
+
+## Avis de sécurité
+
+> ⚠️ Le service LAN de CC Viewer est accessible à tous les appareils du même réseau.
+
+- Prudence sur les **WiFi publics**
+- CC Viewer utilise une **authentification par token** pour protéger l'accès LAN
+- Utilisation recommandée sur des réseaux de confiance
+
+## Au-delà du LAN
+
+- **Outils de tunneling** — frp, ngrok, Tailscale, etc.
+- **Plugins CC Viewer** — Configurez un proxy middleware via le système de plugins

package/concepts/fr/ResponseFields.md

@@ -0,0 +1,50 @@
+# Référence des champs du corps de réponse
+
+Référence des champs du corps de réponse de l'API Claude `/v1/messages`.
+
+## Champs de niveau supérieur
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| **model** | string | Nom du modèle réellement utilisé, p. ex. `claude-opus-4-6` |
+| **id** | string | Identifiant unique de cette réponse, p. ex. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Toujours `"message"` |
+| **role** | string | Toujours `"assistant"` |
+| **content** | array | Tableau de blocs de contenu générés par le modèle, contenant du texte, des appels d'outils, le processus de réflexion, etc. |
+| **stop_reason** | string | Raison de l'arrêt : `"end_turn"` (fin normale), `"tool_use"` (exécution d'un outil requise), `"max_tokens"` (limite de tokens atteinte) |
+| **stop_sequence** | string/null | La séquence ayant déclenché l'arrêt, généralement `null` |
+| **usage** | object | Statistiques d'utilisation des tokens (voir ci-dessous) |
+
+## Types de blocs content
+
+| Type | Description |
+|------|-------------|
+| **text** | Réponse textuelle du modèle, contient un champ `text` |
+| **tool_use** | Demande d'appel d'outil, contient `name` (nom de l'outil), `input` (paramètres), `id` (ID de l'appel, utilisé pour associer au tool_result) |
+| **thinking** | Contenu de réflexion étendue (apparaît uniquement lorsque le mode de réflexion est activé), contient un champ `thinking` |
+
+## Détail des champs usage
+
+| Champ | Description |
+|-------|-------------|
+| **input_tokens** | Nombre de tokens d'entrée n'ayant pas atteint le cache (facturés au tarif plein) |
+| **cache_creation_input_tokens** | Nombre de tokens pour les nouvelles entrées de cache créées (écriture en cache, facturation supérieure à l'entrée normale) |
+| **cache_read_input_tokens** | Nombre de tokens ayant atteint le cache (lecture du cache, facturation bien inférieure à l'entrée normale) |
+| **output_tokens** | Nombre de tokens générés par le modèle |
+| **service_tier** | Niveau de service, p. ex. `"standard"` |
+| **inference_geo** | Géographie d'inférence, p. ex. `"not_available"` indique qu'aucune information géographique n'est fournie |
+
+## Sous-champs de cache_creation
+
+| Champ | Description |
+|-------|-------------|
+| **ephemeral_5m_input_tokens** | Nombre de tokens de création de cache à court terme avec un TTL de 5 minutes |
+| **ephemeral_1h_input_tokens** | Nombre de tokens de création de cache à long terme avec un TTL de 1 heure |
+
+> **À propos de la facturation du cache** : Le prix unitaire de `cache_read_input_tokens` est bien inférieur à celui de `input_tokens`, tandis que le prix unitaire de `cache_creation_input_tokens` est légèrement supérieur à celui de l'entrée normale. Par conséquent, maintenir un taux de succès de cache élevé dans les conversations continues peut réduire considérablement les coûts. Vous pouvez surveiller visuellement ce ratio grâce à la métrique « Taux de succès » dans cc-viewer.
+
+## Signification de stop_reason
+
+- **end_turn** : Le modèle a terminé sa réponse normalement
+- **tool_use** : Le modèle doit appeler un outil ; le contenu inclura un bloc `tool_use`. La requête suivante doit ajouter un `tool_result` dans les messages pour poursuivre la conversation
+- **max_tokens** : La réponse a été tronquée en raison de l'atteinte de la limite `max_tokens` et peut être incomplète

package/concepts/fr/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Définition
+
+Search est un type de sous-agent lancé par l'agent principal de Claude Code pour effectuer des recherches dans le code source. Il exécute des recherches ciblées de fichiers et de contenu à l'aide d'outils tels que Glob, Grep et Read, puis renvoie les résultats à l'agent parent.
+
+## Comportement
+
+- Lancé automatiquement lorsque l'agent principal doit rechercher ou explorer le code source
+- S'exécute dans un contexte isolé avec un accès en lecture seule
+- Utilise Glob pour la correspondance de motifs de fichiers, Grep pour la recherche de contenu et Read pour l'inspection de fichiers
+- Renvoie les résultats de recherche à l'agent parent pour un traitement ultérieur
+
+## Quand il apparaît
+
+Les sous-agents Search apparaissent généralement lorsque :
+
+1. L'agent principal doit trouver des fichiers, des fonctions ou des motifs de code spécifiques
+2. L'utilisateur demande une exploration large du code source
+3. L'agent examine des dépendances, des références ou des patterns d'utilisation