cx-viewer 1.0.0

package/concepts/ja/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — 究極の願望マシン
+
+## UltraPlan とは
+
+UltraPlan は、Claude Code のネイティブ `/ultraplan` コマンドに対する cc-viewer の**ローカライズ実装**です。Claude の公式リモートサービスを起動することなく、ローカル環境で `/ultraplan` のフル機能を利用でき、Claude Code が**マルチエージェント協調**により複雑な計画・実装タスクを遂行するよう導きます。
+
+通常の Plan モードや Agent Team と比較して、UltraPlan は以下が可能です：
+- タスクの複雑さを自動評価し、最適な計画戦略を選択
+- 複数の並列エージェントを配置し、異なる観点からコードベースを探索
+- 外部リサーチ（webSearch）を取り入れ、業界のベストプラクティスを参照
+- 計画の実行後、自動的に Code Review Team を編成しコードレビューを実施
+- 完全な **Plan → Execute → Review → Fix** のクローズドループを形成
+
+---
+
+## 重要な注意事項
+
+### 1. UltraPlan は万能ではない
+UltraPlan はより強力な願望マシンですが、すべての願いが叶うわけではありません。Plan や Agent Team より強力ですが、直接「お金を稼ぐ」ことはできません。適切なタスク粒度を考慮してください——大きな目標を実行可能な中規模タスクに分割し、一度にすべてを達成しようとしないでください。
+
+### 2. 現時点ではプログラミングプロジェクトに最も効果的
+UltraPlan のテンプレートとワークフローは、プログラミングプロジェクト向けに深く最適化されています。他のシナリオ（ドキュメント作成、データ分析など）も試すことはできますが、将来のバージョンでの対応を待つことをお勧めします。
+
+### 3. 実行時間とコンテキストウィンドウの要件
+- UltraPlan の正常な実行には通常 **30 分以上**かかります
+- MainAgent に大きなコンテキストウィンドウが必要です（1M context の Opus モデルを推奨）
+- 200K モデルのみの場合、**実行前に必ず `/clear` でコンテキストをクリアしてください**
+- Claude Code の `/compact` はコンテキストウィンドウが不足すると性能が低下します——空間の枯渇を避けてください
+- 十分なコンテキスト空間を維持することが、UltraPlan を成功させるための重要な前提条件です
+
+ローカライズ版 UltraPlan についてご質問やご提案がありましたら、お気軽に [GitHub Issues](https://github.com/anthropics/claude-code/issues) でディスカッションにご参加ください。
+
+---
+
+## 仕組み
+
+UltraPlan には 2 つの動作モードがあります：
+
+### 自動モード
+タスクの複雑さ（スコア 4-12）を自動分析し、異なる戦略にルーティングします：
+
+| ルート | スコア | 戦略 |
+|--------|--------|------|
+| ルート A | 4-6 | 軽量な計画と直接的なコード探索 |
+| ルート B | 7-9 | 構造図（Mermaid / ASCII）を伴う計画 |
+| ルート C | 10-12 | マルチエージェント探索 + レビューのクローズドループ |
+
+### 強制モード
+完全なルート C のマルチエージェントワークフローを直接起動します：
+1. 最大 5 つの並列エージェントを配置し、コードベースを同時に探索（アーキテクチャ、ファイル特定、リスク評価など）
+2. オプションでリサーチエージェントを配置し、webSearch で業界ソリューションを調査
+3. すべてのエージェントの調査結果を統合し、詳細な実装計画にまとめる
+4. レビューエージェントを配置し、複数の観点から計画を精査
+5. 承認後に計画を実行
+6. 実装完了後、自動的に Code Review Team を編成しコード品質を検証

package/concepts/ko/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（요청 본문 증분 비교）
+
+## 배경
+
+Claude Code의 MainAgent는 전체 컨텍스트 전송 방식을 채택하고 있어, 매 요청마다 완전한 대화 이력, system prompt, 도구 정의 등의 내용을 포함합니다. 이는 대화가 진행될수록 요청 본문이 점점 커진다는 것을 의미하며, 원시 Body를 직접 확인해서는 "이번에 실제로 무엇이 추가되었는지"를 빠르게 파악하기 어렵습니다.
+
+Body Diff JSON은 바로 이 문제를 해결하기 위한 것입니다. 전후 두 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 두 가지 보기 모드를 지원하며, 원클릭 복사 가능
+- 좌측 상단 **CC-Viewer → 전역 설정**에서 "Body Diff JSON 기본 펼치기"를 설정할 수 있습니다

package/concepts/ko/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/ko/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는 전후 두 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. 하나의 요청이 여러 원인에 동시에 해당할 수 있음 (예: 모델 전환 + 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/ko/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/ko/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는 집중된 시각을 제공하여, 핵심 컨텍스트가 저하되지 않았는지, 예상치 못한 내용으로 오염되지 않았는지 빠르게 확인할 수 있음 -- 원본 메시지를 하나씩 검토할 필요 없음
+
+## 다중 레벨 캐시 전략
+
+Claude Code에 대응하는 KV-Cache는 하나만 있는 것이 아닙니다. 서버 측에서는 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/ko/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/ko/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/ko/QRCode.md

@@ -0,0 +1,25 @@
+# 모바일 QR 코드 접속
+
+## 작동 원리
+
+CC Viewer는 로컬에서 HTTP 서버를 시작하고 **LAN 주소**(예: `http://192.168.1.100:7008`)를 생성합니다. QR 코드를 스캔하면 같은 WiFi 네트워크를 통해 휴대폰에서 Claude Code를 사용할 수 있습니다.
+
+## 연결할 수 없는 경우
+
+1. **같은 네트워크가 아님** — 휴대폰과 컴퓨터가 같은 WiFi에 연결되어야 합니다 (같은 라우터/같은 네트워크 이름)
+2. **방화벽 차단** — OS 방화벽이 수신 연결을 차단할 수 있습니다
+3. **기업 네트워크 격리** — AP 격리로 장치 간 통신이 차단될 수 있습니다
+4. **VPN 간섭** — VPN이 네트워크 경로를 방해할 수 있습니다
+
+## 보안 참고사항
+
+> ⚠️ CC Viewer의 LAN 서비스는 같은 네트워크의 모든 장치에서 접근 가능합니다.
+
+- **공용 WiFi**에서 사용 시 주의하세요
+- CC Viewer는 **토큰 인증**으로 LAN 접근을 보호합니다
+- 신뢰할 수 있는 네트워크에서 사용을 권장합니다
+
+## LAN 외부 접속
+
+- **터널링 도구** — frp, ngrok, Tailscale 등
+- **CC Viewer 플러그인** — 플러그인으로 프록시를 구성하여 네트워크 간 접근 가능

package/concepts/ko/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/ko/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가 의존성, 참조 또는 사용 패턴을 조사할 때

package/concepts/ko/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## 정의
+
+Teammate는 Claude Code Agent Team 모드에서의 협업 agent입니다. 메인 agent가 `TeamCreate`로 팀을 생성하고 `Agent` 도구로 teammate를 생성하면, 각 teammate는 독립적인 agent 프로세스로 실행되며, 자체 컨텍스트 윈도우와 도구 세트를 가지고 `SendMessage`를 통해 팀 멤버와 통신합니다.
+
+## SubAgent와의 차이점
+
+| 특징 | Teammate | SubAgent |
+|------|----------|----------|
+| 생명주기 | 지속적으로 존재하며, 여러 번 메시지 수신 가능 | 일회성 작업, 완료 후 소멸 |
+| 통신 방식 | SendMessage 양방향 메시지 | 부모→자식 단방향 호출, 결과 반환 |
+| 컨텍스트 | 독립적인 완전한 컨텍스트, 턴 간 유지 | 격리된 작업 컨텍스트 |
+| 협업 모델 | 팀 협업, 상호 통신 가능 | 계층 구조, 부모 agent와만 상호작용 |
+| 작업 유형 | 복잡한 다단계 작업 | 검색, 탐색 등 단일 작업 |
+
+## 동작
+
+- 메인 agent(team lead)가 `Agent` 도구로 생성하고 `team_name`을 할당
+- `TaskList` / `TaskGet` / `TaskUpdate`를 통해 작업 목록 공유
+- 매 턴 실행 완료 후 idle 상태로 진입하여 새 메시지의 깨움을 대기
+- `shutdown_request`를 통해 정상 종료 가능
+
+## 통계 패널 설명
+
+Teammate 통계 패널은 각 teammate의 API 호출 횟수를 표시합니다. `Name` 열은 teammate 이름(예: `reviewer-security`, `reviewer-pipeline`)이며, `횟수` 열은 해당 teammate가 발생시킨 API 요청 총 수입니다.