136 lines
3.0 KiB
Markdown
136 lines
3.0 KiB
Markdown
|
# Phase 1：后端 Tools API 开发
|
|||
|
|
|
|||
|
|
日期：2026-04-08
|
|||
|
|
状态：待开始
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 本阶段目的
|
|||
|
|
|
|||
|
|
开发 `GET /api/tools` 接口，聚合两套工具体系的元数据，为前端 Tools Tab 提供数据源。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 核心文件
|
|||
|
|
|
|||
|
|
| 文件 | 作用 |
|
|||
|
|
|------|------|
|
|||
|
|
| `app/routers/tools.py` | 新建，Tools 路由 |
|
|||
|
|
| `app/schemas/tools.py` | 新建，Tools API Pydantic Schema |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. API 设计
|
|||
|
|
|
|||
|
|
### 3.1 接口
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GET /api/tools
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 响应结构
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class ToolCommand(BaseModel):
|
|||
|
|
name: str
|
|||
|
|
description: str
|
|||
|
|
parameters: dict # JSON Schema
|
|||
|
|
|
|||
|
|
class ToolStats(BaseModel):
|
|||
|
|
call_count: int
|
|||
|
|
error_count: int
|
|||
|
|
total_duration_ms: int
|
|||
|
|
avg_duration_ms: int
|
|||
|
|
error_rate: float
|
|||
|
|
|
|||
|
|
class ToolCategory(BaseModel):
|
|||
|
|
name: str # 显示用中文分类名
|
|||
|
|
source: str # "manifest" | "agent"
|
|||
|
|
tools: list[ToolInfo]
|
|||
|
|
|
|||
|
|
class ToolInfo(BaseModel):
|
|||
|
|
name: str
|
|||
|
|
display_name: str
|
|||
|
|
description: str
|
|||
|
|
category: str
|
|||
|
|
tags: list[str]
|
|||
|
|
enabled: bool
|
|||
|
|
source: str # "manifest" | "agent"
|
|||
|
|
commands: list[ToolCommand]
|
|||
|
|
stats: ToolStats | None
|
|||
|
|
|
|||
|
|
class ToolsResponse(BaseModel):
|
|||
|
|
categories: list[ToolCategory]
|
|||
|
|
summary: dict:
|
|||
|
|
total: int
|
|||
|
|
active: int
|
|||
|
|
by_source: dict
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 分类结构
|
|||
|
|
|
|||
|
|
按工具来源分为两大类：
|
|||
|
|
|
|||
|
|
**注册层（source: "manifest"）**
|
|||
|
|
|
|||
|
|
| Category Name | 来源 |
|
|||
|
|
|--------------|------|
|
|||
|
|
| `文件操作` | `manifests/file_operator.yaml` |
|
|||
|
|
| `任务管理` | `manifests/task_manager.yaml` |
|
|||
|
|
| `网页抓取` | `manifests/web_fetch.yaml` |
|
|||
|
|
| `联网搜索` | `manifests/web_search.yaml` |
|
|||
|
|
|
|||
|
|
**Agent 层（source: "agent"）**
|
|||
|
|
|
|||
|
|
| Category Name | 来源 |
|
|||
|
|
|--------------|------|
|
|||
|
|
| `文件工具` | `builtins/file_tools.py` |
|
|||
|
|
| `系统命令` | `builtins/system_tools.py` |
|
|||
|
|
| `开发工具` | `builtins/dev_tools.py` |
|
|||
|
|
| `协作工具` | `builtins/collaboration_tools.py` |
|
|||
|
|
| `知识检索` | `search.py` |
|
|||
|
|
| `日程管理` | `schedule.py` |
|
|||
|
|
| `任务管理` | `task.py` |
|
|||
|
|
| `论坛功能` | `forum.py` |
|
|||
|
|
| `时间推理` | `time_reasoning.py` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 实现逻辑
|
|||
|
|
|
|||
|
|
### 4.1 数据聚合流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
1. 从 ToolRegistry.list_all() 获取注册层工具元数据
|
|||
|
|
2. 扫描 app/agents/tools/ 下所有 @tool 装饰器，获取 Agent 层工具
|
|||
|
|
3. 合并两套数据，按 category 分组
|
|||
|
|
4. 调用 ToolRegistry.get_stats() 获取统计数据
|
|||
|
|
5. 返回聚合后的 categories + summary
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.2 Agent 层工具扫描
|
|||
|
|
|
|||
|
|
通过内省 `app/agents/tools/` 目录下所有 `@tool` 装饰的函数，提取：
|
|||
|
|
|
|||
|
|
- `__name__` → tool name
|
|||
|
|
- `__doc__` → description
|
|||
|
|
- `__annotations__` → parameters schema
|
|||
|
|
|
|||
|
|
### 4.3 注册路由
|
|||
|
|
|
|||
|
|
在 `app/main.py` 中注册新路由：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from app.routers import tools as tools_router
|
|||
|
|
app.include_router(tools_router.router, prefix="/api", tags=["tools"])
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 产出要求
|
|||
|
|
|
|||
|
|
- [x] `GET /api/tools` 接口可调用，返回完整工具列表
|
|||
|
|
- [x] 两套工具体系元数据正确聚合
|
|||
|
|
- [x] 统计数据（调用次数、错误率）正确返回
|
|||
|
|
- [x] 按 category 分组，source 字段区分来源
|