先亮个结论如果你的Agent项目还在用“启动时把所有工具一股脑塞进System Prompt”的方式那做到后面会非常难受。我在做Agent平台的时候技能文件越堆越多function call定义膨胀到上百个再加上要接外部MCP服务端每次请求光是工具定义就要吃掉几千个token上下文窗口还没开始干正事就被占掉一截首包响应延迟也肉眼可见地涨。后来我把整个“能力接入”重构成了渐进式加载方案把Skill、Function Call、MCP三类能力按需加载、按级加载整个系统才终于变得可维护、可扩展。这篇就聊聊这套方案的设计思路、落地细节和踩坑经验适合正在做Agent开发、或者准备把智能体做成产品化的团队参考。1. 为什么要把能力从“全量加载”改成“渐进式”1.1 全量加载的三个真实痛点先说痛点否则你不会理解为什么要折腾。第一个痛点是上下文窗口被工具定义吞噬。主流模型的上下文也就几万到几十万token工具定义本身就要占不小的比例。我的项目早期有20多个skill、70多个function call、再加3个MCP服务端的工具描述拼出来的工具块超过了1.2万token也就是说模型每轮对话都要为这些“可能用不上”的能力买单。第二个痛点是延迟被拉高。工具定义越长模型在“选择工具”这一步的推理耗时就越长。实测同样的单轮问答工具定义从1.2万token降到1500token之后首包返回时间能快1到2秒这对在线交互场景来说是质的差别。第三个痛点是冲突管理困难。多个skill可能会注册同名的functionMCP工具和本地工具也可能出现行为重叠全量加载时这些冲突会同时暴露在模型面前模型经常“选择困难”甚至调用错。1.2 渐进式加载的核心思路所谓渐进式总结成一句话就是把能力从“常驻内存”变为“按需装载”从“一次注入”变为“分级注入”。我参考了操作系统的分页调度思想——不是所有代码都在内存里而是把高频、基础的代码放在常驻段把低频、大块的代码放在交换区用到再换入。映射到Agent场景就是把能力分成三个层级核心层永远注入任务层根据用户意图按需唤醒外部层通过MCP协议在真正调用时才会建立连接。这样做的收益不止是省token和降延迟更重要的是让模型“看到”的候选工具变少反而提升了工具选择的准确率——这跟“选择越多越难决策”的道理一样。2. 整体架构设计三级加载与统一注册中心2.1 三类能力域的分工差异很多同学把Skill、Function Call、MCP混为一谈这其实是三类差别很大的东西把它们放进同一个“工具”池子管理是很多项目混乱的根源。能力类型本质加载成本典型场景Skill面向Agent的行为模板/提示词流程低主要是文本代码审查、文案撰写、数据分析流程Function Call本地可执行函数的元数据描述低定义短小内部API、业务操作、状态读写MCP外部服务能力的标准化协议接入高需建连握手、资源描述数据库查询、设计稿读取、第三方SaaS在三类能力里MCP的加载成本最高。因为MCP协议不是简单给模型看一段JSON定义就完事它需要客户端和服务端建立会话、交换能力清单、初始化资源有的还要鉴权。如果每次启动都把所有MCP服务端连一遍不仅慢还可能因为某个服务挂掉导致整个Agent启动失败。所以我对MCP采用的是“懒连接会话复用”后面第3章会详细说。2.2 描述符与Manifest设计渐进式加载的前提是系统“知道”每个能力是什么、什么时候该被加载、加载它需要什么前置条件。这就需要一个统一的能力描述符把所有能力都描述成套规范的结构。我用的核心字段是这个样子的interface CapabilityDescriptor { id: string; type: skill | function | mcp; name: string; description: string; tags: string[]; loadLevel: core | on-demand | external; trigger: { keywords: string[]; weight: number; // 0~1触发权重 }; dependencies?: string[]; ttlSeconds?: number; // 命中后缓存多少秒 schema?: string; // function call 参数格式或 MCP 资源描述 }这套描述符被汇总成一个总控Manifest文件通常是JSON或YAML。系统启动时只加载Manifest索引也就是所有能力的“目录”但不会把能力的完整定义全部塞给模型。这句话很关键Manifest是给系统调度器看的不是给模型看的。模型每轮只看到被调度器“选中”的那一小撮能力的完整描述。2.3 三级加载模型我把加载分成三级分别对应不同的生命周期策略。第一级是核心常驻层。这一层只放Agent运行所绝对必需的能力比如基础的对话处理、意图识别的兜底工具、会话上下文管理。数量控制在5个以内完整定义拼起来不超过500token。这一层的目的就是“保底”确保任何一轮对话模型都有基本工具可用。第二级是按需唤醒层。这一层放的是业务技能和常用本地函数。调度器根据用户输入做意图匹配命中就把它注入当轮请求并缓存一段时间。比如用户说“帮我审查一下这段代码”调度器匹配到code_review的skill和对应的function就把它们的完整描述拼进上下文。第三级是外部扩展层。这一层对应MCP服务。它的特点是不只做描述注入还要做真实连接的管理。“按需”不是说用户一提到关键词就立刻连MCP而是模型已经决定调用这个MCP工具时调度器才发起连接获取最新的工具schema再让模型发起具体调用。这样MCP服务端的工具列表变化也不需要重新部署Agent天然支持热更新。3. 核心实现细节与关键代码3.1 注册中心实现注册中心是整个方案的“心脏”所有能力都先在这里注册再按规则被调度。我的实现不复杂本质上是三个Map加上一个索引核心代码如下class CapabilityRegistry { private descriptors new Mapstring, CapabilityDescriptor(); private byTag new Mapstring, string[](); private loadedTypes new Setcore | on-demand | external(); register(descriptor: CapabilityDescriptor) { this.descriptors.set(descriptor.id, descriptor); for (const tag of descriptor.tags) { if (!this.byTag.has(tag)) this.byTag.set(tag, []); this.byTag.get(tag)!.push(descriptor.id); } } get(id: string) { return this.descriptors.get(id); } matchByInput(input: string): CapabilityDescriptor[] { const hits: { desc: CapabilityDescriptor; score: number }[] []; for (const desc of this.descriptors.values()) { if (desc.loadLevel external) continue; // MCP 不参与意图匹配 let score 0; for (const kw of desc.trigger.keywords) { if (input.includes(kw)) score desc.trigger.weight; } if (score 0) hits.push({ desc, score }); } return hits.sort((a, b) b.score - a.score) .map(h h.desc); } }提示关键词匹配只是第一步千万不要只靠includes做过度的意图判断。我实际还叠加了一层基于embedding的相似度召回做法是把每个能力的description转成向量用户输入先做一次向量检索召回Top K再用关键词匹配结果做加权融合。这样既能抓住“同义表达”又不至于因为纯向量召回引入无关工具。3.2 意图匹配与加载决策匹配到候选能力之后要做一个“加载决策”这轮到底加载哪些、不加载哪些。我的策略是设定一个预算上限比如单轮最多注入2000token的工具定义。先把命中分数最高的能力塞进去如果在预算内就继续塞直到预算用完或者候选被排完。这里有个容易踩的坑语言模型的指令遵循能力会随着上下文里的工具数量增多而下降。即便预算允许我也不建议单轮注入超过15个工具。超过这个数模型经常出现工具名混淆、参数传错的情况。所以我的实际做法是预算上限2000token、数量上限10个两者取其先达到者。决策逻辑大致如下function decideCapabilities(userInput: string, registry: CapabilityRegistry) { const candidates registry.matchByInput(userInput); const picked: CapabilityDescriptor[] []; let tokenBudget 2000; for (const cand of candidates) { const cost estimateTokens(cand); if (cost tokenBudget || picked.length 10) break; picked.push(cand); tokenBudget - cost; } return picked; }3.3 上下文注入与生命周期管理选完能力之后怎么注入上下文也有讲究。我采用“两段式注入”全局段永远放核心层能力在System Prompt的固定位置。动态段当轮选中的按需能力拼接在用户消息之前用一个明确的标记包裹比如[Loaded Capabilities]到[/Loaded Capabilities]。生命周期管理上我给每个“按需唤醒”的能力设置了TTL缓存。第一次命中后在TTL时间内再次命中就直接复用不用重新做意图计算TTL到期或者Agent进入新一轮独立任务时则把它从动态段移除。class LoadedCapabilityCache { private cache new Mapstring, { desc: CapabilityDescriptor; expiresAt: number }(); getIfFresh(id: string) { const item this.cache.get(id); if (!item) return null; if (Date.now() item.expiresAt) { this.cache.delete(id); return null; } return item; } }3.4 MCP客户端懒连接MCP这块是最容易翻车的。早期我图省事启动Agent时候就把所有MCP服务端连好结果经常被性能差的测试服务端拖到超时。后来改成懒连接模型没有实际调用对应工具之前Agent进程不主动连MCP服务端等模型发出了某个MCP工具的调用请求调度器先去建立连接、同步工具schema、再放行调用。class McpConnectionManager { private connections new Mapstring, Promiseany(); async getConnection(serverId: string) { if (!this.connections.has(serverId)) { const connPromise this.establish(serverId); this.connections.set(serverId, connPromise); } try { return await this.connections.get(serverId)!; } catch (e) { this.connections.delete(serverId); // 失败后允许重试重建 throw e; } } }建立成功后的连接会放进连接池复用并带一个空闲超时机制比如10分钟没有调用就自动断开释放资源。这里要注意捕获连接异常后一定要从Map里删掉否则这个Promise会一直缓存后续调用会永久失败——这个坑我踩过排查了很久。4. 实操落地一套可照抄的配置与流程4.1 Manifest文件范式与其在代码里写死注册逻辑不如把能力清单外置成Manifest文件。这样新增一个skill或者接一个新的MCP服务只需要改配置不需要改代码。以下是我实际在用的YAML结构你可以直接借鉴core: - id: fallback_chat type: function description: 通用对话兜底无其他工具命中时使用 schema: {\type\:\object\,\properties\:{}} on_demand: - id: code_review type: skill description: 执行代码审查流程包含规范检查、安全问题扫描、优化建议生成 tags: [code, review, quality] trigger: keywords: [审查, review, 检查这段代码, code review] weight: 0.85 ttlSeconds: 300 - id: get_user_order type: function description: 查询用户订单状态 tags: [order, trade, user] trigger: keywords: [订单, 下单, order] weight: 0.8 ttlSeconds: 120 external: - id: docs_service type: mcp mcp_server: docs-server description: 通过MCP连接文档知识库支持检索和问答 trigger: keywords: [文档, 说明书, 手册, 检索] weight: 0.6 ttlSeconds: 600这里有个经验trigger关键词不要贪多每个能力3到6个高质量覆盖词就够宁可少而准也不要堆一堆噪音词导致互相干扰。我见过一个团队把某个tool的keywords写了40多个结果所有用户输入都命中它那次事故之后我订了个规则关键词超过8个就必须拆能力。4.2 一次典型请求的完整加载时序我把一次带渐进式加载的请求流程梳理一下方便你按图索骥。用户输入进入调度器。调度器先从核心层取出常驻能力描述估算基础token占用。调度器同时跑关键词匹配和向量召回合并出候选能力列表。按分数从高到低依次评估预算足够且数量未超限则选定这批能力。构建上下文System Prompt 全局能力段 动态能力段 用户输入。模型推理若生成function call且目标能力涉及MCP服务则走懒连接流程。连接建立后执行实际调用结果回填给模型。一轮结束后按TTL策略更新动态能力缓存长时间未用的MCP连接进入空闲回收。这个流程每步都有独立的监控点。我建议至少打四类日志候选能力命中列表、最终注入能力列表、注入token总量、MCP建连耗时。有了这四类数据优化时基本不用靠猜。4.3 预算阈值与扩展建议预算值不要拍脑袋定。我的做法是先做一次“大盘扫描”把全量能力定义拼起来统计总token数然后观察线上100次真实请求里每轮实际被调用的工具集合占用多少token。一般取P90值作为预算上限比较合理。我这边全量总token约1.2万实际P90只有1600token所以预算定到2000token是够用的。另外建议把预算做成可配置项而不是硬编码。不同模型上下文能力不一样同一个模型的版本更新也可能优化工具调用表现。预留一个配置字段后面调优时就不用改代码。5. 踩坑实录与常见问题排查5.1 高频问题速查表做这套方案的过程中我整理了一份常见问题清单基本都是真实遇到过的。问题现象根因解决办法模型一直答非所问从不调用function动态能力注入位置不对模型忽略了把动态段放到用户消息前并用[Loaded Capabilities]包裹实验后命中率提升明显MCP调用偶发超时懒连接导致首次调用的握手延迟叠加在调用里为MCP建立“预连接”机制意图命中至external层时提前发起连接多个skill同时命中模型不知道该用哪个关键词权重设计不合理命中分数拉不开差距降低通用词的权重对专属领域词给高权重比如“订单”给0.8“查询”只给0.4工具定义被人为截断预算计算按字符估算和实际token数偏差大换成按tokenizer估算或者统一按字符数×0.28粗估后预留20%余量Agent重启后MCP频繁重连连接没有复用或空闲回收阈值太小把空闲回收时间从2分钟调到10分钟并记录连接复用命中率5.2 排查思路与调试技巧这类问题排查最忌讳的就是瞎猜。我给自己定了条铁律一切以日志为准先看候选命中、再看注入列表、最后看模型实际输出。流程是先从调度器日志确认候选能力是否被正确命中如果这步就错了那就去查关键词匹配和向量召回的数据如果候选没问题再看注入预算确认最终注入给模型的能力列表是否符合预期最后看模型输出确认是模型没理解工具描述还是工具定义本身有歧义。还有一个很实用的小技巧给每个注入段打一个不可见的指纹注释例如!-- caps:20250101:3tools --配合流量回放工具可以准确定位到某一轮请求到底注入了哪些能力别小看这个细节线上定位问题的时候能省一半时间。5.3 性能优化与演进建议如果要做更大规模的Agent平台我还有几条经验值得分享。第一向量召回和关键词匹配是可以完全并行的两个结果出来了再做合并不要串行执行。第二技能的完整定义文本可以预编译成结构化缓存不要每次匹配都重新解析YAML。第三MCP的schema同步可以采用订阅模式MCP服务端发布变更通知时再全量拉取而不是每次调用都拉。这样核心链路上几乎不会出现解析和传输瓶颈。演进方向上我认为渐进式加载这套模式大概率会成为Agent框架的标准能力。目前已有一些框架支持“工具按需发现”但从描述符标准、调度策略到预连接优化还远没有统一。如果你做的是开源Agent项目在Manifest层做好协议抽象以后对接不同模型和不同MCP服务会从容很多。最后再分享一个实在的体会。渐进式加载听起来是个技术方案但它在产品层面带来的改变可能比技术层面更大用户第一次打开Agent时不再需要等十几秒加载所有服务任务型Agent的响应更快了技能市场甚至可以按用户当前页面上下文动态推送可用的skill。我在实际使用中最明显的感觉是以前“工具越多越迟钝”的魔咒被打破了能力库越丰富系统反而能通过精确调度做到更快更准。这套方案的内核并不复杂早期版本甚至只用了一个类就实现了核心调度逻辑难的是想清楚“加载什么、何时加载、加载多少、何时卸载”这几件事以及把这些规则沉淀成可观测、可配置的工程能力。你完全可以先在小规模项目里从Manifest 关键词匹配开始跑起来等量大了再逐步补向量召回和预连接这条路我已经替你验证过了。