cc-viewer 1.6.49 → 1.6.50

package/concepts/th/ToolsFirst.md

@@ -0,0 +1,47 @@
+# ทำไม Tools ถึงแสดงก่อน?
+
+ในแผง Context ของ cc-viewer **Tools จะปรากฏก่อน System Prompt และ Messages** ลำดับนี้สะท้อนให้เห็นถึง **ลำดับ prefix ของ KV-Cache ใน Anthropic API** อย่างแม่นยำ
+
+## ลำดับ prefix ของ KV-Cache
+
+เมื่อ Anthropic API สร้าง KV-Cache จะเชื่อมต่อบริบทเป็น prefix ตาม **ลำดับที่ตายตัว** นี้:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+หมายความว่า **Tools อยู่ก่อน System Prompt ที่จุดเริ่มต้นของ cache prefix**
+
+## ทำไม Tools จึงมีน้ำหนักใน cache มากกว่า System?
+
+ในการจับคู่ prefix ของ KV-Cache **เนื้อหาที่อยู่ก่อนหน้ามีความสำคัญมากกว่า** — การเปลี่ยนแปลงใดๆ จะทำให้ทุกอย่างที่ตามมาเป็นโมฆะ:
+
+1. **การจับคู่ prefix เริ่มต้นจากจุดเริ่มต้น**: KV-Cache เปรียบเทียบคำขอปัจจุบันกับ prefix ที่แคชไว้ทีละ token จากจุดเริ่มต้น เมื่อพบความไม่ตรงกัน เนื้อหาทั้งหมดที่ตามมาจะถูกทำให้เป็นโมฆะ
+
+2. **Tools เปลี่ยน = cache ทั้งหมดเป็นโมฆะ**: เนื่องจาก Tools อยู่ก่อน การเปลี่ยนแปลงใดๆ ในนิยามของเครื่องมือ (แม้แต่การเพิ่มหรือลบ MCP tool เพียงอันเดียว) จะ **ทำลาย prefix จากจุดเริ่มต้น** ทำให้ System Prompt และ Messages ที่แคชไว้ทั้งหมดเป็นโมฆะ
+
+3. **System เปลี่ยน = cache ของ Messages เป็นโมฆะ**: System Prompt อยู่ตรงกลาง ดังนั้นการเปลี่ยนแปลงจึงทำให้เฉพาะส่วน Messages ที่ตามมาเป็นโมฆะ
+
+4. **Messages เปลี่ยน = ส่งผลเฉพาะส่วนท้าย**: Messages อยู่ท้ายสุด ดังนั้นการเพิ่มข้อความใหม่จะทำให้เฉพาะส่วนท้ายเล็กๆ เป็นโมฆะ — cache ของ Tools และ System ยังคงสมบูรณ์
+
+## ผลกระทบในทางปฏิบัติ
+
+| ประเภทการเปลี่ยนแปลง | ผลกระทบต่อ cache | สถานการณ์ทั่วไป |
+|----------------------|-----------------|-----------------|
+| เพิ่ม/ลบ Tool | **เป็นโมฆะทั้งหมด** | เชื่อมต่อ/ตัดการเชื่อมต่อ MCP server, เปิด/ปิด IDE plugin |
+| เปลี่ยน System Prompt | สูญเสีย cache ของ Messages | แก้ไข CLAUDE.md, การฉีด system reminder |
+| เพิ่มข้อความใหม่ | เพิ่มเฉพาะส่วนท้ายเท่านั้น | การสนทนาปกติ (พบบ่อยที่สุด, ถูกที่สุด) |
+
+นี่คือเหตุผลที่ `tools_change` ใน [CacheRebuild](CacheRebuild.md) มักเป็นเหตุผลของการสร้างใหม่ที่แพงที่สุด — มันทำลายห่วงโซ่ prefix ตั้งแต่ด้านหน้าสุด
+
+## การออกแบบเลย์เอาต์ของ cc-viewer
+
+cc-viewer จัดเรียงแผง Context ให้ตรงกับลำดับ prefix ของ KV-Cache:
+
+- **ลำดับจากบนลงล่าง = ลำดับการเชื่อมต่อ prefix ของ cache**
+- **การเปลี่ยนแปลงที่อยู่สูงกว่ามีผลกระทบต่ออัตรา cache hit มากกว่า**
+- เมื่อใช้ร่วมกับแผง [KV-Cache-Text](KVCacheContent.md) คุณสามารถดูข้อความ prefix ของ cache ทั้งหมดได้โดยตรง

package/concepts/tr/ToolsFirst.md

@@ -0,0 +1,47 @@
+# Tools Neden İlk Sırada Gösterilir?
+
+cc-viewer'ın Bağlam panelinde **Tools, System Prompt ve Messages'tan önce görünür**. Bu sıralama, **Anthropic API'nin KV-Cache önek sırasını** tam olarak yansıtır.
+
+## KV-Cache Önek Sırası
+
+Anthropic'in API'si KV-Cache'i oluştururken, bağlamı bu **sabit sırayla** bir önek olarak birleştirir:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Bu, **Tools'un cache önekinin en başında System Prompt'tan önce yer aldığı** anlamına gelir.
+
+## Tools Neden System'dan Daha Fazla Cache Ağırlığına Sahip?
+
+KV-Cache önek eşleştirmesinde **önceki içerik daha kritiktir** — herhangi bir değişiklik, sonrasındaki her şeyi geçersiz kılar:
+
+1. **Önek eşleştirmesi baştan başlar**: KV-Cache, mevcut isteği önbellekteki önekle baştan token token karşılaştırır. Bir uyuşmazlık bulunduğu anda, sonraki tüm içerik geçersiz kılınır.
+
+2. **Tools değişirse = tüm cache geçersiz**: Tools ilk sırada olduğundan, araç tanımlarındaki herhangi bir değişiklik (tek bir MCP tool eklenmesi veya kaldırılması bile) **öneki en başından bozar** ve önbelleğe alınan tüm System Prompt ile Messages'ı geçersiz kılar.
+
+3. **System değişirse = Messages cache geçersiz**: System Prompt ortada yer aldığından, değişiklikler yalnızca sonrasındaki Messages bölümünü geçersiz kılar.
+
+4. **Messages değişirse = yalnızca kuyruk etkilenir**: Messages en sonda yer aldığından, yeni mesajlar eklemek yalnızca küçük bir son segmenti geçersiz kılar — Tools ve System cache'i bütün kalır.
+
+## Pratik Etki
+
+| Değişiklik Türü | Cache Etkisi | Tipik Senaryo |
+|-----------------|-------------|---------------|
+| Tool eklendi/kaldırıldı | **Tam geçersizleştirme** | MCP sunucu bağlan/kes, IDE eklentisi aç/kapat |
+| System Prompt değişikliği | Messages cache kaybı | CLAUDE.md düzenleme, system reminder enjeksiyonu |
+| Yeni mesaj eklendi | Yalnızca kuyruk artışı | Normal konuşma akışı (en yaygın, en ucuz) |
+
+Bu nedenle [CacheRebuild](CacheRebuild.md)'deki `tools_change`, genellikle en pahalı yeniden oluşturma nedenidir — önek zincirini en baştan kırar.
+
+## cc-viewer'ın Düzen Tasarımı
+
+cc-viewer, Bağlam panelini KV-Cache önek sırasına uyacak şekilde düzenler:
+
+- **Yukarıdan aşağıya sıra = cache önek birleştirme sırası**
+- **Daha yukarıdaki değişikliklerin cache isabet oranına etkisi daha büyüktür**
+- [KV-Cache-Text](KVCacheContent.md) paneliyle birlikte, tam cache önek metnini doğrudan görebilirsiniz

package/concepts/uk/ToolsFirst.md

@@ -0,0 +1,47 @@
+# Чому Tools відображаються першими?
+
+На панелі Context у cc-viewer **Tools з'являються перед System Prompt та Messages**. Такий порядок точно відображає **послідовність префікса KV-Cache в Anthropic API**.
+
+## Послідовність префікса KV-Cache
+
+Коли Anthropic API будує KV-Cache, він об'єднує контекст у префікс у такому **фіксованому порядку**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+Це означає, що **Tools розміщені перед System Prompt на самому початку префікса кешу**.
+
+## Чому Tools мають більшу вагу в кеші, ніж System?
+
+При зіставленні префіксів KV-Cache **більш раннє розташування контенту є більш критичним** — будь-яка зміна скасовує все, що йде після:
+
+1. **Зіставлення префіксів починається з початку**: KV-Cache порівнює поточний запит із кешованим префіксом token за token від початку. Щойно виявляється розбіжність, весь наступний контент стає недійсним.
+
+2. **Зміна Tools = весь кеш скасовано**: Оскільки Tools стоять першими, будь-яка зміна у визначеннях інструментів (навіть додавання або видалення одного MCP tool) **ламає префікс з самого початку**, роблячи недійсними весь кешований System Prompt та Messages.
+
+3. **Зміна System = кеш Messages скасовано**: System Prompt розташований посередині, тому його зміни скасовують лише наступну частину Messages.
+
+4. **Зміна Messages = впливає тільки на хвіст**: Messages знаходяться в кінці, тому додавання нових повідомлень скасовує лише невеликий кінцевий сегмент — кеш Tools та System залишається незайманим.
+
+## Практичний вплив
+
+| Тип зміни | Вплив на кеш | Типовий сценарій |
+|-----------|-------------|-----------------|
+| Tool додано/видалено | **Повне скасування** | Підключення/відключення MCP server, увімкнення/вимкнення плагіна IDE |
+| Зміна System Prompt | Втрата кешу Messages | Редагування CLAUDE.md, ін'єкція system reminder |
+| Додано нове повідомлення | Лише хвостове збільшення | Звичайний хід розмови (найпоширеніший, найдешевший) |
+
+Саме тому `tools_change` у [CacheRebuild](CacheRebuild.md) зазвичай є найдорожчою причиною перебудови — вона ламає ланцюг префіксів з самого початку.
+
+## Дизайн макету cc-viewer
+
+cc-viewer розташовує панель Context відповідно до послідовності префікса KV-Cache:
+
+- **Порядок зверху вниз = порядок об'єднання префікса кешу**
+- **Зміни вище мають більший вплив на частоту влучань у кеш**
+- У поєднанні з панеллю [KV-Cache-Text](KVCacheContent.md) ви можете безпосередньо бачити повний текст префікса кешу

package/concepts/zh/ToolsFirst.md

@@ -0,0 +1,47 @@
+# 为什么工具排在第一位？
+
+在 cc-viewer 的 Context 面板中，**工具（Tools）被放在 System Prompt 和 Messages 之前**。这不是随意排列，而是为了**精确反映 Anthropic API 的实际 KV-Cache 前缀顺序**。
+
+## KV-Cache 前缀序列
+
+Anthropic API 在构建 KV-Cache 时，按以下**固定顺序**将上下文拼接为前缀序列：
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema 定义)                      │  ← 缓存前缀的最前端
+│ 2. System Prompt                                 │
+│ 3. Messages (历史对话 + 当前 turn)               │  ← 缓存前缀的最后端
+└─────────────────────────────────────────────────┘
+```
+
+这意味着 **Tools 比 System Prompt 更靠近缓存前缀的起始位置**。
+
+## 为什么 Tools 的缓存权重比 System 还高？
+
+在 KV-Cache 的前缀匹配机制中，**越靠前的内容越稳定**，对缓存命中的影响越大：
+
+1. **前缀匹配是从头开始的**：KV-Cache 通过比较当前请求与上一次缓存的前缀序列来决定能复用多少。从第一个 token 开始逐一比较，一旦遇到不匹配就中断，后续全部失效。
+
+2. **Tools 变化 = 全部缓存失效**：因为 Tools 在最前面，如果工具定义发生任何变化（哪怕只是增减一个 MCP tool），**整个缓存前缀从头开始就不匹配**，所有后续的 System Prompt 和 Messages 缓存全部作废。
+
+3. **System 变化 = Messages 缓存失效**：System Prompt 在中间，它的变化只会导致后面的 Messages 缓存失效，但 Tools 部分的缓存仍然有效。
+
+4. **Messages 变化 = 只影响末尾**：Messages 在最后，新消息的追加只会让最后一小段缓存失效，前面的 Tools 和 System 缓存不受影响。
+
+## 实际影响
+
+| 变化类型 | 缓存影响 | 典型场景 |
+|----------|---------|---------|
+| 工具增减 | **全部失效** | MCP server 连接/断开、IDE 插件启停 |
+| System Prompt 变化 | Messages 缓存失效 | CLAUDE.md 修改、system reminder 注入 |
+| 新增消息 | 仅末尾增量 | 正常对话流（最常见，也最省钱） |
+
+这也是为什么 [CacheRebuild](CacheRebuild.md) 中 `tools_change` 导致的缓存重建成本往往最高 —— 它从最前面就打断了缓存前缀链。
+
+## cc-viewer 的排列设计
+
+cc-viewer 将 Context 面板的排列顺序设计为与 KV-Cache 前缀序列一致：
+
+- **从上到下的顺序 = 缓存前缀的拼接顺序**
+- **越靠上的部分变化，对缓存命中率的打击越大**
+- 配合 [KV-Cache-Text](KVCacheContent.md) 面板，可以直接看到缓存前缀的完整文本

package/concepts/zh-TW/ToolsFirst.md

@@ -0,0 +1,47 @@
+# 為什麼 Tools 排在最前面？
+
+在 cc-viewer 的 Context 面板中，**Tools 顯示在 System Prompt 和 Messages 之前**。這個排列順序精確地反映了 **Anthropic API 的 KV-Cache 前綴序列**。
+
+## KV-Cache 前綴序列
+
+當 Anthropic 的 API 建構 KV-Cache 時，會以這個**固定順序**將上下文串接為前綴：
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+這意味著 **Tools 位於 cache 前綴的最開頭，排在 System Prompt 之前**。
+
+## 為什麼 Tools 的 Cache 權重高於 System？
+
+在 KV-Cache 前綴比對中，**越靠前的內容越關鍵** — 任何變動都會使其後的所有內容失效：
+
+1. **前綴比對從頭開始**：KV-Cache 從起始位置逐 token 將當前請求與快取前綴進行比對。一旦發現不匹配，後續所有內容都會立即失效。
+
+2. **Tools 變動 = 整個 cache 失效**：由於 Tools 排在最前面，任何工具定義的變更（即使只是新增或移除一個 MCP tool）都會**從最開頭破壞前綴**，使所有已快取的 System Prompt 和 Messages 失效。
+
+3. **System 變動 = Messages cache 失效**：System Prompt 位於中間，因此其變更只會使後續的 Messages 部分失效。
+
+4. **Messages 變動 = 只影響尾部**：Messages 排在最後，因此新增訊息只會使末尾的一小段失效 — Tools 和 System 的 cache 仍保持完整。
+
+## 實際影響
+
+| 變動類型 | Cache 影響 | 典型情境 |
+|----------|-----------|---------|
+| Tool 新增/移除 | **完全失效** | MCP server 連線/斷線、IDE 插件切換 |
+| System Prompt 變更 | Messages cache 遺失 | CLAUDE.md 編輯、system reminder 注入 |
+| 新增訊息 | 僅尾部遞增 | 正常對話流程（最常見、成本最低） |
+
+這就是為什麼 [CacheRebuild](CacheRebuild.md) 中的 `tools_change` 往往是成本最高的重建原因 — 它從最前端破壞了前綴鏈。
+
+## cc-viewer 的版面設計
+
+cc-viewer 將 Context 面板的排列方式與 KV-Cache 前綴序列相對應：
+
+- **由上到下的順序 = cache 前綴串接順序**
+- **越靠上的變動對 cache 命中率的影響越大**
+- 搭配 [KV-Cache-Text](KVCacheContent.md) 面板，您可以直接查看完整的 cache 前綴文字