From 955e550b29683ec8886b0bf0df4c7f9d10b915e4 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 21 Oct 2026 11:01:50 +0800 Subject: [PATCH] =?UTF-8?q?feat(mcp):=20=E5=A2=9E=E5=8A=A0=20mode=3Dskill?= =?UTF-8?q?=EF=BC=8C=E6=8A=8A=20MCP=20=E5=B7=A5=E5=85=B7=E4=BB=A5=E6=8A=80?= =?UTF-8?q?=E8=83=BD=E5=BD=A2=E5=BC=8F=E6=9A=B4=E9=9C=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 首行改为自解释的一句话(技能清单取首行) --- README.md | 23 ++++---- app/AGENTS.md | 16 +++--- app/config.example.yml | 4 +- app/server/config.js | 11 ++-- app/server/mcp.js | 49 +++++++++++------ app/server/public/index.html | 2 +- app/server/public/js/settings.js | 8 +-- app/server/routes/skills.js | 10 ++-- app/server/server.js | 15 +----- app/server/tools/executor.js | 6 ++- app/server/tools/skills.js | 90 +++++++++++++++++++------------- mcp/image_task/src/mcp-server.js | 2 +- mcp/video_task/src/mcp-server.js | 2 +- scripts/init.sh | 2 + skills/README.md | 39 +++++++------- skills/image/SKILL.md | 42 --------------- skills/video/SKILL.md | 45 ---------------- 17 files changed, 152 insertions(+), 214 deletions(-) delete mode 100644 skills/image/SKILL.md delete mode 100644 skills/video/SKILL.md diff --git a/README.md b/README.md index c144794..d494eac 100644 --- a/README.md +++ b/README.md @@ -112,13 +112,13 @@ mcp_servers: 每个服务可用 `mode` 控制「工具是否下发给模型」: -| `mode` | 连接/发现 | 模型可见 | 谁可以调用 | -|---|---|---|---| -| `advertise`(默认) | ✓ | ✓ | 模型与技能 | -| `silent` | ✓ | ✗ | 技能(`mcp_tool`)与 `lab` | -| `disable` | ✗ | ✗ | 无人 | +| `mode` | 连接/发现 | 进 tools 数组 | 进技能清单 | 谁可以调用 | +|---|---|---|---|---| +| `advertise`(默认) | ✓ | ✓ | ✗ | 模型与技能 | +| `skill` | ✓ | ✗ | ✓ | `skill` 工具与 `lab` | +| `disable` | ✗ | ✗ | ✗ | 无人 | -`silent` 用于「能力包在技能后面」的场景:工具照常发现并注册,只是不进模型的 tools 数组,省掉每轮的 schema 开销。旧字段 `enable` 已废弃,写进配置会直接启动报错。 +`skill` 用于「能力包在技能后面」的场景:工具照常发现并注册,只是不进模型的 tools 数组,改为以技能形式暴露——`{"list":"all"}` 能看到它,`{"get":"<名>"}` 直接返回 MCP 原始的 `description` + `input_schema`,`{"run":"<名>","args":{…}}` 转发给服务。不用在 `skills/` 里建目录。旧字段 `enable` 已废弃,`mode: silent` 已移除(启动会报错并提示改用 `skill`)。 工具发现只在启动时做一次,因此发现失败后会自动按 **2s / 20s / 1min 重试 3 次**(覆盖 compose 并行拉起与宿主机重启后的容器乱序);成功后工具在下一轮请求即可用,三次都失败则需重启 core。三个 MCP 服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。 @@ -196,7 +196,7 @@ mcp_servers: | `model_profiles` | prompt + 工具名单组合;模型用 `profile: <名>` 引用 | | `tools_deny` | 全局工具黑名单,默认屏蔽元工具 `lab` | | `auth` | 登录账号、`secret`、有效期;留空则不启用认证 | -| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`mode`(advertise / silent / disable)、`timeout_ms`、工具名单 | +| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`mode`(advertise / skill / disable)、`timeout_ms`、工具名单 | | `public_link` | 公网临时链接前缀与有效期 | | `agent` | 温度、最大工具迭代、重试、语言、压缩阈值、空闲收口、历史裁剪 | | `memory` | 日记注入条数、保留期、空闲收口阈值 | @@ -280,17 +280,16 @@ platforms: ```text skills/my-skill/ -├── SKILL.md # 必需:描述、input_schema、可选 required / visit_url / mcp_tool -├── run.py | run.sh # 入口,唯一命令行参数是 JSON 字符串(声明 mcp_tool 时不需要) +├── SKILL.md # 必需:描述、input_schema、可选 required / visit_url +├── run.py | run.sh # 入口,唯一命令行参数是 JSON 字符串 ├── requirements.txt # 可选:Python 依赖 └── install.sh # 可选:系统层安装脚本,镜像构建期执行 ``` - `SKILL.md` 的 `description` 会进入 system prompt,模型启动时就知道有哪些技能。 - `input_schema.required` 在 `{"run":"<名>","args":{...}}` 前校验。 -- `mcp_tool`:声明后端为某个 MCP 工具。此时 `run` 由 core 直接转发给 MCP(不落沙箱、不需要密钥), - 配合该服务的 `mode: silent` 就能把工具从模型的 tools 数组里隐藏,只留一行技能描述。仓库自带的 - `skills/image`、`skills/video` 就是这么封装的 `image_task` / `video_task`。 +- MCP 工具不用建目录:给该服务配 `mode: skill`,平台会自动把它暴露成技能(`get` 返回 MCP 原始的 + `input_schema`,`run` 转发),见上文「同栈 MCP 服务」。 - 入口脚本以绝对路径启动;远端执行时 cwd 是会话目录,本地开发时是技能目录。相对路径参数会先按会话目录转成绝对路径。 - `requirements.txt` 的依赖由 `agent-executor-init` 安装到 `skills/deps`;技能容器通过 `PYTHONPATH` 可见。 - `install.sh` 在镜像构建期以 root 执行,用于必须落在系统层的依赖。改完需要重建 executor 镜像。 diff --git a/app/AGENTS.md b/app/AGENTS.md index dd36f6b..64d21c3 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -158,9 +158,11 @@ POST /api/sessions/:id/messages 白名单、`tools_deny` 黑名单(**deny 赢**;profile 不配 deny 时继承全局 `tools_deny`)。 `tools_allow: []` = 零工具(纯文本组合)。过滤只影响"模型看得到什么",名单外工具若真被调用, `executeTool` 仍会执行(不误杀)。 -- MCP 服务按 `mcp_servers[].mode` 参与:`advertise`(默认)进 `toolDefs` 下发;`silent` 只进 - `toolIndex`(`mcp.hasTool` 为真,技能 `mcp_tool` 与 `lab` 可调)但不进 tools 数组;`disable` - 连 `tools/list` 都不发。旧字段 `enable` 已废弃,出现即报配置错(不静默忽略)。 +- MCP 服务按 `mcp_servers[].mode` 参与:`advertise`(默认)进 `toolDefs` 下发;`skill` 只进 + `toolIndex`(`mcp.hasTool` 为真,`lab` 可调),且由 `skills.js` 自动 + 包装成技能(`mcp.skillTools()` / `getSkillTool()`,get 返回注册表里的原始 inputSchema); + `disable` 连 `tools/list` 都不发。旧字段 `enable` 已废弃,`mode: silent` 已移除, + 出现即报配置错(不静默忽略)。 - `executeTool(baseCtx, name, args)`:先查 `HANDLERS` 表,未命中再交给 MCP 注册表。 `ctx = {sessionId, taskDir, run, cfg, db, vision}`;工具返回字符串,`read_file` 读图时返回 `{text, image_rel}`(由 engine 转成 `image_ref` 块)。 @@ -176,9 +178,11 @@ POST /api/sessions/:id/messages `run` 前校验;相对路径参数按会话目录转绝对路径;入口一律用绝对路径(远端 cwd 是会话目录)。 配了 executor 就走 `remote-exec`,否则本地 `spawn`。旧形状 `{op, name, input_args}` 仅由 `toolSkill` 兜底翻译(存量技能文档里还写着它),不再对外文档化。 - 声明了 `mcp_tool` 的技能走另一条后端:`runSkill` 在 `absolutizeArgs` **之前**分流,由 core - 直接 `mcp.callTool` 转发(不落沙箱,所以也不需要任何密钥);否则 URL 与含 `/` 的 prompt 会被 - 当路径改写。此时不跑 `input_schema.required` 校验(参数与 MCP 工具自己的 `op` 相关,交给服务管)。 + 模型可见的技能清单是 `listCallableSkills`(目录技能 + `mode=skill` 的 MCP 工具,同名时目录胜出); + 设置页的技能 API 仍只用 `listSkills`(按目录增删改),两者不要混用。 + mode=skill 的 MCP 技能在 `runSkill` 里位于 `absolutizeArgs` **之前**:直接 `mcp.callTool` 转发 + (不落沙箱,也不需要密钥),因此 URL 与含 `/` 的 prompt 不会被当路径改写;同样不跑 + `input_schema.required` 校验(参数与 MCP 工具自己的 `op` 相关,交给服务管)。 - 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/config.example.yml b/app/config.example.yml index 9b0909f..86e4207 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -79,8 +79,8 @@ auth: # users 留空 = 不启用登 # model: qwen-tp/qwen3.8-flash # 选填:该用户新建会话时锁定的模型(内部键「平台名/模型id」) # MCP 服务列表(仓库自带的 mcp/ 三个服务,或栈外服务):每项 {name?, url, headers?, mode?(默认 advertise), timeout_ms?, tools_allow?, tools_deny?}。 -# mode 三态:advertise=工具下发给模型;silent=只注册可调用(技能 mcp_tool / lab)不下发;disable=不连接、不发现。 -# 旧字段 enable 已废弃,写进配置会启动报错。 +# mode 三态:advertise=工具下发给模型;skill=不下发,改为以技能形式暴露(get 返回原始 input_schema,run 转发); +# disable=不连接、不发现。旧字段 enable 已废弃;mode: silent 已移除(改用 skill),写进配置会启动报错。 mcp_servers: [] public_link: diff --git a/app/server/config.js b/app/server/config.js index 5342ca3..1eabf22 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -122,7 +122,8 @@ const DEFAULTS = { // 登录认证:{users:[{user,password}], secret?, ttl_ms?};null / users 空 = 不启用。 auth: null, // 外部 MCP 服务列表(无默认值):{name?, url, headers?, mode?(默认 advertise), timeout_ms?(默认 60s)}。 - // mode 三态:advertise=工具下发给模型;silent=只注册可调用(技能/lab)不下发;disable=不加载。 + // mode 三态:advertise=工具下发给模型;skill=不下发,改为以技能形式暴露(get 返回原始 + // input_schema,run 直接转发);disable=不加载。 mcp_servers: [], // 公网临时链接:base_url 非空才启用 mint_public_link;容器配 VIRTUAL_HOST 时以它为准。 public_link: { base_url: '', ttl_ms: 1800000 }, @@ -352,14 +353,14 @@ function parseAndValidate(rawText, configPath) { // 旧字段 enable 已废弃且不静默忽略:未知键会被无声丢弃,那样「以为关了」的服务会照常连上、 // 照常烧额度。宁可启动即报错,把迁移动作逼到明面上。 if (s.enable !== undefined) { - throw new Error('mcp_servers 的 enable 已废弃,请改用 mode: advertise | silent | disable'); + throw new Error('mcp_servers 的 enable 已废弃,请改用 mode: advertise | skill | disable'); } - // 三态:advertise(默认,工具下发给模型)/ silent(注册但不下发,配合技能 mcp_tool 使用)/ + // 三态:advertise(默认,工具下发给模型)/ skill(不下发,改为以技能形式暴露)/ // disable(不连接、不发现)。拼错要报错而不是回落默认,否则又是一次静默降级。 const mode = String(s.mode == null ? '' : s.mode).trim().toLowerCase(); if (!mode) s.mode = 'advertise'; - else if (mode === 'advertise' || mode === 'silent' || mode === 'disable') s.mode = mode; - else throw new Error('mcp_servers 的 mode 只能是 advertise / silent / disable,收到:' + mode); + else if (mode === 'advertise' || mode === 'skill' || mode === 'disable') s.mode = mode; + else throw new Error('mcp_servers 的 mode 只能是 advertise / skill / disable,收到:' + mode); const headers = {}; for (const [k, v] of Object.entries(s.headers || {})) headers[k] = String(v); s.headers = headers; diff --git a/app/server/mcp.js b/app/server/mcp.js index 1beec41..b7e53d2 100644 --- a/app/server/mcp.js +++ b/app/server/mcp.js @@ -3,7 +3,8 @@ // 启动时 init() 对每个服务调 tools/list 发现工具(mode: disable 的服务跳过加载;配了 tools_allow/tools_deny // 时按名单过滤),发现失败的服务按 2s / 20s / 1min 再试 3 次(容器并行启动/重启后的乱序兜底),转成 OpenAI function 格式, // 追加在内置工具(definitions.json)之后一起随 system prompt 发给模型; -// mode: silent 的服务工具照常注册进 toolIndex(技能 mcp_tool / lab 可调),只是不追加进 toolDefs(模型看不到)。 +// mode: skill 的服务工具照常注册进 toolIndex(lab 可调),不追加进 +// toolDefs,而是由 tools/skills.js 自动包装成技能(get 返回注册表里的原始 input_schema)。 // 工具调用经 tools/call 转发给对应服务。 // 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名, // 仅当与内置工具或其他 MCP 工具重名时加「服务名__」前缀。 @@ -15,7 +16,7 @@ const log = require('./log'); const CALL_TIMEOUT_MS = 60000; let toolDefs = []; // OpenAI function 格式(所有 MCP 工具) -const toolIndex = new Map(); // 发送名 -> { server, tool }(服务配置 + 原始工具名) +const toolIndex = new Map(); // 发送名 -> { server, tool, def }(服务配置 + 原始工具名 + 原始契约) let builtinNames = new Set(); let PUBLIC_BASE = ''; // core 自身公网前缀(loadConfig 已归一:VIRTUAL_HOST 优先 config.yml);随每次请求 X-Public-Base 头下发 @@ -147,21 +148,20 @@ async function loadServer(s) { if (!t || !t.name) continue; let name = t.name; if (builtinNames.has(name) || toolIndex.has(name)) name = s.name + '__' + name; - // 先进索引:silent 的工具要能被技能(mcp_tool)与 lab 调到,只是不下发。 - toolIndex.set(name, { server: s, tool: t.name }); - if (s.mode === 'silent') { hidden++; continue; } - toolDefs.push({ - type: 'function', - function: { - name, - description: t.description || t.title || '', - parameters: t.inputSchema || t.input_schema || { type: 'object', properties: {} }, - }, - }); + // 先进索引:mode=skill 的工具同样要能被 lab 调到,只是不下发。 + // 索引里连规范化后的契约一起留住,技能 get 时原样返回(单一份真相,不会跟 MCP 实现漂移)。 + const def = { + name, + description: t.description || t.title || '', + parameters: t.inputSchema || t.input_schema || { type: 'object', properties: {} }, + }; + toolIndex.set(name, { server: s, tool: t.name, def }); + if (s.mode === 'skill') { hidden++; continue; } + toolDefs.push({ type: 'function', function: def }); } let msg = s.name + ': 发现 ' + tools.length + ' 个工具' + (s.sessionId ? ' (session)' : ''); if (tools.length !== all.length) msg += '(服务端共 ' + all.length + ' 个,已按 tools_allow/tools_deny 过滤)'; - if (hidden) msg += '(mode=silent:' + hidden + ' 个不下发给模型,仅供技能调用)'; + if (hidden) msg += '(mode=skill:' + hidden + ' 个以技能形式暴露,不下发给模型)'; log.info('mcp', msg); // 配了名单却一个都没过滤中,十有八九是名单里的名字跟 tools/list 返回不一致; // 不 warn 的话排查时只能对着「发现 0 个工具」干瞪眼。 @@ -233,6 +233,25 @@ function toolDefinitions() { return toolDefs; } function hasTool(name) { return toolIndex.has(name); } +// mode=skill 的工具:不进 tools 数组,由 skills.js 包装成技能(list/get/run)。 +// 名字一律用最终可调用名(含重名时的 server__ 前缀),否则模型拿到的是调不通的名字。 +function skillTools() { + const out = []; + for (const [name, e] of toolIndex) { + if (!e || !e.server || e.server.mode !== 'skill' || !e.def) continue; + out.push({ name, description: e.def.description, parameters: e.def.parameters, server: e.server.name, tool: e.tool }); + } + return out; +} + +// 只认 mode=skill:advertise 的工具已经直接下发给模型,不必再绕技能这一层。 +function getSkillTool(name) { + const key = String(name == null ? '' : name).trim(); + const e = toolIndex.get(key); + if (!e || !e.server || e.server.mode !== 'skill' || !e.def) return null; + return { name: key, description: e.def.description, parameters: e.def.parameters, server: e.server.name, tool: e.tool }; +} + // 把工具调用转发给对应 MCP 服务,返回给模型的文本结果。 // 超时取该服务的 timeout_ms(config.js 里归一化 + 夹过区间);这里再兜一次底, // 兼容没走配置加载的调用方(如测试里手搓的 cfg)。 @@ -276,4 +295,4 @@ async function notifyTool(name, args, timeoutMs, extraHeaders) { } } -module.exports = { init, toolDefinitions, hasTool, callTool, notifyTool }; +module.exports = { init, toolDefinitions, hasTool, skillTools, getSkillTool, callTool, notifyTool }; diff --git a/app/server/public/index.html b/app/server/public/index.html index 73427e0..40813bc 100644 --- a/app/server/public/index.html +++ b/app/server/public/index.html @@ -339,7 +339,7 @@ diff --git a/app/server/public/js/settings.js b/app/server/public/js/settings.js index 3901759..60e6a14 100644 --- a/app/server/public/js/settings.js +++ b/app/server/public/js/settings.js @@ -1421,7 +1421,7 @@ // · 新增 = append 到 mcp_servers; // · 删 = delete mcp_servers[pi]; // · 改 = setIn mcp_servers[pi].(name|url|timeout_ms|mode);headers 是普通键值对象,整体 setIn 一次到位。 - // mode 三态:advertise(默认,工具下发给模型) / silent(只注册可调用,不下发) / disable(不加载): + // mode 三态:advertise(默认,工具下发给模型) / skill(不下发,以技能形式暴露) / disable(不加载): // 默认值不写进文件——选 advertise 时删键,回落到 config.js 的缺省。 // 运行配置(cg.effective.mcp_servers)即文件刚解析后的视图,按 pi 直接定位;重启后才会重新发现工具。 let mcpEdit = null; // 工作态:{ idx, headers:[{key, value, masked}] };idx=-1 为新增 @@ -1451,7 +1451,7 @@ ? '
配置已写入,重启后生效
' : ''; box.innerHTML = banner + SET.cfgMcp.map(mcpCardHtml).join('') + - '
点卡片编辑 MCP 服务。advertise 的工具启动时发现并追加到内置工具之后;silent 只注册可调用(供技能 mcp_tool),不下发给模型。
'; + '
点卡片编辑 MCP 服务。advertise 的工具启动时发现并追加到内置工具之后;skill 不下发,改为以技能形式暴露(skill 工具里 get 拿到原始 input_schema)。
'; } catch (e) { const b = $('mcp-list'); if (b && (!ctx || ctx())) b.innerHTML = '
加载失败:' + esc(e.message) + '
'; @@ -1462,8 +1462,8 @@ const mode = s.mode || 'advertise'; const stateHtml = mode === 'disable' ? '已禁用' - : mode === 'silent' - ? '仅技能可见' + : mode === 'skill' + ? '以技能暴露' : '启用'; const entries = Object.entries(s.headers || {}); // header 值等同密码对待:后端 effective 已脱敏为固定短掩码,这里透传展示;若收到未脱敏原文也一律替换,不外显 diff --git a/app/server/routes/skills.js b/app/server/routes/skills.js index 67f0330..f39c434 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, parseFrontMatter, listSkills, formatSkillListForPrompt } = require('../tools/skills'); +const { extractDescription, listCallableSkills, formatSkillListForPrompt } = require('../tools/skills'); const { sanitizeName } = require('./files'); const router = express.Router(); @@ -79,7 +79,7 @@ function absInSkill(dir, rel) { // 模型立即感知新技能或改名,无需重启。fire-and-forget:扫描失败不影响 API 响应, // skill {"list":"all"} 仍是实时兜底。 function refreshSkillPrompt() { - listSkills({ cfg: engine.getConfig() }) + listCallableSkills({ cfg: engine.getConfig() }) .then(list => llm.setSkillListText(formatSkillListForPrompt(list))) .catch(() => {}); } @@ -118,12 +118,9 @@ router.get('/', wrap(async (req, res) => { const dir = path.join(root, e.name); let description = '(缺 SKILL.md)'; let hasMd = false; - let mcpTool = ''; try { 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); @@ -132,7 +129,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' : (mcpTool ? 'mcp' : null), + : fs.existsSync(path.join(dir, 'run.sh')) ? 'sh' : 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, @@ -160,7 +157,6 @@ 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 6649365..31bacb7 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -181,20 +181,9 @@ mcp.init(cfg).then(async () => { // 技能列表快照:模型直接感知已有技能,免先 {"list":"all"} 探索; // 此处失败不阻塞启动,{"list":"all"} 仍可做实时兜底。 try { - const list = await skills.listSkills({ cfg }); + const list = await skills.listCallableSkills({ 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); } @@ -205,7 +194,7 @@ mcp.init(cfg).then(async () => { log.info('startup', ' data_root=' + cfg.data_root); log.info('startup', ' models=' + cfg.models.map(m => m.id + '@' + m.url).join(', ')); const mcpList = (cfg.mcp_servers || []).map(s => s.name + '@' + s.url + - (s.mode === 'disable' ? '(禁用)' : s.mode === 'silent' ? '(仅技能)' : '')).join(', '); + (s.mode === 'disable' ? '(禁用)' : s.mode === 'skill' ? '(技能)' : '')).join(', '); log.info('startup', ' mcp_servers=' + (mcpList || '(none)')); log.info('startup', ' auth=' + (auth.enabled ? 'login: ' + cfg.auth.users.map(u => u.user).join(', ') : '(disabled)')); log.info('startup', ' wxbot=' + (cfg.wxbot.url && cfg.wxbot.token ? cfg.wxbot.url : '(未启用)')); diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index 369c4ee..27cf2db 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -1504,6 +1504,8 @@ function toolDb(ctx, args) { // list 的值是范围而非布尔:将来技能分类落地时直接扩成 {list:"<分类>"},调用形状不变, // 模型不用学第二套写法。今天只认 "all" 且报错点名——静默返回全部会让错拼的分类名 // 看起来「能用」,将来接分类时更难排查。 +// {list:"all"} 的清单 = 目录技能 + mode=skill 的 MCP 工具;get/run 对两者一视同仁: +// 目录技能读 SKILL.md,MCP 技能直接回注册表里的原始 input_schema。 // args 仅 run 用且可缺省:runSkill 把 null 视作 {},真正缺哪些字段由各技能 input_schema // 校验点名报错(工具层再 gate 一层是双重门槛,无益)。 // 旧形状 {op, name, input_args} 仍接受:存量技能文档的调用示例里写的是它,模型 get 到 @@ -1554,7 +1556,7 @@ async function legacyToolSkill(ctx, a) { const name = String(a.name == null ? '' : a.name).trim(); switch (op) { case 'list': - return JSON.stringify(await skills.listSkills(ctx), null, 2); + return JSON.stringify(await skills.listCallableSkills(ctx), null, 2); case 'get': if (!name) throw new Error('op=get 缺少技能名。' + SKILL_USAGE); return skills.getSkillInfo(ctx, name); @@ -1582,7 +1584,7 @@ async function toolSkill(ctx, args) { const scope = String(a.list).trim().toLowerCase(); if (scope !== 'all') throw new Error('list 目前只支持 "all"(技能分类尚未提供),收到:"' + scope + '"'); rejectSkillArgs(a, 'list'); - return JSON.stringify(await skills.listSkills(ctx), null, 2); + return JSON.stringify(await skills.listCallableSkills(ctx), null, 2); } const name = skillNameArg(a[verb], verb); if (verb === 'get') { diff --git a/app/server/tools/skills.js b/app/server/tools/skills.js index f52e8c2..07cf97c 100644 --- a/app/server/tools/skills.js +++ b/app/server/tools/skills.js @@ -4,8 +4,9 @@ // 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录: // /SKILL.md(必须)、run.py | run.sh(入口)、requirements.txt、install.sh(可选)。 // 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 args)。 -// 后端两种:脚本(run.py/run.sh,落 executor 沙箱执行)与 MCP(front matter 声明 mcp_tool, -// run 由 core 直接调 mcp.callTool,不经沙箱——凭证留在 core,模型只看到一行技能描述)。 +// 后端两种:脚本(run.py/run.sh,落 executor 沙箱执行)与 MCP(core 直接 mcp.callTool 转发, +// 不经沙箱——凭证留在 core)。MCP 技能不落目录:服务配成 mode=skill 时由平台自动暴露, +// 参数契约直接取注册表里的原始 input_schema。 const fs = require('fs'); const fsp = require('fs').promises; const path = require('path'); @@ -13,7 +14,7 @@ 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,不成环。 +// mode=skill 的 MCP 工具在 get/run 时由 core 直接转发;mcp.js 只依赖 ./log,不成环。 const mcp = require('../mcp'); class SkillNotFoundError extends Error { @@ -68,22 +69,44 @@ async function listSkills(ctx) { let content; try { content = await fsp.readFile(mdPath, 'utf8'); } catch (_) { continue; } // frontmatter 可选 required: true —— 进 system prompt 时行首标 **required**(配合模板里的强制条款) - // 可选 mcp_tool: —— 声明后端为 MCP 服务(run 不落沙箱),仅在声明时带该键 - let required = false, mcpTool = ''; + let required = false; try { - const fm = parseFrontMatter(content); - required = fm.required === true; - mcpTool = String(fm.mcp_tool || '').trim(); + required = parseFrontMatter(content).required === true; } catch (_) {} - const item = { name: e.name, description: extractDescription(content), required: required }; - if (mcpTool) item.mcp_tool = mcpTool; - out.push(item); + out.push({ name: e.name, description: extractDescription(content), required: required }); + } + out.sort((a, b) => a.name.localeCompare(b.name)); + return out; +} + +// ---------- MCP 技能(mode=skill)---------- +// mode=skill 的服务:工具不进 tools 数组,而是自动成为技能。既省掉每轮的 schema 开销, +// 又不用在 skills_root 里建目录、手抄一份参数说明——get 直接返回注册表里的原始 input_schema。 +// 目录技能优先:同名时目录技能胜出并打 warn。手写包装可以遮住自动版,迁移期也不会撞车。 + +// MCP 的 description 常是多段文本;清单里只取第一行,完整内容留给 get。 +function firstLine(s) { + const line = String(s == null ? '' : s).split(/\r?\n/).map(l => l.trim()).find(Boolean); + return line || '(无描述)'; +} + +// 模型可见的技能全集 = 目录技能 + mode=skill 的 MCP 工具。 +// 设置页的技能 API 只用 listSkills(它按目录增删改),不要混用这个函数。 +async function listCallableSkills(ctx) { + const dir = await listSkills(ctx); + const taken = new Set(dir.map(s => s.name)); + const out = dir.slice(); + for (const t of mcp.skillTools()) { + if (taken.has(t.name)) { + log.warn('skills', 'MCP 工具 ' + t.name + ' 与目录技能同名,按目录技能处理(mode=skill 的这份被遮蔽)'); + continue; + } + out.push({ name: t.name, description: firstLine(t.description), required: false }); } out.sort((a, b) => a.name.localeCompare(b.name)); return out; } -// ---------- system prompt 注入:可用技能列表 ---------- // 把技能列表格式化成 “## Available Skills” 段落(每行 `- [**required** ]名字: 描述`; // listSkills 已按名字 localeCompare 排序,行序恒定,不破坏前缀缓存; // 参数查 get,执行 run;描述如需实时复核仍可查 list)。 @@ -104,10 +127,12 @@ function formatSkillListForPrompt(list) { async function getSkillInfo(ctx, skillName) { const dir = skillDir(ctx, skillName); const mdPath = path.join(dir, 'SKILL.md'); - if (!fs.existsSync(mdPath)) { - throw new SkillNotFoundError('技能不存在或缺少 SKILL.md:' + skillName); - } - return fsp.readFile(mdPath, 'utf8'); + if (fs.existsSync(mdPath)) return fsp.readFile(mdPath, 'utf8'); + // mode=skill 的 MCP 技能没有目录:直接返回注册表里的原始契约(description + input_schema), + // 模型看到的就是服务端实际声明的参数,不存在手抄副本漂移的问题。 + const t = mcp.getSkillTool(skillName); + if (t) return JSON.stringify({ name: t.name, description: t.description, input_schema: t.parameters }, null, 2); + throw new SkillNotFoundError('技能不存在或缺少 SKILL.md:' + skillName); } // ---------- 参数路径预处理 ---------- @@ -217,7 +242,16 @@ async function runSkill(ctx, skillName, inputArgs) { throw new SkillExecutionError('技能参数必须是对象(键值参数),收到:' + JSON.stringify(inputArgs).slice(0, 80), 1); } const dir = skillDir(ctx, skillName); - if (!fs.existsSync(dir)) throw new SkillNotFoundError('技能不存在:' + skillName); + if (!fs.existsSync(dir)) { + // mode=skill 的 MCP 技能:直接转发。同样不做 absolutizeArgs——URL 与含 '/' 的 prompt + // 会被当成路径改写坏;也不做 validateArgs,参数与 MCP 工具自己的 op 相关。 + const t = mcp.getSkillTool(skillName); + if (t) { + log.info('skills', '执行 MCP 技能 ' + t.name + ' → ' + t.server + '/' + t.tool); + return mcp.callTool(t.name, inputArgs || {}, ctx); + } + throw new SkillNotFoundError('技能不存在:' + skillName); + } const mdPath = path.join(dir, 'SKILL.md'); if (!fs.existsSync(mdPath)) throw new SkillNotFoundError('技能缺少 SKILL.md:' + skillName); @@ -225,24 +259,6 @@ async function runSkill(ctx, skillName, inputArgs) { 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); @@ -261,7 +277,7 @@ async function runSkill(ctx, skillName, inputArgs) { entry = 'bash'; cmdArgs = [runSh, payload]; } else { - throw new SkillExecutionError('技能 ' + skillName + ' 缺少入口 run.py 或 run.sh(也未声明 mcp_tool)', 1); + throw new SkillExecutionError('技能 ' + skillName + ' 缺少入口 run.py 或 run.sh', 1); } // cwd:远端取会话目录(executor 侧命中 session 隔离,技能看到的 /workspace/tasks/ @@ -273,4 +289,4 @@ async function runSkill(ctx, skillName, inputArgs) { return runEntry(ctx, entry, cmdArgs, execCwd, timeoutMs); } -module.exports = { listSkills, getSkillInfo, runSkill, skillsRoot, parseFrontMatter, extractDescription, formatSkillListForPrompt }; +module.exports = { listSkills, listCallableSkills, getSkillInfo, runSkill, skillsRoot, parseFrontMatter, extractDescription, formatSkillListForPrompt }; diff --git a/mcp/image_task/src/mcp-server.js b/mcp/image_task/src/mcp-server.js index 1b85e10..d9d7ec0 100644 --- a/mcp/image_task/src/mcp-server.js +++ b/mcp/image_task/src/mcp-server.js @@ -303,7 +303,7 @@ function buildServer() { server.tool( "image_task", - `Manages asynchronous image generation tasks. + `AI image generation. op=create Submit a new task. Returns a task_id immediately; generation runs in background. Requires prompt. diff --git a/mcp/video_task/src/mcp-server.js b/mcp/video_task/src/mcp-server.js index 92a9467..32ac6e0 100644 --- a/mcp/video_task/src/mcp-server.js +++ b/mcp/video_task/src/mcp-server.js @@ -336,7 +336,7 @@ function buildServer() { server.tool( "video_task", - `Manages asynchronous video generation tasks. + `AI video generation. op=create Submit a new task. Returns a task_id immediately; generation runs asynchronously. Requires at least one of prompt or image_url. diff --git a/scripts/init.sh b/scripts/init.sh index acf703f..c231bfd 100755 --- a/scripts/init.sh +++ b/scripts/init.sh @@ -211,10 +211,12 @@ EOF url: "http://mcp_image_task:3000/mcp" headers: Authorization: "Bearer $BIGMODEL_KEY" + mode: skill # 不下发给模型,以技能形式暴露(skill 工具里 list/get/run) - name: video_task url: "http://mcp_video_task:3000/mcp" headers: Authorization: "Bearer $BIGMODEL_KEY" + mode: skill EOF else cat <<'EOF' diff --git a/skills/README.md b/skills/README.md index 44decd3..24ac8f1 100644 --- a/skills/README.md +++ b/skills/README.md @@ -22,7 +22,7 @@ skills/ └── / ├── 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` 的工具数量,便于确认暴露是否生效。 --- diff --git a/skills/image/SKILL.md b/skills/image/SKILL.md deleted file mode 100644 index ed94485..0000000 --- a/skills/image/SKILL.md +++ /dev/null @@ -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: ` - -## 注意 - -- 生成通常 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 deleted file mode 100644 index c7ed9cb..0000000 --- a/skills/video/SKILL.md +++ /dev/null @@ -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: ` - -## 注意 - -- 生成通常 1~5 分钟。`PROCESSING` 时不要高频轮询:可以先把其它事做完,再回来查。 -- 结果只有 URL,不落盘;需要本地文件时用 `terminal` 的 `curl -fsSL -o out.mp4 ""`。 -- 图生视频的参考图必须公网可达:本地文件先 `mint_public_link`,再把它返回的地址填进 `image_url`。 -- 模型名、分辨率、帧率、水印等由服务端配置决定,调用时不需要传。