feat(mcp): 增加 mode=skill,把 MCP 工具以技能形式暴露

mode 三态改为 advertise / skill / disable:
- skill 不下发到 tools 数组,由 skill 工具的 list/get/run 暴露
- get 返回 MCP 原始的 description + input_schema;run 直接转发,不做路径改写与 required 预检
- 移除 mode: silent(不设专门迁移文案)与 front matter mcp_tool 包装
- 删除 skills/image、skills/video,改由 image_task / video_task 的 mode: skill 提供
- 技能清单改用 listCallableSkills(目录 + MCP,同名时目录胜出);设置页仍只列目录
- init.sh 配了 BIGMODEL_KEY 时给 image_task / video_task 写 mode: skill
- image_task / video_task 的 tool description 首行改为自解释的一句话(技能清单取首行)
This commit is contained in:
2026-10-21 11:01:50 +08:00
parent 76a0e9ad86
commit 955e550b29
17 changed files with 152 additions and 214 deletions
+18 -21
View File
@@ -22,7 +22,7 @@
skills/
└── <skill-name>/
├── SKILL.md # 技能描述文件(必须)
├── run.py # 技能主入口(Python 脚本,推荐)或 run.sh;声明 mcp_tool 时不需要
├── run.py # 技能主入口(Python 脚本,推荐)或 run.sh
├── requirements.txt # Python 依赖(可选,若需要第三方包)
├── install.sh # 系统级依赖安装脚本(可选,如 apt-get)
└── ... # 其他技能相关文件(如字体、模板等)
@@ -53,7 +53,6 @@ input_schema:
output_schema:
# 输出描述
visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板
mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此时不需要入口脚本)
---
```
@@ -62,7 +61,6 @@ mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此
- `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。
- `output_schema`:输出结果的描述(可选)。
- `visit_url`:(可选)页面类技能声明的访问路径模板,`{task_id}` 占位执行时替换为会话 id。`run` 成功后由 core(tools/executor.js)拼上 `public_link.base_url`,在输出末尾追加一行「访问地址:<完整 URL>」——技能进程跑在 executor 隔离视图里不知道公网地址,完整链接只能 core 补;AI 拿到相对路径会原样转给用户,而相对路径打不开。
- `mcp_tool`:(可选)声明该技能的后端是某个已注册的 MCP 工具(见 3.3)。声明后不需要 `run.py` / `run.sh`。
- 若未提供 Front Matter,系统会尝试从正文第一行提取描述。
### 3.2 正文内容
@@ -89,27 +87,26 @@ mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此
---
### 3.3 MCP 后端技能(无入口脚本)
### 3.3 MCP 后端技能(不建目录)
front matter 里写 `mcp_tool: <工具名>`,这个技能的 `run` 就不落 executor 沙箱,而是由 **core
直接调用 `mcp.callTool`** 转发给 `mcp_servers` 里配置的服务:
把 `config.yml` 里某个 MCP 服务配成 `mode: skill` 即可:它的每个工具会自动成为技能,不需要
`SKILL.md`,也不需要入口脚本。
```yaml
---
name: image
description: AI 生成图片(CogView)。op=create 传 prompt 拿 task_id,再 op=get 取图片 URL
mcp_tool: image_task
---
```
- `{"list":"all"}` 里出现工具名,描述取 MCP `description` 的第一行;
- `{"get":"<工具名>"}` 直接返回 MCP 原始的 `description` + `input_schema`(单一来源,不会与
实现漂移);
- `{"run":"<工具名>","args":{…}}` 把 `args` 原样透传成 MCP 的 `arguments`,由 core 直接转发。
- `args` **原样透传**成 MCP 工具的 `arguments`;参数校验由 MCP 服务负责(不做
`input_schema.required` 预检——MCP 工具的参数常与它自己的 `op` 相关,静态必填列表会误伤)。
- **不经过沙箱**,所以也不需要密钥:凭证留在 core 的 `mcp_servers[].headers` 里。
executor 的环境变量白名单会按名字丢掉 `*KEY` / `*TOKEN`,沙箱本来也拿不到。
- 目的通常是省上下文:把该服务设成 `mode: silent`,工具不进模型的 tools 数组,模型只看到
技能清单里的一行描述,需要时再用 `{"get":"<名>"}` 读本文件。
- `mcp_tool` 填**最终工具名**(与内置工具重名时会被加 `<服务名>__` 前缀,见 `app/AGENTS.md`)。
- 启动时 core 会自检:声明的工具不在注册表里会打 `warn`,不会等到模型第一次调用才暴露。
几个约束:
- 参数校验交给 MCP 服务,core 不做 `input_schema.required` 预检(MCP 工具的参数常与它自己的
`op` 相关,静态必填列表会误伤)。
- `args` **不做相对路径改写**:服务拿到什么就是什么。URL、含 `/` 的 prompt 因此不会被改坏,
但本地文件路径也不会被自动补全——需要公网 URL 的先用 `mint_public_link`。
- 不经过沙箱,所以不需要密钥:凭证留在 core 的 `mcp_servers[].headers` 里。
- 工具名用**最终可调用名**(与内置工具重名时会被加 `<服务名>__` 前缀,见 `app/AGENTS.md`)。
- 与目录技能同名时目录技能优先,自动暴露的那份被遮蔽并打 `warn`。
- 启动日志会打印 `mode=skill` 的工具数量,便于确认暴露是否生效。
---
-42
View File
@@ -1,42 +0,0 @@
---
name: image
description: AI 生成图片(CogView)。op=create 传 prompt 拿 task_id,再 op=get 取图片 URL
mcp_tool: image_task
---
## 功能
调用智谱 CogView 生成图片。异步任务语义:提交立即返回 `task_id`,生成在服务端后台进行。
## 参数
`args` 原样透传给底层服务:
- `op=create`:`prompt` 必填。描述越具体越好(主体、风格、构图、光线、画面里的文字要求)。
- `op=get`:`task_id` 必填,取回任务状态;`SUCCESS` 时返回图片 URL。
## 用法
1. 提交
```
skill {"run":"image","args":{"op":"create","prompt":"一只橘猫趴在窗台上晒太阳,水彩风格"}}
```
→ 返回 `task_id` 与 `task_status: PROCESSING`
2. 查询
```
skill {"run":"image","args":{"op":"get","task_id":"<上一步返回的 id>"}}
```
→ `SUCCESS` 时返回 `Image N: <url>`
## 注意
- 生成通常 10~60 秒。看到 `PROCESSING` 就过几秒再查,不要连续轮询。
- 结果只有 URL,不落盘。要在会话里使用图片,用 `terminal` 下载:
`curl -fsSL -o out.png "<url>"`,之后 `read_file` 可以直接看图。
- 要让外部服务取这张图,先下载成本地文件,再用 `mint_public_link` 签发链接。
- 模型名与出图参数由服务端配置决定,调用时不需要也不该传。
-45
View File
@@ -1,45 +0,0 @@
---
name: video
description: AI 生成视频(CogVideo)。op=create 给 prompt(可加 image_url)拿 task_id,op=get 取视频 URL
mcp_tool: video_task
---
## 功能
文生视频 / 图生视频。异步任务语义:提交立即返回 `task_id`,生成在服务端进行,本技能不内部轮询。
## 参数
`args` 原样透传给底层服务:
- `op=create`:`prompt` 与 `image_url` **至少给一个**。
- 文生视频:只给 `prompt`(≤512 字符)。
- 图生视频:再给 `image_url`——必须是公网可访问的 png / jpeg / jpg、≤5MB。本地图片先用
`mint_public_link` 签发临时 URL,**不要**自己拼内网地址。
- `with_audio`:可选,是否生成 AI 音频,默认 `false`。
- `op=get`:`task_id` 必填;`SUCCESS` 时返回 Video URL(有封面时一并返回)。
## 用法
1. 提交
```
skill {"run":"video","args":{"op":"create","prompt":"镜头缓慢推进,海浪拍打礁石","with_audio":true}}
```
→ 返回 `task_id`
2. 查询
```
skill {"run":"video","args":{"op":"get","task_id":"<上一步返回的 id>"}}
```
→ `SUCCESS` 时返回 `Video URL: <url>`
## 注意
- 生成通常 1~5 分钟。`PROCESSING` 时不要高频轮询:可以先把其它事做完,再回来查。
- 结果只有 URL,不落盘;需要本地文件时用 `terminal` 的 `curl -fsSL -o out.mp4 "<url>"`。
- 图生视频的参考图必须公网可达:本地文件先 `mint_public_link`,再把它返回的地址填进 `image_url`。
- 模型名、分辨率、帧率、水印等由服务端配置决定,调用时不需要传。