企业官网建设流程全解析

"XXL-AI"这名字最近在我关注的开源社区里出现频率挺高。不少朋友私下问我：这到底是个什么项目？适合谁用？里面提到的Agent编排、MCP、SKILL、RAG这些词，单个抽出来都熟悉，但组合在一起形成一个平台底座，能解决什么问题？我用了一段时间，跑了几个真实场景，包括多Agent协作、知识库问答、工具调用，还把它接进了一个模拟的企业内部工单系统里。这篇文章不重复官网文档，只讲我在选型、落地和排错过程中的个人经验和判断。

先说说这个平台的定位：XXL-AI是一个偏工程化的AI应用开发平台，核心卖点有三个。第一是Agent编排，支持把多个不同职责的Agent组织成一个有逻辑的协作流程；第二是多供应商接入，不绑定某一家大模型厂商，OpenAI、Anthropic以及国产几家主流接口可以同时挂载，按路由规则灵活切换；第三是扩展机制，把MCP（模型上下文协议）、SKILL（技能包）、RAG（检索增强生成）三件事统一纳入了平台底座，简化了配置和运维成本。适合谁用？我的结论是：适合已经过了“玩Prompt”阶段、正在认真做AI应用工程化的团队，也适合想从零搭一套内部Agent中台、又不想重复造轮子的开发者。

下面进入正题，我把完整的选型思路、架构拆解、实操过程和踩坑记录整理出来，希望能帮你少走弯路。

1. 整体设计与思路拆解：为什么说XXL-AI解决了真问题

1.1 先看痛点：AI应用开发到底难在哪里

过去一年，我见过不少团队做AI应用，路线大同小异：先用LangChain或直接调用大模型API写一个原型，验证效果不错，然后进入工程化阶段。这时候问题就浮出来了。

第一个痛点是模型绑定。代码里写死了一个模型供应商的SDK，等要切换或者做灾备时，改造成本极高。有些团队甚至因为某个供应商限流，整个业务停滞半天。第二个痛点是Agent之间的关系混乱。一个稍复杂的任务会被拆成多个子任务，如果每个子任务都起一个独立的Agent进程，彼此之间没有统一编排，状态不一致，日志满天飞，出问题根本不知道从哪查起。第三个痛点是工具和知识库没有统一标准。有的用直接函数调用，有的用OpenAI Function Calling，有的自研插件协议，五花八门，复用性极差。

XXL-AI的设计思路，其实是在回答一个问题：如果把AI应用的“运行时环境”抽象出来，做成一个像应用服务器一样的东西，是不是就能解决上述混乱？它在最底层提供了一套统一的执行引擎，往上封装了Agent编排、模型路由、工具扩展和知识检索四件事。这样业务团队只需要关心Agent的逻辑本身，而不需要关心底层是哪个模型、通过什么协议调用工具。

1.2 核心架构分层：编排层、模型层、扩展层、底座

我理解XXL-AI的架构逻辑大致分四层，这种分层和Spring MVC那套分层的思维很像，核心目标都是“解耦”与“可替换”。

• 编排层：负责定义Agent之间的执行顺序、分支条件和数据传递方式。支持顺序执行、并行执行、条件跳转和人工审批中断。
• 模型层：统一封装各家大模型API，抽象出Chat、Embedding、Function Calling等能力接口。开发者在上层不需要感知模型厂商差异。
• 扩展层：MCP用于接入外部工具和数据源，SKILL用于沉淀可复用的技能包，RAG用于外挂知识库检索。
• 工程底座：包含链路追踪、配置管理、权限控制、任务队列、审计日志等企业级基础设施组件。

这套架构的最大价值在于“替换成本”被降到了很低。举个例子：如果今天你的场景里用的是A模型的128K上下文版本，明天想换成B模型的同规格版本，只需在控制台修改模型路由配置，不需要改动任何Agent逻辑代码。这在真实业务中非常实用，因为大模型市场变化太快，把宝押在一家厂商身上风险实在太高。

1.3 非侵入式扩展：MCP、SKILL、RAG为什么能和谐共存

不少人问：MCP、SKILL、RAG三者的边界在哪里？会不会功能重叠？我的理解是这样的。

MCP本质上是一个“工具协议”，解决的是Agent“能做什么”的问题。比如查询数据库、调用外部API、读取文件系统，这些都算工具。MCP把工具统一成标准协议，Agent不需要针对每个工具单独适配。SKILL是“模式与技能的封装”，解决的是“怎么做才做得好”的问题。它可以把一套优秀的提示词模板、工具调用顺序、参数校验逻辑打包成一个可复用的技能包。RAG解决的是“不知道的信息从哪里来”的问题，核心在知识库的索引与检索。

三者侧重点完全不同，所以可以无缝共存。用一个商业分析Agent举例：RAG负责从企业知识库里检索内部数据和方法论，MCP负责调用财务系统API获取订单数据，SKILL则封装了“如何撰写一份高质量商业分析报告”的完整方法论。三者组合，缺一不可。

提示：如果团队刚接触这些概念，建议从MCP入门。它的标准化程度最高，官方工具如filesystem、git、database等可以直接用，容易获得正反馈。

2. Agent编排核心原理解析：从单Agent到多Agent协作

2.1 编排模型：流程式编排与智能编排的抉择

把多个Agent组合起来干活，现在主流的方式有两种。一种是流程式编排，开发者用代码或可视化配置定义好Agent的执行步骤：A先做，输出传给B，B做完传给C。另一种是智能编排，由一个“调度Agent”根据任务目标动态选择合适的Agent并规划执行顺序。

我在实际使用中感受是：生产环境更适合流程式编排，因为逻辑可预测、可维护、可观测。比如“客户咨询工单分类”这个场景，你可以明确流程：先由意图识别Agent判断客户诉求，再由信息检索Agent去知识库找答案，最后由应答生成Agent组织回复语言。每一步都有明确输入输出，出了问题也容易定位。智能编排适合快速原型验证，但在复杂业务中，调度Agent自身的判断可能出错，导致执行路径不可控，一旦出错排查成本很高。

XXL-AI的编排引擎对两者都支持，但它的核心设计更偏向流程式，提供的Workflow DSL可以用JSON或YAML定义状态机。这样的设计思路我认为是务实的。

我分享一下二分类的最简单定义示例：

workflow: id: support_triage start: intent_classifier steps: intent_classifier: agent: intent_agent output: intent next: order_query: order_agent complaint: complaint_agent general: qa_agent order_agent: agent: order_info_agent next: responder complaint_agent: agent: complaint_agent next: responder qa_agent: agent: general_qa_agent next: responder responder: agent: reply_agent end: true

这段配置的意思是：第一个Agent先判断意图，根据结果路由到不同的后续Agent，最终统一交给回复生成Agent汇总。整个执行过程，中间任何一步出错都能通过Trace日志回溯。

2.2 多Agent协作模式：主从式、协作式与流水线式

在XXL-AI里，多Agent协作有几种典型模式。

主从式最常用来做“任务分解”，适合复杂目标拆解。一个“项目经理Agent”接到大目标，自行拆解成子任务交给“执行Agent”，并接收执行结果汇总判断是否继续或调整。协作式适合并行处理。比如一份文档要做多语言翻译和摘要，可以同时启动多个Agent处理不同章节，最后合并。流水线式适合流程清晰固定的业务。比如自动化测试报告生成：先代码扫描Agent发现问题，再缺陷分析Agent分类定级，最后报告Agent输出格式化结果。

我测试过并行度对性能的影响。在相同模型规格下，流水线模式的端到端延迟取决于链路总时长；协作模式因为并行执行，总耗时接近最慢的那个子任务。XXL-AI的任务调度器支持按DAG（有向无环图）执行，意味着你可以定义某个步骤依赖哪些上游步骤的结果，执行引擎会自动等待依赖满足后再启动下游步骤，而不是机械地按顺序等待。

DAG编排在处理“某一步需要等待多个数据源”的场景尤其高效。比如生成月度经营分析报告，需要等待销售数据、财务数据和市场数据三个Agent都完成后，汇总Agent才能开始工作。在真实场景里，数据准备往往是并发进行的，如果按顺序等，时间成本成倍增加。

2.3 状态管理与人工审批：生产级Agent的关键能力

Agent编排里最容易被忽略的是“状态”问题。一个Agent运行过程中需要调用工具获取中间结果，如果Agent工作在一个无状态环境里，工具返回的数据放哪里？Agent之间的上下文如何共享？整个工作流的中间状态一旦出现网络抖动，能否恢复到原先的进度，还是必须从头再来？

XXL-AI引入了一种“工作流上下文”的机制，相当于一个运行时数据总线。工作流每一步的输出都会写入上下文，任何需要该数据的步骤都可以从中读取。上下文支持结构化存储，不仅保存文本，还能保存JSON结构、文件引用和向量检索结果。

人工审批环节在偏严肃的场景（例如生产变更执行、工单派发）中不可省。平台提供了审批节点能力：工作流运行到审批节点时自动暂停，等待用户在控制台确认后推送通知并放行继续。如果没有这类能力，直接让Agent全自动执行高风险操作，出了问题没有人工兜底的通道。

3. 三大扩展机制实战拆解：MCP、SKILL、RAG逐个说透

3.1 MCP实操：把外部工具接进Agent的标准化姿势

MCP的全称是Model Context Protocol，可以把它理解为“AI应用领域的USB接口”。以前每个工具都需要开发对应的适配器，现在只要是支持MCP的工具，都用同一种协议对接，即插即用。

XXL-AI内置了MCP客户端，支持HTTP和Streamable HTTP两种传输方式。实操时我发现HTTP方式最省事，因为它不需要本地子进程管理，更适合部署在容器环境。

配置一个GitHub仓库管理工具作为MCP Server，最简单的配置格式如下：

mcp_servers: github_repo: transport: http url: http://mcp-gateway.mycompany.com/github auth: type: token token_env: GITHUB_TOKEN

配置完成后，Agent在对话中提到“查看本仓库Issue列表”时，平台会自动发现并调用这个MCP工具。这里有一个细节：不同的模型对工具描述的理解能力有差异。有些模型在多个工具之间容易混淆，所以工具描述和参数说明要写清楚，建议在工具描述里加入典型的使用场景示例。

很多团队遇到“Agent找不到MCP工具”的问题，我的经验是先检查MCP Server的连通性。可以用浏览器直接访问HTTP接口的根地址，如果能返回协议握手信息，说明服务正常，再去排查工具的发现与加载逻辑。

3.2 SKILL实战：把最佳实践沉淀成可复用技能包

MCP解决“能做什么”，SKILL解决“怎么做”。一个SKILL包通常包含：技能元信息、提示词模板、可选择的工具列表、校验规则和执行逻辑代码。

我做客服Agent时沉淀了一个“工单分类SKILL”，它将分类逻辑、字段校验、相似案例推荐全部封装在一起。其他Agent如果也做工单处理，直接引用这个SKILL即可，不必重复开发。

SKILL的调用逻辑可以是静态的，也可以是动态的。静态调用是指Agent被配置为固定使用某个SKILL；动态调用是指由Agent从SKILL库中根据任务描述自行选择合适的SKILL。在实际运行中，动态调用对模型的任务识别能力要求更高。如果模型版本较旧，建议先手工绑定，等模型升级后再开放动态加载。

SKILL与MCP的配合是很有意思的实验场景。以“外部数据源调研”SKILL为例，流程如下：先调用搜索MCP获取候选资料，再调用浏览器MCP打开相关链接，然后由总结模块提炼要点，最后将结果写入知识库。整个流程全部由Skill脚本控制，每一步的工具调用都提前声明好，运行时稳定可控。

3.3 RAG实战：从搭知识库到检索调优的关键细节

RAG这部分，我要先澄清一个常见误区：不是所有问题都需要RAG。如果你的Agent不需要回答企业内网文档里的问题，那RAG纯属增加复杂度。只有需要基于特定知识产出答案，才需要考虑检索增强。

XXL-AI的RAG流程为标准三段式：先加载与切分文档，再向量化入库，最后查询时先检索再生成。我实测的经验是：向量化前先做文档清洗，比调模型参数更有效。很多企业文档是从旧系统导入的，残留大量无关页眉页脚，不清理会严重污染检索结果。

切分参数方面，我常用的是：中文文本按400到500个字符切，重叠区域50个字符。太小则丢失上下文语义，太大会引入噪声并浪费上下文窗口。切分时按标题结构优先切，有章节标记的文档比纯文本块效果好很多。这块实践下来，结构感知的切分方法通常比固定大小切分能提升10%到20%的命中率。

检索召回与重排序是RAG的另外一个核心。初始检索往往用Embedding向量做相似度查询，命中TopK，但如果知识库较大，TopK单独靠向量召回会漏掉一些匹配不到关键词但语义相关的文档。我建议在向量检索基础上加入关键词混合检索，再接一个重排序器（Reranker）对候选结果精排。其中有一种重排序方式与搜索关键词本身契合度较高，它可以衡量候选文档与用户问题之间的关联程度，输出一个重排得分，按分数筛选TopN送入大模型。

关于“RAG知识库能存图片吗”这个问题，我的结论是，可以存，但要看用途。如果图片里是设计稿和表格，需要让模型“看”图，那么需要配置多模态模型才能实现图片内容解析。如果只是为了给“文本检索”返回一个图片附件，那存入的是图片的描述信息和文件地址，本质上仍然是文本检索问题。XXL-AI的知识库支持文本块、文件引用和向量索引的组合，所以两种思路都能实现。

3.4 知识库形态对比：KG、RAG与结构知识库该选谁

热词里提到“kg知识库、rag知识库和结构知识库区分以及应用场景”，这个值得展开。三者不是替代关系，而是适用不同问题类型。

• 纯RAG知识库：适合非结构化文档的语义检索和问答。典型场景是产品手册、制度文档等。数据形态是文档切片，底层是向量索引加关键词索引。
• 知识图谱（KG）：适合回答关系类问题。比如“A员工的上级是谁”“B组件被哪些系统引用”。数据形态是实体和关系，底层是图数据库。
• 结构知识库：适合查询精确、可严格定义的业务数据。比如订单状态、库存数量等。数据形态是行列表，底层是SQL或API。

实际项目中经常混用。一个企业内部的智能问答助手，通常会用结构知识库对接ERP系统查业务数据，用RAG检索制度文档，用知识图谱做组织架构和权限关系查询。XXL-AI把这几种知识源都抽象成了数据源插件，Agent可以在一次对话中决策先去查哪个库，再查哪个库。

我踩过的坑是：如果对多个知识源做并行检索，返回的结果碎片很多，生成时容易互相打架。建议在Agent流程里明确检索顺序，先查最刚性的数据源（比如SQL里的订单状态），再结合松散的文档知识完善话术表达。

4. 工程化底座：让AI应用真正扛得住生产环境

4.1 多供应商接入与动态路由：不再被单一模型绑架

工程化的第一关是模型接入。XXL-AI抽象了一个统一模型网关，支持多个供应商接入，并且可以针对不同业务配置不同的路由规则。

比如一个平台里同时跑两个业务：一个业务对成本敏感，要求优先使用便宜模型；另一个业务对准确性要求高，规定必须使用强推理模型。可以用模型路由规则实现：

{ "domain1": { "provider": "aliyun_qwen", "model": "qwen-plus", "fallback_provider": "openai", "fallback_model": "gpt-4o-mini" }, "domain2": { "provider": "openai", "model": "gpt-4o", "fallback_provider": "anthropic", "fallback_model": "claude-sonnet-4" } }

这样实现了：业务1默认走便宜模型，业务2走强推理。如果主供应商限流或报错，自动回退到备用供应商，用户无感知。这种故障转移能力在依赖外部API的生产系统中非常重要，单点故障往往意味着直接业务损失。

选模型也有讲究。按照任务域去判断：情感判断、文本分类、标题生成这类任务，便宜的大模型已经足够；长链路推理和代码生成，必须用推理能力强的大参数模型。别迷信“模型越大越好”，在平台里，模型是资源，按成本与效果合理分布才是正道。

4.2 链路追踪与可观测性：排查Agent问题的基础设施

Agent应用最让人头疼的就是“黑盒”。它到底调用了哪些工具、每一步的Prompt是什么、模型返回了什么、为什么走到某个分支，在缺乏可观测性的系统里，全都无从查起。XXL-AI内置了请求全链路追踪，从外部请求进入平台开始，到最后响应返回，每一步的耗时、输入输出、调用的工具和模型都被记录下来。

排查一个失败案例，正确的阅读顺序是：先看请求追踪图确认卡在哪个环节，再点开节点详情查看输入输出。有时候问题出在模型返回格式不符合预期，有时候是MCP工具超时，也有时候是“被知识库返回的旧版本文档误导”。大部分情况都能通过链路日志快速定位。

建议团队在接入初期就对生产环境开启全量追踪。这个基础数据日后可以做质量分析，观察Agent的失败率是否与某些特定模型或技能包相关。

4.3 配置管理、权限控制与审计：AI平台的合规底线

企业内部用AI平台，三个事情绕不开：参数是否统一管理、谁能修改配置、操作是否有审计日志。

XXL-AI提供了一套配置管理中心：模型密钥、MCP连接信息、SKILL版本号、知识库绑定关系等，都支持集中配置和灰度发布。原因在于，大模型API的调用参数比较敏感，密钥不应该散落在各个业务代码仓库里，任何一次变更都应该是可控和可追溯的。

权限与审计方面，至少要分三类角色：开发者、运维者、业务使用者。开发者有权限编排流程但不能直接查看密钥明文；运维者负责管理模型与基础设施；业务使用者只能运行Agent并查看结果，不能改动底层配置。平台记录了每次编排的版本、调试记录、线上调用，这在审计场景中能发挥关键作用。

4.4 性能与成本：Token消耗的观测与控制

AI应用的运行成本，往往不是采购平台本身，而是模型Token的消耗。有些团队运营一段时间后才发现，最烧钱的是把大量无关上下文反复传给模型。

通过XXL-AI的成本看板，我看到单个Agent的平均Token消耗、MCP工具返回给模型的内容占比、知识库上下文占用。用这些数据做调优，很有依据。常见优化手段包括：缩短工具返回的文本长度（MCP返回尽量精简成摘要）、缩减向量检索相关度较低的段落、合理设置上下文窗口上限。

这里有一个一般的经验数值：对于RAG问答Agent，送入生成模型的上下文里，知识库内容占比尽量控制在60%以下，剩下35%左右预留给提示词和工具返回，再留一部分给模型生成。若知识库内容占比过高，输出容易变得冗长，无限重复原文。

5. 实操过程与核心环节实现：从零搭一个“企业知识问答Agent”

5.1 场景定义与Agent角色设计

空谈架构不如直接跑一个实例。我选取了一个非常典型的场景：企业内部智能问答Agent。这个Agent需要支持三种请求：查员工手册中的差旅制度、查询某个订单当前状态、生成一段符合公司规范的周报总结。

这个场景同时覆盖了三类核心能力：RAG对制度文档回答、MCP对订单系统查询、SKILL对周报格式的规范约束。

Agent设计上，我没有做成一个“万能Agent”，而是拆成了三个子Agent。

• 制度知识Agent：面向员工手册知识库，回答差旅制度、报销规范等内容。
• 订单查询Agent：通过MCP调用订单系统API，返回订单状态信息。
• 周报生成Agent：收集用户输入的碎片信息，按公司格式生成周报文本。

三个Agent内部做各自擅长的子任务，再由一个路由Agent判断请求的意图，分发到对应子Agent。这套设计的核心在于避免单Agent上下文过长以及各类工具混杂导致的决策混乱。

5.2 数据准备与知识库搭建

知识库这一步，我直接上传了员工手册PDF。文档加载后，平台自动切分成文本块。我第一次用默认参数跑完，检索出来的内容很零散，经常只匹配到目录页。后来我手动清洗了文档的页眉页脚，重新按一级章节拆分，效果好了很多。

实操中建议文档块按“章节标题 + 正文内容”组合存储，这样检索时能命中更合格的上下文。如果原始文档目录层级很清晰，尽量保留章节层级关系，让RAG的检索结果有“上下文归属”，生成答案时更容易理解内容在整篇文档中的位置。

5.3 工具接入与技能封装

订单查询MCP工具，我用HTTP方式接入，先在平台里配置了Bearer Token认证。配置完成后先做了连通性测试，再进入Agent测试。直接在Agent对话里发了一句“订单OD20240001当前是什么状态”，它成功调用了订单查询接口并返回格式化结果。MCP工具描述里写有完整的使用说明，模型能准确抽取参数并判断是否需要调用该工具。

周报生成SKILL，我定义成一个静态技能包，里面包含周报格式模板、禁止事项（不得虚构数据）、写作语气要求、字数与结构说明。在Agent里引用该SKILL后，生成结果格式稳定，不再出现随机的风格漂移。这比单纯在系统提示词里写一长串“请你遵守”效果好得多。

5.4 编排串联与联调测试

三个子Agent完成后，我用DAG编排把它们串起来。路由Agent作为主入口，根据用户输入判断意图并路由到对应子Agent。

联调中最有价值的测试用例是一个混合问题：“我这个订单OD20240001已经发货了，帮我看看还剩多少预算，然后写一段周报总结”。这条输入跨了订单查询、制度知识、周报生成三个Agent。在合理的编排下，路由Agent把这条输入先拆解为多个意图，分发给对应子Agent，最终汇总生成一份包含物流状态和预算情况的周报。拆得好，模型能力消耗更低，各模块得到复用；拆不好，逻辑混乱，结果因为上下文参数错乱而不可控。

联调过程中我发现一个规律：Agent边界不能按“功能”切，要按“数据域”切。订单查询Agent只该关心订单这个数据域，制度知识Agent只该关心制度文档。如果把“订单查询”和“退款审批”绑在同一个Agent里，当退款规则独立更新时，你必须重新部署整个Agent，很不灵活。

5.5 部署上线与灰度放量

联调通过后，我把Agent部署到了生产环境，先开放给5名内部测试人员试用了几天。灰度期间，我持续观察追踪日志：发现一个主要的问题是，当用户连续多轮追问时，模型倾向于复用旧上下文，有时会遗漏用户口径的修改。解决办法是在系统层面加了“每轮对话核心信息重写”逻辑，把多轮对话中的最新意图抽取出来作为本轮的输入上下文。

确认稳定后逐步放开。上线一个月，对话跑了两千多次，订单查询类问题的工具调用成功率达到预期，制度知识类回答覆盖率也比较满意，周报生成没有出现明显的不合规内容。

6. 常见问题与排查技巧实录

6.1 问题速查表：按症状定位原因

我把自己遇到的和社区里高频出现的几类问题整理成一个速查表，便于快速对照处理。

6.2 被最多人问到的几个具体问题

“codex无法找到mcp”这类问题其实与具体某个工具无关，更常见的是MCP配置与平台服务不匹配。建议检查三处：MCP服务端是否可通过当前网络端口访问；AuthToken是否具备调用权限；服务端协议版本与客户端是否兼容。

“dify 浏览器mcp”这类场景属于把浏览器控制能力接入Agent。浏览器MCP可以完成打开页面、点击、读取网页内容等操作。需要注意浏览器实例的资源隔离。在一个容器里同时跑多个浏览器MCP实例会消耗大量内存，建议按需启动或复用池化浏览器。

“rag知识库能存储图片嘛”这个问题我在前面已经提过，这里补充一句：如果图片内容需要被“理解”，记得在生成模型那边配置多模态能力，否则图片检索回来后模型也无法读取图片内容。

“kg知识库、rag知识库和结构知识库区分”如果还不清楚，回到一个原点问题：你要回答的是“是什么”“谁和谁有什么关系”还是“现在是多少”。RAG回答“是什么”，知识图谱回答关系和路径，结构知识库回答精确数值和状态。选择知识源类型前，先想明白问题类型。

6.3 经验总结：稳定比炫技重要

跑了一整轮下来，我个人最深的体会是人并非依赖某个单一功能，而是依赖“一套把复杂事情组织起来的基础设施”。Agent编排框架本身意义有限，多供应商路由和追踪分析才是日常排障的关键。扩展机制也同样重要：MCP、SKILL、RAG这三者从三个角度让Agent在真实环境中变得可用，一条链路下来，从意图理解到工具调用、知识检索、格式生成，均有标准规则和可追踪痕迹。

最后分享一个我个人的选择判断：如果你的项目只在技术Demo阶段，不需要上XXL-AI这种完整平台，用SDK直接写可能更快。一旦要进生产，要多人协作，要面对复杂业务模型、不同模型的表现差异、工具调用的稳定性担忧，那就值得把这类工程底座作为项目骨架来用。做AI应用，什么时候都有奇思妙想来实现，但底座的稳定性往往决定了应用能走多远。