用 Rust 打造 AI Skill 管理神器：MCP Server + Web 管理 + 桌面 GUI 三合一架构实践

本文分享自研 Rust 全栈 AI Skill 管理系统 AISkillBox，单进程内置 MCP 协议服务、Salvo Web 后台、egui 桌面客户端，一站式解决 Cursor/Zed/WorkBuddy 多编辑器技能分散、配置繁琐问题。
适配人群：Rust 开发者、AI 编码工具重度使用者、MCP 协议实践学习者。

一、项目背景

日常使用 Cursor、Zed 等 AI 编码工具时，大量 Skill 技能文件分散在不同编辑器目录，存在三大痛点：

1. 技能无法互通：每个编辑器单独维护一套 Skill，复制配置文件操作繁琐；
2. 缺少统一管控：无法批量启用/禁用、备份、归档技能；
3. AI 无法自主管理：必须人工修改文件，不能通过对话指令完成技能增删。

基于以上痛点，使用 Rust 开发三合一架构工具 AISkillBox，单 exe 开箱即用，同时提供三种交互入口：

• MCP Server：AI 编辑器通过标准 MCP 协议直接调用、管理全部技能；
• Salvo Web 管理后台：浏览器远程可视化批量运维，支持高危权限操作；
• egui 原生桌面 GUI：本地轻量化快捷操作，适配 Windows 系统托盘、开机自启。

二、整体架构

架构核心规则

1. 三组件同进程，通过 Arc<RwLock<ToolManager>> 共享状态，数据天然一致；
2. MCP、Web 分别作为独立 Tokio 异步任务并行运行；
3. 桌面 GUI 不直接操作底层核心调度，统一 HTTP 调用 Web 接口，实现解耦。

三、全栈技术栈明细

分层领域	依赖库/技术	核心用途
基础语言	Rust 2024 Edition	系统级性能、内存安全无GC、跨平台编译
异步运行时	Tokio(full feature)	统一异步调度，同时支撑MCP、Web双服务并发
MCP协议层	rmcp 2.0.0	官方标准MCP SDK，支持Streamable HTTP、stdio双传输模式
MCP HTTP传输	Axum 0.8	封装MCP /mcp 端点HTTP服务
Web后台框架	Salvo 0.95.0	RESTful API 服务 + Vue前端静态资源托管
桌面GUI	egui/eframe 0.33.3	即时模式原生桌面窗口，跨Windows/macOS/Linux
系统托盘	tray-icon + muda	Windows托盘后台常驻、右键快捷菜单
数据存储	rusqlite(SQLite WAL)	存储Skill元数据、启用状态、删除标记
配置解析	Figment	TOML配置文件 + 环境变量分层配置
Skill文档解析	yaml-rust2	解析SKILL.md头部YAML元数据
编译打包	cargo-dist + winres	单文件exe打包，内置Windows程序图标，体积优化至10MB

四、MCP Server 模块设计

4.1 协议双传输模式

基于 rmcp 实现标准 MCP ServerHandler，同时支持两种接入方式：

1. HTTP 默认模式：端口10881，StreamableHttpService 暴露 /mcp 端点，适配Zed、Cursor等编辑器；
2. stdio 调试模式：启动时携带 --stdio 参数，用于进程直连调试。

核心Handler结构体：

pub struct EcMcpHandler {
    tool_manager: ToolManager,
    reload_flag: Arc<AtomicBool>, // 无锁热重载标记
}

4.2 Skill 自动注册机制

程序启动自动扫描根目录 skills/，读取每个技能文件夹内 SKILL.md 的YAML头部元数据，动态注册为MCP可调用工具：

---
name: my-skill
description: 技能功能描述
tags: [代码处理,图像批量]
---
# 此处为技能完整指令文本

AI调用工具时，服务会直接返回完整SKILL.md内容作为指令上下文。

4.3 内置管理工具集（9个原生工具）

除自定义Skill外，MCP内置原生管理工具，AI可通过对话完成全生命周期管理：

工具名称	实现功能
list_skills	读取全部技能元数据，返回列表
search_skills	关键词/标签模糊检索技能
enable_skill / disable_skill	切换技能启用状态
delete_skill	软删除，移入回收站目录，数据库标记deleted=1
restore_skill	将回收站技能恢复至正常目录
list_trash	读取回收站全部归档技能
refresh_skills	重载本地skills目录，刷新工具注册表
migrate_skills	跨编辑器技能迁移指引

4.4 无锁热重载实现

使用 AtomicBool 原子标记实现无锁重载，避免读写阻塞：

// Web后台触发刷新时，设置重载标记
reload_flag.store(true, Ordering::SeqCst);

// MCP每次调用工具后自动检查标记
if self.reload_flag.swap(false, Ordering::SeqCst) {
    self.tool_manager.reload().await;
}

五、Salvo Web 管理后台

Web服务监听10882端口，分为REST管理API + Vue3前端静态资源两大模块。

5.1 核心API路由设计

# 技能管理接口
GET    /api/admin/skills          获取全部技能列表
GET    /api/admin/skills/search    关键词/标签检索
DELETE /api/admin/skills/:name      软删除技能
POST   /api/admin/skills/:name/restore 恢复回收站技能
POST   /api/admin/skills/:name/enable    启用技能
POST   /api/admin/skills/:name/disable   禁用技能

# 回收站接口
GET    /api/admin/trash             获取回收站归档技能

# 服务控制接口
POST   /api/admin/service/*         MCP服务启停、重启控制

5.2 共享状态依赖注入

使用Salvo内置 affix_state 中间件，将全局数据库连接、ToolManager注入所有接口路由，全局单例共享：

Router::new()
    // 注入全局数据库实例
    .push(Router::with_path("api/admin/skills").hoop(salvo::affix_state::inject(db)))
    // 托管Vue前端静态资源
    .push(Router::with_path("/<**path>").serve_static(static_dir))

5.3 静态资源分层托管

路由拆分两类静态资源，隔离业务页面与说明文档：

1. /web-admin/{*path}：托管Vue3编译后的管理后台前端资源；
2. /{*path}：项目公共说明、使用文档静态页面。

六、egui 桌面GUI客户端

6.1 选型依据

选用egui/eframe作为桌面框架，核心优势：

1. 纯Rust实现，无需Electron，打包体积小、内存占用低；
2. 即时模式渲染，界面迭代开发效率高；
3. 原生支持深色/浅色主题实时切换，适配Windows系统显示设置；
4. 配套托盘库实现后台常驻，最小化到系统托盘。

6.2 GUI 五大功能模块

1. MCP服务控制面板：一键启动/停止/重启服务、刷新运行状态，展示双端口配置；
2. 系统全局设置：开机自启注册表配置、托盘常驻开关、深色/浅色夜间模式切换，附带「网页管理」快捷跳转按钮；
3. Skill列表管理：分页展示全部技能，每行配备启用/删除按钮，直观操作无需右键菜单；
4. 批量导入功能：支持拖拽技能文件夹/文件、文件选择弹窗两种导入方式；
5. 系统托盘拓展：窗口最小化自动隐藏至托盘，托盘右键菜单快速打开窗口、停止服务、退出程序。
   

6.3 GUI与底层解耦设计

桌面客户端不直接读写数据库、操作ToolManager，全部管理操作通过HTTP请求调用本地Web后台接口，彻底解耦UI与核心业务逻辑：

// api_client.rs GUI专用请求封装
pub fn list_skills() -> Result<Vec<SkillInfo>> {
    let url = format!("http://{}/api/admin/skills", base_url());
    // 发起GET请求，解析JSON返回技能列表
}

七、核心底层设计模式

7.1 Arc 全局共享状态

核心调度工具 ToolManager 使用 Arc<RwLock<>> 包装，支持MCP、Web、GUI多任务安全并发读写，无数据竞争：

pub struct ToolManager {
    tools: Arc<RwLock<Vec<ToolConfig>>>,
    executor: Arc<RwLock<ToolExecutor>>,
    skills: Arc<RwLock<Vec<SkillInfo>>>,
}

7.2 策略模式：工具执行分发

所有内置管理工具、自定义Skill统一封装为异步闭包，存入HashMap按工具名分发调用，拓展新工具无需修改匹配分支：

// 工具执行器类型定义
type ToolHandler = Arc<dyn Fn(Value) -> Pin<Box<dyn Future<Output = ToolResult> + Send>>>;

pub struct ToolExecutor {
    handlers: HashMap<String, ToolHandler>,
}

7.3 两阶段软删除+回收站机制

严格区分安全操作与高危操作，避免误删丢失技能资产：

1. 软删除（GUI/Web均可操作）：技能文件夹移动至 skill-trash/，文件夹名称附加时间戳防止重名冲突，SQLite数据库标记 deleted=1；
2. 永久删除（仅Web后台开放权限）：彻底删除回收站文件夹、清除数据库对应记录，GUI客户端不暴露该高危操作入口，保障本地操作安全。

7.4 SkillStore 存储Trait抽象

数据库操作通过Trait抽象定义接口，底层实现基于SQLite，后续可无缝替换其他存储引擎，代码低耦合易拓展：

pub trait SkillStore {
    fn upsert(&self, skill: &SkillInfo) -> Result<()>;
    fn list_all(&self) -> Result<Vec<SkillInfo>>;
    fn search(&self, query: &str, tags: Option<&str>) -> Result<Vec<SkillInfo>>;
    fn set_enabled(&self, name: &str, enabled: bool) -> Result<()>;
    fn soft_delete(&self, name: &str) -> Result<()>;
    fn restore(&self, name: &str) -> Result<()>;
}

八、Release 编译体积优化配置

Cargo.toml 发布配置，剥离调试符号、链接时全局优化，最终单exe体积仅约10MB：

[profile.release]
strip = true    # 移除调试符号，大幅缩减体积
lto = true      # 链接时全局优化，提升运行性能
opt-level = "z" # 优先优化二进制文件大小

配套 winres 编译嵌入Windows程序图标，编译产物为独立exe，无外部依赖，开箱即用。

九、 架构落地价值

1. 职责彻底解耦：MCP仅承担AI通信转发，复杂技能管理、批量运维逻辑全部剥离至Web服务，MCP轻量无冗余，AI调用低延迟；
2. 分层安全权限隔离：本地GUI仅开放安全软删除、技能开关；永久删除等高风险操作仅在带权限校验的Web后台开放，防止本地误操作丢失技能资产；
3. 多场景适配：桌面GUI满足本地快速启停、日常技能管理；Web后台支持浏览器远程批量运维；MCP协议打通所有AI编辑器，实现对话式管理技能；
4. Rust全栈高性能：整套系统核心逻辑纯Rust实现，内存安全无泄漏，异步并发架构资源占用极低，可7×24小时后台稳定运行。

拓展阅读

1. rmcp MCP官方协议文档
2. Salvo Rust Web框架官方指南
3. egui/eframe 桌面开发文档