# 工具与自动测试 (Tools & Autotest) API

工具与自动测试 API 用于管理可用工具列表和自动测试功能。

## 基础信息

| 项目 | 值 |
|------|-----|
| Base URL | `/api/v1/tools` |
| 认证方式 | Bearer Token (预留) |

---

## 可用工具 (Tool Registry)

系统内置以下工具：

| 工具ID | 名称 | 类别 | 说明 |
|--------|------|------|------|
| calculator | 计算器 | query | 执行数学计算 |
| code_interpreter | 代码执行 | query | 安全地执行Python代码 |
| current_time | 当前时间 | query | 获取当前本地时间 |
| turn_on_camera | 打开摄像头 | system | 执行打开摄像头命令 |
| turn_off_camera | 关闭摄像头 | system | 执行关闭摄像头命令 |
| increase_volume | 调高音量 | system | 提升设备音量 |
| decrease_volume | 调低音量 | system | 降低设备音量 |
| voice_msg_prompt | 语音消息提示 | system | 播报一条语音提示消息 |
| text_msg_prompt | 文本消息提示 | system | 显示一条文本弹窗提示 |
| voice_choice_prompt | 语音选项提示 | system | 播报问题并展示可选项，等待用户选择 |
| text_choice_prompt | 文本选项提示 | system | 显示文本选项弹窗并等待用户选择 |

**类别说明：**
- `query`: 查询类工具，需要配置 HTTP URL
- `system`: 系统类工具，直接在客户端执行

---

## API 端点

### 1. 获取可用工具列表

```http
GET /api/v1/tools/list
```

**Response:**

```json
{
  "tools": {
    "search": {
      "name": "网络搜索",
      "description": "搜索互联网获取最新信息",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string", "description": "搜索关键词"}
        },
        "required": ["query"]
      }
    },
    "calculator": {
      "name": "计算器",
      "description": "执行数学计算",
      "parameters": {
        "type": "object",
        "properties": {
          "expression": {"type": "string", "description": "数学表达式，如: 2 + 3 * 4"}
        },
        "required": ["expression"]
      }
    },
    "weather": {
      "name": "天气查询",
      "description": "查询指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string", "description": "城市名称"}
        },
        "required": ["city"]
      }
    },
    "translate": {
      "name": "翻译",
      "description": "翻译文本到指定语言",
      "parameters": {
        "type": "object",
        "properties": {
          "text": {"type": "string", "description": "要翻译的文本"},
          "target_lang": {"type": "string", "description": "目标语言，如: en, ja, ko"}
        },
        "required": ["text", "target_lang"]
      }
    },
    "knowledge": {
      "name": "知识库查询",
      "description": "从知识库中检索相关信息",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string", "description": "查询内容"},
          "kb_id": {"type": "string", "description": "知识库ID"}
        },
        "required": ["query"]
      }
    },
    "code_interpreter": {
      "name": "代码执行",
      "description": "安全地执行Python代码",
      "parameters": {
        "type": "object",
        "properties": {
          "code": {"type": "string", "description": "要执行的Python代码"}
        },
        "required": ["code"]
      }
    }
  }
}
```

---

### 2. 获取工具详情

```http
GET /api/v1/tools/list/{tool_id}
```

**Path Parameters:**

| 参数 | 类型 | 说明 |
|------|------|------|
| tool_id | string | 工具ID |

**Response:**

```json
{
  "name": "计算器",
  "description": "执行数学计算",
  "parameters": {
    "type": "object",
    "properties": {
      "expression": {"type": "string", "description": "数学表达式，如: 2 + 3 * 4"}
    },
    "required": ["expression"]
  }
}
```

**错误响应 (工具不存在):**

```json
{
  "detail": "Tool not found"
}
```

---

### 3. 健康检查

```http
GET /api/v1/tools/health
```

**Response:**

```json
{
  "status": "healthy",
  "timestamp": 1705315200.123,
  "tools": ["search", "calculator", "weather", "translate", "knowledge", "code_interpreter"]
}
```

---

### 4. 获取工具资源列表

```http
GET /api/v1/tools/resources
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| category | string | 否 | - | 过滤类别: "query" \| "system" |
| enabled | boolean | 否 | - | 过滤启用状态 |
| include_system | boolean | 否 | true | 是否包含系统工具 |
| page | int | 否 | 1 | 页码 |
| limit | int | 否 | 100 | 每页数量 |

**Response:**

```json
{
  "total": 15,
  "page": 1,
  "limit": 100,
  "list": [
    {
      "id": "calculator",
      "user_id": 1,
      "name": "计算器",
      "description": "执行数学计算",
      "category": "query",
      "icon": "Terminal",
      "http_method": "GET",
      "http_url": null,
      "http_timeout_ms": 10000,
      "parameter_schema": {
        "type": "object",
        "properties": {
          "expression": {"type": "string", "description": "数学表达式"}
        },
        "required": ["expression"]
      },
      "parameter_defaults": {},
      "wait_for_response": false,
      "enabled": true,
      "is_system": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

---

### 5. 获取工具资源详情

```http
GET /api/v1/tools/resources/{id}
```

---

### 6. 创建工具资源

```http
POST /api/v1/tools/resources
```

**Request Body:**

```json
{
  "name": "订单查询",
  "description": "查询用户订单信息",
  "category": "query",
  "icon": "Search",
  "http_method": "POST",
  "http_url": "https://api.example.com/orders",
  "http_headers": {"Authorization": "Bearer {api_key}"},
  "http_timeout_ms": 10000,
  "parameter_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "订单ID"}
    },
    "required": ["order_id"]
  },
  "enabled": true
}
```

**Fields 说明:**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 否 | 工具ID，默认自动生成 |
| name | string | 是 | 工具名称 |
| description | string | 否 | 工具描述 |
| category | string | 是 | 类别: "query" \| "system" |
| icon | string | 否 | 图标名称 |
| http_method | string | 否 | HTTP 方法，默认 GET |
| http_url | string | 否* | HTTP 请求地址 (query 类必填) |
| http_headers | object | 否 | HTTP 请求头 |
| http_timeout_ms | int | 否 | 超时时间(毫秒)，默认 10000 |
| parameter_schema | object | 否 | 参数 JSON Schema |
| parameter_defaults | object | 否 | 默认参数值 |
| wait_for_response | boolean | 否 | 是否等待响应 (仅 system 类) |
| enabled | boolean | 否 | 是否启用，默认 true |

---

### 7. 更新工具资源

```http
PUT /api/v1/tools/resources/{id}
```

---

### 8. 删除工具资源

```http
DELETE /api/v1/tools/resources/{id}
```

---

## 自动测试 (Autotest)

### 4. 运行完整自动测试

```http
POST /api/v1/tools/autotest
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| llm_model_id | string | 否 | - | LLM 模型ID |
| asr_model_id | string | 否 | - | ASR 模型ID |
| test_llm | boolean | 否 | true | 是否测试LLM |
| test_asr | boolean | 否 | true | 是否测试ASR |

**Response:**

```json
{
  "id": "abc12345",
  "started_at": 1705315200.0,
  "duration_ms": 2500,
  "tests": [
    {
      "name": "Model Existence",
      "passed": true,
      "message": "Found model: GPT-4o",
      "duration_ms": 15
    },
    {
      "name": "API Connection",
      "passed": true,
      "message": "Latency: 150ms",
      "duration_ms": 150
    },
    {
      "name": "Temperature Setting",
      "passed": true,
      "message": "temperature=0.7"
    },
    {
      "name": "Streaming Support",
      "passed": true,
      "message": "Received 15 chunks",
      "duration_ms": 800
    }
  ],
  "summary": {
    "passed": 4,
    "failed": 0,
    "total": 4
  }
}
```

---

### 5. 测试单个 LLM 模型

```http
POST /api/v1/tools/autotest/llm/{model_id}
```

**Path Parameters:**

| 参数 | 类型 | 说明 |
|------|------|------|
| model_id | string | LLM 模型ID |

**Response:**

```json
{
  "id": "llm_test_001",
  "started_at": 1705315200.0,
  "duration_ms": 1200,
  "tests": [
    {
      "name": "Model Existence",
      "passed": true,
      "message": "Found model: GPT-4o",
      "duration_ms": 10
    },
    {
      "name": "API Connection",
      "passed": true,
      "message": "Latency: 180ms",
      "duration_ms": 180
    },
    {
      "name": "Temperature Setting",
      "passed": true,
      "message": "temperature=0.7"
    },
    {
      "name": "Streaming Support",
      "passed": true,
      "message": "Received 12 chunks",
      "duration_ms": 650
    }
  ],
  "summary": {
    "passed": 4,
    "failed": 0,
    "total": 4
  }
}
```

---

### 6. 测试单个 ASR 模型

```http
POST /api/v1/tools/autotest/asr/{model_id}
```

**Path Parameters:**

| 参数 | 类型 | 说明 |
|------|------|------|
| model_id | string | ASR 模型ID |

**Response:**

```json
{
  "id": "asr_test_001",
  "started_at": 1705315200.0,
  "duration_ms": 800,
  "tests": [
    {
      "name": "Model Existence",
      "passed": true,
      "message": "Found model: Whisper-1",
      "duration_ms": 8
    },
    {
      "name": "Hotwords Config",
      "passed": true,
      "message": "Hotwords: 3 words"
    },
    {
      "name": "API Availability",
      "passed": true,
      "message": "Status: 200",
      "duration_ms": 250
    },
    {
      "name": "Language Config",
      "passed": true,
      "message": "Language: zh"
    }
  ],
  "summary": {
    "passed": 4,
    "failed": 0,
    "total": 4
  }
}
```

---

### 7. 发送测试消息

```http
POST /api/v1/tools/test-message
```

**Query Parameters:**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| llm_model_id | string | 是 | - | LLM 模型ID |
| message | string | 否 | "Hello, this is a test message." | 测试消息 |

**Response:**

```json
{
  "success": true,
  "reply": "Hello! This is a test reply from GPT-4o.",
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 12,
    "total_tokens": 27
  }
}
```

**错误响应 (模型不存在):**

```json
{
  "detail": "LLM Model not found"
}
```

---

## 测试结果结构

### AutotestResult

```typescript
interface AutotestResult {
  id: string;           // 测试ID
  started_at: number;   // 开始时间戳
  duration_ms: number;  // 总耗时(毫秒)
  tests: TestCase[];    // 测试用例列表
  summary: TestSummary; // 测试摘要
}

interface TestCase {
  name: string;         // 测试名称
  passed: boolean;      // 是否通过
  message: string;      // 测试消息
  duration_ms: number;  // 耗时(毫秒)
}

interface TestSummary {
  passed: number;       // 通过数量
  failed: number;       // 失败数量
  total: number;        // 总数量
}
```

---

## 测试项目说明

### LLM 模型测试项目

| 测试名称 | 说明 |
|----------|------|
| Model Existence | 检查模型是否存在于数据库 |
| API Connection | 测试 API 连接并测量延迟 |
| Temperature Setting | 检查温度配置 |
| Streaming Support | 测试流式响应支持 |

### ASR 模型测试项目

| 测试名称 | 说明 |
|----------|------|
| Model Existence | 检查模型是否存在于数据库 |
| Hotwords Config | 检查热词配置 |
| API Availability | 测试 API 可用性 |
| Language Config | 检查语言配置 |

---

## 单元测试

项目包含完整的单元测试，位于 `api/tests/test_tools.py`。

### 测试用例概览

| 测试类 | 说明 |
|--------|------|
| TestToolsAPI | 工具列表、健康检查等基础功能测试 |
| TestAutotestAPI | 自动测试功能完整测试 |

### 运行测试

```bash
# 运行工具相关测试
pytest api/tests/test_tools.py -v

# 运行所有测试
pytest api/tests/ -v
```