mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 22:05:50 +00:00
claude-code with OpenAI mode fix
This commit is contained in:
HitMargin
220
docs/tools/file-operations.mdx
Normal file
220
docs/tools/file-operations.mdx
Normal file
@@ -0,0 +1,220 @@
|
||||
---
|
||||
title: "文件操作工具 - 三大工具的源码级解剖"
|
||||
description: "逆向分析 FileRead、FileEdit、FileWrite 三大工具的完整执行链路：去重缓存、AST 安全编辑、原子性读写、文件历史快照的实现细节。"
|
||||
keywords: ["文件操作", "FileRead", "FileEdit", "FileWrite", "代码编辑", "原子写入"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码层面解剖三大文件工具的完整执行链路 */}
|
||||
|
||||
## 三大工具的职责分化
|
||||
|
||||
Claude Code 将文件操作拆分为三个独立工具——这不是功能划分，而是**风险分级**：
|
||||
|
||||
| 工具 | 权限级别 | 核心方法 | 关键属性 |
|
||||
|------|---------|---------|---------|
|
||||
| **Read** | 只读（免审批） | `isReadOnly() → true` | `maxResultSizeChars: Infinity` |
|
||||
| **Edit** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |
|
||||
| **Write** | 写入（需确认） | `checkWritePermissionForTool()` | `maxResultSizeChars: 100,000` |
|
||||
|
||||
<Tip>
|
||||
Read 的 `maxResultSizeChars` 是 `Infinity`，但这并不意味着无限制输出——真正的截断发生在 `validateContentTokens()` 中基于 token 预算的动态判定，而非字符数硬限制。
|
||||
</Tip>
|
||||
|
||||
## FileRead：多模态文件读取引擎
|
||||
|
||||
源码路径：`src/tools/FileReadTool/FileReadTool.ts`
|
||||
|
||||
### 读取去重机制
|
||||
|
||||
Read 工具有一个常被忽视但至关重要的**去重层**。当 AI 重复读取同一个文件的同一范围时，系统不会浪费 token 发送两份完整内容：
|
||||
|
||||
```typescript
|
||||
// FileReadTool.ts:530-573 — 去重逻辑
|
||||
const existingState = readFileState.get(fullFilePath)
|
||||
if (existingState && !existingState.isPartialView && existingState.offset !== undefined) {
|
||||
const rangeMatch = existingState.offset === offset && existingState.limit === limit
|
||||
if (rangeMatch) {
|
||||
const mtimeMs = await getFileModificationTimeAsync(fullFilePath)
|
||||
if (mtimeMs === existingState.timestamp) {
|
||||
return { data: { type: 'file_unchanged', file: { filePath: file_path } } }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关键设计点：
|
||||
- 去重仅对 **Read 工具自身的读取**生效（通过 `offset !== undefined` 判定）
|
||||
- Edit/Write 也会写入 `readFileState`，但它们的 `offset` 为 `undefined`，所以不会误命中去重
|
||||
- 通过 mtime 比对确保文件未被外部修改
|
||||
- 有 GrowthBook killswitch（`tengu_read_dedup_killswitch`）可紧急关闭
|
||||
|
||||
实测数据：BQ proxy 显示约 18% 的 Read 调用是同文件碰撞，占 fleet `cache_creation` 的 2.64%。
|
||||
|
||||
### 多格式分发：文本、图片、PDF、Notebook 四条路径
|
||||
|
||||
Read 工具的 `callInner()` 按 `ext` 分发到四条完全不同的处理路径：
|
||||
|
||||
```
|
||||
.ipynb → readNotebook() → JSON cell 解析 → token 校验
|
||||
.png/.jpg/.gif/.webp → readImageWithTokenBudget() → 压缩+降采样
|
||||
.pdf → extractPDFPages() / readPDF() → 页面级提取
|
||||
其他 → readFileInRange() → 分页读取
|
||||
```
|
||||
|
||||
**图片路径的压缩策略**特别精细：
|
||||
1. 先用 `maybeResizeAndDownsampleImageBuffer()` 标准缩放
|
||||
2. 用 `base64.length * 0.125` 估算 token 数
|
||||
3. 超出预算时调用 `compressImageBufferWithTokenLimit()` 激进压缩
|
||||
4. 仍然超限时用 sharp 做最后兜底：`resize(400,400).jpeg({quality:20})`
|
||||
|
||||
**PDF 路径**有页数阈值：超过 `PDF_AT_MENTION_INLINE_THRESHOLD`（默认值在 `apiLimits.ts`）时强制分页读取，每请求最多 `PDF_MAX_PAGES_PER_READ` 页。
|
||||
|
||||
### 安全防线
|
||||
|
||||
Read 工具在 `validateInput()` 中设置了多层安全门：
|
||||
|
||||
1. **设备文件屏蔽**（`BLOCKED_DEVICE_PATHS`）：`/dev/zero`、`/dev/random`、`/dev/tty` 等——防止无限输出或阻塞挂起
|
||||
2. **二进制文件拒绝**（`hasBinaryExtension`）：排除 PDF 和图片扩展名后，阻止读取 `.exe`、`.so` 等二进制文件
|
||||
3. **UNC 路径跳过**：Windows 下 `\\server\share` 路径跳过文件系统操作，防止 SMB NTLM 凭据泄露
|
||||
4. **权限拒绝规则**（`matchingRuleForInput`）：匹配 `deny` 规则后直接拒绝
|
||||
|
||||
### 文件未找到时的智能建议
|
||||
|
||||
当文件不存在时，Read 不会只报一个 "file not found"：
|
||||
|
||||
```typescript
|
||||
// FileReadTool.ts:639-647
|
||||
const similarFilename = findSimilarFile(fullFilePath) // 相似扩展名
|
||||
const cwdSuggestion = await suggestPathUnderCwd(fullFilePath) // cwd 相对路径建议
|
||||
// macOS 截图特殊处理：薄空格(U+202F) vs 普通空格
|
||||
const altPath = getAlternateScreenshotPath(fullFilePath)
|
||||
```
|
||||
|
||||
对 macOS 截图文件名中 AM/PM 前的薄空格（U+202F）做了特殊处理——这是实测中发现的跨 macOS 版本兼容性问题。
|
||||
|
||||
## FileEdit：精确字符串替换引擎
|
||||
|
||||
源码路径：`src/tools/FileEditTool/FileEditTool.ts` + `utils.ts`
|
||||
|
||||
### 引号标准化：AI 无法输出的字符怎么办
|
||||
|
||||
AI 模型只能输出直引号（`'` `"`），但源码中可能使用弯引号（`'` `'` `"` `"`）。`findActualString()` 函数处理了这个不对齐：
|
||||
|
||||
```typescript
|
||||
// utils.ts:73-93
|
||||
export function findActualString(fileContent: string, searchString: string): string | null {
|
||||
if (fileContent.includes(searchString)) return searchString // 精确匹配
|
||||
const normalizedSearch = normalizeQuotes(searchString) // 弯引号→直引号
|
||||
const normalizedFile = normalizeQuotes(fileContent)
|
||||
const idx = normalizedFile.indexOf(normalizedSearch)
|
||||
if (idx !== -1) return fileContent.substring(idx, idx + searchString.length)
|
||||
return null
|
||||
}
|
||||
```
|
||||
|
||||
匹配后还有**反向引号保持**（`preserveQuoteStyle`）：如果文件用弯引号，替换后的新字符串也自动转换为弯引号，包括缩写中的撇号（如 "don't"）。
|
||||
|
||||
### 原子性读-改-写
|
||||
|
||||
Edit 工具的 `call()` 方法实现了一个**无锁原子更新**协议：
|
||||
|
||||
```
|
||||
1. await fs.mkdir(dir) ← 确保目录存在（异步，在临界区外）
|
||||
2. await fileHistoryTrackEdit() ← 备份旧内容（异步，在临界区外）
|
||||
3. readFileSyncWithMetadata() ← 同步读取当前文件内容（临界区开始）
|
||||
4. getFileModificationTime() ← mtime 校验
|
||||
5. findActualString() ← 引号标准化匹配
|
||||
6. getPatchForEdit() ← 计算 diff
|
||||
7. writeTextContent() ← 写入磁盘
|
||||
8. readFileState.set() ← 更新缓存（临界区结束）
|
||||
```
|
||||
|
||||
步骤 3-8 之间**不允许任何异步操作**（源码注释明确写道："Please avoid async operations between here and writing to disk to preserve atomicity"）。这确保了在 mtime 校验和实际写入之间不会有其他进程修改文件。
|
||||
|
||||
### 防覆写校验
|
||||
|
||||
Edit 工具在 `validateInput()` 中检查两个条件：
|
||||
1. **必须先读取**（`readFileState` 中有记录且不是局部视图）
|
||||
2. **文件未被外部修改**（`mtime` 未变，或全量读取时内容完全一致）
|
||||
|
||||
```typescript
|
||||
// FileEditTool.ts:290-311 — Windows 特殊处理
|
||||
const isFullRead = readTimestamp.offset === undefined && readTimestamp.limit === undefined
|
||||
if (isFullRead && fileContent === readTimestamp.content) {
|
||||
// 内容不变，安全继续（Windows 云同步/杀毒可能改 mtime）
|
||||
}
|
||||
```
|
||||
|
||||
Windows 上的 mtime 可能因云同步、杀毒软件等被修改而不改变内容，因此对全量读取做了内容级比对作为兜底。
|
||||
|
||||
### 编辑大小限制
|
||||
|
||||
```typescript
|
||||
const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB
|
||||
```
|
||||
|
||||
超过 1 GiB 的文件直接拒绝编辑——这是 V8 字符串长度限制（~2^30 字符）的安全边界。
|
||||
|
||||
## FileWrite：全量写入与创建
|
||||
|
||||
源码路径：`src/tools/FileWriteTool/FileWriteTool.ts`
|
||||
|
||||
Write 工具与 Edit 共享大部分基础设施（权限检查、mtime 校验、fileHistory 备份），但有两个关键差异：
|
||||
|
||||
### 行尾处理
|
||||
|
||||
```typescript
|
||||
// FileWriteTool.ts:300-305 — 关键注释
|
||||
// Write is a full content replacement — the model sent explicit line endings
|
||||
// in `content` and meant them. Do not rewrite them.
|
||||
writeTextContent(fullFilePath, content, enc, 'LF')
|
||||
```
|
||||
|
||||
Write 工具始终使用 `LF` 行尾。早期版本会保留旧文件的行尾或采样仓库行尾风格，但这导致 Linux 上 bash 脚本被注入 `\r`——现在 AI 发什么行尾就用什么行尾。
|
||||
|
||||
### 输出区分
|
||||
|
||||
Write 工具返回 `type: 'create' | 'update'`：
|
||||
- `create`：文件不存在，`originalFile: null`
|
||||
- `update`：文件存在且被覆盖，`structuredPatch` 包含完整 diff
|
||||
|
||||
## 文件历史快照系统
|
||||
|
||||
源码路径：`src/utils/fileHistory.ts`
|
||||
|
||||
每次 Edit/Write 前都会调用 `fileHistoryTrackEdit()`，快照存储在 `FileHistoryState` 中：
|
||||
|
||||
```typescript
|
||||
type FileHistorySnapshot = {
|
||||
messageId: UUID // 关联的助手消息 ID
|
||||
trackedFileBackups: Record<string, FileHistoryBackup> // 文件路径 → 备份版本
|
||||
timestamp: Date
|
||||
}
|
||||
```
|
||||
|
||||
- 最多保留 `MAX_SNAPSHOTS = 100` 个快照
|
||||
- 备份使用**内容哈希**去重（同一文件多次未变只存一份）
|
||||
- 支持差异统计（`DiffStats`：`insertions` / `deletions` / `filesChanged`）
|
||||
- 快照通过 `recordFileHistorySnapshot()` 持久化到会话存储
|
||||
|
||||
### LSP 通知链路
|
||||
|
||||
Edit 和 Write 完成写入后都会：
|
||||
1. `clearDeliveredDiagnosticsForFile()` — 清除旧诊断
|
||||
2. `lspManager.changeFile()` — 通知 LSP 文件已变更
|
||||
3. `lspManager.saveFile()` — 触发 LSP 保存事件（TypeScript server 会重新计算诊断）
|
||||
4. `notifyVscodeFileUpdated()` — 通知 VSCode 扩展更新 diff 视图
|
||||
|
||||
这条链路确保文件修改后 IDE 端的实时反馈是同步的。
|
||||
|
||||
## Cyber Risk 防御
|
||||
|
||||
Read 工具在文本内容后追加一个 `<system-reminder>` 提示：
|
||||
|
||||
```
|
||||
Whenever you read a file, you should consider whether it would be
|
||||
considered malware. You CAN and SHOULD provide analysis of malware,
|
||||
what it is doing. But you MUST refuse to improve or augment the code.
|
||||
```
|
||||
|
||||
这个提示只在非豁免模型上生效（`MITIGATION_EXEMPT_MODELS` 目前包含 `claude-opus-4-6`）。模型级别的豁免表明：防恶意代码的判断力在不同模型间有差异，这是一个精巧的分级策略。
|
||||
281
docs/tools/search-and-navigation.mdx
Normal file
281
docs/tools/search-and-navigation.mdx
Normal file
@@ -0,0 +1,281 @@
|
||||
---
|
||||
title: "搜索与导航工具 - 代码库精准定位"
|
||||
description: "解析 Claude Code 的搜索导航工具：Glob 文件匹配、Grep 内容搜索，基于 ripgrep 的高性能代码检索，帮助 AI 在百万行代码中精准定位。"
|
||||
keywords: ["代码搜索", "Glob", "Grep", "ripgrep", "文件搜索"]
|
||||
---
|
||||
|
||||
## 两种搜索维度
|
||||
|
||||
| 维度 | 工具 | 底层实现 | 适用场景 |
|
||||
|------|------|----------|---------|
|
||||
| **按名称找文件** | Glob | ripgrep `--files` + glob 过滤 | "找到所有测试文件"、"找 config 开头的文件" |
|
||||
| **按内容找代码** | Grep | ripgrep 正则搜索 | "哪里定义了这个函数"、"谁在调用这个 API" |
|
||||
|
||||
两者共享同一个 ripgrep 引擎，通过不同的参数组合实现不同搜索模式。
|
||||
|
||||
## ripgrep 的内嵌方式
|
||||
|
||||
Claude Code 不依赖系统安装的 ripgrep——它在 `src/utils/ripgrep.ts` 中实现了三级降级策略：
|
||||
|
||||
```
|
||||
优先级 1: 系统 ripgrep (USE_BUILTIN_RIPGREP=false)
|
||||
→ 使用 PATH 中的 rg 二进制
|
||||
→ 安全考虑：只用命令名 'rg'，不用完整路径，防止 PATH 劫持
|
||||
|
||||
优先级 2: 内嵌模式 (bundled/native build)
|
||||
→ process.execPath 自身，argv0='rg'
|
||||
→ Bun 将 rg 静态编译进二进制，通过 argv0 分发
|
||||
|
||||
优先级 3: vendor 目录 (npm build)
|
||||
→ vendor/ripgrep/{arch}-{platform}/rg
|
||||
→ macOS 需要 codesign 签名 + 移除 quarantine xattr
|
||||
```
|
||||
|
||||
平台适配示例：
|
||||
```
|
||||
vendor/ripgrep/
|
||||
├── x86_64-darwin/rg # macOS Intel
|
||||
├── arm64-darwin/rg # macOS Apple Silicon
|
||||
├── x86_64-linux/rg # Linux Intel
|
||||
├── arm64-linux/rg # Linux ARM
|
||||
└── x86_64-win32/rg.exe # Windows
|
||||
```
|
||||
|
||||
### macOS 代码签名
|
||||
|
||||
vendor 模式下的 rg 二进制需要 ad-hoc 签名才能通过 Gatekeeper（`codesignRipgrepIfNecessary()`）：
|
||||
|
||||
```typescript
|
||||
// 首次使用时执行：
|
||||
// 1. 检查是否已是有效签名
|
||||
codesign -vv -d <rg-path>
|
||||
// 2. 如果只是 linker-signed，重新签名
|
||||
codesign --sign - --force --preserve-metadata=entitlements,requirements,flags,runtime <rg-path>
|
||||
// 3. 移除隔离属性
|
||||
xattr -d com.apple.quarantine <rg-path>
|
||||
```
|
||||
|
||||
## 搜索结果的设计考量
|
||||
|
||||
### head_limit 与 Token 预算
|
||||
|
||||
大型项目的搜索结果可能有数十万条。默认最多返回 250 条匹配——这不是随意选择，而是**token 预算**的约束：
|
||||
|
||||
- 每条匹配行约 50-100 token
|
||||
- 250 条 ≈ 12,500-25,000 token
|
||||
- 这大约占 200k 上下文窗口的 6-12%
|
||||
- 超过这个比例，AI 的推理质量会下降
|
||||
|
||||
Grep 工具的 `head_limit` 参数让 AI 可以按需调整——搜索小项目时可以用更大的值。
|
||||
|
||||
### 按修改时间排序
|
||||
|
||||
Glob 默认把**最近修改的文件排在前面**。这不是默认的文件系统排序，而是刻意的设计决策：
|
||||
|
||||
```
|
||||
设计假设：最近修改的文件最可能与当前任务相关
|
||||
实际效果：AI 优先看到"活"的代码，而不是沉寂的历史文件
|
||||
```
|
||||
|
||||
在 `src/tools/GlobTool/` 中，ripgrep 的输出在返回给 AI 前按 mtime 排序。
|
||||
|
||||
### ripgrep 的错误处理
|
||||
|
||||
ripgrep 执行有专门的错误恢复链（`src/utils/ripgrep.ts`）：
|
||||
|
||||
| 错误 | 处理 |
|
||||
|------|------|
|
||||
| **EAGAIN**（资源不足） | 自动以单线程模式 `-j 1` 重试 |
|
||||
| **超时**（默认 20s，WSL 60s） | 返回已有部分结果，丢弃可能不完整的最后一行 |
|
||||
| **缓冲区溢出** | 截断到 20MB，返回已收集的结果 |
|
||||
| **SIGTERM 失效** | 5 秒后升级为 SIGKILL |
|
||||
|
||||
## ToolSearch：在 50+ 工具中发现目标
|
||||
|
||||
当可用工具超过 50 个时（含 MCP 提供的外部工具），AI 可能不知道该用哪个。**ToolSearch**（`src/tools/ToolSearchTool/`）提供了工具发现机制。
|
||||
|
||||
### 搜索算法
|
||||
|
||||
ToolSearch 实现了基于关键词的加权搜索（`searchToolsWithKeywords()`）：
|
||||
|
||||
```
|
||||
输入: query = "database connection"
|
||||
↓
|
||||
1. 精确匹配: 检查是否有工具名完全匹配（快速路径）
|
||||
2. MCP 前缀匹配: "mcp__postgres" → 匹配所有 postgres 相关工具
|
||||
3. 关键词拆分: ["database", "connection"]
|
||||
4. 工具名解析:
|
||||
- MCP 工具: "mcp__server__action" → ["server", "action"]
|
||||
- 普通工具: "FileEditTool" → ["file", "edit", "tool"]
|
||||
5. 加权评分:
|
||||
- 工具名精确匹配: 10 分（MCP: 12 分）
|
||||
- 工具名部分匹配: 5 分（MCP: 6 分）
|
||||
- searchHint 匹配: 4 分
|
||||
- 描述匹配: 2 分
|
||||
6. 必选词过滤: "+database" 前缀表示必须包含
|
||||
7. 按分数排序，返回 top-N
|
||||
```
|
||||
|
||||
### `select:` 直接选择
|
||||
|
||||
AI 也可以用 `select:ToolName` 精确选择已知工具。这比搜索更快，且支持逗号分隔的批量选择（`select:A,B,C`）。
|
||||
|
||||
### 延迟加载（Deferred Tools）
|
||||
|
||||
不是所有工具都常驻内存。MCP 工具和低频工具被标记为 `isDeferredTool`，只有在 ToolSearch 选中后才真正加载。这减少了每次 API 调用的 token 开销（工具描述占用大量 token）。
|
||||
|
||||
### 缓存策略
|
||||
|
||||
工具描述的获取是 memoized 的——只在延迟工具集合变化时清除缓存：
|
||||
|
||||
```typescript
|
||||
// 工具名排序后拼接作为缓存 key
|
||||
function getDeferredToolsCacheKey(deferredTools: Tools): string {
|
||||
return deferredTools.map(t => t.name).sort().join(',')
|
||||
}
|
||||
```
|
||||
|
||||
## Web 搜索与抓取
|
||||
|
||||
AI 的信息获取不局限于本地代码：
|
||||
|
||||
- **WebSearch**（`src/tools/WebSearchTool/`）：调用 Anthropic API 的 `web_search_20250305` server tool 搜索互联网
|
||||
- **WebFetch**（`src/tools/WebFetchTool/`）：抓取特定 URL 内容，转换为 Markdown 供 AI 阅读
|
||||
|
||||
这让 AI 可以查阅文档、搜索 Stack Overflow、阅读 GitHub issue——和人类开发者的工作方式一致。
|
||||
|
||||
### WebSearch 实现机制
|
||||
|
||||
WebSearch 通过适配器模式支持两种搜索后端，由 `src/tools/WebSearchTool/adapters/` 中的工厂函数 `createAdapter()` 选择：
|
||||
|
||||
```
|
||||
适配器架构:
|
||||
WebSearchTool.call()
|
||||
→ createAdapter() 选择后端
|
||||
├─ ApiSearchAdapter — Anthropic API 服务端搜索（需官方 API 密钥）
|
||||
└─ BingSearchAdapter — 直接抓取 Bing 搜索页面解析（无需 API 密钥）
|
||||
→ adapter.search(query, options)
|
||||
→ 转换为统一 SearchResult[] 格式返回
|
||||
```
|
||||
|
||||
#### 适配器选择逻辑
|
||||
|
||||
`adapters/index.ts` 中的工厂函数按以下优先级选择后端：
|
||||
|
||||
| 优先级 | 条件 | 适配器 |
|
||||
|--------|------|--------|
|
||||
| 1 | 环境变量 `WEB_SEARCH_ADAPTER=api` | `ApiSearchAdapter` |
|
||||
| 2 | 环境变量 `WEB_SEARCH_ADAPTER=bing` | `BingSearchAdapter` |
|
||||
| 3 | API Base URL 指向 Anthropic 官方 | `ApiSearchAdapter` |
|
||||
| 4 | 第三方代理 / 非官方端点 | `BingSearchAdapter` |
|
||||
|
||||
适配器是无状态的，同一会话内缓存复用。
|
||||
|
||||
#### ApiSearchAdapter — API 服务端搜索
|
||||
|
||||
将搜索请求委托给 Anthropic API 的 `web_search_20250305` server tool：
|
||||
|
||||
```
|
||||
调用链:
|
||||
ApiSearchAdapter.search(query, options)
|
||||
→ queryModelWithStreaming() 发起独立的 API 调用
|
||||
→ 携带 extraToolSchemas: [BetaWebSearchTool20250305]
|
||||
→ API 服务端执行搜索，返回流式事件
|
||||
→ server_tool_use / web_search_tool_result / text 交替返回
|
||||
→ extractSearchResults() 从 content blocks 提取 SearchResult[]
|
||||
```
|
||||
|
||||
| 特性 | 实现 |
|
||||
|------|------|
|
||||
| **模型选择** | Feature flag `tengu_plum_vx3` 控制用 Haiku（强制 tool_choice）还是主模型 |
|
||||
| **搜索上限** | 每次调用最多 8 次搜索（`max_uses: 8`） |
|
||||
| **域过滤** | 支持 `allowedDomains` / `blockedDomains` |
|
||||
| **进度追踪** | 流式解析 `input_json_delta` 提取 query，实时回调 `onProgress` |
|
||||
|
||||
#### BingSearchAdapter — Bing 搜索页面解析
|
||||
|
||||
直接抓取 Bing 搜索 HTML 并用正则提取结果，无需 API 密钥：
|
||||
|
||||
```
|
||||
调用链:
|
||||
BingSearchAdapter.search(query, options)
|
||||
→ axios.get(bing.com/search?q=...) — 使用浏览器级别 headers 绕过反爬
|
||||
→ extractBingResults(html)
|
||||
→ 正则匹配 <li class="b_algo"> 块
|
||||
→ 提取 <h2><a> 标题和 URL
|
||||
→ resolveBingUrl() 解码 Bing 重定向链接
|
||||
→ extractSnippet() 三级降级提取摘要
|
||||
→ 客户端域过滤 (allowedDomains / blockedDomains)
|
||||
→ 返回 SearchResult[]
|
||||
```
|
||||
|
||||
**反爬策略**：Bing 对非浏览器 UA 返回需要 JS 渲染的空页面。适配器使用完整的 Edge 浏览器请求头（包含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等现代浏览器标头）确保获得完整 HTML。同时使用 `setmkt=en-US` 参数统一市场定位，避免 Bing 基于用户 IP 做区域化定向（如跳转到德语/新加坡市场导致结果不相关）。
|
||||
|
||||
**URL 解码**：Bing 搜索结果中的 URL 为重定向格式（`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`），`resolveBingUrl()` 从 `u` 参数中 base64 解码出真实目标 URL（`a1` 前缀 = https，`a0` = http）。
|
||||
|
||||
**摘要提取**（`extractSnippet()`）按优先级尝试三个来源：
|
||||
1. `<p class="b_lineclamp...">` — 带行截断的摘要段落
|
||||
2. `<div class="b_caption">` 内的 `<p>` — 普通摘要段落
|
||||
3. `<div class="b_caption">` 的直接文本内容 — 兜底方案
|
||||
|
||||
| 特性 | 实现 |
|
||||
|------|------|
|
||||
| **超时** | 30 秒（`FETCH_TIMEOUT_MS`） |
|
||||
| **域过滤** | 支持 `allowedDomains` / `blockedDomains`，含子域名匹配 |
|
||||
| **进度追踪** | 发送 query_update 和 search_results_received 回调 |
|
||||
| **中止支持** | 外部 AbortSignal 传播到 axios 请求 |
|
||||
|
||||
### WebSearchTool 统一接口
|
||||
|
||||
`WebSearchTool`（`src/tools/WebSearchTool/WebSearchTool.ts`）是面向主循环的工具定义，所有 provider 均可使用（`isEnabled()` 始终返回 true）。它将适配器返回的 `SearchResult[]` 转换为内部 `Output` 格式，`mapToolResultToToolResultBlockParam` 将搜索结果格式化为带 markdown 超链接的文本，并附加 "REMINDER" 要求主模型在回复中包含 Sources。
|
||||
|
||||
### WebFetch 实现机制
|
||||
|
||||
WebFetch 是一个完整的 HTTP 客户端 + 内容处理管线：
|
||||
|
||||
```
|
||||
调用链:
|
||||
WebFetchTool.call({ url, prompt })
|
||||
→ getURLMarkdownContent(url)
|
||||
→ validateURL() — 长度≤2000、无用户名密码、公网域名
|
||||
→ URL_CACHE 命中检查（15 分钟 TTL LRU，50MB 上限）
|
||||
→ checkDomainBlocklist() — 调用 api.anthropic.com/api/web/domain_info 预检
|
||||
→ getWithPermittedRedirects() — axios 请求，自定义重定向处理
|
||||
→ HTML → Turndown 转 Markdown（懒加载单例，~1.4MB）
|
||||
→ 非 HTML → 原始文本
|
||||
→ 二进制（PDF 等）→ persistBinaryContent() 保存到磁盘
|
||||
→ applyPromptToMarkdown()
|
||||
→ 截断到 100K 字符
|
||||
→ queryHaiku() 用小模型按 prompt 提取信息
|
||||
→ 返回处理后的结果
|
||||
```
|
||||
|
||||
安全防护多层设计：
|
||||
|
||||
| 层级 | 机制 | 说明 |
|
||||
|------|------|------|
|
||||
| **域名预检** | `checkDomainBlocklist()` | 调用 `api.anthropic.com/api/web/domain_info?domain=…`，5 分钟缓存 |
|
||||
| **重定向控制** | `isPermittedRedirect()` | 仅允许同 host（±www）重定向，跨域重定向返回提示让 AI 重新调用 |
|
||||
| **重定向深度** | `MAX_REDIRECTS = 10` | 防止重定向循环无限挂起 |
|
||||
| **内容大小** | `MAX_HTTP_CONTENT_LENGTH = 10MB` | 单次响应上限 |
|
||||
| **请求超时** | `FETCH_TIMEOUT_MS = 60s` | 主请求超时；域名预检 10s |
|
||||
| **URL 验证** | `validateURL()` | 长度、协议、用户名密码、公网域名检查 |
|
||||
| **egress 检测** | `X-Proxy-Error: blocked-by-allowlist` | 检测企业代理拦截 |
|
||||
|
||||
预批准域名（`src/tools/WebFetchTool/preapproved.ts`）：
|
||||
|
||||
用户无需手动授权即可抓取的域名列表，包含 ~90 个主流技术文档站点（MDN、Python docs、React docs、AWS docs 等）。列表分为 hostname-only 和 path-prefix 两类，查找复杂度 O(1)。
|
||||
|
||||
对预批准域名，WebFetch 跳过 Haiku 摘要步骤（如果内容是 Markdown 且 < 100K 字符），直接返回原文——因为技术文档本身的结构化程度已经足够好。
|
||||
|
||||
权限模型方面，WebFetch 按 hostname 生成 `domain:xxx` 规则匹配用户的 allow/deny/ask 规则，支持用户对特定域名配置永久允许或拒绝。
|
||||
|
||||
### ripgrep 的流式输出
|
||||
|
||||
对于交互式场景（如 QuickOpen），ripgrep 支持**流式输出**（`ripGrepStream()`）：
|
||||
|
||||
```
|
||||
rg --files → 逐 chunk 到达 → 按行分割 → onLines(lines) 回调
|
||||
```
|
||||
|
||||
不需要等 ripgrep 完成整个搜索——第一批结果在 rg 仍在遍历目录树时就已展示。调用者可以通过 AbortSignal 提前终止搜索（例如找到足够多的结果后）。
|
||||
168
docs/tools/shell-execution.mdx
Normal file
168
docs/tools/shell-execution.mdx
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
title: "命令执行工具 - BashTool 安全设计与实现"
|
||||
description: "从源码角度解析 Claude Code BashTool：只读命令判定、AST 安全解析、自动后台化、输出截断和专用工具 vs shell 命令的设计权衡。"
|
||||
keywords: ["Bash 工具", "命令执行", "Shell 执行", "安全命令", "AI 执行命令"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 BashTool 的安全设计、执行链路和关键工程决策 */}
|
||||
|
||||
## 执行链路总览
|
||||
|
||||
一条 Bash 命令从 AI 决策到实际执行的完整路径：
|
||||
|
||||
```
|
||||
AI 生成 tool_use: { command: "npm test" }
|
||||
↓
|
||||
BashTool.validateInput() ← 基础输入校验
|
||||
↓
|
||||
BashTool.checkPermissions() ← 权限检查（详见安全体系章节）
|
||||
├── isReadOnly()? → 自动 allow（只读命令免审批）
|
||||
├── bashToolHasPermission() ← AST 解析 + 语义检查 + 规则匹配
|
||||
└── 未匹配 → 弹窗确认
|
||||
↓
|
||||
BashTool.call() → runShellCommand()
|
||||
↓
|
||||
shouldUseSandbox(input) ← 是否需要沙箱包裹
|
||||
↓
|
||||
Shell.exec(command, { shouldUseSandbox, shouldAutoBackground })
|
||||
↓
|
||||
spawn(wrapped_command) ← 实际进程创建
|
||||
```
|
||||
|
||||
## 只读命令的判定：为什么 Read 免审批而 Bash 不一定
|
||||
|
||||
BashTool 的 `isReadOnly()` 方法（`BashTool.tsx:437`）决定一条命令是否被视为"只读"：
|
||||
|
||||
```typescript
|
||||
isReadOnly(input) {
|
||||
const compoundCommandHasCd = commandHasAnyCd(input.command)
|
||||
const result = checkReadOnlyConstraints(input, compoundCommandHasCd)
|
||||
return result.behavior === 'allow'
|
||||
}
|
||||
```
|
||||
|
||||
判定逻辑基于 4 个命令集合（`BashTool.tsx:60-78`）：
|
||||
|
||||
| 集合 | 命令 | 性质 |
|
||||
|------|------|------|
|
||||
| `BASH_SEARCH_COMMANDS` | find, grep, rg, ag, ack, locate, which, whereis | 搜索类 |
|
||||
| `BASH_READ_COMMANDS` | cat, head, tail, wc, stat, file, jq, awk, sort, uniq... | 读取/分析类 |
|
||||
| `BASH_LIST_COMMANDS` | ls, tree, du | 列表类 |
|
||||
| `BASH_SEMANTIC_NEUTRAL_COMMANDS` | echo, printf, true, false, : | 语义中性（不影响判定） |
|
||||
|
||||
对于复合命令（`ls dir && echo "---" && ls dir2`），系统拆分后逐段检查——**所有非中性段都必须属于上述集合**，整条命令才被视为只读。
|
||||
|
||||
```typescript
|
||||
// BashTool.tsx:95 — 简化的判定逻辑
|
||||
for (const part of partsWithOperators) {
|
||||
if (BASH_SEMANTIC_NEUTRAL_COMMANDS.has(baseCommand)) continue // 跳过中性段
|
||||
if (!isPartSearch && !isPartRead && !isPartList) {
|
||||
return { isSearch: false, isRead: false, isList: false } // 有任何一段不通过 → 非只读
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## AST 安全解析：tree-sitter bash 解析
|
||||
|
||||
`preparePermissionMatcher()`（`BashTool.tsx:445`）在权限检查前用 `parseForSecurity()` 解析命令结构：
|
||||
|
||||
```typescript
|
||||
async preparePermissionMatcher({ command }) {
|
||||
const parsed = await parseForSecurity(command)
|
||||
if (parsed.kind !== 'simple') {
|
||||
return () => true // 解析失败 → fail-safe，触发所有 hook
|
||||
}
|
||||
// 提取子命令列表，剥离 VAR=val 前缀
|
||||
const subcommands = parsed.commands.map(c => c.argv.join(' '))
|
||||
return pattern => {
|
||||
return subcommands.some(cmd => matchWildcardPattern(pattern, cmd))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
关键安全点：对于复合命令 `ls && git push`，解析后拆分为 `["ls", "git push"]`，确保 `git push` 不会因为前半段是只读命令而绕过权限检查。解析失败时采用 fail-safe 策略——假设不安全，触发所有安全 hook。
|
||||
|
||||
## 超时控制：分级策略
|
||||
|
||||
```
|
||||
用户指定 timeout → 直接使用
|
||||
↓ 未指定
|
||||
getDefaultTimeoutMs()
|
||||
├── 默认上限：120,000ms（2 分钟）
|
||||
└── 最大上限：600,000ms（10 分钟，用户显式设置时）
|
||||
```
|
||||
|
||||
超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:129`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。
|
||||
|
||||
## 自动后台化
|
||||
|
||||
长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：
|
||||
|
||||
```typescript
|
||||
// BashTool.tsx:880
|
||||
const shouldAutoBackground = !isBackgroundTasksDisabled
|
||||
&& isAutobackgroundingAllowed(command)
|
||||
```
|
||||
|
||||
自动后台化的完整链路：
|
||||
|
||||
```
|
||||
命令开始执行
|
||||
↓ 进度轮询
|
||||
15 秒内未完成（ASSISTANT_BLOCKING_BUDGET_MS）
|
||||
↓
|
||||
检查 isAutobackgroundingAllowed(command)
|
||||
↓ 允许
|
||||
将前台任务转为后台任务（backgroundExistingForegroundTask）
|
||||
↓
|
||||
shellCommand.onTimeout → spawnBackgroundTask()
|
||||
↓
|
||||
返回 taskId 给 AI，AI 可以继续做其他事
|
||||
↓
|
||||
后台任务完成后通过通知机制汇报结果
|
||||
```
|
||||
|
||||
主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 `npm install` 阻塞整个 agentic loop 数分钟。
|
||||
|
||||
## 输出截断策略
|
||||
|
||||
命令输出过长时会触发截断，防止把海量日志塞进 AI 的上下文窗口：
|
||||
|
||||
| 截断点 | 位置 | 行为 |
|
||||
|--------|------|------|
|
||||
| `maxResultSizeChars` | 工具级（通常 100K 字符） | 超长输出在写入消息前截断 |
|
||||
| 进度轮询截断 | `onProgress` 回调 | 只传递最后几行作为进度显示 |
|
||||
| `totalBytes` 标记 | `isIncomplete` 参数 | 告知 AI 输出被截断 |
|
||||
|
||||
截断不是简单砍尾——`isIncomplete` 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。
|
||||
|
||||
## 为什么用专用工具而不是直接调 shell
|
||||
|
||||
Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。这不仅是用户体验的选择，更是架构层面的设计决策：
|
||||
|
||||
| 维度 | 专用工具 | Bash 命令 |
|
||||
|------|---------|----------|
|
||||
| **权限粒度** | `Read` 是只读操作 → 自动放行 | `Bash: cat file` 需要审批整条命令（cat 在只读集合中但走不同路径） |
|
||||
| **输出结构化** | 返回结构化数据，UI 可渲染 diff、高亮 | 纯文本输出，无渲染优化 |
|
||||
| **性能优化** | 文件缓存、分页、token 预算控制 | 每次都是新进程，无缓存 |
|
||||
| **并发安全** | `isConcurrencySafe()` 返回 `true` → 可并行执行 | Bash 命令可能有副作用，串行执行 |
|
||||
| **安全审计** | 工具名精确匹配权限规则 | 需 AST 解析命令结构后匹配 |
|
||||
|
||||
`isConcurrencySafe()`（`BashTool.tsx:434`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。
|
||||
|
||||
## 进度反馈的流式设计
|
||||
|
||||
BashTool 的命令执行是流式的，通过 `onProgress` 回调逐行推送输出：
|
||||
|
||||
```
|
||||
runShellCommand()
|
||||
├── Shell.exec() 启动子进程
|
||||
├── 每秒轮询输出文件
|
||||
├── onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete)
|
||||
│ ├── 更新 lastProgressOutput / fullOutput
|
||||
│ └── resolveProgress() → 唤醒 generator yield
|
||||
├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
|
||||
└── return { code, stdout, interrupted, ... }
|
||||
```
|
||||
|
||||
UI 层通过 `useToolCallProgress` hook 实时展示命令输出。`resolveProgress()` 信号机制让 generator 在有新数据时才 yield，避免了忙等待。
|
||||
212
docs/tools/task-management.mdx
Normal file
212
docs/tools/task-management.mdx
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
title: "任务管理系统 - TodoWrite 与 Tasks 双轨架构"
|
||||
description: "揭秘 Claude Code 任务管理系统的双轨架构：V1 内存 TodoWrite 与 V2 文件系统 Tasks，包含依赖管理、认领竞争和验证推动机制。"
|
||||
keywords: ["任务管理", "TodoWrite", "任务队列", "依赖管理", "多任务"]
|
||||
---
|
||||
|
||||
{/* 本章目标：揭示任务系统 V1（内存 TodoWrite）和 V2（文件系统 Task*）的双轨架构，以及依赖管理、认领竞争、验证推动的工程细节 */}
|
||||
|
||||
## 双轨架构：TodoWrite V1 与 Tasks V2
|
||||
|
||||
Claude Code 的任务管理并非单一系统，而是两个并存、按运行模式切换的实现：
|
||||
|
||||
| 维度 | V1: TodoWrite | V2: TaskCreate / TaskUpdate / TaskList / TaskGet |
|
||||
|------|--------------|--------------------------------------------------|
|
||||
| **启用条件** | 非交互式（pipe/SDK）或 `isTodoV2Enabled()` 返回 `false` | 交互式 REPL（默认）或 `CLAUDE_CODE_ENABLE_TASKS=1` |
|
||||
| **存储** | 内存中 `AppState.todos[sessionId]`（Zustand store） | 文件系统 `~/.claude/tasks/<taskListId>/<id>.json` |
|
||||
| **数据模型** | `{content, status, activeForm}` — 扁平三元组 | `{id, subject, description, activeForm, owner, status, blocks[], blockedBy[], metadata}` — 完整实体 |
|
||||
| **持久化** | 进程退出即丢失 | 跨进程存活，支持多 Agent 并发访问 |
|
||||
| **并发安全** | 无（单会话单写者） | 文件锁 + 高水位标记 + TOCTOU 防护 |
|
||||
|
||||
切换逻辑位于 `isTodoV2Enabled()`（`src/utils/tasks.ts:133`）：交互式会话默认启用 V2，SDK/pipe 模式回落 V1。两者互斥——`TodoWriteTool.isEnabled` 返回 `!isTodoV2Enabled()`，而 `TaskCreateTool.isEnabled` 返回 `isTodoV2Enabled()`。
|
||||
|
||||
## V1：TodoWrite 的极简设计
|
||||
|
||||
TodoWrite 本质是一个**全量替换**操作——每次调用传入完整的 `todos[]` 数组，完全覆盖之前的状态：
|
||||
|
||||
```typescript
|
||||
// src/tools/TodoWriteTool/TodoWriteTool.ts — call() 核心逻辑
|
||||
async call({ todos }, context) {
|
||||
const todoKey = context.agentId ?? getSessionId()
|
||||
const oldTodos = appState.todos[todoKey] ?? []
|
||||
const allDone = todos.every(_ => _.status === 'completed')
|
||||
const newTodos = allDone ? [] : todos // 全部完成则清空列表
|
||||
// ... 写入 AppState
|
||||
}
|
||||
```
|
||||
|
||||
### 智能清空与验证推动
|
||||
|
||||
一个微妙的设计：当所有任务都 `completed` 时，`newTodos` 被设为空数组（而非保留 `completed` 列表）。这确保 UI 上不会有"已完成"的视觉噪音。
|
||||
|
||||
此外，V1 包含一个**验证推动**（verification nudge）机制：当主线程 Agent 完成 3+ 个任务且没有任何一个是验证步骤时，系统在 tool_result 中追加提示，催促 Agent 派生验证子 Agent：
|
||||
|
||||
```typescript
|
||||
// 条件：主线程 + 全部完成 + ≥3 项 + 无验证任务
|
||||
if (allDone && todos.length >= 3 && !todos.some(t => /verif/i.test(t.content))) {
|
||||
verificationNudgeNeeded = true
|
||||
}
|
||||
// tool_result 中追加：
|
||||
// "NOTE: You just closed out 3+ tasks and none was a verification step..."
|
||||
```
|
||||
|
||||
这是防止 Agent "自说自话地宣布完成"的防御性设计——通过结构性推动而非硬约束。
|
||||
|
||||
## V2：文件系统持久化的任务系统
|
||||
|
||||
### 数据模型
|
||||
|
||||
每个任务是一个独立 JSON 文件，路径为 `~/.claude/tasks/<taskListId>/<id>.json`：
|
||||
|
||||
```typescript
|
||||
// src/utils/tasks.ts — TaskSchema
|
||||
{
|
||||
id: string, // 自增整数（1, 2, 3...）
|
||||
subject: string, // 祈使句标题（如 "Fix auth bug"）
|
||||
description: string, // 详细描述
|
||||
activeForm?: string, // 进行时形式（如 "Fixing auth bug"），用于 spinner
|
||||
owner?: string, // 认领该任务的 Agent ID/名称
|
||||
status: "pending" | "in_progress" | "completed",
|
||||
blocks: string[], // 此任务阻塞哪些任务 ID
|
||||
blockedBy: string[], // 哪些任务 ID 阻塞此任务
|
||||
metadata?: Record<string, unknown> // 任意附加数据
|
||||
}
|
||||
```
|
||||
|
||||
### 任务列表 ID 的解析优先级
|
||||
|
||||
`getTaskListId()` 按 5 级优先级解析任务归属：
|
||||
|
||||
1. `CLAUDE_CODE_TASK_LIST_ID` 环境变量（显式覆盖）
|
||||
2. 进程内 teammate 上下文的 teamName（共享 leader 的任务列表）
|
||||
3. `CLAUDE_CODE_TEAM_NAME` 环境变量（进程级 teammate）
|
||||
4. Leader 通过 `setLeaderTeamName()` 设置的 teamName
|
||||
5. `getSessionId()`（独立会话的兜底）
|
||||
|
||||
这意味着多 Agent 团队模式下，所有 teammate 自动共享同一个任务列表，无需额外协调。
|
||||
|
||||
### ID 分配与高水位标记
|
||||
|
||||
任务 ID 是简单的递增整数，但在并发场景下需要防止竞争：
|
||||
|
||||
```typescript
|
||||
// src/utils/tasks.ts — createTask() 简化
|
||||
async function createTask(taskListId, taskData) {
|
||||
release = await lockfile.lock(lockPath, LOCK_OPTIONS) // 获取排他锁
|
||||
const highestId = await findHighestTaskId(taskListId) // 读取当前最大 ID
|
||||
const id = String(highestId + 1) // 递增
|
||||
await writeFile(path, JSON.stringify({ id, ...taskData }))
|
||||
return id
|
||||
}
|
||||
```
|
||||
|
||||
锁配置使用指数退避重试 30 次（总计约 2.6 秒），适配 10+ 并发 Agent 的 swarm 场景。
|
||||
|
||||
高水位标记文件 `.highwatermark` 确保删除任务后 ID 不会被重用——即使任务 #5 被删除，下一个新建任务仍然是 #6。
|
||||
|
||||
## 依赖管理：blocks / blockedBy
|
||||
|
||||
任务间的依赖通过双向链表式的 `blocks` / `blockedBy` 字段实现：
|
||||
|
||||
- `taskA.blocks = ["3"]` 表示 "任务 A 完成前，任务 3 不能开始"
|
||||
- `task3.blockedBy = ["A"]` 表示 "任务 3 必须等任务 A 完成"
|
||||
|
||||
`blockTask()` 函数同时维护两端：
|
||||
|
||||
```typescript
|
||||
// src/utils/tasks.ts — blockTask()
|
||||
// A blocks B → 更新 A.blocks 加入 B，同时更新 B.blockedBy 加入 A
|
||||
if (!fromTask.blocks.includes(toTaskId)) {
|
||||
await updateTask(taskListId, fromTaskId, { blocks: [...fromTask.blocks, toTaskId] })
|
||||
}
|
||||
if (!toTask.blockedBy.includes(fromTaskId)) {
|
||||
await updateTask(taskListId, toTaskId, { blockedBy: [...toTask.blockedBy, fromTaskId] })
|
||||
}
|
||||
```
|
||||
|
||||
删除任务时，系统自动清理所有指向它的依赖引用（`deleteTask()` 遍历全部任务移除 `blocks` 和 `blockedBy` 中的引用）。
|
||||
|
||||
## 任务认领与并发控制
|
||||
|
||||
`claimTask()` 是 V2 的核心并发原语，支持两种锁定粒度：
|
||||
|
||||
### 1. 任务级锁（默认）
|
||||
|
||||
仅锁定目标任务文件，适合单 Agent 场景：
|
||||
|
||||
```
|
||||
getTask → 检查 owner → 检查 status → 检查 blockedBy → 写入 owner
|
||||
```
|
||||
|
||||
### 2. 列表级锁 + Agent 忙碌检查
|
||||
|
||||
当 `checkAgentBusy: true` 时，锁定整个任务列表目录（`.lock` 文件），原子化地完成：
|
||||
|
||||
```
|
||||
listTasks → 检查任务状态 → 检查依赖 → 检查 Agent 是否已拥有其他未完成任务 → 写入 owner
|
||||
```
|
||||
|
||||
认领失败有 4 种原因：
|
||||
|
||||
| `reason` | 含义 |
|
||||
|----------|------|
|
||||
| `task_not_found` | 任务 ID 不存在 |
|
||||
| `already_claimed` | 已被其他 Agent 认领 |
|
||||
| `already_resolved` | 任务已标记 completed |
|
||||
| `blocked` | blockedBy 列表中有未完成的任务 |
|
||||
| `agent_busy` | 该 Agent 已拥有其他未完成任务（仅 `checkAgentBusy` 模式） |
|
||||
|
||||
## Agent 团队的任务生命周期
|
||||
|
||||
在 swarms 模式下，任务系统的生命周期是这样的：
|
||||
|
||||
```
|
||||
Leader 创建团队
|
||||
↓
|
||||
Leader 用 TaskCreate 创建任务（status=pending, owner=undefined）
|
||||
↓
|
||||
Leader 用 TaskUpdate 设置依赖关系（addBlocks/addBlockedBy）
|
||||
↓
|
||||
Teammate 调用 TaskList → 发现可认领的任务
|
||||
↓
|
||||
Teammate 调用 TaskUpdate(taskId, {status: "in_progress"})
|
||||
→ 自动设置 owner 为 teammate 名称
|
||||
→ Leader 通过 mailbox 收到 task_assignment 通知
|
||||
↓
|
||||
Teammate 完成工作 → TaskUpdate(taskId, {status: "completed"})
|
||||
→ tool_result 提示 "Call TaskList to find your next available task"
|
||||
→ 依赖此任务的其他任务自动解锁
|
||||
↓
|
||||
Teammate 异常退出 → unassignTeammateTasks()
|
||||
→ 未完成任务被重置为 pending + owner=undefined
|
||||
→ Leader 收到通知并重新分配
|
||||
```
|
||||
|
||||
### Hooks 集成
|
||||
|
||||
TaskCreate 和 TaskUpdate 都集成了 hooks 系统：
|
||||
|
||||
- **创建时**：`executeTaskCreatedHooks` — 外部钩子可以阻断任务创建（blockingError 导致任务被立即删除）
|
||||
- **完成时**：`executeTaskCompletedHooks` — 外部钩子可以阻断任务标记为完成
|
||||
|
||||
这允许外部系统（CI、审批流）参与任务状态机。
|
||||
|
||||
## activeForm：终端 UX 的细节
|
||||
|
||||
每个任务有两个文案字段：
|
||||
|
||||
- `subject`：祈使句，用于任务列表展示（"Fix auth bug"）
|
||||
- `activeForm`：进行时形式，用于 spinner 动画（"Fixing auth bug..."）
|
||||
|
||||
当 `activeForm` 缺省时，spinner 回退显示 `subject`。这个看似微小的设计确保了用户在等待时看到的是"正在做什么"而非"要做什么"。
|
||||
|
||||
## Plan Mode 与任务系统的配合
|
||||
|
||||
Plan Mode（计划模式）和任务系统是互补但独立的机制：
|
||||
|
||||
1. Plan Mode 限制工具集为只读（搜索、阅读），迫使 AI 先理解再行动
|
||||
2. AI 在 Plan Mode 中用 TaskCreate 建立任务列表
|
||||
3. 用户审批后退出 Plan Mode
|
||||
4. AI 按 `blockedBy` 拓扑序逐项执行，每项用 TaskUpdate 标记进度
|
||||
|
||||
`shouldDefer: true` 属性确保这些工具调用不会触发权限确认弹窗——任务管理操作始终自动批准，因为它们不产生副作用。
|
||||
206
docs/tools/what-are-tools.mdx
Normal file
206
docs/tools/what-are-tools.mdx
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
title: "工具系统设计 - AI 如何从说到做"
|
||||
description: "深入理解 Claude Code 的 Tool 抽象设计：从类型定义、注册机制、调用链路到渲染系统，揭示 50+ 内置工具如何通过统一的 Tool 接口协同工作。"
|
||||
keywords: ["工具系统", "Tool 抽象", "AI 工具", "function calling", "buildTool", "getTools"]
|
||||
---
|
||||
|
||||
{/* 本章目标：基于 src/Tool.ts 和 src/tools.ts 揭示工具系统的完整架构 */}
|
||||
|
||||
## AI 为什么需要工具
|
||||
|
||||
大语言模型本质上只能做一件事：**根据输入文本，生成输出文本**。
|
||||
|
||||
它不能读文件、不能执行命令、不能搜索代码。要让 AI 真正"动手"，需要一个桥梁——这就是 **Tool**（工具）。
|
||||
|
||||
工具是 AI 的双手。AI 说"我想读这个文件"，工具系统替它真正去读；AI 说"我想执行这条命令"，工具系统替它真正去跑。
|
||||
|
||||
## Tool 类型：35 个字段的统一接口
|
||||
|
||||
所有工具都实现 `src/Tool.ts:362` 的 `Tool<Input, Output, Progress>` 类型。这不是一个 class，而是一个包含 35+ 字段的**结构化类型**（structural typing），任何满足该接口的对象就是一个工具：
|
||||
|
||||
### 核心四要素
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | `string` | 唯一标识（如 `Read`、`Bash`、`Agent`） |
|
||||
| `description()` | `(input) => Promise<string>` | **动态描述**——根据输入参数返回不同描述（如 `Execute skill: ${skill}`） |
|
||||
| `inputSchema` | `z.ZodType` | Zod schema，定义参数类型和校验规则 |
|
||||
| `call()` | `(args, context, canUseTool, parentMessage, onProgress?) => Promise<ToolResult<Output>>` | 执行函数 |
|
||||
|
||||
### 注册与发现
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `aliases` | 别名数组（向后兼容重命名） |
|
||||
| `searchHint` | 3-10 词的短语，供 ToolSearch 关键词匹配（如 `"jupyter"` for NotebookEdit） |
|
||||
| `shouldDefer` | 是否延迟加载（配合 ToolSearch 按需加载） |
|
||||
| `alwaysLoad` | 永不延迟加载（如 SkillTool 必须在 turn 1 可见） |
|
||||
| `isEnabled()` | 运行时开关（如 PowerShellTool 检查平台） |
|
||||
|
||||
### 安全与权限
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `validateInput()` | 输入校验（在权限检查之前），返回 `ValidationResult` |
|
||||
| `checkPermissions()` | 权限检查（在校验之后），返回 `PermissionResult` |
|
||||
| `isReadOnly()` | 是否只读操作（影响权限模式） |
|
||||
| `isDestructive()` | 是否不可逆操作（删除、覆盖、发送） |
|
||||
| `isConcurrencySafe()` | 相同输入是否可以并行执行 |
|
||||
| `preparePermissionMatcher()` | 为 Hook 的 `if` 条件准备模式匹配器 |
|
||||
| `interruptBehavior()` | 用户中断时的行为：`'cancel'` 或 `'block'` |
|
||||
|
||||
### 输出与渲染
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `maxResultSizeChars` | 结果字符上限（超出则持久化到磁盘，如 `100_000`） |
|
||||
| `mapToolResultToToolResultBlockParam()` | 将 Output 映射为 API 格式的 `ToolResultBlockParam` |
|
||||
| `renderToolResultMessage()` | React 组件渲染工具结果到终端 |
|
||||
| `renderToolUseMessage()` | React 组件渲染工具调用过程 |
|
||||
| `backfillObservableInput()` | 在不破坏 prompt cache 的前提下回填可观察字段 |
|
||||
|
||||
### 上下文与 Prompt
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `prompt()` | 返回该工具的详细使用说明，注入到 System Prompt |
|
||||
| `outputSchema` | 输出 Zod schema（用于类型安全的结果处理） |
|
||||
| `getPath()` | 提取操作的文件路径（用于权限匹配和 UI 显示） |
|
||||
|
||||
## 工具注册：`getTools()` 的分层组装
|
||||
|
||||
`src/tools.ts` 的 `getAllBaseTools()`（第 191 行）是工具注册的核心：
|
||||
|
||||
```
|
||||
固定工具（始终可用）:
|
||||
AgentTool, BashTool, FileReadTool, FileEditTool, FileWriteTool,
|
||||
NotebookEditTool, WebFetchTool, WebSearchTool, TodoWriteTool,
|
||||
AskUserQuestionTool, SkillTool, EnterPlanModeTool, ExitPlanModeV2Tool,
|
||||
TaskOutputTool, BriefTool, ListMcpResourcesTool, ReadMcpResourceTool
|
||||
|
||||
条件工具（运行时检查）:
|
||||
← hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]
|
||||
← isTodoV2Enabled() ? V2 Tasks : []
|
||||
← isWorktreeModeEnabled() ? Worktree : []
|
||||
← isAgentSwarmsEnabled() ? Teams : []
|
||||
← isToolSearchEnabled() ? ToolSearch: []
|
||||
← isPowerShellToolEnabled() ? PowerShell: []
|
||||
|
||||
Feature-flag 工具:
|
||||
← feature('COORDINATOR_MODE') ? [coordinatorMode tools]
|
||||
← feature('KAIROS') ? [SleepTool, SendUserFileTool, ...]
|
||||
← feature('WEB_BROWSER_TOOL') ? [WebBrowserTool]
|
||||
← feature('HISTORY_SNIP') ? [SnipTool]
|
||||
|
||||
Ant-only 工具:
|
||||
← process.env.USER_TYPE === 'ant' ? [REPLTool, ConfigTool, TungstenTool]
|
||||
```
|
||||
|
||||
`getTools()`（第 269 行）在 `getAllBaseTools()` 基础上应用权限过滤：
|
||||
|
||||
```typescript
|
||||
export const getTools = (permissionContext): Tools => {
|
||||
const base = getAllBaseTools()
|
||||
// 过滤 blanket deny 规则命中的工具
|
||||
return filterToolsByDenyRules(base, permissionContext)
|
||||
}
|
||||
```
|
||||
|
||||
**关键设计**：工具列表在每次 API 调用时组装（而非全局缓存），因为 `isEnabled()` 的结果可能随运行时状态变化。
|
||||
|
||||
## `buildTool()` 工厂函数
|
||||
|
||||
大多数工具通过 `buildTool()` 创建（`src/Tool.ts:721`），它是一个类型安全的构造器：
|
||||
|
||||
```typescript
|
||||
export const BashTool: Tool<...> = buildTool({
|
||||
name: 'Bash',
|
||||
inputSchema: lazySchema(() => z.object({command: z.string(), ...})),
|
||||
// ...其他字段
|
||||
}) satisfies ToolDef<Input, Output, Progress>
|
||||
```
|
||||
|
||||
`satisfies ToolDef` 确保编译时类型检查，`lazySchema` 延迟 Zod schema 解析（避免循环依赖）。
|
||||
|
||||
## 工具调用的完整链路
|
||||
|
||||
从 AI 发出 `tool_use` 到结果回传，经过以下步骤：
|
||||
|
||||
```
|
||||
1. API 返回 tool_use block（包含 name + input）
|
||||
↓
|
||||
2. StreamingToolExecutor.addTool() / runTools()
|
||||
↓
|
||||
3. findToolByName() 查找工具
|
||||
↓
|
||||
4. validateInput() — 输入校验
|
||||
↓ 失败 → 返回错误 tool_result
|
||||
5. canUseTool() — 权限 UI（Ask 模式下弹确认）
|
||||
↓ 拒绝 → 返回拒绝 tool_result
|
||||
6. checkPermissions() — 规则匹配
|
||||
↓
|
||||
7. call() — 执行实际操作
|
||||
↓ onProgress() 回调实时更新 UI
|
||||
8. 返回 ToolResult<Output>
|
||||
↓
|
||||
9. mapToolResultToToolResultBlockParam() — 转为 API 格式
|
||||
↓
|
||||
10. 新消息追加到对话 → 进入下一轮迭代
|
||||
```
|
||||
|
||||
## 工具结果的预算控制
|
||||
|
||||
每个工具通过 `maxResultSizeChars` 声明输出上限：
|
||||
|
||||
- **BashTool**：`30_000`（命令输出）
|
||||
- **SkillTool**：`100_000`（技能执行结果）
|
||||
- **FileReadTool**：`Infinity`（文件内容不走持久化，避免 Read→file→Read 循环）
|
||||
|
||||
超出上限的结果被 `applyToolResultBudget()`（`src/utils/toolResultStorage.ts`）持久化到磁盘，AI 只收到预览 + 文件路径。
|
||||
|
||||
## MCP 工具的扩展
|
||||
|
||||
MCP Server 提供的工具通过 `mcpInfo` 字段标记来源：
|
||||
|
||||
```typescript
|
||||
mcpInfo?: { serverName: string; toolName: string }
|
||||
```
|
||||
|
||||
MCP 工具的 `inputJSONSchema` 直接使用 JSON Schema（而非 Zod），因为 schema 来自远程协议。它们通过 `filterToolsByDenyRules()` 支持 `mcp__server` 前缀的 blanket deny 规则。
|
||||
|
||||
## 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>
|
||||
|
||||
## 工具的可视化渲染
|
||||
|
||||
工具不仅能"做事"，还能"展示"。每个工具通过 React 组件定义 UI 渲染：
|
||||
|
||||
- **FileEdit** → `renderToolResultMessage` 展示语法高亮的 diff 视图
|
||||
- **Bash** → 实时显示命令输出（通过 `onProgress` 回调），带进度指示
|
||||
- **Grep** → 高亮匹配结果，显示文件路径和行号链接
|
||||
- **Agent** → 显示子 Agent 的进度条和状态
|
||||
- **SkillTool** → 渲染技能执行进度
|
||||
|
||||
`isSearchOrReadCommand()` 允许工具声明自己是搜索/读取操作，触发 UI 的折叠显示模式（避免大量搜索结果占满屏幕）。
|
||||
|
||||
`getActivityDescription()` 为 spinner 提供活动描述（如 "Reading src/foo.ts"、"Running bun test"），替代默认的工具名显示。
|
||||
Reference in New Issue
Block a user