mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 22:05:50 +00:00
83f56ed425
移除 TypeScript 类型定义、源码路径和 buildTool 代码， 聚焦统一接口的设计洞察（动态描述、校验-权限分离、 渲染一等公民）、分层注册策略和调用链路的错误处理设计。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
131 lines
5.7 KiB
Plaintext
131 lines
5.7 KiB
Plaintext
---
|
||
title: "工具系统"
|
||
description: "AI 本质上只能生成文本。工具是 AI 的双手——让它能读文件、跑命令、搜代码。理解统一接口、分层注册和调用链路的设计。"
|
||
keywords: ["工具系统", "Tool 抽象", "AI 工具", "function calling"]
|
||
---
|
||
|
||
## 核心问题
|
||
|
||
大语言模型本质上只能做一件事：**根据输入文本，生成输出文本**。
|
||
|
||
它不能读文件、不能执行命令、不能搜索代码。要让 AI 真正"动手"，需要一个桥梁——这就是 **Tool**（工具）。
|
||
|
||
工具是 AI 的双手。AI 说"我想读这个文件"，工具系统替它真正去读；AI 说"我想执行这条命令"，工具系统替它真正去跑。
|
||
|
||
## 统一接口：一个工具长什么样
|
||
|
||
所有工具——无论是读文件、执行命令还是启动子 Agent——都实现同一个接口。这不是一个类，而是一个结构化类型：任何满足该接口的对象就是一个工具。
|
||
|
||
### 核心四要素
|
||
|
||
| 要素 | 作用 |
|
||
|------|------|
|
||
| **name** | 唯一标识（如 `Read`、`Bash`、`Agent`） |
|
||
| **description()** | 动态描述——根据输入参数返回不同描述 |
|
||
| **inputSchema** | 参数类型和校验规则（Zod schema） |
|
||
| **call()** | 执行函数——真正做事的地方 |
|
||
|
||
**设计洞察**：`description()` 是动态的而非静态字符串。这意味着同一个工具在不同参数下可以展示不同的描述——例如 Agent 工具会显示它正在执行的具体子任务。
|
||
|
||
### 安全层字段
|
||
|
||
工具接口包含了完整的安全控制：
|
||
|
||
- **validateInput()** — 输入校验（在权限检查之前）
|
||
- **checkPermissions()** — 权限检查（在校验之后）
|
||
- **isReadOnly()** — 是否只读（影响权限模式的自动审批）
|
||
- **isDestructive()** — 是否不可逆（触发更严格的确认）
|
||
- **interruptBehavior()** — 用户中断时的行为（取消 vs 阻塞）
|
||
|
||
**设计考量**：校验和权限是两个独立步骤，有明确的执行顺序。校验先于权限——如果输入本身不合法，就不需要检查权限。这避免了在无效输入上触发权限 UI 的尴尬体验。
|
||
|
||
### 渲染字段
|
||
|
||
每个工具不仅有执行逻辑，还有 UI 渲染：
|
||
- 工具调用时的进度展示
|
||
- 工具结果的内容渲染
|
||
- 活动描述（为 spinner 提供文字，如 "Reading src/foo.ts"）
|
||
|
||
**设计哲学**：工具不是黑盒。用户应该实时看到 AI 正在做什么、结果是什么。渲染与执行是同一接口的一等公民。
|
||
|
||
## 工具注册：分层组装
|
||
|
||
工具不是一次性全部加载的。系统使用分层注册策略：
|
||
|
||
### 固定工具（始终可用）
|
||
|
||
文件操作（Read/Write/Edit）、命令执行（Bash）、搜索（Glob/Grep）、Web（Fetch/Search）等基础工具始终在工具列表中。
|
||
|
||
### 条件工具（运行时检查）
|
||
|
||
| 条件 | 加载的工具 |
|
||
|------|-----------|
|
||
| 需要搜索能力 | GlobTool、GrepTool |
|
||
| 平台是 Windows | PowerShellTool |
|
||
| Worktree 模式 | EnterWorktree/ExitWorktree |
|
||
| Agent Swarms 启用 | Teams 相关工具 |
|
||
|
||
### Feature-flag 工具
|
||
|
||
通过 feature flag 控制的实验性工具——协调者模式工具、KAIROS 工具等。
|
||
|
||
**关键设计**：工具列表在每次 API 调用时重新组装，而非全局缓存。因为 `isEnabled()` 的结果可能随运行时状态变化——例如 MCP 服务器在会话中途连接或断开。
|
||
|
||
## 工具调用链路
|
||
|
||
从 AI 发出调用到结果回传，经过一条严格的管道：
|
||
|
||
```
|
||
API 返回 tool_use → 输入校验 → 权限检查 → 执行 → 结果格式化 → 回传 API
|
||
```
|
||
|
||
每一步都有明确的失败路径：
|
||
- 校验失败 → 返回错误，AI 可以修正参数重试
|
||
- 权限拒绝 → 返回拒绝原因，AI 可以调整方案
|
||
- 执行出错 → 返回错误信息，AI 可以诊断重试
|
||
|
||
**设计考量**：错误不是异常——它们是正常的对话流程。AI 看到错误信息后会自行调整，不需要人类介入。这把"AI 犯错 → 人类纠正"的循环转变为"AI 试错 → 自我纠正"的循环。
|
||
|
||
## 工具结果的预算控制
|
||
|
||
每个工具声明自己的输出上限（BashTool: 30K 字符，SkillTool: 100K 等）。超出上限的结果被持久化到磁盘，AI 只收到预览 + 文件路径。
|
||
|
||
**为什么不无限返回**？因为工具输出的 token 会累积到上下文中。一个 `find /` 命令可能产生几十万字符的输出——如果不限制，几次工具调用就能耗尽整个上下文窗口。
|
||
|
||
FileReadTool 故意设为无上限——文件内容需要完整呈现给 AI，截断可能导致错误的代码修改。
|
||
|
||
## MCP 工具的扩展
|
||
|
||
MCP（Model Context Protocol）允许外部工具注册到系统中。MCP 工具的 schema 使用 JSON Schema 而非 Zod，因为 schema 来自远程协议而非本地定义。
|
||
|
||
MCP 工具支持 `mcp__server` 前缀的 deny 规则——用户可以精确控制哪些 MCP 服务器的哪些工具被禁止使用。
|
||
|
||
## 50+ 内置工具全景
|
||
|
||
<CardGroup cols={3}>
|
||
<Card title="文件操作" icon="file">
|
||
Read / Write / Edit / Glob / Grep / NotebookEdit
|
||
</Card>
|
||
<Card title="命令执行" icon="terminal">
|
||
Bash / PowerShell
|
||
</Card>
|
||
<Card title="对话管理" icon="comments">
|
||
Agent / SendMessage / AskUserQuestion
|
||
</Card>
|
||
<Card title="任务追踪" icon="list-check">
|
||
TaskCreate / TaskUpdate / TaskList / TaskGet / TaskOutput / TaskStop
|
||
</Card>
|
||
<Card title="Web 能力" icon="globe">
|
||
WebFetch / WebSearch / WebBrowser
|
||
</Card>
|
||
<Card title="规划与版本" icon="map">
|
||
EnterPlanMode / ExitPlanMode / Worktree / TodoWrite / ToolSearch
|
||
</Card>
|
||
</CardGroup>
|
||
|
||
## 接下来
|
||
|
||
- **文件操作** — Read/Write/Edit 的设计和安全机制
|
||
- **搜索与导航** — Glob/Grep 的搜索策略
|
||
- **Shell 执行** — Bash 的沙箱和超时控制
|