做AI应用开发最常见的状态就是Demo写得飞起一上生产就抓瞎。今天用一个厂商的模型接口明天换个供应商又要改代码后天客户让Agent去查数据库、翻内部wiki发现模型根本没有手也没有记忆。我搭建XXL-AI这个AI应用开发平台核心就是把这些碎片化的问题收敛成一套可复用的底座——Agent编排负责把任务拆给多个智能体多供应商网关负责底层模型接入MCP、SKILL、RAG三种扩展机制分别解决工具、技能和知识的问题。这个平台解决的不是“某个模型调得好不好”而是“团队能不能稳定交付AI应用”。如果你正在做Agent架构、内部AI平台、知识库系统或者已经被供应商锁定、工具调用混乱、Prompt越写越长却越来越不可控那下面这套设计笔记应该能给你不少参考。1. 整体架构为什么把XXL-AI拆成四层1.1 想解决的核心问题我见过很多AI项目在初期跑得很快上线之后却变成灾难。原因不是模型不行而是三个核心问题没有收敛第一应用和模型供应商强耦合换一个模型等于重写业务代码第二工具调用没有统一标准每个对接方各写各的SDKAgent根本不知道该找谁第三知识、技能和业务逻辑全部堆在Prompt里项目一多就完全失控。所以我在设计XXL-AI时没有急着写Agent逻辑而是先把平台拆成接入层、编排层、扩展层和工程化底座。接入层统一管理多供应商模型编排层处理Agent任务的分发与协作扩展层把MCP、SKILL、RAG各自的能力标准化底座则负责观测、安全、配置和发布。这样的分层很直观每层只解决一类问题替换任何一层都不影响其他部分。很多人听到“平台”就觉得很重其实恰恰相反。拆层之后单个Agent应用可以只依赖其中一层比如只接多供应商网关跑一个问答机器人不需要硬上完整编排。平台的价值是“需要时能支撑不需要时不拖累”而不是一上来就给你一个庞然大物。1.2 四层架构与选型逻辑四层架构的核心逻辑如下接入与网关层统一多供应商模型API负责认证、计费、限流、路由和降级。这一层让上层代码永远只面对一套接口。Agent编排层负责任务规划、多Agent调度、状态共享、工具注册和回合控制。我把编排层当成“大脑的肢体指挥中心”。能力扩展层MCP解决外部工具接入SKILL解决内部能力沉淀RAG解决私域知识检索。三者互补不互相替代。工程化底座包括可观测性、配置中心、安全策略、CI/CD与回滚机制是整个平台能不能长期维护的关键。为什么把MCP、SKILL、RAG并列为三种扩展机制因为它们处理的问题层次完全不同。MCP是“手”让模型够到外部工具SKILL是“招式”把一套成熟的做事方法固化下来RAG是“记忆”让模型能读取不属于训练数据的知识。很多人会纠结到底该用MCP还是RAG实际它们根本不是竞争关系你要查内部文档用RAG你要调用外部系统用MCP你要把整套处理流程沉淀下来用SKILL。选型上还有一条重要经验能标准化就标准化不能标准化的才做定制。MCP协议有社区标准就用MCPSKILL的触发词和步骤结构可以自定义RAG的链路则按数据情况灵活组合。平台的成熟度不取决于它支持多少奇技淫巧而取决于它能不能把日常高频动作变成固化能力。2. 多供应商接入模型网关的抽象与降级2.1 统一接口层的设计要点多供应商接入的第一件事不是写代码而是定义统一接口。不同模型厂商的API差异非常大有的支持流式输出有的参数名不同有的错误码含义完全不一样token计算方式也不同。如果不抽象业务代码里会散落一大堆厂商SDK的调用换供应商等于重构。我在XXL-AI里做了一个轻量LLM网关用Adapter模式包装每个供应商。网关向上暴露统一的接口大概长这样providers: - name: vendorA model: model-a-large adapter: openai-compatible api_key_env: VENDOR_A_KEY base_url: https://api.vendor-a.example.com - name: vendorB model: model-b-chat adapter: vendor-b-sdk api_key_env: VENDOR_B_KEY base_url: https://api.vendor-b.example.com业务代码永远只调用网关不感知底层是A还是B。切换模型时只需要在配置中心改一个路由规则。这里有一个容易忽略的细节tokenizer不一致。A模型的“上下文窗口”和B模型的窗口即使数字相同实际能容纳的字符数也不同。切换模型后要重新验证长文本截断行为不能只看参数声明。还建议做参数过滤。不同供应商支持的采样参数不一样vendorB不支持某个供应商的reasoning_effort或response_format网关会在转发前把不兼容参数剥离而不是让业务报错。这个动作看起来不复杂但在实际切换模型时能省很多排查时间。2.2 路由、降级与成本平衡多供应商接入不只是“能调用”还得“调得聪明”。我把路由策略分成了三档。第一档是高智力任务比如复杂推理、代码审查路由到最强的大模型第二档是日常对话、文本润色用小模型就够第三档是批量处理、信息抽取直接用便宜的本地模型牺牲一点效果换成本。降级逻辑要放在网关里而不是业务代码里。供应商A超时或返回5xx错误时网关自动切换到供应商B的同能力模型连续失败还会进入熔断状态避免疯狂重试把账单打爆。实测下来这样能保证Agent长时间运行时的稳定性不会因为一次供应商波动导致整个任务失败。成本管理上我按任务类型和项目维度分别计价。每个请求会记录输入输出token数支持配额和预算限制。比如“数据分析”这个业务线每天最多消费100万token超过自动降级到低配模型或暂停非核心任务。不这么做等月底账单出来再后悔就晚了。2.3 多供应商切换的实操记录上线初期我们做了一次真实切换对比同一个测试集从供应商A切到供应商B只改了一个配置项。效果差异比预期大有些简单分类任务B表现更好复杂推理任务A明显更稳。这件事给我两个教训第一不能迷信某一家的宣传数据要用自己的评估集跑第二不同任务类型可能需要不同的默认供应商路由规则必须支持按任务维度定制。另一个坑是流式与全量模式的差异。有的供应商在流式模式下返回内容格式不稳定有的在非流式下容易出现超时。多供应商网关测试时一定要把两种模式都跑一遍不要只测全量返回。我还遇到过一次奇怪问题切换供应商后Agent突然开始输出大段英文。排查下来是对方默认的system prompt风格与国内业务场景不匹配最终在网关层强制加了一套统一的系统提示词前缀才解决。3. Agent编排从单Agent到多Agent协作3.1 编排模型与场景示例单Agent解决复杂任务时很容易“一手包办”结果就是上下文爆炸、工具调用顺序混乱、中间结果丢失。XXL-AI里的做法是引入多Agent编排把大任务拆成小任务每个Agent只负责自己擅长的一环。常见编排模式有这么几种链式编排Agent A的输出作为Agent B的输入适合有先后依赖的流程并行编排多个Agent同时处理互不依赖的子任务路由编排主控Agent按意图把请求分发给不同子Agent竞合模式多个Agent产出多份答案再由评审Agent选择最佳方案。以数据分析场景为例Planner Agent先拆解问题生成分析计划Retriever Agent去RAG知识库和内部wiki检索业务背景SQL Agent连接数据库取数Reviewer Agent检查SQL结果和结论是否匹配。这就是一个典型的多Agent编排示例。如果让一个Agent全干大概率会在中途混淆“查文档”和“查数据库”的上下文。拆开后每个Agent的上下文都保持干净出问题也能定位到具体环节。3.2 编排引擎的关键机制编排引擎不是简单“调几个Agent”核心机制有四块。第一是上下文总线所有Agent共享一套可访问的状态但只暴露当前任务需要的最小字段避免互相污染。第二是调度器维护任务队列决定哪个Agent先跑、哪个可以并行、哪个要等依赖。第三是工具注册表Agent能调用什么工具由注册表控制不直接拼字面量。第四是回合控制器限制最大迭代次数防止Agent无休止地互相“踢皮球”。上下文管理是编排中最容易翻车的地方。子Agent处理完任务后我会把它的冗长中间输出做一个摘要只把摘要放回上下文总线。就好比开多人会议秘书只需要把每个人的结论记录下来而不是把每个人说的话全部转述一遍。没有这个机制多Agent跑几轮后上下文就会溢出模型开始遗忘最开始的目标。调度器还要支持中断和恢复。任务执行到一半上游数据源超时了不能整个任务放弃要能保存当前进度等依赖恢复后继续。这块和传统分布式任务编排很像区别只是把“节点”换成了“Agent”但状态管理、重试、超时的思路完全可以复用。3.3 多Agent编排的常见坑踩过的坑里排第一的是死循环。两个Agent互相认为“下一步该你处理”如果没有最大迭代次数和环检测就会无限调用。我现在给每个编排任务默认加50轮硬上限超过就触发告警并进入人工接管流程费用和调试成本都下降了一大截。排第二的是上下文膨胀。子Agent输出万字报告主控Agent全部塞进记忆下一轮推理质量急剧下降。后来我强制每个Agent返回结构化结果比如JSON只包含核心字段长文本单独存外部存储上下文里只放引用ID。排第三的是计划与执行脱节。Planner拆出的步骤可能是错的但后续Agent会机械地执行。我的经验是每一个执行Agent在被调用时都允许“质疑计划合理性”如果发现前置条件不对可以打回给Planner重新规划而不是硬着头皮跑出一个错误答案。4. MCP扩展把工具接入变成标准动作4.1 MCP到底是什么协议经常有人问MCP到底是软件协议还是硬件协议这个概念问得很关键。MCP全称Model Context Protocol是一个应用层的软件协议作用是在模型、Agent与外部工具之间建立标准化的接口约定。它不关心物理设备如何握手也不属于硬件通信协议它约定的核心是工具怎么描述自己、客户端怎么发现工具、工具调用请求和结果怎么编码。类比理解MCP就像模型世界的USB-C接口。工具方实现一个MCP Server把自己的能力按统一格式暴露出来平台或客户端作为MCP Client通过一套标准动作去发现和调用这些能力。工具方不用为一款模型写一套SDK模型侧也不用为几十个工具各写一遍对接代码。只要大家都说MCP语言就能即插即用。MCP的传输层主要有两种本地进程通过stdio跑远程服务通过HTTP流式或SSE跑。我这里建议内部平台优先用HTTP流式便于统一鉴权、日志和负载均衡本地开发工具可以走stdio启动快、配置相对简单。协议层面本质是基于JSON-RPC的请求响应所以任何语言都可以集成。4.2 接入一个MCP Server的完整流程在XXL-AI里接入一个MCP Server是标准动作流程不长但每一步都有讲究。第一步部署或获取MCP Server地址。自己写的服务可以监听本地端口第三方工具通常提供一个远程Endpoint。第二步在平台的“工具注册中心”登记这个Server让它执行一次tools/list发现工具清单自动导入每个工具的名称、描述和输入参数Schema。第三步配置鉴权信息比如API Token、OAuth凭据。第四步把工具授权给指定Agent并设置危险操作提醒。第五步做三组测试直接调用工具、通过Agent调用工具、并发触发工具确认结果能正确解析。一个MCP工具调用在协议层的本质就是一次JSON-RPC请求大致长这样{ jsonrpc: 2.0, method: tools/call, params: { name: get_weather, arguments: { city: beijing } } }工具返回的结构会影响Agent能否正确使用结果。如果工具只返回“调用成功”而没有具体数据模型就不知道下一步该怎么办。我的经验是工具返回值必须尽量结构化关键字段明确最好附带一句话的“结果摘要”让模型快速判断该做什么。4.3 生态联动编辑器、浏览器、设计工具MCP生态这两年的发展速度比想象中快。编辑器类工具已经普遍支持MCP开发者可以在编码助手里挂文件系统、Git、浏览器调试等工具低代码平台上也能配置MCP连接器让不具备编程能力的用户接入外部系统设计协作工具可以通过MCP授权让Agent读取画板、导出切图、生成标注甚至游戏引擎也在探索MCP通过协议控制编辑器做批量场景搭建和自动化测试。交互类工具接入时安全控制要更严格。比如通过浏览器MCP让Agent操作网页如果只是读取页面信息风险可控如果涉及点击按钮、填写表单、批量下载必须加审批流。我见过一个自动化采集任务因为没加白名单Agent把不该下载的文件全抓下来了。给Agent开放工具权限时永远遵循最小权限原则宁可多花两分钟配置不要事后花两天善后。设计工具这类外部系统的授权通常走OAuth容易出现“配置了MCP但工具列表为空”的情况。排查顺序一般是先确认MCP Server到底有没有启动再确认授权回调地址是否填写正确最后看客户端是否重新加载了工具列表。很多“工具不存在”的问题其实是客户端没重启不是服务端的问题。4.4 MCP接入常见问题速查问题常见原因排查与解决工具列表为空MCP客户端未重新拉起或服务端tools/list失败重启客户端查看MCP Server日志先手工调用tools/list验证授权失败OAuth回调地址错误、Token过期核对回调地址重新走授权流程检查Token有效期调用超时工具端处理时间过长或网络不通先直接调用工具接口确认耗时再调整客户端超时时间工具返回格式模型看不懂很多MCP工具只返回“ok”或HTML在平台层增加结果摘要器对非结构化返回做抽取后再交给模型工具名冲突多个MCP Server定义了同名工具工具注册时统一加命名空间前辍如git_get_status、wiki_get_page5. SKILL扩展让能力可复用、可版本化5.1 SKILL为什么不是Prompt模板Prompt模板的问题是“只有话术没有流程”。你告诉模型“写一份周报”它可能写得不错但不会去查日志、不会调日历、不会做数据校验。SKILL是把一整条做事流程打包触发条件、输入参数、执行步骤、工具调用、输出格式、质量校验都写在里面。模型执行SKILL不是“即兴发挥”而是按操作手册逐步操作。举一个比喻Prompt模板是菜谱SKILL是安装了菜谱、食材清单、火候控制和装盘要求的厨师工作站。同样是做西红柿炒蛋菜谱只告诉你放多少盐工作站会告诉你先备菜再热锅炒完还要尝一下确认咸淡。SKILL和Agent的关系也很直接Agent是执行主体SKILL是执行方案。一个Agent可以按需加载不同的SKILL比如“问答Agent”在不同场景下加载“客服话术SKILL”或“技术文档SKILL”。把“知识”和“执行方式”分离之后团队可以并行维护各自的SKILL不需要每次都改Agent的主逻辑。5.2 SKILL的结构与编码管理我在XXL-AI里给SKILL定义了一套最小结构每个技能都由四部分组成元信息、触发条件、执行步骤、输出规范。元信息包括技能ID、名称、版本号、作者、依赖的工具和RAG集合。触发条件可以是关键词、意图分类结果也可以是另一个Agent的显式调用。执行步骤是核心可以是固定序列也可以允许模型在约束范围内微调。输出规范则对格式、语气、长度做硬约束。下面是一个很简化的SKILL配置示例id: SKILL-DEMO-001 name: weekly-report-writer version: 1.3.0 trigger: type: intent keywords: [周报, weekly report] steps: - retrieve: daily_log - invoke_mcp: calendar_tool - compose: report_draft - review: style_check output: format: markdown style: concise关于“skill编码247、skill编码193”这类说法我猜你可能是看到了技能编码、技能编号管理相关的内容。在工程化平台里技能ID和版本号真的很重要。早期我们靠文件夹名字管理SKILL结果出现“final_v3_最终版”这种鬼东西。后来统一了编码规则类似SKILL-业务域-序号同一技能用语义化版本号管理修改必须走Git提交和评审发布之后不能原地改内容只能发新版本。做过一次线上事故回滚之后你会发现这套流程不是负担是救命稻草。5.3 几个能直接上手的SKILL案例第一个是AI备课SKILL。它接收教材章节文本输出教学目标、知识清单、课堂互动问题和课后练习。执行时先调用RAG检索校本资料再用“生成教案草稿→按学生年级调整难度→检查是否包含分层教学”三个步骤收尾。这比直接让模型写教案稳定得多因为步骤里的“调整难度”不是靠模型心情而是有明确的年级参数表。第二个是“去AI味”改写SKILL。很多人抱怨AI输出一股机器味语气空洞、关联词泛滥、总结陈词太多。这个SKILL的做法是先让模型识别文本中的高频AI句式比如“首先/其次/最后”“总而言之”“随着...的发展”再改写为短句和口语词最后把抽象总结替换成具体例子。实测下来改写后的文案自然很多关键不是让模型“写得像人”而是给它一套明确的改稿规则。第三个是周报生成SKILL。它把RAG检索日志、MCP调用日历、输出模板整合在一起先取本周工作条目再按项目和成果分类最后压缩成“业务结果数据佐证下周计划”的结构。社区里同类的SuperPower Skill和WorkBuddy Skill思路也类似关键都是把工作流固化而不是只写一句“帮我写周报”。还有像测试用例生成SKILL、分镜动作描述SKILL等本质上都一样输入某个领域资料按固定步骤拆解输出符合专业格式的结果再自动检查一遍。SKILL最能发挥作用的地方是把那些“团队已经通过无数次Prompt调教出来的好方法”沉淀下来变成每个人都能直接调用的资产。6. RAG扩展知识库的搭建与突破瓶颈6.1 RAG知识库能否存储图片很多人问“RAG知识库能存储图片吗”这个问题要看应用场景。传统RAG主要面向文本文档切块、文本向量化、检索文本块。如果只是想通过关键词搜索图片可以把图片的文件名、OCR文本和人工描述作为索引存入知识库检索到文本时返回关联图片路径。这种方案实现简单很多内部图片管理系统都够用。如果要做真正的语义检索比如“找一张去年年会现场很热闹的照片”那就需要多模态Embedding。先用多模态模型把图片编码成向量再把查询文本编码成向量在同一个向量空间里做相似度计算。支持以文搜图甚至以图搜图。动手前还要想清楚图片是否涉及人物肖像和隐私本地知识库存储大量图片需要占用多少磁盘和GPU显存如果只是轻量场景不建议一开始就上多模态先把OCR文本和元数据检索做好性价比要高很多。6.2 本地零基础搭建RAG的路线本地搭建RAG没有想象中那么难零基础路线可以分成五步。第一步是文档解析与清洗用本地工具把PDF、Word、Markdown统一转成纯文本或Markdown常见的文本拆解工具有markitdown、unstructured等。关键要把页眉页脚、导航栏、重复模板文字清理掉不然这些噪音会在切块时混进上下文。第二步是切块按照章节或固定长度切推荐chunk size在256到512字符之间相邻块之间加128字符重叠。第三步是向量化用本地Embedding模型生成向量比如小巧好用的bge-m3系列。第四步是检索把用户问题向量化后在向量库里做余弦相似度搜索返回topK块。第五步是生成将检索到的文本块拼接到Prompt里让模型只基于这些材料回答。这样一套链路在个人电脑上完全跑得动重点不是GPU多强而是切块和清洗质量。如果想要快一点可以借助Ollama加载本地大模型和Embedding模型再配一个轻量向量库如Chroma或Qdrant。Java技术栈还可以看langchain4j的Easy RAG模块它能帮你省一步手动搭链路的活。本地RAG的好处是数据不出内网适合公司内部wiki、产品文档、法律合规资料这类敏感内容也适合做零成本实验。6.3 RAG升级从文本检索到结构化知识RAG的瓶颈很多人遇到过文档切块破坏了语义检索结果不相关甚至把互相矛盾的内容一起给了模型。问题大多出在“切分”和“召回”两个环节而不是模型本身。我推荐的升级路径是先做段落级检索再加Rerank。把文档按语义完整段落切分检索时先粗召回一批段落再用交叉编码器Rerank模型精排效果提升非常明显。简单说就是先海选再决赛模型质量一样也能让答案靠谱很多。再进一步是给知识库加结构。比如Ontology RAG或GraphRAG思路先把文档中的实体和关系抽取成知识图谱再根据用户问题从图谱里检索关联实体和路径把图结构信息拼进上下文。这种方法在回答“A和B是什么关系”“发生了哪些连锁事件”这类问题时比纯文本检索强得多。也不要迷信“RAG能解决一切事实问题”。知识库更新频率、文档冲突、查询改写都会影响效果。我的习惯是每次跑RAG都记录检索命中了哪些文档让用户或运营能看到答案的“证据来源”。知识库不是越大越好而是越准确越好一个有来源可追溯的精简知识库远比一个什么都不精的“大杂烩”有价值。7. 工程化底座可观测、可配置、可安全交付7.1 Agent链路追踪与质量评估没有可观测性的Agent平台就是黑盒。我要求XXL-AI里每一次Agent运行都生成一个trace_id记录模型调用、工具调用、MCP请求、RAG检索命中和Token消耗。排查问题时拿着trace_id可以精确看到是哪一步返回了错误、哪一步的上下文丢了、哪个工具执行超时。这和后端服务的链路追踪思路一样只是多记录了一层模型输入输出和token成本。质量评估也不能靠感觉。我会用离线评估集定期跑回归把典型问题、典型文档、典型问答整理成测试集每次改Skill或换模型后自动跑一遍用LLM-as-judge打质量分。线上则监控任务完成率、平均轮数、工具调用成功率。没有这些指标你根本不知道一个“好像变聪明了”的改动实际上让30%任务失败了。7.2 配置、安全与发布供应商密钥、模型参数、SKILL版本、工具白名单这些配置如果散落在代码里迟早出事。我把它们统一收敛到配置中心按项目和环境隔离。发布流程上SKILL和工作流都先灰度到小流量观察质量分和错误率再全量并保留一键回滚能力。有一次我改了某个SKILL的输出结构导致下游解析程序崩了靠的就是配置版本回滚在十分钟内恢复。安全层面有三个必做项一是Prompt注入防护用户输入里可能带了恶意指令比如“忽略之前所有要求”平台层要加检测和过滤二是敏感数据脱敏日志和上下文里不能出现身份证、手机号等明文三是多租户数据隔离不同业务线的RAG知识库和工具权限必须彻底分开。8. 常见问题与排查记录8.1 高频问题速查表问题常见原因排查与解决Agent提示找不到MCP工具客户端未重新加载工具列表重启客户端用tools/list验证工具是否存在MCP授权成功但调用403Token过期或权限范围不匹配重新授权检查OAuth scope确认工具白名单配置多供应商切换后回答质量下降不同模型指令遵循能力差异跑一遍离线回归集按任务类型调整路由规则RAG检索结果不相关切块过大、查询改写缺失、文档有噪声减小chunk size加Rerank清洗文档后再灌库Agent任务跑了一半中断外部依赖超时或执行被熔断查看trace_id定位具体环节增加重试和断点恢复上下文爆满多Agent中间结果全部塞入主上下文加摘要器只保留结构化结果长文本放外部存储SKILL版本混乱没有统一ID和版本管理按编码规则重建Skill清单用语义化版本管理并加评审8.2 我踩过的三个比较深的坑第一个坑是“工具返回非结构化数据”。早期接入一个MCP工具返回值是一个HTML页面模型根本解析不了整个环节逻辑直接垮掉。后来我在平台层加了结果摘要器自动把HTML转成核心内容再交给模型这个问题才解决。凡是接工具一定要先想清楚“模型能不能看懂这个返回结果”。第二个坑是“只测成功路径”。多Agent编排常常在失败路径上出问题子Agent报错后主控Agent不知道是重试还是换方案直接傻掉。我现在每个任务都要写清楚“失败后怎么降级”比如“SQL工具失败后再查一次缓存仍然失败就明确告诉用户查不了”而不是让模型临场乱发挥。第三个坑是“知识库更新了但检索还在用旧数据”。我遇到过用户反馈答案过时查了很久才发现RAG索引没有跟着文档库更新。现在文档库更新事件会触发索引重建任务并在重建完成前切换流量避免新旧混合。知识库一定不能只“灌进去”就不管更新和失效机制必须第一时间设计好。根据我个人和团队折腾XXL-AI的经验最值得先做的不是Agent而是底座。先把多供应商网关、日志链路、工具注册表搭起来可能只占一天开发时间后面调试和扩展时能省下一周都不止。至于MCP、SKILL、RAG千万不要三选一它们是不同层次问题的不同答案。工具标准化靠MCP能力沉淀靠SKILL知识接入靠RAG三者都在位时Agent才真正接近一个可以交付的产品。这个平台后续我打算往可视化编排和多人协同方向继续演进让产品同学也能自己搭Agent流程。上面这些记录希望对正在做AI应用平台的你有一点帮助。