cx-viewer 1.0.0

package/concepts/de/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (Inkrementeller Request-Body-Vergleich)
+
+## Hintergrund
+
+Der MainAgent von Claude Code verwendet einen Vollkontext-Sendemechanismus – jede Anfrage enthält den vollständigen Gesprächsverlauf, System-Prompt, Tool-Definitionen usw. Das bedeutet, dass der Request-Body im Laufe des Gesprächs immer größer wird und es schwierig ist, im Roh-Body schnell zu erkennen, „was in dieser Runde tatsächlich neu hinzugekommen ist".
+
+Body Diff JSON löst genau dieses Problem: Es vergleicht automatisch die Bodies zweier aufeinanderfolgender MainAgent-Anfragen, extrahiert die inkrementellen Teile und zeigt auf einen Blick, welche Inhalte in dieser Anfrage tatsächlich neu sind.
+
+## Funktionsweise
+
+1. **Erkennung aufeinanderfolgender MainAgent-Anfragen**: Die aktuelle Anfrage muss vom Typ MainAgent sein, und es muss eine vorherige MainAgent-Anfrage existieren
+2. **Feldweiser Vergleich**: Alle Top-Level-Felder des Request-Body werden durchlaufen, interne Attribute mit `_`-Präfix werden übersprungen
+3. **Intelligente Differenzextraktion**:
+   - Neue Felder: werden direkt angezeigt
+   - Gelöschte Felder: werden nicht angezeigt (beeinträchtigen normalerweise nicht das Verständnis)
+   - Geänderte Felder: zeigen den aktuellen Wert
+   - `messages`-Array wird speziell behandelt: Es werden nur neue Nachrichten angezeigt (da im normalen Gespräch Nachrichten angehängt werden und die Präfix-Nachrichten unverändert bleiben)
+4. **Erkennung einer Verkleinerung des Request-Body**: Wenn der aktuelle Request-Body kleiner ist als der vorherige, deutet dies auf eine Kontextkürzung oder Sitzungszurücksetzung hin – in diesem Fall wird ein Hinweis statt eines Diffs angezeigt
+
+## Typische Szenarien
+
+In einer normalen Gesprächsrunde enthält Body Diff JSON normalerweise nur:
+- `messages`: 1–2 neue Nachrichten (Benutzereingabe + Antwort des Assistenten aus der vorherigen Runde)
+
+Wenn im Diff Änderungen an Feldern wie `system`, `tools`, `model` usw. erscheinen, bedeutet dies, dass sich die Konfiguration in dieser Runde geändert hat – was oft auch der Grund für einen Cache-Rebuild ist.
+
+## Verwendung
+
+- Body Diff JSON wird im Detailbereich der MainAgent-Anfrage angezeigt
+- Klicken Sie auf den Titel zum Auf-/Zuklappen
+- Unterstützt JSON- und Text-Ansichtsmodi sowie Ein-Klick-Kopieren
+- Unter **CC-Viewer → Globale Einstellungen** (oben links) können Sie „Body Diff JSON standardmäßig aufklappen" einstellen

package/concepts/de/BodyFields.md

@@ -0,0 +1,42 @@
+# Beschreibung der Request-Body-Felder
+
+Beschreibung der Top-Level-Felder des Request-Bodys der Claude API `/v1/messages`.
+
+## Feldliste
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| **model** | string | Name des verwendeten Modells, z. B. `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Nachrichtenverlauf der Konversation. Jede Nachricht enthält `role` (user/assistant) und `content` (ein Block-Array aus Text, Bildern, tool_use, tool_result usw.) |
+| **system** | array | System-Prompt. Enthält die Kernanweisungen von Codex, Anweisungen zur Tool-Nutzung, Umgebungsinformationen, CLAUDE.md-Inhalte usw. Blöcke mit `cache_control` werden durch Prompt-Caching zwischengespeichert |
+| **tools** | array | Liste der verfügbaren Tool-Definitionen. Jedes Tool enthält `name`, `description` und `input_schema` (JSON Schema). Der MainAgent hat typischerweise 20+ Tools, SubAgents nur wenige |
+| **metadata** | object | Anfrage-Metadaten, enthält typischerweise `user_id` zur Benutzeridentifikation |
+| **max_tokens** | number | Maximale Token-Anzahl pro Modellantwort, z. B. `16000`, `64000` |
+| **thinking** | object | Konfiguration des erweiterten Denkens. `type: "enabled"` aktiviert den Denkmodus, `budget_tokens` steuert das Token-Limit für das Denken |
+| **context_management** | object | Konfiguration der Kontextverwaltung. `truncation: "auto"` erlaubt Codex, zu lange Nachrichtenverläufe automatisch zu kürzen |
+| **output_config** | object | Ausgabekonfiguration, z. B. `format`-Einstellungen |
+| **stream** | boolean | Ob Streaming-Antworten aktiviert sind. Codex verwendet immer `true` |
+
+## messages-Struktur
+
+Der `content` jeder Nachricht ist ein Block-Array mit folgenden gängigen Typen:
+
+- **text**: Normaler Textinhalt
+- **tool_use**: Modell ruft ein Tool auf (enthält `name`, `input`)
+- **tool_result**: Ergebnis der Tool-Ausführung (enthält `tool_use_id`, `content`)
+- **image**: Bildinhalt (Base64 oder URL)
+- **thinking**: Denkprozess des Modells (erweiterter Denkmodus)
+
+## system-Struktur
+
+Das System-Prompt-Array enthält typischerweise:
+
+1. **Kern-Agent-Anweisungen** ("You are Codex...")
+2. **Regeln zur Tool-Nutzung**
+3. **CLAUDE.md-Inhalte** (projektspezifische Anweisungen)
+4. **Skill-Hinweise** (Skills Reminder)
+5. **Umgebungsinformationen** (OS, Shell, Git-Status usw.) — Tatsächlich ist Codex stark von Git abhängig. Wenn ein Git-Repository im Projekt vorhanden ist, kann Codex ein besseres Verständnis des Projekts zeigen, einschließlich der Möglichkeit, Remote-Änderungen und Commit-Verläufe zur Analyse heranzuziehen
+
+Blöcke mit der Markierung `cache_control: { type: "ephemeral" }` werden von der Anthropic API 5 Minuten lang zwischengespeichert. Bei einem Cache-Treffer wird mit `cache_read_input_tokens` abgerechnet (deutlich günstiger als `input_tokens`).
+
+> **Hinweis**: Bei speziellen Clients wie Codex verlässt sich der Anthropic-Server tatsächlich nicht vollständig auf das `cache_control`-Attribut in der Anfrage, um das Caching-Verhalten zu bestimmen. Der Server führt automatisch Caching-Strategien für bestimmte Felder aus (wie System-Prompt, Tool-Definitionen), auch wenn die Anfrage keine explizite `cache_control`-Markierung enthält. Wenn Sie dieses Attribut also nicht im Request-Body sehen, brauchen Sie sich nicht zu wundern — der Server hat das Caching bereits im Hintergrund durchgeführt, ohne diese Information dem Client offenzulegen. Dies ist eine Art stillschweigende Übereinkunft zwischen Codex und der Anthropic API.

package/concepts/de/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (Cache-Neuaufbau)
+
+## Hintergrund
+
+Der Prompt-Caching-Mechanismus von Anthropic verkettet system → tools → messages (bis zum Cache-Breakpoint) in der Anfrage sequenziell zu einem Cache-Schlüssel. Wenn der Cache-Schlüssel mit der vorherigen Anfrage exakt übereinstimmt, gibt die API `cache_read_input_tokens` zurück (Cache-Treffer); wenn sich der Cache-Schlüssel ändert, erstellt die API den Cache neu und gibt eine große Anzahl von `cache_creation_input_tokens` zurück – das ist der Cache-Neuaufbau.
+
+Ein Cache-Neuaufbau bedeutet zusätzliche Token-Kosten (Cache Creation ist teurer als Cache Read), daher hat die Identifizierung der Neuaufbau-Ursachen direkten Wert für die Kostenoptimierung.
+
+## Klassifizierung der Cache-Neuaufbau-Ursachen
+
+cc-viewer vergleicht die Bodies zweier aufeinanderfolgender MainAgent-Anfragen und bestimmt präzise die Ursache des Cache-Neuaufbaus:
+
+| reason | Bedeutung | Erkennungsmethode |
+|--------|-----------|-------------------|
+| `ttl` | Cache abgelaufen | Mehr als 5 Minuten seit der letzten MainAgent-Anfrage |
+| `system_change` | System-Prompt geändert | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Tool-Definitionen geändert | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Modellwechsel | `prev.model !== curr.model` |
+| `msg_truncated` | Nachrichtenstapel gekürzt | Die aktuelle Anfrage hat weniger Messages als die vorherige, typischerweise ausgelöst durch Kontextfenster-Überlauf |
+| `msg_modified` | Verlaufsnachrichten geändert | Präfix-Nachrichten stimmen nicht überein (beim normalen Anhängen sollte das Präfix identisch sein) |
+| `key_change` | Unbekannte Schlüsseländerung | Fallback, wenn keine der obigen Bedingungen zutrifft |
+
+## Prioritätsreihenfolge
+
+1. Zuerst wird das Zeitintervall geprüft – über 5 Minuten wird direkt als `ttl` eingestuft, ohne Body-Vergleich
+2. Dann werden nacheinander model, system, tools, messages geprüft
+3. Eine Anfrage kann mehrere Ursachen gleichzeitig auslösen (z.B. Modellwechsel + System-Prompt-Änderung), wobei das `reasons`-Array alle Treffer enthält und der Tooltip sie zeilenweise anzeigt
+
+## Häufige Szenarien
+
+- **`ttl`**: Der Benutzer pausiert länger als 5 Minuten und setzt dann fort – der Cache läuft natürlich ab
+- **`system_change`**: Claude Code hat den System-Prompt aktualisiert (z.B. neue CLAUDE.md geladen, Project Instructions geändert)
+- **`tools_change`**: MCP-Server-Verbindung/-Trennung führt zu Änderungen in der verfügbaren Tool-Liste
+- **`model_change`**: Der Benutzer wechselt das Modell über den `/model`-Befehl
+- **`msg_truncated`**: Ein zu langes Gespräch löst die Kontextfenster-Verwaltung aus, Claude Code kürzt frühere Nachrichten
+- **`msg_modified`**: Claude Code hat Verlaufsnachrichten bearbeitet (z.B. `/compact` ersetzt Originalnachrichten durch komprimierte Zusammenfassungen)

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

@@ -0,0 +1,49 @@
+# KV-Cache-Inhalt
+
+## Was ist Prompt Caching?
+
+Wenn du mit Claude kommunizierst, wird bei jeder API-Anfrage der vollständige Gesprächskontext gesendet (System Prompt + Tool-Definitionen + Nachrichtenverlauf). Der Prompt-Caching-Mechanismus von Anthropic speichert bereits berechnete Präfix-Inhalte serverseitig. Wenn nachfolgende Anfragen denselben Präfix haben, werden die zwischengespeicherten Ergebnisse direkt wiederverwendet, wodurch redundante Berechnungen übersprungen und Latenz sowie Kosten erheblich reduziert werden.
+
+In cc-viewer wird dieser Mechanismus als „KV-Cache" bezeichnet und entspricht dem Prompt Caching auf Anthropic-API-Ebene – nicht dem Key-Value-Cache der internen Transformer-Attention-Schichten des LLM.
+
+## Wie Caching funktioniert
+
+Das Prompt Caching von Anthropic erstellt den Cache-Schlüssel in fester Reihenfolge:
+
+```
+Tools → System Prompt → Messages (bis zum Cache-Breakpoint)
+```
+
+Solange dieser Präfix innerhalb des TTL-Fensters mit einer früheren Anfrage vollständig übereinstimmt, wird der Cache getroffen (Rückgabe von `cache_read_input_tokens`), anstatt neu zu berechnen (`cache_creation_input_tokens`).
+
+> **Claude Code ist nicht zwingend auf das `cache_control`-Attribut angewiesen. Die Serverseite entfernt teilweise diese Attribute, kann aber dennoch gut Caches erstellen. Das Fehlen des `cache_control`-Attributs bedeutet also nicht, dass kein Caching stattfindet.**
+>
+> Für spezielle Clients wie Claude Code verlässt sich die Serverseite von Anthropic nicht vollständig auf das `cache_control`-Attribut in der Anfrage, um das Caching-Verhalten zu bestimmen. Der Server führt automatisch Caching-Strategien für bestimmte Felder aus (wie System Prompt und Tool-Definitionen), auch wenn die Anfrage keine expliziten `cache_control`-Markierungen enthält. Wenn du dieses Attribut also nicht im Request Body siehst, besteht kein Grund zur Verwirrung – der Server hat das Caching bereits im Hintergrund durchgeführt, diese Information wird dem Client nur nicht offengelegt. Dies ist eine stillschweigende Vereinbarung zwischen Claude Code und der Anthropic-API.
+
+## Was ist der „aktuelle KV-Cache-Inhalt"?
+
+Der in cc-viewer angezeigte „aktuelle KV-Cache-Inhalt" wird aus der letzten MainAgent-Anfrage extrahiert und umfasst den Inhalt vor der Cache-Grenze (Cache-Breakpoint). Im Einzelnen beinhaltet er:
+
+- **System Prompt**: Die Systemanweisungen von Claude Code, einschließlich grundlegender Agent-Anweisungen, Tool-Nutzungsrichtlinien, CLAUDE.md-Projektanweisungen, Umgebungsinformationen usw.
+- **Tools**: Die Liste der aktuell verfügbaren Tool-Definitionen (wie Read, Write, Bash, Agent, MCP-Tools usw.)
+- **Messages**: Der zwischengespeicherte Teil des Nachrichtenverlaufs (typischerweise ältere Nachrichten bis zur letzten `cache_control`-Markierung)
+
+## Warum sollte man den Cache-Inhalt ansehen?
+
+1. **Kontext verstehen**: Erfahre, welche Inhalte Claude aktuell „im Gedächtnis" hat, um zu beurteilen, ob sein Verhalten den Erwartungen entspricht
+2. **Kostenoptimierung**: Cache-Treffer sind deutlich günstiger als Neuberechnungen. Die Ansicht des Cache-Inhalts hilft zu verstehen, warum bestimmte Anfragen einen Cache-Neuaufbau (Cache Rebuild) ausgelöst haben
+3. **Gespräche debuggen**: Wenn Claudes Antworten nicht den Erwartungen entsprechen, kannst du den Cache-Inhalt überprüfen, um sicherzustellen, dass System Prompt und Nachrichtenverlauf korrekt sind
+4. **Kontextqualitäts-Monitoring**: Beim Debuggen, Ändern von Konfigurationen oder Anpassen von Prompts bietet der KV-Cache-Text eine zentrale Ansicht, die dir hilft, schnell zu überprüfen, ob der Kernkontext degradiert ist oder durch unerwartete Inhalte verunreinigt wurde – ohne die Originalnachrichten einzeln durchsehen zu müssen
+
+## Mehrstufige Caching-Strategie
+
+Der KV-Cache von Claude Code besteht nicht nur aus einem einzigen Cache. Die Serverseite erstellt separate Caches für Tools und System Prompt, unabhängig vom Messages-Cache. Der Vorteil dieses Designs: Wenn der Messages-Stack Probleme aufweist (z. B. Kontextabschneidung, Nachrichtenänderungen usw.) und neu aufgebaut werden muss, werden die Caches für Tools und System Prompt nicht mit invalidiert, wodurch eine vollständige Neuberechnung vermieden wird.
+
+Dies ist eine aktuelle serverseitige Optimierungsstrategie – da Tool-Definitionen und System Prompt im normalen Betrieb relativ stabil sind und sich selten ändern, minimiert das separate Caching unnötigen Neuaufbau-Overhead. Wenn du den Cache beobachtest, wirst du feststellen, dass außer bei einem Neuaufbau der Tools (der den gesamten Cache neu erstellen erfordert) bei Änderungen am System Prompt oder an den Messages immer noch vererbbare Caches zur Verfügung stehen.
+
+## Lebenszyklus des Caches
+
+- **Erstellung**: Bei der ersten Anfrage oder nach Cache-Invalidierung erstellt die API einen neuen Cache (`cache_creation_input_tokens`)
+- **Treffer**: Nachfolgende Anfragen mit identischem Präfix verwenden den Cache wieder (`cache_read_input_tokens`)
+- **Ablauf**: Der Cache hat eine TTL (Time to Live) von 5 Minuten und wird nach Ablauf automatisch ungültig
+- **Neuaufbau**: Wenn sich System Prompt, Tool-Liste, Modell oder Nachrichteninhalte ändern, stimmt der Cache-Schlüssel nicht mehr überein und löst einen Cache-Neuaufbau der entsprechenden Ebene aus

package/concepts/de/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Definition
+
+MainAgent ist die Hauptanfragekette von Claude Code im Nicht-Agent-Team-Modus. Jede Interaktion eines Benutzers mit Claude Code erzeugt eine Reihe von API-Anfragen, wobei die MainAgent-Anfragen die Kern-Gesprächskette bilden – sie tragen den vollständigen System-Prompt, Tool-Definitionen und Nachrichtenverlauf.
+
+## Erkennung
+
+In cc-viewer wird MainAgent durch `req.mainAgent === true` identifiziert und von `interceptor.js` beim Abfangen der Anfrage automatisch markiert.
+
+Erkennungsbedingungen (alle müssen erfüllt sein):
+- Der Request-Body enthält das `system`-Feld (System-Prompt)
+- Der Request-Body enthält das `tools`-Array (Tool-Definitionen)
+- Der System-Prompt enthält den charakteristischen Text "Claude Code"
+
+## Unterschied zu SubAgent
+
+| Merkmal | MainAgent | SubAgent |
+|---------|-----------|----------|
+| System-Prompt | Vollständiger Claude Code Haupt-Prompt | Kompakter aufgabenspezifischer Prompt |
+| tools-Array | Enthält alle verfügbaren Tools | Enthält normalerweise nur die wenigen für die Aufgabe benötigten Tools |
+| Nachrichtenverlauf | Akkumuliert den vollständigen Gesprächskontext | Enthält nur aufgabenbezogene Nachrichten |
+| Cache-Verhalten | Hat Prompt Caching (5 Minuten TTL) | Normalerweise kein Cache oder kleinerer Cache |

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

@@ -0,0 +1,25 @@
+# Mobiler QR-Code-Zugang
+
+## Funktionsweise
+
+CC Viewer startet einen HTTP-Server und generiert eine **LAN-Adresse** (z.B. `http://192.168.1.100:7008`). Scannen Sie den QR-Code, um über dasselbe WiFi-Netzwerk von Ihrem Smartphone auf Claude Code zuzugreifen.
+
+## Warum kann ich keine Verbindung herstellen?
+
+1. **Nicht im selben Netzwerk** — Smartphone und Computer müssen mit demselben WiFi verbunden sein (gleicher Router/gleicher Netzwerkname)
+2. **Firewall-Blockierung** — Die OS-Firewall blockiert möglicherweise eingehende Verbindungen
+3. **Unternehmensnetzwerk-Isolation** — AP-Isolation kann die Kommunikation zwischen Geräten verhindern
+4. **VPN-Störung** — Ein VPN kann den Netzwerkpfad stören
+
+## Sicherheitshinweis
+
+> ⚠️ Der LAN-Dienst von CC Viewer ist für alle Geräte im selben Netzwerk zugänglich.
+
+- Vorsicht bei **öffentlichem WiFi**
+- CC Viewer verwendet **Token-Authentifizierung** zum Schutz des LAN-Zugriffs
+- Verwendung in vertrauenswürdigen Netzwerken empfohlen
+
+## Über das LAN hinaus
+
+- **Tunneling-Tools** — frp, ngrok, Tailscale usw.
+- **CC Viewer Plugins** — Proxy-Middleware über das Plugin-System konfigurieren

package/concepts/de/ResponseFields.md

@@ -0,0 +1,50 @@
+# Beschreibung der Response-Body-Felder
+
+Feldbeschreibung des Antwortkörpers der Claude API `/v1/messages`.
+
+## Felder der obersten Ebene
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| **model** | string | Der tatsächlich verwendete Modellname, z. B. `claude-opus-4-6` |
+| **id** | string | Eindeutiger Bezeichner dieser Antwort, z. B. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Immer `"message"` |
+| **role** | string | Immer `"assistant"` |
+| **content** | array | Array der vom Modell ausgegebenen Inhaltsblöcke, einschließlich Text, Tool-Aufrufe, Denkprozess usw. |
+| **stop_reason** | string | Stoppgrund: `"end_turn"` (normal beendet), `"tool_use"` (Tool-Ausführung erforderlich), `"max_tokens"` (Token-Limit erreicht) |
+| **stop_sequence** | string/null | Die auslösende Stoppsequenz, normalerweise `null` |
+| **usage** | object | Token-Verbrauchsstatistik (siehe unten) |
+
+## content-Blocktypen
+
+| Typ | Beschreibung |
+|-----|--------------|
+| **text** | Textantwort des Modells, enthält das Feld `text` |
+| **tool_use** | Tool-Aufrufanfrage, enthält `name` (Tool-Name), `input` (Parameter), `id` (Aufruf-ID, zur Zuordnung von tool_result) |
+| **thinking** | Erweiterter Denkinhalt (erscheint nur bei aktiviertem Thinking-Modus), enthält das Feld `thinking` |
+
+## usage-Felder im Detail
+
+| Feld | Beschreibung |
+|------|--------------|
+| **input_tokens** | Anzahl der nicht aus dem Cache gelesenen Eingabe-Token (werden zum vollen Preis berechnet) |
+| **cache_creation_input_tokens** | Anzahl der Token, für die in dieser Anfrage ein neuer Cache erstellt wurde (Cache-Schreibvorgang, höhere Kosten als normale Eingabe) |
+| **cache_read_input_tokens** | Anzahl der aus dem Cache gelesenen Token (Cache-Lesevorgang, deutlich günstiger als normale Eingabe) |
+| **output_tokens** | Anzahl der vom Modell ausgegebenen Token |
+| **service_tier** | Servicestufe, z. B. `"standard"` |
+| **inference_geo** | Inferenz-Region, z. B. `"not_available"` bedeutet, dass keine Regionsinformation verfügbar ist |
+
+## cache_creation-Unterfelder
+
+| Feld | Beschreibung |
+|------|--------------|
+| **ephemeral_5m_input_tokens** | Anzahl der Token für kurzlebige Cache-Erstellung mit 5 Minuten TTL |
+| **ephemeral_1h_input_tokens** | Anzahl der Token für langlebige Cache-Erstellung mit 1 Stunde TTL |
+
+> **Zur Cache-Berechnung**: Der Einzelpreis von `cache_read_input_tokens` liegt deutlich unter dem von `input_tokens`, während der Einzelpreis von `cache_creation_input_tokens` etwas über dem normaler Eingabe liegt. Daher kann eine hohe Cache-Trefferquote in fortlaufenden Gesprächen die Kosten erheblich senken. Mit der Kennzahl "Trefferquote" in cc-viewer lässt sich dieses Verhältnis anschaulich überwachen.
+
+## Bedeutung von stop_reason
+
+- **end_turn**: Das Modell hat die Antwort normal abgeschlossen
+- **tool_use**: Das Modell muss ein Tool aufrufen; content enthält einen `tool_use`-Block. In der nächsten Anfrage muss ein `tool_result` in messages angehängt werden, um das Gespräch fortzusetzen
+- **max_tokens**: Das `max_tokens`-Limit wurde erreicht und die Antwort wurde abgeschnitten; die Antwort ist möglicherweise unvollständig

package/concepts/de/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Definition
+
+Search ist ein Sub-Agent-Typ, der vom Haupt-Agent von Claude Code gestartet wird, um Codebase-Suchen durchzuführen. Er führt gezielte Datei- und Inhaltssuchen mit Tools wie Glob, Grep und Read aus und gibt die Ergebnisse anschließend an den übergeordneten Agent zurück.
+
+## Verhalten
+
+- Wird automatisch gestartet, wenn der Haupt-Agent die Codebase durchsuchen oder erkunden muss
+- Läuft in einem isolierten Kontext mit ausschließlich Lesezugriff
+- Verwendet Glob für Datei-Musterabgleiche, Grep für die Inhaltssuche und Read für die Dateiinspektion
+- Gibt Suchergebnisse zur weiteren Verarbeitung an den übergeordneten Agent zurück
+
+## Wann er erscheint
+
+Search-Sub-Agents erscheinen typischerweise wenn:
+
+1. Der Haupt-Agent bestimmte Dateien, Funktionen oder Codemuster finden muss
+2. Eine umfassende Codebase-Erkundung vom Benutzer angefordert wird
+3. Der Agent Abhängigkeiten, Referenzen oder Verwendungsmuster untersucht

package/concepts/de/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## Definition
+
+Ein Teammate ist ein kollaborativer Agent im Team-Modus von Claude Code Agent. Wenn der Haupt-Agent ein Team mit `TeamCreate` erstellt und Teammates mit dem `Agent`-Tool erzeugt, lauft jeder Teammate als unabhangiger Agent-Prozess mit eigenem Kontextfenster und Toolset und kommuniziert uber `SendMessage` mit den Teammitgliedern.
+
+## Unterschied zu SubAgent
+
+| Merkmal | Teammate | SubAgent |
+|---------|----------|----------|
+| Lebenszyklus | Bleibt bestehen, kann mehrfach Nachrichten empfangen | Einmalige Aufgabe, wird nach Abschluss zerstort |
+| Kommunikation | SendMessage bidirektionale Nachrichten | Eltern->Kind unidirektionaler Aufruf, Ergebnis zuruckgeben |
+| Kontext | Unabhangiger vollstandiger Kontext, bleibt uber Runden hinweg erhalten | Isolierter Aufgabenkontext |
+| Zusammenarbeit | Teamarbeit, gegenseitige Kommunikation moglich | Hierarchische Struktur, Interaktion nur mit dem ubergeordneten Agent |
+| Aufgabentyp | Komplexe mehrstufige Aufgaben | Einzelaufgaben wie Suche, Erkundung |
+
+## Verhalten
+
+- Wird vom Haupt-Agent (Team Lead) uber das `Agent`-Tool erstellt und einem `team_name` zugewiesen
+- Teilt die Aufgabenliste uber `TaskList` / `TaskGet` / `TaskUpdate`
+- Wechselt nach jeder Ausfuhrungsrunde in den Idle-Zustand und wartet auf neue Nachrichten zur Aktivierung
+- Kann uber `shutdown_request` ordnungsgemas beendet werden
+
+## Erlauterung zum Statistik-Panel
+
+Das Teammate-Statistik-Panel zeigt die Anzahl der API-Aufrufe fur jeden Teammate an. Die Spalte `Name` enthalt den Teammate-Namen (z. B. `reviewer-security`, `reviewer-pipeline`), die Spalte `Anzahl` die Gesamtzahl der API-Anfragen dieses Teammates.