504 lines
16 KiB
JavaScript
504 lines
16 KiB
JavaScript
import{d as u,o as m,l,m as o,c as s,f as n,t as e,j as r,p as y,q as _}from"./index.js";import{r as j}from"./useMarkdownRenderer.js";import{_ as h}from"./_plugin-vue_export-helper.js";const g=`# 自定义工具开发指南（非常详细｜三层架构版）
|
||
|
||
适用对象：**从零开始、第一次上手** 的管理员。
|
||
当前能力：**仅支持 Python**，且必须在容器内执行；自定义工具仅管理员可见/可用。
|
||
|
||
> 本项目默认不做严格校验（私有化客制化场景）。这让你更自由，但也更容易踩坑。本文用大量例子/反例把坑提前说明。
|
||
|
||
---
|
||
## 0. 快速上手（5 分钟 checklist）
|
||
|
||
1) 创建工具文件夹：\`data/custom_tools/<tool_id>/\`
|
||
2) 写 3 个文件：
|
||
- \`definition.json\`（定义层）
|
||
- \`execution.py\`（执行层）
|
||
- \`return.json\`（返回层，可选但强烈建议先写一个简单截断）
|
||
3) 刷新管理端：
|
||
- 打开 \`admin/policy\`：工具应该出现在 \`custom\` 分类的可选列表里
|
||
4) 用管理员账号在聊天中调用工具（让模型调用或你手动触发）
|
||
|
||
如果第 3 步看不到工具：先看本文的“常见问题/排查”章节。
|
||
|
||
---
|
||
## 1. 三层架构：你在写什么？
|
||
|
||
每个自定义工具由三层组成，各层之间通过“工具运行时”串起来：
|
||
|
||
### 1.1 定义层：\`definition.json\`
|
||
你告诉系统：
|
||
- 工具 ID（也是模型调用的函数名）
|
||
- 工具用途描述（给模型看，决定它会不会用、怎么用）
|
||
- 参数 schema（模型按它组织参数）
|
||
- 分类/图标/超时等元信息
|
||
|
||
### 1.2 执行层：\`execution.py\`（Python 模板）
|
||
你提供“低代码逻辑”：
|
||
- 文件内容会先被做一次 **字符串格式化**（把 \`{参数名}\` 替换成实际入参）
|
||
- 然后在容器内作为 Python 脚本运行
|
||
|
||
### 1.3 返回层：\`return.json\`（后处理）
|
||
对执行结果二次处理，例如：
|
||
- 限制返回长度（避免输出爆炸）
|
||
- 用模板把结果包装成更友好的消息
|
||
|
||
---
|
||
## 2. 目录结构规范（必须遵守）
|
||
|
||
每个工具一个独立目录：\`data/custom_tools/<tool_id>/\`
|
||
|
||
标准文件名：
|
||
\`\`\`
|
||
definition.json # 定义层（必需）
|
||
execution.py # 执行层（必需）
|
||
return.json # 返回层（可选）
|
||
meta.json # 备注/展示层（可选）
|
||
\`\`\`
|
||
|
||
只要某个目录同时存在 \`definition.json\` + \`execution.py\`，系统就会把它加载为“自定义工具”。
|
||
|
||
> 文件编码建议统一 UTF-8。
|
||
|
||
---
|
||
## 3. 运行时规则（你需要牢记的“真实行为”）
|
||
|
||
### 3.1 谁能看到/调用？
|
||
- **只有管理员账号**能看到/调用自定义工具
|
||
- 普通用户看不到工具，也无法在聊天中调用
|
||
|
||
### 3.2 工具如何出现在 \`admin/policy\`？
|
||
- 后端会自动注入一个分类 \`custom\`（名称“自定义工具”）
|
||
- 并把扫描到的自定义工具 ID 填入该分类的工具列表
|
||
- 所以 admin/policy 的“工具可选列表”会出现这些工具名，从而可分配到别的分类
|
||
|
||
### 3.3 执行层为什么“像模板”？
|
||
执行层会先做一次 Python \`str.format\` 类似的格式化：
|
||
- \`{a}\`、\`{op}\`、\`{b}\` 这样的占位符会被替换
|
||
- 这会导致一个大坑：**Python 字典/集合的花括号 \`{}\` 会被误认为占位符**（下文详解）
|
||
|
||
---
|
||
## 4. 定义层 \`definition.json\`：字段规范 + 大量示例
|
||
|
||
### 4.1 推荐字段（强烈建议都写）
|
||
\`\`\`json
|
||
{
|
||
"id": "calc",
|
||
"description": "简单两数运算（加减乘除），仅管理员可见",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"a": { "type": "number", "description": "第一个数字" },
|
||
"op": { "type": "string", "enum": ["+", "-", "*", "/"], "description": "运算符" },
|
||
"b": { "type": "number", "description": "第二个数字" }
|
||
},
|
||
"required": ["a", "op", "b"]
|
||
},
|
||
"category": "custom",
|
||
"icon": "brain.svg",
|
||
"timeout": 15
|
||
}
|
||
\`\`\`
|
||
|
||
字段说明：
|
||
- \`id\`（必填）：工具 ID，建议与文件夹名一致（例如文件夹 \`calc/\`，id 也叫 \`calc\`）
|
||
- \`description\`（强烈建议）：越清楚越好（模型会读它决定是否调用）
|
||
- \`parameters\`（建议）：JSON Schema 风格
|
||
- \`type\`：固定 \`"object"\`
|
||
- \`properties\`：参数字典
|
||
- \`required\`：必填参数数组
|
||
- \`category\`（可选，默认 custom）：用于管理端分类
|
||
- \`icon\`（可选）：SVG 文件名（来自 \`static/icons/\`）
|
||
- \`timeout\`（可选，默认 30）：执行超时秒数
|
||
|
||
> 注意：当前实现里 \`required\` 以 \`parameters.required\` 为准；另外顶层 \`required\` 字段也会被识别，但建议统一写在 \`parameters.required\`。
|
||
|
||
---
|
||
### 4.2 定义层示例 A：最小可用“回声工具”
|
||
文件：\`data/custom_tools/echo/definition.json\`
|
||
\`\`\`json
|
||
{
|
||
"id": "echo",
|
||
"description": "回声：原样返回 text",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"text": { "type": "string", "description": "要回显的文本" }
|
||
},
|
||
"required": ["text"]
|
||
},
|
||
"category": "custom",
|
||
"timeout": 10
|
||
}
|
||
\`\`\`
|
||
|
||
---
|
||
### 4.3 定义层示例 B：可选参数（optional）怎么写？
|
||
\`\`\`json
|
||
{
|
||
"id": "greet",
|
||
"description": "打招呼：name 可选",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": { "type": "string", "description": "名字（可选）" }
|
||
},
|
||
"required": []
|
||
}
|
||
}
|
||
\`\`\`
|
||
执行层里要记得处理 name 缺失的情况（见执行层示例）。
|
||
|
||
---
|
||
### 4.4 反例：参数 schema 写错导致模型不会传参
|
||
反例（\`type\` 写成 string）：
|
||
\`\`\`json
|
||
{
|
||
"id": "bad_schema",
|
||
"parameters": {
|
||
"type": "string",
|
||
"properties": {
|
||
"a": { "type": "number" }
|
||
}
|
||
}
|
||
}
|
||
\`\`\`
|
||
后果：模型端可能无法正确构造对象参数，调用失败或入参为空。
|
||
|
||
---
|
||
## 5. 执行层 \`execution.py\`：核心坑点、写法规范、正反例
|
||
|
||
### 5.1 执行层“模板替换”规则（最关键）
|
||
执行层在运行前会做一次模板替换：
|
||
- \`{a}\` → 入参 a 的值
|
||
- \`{op}\` → 入参 op 的值
|
||
|
||
因此：
|
||
- **你写的不是纯 Python，而是 Python + 占位符**
|
||
- 任何你写的 \`{...}\` 都可能被当成占位符解析
|
||
|
||
---
|
||
### 5.2 大坑：字典/集合花括号必须双写 \`{{\` \`}}\`
|
||
|
||
你之前遇到的报错：
|
||
\`\`\`json
|
||
{
|
||
"success": false,
|
||
"error": "缺少必填参数: \\"'+'\\""
|
||
}
|
||
\`\`\`
|
||
根因就是模板引擎把这段当成“需要一个叫 \`+'\` 的占位符”：
|
||
\`\`\`py
|
||
ops = {'+': operator.add, ...}
|
||
\`\`\`
|
||
|
||
**正确写法：把字典的 \`{}\` 变成 \`{{}}\`**
|
||
示例（正确）：
|
||
\`\`\`py
|
||
ops = {{'+': operator.add, '-': operator.sub, '*': operator.mul, '/': operator.truediv}}
|
||
\`\`\`
|
||
|
||
反例（错误）：
|
||
\`\`\`py
|
||
ops = {'+': operator.add}
|
||
\`\`\`
|
||
|
||
同理：集合 \`{1,2,3}\`、字典推导式 \`{k:v for ...}\` 都需要转义，否则会被误当占位符。
|
||
|
||
---
|
||
### 5.3 参数是字符串时，必须自己加引号（或安全编码）
|
||
|
||
如果参数是字符串：
|
||
- \`{name}\` 替换后会变成裸文本，导致 Python 语法错误
|
||
|
||
正确（加引号）：
|
||
\`\`\`py
|
||
name = '{name}'
|
||
\`\`\`
|
||
|
||
反例（没引号，容易 SyntaxError）：
|
||
\`\`\`py
|
||
name = {name}
|
||
\`\`\`
|
||
|
||
更稳健的写法（推荐）：用 JSON 序列化来安全注入字符串（避免引号/换行破坏代码）。
|
||
\`\`\`py
|
||
import json
|
||
name = json.loads({name_json})
|
||
\`\`\`
|
||
但这需要你在定义层把参数设计成 \`name_json\`，且调用时传入 JSON 字符串；新手不建议第一天就这么做。
|
||
|
||
---
|
||
### 5.4 强烈建议：执行层先做“输入校验”，再计算
|
||
因为没有强校验，入参可能是空、类型不对、字符串里有奇怪字符。
|
||
|
||
示例：对 calc 的 op 做严格白名单检查：
|
||
\`\`\`py
|
||
a = {a}
|
||
op = '{op}'
|
||
b = {b}
|
||
if op not in ['+','-','*','/']:
|
||
raise ValueError('op must be one of + - * /')
|
||
\`\`\`
|
||
|
||
反例（危险）：用 eval 解析运算符/表达式
|
||
\`\`\`py
|
||
print(eval(f\\"{a}{op}{b}\\")) # 不要这么写
|
||
\`\`\`
|
||
原因：op 或其他参数可被注入恶意表达式。
|
||
|
||
---
|
||
### 5.5 执行层示例 1：echo（最简单）
|
||
文件：\`data/custom_tools/echo/execution.py\`
|
||
\`\`\`py
|
||
text = '{text}'
|
||
print(text)
|
||
\`\`\`
|
||
|
||
---
|
||
### 5.6 执行层示例 2：greet（可选参数）
|
||
文件：\`data/custom_tools/greet/execution.py\`
|
||
\`\`\`py
|
||
name = '{name}'
|
||
name = (name or '').strip()
|
||
if not name:
|
||
print('你好！')
|
||
else:
|
||
print(f'你好，{name}！')
|
||
\`\`\`
|
||
注意：这里用到了 f-string 的 \`{name}\`，**它是 Python 运行时的花括号，不会参与模板替换**，因为模板替换已经在执行前完成，且我们这里的 \`{name}\` 是在 Python 代码字符串里，不是模板语法（但仍要注意别在最外层写出新的 \`{}\` 占位符）。
|
||
|
||
---
|
||
### 5.7 执行层示例 3：calc（你要的三参数计算器）
|
||
文件：\`data/custom_tools/calc/execution.py\`
|
||
\`\`\`py
|
||
a = {a}
|
||
op = '{op}'
|
||
b = {b}
|
||
import operator
|
||
ops = {{'+': operator.add, '-': operator.sub, '*': operator.mul, '/': operator.truediv}}
|
||
print(ops[op](a, b))
|
||
\`\`\`
|
||
|
||
要点回顾：
|
||
- 数字：\`a = {a}\`、\`b = {b}\`
|
||
- 字符串：\`op = '{op}'\`
|
||
- 字典：\`ops = {{...}}\`（双花括号）
|
||
|
||
---
|
||
### 5.8 反例：输出过大导致工具失败/截断
|
||
反例：
|
||
\`\`\`py
|
||
print('A' * 1000000)
|
||
\`\`\`
|
||
后果：输出有全局上限（默认 10k 字符左右），你会看到截断或失败提示。
|
||
建议：配合 return.json 的 \`truncate\`，或自行在执行层控制输出长度。
|
||
|
||
---
|
||
### 5.9 反例：死循环导致超时
|
||
\`\`\`py
|
||
while True:
|
||
pass
|
||
\`\`\`
|
||
后果：到 \`timeout\` 后被中断，返回 timeout。
|
||
|
||
---
|
||
## 6. 返回层 \`return.json\`：怎么做二次处理（例子 + 反例）
|
||
|
||
返回层是可选的，但强烈建议至少写一个 \`truncate\`，避免工具输出污染上下文。
|
||
|
||
### 6.1 支持字段（当前版本）
|
||
\`\`\`json
|
||
{
|
||
"truncate": 2000,
|
||
"template": "[tool_id={tool_id}] 输出: {output}"
|
||
}
|
||
\`\`\`
|
||
|
||
- \`truncate\`：整数，输出超过该长度时截断到前 N 字符
|
||
- \`template\`：字符串模板，可用变量：
|
||
- \`{output}\`：stdout+stderr 合并后的输出文本（已按 truncate 处理后的版本）
|
||
- \`{stderr}\`：stderr（如果存在）
|
||
- \`{return_code}\`：进程返回码
|
||
- \`{tool_id}\`：工具 id
|
||
|
||
> \`template\` 只是影响 \`message\` 展示，不会改变 \`output\` 字段本身（除 truncate）。
|
||
|
||
---
|
||
### 6.2 返回层示例：calc 结果更友好
|
||
文件：\`data/custom_tools/calc/return.json\`
|
||
\`\`\`json
|
||
{
|
||
"truncate": 2000,
|
||
"template": "[calc] 结果: {output}"
|
||
}
|
||
\`\`\`
|
||
|
||
---
|
||
### 6.3 反例：template 写错占位符导致忽略
|
||
\`\`\`json
|
||
{ "template": "结果={result}" }
|
||
\`\`\`
|
||
因为 \`{result}\` 不是支持变量，格式化会失败，系统会回退到默认 message（你会看到输出但不按模板展示）。
|
||
|
||
---
|
||
## 7. 备注/展示层 \`meta.json\`：备注与图标
|
||
|
||
### 7.1 meta.json 适合放什么？
|
||
示例：
|
||
\`\`\`json
|
||
{
|
||
"notes": "这是一个示例工具，用于演示参数与模板写法",
|
||
"icon": "calculator.svg",
|
||
"owner": "admin",
|
||
"created_at": "2026-01-05"
|
||
}
|
||
\`\`\`
|
||
|
||
### 7.2 图标怎么选？
|
||
目前图标字段会被保存/返回（前端后续可用它显示工具卡片 SVG）。
|
||
建议写成 \`static/icons/\` 下的文件名，例如：
|
||
- \`brain.svg\`
|
||
- \`terminal.svg\`
|
||
- \`bot.svg\`
|
||
|
||
你可以用命令查看有哪些图标：
|
||
\`\`\`bash
|
||
ls static/icons
|
||
\`\`\`
|
||
|
||
> 当前 UI 可能还没把 icon 真正渲染出来，但字段已经为未来对接准备好。
|
||
|
||
---
|
||
## 8. 如何创建一个新工具：从 0 到可用（完整示例）
|
||
|
||
下面示例创建一个工具 \`text_len\`：计算字符串长度，并在返回层截断。
|
||
|
||
### 8.1 创建目录
|
||
\`\`\`
|
||
data/custom_tools/text_len/
|
||
\`\`\`
|
||
|
||
### 8.2 definition.json
|
||
\`\`\`json
|
||
{
|
||
"id": "text_len",
|
||
"description": "计算文本长度（字符数）",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"text": { "type": "string", "description": "输入文本" }
|
||
},
|
||
"required": ["text"]
|
||
},
|
||
"category": "custom",
|
||
"timeout": 10
|
||
}
|
||
\`\`\`
|
||
|
||
### 8.3 execution.py
|
||
\`\`\`py
|
||
text = '{text}'
|
||
print(len(text))
|
||
\`\`\`
|
||
|
||
### 8.4 return.json（可选）
|
||
\`\`\`json
|
||
{
|
||
"truncate": 200,
|
||
"template": "[text_len] 字符数: {output}"
|
||
}
|
||
\`\`\`
|
||
|
||
### 8.5 验证
|
||
1) 管理端 \`admin/policy\`：应看到 \`text_len\`
|
||
2) 管理员聊天：让模型调用 \`text_len\`，或提示它“用 text_len 计算这段话长度”
|
||
|
||
---
|
||
## 9. 用 API 管理工具（可选）
|
||
|
||
如果你不想手工改文件，也可以调用后端接口（管理员权限）：
|
||
|
||
### 9.1 列表
|
||
\`GET /api/admin/custom-tools\`
|
||
|
||
### 9.2 新增/更新
|
||
\`POST /api/admin/custom-tools\`
|
||
|
||
请求 JSON 推荐结构（字段越全越好）：
|
||
\`\`\`json
|
||
{
|
||
"id": "calc",
|
||
"description": "简单两数运算",
|
||
"parameters": { "type": "object", "properties": {}, "required": [] },
|
||
"required": [],
|
||
"category": "custom",
|
||
"icon": "brain.svg",
|
||
"timeout": 15,
|
||
"execution_code": "print('hello')\\n",
|
||
"return": { "truncate": 2000, "template": "输出: {output}" },
|
||
"meta": { "notes": "通过 API 创建" }
|
||
}
|
||
\`\`\`
|
||
|
||
### 9.3 删除
|
||
\`DELETE /api/admin/custom-tools?id=calc\`
|
||
|
||
---
|
||
## 10. 常见问题与排查（非常实用）
|
||
|
||
### 10.1 admin/policy 看不到工具
|
||
逐条检查：
|
||
1) 你是否用 **管理员账号** 登录？
|
||
2) 工具目录是否存在：\`data/custom_tools/<tool_id>/\`
|
||
3) 是否同时存在两个文件：
|
||
- \`data/custom_tools/<tool_id>/definition.json\`
|
||
- \`data/custom_tools/<tool_id>/execution.py\`
|
||
4) \`definition.json\` 是否是合法 JSON（多一个逗号都会解析失败）
|
||
5) 刷新页面（强刷），必要时重启后端服务
|
||
|
||
### 10.2 调用时报 “缺少必填参数: \\"'+'\\"” 或类似奇怪 key
|
||
几乎可以确定是：**执行层里有未转义的字典/集合花括号**。
|
||
把 \`{\` 改成 \`{{\`，把 \`}\` 改成 \`}}\`（只针对“字典/集合字面量部分”）。
|
||
|
||
### 10.3 调用时报 SyntaxError（语法错误）
|
||
常见原因：
|
||
- 字符串参数没加引号：\`name = {name}\`（错误）
|
||
- 参数中包含换行/引号导致代码被截断（建议先做简单输入，或改用更稳健的注入方式）
|
||
|
||
### 10.4 调用成功但输出很乱/太长
|
||
解决：
|
||
- 在 \`return.json\` 里加 \`truncate\`
|
||
- 或执行层自行控制输出
|
||
|
||
### 10.5 工具能执行但模型不愿意用/总用错
|
||
解决：
|
||
- 优化 \`description\`：写清楚输入输出、限制、例子
|
||
- \`parameters.properties.*.description\` 写清楚含义
|
||
- \`enum\` 尽量给明确可选值（例如运算符）
|
||
|
||
---
|
||
## 11. 规范建议（团队协作必看）
|
||
|
||
### 11.1 命名规范
|
||
- 工具 id：小写 + 下划线（例如 \`calc\`, \`text_len\`, \`db_query\`）
|
||
- 目录名与 \`definition.json.id\` 保持一致
|
||
|
||
### 11.2 输出规范
|
||
建议输出尽量“短而确定”：
|
||
- 优先输出一个结果值或一段简短摘要
|
||
- 需要结构化时输出 JSON（但注意长度）
|
||
|
||
### 11.3 安全与边界
|
||
虽然是私有化环境，也强烈建议：
|
||
- 不要在执行层写破坏性命令/删除文件
|
||
- 不要 \`eval\` 用户输入
|
||
- 给工具合理的 \`timeout\`
|
||
- 给返回层加 \`truncate\`
|
||
|
||
---
|
||
## 12. 当前版本限制（请先接受这些现实）
|
||
- 仅支持 Python（没有 NodeJS 执行）
|
||
- 不提供强校验与沙箱策略自定义（依赖现有容器执行与全局限制）
|
||
- 图标字段已预留（\`icon\`），但前端是否渲染取决于后续 UI 接入
|
||
|
||
`,b={class:"guide-page"},f={class:"guide-header"},x={class:"title-block"},v={class:"desc"},T={class:"actions"},k={class:"ghost",href:"/admin/custom-tools",target:"_blank",rel:"noopener"},P={class:"panel"},S={key:0,class:"status error"},q={key:1,class:"status"},I=["innerHTML"],N=u({__name:"CustomToolsGuideApp",setup(E){const i=r(""),p=r(!0),a=r("");return m(()=>{try{i.value=j(g)}catch(t){a.value=t.message||l("adminCustomTools.renderFailed")}finally{p.value=!1}}),(t,c)=>(o(),s("div",b,[n("header",f,[n("div",x,[c[0]||(c[0]=n("p",{class:"eyebrow"},"Custom Tools",-1)),n("h1",null,e(t.$t("adminCustomTools.guide.title")),1),n("p",v,e(t.$t("adminCustomTools.guide.subtitle")),1)]),n("div",T,[n("a",k,e(t.$t("adminCustomTools.backToList")),1)])]),n("section",P,[a.value?(o(),s("div",S,e(a.value),1)):p.value?(o(),s("div",q,e(t.$t("common.loading")),1)):(o(),s("article",{key:2,class:"markdown",innerHTML:i.value},null,8,I))])]))}}),C=h(N,[["__scopeId","data-v-a78d893f"]]),d=y(C);_(d);d.mount("#custom-tools-guide");
|