cc-viewer 1.6.182 → 1.6.183

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

@@ -1,125 +1,60 @@
 # Agent
 
-## 定義
+啟動一個擁有獨立上下文視窗的自主 Claude Code 子代理，用於處理聚焦的任務並回傳單一合併結果。這是委派開放式研究、平行工作或團隊協作的標準機制。
 
-啟動一個子 agent（SubAgent）來自主處理複雜的多步驟任務。子 agent 是獨立的子程序，擁有各自專用的工具集和上下文。Agent 是新版 Claude Code 中 Task 工具的重新命名版本。
+## 使用時機
 
-## 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `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，從上次執行繼續。適用於在不遺失上下文的情況下接續之前的子 agent |
-| `isolation` | enum | 否 | 隔離模式，`worktree` 建立臨時 git worktree |
-
-## 子 agent 類型
-
-| 類型 | 用途 | 可用工具 |
-|------|------|----------|
-| `Bash` | 命令執行，git 操作 | Bash |
-| `general-purpose` | 通用多步驟任務 | 全部工具 |
-| `Explore` | 快速探索程式碼庫 | 除 Agent/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
-| `Plan` | 設計實施方案 | 除 Agent/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
-| `claude-code-guide` | Claude Code 使用指南問答 | Glob, Grep, Read, WebFetch, WebSearch |
-| `statusline-setup` | 設定狀態列 | Read, Edit |
-
-## 使用場景
-
-**適合使用：**
-- 需要多步驟自主完成的複雜任務
-- 程式碼庫探索和深度研究（使用 Explore 類型）
-- 需要隔離環境的並行工作
-- 需要背景執行的長時間任務
+- 開放式搜尋——你尚不清楚哪些檔案相關，預期需要多輪 `Glob`、`Grep` 與 `Read`。
+- 平行的獨立工作——在同一則訊息中啟動多個代理，同時調查不同領域。
+- 將嘈雜的探索與主對話隔離，使父層上下文保持精簡。
+- 委派給特定的子代理類型，例如 `Explore`、`Plan`、`claude-code-guide` 或 `statusline-setup`。
+- 把一位具名的隊友加入一個運作中的團隊，以便協同進行多代理工作。
 
-**不適合使用：**
-- 讀取特定檔案路徑——直接用 Read 或 Glob
-- 在 2-3 個已知檔案中搜尋——直接用 Read
-- 搜尋特定類別定義——直接用 Glob
+當目標檔案或符號已經明確時，不要使用此工具——直接用 `Read`、`Grep` 或 `Glob`。透過 `Agent` 進行單步查詢會浪費一整個上下文視窗並增加延遲。
 
-## 注意事項
-
-- 子 agent 完成後回傳單條訊息，其結果對使用者不可見，需要主 agent 轉述
-- 可以在單條訊息中發起多個並行 Agent 呼叫以提高效率
-- 背景任務透過 TaskOutput 工具檢查進度
-- Explore 類型比直接呼叫 Glob/Grep 慢，僅在簡單搜尋不夠時使用
-- 長時間執行且不需要立即結果的任務建議使用 `run_in_background: true`；需要結果後才能繼續時使用前台模式（預設）
-- `resume` 參數允許繼續之前啟動的子 agent 會話，保留其累積的上下文
-
-## 原文
+## 參數
 
-<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
+- `description`（string，必填）：描述任務的 3–5 個字短標籤；會顯示在 UI 與記錄中。
+- `prompt`（string，必填）：代理將執行的完整、自我包含的任務說明。必須包含所有必要的背景、限制條件與預期回傳格式。
+- `subagent_type`（string，選填）：預設角色，例如 `general-purpose`、`Explore`、`Plan`、`claude-code-guide` 或 `statusline-setup`。預設為 `general-purpose`。
+- `run_in_background`（boolean，選填）：若為 true，代理會非同步執行，父層可繼續工作；結果稍後取得。
+- `model`（string，選填）：為此代理覆寫模型——`opus`、`sonnet` 或 `haiku`。預設為父層工作階段所用的模型。
+- `isolation`（string，選填）：設為 `worktree` 可讓代理在獨立的 git worktree 中執行，避免其檔案寫入與父層衝突。
+- `team_name`（string，選填）：在加入既有團隊時，該代理要加入的團隊識別碼。
+- `name`（string，選填）：團隊內可尋址的隊友名稱，會作為 `SendMessage` 的 `to` 目標。
 
-The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+## 範例
 
-Available agent types and the tools they have access to:
-- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
-- statusline-setup: Use this agent to configure the user's Claude Code status line setting. (Tools: Read, Edit)
-- Explore: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- claude-code-guide: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can resume using the "resume" parameter. (Tools: Glob, Grep, Read, WebFetch, WebSearch)
+### 範例 1：開放式程式碼搜尋
 
-When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use.
+```
+Agent(
+  description="Find auth middleware",
+  subagent_type="Explore",
+  prompt="Locate every place in this repo where JWT verification is performed. Return a bulleted list of absolute file paths with a one-line note about each site's role. Do not modify any files."
+)
+```
 
-When NOT to use the Agent tool:
-- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
-- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
-- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
-- Other tasks that are not related to the agent descriptions above
+### 範例 2：平行獨立調查
 
-Usage notes:
-- Always include a short description (3-5 words) summarizing what the agent will do
-- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
-- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
-- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
-- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.
-- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.
-- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
-- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
-- The agent's outputs should generally be trusted
-- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
-- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
-- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
-- You can optionally set `isolation: "worktree"` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.
+在同一則訊息中啟動兩個代理——一個檢查建構流水線，一個審視測試框架。每個都有自己的上下文視窗，並回傳摘要。將多個代理放在單一 tool-call 區塊中可以同時執行。
 
-Example usage:
+### 範例 3：把一位隊友加入運作中的團隊
 
-<example_agent_descriptions>
-"test-runner": use this agent after you are done writing code to run tests
-"greeting-responder": use this agent to respond to user greetings with a friendly joke
-</example_agent_descriptions>
+```
+Agent(
+  description="Data layer specialist",
+  team_name="refactor-crew",
+  name="db-lead",
+  prompt="You are db-lead on team refactor-crew. Audit all Prisma schema files and propose a migration plan. Use SendMessage to report findings to the team leader."
+)
+```
 
-<example>
-user: "Please write a function that checks if a number is prime"
-assistant: Sure let me write a function that checks if a number is prime
-assistant: First let me use the Write tool to write a function that checks if a number is prime
-assistant: I'm going to use the Write tool to write the following code:
-<code>
-function isPrime(n) {
-  if (n <= 1) return false
-  for (let i = 2; i * i <= n; i++) {
-    if (n % i === 0) return false
-  }
-  return true
-}
-</code>
-<commentary>
-Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
-</commentary>
-assistant: Now let me use the test-runner agent to run the tests
-assistant: Uses the Agent tool to launch the test-runner agent
-</example>
+## 注意事項
 
-<example>
-user: "Hello"
-<commentary>
-Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
-</commentary>
-assistant: "I'm going to use the Agent tool to launch the greeting-responder agent"
-</example>
-</textarea>
+- 代理不會記得先前的執行內容。每次呼叫都從零開始，因此 `prompt` 必須完全自我包含——包含檔案路徑、慣例、問題，以及你想拿回的答案格式。
+- 代理只會回傳一則最終訊息。它無法在執行過程中反問釐清，因此 prompt 中的模糊不清會變成結果中的猜測。
+- 當子任務彼此獨立時，平行執行多個代理比循序呼叫快得多。請把它們批次放在單一 tool-call 區塊中。
+- 若代理將寫入檔案，而你想在合併至主工作樹之前先檢視變更，就用 `isolation: "worktree"`。
+- 對於唯讀偵查，優先選擇 `subagent_type: "Explore"`；設計工作則選 `Plan`；混合讀寫任務使用預設的 `general-purpose`。
+- 背景代理（`run_in_background: true`）適合長時間的工作；不要用 sleep 迴圈輪詢——完成時父層會收到通知。

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

@@ -1,75 +1,60 @@
 # AskUserQuestion
 
-## 定義
+在聊天 UI 中向使用者呈現一個或多個結構化的選擇題，收集其選擇後回傳給助理——適合用來釐清意圖，而不必透過自由形式的來回對話。
 
-在執行過程中向使用者提問，用於取得澄清、驗證假設或請求決策。
+## 使用時機
 
-## 參數
-
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `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
+- `questions`（array，必填）：一次顯示一到四個問題。每個問題物件包含：
+  - `question`（string，必填）：完整的問題文字，以問號結尾。
+  - `header`（string，必填）：顯示於問題上方的短標籤（最多 12 個字元）。
+  - `options`（array，必填）：二到四個選項物件。每個選項有 `label`（1–5 個字）、`description` 與選填的 `markdown` 預覽。
+  - `multiSelect`（boolean，必填）：為 `true` 時允許使用者選擇多個選項。
+
+## 範例
+
+### 範例 1：選擇單一框架
+
+```
+AskUserQuestion(questions=[{
+  "header": "Test runner",
+  "question": "Which test runner should I configure?",
+  "multiSelect": false,
+  "options": [
+    {"label": "Vitest (Recommended)", "description": "Fast, Vite-native, Jest-compatible API"},
+    {"label": "Jest",                  "description": "Mature, broadest plugin ecosystem"},
+    {"label": "Node --test",           "description": "Zero dependencies, built in"}
+  ]
+}])
+```
+
+### 範例 2：並排預覽兩種版面
+
+```
+AskUserQuestion(questions=[{
+  "header": "Layout",
+  "question": "Which dashboard layout do you prefer?",
+  "multiSelect": false,
+  "options": [
+    {"label": "Sidebar",  "description": "Nav on the left", "markdown": "```\n+------+---------+\n| NAV  | CONTENT |\n+------+---------+\n```"},
+    {"label": "Top bar",  "description": "Nav across top",  "markdown": "```\n+-----------------+\n|       NAV       |\n+-----------------+\n|     CONTENT     |\n+-----------------+\n```"}
+  ]
+}])
+```
 
 ## 注意事項
 
-- 使用者始終可以選擇 "Other" 提供自訂輸入
-- 推薦選項放在第一位，並在 label 末尾加 "(Recommended)"
-- `markdown` 預覽僅支援單選問題
-- 有 `markdown` 的選項會切換為左右並排佈局
-- 在規劃模式中，用於在確定方案前澄清需求
-
-## 原文
-
-<textarea readonly>Use this tool when you need to ask the user questions during execution. This allows you to:
-1. Gather user preferences or requirements
-2. Clarify ambiguous instructions
-3. Get decisions on implementation choices as you work
-4. Offer choices to the user about what direction to take.
-
-Usage notes:
-- Users will always be able to select "Other" to provide custom text input
-- Use multiSelect: true to allow multiple answers to be selected for a question
-- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
-
-Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ExitPlanMode for plan approval. IMPORTANT: Do not reference "the plan" in your questions (e.g., "Do you have feedback about the plan?", "Does the plan look good?") because the user cannot see the plan in the UI until you call ExitPlanMode. If you need plan approval, use ExitPlanMode instead.
-
-Preview feature:
-Use the optional `markdown` field on options when presenting concrete artifacts that users need to visually compare:
-- ASCII mockups of UI layouts or components
-- Code snippets showing different implementations
-- Diagram variations
-- Configuration examples
-
-When any option has a markdown, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
-</textarea>
+- UI 會自動在每個問題後面附加一個「Other」自由文字選項。請不要自行加入「Other」、「None」或「Custom」——會重複內建的退出機制。
+- 每次呼叫限制 1–4 個問題，每個問題限制 2–4 個選項。超出範圍會被 harness 拒絕。
+- 若你推薦某個特定選項，把它排第一個並在 label 後附加「(Recommended)」，UI 會凸顯該偏好路徑。
+- `markdown` 欄位的預覽僅在單選問題中支援。用於視覺化成果（ASCII 版面、程式片段、設定 diff），而不是只需 label 加說明即可的偏好問題。
+- 當某題中有任一選項帶有 `markdown` 值時，UI 會切換為並排版面——左側為選項列表，右側為預覽。
+- 不要用 `AskUserQuestion` 詢問「這個計畫可以嗎？」——請改呼叫 `ExitPlanMode`，那是為計畫批准所設計的工具。在計畫模式下，也避免在問題文字中提到「the plan」，因為在 `ExitPlanMode` 執行之前使用者看不到計畫。
+- 不要使用此工具索取敏感或自由形式的輸入，例如 API 金鑰或密碼。請改在聊天中詢問。

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

@@ -1,167 +1,39 @@
 # Bash
 
-## 定義
+在一個持續存在的工作目錄中執行 shell 指令，並回傳其 stdout/stderr。最好保留給沒有任何專屬 Claude Code 工具能表達的操作使用，例如執行 git、npm、docker 或建構指令稿。
 
-執行 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）初始化
-
-## 原文
-
-<textarea readonly>Executes a given bash command and returns its output.
-
-The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+- 執行 git 操作（`git status`、`git diff`、`git commit`、`gh pr create`）
+- 執行套件管理器與建構工具（`npm install`、`npm run build`、`pytest`、`cargo build`）
+- 透過 `run_in_background` 在背景啟動長時間執行的程序（開發伺服器、watcher）
+- 呼叫沒有內建對應工具的領域專屬 CLI（`docker`、`terraform`、`kubectl`、`gh`）
+- 在先後順序很重要時，使用 `&&` 把相依步驟串接起來
 
-IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
-
- - File search: Use Glob (NOT find or ls)
- - Content search: Use Grep (NOT grep or rg)
- - Read files: Use Read (NOT cat/head/tail)
- - Edit files: Use Edit (NOT sed/awk)
- - Write files: Use Write (NOT echo >/cat <<EOF)
- - Communication: Output text directly (NOT echo/printf)
-While the Bash tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
-
-# Instructions
- - If your command will create new directories or files, first use this tool to run `ls` to verify the parent directory exists and is the correct location.
- - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
- - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.
- - You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
- - You can use the `run_in_background` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
- - Write a clear, concise description of what your command does. For simple commands, keep it brief (5-10 words). For complex commands (piped commands, obscure flags, or anything hard to understand at a glance), include enough context so that the user can understand what your command will do.
- - When issuing multiple commands:
-  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
-  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
-  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
-  - DO NOT use newlines to separate commands (newlines are ok in quoted strings).
- - For git commands:
-  - Prefer to create a new commit rather than amending an existing commit.
-  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
-  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
- - Avoid unnecessary `sleep` commands:
-  - Do not sleep between commands that can run immediately — just run them.
-  - If your command is long running and you would like to be notified when it finishes – simply run your command using `run_in_background`. There is no need to sleep in this case.
-  - Do not retry failing commands in a sleep loop — diagnose the root cause or consider an alternative approach.
-  - If waiting for a background task you started with `run_in_background`, you will be notified when it completes — do not poll.
-  - If you must poll an external process, use a check command (e.g. `gh run view`) rather than sleeping first.
-  - If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.
-
-# Committing changes with git
-
-Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
-
-Git Safety Protocol:
-- NEVER update the git config
-- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. Taking unauthorized destructive actions is unhelpful and can result in lost work, so it's best to ONLY run these commands when given direct instructions 
-- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
-- NEVER run force push to main/master, warn the user if they request it
-- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
-- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
-- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive
-
-1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:
-  - Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
-  - Run a git diff command to see both staged and unstaged changes that will be committed.
-  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
-2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
-  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
-  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
-  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
-  - Ensure it accurately reflects the changes and their purpose
-3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands:
-   - Add relevant untracked files to the staging area.
-   - Create the commit with a message ending with:
-   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-   - Run git status after the commit completes to verify success.
-   Note: git status depends on the commit completing, so run it sequentially after the commit.
-4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
-
-Important notes:
-- NEVER run additional commands to read or explore code, besides git bash commands
-- NEVER use the TodoWrite or Agent tools
-- DO NOT push to the remote repository unless the user explicitly asks you to do so
-- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
-- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
-- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
-- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
-<example>
-git commit -m "$(cat <<'EOF'
-   Commit message here.
-
-   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-   EOF
-   )"
-</example>
+## 參數
 
-# Creating pull requests
-Use the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.
+- `command`（string，必填）：要執行的確切 shell 指令。
+- `description`（string，必填）：簡短、主動語態的摘要（簡單指令 5–10 字；管線或較冷門的指令可加上更多背景）。
+- `timeout`（number，選填）：逾時毫秒數，最大 `600000`（10 分鐘）。預設 `120000`（2 分鐘）。
+- `run_in_background`（boolean，選填）：為 `true` 時，指令會在背景執行，完成時你會收到通知。不要自己附加 `&`。
 
-IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
+## 範例
 
-1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel using the Bash tool, in order to understand the current state of the branch since it diverged from the main branch:
-   - Run a git status command to see all untracked files (never use -uall flag)
-   - Run a git diff command to see both staged and unstaged changes that will be committed
-   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
-   - Run a git log command and `git diff [base-branch]...HEAD` to understand the full commit history for the current branch (from the time it diverged from the base branch)
-2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
-   - Keep the PR title short (under 70 characters)
-   - Use the description/body for details, not the title
-3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands in parallel:
-   - Create new branch if needed
-   - Push to remote with -u flag if needed
-   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.
-<example>
-gh pr create --title "the pr title" --body "$(cat <<'EOF'
-## Summary
-<1-3 bullet points>
+### 範例 1：提交前檢查 repo 狀態
+在同一則訊息中以兩個平行的 `Bash` 呼叫送出 `git status` 與 `git diff --stat`，快速蒐集背景資訊，之後再於後續呼叫中組裝 commit。
 
-## Test plan
-[Bulleted markdown checklist of TODOs for testing the pull request...]
+### 範例 2：串接相依的建構步驟
+使用單一呼叫例如 `npm ci && npm run build && npm test`，每個步驟只有在前一步成功後才會執行。只有在你刻意希望後續步驟即使前面失敗也要執行時，才使用 `;`。
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-</example>
+### 範例 3：長時間執行的開發伺服器
+以 `run_in_background: true` 呼叫 `npm run dev`。該程序結束時你會收到通知。不要用 `sleep` 迴圈輪詢；請診斷失敗原因，而不是盲目重試。
 
-Important:
-- DO NOT use the TodoWrite or Agent tools
-- Return the PR URL when you're done, so the user can see it
+## 注意事項
 
-# Other common operations
-- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments</textarea>
+- 工作目錄會在呼叫之間保持，但 shell 狀態（export 的變數、shell 函式、別名）不會保留。優先使用絕對路徑，除非使用者要求，否則避免 `cd`。
+- 優先使用專屬工具，而不是管線化的 shell 對應指令：用 `Glob` 取代 `find`/`ls`、`Grep` 取代 `grep`/`rg`、`Read` 取代 `cat`/`head`/`tail`、`Edit` 取代 `sed`/`awk`、`Write` 取代 `echo >` 或 heredoc，面向使用者的輸出以一般助理文字取代 `echo`/`printf`。
+- 任何包含空白的路徑請以雙引號括起來（例如 `"/Users/me/My Project/file.txt"`）。
+- 對於獨立指令，請在單一訊息中平行送出多個 `Bash` 呼叫。只有在一個指令依賴另一個時才使用 `&&` 串接。
+- 超過 30000 個字元的輸出會被截斷。擷取大量記錄時，請重新導向至檔案，再用 `Read` 工具讀取。
+- 不要使用互動旗標例如 `git rebase -i` 或 `git add -i`；它們無法透過此工具接收輸入。
+- 除非使用者明確要求，不要略過 git hooks（`--no-verify`、`--no-gpg-sign`）或執行破壞性操作（`reset --hard`、`push --force`、`clean -f`）。

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

@@ -0,0 +1,57 @@
+# CronCreate
+
+將提示詞排入佇列，於未來特定時間執行，支援一次性觸發與週期性重複兩種模式。使用標準的 5 欄位 cron 表達式，基於使用者本地時區，無需進行時區轉換。
+
+## 使用時機
+
+- **一次性提醒**：當使用者希望在特定時間收到提醒時（如「明天下午 3 點提醒我」），將 `recurring` 設為 `false`，任務觸發一次後自動刪除。
+- **週期性排程**：當使用者希望某件事反覆發生時（如「每個工作日早上 9 點」、「每 30 分鐘一次」），使用預設的 `recurring: true`。
+- **自主 Agent 迴圈**：當需要建立定期自我觸發的工作流程時，例如每日摘要或週期性狀態檢查。
+- **持久化任務**：當排程需要在工作階段重新啟動後繼續保留時，傳入 `durable: true`，任務將寫入 `.claude/scheduled_tasks.json`。
+- **大約時間請求**：當使用者說「大約 9 點」或「每小時」時，應選擇非整點分鐘值（例如 `57 8 * * *` 或 `7 * * * *`），避免大量使用者在 :00 或 :30 時刻同時觸發。
+
+## 參數
+
+- `cron`（string，必填）：基於使用者本地時區的 5 欄位 cron 表達式，格式為 `分鐘 小時 日 月 星期`。例如 `"0 9 * * 1-5"` 表示週一至週五早上 9:00。
+- `prompt`（string，必填）：cron 觸發時要排入佇列的提示詞文字，即到達排程時間時將提交給 REPL 的確切內容。
+- `recurring`（boolean，選填，預設 `true`）：為 `true` 時，任務在每個符合的 cron 週期觸發，7 天後自動過期；為 `false` 時，任務僅觸發一次後自動刪除，適用於一次性提醒。
+- `durable`（boolean，選填，預設 `false`）：為 `false` 時，排程僅存於記憶體中，工作階段結束後即消失；為 `true` 時，任務持久化至 `.claude/scheduled_tasks.json`，重新啟動後仍然有效。
+
+## 範例
+
+### 範例 1：一次性提醒
+
+使用者說：「明天下午 2:30 提醒我寄送週報。」假設明天是 4 月 21 日：
+
+```json
+{
+  "cron": "30 14 21 4 *",
+  "prompt": "提醒：現在寄送週報。",
+  "recurring": false,
+  "durable": true
+}
+```
+
+`recurring: false` 確保任務觸發後自動刪除。`durable: true` 保證在此之前的重新啟動不會遺失該任務。
+
+### 範例 2：週期性工作日早晨任務
+
+使用者說：「每個工作日早上，彙整我的 GitHub 未處理 Issue。」
+
+```json
+{
+  "cron": "3 9 * * 1-5",
+  "prompt": "彙整所有指派給我的 GitHub 未處理 Issue。",
+  "recurring": true,
+  "durable": true
+}
+```
+
+使用分鐘 `3` 而非 `0`，避免在整點造成伺服器負載尖峰。該任務 7 天後自動過期。
+
+## 注意事項
+
+- **7 天自動過期**：週期性任務最多運行 7 天後自動刪除。若需更長時間的排程，請在過期前重新建立。
+- **僅在閒置時觸發**：`CronCreate` 僅在 REPL 未處理其他查詢時才將提示詞排入佇列。若觸發時 REPL 正在忙碌，提示詞將等待當前查詢完成後再執行。
+- **避免使用 :00 和 :30 分鐘值**：對於大約時間的請求，應主動選擇非整點分鐘值，以分散系統負載。只有使用者明確指定某個精確分鐘時，才使用 :00 或 :30。
+- **無需時區轉換**：cron 表達式直接按使用者本地時區解析，無需轉換為 UTC 或其他時區。

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

@@ -0,0 +1,43 @@
+# CronDelete
+
+取消先前透過 `CronCreate` 排程的定時任務，立即將其從記憶體會話儲存中移除。若任務已被自動刪除（單次任務觸發後自動移除，週期性任務在 7 天後自動過期），則此操作無效。
+
+## 使用時機
+
+- 使用者要求在 7 天自動過期前停止某個週期性定時任務。
+- 單次任務不再需要，希望在觸發前予以取消。
+- 需要變更現有任務的排程表達式——先以 `CronDelete` 刪除，再以 `CronCreate` 搭配新的表達式重新建立。
+- 清理多個過期任務，保持會話儲存整潔。
+
+## 參數
+
+- `id`（string，必填）：`CronCreate` 建立任務時回傳的任務 ID。此值必須完全相符，不支援模糊搜尋或依名稱查找。
+
+## 範例
+
+### 範例 1：取消正在執行的週期性任務
+
+先前建立了一個 ID 為 `"cron_abc123"` 的週期性任務，使用者要求停止它。
+
+```
+CronDelete({ id: "cron_abc123" })
+```
+
+該任務從會話儲存中移除，不會再次觸發。
+
+### 範例 2：在觸發前移除過期的單次任務
+
+一個 ID 為 `"cron_xyz789"` 的單次任務被排程為 30 分鐘後執行，但使用者決定不再需要它。
+
+```
+CronDelete({ id: "cron_xyz789" })
+```
+
+任務被取消，原定觸發時間到來時不會執行任何動作。
+
+## 注意事項
+
+- `id` 必須來自 `CronCreate` 的回傳值。無法透過描述或回呼查找任務——若日後可能需要取消，請事先保存 ID。
+- 若任務已被自動刪除（作為單次任務觸發，或達到 7 天週期過期），以該 ID 呼叫 `CronDelete` 為無操作，不會產生錯誤。
+- `CronDelete` 僅影響目前的記憶體會話。若執行環境不跨重新啟動持久化定時任務狀態，則無論是否呼叫 `CronDelete`，重新啟動後任務均會遺失。
+- 沒有批次刪除操作，需使用各自的 `id` 逐一取消每個任務。

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

@@ -0,0 +1,30 @@
+# CronList
+
+列出目前工作階段中透過 `CronCreate` 建立的所有排程任務。傳回每個活躍任務的摘要，包含 `id`、cron 表達式、縮略 `prompt`、`recurring` 旗標、`durable` 旗標及下次觸發時間。
+
+## 使用時機
+
+- 在修改設定或結束工作階段前，審視目前已排程的所有任務。
+- 在呼叫 `CronDelete` 刪除任務前，先找到正確的 `id`。
+- 透過確認任務是否存在及其下次觸發時間，排查預期任務未執行的問題。
+- 確認某個一次性（非循環）任務是否尚未觸發、仍處於待執行狀態。
+
+## 參數
+
+無。
+
+## 範例
+
+### 範例 1：審視所有已排程任務
+
+不帶任何引數呼叫 `CronList`，即可取得所有活躍排程任務的完整清單。傳回結果包含每個任務的 `id`、cron 表達式、`prompt` 的截短版本、是否 `recurring`（循環）、是否 `durable`（持久化）以及下次觸發時間。
+
+### 範例 2：找到特定循環任務的 id
+
+若您建立了多個排程任務並需要刪除其中一個，請先呼叫 `CronList`。在傳回清單中找出 `prompt` 摘要和 cron 表達式與目標任務相符的項目，複製其 `id` 並傳入 `CronDelete`。
+
+## 注意事項
+
+- 僅列出目前工作階段中建立的任務，除非建立時指定了 `durable: true`，該選項允許任務在工作階段重新啟動後持續存在。
+- 摘要中的 `prompt` 欄位會被截短，僅顯示完整提示文字的開頭部分，並非全部內容。
+- 已觸發並執行完畢的一次性任務（`recurring` 為 `false`）會被自動刪除，不再出現在清單中。