cx-viewer 1.0.0

package/concepts/it/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — La Macchina dei Desideri Definitiva
+
+## Cos'e UltraPlan
+
+UltraPlan e l'**implementazione localizzata** di cc-viewer del comando nativo `/ultraplan` di Claude Code. Permette di utilizzare le funzionalita complete di `/ultraplan` nel proprio ambiente locale **senza dover avviare il servizio remoto ufficiale di Claude**, guidando Claude Code nel portare a termine compiti complessi di pianificazione e implementazione utilizzando la **collaborazione multi-agente**.
+
+Rispetto alla modalita Plan standard o ad Agent Team, UltraPlan puo:
+- Valutare automaticamente la complessita del compito e selezionare la strategia di pianificazione ottimale
+- Dispiegare piu agenti in parallelo per esplorare la codebase da diverse dimensioni
+- Incorporare ricerche esterne (webSearch) per le migliori pratiche del settore
+- Assemblare automaticamente un Code Review Team dopo l'esecuzione del piano per la revisione del codice
+- Formare un ciclo chiuso completo **Plan → Execute → Review → Fix**
+
+---
+
+## Note Importanti
+
+### 1. UltraPlan Non E Onnipotente
+UltraPlan e una macchina dei desideri piu potente, ma cio non significa che ogni desiderio possa essere esaudito. E piu potente di Plan e Agent Team, ma non puo direttamente "farti guadagnare soldi". Considera una granularita dei compiti ragionevole — suddividi i grandi obiettivi in compiti medi eseguibili piuttosto che cercare di realizzare tutto in un colpo solo.
+
+### 2. Attualmente Piu Efficace per Progetti di Programmazione
+I modelli e i flussi di lavoro di UltraPlan sono profondamente ottimizzati per progetti di programmazione. Altri scenari (documentazione, analisi dati, ecc.) possono essere tentati, ma si consiglia di attendere gli adattamenti nelle versioni future.
+
+### 3. Tempo di Esecuzione e Requisiti della Finestra di Contesto
+- Un'esecuzione riuscita di UltraPlan richiede tipicamente **30 minuti o piu**
+- Richiede che il MainAgent abbia una finestra di contesto ampia (modello Opus con 1M di contesto consigliato)
+- Se si dispone solo di un modello 200K, **assicurarsi di eseguire `/clear` sul contesto prima dell'esecuzione**
+- Il `/compact` di Claude Code funziona male quando la finestra di contesto e insufficiente — evitare di esaurire lo spazio
+- Mantenere spazio di contesto sufficiente e un prerequisito critico per l'esecuzione riuscita di UltraPlan
+
+Se hai domande o suggerimenti sull'UltraPlan localizzato, sentiti libero di aprire [Issues su GitHub](https://github.com/anthropics/claude-code/issues) per discutere e collaborare.
+
+---
+
+## Come Funziona
+
+UltraPlan offre due modalita operative:
+
+### Modalita Automatica
+Analizza automaticamente la complessita del compito (punteggio 4-12) e instrada verso diverse strategie:
+
+| Percorso | Punteggio | Strategia |
+|----------|-----------|-----------|
+| Percorso A | 4-6 | Pianificazione leggera con esplorazione diretta del codice |
+| Percorso B | 7-9 | Pianificazione con diagrammi strutturali (Mermaid / ASCII) |
+| Percorso C | 10-12 | Esplorazione multi-agente + ciclo chiuso di revisione |
+
+### Modalita Forzata
+Attiva direttamente il flusso di lavoro multi-agente completo del Percorso C:
+1. Dispiegare fino a 5 agenti in parallelo per esplorare simultaneamente la codebase (architettura, identificazione file, valutazione rischi, ecc.)
+2. Opzionalmente dispiegare un agente di ricerca per investigare soluzioni del settore tramite webSearch
+3. Sintetizzare tutte le scoperte degli agenti in un piano di implementazione dettagliato
+4. Dispiegare un agente di revisione per esaminare il piano da molteplici prospettive
+5. Eseguire il piano una volta approvato
+6. Assemblare automaticamente un Code Review Team per validare la qualita del codice dopo l'implementazione

package/concepts/ja/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（リクエストボディの差分比較）
+
+## 背景
+
+Claude Code の MainAgent はフルコンテキスト送信方式を採用しており、リクエストごとに完全な会話履歴、system prompt、ツール定義などを含みます。つまり会話が進むにつれてリクエストボディはどんどん大きくなり、生の Body を直接見ても「今回実際に何が追加されたのか」を素早く特定するのは困難です。
+
+Body Diff JSON はまさにこの問題を解決するためのものです。前後2つの MainAgent リクエストの body を自動比較し、差分部分を抽出することで、今回のリクエストで実際に追加された内容を一目で把握できます。
+
+## 動作原理
+
+1. **連続する MainAgent リクエストの識別**：現在のリクエストが MainAgent タイプであり、かつ前の MainAgent リクエストが存在すること
+2. **フィールドごとの比較**：リクエストボディのすべてのトップレベルフィールドを走査し、`_` プレフィックスの内部属性はスキップ
+3. **スマートな差分抽出**：
+   - 追加されたフィールド：そのまま表示
+   - 削除されたフィールド：非表示（通常、理解に影響しない）
+   - 変更されたフィールド：現在の値を表示
+   - `messages` 配列は特別処理：追加されたメッセージのみ表示（通常の会話は追記モードで、プレフィックスメッセージは不変のため）
+4. **リクエストボディの縮小検出**：現在のリクエストボディが前回より小さい場合、コンテキストの切り詰めやセッションリセットが発生したことを意味し、diff ではなく通知メッセージを表示
+
+## 典型的なシナリオ
+
+通常の会話ラウンドでは、Body Diff JSON には以下のみが含まれます：
+- `messages`：追加された1〜2件のメッセージ（ユーザーの入力 + 前回のアシスタントの応答）
+
+diff に `system`、`tools`、`model` などのフィールドの変更が表示された場合、今回のリクエストで設定変更が発生したことを意味し、これはキャッシュ再構築の原因でもあることが多いです。
+
+## 使い方
+
+- Body Diff JSON は MainAgent リクエストの詳細パネルに表示されます
+- タイトルをクリックで展開/折りたたみ
+- JSON と Text の2つの表示モードに対応し、ワンクリックコピーも可能
+- 左上の **CC-Viewer → グローバル設定** で「Body Diff JSON をデフォルトで展開」を設定できます

package/concepts/ja/BodyFields.md

@@ -0,0 +1,42 @@
+# Request Body フィールド説明
+
+Claude API `/v1/messages` リクエストボディのトップレベルフィールドの説明。
+
+## フィールド一覧
+
+| フィールド | 型 | 説明 |
+|------|------|------|
+| **model** | string | 使用するモデル名。例：`claude-opus-4-6`、`claude-sonnet-4-6` |
+| **messages** | array | 会話メッセージの履歴。各メッセージには `role`（user/assistant）と `content`（テキスト、画像、tool_use、tool_result などの block 配列）が含まれる |
+| **system** | array | System prompt。Codex のコア指令、ツール使用説明、環境情報、CLAUDE.md の内容などを含む。`cache_control` 付きのブロックは prompt caching される |
+| **tools** | array | 利用可能なツール定義のリスト。各ツールには `name`、`description`、`input_schema`（JSON Schema）が含まれる。MainAgent には通常 20 以上のツールがあり、SubAgent には少数のみ |
+| **metadata** | object | リクエストメタデータ。通常、ユーザーを識別するための `user_id` を含む |
+| **max_tokens** | number | モデルが一度の応答で生成する最大トークン数。例：`16000`、`64000` |
+| **thinking** | object | 拡張思考の設定。`type: "enabled"` で思考モードを有効にし、`budget_tokens` で思考トークンの上限を制御する |
+| **context_management** | object | コンテキスト管理の設定。`truncation: "auto"` により、Codex は長すぎるメッセージ履歴を自動的に切り詰めることができる |
+| **output_config** | object | 出力設定。`format` の設定など |
+| **stream** | boolean | ストリーミングレスポンスを有効にするかどうか。Codex は常に `true` を使用する |
+
+## messages の構造
+
+各メッセージの `content` は block 配列で、一般的な型は以下の通り：
+
+- **text**: 通常のテキストコンテンツ
+- **tool_use**: モデルによるツール呼び出し（`name`、`input` を含む）
+- **tool_result**: ツールの実行結果（`tool_use_id`、`content` を含む）
+- **image**: 画像コンテンツ（base64 または URL）
+- **thinking**: モデルの思考プロセス（拡張思考モード）
+
+## system の構造
+
+system prompt 配列には通常以下が含まれる：
+
+1. **コア agent 指令**（"You are Codex..."）
+2. **ツール使用規範**
+3. **CLAUDE.md の内容**（プロジェクトレベルの指令）
+4. **スキルプロンプト**（skills reminder）
+5. **環境情報**（OS、shell、git ステータスなど）— 実際のところ、Codex は git に大きく依存している。プロジェクトに git リポジトリが存在する場合、Codex はリモートの変更やコミット履歴を取得して分析を補助するなど、プロジェクトに対してより優れた理解力を発揮できる
+
+`cache_control: { type: "ephemeral" }` マークが付いたブロックは Anthropic API により 5 分間キャッシュされ、キャッシュヒット時は `cache_read_input_tokens` として課金される（`input_tokens` よりはるかに低い）。
+
+> **注意**：Codex のような特殊なクライアントの場合、Anthropic のサーバー側はリクエスト中の `cache_control` 属性に完全に依存してキャッシュ動作を決定しているわけではない。サーバー側は特定のフィールド（system prompt やツール定義など）に対して自動的にキャッシュポリシーを適用しており、リクエストに `cache_control` マークが明示的に含まれていなくても同様である。したがって、リクエストボディにこの属性が見当たらなくても疑問に思う必要はない——サーバー側がバックグラウンドでキャッシュ操作を完了しており、その情報をクライアントに公開していないだけである。これは Codex と Anthropic API の間の暗黙の了解である。

package/concepts/ja/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild（キャッシュ再構築）
+
+## 背景
+
+Anthropic の prompt caching メカニズムは、リクエスト内の system → tools → messages（キャッシュブレークポイントまで）を順番に連結してキャッシュキーを生成します。キャッシュキーが前回のリクエストと完全に一致する場合、API は `cache_read_input_tokens`（キャッシュヒット）を返します。キャッシュキーが変更された場合、API はキャッシュを再作成し、大量の `cache_creation_input_tokens` を返します。これがキャッシュ再構築です。
+
+キャッシュ再構築は追加のトークン課金を意味します（cache creation の価格は cache read より高い）。そのため、再構築の原因を特定することはコスト最適化に直接的な価値があります。
+
+## キャッシュ再構築の原因分類
+
+cc-viewer は前後2つの MainAgent リクエストの body を比較し、キャッシュ再構築の原因を正確に判定します：
+
+| reason | 意味 | 判定方法 |
+|--------|------|----------|
+| `ttl` | キャッシュ期限切れ | 前の MainAgent リクエストから5分以上経過 |
+| `system_change` | system prompt の変更 | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | ツール定義の変更 | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | モデル切り替え | `prev.model !== curr.model` |
+| `msg_truncated` | メッセージスタックの切り詰め | 現在のリクエストの messages 数が前回より少ない。通常コンテキストウィンドウのオーバーフローによる切り詰めで発生 |
+| `msg_modified` | 履歴メッセージの変更 | プレフィックスメッセージの内容が不一致（通常の追記時はプレフィックスが完全に同一であるべき） |
+| `key_change` | 不明なキー変更 | 上記のいずれにも該当しない場合のフォールバック |
+
+## 判定優先順位
+
+1. まず時間間隔を確認——5分を超えた場合は直接 `ttl` と判定し、body 比較は行わない
+2. 次に model、system、tools、messages を順に確認
+3. 1つのリクエストが複数の原因に同時に該当する場合がある（例：モデル切り替え + system prompt 変更）。この場合 `reasons` 配列にすべての該当項目が含まれ、tooltip では改行表示される
+
+## よくあるシナリオ
+
+- **`ttl`**：ユーザーが5分以上操作を中断した後に再開し、キャッシュが自然に期限切れ
+- **`system_change`**：Claude Code が system prompt を更新（新しい CLAUDE.md の読み込み、project instructions の変更など）
+- **`tools_change`**：MCP server の接続/切断により利用可能なツールリストが変化
+- **`model_change`**：ユーザーが `/model` コマンドでモデルを切り替え
+- **`msg_truncated`**：会話が長くなりコンテキストウィンドウ管理が発動、Claude Code が初期のメッセージを切り詰め
+- **`msg_modified`**：Claude Code が履歴メッセージを編集（例：`/compact` で圧縮サマリーが元のメッセージを置換）

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

@@ -0,0 +1,49 @@
+# KV-Cache キャッシュ内容
+
+## Prompt Caching とは？
+
+Claude と会話するとき、API リクエストごとに完全な会話コンテキスト（system prompt + ツール定義 + 過去のメッセージ）が送信されます。Anthropic の prompt caching メカニズムは、既に計算済みのプレフィックス内容をサーバー側にキャッシュし、後続のリクエストでプレフィックスが一致する場合、キャッシュ結果を直接再利用して重複計算をスキップし、レイテンシーとコストを大幅に削減します。
+
+cc-viewer ではこのメカニズムを「KV-Cache」と呼んでいますが、これは Anthropic API レベルの prompt caching に対応するものであり、LLM 内部の transformer アテンション層の key-value cache ではありません。
+
+## キャッシュの動作原理
+
+Anthropic の prompt caching は固定順序でキャッシュキーを連結します：
+
+```
+Tools → System Prompt → Messages（キャッシュブレークポイントまで）
+```
+
+このプレフィックスが TTL ウィンドウ内のいずれかのリクエストと完全に一致する場合、API はキャッシュにヒット（`cache_read_input_tokens` を返す）し、再計算（`cache_creation_input_tokens`）は行われません。
+
+> **Claude Code は `cache_control` 属性に強く依存しておらず、サーバー側はこれらの属性の一部を除去しつつも適切にキャッシュを作成できるため、`cache_control` 属性が見当たらなくてもキャッシュされていないわけではありません**
+>
+> Claude Code のような特殊なクライアントに対して、Anthropic のサーバー側はリクエスト中の `cache_control` 属性だけに完全に依存してキャッシュ動作を決定しているわけではありません。サーバー側は特定のフィールド（system prompt、tools 定義など）に対して自動的にキャッシュポリシーを実行しており、リクエストに `cache_control` マークが明示的に含まれていなくても同様です。そのため、リクエストボディにこの属性が見当たらなくても不思議に思う必要はありません——サーバー側は裏側でキャッシュ操作を完了していますが、この情報をクライアントに公開していないだけです。これは Claude Code と Anthropic API の間の暗黙の了解です。
+
+## 「現在の KV-Cache キャッシュ内容」とは？
+
+cc-viewer に表示される「現在の KV-Cache キャッシュ内容」は、最新の MainAgent リクエストから抽出された、キャッシュ境界（cache breakpoint）より前の内容です。具体的には以下を含みます：
+
+- **System Prompt**：Claude Code のシステム指示。コア agent 指示、ツール使用規範、CLAUDE.md プロジェクト指示、環境情報などを含む
+- **Tools**：現在利用可能なツール定義リスト（Read、Write、Bash、Agent、MCP ツールなど）
+- **Messages**：会話履歴でキャッシュされた部分（通常は初期のメッセージで、最後の `cache_control` マークまで）
+
+## キャッシュ内容を確認する理由
+
+1. **コンテキストの理解**：Claude が現在「記憶している」内容を把握し、その動作が期待通りかどうかを判断するのに役立つ
+2. **コスト最適化**：キャッシュヒット時のコストは再計算より大幅に低い。キャッシュ内容を確認することで、特定のリクエストがキャッシュ再構築（cache rebuild）をトリガーした理由を理解できる
+3. **会話のデバッグ**：Claude の回答が期待と異なる場合、キャッシュ内容を確認して system prompt と過去のメッセージが正しいかを確認できる
+4. **コンテキスト品質監視**：デバッグ、設定変更、prompt 調整の過程で、KV-Cache-Text は集約されたビューを提供し、コアコンテキストが劣化していないか、予期しない内容で汚染されていないかを素早く確認できる——元のメッセージを1つずつ確認する必要はない
+
+## マルチレベルキャッシュ戦略
+
+Claude Code に対応する KV-Cache は1つだけではありません。サーバー側は Tools と System Prompt に対して個別にキャッシュを生成し、Messages 部分のキャッシュとは独立しています。この設計の利点は、messages スタックに混乱が生じた場合（コンテキストの切り捨て、メッセージの変更など）に再構築が必要になっても、Tools と System Prompt のキャッシュが連動して無効化されることなく、全面的な再計算を避けられることです。
+
+これは現段階のサーバー側の最適化戦略です——Tools 定義と System Prompt は通常の使用過程で比較的安定しており、変更が少ないため、個別にキャッシュすることで不要な再構築コストを最大限に削減できます。そのため、Cache を観察すると、Tools の再構築ではすべてのキャッシュを完全にリフレッシュする必要がある一方、System Prompt と Messages の破壊では引き続き利用可能な継承キャッシュが存在することがわかります。
+
+## キャッシュのライフサイクル
+
+- **作成**：初回リクエストまたはキャッシュ無効化後、API は新しいキャッシュを作成（`cache_creation_input_tokens`）
+- **ヒット**：後続リクエストのプレフィックスが一致する場合、キャッシュを再利用（`cache_read_input_tokens`）
+- **期限切れ**：キャッシュは 5 分の TTL（存続時間）を持ち、タイムアウト後は自動的に無効化
+- **再構築**：system prompt、ツールリスト、モデル、またはメッセージの内容が変更されると、キャッシュキーが一致せず、対応するレベルのキャッシュ再構築がトリガーされる

package/concepts/ja/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## 定義
+
+MainAgent は、Claude Code が非 agent team 状態における主幹リクエストチェーンです。ユーザーと Claude Code のやり取りのたびに一連の API リクエストが生成され、その中で MainAgent リクエストがコア会話チェーンを構成します。これらは完全な system prompt、ツール定義、メッセージ履歴を含みます。
+
+## 識別方法
+
+cc-viewer では、MainAgent は `req.mainAgent === true` で識別され、`interceptor.js` がリクエストキャプチャ時に自動的にマーキングします。
+
+判定条件（すべて満たす）：
+- リクエストボディに `system` フィールド（system prompt）が含まれる
+- リクエストボディに `tools` 配列（ツール定義）が含まれる
+- system prompt に "Claude Code" の特徴テキストが含まれる
+
+## SubAgent との違い
+
+| 特徴 | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | 完全な Claude Code メインプロンプト | 簡潔なタスク専用プロンプト |
+| tools 配列 | 利用可能なすべてのツールを含む | 通常タスクに必要な少数のツールのみ |
+| メッセージ履歴 | 完全な会話コンテキストを蓄積 | サブタスク関連のメッセージのみ |
+| キャッシュ動作 | prompt caching あり（5分 TTL） | 通常キャッシュなし、またはキャッシュが小さい |

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

@@ -0,0 +1,25 @@
+# モバイルQRコードアクセス
+
+## 仕組み
+
+CC Viewer はローカルで HTTP サーバーを起動し、**LAN アドレス**（例：`http://192.168.1.100:7008`）を生成します。QR コードをスキャンすると、同じ WiFi ネットワーク経由でスマートフォンから Claude Code を操作できます。
+
+## 接続できない場合
+
+1. **同じネットワークにいない** — スマートフォンと PC が同じ WiFi に接続されている必要があります（同じルーター/同じネットワーク名）
+2. **ファイアウォール** — OS のファイアウォールが着信接続をブロックしている可能性があります
+3. **企業ネットワーク隔離** — AP 隔離により端末間通信が遮断されている場合があります
+4. **VPN 干渉** — VPN がネットワーク経路を妨げている可能性があります
+
+## セキュリティに関する注意
+
+> ⚠️ CC Viewer の LAN サービスは、同じネットワーク上のすべてのデバイスからアクセス可能です。
+
+- **公共 WiFi** では注意してください
+- CC Viewer は **トークン認証**で LAN アクセスを保護します
+- 信頼できるネットワークでの使用を推奨します
+
+## LAN を超えたアクセス
+
+- **トンネリングツール** — frp、ngrok、Tailscale 等
+- **CC Viewer プラグイン** — プラグインでプロキシを設定し、ネットワークを越えてアクセス可能

package/concepts/ja/ResponseFields.md

@@ -0,0 +1,50 @@
+# Response Body フィールド説明
+
+Claude API `/v1/messages` レスポンスボディのフィールド説明。
+
+## トップレベルフィールド
+
+| フィールド | 型 | 説明 |
+|------|------|------|
+| **model** | string | 実際に使用されたモデル名。例: `claude-opus-4-6` |
+| **id** | string | 今回のレスポンスの一意識別子。例: `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | 固定値 `"message"` |
+| **role** | string | 固定値 `"assistant"` |
+| **content** | array | モデル出力のコンテンツブロック配列。テキスト、ツール呼び出し、思考プロセスなどを含む |
+| **stop_reason** | string | 停止理由: `"end_turn"`（正常終了）、`"tool_use"`（ツール実行が必要）、`"max_tokens"`（トークン上限に到達） |
+| **stop_sequence** | string/null | 停止をトリガーしたシーケンス。通常は `null` |
+| **usage** | object | トークン使用量の統計（詳細は下記参照） |
+
+## content ブロックタイプ
+
+| タイプ | 説明 |
+|------|------|
+| **text** | モデルのテキスト応答。`text` フィールドを含む |
+| **tool_use** | ツール呼び出しリクエスト。`name`（ツール名）、`input`（パラメータ）、`id`（呼び出し ID、tool_result とのマッチングに使用）を含む |
+| **thinking** | 拡張思考の内容（thinking モードが有効な場合のみ出現）。`thinking` フィールドを含む |
+
+## usage フィールド詳細
+
+| フィールド | 説明 |
+|------|------|
+| **input_tokens** | キャッシュにヒットしなかった入力トークン数（通常料金で課金） |
+| **cache_creation_input_tokens** | 今回新たに作成されたキャッシュのトークン数（キャッシュ書き込み、通常入力より高い料金） |
+| **cache_read_input_tokens** | キャッシュにヒットしたトークン数（キャッシュ読み取り、通常入力より大幅に低い料金） |
+| **output_tokens** | モデル出力のトークン数 |
+| **service_tier** | サービスティア。例: `"standard"` |
+| **inference_geo** | 推論リージョン。例: `"not_available"` はリージョン情報が提供されていないことを示す |
+
+## cache_creation サブフィールド
+
+| フィールド | 説明 |
+|------|------|
+| **ephemeral_5m_input_tokens** | TTL 5分の短期キャッシュ作成トークン数 |
+| **ephemeral_1h_input_tokens** | TTL 1時間の長期キャッシュ作成トークン数 |
+
+> **キャッシュ課金について**: `cache_read_input_tokens` の単価は `input_tokens` よりはるかに低く、`cache_creation_input_tokens` の単価は通常入力よりやや高くなっています。そのため、継続的な会話で高いキャッシュヒット率を維持することで、費用を大幅に削減できます。cc-viewer の「ヒット率」指標でこの比率を直感的に監視できます。
+
+## stop_reason の意味
+
+- **end_turn**: モデルが正常に応答を完了
+- **tool_use**: モデルがツールの呼び出しを必要としており、content に `tool_use` ブロックが含まれる。次のリクエストでは messages に `tool_result` を追加して会話を継続する必要がある
+- **max_tokens**: `max_tokens` の制限に達して切り詰められたため、応答が不完全な可能性がある

package/concepts/ja/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## 定義
+
+Search は、コードベースの検索を実行するために Claude Code のメイン agent によって生成されるサブ agent タイプです。Glob、Grep、Read などのツールを使用してファイルやコンテンツの対象を絞った検索を実行し、結果を親 agent に返します。
+
+## 動作
+
+- メイン agent がコードベースを検索または探索する必要があるときに自動的に生成される
+- 読み取り専用アクセス権を持つ隔離されたコンテキストで実行される
+- ファイルパターンマッチングには Glob、コンテンツ検索には Grep、ファイル検査には Read を使用する
+- さらなる処理のために検索結果を親 agent に返す
+
+## 表示されるタイミング
+
+Search サブ agent は通常、次のような場合に表示されます:
+
+1. メイン agent が特定のファイル、関数、またはコードパターンを見つける必要があるとき
+2. ユーザーが広範なコードベース探索を要求したとき
+3. agent が依存関係、参照、または使用パターンを調査しているとき