cc-viewer 1.6.182 → 1.6.183

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

@@ -1,46 +1,38 @@
 # Edit
 
-## 定義
+在既有檔案中進行精確的字串替換。這是修改檔案的首選方式，因為只傳輸 diff，能讓編輯精確且可審核。
 
-透過精確的字串替換來編輯檔案。將檔案中的 `old_string` 替換為 `new_string`。
+## 使用時機
 
-## 參數
+- 修正單一函式中的 bug，而不重寫周圍整個檔案
+- 更新設定值、版本字串或 import 路徑
+- 使用 `replace_all` 在整個檔案中重新命名符號
+- 在某個錨點附近插入區塊（擴大 `old_string` 以包含附近的上下文，然後提供替換內容）
+- 在多步驟重構中套用小而有明確範圍的編輯
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `file_path` | string | 是 | 要修改的檔案的絕對路徑 |
-| `old_string` | string | 是 | 要替換的原始文字 |
-| `new_string` | string | 是 | 替換後的新文字（必須與 old_string 不同） |
-| `replace_all` | boolean | 否 | 是否替換所有匹配項，預設 `false` |
+## 參數
 
-## 使用場景
+- `file_path`（string，必填）：要修改的檔案絕對路徑。
+- `old_string`（string，必填）：要搜尋的確切文字。必須逐字完全相符，包括空白與縮排。
+- `new_string`（string，必填）：替換文字。必須與 `old_string` 不同。
+- `replace_all`（boolean，選填）：為 `true` 時會取代 `old_string` 的每一個出現處。預設為 `false`，此時要求比對結果必須唯一。
 
-**適合使用：**
-- 修改現有檔案中的特定程式碼段
-- 修復 bug、更新邏輯
-- 重新命名變數（配合 `replace_all: true`）
-- 任何需要精確修改檔案內容的場景
+## 範例
 
-**不適合使用：**
-- 建立新檔案——應使用 Write
-- 大規模重寫——可能需要 Write 覆寫整個檔案
+### 範例 1：修正單一呼叫點
+將 `old_string` 設為精確的一行 `const port = 3000;`，`new_string` 設為 `const port = process.env.PORT ?? 3000;`。由於比對唯一，`replace_all` 可保持預設值。
 
-## 注意事項
+### 範例 2：在整個檔案中重新命名符號
+要把 `api.ts` 內的 `getUser` 全部改為 `fetchUser`，請設 `old_string: "getUser"`、`new_string: "fetchUser"`、`replace_all: true`。
 
-- 使用前必須先透過 Read 讀取過該檔案，否則會報錯
-- `old_string` 在檔案中必須是唯一的，否則編輯失敗。如果不唯一，需要提供更多上下文使其唯一，或使用 `replace_all`
-- 編輯文字時必須保持原始縮排（tab/空格），不要包含 Read 輸出中的行號前綴
-- 優先編輯現有檔案，而非建立新檔案
-- `new_string` 必須與 `old_string` 不同
+### 範例 3：消除重複片段的歧義
+若 `return null;` 在多個分支中都出現，請擴大 `old_string` 包含周圍上下文（例如前面的 `if` 行），以確保比對唯一。否則工具會報錯而不是去猜測。
 
-## 原文
-
-<textarea readonly>Performs exact string replacements in files.
+## 注意事項
 
-Usage:
-- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
-- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
-- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.</textarea>
+- 在目前工作階段中，你必須先對該檔案呼叫過至少一次 `Read`，`Edit` 才會接受變更。`Read` 輸出中的行號前綴不是檔案內容的一部分；請不要將其納入 `old_string` 或 `new_string`。
+- 空白字元必須完全相符。注意 tab 與空格、行尾空白，特別是在 YAML、Makefile 與 Python 中。
+- 若 `old_string` 不唯一且 `replace_all` 為 `false`，編輯會失敗。請擴充上下文或啟用 `replace_all`。
+- 只要檔案已存在，請優先使用 `Edit` 而不是 `Write`；`Write` 會覆寫整個檔案，不小心就會遺失無關的內容。
+- 對同一檔案做多處不相關的修改時，請依序送出多個 `Edit` 呼叫，而不是單一大型、脆弱的替換。
+- 編輯原始碼時請避免引入 emoji、行銷文案或未請求的說明文件區塊。

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

@@ -1,128 +1,35 @@
 # EnterPlanMode
 
-## 定義
+將工作階段切換至計畫模式，這是一個唯讀的探索階段，助理在此階段調查程式碼庫並草擬具體的實作計畫，供使用者在任何檔案被修改之前先行核准。
 
-將 Claude Code 切換到規劃模式，用於在實施前探索程式碼庫並設計方案。
+## 使用時機
+
+- 使用者要求進行跨越多個檔案或子系統的非簡易變更。
+- 需求含糊，助理需要先讀程式碼再決定做法。
+- 提議進行重構、遷移或相依性升級，影響範圍尚不明確。
+- 使用者明確表示「先規劃一下」、「先做個計畫」，或要求設計評審。
+- 風險高到直接動手編輯可能浪費成果或損壞狀態。
 
 ## 參數
 
-無參數。
+無。`EnterPlanMode` 不接受任何參數——以空的參數物件呼叫即可。
 
-## 使用場景
+## 範例
 
-**適合使用：**
-- 新功能實作——需要架構決策
-- 存在多種可行方案——需要使用者選擇
-- 程式碼修改影響現有行為或結構
-- 多檔案變更——可能涉及 2-3 個以上檔案
-- 需求不明確——需要先探索再理解範圍
-- 使用者偏好很重要——實作可以有多種合理方向
+### 範例 1：大型功能需求
 
-**不適合使用：**
-- 單行或少量行的修復（拼寫錯誤、明顯 bug）
-- 使用者已給出非常具體的指令
-- 純研究/探索任務——應使用 Task（Explore 類型）
+使用者要求：「在管理後台加入 Okta SSO。」助理呼叫 `EnterPlanMode`，接著花數輪讀取認證中介層、session 儲存、路由守衛與既有登入 UI。它撰寫計畫描述所需變更、遷移步驟與測試覆蓋範圍，然後透過 `ExitPlanMode` 送出核准。
 
-## 規劃模式中的行為
+### 範例 2：風險較高的重構
 
-進入規劃模式後，Claude Code 會：
-1. 使用 Glob、Grep、Read 工具深入探索程式碼庫
-2. 理解現有模式和架構
-3. 設計實施方案
-4. 將方案提交給使用者審批
-5. 如需澄清可使用 AskUserQuestion
-6. 方案就緒後透過 ExitPlanMode 退出
+使用者說：「把 REST controller 轉成 tRPC。」助理進入計畫模式，審視每個 controller，列出公開契約，列舉部署階段（shim、雙讀、切換），並在動任何檔案之前提出排序計畫。
 
 ## 注意事項
 
-- 此工具需要使用者同意才能進入規劃模式
-- 如果不確定是否需要規劃，傾向於規劃——提前對齊比返工好
-
-## 原文
-
-<textarea readonly>Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
-
-## When to Use This Tool
-
-**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
-
-1. **New Feature Implementation**: Adding meaningful new functionality
-   - Example: "Add a logout button" - where should it go? What should happen on click?
-   - Example: "Add form validation" - what rules? What error messages?
-
-2. **Multiple Valid Approaches**: The task can be solved in several different ways
-   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
-   - Example: "Improve performance" - many optimization strategies possible
-
-3. **Code Modifications**: Changes that affect existing behavior or structure
-   - Example: "Update the login flow" - what exactly should change?
-   - Example: "Refactor this component" - what's the target architecture?
-
-4. **Architectural Decisions**: The task requires choosing between patterns or technologies
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-   - Example: "Implement state management" - Redux vs Context vs custom solution
-
-5. **Multi-File Changes**: The task will likely touch more than 2-3 files
-   - Example: "Refactor the authentication system"
-   - Example: "Add a new API endpoint with tests"
-
-6. **Unclear Requirements**: You need to explore before understanding the full scope
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Fix the bug in checkout" - need to investigate root cause
-
-7. **User Preferences Matter**: The implementation could reasonably go multiple ways
-   - If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead
-   - Plan mode lets you explore first, then present options with context
-
-## When NOT to Use This Tool
-
-Only skip EnterPlanMode for simple tasks:
-- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
-- Adding a single function with clear requirements
-- Tasks where the user has given very specific, detailed instructions
-- Pure research/exploration tasks (use the Agent tool with explore agent instead)
-
-## What Happens in Plan Mode
-
-In plan mode, you'll:
-1. Thoroughly explore the codebase using Glob, Grep, and Read tools
-2. Understand existing patterns and architecture
-3. Design an implementation approach
-4. Present your plan to the user for approval
-5. Use AskUserQuestion if you need to clarify approaches
-6. Exit plan mode with ExitPlanMode when ready to implement
-
-## Examples
-
-### GOOD - Use EnterPlanMode:
-User: "Add user authentication to the app"
-- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
-
-User: "Optimize the database queries"
-- Multiple approaches possible, need to profile first, significant impact
-
-User: "Implement dark mode"
-- Architectural decision on theme system, affects many components
-
-User: "Add a delete button to the user profile"
-- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
-
-User: "Update the error handling in the API"
-- Affects multiple files, user should approve the approach
-
-### BAD - Don't use EnterPlanMode:
-User: "Fix the typo in the README"
-- Straightforward, no planning needed
-
-User: "Add a console.log to debug this function"
-- Simple, obvious implementation
-
-User: "What files handle routing?"
-- Research task, not implementation planning
-
-## Important Notes
-
-- This tool REQUIRES user approval - they must consent to entering plan mode
-- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
-- Users appreciate being consulted before significant changes are made to their codebase
-</textarea>
+- 計畫模式依約定為唯讀。在其中，助理不得執行 `Edit`、`Write`、`NotebookEdit` 或任何有變更效應的 shell 指令。只能使用 `Read`、`Grep`、`Glob` 與非破壞性的 `Bash` 指令。
+- 不要為了瑣碎的單行編輯、純研究問題，或使用者已完整指定變更細節的任務進入計畫模式。額外成本反而弊大於利。
+- 在 Auto 模式下，除非使用者明確要求，否則不建議進入計畫模式——Auto 模式偏好行動勝於前期規劃。
+- 使用計畫模式來減少高成本工作的轉向。五分鐘的計畫常能省下一小時誤入歧途的編輯。
+- 一旦進入計畫模式，把調查重心放在實際會變動的系統部位。避免對與任務無關的 repo 做全面巡禮。
+- 計畫本身應寫入 harness 預期的路徑，這樣 `ExitPlanMode` 才能送交。計畫應包含具體的檔案路徑、函式名稱與驗證步驟，而非空泛意圖。
+- 使用者可能拒絕計畫並要求修訂。請在計畫模式內反覆迭代，直到計畫獲得接受；接受後再退出。

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

@@ -1,56 +1,44 @@
 # EnterWorktree
 
-## 定義
+在新的分支上建立一個隔離的 Git worktree，或將工作階段切換到目前 repo 的既有 worktree，讓平行或實驗性質的工作可以進行而不影響主要 checkout。
 
-Creates an isolated git worktree and switches the current session into it. Only used when the user explicitly asks to work in a worktree.
+## 使用時機
 
-## 參數
-
-| Name | Type | Required | Description |
-|---|---|---|---|
-| name | string | No | A name for the worktree. If not provided, a random name is generated. |
-
-## 使用場景
+- 使用者明確表示「worktree」——例如「start a worktree」、「create a worktree」或「work in a worktree」。
+- `CLAUDE.md` 或持久記憶中的專案指示要求你為目前任務使用 worktree。
+- 你想繼續之前已設置為 worktree 的任務（透過 `path` 重新進入）。
+- 需要多個實驗性分支同時存在於磁碟上，避免頻繁切換 checkout。
+- 長時間執行的任務需要與主工作樹中的其他無關編輯隔離。
 
-**適合使用：**
-- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree")
-
-**不適合使用：**
-- The user asks to create/switch branches — use git commands instead
-- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
-
-## 注意事項
-
-- Must be in a git repository, or have WorktreeCreate/WorktreeRemove hooks configured
-- Must not already be in a worktree
-
-## 原文
-
-<textarea readonly>Use this tool ONLY when the user explicitly asks to work in a worktree. This tool creates an isolated git worktree and switches the current session into it.
+## 參數
 
-## When to Use
+- `name`（string，選填）：新 worktree 目錄的名稱。每個以 `/` 分隔的區段只能包含字母、數字、點、底線與破折號；完整字串上限 64 個字元。若未提供且也未提供 `path`，會產生隨機名稱。與 `path` 互斥。
+- `path`（string，選填）：要切入的目前 repo 既有 worktree 的檔案系統路徑。必須出現在該 repo 的 `git worktree list` 中；若路徑不是目前 repo 註冊的 worktree 則會被拒絕。與 `name` 互斥。
 
-- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
+## 範例
 
-## When NOT to Use
+### 範例 1：以描述性名稱建立新 worktree
 
-- The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
-- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
-- Never use this tool unless the user explicitly mentions "worktree"
+```
+EnterWorktree(name="feat/okta-sso")
+```
 
-## Requirements
+以 `HEAD` 為基礎，在新分支上建立 `.claude/worktrees/feat/okta-sso`，並將工作階段的工作目錄切換進去。在你退出之前，後續的檔案編輯與 shell 指令都在該 worktree 內執行。
 
-- Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
-- Must not already be in a worktree
+### 範例 2：重新進入既有 worktree
 
-## Behavior
+```
+EnterWorktree(path="/Users/me/repo/.claude/worktrees/feat/okta-sso")
+```
 
-- In a git repository: creates a new git worktree inside `.claude/worktrees/` with a new branch based on HEAD
-- Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
-- Switches the session's working directory to the new worktree
-- On session exit, the user will be prompted to keep or remove the worktree
+回到先前建立的 worktree 繼續工作。由於你是透過 `path` 進入，`ExitWorktree` 不會自動刪除它——以 `action: "keep"` 離開，只會回到原來的目錄。
 
-## Parameters
+## 注意事項
 
-- `name` (optional): A name for the worktree. If not provided, a random name is generated.
-</textarea>
+- 除非使用者明確提出或專案指示要求，否則不要呼叫 `EnterWorktree`。一般的切換分支或修 bug 請求應使用一般 Git 指令，而非 worktree。
+- 在 Git repo 內呼叫時，工具會在 `.claude/worktrees/` 底下建立一個 worktree，並以 `HEAD` 為基礎註冊新分支。在非 Git repo 中，則委派給 `settings.json` 中設定的 `WorktreeCreate` / `WorktreeRemove` hooks，以進行不依賴 VCS 的隔離。
+- 同一時間只能啟用一個 worktree session。若你已在 worktree session 中，工具會拒絕執行；請先用 `ExitWorktree` 退出。
+- 使用 `ExitWorktree` 在 session 進行中退出。若 session 結束時仍在新建立的 worktree 內，會提示使用者保留或移除。
+- 透過 `path` 進入的 worktree 被視為外部——以 `action: "remove"` 呼叫 `ExitWorktree` 不會刪除它們。這是保護使用者手動管理之 worktree 的安全機制。
+- 新 worktree 繼承目前分支的內容，但擁有獨立的工作目錄與索引。主 checkout 中已暫存或未暫存的變更在 worktree 內看不到。
+- 命名建議：加上工作種類前綴（`feat/`、`fix/`、`spike/`），以便在 `git worktree list` 中輕鬆區分多個並行 worktree。

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

@@ -1,62 +1,42 @@
 # ExitPlanMode
 
-## 定義
+送出在計畫模式中所撰寫的實作計畫供使用者核准，若獲核准則讓工作階段離開計畫模式，以便開始進行編輯。
 
-退出規劃模式並將方案提交給使用者審批。方案內容從之前寫入的計畫檔案中讀取。
+## 使用時機
 
-## 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `allowedPrompts` | array | 否 | 實施方案所需的權限描述列表 |
-
-`allowedPrompts` 陣列中每個元素：
-
-| 欄位 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `tool` | enum | 是 | 適用的工具，目前僅支援 `Bash` |
-| `prompt` | string | 是 | 操作的語義描述（如 "run tests"、"install dependencies"） |
-
-## 使用場景
+- 在 `EnterPlanMode` 期間撰寫的計畫已完成，可供審閱。
+- 任務偏向實作（程式碼或設定變更），而非純研究，因此明確的計畫適合此任務。
+- 所有前置閱讀與分析已完成；在使用者決定之前無需進一步調查。
+- 助理已列出具體的檔案路徑、函式與步驟，而非僅是目標。
+- 使用者要求查看計畫，或計畫模式流程即將交接給編輯工具。
 
-**適合使用：**
-- 規劃模式中方案已完成，準備提交使用者審批
-- 僅用於需要撰寫程式碼的實施任務
-
-**不適合使用：**
-- 純研究/探索任務——不需要退出規劃模式
-- 想問使用者「方案可以嗎？」——這正是此工具的功能，不要用 AskUserQuestion 來問
-
-## 注意事項
+## 參數
 
-- 此工具不接受方案內容作為參數——它從之前寫入的計畫檔案中讀取
-- 使用者會看到計畫檔案的內容來審批
-- 不要在呼叫此工具前用 AskUserQuestion 問「方案是否可以」，這是重複的
-- 不要在問題中提及「計畫」，因為使用者在 ExitPlanMode 之前看不到計畫內容
+- `allowedPrompts`（array，選填）：使用者可在核准畫面上輸入的 prompts，用以自動核准或修改計畫。每個元素指定一個範圍化的權限（例如一個操作名稱與所適用的工具）。不設定則使用預設核准流程。
 
-## 原文
+## 範例
 
-<textarea readonly>Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+### 範例 1：標準送出
 
-## How This Tool Works
-- You should have already written your plan to the plan file specified in the plan mode system message
-- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
-- This tool simply signals that you're done planning and ready for the user to review and approve
-- The user will see the contents of your plan file when they review it
+在計畫模式中調查認證重構並把計畫檔案寫入磁碟後，助理不帶參數呼叫 `ExitPlanMode`。Harness 會從正式位置讀取計畫，顯示給使用者，並等待核准或拒絕。
 
-## When to Use This Tool
-IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+### 範例 2：預先核准的快捷動作
 
-## Before Using This Tool
-Ensure your plan is complete and unambiguous:
-- If you have unresolved questions about requirements or approach, use AskUserQuestion first (in earlier phases)
-- Once your plan is finalized, use THIS tool to request approval
+```
+ExitPlanMode(allowedPrompts=[
+  {"tool": "Bash", "prompt": "run tests"},
+  {"tool": "Bash", "prompt": "install dependencies"}
+])
+```
 
-**Important:** Do NOT use AskUserQuestion to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
+讓使用者預先授權慣用的後續指令，助理在實作期間就不必為每個權限提示暫停。
 
-## Examples
+## 注意事項
 
-1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
-2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
-3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.
-</textarea>
+- `ExitPlanMode` 只對實作類工作有意義。若使用者的請求是沒有檔案變更的研究或說明任務，直接作答——不要只為了退出而走計畫模式流程。
+- 計畫必須在呼叫此工具之前已寫入磁碟。`ExitPlanMode` 不接受將計畫內容作為參數；它從 harness 預期的路徑讀取。
+- 若使用者拒絕計畫，你會回到計畫模式。依回饋修訂後再次送出；在計畫未核准前不要開始編輯檔案。
+- 核准允許你離開計畫模式並在計畫描述的範圍內使用變更性工具（`Edit`、`Write`、`Bash` 等）。事後擴大範圍需要新的計畫或使用者明確同意。
+- 不要在呼叫此工具前用 `AskUserQuestion` 問「這個計畫可以嗎？」——請求計畫核准正是 `ExitPlanMode` 所做的事，而且在計畫送出前使用者看不到它。
+- 計畫要簡潔且可執行。審閱者應能在一分鐘內掃讀完畢，並確切了解會變更什麼。
+- 若你在實作途中發現計畫錯了，請停下來向使用者回報，而不是悄悄偏離。重新進入計畫模式是一個可行的下一步。

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

@@ -0,0 +1,41 @@
+# ExitWorktree
+
+退出由 `EnterWorktree` 建立的 worktree 工作階段，並將工作階段返回到原始工作目錄。此工具僅對當前工作階段中由 `EnterWorktree` 建立的 worktree 生效；若沒有活躍的此類工作階段，呼叫將為空操作。
+
+## 使用時機
+
+- 已完成隔離 worktree 中的工作，希望返回主工作目錄。
+- 在功能分支 worktree 中完成任務並合併後，需要清理該分支和目錄。
+- 希望保留 worktree 以便稍後繼續使用，只需返回原始目錄而不刪除任何內容。
+- 希望放棄實驗性或臨時性分支，不在磁碟上保留任何產物。
+- 需要開啟新的 `EnterWorktree` 工作階段，必須先退出當前工作階段。
+
+## 參數
+
+- `action`（字串，必填）：`"keep"` 保留 worktree 目錄和分支，以便之後返回；`"remove"` 刪除 worktree 目錄及其分支，執行乾淨退出。
+- `discard_changes`（布林值，選填，預設 `false`）：僅在 `action` 為 `"remove"` 時有意義。若 worktree 存在未提交的檔案或不在原始分支上的提交，工具將拒絕刪除，除非將 `discard_changes` 設定為 `true`。錯誤回應會列出具體變更，以便在重新呼叫前與使用者確認。
+
+## 範例
+
+### 範例 1：合併變更後的乾淨退出
+
+在 worktree 中完成工作並將分支合併到主分支後，使用 `action: "remove"` 呼叫 `ExitWorktree`，刪除 worktree 目錄和分支，並返回原始工作目錄。
+
+```
+ExitWorktree(action: "remove")
+```
+
+### 範例 2：丟棄含有未提交實驗程式碼的臨時 worktree
+
+若 worktree 包含需要完全丟棄的實驗性未提交變更，先嘗試 `action: "remove"`。工具將拒絕並列出未提交的變更。在與使用者確認可以丟棄後，再次呼叫並傳入 `discard_changes: true`。
+
+```
+ExitWorktree(action: "remove", discard_changes: true)
+```
+
+## 注意事項
+
+- 此工具僅對當前工作階段中由 `EnterWorktree` 建立的 worktree 生效。它不會影響透過 `git worktree add` 建立的 worktree、先前工作階段的 worktree，或從未呼叫過 `EnterWorktree` 時的普通工作目錄——這些情況下呼叫為空操作。
+- 若 worktree 存在未提交的變更或未合入原始分支的提交，`action: "remove"` 將拒絕執行，除非明確提供 `discard_changes: true`。設定此參數前務必與使用者確認，因為資料一旦刪除無法恢復。
+- 若 worktree 附有 tmux 工作階段：`remove` 時該工作階段會被終止；`keep` 時工作階段繼續運行，並返回其名稱以便使用者之後重新連線。
+- `ExitWorktree` 完成後，可再次呼叫 `EnterWorktree` 開始新的 worktree 工作階段。

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

@@ -1,39 +1,35 @@
 # Glob
 
-## 定義
+依 glob 模式比對檔名，並以最近修改時間優先的順序回傳路徑。針對任何規模的程式碼庫都能快速定位檔案，無需透過 `find`。
 
-快速的檔案名稱模式匹配工具，支援任意規模的程式碼庫。回傳按修改時間排序的匹配檔案路徑。
+## 使用時機
 
-## 參數
+- 列舉特定副檔名的每個檔案（例如 `src` 底下所有 `*.ts` 檔案）
+- 依命名慣例發掘設定或 fixture 檔案（`**/jest.config.*`、`**/*.test.tsx`）
+- 在執行針對性 `Grep` 之前縮小搜尋範圍
+- 在呼叫 `Write` 之前，檢查某個已知模式下是否已存在檔案
+- 透過修改時間排序找出最近被動過的檔案
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `pattern` | string | 是 | glob 模式（如 `**/*.js`、`src/**/*.ts`） |
-| `path` | string | 否 | 搜尋目錄，預設為當前工作目錄。不要傳 "undefined" 或 "null" |
+## 參數
 
-## 使用場景
+- `pattern`（string，必填）：要比對的 glob 表達式。支援 `*` 代表單一區段萬用字元、`**` 代表遞迴比對、`{a,b}` 代表替換選項，例如 `src/**/*.{ts,tsx}`。
+- `path`（string，選填）：搜尋的目錄。若提供，必須是有效的目錄路徑。完全省略此欄位以搜尋目前工作目錄。請勿傳入字串 `"undefined"` 或 `"null"`。
 
-**適合使用：**
-- 按檔案名稱模式查找檔案
-- 查找特定類型的所有檔案（如所有 `.tsx` 檔案）
-- 查找特定類別定義（如 `class Foo`）時先定位檔案
-- 可以在單條訊息中並行發起多個 Glob 呼叫
+## 範例
 
-**不適合使用：**
-- 搜尋檔案內容——應使用 Grep
-- 需要多輪搜尋的開放式探索——應使用 Task（Explore 類型）
+### 範例 1：所有 TypeScript 原始檔
+以 `pattern: "src/**/*.ts"` 呼叫 `Glob`。結果是按 mtime 排序的清單，所以最近編輯過的檔案會排在最前面，有助於聚焦熱點。
 
-## 注意事項
+### 範例 2：定位 class 定義候選
+當你懷疑某個 class 位於你不知道名稱的檔案中，可用 `pattern: "**/*UserService*"` 搜尋以縮小候選範圍，接著用 `Read` 或 `Grep` 跟進。
 
-- 支援標準 glob 語法：`*` 匹配單層，`**` 匹配多層，`{}` 匹配多選
-- 結果按修改時間排序
-- 比 Bash 的 `find` 命令更推薦使用
+### 範例 3：大型任務前的平行探索
+在單一訊息中送出多個 `Glob` 呼叫（例如一個 `**/*.test.ts`、一個 `**/fixtures/**`），兩者平行執行，結果可彼此對照。
 
-## 原文
+## 注意事項
 
-<textarea readonly>- Fast file pattern matching tool that works with any codebase size
-- Supports glob patterns like "**/*.js" or "src/**/*.ts"
-- Returns matching file paths sorted by modification time
-- Use this tool when you need to find files by name patterns
-- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
-- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.</textarea>
+- 結果依檔案修改時間排序（最新優先），而非字母序。若需要穩定排序，請於下游自行排序。
+- 模式由工具而非 shell 解析；你不必像命令列那樣為模式加引號或轉義。
+- 對需要多輪搜尋與推理的開放式探索，改以 `Agent` 委派 Explore 代理，而不是串接多個 `Glob`。
+- 檔名探索優先使用 `Glob`，而不是透過 `Bash` 呼叫 `find` 或 `ls`；它處理權限的一致性較好，也會回傳結構化輸出。
+- 要搜尋檔案內容（而非檔名）時，改用 `Grep`。

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

@@ -1,57 +1,46 @@
 # Grep
 
-## 定義
+使用 ripgrep 引擎搜尋檔案內容。支援完整的正規表示式、檔案類型過濾與三種輸出模式，讓你在精確度與精簡度之間取捨。
 
-基於 ripgrep 的強大內容搜尋工具。支援正規表示式、檔案類型過濾和多種輸出模式。
+## 使用時機
+
+- 定位某個函式的每個呼叫點，或某個識別字的每個參照
+- 檢查某個字串或錯誤訊息是否出現在程式碼庫的任何地方
+- 統計某個模式的出現次數，以評估重構前的影響範圍
+- 以檔案類型（`type: "ts"`）或 glob（`glob: "**/*.tsx"`）縮小搜尋
+- 透過 `multiline: true` 擷取跨行比對，如多行 struct 定義或 JSX 區塊
 
 ## 參數
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `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 類型）
+- `pattern`（string，必填）：要搜尋的正規表示式。使用 ripgrep 語法，因此字面上的大括號需要轉義（例如用 `interface\{\}` 以尋找 `interface{}`）。
+- `path`（string，選填）：要搜尋的檔案或目錄。預設為目前工作目錄。
+- `glob`（string，選填）：檔名過濾，例如 `*.js` 或 `*.{ts,tsx}`。
+- `type`（string，選填）：檔案類型捷徑，例如 `js`、`py`、`rust`、`go`。對於常見語言比 `glob` 更有效率。
+- `output_mode`（enum，選填）：`files_with_matches`（預設，只回傳路徑）、`content`（回傳比對到的行）或 `count`（回傳比對次數）。
+- `-i`（boolean，選填）：不分大小寫比對。
+- `-n`（boolean，選填）：在 `content` 模式中顯示行號。預設為 `true`。
+- `-A`（number，選填）：每個比對後顯示的上下文行數（需 `content` 模式）。
+- `-B`（number，選填）：每個比對前顯示的上下文行數（需 `content` 模式）。
+- `-C` / `context`（number，選填）：每個比對前後的上下文行數。
+- `multiline`（boolean，選填）：允許模式跨越換行（`.` 可比對 `\n`）。預設為 `false`。
+- `head_limit`（number，選填）：限制回傳的行數、檔案路徑或 count 條目。預設 250；傳入 `0` 表示不限制（請謹慎使用）。
+- `offset`（number，選填）：在套用 `head_limit` 前略過前 N 筆結果。預設為 `0`。
+
+## 範例
+
+### 範例 1：找出某個函式的所有呼叫點
+設 `pattern: "registerHandler\\("`、`output_mode: "content"`、`-C: 2`，以查看每個呼叫周圍的行。
+
+### 範例 2：依類型統計比對次數
+設 `pattern: "TODO"`、`type: "py"`、`output_mode: "count"`，查看 Python 原始碼中每個檔案的 TODO 總數。
+
+### 範例 3：多行 struct 比對
+搭配 `multiline: true` 使用 `pattern: "struct Config \\{[\\s\\S]*?version"`，擷取 Go struct 中幾行之內宣告的欄位。
 
 ## 注意事項
 
-- 使用 ripgrep 語法（非 grep），花括號等特殊字元需要跳脫
-- `files_with_matches` 模式只回傳檔案路徑，最高效
-- `content` 模式回傳匹配行內容，支援上下文行
-- 多行匹配需要設定 `multiline: true`
-- 始終優先使用 Grep 工具而非 Bash 中的 `grep` 或 `rg` 命令
-
-## 原文
-
-<textarea readonly>A powerful search tool built on ripgrep
-
-  Usage:
-  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
-  - Supports full regex syntax (e.g., "log.*Error", "function\s+\w+")
-  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
-  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
-  - Use Agent tool for open-ended searches requiring multiple rounds
-  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\{\}` to find `interface{}` in Go code)
-  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \{[\s\S]*?field`, use `multiline: true`
-</textarea>
+- 一律優先使用 `Grep`，而不是透過 `Bash` 執行 `grep` 或 `rg`；此工具針對正確權限與結構化輸出做了最佳化。
+- 預設輸出模式為 `files_with_matches`，成本最低。只有在你真的需要看到內容時才切換到 `content`。
+- 除非 `output_mode` 為 `content`，否則 context 旗標（`-A`、`-B`、`-C`）會被忽略。
+- 大型結果集會消耗上下文 tokens。使用 `head_limit`、`offset` 或更緊的 `glob`/`type` 過濾器以保持聚焦。
+- 檔名探索請改用 `Glob`；需要多輪開放式調查時，可以派發以 Explore 代理執行的 `Agent`。