# 工具调用 API (已迁移至 AI-Core)

> **Base URL:** `http://<host>:8081` | **Auth:** 无  
> **迁移说明:** tool-engine 服务 (8092) 已移除。工具注册与调用功能已整合到 `pkg/plugins` 共享模块，由 AI-Core (8081) 直接管理。API 路径保持不变。  
> **源码:** [pkg/plugins/manager/registry.go](../../backend/pkg/plugins/manager/registry.go)

工具注册中心管理 15+ 个内置工具，通过内存环形缓冲区 (500 条) 记录调用日志。

---

## 目录

1. [GET /api/v1/health](#1-get-apiv1health)
2. [GET /api/v1/tools](#2-get-apiv1tools)
3. [GET /api/v1/tools/:name](#3-get-apiv1toolsname)
4. [POST /api/v1/tools/:name/execute](#4-post-apiv1toolsnameexecute)
5. [POST /api/v1/tools/execute — 批量执行](#5-post-apiv1toolsexecute)
6. [GET /api/v1/tools/calls](#6-get-apiv1toolscalls)
7. [GET /api/v1/tools/calls/stats](#7-get-apiv1toolscallsstats)
8. [已注册工具参考](#8-已注册工具参考)

---

## 数据模型

### ToolDefinition

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 工具标识 |
| `description` | string | 功能描述 |
| `parameters` | object | JSON Schema 参数定义 |

### CallLogRecord

| 字段 | 类型 | 说明 |
|------|------|------|
| `call_id` | string | 调用唯一标识 (纳秒时间戳) |
| `tool_name` | string | 工具名 |
| `arguments` | string | 调用参数 (JSON 字符串) |
| `output` | string | 输出文本 |
| `error` | string | 错误信息 |
| `success` | bool | 是否成功 |
| `duration_ms` | int | 执行耗时 |
| `timestamp` | int64 | Unix 毫秒时间戳 |

### ToolCallCount

| 字段 | 类型 | 说明 |
|------|------|------|
| `tool_name` | string | 工具名 |
| `count` | int | 调用总数 |
| `success_count` | int | 成功次数 |
| `fail_count` | int | 失败次数 |
| `avg_duration_ms` | float64 | 平均耗时 |

---

## 1. GET /api/v1/health

```json
{ "status": "ok", "service": "ai-core" }
```

---

## 2. GET /api/v1/tools — 工具列表

```json
{
  "tools": [ ToolDefinition, ... ],
  "total": 13
}
```

---

## 3. GET /api/v1/tools/:name — 工具详情

```json
{ "name": "calculator", "description": "...", "parameters": { ... } }
```

**404:** `{"error":"工具 {name} 不存在"}`

---

## 4. POST /api/v1/tools/:name/execute — 执行工具

### 请求

```json
{ "arguments": { "expression": "3 + 4 * 2" } }
```

### Query 参数 (可选，用于日志)

| 参数 | 说明 |
|------|------|
| `user_id` | 调用用户 |
| `session_id` | 调用会话 |

### 响应 200

```json
{
  "id": "",
  "output": "11",
  "error": ""
}
```

- 成功: `output` 有值，`error` 为空字符串
- 失败: `output` 可能为空，`error` 有值 —— **仍然返回 HTTP 200**，调用方需检查 `error` 字段

**500:** `{"error":"执行工具 {name} 失败: ..."}` — 工具注册表未找到（非参数错误）

---

## 5. POST /api/v1/tools/execute — 批量执行

```json
// 请求
{
  "calls": [
    { "id": "call-1", "name": "calculator", "arguments": { "expression": "3+4" } },
    { "id": "call-2", "name": "datetime",    "arguments": { "action": "now" } }
  ]
}

// 响应 200
{
  "results": [
    { "id": "call-1", "output": "7",  "error": "" },
    { "id": "call-2", "output": "2024-01-01 12:00:00", "error": "" }
  ]
}
```

| 状态码 | 错误 |
|--------|------|
| 400 | `{"error":"calls 不能为空"}` |
| 400 | `{"error":"请求体格式错误: ..."}` |

---

## 6. GET /api/v1/tools/calls — 调用日志

内存环形缓冲区 (500 条)，无需数据库。

### Query 参数

| 参数 | 默认 | 说明 |
|------|------|------|
| `tool_name` | 全部 | 按工具名过滤 |
| `page` | 1 | 页码 |
| `limit` | 50 (max 500) | 每页条数 |

### 响应 200

```json
{
  "calls": [ CallLogRecord, ... ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "total_pages": 8
}
```

---

## 7. GET /api/v1/tools/calls/stats — 调用统计

```json
{
  "total_calls": 150,
  "success_count": 140,
  "fail_count": 10,
  "success_rate": 93.33,
  "avg_duration_ms": 45.2,
  "by_tool": [
    { "tool_name": "calculator", "count": 80, "success_count": 78, "fail_count": 2, "avg_duration_ms": 12.3 }
  ]
}
```

内存缓冲区，重启后数据清零。

---

## 8. 已注册工具参考

### calculator — 数学计算

| 参数 | 必填 | 说明 |
|------|------|------|
| `expression` | 是 | 数学表达式 (如 `3 + 4 * 2`) |

### datetime — 日期时间

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `now`, `format`, `add`, `diff`, `timezone_list` |
| `format` | 否 | 时间格式 (action=format 时) |
| `timezone` | 否 | 时区 |
| `date` | 否 | 日期 |
| `duration` | 否 | 时长 (action=add 时) |
| `date2` | 否 | 第二个日期 (action=diff 时) |

### text — 文本处理

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `count`, `summarize`, `translate`, `extract` |
| `text` | 是 | 文本内容 |
| `target_lang` | 否 | 目标语言 (translate) |
| `pattern` | 否 | 提取模式 (extract) |

### crypto — 加密编码

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `hash`, `base64_encode`, `base64_decode`, `url_encode`, `url_decode` |
| `input` | 是 | 输入文本 |
| `algorithm` | 否 | hash 算法: `md5`, `sha1`, `sha256`, `sha512` (默认 sha256) |

### random — 随机生成

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `number`, `uuid`, `password`, `pick`, `shuffle` |
| `min` | 否 | 最小值 (number) |
| `max` | 否 | 最大值 (number) |
| `length` | 否 | 长度 (password) |
| `items` | 否 | 选项数组 (pick/shuffle) |
| `count` | 否 | 选取数量 (pick) |

### markdown — Markdown 处理

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `to_html`, `to_text`, `extract_links`, `extract_code`, `table_of_contents` |
| `markdown` | 是 | Markdown 原文 |

### json_ops — JSON 操作

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `parse`, `query`, `validate` |
| `json_string` | 是 | JSON 字符串 |
| `path` | 否 | 查询路径 (query) |

### file_ops — 文件操作

| 参数 | 必填 | 说明 |
|------|------|------|
| `action` | 是 | `read`, `write`, `list`, `exists`, `delete` |
| `path` | 是 | 文件路径 |
| `content` | 否 | 写入内容 (write) |

### http_request — HTTP 请求

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `url` | 是 | — | 请求 URL |
| `method` | 否 | GET | HTTP 方法 |
| `headers` | 否 | {} | 请求头 |
| `body` | 否 | — | 请求体 |
| `timeout` | 否 | 30s | 超时秒数 |

### web_search — 网页搜索

| 参数 | 必填 | 说明 |
|------|------|------|
| `query` | 是 | 搜索关键词 |

### web_fetch — 网页抓取

| 参数 | 必填 | 说明 |
|------|------|------|
| `url` | 是 | 目标 URL |

### iot_query — IoT 设备查询

| 参数 | 必填 | 说明 |
|------|------|------|
| `device_id` | 否 | 设备 ID (缺省返回全部) |

### iot_control — IoT 设备控制

| 参数 | 必填 | 说明 |
|------|------|------|
| `device_id` | 是 | 设备 ID (别名 `entity_id`) |
| `action` | 是 | `toggle`, `turn_on`, `turn_off`, `set_temperature`, `set_brightness`, `set_position`, `set_mode`, `set_color` (支持中文名) |
| `value` | 否 | 值 (set_* 动作时需要) |