做 AI Agent 的工程化做了快一年我最直观的感受是LLM、Tools、MCP、Skills 这四个词单独拎出来每一个都不难理解但当它们同时出现在一个真实项目里的时候事情就开始失控了。模型要接好几个厂商的接口工具是散落在代码里的几十个函数MCP server 今天加一个明天挂一个Skills 更是从各个 GitHub 仓库里捡回来的压缩包。每个东西都有自己的接入方式、鉴权方式和版本节奏最后所有逻辑全堆在 Agent 主进程里改一处就要全家桶回归。所以我特别能理解 tsm-hub 这个项目想干什么——把 LLM、Tools、MCP、Skills 收进一个统一网关让上层应用只关心我要什么能力不关心能力到底在哪里、怎么调。这篇文章我就从架构设计、模块拆解、落地配置、踩坑记录四个方面把这类统一网关的完整方案盘一遍。文章面向正在做 Agent 平台、内部 AI 中台或者单纯想把个人开发环境规整干净的朋友如果你现在还分不清 MCP 和 Skill 的差异我会在正文里把它讲透。1. 为什么需要 tsm-hubAI 应用开发正在被碎片化拖垮1.1 三个真实的现场问题先说说我在多个项目里反复遇到的三个问题它们几乎是所有 Agent 工程化团队的共同痛点。第一个是模型渠道割裂。同一个业务场景里可能要同时用 OpenAI 的聊天模型、某家的 Embedding 模型、一个开源本地模型的推理服务还要给不同 client 准备 fallback 链路。这些模型的请求格式、鉴权方式、限流策略各不相同有些人为了省事直接在代码里写死厂商 SDK结果换一个模型供应商就要改一遍核心调用代码。第二个是工具定义散乱。支持 function calling 的框架越来越多但每个工具都要单独维护一份 JSON Schema工具之间的共享依赖、权限边界、调用频控、审计日志全都要自己设计。一开始只有三五个工具还好工具超过二十个以后光是保证每个工具的 description 和参数说明准确、不会被模型误导就已经是一件很费精力的事情了。第三个是 MCP 生态快速膨胀。MCP server 的数量这两年的增长幅度很大但它们之间的传输方式、能力声明方式、启动方式差异实在太多。有的是 stdio 子进程有的是 streamable HTTP有的是 WebSocket。每个 server 的初始化握手、健康检查、崩溃重连、版本升级都变成了 Agent 框架本身的负担。我真见过有人在生产环境里用一个脚本去管理十几个 MCP server脚本里全是 sleep 和 grep 日志的 hack。Skills 的问题更隐蔽。社区里流行的 Skill 本质上是一个提示词模板 若干脚本 静态资源的目录没有统一安装机制没有依赖管理也没有版本声明。今天从仓库 A 复制一个 skill 进来明天从仓库 B 复制另一个两个 skill 里可能引用了同一个 Python 包的不同版本过两周就忘了当初装过什么。时间一长skill 目录就变成了无人敢动的沼泽。1.2 网关模式的本质要解决上面这些问题直觉上会想到把东西全塞到一个进程里统一处理。但真这么做会发现Agent 进程会变得越来越臃肿而且换一个语言栈就得重新实现一遍。tsm-hub 的做法是典型的网关模式用一个独立服务在能力提供方和调用方之间做一层横向打通。严格来说tsm-hub 做的事情是把四类资源抽象成四种可管理对象。LLM 被抽象成可路由的模型资源Tools 被抽象成带标准函数签名的可注册能力MCP Server 被抽象成外部工具服务的连接代理Skills 被抽象成可组合的技能包。上层 Agent 不再直接面对各家的 SDK 和协议而是面对一套统一 API、一份配置文件和一套鉴权体系。这样做最大的变化是控制面和数据面分离了。模型接入、工具注册、MCP 连接、Skill 版本管理这些属于控制面操作请求转发、上下文注入、工具调用、结果返回这些属于数据面操作。两件事分开以后加一个新模型或者挂一个新 MCP server就不再需要动 Agent 核心代码。1.3 一套配置搞定所有能力统一网关带来的直接收益是配置化的能力管理。比如我需要给我的 agent 增加一个浏览器自动化能力传统做法是在代码里集成 Playwright再手写浏览器控制函数还要处理浏览器实例的生命周期。而在 tsm-hub 这种网关里只需要注册一个 Playwright MCP server然后在 skills 配置里允许某个技能使用它剩下的工作就是写一条配置。我在自己环境里落地这类方案时最明显的感觉就是加法变得安全了。之前加一个工具要担心会不会影响已有工具的 function calling 表现现在每个工具的 Schema、可见性和调用通道都是独立管理的新的能力进来默认不开放给任何 agent需要显式授权才会被上层看到。这种默认收敛的设计帮我挡掉了很多潜在故障。2. 整体架构拆解网关模式背后的设计逻辑2.1 TSM 的含义控制面与数据面的分离项目名里的 TSM我理解为 Tool-Skill-Model 的缩写也有人解释为 Tools、Skills、MCP 的统一管理。无论哪种理解核心都是把能力组织这件事从应用层抽离出来。整个架构最关键的是控制面和数据面的分离设计。控制面负责配置、注册、鉴权、版本管理数据面负责实际的调用转发。我在设计这类系统时习惯把配置存储在独立的配置中心或者一个 YAML 文件里运行时只保存一份已加载的内存态。这样改配置不需要重启 Agent只需要触发一次 reload。数据面的转发链路是请求进入网关 - 鉴权与路由 - 能力调度 - 结果聚合 - 返回。这里有个容易被忽略的细节LLM 调用往往不是一次就结束的Agent 会多次在模型和工具之间往返。所以网关的数据面必须支持会话级别的上下文保持不能简单地把每次请求当成独立的 HTTP 调用。2.2 统一抽象层四种资源如何被归一化为了让上层 Agent 能够用一致的方式处理四种资源需要定义一套统一的资源描述规范。我给一个具体例子这套规范我在实际项目里验证过可以覆盖大多数场景每种资源都拥有全局唯一的 ID 和版本号比如model:gpt-4o-mini:20250101或者skill:web-research:v3。每个资源都有一个元信息描述包括名称、用途、依赖关系、权限标签。Tool 和 MCP Server 都向外暴露一组 OpenAI function calling 风格的 JSON SchemaSkill 编译后产生提示词片段和可见工具白名单Model 则标记自己的能力位比如是否支持聊天、是否支持 Embedding、是否支持视觉。有了这层归一化上层 Agent 看到的是一棵能力树而不是一堆散落的接口。能力树的好处是可以做细粒度的授权。比如我可以让数据分析技能只能访问数据库查询工具和代码执行工具让网页研究技能只能访问搜索工具和浏览器 MCP。这比在 Agent 代码里写一堆 if else 判断要干净得多。2.3 三个关键设计取舍这类统一网关在技术选型上有几个绕不开的取舍。我逐个讲讲我的理解。第一个取舍是网关模式 vs SDK 模式。很多人倾向于发一个 Python SDK让各业务线直接调用。但 SDK 方案天然排斥非 Python 技术栈而且工具注册、权限策略这些逻辑散落在各个服务的依赖里很难统一升级。网关模式牺牲了一点性能额外一跳的延迟换来了跨语言复用和集中治理。我自己的经验是一次内部 HTTP 调用在局域网里的延迟只有 1-3 毫秒对于 AI 应用动辄数秒的模型推理时间来说完全可以忽略。第二个取舍是能力 ID 权限标签。为什么不能让 Agent 直接用工具名去调用因为在多团队场景里工具名会有歧义。一个叫search的工具在不同业务线下含义完全不同。所以我在设计里强制要求所有能力都有命名空间和版本号比如mcp__playwright__browser_goto。权限标签则用于后续做策略引擎比如只读工具和写操作工具的管控力度应该不同。第三个取舍是MCP 和原生 Tool 并存。MCP 生态丰富但网络链路更长stdio 子进程还会增加进程管理复杂度。本地高频调用如果走 MCP 反而慢而且不好调试。所以我把工具执行层设计成两种模式本地进程内函数模式和远程 MCP server 代理模式。两种模式对外暴露的都是同一套函数 SchemaAgent 不需要感受到差异。这个并存设计让系统的适用范围宽了很多。3. 核心模块深度解析与实操要点3.1 LLM 网关模型路由、fallback 与统一接入格式LLM 网关是整个 hub 里最基础的模块因为它承载的是所有 Agent 的对话和补全请求。我把它拆成三部分统一出口、模型抽象、路由策略。统一出口很好理解对外只暴露一个 OpenAI 兼容的/v1/chat/completions接口。这样上层任何支持 OpenAI SDK 的框架都能直接接入我的 Django 服务、FastAPI 服务、命令行工具都不用改代码。在网关内部再针对不同模型厂商的原始 API 做适配把请求格式转换成各家需要的样子。模型抽象层的任务是把模型实例变成具有路由标签的资源。我平时会在配置里给每个模型标上能力标签和成本档位例如models: - name: gpt-4o-mini provider: openai-compatible base_url: https://api.example.com/v1 api_key_env: LLM_API_KEY tags: [chat, fast] cost_level: low - name: gpt-4o provider: openai-compatible base_url: https://api.example.com/v1 api_key_env: LLM_API_KEY tags: [chat, reasoning] cost_level: high路由策略是 LLM 网关里最有价值的部分。我常用三种策略按成本路由、按能力路由、按兜底链路由。按成本路由就是默认使用cost_level: low的模型当收到特定指令或者检测到任务复杂度偏高时升级到reasoning模型按能力路由则是根据请求里是否带图片、是否要求工具调用等信号分发到不同模型。兜底链是给每个路由目标配一条 fallback 列表主模型返回 5xx 或者限流错误时自动按顺序尝试下一个模型。这里有个容易踩的坑fallback 链设置不当会烧钱。我之前做过一个配置把昂贵的强推理模型放在兜底链最后结果因为主模型频繁超时大量请求真被转到了贵模型上月底账单直接翻倍。合理的做法是给 fallback 设置概率阈值和次数上限并单独计量被 fallback 消费的 token 数。3.2 Tools 标准化从临时函数到企业级资产Agent 里的 function calling 之所以难维护是因为大家一开始都把工具当普通函数写没人做登记和版本管理。tsm-hub 把 Tools 提升到了资产管理级别。每个工具在网关里都对应一条注册记录字段大致包括全局唯一名称、用途描述、JSON Schema 参数定义、执行目标本地函数还是远端 HTTP、权限标签、调用频控限制、审计开关。注册完以后工具不会自动对 Agent 可见需要绑定到具体的 Skill 或显式授权给某个应用。我在实际项目中强烈建议工具的 description 要写得像写给一个聪明的陌生人看而不是写给同事看。因为模型通过 description 决定何时调用工具描述太含糊模型就会在不该调用的时候调用描述太冗长又浪费上下文 token。标准的做法是先用一两句话说明工具做什么然后说明典型使用条件必要时给出一个反例。比如{ type: function, function: { name: search_web, description: 搜索互联网并返回网页摘要。适用于需要外部实时信息的问题不适用于用户已提供完整资料的情况。, parameters: { type: object, properties: { query: { type: string, description: 搜索关键词 }, max_results: { type: integer, default: 5 } }, required: [query] } } }工具标准化还有一个隐形收益可以给工具做自动化测试。以前 agent 里的函数散在各种业务模块想单独跑工具测试要 mock 一堆上下文现在工具是独立注册的每个工具都能在测试环境里单独调用传入固定参数、断言输出格式回归成本大幅下降。3.3 MCP 接入统一协议下的 server 生命周期管理MCPModel Context Protocol本质上是一套基于 JSON-RPC 2.0 的协议核心就三段调用initialize完成握手tools/list获取工具列表tools/call执行工具调用。tsm-hub 在其中的角色是当 MCP client 去连接外部 server。我见过很多人在接入 MCP 时只图连上能用完全不管生命周期结果 server 进程崩了没人拉起网络断了没有重连。在网关里我们至少要对 MCP server 做四件事连接配置、健康检查、重连策略、能力校验。一个典型的 MCP server 配置长这样mcp_servers: playwright: transport: streamable-http url: http://127.0.0.1:8931/mcp healthcheck: interval_sec: 30 timeout_sec: 5 capabilities: tools: true resources: false blender: transport: stdio command: npx args: [-y, modelcontextprotocol/server-blender]配置里值得注意的一点是capabilities字段。MCP 协议允许 server 声明自己支持 tools、resources、prompts 等能力。如果某个 server 只声明了 resources 没有声明 tools但我们的 agent 却尝试调用它的工具就会收到空列表。这类问题排查起来很费劲所以我习惯在注册阶段就做一次主动握手网关起来时逐个调用tools/list把返回的工具名缓存下来并且在健康检查报告里打印每个 server 的工具数量。数量异常的 server 一眼就能看到。MCP 接入还有一个容易忽略的细节工具名冲突。不同 MCP server 可能都暴露一个叫execute或run的工具如果直接暴露给 agent模型很容易选错。我的做法是统一加前缀比如playwright__browser_goto、blender__mesh_create。这个前缀规则在网关内部强制实现Agent 感知到的永远是重命名后的完整名称不会再撞车。3.4 Skills 管理把提示词、脚本与资源打包成可复用技能Skill 这个概念来自 Claude 生态但现在已经成了 Agent 工程的通用概念。一个 Skill 的本质是把完成某类任务所需的指令、参考脚本、资源模板、依赖说明打包成一个自包含的单元。搞过前端开发的朋友会发现它特别像一个带 README 和 template 的 npm 包。我在 tsm-hub 里Skill 的标准目录结构是skills/ web-research/ SKILL.md scripts/fetch.py requirements.txt assets/templates/report.md.j2SKILL.md 是一个带 YAML frontmatter 的 Markdown 文件里面写清技能名称、版本、用途描述、使用步骤、典型输出格式。网关在加载 Skill 时会把 SKILL.md 里的指令编译成一段系统提示词同时读取 Skill 声明需要的工具白名单和 MCP server 列表把这些工具的 Schema 一起注入到上下文里。Skill 版本管理是我踩过坑之后才补上的。早期我允许直接覆盖同名 Skill 目录结果某次升级 web-research 技能后同一套代码里的解析脚本行为变了所有 report 都少了一节。后来我把 Skill 也纳入了版本策略每个注册的 Skill 必须带语义化版本号Agent 调用时明确指定skillweb-researchv3网关才能把对应版本内容注入。还有一个技巧分享给经常写 Skill 的人不要在 SKILL.md 里写太长的工作流。模型读长流程指令时执行靠前步骤的确定性尚可越到后面越容易漂移。我把长流程拆分成了多个子 Skill每个子 Skill 只负责一个动作再通过主 Skill 里的步骤编排规则把它们串起来。实测下来这种方式比一个巨型 SKILL.md 稳定得多。4. 从零落地 tsm-hub部署、配置与首次调用4.1 开箱环境准备与基础部署以我自己惯用的部署方式为例我会准备一台 Linux 机器安装 Python 3.11 以上版本和 Docker然后通过一个仓库里的docker-compose.yml起服务。因为网关需要连接各种外部依赖我强烈建议数据目录单独挂卷至少包含config/和skills/两个子目录。启动之前把环境变量准备好主要是各类密钥。配置里我习惯用env:引用环境变量而不是直接写明文 key。这样配置文件可以进 Git密钥留在部署平台。启动命令很简单docker compose up -d curl http://localhost:8080/healthz健康检查接口会返回当前加载的模型数量、工具数量、MCP server 连接状态和 Skill 数量。第一次启动如果看到 MCP server 状态为connecting不要慌很多 stdio 类型的 server 首启比较慢等一会儿再看。4.2 最小配置接入一个 LLM 和注册一个本地 Tool最小可用配置其实只需要一个 LLM 和一个本地 Tool。配置文件的重点是这样的先声明模型models: - name: my-llm provider: openai-compatible base_url: https://api.example.com/v1 api_key_env: LLM_API_KEY tags: [chat]接着注册一个本地工具。你的代码里只需要写一个普通函数比如实现当前时间查询from tsm_hub import register_tool register_tool( nameget_current_time, description获取当前时间适用于所有问现在几点的场景。, schema{ type: object, properties: { timezone: {type: string, default: Asia/Shanghai} } } ) def get_current_time(timezone: str Asia/Shanghai) - str: from datetime import datetime from zoneinfo import ZoneInfo return datetime.now(ZoneInfo(timezone)).isoformat()注意到.py文件不需要额外注册路由网关启动时会扫描指定目录下的装饰器标签自动把函数转换成标准的 function schema。我在本地运行时常用tsm-hub serve --config config.yaml --plugins ./plugins这条命令插件目录里放的就是工具实现。4.3 进阶配置挂载外部 MCP server 并注册 Skill最小闭环跑了以后再挂 MCP server。以我最常用的 Playwright MCP 为例先在外面把 MCP server 单独跑起来再把地址写进网关配置。这里有个容易踩的坑如果 MCP server 跑在 docker 里而网关也跑在 docker 里127.0.0.1会指向容器自己的回环地址根本连不上。要用host.docker.internal或者其他容器名来解析。Skill 的注册更直接把 skill 目录放进skills/目录然后执行一次 reload 命令curl -X POST http://localhost:8080/admin/reloadreload 之后健康检查接口里如果出现skill: web-researchv3就说明技能加载成功。这一步建议大家做成 CI 的一部分任何提交到 skills 仓库的改动合并后就自动触发 staging 环境 reload跑一遍冒烟测试再发布能避免大量本地能跑线上不认的问题。4.4 通过统一网关发起一次真实调用一切都配置好之后上层调用非常简单。用 Python 举个例子from tsm_hub import HubClient client HubClient(base_urlhttp://localhost:8080, api_keysk-local) resp client.chat( query帮我查一下 Playwright 这个开源项目的 star 增长趋势并整理成简短的周报, modelmy-llm, skillweb-researchv3, tools[search_web, mcp__playwright__browser_goto], ) print(resp.text)这个请求里我显式指定了模型、Skill 和允许使用的工具集合。网关收到请求后会先加载web-research技能的系统提示词再把两个工具的 Schema 挂到上下文里最后调用模型。模型如果决定先调用搜索工具网关负责执行工具并把结果作为后续消息传回模型整个往返过程对调用方透明。我建议初次使用时把响应里的trace_id存下来。后面排查问题的时候网关的所有请求日志都会关联这个 trace_id从模型调用到工具执行每一条都有记录比在 Agent 侧拼日志要靠谱得多。5. 常见问题速查与避坑经验5.1 连接类问题这类问题通常表现为 MCP server 一直connecting或者 Tool 调用超时。最常见的原因是网络链路不对。我在 docker 环境里被127.0.0.1坑过很多次要记得跨容器访问目标服务时改用host.docker.internal。其次是防火墙和代理拦截如果配置了全局代理内部 HTTP 请求也可能被代理兜走最好在启动环境里对内部网段设置 no_proxy。另一个连接问题的隐蔽来源是 stdio 类型的 MCP server。它由网关拉起子进程如果子进程启动时报错日志却写到了 stderr 没被网关捕获你会看到 server 状态一直是initializing。排查办法是先在命令行手动执行一遍 server 启动命令如果命令行本身跑不出结果那和网关无关是 server 依赖或环境变量的问题。5.2 协议与格式类问题这类问题最典型的是MCP server 已连接tools/list能返回但调用后返回的参数校验错误。原因是很多外部 server 的工具 Schema 写得并不严格有些参数声明了必填但实现里并不需要有些默认值没有声明在 Schema 里。模型按 Schema 传参撞上不匹配的实现就会报错。我的对策是在网关里加了一层参数清洗调用外部工具前按照 Schema 里的default值补齐缺失字段剔除 Schema 里没声明的多余字段。这样一来模型偶尔多传或者漏传参数网关都能兜回来实际错误率明显下降。5.3 运行期效率与稳定性问题运行期最常见的问题是上下文膨胀。Skill 注入的提示词太长加上工具 Schema 太多模型上下文被塞得满满的不仅费用上涨推理延迟也会变长。我建议给工具 Schema 做分级高频常用工具始终注入低频工具只保留名称和一句话描述等模型明确表示需要时才通过二次请求拉取详细 Schema。虽然多了一次交互但整体 token 省了很多。稳定性方面MCP server 出现偶发性崩溃很正常。网关里设置了自动重连但重连间隔要调得保守一点我目前用 30 秒起步、指数退避到 5 分钟。重连期间调用请求会失败我在网关层会返回一个标准 error codeAgent 看到后可以提示用户该能力暂时不可用而不是直接把一个模棱两可的异常抛给用户。5.4 问题速查表现象可能原因排查方法解决方案MCP server 一直 connecting网络隔离或端口不通telnet目标端口、查看 server 启动日志改用 host.docker.internal 或修正防火墙tools/list 返回空列表server 未声明 tools 能力查看 server 的 capabilities在配置里开启 tools 能力或换 server工具调用报参数校验错误Schema 与实现不一致在网关侧打印实际落库参数启用参数清洗剔除多余字段并补默认值Skill 注入后回复质量下降SKILL.md 太长或工具白名单过宽查看注入后的实际 token 量拆分 Skill、缩小工具范围fallback 后费用飙升兜底链次数无限制查看 token 计量报表设置 fallback 次数阈值和概率开关stdio 类型 server 启动失败server 依赖缺失手动执行 server 启动命令补依赖、修正 node/python 环境6. 应用场景与后续进化方向6.1 作为企业内部 AI 能力中台统一网关最典型的归宿是成为企业内部多个业务线共享的 AI 能力中台。不同部门都在做自己的 Agent如果没有统一网关每个部门都要自己对接模型厂商、维护工具服务、管理 MCP server等于重复发明轮子。接上 tsm-hub 以后模型密钥统一由平台方管理工具由各业务线以插件形式注册能力开放范围由平台统一审批。这样既保证了灵活性又避免了模型账单和密钥权限失控。在这个场景里网关的运维价值甚至比开发价值更明显。因为所有能力都有注册记录和调用日志安全审计、成本分摊、容量规划都能按资源 ID 维度来做。出问题的时候说是mcp__payment__query_balance这个工具最近三天成功率下降比笼统说agent 有问题要高效得多。6.2 作为个人与团队的 Agent 开发基础设施小型团队或个人开发者也完全用得上这套模式。我认识的不少研究者手头有几十个脚本工具和几个常用的 MCP server以前每个项目都要复制一遍工具定义现在只要维护一个统一的配置文件所有项目通过同一个网关调用。对个人来说最大的收益其实是少写胶水代码新项目接入模型和工具只需要写一份 config 引用不用再为每个新项目重新搭一遍 function calling 的管子。此外统一网关还给个人开发带来一个额外好处可以安心升级。以前升级某个工具库总担心影响正在跑的项目现在工具以独立插件形式存在升级时先在 staging 里跑回归测试确认没问题再切换做起来很顺手。6.3 能力扩展多租户、策略引擎与技能市场再往后走这类网关的进化方向也很明确。第一是多租户每个业务线拥有独立的能力可见范围、独立的 token 配额和独立的审计视角。第二是策略引擎不只做静态授权还能基于上下文做动态判断比如包含财务关键词的请求禁止调用写操作工具。第三是技能市场把经过验证的 Skill 和 MCP server 做成可分享的内部包团队之间维护一套公共资产仓库而不是靠复制目录传播。我个人在实际搭建这套东西时最深的体会是别贪大。先跑通一个模型、一个工具、一个 MCP server 的最小闭环把日志和 trace 体系建好比一开始就追求大而全的配置要重要得多。我见过太多项目上来就接了十几个 MCP server结果排查问题的时间远超开发时间。小步快跑能力一个一个加才是这类网关能长期稳定运转的节奏。