cc-viewer 1.6.182 → 1.6.183

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

@@ -0,0 +1,50 @@
+# Monitor
+
+啟動一個後台監視器，從長時間執行的腳本中即時推送事件。每一行標準輸出都會成為一則通知——繼續工作，事件會即時出現在對話中。
+
+## 使用時機
+
+- 在部署執行期間，持續追蹤日誌檔案中的錯誤、警告或崩潰特徵
+- 每隔 30 秒輪詢遠端 API、PR 或 CI 流水線，取得最新狀態事件
+- 即時監視檔案系統目錄或建置輸出的變更
+- 在多次迭代中等待特定條件（例如訓練步驟里程碑或佇列清空）
+- **不適用於**簡單的「等待完成」場景——請改用帶 `run_in_background` 的 `Bash`，它會在程序退出時發送一次完成通知
+
+## 參數
+
+- `command`（字串，必填）：要執行的 shell 命令或腳本。寫入標準輸出的每一行都會成為獨立的通知事件。程序退出後監視器結束。
+- `description`（字串，必填）：在每則通知中顯示的簡短可讀標籤。請盡量具體——「deploy.log 中的錯誤」比「監視日誌」更清楚。此標籤用於識別觸發通知的監視器。
+- `timeout_ms`（數字，預設 `300000`，最大 `3600000`）：終止時限（毫秒）。超過此時長後程序將被強制終止。當 `persistent: true` 時此參數無效。
+- `persistent`（布林值，預設 `false`）：設為 `true` 時，監視器在整個工作階段期間持續執行，不受逾時限制。可透過 `TaskStop` 明確停止。
+
+## 範例
+
+### 範例 1：追蹤日誌檔案中的錯誤和崩潰
+
+此範例涵蓋所有終止狀態：成功標記、回溯資訊、常見錯誤關鍵詞、OOM 終止以及意外程序退出。
+
+```bash
+tail -F /var/log/deploy.log | grep -E --line-buffered \
+  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
+```
+
+每個管道中都必須使用 `grep --line-buffered`。若不使用，作業系統會以 4 KB 區塊為單位緩衝輸出，事件可能延遲數分鐘。交替匹配模式同時涵蓋成功路徑（`deployed`）和失敗路徑（`Traceback`、`Error`、`FAILED`、`Killed`、`OOM`）。只監視成功標記的監視器在崩潰時會保持靜默——靜默與「仍在執行」無法區分。
+
+### 範例 2：每 30 秒輪詢一次遠端 API
+
+```bash
+while true; do
+  curl -sf "https://api.example.com/status" || true
+  sleep 30
+done | grep --line-buffered -E "completed|failed|error"
+```
+
+`|| true` 防止偶發的網路故障中斷迴圈。遠端 API 建議採用 30 秒以上的輪詢間隔，以避免觸發頻率限制。調整 grep 模式，同時擷取成功和失敗回應，避免 API 端錯誤被靜默掩蓋。
+
+## 注意事項
+
+- **管道中必須始終使用 `grep --line-buffered`。** 若不使用，管道緩衝會將事件延遲數分鐘，因為作業系統會累積輸出直到填滿 4 KB 區塊。`--line-buffered` 強制在每行後刷新緩衝。
+- **篩選器必須同時涵蓋成功和失敗特徵。** 只監視成功標記的監視器在崩潰、掛起或意外退出時會保持靜默。擴大匹配範圍：在成功關鍵詞之外，還應包含 `Error`、`Traceback`、`FAILED`、`Killed`、`OOM` 等終止狀態標記。
+- **遠端 API 的輪詢間隔不少於 30 秒。** 對外部服務進行高頻輪詢可能觸發頻率限制或封鎖。對於本地檔案系統或程序檢查，0.5–1 秒的間隔是合適的。
+- **對於工作階段級長期監視，使用 `persistent: true`。** 預設 `timeout_ms` 為 300 000 毫秒（5 分鐘），逾時後程序會被終止。若希望監視器持續執行直至手動停止，請設定 `persistent: true`，並在完成後呼叫 `TaskStop`。
+- **事件過多時自動停止。** 每行標準輸出都是一則對話訊息。如果篩選器太寬鬆、產生過多事件，監視器會被自動停止。請使用更精確的 `grep` 模式重新啟動。200 毫秒內到達的多行會合併為一則通知。

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

@@ -1,33 +1,39 @@
 # NotebookEdit
 
-## 定義
+修改 Jupyter notebook（`.ipynb`）中的單一 cell。支援取代 cell 原始碼、插入新 cell 或刪除既有 cell，同時保留 notebook 其餘結構。
 
-替換、插入或刪除 Jupyter notebook（.ipynb 檔案）中的特定儲存格。
+## 使用時機
+
+- 修正或更新分析 notebook 中的某個 code cell，而不重寫整個檔案
+- 替換某個 markdown cell 以改善敘事或新增說明
+- 在既有 notebook 中的已知位置插入新的 code 或 markdown cell
+- 移除已過時或損壞的 cell，使下游 cell 不再依賴它
+- 透過一次一個 cell 的迭代來準備可重現的 notebook
 
 ## 參數
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `notebook_path` | string | 是 | notebook 檔案的絕對路徑 |
-| `new_source` | string | 是 | 儲存格的新內容 |
-| `cell_id` | string | 否 | 要編輯的儲存格 ID。插入模式下新儲存格插入到此 ID 之後 |
-| `cell_type` | enum | 否 | 儲存格類型：`code` 或 `markdown`。插入模式下必填 |
-| `edit_mode` | enum | 否 | 編輯模式：`replace`（預設）、`insert`、`delete` |
+- `notebook_path`（string，必填）：`.ipynb` 檔案的絕對路徑。相對路徑會被拒絕。
+- `new_source`（string，必填）：新的 cell 原始碼。對 `replace` 與 `insert` 來說會成為 cell 內容；對 `delete` 會被忽略，但 schema 仍要求提供。
+- `cell_id`（string，選填）：目標 cell 的 ID。在 `replace` 與 `delete` 模式下，工具作用於此 cell。在 `insert` 模式下，新 cell 會插入於此 ID 的 cell 之後；省略則插入到 notebook 最上方。
+- `cell_type`（enum，選填）：`code` 或 `markdown`。`edit_mode` 為 `insert` 時必填。在 `replace` 時省略則保留既有 cell 的類型。
+- `edit_mode`（enum，選填）：`replace`（預設）、`insert` 或 `delete`。
 
-## 使用場景
+## 範例
 
-**適合使用：**
-- 修改 Jupyter notebook 中的程式碼或 markdown 儲存格
-- 向 notebook 新增儲存格
-- 刪除 notebook 中的儲存格
+### 範例 1：替換有 bug 的 code cell
+呼叫 `NotebookEdit`，將 `notebook_path` 設為絕對路徑、`cell_id` 設為目標 cell 的 ID，並以修正後的 Python 程式碼填入 `new_source`。`edit_mode` 保留預設的 `replace`。
 
-## 注意事項
+### 範例 2：插入 markdown 說明
+要在既有 `setup` cell 之後新增一個 markdown cell，設 `edit_mode: "insert"`、`cell_type: "markdown"`、`cell_id` 為 setup cell 的 ID，並把敘事放在 `new_source`。
 
-- `cell_number` 是 0 索引的
-- `insert` 模式在指定位置插入新儲存格
-- `delete` 模式刪除指定位置的儲存格
-- 路徑必須是絕對路徑
+### 範例 3：刪除過期的 cell
+設 `edit_mode: "delete"` 並提供要移除之 cell 的 `cell_id`。`new_source` 隨便給一個字串即可；它不會被套用。
 
-## 原文
+## 注意事項
 
-<textarea readonly>Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing. The notebook_path parameter must be an absolute path, not a relative path. The cell_number is 0-indexed. Use edit_mode=insert to add a new cell at the index specified by cell_number. Use edit_mode=delete to delete the cell at the index specified by cell_number.</textarea>
+- 一律傳入絕對路徑。`NotebookEdit` 不會依工作目錄解析相對路徑。
+- 工具只會改寫目標 cell；其他不相關 cell 的執行計數、輸出與 metadata 保持不動。
+- 插入時未指定 `cell_id`，新 cell 會被放到 notebook 最前面。
+- `cell_type` 在插入時為必填。在替換時若不打算把 code cell 改成 markdown（或反之），就省略此參數。
+- 要檢視 cell 並取得其 ID，請先以 `Read` 工具讀取 notebook；它會回傳含內容與輸出的 cells。
+- 一般原始檔請使用 `Edit`；`NotebookEdit` 專屬於 `.ipynb` JSON 並理解其 cell 結構。

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

@@ -0,0 +1,48 @@
+# PushNotification
+
+從目前的 Claude Code 工作階段傳送桌面通知。如果已連接遠端控制，也會同步推送到使用者的手機，將其注意力從當前所在的地方拉回工作階段。
+
+## 使用時機
+
+- 使用者可能已離開終端機，而一項耗時較長的任務已完成
+- 建置、測試或部署已完成，結果已可供檢視
+- 工作進行到需要使用者輸入才能繼續的決策點
+- 發生了你無法自主解決的錯誤或阻塞
+- 使用者明確要求在特定任務或條件達成時通知他們
+
+## 何時不應使用
+
+不要在任務執行過程中發送例行進度更新通知，也不要在回覆使用者剛提問、顯然仍在等待回覆的問題時發送通知。短任務完成時不要通知——若使用者剛提交並正在等待，通知毫無價值，反而會削弱對後續通知的信任。強烈建議預設不發送。
+
+## 參數
+
+- `message`（字串，必填）：通知內文。請保持在 200 個字元以內；行動裝置作業系統會截斷過長的字串。以使用者會採取行動的內容開頭："build failed: 2 auth tests" 比 "task complete" 更有用。
+- `status`（字串，必填）：固定設為 `"proactive"`。這是固定標記，不可更改。
+
+## 範例
+
+### 範例 1：長時間分析完成後傳送通知
+
+使用者請求了一次全倉庫依賴審計，執行耗時數分鐘，使用者已離開。報告就緒後：
+
+```
+message: "依賴審計完成：lodash、axios、jsonwebtoken 中發現 3 個高危 CVE。報告見 audit-report.txt"
+status: "proactive"
+```
+
+### 範例 2：自主工作過程中標記決策點
+
+在多步驟重構中，發現兩個模組的介面存在衝突，無法在沒有設計決策的情況下合併：
+
+```
+message: "重構已暫停：AuthService 與 UserService 的 token 介面衝突，需要您的決策後才能繼續。"
+status: "proactive"
+```
+
+## 注意事項
+
+- 預設**不發送**。無論使用者正在做什麼，通知都會打斷他們。應將其視為一種成本，必須由資訊的價值來證明其合理性。
+- 以可採取行動的內容開頭。前幾個字應告訴使用者發生了什麼，以及他們需要做什麼——而非籠統的狀態標籤。
+- 將 `message` 保持在 200 個字元以內。行動裝置作業系統會截斷過長字串，可能切掉末尾最重要的部分。
+- 若結果顯示推送因未連接遠端控制而未發送，這是預期行為。無需重試或後續處理；桌面通知仍會在本地觸發。
+- 避免濫發通知。若頻繁為瑣事發送通知，使用者會開始忽略它們。請將此工具保留給使用者極可能已離開、且確實需要立即得知結果的時刻。

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

@@ -1,56 +1,41 @@
 # Read
 
-## 定義
+從本機檔案系統載入單一檔案的內容。支援純文字、原始碼、圖片、PDF 與 Jupyter notebook，並以 `cat -n` 風格回傳以 1 為起始的行號。
 
-從本機檔案系統讀取檔案內容。支援文字檔案、圖片、PDF 和 Jupyter notebook。
+## 使用時機
+
+- 在編輯或分析前，依已知路徑讀取原始檔案
+- 檢視設定檔、lockfile、記錄或產出的成品
+- 檢視使用者貼入對話中的螢幕截圖或示意圖
+- 從長 PDF 手冊中擷取特定頁面範圍
+- 開啟 `.ipynb` notebook 同時檢視程式碼 cell、markdown 與 cell 輸出
 
 ## 參數
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `file_path` | string | 是 | 檔案的絕對路徑 |
-| `offset` | number | 否 | 起始行號（用於大檔案分段讀取） |
-| `limit` | number | 否 | 讀取行數（用於大檔案分段讀取） |
-| `pages` | string | 否 | PDF 頁碼範圍（如 "1-5"、"3"、"10-20"），僅適用於 PDF |
+- `file_path`（string，必填）：目標檔案的絕對路徑。相對路徑會被拒絕。
+- `offset`（integer，選填）：從以 1 為起始的行號開始讀取。對大檔搭配 `limit` 使用很實用。
+- `limit`（integer，選填）：從 `offset` 開始回傳的最大行數。未提供時預設為檔案頂端起的 2000 行。
+- `pages`（string，選填）：PDF 檔案的頁碼範圍，例如 `"1-5"`、`"3"` 或 `"10-20"`。對超過 10 頁的 PDF 為必填；每次請求最多 20 頁。
+
+## 範例
+
+### 範例 1：讀取整個小檔案
+僅以 `file_path` 為 `/Users/me/project/src/index.ts` 呼叫 `Read`。最多會回傳 2000 行並附行號，通常足以提供編輯所需的上下文。
 
-## 使用場景
+### 範例 2：分頁瀏覽長記錄
+對上萬行的記錄檔使用 `offset: 5001` 與 `limit: 500`，擷取狹窄區段而不浪費上下文 tokens。
 
-**適合使用：**
-- 讀取程式碼檔案、設定檔等文字檔案
-- 查看圖片檔案（Claude 是多模態模型）
-- 讀取 PDF 文件
-- 讀取 Jupyter notebook（回傳所有儲存格及輸出）
-- 並行讀取多個檔案以取得上下文
+### 範例 3：擷取特定 PDF 頁面
+對於 `/tmp/spec.pdf` 這份 120 頁的 PDF，設 `pages: "8-15"` 只擷取所需章節。對大型 PDF 省略 `pages` 會產生錯誤。
 
-**不適合使用：**
-- 讀取目錄——應使用 Bash 的 `ls` 命令
-- 開放式程式碼庫探索——應使用 Task（Explore 類型）
+### 範例 4：檢視圖片
+傳入 PNG 或 JPG 螢幕截圖的絕對路徑。圖片會以視覺形式呈現，Claude Code 可直接對其推理。
 
 ## 注意事項
 
-- 路徑必須是絕對路徑，不能是相對路徑
-- 預設讀取檔案前 2000 行
-- 超過 2000 字元的行會被截斷
-- 輸出使用 `cat -n` 格式，行號從 1 開始
-- 大型 PDF（超過 10 頁）必須指定 `pages` 參數，每次最多 20 頁
-- 讀取不存在的檔案會回傳錯誤（不會當機）
-- 可以在單條訊息中並行呼叫多個 Read
-
-## 原文
-
-<textarea readonly>Reads a file from the local filesystem. You can access any file directly by using this tool.
-Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
-
-Usage:
-- The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to 2000 lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
-- Any lines longer than 2000 characters will be truncated
-- Results are returned using cat -n format, with line numbers starting at 1
-- This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
-- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: "1-5"). Reading a large PDF without the pages parameter will fail. Maximum 20 pages per request.
-- This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
-- This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
-- You can call multiple tools in a single response. It is always better to speculatively read multiple potentially useful files in parallel.
-- You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
-- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.</textarea>
+- 一律優先使用絕對路徑。若使用者提供了絕對路徑，就照用。
+- 超過 2000 字元的行會被截斷；對於極寬的資料，請把回傳內容視為可能被截斷。
+- 需要讀取多個獨立檔案嗎？在同一次回應中平行送出多個 `Read` 呼叫。
+- `Read` 無法列出目錄。請改用 `Bash` 的 `ls` 呼叫或 `Glob` 工具。
+- 讀取既有但空白的檔案會回傳系統提示而非檔案位元組，請明確處理該訊號。
+- 在目前工作階段中，你必須先成功 `Read` 過同一個檔案，才能對其使用 `Edit`。

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

@@ -0,0 +1,73 @@
+# RemoteTrigger
+
+呼叫 claude.ai 遠端觸發器 API，用於管理排程任務和按需觸發執行。OAuth 權杖由工具內部處理，不會暴露給模型或 shell。
+
+## 使用時機
+
+- 管理 claude.ai 上的遠端代理程式（觸發器），包括列出、檢視和更新現有觸發器
+- 建立以 cron 排程為基礎的自動化任務，讓 Claude 代理程式按週期性排程執行
+- 按需觸發現有觸發器，無需等待其下一次排程執行時間
+- 列出或稽核所有目前的觸發器，以檢視其設定和狀態
+- 更新觸發器設定，例如排程、負載或說明，而無需重新建立觸發器
+
+## 參數
+
+- `action` (string, 必填)：要執行的操作 — 可選值為 `list`、`get`、`create`、`update` 或 `run`
+- `trigger_id` (string, `get`、`update` 和 `run` 時必填)：要操作的觸發器識別碼；必須符合模式 `^[\w-]+$`（僅限單字字元和連字號）
+- `body` (object, `create` 和 `update` 時必填；`run` 時選填)：傳送至 API 的請求負載
+
+## 範例
+
+### 範例 1：列出所有觸發器
+
+```json
+{
+  "action": "list"
+}
+```
+
+呼叫 `GET /v1/code/triggers`，傳回與已驗證帳戶相關聯的所有觸發器的 JSON 陣列。
+
+### 範例 2：建立每個工作日早晨執行的新觸發器
+
+```json
+{
+  "action": "create",
+  "body": {
+    "name": "weekday-morning-report",
+    "schedule": "0 8 * * 1-5",
+    "description": "每個工作日 UTC 08:00 產生每日摘要"
+  }
+}
+```
+
+使用提供的請求本文呼叫 `POST /v1/code/triggers`，傳回新建立的觸發器物件，包含其指派的 `trigger_id`。
+
+### 範例 3：按需觸發
+
+```json
+{
+  "action": "run",
+  "trigger_id": "my-report-trigger"
+}
+```
+
+立即呼叫 `POST /v1/code/triggers/my-report-trigger/run`，略過排程時間執行。
+
+### 範例 4：取得單一觸發器
+
+```json
+{
+  "action": "get",
+  "trigger_id": "my-report-trigger"
+}
+```
+
+呼叫 `GET /v1/code/triggers/my-report-trigger`，傳回完整的觸發器設定。
+
+## 注意事項
+
+- OAuth 權杖由工具在程序內注入 — 切勿手動複製、貼上或記錄權杖；這樣做會帶來安全風險，且在使用本工具時完全沒有必要。
+- 對於所有觸發器 API 呼叫，請優先使用本工具而非原始 `curl` 或其他 HTTP 用戶端；直接使用 HTTP 會略過安全權杖注入，可能暴露憑證。
+- 工具傳回來自 API 的原始 JSON 回應；呼叫端負責剖析回應並處理錯誤狀態碼。
+- `trigger_id` 的值必須符合模式 `^[\w-]+$` — 僅允許使用字母數字字元、底線和連字號；包含空格或特殊字元將導致請求失敗。

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

@@ -0,0 +1,56 @@
+# ScheduleWakeup
+
+在 `/loop` 動態模式下排程何時恢復工作。此工具讓 Claude 能夠自主控制任務迭代節奏，休眠指定時間後以相同的迴圈提示詞再次觸發。
+
+## 使用時機
+
+- 在 `/loop` 動態任務中自主控制節奏，迭代間隔取決於工作狀態而非固定時鐘
+- 等待耗時較長的建置、部署或測試執行完成後再檢查結果
+- 在目前沒有特定訊號需要監視時，在迭代之間插入閒置等待
+- 執行無使用者提示的自主迴圈——將字面量哨兵值 `<<autonomous-loop-dynamic>>` 作為 `prompt` 傳入
+- 輪詢即將發生狀態變化的程序（使用較短延遲以保持快取熱態）
+
+## 參數
+
+- `delaySeconds`（數字，必填）：距恢復的秒數。執行環境會自動將值限制在 `[60, 3600]` 範圍內，無需手動限制。
+- `reason`（字串，必填）：一句簡短的句子，解釋所選延遲時間的原因。顯示給使用者並記錄到遙測資料中。請具體說明——「正在檢查耗時較長的 bun 建置」比「等待中」更有用。
+- `prompt`（字串，必填）：喚醒時觸發的 `/loop` 輸入。每輪傳入相同的字串，使下次觸發能重複執行該任務。對於無使用者提示的自主迴圈，傳入字面量哨兵值 `<<autonomous-loop-dynamic>>`。
+
+## 範例
+
+### 範例 1：短暫延遲以重新檢查快速變化的訊號（保持快取熱態）
+
+建置剛剛啟動，通常需要兩到三分鐘完成。
+
+```json
+{
+  "delaySeconds": 120,
+  "reason": "檢查預計約 2 分鐘後完成的 bun 建置",
+  "prompt": "檢查建置狀態並回報任何錯誤"
+}
+```
+
+120 秒的延遲使對話上下文保持在 Anthropic 提示快取中（TTL 5 分鐘），因此下次喚醒更快、成本更低。
+
+### 範例 2：較長的閒置等待（接受快取未命中，分攤至更長的等待時間）
+
+資料庫遷移正在執行，通常需要 20–40 分鐘。
+
+```json
+{
+  "delaySeconds": 1200,
+  "reason": "遷移通常需要 20–40 分鐘；20 分鐘後再檢查",
+  "prompt": "檢查遷移狀態，完成後繼續"
+}
+```
+
+喚醒時快取將會冷卻，但 20 分鐘的等待足以分攤單次快取未命中的代價。每 5 分鐘輪詢一次會以相同的快取未命中代價重複 4 次，毫無收益。
+
+## 注意事項
+
+- **5 分鐘快取 TTL**：Anthropic 提示快取在 300 秒後過期。延遲低於 300 秒可保持上下文熱態；延遲超過 300 秒則在下次喚醒時產生快取未命中。
+- **避免恰好設定 300 秒**：這是最糟糕的選擇——既承擔了快取未命中的代價，又沒有獲得實質性更長的等待時間。要麼降至 270 秒（保持快取熱態），要麼提交到 1200 秒或更長（一次快取未命中換來更長的等待）。
+- **閒置等待的預設值**：當沒有特定訊號需要監視時，使用 **1200–1800 秒**（20–30 分鐘）。這讓迴圈能定期檢查，而不會每小時因無意義的快取未命中損耗 12 次。
+- **自動限制範圍**：執行環境會將 `delaySeconds` 限制在 `[60, 3600]` 範圍內。低於 60 的值變為 60；超過 3600 的值變為 3600。無需自行處理這些邊界。
+- **省略呼叫即結束迴圈**：如果打算停止迭代，請勿呼叫 ScheduleWakeup。省略該呼叫即可結束迴圈。
+- **每輪傳入相同的 `prompt`**：`prompt` 欄位在每次呼叫時必須攜帶原始 `/loop` 指令，以便下次喚醒知道要恢復哪個任務。

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

@@ -1,41 +1,68 @@
 # SendMessage
 
-## 定義
+在一個運作中的團隊內將訊息從一位成員傳給另一位，或同時向每位隊友廣播。這是隊友唯一能聽到的頻道——寫入一般文字輸出的內容對他們不可見。
 
-在團隊內的 agent 之間傳送訊息。用於直接通訊、廣播以及協議訊息（關閉請求 / 回應、計畫審批）。
+## 使用時機
+
+- 在團隊協作中，把任務指派或子問題移交給具名的隊友。
+- 向另一位代理請求狀態、中間發現或程式碼審閱。
+- 透過 `*` 向整個團隊廣播決定、共同限制或關閉通知。
+- 回覆協議 prompt，例如團隊領導的關閉請求或計畫核准請求。
+- 在委派任務結束時完成回報，讓領導可以把項目標記為完成。
 
 ## 參數
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `to` | string | 是 | 接收方：隊友名稱，或 `"*"` 廣播給所有人 |
-| `message` | string / object | 是 | 純文字訊息或結構化協議物件 |
-| `summary` | string | 否 | 在 UI 中顯示的 5-10 字預覽 |
+- `to`（string，必填）：目標隊友在團隊中註冊的 `name`，或 `*` 表示一次向所有隊友廣播。
+- `message`（string 或 object，必填）：一般通訊用純文字，或如 `shutdown_response`、`plan_approval_response` 等協議回應的結構化物件。
+- `summary`（string，選填）：5–10 字的預覽，顯示在團隊活動記錄中供純文字訊息使用。長字串訊息必填；`message` 為協議物件時忽略。
+
+## 範例
+
+### 範例 1：直接移交任務
+
+```
+SendMessage(
+  to="db-lead",
+  message="Please audit prisma/schema.prisma and list any model missing createdAt/updatedAt timestamps. Reply when done.",
+  summary="Audit schema for missing timestamps"
+)
+```
 
-## 訊息類型
+### 範例 2：廣播共同限制
 
-### 純文字
-隊友之間的直接訊息，用於協調、狀態更新和任務討論。
+```
+SendMessage(
+  to="*",
+  message="Reminder: do not touch files under legacy/ — that subtree is frozen until the migration PR lands.",
+  summary="Freeze legacy/ during migration"
+)
+```
 
-### 關閉請求
-請求隊友優雅關閉：`{ type: "shutdown_request", reason: "..." }`
+### 範例 3：協議回應
 
-### 關閉回應
-隊友批准或拒絕關閉：`{ type: "shutdown_response", approve: true/false }`
+使用結構化訊息回應領導的關閉請求：
 
-### 計畫審批回應
-批准或拒絕隊友的計畫：`{ type: "plan_approval_response", approve: true/false }`
+```
+SendMessage(
+  to="leader",
+  message={ "type": "shutdown_response", "ready": true, "final_report": "All assigned diff chunks committed on branch refactor-crew/db-lead." }
+)
+```
 
-## 廣播與直發
+### 範例 4：計畫核准回應
 
-- **直發**（`to: "隊友名稱"`）：傳送給特定隊友 — 大多數通訊的首選方式
-- **廣播**（`to: "*"`）：傳送給所有隊友 — 僅在需要全團隊緊急通知時使用
+```
+SendMessage(
+  to="leader",
+  message={ "type": "plan_approval_response", "approved": true, "notes": "LGTM, but please split step 4 into migration + backfill." }
+)
+```
 
-## 相關工具
+## 注意事項
 
-| 工具 | 用途 |
-|------|------|
-| `TeamCreate` | 建立新團隊 |
-| `TeamDelete` | 完成後刪除團隊 |
-| `Agent` | 生成加入團隊的隊友 |
-| `TaskCreate` / `TaskUpdate` / `TaskList` | 管理共享任務列表 |
+- 你一般的助理文字輸出不會傳送給隊友。若你想讓另一位代理看到某些內容，必須透過 `SendMessage` 傳遞。這是團隊工作流程中最常見的錯誤。
+- 廣播（`to: "*"`）代價高昂——它會喚醒每位隊友並耗用他們的上下文。請保留給真的影響所有人的公告。偏好定向傳送。
+- 訊息要精簡、具行動導向。提供收件人需要的檔案路徑、限制與期望的回覆格式；記得他們與你沒有共享記憶。
+- 協議訊息物件（`shutdown_response`、`plan_approval_response`）具有固定形式。不要把協議欄位混入純文字訊息，或反之。
+- 訊息是非同步的。收件人會在下一輪收到你的訊息；在他們回覆之前不要假設他們已讀或採取行動。
+- 寫得好的 `summary` 能讓團隊活動記錄在領導眼中易於掃讀——請把它當 commit subject line 對待。

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

@@ -1,56 +1,47 @@
 # Skill
 
-## 定義
+在當前對話中呼叫具名的 skill。Skill 是預先封裝的能力組合——領域知識、工作流程，以及有時也包含工具存取——由 harness 透過系統提示（system reminder）揭露給助理。
 
-在主對話中執行一個技能（skill）。技能是使用者可透過 slash command（如 `/commit`、`/review-pr`）呼叫的專用能力。
+## 使用時機
 
-## 參數
+- 使用者輸入 slash command，例如 `/review` 或 `/init`——slash command 是 skill，必須透過此工具執行。
+- 使用者描述的任務符合某個已公告 skill 的觸發條件（例如要求掃描逐字稿以找出重複出現的權限提示，就符合 `fewer-permission-prompts`）。
+- 某個 skill 的目的說明與目前的檔案、請求或對話背景直接吻合。
+- 有專門且可重複的工作流程以 skill 形式提供，且這份正式程序比臨時做法更好。
+- 使用者問「有哪些 skill 可用」——列出公告的名稱，並在他們確認時才呼叫。
 
-| 參數 | 類型 | 必填 | 說明 |
-|------|------|------|------|
-| `skill` | string | 是 | 技能名稱（如 "commit"、"review-pr"、"pdf"） |
-| `args` | string | 否 | 技能參數 |
+## 參數
 
-## 使用場景
+- `skill`（string，必填）：目前 available-skills 系統提示中所列的確切 skill 名稱。若為外掛命名空間下的 skill，請使用完整 `plugin:skill` 形式（例如 `skill-creator:skill-creator`）。不要帶前置斜線。
+- `args`（string，選填）：傳給 skill 的自由形式參數。格式與語意由每個 skill 自己的說明定義。
 
-**適合使用：**
-- 使用者輸入了 `/<skill-name>` 格式的 slash command
-- 使用者的請求匹配某個已註冊技能的功能
+## 範例
 
-**不適合使用：**
-- 內建 CLI 命令（如 `/help`、`/clear`）
-- 已經在執行中的技能
-- 未在可用技能列表中的技能名稱
+### 範例 1：對目前分支執行 review skill
 
-## 注意事項
+```
+Skill(skill="review")
+```
 
-- 技能被呼叫後會展開為完整的 prompt
-- 支援完全限定名稱（如 `ms-office-suite:pdf`）
-- 可用技能列表在 system-reminder 訊息中提供
-- 看到 `<command-name>` 標籤時說明技能已載入，應直接執行而非再次呼叫此工具
-- 不要在未實際呼叫工具的情況下提及某個技能
+`review` skill 封裝了對當前基底分支進行 pull request 審閱的步驟。呼叫它會把 harness 定義的審閱流程載入本輪。
 
-## 原文
+### 範例 2：以參數呼叫外掛命名空間下的 skill
 
-<textarea readonly>Execute a skill within the main conversation
+```
+Skill(
+  skill="skill-creator:skill-creator",
+  args="create a skill that summarizes git log for a given date range"
+)
+```
 
-When users ask you to perform tasks, check if any of the available skills match. Skills provide specialized capabilities and domain knowledge.
+將請求導向 `skill-creator` 外掛的進入點，啟動撰寫 skill 的工作流程。
 
-When users reference a "slash command" or "/<something>" (e.g., "/commit", "/review-pr"), they are referring to a skill. Use this tool to invoke it.
-
-How to invoke:
-- Use this tool with the skill name and optional arguments
-- Examples:
-  - `skill: "pdf"` - invoke the pdf skill
-  - `skill: "commit", args: "-m 'Fix bug'"` - invoke with arguments
-  - `skill: "review-pr", args: "123"` - invoke with arguments
-  - `skill: "ms-office-suite:pdf"` - invoke using fully qualified name
+## 注意事項
 
-Important:
-- Available skills are listed in system-reminder messages in the conversation
-- When a skill matches the user's request, this is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task
-- NEVER mention a skill without actually calling this tool
-- Do not invoke a skill that is already running
-- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
-- If you see a <command-name> tag in the current conversation turn, the skill has ALREADY been loaded - follow the instructions directly instead of calling this tool again
-</textarea>
+- 只能呼叫名稱完全列在 available-skills 系統提示中的 skill，或使用者在訊息中直接以 `/name` 輸入的 skill。絕對不要從記憶或訓練資料中猜測或臆造 skill 名稱——若該 skill 未被公告，就不要呼叫此工具。
+- 當使用者的請求符合已公告的 skill，呼叫 `Skill` 是阻斷性前置動作：在就任務產生任何其他回應之前先呼叫它。不要描述 skill 會做什麼——直接執行它。
+- 不要在未實際呼叫 skill 的情況下提起 skill 的名稱。宣告 skill 卻不呼叫工具會誤導使用者。
+- 不要使用 `Skill` 來執行內建 CLI 指令，例如 `/help`、`/clear`、`/model` 或 `/exit`。這些由 harness 直接處理。
+- 不要重新呼叫本輪已在執行中的 skill。若你在目前這輪看到 `<command-name>` 標籤，代表該 skill 已載入——請就地依其指示進行，而不是再次呼叫工具。
+- 若多個 skill 都適用，請挑最具體的那一個。對於新增權限或 hook 等設定變更，優先選擇 `update-config` 而非一般的設定路徑。
+- Skill 執行可能為本輪餘下時間引入新的系統提示、工具或限制。skill 完成後，請重新閱讀對話狀態再繼續。