Cyrene/docs/api/backend-services/tool-engine.md

Tool-Engine API

Base URL: http://<host>:8092 | Auth: 无

工具引擎注册了 13 个内置工具，支持单次和批量执行，可选数据库持久化的调用日志。

---

目录

1. GET /api/v1/health
2. GET /api/v1/tools
3. GET /api/v1/tools/:name
4. POST /api/v1/tools/:name/execute
5. POST /api/v1/tools/execute — 批量执行
6. GET /api/v1/tools/calls
7. GET /api/v1/tools/calls/stats
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

{ "status": "ok", "service": "tool-engine" }

---

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

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

---

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

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

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

---

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

请求

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

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

参数	说明
user_id	调用用户
session_id	调用会话

响应 200

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

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

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

---

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

// 请求
{
  "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

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

---

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

{
  "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_* 动作时需要)