XXL-AI 是一套我们自己从零搭起来的 AI 应用开发平台核心就干三件事Agent 编排、多供应商模型接入以及以 MCP、SKILL、RAG 为核心的扩展机制底下再垫一层能扛住生产环境的工程化底座。这篇文章不写官方文档式的功能介绍而是把平台的设计取舍、关键实现和踩过的坑从头到尾拆一遍。如果你正在做 AI 应用开发或者正纠结怎么把 Agent 从 Demo 推向生产这篇应该对你有用。先说背景。我们团队从去年开始密集接各种 AI 需求一开始图省事直接套现成的 Agent 框架结果每次换模型都要动代码接一个内部工具就要写一坨胶水层知识库和 Agent 完全是两套体系各跑各的。三四个项目做完大家都在重复造轮子于是决定把一套内部统一的应用开发平台做出来后来一步步完善成了今天的 XXL-AI。1. 项目定位为什么从零写一套 AI 应用开发平台1.1 现成框架的痛市面上 Agent 框架不算少LangChain、LangGraph、AutoGen 这些都是好轮子。但实际用下来我发现它们有一个共同问题框架本身解决的大多是编排这一层而真实业务里一大半工作量恰恰在编排之外。举个例子我们之前用某个编排框架接一个内部问答机器人光是把公司里的几个 API 封装成工具就花了一周。每个工具要写描述、定参数、处理错误、做认证还要考虑模型能不能理解这个工具的用途一行胶水代码都省不了。更麻烦的是一旦要接 RAG 知识库又得自己另拉一套向量检索流程跟编排框架之间没有标准接口两边对接全靠人工约定。多供应商接入也是框架默认支持 OpenAI 格式但换成别的模型时经常要绕路流式输出的差异、工具调用参数格式的差异全都要单独适配。说白了现成框架帮你解决了流程怎么走但流程里每一步的资源从哪来、出错了怎么处理、线上怎么观察这些事还都得自己搭。1.2 平台的设计目标所以我们定平台目标时就五条后面所有架构决策都围绕这五条展开Agent 编排是核心但不做成全家桶保留手写流程的能力。多供应商要做成标配任何模型一键切换不绑架使用者。扩展机制职责清晰MCP 管工具SKILL 管方法论RAG 管知识。工程化能力前置可观测、可配置、可部署而不是上线前补课。所有模块走标准接口方便单独替换和二次开发。这个定位决定了 XXL-AI 不是又一个 Agent 框架而更像一个AI 应用开发底座。编排只是其中一层真正有价值的是把工具、知识、模型、流程、运维这些散落的能力用一种统一的、低心智负担的方式组织在一起。2. Agent 编排把单脑变成团队2.1 编排模型的选择Agent 框架与编排这个方向现在很热但实际拆开看编排模型也就那么几种顺序执行、并行分发、主从委派、图编排。我们第一版直接上了图编排思路后来发现过度设计了。大部分业务根本用不到复杂的 DAG反而是线性流程加条件分支最实用而且最容易排查问题。最后我们做了一套轻量图编排节点类型支持 LLM 调用、条件判断、MCP 工具调用、用户交互和并行分发边支持条件边和并行边。底层自己实现没有依赖 LangGraph主要原因有两个一是我们的状态管理要兼容多供应商流式输出和人工审核打断现成框架在这两个场景下反而很难扩展二是依赖越少部署和排查越简单线上出问题能直接看源码。2.2 三种核心编排模式实际项目里用得最多的就是下面三种模式我把它们都做成平台内置能力不用手写流程编排模式适用场景特点典型例子串行管道流程固定的文档处理上下文逐级传递状态清晰读文件 - 摘要 - 翻译 - 归档并行分发多角度分析、批量处理子任务独立结果汇总市场调研三路并行主从委派复杂任务拆解主管 Agent 拆解专家 Agent 执行技术方案评审这三种模式可以混合使用比如先并行分发收集结果再进入串行管道做汇总编排层都支持。2.3 一个多 Agent 编排的示例拿我们内部一直在用的技术方案评审 Agent举例。主管 Agent 收到一份方案文档后先做意图识别判断这是架构评审、安全评审还是成本评审然后并行派给三个专家 Agent架构专家、安全专家、成本专家。每个专家 Agent 有自己独立的上下文窗口和技能配置互不干扰。最后主管 Agent 汇总所有意见生成带优先级的评审结论。这里有个关键设计专家 Agent 之间不直接通信所有状态都通过编排层传递。这样做的好处是复杂度可控出问题好定位——你永远知道数据是在哪个节点被谁改的。上下文传递我们也做了结构化设计每个节点只接收它需要的字段不把无关的历史对话全塞给模型省 Token 是一方面更重要的是减少模型被无关信息干扰的概率。3. 多供应商接入一套接口跑遍所有模型3.1 适配层设计多供应商这件事说出来就一句话统一接口做起来全是细节。我们定义了一套自己的模型接口涵盖五类能力对话补全、流式输出、工具调用、向量化、重排序。每一类能力背后各对接一个适配器。OpenAI、Anthropic、DeepSeek、通义、豆包各有自己的适配器本地私有化部署的模型走 Ollama 适配器。所有配置走统一格式一个模型源的描述文件长这样provider: name: deepseek type: openai-compatible base_url: https://api.deepseek.com api_key_env: DEEPSEEK_API_KEY models: - name: deepseek-chat capabilities: [chat, tool] context_window: 64000 max_tokens: 8192这个设计的核心收益是新接一个供应商时只需要写一个适配器剩下的路由、重试、配额、监控全部走公共逻辑。我们接入一个新模型源的平均时间从最初的几天压缩到了半天以内。3.2 模型路由与降级多供应商不光是能切换更重要的是按需选模型。我们在平台里配置了路由策略支持按任务类型、成本上限、延迟优先级来选模型。比如摘要类任务默认走便宜的小模型复杂推理走旗舰模型代码生成走代码专项模型。降级策略也是在这里实现的主模型挂了自动切备用模型并告警流式输出中断时自动重连重试次数和退避策略都可配置。这块我们实测下来收益非常大线上跑了几个月因为模型源故障导致的用户可感知错误几乎降到了零。还有一个容易被忽视的点配额管理。每个模型源都有速率限制如果不做控制一个高并发任务就能把整条链路打满。我们在适配层做了令牌桶限流每个模型源独立配额超限自动排队或者降级到其他供应商。4. MCP SKILL RAG三大扩展机制怎么协同4.1 MCPAgent 的手MCP 协议Model Context Protocol这两年火起来不是没道理——它把 Agent 和外部工具之间的交互标准化了工具像 USB 设备一样即插即用。理解 MCP 不用想得太复杂本质就是一个服务把自己能干什么、参数是什么、返回什么用统一格式暴露出来Agent 通过协议去发现工具、传参数、拿结果。底层走 JSON-RPC 2.0传输层支持 stdio 和 HTTP/SSE 两种方式。我们在平台里把 MCP 作为工具接入的一等公民。生产环境优先用 HTTP 形态因为跨机器部署方便、鉴权好做。每个 MCP 服务在启动时注册自己的工具列表Agent 运行时通过 MCP 网关做工具发现不需要在代码里写死。这意味着新工具上线只要部署一个 MCP 服务并在平台里登记一下所有 Agent 立刻就能用。MCP 工具的安全性也得单独说。工具一旦暴露危险操作比如删文件、发消息、调支付后果很严重。我们给 MCP 调用做了权限分级按 Agent 角色控制可调用的工具范围默认最小权限需要哪个开哪个。4.2 SKILLAgent 的方法论工具有了但什么时候用什么工具、用完之后下一步干什么还需要一个更高层的封装这就是 SKILL。一个 SKILL 相当于一个可复用的技能插件定义了一件事从触发到完成的完整路径。它里面可以引用 MCP 工具、可以访问 RAG 知识库、可以编排多个 LLM 调用。网上常提到的skill 编码 193skill 编码 247这类编号其实就是技能仓库里的版本标识用于追踪一个技能从定义到迭代的全过程。我们定义 SKILL 用结构化的描述文件字段包括触发条件、输入输出定义、执行步骤、依赖的工具和知识库。执行步骤用一套轻量 DSL 描述支持顺序、分支、循环和人工审核节点skill: name: industry_analysis_report description: 生成行业分析报告 trigger: type: llm_classify categories: [行业分析, 市场调研] steps: - action: rag_search knowledge_base: industry_reports - action: mcp_tool tool: web_search input: {query} - action: llm_generate prompt_template: report_industry_v2 output: format: markdown这里有一个容易被忽略的细节SKILL 的触发条件不能只靠关键词匹配否则用户换个说法技能就漏触发。我们的做法是关键词加分类模型兜底让 LLM 判断用户意图最接近哪个 Skill宁可多触发再在技能内部校验也不要漏触发。4.3 RAGAgent 的记忆RAG 知识库这块平台里做成了标准化模块全流程覆盖文档解析、分块、向量化、存储、检索、重排。分块策略我们踩过不少坑。最开始按固定字符长度硬切效果很差经常把一段完整的语义拦腰截断。后来改成按文档标题结构切配合重叠区召回质量才明显上来。比如一篇技术方案文档按章 - 节的层级去切块每一块都有完整语义检索时命中率比固定长度切块高了不少。向量化模型也可以走多供应商切换存储层支持主流向量数据库。检索我们用的是混合检索向量召回加关键词召回再用重排模型把结果合并排序。网上很多 RAG 实战文章都强调重排的重要性实际跑下来确实如此——不加重排的 Top5 结果被用户吐槽过好几次答非所问。RAG 的瓶颈归根结底在查得准和更新及时两件事上。查得准靠分块和重排更新及时靠索引重建。4.4 三者的协作链路如果只把 MCP、SKILL、RAG 当三个独立功能那这套体系的价值就少了一大半。真正厉害的是它们组合起来的效果。拿我们的技术调研 Agent举例完整链路是这样的用户提一个问题 - 编排层匹配 SKILL - SKILL 执行中触发 RAG 检索把历史调研报告作为背景知识 - 然后调用 MCP 接的搜索工具补充最新信息 - 最后 LLM 综合生成结论。这个链路里RAG 管我记得什么MCP 管我能做什么SKILL 管我该怎么做。三者各司其职又通过编排层串成一条完整的工作流。这就是我们理解的Agent 六边形能力模型负责思考MCP 负责动手RAG 负责记忆SKILL 负责方法编排负责协同工程底座负责稳定。5. 工程化底座从能跑到能上线5.1 架构与模块划分平台整体分四层接入层、编排层、能力层、底座层。接入层负责 API 网关和认证编排层跑 Agent 流程和状态管理能力层放模型适配、MCP 网关、SKILL 引擎和 RAG 服务底座层是配置中心、日志、监控、任务调度。分层的核心逻辑是每一层只依赖下一层不跨层调用。这样做的直接好处是一个模块出问题不会拖垮整条链路而且模块边界清楚单人也能独立维护一块多人协作不打架。5.2 链路可观测AI 应用的可观测性和普通后端不一样你得能看到一次完整请求里调了哪个模型、传了什么提示词、模型返回了什么、触发了几次工具调用、每个工具耗时和 Token 消耗是多少。我们给每次请求生成一个 Trace ID把整条链路的所有事件都打上这个 ID。线上出问题直接按 Trace ID 查一次对话的完整时间线和计费明细。这个习惯强烈建议早点养起来不然 Agent 一复杂问题定位就是大海捞针。我们早期吃过这个亏有一次线上 Agent 行为异常排查了两天最后才发现是某个 MCP 工具返回了脏数据如果当时有完整的链路日志半小时就能定位。5.3 部署与配置部署上平台整体打包成 Docker Compose核心服务可以拆开独立扩容。模型路由、知识库配置、SKILL 列表全部走配置中心热更新改配置不需要重启服务。这个对业务方特别重要他们调提示词、调检索参数都是高频操作如果每次都要走发版流程根本没法快速迭代。安全上我们做了两件事都是被现实教做人之后才补上的。第一密钥不进代码统一走环境变量注入配置中心里只存变量引用。第二MCP 工具调用权限按 Agent 角色控制默认最小权限。这两条看着简单但很多人忽视等到线上出事故再补就晚了。6. 常见问题与排查技巧实录6.1 MCP 工具连接失败线上最常见的问题是 Agent 报tool not found或者超时。排查下来大部分原因是 MCP 服务没启动、地址配置错误或者鉴权失败。我们遇到过同一个 MCP 服务在测试环境跑得好好的上生产就连不上最后发现是生产环境防火墙没放行对应端口。建议在平台里加一道 MCP 服务健康检查在 Agent 启动时主动探测所有注册过的工具连接不通的直接告警并屏蔽避免用户遇到半截对话突然说工具不可用。6.2 SKILL 调用不命中SKILL 的触发条件写得太模糊Agent 就会把请求分到别的技能甚至不触发。我们的经验是触发条件用具体的关键词加一个分类模型兜底宁可多触发再在技能内部做前置校验也不要漏触发。漏触发的用户体感是机器人根本没听懂我要什么比多触发更伤体验。另外一个坑是 SKILL 的输入输出定义不严谨。如果输入字段描述模糊LLM 在填充参数时会凭感觉瞎传导致下游工具收到格式错误的数据。我们后来在 SKILL 定义里加了字段类型和校验规则参数错误直接报结构化错误信息而不是把错误信息原样丢给模型。6.3 RAG 检索结果差、内容陈旧检索结果差最常见的原因是分块质量差。长文档按固定长度硬切天然会把语义割裂。我们改成按标题结构分块后检索命中率提升明显。另一个坑是知识库更新后检索结果还是旧的因为索引更新不及时。我们有个内部知识库业务方总是改了文档就以为 Agent 马上能学到结果问出来的还是旧答案。现在每次知识库变更都强制重建索引并做一轮抽样验证——抽几个核心问题重新问一遍对比答案有没有更新。这个步骤不能省。6.4 流式响应中断流式输出是用户感知最明显的功能一旦断流体验就极差。我们排查过几次发现原因集中在外层网关超时设置太短还有代理层缓冲了响应导致首字延迟。解决方案是网关超时调到 60 秒以上关闭代理缓冲让内容边生成边下发。另有一个细节流式中断后要能自动重连续传不能直接抛错否则用户打个长问题大概率看到一半就断。最后说点个人体会。这套平台从第一个版本到现在我们团队自己的所有 AI 项目都跑在上面前后迭代了快一年。最大的感受是做 AI 应用开发平台真正难的不是模型调用本身而是把工具、知识、流程、可观测性这些东西用一种统一的、低心智负担的方式组织起来。MCP 解决了工具的标准化SKILL 解决了方法的沉淀复用RAG 解决了知识的供给工程化底座保证这一切在线上不添乱。如果你也想做类似的东西我的建议是先把最小可用闭环跑通一个 Agent、一个 MCP 工具、一块知识库、一份链路日志够了再往上加。别一上来就追求大而全平台是长出来的不是设计出来的。