MCP 与 Skills 集成及 Schema 校验强化架构设计
1. 背景与目标
在将 Yanshi 推进为生产级后端网关的服务化进程中,底层的 yanshi-skills 模块需要能够处理更加复杂和健壮的外部工具集成。目前的系统:
- 只能执行受限的本地内置工具(
file,shell,http,script)。 script工具执行缺乏大模型输入参数的 Schema 强校验,极易因为模型幻觉导致脚本崩溃。
目标:
通过引入 yanshi-mcp 客户端,使技能清单(skill.toml 和 SKILL.md)支持声明式挂载外部 MCP Server;同时为本地脚本注入 parameters Schema,实现网关侧的早期参数拦截和校验。
2. 数据结构设计 (Manifest Schema)
2.0 Skill 格式优先级
SKILL.md 是推荐的标准入口,用 YAML frontmatter 表达结构化元数据,用 Markdown 表达技能说明。skill.toml 保留为兼容和更强结构化的 runtime manifest。
同一目录同时存在 SKILL.md 和 skill.toml 时,当前加载规则保持为 skill.toml 优先,以兼容已有 Yanshi 技能并允许部署侧覆盖 portable SKILL.md。
2.1 MCP Server 配置
在 yanshi-skills/src/manifest.rs 中增加:
#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct McpServerConfig {
pub name: String,
pub command: String,
#[serde(default)]
pub args: Vec<String>,
#[serde(default)]
pub env: HashMap<String, String>,
}
}
并在 SkillManifest 顶层增加 #[serde(default)] pub mcp_servers: Vec<McpServerConfig>。
2.2 SKILL.md 支持
对于标准的 SKILL.md,优先使用结构化 frontmatter 字段:
mcp_servers:
- name: github
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
timeout_secs: 30
旧版 metadata.mcp_servers = "[{\"name\": \"github\", \"command\": \"npx\", ...}]" JSON 字符串形式仍保留为兼容 fallback。
2.3 工具参数校验 (Tool Schema)
修改 manifest.rs 中的 ToolConfig,为其增加:
#![allow(unused)]
fn main() {
#[serde(default)]
pub parameters: Option<serde_json::Value>, // 期望是一个 JSON Schema
}
3. Builder 实例化流程 (SkillBuilder)
在 yanshi-skills/src/builder.rs 的 build() 函数中:
- 依然初始化原有的
FileTool,ShellTool,HttpTool,ScriptTool。 - 遍历清单中的
mcp_servers数组。 - 对每个 Server,使用
StdioTransport拉起其子进程,并实例化McpClient。 - 调用客户端的
list_tools()获取远程工具列表。 - 通过
ToolRegistry注册远程工具的适配器包装类。
(注:鉴于异步和所有权生命周期问题,可能需要将 McpClient 包装为 Arc 或在 Agent 执行上下文中保持。为简化第一版实现,我们在此仅添加解析模型并在本地 Tool 增加 Schema 校验)
4. 脚本工具改造 (ScriptTool)
在 yanshi-tools/src/builtin/script.rs 中:
ScriptTool::new将接收一个可选的parameters_schema(即serde_json::Value)。- 引入
jsonschema库(如果不需要额外依赖,可先使用serde_json检查必需字段)。 - 在
Tool::execute执行之前:#![allow(unused)] fn main() { if let Some(schema) = &self.parameters_schema { // Validate JSON args against schema // If failed -> Return ToolOutput with validation error message immediately } }
5. 错误处理策略 (No Unwrap Policy)
- 在解析、验证阶段遇到错误应返回
SkillError或ToolError。 - 不使用
unwrap或expect,保证系统遇到配置异常时能平滑失败,不会产生 Panic。