cc-viewer 1.2.0 → 1.2.2

package/concepts/zh/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## 定义
+
+执行 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）初始化
+
+## 在 cc-viewer 中的意义
+
+Bash 调用在请求日志中表现为 `tool_use`（包含命令）和 `tool_result`（包含输出）content block 对。命令执行的输出可用于分析模型的操作行为。

package/concepts/zh/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## 定义
+
+通过精确的字符串替换来编辑文件。将文件中的 `old_string` 替换为 `new_string`。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_path` | string | 是 | 要修改的文件的绝对路径 |
+| `old_string` | string | 是 | 要替换的原始文本 |
+| `new_string` | string | 是 | 替换后的新文本（必须与 old_string 不同） |
+| `replace_all` | boolean | 否 | 是否替换所有匹配项，默认 `false` |
+
+## 使用场景
+
+**适合使用：**
+- 修改现有文件中的特定代码段
+- 修复 bug、更新逻辑
+- 重命名变量（配合 `replace_all: true`）
+- 任何需要精确修改文件内容的场景
+
+**不适合使用：**
+- 创建新文件——应使用 Write
+- 大规模重写——可能需要 Write 覆盖整个文件
+
+## 注意事项
+
+- 使用前必须先通过 Read 读取过该文件，否则会报错
+- `old_string` 在文件中必须是唯一的，否则编辑失败。如果不唯一，需要提供更多上下文使其唯一，或使用 `replace_all`
+- 编辑文本时必须保持原始缩进（tab/空格），不要包含 Read 输出中的行号前缀
+- 优先编辑现有文件，而非创建新文件
+- `new_string` 必须与 `old_string` 不同
+
+## 在 cc-viewer 中的意义
+
+Edit 调用在请求日志中表现为 `tool_use` content block，其 `input` 包含 `old_string` 和 `new_string`，可用于追踪模型对文件做了哪些修改。

package/concepts/zh/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## 定义
+
+将 Claude Code 切换到规划模式，用于在实施前探索代码库并设计方案。
+
+## 参数
+
+无参数。
+
+## 使用场景
+
+**适合使用：**
+- 新功能实现——需要架构决策
+- 存在多种可行方案——需要用户选择
+- 代码修改影响现有行为或结构
+- 多文件变更——可能涉及 2-3 个以上文件
+- 需求不明确——需要先探索再理解范围
+- 用户偏好很重要——实现可以有多种合理方向
+
+**不适合使用：**
+- 单行或少量行的修复（拼写错误、明显 bug）
+- 用户已给出非常具体的指令
+- 纯研究/探索任务——应使用 Task（Explore 类型）
+
+## 规划模式中的行为
+
+进入规划模式后，Claude Code 会：
+1. 使用 Glob、Grep、Read 工具深入探索代码库
+2. 理解现有模式和架构
+3. 设计实施方案
+4. 将方案提交给用户审批
+5. 如需澄清可使用 AskUserQuestion
+6. 方案就绪后通过 ExitPlanMode 退出
+
+## 注意事项
+
+- 此工具需要用户同意才能进入规划模式
+- 如果不确定是否需要规划，倾向于规划——提前对齐比返工好
+
+## 在 cc-viewer 中的意义
+
+EnterPlanMode 调用在请求日志中表现为 `tool_use` content block。进入规划模式后的请求序列通常以探索性工具调用（Glob、Grep、Read）为主，直到 ExitPlanMode 被调用。

package/concepts/zh/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## 定义
+
+退出规划模式并将方案提交给用户审批。方案内容从之前写入的计划文件中读取。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `allowedPrompts` | array | 否 | 实施方案所需的权限描述列表 |
+
+`allowedPrompts` 数组中每个元素：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tool` | enum | 是 | 适用的工具，目前仅支持 `Bash` |
+| `prompt` | string | 是 | 操作的语义描述（如 "run tests"、"install dependencies"） |
+
+## 使用场景
+
+**适合使用：**
+- 规划模式中方案已完成，准备提交用户审批
+- 仅用于需要编写代码的实施任务
+
+**不适合使用：**
+- 纯研究/探索任务——不需要退出规划模式
+- 想问用户"方案可以吗？"——这正是此工具的功能，不要用 AskUserQuestion 来问
+
+## 注意事项
+
+- 此工具不接受方案内容作为参数——它从之前写入的计划文件中读取
+- 用户会看到计划文件的内容来审批
+- 不要在调用此工具前用 AskUserQuestion 问"方案是否可以"，这是重复的
+- 不要在问题中提及"计划"，因为用户在 ExitPlanMode 之前看不到计划内容
+
+## 在 cc-viewer 中的意义
+
+ExitPlanMode 调用标志着规划阶段的结束。在请求日志中，此调用之后的请求通常转为实施性操作（Edit、Write、Bash 等）。

package/concepts/zh/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## 定义
+
+快速的文件名模式匹配工具，支持任意规模的代码库。返回按修改时间排序的匹配文件路径。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pattern` | string | 是 | glob 模式（如 `**/*.js`、`src/**/*.ts`） |
+| `path` | string | 否 | 搜索目录，默认为当前工作目录。不要传 "undefined" 或 "null" |
+
+## 使用场景
+
+**适合使用：**
+- 按文件名模式查找文件
+- 查找特定类型的所有文件（如所有 `.tsx` 文件）
+- 查找特定类定义（如 `class Foo`）时先定位文件
+- 可以在单条消息中并行发起多个 Glob 调用
+
+**不适合使用：**
+- 搜索文件内容——应使用 Grep
+- 需要多轮搜索的开放式探索——应使用 Task（Explore 类型）
+
+## 注意事项
+
+- 支持标准 glob 语法：`*` 匹配单层，`**` 匹配多层，`{}` 匹配多选
+- 结果按修改时间排序
+- 比 Bash 的 `find` 命令更推荐使用
+
+## 在 cc-viewer 中的意义
+
+Glob 调用在请求日志中表现为 `tool_use` / `tool_result` content block 对。`tool_result` 包含匹配的文件路径列表。

package/concepts/zh/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## 定义
+
+基于 ripgrep 的强大内容搜索工具。支持正则表达式、文件类型过滤和多种输出模式。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `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 类型）
+
+## 注意事项
+
+- 使用 ripgrep 语法（非 grep），花括号等特殊字符需要转义
+- `files_with_matches` 模式只返回文件路径，最高效
+- `content` 模式返回匹配行内容，支持上下文行
+- 多行匹配需要设置 `multiline: true`
+- 始终优先使用 Grep 工具而非 Bash 中的 `grep` 或 `rg` 命令
+
+## 在 cc-viewer 中的意义
+
+Grep 调用在请求日志中表现为 `tool_use` / `tool_result` content block 对。`tool_result` 包含搜索结果。

package/concepts/zh/Tool-NotebookEdit.md

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## 定义
+
+替换、插入或删除 Jupyter notebook（.ipynb 文件）中的特定单元格。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `notebook_path` | string | 是 | notebook 文件的绝对路径 |
+| `new_source` | string | 是 | 单元格的新内容 |
+| `cell_id` | string | 否 | 要编辑的单元格 ID。插入模式下新单元格插入到此 ID 之后 |
+| `cell_type` | enum | 否 | 单元格类型：`code` 或 `markdown`。插入模式下必填 |
+| `edit_mode` | enum | 否 | 编辑模式：`replace`（默认）、`insert`、`delete` |
+
+## 使用场景
+
+**适合使用：**
+- 修改 Jupyter notebook 中的代码或 markdown 单元格
+- 向 notebook 添加新单元格
+- 删除 notebook 中的单元格
+
+## 注意事项
+
+- `cell_number` 是 0 索引的
+- `insert` 模式在指定位置插入新单元格
+- `delete` 模式删除指定位置的单元格
+- 路径必须是绝对路径
+
+## 在 cc-viewer 中的意义
+
+NotebookEdit 调用在请求日志中表现为 `tool_use` content block，记录了对 notebook 的具体修改操作。

package/concepts/zh/Tool-Read.md

@@ -0,0 +1,41 @@
+# Read
+
+## 定义
+
+从本地文件系统读取文件内容。支持文本文件、图片、PDF 和 Jupyter notebook。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_path` | string | 是 | 文件的绝对路径 |
+| `offset` | number | 否 | 起始行号（用于大文件分段读取） |
+| `limit` | number | 否 | 读取行数（用于大文件分段读取） |
+| `pages` | string | 否 | PDF 页码范围（如 "1-5"、"3"、"10-20"），仅适用于 PDF |
+
+## 使用场景
+
+**适合使用：**
+- 读取代码文件、配置文件等文本文件
+- 查看图片文件（Claude 是多模态模型）
+- 读取 PDF 文档
+- 读取 Jupyter notebook（返回所有单元格及输出）
+- 并行读取多个文件以获取上下文
+
+**不适合使用：**
+- 读取目录——应使用 Bash 的 `ls` 命令
+- 开放式代码库探索——应使用 Task（Explore 类型）
+
+## 注意事项
+
+- 路径必须是绝对路径，不能是相对路径
+- 默认读取文件前 2000 行
+- 超过 2000 字符的行会被截断
+- 输出使用 `cat -n` 格式，行号从 1 开始
+- 大型 PDF（超过 10 页）必须指定 `pages` 参数，每次最多 20 页
+- 读取不存在的文件会返回错误（不会崩溃）
+- 可以在单条消息中并行调用多个 Read
+
+## 在 cc-viewer 中的意义
+
+Read 调用在请求日志中表现为 `tool_use`（调用）和 `tool_result`（返回内容）content block 对。`tool_result` 中包含文件的实际内容，可用于分析模型读取了哪些文件。

package/concepts/zh/Tool-Skill.md

@@ -0,0 +1,35 @@
+# Skill
+
+## 定义
+
+在主对话中执行一个技能（skill）。技能是用户可通过 slash command（如 `/commit`、`/review-pr`）调用的专用能力。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `skill` | string | 是 | 技能名称（如 "commit"、"review-pr"、"pdf"） |
+| `args` | string | 否 | 技能参数 |
+
+## 使用场景
+
+**适合使用：**
+- 用户输入了 `/<skill-name>` 格式的 slash command
+- 用户的请求匹配某个已注册技能的功能
+
+**不适合使用：**
+- 内置 CLI 命令（如 `/help`、`/clear`）
+- 已经在运行中的技能
+- 未在可用技能列表中的技能名称
+
+## 注意事项
+
+- 技能被调用后会展开为完整的 prompt
+- 支持完全限定名称（如 `ms-office-suite:pdf`）
+- 可用技能列表在 system-reminder 消息中提供
+- 看到 `<command-name>` 标签时说明技能已加载，应直接执行而非再次调用此工具
+- 不要在未实际调用工具的情况下提及某个技能
+
+## 在 cc-viewer 中的意义
+
+Skill 调用在请求日志中表现为 `tool_use` content block。技能展开后的 prompt 会影响后续请求的 system prompt 或消息内容。

package/concepts/zh/Tool-Task.md

@@ -0,0 +1,53 @@
+# Task
+
+## 定义
+
+启动一个子 agent（SubAgent）来自主处理复杂的多步骤任务。子 agent 是独立的子进程，拥有各自专用的工具集和上下文。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prompt` | string | 是 | 子 agent 要执行的任务描述 |
+| `description` | string | 是 | 3-5 个词的简短摘要 |
+| `subagent_type` | string | 是 | 子 agent 类型，决定可用工具集 |
+| `model` | enum | 否 | 指定模型（sonnet / opus / haiku），默认继承父级 |
+| `max_turns` | integer | 否 | 最大 agentic 轮次数 |
+| `run_in_background` | boolean | 否 | 是否后台运行，后台任务返回 output_file 路径 |
+| `resume` | string | 否 | 要恢复的 agent ID，从上次执行继续 |
+| `isolation` | enum | 否 | 隔离模式，`worktree` 创建临时 git worktree |
+
+## 子 agent 类型
+
+| 类型 | 用途 | 可用工具 |
+|------|------|----------|
+| `Bash` | 命令执行，git 操作 | Bash |
+| `general-purpose` | 通用多步骤任务 | 全部工具 |
+| `Explore` | 快速探索代码库 | 除 Task/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
+| `Plan` | 设计实施方案 | 除 Task/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
+| `claude-code-guide` | Claude Code 使用指南问答 | Glob, Grep, Read, WebFetch, WebSearch |
+| `statusline-setup` | 配置状态栏 | Read, Edit |
+
+## 使用场景
+
+**适合使用：**
+- 需要多步骤自主完成的复杂任务
+- 代码库探索和深度研究（使用 Explore 类型）
+- 需要隔离环境的并行工作
+- 需要后台运行的长时间任务
+
+**不适合使用：**
+- 读取特定文件路径——直接用 Read 或 Glob
+- 在 2-3 个已知文件中搜索——直接用 Read
+- 搜索特定类定义——直接用 Glob
+
+## 注意事项
+
+- 子 agent 完成后返回单条消息，其结果对用户不可见，需要主 agent 转述
+- 可以在单条消息中发起多个并行 Task 调用以提高效率
+- 后台任务通过 TaskOutput 工具检查进度
+- Explore 类型比直接调用 Glob/Grep 慢，仅在简单搜索不够时使用
+
+## 在 cc-viewer 中的意义
+
+Task 调用会产生 SubAgent 请求链路，在请求列表中可以看到独立于 MainAgent 的子请求序列。SubAgent 请求通常具有精简的 system prompt 和较少的工具定义，与 MainAgent 形成明显对比。

package/concepts/zh/Tool-TaskCreate.md

@@ -0,0 +1,38 @@
+# TaskCreate
+
+## 定义
+
+创建结构化的任务列表条目，用于跟踪进度、组织复杂任务，并向用户展示工作进展。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `subject` | string | 是 | 简短的任务标题，使用祈使句（如 "Fix authentication bug"） |
+| `description` | string | 是 | 详细描述，包含上下文和验收标准 |
+| `activeForm` | string | 否 | 进行中时显示的现在进行时文本（如 "Fixing authentication bug"） |
+| `metadata` | object | 否 | 附加到任务的任意元数据 |
+
+## 使用场景
+
+**适合使用：**
+- 复杂的多步骤任务（3 步以上）
+- 用户提供了多个待办事项
+- 在规划模式中跟踪工作
+- 用户明确要求使用 todo 列表
+
+**不适合使用：**
+- 单一简单任务
+- 3 步以内的简单操作
+- 纯对话或信息查询
+
+## 注意事项
+
+- 所有新建任务的初始状态为 `pending`
+- `subject` 使用祈使句（"Run tests"），`activeForm` 使用现在进行时（"Running tests"）
+- 创建任务后可通过 TaskUpdate 设置依赖关系（blocks/blockedBy）
+- 创建前应先调用 TaskList 检查是否有重复任务
+
+## 在 cc-viewer 中的意义
+
+TaskCreate 是 Claude Code 内部的任务管理操作，不产生独立的 API 请求。但在 Chat Mode 中可以看到模型调用此工具的 tool_use block。

package/concepts/zh/Tool-TaskGet.md

@@ -0,0 +1,35 @@
+# TaskGet
+
+## 定义
+
+通过任务 ID 获取任务的完整详情。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `taskId` | string | 是 | 要获取的任务 ID |
+
+## 返回内容
+
+- `subject` — 任务标题
+- `description` — 详细需求和上下文
+- `status` — 状态：`pending`、`in_progress` 或 `completed`
+- `blocks` — 被此任务阻塞的任务列表
+- `blockedBy` — 阻塞此任务的前置任务列表
+
+## 使用场景
+
+**适合使用：**
+- 开始工作前获取任务的完整描述和上下文
+- 了解任务的依赖关系
+- 被分配任务后获取完整需求
+
+## 注意事项
+
+- 获取任务后应检查 `blockedBy` 列表是否为空再开始工作
+- 使用 TaskList 查看所有任务的摘要信息
+
+## 在 cc-viewer 中的意义
+
+TaskGet 是内部任务管理操作，不产生独立的 API 请求。

package/concepts/zh/Tool-TaskList.md

@@ -0,0 +1,36 @@
+# TaskList
+
+## 定义
+
+列出任务列表中的所有任务，查看整体进度和可用工作。
+
+## 参数
+
+无参数。
+
+## 返回内容
+
+每个任务的摘要信息：
+- `id` — 任务标识符
+- `subject` — 简短描述
+- `status` — 状态：`pending`、`in_progress` 或 `completed`
+- `owner` — 负责人（agent ID），空表示未分配
+- `blockedBy` — 阻塞此任务的未完成任务 ID 列表
+
+## 使用场景
+
+**适合使用：**
+- 查看有哪些可用任务（状态为 pending、无 owner、未被阻塞）
+- 检查项目整体进度
+- 查找被阻塞的任务
+- 完成一个任务后查找下一个
+
+## 注意事项
+
+- 优先按 ID 顺序处理任务（最小 ID 优先），因为早期任务通常为后续任务提供上下文
+- 有 `blockedBy` 的任务在依赖解除前不能认领
+- 使用 TaskGet 获取特定任务的完整详情
+
+## 在 cc-viewer 中的意义
+
+TaskList 是内部任务管理操作，不产生独立的 API 请求。

package/concepts/zh/Tool-TaskOutput.md

@@ -0,0 +1,34 @@
+# TaskOutput
+
+## 定义
+
+获取正在运行或已完成的后台任务的输出。适用于后台 shell、异步 agent 和远程会话。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `task_id` | string | 是 | 任务 ID |
+| `block` | boolean | 是 | 是否阻塞等待任务完成，默认 `true` |
+| `timeout` | number | 是 | 最大等待时间（毫秒），默认 30000，最大 600000 |
+
+## 使用场景
+
+**适合使用：**
+- 检查通过 Task（`run_in_background: true`）启动的后台 agent 的进度
+- 获取后台 Bash 命令的执行结果
+- 等待异步任务完成并获取输出
+
+**不适合使用：**
+- 前台任务——前台任务直接返回结果，无需此工具
+
+## 注意事项
+
+- `block: true` 会阻塞直到任务完成或超时
+- `block: false` 用于非阻塞检查当前状态
+- 任务 ID 可通过 `/tasks` 命令查找
+- 适用于所有任务类型：后台 shell、异步 agent、远程会话
+
+## 在 cc-viewer 中的意义
+
+TaskOutput 调用本身不产生 API 请求，它是 Claude Code 内部的任务管理操作，不会出现在请求日志中。

package/concepts/zh/Tool-TaskStop.md

@@ -0,0 +1,27 @@
+# TaskStop
+
+## 定义
+
+停止一个正在运行的后台任务。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `task_id` | string | 否 | 要停止的后台任务 ID |
+| `shell_id` | string | 否 | 已弃用，使用 `task_id` 代替 |
+
+## 使用场景
+
+**适合使用：**
+- 终止不再需要的长时间运行任务
+- 取消错误启动的后台任务
+
+## 注意事项
+
+- 返回成功或失败状态
+- `shell_id` 参数已弃用，应使用 `task_id`
+
+## 在 cc-viewer 中的意义
+
+TaskStop 调用本身不产生 API 请求，属于 Claude Code 内部任务管理操作。

package/concepts/zh/Tool-TaskUpdate.md

@@ -0,0 +1,49 @@
+# TaskUpdate
+
+## 定义
+
+更新任务列表中某个任务的状态、内容或依赖关系。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `taskId` | string | 是 | 要更新的任务 ID |
+| `status` | enum | 否 | 新状态：`pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | 否 | 新标题 |
+| `description` | string | 否 | 新描述 |
+| `activeForm` | string | 否 | 进行中时显示的现在进行时文本 |
+| `owner` | string | 否 | 新的任务负责人（agent 名称） |
+| `metadata` | object | 否 | 要合并的元数据（设为 null 可删除键） |
+| `addBlocks` | string[] | 否 | 被此任务阻塞的任务 ID 列表 |
+| `addBlockedBy` | string[] | 否 | 阻塞此任务的前置任务 ID 列表 |
+
+## 状态流转
+
+```
+pending → in_progress → completed
+```
+
+`deleted` 可从任何状态转入，永久移除任务。
+
+## 使用场景
+
+**适合使用：**
+- 开始工作时标记任务为 `in_progress`
+- 完成工作后标记任务为 `completed`
+- 设置任务间的依赖关系
+- 需求变更时更新任务内容
+
+**重要规则：**
+- 只有在完全完成任务时才标记为 `completed`
+- 遇到错误或阻塞时保持 `in_progress`
+- 测试失败、实现不完整、遇到未解决错误时不得标记为 `completed`
+
+## 注意事项
+
+- 更新前应先通过 TaskGet 获取任务最新状态，避免过期数据
+- 完成任务后调用 TaskList 查找下一个可用任务
+
+## 在 cc-viewer 中的意义
+
+TaskUpdate 是内部任务管理操作，不产生独立的 API 请求。

package/concepts/zh/Tool-WebFetch.md

@@ -0,0 +1,36 @@
+# WebFetch
+
+## 定义
+
+抓取指定 URL 的网页内容，将 HTML 转换为 markdown，并使用 AI 模型根据 prompt 处理内容。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | string (URI) | 是 | 要抓取的完整 URL |
+| `prompt` | string | 是 | 描述要从页面中提取什么信息 |
+
+## 使用场景
+
+**适合使用：**
+- 获取公开网页的内容
+- 查阅在线文档
+- 提取网页中的特定信息
+
+**不适合使用：**
+- 需要认证的 URL（Google Docs、Confluence、Jira、GitHub 等）——应先查找专用的 MCP 工具
+- GitHub URL——优先使用 `gh` CLI
+
+## 注意事项
+
+- URL 必须是完整的有效 URL
+- HTTP 会自动升级为 HTTPS
+- 内容过大时结果可能被摘要
+- 包含 15 分钟自清理缓存
+- 当 URL 重定向到不同主机时，工具会返回重定向 URL，需要用新 URL 重新请求
+- 如果有 MCP 提供的 web fetch 工具可用，优先使用那个
+
+## 在 cc-viewer 中的意义
+
+WebFetch 调用在请求日志中表现为 `tool_use` / `tool_result` content block 对。`tool_result` 包含经 AI 处理后的网页内容摘要。