0fdc0acf91
对照 0.7 BREAKING CHANGE 逐文件复核 docs/，移除/修正已下线功能的描述： - 移除 LightRAG、独立图谱上传、Ollama、旧版 v1 模型配置等已删除能力的描述 - 知识库类型更新为 Milvus + 只读连接器（Dify、Notion），补全图谱存储链路 （Neo4j + PostgreSQL + Milvus 语义索引，RRF 融合） - 补全知识库工具集（find_kb_document/open_kb_document），修正 Skills 沙盒路径 为 /home/gem/skills、中间件目录为 agents/middlewares、评估入口为侧边栏 tab - 知识库权限三档修正为 全局共享/部门共享/指定人可访问 - 下载版本统一为 0.7.0.dev0 - README 新增简介、技术栈与 0.7 动态，特性描述细化 经核实保留 Neo4j（仍用于 Milvus 知识库内图谱）与 MCP enabled 机制（仍在用）， 未误删。vitepress build 验证通过。
107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
# 工具系统
|
||
|
||
Yuxi 的工具系统基于注册机制，支持多种工具类型的动态组装。
|
||
|
||
## 工具注册机制
|
||
|
||
Yuxi 的工具系统采用 `@tool` 装饰器注册机制，核心位于 `backend/package/yuxi/agents/toolkits/registry.py`。
|
||
|
||
### @tool 装饰器
|
||
|
||
```python
|
||
from yuxi.agents.toolkits.registry import tool
|
||
|
||
@tool(category="buildin", tags=["计算"], display_name="计算器")
|
||
def calculator(a: float, b: float, operation: str) -> float:
|
||
"""计算器：对给定的2个数字进行基本数学运算"""
|
||
...
|
||
```
|
||
|
||
装饰器参数：
|
||
- **category**: 工具分类，用于分组（`buildin`、`mysql`、`debug`）
|
||
- **tags**: 标签列表，用于前端展示
|
||
- **display_name**: 显示名称（给人看的名字）
|
||
- **icon**: 图标名称（可选）
|
||
|
||
### 自动发现
|
||
|
||
导入 `toolkits` 包时会自动触发注册：
|
||
|
||
```python
|
||
from yuxi.agents.toolkits import buildin, mysql # 触发 @tool 装饰器执行
|
||
```
|
||
|
||
`toolkits/__init__.py` 中已包含 `buildin`、`mysql`、`debug` 模块的导入，这些模块加载时会自动注册所有带 `@tool` 装饰器的函数。
|
||
|
||
## 工具分类
|
||
|
||
### 内置工具 (buildin)
|
||
|
||
| 工具 | 说明 |
|
||
|------|------|
|
||
| `calculator` | 计算器，支持加减乘除 |
|
||
| `ask_user_question` | 向用户发起交互式提问 |
|
||
| `present_artifacts` | 展示 Agent 沙盒 outputs 目录下的产物文件 |
|
||
| `tavily_search` | Tavily 网页搜索（需配置 `TAVILY_API_KEY`） |
|
||
|
||
Qwen-Image 生成能力已迁移为内置 Skill `image-gen`。模型调用与图片下载在 Agent 沙盒中完成，生成后的图片保存到 `/home/gem/user-data/outputs/`，再通过 `present_artifacts` 展示。
|
||
|
||
### MySQL 工具 (mysql)
|
||
|
||
| 工具 | 说明 |
|
||
|------|------|
|
||
| `mysql_list_tables` | 列出数据库中所有表 |
|
||
| `mysql_describe_table` | 获取表结构信息 |
|
||
| `mysql_query` | 执行只读 SQL 查询 |
|
||
|
||
### 知识库工具 (kbs)
|
||
|
||
知识库工具通过 `get_common_kb_tools()` 获取，不通过 `@tool` 装饰器注册：
|
||
|
||
```python
|
||
from yuxi.agents.toolkits.kbs import get_common_kb_tools
|
||
|
||
kb_tools = get_common_kb_tools()
|
||
# 返回: [list_kbs, get_mindmap, query_kb, find_kb_document, open_kb_document]
|
||
```
|
||
|
||
| 工具 | 说明 |
|
||
|------|------|
|
||
| `list_kbs` | 列出用户可访问的知识库 |
|
||
| `get_mindmap` | 获取知识库的思维导图结构 |
|
||
| `query_kb` | 在指定知识库中检索内容，返回结构化的 `resource_id`（即 `kb_id`）/`file_id`/`chunk` |
|
||
| `find_kb_document` | 在已知文件内按关键词或正则定位内容 |
|
||
| `open_kb_document` | 按 `file_id` 分段打开知识库文档（默认窗口 1800 行） |
|
||
|
||
## 工具组装
|
||
|
||
工具组装在 `RuntimeConfigMiddleware` 中完成。根据上下文配置筛选工具：
|
||
|
||
1. **基础工具**：从 `context.tools` 中按名称筛选
|
||
2. **MCP 工具**：根据 `context.mcps` 加载 MCP 服务器工具
|
||
3. **知识库工具**：由 `KnowledgeBaseMiddleware` 独立处理
|
||
|
||
```python
|
||
# 中间件中的工具筛选逻辑
|
||
async def get_tools_from_context(self, context) -> list:
|
||
selected_tools = []
|
||
|
||
# 1. 基础工具
|
||
for tool_name in context.tools or []:
|
||
if tool_name in tools_map:
|
||
selected_tools.append(tools_map[tool_name])
|
||
|
||
# 2. MCP 工具
|
||
for server_name in context.mcps or []:
|
||
mcp_tools = await get_enabled_mcp_tools(server_name)
|
||
selected_tools.extend(mcp_tools)
|
||
|
||
return selected_tools
|
||
```
|
||
|
||
## Skills 集成
|
||
|
||
Skills 与工具是两种不同的扩展机制。工具是具体的功能实现，而 Skills 是包含提示词、工具依赖和元数据的完整技能包。通过 `context.skills` 配置 Skills 时，对应的技能文件会被挂载到沙盒的 `/home/gem/skills/<slug>/...`，智能体可以通过读取 SKILL.md 来了解如何使用这些技能。
|
||
|
||
关于 Skills 的详细机制，请参阅 [Skills 管理](./skills-management.md)。
|