1. 为什么我需要第三个统一网关分散接入的混乱现状先交代一下背景。我所在的团队从去年开始密集推进 AI 能力落地每个人都在自己的项目里接 LLM。那段时间我经常要处理一种哭笑不得的重复劳动甲用 OpenAI 接口接了分析助手乙用另一个厂商的模型做了文本摘要丙自己搭了个内部工具让模型调用数据库查询丁又单独部署了一个 MCP server 暴露公司维基给 Agent 用。表面上大家各干各的实际上这些项目之间的模型连接、工具注册、权限控制几乎都是各写一套没有一个公共的底座。刚开始我觉得这也没什么毕竟每套业务都有自己的特殊性。直到有一次我需要把两个项目的能力互相打通——A 项目里已经做好的一个文档解析工具要提供给 B 项目的 Agent 使用结果发现 B 项目根本不知道怎么调用 A 的工具因为两边定义的参数格式、认证方式、超时机制完全不一样。为了让它俩协作我硬生生在中间补了一层胶水代码调了两天 bug 才算跑通。那次经历让我彻底意识到靠谁需要谁去对接的协作方式本质上是在给系统持续制造技术债。后来我做了一个决定与其继续在各个项目里重复造轮子不如把 LLM 接入、Tools 注册、MCP 连接、Skills 管理全部收进一个统一的网关层让所有上层的 Agent 和业务应用都通过它来访问模型能力和工具能力。这个项目我命名为 tsm-hub取的是 Tools、Skills、Models 三个词的首字母顺便也暗含了集中枢纽的意思。这篇文章就是把整个项目的设计思路、落地过程和一些踩坑记录写出来给同样在搞 AI 基础设施的团队一个参考。适合读这篇文章的人有两类一类是正在规划 Agent 平台或 LLM 网关架构的后端工程师、AI 平台工程师另一类是单纯被项目里接了个大模型但不知道怎么管工具困扰的开发者。我会尽量把设计取舍和背后的为什么讲清楚而不只是贴代码。2. tsm-hub 的设计锚点先想清楚网关到底管什么在动手写第一行代码之前我花了大概一周时间梳理需求。不做这一步的后果很容易预见写着写着网关就会变成一个什么都往里塞的万能筐最后谁也维护不了。我给自己列了四个必须回答的问题。第一网关是不是又要重新抽象一遍模型接入市面上的 LLM 接入层已经很多了什么 OpenAI SDK、各种厂商的 Python 包几乎每个模型都有一套自己的调法。如果 tsm-hub 再搞一个完全新的抽象那和过去所有项目里的胶水代码没有本质区别。所以我的选择是网关统一以 OpenAI 兼容格式作为对外模型接口内部通过 provider 适配层去对接不同厂商的 API。这样上层业务完全不用改只要会调 OpenAI 格式就能用而底层想切换模型的时候只需要在网关改配置。第二工具调用的标准谁能服众工具这一层最靠谱的通用描述语言就是 JSON Schema。OpenAI 的 function calling、Anthropic 的 tool use、以及大部分国产模型平台的工具定义本质上都遵循 JSON Schema 的结构。我决定所有注册进网关的工具都必须提供完整的 JSON Schema 入参定义并且由网关统一维护每个工具的能力描述、入参校验、超时配置和错误映射。上层 Agent 不用感知工具底层跑的是什么语言、部署在哪台机器。第三MCP 场景下网关扮演什么角色MCPModel Context Protocol这两年势头很猛它要解决的是模型和外部数据源/服务之间的通信标准化问题。本质上 MCP 协议是件好事但一个很现实的问题是很多 Agent 项目发现自己要维护好几个 MCP client 的连接、处理握手、路由请求、管理多 server 的会话这些工作非常重复。tsm-hub 的定位是做一个 MCP 客户端网关 把远端各种 MCP server 变成网关内部的基础设施资源上层 Agent 只调用网关暴露的 HTTP 接口由网关代为完成 MCP 握手、请求转发和结果回传。第四Skills 到底是什么层级的东西现在Skills这个词在 Agent 领域有点被炒糊了有人把它理解为提示词模板有人理解为工具的集合还有人理解成完全自动化的任务流。我给的落地方案是Skills 是绑定在 Agent 上的领域能力包它把系统提示词、工具列表、调用约束、甚至一部分 MCP 资源绑定成一个整体配置。Agent 启用一个 Skill就等于同时加载了这套东西的所有能力。它不是一个运行时独立运行的进程而是一种编排层的抽象。这四个问题想清楚之后tsm-hub 的边界就明确了模型接入归网关管、工具注册归网关管、MCP server 的生命周期和请求分发归网关管、Skills 的装配和启用也归网关管。业务逻辑继续留在上层应用里网关绝不越界去帮业务做决策。3. 请求从进入到返回的完整链盘一次带工具调用的对话到底走了哪些路有了设计锚点我直接进入核心链路的设计。tsm-hub 的请求处理流程是我最重视的部分因为一个网关如果不能让调用者清晰理解请求从哪里进、到哪里出、中间经历了什么那它在生产环境里就是黑盒出了问题根本没法排查。一次典型的请求长这样上层 Agent 发来一个用户问题比如查一下上个月华南区的销售数据并用一句话概括趋势。网关的完整处理过程拆成六个环节。环节一认证与路由。请求先打到网关的 /v1/chat/completions 接口网关根据 API key 识别调用者身份查到它对哪些模型有权限、默认使用哪个模型、坐了哪些 Skills 绑定。这一步还包含租户隔离和频控策略。接着网关把请求参数里的 model 字段映射到实际的后端模型配置这个映射表存在网关的配置中心里。环节二上下文装配。网关把 Agent 绑定的 Skill 内容加载进来主要包括系统提示词扩展、Skill 声明的工具白名单、以及可能附加的知识库检索提示。这一步很关键——模型实际感知到的系统提示词已经不是上层 Agent 最初发来的那一段而是经过了 Skill 层的叠加。环节三首次模型调用。网关把拼装好的 messages、tools 定义一起发给后端模型。注意这里 tools 的定义是网关从工具注册中心动态捞出来的它会过滤出当前 Agent 有权限调用的工具再转换成目标模型厂商要求的格式。模型如果判断需要调用工具会返回一个 tool_calls 结构而不是直接给最终答案。环节四工具分发与执行。网关解析 tool_calls对每一个工具调用请求做合法性检查参数是否满足 JSON Schema、工具是否存在、调用者是否有权限然后按工具注册的路由信息把请求发出去。这里的发出去可能是 HTTP 调用一个内部微服务也可能是通过 MCP client 转发给某个 MCP server还可能是直接执行一段内嵌的本地函数。工具执行结果统一包成网关定义的消息格式。环节五结果回填与二次模型调用。工具执行结果作为 tool 角色的消息追加到对话上下文里网关再次发起模型调用。这一次模型拿到了真实的工具返回数据才会生成面向用户的最终文本。这一步在 Agent 场景里经常会循环多次因为模型可能看了第一次工具结果后还想再调第二个工具网关要支持这种多轮工具调用的循环并且设置最大迭代次数防止死循环。环节六流式返回与审计。最终生成结果通过 SSE 流式返回给上层 Agent。同时网关把整条链路的调用日志、token 消耗、各环节耗时写进审计存储方便后面复盘。这个链路听起来不复杂但落地的时候有一堆细节值得讲尤其是第四环节的工具分发。工具执行结果到底应该怎么包直接决定了模型看到的数据质量。以我的经验工具返回结果不能是裸数据必须带上执行状态。所以我定义了一个标准包裹结构每个工具结果至少包含 status成功/失败/超时、result业务数据、error失败时的错误描述、latency_ms耗时、tool_call_id用于和多轮对话对齐。4. 模型适配层的实现细节统一格式是理想厂商差异是现实现在进入到 tsm-hub 里最给我添麻烦、也最值得写的一个模块模型适配层。我必须先说一个反直觉的结论OpenAI 兼容格式并不是所有模型都能天然兼容的。名义上大家都说支持实际用起来你会发现各有各的小脾气。我接入过的模型包括 OpenAI 系、Anthropic 系、以及几家国产大模型平台表面都是 chat completion 的格式细节差异能把人逼疯。第一个差异是工具调用的返回格式。OpenAI 的 tool_calls 长这样{ tool_calls: [ { id: call_abc, type: function, function: { name: query_sales, arguments: {\region\:\华南\,\month\:\last_month\} } } ] }注意 arguments 是一个 JSON 字符串不是对象。而 Anthropic 的 tool_use 返回块里 input 直接就是对象名字也不一样。我在适配层里写了一个归一化函数把各家返回的 tool_call 统一转成网关内部结构再在发给上层时统一成 OpenAI 格式。这样上层永远不用感知底层模型是谁。第二个差异是系统提示词的处理方式。Anthropic 对 system 消息有单独的字段而 OpenAI 是把 system 当作 messages 里的普通角色。有些不那么严格的平台会拒绝超过一条的 system 消息有的则会静默合并。针对这个我在适配层里做了一个 system 消息合并器当 Agent 配置的 Skill 和业务都提供了系统提示词时网关按基础系统片段 Skill 片段 业务临时片段的顺序拼接成一条完整的 system而不是发送多条。第三个差异是模型的非工具混合输出。有的模型在返回 tool_calls 的同时还会附带一段文字解释有些平台这段文字会留在 content 里有些平台的 content 直接是 null。为了让上层展示更友好我在归一化时会把这种附带文本单独提取出来作为 tool_calls 前的 assistant 消息保留。这样 Agent 可以先把模型的话播给用户听再去执行工具体验上比傻等工具执行完再一次性回复要自然得多。还有一个我实测踩过的坑不同模型的 max_tokens 上限差异极大。有的模型单次输出上限才 4K token有的能到 32K。网关不能把上层传来的 max_tokens 原封不动传给所有模型否则小上限的模型会直接报参数非法。我的处理方式是适配层维护每个模型的最大 token 区间上层传的参数超过模型上限时就静默截断到模型上限低于模型下限时就拉高到下限。这个动作不大但能避免生产环境里一堆莫名其妙的 400 报错。5. 工具注册中心与 MCP 连接池网关最容易翻车的两个地方工具注册中心是我在设计阶段着墨最多、也最浸润经验的部分。先讲它的数据模型。每个注册进 tsm-hub 的工具本质上是一条路由配置包含以下字段字段说明示例name工具唯一名称Agent 通过它引用工具query_sales_datadescription模型决定是否调用工具的判断依据查询指定区域和月份的销售汇总数据parametersJSON Schema 入参定义定义 region、month 字段类型与必填性executor工具实际执行方式http: //sales-service/call 或 mcp://bi-server/tool/querytimeout_ms单次执行超时5000retry_policy失败重试策略指数退避最多两次scope哪些租户或 Agent 可用all 或按租户 ID这里必须强调 description 怎么写。很多第一次做工具接入的人容易把 description 写得很笼统比如查询销售数据。模型面对多个工具时根本分辨不出 query_sales_data 和 query_sales_summary 有什么区别于是它可能随机选一个或者干脆不调用。我的经验是description 要把什么时候该调用这个工具和什么时候不该调用写清楚甚至可以把调用前提写进去。一个我实际用过的例子当用户询问销售数字或任何与销量、金额、订单量相关的统计口径问题时调用此工具。如果用户只是要下载销售报表文件请使用 download_sales_report 而不是本工具。这种正反双重描述的效果非常明显模型选错的概率大幅下降。再说 MCP 连接池。这是网关里让我翻车最狠的一个模块。MCP 客户端和 MCP server 交互时要先完成 initialize 握手这个握手过程要做版本协商、能力声明、认证一次握手正常也要几十到几百毫秒。如果网关对每一次工具调用都重新建立连接性能根本无法接受。我在 tsm-hub 里维护了一个 MCP 连接池按照 server 地址做连接复用。每个 MCP server 在首次被某个工具调用的时候建立连接后续请求通过同一个 session 通道发送 JSON-RPC 消息。连接池还会做定期健康检查发现 server 失联就标记为不可用并触发自动重连。光有连接复用还不够还有一个并发问题。同一个 MCP server 的 session 通常是串行处理请求的如果网关一次性收到多个工具调用都指向同一个 MCP server直接往一个 session 里并发写消息很容易出现乱序响应。我的解决方案是给每个 MCP server 的连接池加请求队列默认每一个 session 同时只允许处理一个请求其他请求按到达顺序排队。后来觉得性能不够又改成了每 server 配置最大并发数通过多个 session 实例分摊压力。这个参数不能盲目调大因为 MCP server 未必是并发安全的调大了可能直接把你远程服务的内存打爆。工具注册中心还有一个容易被忽略的问题工具幂等性。HTTP 执行类的工具天然存在网络抖动导致的超时重试如果上游服务没有做幂等处理重试就意味着重复下单、重复发消息。网关的 retry_policy 应该允许工具在注册时声明是否可重试标记为不可重试的工具在超时后只能直接返回失败不再自动补一次请求。我在早期版本里没做这个标记结果某个工具因为超时重试给用户重复发送了两次审批通知排查了半天才发现是网关的重试逻辑在作祟。6. Skills 的声明式设计把技能当配置写而不是当代码写Skills 在 tsm-hub 里被设计成可加载的配置包。它不包含任何运行逻辑只描述一套能力组合。每份 Skill 遵循一个简单的目录结构核心是一个 markdown 格式的清单文件skills/ sales-analyst/ SKILL.md prompts/ default.md tools.yaml mcp_resources.yamlSKILL.md 开头声明元信息--- name: sales-analyst description: 让 Agent 具备销售数据分析能力适用于销售日报、月度复盘、区域对比等场景 version: 1.2.0 ---正文部分写的是对 Agent 行为的约束和引导比如要求 Agent 在查询前先通过工具确认日期格式、在给出结论时必须附上数据来源等。这些内容会在请求进入网关时被拼接到系统提示词里。tools.yaml 定义了启用这个 Skill 时要加载哪些工具权限tools: - query_sales_data - download_sales_report - compare_regions mcp: servers: - bi-server这也就是说当上层 Agent 声明启用 sales-analyst 这个 Skilltsm-hub 就知道这个 Agent 能调用哪几个工具、能访问哪个 MCP server。用户没启用这个 Skill 的时候就算他手动在请求里指定了 query_sales_data网关也会拒绝执行因为没有 Skill 授予权限。我在设计初期把 Skills 做得太重了想让它支持一套自己的上下文记忆机制、甚至内置一个小状态机。后来被团队成员劝住了——越重的抽象越难普及最终我砍掉了所有运行态的东西让 Skills 只保留声明和装配这一个职责。实际效果证明这个决定是对的因为我们可以非常轻量地通过修改 SKILL.md 内容来调整 Agent 行为不需要改任何代码。有一次产品想调整 Agent 对数据的解读风格我直接把 SKILL.md 里的一段行为描述改了重新加载五分钟生效。这里还涉及一个细节Skill 的版本管理。我遇到过这种情况——同一个 Skill 被多个 Agent 使用更新后部分 Agent 对旧版依赖很强直接全部切换版本可能导致行为突变。tsm-hub 的方案是技能版本钉扎每个 Agent 在绑定 Skill 的时候会记录一个版本号网关对外暴露的是具体版本对应的装配内容而不是简单的最新版。新版本会先在一个测试 Agent 上跑一段时间确认没问题再做默认切换。这有点类似于依赖管理里的 lockfile踩过坑的人应该能理解为什么要这么做。Skills 还有一个好处是能倒逼团队把知识文档化。以前提示词都散落在代码里、需求文档里、甚至个人聊天记录里有了 Skills 之后Agent 的能力边界和行为约束第一次有了一个集中、有版本、可审查的载体。我们团队的运营同学也能参与 Agent 调优了因为她只需要修改 SKILL.md 里的文本不需要碰任何代码。7. 配置格式与最小可用部署三十分钟跑起来一个网关全部设计说完了如果你也想在自己的环境里把 tsm-hub 跑起来我给出一份最小可用的部署实例。tsm-hub 的默认配置入口在一个 tsm.yaml 文件里核心包含三块模型接入、工具注册、技能绑定。下面是实际可用的最小配置我省略了部分本地密钥。server: port: 8080 api_key: sk-local-dev models: default: deepseek-chat providers: - name: deepseek type: openai_compatible base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} models: [deepseek-chat, deepseek-reasoner] - name: anthropic type: anthropic api_key: ${ANTHROPIC_API_KEY} models: [claude-sonnet-4] tools: - name: current_time description: 获取当前服务器时间当用户询问日期时间时调用 parameters: type: object properties: {} executor: type: local function: builtin.current_time - name: web_search description: 搜索最新网络资讯当用户询问实时信息、新闻、事实核查时使用 parameters: type: object properties: query: { type: string, description: 搜索关键词尽量精确 } executor: type: http url: http://search-service:3000/search timeout_ms: 8000 mcp: servers: - name: wiki-server transport: sse url: http://wiki-mcp:8081/sse skills: - name: basic-assistant tools: [current_time, web_search] mcp_servers: [wiki-server]这份配置大概表达了三件事。第一模型默认走 deepseek 的兼容接口同时把 Anthropic 也接进来备用。第二网关内置了一个本地时间工具和一个 HTTP 搜索工具。第三MCP 层挂了一个 wiki-server并且把前两件套进一个叫 basic-assistant 的 Skill 里。部署我用的是 Docker Compose一个大致的形态services: tsm-hub: image: tsmhub/tsm-hub:0.6.2 ports: - 8080:8080 environment: - DEEPSEEK_API_KEY${DEEPSEEK_API_KEY} - ANTHROPIC_API_KEY${ANTHROPIC_API_KEY} volumes: - ./tsm.yaml:/app/tsm.yaml - ./skills:/app/skills restart: unless-stopped search-service: image: myorg/search-service:1.2.0 restart: unless-stopped wiki-mcp: image: myorg/wiki-mcp:latest restart: unless-stopped上层 Agent 接到 tsm-hub 的方式非常简单就是调用 OpenAI 格式的接口。如果要让 Agent 启用 basic-assistant 这个 Skill只需要在请求的 header 里带上 Agent 的标识网关根据这个标识查它的技能绑定关系自动加载对应 Skill如果 Agent 没有绑定任何 Skill网关就只暴露 models 配置里的默认模型能力不注入任何工具。硬控制这一点很重要防止有 Agent 绕过技能体系去调用没授权的工具。8. 实测表现与三个让我失眠的线上问题技术方案说完了来点真刀真枪的实测数据。我压测过 tsm-hub 在单机 2C4G 环境下的表现结果供参考纯文本生成不调工具场景下网关自身的额外开销只有 8 到 15 毫秒带一个工具调用的场景网关额外开销在 20 到 40 毫秒。真正的耗时大头还是模型 API 本身和工具服务的响应时间。具体数据取决于模型和工具。不过性能那点开销不是让我睡不着的原因真正让我半夜爬起来看日志的是下面三个问题。问题一MCP server 握手后的会话失效请求排队被卡死。早期版本里MCP 连接池里如果一个 session 已经断开但它还留在可用队列里后续请求就会一直往这个死会话上写消息然后白白等到超时。这个问题的排查过程很经典——表面现象是某个 Agent 的工具调用特别慢每次都卡 10 秒才报错但看 MCP server 的日志又没有任何报错。最后我在网关里加了会话健康标记每次从连接池取 session 前先发一个 ping 消息或者记录上一次收到的 server 端消息时间超过 60 秒未收到任何响应就强制重建连接。这个坑让我意识到连接池管的不只是连接更重要的是连接的有效性。问题二工具返回体过大把模型的上下文窗口撑爆。有一个 MCP server 返回的数据经常是几万字的原始文本网关直接把它塞进 messages 发给模型结果模型提示 context length exceeded。后来我加了一个工具结果裁剪器对于超过阈值的结果先尝试用摘要提示词只保留关键信息或者直接将结果截断并注明结果已截断完整数据请通过查询工具获取。这个设计需要工具在注册时声明自己的返回体是否可裁剪可裁剪的才允许做摘要处理。问题三多 Agent 共用同一个 MCP server 时的资源争抢。某个 MCP server 底层连着一个外部数据库连接数有限。网关按照并发参数给这个 server 开了 8 个 session结果高峰期把数据库连接全占满了其他业务直接被拖垮。最后我给 MCP server 的连接池加了一个全局并发配额并且支持在工具维度设置限流。这套限流机制上线之后同一个 server 被多个 Agent 大量调用时再也没出过互相拖垮的事。9. 网关的下一步我眼里 tsm-hub 还能往哪里走tsm-hub 目前已经是我们团队 AI 基础设施的核心组件但说实话它还远没到可以高枕无忧的状态。我这里想聊聊自己计划里的一些方向也许你也能从里面找到启发。第一个方向是把网关的审计数据真正用起来。现在每次请求的模型调用、工具调用、token 消耗都记录了日志但我们目前的用法只停留在出了问题翻日志。下一步我想在网关内部做一层简单的质量和成本看板比如每个 Skill 的工具调用成功率、平均耗时、模型 token 浪费率工具结果被重复发送导致的 token 膨胀。这些数据如果可视化出来对优化 Skill 配置非常有帮助。第二个方向是让 Skill 支持条件装配。现在的 Skill 是绑定后全部加载但有些场景希望 Agent 根据意图动态启用部分工具。比如 Agent 先判断用户的问题偏向知识问答还是数据分析然后再决定载入哪个小技能包。这会比现在一次性加载一个大而全的 Skill 更省 token但注意这也意味着网关要做请求级动态装配复杂度会显著上升我不会轻易动这个结构。第三个方向是强化网关对多租户的支持。目前我们对租户的隔离主要靠 API key 和权限过滤工具注册表和 MCP server 配置还是全局共享的。以后如果真要做成多业务线可自助申请的平台可能得把配置模型从全局扁平升级成租户口令式——每个租户能看到和使用的工具、模型、Skill 各不相同。这不是一个简单的数据模型调整牵扯到配置合并、权限推导和密钥托管方式的变化。我个人的体会是网关这类基础设施项目最忌讳的就是闭门造车。它服务的对象是上层的各式 Agent 和应用如果你的抽象跟实际使用方式脱节再漂亮的架构也撑不住真实业务的冲击。tsm-hub 一路改到现在很多我认为细致入微的设计反而是在被使用者反复问为什么不能更简单一点之后砍掉的。如果你也在做类似的东西我的建议很简单第一版能跑通最小闭环就赶紧上然后让真实请求来教育你配置格式尽可能用主流生态的语言来表述别自造一套概念最后永远给每一种工具调用失败留一条显眼的可排查路径否则线上出问题时你会在日志和数据之间挣扎很久。如果你已经在自己的项目里做了类似的统一网关或者对 tsm-hub 的某个设计有不同的实现思路欢迎来聊聊。这类基础设施没有标准答案每踩过一个坑都是赚到的经验。