cc-viewer 1.2.1 → 1.2.2

package/concepts/ru/Tool-Write.md

@@ -0,0 +1,32 @@
+# Write
+
+## Определение
+
+Записывает содержимое в локальную файловую систему. Если файл уже существует, перезаписывает его.
+
+## Параметры
+
+| Параметр | Тип | Обязательный | Описание |
+|------|------|------|------|
+| `file_path` | string | Да | Абсолютный путь к файлу (должен быть абсолютным) |
+| `content` | string | Да | Содержимое для записи |
+
+## Сценарии использования
+
+**Подходящее применение:**
+- Создание новых файлов
+- Когда требуется полная перезапись содержимого файла
+
+**Неподходящее применение:**
+- Модификация локального содержимого файла — следует использовать Edit
+- Не следует проактивно создавать файлы документации (*.md) или README, если пользователь явно не просит
+
+## Примечания
+
+- Если целевой файл уже существует, его необходимо сначала прочитать через Read, иначе операция завершится ошибкой
+- Перезаписывает всё содержимое существующего файла
+- Предпочитайте Edit для редактирования существующих файлов, Write предназначен только для создания новых файлов или полной перезаписи
+
+## Значение в cc-viewer
+
+Вызов Write в логах запросов отображается как блок content `tool_use`, чей `input.content` содержит полное записанное содержимое.

package/concepts/ru/Tool-executeCode.md

@@ -0,0 +1,33 @@
+# executeCode (mcp__ide__executeCode)
+
+## Определение
+
+Выполняет код Python в ядре Jupyter текущего файла notebook.
+
+## Параметры
+
+| Параметр | Тип | Обязательный | Описание |
+|------|------|------|------|
+| `code` | string | Да | Код Python для выполнения |
+
+## Сценарии использования
+
+**Подходящее применение:**
+- Выполнение кода в среде Jupyter notebook
+- Тестирование фрагментов кода
+- Анализ данных и вычисления
+
+**Неподходящее применение:**
+- Выполнение кода вне среды Jupyter — следует использовать Bash
+- Модификация файлов — следует использовать Edit или Write
+
+## Примечания
+
+- Это инструмент MCP (Model Context Protocol), предоставляемый интеграцией с IDE
+- Код выполняется в текущем ядре Jupyter, состояние сохраняется между вызовами
+- Если пользователь явно не просит, следует избегать объявления переменных или изменения состояния ядра
+- После перезапуска ядра состояние теряется
+
+## Значение в cc-viewer
+
+executeCode — это инструмент MCP, появляющийся в массиве `tools` логов запросов под именем `mcp__ide__executeCode`. Его вызовы и возвраты следуют стандартному шаблону `tool_use` / `tool_result`. Добавление/удаление инструментов MCP вызывает изменение массива tools, что может привести к пересборке кеша.

package/concepts/ru/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Определение
+
+Получает диагностическую информацию языка из VS Code, включая синтаксические ошибки, ошибки типов, предупреждения lint и т.д.
+
+## Параметры
+
+| Параметр | Тип | Обязательный | Описание |
+|------|------|------|------|
+| `uri` | string | Нет | URI файла. Если не указан, получает диагностику всех файлов |
+
+## Сценарии использования
+
+**Подходящее применение:**
+- Проверка семантических проблем кода: синтаксис, типы, lint и т.д.
+- Верификация после редактирования кода на предмет новых ошибок
+- Замена команд Bash для проверки качества кода
+
+**Неподходящее применение:**
+- Запуск тестов — следует использовать Bash
+- Проверка ошибок времени выполнения — следует использовать Bash для выполнения кода
+
+## Примечания
+
+- Это инструмент MCP (Model Context Protocol), предоставляемый интеграцией с IDE
+- Доступен только в среде VS Code / IDE
+- Предпочитайте использование этого инструмента вместо команд Bash для проверки проблем с кодом
+
+## Значение в cc-viewer
+
+getDiagnostics — это инструмент MCP, появляющийся в массиве `tools` логов запросов под именем `mcp__ide__getDiagnostics`. Его вызовы и возвраты следуют стандартному шаблону `tool_use` / `tool_result`. Добавление/удаление инструментов MCP вызывает изменение массива tools, что может привести к пересборке кеша.

package/concepts/ru/Tools.md

@@ -0,0 +1,73 @@
+# Обзор инструментов Claude Code
+
+Claude Code предоставляет модели набор встроенных инструментов через механизм tool_use API Anthropic. Массив `tools` в каждом запросе MainAgent содержит полные определения JSON Schema этих инструментов, а модель вызывает их в ответе через блоки content `tool_use`.
+
+Ниже приведён категоризированный индекс всех инструментов.
+
+## Система агентов
+
+| Инструмент | Назначение |
+|------|------|
+| [Task](Tool-Task.md) | Запуск суб-агента (SubAgent) для обработки сложных многоэтапных задач |
+| [TaskOutput](Tool-TaskOutput.md) | Получение результата фоновой задачи |
+| [TaskStop](Tool-TaskStop.md) | Остановка работающей фоновой задачи |
+| [TaskCreate](Tool-TaskCreate.md) | Создание записи в структурированном списке задач |
+| [TaskGet](Tool-TaskGet.md) | Получение деталей задачи |
+| [TaskUpdate](Tool-TaskUpdate.md) | Обновление статуса задачи, зависимостей и т.д. |
+| [TaskList](Tool-TaskList.md) | Отображение списка всех задач |
+
+## Операции с файлами
+
+| Инструмент | Назначение |
+|------|------|
+| [Read](Tool-Read.md) | Чтение содержимого файла (поддержка текста, изображений, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Редактирование файла через точную замену строк |
+| [Write](Tool-Write.md) | Запись или перезапись файла |
+| [NotebookEdit](Tool-NotebookEdit.md) | Редактирование ячеек Jupyter notebook |
+
+## Поиск
+
+| Инструмент | Назначение |
+|------|------|
+| [Glob](Tool-Glob.md) | Поиск файлов по шаблону имени |
+| [Grep](Tool-Grep.md) | Поиск по содержимому файлов на основе ripgrep |
+
+## Терминал
+
+| Инструмент | Назначение |
+|------|------|
+| [Bash](Tool-Bash.md) | Выполнение команд shell |
+
+## Web
+
+| Инструмент | Назначение |
+|------|------|
+| [WebFetch](Tool-WebFetch.md) | Получение содержимого веб-страниц и обработка с помощью AI |
+| [WebSearch](Tool-WebSearch.md) | Запросы к поисковой системе |
+
+## Планирование и взаимодействие
+
+| Инструмент | Назначение |
+|------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Вход в режим планирования, проектирование плана реализации |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Выход из режима планирования и отправка плана на утверждение пользователю |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Задать вопрос пользователю для уточнения или принятия решения |
+
+## Расширения
+
+| Инструмент | Назначение |
+|------|------|
+| [Skill](Tool-Skill.md) | Выполнение навыка (slash command) |
+
+## Интеграция с IDE
+
+| Инструмент | Назначение |
+|------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Получение диагностической информации языка из VS Code |
+| [executeCode](Tool-executeCode.md) | Выполнение кода в ядре Jupyter |
+
+## Значение в cc-viewer
+
+Вызовы инструментов — одни из наиболее важных наблюдаемых данных в логах запросов Claude Code. Массив `tools` каждого запроса MainAgent определяет набор инструментов, доступных модели, а блоки content `tool_use` / `tool_result` в ответе фиксируют фактические вызовы инструментов и их результаты. cc-viewer парсит эти данные для воссоздания полной цепочки вызовов инструментов в Chat Mode.
+
+Изменения в определениях инструментов (например, добавление/удаление инструментов из-за подключения/отключения MCP-сервера) вызывают пересборку кеша, подробнее в [CacheRebuild](CacheRebuild.md).

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/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/CacheRebuild.md

@@ -0,0 +1,40 @@
+# 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` แทนที่ข้อความต้นฉบับด้วยสรุปแบบบีบอัด)
+
+## การแสดงผลใน cc-viewer
+
+ในรายการคำร้องขอ คำร้องขอที่มีการสร้างแคชใหม่จะแสดงตัวบ่งชี้จุดสีแดงในบรรทัดแคช เมื่อเลื่อนเมาส์ไปวาง tooltip จะแสดงคำอธิบายสาเหตุการสร้างใหม่โดยเฉพาะ (รองรับ 18 ภาษา)

package/concepts/th/MainAgent.md

@@ -0,0 +1,30 @@
+# 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 นาที) | โดยปกติไม่มีแคชหรือแคชขนาดเล็ก |
+
+## ความสำคัญใน cc-viewer
+
+- **การติดตามแคช**: สถานะ prompt caching ของคำร้องขอ MainAgent ส่งผลโดยตรงต่อค่าใช้จ่าย โดยการตรวจสอบสัดส่วนระหว่าง `cache_creation_input_tokens` กับ `cache_read_input_tokens` สามารถประเมินอัตราการเข้าถึงแคชได้
+- **การวิเคราะห์การสูญเสียแคช**: เมื่อคำร้องขอ MainAgent มี cache creation จำนวนมาก (แทนที่จะเป็น cache read) แสดงว่าแคชสูญหายและถูกสร้างใหม่ cc-viewer จะทำเครื่องหมายคำร้องขอเหล่านี้ด้วยตัวบ่งชี้จุดสีแดง
+- **การวิเคราะห์สายหลัก**: ลำดับคำร้องขอ MainAgent สะท้อนกระบวนการโต้ตอบทั้งหมดของผู้ใช้กับ Claude Code ซึ่งเป็นข้อมูลหลักสำหรับการวิเคราะห์พฤติกรรมเซสชัน
+- **การสร้างเซสชันใหม่**: cc-viewer สร้างมุมมองการสนทนา (Chat Mode) ใหม่ผ่านประวัติข้อความของคำร้องขอ MainAgent

package/concepts/th/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## คำจำกัดความ
+
+ถามคำถามผู้ใช้ระหว่างการดำเนินงาน เพื่อขอคำชี้แจง ตรวจสอบสมมติฐาน หรือขอการตัดสินใจ
+
+## พารามิเตอร์
+
+| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `questions` | array | ใช่ | รายการคำถาม (1-4 คำถาม) |
+| `answers` | object | ไม่ | คำตอบที่รวบรวมจากผู้ใช้ |
+| `annotations` | object | ไม่ | หมายเหตุสำหรับแต่ละคำถาม (เช่น บันทึกการแสดงตัวอย่างตัวเลือก) |
+| `metadata` | object | ไม่ | ข้อมูลเมตาสำหรับการติดตามและวิเคราะห์ |
+
+แต่ละอ็อบเจกต์ `question`:
+
+| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `question` | string | ใช่ | ข้อความคำถามแบบเต็ม ควรลงท้ายด้วยเครื่องหมายคำถาม |
+| `header` | string | ใช่ | ป้ายกำกับสั้น (สูงสุด 12 ตัวอักษร) แสดงเป็นชิปแท็ก |
+| `options` | array | ใช่ | 2-4 ตัวเลือก |
+| `multiSelect` | boolean | ใช่ | อนุญาตให้เลือกหลายรายการหรือไม่ |
+
+แต่ละอ็อบเจกต์ `option`:
+
+| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `label` | string | ใช่ | ข้อความแสดงตัวเลือก (1-5 คำ) |
+| `description` | string | ใช่ | คำอธิบายตัวเลือก |
+| `markdown` | string | ไม่ | เนื้อหาแสดงตัวอย่าง (สำหรับการเปรียบเทียบภาพของเลย์เอาต์ ASCII, โค้ดสนิปเป็ต ฯลฯ) |
+
+## สถานการณ์การใช้งาน
+
+**เหมาะสำหรับ:**
+- รวบรวมความต้องการหรือข้อกำหนดของผู้ใช้
+- ชี้แจงคำสั่งที่คลุมเครือ
+- รับการตัดสินใจระหว่างการดำเนินงาน
+- เสนอทางเลือกทิศทางให้ผู้ใช้
+
+**ไม่เหมาะสำหรับ:**
+- ถามว่า "แผนนี้โอเคไหม?" — ควรใช้ ExitPlanMode
+
+## ข้อควรระวัง
+
+- ผู้ใช้สามารถเลือก "Other" เพื่อให้อินพุตที่กำหนดเองได้เสมอ
+- ตัวเลือกที่แนะนำควรอยู่ในลำดับแรก โดยเพิ่ม "(Recommended)" ที่ท้าย label
+- การแสดงตัวอย่าง `markdown` รองรับเฉพาะคำถามแบบเลือกรายการเดียว
+- ตัวเลือกที่มี `markdown` จะสลับเป็นเลย์เอาต์แบบเคียงข้างกัน
+- ในโหมดวางแผน ใช้เพื่อชี้แจงข้อกำหนดก่อนกำหนดแผน
+
+## ความสำคัญใน cc-viewer
+
+การเรียก AskUserQuestion ปรากฏในบันทึกคำร้องขอเป็น content block `tool_use` ซึ่งมีคำจำกัดความของคำถามและตัวเลือก คำตอบของผู้ใช้จะปรากฏในประวัติข้อความของคำร้องขอถัดไป

package/concepts/th/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## คำจำกัดความ
+
+รันคำสั่ง shell รองรับการตั้งค่า timeout เสริม ไดเรกทอรีทำงานจะคงอยู่ระหว่างคำสั่ง แต่สถานะ shell (ตัวแปรสภาพแวดล้อม ฯลฯ) จะไม่คงอยู่
+
+## พารามิเตอร์
+
+| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `command` | string | ใช่ | คำสั่ง bash ที่จะรัน |
+| `description` | string | ไม่ | คำอธิบายสั้นของคำสั่ง |
+| `timeout` | number | ไม่ | เวลา timeout (มิลลิวินาที) สูงสุด 600000 ค่าเริ่มต้น 120000 |
+| `run_in_background` | boolean | ไม่ | รันในเบื้องหลังหรือไม่ |
+
+## สถานการณ์การใช้งาน
+
+**เหมาะสำหรับ:**
+- การดำเนินการ git (commit, push, branch ฯลฯ)
+- คำสั่งจัดการแพ็กเกจ เช่น npm/yarn
+- การดำเนินการ docker
+- คำสั่งคอมไพล์และบิลด์
+- แสดงรายการเนื้อหาไดเรกทอรี (`ls`)
+- คำสั่งระบบอื่นๆ ที่ต้องการการรัน shell
+
+**ไม่เหมาะสำหรับ:**
+- อ่านไฟล์ — ควรใช้ Read
+- ค้นหาชื่อไฟล์ — ควรใช้ Glob
+- ค้นหาเนื้อหาไฟล์ — ควรใช้ Grep
+- แก้ไขไฟล์ — ควรใช้ Edit
+- เขียนไฟล์ — ควรใช้ Write
+- แสดงข้อมูลให้ผู้ใช้ — แสดงโดยตรงในข้อความตอบกลับ
+- กระบวนการที่ทำงานนาน (dev server, โหมด watch) — แนะนำให้ผู้ใช้รันเอง
+
+## ข้อควรระวัง
+
+- พาธที่มีช่องว่างต้องใส่เครื่องหมายคำพูดคู่
+- ผลลัพธ์ที่เกิน 30000 ตัวอักษรจะถูกตัดทอน
+- คำสั่งเบื้องหลังรับผลลัพธ์ผ่าน TaskOutput
+- ควรใช้พาธแบบสัมบูรณ์ หลีกเลี่ยง `cd`
+- คำสั่งอิสระสามารถเรียก Bash หลายตัวพร้อมกันได้
+- คำสั่งที่มีการพึ่งพาควรเชื่อมด้วย `&&`
+- สภาพแวดล้อม shell จะถูกเริ่มต้นจาก profile ของผู้ใช้ (bash หรือ zsh)
+
+## ความสำคัญใน cc-viewer
+
+การเรียก Bash ปรากฏในบันทึกคำร้องขอเป็นคู่ content block `tool_use` (มีคำสั่ง) และ `tool_result` (มีผลลัพธ์) ผลลัพธ์การรันคำสั่งสามารถใช้วิเคราะห์พฤติกรรมการดำเนินงานของโมเดลได้

package/concepts/th/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## คำจำกัดความ
+
+แก้ไขไฟล์ด้วยการแทนที่สตริงที่แม่นยำ แทนที่ `old_string` ด้วย `new_string` ในไฟล์
+
+## พารามิเตอร์
+
+| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `file_path` | string | ใช่ | พาธแบบสัมบูรณ์ของไฟล์ที่จะแก้ไข |
+| `old_string` | string | ใช่ | ข้อความต้นฉบับที่จะถูกแทนที่ |
+| `new_string` | string | ใช่ | ข้อความใหม่หลังการแทนที่ (ต้องแตกต่างจาก old_string) |
+| `replace_all` | boolean | ไม่ | แทนที่ทุกรายการที่ตรงกันหรือไม่ ค่าเริ่มต้น `false` |
+
+## สถานการณ์การใช้งาน
+
+**เหมาะสำหรับ:**
+- แก้ไขส่วนโค้ดเฉพาะในไฟล์ที่มีอยู่
+- แก้ไขบัก อัปเดตลอจิก
+- เปลี่ยนชื่อตัวแปร (ใช้ร่วมกับ `replace_all: true`)
+- สถานการณ์ใดก็ตามที่ต้องการแก้ไขเนื้อหาไฟล์อย่างแม่นยำ
+
+**ไม่เหมาะสำหรับ:**
+- สร้างไฟล์ใหม่ — ควรใช้ Write
+- เขียนใหม่ขนาดใหญ่ — อาจต้องใช้ Write เพื่อเขียนทับไฟล์ทั้งหมด
+
+## ข้อควรระวัง
+
+- ก่อนใช้ต้องอ่านไฟล์ผ่าน Read ก่อน มิฉะนั้นจะเกิดข้อผิดพลาด
+- `old_string` ต้องไม่ซ้ำกันในไฟล์ มิฉะนั้นการแก้ไขจะล้มเหลว หากไม่ไม่ซ้ำกัน ให้เพิ่มบริบทเพื่อให้ไม่ซ้ำกัน หรือใช้ `replace_all`
+- เมื่อแก้ไขข้อความต้องรักษาการเยื้องต้นฉบับ (tab/ช่องว่าง) อย่ารวมคำนำหน้าหมายเลขบรรทัดจากผลลัพธ์ Read
+- ควรแก้ไขไฟล์ที่มีอยู่มากกว่าสร้างไฟล์ใหม่
+- `new_string` ต้องแตกต่างจาก `old_string`
+
+## ความสำคัญใน cc-viewer
+
+การเรียก Edit ปรากฏในบันทึกคำร้องขอเป็น content block `tool_use` ซึ่ง `input` มี `old_string` และ `new_string` สามารถใช้ติดตามว่าโมเดลทำการแก้ไขอะไรในไฟล์

package/concepts/th/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## คำจำกัดความ
+
+สลับ Claude Code เข้าสู่โหมดวางแผน ใช้สำหรับสำรวจโค้ดเบสและออกแบบแผนก่อนการดำเนินงาน
+
+## พารามิเตอร์
+
+ไม่มีพารามิเตอร์
+
+## สถานการณ์การใช้งาน
+
+**เหมาะสำหรับ:**
+- การพัฒนาฟีเจอร์ใหม่ — ต้องการการตัดสินใจด้านสถาปัตยกรรม
+- มีหลายแนวทางที่เป็นไปได้ — ต้องการให้ผู้ใช้เลือก
+- การแก้ไขโค้ดส่งผลต่อพฤติกรรมหรือโครงสร้างที่มีอยู่
+- การเปลี่ยนแปลงหลายไฟล์ — อาจเกี่ยวข้องกับ 2-3 ไฟล์ขึ้นไป
+- ข้อกำหนดไม่ชัดเจน — ต้องสำรวจก่อนเพื่อเข้าใจขอบเขต
+- ความต้องการของผู้ใช้สำคัญ — การดำเนินงานอาจมีหลายทิศทางที่สมเหตุสมผล
+
+**ไม่เหมาะสำหรับ:**
+- การแก้ไขบรรทัดเดียวหรือไม่กี่บรรทัด (พิมพ์ผิด, บักที่ชัดเจน)
+- ผู้ใช้ให้คำสั่งที่เฉพาะเจาะจงมากแล้ว
+- งานวิจัย/สำรวจล้วนๆ — ควรใช้ Task (ประเภท Explore)
+
+## พฤติกรรมในโหมดวางแผน
+
+หลังจากเข้าสู่โหมดวางแผน Claude Code จะ:
+1. ใช้เครื่องมือ Glob, Grep, Read เพื่อสำรวจโค้ดเบสอย่างลึกซึ้ง
+2. ทำความเข้าใจรูปแบบและสถาปัตยกรรมที่มีอยู่
+3. ออกแบบแผนการดำเนินงาน
+4. ส่งแผนให้ผู้ใช้อนุมัติ
+5. ใช้ AskUserQuestion หากต้องการคำชี้แจง
+6. ออกผ่าน ExitPlanMode เมื่อแผนพร้อม
+
+## ข้อควรระวัง
+
+- เครื่องมือนี้ต้องได้รับความยินยอมจากผู้ใช้เพื่อเข้าสู่โหมดวางแผน
+- หากไม่แน่ใจว่าต้องวางแผนหรือไม่ ให้เลือกวางแผน — การจัดแนวล่วงหน้าดีกว่าการทำงานซ้ำ
+
+## ความสำคัญใน cc-viewer
+
+การเรียก EnterPlanMode ปรากฏในบันทึกคำร้องขอเป็น content block `tool_use` หลังจากเข้าสู่โหมดวางแผน ลำดับคำร้องขอมักจะเป็นการเรียกเครื่องมือสำรวจ (Glob, Grep, Read) เป็นหลัก จนกว่า ExitPlanMode จะถูกเรียก

package/concepts/th/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## คำจำกัดความ
+
+ออกจากโหมดวางแผนและส่งแผนให้ผู้ใช้อนุมัติ เนื้อหาแผนจะถูกอ่านจากไฟล์แผนที่เขียนไว้ก่อนหน้า
+
+## พารามิเตอร์
+
+| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `allowedPrompts` | array | ไม่ | รายการคำอธิบายสิทธิ์ที่จำเป็นสำหรับแผนการดำเนินงาน |
+
+แต่ละองค์ประกอบในอาร์เรย์ `allowedPrompts`:
+
+| ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `tool` | enum | ใช่ | เครื่องมือที่ใช้ได้ ปัจจุบันรองรับเฉพาะ `Bash` |
+| `prompt` | string | ใช่ | คำอธิบายเชิงความหมายของการดำเนินงาน (เช่น "run tests", "install dependencies") |
+
+## สถานการณ์การใช้งาน
+
+**เหมาะสำหรับ:**
+- ในโหมดวางแผน เมื่อแผนเสร็จสมบูรณ์และพร้อมส่งให้ผู้ใช้อนุมัติ
+- ใช้เฉพาะสำหรับงานดำเนินการที่ต้องเขียนโค้ด
+
+**ไม่เหมาะสำหรับ:**
+- งานวิจัย/สำรวจล้วนๆ — ไม่จำเป็นต้องออกจากโหมดวางแผน
+- ต้องการถามผู้ใช้ว่า "แผนนี้โอเคไหม?" — นี่คือฟังก์ชันของเครื่องมือนี้เอง อย่าใช้ AskUserQuestion เพื่อถาม
+
+## ข้อควรระวัง
+
+- เครื่องมือนี้ไม่รับเนื้อหาแผนเป็นพารามิเตอร์ — มันอ่านจากไฟล์แผนที่เขียนไว้ก่อนหน้า
+- ผู้ใช้จะเห็นเนื้อหาของไฟล์แผนเพื่ออนุมัติ
+- อย่าใช้ AskUserQuestion ถามว่า "แผนโอเคไหม?" ก่อนเรียกเครื่องมือนี้ เพราะเป็นการซ้ำซ้อน
+- อย่ากล่าวถึง "แผน" ในคำถาม เพราะผู้ใช้ไม่สามารถเห็นเนื้อหาแผนก่อน ExitPlanMode
+
+## ความสำคัญใน cc-viewer
+
+การเรียก ExitPlanMode เป็นเครื่องหมายสิ้นสุดขั้นตอนการวางแผน ในบันทึกคำร้องขอ คำร้องขอหลังจากการเรียกนี้มักจะเปลี่ยนเป็นการดำเนินงานเชิงปฏิบัติ (Edit, Write, Bash ฯลฯ)

package/concepts/th/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## คำจำกัดความ
+
+เครื่องมือจับคู่รูปแบบชื่อไฟล์ที่รวดเร็ว รองรับโค้ดเบสทุกขนาด ส่งคืนพาธไฟล์ที่ตรงกันเรียงตามเวลาแก้ไข
+
+## พารามิเตอร์
+
+| พารามิเตอร์ | ประเภท | จำเป็น | คำอธิบาย |
+|------|------|------|------|
+| `pattern` | string | ใช่ | รูปแบบ glob (เช่น `**/*.js`, `src/**/*.ts`) |
+| `path` | string | ไม่ | ไดเรกทอรีค้นหา ค่าเริ่มต้นคือไดเรกทอรีทำงานปัจจุบัน อย่าส่ง "undefined" หรือ "null" |
+
+## สถานการณ์การใช้งาน
+
+**เหมาะสำหรับ:**
+- ค้นหาไฟล์ตามรูปแบบชื่อ
+- ค้นหาไฟล์ทั้งหมดของประเภทเฉพาะ (เช่น ไฟล์ `.tsx` ทั้งหมด)
+- ระบุตำแหน่งไฟล์เมื่อค้นหาคำจำกัดความคลาสเฉพาะ (เช่น `class Foo`)
+- สามารถเรียก Glob หลายครั้งพร้อมกันในข้อความเดียว
+
+**ไม่เหมาะสำหรับ:**
+- ค้นหาเนื้อหาไฟล์ — ควรใช้ Grep
+- การสำรวจแบบเปิดที่ต้องค้นหาหลายรอบ — ควรใช้ Task (ประเภท Explore)
+
+## ข้อควรระวัง
+
+- รองรับไวยากรณ์ glob มาตรฐาน: `*` จับคู่ระดับเดียว, `**` จับคู่หลายระดับ, `{}` จับคู่หลายตัวเลือก
+- ผลลัพธ์เรียงตามเวลาแก้ไข
+- แนะนำให้ใช้มากกว่าคำสั่ง `find` ของ Bash
+
+## ความสำคัญใน cc-viewer
+
+การเรียก Glob ปรากฏในบันทึกคำร้องขอเป็นคู่ content block `tool_use` / `tool_result` โดย `tool_result` มีรายการพาธไฟล์ที่ตรงกัน