AskaEth
70f8b30d04
新增 docs/api/gateway-api.md：面向客户端开发的网关 API 统一文档，覆盖全部 16 个模块。 新增 docs/api/backend-services/：后端服务详细文档 (ai-core, memory-service, voice-service, iot-debug, tool-engine)。 更新 .gitignore：docs/api/ 例外允许推送，其他 docs/ 内容仍忽略。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
298 lines
7.0 KiB
Markdown
298 lines
7.0 KiB
Markdown
# Tool-Engine API
|
|
|
|
**Base URL:** `http://<host>:8092` | **Auth:** 无
|
|
|
|
工具引擎注册了 13 个内置工具，支持单次和批量执行，可选数据库持久化的调用日志。
|
|
|
|
---
|
|
|
|
## 目录
|
|
|
|
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
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `id` | int | 数据库自增 ID |
|
|
| `call_id` | string | UUID v4 |
|
|
| `tool_name` | string | 工具名 |
|
|
| `arguments` | json.RawMessage | 调用参数 |
|
|
| `output` | string | 输出文本 |
|
|
| `error` | string | 错误信息 |
|
|
| `success` | bool | 是否成功 |
|
|
| `duration_ms` | int | 执行耗时 |
|
|
| `user_id` | string | 调用用户 |
|
|
| `session_id` | string | 调用会话 |
|
|
| `created_at` | string | 时间戳 |
|
|
|
|
### 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": "tool-engine" }
|
|
```
|
|
|
|
---
|
|
|
|
## 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 — 调用日志
|
|
|
|
需要 `DB_URL` 环境变量。未配置数据库时返回空结果。
|
|
|
|
### Query 参数
|
|
|
|
| 参数 | 默认 | 说明 |
|
|
|------|------|------|
|
|
| `tool_name` | 全部 | 按工具名过滤 |
|
|
| `page` | 1 | 页码 |
|
|
| `limit` | 20 (max 100) | 每页条数 |
|
|
|
|
### 响应 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 }
|
|
]
|
|
}
|
|
```
|
|
|
|
未配置数据库时全返回 0。
|
|
|
|
---
|
|
|
|
## 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_* 动作时需要) |
|