企业官网建设流程全解析

XXL-AI这个词，最近在AI应用开发圈子里的讨论度确实不低。我最初看到这个项目标题，第一反应是"又一个写Demo的框架"，但把Agent编排、多供应商、MCP、SKILL、RAG、工程化底座这几个关键词摆在一起之后，我意识到这个定位并不是想多造一个轮子，而是想把AI应用从"技术验证"真正推向"工程化落地"。作为一个用各类AI框架搭过十几个应用的人，可以直说：这类平台真正值钱的地方，不在某个单一能力有多炫，而在于它怎么把模型、工具、知识、流程、治理这些东西揉在一起，让一个普通团队也能稳定上线一个Agent应用。

这篇文章我会按自己的理解，把XXL-AI这类"AI应用开发平台"的核心设计逻辑拆开讲，包括Agent编排该怎么建、多供应商切换的坑在哪、MCP和SKILL和RAG三种扩展机制分别解决什么问题，以及工程化底座为什么比模型本身更决定项目生死。最后会带一个完整的客服Agent实操案例和踩坑实录。适合三种人看：想快速验证AI产品idea但不想从零造轮子的开发者，想给企业内部系统接AI能力的架构师，以及正在学习Agent编排和RAG相关课程的同学。

1. 整体设计拆解：XXL-AI到底做了什么

1.1 为什么需要AI应用开发平台

先说一个现状：现在的模型能力确实很强，但单独调用一个模型API，得到的只是"回答问题的工具"，不是"能完成任务的系统"。一个真正的AI应用，比如客服助手、文档分析agent、自动化运维机器人，至少要经过"理解用户意图→规划步骤→调用工具→检索知识→生成回复"这么一串链路，而且还要考虑用哪家模型、换模型怎么办、怎么记录每次请求、怎么控成本、怎么防止乱跑。

没有平台的时候，这些事全得自己来。我自己经历过最痛苦的阶段就是：接OpenAI的SDK，接Anthropic的SDK，接国产模型的SDK，每个SDK的报文结构还不一样；写Agent循环要自己维护"思考、行动、观察"的状态机；做知识库要自己选向量库、自己写分块和prompt拼接；最后做完一个demo，发现连日志都没有，线上出问题只能靠猜。这感觉就像开餐厅，明明买到了顶级半成品食材，结果水、电、煤气、切配流程、冷链、记账全得自己搭，厨师根本没法专心炒菜。

XXL-AI这类AI应用开发平台，本质就是把"水电煤气"铺好，让团队直接把精力放在业务逻辑上。它解决的问题是结构性的：模型接入、流程编排、工具扩展、知识增强、运行治理，这些不该在每个项目里重复造轮子，应该沉淀成平台能力。适合谁呢？适合那些目标是"上线一个Agent服务"而不是"研究模型本身"的团队。如果你只是跑个One-shot prompt，那用不到平台；一旦要做多步骤、多轮、多工具、多模型的系统，平台的价值就会迅速显现。

1.2 四大核心模块的设计逻辑

XXL-AI这个标题里最值得品的是四个关键词的排列：Agent编排、多供应商、「MCP + SKILL + RAG」扩展、工程化底座。这不是随便堆砌，而是对应了一个AI应用从输入到输出的完整链路里必须解决的四个问题。

我习惯用一张表来理解它们的分工：

这六个能力组合起来，基本就是一个AI应用的"操作系统"。我特别想强调的是，缺少任何一块，短期都能跑Demo，但长期一定会碰壁。比如只有编排没有运维，线上卡死没人知道；只有RAG没有多供应商，换模型得把所有知识库代码重写一遍；只有工程化底座但没扩展机制，那Agent就只是个"只会聊天的空壳"。

为什么这个平台设计成"平台"而不是"一个库"？因为库只能解决单点，平台才能把上面的链路串起来。我见过很多团队用LangChain写脚本，写到后面发现每个脚本都在重复"初始化模型、加载prompt、拼接上下文、记录日志"这些代码，这就是平台应该吸收掉的复杂度。

2. 核心细节解析：Agent编排与多供应商

2.1 Agent编排：从流程图到可观测的Pipeline

很多人以为Agent编排就是"在代码里写个while循环调用大模型"，其实不是。真正的编排是把一个复杂任务拆成节点，按条件流转，并管理节点的输入输出、上下文、超时、重试。XXL-AI这类平台通常用"节点+边"的图结构来描述流程，而不是让模型自由发挥到一个黑盒里。为什么？因为图结构透明、可控、可测试，出了问题能定位到具体节点；而纯代码式Agent一旦跑飞，工程师只能看到"模型在不停说话"，根本不知道在哪一步。

一个客服Agent的编排流程，大概长这样：

nodes: - id: intent type: llm prompt: "识别用户意图：query_order / product_faq / after_sales" output: intent - id: route type: condition source: intent branches: - if: 'intent == "query_order"' next: get_order_tool - if: 'intent == "product_faq"' next: rag_retrieve - if: 'intent == "after_sales"' next: after_sales_skill - id: get_order_tool type: mcp_tool server: order_system tool: get_order_status input: { order_no: state.order_no } - id: rag_retrieve type: rag query: state.user_input top_k: 5 - id: answer type: llm prompt: "基于检索结果和工具结果给出最终回答"

关键点在于"状态传递"。编排引擎要维护一个上下文对象（通常叫state或payload），每个节点从里面取需要的字段，处理后把结果写回去。这样设计有两个好处：一是上下文不会全塞进模型，节省token；二是每个节点的输入输出都能被记录，方便排查。

我踩过的坑就是：早期图省事，把整个对话历史全传给每个LLM节点，结果一个5000字的历史塞进去，光token就烧掉一大半，模型还容易被无关信息带偏。后来改成"按节点取字段"——意图识别只需要最近一句话，订单查询只需要order_no，生成回答才需要检索结果和工具结果。这个改动让成本和准确率都明显改善。

编排里还有个容易忽略的东西：循环和退出条件。比如一个"自动优化方案"的Agent，可能要反复修改文案直到评分达标，你得给循环设置最大迭代次数，比如max_iterations: 3，否则模型一旦觉得自己永远不满意，任务就会无限跑下去，烧钱烧到天荒地老。

2.2 多供应商适配：一次接入，到处切换

多供应商这块，表面看是"多接几家模型SDK"，实际上是一门适配工程。不同供应商的API差异远远不止"报文格式不同"这么简单：有的支持Function Calling，有的支持JSON Mode，有的返回reasoning_content，有的要传system prompt，有的上下文窗口只有8K，有的支持128K，更不说流式输出格式、速率限制、计费单位这些细节。

XXL-AI的做法通常是提供一个"统一模型接口"，把所有供应商都包装成同一种调用方式，然后在配置层做路由和降级。我用一个表格来说明典型的供应商差异和适配策略：

所以不要以为"统一接口"只是把URL换一下。真正做得好的平台会做"能力探测"：启动时跑一次小请求，看这个模型支不支持流式、支不支持工具调用、最大上下文多长，然后把这些能力元数据存起来，供编排引擎做路由决策。

供应商切换的实操要点，我总结为四件事：一是定义好主备关系，默认用便宜的模型处理简单意图，复杂任务才切到强模型；二是配好"重试+降级"规则，比如主模型连续报错3次就切备用模型，而不是让用户看到报错；三是把每个调用的usage（token用量）记录下来，否则月底账单出来根本不知道钱花在哪；四是在切换时保留原始响应原文，我一直建议把供应商原始返回和转换后的统一结构都写入日志，这样排查问题时有据可查，不用猜。

2.3 编排与供应商结合的常见误操作

这块我单独拎出来说，因为很多人栽在这里。最常见的问题是"流式输出不会在编排里传递"。如果你的Agent最终要给用户打字机效果，但中间节点比如RAG检索、工具调用是同步的，那你要设计成"最后生成阶段才开流式"，而不是全流程都流式，否则中间节点的流式输出会把一条完整消息切成无数碎片，前端界面惨不忍睹。

另一个问题是"重试幂等"。工具节点比如"发短信"「扣款」这类有副作用的操作，重试必须小心。如果订单查询超时，重试没问题；如果是"创建订单"超时，重试可能造成重复订单。XXL-AI这类平台里，通常会给工具节点配"幂等策略"，比如要求MCP工具提供requestId参数来实现去重。我自己的经验是：给所有写操作都带上requestId，服务端根据requestId判重，这是血的教训换来的。

还需要警惕的是"上下文爆掉"。多步编排里，如果每个节点都把全部中间结果拼到下一轮，最后一个节点的上下文可能超出模型窗口。我建议每步都显式声明"传给下一步的字段"，比让引擎自动拼接所有数据要可控得多。实测下来，精简后的编排不仅省token，出错概率也低，模型不容易被无关中间量干扰。

3. 扩展机制拆解：MCP、SKILL、RAG

3.1 MCP：把工具标准化接入

MCP（Model Context Protocol）最近讨论度很高，你可以把它理解成AI世界的USB-C接口。以前每个Agent要接一种系统能力，就得写一套专用连接器，比如查订单写一个、发消息写一个，换框架就重写一遍。MCP的意义在于：只要Agent平台内置了MCP Client，而工具方提供了一个MCP Server，两边就能自动握手——工具描述、入参出参Schema、鉴权信息都能自动被Agent读取，不用再手工维护工具文档。

在XXL-AI里接MCP工具，流程大概是这样：

{ "mcpServers": { "order_system": { "type": "http", "url": "https://mcp.internal.example.com/order", "headers": { "Authorization": "Bearer sk-xxx" }, "enabledTools": ["get_order_status", "create_return_request"] }, "code_repo": { "type": "stdio", "command": "npx", "args": ["-y", "my-mcp-code-server"] } } }

这里有三个细节值得说。第一，enabledTools一定要做白名单。我之前试过把一个MCP Server上20多个工具全放给Agent，结果模型在选择工具时明显变笨，经常选错，后来我把无关工具禁掉，只留5个跟任务相关的，准确率立刻上来了。第二，HTTP类型和stdio类型使用场景不同：远程共享的、需要鉴权的服务用HTTP，本地开发的工具用stdio更方便。第三，很多工具需要额外授权，比如接入Figma、蓝湖这些外部产品时，通常要走OAuth；这个授权流程跟平台自身的API Key是两码事，别混在一起配。我见过有人说"codex无法找到MCP"，一半以上的情况就是鉴权过期或者工具没启用。

MCP还有一个"流式输出"的特性容易踩坑。比如mcp工具有的要把内容流式写到文件，这种工具往往返回的是"任务已提交"而不是完整结果，你要在后续节点轮询任务状态，不然Agent会以为工具没干完活。

3.2 SKILL：把能力固化成技能包

SKILL这个概念，和MCP是互补的。MCP解决"能干什么"，SKILL解决"该怎么干"。一个SKILL不是一段简单的prompt，而是一个结构化的"技能包"——它包含场景描述、触发条件、操作步骤、输入输出定义、约束边界、参考示例，甚至可以指定要调用哪些MCP工具。你可以把SKILL理解为"把团队里某个优秀员工的作业方法标准化了"。

举个例子，一个客服退换货处理的SKILL可以这样定义：

skill: name: after_sales_return_process description: "处理用户退换货请求的完整流程" trigger: intent: after_sales requires: order_no, reason, user_role steps: - action: mcp_tool server: order_system tool: validate_order input: order_no expect: valid_order=true - action: mcp_tool server: order_system tool: create_return_request input: order_no: state.order_no reason: state.reason constraints: - "仅处理已签收订单" - "退货理由必须填写，否则终止" examples: - "我今天收到的衣服破了个洞，想退货" output: "已为您创建退货单，快递小哥将在24小时内上门取件"

为什么SKILL这么有价值？因为它把"经验"变成了可复制、可测试、可换底模的东西。同一个SKILL，底下的模型可以从GPT换到国产模型，只要模型能力达标，技能行为基本一致。最近热词里出现的"skill编码247""skill编码193"这类，很大程度上就是社区在给技能包做标准化编号，让不同人写的SKILL可以互相引用和组合。我建议一个团队内部先沉淀三五个高频场景的技能包，比让每个人从零写prompt要高效得多。

SKILL和普通prompt的区别，我用一句话总结：prompt是给模型的"话术"，SKILL是给系统的"操作手册+话术+边界"。如果你只是在prompt里写"你是一个客服"，那是没有SOP的；SKILL把"SOP拆步骤、每步调什么工具、什么情况不许做"都写死了，Agent的行为就稳定了。

3.3 RAG：把企业知识变成模型记忆

RAG（检索增强生成）是这几年落地最广的技术，原因很朴素：模型再强也没读过你们公司的内部文档，你不可能因为几十页操作手册就去微调一个大模型。RAG的思路就是"先查资料，再答题"——把私域知识切块存进向量库，用户在提问时检索相关片段，和问题一起拼给模型，让模型基于检索结果回答。

完整链路长这样：文档导入→解析清洗→分块→Embedding向量化→写入向量库→运行时查询向量库→（可选）重排→拼装Prompt→生成回答。看起来简单，但每个环节都能影响最终效果。最关键的两个参数是分块大小和检索策略。

分块参数，我一般这么设：中文资料chunk_size取300到500字左右，overlap设10%到15%。太小了上下文碎片化、丢失上下文，太大了检索精准度下降，而且塞进prompt会浪费token。Overlap是为了让前后两块之间“接上头”，避免一句话戛然而止。像产品手册这类强结构化文档，我用300字块就够了；制度文件这种段落长的，我反而会稍微调大到500字，注意这个没有绝对标准，要根据证据测试。

检索策略，我强烈建议做混合检索（向量检索+关键词检索）加一个Rerank层。纯向量检索对中文专有名词、API名、产品型号很不友好，比如用户问"XXL-3000型怎么退换"，向量检索可能召回一堆无关片段，关键词检索反而能精准命中。混合检索就是把两种候选合并，再用重排模型排序，实测下来召回准确率能提不少。有人问RAG知识库能不能存图片，严格说传统向量库存的是文本向量，图片要用多模态模型做图文结合的检索，那是另一条技术路线，别混为一谈。

RAG的真正瓶颈，我看下来主要是两个：一是“检索正确但模型没用上”，这时要检查prompt对检索结果的强调和引用格式；二是“检索召回了错误内容”，需要调metadata过滤、query改写、score阈值、topK。例如我们可以把所有文档按“产品线”“版本号”“适用地区”打上metadata标签，查询时先过滤，命中率会显著提高。

3.4 三种扩展机制如何分工与选型

MCP、SKILL、RAG放一起，很多人会有点晕。我用一个实战判断逻辑帮各位梳理：当你想让Agent去“查订单状态、发消息、执行代码”时，这是实时系统操作，走MCP；当你有一堆企业文档要变成问答知识时，走RAG；当某个场景有标准作业流程，比如“售后处理SOP”“工作总结模板”“文档转PDF并加密”，就是SKILL；而一个成熟Agent，往往同时用好几种。

我见过不少失败的AI应用，就是“看起来什么都能接，但什么都没接好”。工具、技能、知识库一股脑全塞进去，Agent反而像个没有经验的新员工——工具太多选不中、技能太多记不住、知识库没清洗乱回答。我的建议是，先想清楚你的业务到底是“系统操作重”还是“知识问答重”，然后主攻对应的扩展方式，其他作为辅助，不要一上来就追求全家桶。

4. 工程化底座：从演示到生产的最后一公里

4.1 为什么要做工程化

功能Demo跑通之后，最扎心的一句话是“能不能上线”。上线意味着：出问题能查、费用能控、权限能管、模型抖动能扛。没有这些，AI应用就是个黑盒，老板问一句“那天那个客服机器人为什么答错？”你连日志都翻不出来，只能尴尬地复现。这就是工程化底座的价值。

XXL-AI把工程化作为自己的一个卖点，说明它很清楚AI应用和传统后端系统一样需要治理能力，而且AI应用比普通Web服务更要治理——因为大模型的输出是不确定的，你必须记录它每一次的输入输出，才能解释“为什么是这个回答”。我自己的体会是，一个AI应用项目，模型选型和技术方案大概只占三成工作量，剩下七成都在和“不确定性、成本、权限、稳定性、可追溯性”搏斗。平台能把这七成做扎实，项目成功率会高很多。

4.2 关键工程化模块的落地要点

工程化底座范围很大，我挑几个最关键的讲：

第一件事是任务链路追踪。给每一次Agent执行分配一个trace_id，每个节点都记录输入、输出、耗时、token消耗、调用模型等。这样用户说“刚才回答错了”，你可以顺着trace_id看到意图识别是否对、检索了什么、工具返回了什么、最后生成的prompt是什么。我强烈建议这个从第一天就做，而不是上线后补。

第二件事是成本计量和多维汇总。按供应商、模型、项目、日期统计费用，设置预算告警。AI应用成本最大的坑是没人盯着token消耗，一次多Agent并发任务可能烧掉几十万token，没有计量就只能等账单吓自己。实测下来，平台级的成本看板能显著减少浪费。

第三件事是权限体系和审计。谁有权限创建Agent、谁有权限改知识库、谁有权限调用某个工具，都要控制。道理和数据库权限一样，只是很多人做AI应用时把它忽略了。

第四件事是限流和队列。模型的速率限制（Rate Limit）是真实存在的，你直接把大量请求打到供应商API，很快会收到429。平台里应该内置任务队列和并发控制，让请求平稳地发送。

第五件事是配置和版本管理。Agent的prompt、SKILL、知识库、模型参数，都要有版本记录。我见过一个团队改了一段prompt没记录，上线后准确率掉了却不知道回滚到哪个版本。配置版本化这件事，越早做越省心。

我特别想提醒的是：别为了工程化而工程化。第一步可以先只做日志和trace，把应用运行过程看清楚；成本看板和权限，等业务发展起来了再补。工程化应该跟着痛点走，一次性铺太大反而是负担。

5. 实操过程：从零跑通一个客服Agent场景

5.1 场景设计与前置准备

讲完理论，来一个完整的实操案例。我们假设要做一个电商客服Agent，它能处理三类问题：产品问询、订单查询、售后流程咨询。这三个正好对应RAG、MCP、SKILL三种扩展方式，非常适合练手。

前置准备有这几样：一个装有XXL-AI（或类似具备这些能力的平台）的环境，一个能用的模型供应商API Key，一个订单查询接口（哪怕拿Mock服务模拟），以及一份产品手册PDF。我个人建议第一版用Mock接口，把链路跑通了再接真实系统，否则问题会混杂在一起，“不知道是Agent的问题还是接口的问题”。

按我的习惯，先画一条最小路径：用户提问→意图识别→分三条线走→生成回复。这条路径跑通后，再逐步加“情绪判断”“转人工”“多轮澄清”这些花活。别一上来就设计一个十节点的超复杂图，调试会调到怀疑人生。

5.2 配置模型供应商与创建项目

进入XXL-AI控制台，第一步是配置供应商。我通常把供应商分成“主”和“备”两个：主用便宜且响应快的模型处理高频简单问题，备用一个更强的大模型处理复杂推理。以OpenAI Compatible格式为例子，配置大概长这样：

{ "provider": "openai_compatible", "base_url": "https://api.example.com/v1", "api_key": "sk-xxx", "models": [ { "id": "fast-chat", "capabilities": ["chat", "stream", "tool_call"], "max_context": 32768 }, { "id": "strong-reason", "capabilities": ["chat", "stream", "tool_call"], "max_context": 131072 } ] }

配置好之后，先做一个最简单的测试：在对话窗口直接问Chat模式“你好”，确认供应商通了。这一步排除掉网络、Key失效、模型名写错等基础问题，再往后面走。千万别一上来就配编排，出了问题你根本分不清是模型还是流程。

5.3 搭建Agent编排流程

接下来创建Agent并搭建编排流程。我给客服Agent设计四个核心节点：意图识别、条件路由、RAG检索/工具调用、生成回答。这个“四板斧”套路覆盖了大部分查询型Agent，你可以直接抄。

意图识别节点只把用户最近一句话喂给模型，输出一个JSON。比如：

id: intent type: llm input: state.last_user_message prompt: | 判断用户意图，只能输出以下之一： product_faq: 问产品功能/规格/使用 query_order: 查订单状态/物流 after_sales: 退换货/售后 输出JSON: {"intent": "..."} output: state.intent

路由节点按意图分流，然后各分支执行对应操作。RAG检索节点会去查知识库，MCP工具节点会调用订单系统。最后在生成节点，把检索到的片段或工具返回的订单状态整理一下，再让模型生成用户友好的回复。

我建议的测试顺序是：先单独测每个节点，再连起来测全流程。逐个节点点“运行测试”，确保每个结点输出符合预期，再跑整体。不要上来就全流程测试，否则出错时定位范围太大，浪费时间。

5.4 接入RAG知识库

产品问询场景需要RAG知识库。实操步骤就是：上传产品手册PDF→文本解析→分块→向量化→写入内置向量库→测试检索。

这里容易遇见的坑是PDF解析。PDF里如果带表格，普通文本解析会把表格内容截断成看不懂的碎片。我建议对含表格的文档先转成Markdown或HTML再抽取，比直接抽文本强不少。解析完不要急着向量化，先肉眼扫一遍清洗结果，去掉页眉页脚、图表里没意义的数字。

分块我用300字、overlap 45字，向量模型用中文场景下常用的bge-m3这类。检索测试时，我习惯同时看两个指标：查没查到（命中率）和查得准不准（相关性）。如果没查到，把topK调大一点到8、阈值调低一点；如果查到了但模型不会用，那是生成prompt的问题，不是检索的问题，要再修改生成节点的提示词，比如“只依据以下资料回答，资料没有明确说明时承认不知道”。

5.5 接入MCP工具与服务

订单查询需要走MCP。我先用工具包写一个MCP Server把Mock订单接口包起来，然后按3.1节那套配置接入平台。接入后，一定要先在平台里单独测试这个工具，先调用get_order_status测试看给参数能不能返回正确结果。

单独测试通过后再放进Agent流程。很多人的问题就是跳过这个步骤，直接编排里去调用，结果工具报错，你根本分不清是“工具本身坏了”还是“编排参数传错了”。我先在工具的调试面板里调用一次，看到如下结果：

{ "order_no": "DD20240101", "status": "已发货", "express": "顺丰", "estimated_arrival": "2025-03-01" }

然后才把它接到“订单查询”分支里。我在MCP工具节点上还加了一个超时：5秒。因为Mock接口很快，但真实接口不一定，如果超时就让Agent说“查询超时，请稍后再试”，而不是干等导致整个流程卡住。

5.6 测试、调参和上线前收尾

全流程最后是联调测试。不要只测标准输入，还要测几个刁难场景：用户同时问了产品和订单、用户情绪暴躁、知识库里没有答案、订单号格式错误。这些Case你会发现Agent有一半会答错，正常现象，调prompt和参数就好。

比如“同时问产品和订单”，我调整提示词让模型先拆分意图，不允许只选一个，而是拆成两个子任务并行。再比如“订单号格式错误”，我在MCP工具调用前加了一个代码节点做格式校验，不符合就让Agent反问客户索要正确单号，而不是直接调接口然后报错。

上线前还有几个收尾动作：打开trace记录并实际走一遍流程确认能看到每一步日志；配置月度预算告警；把备用模型配好，测试一下主模型故意报错时能否自动切到备用模型；最后跑一遍并发压测，确认平台限流没被击穿。全都过了，才敢说“可以上线”。

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

6.1 供应商切换后返回格式不一致

很多人在主备模型切换后遇到这类问题：同一个编排流程，主模型跑得好好的，切到备用模型就报错，或者回答质量明显变差。原因多半不在编排，而在模型能力差异。有的模型不支持工具调用，有的模型不输出JSON，有的模型非要你传特殊参数。遇到这种问题，先看日志里这个模型调用的“原始返回”，确认它返回了什么、缺了什么字段，然后再决定是加降级还是换能力相当的另一款模型。我给团队的规则是：备选模型在主模型同一能力层级里选，不要指望一个便宜模型能完全替代强模型的复杂推理，指望了就会在线上翻车。

6.2 MCP工具找不到、超时、鉴权失败

“模型根本不调用我配好的MCP工具”是最高频问题之一。首先检查工具描述是否写得清楚，模型是通过描述来决定“要不要选这个工具”的，描述模糊它就瞎选。比如“查询订单状态，输入订单号，返回物流和进度”就比“订单工具”好得多。第二，确认工具白名单和参数Schema是否完整，必填参数缺了模型就会犹豫。第三，检查授权和超时，尤其是OAuth类的MCP服务，授权token过期后工具会一直失败，日志里看有没有401或403。第四，用调试模式单独调一次，确认工具本身是好的，再放回流程里。MCP相关的问题，80%都可以在“单独调试工具”这一步暴露出来，别老去怀疑Agent，先怀疑工具本身。

6.3 RAG命不中或者命中了不会用

知识库明明有答案，Agent却说“不知道”，这种问题我至少见了二十次。排查思路分两步：第一，去检索日志里看“召回结果里到底有没有正确答案”。如果没有，就是检索环节问题，调低score阈值、提高topK、做混合检索、加metadata过滤，或者重新调分块大小，我之前有一个案例是把分块从500字调到300字，命中率立刻上来了。第二，如果召回结果里明明有正确答案，但模型没用上，那问题在生成prompt。我把prompt调整为“你只能根据'''资料'''中的内容回答，如果资料里有答案，请原文引用相关数据；如果没有，请明确说明”，效果立竿见影。记住：RAG链路分两段，检索到不等于回答对，两段要分开排查。

6.4 Agent编排卡死、循环和上下文爆炸

任务一直“运行中”不动，最让人头大。结合实测经验，最常见原因是循环节点没有退出条件，或者某个分支走到了死路。第一次遇到时我整个人都蒙了，后来在平台里看到trace停在某个节点反复重试，才意识到是工具调用一直返回错误，但重试上限被设成了无限次。解决方法是给所有节点设超时和重试上限，给循环设置max_iterations，并且在编排引擎里加全局“最大执行时间”兜底；超出了就中止，返回“任务超时，请重试”。另外一个容易被忽略的是上下文爆炸：一些编排引擎默认把前面节点的全部输出都塞给后续节点，几轮之后超过模型上下文长度。排查方法是打开节点入参，看各节点到底收到了哪些数据量；优化方法是显式声明每个节点的输出字段，保持链路数据精简。

6.5 成本突然飙升

成本问题我放在最后一个讲，因为它最容易被忽视，却也最致命。常见诱发因素有三个：一是编排设计不合理，多Agent递归调用、循环不设置上限；二是历史记录无节制塞入，上下文越长花钱越多；三是模型选择无分层，所有请求都用贵模型。我的实战手段是，先设置单任务成本上限，然后对高频简单请求用便宜模型并加缓存，再对复杂请求才用强模型。同时，把trace里的usage字段和成本看板打通，每周过一眼，等告警才去查就晚了。

最后再分享一个我个人的感触：像XXL-AI这样的AI应用开发平台，真正降低的并不是“调用模型的难度”，而是“把模型变成业务系统一部分的难度”。你可能不需要一口气把所有功能都用上，但Agent编排、多供应商、MCP、SKILL、RAG、工程化底座这六块肌肉，每一块都值得单独练熟，再组合起来。只有把每一环都真正搞明白，AI应用才不会停留在“跑得通Demo”，而是稳稳地跑在生产环境里，变成一个哪怕模型输出不可控、系统也依然可控的工程交付。