cx-viewer 1.0.0

package/concepts/fr/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — La Machine a Voeux Ultime
+
+## Qu'est-ce que UltraPlan
+
+UltraPlan est l'**implementation localisee** par cc-viewer de la commande native `/ultraplan` de Claude Code. Il vous permet d'utiliser les capacites completes de `/ultraplan` dans votre environnement local **sans avoir besoin de lancer le service distant officiel de Claude**, en guidant Claude Code pour accomplir des taches complexes de planification et d'implementation en utilisant la **collaboration multi-agents**.
+
+Par rapport au mode Plan classique ou a Agent Team, UltraPlan peut :
+- Evaluer automatiquement la complexite de la tache et selectionner la strategie de planification optimale
+- Deployer plusieurs agents en parallele pour explorer la base de code sous differentes dimensions
+- Integrer la recherche externe (webSearch) pour les meilleures pratiques de l'industrie
+- Assembler automatiquement une Code Review Team apres l'execution du plan pour la revue de code
+- Former une boucle fermee complete **Plan → Execute → Review → Fix**
+
+---
+
+## Notes Importantes
+
+### 1. UltraPlan N'est Pas Omnipotent
+UltraPlan est une machine a voeux plus puissante, mais cela ne signifie pas que chaque voeu peut etre exauce. Il est plus puissant que Plan et Agent Team, mais ne peut pas directement « vous faire gagner de l'argent ». Considerez une granularite de taches raisonnable — decomposez les grands objectifs en taches moyennes executables plutot que d'essayer de tout accomplir en une seule fois.
+
+### 2. Actuellement Plus Efficace pour les Projets de Programmation
+Les modeles et flux de travail d'UltraPlan sont profondement optimises pour les projets de programmation. D'autres scenarios (documentation, analyse de donnees, etc.) peuvent etre tentes, mais il est conseille d'attendre les adaptations des versions futures.
+
+### 3. Temps d'Execution et Exigences de Fenetre de Contexte
+- Une execution reussie d'UltraPlan prend generalement **30 minutes ou plus**
+- Necessite que le MainAgent dispose d'une grande fenetre de contexte (modele Opus avec 1M de contexte recommande)
+- Si vous ne disposez que d'un modele 200K, **assurez-vous de faire `/clear` sur le contexte avant l'execution**
+- Le `/compact` de Claude Code fonctionne mal lorsque la fenetre de contexte est insuffisante — evitez de manquer d'espace
+- Maintenir un espace de contexte suffisant est un prerequis essentiel pour la reussite de l'execution d'UltraPlan
+
+Si vous avez des questions ou des suggestions concernant l'UltraPlan localise, n'hesitez pas a ouvrir des [Issues sur GitHub](https://github.com/anthropics/claude-code/issues) pour discuter et collaborer.
+
+---
+
+## Fonctionnement
+
+UltraPlan propose deux modes de fonctionnement :
+
+### Mode Automatique
+Analyse automatiquement la complexite de la tache (score 4-12) et oriente vers differentes strategies :
+
+| Route | Score | Strategie |
+|-------|-------|-----------|
+| Route A | 4-6 | Planification legere avec exploration directe du code |
+| Route B | 7-9 | Planification avec diagrammes structurels (Mermaid / ASCII) |
+| Route C | 10-12 | Exploration multi-agents + boucle fermee de revue |
+
+### Mode Force
+Active directement le flux de travail multi-agents complet de la Route C :
+1. Deployer jusqu'a 5 agents en parallele pour explorer simultanement la base de code (architecture, identification des fichiers, evaluation des risques, etc.)
+2. Optionnellement deployer un agent de recherche pour investiguer les solutions de l'industrie via webSearch
+3. Synthetiser toutes les decouvertes des agents en un plan d'implementation detaille
+4. Deployer un agent de revue pour examiner le plan sous plusieurs perspectives
+5. Executer le plan une fois approuve
+6. Assembler automatiquement une Code Review Team pour valider la qualite du code apres l'implementation

package/concepts/it/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (confronto incrementale del corpo della richiesta)
+
+## Contesto
+
+Il MainAgent di Claude Code utilizza un meccanismo di invio del contesto completo: ogni richiesta include l'intera cronologia della conversazione, il system prompt, le definizioni degli strumenti, ecc. Ciò significa che, man mano che la conversazione procede, il corpo della richiesta diventa sempre più grande, rendendo difficile individuare rapidamente "cosa è stato aggiunto in questo turno" esaminando il Body grezzo.
+
+Body Diff JSON è stato creato proprio per risolvere questo problema: confronta automaticamente i body di due richieste MainAgent consecutive, estraendo la parte incrementale, permettendoti di vedere a colpo d'occhio il contenuto effettivamente aggiunto in questa richiesta.
+
+## Come funziona
+
+1. **Identificazione delle richieste MainAgent consecutive**: la richiesta corrente deve essere di tipo MainAgent e deve esistere una richiesta MainAgent precedente
+2. **Confronto campo per campo**: vengono esaminati tutti i campi di primo livello del corpo della richiesta, saltando le proprietà interne con prefisso `_`
+3. **Estrazione intelligente delle differenze**:
+   - Campi aggiunti: mostrati direttamente
+   - Campi rimossi: non mostrati (generalmente non influenzano la comprensione)
+   - Campi modificati: viene mostrato il valore corrente
+   - Trattamento speciale dell'array `messages`: vengono mostrati solo i messaggi aggiunti (poiché in una conversazione normale i messaggi vengono accodati e il prefisso rimane invariato)
+4. **Rilevamento della riduzione del corpo**: se il corpo della richiesta corrente è più piccolo del precedente, significa che si è verificato un troncamento del contesto o un reset della sessione; in tal caso viene mostrato un messaggio informativo anziché il diff
+
+## Scenari tipici
+
+In un turno di conversazione normale, il Body Diff JSON contiene solitamente solo:
+- `messages`: 1~2 messaggi aggiunti (l'input dell'utente + la risposta dell'assistente del turno precedente)
+
+Se nel diff compaiono modifiche a campi come `system`, `tools`, `model`, significa che in questo turno si è verificata una modifica della configurazione, che spesso è anche la causa della ricostruzione della cache.
+
+## Modalità d'uso
+
+- Il Body Diff JSON viene mostrato nel pannello dei dettagli della richiesta MainAgent
+- Clicca sul titolo per espandere/comprimere
+- Supporta due modalità di visualizzazione, JSON e Text, oltre alla copia con un clic
+- In alto a sinistra, in **CC-Viewer → Impostazioni globali**, puoi impostare "Espandi Body Diff JSON per impostazione predefinita"

package/concepts/it/BodyFields.md

@@ -0,0 +1,42 @@
+# Descrizione dei campi del Request Body
+
+Descrizione dei campi di primo livello del corpo della richiesta dell'API Claude `/v1/messages`.
+
+## Elenco dei campi
+
+| Campo | Tipo | Descrizione |
+|-------|------|-------------|
+| **model** | string | Nome del modello utilizzato, ad es. `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Cronologia dei messaggi della conversazione. Ogni messaggio contiene `role` (user/assistant) e `content` (un array di blocchi: testo, immagini, tool_use, tool_result ecc.) |
+| **system** | array | System prompt. Contiene le istruzioni principali di Codex, le istruzioni per l'uso degli strumenti, le informazioni sull'ambiente, i contenuti di CLAUDE.md ecc. I blocchi con `cache_control` vengono memorizzati nella cache tramite prompt caching |
+| **tools** | array | Elenco delle definizioni degli strumenti disponibili. Ogni strumento contiene `name`, `description` e `input_schema` (JSON Schema). Il MainAgent ha tipicamente 20+ strumenti, i SubAgent ne hanno solo pochi |
+| **metadata** | object | Metadati della richiesta, tipicamente contiene `user_id` per identificare l'utente |
+| **max_tokens** | number | Numero massimo di token per singola risposta del modello, ad es. `16000`, `64000` |
+| **thinking** | object | Configurazione del pensiero esteso. `type: "enabled"` attiva la modalità di pensiero, `budget_tokens` controlla il limite di token per il pensiero |
+| **context_management** | object | Configurazione della gestione del contesto. `truncation: "auto"` consente a Codex di troncare automaticamente cronologie di messaggi troppo lunghe |
+| **output_config** | object | Configurazione dell'output, ad es. impostazioni di `format` |
+| **stream** | boolean | Se le risposte in streaming sono abilitate. Codex utilizza sempre `true` |
+
+## Struttura di messages
+
+Il `content` di ogni messaggio è un array di blocchi con i seguenti tipi comuni:
+
+- **text**: Contenuto testuale normale
+- **tool_use**: Il modello invoca uno strumento (contiene `name`, `input`)
+- **tool_result**: Risultato dell'esecuzione dello strumento (contiene `tool_use_id`, `content`)
+- **image**: Contenuto immagine (base64 o URL)
+- **thinking**: Processo di pensiero del modello (modalità di pensiero esteso)
+
+## Struttura di system
+
+L'array del system prompt contiene tipicamente:
+
+1. **Istruzioni principali dell'agent** ("You are Codex...")
+2. **Specifiche per l'uso degli strumenti**
+3. **Contenuti di CLAUDE.md** (istruzioni a livello di progetto)
+4. **Promemoria delle skill** (skills reminder)
+5. **Informazioni sull'ambiente** (OS, shell, stato di git ecc.) — Di fatto, Codex dipende fortemente da git. Se nel progetto esiste un repository git, Codex riesce a dimostrare una migliore comprensione del progetto, inclusa la possibilità di recuperare modifiche remote e cronologie di commit per supportare l'analisi
+
+I blocchi contrassegnati con `cache_control: { type: "ephemeral" }` vengono memorizzati nella cache dall'API Anthropic per 5 minuti. Quando la cache viene utilizzata, la fatturazione avviene tramite `cache_read_input_tokens` (molto inferiore rispetto a `input_tokens`).
+
+> **Nota**: Per client speciali come Codex, il server Anthropic in realtà non si basa completamente sull'attributo `cache_control` nella richiesta per determinare il comportamento della cache. Il server esegue automaticamente strategie di caching per campi specifici (come il system prompt e le definizioni degli strumenti), anche quando la richiesta non contiene esplicitamente il marcatore `cache_control`. Pertanto, quando non vedete questo attributo nel corpo della richiesta, non c'è motivo di preoccuparsi: il server ha già eseguito le operazioni di caching dietro le quinte, senza esporre queste informazioni al client. Questa è una sorta di intesa tacita tra Codex e l'API Anthropic.

package/concepts/it/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (ricostruzione della cache)
+
+## Contesto
+
+Il meccanismo di prompt caching di Anthropic concatena in sequenza system → tools → messages (fino al cache breakpoint) della richiesta come chiave di cache. Quando la chiave di cache corrisponde esattamente alla richiesta precedente, l'API restituisce `cache_read_input_tokens` (cache hit); quando la chiave di cache cambia, l'API ricrea la cache, restituendo un gran numero di `cache_creation_input_tokens`, ovvero una ricostruzione della cache.
+
+La ricostruzione della cache comporta costi aggiuntivi di token (il prezzo della cache creation è superiore a quello della cache read), pertanto identificare la causa della ricostruzione ha un valore diretto per l'ottimizzazione dei costi.
+
+## Classificazione delle cause di ricostruzione della cache
+
+cc-viewer confronta i body di due richieste MainAgent consecutive per determinare con precisione la causa della ricostruzione della cache:
+
+| reason | Significato | Metodo di determinazione |
+|--------|------|----------|
+| `ttl` | Cache scaduta | Sono trascorsi più di 5 minuti dall'ultima richiesta MainAgent |
+| `system_change` | Modifica del system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Modifica delle definizioni degli strumenti | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Cambio di modello | `prev.model !== curr.model` |
+| `msg_truncated` | Stack dei messaggi troncato | Il numero di messaggi della richiesta corrente è inferiore a quello della richiesta precedente, solitamente causato dal troncamento per overflow della finestra di contesto |
+| `msg_modified` | Modifica dei messaggi storici | Il contenuto dei messaggi prefisso non è coerente (durante l'accodamento normale il prefisso dovrebbe essere identico) |
+| `key_change` | Modifica di chiave sconosciuta | Fallback quando nessuna delle condizioni precedenti corrisponde |
+
+## Priorità di determinazione
+
+1. Prima si controlla l'intervallo di tempo — se supera i 5 minuti, si determina direttamente `ttl`, senza confronto del body
+2. Poi si controllano in sequenza model, system, tools, messages
+3. Una richiesta può corrispondere a più cause contemporaneamente (es. cambio di modello + modifica del system prompt); in tal caso l'array `reasons` contiene tutti gli elementi corrispondenti e il tooltip li mostra su righe separate
+
+## Scenari comuni
+
+- **`ttl`**: l'utente ha interrotto le operazioni per più di 5 minuti e poi ha ripreso, la cache è scaduta naturalmente
+- **`system_change`**: Claude Code ha aggiornato il system prompt (es. caricamento di un nuovo CLAUDE.md, modifica delle project instructions)
+- **`tools_change`**: la connessione/disconnessione di un MCP server ha causato una modifica della lista degli strumenti disponibili
+- **`model_change`**: l'utente ha cambiato modello tramite il comando `/model`
+- **`msg_truncated`**: una conversazione troppo lunga ha attivato la gestione della finestra di contesto, Claude Code ha troncato i messaggi precedenti
+- **`msg_modified`**: Claude Code ha modificato i messaggi storici (es. `/compact` ha sostituito i messaggi originali con un riepilogo compresso)

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

@@ -0,0 +1,49 @@
+# Contenuto della KV-Cache
+
+## Cos'e il Prompt Caching?
+
+Quando comunichi con Claude, ogni richiesta API invia l'intero contesto della conversazione (system prompt + definizioni degli strumenti + cronologia dei messaggi). Il meccanismo di prompt caching di Anthropic memorizza sul server i contenuti del prefisso gia calcolati. Se le richieste successive hanno lo stesso prefisso, i risultati memorizzati vengono riutilizzati direttamente, saltando i calcoli ridondanti e riducendo significativamente latenza e costi.
+
+In cc-viewer questo meccanismo viene chiamato "KV-Cache" e corrisponde al prompt caching a livello di API Anthropic, non alla key-value cache interna dei livelli di attenzione del transformer dell'LLM.
+
+## Come funziona il caching
+
+Il prompt caching di Anthropic costruisce la chiave di cache in un ordine fisso:
+
+```
+Tools → System Prompt → Messages (fino al cache breakpoint)
+```
+
+Finche questo prefisso corrisponde esattamente a una richiesta precedente all'interno della finestra TTL, l'API restituira un cache hit (`cache_read_input_tokens`) invece di ricalcolare (`cache_creation_input_tokens`).
+
+> **Claude Code non dipende strettamente dall'attributo `cache_control`. Il server rimuove parzialmente questi attributi, ma riesce comunque a creare la cache efficacemente. Quindi l'assenza dell'attributo `cache_control` non significa che il contenuto non sia stato memorizzato nella cache.**
+>
+> Per client speciali come Claude Code, il server di Anthropic non si basa completamente sull'attributo `cache_control` nella richiesta per determinare il comportamento della cache. Il server esegue automaticamente strategie di caching per campi specifici (come system prompt e definizioni degli strumenti), anche quando la richiesta non contiene marcatori `cache_control` espliciti. Pertanto, se non vedi questo attributo nel corpo della richiesta, non c'e motivo di preoccupazione: il server ha gia completato l'operazione di caching dietro le quinte, semplicemente non espone questa informazione al client. Questa e un'intesa tacita tra Claude Code e l'API di Anthropic.
+
+## Cos'e il "contenuto attuale della KV-Cache"?
+
+Il "contenuto attuale della KV-Cache" mostrato in cc-viewer viene estratto dall'ultima richiesta del MainAgent e include il contenuto che precede il confine della cache (cache breakpoint). Nello specifico comprende:
+
+- **System Prompt**: le istruzioni di sistema di Claude Code, incluse le istruzioni principali dell'agent, le specifiche d'uso degli strumenti, le istruzioni del progetto CLAUDE.md, le informazioni sull'ambiente, ecc.
+- **Tools**: l'elenco delle definizioni degli strumenti attualmente disponibili (come Read, Write, Bash, Agent, strumenti MCP, ecc.)
+- **Messages**: la porzione memorizzata della cronologia della conversazione (tipicamente i messaggi piu vecchi, fino all'ultimo marcatore `cache_control`)
+
+## Perche visualizzare il contenuto della cache?
+
+1. **Comprendere il contesto**: scopri quali contenuti Claude ha attualmente "in memoria" per valutare se il suo comportamento corrisponde alle aspettative
+2. **Ottimizzazione dei costi**: i cache hit costano molto meno dei ricalcoli. Visualizzare il contenuto della cache aiuta a capire perche certe richieste hanno attivato una ricostruzione della cache (cache rebuild)
+3. **Debug delle conversazioni**: quando le risposte di Claude non corrispondono alle aspettative, controllare il contenuto della cache permette di verificare che il system prompt e la cronologia dei messaggi siano corretti
+4. **Monitoraggio della qualita del contesto**: durante il debug, la modifica delle configurazioni o la regolazione dei prompt, il KV-Cache-Text offre una vista centralizzata che ti aiuta a verificare rapidamente se il contesto principale si e degradato o e stato contaminato da contenuti inattesi, senza dover scorrere manualmente ogni singolo messaggio originale
+
+## Strategia di caching multilivello
+
+La KV-Cache di Claude Code non e composta da un'unica cache. Il server genera cache separate per Tools e System Prompt, indipendenti dalla cache dei Messages. Il vantaggio di questo design e che quando lo stack dei messaggi presenta problemi (come troncamento del contesto, modifiche ai messaggi, ecc.) e necessita di ricostruzione, le cache di Tools e System Prompt non vengono invalidate insieme, evitando un ricalcolo completo.
+
+Questa e una strategia di ottimizzazione attuale del server: poiche le definizioni degli strumenti e il system prompt sono relativamente stabili durante l'uso normale e cambiano raramente, memorizzarli separatamente nella cache riduce al minimo il sovracosto di ricostruzioni non necessarie. Osservando la cache noterai che, a parte la ricostruzione dei Tools (che richiede il refresh completo della cache), le modifiche al System Prompt e ai Messages hanno comunque cache ereditabili disponibili.
+
+## Ciclo di vita della cache
+
+- **Creazione**: alla prima richiesta o dopo l'invalidazione della cache, l'API crea una nuova cache (`cache_creation_input_tokens`)
+- **Hit**: le richieste successive con prefisso identico riutilizzano la cache (`cache_read_input_tokens`)
+- **Scadenza**: la cache ha un TTL (Time to Live) di 5 minuti e scade automaticamente al termine
+- **Ricostruzione**: quando il system prompt, l'elenco degli strumenti, il modello o il contenuto dei messaggi cambiano, la chiave di cache non corrisponde piu e viene attivata una ricostruzione della cache al livello corrispondente

package/concepts/it/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Definizione
+
+MainAgent è la catena di richieste principale di Claude Code quando non è in modalità agent team. Ogni interazione dell'utente con Claude Code genera una serie di richieste API, tra cui le richieste MainAgent costituiscono la catena di conversazione principale — trasportano il system prompt completo, le definizioni degli strumenti e la cronologia dei messaggi.
+
+## Metodo di identificazione
+
+In cc-viewer, MainAgent è identificato tramite `req.mainAgent === true`, contrassegnato automaticamente da `interceptor.js` al momento della cattura della richiesta.
+
+Condizioni di determinazione (tutte devono essere soddisfatte):
+- Il corpo della richiesta contiene il campo `system` (system prompt)
+- Il corpo della richiesta contiene l'array `tools` (definizioni degli strumenti)
+- Il system prompt contiene il testo caratteristico "Claude Code"
+
+## Differenze rispetto al SubAgent
+
+| Caratteristica | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | Prompt principale completo di Claude Code | Prompt semplificato specifico per il task |
+| Array tools | Contiene tutti gli strumenti disponibili | Solitamente contiene solo i pochi strumenti necessari per il task |
+| Cronologia messaggi | Accumula il contesto completo della conversazione | Contiene solo i messaggi relativi al sotto-task |
+| Comportamento cache | Ha prompt caching (TTL di 5 minuti) | Solitamente senza cache o con cache ridotta |

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

@@ -0,0 +1,25 @@
+# Accesso mobile tramite QR code
+
+## Come funziona
+
+CC Viewer avvia un server HTTP e genera un **indirizzo LAN** (es: `http://192.168.1.100:7008`). Scansiona il QR code per accedere a Claude Code dal tuo smartphone tramite la stessa rete WiFi.
+
+## Perché non riesco a connettermi?
+
+1. **Non sulla stessa rete** — Smartphone e computer devono essere sulla stessa rete WiFi (stesso router/stesso nome di rete)
+2. **Blocco firewall** — Il firewall del sistema potrebbe bloccare le connessioni in entrata
+3. **Isolamento rete aziendale** — L'isolamento AP può impedire la comunicazione tra dispositivi
+4. **Interferenza VPN** — Una VPN può interrompere il percorso di rete
+
+## Avviso di sicurezza
+
+> ⚠️ Il servizio LAN di CC Viewer è accessibile a tutti i dispositivi sulla stessa rete.
+
+- Attenzione nelle **reti WiFi pubbliche**
+- CC Viewer utilizza **autenticazione tramite token** per proteggere l'accesso LAN
+- Si consiglia l'uso su reti affidabili
+
+## Oltre la LAN
+
+- **Strumenti di tunneling** — frp, ngrok, Tailscale, ecc.
+- **Plugin CC Viewer** — Configura un proxy middleware tramite il sistema di plugin

package/concepts/it/ResponseFields.md

@@ -0,0 +1,50 @@
+# Descrizione dei campi del Response Body
+
+Descrizione dei campi del corpo della risposta dell'API Claude `/v1/messages`.
+
+## Campi di primo livello
+
+| Campo | Tipo | Descrizione |
+|-------|------|-------------|
+| **model** | string | Nome del modello effettivamente utilizzato, ad es. `claude-opus-4-6` |
+| **id** | string | Identificatore univoco di questa risposta, ad es. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Sempre `"message"` |
+| **role** | string | Sempre `"assistant"` |
+| **content** | array | Array dei blocchi di contenuto prodotti dal modello, inclusi testo, chiamate a tool, processo di pensiero, ecc. |
+| **stop_reason** | string | Motivo dell'arresto: `"end_turn"` (completamento normale), `"tool_use"` (necessaria esecuzione di un tool), `"max_tokens"` (raggiunto il limite di token) |
+| **stop_sequence** | string/null | La sequenza che ha attivato l'arresto, di solito `null` |
+| **usage** | object | Statistiche di utilizzo dei token (vedi sotto) |
+
+## Tipi di blocco content
+
+| Tipo | Descrizione |
+|------|-------------|
+| **text** | Risposta testuale del modello, contiene il campo `text` |
+| **tool_use** | Richiesta di chiamata a un tool, contiene `name` (nome del tool), `input` (parametri), `id` (ID della chiamata, usato per associare il tool_result) |
+| **thinking** | Contenuto del pensiero esteso (appare solo con la modalità thinking attivata), contiene il campo `thinking` |
+
+## Dettaglio dei campi usage
+
+| Campo | Descrizione |
+|-------|-------------|
+| **input_tokens** | Numero di token di input non presenti nella cache (addebitati a prezzo pieno) |
+| **cache_creation_input_tokens** | Numero di token per cui è stata creata una nuova cache in questa richiesta (scrittura cache, costo superiore all'input normale) |
+| **cache_read_input_tokens** | Numero di token letti dalla cache (lettura cache, costo molto inferiore all'input normale) |
+| **output_tokens** | Numero di token prodotti dal modello |
+| **service_tier** | Livello di servizio, ad es. `"standard"` |
+| **inference_geo** | Regione di inferenza, ad es. `"not_available"` indica che l'informazione sulla regione non è disponibile |
+
+## Sottocampi di cache_creation
+
+| Campo | Descrizione |
+|-------|-------------|
+| **ephemeral_5m_input_tokens** | Numero di token per la creazione di cache a breve termine con TTL di 5 minuti |
+| **ephemeral_1h_input_tokens** | Numero di token per la creazione di cache a lungo termine con TTL di 1 ora |
+
+> **Sulla tariffazione della cache**: Il prezzo unitario di `cache_read_input_tokens` è molto inferiore a quello di `input_tokens`, mentre il prezzo unitario di `cache_creation_input_tokens` è leggermente superiore a quello dell'input normale. Pertanto, mantenere un alto tasso di hit della cache nelle conversazioni continuative può ridurre significativamente i costi. Tramite la metrica "tasso di hit" di cc-viewer è possibile monitorare visivamente questa proporzione.
+
+## Significato di stop_reason
+
+- **end_turn**: Il modello ha completato normalmente la risposta
+- **tool_use**: Il modello deve chiamare un tool; content conterrà un blocco `tool_use`. Nella richiesta successiva è necessario aggiungere un `tool_result` nei messages per continuare la conversazione
+- **max_tokens**: Raggiunto il limite `max_tokens`, la risposta è stata troncata e potrebbe essere incompleta

package/concepts/it/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Definizione
+
+Search è un tipo di sotto-agente avviato dall'agente principale di Claude Code per eseguire ricerche nel codice sorgente. Esegue ricerche mirate di file e contenuto utilizzando strumenti come Glob, Grep e Read, quindi restituisce i risultati all'agente padre.
+
+## Comportamento
+
+- Avviato automaticamente quando l'agente principale deve cercare o esplorare il codice sorgente
+- Viene eseguito in un contesto isolato con accesso in sola lettura
+- Usa Glob per la corrispondenza di pattern di file, Grep per la ricerca di contenuto e Read per l'ispezione di file
+- Restituisce i risultati della ricerca all'agente padre per ulteriore elaborazione
+
+## Quando appare
+
+I sotto-agenti Search appaiono tipicamente quando:
+
+1. L'agente principale deve trovare file, funzioni o pattern di codice specifici
+2. L'utente richiede un'esplorazione ampia del codice sorgente
+3. L'agente sta esaminando dipendenze, riferimenti o pattern di utilizzo