1. tsm-hub 要解决的问题从“能用”到“好用”的那道坎1.1 一个真实痛点AI Agent 项目里的“三重割裂”如果你最近在做 LLM 应用开发尤其是那种带工具调用和 Agent 能力的项目大概率遇到过这些情况模型这边接的是 OpenAI 兼容接口换一个供应商就得改一套连接配置工具那边散落在各个业务模块里有的走 HTTP 接口、有的走本地函数还有的塞在某个 MCP Server 里技能和经验沉淀更是随意写好的 prompt 模板藏在笔记软件里换台电脑就找不到。我见过不少团队AI 应用功能没问题但代码越写越乱。模型调用逻辑、工具注册表、提示词模板揉在一个文件里加一个新工具要动核心代码换一个模型要全局搜索替换。这个时候真正需要的不是再写一个 Agent 框架而是把 LLM、Tools、MCP、Skills 这几类资产收口到一个统一的网关层。tsm-hub 就是干这件事的。它的核心思路很简单所有模型、工具、技能都通过一个统一入口注册、发现、调用。上层业务不再关心底层接的是哪个模型、工具部署在哪台机器、技能是用什么格式写的。这其实是软件工程里经典的外观模式只不过应用在了 AI Infra 层。做出来的效果是业务代码只跟网关打交道模型和工具的更换对上层完全透明。1.2 tsm-hub 的定位中间层网关不是框架更不是业务系统很多人在第一次看到 tsm-hub 时会问它和 LangChain、LlamaIndex 这些有什么区别它是不是又一个 Agent 框架我的理解是tsm-hub 的定位更接近一个“网关”或者说“调度中枢”。它不规定你用什么编排方式不做复杂的 Agent 决策循环也不绑定特定的前端界面。它解决的是资产接入和调度的问题一个模型要接入系统走一遍注册流程就行一个工具要上线按规范声明接口就行一个 MCP Server 要挂载配置连接信息就行一个 Skill 要生效放对目录并做一次索引构建就行。这跟你直接用代码调用 SDK 是两种体验。直接调用 SDK 是在代码里硬编码依赖而通过网关调用是在统一契约下做资源接入。打个比方前者是每次出差都要自己订酒店、租车、找会议室后者是给行政一个需求单行政统一安排好。tsm-hub 做的是那个“行政”的角色。适合来参考这个方案的主要是有一定积累、开始被杂乱的模型与工具管理折磨的 AI 应用开发者以及想给团队沉淀一套标准化 AI 资产接入规范的技术负责人。如果你现在只是写个 Demo 跑通一次对话那确实用不上这类网关但只要你开始同时接两三家模型、维护十几个工具、想让团队协作而不是各写各的这个思路就很有价值。2. 整体设计拆解四类资产的统一调度模型2.1 统一入口一次接入处处调用tsm-hub 在架构上最核心的设计是规定了四类资产的接入契约。LLM 用一种声明格式描述模型信息Tools 用一种接口规范声明工具能力MCP Server 用标准的 MCP 协议接入Skills 用一套目录和元数据规范管理。这四个维度并不互斥它们在实际场景里是协作关系。比如你有一个“查天气”的工具它可以是一个本地函数工具也可以是一个 MCP Server 提供的工具。从网关视角看它们都归为“可被模型调用的能力”。Skills 则更偏上层它是一套带预设指令、示例、参数说明和工具编排方案的能力包。Skill 可以内部引用多个 Tools也可以在调用时指定使用哪个 LLM。统一入口带来的直接好处是调用方式的收敛。业务侧只需要向网关发送一个请求里面带上目标 Skill 名称或直接请求某个工具网关负责去匹配模型、组装上下文、解析返回结构。我把这种模式叫做“声明式调用”——业务不关心过程只声明要什么结果。实操中这个设计带来的收益很明显。我们团队之前新接一个向量数据库查询工具从开发到上线用了两天就是因为只需要按网关的工具规范写一个声明文件和一个 handler 函数注册完即可被所有 Skill 复用。之前直接在 Agent 代码里写工具调用至少要改三四个文件还要处理函数命名冲突。2.2 LLM 层多模型路由与鉴权收敛LLM 接入是网关最贴近日常使用的部分。tsm-hub 将模型视为可路由的资源每个模型配置里包含供应商信息、模型名称、base URL、鉴权方式、上下文长度上限、默认参数等。网关在收到调用请求后根据路由规则挑选合适的模型执行。路由规则可以很简单也可以很复杂。简单的写法是给每个模型打标签比如“代码能力”“中文写作”“低延迟”“高性价比”请求里声明需要的标签网关按标签匹配。复杂一点可以支持权重分配、故障降级、上下文长度自适应等策略。我实际用下来先做基于标签的静态路由就够应付绝大多数场景没必要一上来就上动态负载均衡。鉴权收敛是这里最值得花力气的地方。模型 API 的密钥散落在各个业务代码里是不少项目的常态。我见过一个项目仓库里某个工具的配置文件写死了生产环境的 API Key一次偶然的提交就泄露了。走网关之后密钥统一放在服务端环境变量或密钥管理服务中业务侧只持有网关自身的访问凭证。这样即使某个业务模块被反编译或日志泄露也拿不到真正的模型密钥。2.3 Tools 与 MCP标准协议下的工具接入工具接入这块是 tsm-hub 和 MCP 协议结合最紧密的部分。MCP 给了工具一个标准化的接入协议工具提供方只要实现一个 MCP Server就能让支持 MCP 的客户端调用。tsm-hub 做的事情是把多个 MCP Server 统一挂载到网关里同时对尚未 MCP 化的本地函数和历史 HTTP 接口提供同样的工具契约。我建议把工具划分为三类来管理Prompts 工具、Res Prompts 工具、查询类工具。这个分类不一定是官方概念但实践中很实用Prompts 类需要模型根据用户问题生成参数再调用比如“生成一段查询语句并发给数据库 API”Res 类由外部事件触发或定时执行Agent 直接取回结果比如“拉取某个接口的最新数据”查询类纯粹的函数式调用输入参数确定输出结果确定不需要模型参与生成这种区分的意义在于调用时机的不同。Agent 循环中不是所有工具都需要先经过模型生成参数有些工具可以直接执行并把结果塞回上下文这能省不少 token 和响应时间。MCP 工具的接入相对直接关键是确保 server 的连接信息正确。我遇到过不少 MCP 连接问题最后发现是传输方式选错了——有的 Server 只支持 stdio有的只支持 HTTP配置里没对应上就死活连不通。这一块我会在后面问题排查章节展开细说。2.4 Skills可复用技能包的加载链路Skills 是 tsm-hub 里最有想象力的部分。它像一个可复用技能单元封装了完成一类任务所需的全部要素系统提示词、工具列表、调用流程示例、必要参数和输出格式定义。比如你写了一个“代码审查 Skill”它内部指定要调用“读取仓库结构”和“读取文件内容”两个工具并用一段高质量 prompt 约束模型按安全、性能、可维护性三个维度输出审查意见。Skill 的价值在于沉淀和复用。团队里最会写 prompt 的人把技能打磨好其他人通过网关直接调用这个 Skill不需要重新设计 prompt。久而久之网关变成了一个组织级的 AI 能力资产库。新同学上手项目看一遍已注册的 Skills 就知道这个项目能做哪些事比看一堆文档高效得多。加载链路也很清晰。一个 Skill 就是一组文件SKILL.md 描述技能行为和适用范围skills/ 目录存放可复用的子步骤或子技能scripts/ 目录放需要执行的脚本 的流程里还会带上 demo 示例。网关启动时扫描技能目录解析元数据构建索引。调用时通过名称或描述匹配把匹配到的 Skill 内容注入上下文模板再和用户的输入一起送进大模型。我实践中的一个体会是Skill 的粒度要控制好。太粗则难以复用太细则调用成本高、维护负担重。经验和技巧是围绕高频且有明确边界的事务建 Skill比如“周报生成”“接口文档审查”“SQL 优化建议”。像“写代码”这种边界极宽的技能不建议做成一个 Skill拆成“修复语法错误”“补充测试用例”“重构函数”这种粒度更实用。3. 实操过程与核心环节实现3.1 环境准备初始化一个最小可用的 tsm-hub 实例先说环境。tsm-hub 本质上是运行在服务端的网关服务我习惯用 Docker 部署这样模型连接、工具注册和技能索引都在容器里收敛不污染宿主机环境。基础依赖包括 Python 3.11、Node.js 18部分 MCP Server 需要、Docker 和 Docker Compose。初始化时我会分三步走。第一步准备一个干净的配置文件目录把网关的核心配置拆成几个文件config.yaml放全局配置models.yaml放模型注册表tools.yaml放工具与 MCP Server 注册表skills/目录放技能包。第二步把模型供应商的密钥配置到环境变量里坚决不写在 yaml 文件中。第三步跑起一个最小实例先不加入任何工具和技能只验证模型调用通路。这里我踩过一个坑。早期图省事把密钥直接写进了config.yaml结果在一次协作提交中差点把密钥推到远端仓库。后来强制规定所有密钥必须通过环境变量或密钥管理服务注入配置文件只允许引用变量名。建议你在一开始就建立这个习惯否则后期整改成本极高。最小实例验证通过之后再做工具和技能的接入。3.2 网关路由核心逻辑设计与实现网关的核心路由逻辑就是把“请求”转化为“具体模型和工具的调用链”。我在实际设计时把一次典型调用拆成了五个阶段解析意图、匹配 Skill、填充上下文、路由模型、执行工具调用组合。解析意图阶段网关读取用户的自然语言输入同时附带上一次对话的上下文摘要。匹配 Skill 阶段通过对输入做嵌入向量化与 Skill 索引做相似度检索选出一个或多个候选 Skill。填充上下文阶段把 Skill 的 system prompt、相关工具定义、示例片段组装成模型可理解的上下文。路由模型阶段最需要仔细琢磨。我采用的方案是维护一份路由表每条路由规则包含标签匹配条件和权重。比如“优先使用代码能力强的模型处理 Coding 类 Skill通用对话走低成本模型流式输出场景选择流式支持稳定的模型”。实现的时候其实就是根据请求携带的元数据如 Skill 类型、用户等级、超时要求去过滤模型列表再按优先级排序选出一个。执行工具调用组合阶段网关把模型输出的工具调用意图解析成具体的工具执行计划逐个调用工具并把结果回传给模型。这里需要注意递归深度控制。模型有时候会连续调用多个工具如果放任不管一方面 token 消耗巨大另一方面可能进入死循环。我的做法是设置单轮任务最大工具调用次数为 8 次达到上限后强制让模型基于已有信息作答。伪代码逻辑大致如下async def handle_request(user_input, session_id): skills match_skills(user_input) model select_model(skills.preferred_tags, user_input) context build_context(skills, session_history) tool_calls 0 while tool_calls MAX_TOOL_CALLS: response await llm.chat(model, context, toolsskill_tools) if not response.tool_calls: return response.content results await execute_tool_calls(response.tool_calls) context.add_assistant_tool_results(results) tool_calls len(response.tool_calls) return fallback_response(工具调用次数超过限制基于已有信息回答)这里要特别提醒一点工具调用结果的回传格式一定要规范。不同模型对工具结果的格式要求略有差异但按照 MCP 协议里定义的 ToolResult 结构来组织是最稳妥的。否则模型会不理解工具返回了什么可能在下一轮重复调用同一个工具浪费时间和 token。3.3 对接 MCP Server 的完整步骤对接 MCP Server是 tsm-hub 在实际落地中最常用的能力。先说怎么检测一个 MCP Server 是否正常。我习惯先用官方 CLI 单独跑一遍看能否通过 stdio 模式发起一次工具列表查询。这一步能过滤掉大量“配置问题其实是 Server 本身有问题”的情况。确认 Server 正常后在tools.yaml里注册连接信息。一份典型的 MCP Server 注册配置长这样tools: - name: my-mcp-server transport: stdio command: npx args: - some/mcp-server env: - MCP_SERVER_TOKEN: {{env.MCP_SERVER_TOKEN}} enabled: true如果 Server 支持 HTTP 模式就改换transport: http并填上url字段。两种模式的选择标准很简单本地进程或内网服务用 stdio跨网络或需要被多个网关实例共享的用 HTTP。我在一个多实例部署场景里所有 Server 都走了 HTTP 模式因为 stdio 模式下每个网关实例都要拉起一份额外的子进程内存开销和进程管理复杂度都会上升。MCP 工具接入后建议做一次连通性测试。调用一个最简单的工具比如 Server 自带的“ping”或“echo”确认数据能通。如果连最简单的工具都失败不要急着查网关配置先用 MCP 检测工具单独测 Server两边都通过后再检查网关的注册信息。蓝湖 MCP、Playwright MCP、Burpsuite MCP 这些都是社区里比较常用的 Server。Playwright MCP 接入之后前端可以直接通过自然语言让 Agent 操作浏览器Burpsuite MCP 接入后安全测试的一些自动化操作也能纳入 Agent 流程管理。你只需要理解一点不管 MCP Server 本身多强大对网关来说它就是一个“工具提供方”接入路径完全相同。3.4 配置一个可复用的 Skill 并通过网关下发这一节我会完整走一遍 Skill 的创建、注册和调用流程以“生成接口变更影响分析”这个真实场景为例。第一步在skills/目录下创建名为api-impact-analysis的文件夹。里面放两个文件。SKILL.md的内容包括技能名称、描述、应用场景、输入参数定义、执行流程和输出格式。第二步在描述里明确写清楚“这个技能适用于接口变更前的影响范围分析输入是接口名称和变更内容描述输出是影响服务列表、调用方清单和风险等级”。Skill 若要调用工具需要在元数据里声明依赖的工具列表。例如这个分析技能依赖一个“搜索代码仓库里的接口调用点”的 MCP 工具和一个“查询服务归属关系”的本地函数工具。声明格式如下name: api-impact-analysis description: 分析接口变更的影响范围包括影响服务、调用方和风险等级 tools: - search-code-usages - query-service-owner parameters: - api_name: string - change_desc: string output_schema: type: object properties: impact_services: array risk_level: string注册完成后网关需要重建一次技能索引。我每次修改 Skill 元数据后都会调用内部接口触发索引刷新而不是重启整个服务。实测下来这个操作非常高频最好在管理界面里加一个“重新加载技能”按钮不然每次改 prompt 都要重启网关开发体验会很差。调用方式很简单。业务侧提交用户输入“分析 /order/create 接口改成异步的影响”网关自动匹配到api-impact-analysisSkill提取参数拉起模型和工具执行链最终返回结构化的影响分析报告。整个过程对业务侧就是一个普通的 AI 调用真正干活的全在网关内部完成。4. 常见问题与排查技巧实录4.1 MCP 连接反复超时先查这三处MCP 连接超时是我在接入过程中遇到的最频繁问题。排查顺序我总结为三步实测可以解决九成以上的超时问题。先看传输方式和连接地址是否匹配。用 stdio 模式时要确认command字段里的启动命令在宿主机环境能直接执行。我在一个环境里用 npx 启动 Server结果宿主机没有预装 Node.js网关自然起不来。用 HTTP 模式时重点检查url是否写到了具体端点比如http://host:port/mcp有些 Server 的基础路径不是根路径需要仔细读文档。再看网络和防火墙。容器部署时网关容器和 MCP Server 容器如果在同一台机器上别用localhost访问要用服务名或宿主机 IP。这里容易踩坑的点是docker-compose 里服务名就是 DNS 名称写localhost会指到网关容器自身。最后看 Server 的鉴权配置。不少 MCP Server 需要 Token 或 API Key除了在配置里填对之外还要确认环境变量注入正确。我遇到过 Server 本身正常但因为环境变量名写错导致鉴权失败Server 返回的数据格式异常网关侧表现就是超时。连接超时未必是网络问题鉴权失败后的无响应也会被当成超时处理这一点需要有意识地区分。4.2 工具参数 Schema 对不上让模型输出符合契约模型生成了工具调用请求但参数和工具定义的 JSON Schema 对不上这是大规模启用工具调用后一定会遇到的问题。典型表现是模型传入了一个多余的字段或者必填字段缺失网关在校验参数时报错。我的经验是两层防线并行。第一层在网关的工具执行层做严格参数校验过滤掉不合法的调用请求返回清晰的校验失败信息给模型让模型自行修正。第二层在给模型定义工具时把 Schema 写细、写准。描述字段不要用模糊表达比如operation_type这个名字就不够好改成operation_type_enum并在描述里列出可选值。另一个有效技巧是给工具参数提供示例值。模型在参考示例后生成的参数往往更规范。OpenAI 兼容接口的 tool schema 里允许添加examples字段建议每个关键字段都写上。别小看这个细节它能显著降低参数生成出错率。如果模型仍然频繁生成非法参数可以考虑换一个工具调用能力更强的模型或者在请求前对用户输入做一次“工具调用意图预解析”先由一个小模型提取参数再由主模型按照预解析的参数发起调用。这种做法适合对工具调用准确率要求极高的场景代价是增加一次模型推理的延迟和成本。4.3 密钥与鉴权信息泄露风险密钥管理是统一网关必须面对的问题。把密钥集中在网关上如果网关自身防护不到位反而变成了一个“高价值攻击目标”。所以密钥保护要分层做。第一层是存储安全。所有密钥不落盘进入内存后使用完毕即释放。持久化需求用环境变量或专用密钥管理服务。配置文件里只写占位符。第二层是访问控制。网关管理接口必须做身份认证和权限隔离建议为不同的业务线分配不同的访问令牌每个令牌只能调用被授权的模型和工具。第三层是日志脱敏。网关在打印日志时要过滤掉密钥、Token 等敏感字段。我见过一次线上事故网关 debug 日志把完整请求体打印出来了里面带着用户的鉴权信息幸好发现及时没有造成实际损失。另外在 OpenAI 兼容接口的调用链路上模型厂商往往会记录请求内容。如果你们处理的数据有保密要求除了在网关做脱敏之外还要在模型服务条款上确认数据使用范围。这不是代码问题但同样值得纳入密钥与数据安全的整体方案里考虑。4.4 技能加载失败/不生效的排查顺序Skill 加载失败看起来复杂其实大多数是文件组织的低级问题。排查顺序我建议从目录结构开始。确认SKILL.md在技能根目录下且文件名完全正确。大小写敏感的系统上skill.md和SKILL.md是不同文件网关通常会明确要求SKILL.md的规范写法。再看元数据格式。YAML 解析失败是高频问题最常见的是缩进不一致和特殊字符未转义。准备一个 YAML 校验工具写完元数据先校验再放到技能目录。其次是描述信息的索引问题网关在加载技能时会重建向量索引如果描述信息太短或太宽泛会导致调用时匹配不到表现就是“技能不生效”。这里需要保证 description 里有足够的领域关键词方便语义匹配。最后一个容易被忽略的问题是技能里声明了工具但工具未挂载。网关在技能验证阶段不会强制检查工具是否存在而是会在调用阶段才报错。如果你是新建了技能但没顺带注册依赖的工具调用时就会一直失败。牢记一个操作顺序先注册工具再创建技能。5. 关于统一网关的一点个人体会把 LLM、Tools、MCP、Skills 收进统一网关本质上不是技术堆叠而是给团队建立一套统一的 AI 能力接入规范。我个人体会最深的一点是这套规范越早建立越好。项目初期看起来“直接调用模型、直接写函数”更省事但当工具超过十个、模型超过两个之后重构成本会急剧上升。在多个项目里实践下来tsm-hub 这种网关模式并没有增加多少链路损耗反而大幅降低了资产接入和权限管控的成本。新增一个模型只是加一条配置新增一个团队只是发一把令牌新增一种能力只是挂一个 Server这种“加新东西不用动老代码”的体验在长期维护阶段尤其明显。最后给你一个建议别想着一步到位把所有能力都接进网关。从最痛的点入手比如先把多模型的切换收敛进来再加第二个工具、第三个 MCP Server最后再沉淀 Skill。网关是越用越顺手的前期铺垫得再细不如先用起来在真实调用中逐步完善契约。这也是我踩过不少坑之后才明白的道理。
