cx-viewer 1.0.2 → 1.0.4

package/concepts/ja/Tool-TaskOutput.md

@@ -1,40 +0,0 @@
-# TaskOutput
-
-## 定義
-
-実行中または完了したバックグラウンドタスクの出力を取得します。バックグラウンドシェル、非同期 agent、リモートセッションに適用。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `task_id` | string | はい | タスク ID |
-| `block` | boolean | はい | タスク完了までブロック待機するかどうか、デフォルト `true` |
-| `timeout` | number | はい | 最大待機時間（ミリ秒）、デフォルト 30000、最大 600000 |
-
-## 使用シナリオ
-
-**適している場合：**
-- Task（`run_in_background: true`）で起動したバックグラウンド agent の進捗確認
-- バックグラウンド Bash コマンドの実行結果を取得
-- 非同期タスクの完了を待って出力を取得
-
-**適していない場合：**
-- フォアグラウンドタスク——フォアグラウンドタスクは直接結果を返すため、このツールは不要
-
-## 注意事項
-
-- `block: true` はタスク完了またはタイムアウトまでブロック
-- `block: false` はノンブロッキングで現在の状態を確認
-- タスク ID は `/tasks` コマンドで検索可能
-- すべてのタスクタイプに適用：バックグラウンドシェル、非同期 agent、リモートセッション
-
-## 原文
-
-<textarea readonly>- Retrieves output from a running or completed task (background shell, agent, or remote session)
-- Takes a task_id parameter identifying the task
-- Returns the task output along with status information
-- Use block=true (default) to wait for task completion
-- Use block=false for non-blocking check of current status
-- Task IDs can be found using the /tasks command
-- Works with all task types: background shells, async agents, and remote sessions</textarea>

package/concepts/ja/Tool-TaskStop.md

@@ -1,32 +0,0 @@
-# TaskStop
-
-## 定義
-
-実行中のバックグラウンドタスクを停止します。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `task_id` | string | いいえ | 停止するバックグラウンドタスクの ID |
-| `shell_id` | string | いいえ | 非推奨、`task_id` を代わりに使用 |
-
-## 使用シナリオ
-
-**適している場合：**
-- 不要になった長時間実行タスクの終了
-- 誤って起動したバックグラウンドタスクのキャンセル
-
-## 注意事項
-
-- 成功または失敗のステータスを返す
-- `shell_id` パラメータは非推奨、`task_id` を使用すべき
-
-## 原文
-
-<textarea readonly>
-- Stops a running background task by its ID
-- Takes a task_id parameter identifying the task to stop
-- Returns a success or failure status
-- Use this tool when you need to terminate a long-running task
-</textarea>

package/concepts/ja/Tool-TaskUpdate.md

@@ -1,123 +0,0 @@
-# TaskUpdate
-
-## 定義
-
-タスクリスト内の特定タスクのステータス、内容、または依存関係を更新します。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `taskId` | string | はい | 更新するタスクの ID |
-| `status` | enum | いいえ | 新しいステータス：`pending` / `in_progress` / `completed` / `deleted` |
-| `subject` | string | いいえ | 新しいタイトル |
-| `description` | string | いいえ | 新しい説明 |
-| `activeForm` | string | いいえ | 進行中に表示する現在進行形テキスト |
-| `owner` | string | いいえ | 新しいタスク担当者（agent 名） |
-| `metadata` | object | いいえ | マージするメタデータ（null に設定するとキーを削除） |
-| `addBlocks` | string[] | いいえ | このタスクによってブロックされるタスク ID のリスト |
-| `addBlockedBy` | string[] | いいえ | このタスクをブロックする前提タスク ID のリスト |
-
-## ステータス遷移
-
-```
-pending → in_progress → completed
-```
-
-`deleted` は任意のステータスから遷移可能で、タスクを永久に削除します。
-
-## 使用シナリオ
-
-**適している場合：**
-- 作業開始時にタスクを `in_progress` にマーク
-- 作業完了後にタスクを `completed` にマーク
-- タスク間の依存関係を設定
-- 要件変更時にタスク内容を更新
-
-**重要なルール：**
-- タスクを完全に完了した場合のみ `completed` にマーク
-- エラーやブロックに遭遇した場合は `in_progress` を維持
-- テスト失敗、実装不完全、未解決エラーがある場合は `completed` にマークしてはならない
-
-## 注意事項
-
-- 更新前に TaskGet でタスクの最新ステータスを取得し、古いデータを避ける
-- タスク完了後に TaskList を呼び出して次の利用可能なタスクを検索
-
-## 原文
-
-<textarea readonly>Use this tool to update a task in the task list.
-
-## When to Use This Tool
-
-**Mark tasks as resolved:**
-- When you have completed the work described in a task
-- When a task is no longer needed or has been superseded
-- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
-- After resolving, call TaskList to find your next task
-
-- ONLY mark a task as completed when you have FULLY accomplished it
-- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
-- When blocked, create a new task describing what needs to be resolved
-- Never mark a task as completed if:
-  - Tests are failing
-  - Implementation is partial
-  - You encountered unresolved errors
-  - You couldn't find necessary files or dependencies
-
-**Delete tasks:**
-- When a task is no longer relevant or was created in error
-- Setting status to `deleted` permanently removes the task
-
-**Update task details:**
-- When requirements change or become clearer
-- When establishing dependencies between tasks
-
-## Fields You Can Update
-
-- **status**: The task status (see Status Workflow below)
-- **subject**: Change the task title (imperative form, e.g., "Run tests")
-- **description**: Change the task description
-- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
-- **owner**: Change the task owner (agent name)
-- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
-- **addBlocks**: Mark tasks that cannot start until this one completes
-- **addBlockedBy**: Mark tasks that must complete before this one can start
-
-## Status Workflow
-
-Status progresses: `pending` → `in_progress` → `completed`
-
-Use `deleted` to permanently remove a task.
-
-## Staleness
-
-Make sure to read a task's latest state using `TaskGet` before updating it.
-
-## Examples
-
-Mark task as in progress when starting work:
-```json
-{"taskId": "1", "status": "in_progress"}
-```
-
-Mark task as completed after finishing work:
-```json
-{"taskId": "1", "status": "completed"}
-```
-
-Delete a task:
-```json
-{"taskId": "1", "status": "deleted"}
-```
-
-Claim a task by setting owner:
-```json
-{"taskId": "1", "owner": "my-name"}
-```
-
-Set up task dependencies:
-```json
-{"taskId": "2", "addBlockedBy": ["1"]}
-```
-</textarea>

package/concepts/ja/Tool-TeamCreate.md

@@ -1,38 +0,0 @@
-# TeamCreate
-
-## 定義
-
-プロジェクトに取り組む複数の agent を調整するための新しいチームを作成します。チームは共有タスクリストと agent 間のメッセージングを通じて並列タスク実行を可能にします。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `team_name` | string | はい | 新しいチームの名前 |
-| `description` | string | いいえ | チームの説明 / 目的 |
-| `agent_type` | string | いいえ | チームリーダーのタイプ / ロール |
-
-## 作成されるもの
-
-- **チーム設定ファイル**: `~/.claude/teams/{team-name}/config.json` — メンバーリストとメタデータを保存
-- **タスクリストディレクトリ**: `~/.claude/tasks/{team-name}/` — すべてのチームメンバーが共有するタスクリスト
-
-チームとタスクリストは 1:1 の対応関係にあります。
-
-## チームワークフロー
-
-1. **TeamCreate** — チームとそのタスクリストを作成
-2. **TaskCreate** — チームのタスクを定義
-3. **Agent**（`team_name` + `name` を指定）— チームに参加するチームメンバーを起動
-4. **TaskUpdate** — `owner` を通じてチ��ムメンバーにタスクを割り当て
-5. チームメンバーがタスクに���り組み、**SendMessage** を通じて通信
-6. 完了後チームメンバーをシャットダウン、その後 **TeamDelete** でクリーンアップ
-
-## 関連ツール
-
-| ツール | 目的 |
-|--------|------|
-| `TeamDelete` | チームとタスクディレクトリを削除 |
-| `SendMessage` | チーム内の agent 間通信 |
-| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 共有タスクリストの管理 |
-| `Agent` | チームに参加するチームメンバーを起動 |

package/concepts/ja/Tool-TeamDelete.md

@@ -1,30 +0,0 @@
-# TeamDelete
-
-## 定義
-
-マルチ agent コラボレーション作業が完了した際に、チームと関連するタスクディレクトリを削除します。TeamCreate のクリーンアップ対応操作です。
-
-## 動作
-
-- チームディレクトリを削除: `~/.claude/teams/{team-name}/`
-- タスクディレクトリを削除: `~/.claude/tasks/{team-name}/`
-- 現在のセッションからチームコンテキストをクリア
-
-**重要**: チームにまだアクティブなメンバーがいる場合、TeamDelete は失敗します。SendMessage のシャットダウンリクエストを通じて、先にすべてのチームメンバーを適切にシャットダウンする必要があります。
-
-## 典型的な使用方法
-
-TeamDelete はチームワークフローの終了時に呼び出されます:
-
-1. すべてのタスクが完了
-2. `SendMessage` で `shutdown_request` を送信してチームメンバーをシャットダウン
-3. **TeamDelete** がチームとタスクディレクトリを削除
-
-## 関連ツール
-
-| ツール | 目的 |
-|--------|------|
-| `TeamCreate` | 新しいチームとそのタスクリストを作成 |
-| `SendMessage` | チームメンバーとの通信 / シャットダウンリクエストの送信 |
-| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 共有タスクリストの管理 |
-| `Agent` | チームに参加するチームメンバーを起動 |

package/concepts/ja/Tool-WebFetch.md

@@ -1,55 +0,0 @@
-# WebFetch
-
-## 定義
-
-指定 URL のウェブページ内容を取得し、HTML を markdown に変換し、AI モデルで prompt に基づいて内容を処理します。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `url` | string (URI) | はい | 取得する完全な URL |
-| `prompt` | string | はい | ページからどの情報を抽出するかの説明 |
-
-## 使用シナリオ
-
-**適している場合：**
-- 公開ウェブページの内容を取得
-- オンラインドキュメントの参照
-- ウェブページから特定の情報を抽出
-
-**適していない場合：**
-- 認証が必要な URL（Google Docs、Confluence、Jira、GitHub など）——まず専用の MCP ツールを探すべき
-- GitHub URL——`gh` CLI を優先使用
-
-## 注意事項
-
-- URL は完全な有効 URL でなければならない
-- HTTP は自動的に HTTPS にアップグレード
-- 内容が大きすぎる場合、結果が要約される可能性がある
-- 15分の自動クリーニングキャッシュを含む
-- URL が異なるホストにリダイレクトされた場合、ツールはリダイレクト URL を返し、新しい URL で再リクエストが必要
-- MCP 提供の web fetch ツールが利用可能な場合、そちらを優先使用
-
-## 原文
-
-<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
-
-- Fetches content from a specified URL and processes it using an AI model
-- Takes a URL and a prompt as input
-- Fetches the URL content, converts HTML to markdown
-- Processes the content with the prompt using a small, fast model
-- Returns the model's response about the content
-- Use this tool when you need to retrieve and analyze web content
-
-Usage notes:
-  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
-  - The URL must be a fully-formed valid URL
-  - HTTP URLs will be automatically upgraded to HTTPS
-  - The prompt should describe what information you want to extract from the page
-  - This tool is read-only and does not modify any files
-  - Results may be summarized if the content is very large
-  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
-  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
-  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
-</textarea>

package/concepts/ja/Tool-WebSearch.md

@@ -1,58 +0,0 @@
-# WebSearch
-
-## 定義
-
-検索エンジンクエリを実行し、最新情報を取得するための検索結果を返します。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `query` | string | はい | 検索クエリ（最低2文字） |
-| `allowed_domains` | string[] | いいえ | これらのドメインの結果のみを含む |
-| `blocked_domains` | string[] | いいえ | これらのドメインの結果を除外 |
-
-## 使用シナリオ
-
-**適している場合：**
-- モデルの知識カットオフ日を超えた最新情報の取得
-- 現在のイベントや最新データの検索
-- 最新の技術ドキュメントの検索
-
-## 注意事項
-
-- 検索結果は markdown ハイパーリンク形式で返される
-- 使用後はレスポンスの末尾に "Sources:" セクションを付け、関連 URL を列挙する必要がある
-- ドメインフィルタリング（包含/除外）に対応
-- 検索クエリには現在の年を使用すべき
-- 米国でのみ利用可能
-
-## 原文
-
-<textarea readonly>
-- Allows Claude to search the web and use the results to inform responses
-- Provides up-to-date information for current events and recent data
-- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
-- Use this tool for accessing information beyond Claude's knowledge cutoff
-- Searches are performed automatically within a single API call
-
-CRITICAL REQUIREMENT - You MUST follow this:
-  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
-  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
-  - This is MANDATORY - never skip including sources in your response
-  - Example format:
-
-    [Your answer here]
-
-    Sources:
-    - [Source Title 1](https://example.com/1)
-    - [Source Title 2](https://example.com/2)
-
-Usage notes:
-  - Domain filtering is supported to include or block specific websites
-  - Web search is only available in the US
-
-IMPORTANT - Use the correct year in search queries:
-  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
-  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
-</textarea>

package/concepts/ja/Tool-Write.md

@@ -1,39 +0,0 @@
-# Write
-
-## 定義
-
-ローカルファイルシステムにコンテンツを書き込みます。ファイルが既に存在する場合は上書きします。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `file_path` | string | はい | ファイルの絶対パス（絶対パスでなければならない） |
-| `content` | string | はい | 書き込む内容 |
-
-## 使用シナリオ
-
-**適している場合：**
-- 新規ファイルの作成
-- ファイル内容を完全に書き換える必要がある場合
-
-**適していない場合：**
-- ファイル内の部分的な内容の変更——Edit を使用すべき
-- ドキュメントファイル（*.md）や README を自発的に作成すべきではない。ユーザーが明示的に要求した場合を除く
-
-## 注意事項
-
-- 対象ファイルが既に存在する場合、先に Read で読み取る必要がある。そうでないと失敗する
-- 既存ファイルの全内容を上書きする
-- 既存ファイルの編集には Edit を優先使用し、Write は新規ファイル作成または完全な書き換えにのみ使用
-
-## 原文
-
-<textarea readonly>Writes a file to the local filesystem.
-
-Usage:
-- This tool will overwrite the existing file if there is one at the provided path.
-- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
-- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
-- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
-- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

package/concepts/ja/Tool-executeCode.md

@@ -1,41 +0,0 @@
-# executeCode (mcp__ide__executeCode)
-
-## 定義
-
-現在の notebook ファイルの Jupyter kernel で Python コードを実行します。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `code` | string | はい | 実行する Python コード |
-
-## 使用シナリオ
-
-**適している場合：**
-- Jupyter notebook 環境でコードを実行
-- コードスニペットのテスト
-- データ分析と計算
-
-**適していない場合：**
-- 非 Jupyter 環境でのコード実行——Bash を使用すべき
-- ファイルの変更——Edit または Write を使用すべき
-
-## 注意事項
-
-- これは MCP（Model Context Protocol）ツールで、IDE 統合により提供
-- コードは現在の Jupyter kernel で実行され、状態は呼び出し間で永続化
-- ユーザーが明示的に要求しない限り、変数の宣言や kernel 状態の変更を避けるべき
-- kernel 再起動後は状態が失われる
-
-## 原文
-
-<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
-    
-    All code will be executed in the current Jupyter kernel.
-    
-    Avoid declaring variables or modifying the state of the kernel unless the user
-    explicitly asks for it.
-    
-    Any code executed will persist across calls to this tool, unless the kernel
-    has been restarted.</textarea>

package/concepts/ja/Tool-getDiagnostics.md

@@ -1,32 +0,0 @@
-# getDiagnostics (mcp__ide__getDiagnostics)
-
-## 定義
-
-VS Code から言語診断情報を取得します。構文エラー、型エラー、lint 警告などを含みます。
-
-## パラメータ
-
-| パラメータ | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `uri` | string | いいえ | ファイル URI。指定しない場合はすべてのファイルの診断情報を取得 |
-
-## 使用シナリオ
-
-**適している場合：**
-- コードの構文、型、lint などのセマンティック問題をチェック
-- コード編集後に新しいエラーが導入されていないか検証
-- Bash コマンドの代わりにコード品質をチェック
-
-**適していない場合：**
-- テストの実行——Bash を使用すべき
-- ランタイムエラーのチェック——Bash でコードを実行すべき
-
-## 注意事項
-
-- これは MCP（Model Context Protocol）ツールで、IDE 統合により提供
-- VS Code / IDE 環境でのみ利用可能
-- コード問題のチェックには Bash コマンドよりもこのツールを優先使用
-
-## 原文
-
-<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/ja/Tools.md

@@ -1,67 +0,0 @@
-# Claude Code ツール一覧
-
-Claude Code は Anthropic API の tool_use メカニズムを通じてモデルに一連の組み込みツールを提供します。各 MainAgent リクエストの `tools` 配列にこれらのツールの完全な JSON Schema 定義が含まれ、モデルはレスポンス内の `tool_use` content block でそれらを呼び出します。
-
-以下はすべてのツールのカテゴリ別インデックスです。
-
-## Agent システム
-
-| ツール | 用途 |
-|--------|------|
-| [Task](Tool-Task.md) | サブ 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) | シェルコマンドの実行 |
-
-## 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 kernel でコードを実行 |

package/concepts/ko/CacheRebuild.md

@@ -1,36 +0,0 @@
-# Cache Rebuild（캐시 재구축）
-
-## 배경
-
-Anthropic의 prompt caching 메커니즘은 요청 내의 system → tools → messages（캐시 브레이크포인트까지）를 순서대로 연결하여 캐시 키를 생성합니다. 캐시 키가 이전 요청과 완전히 일치하면 API는 `cache_read_input_tokens`（캐시 히트）를 반환합니다. 캐시 키가 변경되면 API는 캐시를 다시 생성하고 대량의 `cache_creation_input_tokens`를 반환하는데, 이것이 캐시 재구축입니다.
-
-캐시 재구축은 추가 토큰 과금을 의미합니다（cache creation 가격이 cache read보다 높음）. 따라서 재구축 원인을 식별하는 것은 비용 최적화에 직접적인 가치가 있습니다.
-
-## 캐시 재구축 원인 분류
-
-cc-viewer는 전후 두 MainAgent 요청의 body를 비교하여 캐시 재구축의 원인을 정확히 판정합니다:
-
-| reason | 의미 | 판정 방법 |
-|--------|------|-----------|
-| `ttl` | 캐시 만료 | 이전 MainAgent 요청으로부터 5분 이상 경과 |
-| `system_change` | system prompt 변경 | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
-| `tools_change` | 도구 정의 변경 | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
-| `model_change` | 모델 전환 | `prev.model !== curr.model` |
-| `msg_truncated` | 메시지 스택 잘림 | 현재 요청의 messages 수가 이전보다 적음. 보통 컨텍스트 윈도우 오버플로우로 인한 잘림으로 발생 |
-| `msg_modified` | 이력 메시지 수정 | 접두사 메시지 내용 불일치 (정상적인 추가 시 접두사는 완전히 동일해야 함) |
-| `key_change` | 알 수 없는 키 변경 | 위 조건 모두 해당하지 않을 때의 폴백 |
-
-## 판정 우선순위
-
-1. 먼저 시간 간격 확인 — 5분 초과 시 바로 `ttl`로 판정하고 body 비교는 수행하지 않음
-2. 이후 model, system, tools, messages를 순서대로 확인
-3. 하나의 요청이 여러 원인에 동시에 해당할 수 있음 (예: 모델 전환 + system prompt 변경). 이 경우 `reasons` 배열에 모든 해당 항목이 포함되며, tooltip에서 줄바꿈으로 표시
-
-## 일반적인 시나리오
-
-- **`ttl`**: 사용자가 5분 이상 작업을 중단한 후 재개하여 캐시가 자연 만료
-- **`system_change`**: Claude Code가 system prompt를 업데이트 (새 CLAUDE.md 로드, project instructions 변경 등)
-- **`tools_change`**: MCP server 연결/해제로 사용 가능한 도구 목록 변경
-- **`model_change`**: 사용자가 `/model` 명령으로 모델 전환
-- **`msg_truncated`**: 대화가 길어져 컨텍스트 윈도우 관리가 작동, Claude Code가 초기 메시지를 잘라냄
-- **`msg_modified`**: Claude Code가 이력 메시지를 편집 (예: `/compact`로 압축 요약이 원본 메시지를 대체)

package/concepts/ko/KVCacheContent.md

@@ -1,49 +0,0 @@
-# KV-Cache 캐시 내용
-
-## Prompt Caching이란?
-
-Claude와 대화할 때, 매 API 요청마다 완전한 대화 컨텍스트(system prompt + 도구 정의 + 과거 메시지)가 전송됩니다. Anthropic의 prompt caching 메커니즘은 이미 계산된 접두사 내용을 서버 측에 캐시하고, 후속 요청에서 접두사가 일치하면 캐시 결과를 직접 재사용하여 중복 계산을 건너뛰고, 지연 시간과 비용을 대폭 줄입니다.
-
-cc-viewer에서는 이 메커니즘을 "KV-Cache"라고 부르지만, 이는 Anthropic API 수준의 prompt caching에 해당하는 것이며, LLM 내부 transformer 어텐션 레이어의 key-value cache가 아닙니다.
-
-## 캐시의 작동 원리
-
-Anthropic의 prompt caching은 고정된 순서로 캐시 키를 연결합니다:
-
-```
-Tools → System Prompt → Messages(캐시 브레이크포인트까지)
-```
-
-이 접두사가 TTL 윈도우 내의 어떤 요청과 완전히 일치하면, API는 캐시에 히트(`cache_read_input_tokens` 반환)하며 재계산(`cache_creation_input_tokens`)을 수행하지 않습니다.
-
-> **Claude Code는 `cache_control` 속성에 강하게 의존하지 않으며, 서버 측에서 이러한 속성의 일부를 제거하면서도 캐시를 잘 생성할 수 있으므로, `cache_control` 속성이 보이지 않는다고 해서 캐시되지 않은 것은 아닙니다**
->
-> Claude Code와 같은 특수 클라이언트에 대해, Anthropic 서버 측은 요청 내 `cache_control` 속성에만 완전히 의존하여 캐시 동작을 결정하지 않습니다. 서버 측은 특정 필드(system prompt, tools 정의 등)에 대해 자동으로 캐시 정책을 실행하며, 요청에 `cache_control` 표시가 명시적으로 포함되어 있지 않아도 마찬가지입니다. 따라서 요청 본문에서 이 속성이 보이지 않아도 의아해할 필요가 없습니다 -- 서버 측에서 이미 백그라운드에서 캐시 작업을 완료했지만, 이 정보를 클라이언트에 노출하지 않았을 뿐입니다. 이는 Claude Code와 Anthropic API 사이의 암묵적 합의입니다.
-
-## "현재 KV-Cache 캐시 내용"이란?
-
-cc-viewer에 표시되는 "현재 KV-Cache 캐시 내용"은 최근 MainAgent 요청에서 추출된, 캐시 경계(cache breakpoint) 이전의 내용입니다. 구체적으로 다음을 포함합니다:
-
-- **System Prompt**: Claude Code의 시스템 지시사항으로, 핵심 agent 지시, 도구 사용 규범, CLAUDE.md 프로젝트 지시, 환경 정보 등을 포함
-- **Tools**: 현재 사용 가능한 도구 정의 목록(Read, Write, Bash, Agent, MCP 도구 등)
-- **Messages**: 대화 이력에서 캐시된 부분(일반적으로 초기 메시지로, 마지막 `cache_control` 표시까지)
-
-## 캐시 내용을 확인하는 이유
-
-1. **컨텍스트 이해**: Claude가 현재 "기억하고 있는" 내용을 파악하여, 그 동작이 예상대로인지 판단하는 데 도움
-2. **비용 최적화**: 캐시 히트 시 비용은 재계산보다 훨씬 낮음. 캐시 내용을 확인하면 특정 요청이 캐시 재구축(cache rebuild)을 트리거한 이유를 이해할 수 있음
-3. **대화 디버깅**: Claude의 답변이 예상과 다를 때, 캐시 내용을 확인하여 system prompt와 과거 메시지가 올바른지 확인 가능
-4. **컨텍스트 품질 모니터링**: 디버깅, 설정 변경, prompt 조정 과정에서 KV-Cache-Text는 집중된 시각을 제공하여, 핵심 컨텍스트가 저하되지 않았는지, 예상치 못한 내용으로 오염되지 않았는지 빠르게 확인할 수 있음 -- 원본 메시지를 하나씩 검토할 필요 없음
-
-## 다중 레벨 캐시 전략
-
-Claude Code에 대응하는 KV-Cache는 하나만 있는 것이 아닙니다. 서버 측에서는 Tools와 System Prompt에 대해 각각 별도의 캐시를 생성하며, Messages 부분의 캐시와는 독립적입니다. 이렇게 설계하면 messages 스택에 혼란이 발생했을 때(컨텍스트 잘림, 메시지 수정 등) 재구축이 필요하더라도, Tools와 System Prompt의 캐시가 함께 무효화되지 않아 전체 재계산을 방지할 수 있습니다.
-
-이것은 현 단계 서버 측의 최적화 전략입니다 -- Tools 정의와 System Prompt는 정상적인 사용 과정에서 비교적 안정적이고 변경이 적으므로, 별도로 캐시하면 불필요한 재구축 비용을 최대한 줄일 수 있습니다. 따라서 Cache를 관찰하면, Tools 재구축은 모든 캐시를 완전히 새로고침해야 하지만, System Prompt와 Messages의 파손은 여전히 계승할 수 있는 캐시가 남아 있다는 것을 발견할 수 있습니다.
-
-## 캐시의 생명주기
-
-- **생성**: 초기 요청 또는 캐시 무효화 후 API는 새 캐시를 생성(`cache_creation_input_tokens`)
-- **히트**: 후속 요청의 접두사가 일치하면 캐시 재사용(`cache_read_input_tokens`)
-- **만료**: 캐시는 5분의 TTL(존속 시간)을 가지며, 타임아웃 후 자동 무효화
-- **재구축**: system prompt, 도구 목록, 모델 또는 메시지 내용이 변경되면 캐시 키가 일치하지 않아 해당 레벨의 캐시 재구축이 트리거됨