From 992d9a3515b14246c24b15dd33076e409545c26e Mon Sep 17 00:00:00 2001 From: AskaEth Date: Mon, 22 Jun 2026 21:17:46 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E7=A7=BB=E9=99=A4=E5=B7=B2=E5=BA=9F?= =?UTF-8?q?=E5=BC=83=E7=9A=84=20tool-engine=20API=20=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tool-engine 服务已在 Phase 3 移除，工具调用整合到 pkg/plugins Co-Authored-By: Claude --- docs/api/backend-services/tool-engine.md | 296 ----------------------- 1 file changed, 296 deletions(-) delete mode 100644 docs/api/backend-services/tool-engine.md diff --git a/docs/api/backend-services/tool-engine.md b/docs/api/backend-services/tool-engine.md deleted file mode 100644 index a03f68c..0000000 --- a/docs/api/backend-services/tool-engine.md +++ /dev/null @@ -1,296 +0,0 @@ -# 工具调用 API (已迁移至 AI-Core) - -> **Base URL:** `http://: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_* 动作时需要) |