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

# 《Crush 从入门到精通》第五章：Agent 工具系统详解 ## 工具系统架构 Crush 的工具系统基于 `charm.land/fantasy` 框架构建，采用插件化设计： ``` ┌─────────────────────────────────────────────────────────────┐ │ Fantasy 框架层 │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ fantasy.AgentTool 接口 │ │ │ │ - Name() string │ │ │ │ - Description() string │ │ │ │ - Parameters() any │ │ │ │ - Execute(ctx, params) ToolResponse │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 工具实现层 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 内置工具 │ │ MCP 工具 │ │ 自定义工具 │ │ │ │ (20+ 个) │ │ (动态加载) │ │ (未来支持) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 工具分类 | 分类 | 工具列表 | 功能描述 | |------|---------|---------| | 文件操作 | read, write, edit, glob | 文件读写、搜索 | | 内容搜索 | grep, rg | 代码内容搜索 | | 命令执行 | bash | Shell 命令执行 | | 网络操作 | fetch, web_fetch, web_search | HTTP 请求、网络搜索 | | 代码理解 | diagnostics, references | LSP 诊断、引用查找 | | 任务管理 | todos | 待办事项管理 | | 下载 | download | 文件下载 | --- ## 核心工具详解 ### Edit 工具 **功能**：精确编辑文件内容 ```go 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 工具 **功能**：在文件中搜索内容 ```go 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: ⚠️ 极高风险 │ │ │ │ [拒绝] [临时允许] [永久允许] │ └─────────────────────────────────────────────┘ ``` ### 配置权限 ```yaml permissions: skip_requests: false allowed_tools: - "read" - "write" - "edit" - "bash" - "grep" ``` --- *本文是《Crush 从入门到精通》系列文章的第五章*