cc-viewer 1.2.1 → 1.2.2

package/concepts/zh/Tool-WebSearch.md

@@ -0,0 +1,32 @@
+# WebSearch
+
+## 定义
+
+执行搜索引擎查询，返回搜索结果用于获取最新信息。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `query` | string | 是 | 搜索查询（最少 2 个字符） |
+| `allowed_domains` | string[] | 否 | 仅包含这些域名的结果 |
+| `blocked_domains` | string[] | 否 | 排除这些域名的结果 |
+
+## 使用场景
+
+**适合使用：**
+- 获取超出模型知识截止日期的最新信息
+- 查找当前事件和最新数据
+- 搜索最新的技术文档
+
+## 注意事项
+
+- 搜索结果以 markdown 超链接格式返回
+- 使用后必须在响应末尾附上 "Sources:" 部分，列出相关 URL
+- 支持域名过滤（包含/排除）
+- 搜索查询中应使用当前年份
+- 仅在美国可用
+
+## 在 cc-viewer 中的意义
+
+WebSearch 调用在请求日志中表现为 `tool_use` / `tool_result` content block 对。`tool_result` 包含搜索结果列表。

package/concepts/zh/Tool-Write.md

@@ -0,0 +1,32 @@
+# Write
+
+## 定义
+
+将内容写入本地文件系统。如果文件已存在则覆盖。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_path` | string | 是 | 文件的绝对路径（必须是绝对路径） |
+| `content` | string | 是 | 要写入的内容 |
+
+## 使用场景
+
+**适合使用：**
+- 创建新文件
+- 需要完全重写文件内容时
+
+**不适合使用：**
+- 修改文件中的局部内容——应使用 Edit
+- 不应主动创建文档文件（*.md）或 README，除非用户明确要求
+
+## 注意事项
+
+- 如果目标文件已存在，必须先通过 Read 读取，否则会失败
+- 会覆盖已有文件的全部内容
+- 优先使用 Edit 编辑现有文件，Write 仅用于创建新文件或完全重写
+
+## 在 cc-viewer 中的意义
+
+Write 调用在请求日志中表现为 `tool_use` content block，其 `input.content` 包含写入的完整内容。

package/concepts/zh/Tool-executeCode.md

@@ -0,0 +1,33 @@
+# 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 重启后状态会丢失
+
+## 在 cc-viewer 中的意义
+
+executeCode 是 MCP 工具，在请求日志的 `tools` 数组中以 `mcp__ide__executeCode` 名称出现。其调用和返回遵循标准的 `tool_use` / `tool_result` 模式。MCP 工具的增减会导致 tools 数组变化，可能触发缓存重建。

package/concepts/zh/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/zh/Tools.md

@@ -0,0 +1,73 @@
+# 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) | 执行 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 kernel 中执行代码 |
+
+## 在 cc-viewer 中的意义
+
+工具调用是 Claude Code 请求日志中最核心的可观测数据之一。每个 MainAgent 请求的 `tools` 数组定义了模型可用的工具集，而响应中的 `tool_use` / `tool_result` content block 记录了实际的工具调用与返回。cc-viewer 通过解析这些数据，在 Chat Mode 中还原完整的工具调用链路。
+
+工具定义的变化（如 MCP server 连接/断开导致工具增减）会触发缓存重建，详见 [CacheRebuild](CacheRebuild.md)。

package/concepts/zh/TranslateContextPollution.md

@@ -0,0 +1,47 @@
+# 翻译接口 Context 污染问题
+
+## 背景
+
+CC-Viewer 内置了翻译功能（`POST /api/translate`），通过调用 Anthropic Messages API 实现文本翻译。在早期实现中，翻译请求会复用 Claude Code 会话中缓存的认证凭据——包括 `x-api-key` 和 `authorization` header。这导致了一个隐蔽但严重的问题：翻译结果频繁"答非所问"。
+
+## 问题根因
+
+### 两种认证方式的本质区别
+
+Anthropic API 支持两种认证方式：
+
+| 方式 | Header | 典型来源 | 特点 |
+|------|--------|----------|------|
+| API Key | `x-api-key: sk-ant-...` | 环境变量 / Console 生成 | 无状态，每次请求独立 |
+| OAuth Token | `authorization: Bearer sessionToken` | Claude Code 订阅登录 | 绑定会话，服务端维护上下文关联 |
+
+关键差异在于：**API Key 是无状态的**，每个请求完全独立；而 **OAuth session token 是有状态的**，Anthropic 服务端会将同一 token 的请求关联到同一会话上下文中。
+
+### 污染链路
+
+当 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. **主对话受翻译请求干扰**：翻译请求的内容（用户界面文本片段）可能被注入到主对话的上下文中，导致 Claude Code 的回复出现偏差
+3. **不可预测的行为**：由于上下文污染是服务端行为，客户端无法感知也无法控制
+
+
+## 经验总结
+
+- **OAuth session token 不是"另一种 API Key"**——它携带服务端状态，复用它等于共享上下文
+- **内部服务间调用应使用独立的、无状态的认证方式**，避免与用户会话产生关联
+
+## 参考资料
+
+- [Anthropic API 认证文档](https://docs.anthropic.com/en/api/getting-started) — `x-api-key` 与 `authorization` header 的官方说明
+- [Claude Code 认证方式](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code) — API Key 环境变量管理
+- [Anthropic 禁止第三方应用使用订阅 OAuth](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/) — Anthropic 对 OAuth token 使用范围的限制
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/) — 认证方式对比

package/concepts/zh-TW/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（請求體增量對比）
+
+## 背景
+
+Claude Code 的 MainAgent 採用全量上下文發送機制——每次請求都會攜帶完整的對話歷史、system prompt、工具定義等內容。這意味著隨著對話推進，請求體會越來越龐大，直接查看原始 Body 很難快速定位「這一輪到底新增了什麼」。
+
+Body Diff JSON 正是為了解決這個問題：它自動對比前後兩個 MainAgent 請求的 body，提煉出增量部分，讓你一眼看清本次請求實際新增的內容。
+
+## 工作原理
+
+1. **識別連續的 MainAgent 請求**：當前請求必須是 MainAgent 類型，且存在上一個 MainAgent 請求
+2. **逐欄位對比**：遍歷請求體的所有頂層欄位，跳過 `_` 前綴的內部屬性
+3. **智慧差異提取**：
+   - 新增的欄位：直接展示
+   - 刪除的欄位：不顯示（通常不影響理解）
+   - 變更的欄位：展示當前值
+   - `messages` 陣列特殊處理：只展示新增的訊息（因為正常對話是追加模式，前綴訊息不變）
+4. **請求體縮小偵測**：如果當前請求體比上一個更小，說明發生了上下文截斷或會話重置，此時會顯示提示訊息而非 diff
+
+## 典型場景
+
+在一輪正常對話中，Body Diff JSON 通常只包含：
+- `messages`：新增的 1~2 條訊息（使用者的輸入 + 上一輪助手的回覆）
+
+如果你看到 diff 中出現了 `system`、`tools`、`model` 等欄位的變更，說明本輪請求發生了配置變化，這往往也是快取重建的原因。
+
+## 使用方式
+
+- Body Diff JSON 顯示在 MainAgent 請求的詳情面板中
+- 點擊標題可展開/收起
+- 支援 JSON 和 Text 兩種查看模式，以及一鍵複製
+- 在左上角 **CC-Viewer → 全域設定** 中，可以設定「預設展開 Body Diff JSON」

package/concepts/zh-TW/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild（快取重建）
+
+## 背景
+
+Anthropic 的 prompt caching 機制會將請求中的 system → tools → messages（到 cache breakpoint）按順序拼接為快取鍵。當快取鍵與上一次請求完全一致時，API 回傳 `cache_read_input_tokens`（快取命中）；當快取鍵發生變化，API 會重新建立快取，回傳大量 `cache_creation_input_tokens`，即快取重建。
+
+快取重建意味著額外的 token 計費（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` | 未知鍵變更 | 以上條件均不匹配時的 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 中的展示
+
+請求列表中，快取重建的請求會在 cache 行顯示紅色圓點指示器。滑鼠懸停顯示 tooltip，包含具體的重建原因描述（支援 18 種語言）。

package/concepts/zh-TW/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 | 完整的 Claude Code 主 prompt | 精簡的任務專用 prompt |
+| tools 陣列 | 包含全部可用工具 | 通常只包含任務所需的少量工具 |
+| 訊息歷史 | 累積完整對話上下文 | 僅包含子任務相關訊息 |
+| 快取行為 | 有 prompt caching（5 分鐘 TTL） | 通常無快取或快取較小 |
+
+## 在 cc-viewer 中的意義
+
+- **快取追蹤**：MainAgent 請求的 prompt caching 狀態直接影響費用。透過監控 `cache_creation_input_tokens` 與 `cache_read_input_tokens` 的比例，可以判斷快取命中率
+- **快取遺失分析**：當 MainAgent 請求出現大量 cache creation（而非 cache read），說明快取遺失並被重建，cc-viewer 會透過紅色圓點指示器標記這些請求
+- **主鏈路分析**：MainAgent 請求序列反映了使用者與 Claude Code 的完整互動過程，是分析會話行為的核心資料
+- **會話重建**：cc-viewer 透過 MainAgent 請求的訊息歷史重建對話檢視（Chat Mode）

package/concepts/zh-TW/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" 提供自訂輸入
+- 推薦選項放在第一位，並在 label 末尾加 "(Recommended)"
+- `markdown` 預覽僅支援單選問題
+- 有 `markdown` 的選項會切換為左右並排佈局
+- 在規劃模式中，用於在確定方案前澄清需求
+
+## 在 cc-viewer 中的意義
+
+AskUserQuestion 呼叫在請求日誌中表現為 `tool_use` content block，包含問題和選項定義。使用者的回答會出現在後續請求的訊息歷史中。

package/concepts/zh-TW/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## 定義
+
+執行 shell 命令，支援可選的逾時設定。工作目錄在命令間持久化，但 shell 狀態（環境變數等）不持久化。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `command` | string | 是 | 要執行的 bash 命令 |
+| `description` | string | 否 | 命令的簡短描述 |
+| `timeout` | number | 否 | 逾時時間（毫秒），最大 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 呼叫在請求日誌中表現為 `tool_use`（包含命令）和 `tool_result`（包含輸出）content block 對。命令執行的輸出可用於分析模型的操作行為。

package/concepts/zh-TW/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` |
+
+## 使用場景
+
+**適合使用：**
+- 修改現有檔案中的特定程式碼段
+- 修復 bug、更新邏輯
+- 重新命名變數（配合 `replace_all: true`）
+- 任何需要精確修改檔案內容的場景
+
+**不適合使用：**
+- 建立新檔案——應使用 Write
+- 大規模重寫——可能需要 Write 覆寫整個檔案
+
+## 注意事項
+
+- 使用前必須先透過 Read 讀取過該檔案，否則會報錯
+- `old_string` 在檔案中必須是唯一的，否則編輯失敗。如果不唯一，需要提供更多上下文使其唯一，或使用 `replace_all`
+- 編輯文字時必須保持原始縮排（tab/空格），不要包含 Read 輸出中的行號前綴
+- 優先編輯現有檔案，而非建立新檔案
+- `new_string` 必須與 `old_string` 不同
+
+## 在 cc-viewer 中的意義
+
+Edit 呼叫在請求日誌中表現為 `tool_use` content block，其 `input` 包含 `old_string` 和 `new_string`，可用於追蹤模型對檔案做了哪些修改。

package/concepts/zh-TW/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## 定義
+
+將 Claude Code 切換到規劃模式，用於在實施前探索程式碼庫並設計方案。
+
+## 參數
+
+無參數。
+
+## 使用場景
+
+**適合使用：**
+- 新功能實作——需要架構決策
+- 存在多種可行方案——需要使用者選擇
+- 程式碼修改影響現有行為或結構
+- 多檔案變更——可能涉及 2-3 個以上檔案
+- 需求不明確——需要先探索再理解範圍
+- 使用者偏好很重要——實作可以有多種合理方向
+
+**不適合使用：**
+- 單行或少量行的修復（拼寫錯誤、明顯 bug）
+- 使用者已給出非常具體的指令
+- 純研究/探索任務——應使用 Task（Explore 類型）
+
+## 規劃模式中的行為
+
+進入規劃模式後，Claude Code 會：
+1. 使用 Glob、Grep、Read 工具深入探索程式碼庫
+2. 理解現有模式和架構
+3. 設計實施方案
+4. 將方案提交給使用者審批
+5. 如需澄清可使用 AskUserQuestion
+6. 方案就緒後透過 ExitPlanMode 退出
+
+## 注意事項
+
+- 此工具需要使用者同意才能進入規劃模式
+- 如果不確定是否需要規劃，傾向於規劃——提前對齊比返工好
+
+## 在 cc-viewer 中的意義
+
+EnterPlanMode 呼叫在請求日誌中表現為 `tool_use` content block。進入規劃模式後的請求序列通常以探索性工具呼叫（Glob、Grep、Read）為主，直到 ExitPlanMode 被呼叫。

package/concepts/zh-TW/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/zh-TW/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 語法：`*` 匹配單層，`**` 匹配多層，`{}` 匹配多選
+- 結果按修改時間排序
+- 比 Bash 的 `find` 命令更推薦使用
+
+## 在 cc-viewer 中的意義
+
+Glob 呼叫在請求日誌中表現為 `tool_use` / `tool_result` content block 對。`tool_result` 包含匹配的檔案路徑列表。

package/concepts/zh-TW/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## 定義
+
+基於 ripgrep 的強大內容搜尋工具。支援正規表示式、檔案類型過濾和多種輸出模式。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `pattern` | string | 是 | 正規表示式搜尋模式 |
+| `path` | string | 否 | 搜尋路徑（檔案或目錄），預設當前工作目錄 |
+| `glob` | string | 否 | 檔案名稱過濾（如 `*.js`、`*.{ts,tsx}`） |
+| `type` | string | 否 | 檔案類型過濾（如 `js`、`py`、`rust`），比 glob 更高效 |
+| `output_mode` | enum | 否 | 輸出模式：`files_with_matches`（預設）、`content`、`count` |
+| `-i` | boolean | 否 | 大小寫不敏感搜尋 |
+| `-n` | boolean | 否 | 顯示行號（僅 content 模式），預設 true |
+| `-A` | number | 否 | 匹配後顯示的行數 |
+| `-B` | number | 否 | 匹配前顯示的行數 |
+| `-C` / `context` | number | 否 | 匹配前後顯示的行數 |
+| `head_limit` | number | 否 | 限制輸出條目數，預設 0（無限） |
+| `offset` | number | 否 | 跳過前 N 條結果 |
+| `multiline` | boolean | 否 | 啟用多行匹配模式，預設 false |
+
+## 使用場景
+
+**適合使用：**
+- 在程式碼庫中搜尋特定字串或模式
+- 查找函式/變數的使用位置
+- 按檔案類型過濾搜尋結果
+- 統計匹配數量
+
+**不適合使用：**
+- 按檔案名稱查找檔案——應使用 Glob
+- 需要多輪搜尋的開放式探索——應使用 Task（Explore 類型）
+
+## 注意事項
+
+- 使用 ripgrep 語法（非 grep），花括號等特殊字元需要跳脫
+- `files_with_matches` 模式只回傳檔案路徑，最高效
+- `content` 模式回傳匹配行內容，支援上下文行
+- 多行匹配需要設定 `multiline: true`
+- 始終優先使用 Grep 工具而非 Bash 中的 `grep` 或 `rg` 命令
+
+## 在 cc-viewer 中的意義
+
+Grep 呼叫在請求日誌中表現為 `tool_use` / `tool_result` content block 對。`tool_result` 包含搜尋結果。