工具管理
工具管理
概述
工具是 Agent 执行操作的"手脚"。系统提供 19 项内置工具，并支持通过 MCP 协议、OpenAPI 定义和技能扩展工具集。工具管理页面用于配置和管理所有可用工具。
19 项内置工具
文件操作类（7 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| Read File | 读取文件内容，支持行号范围，上限 5MB | P0（自动执行） |
| Write File | 写入文件，不存在则自动创建含父目录 | P0 |
| Edit | 对已有文件进行局部修改（搜索替换模式） | P0 |
| MultiEdit | 对已有文件进行多处批量修改 | P0 |
| List Directory | 列出目录文件和子目录，显示文件大小 | P0（锁定） |
| Glob Files | 按通配符模式搜索文件，最多 100 条结果 | P0（锁定） |
| Search Files | 在文件内容中按正则搜索，最多 250 条结果 | P0（锁定） |
命令执行类（1 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| Bash | 执行 Shell 命令、脚本、Git 操作，超时 120 秒，输出上限 50KB | P1（首次确认） |
网络类（1 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| Web Fetch | 获取 URL 内容转为 Markdown，自动去噪，15 分钟缓存 | P1 |
任务管理类（1 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| Task Manage | 管理结构化任务列表（待办/进行中/已完成），3 步以上任务自动调用 | P0（锁定） |
技能调用类（1 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| Skill | 调用已安装的 Skill 模块执行专项任务 | P1 |
用户交互类（1 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| AskUserQuestion | Agent 向用户发起提问（最多 4 个问题，每个 2-10 个选项） | P0（锁定） |
子代理类（3 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| create_local_sub_agent | 在本节点创建临时子代理，支持 1-3 级嵌套 | P0 |
| dispatch_sub_agent | 派发任务给已注册的子代理 | P0 |
| dispatch_multi_node_agent | 通过 Gateway 派发任务到远程节点 | P0 |
记忆类（4 项）
| 工具 | 功能 | 安全级别 |
|---|---|---|
| Conversation Search | 按关键词搜索历史对话，支持时间范围过滤，最多 10 条 | P0（锁定） |
| Recent Chats | 列出最近 1-20 条对话会话，支持时间筛选 | P0（锁定） |
| Memory Query | 搜索已存储的用户记忆（语义搜索 + 图谱扩展） | P0（锁定） |
| Memory Manage | 添加、更新或删除用户记忆 | P1 |
安全级别说明
| 级别 | 含义 | 行为 |
|---|---|---|
| P0 | 安全操作 | 自动执行，无需用户确认 |
| P1 | 需要确认 | 首次调用时弹出权限确认 |
| P2 | 每次确认 | 每次调用都需要用户确认 |
| 锁定 | 不可降级 | 安全级别固定，不可调整 |
管理员可在安全护栏中调整非锁定工具的权限级别（组织下限），个人可在 APP 运行时安全中进一步收紧。
MCP 工具协议
**MCP（Model Context Protocol）**是标准化的 AI 工具通信协议，支持通过外部服务扩展工具集。
三种传输方式
| 传输 | 说明 | 适用场景 |
|---|---|---|
| stdio | 本地子进程通信（command + args） | 本地 CLI 工具 |
| SSE | Server-Sent Events（HTTP 长连接） | 远程服务 |
| HTTP | Streamable HTTP API | 远程服务 |
五种认证模式
| 认证 | 说明 |
|---|---|
| none | 无认证 |
| bearer | Bearer Token |
| basic | HTTP Basic Auth |
| service | 服务间认证 |
| oauth2 | OAuth2 授权码流程（自动发现 well-known 端点） |
MCP 管理界面
通过 McpManager 组件管理 MCP 服务器：
- 添加服务器：配置名称、传输方式、连接参数、认证方式
- 编辑/删除：修改或移除已有配置
- 启用/禁用：切换服务器可用状态
- 工具发现：连接后自动发现服务器提供的工具列表
安全隔离
MCP 子进程仅传递白名单环境变量，防止 API Key 等敏感信息泄露。
API 工具
支持从 OpenAPI/Swagger 文档自动解析并创建工具：
| 功能 | 说明 |
|---|---|
| 自动解析 | 从 OpenAPI 规范提取端点、参数 Schema |
| 认证配置 | 五种认证模式 |
| 模板变量 | {{variable}} 动态替换 |
| HTTP 方法 | GET / POST / PUT / DELETE / PATCH |
自定义工具目录 NEW
系统新增 ToolDirectoryManager —— 管理 {dataDir}/TOOLs/{orgId}/_custom/ 目录下的自定义工具，无需重启 APP即可加载。
目录结构
{dataDir}/TOOLs/{orgId}/_custom/
├── my-tool-1/
│ ├── metadata.json
│ └── ...
└── my-tool-2/
├── metadata.json
└── ...
{dataDir}/TOOLs/{orgId}/_custom/
├── my-tool-1/
│ ├── metadata.json
│ └── ...
└── my-tool-2/
├── metadata.json
└── ...
此代码块在浮窗中显示
metadata.json 示例
{
"id": "my-tool-1",
"name": "My Custom Tool",
"description": "自定义工具说明",
"type": "API",
"enabled": true,
"createdAt": 1776921208476,
"updatedAt": 1776921208476
}
{
"id": "my-tool-1",
"name": "My Custom Tool",
"description": "自定义工具说明",
"type": "API",
"enabled": true,
"createdAt": 1776921208476,
"updatedAt": 1776921208476
}
此代码块在浮窗中显示
加载机制
- 扫描方法：
scanAndLoad(orgId) - 类型支持：
API/MCP - 组织隔离：按 orgId 分目录，互不干扰
- 热加载：无需重启 APP
工具加载管线
所有工具按以下顺序加载并合并：
① 内置工具（19 项）
↓
② MCP 工具（从配置的 MCP 服务器发现）
↓
③ API 工具（从 OpenAPI 定义解析）
↓
④ 自定义工具（ToolDirectoryManager 扫描 _custom/ 目录）
↓
⑤ 技能工具（从启用的 Skills 注入 execute_skill_{id}）
↓
⑥ 合并去重 → 最终工具列表 → 发送给 LLM
① 内置工具（19 项）
↓
② MCP 工具（从配置的 MCP 服务器发现）
↓
③ API 工具（从 OpenAPI 定义解析）
↓
④ 自定义工具（ToolDirectoryManager 扫描 _custom/ 目录）
↓
⑤ 技能工具（从启用的 Skills 注入 execute_skill_{id}）
↓
⑥ 合并去重 → 最终工具列表 → 发送给 LLM
此代码块在浮窗中显示
常用工具的使用场景
| 用户请求示例 | Agent 调用的工具 | 说明 |
|---|---|---|
| "帮我看一下 package.json 的内容" | Read File | 读取并返回文件内容 |
| "把函数名从 getData 改为 fetchData" | Edit | 精确搜索替换 |
| "创建一个 README.md" | Write File | 创建新文件 |
| "项目里有哪些 .tsx 文件？" | Glob Files | 按模式搜索文件名 |
| "代码里哪里用到了 useEffect？" | Search Files | 在文件内容中正则搜索 |
| "帮我运行 npm install" | Bash | 执行 Shell 命令 |
| "帮我总结这个网页的内容：https://..." | Web Fetch | 抓取网页转 Markdown |
| "这个任务比较复杂，先列个计划" | Task Manage | 创建结构化任务清单 |
| "帮我搜索昨天关于数据库迁移的对话" | Conversation Search | 搜索历史对话 |
| "记住我偏好用 dark 主题" | Memory Manage | 存储到记忆 |
操作指南：添加 MCP 工具
- 打开 APP → 设置 → 工具 → MCP 工具区域
- 点击 添加 MCP 服务器
- 填写配置：
- 名称：为这个 MCP 服务器起一个识别名称
- 传输方式：选择 stdio / SSE / HTTP
- 如果是 stdio：填写命令（如
npx）和参数（如@anthropic/mcp-server-filesystem） - 如果是 SSE/HTTP：填写服务器 URL
- 如果需要认证，选择认证方式并填写凭证
- 点击 保存
- 系统自动连接服务器并发现可用工具
- 发现的工具出现在工具列表中，默认启用
提示：MCP 子进程仅传递白名单环境变量。如果 MCP 工具需要 API Key 等环境变量，需要在配置的 env 字段中显式声明。
工具禁用的影响
禁用某个工具后，Agent 在对话中完全不知道该工具的存在。这意味着：
| 禁用的工具 | 影响 |
|---|---|
| Bash | Agent 无法执行任何 Shell 命令（npm、git、编译等） |
| Read File / Write File | Agent 无法读取或创建文件 |
| Web Fetch | Agent 无法获取网页内容，搜索类技能也受影响 |
| Memory Query / Manage | Agent 不会查询或存储记忆 |
| Skill | Agent 无法调用任何技能模块 |
| create_local_sub_agent | Agent 无法创建子代理分解任务 |
建议：除非有明确的安全原因，不建议禁用核心文件操作工具（Read / Write / Edit / Glob / Search），否则 Agent 的任务执行能力会严重受限。
常见问题
Agent 说"我无法执行文件操作"
检查文件操作类工具（Read File、Write File、Edit 等）是否被禁用。在工具管理页面确认这些工具处于启用状态。
MCP 工具连接失败
- 确认 MCP 服务器的命令/URL 是否正确
- 如果是 stdio 方式，确认对应的命令已安装（如
npx需要 Node.js 环境） - 检查是否需要环境变量（API Key 等）
- 查看 APP 日志获取详细错误信息
Agent 没有使用我期望的工具
Agent 基于任务需求自主选择工具。如果 Agent 选择了"错误"的工具，可以在对话中明确指示："请使用 Bash 工具执行这个命令"。