第五篇：工具系统深度解析，199个工具的架构与安全

📚 系列文章 05/10 · ⏱️ 阅读时间约 18 分钟

🏗️ 一、工具架构：buildTool 模式

Claude Code 所有工具都遵循统一模式------通过 buildTool() 工厂函数构建：

typescript 复制代码

// src/Tool.ts
export const MCPTool = buildTool({
  isMcp: true,
  name: 'mcp',
  maxResultSizeChars: 100_000,

  async description() {
    return DESCRIPTION  // 动态描述，支持条件返回
  },

  async inputSchema() { /* JSON Schema */ },
  async outputSchema() { /* 输出格式 */ },

  async validate(input, context) {
    // 权限检查
    if (!context.permissions.canRun(input)) {
      return { result: false, errorCode: 403 }
    }
    return { result: true }
  },

  async execute(input, progress, context) {
    // 实际执行逻辑
    return { content: [...] }
  }
})

这个模式有几个精妙设计：

动态描述：description() 是异步函数，可以根据输入返回不同描述
Schema 验证：input/output 通过 Zod Schema 定义，自动校验
进度回调：progress() 用于流式输出（长命令可以实时显示进度）
上下文注入：context 包含权限、会话、文件系统等运行时信息

🔒 二、安全体系：三层权限模型

这是 Claude Code 工具系统最值得学习的部分------一套完整的安全架构。

2.1 权限模式

typescript 复制代码

// src/types/permissions.ts
export type PermissionMode =
  | 'read'     // 只读（不修改文件、不执行危险命令）
  | 'bypass'   // 完全信任（跳过所有确认）
  | 'auto'     // 自动（危险操作会弹窗确认）
  | 'deny'     // 完全禁用

2.2 Bash 安全检查链

BashTool 的安全检查极其严格，经过 6 层验证：

text 复制代码

1. 白名单检查（COMMAND_ALLOWLIST）
   只允许明确列出的命令，未知命令直接拒绝

2. 标志位验证
   例如：git checkout -b 允许，git checkout --force 不允许

3. 路径验证（pathValidation.ts）
   禁止访问 ~/.ssh/、/etc/passwd 等敏感路径

4. 只读检查（readOnlyValidation.ts）
   网络请求、磁盘写入等被标记为 destructive

5. 破坏性命令警告（destructiveCommandWarning.ts）
   rm -rf / 等危险命令触发警告

6. 沙箱检查（shouldUseSandbox.ts）
   高风险命令在沙箱中执行

⚠️ 安全边界 ：Claude Code 内置了 2400+ 行安全代码。COMMAND_ALLOWLIST 声明式地列出每个允许的命令和它的合法标志位，比黑名单模式安全得多。

2.3 文件系统权限

typescript 复制代码

// src/utils/permissions/filesystem.js
// 每个文件操作都经过权限检查
export function checkFileAccess(
  path: string,
  operation: 'read' | 'write' | 'delete',
  permissions: PermissionSettings
): PermissionResult {
  // 1. 检查是否在允许目录内
  if (!isInAllowedDirectory(path, permissions.allow)) {
    return { allowed: false, reason: 'denied' }
  }

  // 2. 检查是否在禁止目录内
  if (isInDeniedDirectory(path, permissions.deny)) {
    return { allowed: false, reason: 'denied' }
  }

  // 3. 写操作需要明确授权
  if (operation === 'write' && permissions.mode !== 'bypass') {
    return { allowed: false, reason: 'needsConfirmation' }
  }

  return { allowed: true }
}

📁 三、文件操作工具族

3.1 FileReadTool（读文件）

支持偏移量和行数限制，避免一次性读取大文件导致内存爆炸。

3.2 FileEditTool（编辑文件）

这是最复杂的工具之一，核心是 sed 语义的实现：

typescript 复制代码

// src/tools/FileEditTool/utils.ts
// 支持三种编辑模式
export type EditMode =
  | { type: 'replace', path, oldStr, newStr }      // 字符串替换
  | { type: 'insert', path, after, newStr }         // 指定位置后插入
  | { type: 'create', path, content }               // 创建新文件

3.3 GlobTool + GrepTool（代码搜索）

text 复制代码

// GlobTool：通配符文件搜索
// 支持：**/*.ts、**/node_modules/**、src/**/*.js

// GrepTool：正则表达式全文搜索
// 支持：上下文行数、正则表达式、大小写敏感

⚡ 四、命令执行工具

4.1 BashTool vs PowerShellTool

Claude Code 同时支持 Linux/Bash 和 Windows/PowerShell：

text 复制代码

// Bash 特殊安全检查：
// - 管道重定向安全
// - 环境变量过滤（LD_*, DYLD_* 被阻止）
// - here-doc 解析安全

// PowerShell 特殊安全检查：
// - ExecutionPolicy 检查
// - Git 安全命令白名单
// - 脚本签名验证

4.2 命令分类

typescript 复制代码

// src/tools/BashTool/readOnlyValidation.ts
// 声明式命令配置
const COMMAND_ALLOWLIST = {
  'cat': { flags: { '-n': 'none', '-b': 'none' } },
  'ls': { flags: { '-l': 'none', '-a': 'none', '-R': 'none' } },
  'grep': { flags: { '-r': 'none', '-n': 'string' } },
  'git': {
    'status': { flags: {} },        // 读，自动允许
    'diff': { flags: { '--stat': 'none' } },
    'log': { flags: { '--oneline': 'none' } },
    'branch': { flags: {} },
    'commit': { flags: { '-m': 'string' }, needsConfirm: true },
    'push': { flags: {}, needsConfirm: true },
    'checkout': { flags: { '-b': 'string' }, needsConfirm: true },
  },
}

🌐 五、网络工具

5.1 WebSearchTool

typescript 复制代码

name: 'web_search',
input: { query: string, recency_days?: number }
output: { results: Array<{ title, url, snippet }> }

5.2 WebFetchTool

typescript 复制代码

// 限制：只能访问预批准域名列表（preapproved.ts）
// 防止 SSRF 攻击（服务器端请求伪造）

// 禁止：内网 IP（10.x、172.16.x、192.168.x）
// 禁止：localhost、127.0.0.1

💡 为什么 WebFetch 有域名白名单？

SSRF（服务器端请求伪造）是严重安全漏洞。Claude Code 防止 AI 被诱导访问内网服务盗取数据。

🤖 六、AgentTool：子 Agent 系统

这是 Claude Code 最独特的能力------让一个 AI Agent 去启动另一个 Agent：

typescript 复制代码

// src/tools/AgentTool/
// 内置 5 种 Agent 类型
const builtInAgents = [
  GENERAL_PURPOSE_AGENT,   // 通用任务执行
  PLAN_AGENT,             // 规划模式
  EXPLORE_AGENT,          // 代码探索
  VERIFICATION_AGENT,     // 验证任务
  CLAUDECODE_GUIDE_AGENT, // 使用指南
]

// 子 Agent 可以并发启动（forkSubagent.ts）
// 每个子 Agent 有独立上下文
// 主 Agent 汇总子 Agent 结果继续工作

使用场景示例：

复制代码

主 Agent："重构这个项目"
  → EXPLORE_AGENT：分析代码结构
  → VERIFICATION_AGENT：写测试用例
  → PLAN_AGENT：生成重构计划
  → 主 Agent 汇总结果，执行修改

🔌 七、MCP 工具集成

Model Context Protocol（MCP）是 Claude Code 连接外部工具的标准协议：

typescript 复制代码

// src/tools/MCPTool/MCPTool.ts
// Claude Code 内置 MCP 客户端
// 连接外部 MCP 服务器（任何实现了 MCP 协议的工具）

class MCPClient {
  async connect(serverConfig: MCPConfig): Promise<void> {
    const connection = await createMCPConnection(serverConfig)
    this.servers.set(serverConfig.name, connection)

    // 注册该服务器提供的所有工具
    const tools = await connection.listTools()
    for (const tool of tools) {
      registerTool(`mcp_${serverConfig.name}_${tool.name}`, tool)
    }
  }
}

📋 八、工具分类速查表

类别	工具	权限级别
文件读	FileRead, Glob, Grep, Bash(cat/ls)	只读，自动允许
文件写	FileWrite, FileEdit	需写权限
命令执行	Bash, PowerShell	白名单+沙箱
Git	git status/diff/log	只读，自动
Git写	git commit/push/checkout	需确认
网络	WebSearch, WebFetch	域名白名单
代码	LSPTool（语法分析/跳转/补全）	只读
Agent	AgentTool（子Agent启动）	需确认
MCP	MCPTool（外部工具集成）	动态权限
任务	TaskCreate/Get/List/Stop/Update	需确认
计划	EnterPlanMode, ExitPlanMode	自动
配置	ConfigTool, SkillTool	需确认
杂项	TodoWrite, Brief, WebSearch, Sleep	各异

🏛️ 九、工具系统架构总结

复制代码

用户输入（自然语言）
    │
    ▼
chat.ts（对话引擎）
    │
    ▼
toolExecution.ts（工具编排）
    │
    ├─► 分组：依赖分析（无依赖 → 并行）
    │
    ├─► 权限检查（validate）
    │     ├─► pathValidation（路径安全）
    │     ├─► readOnlyValidation（只读检查）
    │     ├─► bashSecurity（命令白名单）
    │     └─► destructiveCommandWarning（危险警告）
    │
    ├─► 用户确认（needsConfirm）
    │
    └─► execute（实际执行）
          ├─► 文件工具（filesystem API）
          ├─► Bash工具（spawn child process）
          ├─► Agent工具（fork sub-agent）
          ├─► MCP工具（mcpClient）
          └─► 网络工具（fetch/搜索API）

📋 总结

本篇深入了 Claude Code 工具系统的核心架构：

✅ buildTool 模式：统一工具接口，支持动态描述、Schema 验证、流式进度
✅ 三层权限模型：read / auto / bypass / deny，完整覆盖只读和破坏性操作
✅ Bash 安全：2400+ 行安全代码，声明式命令白名单
✅ 文件安全：路径验证 + 目录白名单，防止越权访问
✅ Agent 系统：内置 5 种 Agent，支持并发 fork 子任务
✅ MCP 集成：通过 Model Context Protocol 连接任意外部工具
✅ 199 个工具：覆盖文件、命令、Git、网络、代码分析、任务计划全部场景

💡 设计精华 ：Claude Code 的工具系统本质是一个安全沙箱 + 权限网关 + 执行引擎。AI 模型负责决策「用什么工具」，而工具系统负责确保这些决策安全可控。这套架构值得在任何 AI Agent 项目中借鉴。

📅 下篇预告

深入解析 代码理解系统------LSPTool 如何实现语法分析、符号跳转、自动补全？敬请期待！

#ClaudeCode #工具系统 #安全架构 #权限模型 #MCP