feat(skills): 技能支持 MCP 后端(front matter mcp_tool)

SKILL.md 声明 mcp_tool 时,op=run 不落 executor 沙箱,由 core 直接 mcp.callTool
转发:凭证留在 core(沙箱的 env 白名单本就会丢掉 *KEY/*TOKEN),模型只看到技能清单
里的一行描述。配合 mcp_servers[].mode: silent,工具不再进每轮请求的 tools 数组。

- skills.js: runSkill 在 absolutizeArgs 之前分流(否则 URL / 含斜杠的 prompt 会被
  当路径改写);不做 input_schema.required 预检(参数与 op 相关,交给 MCP 服务)
- listSkills 带出 mcp_tool;设置页技能卡显示 mcp 后端徽章
- server.js: 启动期自检,缺失后端 warn、两条路并存 info
- 新增 skills/image、skills/video 两个纯文档技能(无 run.py)
- skills/README、README、app/AGENTS 同步
This commit is contained in:
2026-10-21 09:08:57 +08:00
parent 5d5482891f
commit 767caa8574
9 changed files with 179 additions and 14 deletions
+27 -1
View File
@@ -22,7 +22,7 @@
skills/
└── <skill-name>/
├── SKILL.md # 技能描述文件(必须)
├── run.py # 技能主入口(Python 脚本,推荐)或 run.sh
├── run.py # 技能主入口(Python 脚本,推荐)或 run.sh;声明 mcp_tool 时不需要
├── requirements.txt # Python 依赖(可选,若需要第三方包)
├── install.sh # 系统级依赖安装脚本(可选,如 apt-get)
└── ... # 其他技能相关文件(如字体、模板等)
@@ -53,6 +53,7 @@ input_schema:
output_schema:
# 输出描述
visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板
mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此时不需要入口脚本)
---
```
@@ -61,6 +62,7 @@ visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板
- `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。
- `output_schema`:输出结果的描述(可选)。
- `visit_url`:(可选)页面类技能声明的访问路径模板,`{task_id}` 占位执行时替换为会话 id。`op=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 正文内容
@@ -87,6 +89,30 @@ visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板
---
### 3.3 MCP 后端技能(无入口脚本)
front matter 里写 `mcp_tool: <工具名>`,这个技能的 `op=run` 就不落 executor 沙箱,而是由 **core
直接调用 `mcp.callTool`** 转发给 `mcp_servers` 里配置的服务:
```yaml
---
name: image
description: AI 生成图片(CogView)。op=create 传 prompt 拿 task_id,再 op=get 取图片 URL
mcp_tool: image_task
---
```
- `input_args` **原样透传**成 MCP 工具的 `arguments`;参数校验由 MCP 服务负责(不做
`input_schema.required` 预检——MCP 工具的参数常与 op 相关,静态必填列表会误伤)。
- **不经过沙箱**,所以也不需要密钥:凭证留在 core 的 `mcp_servers[].headers` 里。
executor 的环境变量白名单会按名字丢掉 `*KEY` / `*TOKEN`,沙箱本来也拿不到。
- 目的通常是省上下文:把该服务设成 `mode: silent`,工具不进模型的 tools 数组,模型只看到
技能清单里的一行描述,需要时再用 `op=get` 读本文件。
- `mcp_tool` 填**最终工具名**(与内置工具重名时会被加 `<服务名>__` 前缀,见 `app/AGENTS.md`)。
- 启动时 core 会自检:声明的工具不在注册表里会打 `warn`,不会等到模型第一次调用才暴露。
---
## 4. 入口脚本
### 4.1 格式要求
+42
View File
@@ -0,0 +1,42 @@
---
name: image
description: AI 生成图片(CogView)。op=create 传 prompt 拿 task_id,再 op=get 取图片 URL
mcp_tool: image_task
---
## 功能
调用智谱 CogView 生成图片。异步任务语义:提交立即返回 `task_id`,生成在服务端后台进行。
## 参数
`input_args` 原样透传给底层服务:
- `op=create`:`prompt` 必填。描述越具体越好(主体、风格、构图、光线、画面里的文字要求)。
- `op=get`:`task_id` 必填,取回任务状态;`SUCCESS` 时返回图片 URL。
## 用法
1. 提交
```
skill op=run name=image input_args={"op":"create","prompt":"一只橘猫趴在窗台上晒太阳,水彩风格"}
```
→ 返回 `task_id` 与 `task_status: PROCESSING`
2. 查询
```
skill op=run name=image input_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
@@ -0,0 +1,45 @@
---
name: video
description: AI 生成视频(CogVideo)。op=create 给 prompt(可加 image_url)拿 task_id,op=get 取视频 URL
mcp_tool: video_task
---
## 功能
文生视频 / 图生视频。异步任务语义:提交立即返回 `task_id`,生成在服务端进行,本技能不内部轮询。
## 参数
`input_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 op=run name=video input_args={"op":"create","prompt":"镜头缓慢推进,海浪拍打礁石","with_audio":true}
```
→ 返回 `task_id`
2. 查询
```
skill op=run name=video input_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`。
- 模型名、分辨率、帧率、水印等由服务端配置决定,调用时不需要传。