cx-viewer 1.0.0

package/concepts/ru/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Загрязнение контекста в Translate API
+
+## Предыстория
+
+CC-Viewer включает встроенную функцию перевода (`POST /api/translate`), работающую на основе Anthropic Messages API. В ранней реализации запросы на перевод повторно использовали кэшированные учётные данные аутентификации из сессии Claude Code — включая заголовки `x-api-key` и `authorization`. Это вызывало неочевидную, но серьёзную проблему: результаты перевода часто возвращали нерелевантное содержимое.
+
+## Корневая причина
+
+### Фундаментальное различие между двумя методами аутентификации
+
+Anthropic API поддерживает два метода аутентификации:
+
+| Метод | Заголовок | Типичный источник | Характеристики |
+|-------|-----------|-------------------|----------------|
+| API-ключ | `x-api-key: sk-ant-...` | Переменная окружения / Console | Без состояния, каждый запрос независим |
+| OAuth-токен | `authorization: Bearer sessionToken` | Вход по подписке Claude Code | Привязан к сессии, сервер поддерживает ассоциацию контекста |
+
+Ключевое различие: **API-ключи не хранят состояние** — каждый запрос полностью независим; тогда как **OAuth-токены сессии хранят состояние** — сервер Anthropic ассоциирует запросы с одним и тем же токеном с одним и тем же контекстом сессии.
+
+### Цепочка загрязнения
+
+Когда Claude Code использует OAuth-вход по подписке, поток аутентификации выглядит так:
+
+```
+Основной диалог Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                        ↑
+Запрос перевода CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Поскольку запросы на перевод повторно использовали тот же токен сессии, сервер Anthropic может ассоциировать запросы на перевод с контекстом основного диалога Claude Code. Это приводит к:
+
+1. **Результаты перевода под влиянием контекста основного диалога**: Системный промпт запроса на перевод — «вы переводчик», но серверный контекст всё ещё содержит историю диалогов Claude Code, что может влиять на модель
+2. **Основной диалог нарушается запросами на перевод**: Содержимое запросов на перевод (фрагменты текста UI) может быть внедрено в контекст основного диалога, вызывая отклонения в ответах Claude Code
+3. **Непредсказуемое поведение**: Поскольку загрязнение контекста — это поведение на стороне сервера, клиент не может его обнаружить или контролировать
+
+## Извлечённые уроки
+
+- **OAuth-токены сессии — это не «просто ещё один API-ключ»** — они несут серверное состояние, и их повторное использование означает разделение контекста
+- **Внутренние вызовы сервисов должны использовать независимую аутентификацию без состояния**, чтобы избежать ассоциации с пользовательскими сессиями
+
+## Ссылки
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)

package/concepts/ru/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — Идеальная Машина Желаний
+
+## Что такое UltraPlan
+
+UltraPlan — это **локализованная реализация** нативной команды `/ultraplan` Claude Code от cc-viewer. Он позволяет использовать полные возможности `/ultraplan` в вашем локальном окружении **без необходимости запуска официального удалённого сервиса Claude**, направляя Claude Code на выполнение сложных задач планирования и реализации с использованием **мультиагентного взаимодействия**.
+
+По сравнению с обычным режимом Plan или Agent Team, UltraPlan способен:
+- Автоматически оценивать сложность задачи и выбирать оптимальную стратегию планирования
+- Развёртывать несколько параллельных агентов для исследования кодовой базы с разных сторон
+- Использовать внешние исследования (webSearch) для получения лучших отраслевых практик
+- Автоматически формировать команду Code Review после выполнения плана для ревью кода
+- Создавать полный замкнутый цикл **План → Выполнение → Ревью → Исправление**
+
+---
+
+## Важные замечания
+
+### 1. UltraPlan не всемогущ
+UltraPlan — это более мощная машина желаний, но это не значит, что каждое желание может быть исполнено. Он мощнее, чем Plan и Agent Team, но не может напрямую «заработать вам деньги». Учитывайте разумную гранулярность задач — разбивайте большие цели на выполнимые задачи среднего размера, а не пытайтесь достичь всего за один раз.
+
+### 2. В настоящее время наиболее эффективен для программных проектов
+Шаблоны и рабочие процессы UltraPlan глубоко оптимизированы для программных проектов. Другие сценарии (документация, анализ данных и т.д.) можно попробовать, но возможно стоит подождать адаптации в будущих версиях.
+
+### 3. Время выполнения и требования к контекстному окну
+- Успешный запуск UltraPlan обычно занимает **30 минут или более**
+- Требует, чтобы MainAgent имел большое контекстное окно (рекомендуется модель Opus с контекстом 1M)
+- Если у вас только модель на 200K, **обязательно выполните `/clear` контекста перед запуском**
+- Команда `/compact` Claude Code работает плохо при недостаточном контекстном окне — не допускайте исчерпания пространства
+- Поддержание достаточного пространства контекста является критически важным условием для успешного выполнения UltraPlan
+
+Если у вас есть вопросы или предложения по локализованному UltraPlan, не стесняйтесь открывать [Issues на GitHub](https://github.com/anthropics/claude-code/issues) для обсуждения и сотрудничества.
+
+---
+
+## Как это работает
+
+UltraPlan предлагает два режима работы:
+
+### Автоматический режим
+Автоматически анализирует сложность задачи (оценка 4-12) и направляет к различным стратегиям:
+
+| Маршрут | Оценка | Стратегия |
+|---------|--------|-----------|
+| Маршрут A | 4-6 | Лёгкое планирование с прямым исследованием кода |
+| Маршрут B | 7-9 | Планирование со структурными диаграммами (Mermaid / ASCII) |
+| Маршрут C | 10-12 | Мультиагентное исследование + замкнутый цикл ревью |
+
+### Принудительный режим
+Напрямую активирует полный мультиагентный рабочий процесс Маршрута C:
+1. Развёртывание до 5 параллельных агентов для одновременного исследования кодовой базы (архитектура, идентификация файлов, оценка рисков и т.д.)
+2. Опциональное развёртывание исследовательского агента для изучения отраслевых решений через webSearch
+3. Синтез всех результатов агентов в детальный план реализации
+4. Развёртывание агента-ревьюера для тщательной проверки плана с нескольких точек зрения
+5. Выполнение плана после одобрения
+6. Автоматическое формирование команды Code Review для проверки качества кода после реализации

package/concepts/th/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (การเปรียบเทียบส่วนเพิ่มของเนื้อหาคำร้องขอ)
+
+## ภูมิหลัง
+
+MainAgent ของ Claude Code ใช้กลไกการส่งบริบทแบบเต็ม — ทุกคำร้องขอจะมีประวัติการสนทนาทั้งหมด, system prompt, คำจำกัดความเครื่องมือ ฯลฯ ซึ่งหมายความว่าเมื่อการสนทนาดำเนินไป เนื้อหาคำร้องขอจะใหญ่ขึ้นเรื่อยๆ การดู Body ดิบโดยตรงจึงยากที่จะระบุได้อย่างรวดเร็วว่า "รอบนี้เพิ่มอะไรมาบ้าง"
+
+Body Diff JSON ถูกสร้างขึ้นเพื่อแก้ปัญหานี้: มันเปรียบเทียบ body ของคำร้องขอ MainAgent สองรายการที่ต่อเนื่องกันโดยอัตโนมัติ สกัดส่วนที่เพิ่มขึ้น ให้คุณเห็นเนื้อหาที่เพิ่มจริงในคำร้องขอนี้ได้ทันที
+
+## หลักการทำงาน
+
+1. **ระบุคำร้องขอ MainAgent ที่ต่อเนื่องกัน**: คำร้องขอปัจจุบันต้องเป็นประเภท MainAgent และต้องมีคำร้องขอ MainAgent ก่อนหน้า
+2. **เปรียบเทียบทีละฟิลด์**: วนผ่านฟิลด์ระดับบนสุดทั้งหมดของเนื้อหาคำร้องขอ ข้ามคุณสมบัติภายในที่มีคำนำหน้า `_`
+3. **การสกัดความแตกต่างอัจฉริยะ**:
+   - ฟิลด์ที่เพิ่มใหม่: แสดงโดยตรง
+   - ฟิลด์ที่ถูกลบ: ไม่แสดง (โดยปกติไม่ส่งผลต่อความเข้าใจ)
+   - ฟิลด์ที่เปลี่ยนแปลง: แสดงค่าปัจจุบัน
+   - การจัดการพิเศษสำหรับอาร์เรย์ `messages`: แสดงเฉพาะข้อความที่เพิ่มใหม่ (เพราะในการสนทนาปกติเป็นโหมดเพิ่มต่อท้าย ข้อความนำหน้าไม่เปลี่ยนแปลง)
+4. **การตรวจจับเนื้อหาที่เล็กลง**: หากเนื้อหาคำร้องขอปัจจุบันเล็กกว่าก่อนหน้า แสดงว่าเกิดการตัดทอนบริบทหรือรีเซ็ตเซสชัน ในกรณีนี้จะแสดงข้อความแจ้งเตือนแทน diff
+
+## สถานการณ์ทั่วไป
+
+ในรอบการสนทนาปกติ Body Diff JSON มักจะมีเพียง:
+- `messages`: ข้อความใหม่ 1~2 รายการ (อินพุตของผู้ใช้ + คำตอบของผู้ช่วยจากรอบก่อนหน้า)
+
+หากคุณเห็นการเปลี่ยนแปลงของฟิลด์ `system`, `tools`, `model` ฯลฯ ใน diff แสดงว่ารอบนี้มีการเปลี่ยนแปลงการตั้งค่า ซึ่งมักเป็นสาเหตุของการสร้างแคชใหม่ด้วย
+
+## วิธีใช้
+
+- Body Diff JSON แสดงในแผงรายละเอียดของคำร้องขอ MainAgent
+- คลิกที่หัวข้อเพื่อขยาย/ยุบ
+- รองรับสองโหมดการดู: JSON และ Text รวมถึงการคัดลอกด้วยคลิกเดียว
+- ที่มุมซ้ายบนใน **CC-Viewer → การตั้งค่าทั่วไป** สามารถตั้งค่า "ขยาย Body Diff JSON เป็นค่าเริ่มต้น" ได้

package/concepts/th/BodyFields.md

@@ -0,0 +1,42 @@
+# คำอธิบายฟิลด์ Request Body
+
+คำอธิบายฟิลด์ระดับบนสุดของ request body สำหรับ `/v1/messages` ของ Claude API
+
+## รายการฟิลด์
+
+| ฟิลด์ | ประเภท | คำอธิบาย |
+|------|------|------|
+| **model** | string | ชื่อโมเดลที่ใช้ เช่น `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | ประวัติข้อความสนทนา แต่ละข้อความประกอบด้วย `role` (user/assistant) และ `content` (อาร์เรย์ของบล็อก เช่น ข้อความ, รูปภาพ, tool_use, tool_result) |
+| **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` ของแต่ละข้อความเป็นอาร์เรย์ของบล็อก ประเภทที่พบบ่อย ได้แก่:
+
+- **text**: เนื้อหาข้อความธรรมดา
+- **tool_use**: โมเดลเรียกใช้เครื่องมือ (ประกอบด้วย `name`, `input`)
+- **tool_result**: ผลลัพธ์การทำงานของเครื่องมือ (ประกอบด้วย `tool_use_id`, `content`)
+- **image**: เนื้อหารูปภาพ (base64 หรือ URL)
+- **thinking**: กระบวนการคิดของโมเดล (โหมดการคิดแบบขยาย)
+
+## โครงสร้าง system
+
+อาร์เรย์ system prompt โดยทั่วไปประกอบด้วย:
+
+1. **คำสั่งหลักของเอเจนต์** ("You are Codex...")
+2. **ข้อกำหนดการใช้เครื่องมือ**
+3. **เนื้อหา CLAUDE.md** (คำสั่งระดับโปรเจกต์)
+4. **การแจ้งเตือนทักษะ** (skills reminder)
+5. **ข้อมูลสภาพแวดล้อม** (OS, shell, สถานะ git ฯลฯ) — ในความเป็นจริง Codex พึ่งพา git เป็นอย่างมาก หากโปรเจกต์มี git repository Codex สามารถแสดงความเข้าใจโปรเจกต์ได้ดีขึ้น รวมถึงสามารถดึงการเปลี่ยนแปลงจากรีโมตและบันทึกคอมมิตมาช่วยในการวิเคราะห์
+
+บล็อกที่ทำเครื่องหมายด้วย `cache_control: { type: "ephemeral" }` จะถูกแคชโดย Anthropic API เป็นเวลา 5 นาที เมื่อแคชถูกเรียกใช้จะคิดค่าใช้จ่ายเป็น `cache_read_input_tokens` (ต่ำกว่า `input_tokens` มาก)
+
+> **หมายเหตุ**: สำหรับไคลเอ็นต์พิเศษอย่าง Codex เซิร์ฟเวอร์ของ Anthropic ไม่ได้พึ่งพาคุณสมบัติ `cache_control` ในคำขอทั้งหมดเพื่อกำหนดพฤติกรรมการแคช เซิร์ฟเวอร์จะดำเนินนโยบายการแคชโดยอัตโนมัติสำหรับฟิลด์เฉพาะ (เช่น system prompt, คำจำกัดความเครื่องมือ) แม้ว่าคำขอจะไม่มีเครื่องหมาย `cache_control` อย่างชัดเจน ดังนั้น เมื่อคุณไม่เห็นคุณสมบัตินี้ใน request body ไม่ต้องแปลกใจ เซิร์ฟเวอร์ได้ดำเนินการแคชเบื้องหลังแล้ว เพียงแต่ไม่ได้เปิดเผยข้อมูลนี้ให้ไคลเอ็นต์ทราบ นี่คือความเข้าใจโดยปริยายระหว่าง Codex กับ Anthropic API

package/concepts/th/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild (การสร้างแคชใหม่)
+
+## ภูมิหลัง
+
+กลไก prompt caching ของ Anthropic จะนำ system → tools → messages (จนถึง cache breakpoint) ในคำร้องขอมาต่อกันตามลำดับเพื่อสร้างคีย์แคช เมื่อคีย์แคชตรงกับคำร้องขอก่อนหน้าทุกประการ API จะส่งคืน `cache_read_input_tokens` (แคชตรง) เมื่อคีย์แคชเปลี่ยนแปลง API จะสร้างแคชใหม่และส่งคืน `cache_creation_input_tokens` จำนวนมาก นั่นคือการสร้างแคชใหม่
+
+การสร้างแคชใหม่หมายถึงค่าใช้จ่ายโทเค็นเพิ่มเติม (ราคา cache creation สูงกว่า cache read) ดังนั้นการระบุสาเหตุของการสร้างใหม่จึงมีคุณค่าโดยตรงต่อการเพิ่มประสิทธิภาพค่าใช้จ่าย
+
+## การจำแนกสาเหตุการสร้างแคชใหม่
+
+cc-viewer ระบุสาเหตุของการสร้างแคชใหม่อย่างแม่นยำโดยเปรียบเทียบ body ของคำร้องขอ MainAgent สองรายการที่ต่อเนื่องกัน:
+
+| 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` | สแต็กข้อความถูกตัดทอน | จำนวนข้อความของคำร้องขอปัจจุบันน้อยกว่าคำร้องขอก่อนหน้า โดยปกติเกิดจากการตัดทอนเมื่อหน้าต่างบริบทล้น |
+| `msg_modified` | ข้อความประวัติถูกแก้ไข | เนื้อหาข้อความนำหน้าไม่สอดคล้องกัน (ในการเพิ่มปกติ ข้อความนำหน้าควรเหมือนกันทุกประการ) |
+| `key_change` | การเปลี่ยนแปลงคีย์ที่ไม่ทราบสาเหตุ | fallback เมื่อไม่ตรงกับเงื่อนไขใดข้างต้น |
+
+## ลำดับความสำคัญในการตรวจสอบ
+
+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/th/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/th/KVCacheContent.md

@@ -0,0 +1,49 @@
+# เนื้อหาที่แคชใน KV-Cache
+
+## Prompt Caching คืออะไร?
+
+เมื่อคุณสนทนากับ Claude ทุกคำขอ API จะส่งบริบทการสนทนาทั้งหมด (system prompt + คำจำกัดความเครื่องมือ + ข้อความในอดีต) กลไก prompt caching ของ Anthropic จะแคชเนื้อหาคำนำหน้าที่คำนวณไว้แล้วบนเซิร์ฟเวอร์ หากคำขอถัดไปมีคำนำหน้าที่ตรงกัน ก็จะนำผลลัพธ์ที่แคชไว้มาใช้ซ้ำโดยตรง ข้ามการคำนวณซ้ำ ลดเวลาตอบสนองและค่าใช้จ่ายได้อย่างมาก
+
+ใน cc-viewer กลไกนี้เรียกว่า "KV-Cache" ซึ่งตรงกับ prompt caching ในระดับ Anthropic API ไม่ใช่ key-value cache ของชั้น attention ใน transformer ภายใน LLM
+
+## วิธีการทำงานของแคช
+
+Prompt caching ของ Anthropic รวมคีย์แคชในลำดับคงที่:
+
+```
+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, คำจำกัดความเครื่องมือ) แม้ว่าคำขอจะไม่มีแท็ก `cache_control` อย่างชัดเจน ดังนั้นเมื่อคุณไม่เห็นคุณสมบัตินี้ในเนื้อหาคำขอ ไม่ต้องสงสัย — เซิร์ฟเวอร์ได้ดำเนินการแคชเบื้องหลังแล้ว เพียงแต่ไม่ได้เปิดเผยข้อมูลนี้ให้ไคลเอนต์ทราบ นี่คือความเข้าใจโดยปริยายระหว่าง Claude Code กับ Anthropic API
+
+## "เนื้อหาที่แคชใน KV-Cache ปัจจุบัน" คืออะไร?
+
+"เนื้อหาที่แคชใน KV-Cache ปัจจุบัน" ที่แสดงใน cc-viewer คือเนื้อหาที่แยกออกมาจากคำขอ 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 จะให้มุมมองที่เป็นศูนย์กลาง ช่วยให้คุณยืนยันอย่างรวดเร็วว่าบริบทหลักไม่ได้เสื่อมลงหรือถูกปนเปื้อนด้วยเนื้อหาที่ไม่คาดคิด — โดยไม่ต้องตรวจสอบข้อความต้นฉบับทีละรายการ
+
+## กลยุทธ์การแคชหลายระดับ
+
+KV-Cache ที่ตรงกับ Claude Code ไม่ได้มีเพียงสำเนาเดียว เซิร์ฟเวอร์จะสร้างแคชแยกต่างหากสำหรับ Tools และ System Prompt ซึ่งเป็นอิสระจากแคชส่วน Messages ข้อดีของการออกแบบนี้คือ: เมื่อสแต็กข้อความเกิดความผิดพลาด (เช่น การตัดบริบท การแก้ไขข้อความ) และจำเป็นต้องสร้างใหม่ จะไม่ทำให้แคชของ Tools และ System Prompt เป็นโมฆะไปด้วย หลีกเลี่ยงการคำนวณใหม่ทั้งหมด
+
+นี่คือกลยุทธ์การเพิ่มประสิทธิภาพจากฝั่งเซิร์ฟเวอร์ในขั้นตอนปัจจุบัน — เพราะคำจำกัดความเครื่องมือและ System Prompt ค่อนข้างเสถียรในระหว่างการใช้งานปกติและไม่ค่อยเปลี่ยนแปลง การแคชแยกต่างหากจะลดค่าใช้จ่ายในการสร้างใหม่ที่ไม่จำเป็นให้มากที่สุด ดังนั้นเมื่อคุณสังเกตแคช คุณจะพบว่านอกจากการสร้าง Tools ใหม่ที่ต้องรีเฟรชแคชทั้งหมด การเสียหายของ System Prompt และ Messages ยังคงมีแคชที่สืบทอดได้
+
+## วงจรชีวิตของแคช
+
+- **การสร้าง**: ในคำขอแรกหรือหลังจากแคชหมดอายุ API จะสร้างแคชใหม่ (`cache_creation_input_tokens`)
+- **การเข้าถึง**: เมื่อคำขอถัดไปมีคำนำหน้าที่ตรงกัน แคชจะถูกนำกลับมาใช้ใหม่ (`cache_read_input_tokens`)
+- **การหมดอายุ**: แคชมี TTL 5 นาที (ระยะเวลาการมีชีวิต) และหมดอายุโดยอัตโนมัติเมื่อหมดเวลา
+- **การสร้างใหม่**: เมื่อ system prompt รายการเครื่องมือ โมเดล หรือเนื้อหาข้อความเปลี่ยนแปลง คีย์แคชไม่ตรงกัน จะเรียกใช้การสร้างแคชใหม่ในระดับที่ตรงกัน

package/concepts/th/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 | prompt หลักที่สมบูรณ์ของ Claude Code | prompt แบบย่อเฉพาะงาน |
+| อาร์เรย์ tools | มีเครื่องมือทั้งหมดที่ใช้ได้ | โดยปกติมีเฉพาะเครื่องมือที่จำเป็นสำหรับงานเท่านั้น |
+| ประวัติข้อความ | สะสมบริบทการสนทนาทั้งหมด | มีเฉพาะข้อความที่เกี่ยวข้องกับงานย่อย |
+| พฤติกรรมแคช | มี prompt caching (TTL 5 นาที) | โดยปกติไม่มีแคชหรือแคชขนาดเล็ก |

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

@@ -0,0 +1,25 @@
+# เข้าถึงผ่าน QR Code บนมือถือ
+
+## วิธีการทำงาน
+
+CC Viewer เริ่มเซิร์ฟเวอร์ HTTP และสร้าง**ที่อยู่ LAN** (เช่น `http://192.168.1.100:7008`) สแกน QR Code เพื่อเข้าถึง Claude Code จากมือถือผ่านเครือข่าย WiFi เดียวกัน
+
+## ทำไมเชื่อมต่อไม่ได้?
+
+1. **ไม่ได้อยู่ในเครือข่ายเดียวกัน** — มือถือและคอมพิวเตอร์ต้องเชื่อมต่อ WiFi เดียวกัน (เราเตอร์เดียวกัน/ชื่อเครือข่ายเดียวกัน)
+2. **ไฟร์วอลล์บล็อก** — ไฟร์วอลล์ของระบบอาจบล็อกการเชื่อมต่อขาเข้า
+3. **การแยกเครือข่ายองค์กร** — AP Isolation อาจป้องกันการสื่อสารระหว่างอุปกรณ์
+4. **VPN รบกวน** — VPN อาจรบกวนเส้นทางเครือข่าย
+
+## คำเตือนด้านความปลอดภัย
+
+> ⚠️ บริการ LAN ของ CC Viewer สามารถเข้าถึงได้จากทุกอุปกรณ์ในเครือข่ายเดียวกัน
+
+- ระวังเมื่อใช้ **WiFi สาธารณะ**
+- CC Viewer ใช้ **การยืนยันตัวตนด้วยโทเค็น** เพื่อปกป้องการเข้าถึง LAN
+- แนะนำให้ใช้ในเครือข่ายที่เชื่อถือได้
+
+## นอกเหนือจาก LAN
+
+- **เครื่องมือ Tunneling** — frp, ngrok, Tailscale เป็นต้น
+- **ปลั๊กอิน CC Viewer** — กำหนดค่า proxy middleware ผ่านระบบปลั๊กอิน