cc-viewer 1.2.1 → 1.2.2

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

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## 定義
+
+替換、插入或刪除 Jupyter notebook（.ipynb 檔案）中的特定儲存格。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `notebook_path` | string | 是 | notebook 檔案的絕對路徑 |
+| `new_source` | string | 是 | 儲存格的新內容 |
+| `cell_id` | string | 否 | 要編輯的儲存格 ID。插入模式下新儲存格插入到此 ID 之後 |
+| `cell_type` | enum | 否 | 儲存格類型：`code` 或 `markdown`。插入模式下必填 |
+| `edit_mode` | enum | 否 | 編輯模式：`replace`（預設）、`insert`、`delete` |
+
+## 使用場景
+
+**適合使用：**
+- 修改 Jupyter notebook 中的程式碼或 markdown 儲存格
+- 向 notebook 新增儲存格
+- 刪除 notebook 中的儲存格
+
+## 注意事項
+
+- `cell_number` 是 0 索引的
+- `insert` 模式在指定位置插入新儲存格
+- `delete` 模式刪除指定位置的儲存格
+- 路徑必須是絕對路徑
+
+## 在 cc-viewer 中的意義
+
+NotebookEdit 呼叫在請求日誌中表現為 `tool_use` content block，記錄了對 notebook 的具體修改操作。

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

@@ -0,0 +1,41 @@
+# Read
+
+## 定義
+
+從本機檔案系統讀取檔案內容。支援文字檔案、圖片、PDF 和 Jupyter notebook。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `file_path` | string | 是 | 檔案的絕對路徑 |
+| `offset` | number | 否 | 起始行號（用於大檔案分段讀取） |
+| `limit` | number | 否 | 讀取行數（用於大檔案分段讀取） |
+| `pages` | string | 否 | PDF 頁碼範圍（如 "1-5"、"3"、"10-20"），僅適用於 PDF |
+
+## 使用場景
+
+**適合使用：**
+- 讀取程式碼檔案、設定檔等文字檔案
+- 查看圖片檔案（Claude 是多模態模型）
+- 讀取 PDF 文件
+- 讀取 Jupyter notebook（回傳所有儲存格及輸出）
+- 並行讀取多個檔案以取得上下文
+
+**不適合使用：**
+- 讀取目錄——應使用 Bash 的 `ls` 命令
+- 開放式程式碼庫探索——應使用 Task（Explore 類型）
+
+## 注意事項
+
+- 路徑必須是絕對路徑，不能是相對路徑
+- 預設讀取檔案前 2000 行
+- 超過 2000 字元的行會被截斷
+- 輸出使用 `cat -n` 格式，行號從 1 開始
+- 大型 PDF（超過 10 頁）必須指定 `pages` 參數，每次最多 20 頁
+- 讀取不存在的檔案會回傳錯誤（不會當機）
+- 可以在單條訊息中並行呼叫多個 Read
+
+## 在 cc-viewer 中的意義
+
+Read 呼叫在請求日誌中表現為 `tool_use`（呼叫）和 `tool_result`（回傳內容）content block 對。`tool_result` 中包含檔案的實際內容，可用於分析模型讀取了哪些檔案。

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

@@ -0,0 +1,35 @@
+# Skill
+
+## 定義
+
+在主對話中執行一個技能（skill）。技能是使用者可透過 slash command（如 `/commit`、`/review-pr`）呼叫的專用能力。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `skill` | string | 是 | 技能名稱（如 "commit"、"review-pr"、"pdf"） |
+| `args` | string | 否 | 技能參數 |
+
+## 使用場景
+
+**適合使用：**
+- 使用者輸入了 `/<skill-name>` 格式的 slash command
+- 使用者的請求匹配某個已註冊技能的功能
+
+**不適合使用：**
+- 內建 CLI 命令（如 `/help`、`/clear`）
+- 已經在執行中的技能
+- 未在可用技能列表中的技能名稱
+
+## 注意事項
+
+- 技能被呼叫後會展開為完整的 prompt
+- 支援完全限定名稱（如 `ms-office-suite:pdf`）
+- 可用技能列表在 system-reminder 訊息中提供
+- 看到 `<command-name>` 標籤時說明技能已載入，應直接執行而非再次呼叫此工具
+- 不要在未實際呼叫工具的情況下提及某個技能
+
+## 在 cc-viewer 中的意義
+
+Skill 呼叫在請求日誌中表現為 `tool_use` content block。技能展開後的 prompt 會影響後續請求的 system prompt 或訊息內容。

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

@@ -0,0 +1,53 @@
+# Task
+
+## 定義
+
+啟動一個子 agent（SubAgent）來自主處理複雜的多步驟任務。子 agent 是獨立的子程序，擁有各自專用的工具集和上下文。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `prompt` | string | 是 | 子 agent 要執行的任務描述 |
+| `description` | string | 是 | 3-5 個詞的簡短摘要 |
+| `subagent_type` | string | 是 | 子 agent 類型，決定可用工具集 |
+| `model` | enum | 否 | 指定模型（sonnet / opus / haiku），預設繼承父級 |
+| `max_turns` | integer | 否 | 最大 agentic 輪次數 |
+| `run_in_background` | boolean | 否 | 是否背景執行，背景任務回傳 output_file 路徑 |
+| `resume` | string | 否 | 要恢復的 agent ID，從上次執行繼續 |
+| `isolation` | enum | 否 | 隔離模式，`worktree` 建立臨時 git worktree |
+
+## 子 agent 類型
+
+| 類型 | 用途 | 可用工具 |
+|------|------|----------|
+| `Bash` | 命令執行，git 操作 | Bash |
+| `general-purpose` | 通用多步驟任務 | 全部工具 |
+| `Explore` | 快速探索程式碼庫 | 除 Task/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
+| `Plan` | 設計實施方案 | 除 Task/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
+| `claude-code-guide` | Claude Code 使用指南問答 | Glob, Grep, Read, WebFetch, WebSearch |
+| `statusline-setup` | 設定狀態列 | Read, Edit |
+
+## 使用場景
+
+**適合使用：**
+- 需要多步驟自主完成的複雜任務
+- 程式碼庫探索和深度研究（使用 Explore 類型）
+- 需要隔離環境的並行工作
+- 需要背景執行的長時間任務
+
+**不適合使用：**
+- 讀取特定檔案路徑——直接用 Read 或 Glob
+- 在 2-3 個已知檔案中搜尋——直接用 Read
+- 搜尋特定類別定義——直接用 Glob
+
+## 注意事項
+
+- 子 agent 完成後回傳單條訊息，其結果對使用者不可見，需要主 agent 轉述
+- 可以在單條訊息中發起多個並行 Task 呼叫以提高效率
+- 背景任務透過 TaskOutput 工具檢查進度
+- Explore 類型比直接呼叫 Glob/Grep 慢，僅在簡單搜尋不夠時使用
+
+## 在 cc-viewer 中的意義
+
+Task 呼叫會產生 SubAgent 請求鏈路，在請求列表中可以看到獨立於 MainAgent 的子請求序列。SubAgent 請求通常具有精簡的 system prompt 和較少的工具定義，與 MainAgent 形成明顯對比。

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

@@ -0,0 +1,38 @@
+# TaskCreate
+
+## 定義
+
+建立結構化的任務列表條目，用於追蹤進度、組織複雜任務，並向使用者展示工作進展。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `subject` | string | 是 | 簡短的任務標題，使用祈使句（如 "Fix authentication bug"） |
+| `description` | string | 是 | 詳細描述，包含上下文和驗收標準 |
+| `activeForm` | string | 否 | 進行中時顯示的現在進行式文字（如 "Fixing authentication bug"） |
+| `metadata` | object | 否 | 附加到任務的任意中繼資料 |
+
+## 使用場景
+
+**適合使用：**
+- 複雜的多步驟任務（3 步以上）
+- 使用者提供了多個待辦事項
+- 在規劃模式中追蹤工作
+- 使用者明確要求使用 todo 列表
+
+**不適合使用：**
+- 單一簡單任務
+- 3 步以內的簡單操作
+- 純對話或資訊查詢
+
+## 注意事項
+
+- 所有新建任務的初始狀態為 `pending`
+- `subject` 使用祈使句（"Run tests"），`activeForm` 使用現在進行式（"Running tests"）
+- 建立任務後可透過 TaskUpdate 設定依賴關係（blocks/blockedBy）
+- 建立前應先呼叫 TaskList 檢查是否有重複任務
+
+## 在 cc-viewer 中的意義
+
+TaskCreate 是 Claude Code 內部的任務管理操作，不產生獨立的 API 請求。但在 Chat Mode 中可以看到模型呼叫此工具的 tool_use block。

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

@@ -0,0 +1,35 @@
+# TaskGet
+
+## 定義
+
+透過任務 ID 取得任務的完整詳情。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `taskId` | string | 是 | 要取得的任務 ID |
+
+## 回傳內容
+
+- `subject` — 任務標題
+- `description` — 詳細需求和上下文
+- `status` — 狀態：`pending`、`in_progress` 或 `completed`
+- `blocks` — 被此任務阻塞的任務列表
+- `blockedBy` — 阻塞此任務的前置任務列表
+
+## 使用場景
+
+**適合使用：**
+- 開始工作前取得任務的完整描述和上下文
+- 了解任務的依賴關係
+- 被分配任務後取得完整需求
+
+## 注意事項
+
+- 取得任務後應檢查 `blockedBy` 列表是否為空再開始工作
+- 使用 TaskList 查看所有任務的摘要資訊
+
+## 在 cc-viewer 中的意義
+
+TaskGet 是內部任務管理操作，不產生獨立的 API 請求。

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

@@ -0,0 +1,36 @@
+# TaskList
+
+## 定義
+
+列出任務列表中的所有任務，查看整體進度和可用工作。
+
+## 參數
+
+無參數。
+
+## 回傳內容
+
+每個任務的摘要資訊：
+- `id` — 任務識別碼
+- `subject` — 簡短描述
+- `status` — 狀態：`pending`、`in_progress` 或 `completed`
+- `owner` — 負責人（agent ID），空表示未分配
+- `blockedBy` — 阻塞此任務的未完成任務 ID 列表
+
+## 使用場景
+
+**適合使用：**
+- 查看有哪些可用任務（狀態為 pending、無 owner、未被阻塞）
+- 檢查專案整體進度
+- 查找被阻塞的任務
+- 完成一個任務後查找下一個
+
+## 注意事項
+
+- 優先按 ID 順序處理任務（最小 ID 優先），因為早期任務通常為後續任務提供上下文
+- 有 `blockedBy` 的任務在依賴解除前不能認領
+- 使用 TaskGet 取得特定任務的完整詳情
+
+## 在 cc-viewer 中的意義
+
+TaskList 是內部任務管理操作，不產生獨立的 API 請求。

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

@@ -0,0 +1,34 @@
+# TaskOutput
+
+## 定義
+
+取得正在執行或已完成的後台任務的輸出。適用於後台 shell、非同步 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` 命令查找
+- 適用於所有任務類型：後台 shell、非同步 agent、遠端會話
+
+## 在 cc-viewer 中的意義
+
+TaskOutput 呼叫本身不產生 API 請求，它是 Claude Code 內部的任務管理操作，不會出現在請求日誌中。

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

@@ -0,0 +1,27 @@
+# TaskStop
+
+## 定義
+
+停止一個正在執行的後台任務。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `task_id` | string | 否 | 要停止的後台任務 ID |
+| `shell_id` | string | 否 | 已棄用，使用 `task_id` 代替 |
+
+## 使用場景
+
+**適合使用：**
+- 終止不再需要的長時間執行任務
+- 取消錯誤啟動的後台任務
+
+## 注意事項
+
+- 回傳成功或失敗狀態
+- `shell_id` 參數已棄用，應使用 `task_id`
+
+## 在 cc-viewer 中的意義
+
+TaskStop 呼叫本身不產生 API 請求，屬於 Claude Code 內部任務管理操作。

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

@@ -0,0 +1,49 @@
+# 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 查找下一個可用任務
+
+## 在 cc-viewer 中的意義
+
+TaskUpdate 是內部任務管理操作，不產生獨立的 API 請求。

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

@@ -0,0 +1,36 @@
+# 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 工具可用，優先使用那個
+
+## 在 cc-viewer 中的意義
+
+WebFetch 呼叫在請求日誌中表現為 `tool_use` / `tool_result` content block 對。`tool_result` 包含經 AI 處理後的網頁內容摘要。

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

@@ -0,0 +1,46 @@
+# 翻譯 API 上下文污染
+
+## 背景
+
+CC-Viewer 內建了一個由 Anthropic Messages API 驅動的翻譯功能（`POST /api/translate`）。在早期實作中，翻譯請求會重複使用 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/)