《Crush 从入门到精通》第五章：Agent 工具系统详解

工具系统架构

Crush 的工具系统基于 charm.land/fantasy 框架构建，采用插件化设计：

┌─────────────────────────────────────────────────────────────┐
│                      Fantasy 框架层                          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              fantasy.AgentTool 接口                   │  │
│  │  - Name() string                                     │  │
│  │  - Description() string                              │  │
│  │  - Parameters() any                                 │  │
│  │  - Execute(ctx, params) ToolResponse                │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       工具实现层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  内置工具    │  │  MCP 工具    │  │  自定义工具  │       │
│  │  (20+ 个)   │  │  (动态加载)  │  │  (未来支持)  │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘

工具分类

核心工具详解

Edit 工具

功能：精确编辑文件内容

type EditParams struct {
    FilePath   string `json:"file_path"`   // 文件路径
    OldString  string `json:"old_string"`  // 要替换的旧内容
    NewString  string `json:"new_string"`  // 替换后的新内容
    ReplaceAll bool   `json:"replace_all"` // 是否全部替换
}

Bash 工具

功能：执行 Shell 命令

执行流程：
1. 接收命令
2. 权限检查
   ├─ 已授权？ ──▶ 直接执行
   └─ 未授权 ──▶ 请求用户确认
3. 命令执行
4. 返回结果

Grep 工具

功能：在文件中搜索内容

type GrepParams struct {
    Pattern   string   `json:"pattern"`    // 搜索模式
    Path      string   `json:"path"`       // 搜索路径
    Glob      string   `json:"glob"`       // 文件过滤
    IgnoreCase bool   `json:"ignore_case"` // 忽略大小写
    LineNumber bool   `json:"line_number"` // 显示行号
}

工具权限管理

权限系统架构

PermissionService
       │
       ├── Grant(permission)      ──▶ 授予临时权限
       ├── GrantPersistent()      ──▶ 授予持久权限
       ├── Deny(permission)       ──▶ 拒绝权限
       ├── Request(ctx, opts)     ──▶ 请求权限
       └── AutoApproveSession()   ──▶ 自动批准

权限请求流程

用户 ─▶ AI 请求执行 "rm -rf /" ─▶ 系统检测到危险操作
       │
       ▼
┌─────────────────────────────────────────────┐
│          显示权限请求对话框                   │
│  Tool: bash                                 │
│  Command: rm -rf /                         │
│  Risk: ⚠️ 极高风险                          │
│                                         │
│  [拒绝] [临时允许] [永久允许]                │
└─────────────────────────────────────────────┘

配置权限

permissions:
  skip_requests: false
  allowed_tools:
    - "read"
    - "write"
    - "edit"
    - "bash"
    - "grep"

本文是《Crush 从入门到精通》系列文章的第五章