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 响应结构

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 中注册新路由：

from app.routers import tools as tools_router
app.include_router(tools_router.router, prefix="/api", tags=["tools"])

5. 产出要求

GET /api/tools 接口可调用，返回完整工具列表
两套工具体系元数据正确聚合
统计数据（调用次数、错误率）正确返回
按 category 分组，source 字段区分来源

3.0 KiB Raw Blame History Unescape Escape