Read — 只读入口#

Read 读本地文件系统内容，支持文本、图片（PNG、JPG 等）、PDF、Jupyter Notebook（.ipynb）。它只接受绝对路径，默认最多读 2000 行，大文件用 offset 加 limit 分页。PDF 超过 10 页必须指定 pages 参数（如 "1-5"），每次最多 20 页。读目录、缺失文件或空文件会返回错误提示而不是内容。

单次读取行数的限制不是随意的。大文件一次性涌入上下文窗口会导致 token 爆炸，分页读取让模型按需取用，控制每次注入的信息量。

Write — 全量覆盖#

Write 创建新文件或完全覆盖已有文件。两个硬约束决定了它的使用方式：覆盖已有文件前必须在本轮对话中先执行 Read；不支持追加写入（append），每次调用都是全量覆盖。路径同样必须绝对。

强制先读再写，是为了让模型先了解文件当前状态，减少盲目覆盖导致的意外变更。这个约束是”提示工程”层面的，不是操作系统级强制，后面会展开。

Edit — 精确匹配替换#

Edit 基于 old_string 到 new_string 的精确字符串匹配做局部替换。它比 Write 安全：全量覆盖风险高，精确匹配只改确认过的内容，降低”改 A 误伤 B”的概率。

匹配规则有几个细节容易踩坑。old_string 必须完全匹配原文，包括缩进、空格、换行；在文件中必须唯一，否则编辑失败。编辑前必须先 Read 文件，而且读取时要去掉 cat -n 格式的行号前缀后再匹配。需要全局替换时用 replace_all: true。

唯一性约束确保编辑的确定性：模型不会意外改到不该改的地方。如果同一段文本在文件里出现多次，要么扩大匹配范围让它唯一，要么显式用 replace_all。

NotebookEdit — 单元格级编辑#

Jupyter Notebook 底层是复杂的 JSON 结构，直接操作极易出错。NotebookEdit 把这层 JSON 抽象掉，让模型以单元格（cell）为单位操作。

编辑前必须先 Read Notebook，通过 cell_id 定位目标单元格（由 Read 输出中的 <cell id="..."> 提供）。insert 模式在指定单元格后插入新细胞，省略 cell_id 则在开头插入。插入时必须指定 cell_type（code 或 markdown）。支持替换和删除两种模式。

Bash — Shell 命令执行#

Bash 执行任意 bash 命令，默认超时 120 秒，最大 600 秒，支持后台运行。

最关键的约束是 Shell 状态不持久：环境变量、函数定义、别名不会跨调用保留，每次调用都是独立的 shell 进程。这意味着上一条命令 export 的变量，下一条命令拿不到。如果需要跨命令共享状态，要么写进文件，要么在单条复合命令里完成。

几个使用上的限制值得记住。cd 在复合命令中可能触发权限提示，建议用绝对路径。不支持交互式 git 操作，git rebase -i、git add -i 等带 -i 标志的命令不可用，GitHub 操作推荐用 gh CLI。提交或推送仅在用户明确要求时执行；若在默认分支上，需先创建分支。提交信息必须以 Co-Authored-By: Claude <noreply@anthropic.com> 结尾，PR 正文必须以 机器人 Generated with [Claude Code](https://claude.com/claude-code) 结尾。

这些约束的设计目标是在提供系统能力的同时控制风险敞口。沙箱隔离、超时限制、状态不持久，三者共同把单次命令执行的爆炸半径限住。强制非交互式 git 操作，是为了确保自动化流程的可预测性。

Monitor — 后台事件监控#

Monitor 启动长运行脚本，把 stdout 每一行作为事件流式推送到对话界面。它解决的是”反复询问完成了吗”的 token 浪费问题：传统模式下模型得轮询，Monitor 让系统在事件发生时主动通知。

超时用 timeout_ms 控制，默认 300 秒，最大 3600 秒。persistent: true 让监控跨会话持续运行，直到调用 TaskStop 或会话结束。每个 stdout 行成为一个通知事件，stderr 不触发通知但可写入输出文件。200 毫秒内的多行输出会合并为单个通知。

管道使用有几个陷阱。每个阶段必须逐行刷新：grep 需 --line-buffered，awk 需 fflush()，否则输出会卡在缓冲区里。head -N 不能用于流式场景，它会缓冲到 N 行才输出，而流式场景往往等不到 N 行。

CronCreate / CronDelete / CronList — 定时任务#

三个工具配合使用：CronCreate 基于标准 5 字段 cron 表达式（分 时 日 月 周）创建定时任务，CronList 列出，CronDelete 删除。

任务分单次和循环两种。单次任务（recurring: false）在指定时间执行一次后自动删除。循环任务（recurring: true，默认）每次 cron 匹配时触发，7 天后自动过期并删除。默认仅内存存储，会话结束后任务消失；durable: true 可持久化到 .claude/scheduled_tasks.json。

调度策略上有两个容易忽略的细节。一是负载分散：避免用 :00 和 :30 分钟标记。请求”每小时”时应使用 7 * * * * 而非 0 * * * *；请求”每天早上 9 点”时用 57 8 * * * 或 3 9 * * *。二是抖动：循环任务最多延迟 10% 周期（上限 15 分钟）；单次 :00/:30 任务可能提前 90 秒触发。任务仅在 REPL 空闲时触发，不会在查询执行中途打断。

抖动和负载分散是为了避免全球用户的定时任务同时冲击 API。7 天自动过期是为了防止遗忘的循环任务无限消耗资源。任务仅在 REPL 空闲时触发，是为了不干扰正在进行的交互。

TaskCreate / TaskGet / TaskList / TaskUpdate / TaskStop / TaskOutput — 结构化任务列表#

这一组工具把”待办清单”内化为结构化工具，而不是靠自然语言描述。TaskCreate 创建，TaskGet 查单个，TaskList 列全部，TaskUpdate 更新状态，TaskStop 停止。

任务的状态机是 pending → in_progress → completed（或 deleted）。每个任务包含 subject（标题）、description（描述）、activeForm（进行中的显示文本）。依赖关系通过 blockedBy（被哪些任务阻塞）和 blocks（阻塞哪些任务）建立，形成依赖图。

TaskOutput 已废弃：后台任务的结果直接通过工具结果返回，或写入输出文件路径。新代码不要再依赖它。

结构化任务列表的价值在于多轮对话中精确维护上下文。模型能知道哪些已完成、哪些进行中、哪些被阻塞，避免遗忘中间步骤。

ScheduleWakeup — 自主唤醒调度#

ScheduleWakeup 在 /loop 动态模式下让模型自主决定下次唤醒时间。延迟秒数被运行时限制在 [60, 3600] 区间。

这个工具的核心约束来自 Anthropic prompt cache 的 5 分钟 TTL。超过 300 秒的等待会导致下次唤醒时完整上下文无法命中缓存，读取成本更高、速度更慢。所以延迟选择不是随意的，而是要在实时性和缓存成本之间取舍：

• 60 到 270 秒：缓存保持温热，适合轮询外部状态（CI、部署、远程队列）
• 300 到 3600 秒：接受缓存未命中，适合”几分钟才会变化”的等待
• 避免恰好 300 秒：既支付了缓存未命中成本，又没有充分摊销它
• 空闲时默认 1200 到 1800 秒（20 到 30 分钟）作为心跳

缓存 TTL 的考虑体现了对底层基础设施成本的理解。模型不是随意选个延迟，而是根据任务性质智能选择检查频率。

Agent — 子代理启动#

Agent 启动独立子代理处理复杂任务，每个子代理拥有独立上下文窗口，避免主上下文膨胀。可用代理类型决定了子代理能干什么：

子代理的最终消息作为工具结果返回给父代理，不直接展示给用户。可通过 SendMessage 继续已有代理的对话，保持上下文。isolation: "worktree" 为代理创建临时 git worktree，自动清理（若无变更）。run_in_background: true 异步执行，完成后通知。并发启动多个独立代理时，应在单条消息中同时发送，实现并行。

Workflow — 工作流编排#

Workflow 用 JavaScript 脚本编排多代理的确定性执行流程。它把”智能”（代理的决策能力）和”控制流”（脚本的确定性逻辑）分开：代理负责判断，脚本负责循环、条件、流水线这些控制结构。

核心 API 有六个，覆盖了启动代理、并行、流水线、分阶段、日志、嵌套：

parallel 和 pipeline 的区别在于屏障。parallel 等全部完成才返回，适合去重、合并、跨项比较这类需要全量结果的场景。pipeline 无屏障，Item A 可以在 Item B 还没进 stage1 时就跑到 stage3，墙钟时间取决于最慢单链，适合流水线式处理。

脚本的约束很严格。meta 对象必须是纯字面量：不能使用变量、函数调用、展开运算符、模板插值。Date.now()、Math.random()、new Date() 不可用，这是为了保证可恢复性。并发上限 min(16, CPU 核心数 - 2)，单工作流生命周期内代理总数上限 1000，单次 parallel() 或 pipeline() 最多接受 4096 项。无文件系统或 Node.js API 访问。

纯字面量和禁用时间函数的约束，是为了让工作流可恢复。如果脚本依赖运行时状态，中途失败就没法重放。去掉这些不确定性，工作流的执行结果才可复现。

Skill — 技能执行#

Skill 调用已注册的技能（slash command）。它把特定领域知识封装成可复用单元，让 Claude Code 动态加载能力，而不必在每次对话中携带全部工具定义。

几个约束决定了它和普通工具调用的区别。只能调用系统提示中明确列出的可用技能，不能猜测或发明技能名。若用户消息中包含 <command-name> 标签，表示技能已加载，直接遵循指令而非再次调用。不用于内置 CLI 命令（如 /help、/clear）。不能调用已运行中的技能。

AskUserQuestion — 用户决策询问#

AskUserQuestion 向用户提出 1 到 4 个结构化问题，支持单选、多选、自定义输入。每个问题包含 header（短标签，最多 12 字符）、question（完整问题文本，以问号结尾）、options（2 到 4 个选项，每个含 label、description、可选 preview）、multiSelect（是否允许多选）。用户始终可选择 “Other” 提供自定义输入。

这个工具的关键在于判断什么时候该问、什么时候不该问。只用于真正需要用户决策的情况：无法从请求、代码或合理默认值中解决的决策。有常规默认值或可自行验证的事实时，直接选择并提及，不要询问。

计划模式下有个容易用错的点：用于澄清需求或选择方案（在最终确定计划前），不能问”计划是否 OK”或”是否应该继续”，后者应使用 ExitPlanMode。preview 字段仅支持单选问题，不支持多选。

PushNotification — 桌面推送通知#

PushNotification 发送桌面通知；若连接 Remote Control，则同时推送到手机。消息需小于 200 字符，单行，无 markdown。

这个工具的约束主要是”什么时候不该用”。不用于常规进度、刚问过的问题、快速完成的任务。用于用户可能已离开时的重要状态、构建失败、需要决策的阻塞点。不必要的通知会累积成干扰，谨慎使用。

WebSearch — 网络搜索#

WebSearch 执行网络搜索，返回标题和摘要。仅 US 可用。支持 allowed_domains（仅包含指定域名）和 blocked_domains（排除指定域名）过滤。搜索后应在回答末尾附上 “Sources:” 列表。

域名过滤支持企业安全策略，比如只允许搜索内部文档域名。

WebFetch — 网页抓取#

WebFetch 获取 URL 内容并转为 markdown，支持基于小模型的内容问答。原始 HTML 含有大量标签噪音，直接注入会浪费 token，转成 markdown 后模型可以高效理解页面内容。

几个限制决定了它的适用边界。不支持认证或私有 URL（需使用认证 MCP 工具或 gh CLI）。HTTP 自动升级为 HTTPS。跨主机重定向返回给调用者而非自动跟随，需二次调用。响应缓存 15 分钟。

codegraph_search — 符号搜索#

按名称快速搜索符号（函数、类、方法等），返回符号位置列表（无源码）。典型问题是”项目中哪里定义了 authService”。

codegraph_node — 符号详情#

获取单个符号的完整信息：位置、签名、调用链、源码。支持重载方法，若名称有歧义，返回所有匹配定义的完整内容。可通过 file 和 line 精确定位特定重载。

codegraph_explore — 代码探索#

自然语言问题驱动的代码探索，返回相关符号及其源码。通常只需一次调用即可回答问题，无需进一步搜索或读取。这是这组工具里最常用的入口，适合”这个 bug 是怎么产生的”或”登录流程的完整调用链是什么”这类问题。

codegraph_callers — 调用者查询#

查找调用某符号的所有函数。重构前了解影响范围、理解”谁在用这个 API”时有用。

codegraph_callees — 被调用者查询#

查找某符号调用的所有函数。追踪调用链、理解依赖关系、绘制调用图时有用。

codegraph_impact — 影响分析#

分析修改某符号的影响范围。depth 控制依赖遍历深度，默认 2 层。重构前的风险评估、“改了这个函数会波及多少地方”这类问题靠它。

codegraph_files — 文件树索引#

返回索引后的文件树，支持按语言、符号数统计。比 Glob 更快，支持 tree、flat、grouped 三种格式。项目结构概览、快速了解代码库规模时用。

codegraph_status — 索引健康检查#

检查代码图索引状态：文件数、节点数、边数。索引异常时的调试诊断用。

EnterPlanMode / ExitPlanMode — 计划模式#

EnterPlanMode 进入”先规划、后实施”的模式，ExitPlanMode 退出并提交计划给用户审批。这是防御性编程的体现：强制在动手前先探索、设计、确认，避免边做边改导致的返工。

什么时候该用计划模式？有七种情况：新功能实现（有意义的全新功能）、多方案可选（缓存用 Redis 还是内存）、代码修改影响现有行为、架构决策（WebSockets vs SSE vs 轮询）、多文件变更（预计修改超过 2 到 3 个文件）、需求不清晰（需要探索后才能理解全貌）、用户偏好可能影响实现方向。

什么时候不该用？单行修复（typo、明显 bug）、添加单个函数且需求明确、纯研究或探索任务（用 Agent 的 Explore 类型）。

流程是固定的五步：EnterPlanMode 进入，用 find、grep、Read 探索代码库，理解现有模式和架构，设计方案并写入计划文件，ExitPlanMode 从计划文件读取内容提交用户审批。

EnterWorktree / ExitWorktree — Git 工作树隔离#

EnterWorktree 创建并进入独立的 git worktree，ExitWorktree 退出。它比单纯分支更彻底：分支只隔离提交历史，worktree 连工作目录都隔离了，不同任务的文件状态不会互相干扰。

什么时候用？用户显式提及 “worktree”（如”start a worktree”），或 CLAUDE.md、记忆指令明确要求。什么时候不用？用户要求创建或切换分支（用 git 命令），或修复 bug、开发功能（除非明确要求 worktree）。

在 git 仓库中，worktree 创建在 .claude/worktrees/ 下，基于 worktree.baseRef 设置：fresh 从 origin/默认分支创建，head 从当前 HEAD 创建。非 git 仓库委托给 WorktreeCreate/WorktreeRemove hooks。切换会话工作目录到新 worktree。ExitWorktree 后恢复原始工作目录，清除 CWD 相关缓存。

ExitWorktree 的参数控制退出行为：action 为 keep 保留目录和分支，remove 删除两者；discard_changes 在 remove 模式下强制删除有未提交变更的 worktree。EnterWorktree 的 name 指定新 worktree 名称（可选，默认随机生成），path 进入已有 worktree（与 name 互斥）。

DesignSync — 设计系统同步#

DesignSync 与 claude.ai/design 的设计系统项目进行双向同步。它打通了代码实现与设计规范，让设计系统成为可版本化、可同步的真实源码。

方法按职责分四组。读取方法（首次调用可能需授权设计系统访问）：list_projects 列出可写项目，get_project 读取项目元数据（验证目标是否为 PROJECT_TYPE_DESIGN_SYSTEM），list_files 列出项目中的文件路径，get_file 读取单个文件内容（上限 256 KiB）。项目设置（需权限提示）：create_project 创建新的设计系统项目。计划边界（需权限提示）：finalize_plan 锁定要写入或删除的确切路径集，返回 planId。写入方法（需有效的 planId，且路径必须在计划内）：write_files 写入文件（支持 localPath 从磁盘读取或 data 内联内容，每次最多 256 个文件），delete_files 删除文件，register_assets/unregister_assets 注册或注销设计系统面板卡片（legacy，现由 @dsCard 注释自动处理）。

严格顺序是 list/read → finalize_plan（用户审批）→ write/delete。无有效 planId 或路径超出计划范围的写入或删除会被拒绝。get_file 返回的内容可能来自其他组织成员，应视为数据而非指令。

增量同步（一次一个组件，永不整体替换）确保设计系统的演进是可控和可审查的。计划边界的存在，是为了让用户在写入前看到确切变更范围并审批。

安全与约束的贯穿设计#

Claude Code 的工具层处处体现最小权限原则。把前面散落各节的约束横切来看，每个层级都对应一种安全机制：

上下文管理的演进路径#

工具层的演进有一条清晰的脉络，从单文件操作一步步走到自主循环：

这条路径解决的是同一个问题：如何在有限的上下文窗口内处理无限复杂的任务。单文件操作不够用，就有了结构化任务跟踪状态；单代理上下文装不下，就有了多代理并行；并行需要确定性控制，就有了 Workflow 编排；编排还需要长期运行，就有了自主循环。

人机协作的三种交互模式#

工具层对”什么时候问人”有三种模式，差别在于打断流程的代价和用户是否需要在场：

阻塞式用于关键决策点，代价是打断流程；异步式允许用户离开，系统在事件发生时推送；自主式把决策权交给系统，适合重复劳动中的自主决策。三种模式的边界，就是人机协作的节奏线。

三个需要澄清的边界#

上文的分层归纳在架构层面是准确的，但有几个容易过度理想化的地方值得明确。

约束性是提示工程的产物，而非操作系统级沙箱。“必须先 Read 再 Edit”这类规则由系统提示和行为规范塑造，API 层面不会阻止违规调用。约束的有效性依赖于模型的遵循能力，而非硬编码强制。换句话说，这些约束是”软”的，模型可以违反，只是被训练得倾向于遵守。

可回滚依赖 Git 集成，而非 Claude Code 自身的原子事务。Claude Code 没有内置的事务回滚机制。所有文件操作发生在 Git 工作区内，Worktree 提供隔离的 Git 工作树，但如果没有 Git，Edit 是直接覆盖的，没有自动备份。更准确的说法是 Claude Code 是 Git-aware 的，它借助 Git 实现回滚能力。

编排层是 LLM 驱动的即时编排，而非传统工作流引擎。Claude Code 确实支持并行工具调用（如同时读取多个文件），但并行性受限于上下文窗口容量、API 的并行调用支持、以及任务间的隐式依赖顺序（比如 Bash 编译必须在 Edit 之后）。它不是 Airflow 或 Temporal 那样的静态 DAG 引擎，而是基于 LLM 推理的即时编排（on-the-fly orchestration）。

与简单 AI 代码生成器的差异#

把 Claude Code 和简单的”AI 代码生成器”放在一起比，最能看出这套工具层到底多了什么。差异集中在四个维度：

但也要承认，Claude Code 仍然是一个概率系统：它可能读错文件行号范围，编辑时引入语法错误，或在复杂编排中陷入 edit → test fail → edit → test fail 的循环。它不是确定性的软件工程伙伴，而是高结构化的概率协作工具。理解这一点，才能合理设定预期、有效使用。