1. 为什么我会动手做 tsm-hub 这个统一网关先交代一下背景。我平时的工作流里LLM、Tools、MCP、Skills 这四样东西一直是分开打理的模型要接 OpenAI、Claude、本地 Ollama 好几家工具脚本散落在不同项目里有的走 HTTP 接口有的只能命令行调用MCP Server 又是另一套注册逻辑Skills 则是跟着特定客户端走的换个前端就废一半。每次搭一个新项目光是环境接线就花掉小半天。真正让我下定决心写 tsm-hub 的契机是我同时跑三个智能体任务时翻车了。Agent A 要用网页抓取工具Agent B 要调本地数据库 MCPAgent C 要挂一套文档解析 Skills三个任务各拉各的配置互相之间完全不通气。结果日志混乱、工具重复调用、模型上下文被各种冗长的工具定义挤爆。那一刻我意识到缺的不是更多工具而是一个能把它们统一收口的东西。tsm-hub 这个名字简短说就是 Tools, Skills, Models 的 Hub。它不是一个具体的模型也不是又一个 MCP Server而是一个位于应用层和各类资源之间的网关层用一套统一接口把 LLM、Tools、MCP、Skills 全部暴露给上层调用方。上层不需要关心目标资源是跑在远程还是本地、走什么协议、用什么鉴权方式只要按网关定的规范来就行。这篇文章适合谁看如果你也在做 Agent 开发、在维护多个 LLM 应用、或者正在被“工具定义写不进上下文”“Skills 换个客户端就没法用”“MCP 服务一多就乱”这些问题折磨那这篇内容应该对你有用。我会把设计思路、核心模块、配置样例和踩坑记录都摊开讲你说不定能直接拿去做参考实现。2. 核心概念拆解LLM、Tools、MCP、Skills 到底各司其职2.1 四类资源的定位和边界在动手设计统一网关之前先把四类资源的分工理清楚。LLM 好理解就是文本生成模型本体负责推理和产出内容。但光有模型不行模型不知道外部世界发生了什么所以需要 Tools 让模型获得“行动能力”比如查天气、发请求、执行代码。MCP 是另一层抽象它把工具能力协议化。原来你接一个工具要自己写 client接十个工具要维护十套调用规范MCP 的思路是统一成一套协议服务方只要实现 MCP Server调用方用标准 client 就能连接。这里面有个容易混淆的点MCP 和普通 Tools 不是替代关系而是组织关系。MCP Server 可以被包装成 Tool 暴露给模型Tool 内部也可以选择用 MCP 协议和后端通信。Skills 则是更上层的封装。一个 Skill 通常包含一组特定指令、提示词模板、工具引用和调用流程本质上是一个“可复用的能力包”。比如“前端代码审查 Skill”可能包含审查规则清单、需要调用的静态分析工具、输出报告的格式模板。Skills 的价值在于把零散的模型能力和工具调用编排成固定套路。打个比方LLM 是员工Tools 是员工能用的设备MCP 是设备的标准化接口Skills 是员工手里的标准作业流程手册。没有手册员工有设备也不知道组合使用没有标准化接口换一台设备就要重新培训。2.2 统一网关在这中间扮演什么角色网关夹在中间做的就是“统一收纳、统一转发、统一策略”的事情。统一收纳是指所有资源都在网关里注册一个资源一个条目统一转发是上层请求进来后网关根据路由规则分发到对应资源统一策略体现在模型选择、工具优先级、超时重试、权限校验这些横切逻辑上。我见过不少项目不做网关直接在代码里用 if-else 调各种客户端。短期内能用一旦资源数量超过五个或者需要给多个前端共享能力代码就开始失控——每个前端都要重新实现一遍模型切换逻辑每个工具都要单独做鉴权和错误处理。网关把这些共性逻辑下沉到一层上层代码反而变得更薄。3. tsm-hub 的整体架构设计与选型思路3.1 设计目标我不是在做另一个框架动手前我给自己定了几条原则第一不重造协议能站在 MCP 肩膀上就绝不自己发明一套第二可插拔资源接入不能写死第三轻量不想引入一个需要专门运维的重型中间件第四对上层暴露的接口尽量简单哪怕团队里刚入职的新人也能快速上手。基于这四条我最终选择了“核心网关 适配器插槽”的架构。网关本体只负责路由、鉴权、装配、日志几件核心事对每类资源定义一个统一抽象再通过适配器把不同实现转换成抽象定义。好处是接一个新型资源通常只需要写一个适配器不动网关核心代码。3.2 接入层一套规范统一三类资源注册统一网关首先要解决的就是“怎么描述一个资源”。我给 LLM、Tools、MCP、Skills 设计了一套统一的资源描述结构。资源描述里必须有资源类型model、tool、mcp、skill 四种之一。资源 ID全局唯一用于路由引用。连接信息比如 base_url、model_name、command、url。认证信息引用密钥库里的条目不直接存明文。负载程度这个资源适合处理什么类型任务、并发上限多少。举个例子一个 MCP Server 的描述是这样resources: - type: mcp id: local_db_mcp transport: stdio command: npx args: - mcp-server-db auth_ref: db_service_token load: medium一个本地工具描述resources: - type: tool id: file_scanner exec: path/to/scan_script.py input_schema: file output_schema: json timeout_ms: 5000一个模型描述resources: - type: model id: claude_main provider: anthropic model: claude-sonnet-4-5 max_tokens: 8192 fallback: local_ollama_8b这层设计的核心价值是让上层调用只认识资源 ID不关心底层细节。上层说“帮我调用local_db_mcp里的query工具”网关去查注册表、建立连接、做鉴权、执行调用、返回格式化结果。3.3 路由层context 与能力匹配资源都注册好之后下一步是决定某次请求应该走哪条路径。tsm-hub 用的是“按需路由 上下文标签”的策略而不用复杂的语义路由。上层在请求里带 context 标签比如task_typeqa、domainfrontend、required_skillscode_review网关根据标签过滤资源和能力项。这个决策背后有一个重要原因语义路由听上去智能基于 embedding 给请求选资源实际在工程里非常容易出偏差——模型能力边界频繁变化工具是否可用随时变化而标签路由是确定性的完全可控。先保证确定性和可排查性再考虑智能。3.4 上下文装配动态注入技能与工具定义模型调用之前需要把工具定义和技能说明装配进上下文。这一步做不好多资源接入的收益会被上下文爆炸抵消掉。网关的上下文装配策略如下静态部分系统提示词模板、常驻技能说明、全局指令。动态部分按请求标签匹配到的工具定义和 MCP 工具集。会话部分多轮对话历史中累积的中间结果。动态装配时要注意 token 预算控制。工具定义谁写谁知道动辄一两千 token 一个同时塞十个工具就已经很占上下文了。网关里我设置了一个硬顶默认最多装配 6 个工具定义超出部分由模型先给出工具选择倾向再由网关做第二轮装配。这算是工程向的取舍很多方案都会加一层“候选工具排序”但我觉得在网关层做粗过滤就够了真正精细的筛选交给 Agent 逻辑。技能也一样不是全量注入。只有请求标签命中的 Skills 才会被装载到上下文里没命中就不浪费 token。4. 实操从配置文件到跑通第一个请求4.1 快速部署和启动配置先交代一下运行环境。我用 Python 实现依赖不多核心就 FastAPI 加一个配置解析库。安装好依赖后第一步是写配置文件。配置分三段网关本身的监听地址、密钥库配置、资源注册表。一个最小可用的配置文件如下gateway: host: 127.0.0.1 port: 8760 max_concurrent_tasks: 50 secrets: storage: env env_prefix: TSM_KV_ resources: - type: model id: local_ollama provider: openai_compatible base_url: http://localhost:11434/v1 model: llama3.1:8b api_key_env: OLLAMA_KEY - type: tool id: local_notes_parser exec: python path/notes_parser.py input_schema: text output_schema: json timeout_ms: 10000 - type: mcp id: web_search_mcp transport: sse url: http://127.0.0.1:8910/sse auth_ref: web_search_token启动网关后调用入口统一是/v1/exec。一个典型请求体长这样{ resource_id: local_ollama, action: generate, messages: [ {role: user, content: 用 web_search 搜一下最近的 AI Agent 框架动向} ], context_tags: [research, agent_framework], enable_skills: [web_search_assist], max_tokens: 2048 }网关收到之后先解析 context_tags从技能库装载web_search_assist再把web_search_mcp下的搜索工具定义注入上下文然后调用模型等模型发出工具调用请求时网关代理到 MCP Server 执行并返回结果。这个流程里对上层应用来说它只感知到了“我提交了一个请求得到一个回答”并不知道中间发生了几次工具调用、走了哪个 MCP、技能是怎么装配的。这就是网关注入式的价值。4.2 多模型多工具的负载分配逻辑多资源接入之后不能每次都在第一条路径上吊死。tsm-hub 做了一套简单但实用的负载分配逻辑按资源描述里的负载等级排序优先选 load 低的资源。当同一资源被连续失败三次时自动熔断降级到 fallback 资源。支持按请求来源分组限流避免某个业务线把系统打爆。这套逻辑不复杂但是在实测中非常稳。有一次本地 Ollama 服务假死网关连续三次请求失败后自动切到备用模型上层完全无感。4.3 实际接入一个自定义 Skill 的完整演示Skill 是实践中最能体现网关上价值的部分。我演示一下我最近加的一个“前端代码审查 Skill”。第一步建一个 skill 描述文件skill: id: frontend_code_review description: 审查前端代码的潜在问题输出结构化评审报告 trigger_tags: - frontend - review tools: - file_scanner - eslint_mcp prompt_template: | 你是资深前端评审专家。请使用 file_scanner 读取项目文件使用 eslint_mcp 检查代码规范。 输出格式要求 1. 问题列表按严重程度排序 2. 每条问题附修改建议 3. 最后给出整体质量评分满分 100 token_budget: 4000 fallback_action: generate_issues_list_only第二步把 Skill 文件放到技能库目录然后在网关配置里开启扫描路径启动时自动加载。上层请求只要带review或frontend标签这个 Skill 就会被自动装配。第三步实际请求体验。我拿了一个中等规模的前端仓库做测试网关读文件 调用 eslint MCP 模型分析整个流程跑完只花了一次用户请求闭环。对比之前手动拼接这些步骤操作成本下降得很明显。Skill 机制带来的另一个收益是团队复用。一个负责写 Skill 的人把能力封装好其他人不需要知道内部实现细节只要在请求里打标签就能用上整套能力。这对团队协作的改善是肉眼可见的。5. 遇到过的坑和处理方案5.1 工具描述占满上下文问题刚开始直接把所有注册工具全部注入上下文结果一次请求打完发现 token 快爆了。排查后统计光是所有工具的 JSON Schema 加起来就超过 12000 token模型还没开始干活上下文先烧掉三分之一。解决思路是上面说过的“双层装配”第一层只装配请求标签命中的候选工具第二层根据模型初步选择再精确装配。实测 token 消耗降低了约 70%响应速度也有提升。这个问题的通用教训是工具越多越要克制上下文是稀缺资源工具装配是典型的空间换时间矛盾。5.2 不同 MCP Server 稳定性和协议差异MCP 虽然规范统一但实际各 Server 实现的质量参差不齐。有的走 stdio有的走 SSE有的走 WebSocket有的连接一次能用很久有的跑几轮就自动断。我第一次接入一个 WebSocket 传输的 MCP Server 时被“连接中断”折磨到怀疑人生。排查半天发现是 Server 端的空闲超时设置太短只要 30 秒没有消息就自动断开。解决办法是网关层做连接保活和自动重连同时对 MCP 调用统一包裹超时控制和错误重试。最终的配置是重试两次超时时间按工具类型区分查询类 10 秒执行类 60 秒。5.3 Skills 作用域和权限边界早期我犯了一个错Skill 一旦被装载就能调用所有它能引用的工具没有任何权限区分。结果一个只读类的审查 Skill 理论上也能触发写操作。这是很危险的设计。现在我在 Skill 描述里增加了permissions字段声明它允许执行的操作类型和禁止的操作类型。网关会在每次工具调用前做权限校验不匹配直接拒绝。这套机制看起来简单但对多租户或者共享网关的场景必不可少。5.4 常见问题速查表现象可能原因处理动作请求超时MCP Server 空闲断开未重试检查保活配置开启自动重连模型报工具调用失败上下文未装配工具定义检查 context_tags 是否命中资源标签Skill 未生效触发标签不匹配核对请求标签和 Skill 的 trigger_tags工具返回数据格式错乱输出解析器不匹配按统一 JSON Schema 规范工具输出配置改完不生效缓存未刷新调用网关 reload API 或重启进程6. 一些现在用的顺手技巧调试网关时我推荐开一个“干跑模式”。这个模式下网关会把所有请求、装配结果、工具选择、token 消耗打印成跟踪日志但不真正调用模型。用来排查“为什么某个工具没被选中”“为什么 Skill 没注入上下文”这类问题非常高效成本还低。另一个经验是尽量把密钥管理和网关解耦。直接在配置文件里写明文密钥看着方便但项目一旦共享给团队就要出事。我现在全部走环境变量注入配置文件里只放变量名引用这样即使配置库泄露也不会直接暴露密钥。还有一点日志里一定要记录每次请求的“资源实际调用链”。比如一次用户请求实际走了 model A、调用了 tool B、mcp C 两次。这个信息对事后排查、成本归因以及优化路由策略都特别有用。我见过太多默默吞掉工具调用细节的系统一出问题只能对着黑盒发愁。就冲这个调用链可视化的爱我在网关里专门存了一份结构化调用记录字段包括资源 ID、调用时间、耗时、请求参数摘要、返回码。底层逻辑就是一次请求对应一棵调用树上层监听接口随时能查。后来我还给这套日志做了一页薄薄的仪表盘视感从聚合视角能看到哪些工具调用频次高、哪些长期超时、哪些模型资源被闲置。调优路由策略的时候有数据支撑和瞎猜感觉完全是两种效率。7. 关于未来扩展的一点思考网关搭好之后最直接的扩展方向是把 Skill 做成可远程订阅的包。现在 Skills 放在本地目录团队内部还能用但跨团队分发还是要拷贝。下一步我打算加一个简单的仓库协议让 Skill 能按版本从远端拉取并且自动做兼容性检查降低分发成本。另一个方向是强化多模型调度。现在熔断和降级已经做了但还没做到基于任务类型的智能调度——比如代码生成任务优先用 Code 能力强的模型而通用问答走轻量模型。这需要预先对任务类型做分类这个分类器本身又可以用 LLM 来实现形成哪类任务走哪条链路的闭环。还有个小方向我觉得很有实用价值把工具调用的中间结果做缓存归一。很多 Agent 任务里同一个查询可能在多轮对话中被重复调用多次缓存下来能省不少时间和 token 消耗。这算是低成本高收益的优化点。
