cx-viewer 1.0.0

package/concepts/pl/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (przyrostowe porównanie treści żądania)
+
+## Kontekst
+
+MainAgent w Claude Code stosuje mechanizm wysyłania pełnego kontekstu — każde żądanie zawiera kompletną historię rozmowy, system prompt, definicje narzędzi itp. Oznacza to, że w miarę postępu rozmowy treść żądania staje się coraz większa, a bezpośrednie przeglądanie surowego Body utrudnia szybkie zlokalizowanie „co dokładnie zostało dodane w tej turze".
+
+Body Diff JSON rozwiązuje właśnie ten problem: automatycznie porównuje treści dwóch kolejnych żądań MainAgent, wyodrębnia przyrostowe zmiany i pozwala od razu zobaczyć, co faktycznie zostało dodane w bieżącym żądaniu.
+
+## Zasada działania
+
+1. **Identyfikacja kolejnych żądań MainAgent**: bieżące żądanie musi być typu MainAgent i musi istnieć poprzednie żądanie MainAgent
+2. **Porównanie pole po polu**: iteracja po wszystkich polach najwyższego poziomu w treści żądania, z pominięciem wewnętrznych właściwości z prefiksem `_`
+3. **Inteligentne wyodrębnianie różnic**:
+   - Nowe pola: wyświetlane bezpośrednio
+   - Usunięte pola: nie są wyświetlane (zazwyczaj nie wpływają na zrozumienie)
+   - Zmienione pola: wyświetlana jest bieżąca wartość
+   - Tablica `messages` — specjalne traktowanie: wyświetlane są tylko nowe wiadomości (ponieważ w normalnej rozmowie wiadomości są dopisywane, a prefiks pozostaje bez zmian)
+4. **Wykrywanie zmniejszenia treści żądania**: jeśli bieżące żądanie jest mniejsze od poprzedniego, oznacza to obcięcie kontekstu lub reset sesji — w takim przypadku wyświetlany jest komunikat informacyjny zamiast diff
+
+## Typowe scenariusze
+
+W normalnej turze rozmowy Body Diff JSON zazwyczaj zawiera tylko:
+- `messages`: 1–2 nowe wiadomości (dane wejściowe użytkownika + odpowiedź asystenta z poprzedniej tury)
+
+Jeśli w diff pojawiają się zmiany pól `system`, `tools`, `model` itp., oznacza to zmianę konfiguracji w bieżącej turze, co często jest również przyczyną przebudowy cache.
+
+## Sposób użycia
+
+- Body Diff JSON jest wyświetlany w panelu szczegółów żądania MainAgent
+- Kliknięcie nagłówka rozwija/zwija zawartość
+- Obsługuje tryby podglądu JSON i Text oraz kopiowanie jednym kliknięciem
+- W lewym górnym rogu **CC-Viewer → Ustawienia globalne** można ustawić „Domyślnie rozwiń Body Diff JSON"

package/concepts/pl/BodyFields.md

@@ -0,0 +1,42 @@
+# Opis pol Request Body
+
+Opis pol najwyzszego poziomu w request body Claude API `/v1/messages`.
+
+## Lista pol
+
+| Pole | Typ | Opis |
+|------|------|------|
+| **model** | string | Nazwa uzytego modelu, np. `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Historia wiadomosci w konwersacji. Kazda wiadomosc zawiera `role` (user/assistant) i `content` (tablica blokow: tekst, obrazy, tool_use, tool_result itp.) |
+| **system** | array | System prompt. Zawiera glowne instrukcje Codex, wskazowki dotyczace uzycia narzedzi, informacje o srodowisku, zawartosc CLAUDE.md itp. Bloki z `cache_control` sa buforowane przez prompt caching |
+| **tools** | array | Lista definicji dostepnych narzedzi. Kazde narzedzie zawiera `name`, `description` i `input_schema` (JSON Schema). MainAgent ma zwykle 20+ narzedzi, SubAgent ma tylko kilka |
+| **metadata** | object | Metadane zadania, zwykle zawiera `user_id` do identyfikacji uzytkownika |
+| **max_tokens** | number | Maksymalna liczba tokenow w pojedynczej odpowiedzi modelu, np. `16000`, `64000` |
+| **thinking** | object | Konfiguracja rozszerzonego myslenia. `type: "enabled"` wlacza tryb myslenia, `budget_tokens` kontroluje gorny limit tokenow myslenia |
+| **context_management** | object | Konfiguracja zarzadzania kontekstem. `truncation: "auto"` pozwala Codex automatycznie obcinac zbyt dluga historie wiadomosci |
+| **output_config** | object | Konfiguracja wyjscia, np. ustawienia `format` |
+| **stream** | boolean | Czy wlaczyc odpowiedzi strumieniowe. Codex zawsze uzywa `true` |
+
+## Struktura messages
+
+`content` kazdej wiadomosci to tablica blokow, typowe typy:
+
+- **text**: Zwykla zawartosc tekstowa
+- **tool_use**: Model wywoluje narzedzie (zawiera `name`, `input`)
+- **tool_result**: Wynik wykonania narzedzia (zawiera `tool_use_id`, `content`)
+- **image**: Zawartosc obrazu (base64 lub URL)
+- **thinking**: Proces myslenia modelu (tryb rozszerzonego myslenia)
+
+## Struktura system
+
+Tablica system prompt zwykle zawiera:
+
+1. **Glowne instrukcje agenta** ("You are Codex...")
+2. **Zasady uzycia narzedzi**
+3. **Zawartosc CLAUDE.md** (instrukcje na poziomie projektu)
+4. **Przypomnienia o umiejetnosciach** (skills reminder)
+5. **Informacje o srodowisku** (OS, shell, status git itp.) — w rzeczywistosci Codex jest bardzo zalezny od git. Jesli projekt posiada repozytorium git, Codex moze wykazac lepsze zrozumienie projektu, w tym pobierac zdalne zmiany i historie commitow do analizy
+
+Bloki oznaczone `cache_control: { type: "ephemeral" }` sa buforowane przez Anthropic API przez 5 minut. Przy trafieniu w bufor sa rozliczane jako `cache_read_input_tokens` (znacznie taniej niz `input_tokens`).
+
+> **Uwaga**: W przypadku specjalizowanych klientow takich jak Codex, serwer Anthropic w rzeczywistosci nie polega calkowicie na atrybucie `cache_control` w zadaniu do okreslenia zachowania buforowania. Serwer automatycznie stosuje strategie buforowania dla okreslonych pol (takich jak system prompt i definicje tools), nawet jesli zadanie nie zawiera jawnie znacznika `cache_control`. Dlatego nie musisz sie dziwic, gdy nie widzisz tego atrybutu w request body — serwer juz wykonal operacje buforowania za kulisami, po prostu nie ujawnia tej informacji klientowi. To milczace porozumienie miedzy Codex a Anthropic API.

package/concepts/pl/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (przebudowa cache)
+
+## Kontekst
+
+Mechanizm prompt caching Anthropic łączy system → tools → messages (do punktu przerwania cache) w klucz cache. Gdy klucz cache jest identyczny z poprzednim żądaniem, API zwraca `cache_read_input_tokens` (trafienie cache); gdy klucz cache się zmieni, API tworzy cache od nowa, zwracając dużą liczbę `cache_creation_input_tokens`, czyli przebudowę cache.
+
+Przebudowa cache oznacza dodatkowe koszty tokenów (cena cache creation jest wyższa niż cache read), dlatego identyfikacja przyczyn przebudowy ma bezpośrednią wartość dla optymalizacji kosztów.
+
+## Klasyfikacja przyczyn przebudowy cache
+
+cc-viewer porównuje treści dwóch kolejnych żądań MainAgent, aby precyzyjnie określić przyczynę przebudowy cache:
+
+| reason | Znaczenie | Sposób określenia |
+|--------|------|----------|
+| `ttl` | Cache wygasł | Od poprzedniego żądania MainAgent upłynęło ponad 5 minut |
+| `system_change` | Zmiana system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Zmiana definicji narzędzi | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Zmiana modelu | `prev.model !== curr.model` |
+| `msg_truncated` | Obcięcie stosu wiadomości | Bieżące żądanie ma mniej wiadomości niż poprzednie, zazwyczaj z powodu obcięcia wywołanego przepełnieniem okna kontekstu |
+| `msg_modified` | Modyfikacja historii wiadomości | Treść wiadomości prefiksowych jest niespójna (przy normalnym dopisywaniu prefiks powinien być identyczny) |
+| `key_change` | Nieznana zmiana klucza | Fallback, gdy żaden z powyższych warunków nie pasuje |
+
+## Priorytet określania
+
+1. Najpierw sprawdzany jest odstęp czasowy — ponad 5 minut oznacza bezpośrednio `ttl`, bez porównywania treści
+2. Następnie kolejno sprawdzane są: model, system, tools, messages
+3. Jedno żądanie może jednocześnie spełniać wiele przyczyn (np. zmiana modelu + zmiana system prompt), wtedy tablica `reasons` zawiera wszystkie pasujące elementy, a tooltip wyświetla je w osobnych wierszach
+
+## Typowe scenariusze
+
+- **`ttl`**: użytkownik wstrzymał pracę na ponad 5 minut, cache naturalnie wygasł
+- **`system_change`**: Claude Code zaktualizował system prompt (np. załadowanie nowego CLAUDE.md, zmiana instrukcji projektu)
+- **`tools_change`**: połączenie/rozłączenie serwera MCP spowodowało zmianę listy dostępnych narzędzi
+- **`model_change`**: użytkownik przełączył model poleceniem `/model`
+- **`msg_truncated`**: zbyt długi dialog wywołał zarządzanie oknem kontekstu, Claude Code obciął wcześniejsze wiadomości
+- **`msg_modified`**: Claude Code edytował historyczne wiadomości (np. `/compact` zastąpił oryginalne wiadomości skompresowanym podsumowaniem)

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

@@ -0,0 +1,49 @@
+# Zawartość pamięci podręcznej KV-Cache
+
+## Czym jest Prompt Caching?
+
+Gdy rozmawiasz z Claude, każde żądanie API wysyła pełny kontekst konwersacji (system prompt + definicje narzędzi + historia wiadomości). Mechanizm prompt caching Anthropica buforuje na serwerze już obliczoną zawartość prefiksu, a jeśli prefiks jest taki sam przy kolejnych żądaniach, wynik z pamięci podręcznej jest bezpośrednio wykorzystywany ponownie, pomijając powtórne obliczenia i znacząco redukując opóźnienia i koszty.
+
+W cc-viewer mechanizm ten nazywany jest "KV-Cache" i odpowiada prompt cachingowi na poziomie Anthropic API — a nie pamięci podręcznej key-value w warstwach uwagi transformera wewnątrz LLM.
+
+## Jak działa pamięć podręczna
+
+Prompt caching Anthropica łączy klucze pamięci podręcznej w stałej kolejności:
+
+```
+Tools → System Prompt → Messages (do cache breakpoint)
+```
+
+Dopóki ten prefiks jest całkowicie identyczny z dowolnym żądaniem w oknie TTL, API trafi w pamięć podręczną (zwraca `cache_read_input_tokens`) zamiast obliczać ponownie (`cache_creation_input_tokens`).
+
+> **Claude Code nie jest silnie zależny od atrybutu `cache_control` — serwer usuwa niektóre z tych atrybutów, ale nadal potrafi prawidłowo tworzyć pamięć podręczną, więc brak atrybutu `cache_control` nie oznacza, że zawartość nie jest buforowana**
+>
+> Dla specjalnych klientów takich jak Claude Code, serwer Anthropica nie jest całkowicie zależny od atrybutu `cache_control` w żądaniu do określenia zachowania pamięci podręcznej. Serwer automatycznie stosuje strategie buforowania dla określonych pól (takich jak system prompt i definicje narzędzi), nawet gdy żądanie nie zawiera jawnie znaczników `cache_control`. Dlatego nie musisz się dziwić, gdy nie widzisz tego atrybutu w treści żądania — serwer już wykonał operację buforowania za kulisami, po prostu nie ujawnił tej informacji klientowi. Jest to milczące porozumienie między Claude Code a Anthropic API.
+
+## Czym jest "bieżąca zawartość pamięci podręcznej KV-Cache"?
+
+"Bieżąca zawartość pamięci podręcznej KV-Cache" wyświetlana w cc-viewer to zawartość wyodrębniona z ostatniego żądania MainAgent, znajdująca się przed granicą pamięci podręcznej (cache breakpoint). Obejmuje konkretnie:
+
+- **System Prompt**: Instrukcje systemowe Claude Code, w tym podstawowe instrukcje agenta, zasady korzystania z narzędzi, instrukcje projektu CLAUDE.md, informacje o środowisku itp.
+- **Tools**: Lista aktualnie dostępnych definicji narzędzi (takich jak Read, Write, Bash, Agent, narzędzia MCP itp.)
+- **Messages**: Buforowana część historii konwersacji (zwykle starsze wiadomości, do ostatniego znacznika `cache_control`)
+
+## Dlaczego warto przeglądać zawartość pamięci podręcznej?
+
+1. **Zrozumienie kontekstu**: Dowiedz się, jaką zawartość Claude aktualnie "pamięta", i oceń, czy jego zachowanie jest zgodne z oczekiwaniami
+2. **Optymalizacja kosztów**: Trafienie w pamięć podręczną kosztuje znacznie mniej niż ponowne obliczenia. Przeglądanie zawartości pamięci podręcznej pomaga zrozumieć, dlaczego niektóre żądania wyzwoliły przebudowę pamięci podręcznej (cache rebuild)
+3. **Debugowanie konwersacji**: Gdy odpowiedź Claude nie jest zgodna z oczekiwaniami, sprawdzenie zawartości pamięci podręcznej pozwala potwierdzić, czy system prompt i historia wiadomości są poprawne
+4. **Monitorowanie jakości kontekstu**: Podczas debugowania, modyfikacji konfiguracji lub dostosowywania promptów, KV-Cache-Text zapewnia scentralizowaną perspektywę, pomagającą szybko potwierdzić, czy kontekst główny nie uległ pogorszeniu lub nie został zanieczyszczony nieoczekiwaną zawartością — bez konieczności przeglądania oryginalnych wiadomości po kolei
+
+## Wielopoziomowa strategia pamięci podręcznej
+
+Pamięć KV-Cache odpowiadająca Claude Code nie jest pojedynczą pamięcią podręczną. Serwer generuje oddzielne pamięci podręczne dla Tools i System Prompt, niezależnie od pamięci podręcznej Messages. Zaletą tego projektu jest to, że gdy stos wiadomości zostaje zakłócony (np. obcinanie kontekstu, modyfikacja wiadomości) i wymaga przebudowy, nie unieważnia to jednocześnie pamięci podręcznych Tools i System Prompt, unikając pełnego ponownego obliczania.
+
+Jest to strategia optymalizacji po stronie serwera — ponieważ definicje Tools i System Prompt są stosunkowo stabilne podczas normalnego użytkowania i rzadko się zmieniają, oddzielne buforowanie ich maksymalizuje redukcję niepotrzebnych kosztów przebudowy. Dlatego obserwując pamięć podręczną, zauważysz, że oprócz przebudowy Tools, która wymaga pełnego odświeżenia wszystkich pamięci podręcznych, zniszczenie System Prompt i Messages nadal pozwala na dziedziczenie dostępnych pamięci podręcznych.
+
+## Cykl życia pamięci podręcznej
+
+- **Tworzenie**: Przy pierwszym żądaniu lub po wygaśnięciu pamięci podręcznej, API tworzy nową pamięć podręczną (`cache_creation_input_tokens`)
+- **Trafienie**: Kolejne żądania z identycznym prefiksem ponownie wykorzystują pamięć podręczną (`cache_read_input_tokens`)
+- **Wygaśnięcie**: Pamięć podręczna ma TTL (czas życia) wynoszący 5 minut i automatycznie wygasa po tym czasie
+- **Przebudowa**: Gdy system prompt, lista narzędzi, model lub zawartość wiadomości się zmienią, klucz pamięci podręcznej nie pasuje, wyzwalając przebudowę odpowiedniego poziomu

package/concepts/pl/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Definicja
+
+MainAgent to główny łańcuch żądań Claude Code w trybie bez agent team. Każda interakcja użytkownika z Claude Code generuje serię żądań API, z których żądania MainAgent tworzą główny łańcuch dialogu — zawierają pełny system prompt, definicje narzędzi i historię wiadomości.
+
+## Sposób identyfikacji
+
+W cc-viewer MainAgent jest identyfikowany przez `req.mainAgent === true`, automatycznie oznaczany przez `interceptor.js` podczas przechwytywania żądania.
+
+Warunki kwalifikacji (wszystkie muszą być spełnione):
+- Treść żądania zawiera pole `system` (system prompt)
+- Treść żądania zawiera tablicę `tools` (definicje narzędzi)
+- System prompt zawiera tekst charakterystyczny dla "Claude Code"
+
+## Różnice względem SubAgent
+
+| Cecha | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | Pełny główny prompt Claude Code | Uproszczony prompt dedykowany zadaniu |
+| tablica tools | Zawiera wszystkie dostępne narzędzia | Zazwyczaj zawiera tylko kilka narzędzi potrzebnych do zadania |
+| historia wiadomości | Kumuluje pełny kontekst dialogu | Zawiera tylko wiadomości związane z podzadaniem |
+| zachowanie cache | Prompt caching (5 minut TTL) | Zazwyczaj bez cache lub z małym cache |

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

@@ -0,0 +1,25 @@
+# Mobilny dostęp przez kod QR
+
+## Jak to działa
+
+CC Viewer uruchamia serwer HTTP i generuje **adres LAN** (np. `http://192.168.1.100:7008`). Zeskanuj kod QR, aby uzyskać dostęp do Claude Code z telefonu przez tę samą sieć WiFi.
+
+## Dlaczego nie mogę się połączyć?
+
+1. **Nie w tej samej sieci** — Telefon i komputer muszą być w tej samej sieci WiFi (ten sam router/ta sama nazwa sieci)
+2. **Blokada zapory** — Zapora systemowa może blokować połączenia przychodzące
+3. **Izolacja sieci firmowej** — Izolacja AP może uniemożliwiać komunikację między urządzeniami
+4. **Zakłócenia VPN** — VPN może zakłócać trasę sieciową
+
+## Uwagi dotyczące bezpieczeństwa
+
+> ⚠️ Usługa LAN CC Viewer jest dostępna dla wszystkich urządzeń w tej samej sieci.
+
+- Zachowaj ostrożność w **publicznych sieciach WiFi**
+- CC Viewer używa **uwierzytelniania tokenem** do ochrony dostępu LAN
+- Zalecane w zaufanych sieciach
+
+## Poza LAN
+
+- **Narzędzia tunelowania** — frp, ngrok, Tailscale itp.
+- **Wtyczki CC Viewer** — Skonfiguruj proxy middleware przez system wtyczek

package/concepts/pl/ResponseFields.md

@@ -0,0 +1,50 @@
+# Opis pol Response Body
+
+Opis pol odpowiedzi API Claude `/v1/messages`.
+
+## Pola najwyzszego poziomu
+
+| Pole | Typ | Opis |
+|------|------|------|
+| **model** | string | Rzeczywista nazwa modelu, np. `claude-opus-4-6` |
+| **id** | string | Unikalny identyfikator odpowiedzi, np. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Stala wartosc `"message"` |
+| **role** | string | Stala wartosc `"assistant"` |
+| **content** | array | Tablica blokow wyjsciowych modelu, zawierajaca tekst, wywolania narzedzi, proces myslowy itp. |
+| **stop_reason** | string | Powod zatrzymania: `"end_turn"` (normalne zakonczenie), `"tool_use"` (wymagane wykonanie narzedzia), `"max_tokens"` (osiagnieto limit tokenow) |
+| **stop_sequence** | string/null | Sekwencja wyzwalajaca zatrzymanie, zazwyczaj `null` |
+| **usage** | object | Statystyki zuzycia tokenow (szczegoly ponizej) |
+
+## Typy blokow content
+
+| Typ | Opis |
+|------|------|
+| **text** | Odpowiedz tekstowa modelu, zawiera pole `text` |
+| **tool_use** | Zadanie wywolania narzedzia, zawiera `name` (nazwa narzedzia), `input` (parametry), `id` (identyfikator wywolania, uzywany do dopasowania tool_result) |
+| **thinking** | Rozszerzony proces myslowy (wyswietlany tylko przy wlaczonym trybie thinking), zawiera pole `thinking` |
+
+## Szczegoly pola usage
+
+| Pole | Opis |
+|------|------|
+| **input_tokens** | Liczba tokenow wejsciowych bez trafienia w cache (rozliczane po pelnej cenie) |
+| **cache_creation_input_tokens** | Liczba tokenow zapisanych w cache w tym zadaniu (zapis do cache, rozliczane drozej niz zwykle wejscie) |
+| **cache_read_input_tokens** | Liczba tokenow z trafieniem w cache (odczyt z cache, rozliczane znacznie taniej niz zwykle wejscie) |
+| **output_tokens** | Liczba tokenow wyjsciowych modelu |
+| **service_tier** | Poziom uslugi, np. `"standard"` |
+| **inference_geo** | Region wnioskowania, np. `"not_available"` oznacza brak informacji o regionie |
+
+## Podpola cache_creation
+
+| Pole | Opis |
+|------|------|
+| **ephemeral_5m_input_tokens** | Liczba tokenow krotkoterminowego cache z TTL 5 minut |
+| **ephemeral_1h_input_tokens** | Liczba tokenow dlugoterminowego cache z TTL 1 godzina |
+
+> **O rozliczaniu cache**: Cena jednostkowa `cache_read_input_tokens` jest znacznie nizsza niz `input_tokens`, natomiast cena jednostkowa `cache_creation_input_tokens` jest nieco wyzsza niz zwykle wejscie. Dlatego utrzymanie wysokiego wskaznika trafien w cache podczas ciaglych rozmow moze znaczaco obnizic koszty. Za pomoca metryki "wskaznik trafien" w cc-viewer mozna latwo monitorowac te proporcje.
+
+## Znaczenie stop_reason
+
+- **end_turn**: Model normalnie zakonczyl odpowiedz
+- **tool_use**: Model musi wywolac narzedzie, content bedzie zawierac blok `tool_use`. W nastepnym zadaniu nalezy dodac `tool_result` do messages, aby kontynuowac rozmowe
+- **max_tokens**: Osiagnieto limit `max_tokens`, odpowiedz zostala obcieta i moze byc niekompletna

package/concepts/pl/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Definicja
+
+Search jest typem pod-agenta uruchamianego przez głównego agenta Claude Code w celu przeszukiwania kodu źródłowego. Wykonuje ukierunkowane wyszukiwania plików i treści przy użyciu narzędzi takich jak Glob, Grep i Read, a następnie zwraca wyniki do agenta nadrzędnego.
+
+## Zachowanie
+
+- Uruchamiany automatycznie gdy główny agent musi przeszukać lub eksplorować kod źródłowy
+- Działa w izolowanym kontekście z dostępem tylko do odczytu
+- Używa Glob do dopasowywania wzorców plików, Grep do wyszukiwania treści i Read do inspekcji plików
+- Zwraca wyniki wyszukiwania do agenta nadrzędnego w celu dalszego przetwarzania
+
+## Kiedy się pojawia
+
+Pod-agenty Search pojawiają się zazwyczaj gdy:
+
+1. Główny agent musi znaleźć określone pliki, funkcje lub wzorce kodu
+2. Użytkownik prosi o szeroką eksplorację kodu źródłowego
+3. Agent bada zależności, odwołania lub wzorce użycia

package/concepts/pl/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## Definicja
+
+Teammate to agent współpracujący w trybie Claude Code Agent Team. Gdy główny agent tworzy zespół za pomocą `TeamCreate` i generuje teammate'ów przy użyciu narzędzia `Agent`, każdy teammate działa jako niezależny proces agenta z własnym oknem kontekstu i zestawem narzędzi, komunikując się z członkami zespołu za pośrednictwem `SendMessage`.
+
+## Różnice w porównaniu z SubAgent
+
+| Cecha | Teammate | SubAgent |
+|-------|----------|----------|
+| Cykl życia | Trwały, może odbierać wiele wiadomości | Jednorazowe zadanie, niszczony po zakończeniu |
+| Komunikacja | SendMessage — wiadomości dwukierunkowe | Rodzic→dziecko — wywołanie jednokierunkowe, zwraca wynik |
+| Kontekst | Niezależny pełny kontekst, zachowywany między turami | Izolowany kontekst zadania |
+| Model współpracy | Współpraca zespołowa, wzajemna komunikacja | Struktura hierarchiczna, interakcja tylko z agentem nadrzędnym |
+| Typ zadania | Złożone zadania wieloetapowe | Pojedyncze zadania, takie jak wyszukiwanie i eksploracja |
+
+## Zachowanie
+
+- Tworzony przez głównego agenta (team lead) za pomocą narzędzia `Agent` z przypisanym `team_name`
+- Współdzieli listę zadań przez `TaskList` / `TaskGet` / `TaskUpdate`
+- Po każdej rundzie wykonania przechodzi w stan idle i czeka na przebudzenie przez nowe wiadomości
+- Może zostać elegancko zakończony za pomocą `shutdown_request`
+
+## Opis panelu statystyk
+
+Panel statystyk teammate'ów wyświetla liczbę wywołań API dla każdego teammate'a. Kolumna `Name` to nazwa teammate'a (np. `reviewer-security`, `reviewer-pipeline`), a kolumna `Liczba` to łączna liczba żądań API wygenerowanych przez danego teammate'a.