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