diff --git a/README.md b/README.md
index 87b032a..114d8b3 100644
--- a/README.md
+++ b/README.md
@@ -280,14 +280,17 @@ platforms:
```text
skills/my-skill/
-├── SKILL.md # 必需:描述、input_schema、可选 required / visit_url
-├── run.py | run.sh # 必需:入口,唯一命令行参数是 JSON 字符串
+├── SKILL.md # 必需:描述、input_schema、可选 required / visit_url / mcp_tool
+├── run.py | run.sh # 入口,唯一命令行参数是 JSON 字符串(声明 mcp_tool 时不需要)
├── requirements.txt # 可选:Python 依赖
└── install.sh # 可选:系统层安装脚本,镜像构建期执行
```
- `SKILL.md` 的 `description` 会进入 system prompt,模型启动时就知道有哪些技能。
- `input_schema.required` 在 `skill op=run` 前校验。
+- `mcp_tool`:声明后端为某个 MCP 工具。此时 `op=run` 由 core 直接转发给 MCP(不落沙箱、不需要密钥),
+ 配合该服务的 `mode: silent` 就能把工具从模型的 tools 数组里隐藏,只留一行技能描述。仓库自带的
+ `skills/image`、`skills/video` 就是这么封装的 `image_task` / `video_task`。
- 入口脚本以绝对路径启动;远端执行时 cwd 是会话目录,本地开发时是技能目录。相对路径参数会先按会话目录转成绝对路径。
- `requirements.txt` 的依赖由 `agent-executor-init` 安装到 `skills/deps`;技能容器通过 `PYTHONPATH` 可见。
- `install.sh` 在镜像构建期以 root 执行,用于必须落在系统层的依赖。改完需要重建 executor 镜像。
diff --git a/app/AGENTS.md b/app/AGENTS.md
index 3c3efba..e53103e 100644
--- a/app/AGENTS.md
+++ b/app/AGENTS.md
@@ -173,6 +173,9 @@ POST /api/sessions/:id/messages
- 技能(`tools/skills.js`):`SKILL.md` front matter 提供 `description`/`input_schema`;
`input_schema.required` 在 `run` 前校验;相对路径参数按会话目录转绝对路径;入口一律用绝对路径
(远端 cwd 是会话目录)。配了 executor 就走 `remote-exec`,否则本地 `spawn`。
+ 声明了 `mcp_tool` 的技能走另一条后端:`runSkill` 在 `absolutizeArgs` **之前**分流,由 core
+ 直接 `mcp.callTool` 转发(不落沙箱,所以也不需要任何密钥);否则 URL 与含 `/` 的 prompt 会被
+ 当路径改写。此时不跑 `input_schema.required` 校验(参数是 op 相关的,交给 MCP 服务管)。
- MCP(`mcp.js`):启动时 `initialize` → `notifications/initialized` → `tools/list`;与内置或已有
MCP 工具重名时加 `<服务名>__` 前缀;请求随带 `X-Session-Dir`、`X-Public-Base`;
`content` 里的 `ui_card` 块不进模型上下文,转成 SSE `ui_card` 事件。
diff --git a/app/server/public/js/settings.js b/app/server/public/js/settings.js
index 20c4a44..3901759 100644
--- a/app/server/public/js/settings.js
+++ b/app/server/public/js/settings.js
@@ -840,7 +840,7 @@
'
' +
'
' + esc(s.name) +
(s.has_md ? '' : ' 缺 SKILL.md') +
- (s.entry ? ' ' + s.entry + ' 入口' : '') +
+ (s.entry ? ' ' + (s.entry === 'mcp' ? 'mcp 后端' : s.entry + ' 入口') + '' : '') +
'
' +
'
' + esc(s.description || '') + '
' +
'
' + s.file_count + ' 个文件' +
diff --git a/app/server/routes/skills.js b/app/server/routes/skills.js
index ce4d165..5961638 100644
--- a/app/server/routes/skills.js
+++ b/app/server/routes/skills.js
@@ -10,7 +10,7 @@ const multer = require('multer');
const YAML = require('yaml');
const engine = require('../engine');
const llm = require('../llm');
-const { extractDescription, listSkills, formatSkillListForPrompt } = require('../tools/skills');
+const { extractDescription, parseFrontMatter, listSkills, formatSkillListForPrompt } = require('../tools/skills');
const { sanitizeName } = require('./files');
const router = express.Router();
@@ -118,8 +118,12 @@ router.get('/', wrap(async (req, res) => {
const dir = path.join(root, e.name);
let description = '(缺 SKILL.md)';
let hasMd = false;
+ let mcpTool = '';
try {
- description = extractDescription(await fsp.readFile(path.join(dir, 'SKILL.md'), 'utf8'));
+ const content = await fsp.readFile(path.join(dir, 'SKILL.md'), 'utf8');
+ description = extractDescription(content);
+ // mcp_tool 后端没有入口脚本,徽章靠它区分(前端显示「mcp 后端」)
+ mcpTool = String(parseFrontMatter(content).mcp_tool || '').trim();
hasMd = true;
} catch (_) {}
const files = listSkillFiles(dir);
@@ -128,7 +132,7 @@ router.get('/', wrap(async (req, res) => {
description,
has_md: hasMd,
entry: fs.existsSync(path.join(dir, 'run.py')) ? 'py'
- : fs.existsSync(path.join(dir, 'run.sh')) ? 'sh' : null,
+ : fs.existsSync(path.join(dir, 'run.sh')) ? 'sh' : (mcpTool ? 'mcp' : null),
file_count: files.length,
size: files.reduce((s, f) => s + (f.size || 0), 0),
mtime: files.length ? Math.max.apply(null, files.map(f => f.mtime || 0)) : null,
@@ -156,6 +160,7 @@ router.post('/', wrap(async (req, res) => {
'## 用法',
'',
'- 入口脚本 `run.py` 或 `run.sh`,接收一个 JSON 字符串作为唯一命令行参数(含全部入参)。',
+ '- 后端是 MCP 工具时改在 front matter 写 `mcp_tool: <工具名>`,不需要入口脚本。',
'- 可选:`requirements.txt`(Python 依赖)、`install.sh`(系统依赖),首次执行前自动安装。',
'',
].join('\n');
diff --git a/app/server/server.js b/app/server/server.js
index 4ac8177..489706f 100644
--- a/app/server/server.js
+++ b/app/server/server.js
@@ -184,6 +184,17 @@ mcp.init(cfg).then(async () => {
const list = await skills.listSkills({ cfg });
llm.setSkillListText(skills.formatSkillListForPrompt(list));
log.info('startup', ' skills=' + (list.length ? list.map(s => s.name).join(', ') : '(none)'));
+ // mcp_tool 后端自检(mcp.init 已完成,注册表是本轮发现的最终状态):
+ // 启动期点名,避免模型第一次调用才撞墙;两条路并存时也告一声,方便渐进迁移。
+ const advertised = new Set(mcp.toolDefinitions().map(t => t && t.function && t.function.name));
+ for (const s of list) {
+ if (!s.mcp_tool) continue;
+ if (!mcp.hasTool(s.mcp_tool)) {
+ log.warn('startup', '技能 ' + s.name + ' 的 MCP 后端不可用:' + s.mcp_tool + '(检查 mcp_servers 与 mode)');
+ } else if (advertised.has(s.mcp_tool)) {
+ log.info('startup', '技能 ' + s.name + ' 的 MCP 后端 ' + s.mcp_tool + ' 同时下发给模型(两条路并存)');
+ }
+ }
} catch (e) {
log.warn('startup', '技能列表生成失败:' + e.message);
}
diff --git a/app/server/tools/skills.js b/app/server/tools/skills.js
index a51e4db..dcbddf6 100644
--- a/app/server/tools/skills.js
+++ b/app/server/tools/skills.js
@@ -4,6 +4,8 @@
// 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录:
// /SKILL.md(必须)、run.py | run.sh(入口)、requirements.txt、install.sh(可选)。
// 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 input_args)。
+// 后端两种:脚本(run.py/run.sh,落 executor 沙箱执行)与 MCP(front matter 声明 mcp_tool,
+// run 由 core 直接调 mcp.callTool,不经沙箱——凭证留在 core,模型只看到一行技能描述)。
const fs = require('fs');
const fsp = require('fs').promises;
const path = require('path');
@@ -11,6 +13,8 @@ const { spawn } = require('child_process');
const YAML = require('yaml');
const log = require('../log');
const rexec = require('../remote-exec');
+// 技能可声明 mcp_tool(front matter),run 时由 core 直接转发给 MCP;mcp.js 只依赖 ./log,不成环。
+const mcp = require('../mcp');
class SkillNotFoundError extends Error {
constructor(msg) { super(msg); this.name = 'SkillNotFoundError'; }
@@ -64,9 +68,16 @@ async function listSkills(ctx) {
let content;
try { content = await fsp.readFile(mdPath, 'utf8'); } catch (_) { continue; }
// frontmatter 可选 required: true —— 进 system prompt 时行首标 **required**(配合模板里的强制条款)
- let required = false;
- try { required = parseFrontMatter(content).required === true; } catch (_) {}
- out.push({ name: e.name, description: extractDescription(content), required: required });
+ // 可选 mcp_tool: —— 声明后端为 MCP 服务(run 不落沙箱),仅在声明时带该键
+ let required = false, mcpTool = '';
+ try {
+ const fm = parseFrontMatter(content);
+ required = fm.required === true;
+ mcpTool = String(fm.mcp_tool || '').trim();
+ } catch (_) {}
+ const item = { name: e.name, description: extractDescription(content), required: required };
+ if (mcpTool) item.mcp_tool = mcpTool;
+ out.push(item);
}
out.sort((a, b) => a.name.localeCompare(b.name));
return out;
@@ -211,12 +222,31 @@ async function runSkill(ctx, skillName, inputArgs) {
const mdPath = path.join(dir, 'SKILL.md');
if (!fs.existsSync(mdPath)) throw new SkillNotFoundError('技能缺少 SKILL.md:' + skillName);
- // 先把相对路径参数按会话任务目录转成绝对路径(缺任务目录时退回进程当前目录)。
+ let fm = {};
+ try { fm = parseFrontMatter(await fsp.readFile(mdPath, 'utf8')); } catch (_) {}
+
+ // MCP 后端技能(front matter 声明 mcp_tool):run 不落沙箱,由 core 直接转发给 MCP 服务。
+ // core 用 cfg.mcp_servers[].headers 里的凭证调服务,技能进程根本不参与——这是唯一
+ // 既能让模型只看到一行技能描述、又能让 key 不出 core 的路径(executor 的 env 白名单
+ // 会按名字丢掉 *KEY/*TOKEN,沙箱里既拿不到也不该拿到)。
+ // 必须在 absolutizeArgs 之前分流:它把「像路径」的参数改写成会话目录下的绝对路径,
+ // 而 URL(含 '/')与含斜杠的 prompt 都会中招。
+ // 不跑 validateArgs:MCP 工具的参数是 op 相关的(如 op=create 才要 prompt),
+ // 静态 required 列表会误伤 op=get。
+ if (fm.mcp_tool) {
+ const tool = String(fm.mcp_tool).trim();
+ if (!mcp.hasTool(tool)) {
+ throw new SkillExecutionError('技能 ' + skillName + ' 的 MCP 后端不可用:' + tool +
+ '(检查 mcp_servers 是否含该服务,且 mode 不为 disable)', 1);
+ }
+ log.info('skills', '执行 ' + skillName + ':mcp_tool=' + tool);
+ return mcp.callTool(tool, inputArgs || {}, ctx);
+ }
+
+ // 以下是脚本后端(run.py / run.sh):先把相对路径参数按会话任务目录转成绝对路径(缺任务目录时退回进程当前目录)。
const args = absolutizeArgs(inputArgs || {}, ctx.taskDir || process.cwd());
const payload = JSON.stringify(args);
- let fm = {};
- try { fm = parseFrontMatter(await fsp.readFile(mdPath, 'utf8')); } catch (_) {}
validateArgs(fm, args, skillName);
let entry, cmdArgs;
@@ -231,7 +261,7 @@ async function runSkill(ctx, skillName, inputArgs) {
entry = 'bash';
cmdArgs = [runSh, payload];
} else {
- throw new SkillExecutionError('技能 ' + skillName + ' 缺少入口 run.py 或 run.sh', 1);
+ throw new SkillExecutionError('技能 ' + skillName + ' 缺少入口 run.py 或 run.sh(也未声明 mcp_tool)', 1);
}
// cwd:远端取会话目录(executor 侧命中 session 隔离,技能看到的 /workspace/tasks/
diff --git a/skills/README.md b/skills/README.md
index 20b786f..84147b2 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -22,7 +22,7 @@
skills/
└── /
├── 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 格式要求
diff --git a/skills/image/SKILL.md b/skills/image/SKILL.md
new file mode 100644
index 0000000..e35f203
--- /dev/null
+++ b/skills/image/SKILL.md
@@ -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: `
+
+## 注意
+
+- 生成通常 10~60 秒。看到 `PROCESSING` 就过几秒再查,不要连续轮询。
+- 结果只有 URL,不落盘。要在会话里使用图片,用 `terminal` 下载:
+ `curl -fsSL -o out.png ""`,之后 `read_file` 可以直接看图。
+- 要让外部服务取这张图,先下载成本地文件,再用 `mint_public_link` 签发链接。
+- 模型名与出图参数由服务端配置决定,调用时不需要也不该传。
diff --git a/skills/video/SKILL.md b/skills/video/SKILL.md
new file mode 100644
index 0000000..0235e39
--- /dev/null
+++ b/skills/video/SKILL.md
@@ -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: `
+
+## 注意
+
+- 生成通常 1~5 分钟。`PROCESSING` 时不要高频轮询:可以先把其它事做完,再回来查。
+- 结果只有 URL,不落盘;需要本地文件时用 `terminal` 的 `curl -fsSL -o out.mp4 ""`。
+- 图生视频的参考图必须公网可达:本地文件先 `mint_public_link`,再把它返回的地址填进 `image_url`。
+- 模型名、分辨率、帧率、水印等由服务端配置决定,调用时不需要传。