diff --git a/README.md b/README.md index 448ef4f..87b032a 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ PUBLIC_IP=1.2.3.4 \ - `.env`:`EXECUTOR_TOKEN`、`WXBOT_TOKEN`、`AGENT_PORT` 等部署变量。 - `config.yml`:模型平台、登录账号、MCP 服务、公网前缀。 -`image_task` / `video_task` 两个 MCP 服务复用 `BIGMODEL_KEY`(智谱与 BigModel 是同一个 key);未配置 `BIGMODEL_KEY` 时它们以 `enable: false` 写入配置。 +`image_task` / `video_task` 两个 MCP 服务复用 `BIGMODEL_KEY`(智谱与 BigModel 是同一个 key);未配置 `BIGMODEL_KEY` 时它们以 `mode: disable` 写入配置。 `AUTH_USER` / `AUTH_PASSWORD` 不传时默认是 `admin` / `admin`,首次部署务必改掉。 @@ -110,6 +110,16 @@ mcp_servers: 接入栈外的 MCP 服务:在设置页添加 `url` / `headers`,或在 `config.yml` 的 `mcp_servers` 追加一项。服务不可达时 core 只在启动日志里告警,不影响 Web 主流程,但对应工具不会下发给模型。 +每个服务可用 `mode` 控制「工具是否下发给模型」: + +| `mode` | 连接/发现 | 模型可见 | 谁可以调用 | +|---|---|---|---| +| `advertise`(默认) | ✓ | ✓ | 模型与技能 | +| `silent` | ✓ | ✗ | 技能(`mcp_tool`)与 `lab` | +| `disable` | ✗ | ✗ | 无人 | + +`silent` 用于「能力包在技能后面」的场景:工具照常发现并注册,只是不进模型的 tools 数组,省掉每轮的 schema 开销。旧字段 `enable` 已废弃,写进配置会直接启动报错。 + 工具发现只在启动时做一次,因此发现失败后会自动按 **2s / 20s / 1min 重试 3 次**(覆盖 compose 并行拉起与宿主机重启后的容器乱序);成功后工具在下一轮请求即可用,三次都失败则需重启 core。三个 MCP 服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。 --- @@ -186,7 +196,7 @@ mcp_servers: | `model_profiles` | prompt + 工具名单组合;模型用 `profile: <名>` 引用 | | `tools_deny` | 全局工具黑名单,默认屏蔽元工具 `lab` | | `auth` | 登录账号、`secret`、有效期;留空则不启用认证 | -| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`enable`、`timeout_ms`、工具名单 | +| `mcp_servers` | 外部 MCP 服务:`url`、`headers`、`mode`(advertise / silent / disable)、`timeout_ms`、工具名单 | | `public_link` | 公网临时链接前缀与有效期 | | `agent` | 温度、最大工具迭代、重试、语言、压缩阈值、空闲收口、历史裁剪 | | `memory` | 日记注入条数、保留期、空闲收口阈值 | diff --git a/app/AGENTS.md b/app/AGENTS.md index f699c71..3c3efba 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -158,6 +158,9 @@ 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` 已废弃,出现即报配置错(不静默忽略)。 - `executeTool(baseCtx, name, args)`:先查 `HANDLERS` 表,未命中再交给 MCP 注册表。 `ctx = {sessionId, taskDir, run, cfg, db, vision}`;工具返回字符串,`read_file` 读图时返回 `{text, image_rel}`(由 engine 转成 `image_ref` 块)。 diff --git a/app/config.example.yml b/app/config.example.yml index a28d354..9b0909f 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -78,7 +78,9 @@ auth: # users 留空 = 不启用登 role: admin # admin=管理员(全部设置 + 用户管理);user 或缺省=普通用户(仅账户页) # model: qwen-tp/qwen3.8-flash # 选填:该用户新建会话时锁定的模型(内部键「平台名/模型id」) -# MCP 服务列表(仓库自带的 mcp/ 三个服务,或栈外服务):每项 {name?, url, headers?, enable?(默认 true), timeout_ms?, tools_allow?, tools_deny?}。 +# MCP 服务列表(仓库自带的 mcp/ 三个服务,或栈外服务):每项 {name?, url, headers?, mode?(默认 advertise), timeout_ms?, tools_allow?, tools_deny?}。 +# mode 三态:advertise=工具下发给模型;silent=只注册可调用(技能 mcp_tool / lab)不下发;disable=不连接、不发现。 +# 旧字段 enable 已废弃,写进配置会启动报错。 mcp_servers: [] public_link: diff --git a/app/server/config.js b/app/server/config.js index 7f44e15..5342ca3 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -121,7 +121,8 @@ const DEFAULTS = { }, // 登录认证:{users:[{user,password}], secret?, ttl_ms?};null / users 空 = 不启用。 auth: null, - // 外部 MCP 服务列表(无默认值):{name?, url, headers?, enable?(默认 true), timeout_ms?(默认 60s)}。 + // 外部 MCP 服务列表(无默认值):{name?, url, headers?, mode?(默认 advertise), timeout_ms?(默认 60s)}。 + // mode 三态:advertise=工具下发给模型;silent=只注册可调用(技能/lab)不下发;disable=不加载。 mcp_servers: [], // 公网临时链接:base_url 非空才启用 mint_public_link;容器配 VIRTUAL_HOST 时以它为准。 public_link: { base_url: '', ttl_ms: 1800000 }, @@ -340,7 +341,7 @@ function parseAndValidate(rawText, configPath) { } // MCP 服务规范化:url 必填;name 缺省取主机名首段;headers 为普通键值对象(如 Authorization); - // enable 缺省 true,显式 false 时启动不加载该服务的工具(见 mcp.init); + // mode 缺省 advertise,见下方三态校验(工具是否下发 / 是否加载,见 mcp.init); // timeout_ms 为该服务单次 tools/call 的最大等待,缺省 60s(长任务服务如视频生成可调大)。 if (!Array.isArray(cfg.mcp_servers)) cfg.mcp_servers = []; for (const s of cfg.mcp_servers) { @@ -348,8 +349,17 @@ function parseAndValidate(rawText, configPath) { if (!s.name) { try { s.name = String(new URL(s.url).hostname.split('.')[0]); } catch (_) { s.name = 'mcp'; } } - // 容错 YAML 里写成字符串 "false" / "off" 的情况,统一归一为布尔 - s.enable = !(s.enable === false || s.enable === 'false' || s.enable === 'off' || s.enable === 0); + // 旧字段 enable 已废弃且不静默忽略:未知键会被无声丢弃,那样「以为关了」的服务会照常连上、 + // 照常烧额度。宁可启动即报错,把迁移动作逼到明面上。 + if (s.enable !== undefined) { + throw new Error('mcp_servers 的 enable 已废弃,请改用 mode: advertise | silent | disable'); + } + // 三态:advertise(默认,工具下发给模型)/ silent(注册但不下发,配合技能 mcp_tool 使用)/ + // 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); 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 3e37c7c..1beec41 100644 --- a/app/server/mcp.js +++ b/app/server/mcp.js @@ -1,8 +1,9 @@ // 极简 MCP 客户端(Streamable HTTP:JSON-RPC over HTTP,无状态,响应可能是 SSE 帧包裹的 JSON)。 -// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, enable?, timeout_ms?, tools_allow?, tools_deny?}。 -// 启动时 init() 对每个服务调 tools/list 发现工具(enable: false 的服务跳过加载;配了 tools_allow/tools_deny +// MCP 服务在 config.yml 的 mcp_servers 中配置(可多个):{name?, url, headers?, mode?, timeout_ms?, tools_allow?, tools_deny?}。 +// 启动时 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(模型看不到)。 // 工具调用经 tools/call 转发给对应服务。 // 与内置工具严格分离:本模块不碰内置定义;MCP 工具默认沿用原始名, // 仅当与内置工具或其他 MCP 工具重名时加「服务名__」前缀。 @@ -141,11 +142,14 @@ async function loadServer(s) { let tools = all; if (Array.isArray(s.tools_allow)) tools = tools.filter(t => s.tools_allow.includes(t && t.name)); if (Array.isArray(s.tools_deny)) tools = tools.filter(t => !s.tools_deny.includes(t && t.name)); + let hidden = 0; for (const t of tools) { 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: { @@ -157,6 +161,7 @@ async function loadServer(s) { } 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 + ' 个不下发给模型,仅供技能调用)'; log.info('mcp', msg); // 配了名单却一个都没过滤中,十有八九是名单里的名字跟 tools/list 返回不一致; // 不 warn 的话排查时只能对着「发现 0 个工具」干瞪眼。 @@ -213,9 +218,9 @@ async function init(cfg) { const servers = (cfg && cfg.mcp_servers) || []; const failed = []; for (const s of servers) { - // enable: false 时启动不加载该服务(不建工具表;配置保留,改回 true 重启后恢复) - if (s.enable === false) { - log.info('mcp', s.name + ': enable=false,跳过工具加载'); + // mode: disable 时启动不加载该服务(不建工具表;配置保留,改回 advertise 重启后恢复) + if (s.mode === 'disable') { + log.info('mcp', s.name + ': mode=disable,跳过工具加载'); continue; } if (!(await loadServer(s))) failed.push(s); diff --git a/app/server/public/css/style.css b/app/server/public/css/style.css index bf6bcbf..11e65df 100644 --- a/app/server/public/css/style.css +++ b/app/server/public/css/style.css @@ -1098,6 +1098,8 @@ label.icon-btn { cursor: pointer; } .modal .mpe-num { display: flex; align-items: center; gap: 5px; flex: none; font-size: 12.5px; color: var(--gray); } .modal .mpe-num input { width: 92px; padding: 5px 8px; margin: 0; font-size: 13px; border: 1px solid #dde1ea; border-radius: 8px; background: #fff; color: var(--ink); } .modal .mpe-num input:focus { border-color: var(--active); } +/* MCP 的 mode 三态下拉:独立成行(弹窗内容宽仅 ~320px,与超时框同排会撑破),内层 select 用 .modal select 的全宽样式 */ +.modal .mpe-field { display: block; margin-top: 14px; font-size: 12.5px; color: var(--gray); } .modal .mpe-ck { display: flex; align-items: center; gap: 5px; font-size: 12.5px; color: var(--gray); } .modal .mpe-ck input { width: 15px; height: 15px; padding: 0; margin: 0; border: none; background: none; accent-color: var(--active); cursor: pointer; } .modal .mpe-del { flex: none; border: none; background: none; margin: 0; padding: 2px 7px; cursor: pointer; color: var(--gray-light); font-size: 18px; line-height: 1.2; } diff --git a/app/server/public/index.html b/app/server/public/index.html index 938d3f0..73427e0 100644 --- a/app/server/public/index.html +++ b/app/server/public/index.html @@ -335,8 +335,14 @@