cc-viewer 1.6.182 → 1.6.183

package/concepts/zh/Tool-NotebookEdit.md

@@ -1,33 +1,39 @@
 # NotebookEdit
 
-## 定义
+修改 Jupyter notebook（`.ipynb`）中的单个 cell。支持替换 cell 源码、插入新 cell 或删除现有 cell，同时保留其余 notebook 结构。
 
-替换、插入或删除 Jupyter notebook（.ipynb 文件）中的特定单元格。
+## 何时使用
+
+- 修复或更新分析 notebook 中的代码 cell，而无需重写整个文件
+- 替换 markdown cell 以改进叙述或补充文档
+- 在已有 notebook 的已知位置插入新的代码或 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：替换有缺陷的代码 cell
+调用 `NotebookEdit`，将 `notebook_path` 设为绝对路径，`cell_id` 设为目标 cell 的 ID，`new_source` 提供修正后的 Python 代码。`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 的执行计数、输出和元数据保持原样。
+- 在没有 `cell_id` 的情况下插入，新 cell 会放在 notebook 最前面。
+- `cell_type` 在插入时必填。替换时请省略，除非你明确要把代码 cell 转为 markdown（反之亦然）。
+- 要查看 cell 并取得它们的 ID，请先用 `Read` 工具读取 notebook；它会返回 cell 内容与输出。
+- 普通源文件请使用常规 `Edit`；`NotebookEdit` 专门处理 `.ipynb` JSON，并理解其 cell 结构。

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

@@ -1,56 +1,41 @@
 # Read
 
-## 定义
+从本地文件系统加载单个文件的内容。支持纯文本、源代码、图像、PDF 和 Jupyter notebook，并以 `cat -n` 风格返回从 1 起的行号结果。
 
-从本地文件系统读取文件内容。支持文本文件、图片、PDF 和 Jupyter notebook。
+## 何时使用
+
+- 编辑或分析前，读取已知路径的源文件
+- 查看配置文件、锁文件、日志或生成产物
+- 查看用户在对话中粘贴的截图或图表
+- 从长篇 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`，可检索一个窄窗口而不浪费上下文 token。
 
-**适合使用：**
-- 读取代码文件、配置文件等文本文件
-- 查看图片文件（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/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/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/Tool-SendMessage.md

@@ -1,41 +1,68 @@
 # SendMessage
 
-## 定义
+在一个活跃团队内从一名成员向另一名成员发送消息，或一次性广播给所有队友。这是队友能听到的唯一通道——写入普通文本输出的内容对他们不可见。
 
-在团队内的 agent 之间发送消息。用于直接通信、广播以及协议消息（关闭请求/响应、计划审批）。
+## 何时使用
+
+- 在团队协作中，向具名队友分配任务或移交子问题。
+- 向其他代理请求状态、阶段性发现或代码评审。
+- 通过 `*` 向整个团队广播决策、共享约束或关停通告。
+- 回复协议提示，例如团队负责人的关停请求或计划审批请求。
+- 在完成被委派的任务时收尾，让负责人可以把事项标记为完成。
 
 ## 参数
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `to` | string | 是 | 接收方：队友名称，或 `"*"` 广播给所有人 |
-| `message` | string / object | 是 | 纯文本消息或结构化协议对象 |
-| `summary` | string | 否 | 在 UI 中显示的 5-10 字预览 |
+- `to` (string, 必填)：目标队友在团队中注册的 `name`，或用 `*` 向所有队友广播。
+- `message` (string or 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` 能让负责人扫读团队活动日志时一目了然——把它当作提交说明的标题行。

package/concepts/zh/Tool-Skill.md

@@ -1,56 +1,47 @@
 # Skill
 
-## 定义
+在当前对话内调用具名的 skill。Skill 是预打包的能力组合——领域知识、工作流、有时还包含工具权限——由运行时通过系统提醒暴露给助手。
 
-在主对话中执行一个技能（skill）。技能是用户可通过 slash command（如 `/commit`、`/review-pr`）调用的专用能力。
+## 何时使用
 
-## 参数
+- 用户输入像 `/review` 或 `/init` 这样的斜杠命令——斜杠命令就是 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 的步骤。调用它会把运行时定义的审查流程加载到本轮中。
 
-## 原文
+### 示例 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` 插件的入口，触发创作工作流。
 
-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` 调用内置 CLI 命令如 `/help`、`/clear`、`/model` 或 `/exit`。那些由运行时直接处理。
+- 不要重复调用当前轮已在运行的 skill。如果你看到当前轮内有 `<command-name>` 标签，skill 已加载——请直接遵循其指令，而不是再次调用工具。
+- 若多个 skill 都可用，选择最具体的那个。对于添加权限或 hook 等配置改动，优先选 `update-config` 而非通用方式。
+- skill 执行可能在本轮剩余部分引入新的系统提醒、工具或约束。skill 完成后请重新阅读对话状态再继续。

package/concepts/zh/Tool-TaskCreate.md

@@ -1,78 +1,56 @@
 # 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 检查是否有重复任务
-
-## 原文
+对于简单的一次性动作、纯粹的对话，或两三次直接工具调用即可完成的任务，跳过 `TaskCreate`。
 
-<textarea readonly>Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
-It also helps the user understand the progress of the task and overall progress of their requests.
+## 参数
 
-## When to Use This Tool
+- `subject` (string, 必填)：简短的祈使式标题，例如 `Fix login redirect on Safari`。尽量不超过 80 字符。
+- `description` (string, 必填)：详细上下文——问题、约束、验收标准以及未来阅读者所需的文件或链接。写得像有队友会冷启动接手。
+- `activeForm` (string, 可选)：任务处于 `in_progress` 时展示的现在进行时 spinner 文本，例如 `Fixing login redirect on Safari`。与 `subject` 对应，但使用 -ing 形式。
+- `metadata` (object, 可选)：附加到任务的任意结构化数据。常见用途：标签、优先级提示、外部工单 ID 或代理专用配置。
 
-Use this tool proactively in these scenarios:
+新建任务始终以状态 `pending`、无 owner 的形式开始。依赖（`blocks`、`blockedBy`）不在创建时设置——稍后通过 `TaskUpdate` 添加。
 
-- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
-- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
-- Plan mode - When using plan mode, create a task list to track the work
-- User explicitly requests todo list - When the user directly asks you to use the todo list
-- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
-- After receiving new instructions - Immediately capture user requirements as tasks
-- When you start working on a task - Mark it as in_progress BEFORE beginning work
-- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+## 示例
 
-## When NOT to Use This Tool
+### 示例 1
 
-Skip using this tool when:
-- There is only a single, straightforward task
-- The task is trivial and tracking it provides no organizational benefit
-- The task can be completed in less than 3 trivial steps
-- The task is purely conversational or informational
+捕获用户刚提交的 bug 报告。
 
-NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+```
+TaskCreate(
+  subject: "Repair broken PDF export on Windows",
+  description: "Users on Windows 11 report the export button produces a 0-byte file. Reproduce with sample doc in test/fixtures/export/, then fix the code path in src/export/pdf.ts. Acceptance: export writes a valid PDF and the existing export test suite passes.",
+  activeForm: "Repairing broken PDF export on Windows"
+)
+```
 
-## Task Fields
+### 示例 2
 
-- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
-- **description**: Detailed description of what needs to be done, including context and acceptance criteria
-- **activeForm**: Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.
+在会话开始时把 epic 拆成可跟踪的单元。
 
-**IMPORTANT**: Always provide activeForm when creating tasks. The subject should be imperative ("Run tests") while activeForm should be present continuous ("Running tests"). All tasks are created with status `pending`.
+```
+TaskCreate(
+  subject: "Draft migration plan for auth service",
+  description: "Produce a written plan covering rollout stages, rollback strategy, and monitoring. Output: docs/auth-migration.md.",
+  activeForm: "Drafting migration plan for auth service",
+  metadata: { "priority": "P1", "linearId": "AUTH-214" }
+)
+```
 
-## Tips
+## 注意事项
 
-- Create tasks with clear, specific subjects that describe the outcome
-- Include enough detail in the description for another agent to understand and complete the task
-- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
-- Check TaskList first to avoid creating duplicate tasks
-</textarea>
+- `subject` 用祈使语态写，`activeForm` 用现在进行时写，这样当任务切换到 `in_progress` 时 UI 读起来自然。
+- 创建前调用 `TaskList` 以避免重复——团队列表与队友和子代理共享。
+- 不要在 `description` 或 `metadata` 中包含密钥或凭证；任务记录对拥有团队访问权限的任何人可见。
+- 创建后通过 `TaskUpdate` 推进任务生命周期。不要让工作静默停留在 `in_progress`。