cc-viewer 1.2.1 → 1.2.2

package/concepts/th/Tools.md

@@ -0,0 +1,73 @@
+# ภาพรวมเครื่องมือของ Claude Code
+
+Claude Code มอบชุดเครื่องมือในตัวให้กับโมเดลผ่านกลไก tool_use ของ Anthropic API อาร์เรย์ `tools` ของคำร้องขอ MainAgent แต่ละรายการจะมีคำจำกัดความ JSON Schema ที่สมบูรณ์ของเครื่องมือเหล่านี้ และโมเดลจะเรียกใช้ผ่าน content block `tool_use` ในการตอบกลับ
+
+ต่อไปนี้คือดัชนีจำแนกตามหมวดหมู่ของเครื่องมือทั้งหมด
+
+## ระบบ Agent
+
+| เครื่องมือ | วัตถุประสงค์ |
+|------|------|
+| [Task](Tool-Task.md) | เริ่มต้น sub-agent (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 |
+
+## เว็บ
+
+| เครื่องมือ | วัตถุประสงค์ |
+|------|------|
+| [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 kernel |
+
+## ความสำคัญใน cc-viewer
+
+การเรียกใช้เครื่องมือเป็นหนึ่งในข้อมูลที่สังเกตได้สำคัญที่สุดในบันทึกคำร้องขอของ Claude Code อาร์เรย์ `tools` ของคำร้องขอ MainAgent แต่ละรายการกำหนดชุดเครื่องมือที่โมเดลใช้ได้ ในขณะที่ content block `tool_use` / `tool_result` ในการตอบกลับบันทึกการเรียกใช้เครื่องมือจริงและค่าที่ส่งคืน cc-viewer สร้างสายการเรียกใช้เครื่องมือที่สมบูรณ์ใน Chat Mode โดยการวิเคราะห์ข้อมูลเหล่านี้
+
+การเปลี่ยนแปลงคำจำกัดความเครื่องมือ (เช่น การเพิ่ม/ลบเครื่องมือจากการเชื่อมต่อ/ตัดการเชื่อมต่อ MCP server) จะทำให้เกิดการสร้างแคชใหม่ ดูรายละเอียดที่ [CacheRebuild](CacheRebuild.md)

package/concepts/th/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# การปนเปื้อนบริบทใน Translate API
+
+## ความเป็นมา
+
+CC-Viewer มีฟีเจอร์แปลภาษาในตัว (`POST /api/translate`) ที่ขับเคลื่อนโดย Anthropic Messages API ในการพัฒนาช่วงแรก คำขอแปลภาษาใช้ข้อมูลรับรองตัวตนที่แคชไว้จากเซสชัน Claude Code ซ้ำ — รวมถึงทั้ง header `x-api-key` และ `authorization` สิ่งนี้ทำให้เกิดปัญหาที่แนบเนียนแต่ร้ายแรง: ผลลัพธ์การแปลมักส่งคืนเนื้อหาที่ไม่เกี่ยวข้อง
+
+## สาเหตุหลัก
+
+### ความแตกต่างพื้นฐานระหว่างสองวิธีการรับรองตัวตน
+
+Anthropic API รองรับสองวิธีการรับรองตัวตน:
+
+| วิธี | Header | แหล่งที่มาทั่วไป | ลักษณะเฉพาะ |
+|------|--------|-------------------|-------------|
+| API Key | `x-api-key: sk-ant-...` | ตัวแปรสภาพแวดล้อม / Console | ไม่มีสถานะ แต่ละคำขอเป็นอิสระ |
+| OAuth Token | `authorization: Bearer sessionToken` | การเข้าสู่ระบบแบบสมัครสมาชิก Claude Code | ผูกกับเซสชัน เซิร์ฟเวอร์รักษาการเชื่อมโยงบริบท |
+
+ความแตกต่างสำคัญ: **API Key ไม่มีสถานะ** — แต่ละคำขอเป็นอิสระอย่างสมบูรณ์ ในขณะที่ **OAuth session token มีสถานะ** — เซิร์ฟเวอร์ Anthropic เชื่อมโยงคำขอที่ใช้โทเค็นเดียวกันเข้ากับบริบทเซสชันเดียวกัน
+
+### ห่วงโซ่การปนเปื้อน
+
+เมื่อ Claude Code ใช้การเข้าสู่ระบบ OAuth แบบสมัครสมาชิก กระบวนการรับรองตัวตนจะเป็นดังนี้:
+
+```
+การสนทนาหลักของ Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                          ↑
+คำขอแปลภาษาของ CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+เนื่องจากคำขอแปลภาษาใช้ session token เดียวกันซ้ำ เซิร์ฟเวอร์ Anthropic อาจเชื่อมโยงคำขอแปลภาษาเข้ากับบริบทการสนทนาหลักของ Claude Code ส่งผลให้:
+
+1. **ผลลัพธ์การแปลได้รับอิทธิพลจากบริบทการสนทนาหลัก**: system prompt ของคำขอแปลคือ "คุณคือนักแปล" แต่บริบทของเซิร์ฟเวอร์ยังคงมีประวัติการสนทนาของ Claude Code ซึ่งอาจรบกวนโมเดล
+2. **การสนทนาหลักถูกรบกวนจากคำขอแปลภาษา**: เนื้อหาของคำขอแปล (ส่วนข้อความ UI) อาจถูกแทรกเข้าไปในบริบทการสนทนาหลัก ทำให้คำตอบของ Claude Code เบี่ยงเบน
+3. **พฤติกรรมที่คาดเดาไม่ได้**: เนื่องจากการปนเปื้อนบริบทเป็นพฤติกรรมฝั่งเซิร์ฟเวอร์ ไคลเอนต์ไม่สามารถตรวจจับหรือควบคุมได้
+
+## บทเรียนที่ได้รับ
+
+- **OAuth session token ไม่ใช่ "แค่ API Key อีกตัว"** — มันมีสถานะฝั่งเซิร์ฟเวอร์ การใช้ซ้ำหมายถึงการแชร์บริบท
+- **การเรียกบริการภายในควรใช้การรับรองตัวตนแบบอิสระและไม่มีสถานะ** เพื่อหลีกเลี่ยงการเชื่อมโยงกับเซสชันของผู้ใช้
+
+## อ้างอิง
+
+- [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/tr/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (İstek Gövdesi Artımlı Karşılaştırma)
+
+## Arka Plan
+
+Claude Code'un MainAgent'ı tam bağlam gönderme mekanizması kullanır — her istek, konuşma geçmişinin tamamını, system prompt'u, araç tanımlarını ve diğer içerikleri taşır. Bu, konuşma ilerledikçe istek gövdesinin giderek büyüyeceği anlamına gelir ve ham Body'yi doğrudan inceleyerek "bu turda tam olarak ne eklendi" sorusunu yanıtlamak zorlaşır.
+
+Body Diff JSON tam olarak bu sorunu çözmek için tasarlanmıştır: ardışık iki MainAgent isteğinin gövdesini otomatik olarak karşılaştırır, artımlı kısmı çıkarır ve bu istekte gerçekten eklenen içeriği bir bakışta görmenizi sağlar.
+
+## Çalışma Prensibi
+
+1. **Ardışık MainAgent isteklerini tanımlama**: Mevcut istek MainAgent türünde olmalı ve bir önceki MainAgent isteği mevcut olmalıdır
+2. **Alan bazında karşılaştırma**: İstek gövdesinin tüm üst düzey alanları taranır, `_` önekli dahili özellikler atlanır
+3. **Akıllı fark çıkarma**:
+   - Eklenen alanlar: Doğrudan gösterilir
+   - Silinen alanlar: Gösterilmez (genellikle anlamayı etkilemez)
+   - Değişen alanlar: Mevcut değer gösterilir
+   - `messages` dizisi özel işlem görür: Yalnızca eklenen mesajlar gösterilir (normal konuşmada ekleme modunda çalışıldığından önek mesajlar değişmez)
+4. **İstek gövdesi küçülme tespiti**: Mevcut istek gövdesi bir öncekinden küçükse, bağlam kesme veya oturum sıfırlama gerçekleşmiş demektir; bu durumda diff yerine bilgi mesajı gösterilir
+
+## Tipik Senaryolar
+
+Normal bir konuşma turunda Body Diff JSON genellikle yalnızca şunları içerir:
+- `messages`: Eklenen 1~2 mesaj (kullanıcının girişi + bir önceki turun asistan yanıtı)
+
+Diff'te `system`, `tools`, `model` gibi alanların değişikliklerini görüyorsanız, bu turda yapılandırma değişikliği olduğu anlamına gelir ve bu genellikle önbellek yeniden oluşturmanın da nedenidir.
+
+## Kullanım Şekli
+
+- Body Diff JSON, MainAgent isteğinin detay panelinde gösterilir
+- Başlığa tıklayarak genişletip/daraltabilirsiniz
+- JSON ve Text olmak üzere iki görüntüleme modu ile tek tıkla kopyalama desteklenir
+- Sol üst köşedeki **CC-Viewer → Genel Ayarlar** bölümünden "Body Diff JSON'u varsayılan olarak genişlet" seçeneği ayarlanabilir

package/concepts/tr/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild (Önbellek Yeniden Oluşturma)
+
+## Arka Plan
+
+Anthropic'in prompt caching mekanizması, istekteki system → tools → messages (cache breakpoint'e kadar) sırasıyla birleştirerek önbellek anahtarı oluşturur. Önbellek anahtarı bir önceki istekle tamamen aynı olduğunda, API `cache_read_input_tokens` döndürür (önbellek isabet); önbellek anahtarı değiştiğinde, API önbelleği yeniden oluşturur ve büyük miktarda `cache_creation_input_tokens` döndürür, yani önbellek yeniden oluşturma gerçekleşir.
+
+Önbellek yeniden oluşturma ek token ücreti anlamına gelir (cache creation fiyatı cache read'den yüksektir), bu nedenle yeniden oluşturma nedenini belirlemek maliyet optimizasyonu için doğrudan değer taşır.
+
+## Önbellek Yeniden Oluşturma Neden Sınıflandırması
+
+cc-viewer, ardışık iki MainAgent isteğinin gövdesini karşılaştırarak önbellek yeniden oluşturma nedenini kesin olarak belirler:
+
+| reason | Anlamı | Belirleme Yöntemi |
+|--------|--------|-------------------|
+| `ttl` | Önbellek süresi doldu | Önceki MainAgent isteğinden bu yana 5 dakikadan fazla geçmiş |
+| `system_change` | system prompt değişikliği | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Araç tanımı değişikliği | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Model değişikliği | `prev.model !== curr.model` |
+| `msg_truncated` | Mesaj yığını kesildi | Mevcut isteğin messages sayısı öncekinden az, genellikle bağlam penceresi taşması nedeniyle kesme tetiklenir |
+| `msg_modified` | Geçmiş mesajlar değiştirildi | Önek mesaj içerikleri tutarsız (normal ekleme modunda önek tamamen aynı olmalıdır) |
+| `key_change` | Bilinmeyen anahtar değişikliği | Yukarıdaki koşulların hiçbiri eşleşmediğinde fallback |
+
+## Belirleme Önceliği
+
+1. Önce zaman aralığı kontrol edilir — 5 dakikayı aşarsa doğrudan `ttl` olarak belirlenir, body karşılaştırması yapılmaz
+2. Ardından sırasıyla model, system, tools, messages kontrol edilir
+3. Bir istek aynı anda birden fazla nedene sahip olabilir (örn. model değişikliği + system prompt değişikliği), bu durumda `reasons` dizisi tüm eşleşmeleri içerir, tooltip satır satır gösterir
+
+## Yaygın Senaryolar
+
+- **`ttl`**: Kullanıcı 5 dakikadan fazla ara verdikten sonra devam eder, önbellek doğal olarak sona erer
+- **`system_change`**: Claude Code system prompt'u güncelledi (örn. yeni CLAUDE.md yüklendi, project instructions değişti)
+- **`tools_change`**: MCP server bağlantı/kopma nedeniyle kullanılabilir araç listesi değişti
+- **`model_change`**: Kullanıcı `/model` komutuyla model değiştirdi
+- **`msg_truncated`**: Konuşma çok uzadığında bağlam penceresi yönetimi tetiklenir, Claude Code erken mesajları keser
+- **`msg_modified`**: Claude Code geçmiş mesajları düzenledi (örn. `/compact` sıkıştırma özeti orijinal mesajların yerini aldı)
+
+## cc-viewer'da Gösterim
+
+İstek listesinde, önbellek yeniden oluşturulan istekler cache satırında kırmızı nokta göstergesi ile gösterilir. Fare üzerine gelindiğinde tooltip görüntülenir ve yeniden oluşturma nedeninin açıklaması gösterilir (18 dil desteklenir).

package/concepts/tr/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## Tanım
+
+MainAgent, Claude Code'un agent team durumunda olmadığı zamanlardaki ana istek zinciridir. Kullanıcının Claude Code ile her etkileşimi bir dizi API isteği üretir ve bunlar arasında MainAgent istekleri çekirdek konuşma zincirini oluşturur — tam system prompt, araç tanımları ve mesaj geçmişi taşırlar.
+
+## Tanımlama Yöntemi
+
+cc-viewer'da MainAgent, `req.mainAgent === true` ile tanımlanır ve `interceptor.js` tarafından istek yakalama sırasında otomatik olarak işaretlenir.
+
+Belirleme koşulları (tümü karşılanmalı):
+- İstek gövdesi `system` alanı içerir (system prompt)
+- İstek gövdesi `tools` dizisi içerir (araç tanımları)
+- system prompt "Claude Code" karakteristik metni içerir
+
+## SubAgent ile Farkları
+
+| Özellik | MainAgent | SubAgent |
+|---------|-----------|----------|
+| system prompt | Tam Claude Code ana prompt'u | Göreve özel kısaltılmış prompt |
+| tools dizisi | Tüm kullanılabilir araçları içerir | Genellikle yalnızca görev için gereken az sayıda araç |
+| Mesaj geçmişi | Tam konuşma bağlamını biriktirir | Yalnızca alt görevle ilgili mesajlar |
+| Önbellek davranışı | Prompt caching var (5 dakika TTL) | Genellikle önbellek yok veya küçük önbellek |
+
+## cc-viewer'da Önemi
+
+- **Önbellek takibi**: MainAgent isteklerinin prompt caching durumu maliyeti doğrudan etkiler. `cache_creation_input_tokens` ile `cache_read_input_tokens` oranını izleyerek önbellek isabet oranı belirlenebilir
+- **Önbellek kaybı analizi**: MainAgent isteğinde yoğun cache creation (cache read yerine) görüldüğünde, önbellek kaybedilmiş ve yeniden oluşturulmuş demektir; cc-viewer bu istekleri kırmızı nokta göstergesiyle işaretler
+- **Ana zincir analizi**: MainAgent istek dizisi, kullanıcının Claude Code ile tam etkileşim sürecini yansıtır ve oturum davranışını analiz etmek için temel veridir
+- **Oturum yeniden oluşturma**: cc-viewer, MainAgent isteklerinin mesaj geçmişi aracılığıyla konuşma görünümünü (Chat Mode) yeniden oluşturur

package/concepts/tr/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## Tanım
+
+Yürütme sırasında kullanıcıya soru sorarak açıklama alma, varsayımları doğrulama veya karar isteme amacıyla kullanılır.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `questions` | array | Evet | Soru listesi (1-4 soru) |
+| `answers` | object | Hayır | Kullanıcıdan toplanan yanıtlar |
+| `annotations` | object | Hayır | Her soru için notlar (örn. önizleme seçimi açıklamaları) |
+| `metadata` | object | Hayır | İzleme ve analiz için meta veriler |
+
+Her `question` nesnesi:
+
+| Alan | Tür | Zorunlu | Açıklama |
+|------|-----|---------|----------|
+| `question` | string | Evet | Tam soru metni, soru işaretiyle bitmelidir |
+| `header` | string | Evet | Kısa etiket (en fazla 12 karakter), etiket çipi olarak gösterilir |
+| `options` | array | Evet | 2-4 seçenek |
+| `multiSelect` | boolean | Evet | Çoklu seçime izin verilip verilmediği |
+
+Her `option` nesnesi:
+
+| Alan | Tür | Zorunlu | Açıklama |
+|------|-----|---------|----------|
+| `label` | string | Evet | Seçenek görüntüleme metni (1-5 kelime) |
+| `description` | string | Evet | Seçenek açıklaması |
+| `markdown` | string | Hayır | Önizleme içeriği (ASCII düzeni, kod parçacıkları vb. için görsel karşılaştırma) |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Kullanıcı tercihlerini veya gereksinimlerini toplama
+- Belirsiz talimatları netleştirme
+- Uygulama sürecinde karar alma
+- Kullanıcıya yön seçenekleri sunma
+
+**Kullanıma uygun değil:**
+- "Plan uygun mu?" diye sormak — ExitPlanMode kullanılmalıdır
+
+## Dikkat Edilecekler
+
+- Kullanıcı her zaman "Other" seçerek özel girdi sağlayabilir
+- Önerilen seçenek ilk sıraya konulmalı ve label sonuna "(Recommended)" eklenmelidir
+- `markdown` önizlemesi yalnızca tek seçimli sorularda desteklenir
+- `markdown` içeren seçenekler yan yana düzene geçer
+- Planlama modunda, planı kesinleştirmeden önce gereksinimleri netleştirmek için kullanılır
+
+## cc-viewer'da Önemi
+
+AskUserQuestion çağrısı istek günlüğünde `tool_use` content block olarak görünür ve soru ile seçenek tanımlarını içerir. Kullanıcının yanıtı sonraki isteklerin mesaj geçmişinde yer alır.

package/concepts/tr/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## Tanım
+
+Shell komutu çalıştırır, isteğe bağlı zaman aşımı ayarını destekler. Çalışma dizini komutlar arasında kalıcıdır, ancak shell durumu (ortam değişkenleri vb.) kalıcı değildir.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `command` | string | Evet | Çalıştırılacak bash komutu |
+| `description` | string | Hayır | Komutun kısa açıklaması |
+| `timeout` | number | Hayır | Zaman aşımı süresi (milisaniye), maksimum 600000, varsayılan 120000 |
+| `run_in_background` | boolean | Hayır | Arka planda çalıştırılıp çalıştırılmayacağı |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- git işlemleri (commit, push, branch vb.)
+- npm/yarn gibi paket yönetim komutları
+- docker işlemleri
+- Derleme, build komutları
+- Dizin içeriğini listeleme (`ls`)
+- Shell çalıştırması gerektiren diğer sistem komutları
+
+**Kullanıma uygun değil:**
+- Dosya okuma — Read kullanılmalıdır
+- Dosya adı arama — Glob kullanılmalıdır
+- Dosya içeriği arama — Grep kullanılmalıdır
+- Dosya düzenleme — Edit kullanılmalıdır
+- Dosya yazma — Write kullanılmalıdır
+- Kullanıcıya bilgi çıktısı — doğrudan yanıt metninde çıktı verilmelidir
+- Uzun süre çalışan işlemler (dev server, watch modu) — kullanıcının manuel çalıştırması önerilir
+
+## Dikkat Edilecekler
+
+- Boşluk içeren yollar çift tırnak ile sarılmalıdır
+- 30000 karakteri aşan çıktılar kesilir
+- Arka planda çalışan komutların sonuçları TaskOutput ile alınır
+- Mümkün olduğunca mutlak yol kullanılmalı, `cd`'den kaçınılmalıdır
+- Bağımsız komutlar paralel olarak birden fazla Bash çağrısıyla çalıştırılabilir
+- Bağımlılığı olan komutlar `&&` ile zincirlenir
+- Shell ortamı kullanıcının profilinden (bash veya zsh) başlatılır
+
+## cc-viewer'da Önemi
+
+Bash çağrıları istek günlüğünde `tool_use` (komutu içerir) ve `tool_result` (çıktıyı içerir) content block çifti olarak görünür. Komut çalıştırma çıktısı, modelin işlem davranışını analiz etmek için kullanılabilir.

package/concepts/tr/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## Tanım
+
+Kesin dize değiştirme yoluyla dosya düzenler. Dosyadaki `old_string`'i `new_string` ile değiştirir.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `file_path` | string | Evet | Değiştirilecek dosyanın mutlak yolu |
+| `old_string` | string | Evet | Değiştirilecek orijinal metin |
+| `new_string` | string | Evet | Değiştirme sonrası yeni metin (old_string'den farklı olmalıdır) |
+| `replace_all` | boolean | Hayır | Tüm eşleşmelerin değiştirilip değiştirilmeyeceği, varsayılan `false` |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Mevcut dosyadaki belirli kod bölümlerini değiştirme
+- Hata düzeltme, mantık güncelleme
+- Değişken yeniden adlandırma (`replace_all: true` ile birlikte)
+- Dosya içeriğinin kesin değişiklik gerektirdiği tüm senaryolar
+
+**Kullanıma uygun değil:**
+- Yeni dosya oluşturma — Write kullanılmalıdır
+- Büyük ölçekli yeniden yazma — dosyanın tamamını üzerine yazmak için Write gerekebilir
+
+## Dikkat Edilecekler
+
+- Kullanmadan önce dosya Read ile okunmuş olmalıdır, aksi takdirde hata verir
+- `old_string` dosyada benzersiz olmalıdır, aksi takdirde düzenleme başarısız olur. Benzersiz değilse, daha fazla bağlam sağlayarak benzersiz hale getirin veya `replace_all` kullanın
+- Metin düzenlerken orijinal girintileme (tab/boşluk) korunmalıdır, Read çıktısındaki satır numarası önekini dahil etmeyin
+- Yeni dosya oluşturmak yerine mevcut dosyayı düzenlemeyi tercih edin
+- `new_string`, `old_string`'den farklı olmalıdır
+
+## cc-viewer'da Önemi
+
+Edit çağrıları istek günlüğünde `tool_use` content block olarak görünür; `input` alanı `old_string` ve `new_string` içerir ve modelin dosyada hangi değişiklikleri yaptığını izlemek için kullanılabilir.

package/concepts/tr/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## Tanım
+
+Claude Code'u planlama moduna geçirir; uygulamadan önce kod tabanını keşfetmek ve plan tasarlamak için kullanılır.
+
+## Parametreler
+
+Parametre yok.
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Yeni özellik uygulaması — mimari kararlar gerektirir
+- Birden fazla uygulanabilir yaklaşım var — kullanıcı seçimi gerektirir
+- Kod değişikliği mevcut davranışı veya yapıyı etkiler
+- Çoklu dosya değişikliği — 2-3'ten fazla dosya etkilenebilir
+- Gereksinimler belirsiz — önce keşfedip kapsamı anlamak gerekir
+- Kullanıcı tercihi önemli — uygulama birden fazla makul yönde olabilir
+
+**Kullanıma uygun değil:**
+- Tek satır veya az satırlık düzeltmeler (yazım hatası, belirgin bug)
+- Kullanıcı çok spesifik talimatlar vermiş
+- Salt araştırma/keşif görevi — Task (Explore türü) kullanılmalıdır
+
+## Planlama Modundaki Davranış
+
+Planlama moduna girdikten sonra Claude Code:
+1. Glob, Grep, Read araçlarını kullanarak kod tabanını derinlemesine keşfeder
+2. Mevcut kalıpları ve mimariyi anlar
+3. Uygulama planı tasarlar
+4. Planı kullanıcı onayına sunar
+5. Gerekirse AskUserQuestion ile açıklama isteyebilir
+6. Plan hazır olduğunda ExitPlanMode ile çıkar
+
+## Dikkat Edilecekler
+
+- Bu araç, planlama moduna girmek için kullanıcı onayı gerektirir
+- Planlama gerekip gerekmediğinden emin değilseniz, planlamayı tercih edin — önceden uyum sağlamak yeniden çalışmaktan iyidir
+
+## cc-viewer'da Önemi
+
+EnterPlanMode çağrısı istek günlüğünde `tool_use` content block olarak görünür. Planlama moduna girdikten sonraki istek dizisi genellikle keşif amaçlı araç çağrılarından (Glob, Grep, Read) oluşur ve ExitPlanMode çağrılana kadar devam eder.

package/concepts/tr/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## Tanım
+
+Planlama modundan çıkar ve planı kullanıcı onayına sunar. Plan içeriği daha önce yazılmış plan dosyasından okunur.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `allowedPrompts` | array | Hayır | Uygulama planının gerektirdiği izin açıklamaları listesi |
+
+`allowedPrompts` dizisindeki her öğe:
+
+| Alan | Tür | Zorunlu | Açıklama |
+|------|-----|---------|----------|
+| `tool` | enum | Evet | Uygulanacak araç, şu anda yalnızca `Bash` desteklenir |
+| `prompt` | string | Evet | İşlemin anlamsal açıklaması (örn. "run tests", "install dependencies") |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Planlama modunda plan tamamlandı, kullanıcı onayına sunulmaya hazır
+- Yalnızca kod yazılması gereken uygulama görevleri için
+
+**Kullanıma uygun değil:**
+- Salt araştırma/keşif görevi — planlama modundan çıkmaya gerek yok
+- Kullanıcıya "Plan uygun mu?" diye sormak — bu tam olarak bu aracın işlevidir, AskUserQuestion kullanmayın
+
+## Dikkat Edilecekler
+
+- Bu araç plan içeriğini parametre olarak kabul etmez — daha önce yazılmış plan dosyasından okur
+- Kullanıcı onay için plan dosyasının içeriğini görecektir
+- Bu aracı çağırmadan önce AskUserQuestion ile "plan uygun mu?" diye sormayın, bu tekrardır
+- Sorularda "plan"dan bahsetmeyin, çünkü kullanıcı ExitPlanMode'dan önce plan içeriğini göremez
+
+## cc-viewer'da Önemi
+
+ExitPlanMode çağrısı planlama aşamasının sonunu işaret eder. İstek günlüğünde bu çağrıdan sonraki istekler genellikle uygulama işlemlerine (Edit, Write, Bash vb.) dönüşür.

package/concepts/tr/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## Tanım
+
+Herhangi bir boyuttaki kod tabanını destekleyen hızlı dosya adı kalıp eşleştirme aracı. Değişiklik zamanına göre sıralanmış eşleşen dosya yollarını döndürür.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `pattern` | string | Evet | glob kalıbı (örn. `**/*.js`, `src/**/*.ts`) |
+| `path` | string | Hayır | Arama dizini, varsayılan olarak mevcut çalışma dizini. "undefined" veya "null" geçmeyin |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Dosya adı kalıbına göre dosya bulma
+- Belirli türdeki tüm dosyaları bulma (örn. tüm `.tsx` dosyaları)
+- Belirli sınıf tanımını (örn. `class Foo`) ararken önce dosyayı konumlandırma
+- Tek mesajda paralel olarak birden fazla Glob çağrısı yapılabilir
+
+**Kullanıma uygun değil:**
+- Dosya içeriği arama — Grep kullanılmalıdır
+- Birden fazla tur gerektiren açık uçlu keşif — Task (Explore türü) kullanılmalıdır
+
+## Dikkat Edilecekler
+
+- Standart glob sözdizimini destekler: `*` tek seviye, `**` çok seviye, `{}` çoklu seçim eşleştirir
+- Sonuçlar değişiklik zamanına göre sıralanır
+- Bash'in `find` komutundan daha çok önerilir
+
+## cc-viewer'da Önemi
+
+Glob çağrıları istek günlüğünde `tool_use` / `tool_result` content block çifti olarak görünür. `tool_result` eşleşen dosya yollarının listesini içerir.

package/concepts/tr/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## Tanım
+
+ripgrep tabanlı güçlü içerik arama aracı. Düzenli ifadeler, dosya türü filtreleme ve çoklu çıktı modlarını destekler.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `pattern` | string | Evet | Düzenli ifade arama kalıbı |
+| `path` | string | Hayır | Arama yolu (dosya veya dizin), varsayılan mevcut çalışma dizini |
+| `glob` | string | Hayır | Dosya adı filtresi (örn. `*.js`, `*.{ts,tsx}`) |
+| `type` | string | Hayır | Dosya türü filtresi (örn. `js`, `py`, `rust`), glob'dan daha verimli |
+| `output_mode` | enum | Hayır | Çıktı modu: `files_with_matches` (varsayılan), `content`, `count` |
+| `-i` | boolean | Hayır | Büyük/küçük harf duyarsız arama |
+| `-n` | boolean | Hayır | Satır numaralarını göster (yalnızca content modu), varsayılan true |
+| `-A` | number | Hayır | Eşleşmeden sonra gösterilecek satır sayısı |
+| `-B` | number | Hayır | Eşleşmeden önce gösterilecek satır sayısı |
+| `-C` / `context` | number | Hayır | Eşleşme öncesi ve sonrası gösterilecek satır sayısı |
+| `head_limit` | number | Hayır | Çıktı girdi sayısını sınırla, varsayılan 0 (sınırsız) |
+| `offset` | number | Hayır | İlk N sonucu atla |
+| `multiline` | boolean | Hayır | Çok satırlı eşleştirme modunu etkinleştir, varsayılan false |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Kod tabanında belirli dize veya kalıp arama
+- Fonksiyon/değişken kullanım yerlerini bulma
+- Dosya türüne göre arama sonuçlarını filtreleme
+- Eşleşme sayısını sayma
+
+**Kullanıma uygun değil:**
+- Dosya adına göre dosya bulma — Glob kullanılmalıdır
+- Birden fazla tur gerektiren açık uçlu keşif — Task (Explore türü) kullanılmalıdır
+
+## Dikkat Edilecekler
+
+- ripgrep sözdizimi kullanır (grep değil), süslü parantez gibi özel karakterler kaçış gerektirir
+- `files_with_matches` modu yalnızca dosya yollarını döndürür, en verimli moddur
+- `content` modu eşleşen satır içeriklerini döndürür, bağlam satırlarını destekler
+- Çok satırlı eşleştirme için `multiline: true` ayarlanmalıdır
+- Bash'teki `grep` veya `rg` komutu yerine her zaman Grep aracını tercih edin
+
+## cc-viewer'da Önemi
+
+Grep çağrıları istek günlüğünde `tool_use` / `tool_result` content block çifti olarak görünür. `tool_result` arama sonuçlarını içerir.

package/concepts/tr/Tool-NotebookEdit.md

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## Tanım
+
+Jupyter notebook (.ipynb dosyası) içindeki belirli bir hücreyi değiştirme, ekleme veya silme işlemi yapar.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `notebook_path` | string | Evet | Notebook dosyasının mutlak yolu |
+| `new_source` | string | Evet | Hücrenin yeni içeriği |
+| `cell_id` | string | Hayır | Düzenlenecek hücre ID'si. Ekleme modunda yeni hücre bu ID'den sonra eklenir |
+| `cell_type` | enum | Hayır | Hücre türü: `code` veya `markdown`. Ekleme modunda zorunludur |
+| `edit_mode` | enum | Hayır | Düzenleme modu: `replace` (varsayılan), `insert`, `delete` |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Jupyter notebook'taki kod veya markdown hücrelerini değiştirme
+- Notebook'a yeni hücre ekleme
+- Notebook'tan hücre silme
+
+## Dikkat Edilecekler
+
+- `cell_number` 0 indekslidir
+- `insert` modu belirtilen konuma yeni hücre ekler
+- `delete` modu belirtilen konumdaki hücreyi siler
+- Yol mutlak yol olmalıdır
+
+## cc-viewer'da Önemi
+
+NotebookEdit çağrıları istek günlüğünde `tool_use` content block olarak görünür ve notebook üzerindeki belirli değişiklik işlemlerini kaydeder.

package/concepts/tr/Tool-Read.md

@@ -0,0 +1,41 @@
+# Read
+
+## Tanım
+
+Yerel dosya sisteminden dosya içeriğini okur. Metin dosyaları, resimler, PDF ve Jupyter notebook destekler.
+
+## Parametreler
+
+| Parametre | Tür | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `file_path` | string | Evet | Dosyanın mutlak yolu |
+| `offset` | number | Hayır | Başlangıç satır numarası (büyük dosyalar için parçalı okuma) |
+| `limit` | number | Hayır | Okunacak satır sayısı (büyük dosyalar için parçalı okuma) |
+| `pages` | string | Hayır | PDF sayfa aralığı (örn. "1-5", "3", "10-20"), yalnızca PDF için |
+
+## Kullanım Senaryoları
+
+**Kullanıma uygun:**
+- Kod dosyaları, yapılandırma dosyaları gibi metin dosyalarını okuma
+- Resim dosyalarını görüntüleme (Claude çok modlu bir modeldir)
+- PDF belgeleri okuma
+- Jupyter notebook okuma (tüm hücreleri ve çıktıları döndürür)
+- Bağlam elde etmek için birden fazla dosyayı paralel okuma
+
+**Kullanıma uygun değil:**
+- Dizin okuma — Bash'in `ls` komutu kullanılmalıdır
+- Açık uçlu kod tabanı keşfi — Task (Explore türü) kullanılmalıdır
+
+## Dikkat Edilecekler
+
+- Yol mutlak yol olmalıdır, göreli yol kullanılamaz
+- Varsayılan olarak dosyanın ilk 2000 satırını okur
+- 2000 karakteri aşan satırlar kesilir
+- Çıktı `cat -n` formatında, satır numaraları 1'den başlar
+- Büyük PDF'ler (10 sayfadan fazla) için `pages` parametresi belirtilmelidir, her seferinde en fazla 20 sayfa
+- Var olmayan bir dosyayı okumak hata döndürür (çökmez)
+- Tek mesajda birden fazla Read paralel olarak çağrılabilir
+
+## cc-viewer'da Önemi
+
+Read çağrıları istek günlüğünde `tool_use` (çağrı) ve `tool_result` (dönen içerik) content block çifti olarak görünür. `tool_result` dosyanın gerçek içeriğini içerir ve modelin hangi dosyaları okuduğunu analiz etmek için kullanılabilir.