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 字段区分来源
|