feat(temple): add Temple modal with Tools browser and Skills management

2026-04-08 16:46:02 +08:00
parent 51e38e039b
commit aa12c92a5a
12 changed files with 2571 additions and 41 deletions
--- a/development-doc/plan/temple-update/phase-1-tools-api.md
+++ b/development-doc/plan/temple-update/phase-1-tools-api.md
@@ -0,0 +1,135 @@
+# 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 字段区分来源