950 lines
21 KiB
Markdown
950 lines
21 KiB
Markdown
# 工具系统详解
|
||
|
||
本文件说明：详细介绍 Claude Code 的工具系统，包括所有内置工具的功能、输入 schema、权限模型和核心逻辑。
|
||
|
||
## 1. 工具系统架构
|
||
|
||
### 1.1 工具注册表
|
||
|
||
所有内置工具在 `tools.ts` 中注册：
|
||
|
||
```typescript
|
||
export function getAllBaseTools(): Tools {
|
||
return [
|
||
AgentTool,
|
||
TaskOutputTool,
|
||
BashTool,
|
||
GlobTool,
|
||
GrepTool,
|
||
ExitPlanModeV2Tool,
|
||
FileReadTool,
|
||
FileEditTool,
|
||
FileWriteTool,
|
||
NotebookEditTool,
|
||
WebFetchTool,
|
||
TodoWriteTool,
|
||
WebSearchTool,
|
||
TaskStopTool,
|
||
AskUserQuestionTool,
|
||
SkillTool,
|
||
EnterPlanModeTool,
|
||
// ... 更多工具
|
||
]
|
||
}
|
||
```
|
||
|
||
### 1.2 工具调用流程
|
||
|
||
```
|
||
用户输入/模型决策
|
||
│
|
||
▼
|
||
checkPermissions() ────► 权限检查
|
||
│
|
||
▼
|
||
validateInput() ────► 输入验证
|
||
│
|
||
▼
|
||
call() ───────────► 工具执行
|
||
│
|
||
▼
|
||
renderToolResultMessage() ────► 结果渲染
|
||
```
|
||
|
||
### 1.3 工具基类接口
|
||
|
||
所有工具都实现以下核心方法：
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `call(args, context, canUseTool, parentMessage)` | 工具执行入口 |
|
||
| `description(input, options)` | 获取工具描述 |
|
||
| `inputSchema` | 输入参数 Zod Schema |
|
||
| `checkPermissions(input, context)` | 权限检查 |
|
||
| `validateInput(input, context)` | 输入验证 |
|
||
| `renderToolUseMessage(input, options)` | 渲染工具调用消息 |
|
||
| `renderToolResultMessage(content, options)` | 渲染工具结果 |
|
||
|
||
## 2. BashTool - Shell 命令执行
|
||
|
||
### 2.1 功能描述
|
||
|
||
BashTool 是 Claude Code 最核心的工具之一，负责在用户授权下执行 Shell 命令。
|
||
|
||
### 2.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
command: z.string().describe('要执行的命令'),
|
||
cwd: z.string().optional().describe('工作目录'),
|
||
timeout: z.number().optional().describe('超时时间（毫秒）'),
|
||
})
|
||
```
|
||
|
||
### 2.3 权限模型
|
||
|
||
**权限检查规则**：
|
||
1. 检查命令是否匹配 `alwaysAllowRules`
|
||
2. 检查命令是否匹配 `alwaysDenyRules`
|
||
3. 检查命令是否属于危险命令（如 `rm -rf`）
|
||
4. 用户确认后执行
|
||
|
||
**危险命令警告**：
|
||
- `rm -rf` 类删除命令
|
||
- 格式化命令（如 `mkfs`）
|
||
- 覆盖系统文件
|
||
|
||
### 2.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ command, cwd, timeout }, context) {
|
||
// 1. 展开路径
|
||
const fullCommand = expandPath(command)
|
||
|
||
// 2. 权限检查
|
||
const decision = await checkBashPermission(fullCommand, context)
|
||
|
||
// 3. 决定是否使用沙箱
|
||
const shouldSandbox = await shouldUseSandbox(fullCommand)
|
||
|
||
// 4. 执行命令
|
||
if (shouldSandbox) {
|
||
return executeInSandbox(fullCommand, cwd, timeout)
|
||
} else {
|
||
return executeDirect(fullCommand, cwd, timeout)
|
||
}
|
||
|
||
// 5. 追踪文件变更
|
||
if (result.modifiedFiles) {
|
||
for (const file of result.modifiedFiles) {
|
||
updateFileHistory(file, 'modified')
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.5 沙箱执行
|
||
|
||
Claude Code 支持使用沙箱执行危险命令：
|
||
|
||
```typescript
|
||
async function shouldUseSandbox(command: string): Promise<boolean> {
|
||
// 检测命令是否危险
|
||
const isDangerous = detectDangerousCommand(command)
|
||
|
||
// 检查用户是否设置了沙箱偏好
|
||
const sandboxPreference = getSandboxPreference()
|
||
|
||
return isDangerous || sandboxPreference === 'always'
|
||
}
|
||
```
|
||
|
||
## 3. FileReadTool - 文件读取
|
||
|
||
### 3.1 功能描述
|
||
|
||
FileReadTool 用于读取文件内容，支持多种文件类型：
|
||
|
||
- 纯文本文件
|
||
- 图片文件（PNG, JPG, GIF, WebP）
|
||
- PDF 文档
|
||
- Jupyter Notebooks
|
||
|
||
### 3.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
file_path: z.string().describe('要读取的文件绝对路径'),
|
||
offset: z.number().int().nonnegative().optional().describe('起始行号'),
|
||
limit: z.number().int().positive().optional().describe('读取行数'),
|
||
pages: z.string().optional().describe('PDF 页码范围（如 "1-5"）'),
|
||
})
|
||
```
|
||
|
||
### 3.3 权限模型
|
||
|
||
- 检查文件路径是否在允许目录下
|
||
- 检查是否匹配 deny rules
|
||
- 检查是否为会话相关文件（特殊处理）
|
||
|
||
### 3.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ file_path, offset = 1, limit, pages }, context) {
|
||
const ext = path.extname(file_path).toLowerCase()
|
||
|
||
// 根据文件类型处理
|
||
if (ext === '.ipynb') {
|
||
return readNotebook(file_path)
|
||
} else if (IMAGE_EXTENSIONS.has(ext)) {
|
||
return readImage(file_path)
|
||
} else if (ext === '.pdf') {
|
||
return readPDF(file_path, pages)
|
||
} else {
|
||
return readTextFile(file_path, offset, limit)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 特殊处理
|
||
|
||
**Deduplication（去重）**：
|
||
- 如果文件未修改且读取范围相同，返回 `file_unchanged` stub
|
||
- 避免重复发送相同内容浪费 Token
|
||
|
||
**内存新鲜度提示**：
|
||
```typescript
|
||
function memoryFileFreshnessNote(mtimeMs: number): string {
|
||
const age = Date.now() - mtimeMs
|
||
if (age < 60000) return '(updated seconds ago)'
|
||
if (age < 3600000) return `(updated ${Math.floor(age/60000)}m ago)`
|
||
// ...
|
||
}
|
||
```
|
||
|
||
## 4. FileWriteTool - 文件写入
|
||
|
||
### 4.1 功能描述
|
||
|
||
FileWriteTool 用于创建或覆盖文件内容。
|
||
|
||
### 4.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
file_path: z.string().describe('文件路径'),
|
||
content: z.string().describe('文件内容'),
|
||
})
|
||
```
|
||
|
||
### 4.3 权限模型
|
||
|
||
- 写入权限检查
|
||
- 目录创建权限
|
||
- 危险路径保护（如 `/etc`、`/System`）
|
||
|
||
### 4.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ file_path, content }, context) {
|
||
// 1. 验证路径
|
||
const fullPath = expandPath(file_path)
|
||
|
||
// 2. 安全检查
|
||
if (isDangerousPath(fullPath)) {
|
||
throw new Error('Cannot write to protected path')
|
||
}
|
||
|
||
// 3. 确保目录存在
|
||
const dir = path.dirname(fullPath)
|
||
await ensureDirExists(dir)
|
||
|
||
// 4. 写入文件
|
||
await writeFile(fullPath, content)
|
||
|
||
// 5. 更新文件状态缓存
|
||
context.readFileState.set(fullPath, {
|
||
content,
|
||
timestamp: Date.now(),
|
||
})
|
||
|
||
return { success: true, path: fullPath }
|
||
}
|
||
```
|
||
|
||
## 5. FileEditTool - 文件编辑
|
||
|
||
### 5.1 功能描述
|
||
|
||
FileEditTool 支持两种编辑模式：
|
||
|
||
1. **Search/Replace 模式**：通过 old_string 和 new_string 进行替换
|
||
2. **Edit 模式**：直接编辑文件内容
|
||
|
||
### 5.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
file_path: z.string().describe('文件路径'),
|
||
old_string: z.string().optional().describe('要替换的文本（精确匹配）'),
|
||
new_string: z.string().optional().describe('替换后的文本'),
|
||
// 或者使用 partial_diff
|
||
partial_diff: z.object({
|
||
replacements: z.array(z.object({
|
||
old_string: z.string(),
|
||
new_string: z.string(),
|
||
}))
|
||
}).optional()
|
||
})
|
||
```
|
||
|
||
### 5.3 权限模型
|
||
|
||
- 需要有效的 old_string（防止意外覆盖）
|
||
- 不能用于删除整个文件
|
||
- 禁止编辑二进制文件
|
||
|
||
### 5.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ file_path, old_string, new_string, partial_diff }, context) {
|
||
// 1. 读取当前文件内容
|
||
const content = await readFile(file_path)
|
||
|
||
// 2. 执行替换
|
||
let newContent: string
|
||
|
||
if (partial_diff) {
|
||
// 批量替换
|
||
newContent = content
|
||
for (const { old_string, new_string } of partial_diff.replacements) {
|
||
newContent = applyReplacement(newContent, old_string, new_string)
|
||
}
|
||
} else {
|
||
// 单次替换
|
||
newContent = applyReplacement(content, old_string, new_string)
|
||
}
|
||
|
||
// 3. 验证 old_string 存在且唯一
|
||
const occurrences = countOccurrences(content, old_string)
|
||
if (occurrences === 0) {
|
||
throw new Error('old_string not found in file')
|
||
}
|
||
if (occurrences > 1) {
|
||
throw new Error('old_string appears multiple times, be more specific')
|
||
}
|
||
|
||
// 4. 写入文件
|
||
await writeFile(file_path, newContent)
|
||
|
||
// 5. 更新缓存
|
||
context.readFileState.set(file_path, {
|
||
content: newContent,
|
||
timestamp: Date.now(),
|
||
})
|
||
}
|
||
```
|
||
|
||
## 6. GlobTool - 文件模式匹配
|
||
|
||
### 6.1 功能描述
|
||
|
||
使用 glob 模式查找文件。
|
||
|
||
### 6.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
pattern: z.string().describe('Glob 模式（如 "**/*.ts"）'),
|
||
cwd: z.string().optional().describe('搜索根目录'),
|
||
})
|
||
```
|
||
|
||
### 6.3 核心逻辑
|
||
|
||
```typescript
|
||
async call({ pattern, cwd }, context) {
|
||
// 使用 ripgrep 的 glob 功能实现高性能搜索
|
||
const results = await execFile('rg', [
|
||
'--files-with-matches',
|
||
'--glob', pattern,
|
||
cwd || process.cwd()
|
||
])
|
||
|
||
return {
|
||
files: results.split('\n').filter(Boolean)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. GrepTool - 代码搜索
|
||
|
||
### 7.1 功能描述
|
||
|
||
在代码库中搜索匹配文本。
|
||
|
||
### 7.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
pattern: z.string().describe('搜索模式（支持正则）'),
|
||
cwd: z.string().optional().describe('搜索目录'),
|
||
context: z.number().optional().describe('上下文行数'),
|
||
file_pattern: z.string().optional().describe('文件过滤模式'),
|
||
})
|
||
```
|
||
|
||
### 7.3 核心逻辑
|
||
|
||
```typescript
|
||
async call({ pattern, cwd, context = 3, file_pattern }, context) {
|
||
const args = [
|
||
'--json',
|
||
'-C', context.toString(),
|
||
pattern,
|
||
]
|
||
|
||
if (file_pattern) {
|
||
args.push('--glob', file_pattern)
|
||
}
|
||
|
||
args.push(cwd || '.')
|
||
|
||
const results = await execFile('rg', args)
|
||
|
||
// 解析 JSON 输出
|
||
const matches = JSON.parse(results)
|
||
|
||
return {
|
||
matches: matches.map(parseMatch),
|
||
count: matches.length
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. WebFetchTool - 网页获取
|
||
|
||
### 8.1 功能描述
|
||
|
||
获取网页内容。
|
||
|
||
### 8.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
url: z.string().url().describe('网页 URL'),
|
||
})
|
||
```
|
||
|
||
### 8.3 权限模型
|
||
|
||
**预批准域名列表**：
|
||
- anthropic.com
|
||
- claude.ai
|
||
- github.com
|
||
- 主要新闻和文档站点
|
||
|
||
### 8.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ url }, context) {
|
||
// 1. URL 安全检查
|
||
if (!isPreapprovedUrl(url)) {
|
||
const decision = await context.requestPrompt('web_fetch', url)
|
||
if (!decision.approved) {
|
||
throw new Error('URL not approved')
|
||
}
|
||
}
|
||
|
||
// 2. 获取网页
|
||
const response = await fetch(url)
|
||
|
||
// 3. 解析 HTML
|
||
const text = await extractText(response)
|
||
|
||
// 4. 清理和格式化
|
||
return {
|
||
content: cleanHtml(text),
|
||
title: extractTitle(response),
|
||
url,
|
||
}
|
||
}
|
||
```
|
||
|
||
## 9. WebSearchTool - 网络搜索
|
||
|
||
### 9.1 功能描述
|
||
|
||
执行网络搜索。
|
||
|
||
### 9.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
query: z.string().describe('搜索查询'),
|
||
})
|
||
```
|
||
|
||
### 9.3 核心逻辑
|
||
|
||
```typescript
|
||
async call({ query }, context) {
|
||
// 使用搜索引擎 API
|
||
const results = await searchEngine.query(query)
|
||
|
||
return {
|
||
results: results.map(r => ({
|
||
title: r.title,
|
||
url: r.url,
|
||
snippet: r.snippet,
|
||
})),
|
||
total: results.length,
|
||
}
|
||
}
|
||
```
|
||
|
||
## 10. AgentTool - 子 Agent
|
||
|
||
### 10.1 功能描述
|
||
|
||
AgentTool 允许 Claude 创建和管理子 Agent 来并行执行任务。
|
||
|
||
### 10.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
agent: z.enum(['general', 'plan', 'explore', ...]).describe('Agent 类型'),
|
||
prompt: z.string().describe('给 Agent 的指令'),
|
||
agentId: z.string().optional().describe('现有 Agent ID（用于恢复）'),
|
||
maxTurns: z.number().optional().describe('最大轮次'),
|
||
})
|
||
```
|
||
|
||
### 10.3 Agent 类型
|
||
|
||
| 类型 | 描述 |
|
||
|------|------|
|
||
| `general` | 通用任务执行 |
|
||
| `plan` | 计划制定 |
|
||
| `explore` | 代码探索 |
|
||
| `verification` | 验证检查 |
|
||
|
||
### 10.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ agent, prompt, maxTurns }, context) {
|
||
// 1. 创建或恢复 Agent
|
||
const agentId = await createSubAgent({
|
||
type: agent,
|
||
prompt,
|
||
maxTurns,
|
||
})
|
||
|
||
// 2. 执行 Agent
|
||
const result = await runAgent(agentId, context)
|
||
|
||
// 3. 返回结果
|
||
return {
|
||
output: result.output,
|
||
agentId,
|
||
turns: result.turns,
|
||
}
|
||
}
|
||
```
|
||
|
||
## 11. SkillTool - 技能执行
|
||
|
||
### 11.1 功能描述
|
||
|
||
SkillTool 用于执行用户定义的技能（Skills），这些技能以 Markdown 文件形式保存在本地目录中。
|
||
|
||
### 11.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
name: z.string().describe('技能名称'),
|
||
args: z.string().optional().describe('传递给技能的参数'),
|
||
})
|
||
```
|
||
|
||
### 11.3 技能定义格式
|
||
|
||
技能目录结构：
|
||
```
|
||
~/.claude/skills/my-skill/
|
||
└── skill.md
|
||
```
|
||
|
||
skill.md 格式：
|
||
```markdown
|
||
---
|
||
name: my-skill
|
||
description: 这个技能做什么
|
||
---
|
||
|
||
# My Skill
|
||
|
||
这个技能用于执行特定任务...
|
||
|
||
## 使用方法
|
||
|
||
执行时会运行以下脚本...
|
||
```
|
||
|
||
### 11.4 核心逻辑
|
||
|
||
```typescript
|
||
async call({ name, args }, context) {
|
||
// 1. 查找技能定义
|
||
const skill = await findSkill(name)
|
||
|
||
if (!skill) {
|
||
throw new Error(`Skill not found: ${name}`)
|
||
}
|
||
|
||
// 2. 解析技能定义
|
||
const { prompt, script } = parseSkillDefinition(skill)
|
||
|
||
// 3. 执行脚本
|
||
const output = await executeScript(script, { args })
|
||
|
||
return {
|
||
output,
|
||
skillName: name,
|
||
}
|
||
}
|
||
```
|
||
|
||
## 12. MCPTool - Model Context Protocol
|
||
|
||
### 12.1 功能描述
|
||
|
||
MCPTool 是 MCP（Model Context Protocol）协议的工具包装器，允许调用 MCP 服务器提供的工具。
|
||
|
||
### 12.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
server: z.string().describe('MCP 服务器名称'),
|
||
tool: z.string().describe('工具名称'),
|
||
arguments: z.record(z.string(), z.unknown()).optional().describe('工具参数'),
|
||
})
|
||
```
|
||
|
||
### 12.3 核心逻辑
|
||
|
||
```typescript
|
||
async call({ server, tool, arguments }, context) {
|
||
// 1. 获取 MCP 客户端
|
||
const client = context.mcpClients.find(c => c.name === server)
|
||
|
||
if (!client) {
|
||
throw new Error(`MCP server not found: ${server}`)
|
||
}
|
||
|
||
// 2. 发送工具调用请求
|
||
const result = await client.callTool(tool, arguments)
|
||
|
||
// 3. 返回结果
|
||
return result
|
||
}
|
||
```
|
||
|
||
## 13. LSPTool - 语言服务器协议
|
||
|
||
### 13.1 功能描述
|
||
|
||
LSPTool 提供对 Language Server Protocol 的访问，用于代码导航、诊断等。
|
||
|
||
### 13.2 核心功能
|
||
|
||
- 跳转到定义 (Go to Definition)
|
||
- 查找引用 (Find References)
|
||
- 代码补全 (Completions)
|
||
- 诊断信息 (Diagnostics)
|
||
|
||
## 14. NotebookEditTool - Jupyter Notebook 编辑
|
||
|
||
### 14.1 功能描述
|
||
|
||
NotebookEditTool 专门用于编辑 Jupyter Notebook 文件。
|
||
|
||
### 14.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
file_path: z.string().describe('Notebook 文件路径'),
|
||
cell_id: z.string().optional().describe('要编辑的单元格 ID'),
|
||
new_source: z.string().optional().describe('新单元格内容'),
|
||
action: z.enum(['insert', 'delete', 'move']).optional().describe('操作类型'),
|
||
})
|
||
```
|
||
|
||
## 15. Task 系列工具
|
||
|
||
### 15.1 概述
|
||
|
||
Task 系列工具提供完整的任务管理功能：
|
||
|
||
| 工具 | 描述 |
|
||
|------|------|
|
||
| `TaskCreateTool` | 创建新任务 |
|
||
| `TaskGetTool` | 获取任务详情 |
|
||
| `TaskUpdateTool` | 更新任务状态 |
|
||
| `TaskListTool` | 列出任务 |
|
||
| `TaskStopTool` | 停止任务 |
|
||
| `TaskOutputTool` | 获取任务输出 |
|
||
|
||
### 15.2 TaskCreateTool 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
description: z.string().describe('任务描述'),
|
||
status: z.enum(['pending', 'in_progress', 'completed']).optional(),
|
||
priority: z.enum(['low', 'medium', 'high']).optional(),
|
||
})
|
||
```
|
||
|
||
### 15.3 任务状态流转
|
||
|
||
```
|
||
pending ──► in_progress ──► completed
|
||
│ │
|
||
└──────► failed
|
||
```
|
||
|
||
## 16. SendMessageTool - 团队消息
|
||
|
||
### 16.1 功能描述
|
||
|
||
SendMessageTool 用于向团队成员发送消息。
|
||
|
||
### 16.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
recipient: z.string().describe('收件人标识'),
|
||
message: z.string().describe('消息内容'),
|
||
})
|
||
```
|
||
|
||
## 17. TeamCreateTool - 创建团队
|
||
|
||
### 17.1 功能描述
|
||
|
||
TeamCreateTool 创建一个 Agent 团队，团队成员可以协作完成任务。
|
||
|
||
### 17.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
name: z.string().describe('团队名称'),
|
||
members: z.array(z.object({
|
||
name: z.string(),
|
||
role: z.enum(['coordinator', 'worker', 'reviewer']),
|
||
agentType: z.string().optional(),
|
||
})).describe('团队成员'),
|
||
})
|
||
```
|
||
|
||
### 17.3 团队角色
|
||
|
||
| 角色 | 描述 |
|
||
|------|------|
|
||
| `coordinator` | 协调者，负责分配任务 |
|
||
| `worker` | 执行者，负责完成任务 |
|
||
| `reviewer` | 审核者，负责检查结果 |
|
||
|
||
## 18. EnterPlanModeTool / ExitPlanModeTool
|
||
|
||
### 18.1 功能描述
|
||
|
||
计划模式允许 Claude 在执行前先制定计划，用户确认后再执行。
|
||
|
||
### 18.2 输入 Schema
|
||
|
||
```typescript
|
||
// EnterPlanModeTool
|
||
const inputSchema = z.object({
|
||
prompt: z.string().optional().describe('计划提示'),
|
||
})
|
||
|
||
// ExitPlanModeTool
|
||
// 无需参数
|
||
```
|
||
|
||
## 19. EnterWorktreeTool / ExitWorktreeTool
|
||
|
||
### 19.1 功能描述
|
||
|
||
用于创建和切换 Git Worktree，便于在多个分支上同时工作。
|
||
|
||
### 19.2 输入 Schema
|
||
|
||
```typescript
|
||
// EnterWorktreeTool
|
||
const inputSchema = z.object({
|
||
branch: z.string().describe('分支名'),
|
||
path: z.string().optional().describe('Worktree 路径'),
|
||
})
|
||
|
||
// ExitWorktreeTool
|
||
const inputSchema = z.object({
|
||
path: z.string().optional().describe('要删除的 Worktree 路径'),
|
||
})
|
||
```
|
||
|
||
## 20. ToolSearchTool - 工具搜索
|
||
|
||
### 20.1 功能描述
|
||
|
||
ToolSearchTool 允许模型在运行时搜索可用工具，当工具过多时会延迟加载。
|
||
|
||
### 20.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
query: z.string().describe('搜索查询'),
|
||
})
|
||
```
|
||
|
||
### 20.3 延迟加载机制
|
||
|
||
```typescript
|
||
// 当工具数量超过阈值时启用延迟加载
|
||
const TOOL_SEARCH_THRESHOLD = 50
|
||
|
||
if (totalTools > TOOL_SEARCH_THRESHOLD) {
|
||
// 工具标记为 shouldDefer: true
|
||
// 首次调用时需要通过 ToolSearchTool 激活
|
||
}
|
||
```
|
||
|
||
## 21. CronCreateTool - 定时任务
|
||
|
||
### 21.1 功能描述
|
||
|
||
CronCreateTool 创建定时执行的任务。
|
||
|
||
### 21.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
schedule: z.string().describe('Cron 表达式'),
|
||
command: z.string().describe('要执行的命令'),
|
||
name: z.string().optional().describe('任务名称'),
|
||
})
|
||
```
|
||
|
||
## 22. RemoteTriggerTool - 远程触发
|
||
|
||
### 22.1 功能描述
|
||
|
||
RemoteTriggerTool 允许从远程触发任务执行。
|
||
|
||
### 22.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
trigger_id: z.string().describe('触发器 ID'),
|
||
payload: z.record(z.string(), z.unknown()).optional().describe('传递的数据'),
|
||
})
|
||
```
|
||
|
||
## 23. SleepTool - 延迟执行
|
||
|
||
### 23.1 功能描述
|
||
|
||
SleepTool 用于在任务执行中引入延迟。
|
||
|
||
### 23.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
duration: z.number().describe('延迟时间（秒）'),
|
||
})
|
||
```
|
||
|
||
## 24. SyntheticOutputTool - 结构化输出
|
||
|
||
### 24.1 功能描述
|
||
|
||
SyntheticOutputTool 用于提供符合 JSON Schema 的结构化输出。
|
||
|
||
### 24.2 输入 Schema
|
||
|
||
```typescript
|
||
const inputSchema = z.object({
|
||
schema: z.record(z.string(), z.unknown()).describe('JSON Schema'),
|
||
data: z.record(z.string(), z.unknown()).describe('输出数据'),
|
||
})
|
||
```
|
||
|
||
### 24.3 验证机制
|
||
|
||
```typescript
|
||
async call({ schema, data }, context) {
|
||
// 使用 Zod 验证数据
|
||
const validator = z.object(schema)
|
||
const result = validator.safeParse(data)
|
||
|
||
if (!result.success) {
|
||
throw new Error(`Invalid output: ${result.error.message}`)
|
||
}
|
||
|
||
return { validated: result.data }
|
||
}
|
||
```
|
||
|
||
## 25. 工具权限系统总结
|
||
|
||
### 25.1 权限模式
|
||
|
||
| 模式 | 描述 | 行为 |
|
||
|------|------|------|
|
||
| `default` | 默认模式 | 询问危险操作 |
|
||
| `auto` | 自动模式 | 基于规则自动决定 |
|
||
| `bypass` | 绕过模式 | 允许所有操作 |
|
||
| `plan` | 计划模式 | 强制计划模式 |
|
||
|
||
### 25.2 权限检查流程
|
||
|
||
```
|
||
1. validateInput() - 验证输入有效性
|
||
│
|
||
▼
|
||
2. checkPermissions() - 检查权限规则
|
||
│
|
||
├──► alwaysAllow → 返回允许
|
||
│
|
||
├──► alwaysDeny → 返回拒绝
|
||
│
|
||
└──► 需要询问 → 等待用户确认
|
||
```
|
||
|
||
### 25.3 权限规则匹配
|
||
|
||
```typescript
|
||
// 权限规则支持通配符模式
|
||
const rules = {
|
||
'Bash(rm *)': 'deny', // 拒绝所有 rm 命令
|
||
'Bash(git *)': 'allow', // 允许所有 git 命令
|
||
'Read(/home/user/src/*)': 'allow', // 允许读取特定目录
|
||
}
|
||
```
|
||
|
||
## 26. 工具渲染系统
|
||
|
||
### 26.1 渲染方法
|
||
|
||
| 方法 | 用途 |
|
||
|------|------|
|
||
| `renderToolUseMessage` | 渲染工具调用消息 |
|
||
| `renderToolUseTag` | 渲染工具标签（如超时标记） |
|
||
| `renderToolUseProgressMessage` | 渲染进度消息 |
|
||
| `renderToolResultMessage` | 渲染工具结果 |
|
||
| `renderToolUseErrorMessage` | 渲染错误消息 |
|
||
| `renderToolUseRejectedMessage` | 渲染拒绝消息 |
|
||
|
||
### 26.2 渲染选项
|
||
|
||
```typescript
|
||
interface RenderOptions {
|
||
style?: 'condensed' | 'full'
|
||
theme?: ThemeName
|
||
verbose?: boolean
|
||
isTranscriptMode?: boolean
|
||
terminalSize?: { columns: number; rows: number }
|
||
}
|
||
```
|
||
|
||
## 27. 总结
|
||
|
||
Claude Code 的工具系统设计遵循以下原则：
|
||
|
||
1. **一致性**：所有工具实现统一的 Tool 接口
|
||
2. **安全性**：细粒度的权限控制和验证
|
||
3. **可扩展性**：支持 MCP、插件、技能等多种扩展机制
|
||
4. **用户控制**：用户可精确控制每个工具的使用权限
|
||
5. **高性能**：支持流式执行、缓存、去重等优化
|