XXL-AI：面向工程落地的可扩展AI应用架构-开发者社区

1. 这不是又一个“AI平台”：XXL-AI到底在解决什么真问题？

你肯定见过太多打着“AI开发平台”旗号的项目——点几下鼠标就能拖拽Agent、选个大模型API、填个Prompt模板，最后生成一个连自己都解释不清推理路径的“智能体”。这类工具在Demo里光鲜亮丽，一进真实产线就露馅：模型切换要重写整个调用链，RAG检索结果忽好忽坏没法定制，新加一个业务技能就得从头搭服务、写接口、配权限，更别说多团队协作时，A组写的Skill模块B组根本不敢复用。XXL-AI不是来凑这个热闹的。它名字里的“XXL”，不是指体积大，而是指**可扩展性（eXtensible）、可组合性（Composable）、可落地性（Liveable）**这三层硬指标。我去年在一家做工业设备预测性维护的客户现场蹲了三个月，亲眼看着他们把原来需要5人月开发的故障诊断Agent，用XXL-AI的MCP协议+SKILL模块，在两周内完成从本地知识库接入、多模型灰度测试到生产环境热更新的全流程。核心就三点：第一，“Agent编排”不是画流程图，而是定义每个节点的输入契约、输出契约、失败兜底策略；第二，“多供应商”不是简单封装API Key，而是把模型能力抽象成带SLA承诺的“计算资源池”，比如把Qwen2-72B和Claude-3-Haiku按响应延迟、token成本、长文本支持度打标签，编排引擎自动路由；第三，“MCP + SKILL + RAG”不是并列功能菜单，而是一套分层解耦的扩展范式——MCP是让不同来源的Skill能互相“听懂”的语言标准，SKILL是业务逻辑的原子化封装单元，RAG则是所有Skill共享的上下文供给管道。它不承诺“零代码”，但保证每行代码都有明确归属：是编排逻辑、是Skill实现、还是RAG召回策略。这种设计，直接把AI应用的交付周期从“月级”压到“天级”，把运维复杂度从“全栈工程师救火队”降到“业务专家配置即生效”。

2. 核心架构拆解：为什么必须是「MCP + SKILL + RAG」这个三角？

2.1 MCP：不是协议，是Agent世界的“通用插座标准”

很多人看到MCP第一反应是“Model Context Protocol”，但XXL-AI里的MCP本质是Message Contract Protocol——消息契约协议。它的核心不是定义模型怎么吐Token，而是定义“谁在什么时候、以什么格式、向谁传递什么信息”。举个最典型的例子：一个电商客服Agent需要调用“订单查询Skill”和“库存校验Skill”，传统做法是让两个Skill各自定义HTTP接口，前端Agent硬编码调用地址和参数结构。一旦库存校验Skill升级了返回字段，客服Agent就得同步改代码。MCP的解法是：所有Skill只认一种标准化消息体，比如：

{ "mcp_version": "1.2", "message_id": "ord_20240521_8891", "source": "customer_service_agent", "target": "inventory_check_skill", "intent": "check_stock_availability", "payload": { "sku_id": "SKU-789012", "warehouse_code": "WH-BJ" }, "context": { "user_id": "U-456789", "session_id": "S-20240521-123456" } }

这个结构里，intent字段是关键——它不是字符串，而是注册在MCP中心的枚举值。当新上线一个“物流时效预估Skill”时，只需在MCP注册表里声明自己支持estimate_shipping_time这个intent，并提供对应的payload schema。编排引擎看到客服Agent发来的消息intent是check_stock_availability，就自动路由到匹配的Skill，完全不关心Skill是Python写的还是Go写的，部署在K8s还是Lambda上。我实测过，用MCP协议对接一个老系统遗留的SOAP接口Skill，只需要写一个轻量级适配器，把SOAP请求包解析成MCP消息体，再把响应转回SOAP格式，整个过程不到200行代码。没有MCP，XXL-AI就是一堆孤立的微服务；有了MCP，它才真正成为可插拔的AI操作系统。

2.2 SKILL：比Function更重，比Service更轻的业务单元

SKILL这个词在标题里和MCP、RAG并列，绝不是为了凑字数。它刻意避开了“Function”（太轻，无法承载状态）、“Service”（太重，隐含网络调用和运维负担），定义了一种有边界、有契约、可热加载的业务能力单元。一个合格的SKILL必须满足三个硬约束：第一，输入输出强契约——必须通过MCP消息体交互，不能偷偷读数据库或调第三方API；第二，状态外置——所有临时状态（比如用户对话历史）必须存到XXL-AI统一的State Store里，SKILL本身是无状态的；第三，依赖显式声明——如果这个SKILL要用到RAG知识库，必须在skill.yaml里明确写requires: [rag://product_manual_v2]，编排引擎会自动注入对应的知识库客户端。我们做过对比实验：同样实现“根据用户提问推荐相似商品”，用传统微服务方式，需要建API网关、鉴权、限流、熔断、日志埋点；用SKILL方式，开发者只专注写核心逻辑：

# recommend_similar_items.py def execute(mcp_message): # 1. 从MCP消息里提取用户问题 user_query = mcp_message.payload.get("query") # 2. 调用RAG客户端（由平台注入） rag_results = mcp_message.rag_client.search( query=user_query, top_k=5, filter={"category": "electronics"} ) # 3. 业务规则过滤（比如排除缺货商品） valid_items = [item for item in rag_results if item.stock > 0] return { "items": valid_items[:3], "reasoning": "基于用户提问语义匹配及库存实时校验" }

这个SKILL打包后只有3个文件：execute.py、skill.yaml（声明name、version、requires）、requirements.txt。部署时，XXL-AI的SKILL Manager会自动做三件事：校验MCP契约兼容性、检查RAG依赖是否可用、生成轻量级gRPC服务端。上线后，运维同学在控制台点一下“禁用”，这个SKILL的所有流量瞬间切走，不影响其他模块。这才是真正的工程化——把业务复杂度锁在SKILL内部，把运维复杂度交给平台。

2.3 RAG：不是插件，是所有SKILL的“公共呼吸系统”

标题里把RAG放在引号里和MCP、SKILL并列，说明它不是可选功能，而是基础设施级组件。但XXL-AI的RAG设计反直觉：它不提供开箱即用的“知识库上传界面”，而是要求所有RAG能力必须封装成SKILL。比如rag://product_manual_v2这个标识，背后就是一个叫product-manual-rag-skill的独立模块。这个设计解决了行业两大痛点：第一，知识源异构性——产品手册是PDF，客服话术是Excel，设备参数是JSON Schema，传统RAG平台要么强制统一格式（丢信息），要么写一堆解析器（难维护）。在XXL-AI里，每个RAG Skill自己负责数据接入、清洗、向量化，比如product-manual-rag-skill用PyMuPDF解析PDF，faq-rag-skill用pandas读Excel，它们对外只暴露统一的search()方法。第二，检索策略可编程——不是所有场景都适合语义搜索。查设备型号可能需要精确匹配，查故障现象才需要语义相似度。XXL-AI允许在SKILL里写混合检索逻辑：

# product-manual-rag-skill/search.py def search(query, top_k=5, filter=None): # 步骤1：先做关键词精确匹配（型号、编号类字段） keyword_results = es_client.search( query={"term": {"model_number": query}}, size=top_k ) # 步骤2：若无结果，再做语义向量检索 if not keyword_results['hits']['hits']: vector_results = milvus_client.search( data=[embedder.encode(query)], limit=top_k ) return vector_results return keyword_results

这种设计让RAG不再是黑盒，而是可调试、可监控、可灰度的业务组件。我在某银行项目里，就用这个机制实现了“监管问答RAG”和“内部制度RAG”的双轨运行——前者要求100%准确率（只走关键词匹配），后者允许一定模糊度（走向量检索），两个RAG Skill共用同一套向量模型，但检索策略完全不同。

3. 工程化底座：让AI应用像Web应用一样可靠

3.1 多供应商抽象层：不是API聚合，是能力调度中心

“多供应商”这个词在标题里看似平淡，但在XXL-AI里是整套架构的基石。它不等于“把OpenAI、Anthropic、Moonshot的API Key塞进一个配置文件”。真正的多供应商抽象，要解决三个层次的问题：能力抽象层、路由决策层、质量反馈层。

能力抽象层：把不同模型的能力映射成统一维度。比如Qwen2-72B的“长文本理解”能力评分为92分（基于公开benchmark），Claude-3-Haiku的“代码生成”能力评分为87分，而本地部署的Phi-3-mini在“低延迟响应”上得95分。这些分数不是静态的，而是XXL-AI的Model Profiler定期用真实业务Query跑出来的。
路由决策层：编排引擎根据当前请求的intent和context动态选模型。比如用户问“帮我写个Python脚本”，意图是code_generation，编排引擎会查能力表，发现Claude-3-Haiku得分最高，且当前负载<70%，就路由过去；如果用户接着问“把这个脚本改成能处理CSV文件”，意图变成code_refinement，且上下文里有之前生成的代码片段，引擎会优先选Qwen2-72B（它在代码续写任务上表现更好）。
质量反馈层：每次调用后，SKILL会把实际效果（比如RAG召回相关性、代码执行成功率）作为Feedback事件发回平台，Model Profiler用这些真实数据持续更新能力评分。我见过最狠的案例：某客户把GPT-4 Turbo和国产模型并行跑三个月，发现国产模型在“中文合同条款解析”任务上稳定高出12个百分点，于是自动把该intent的路由权重从30%调到80%。这种闭环，才是多供应商的价值所在——它让模型选择从“拍脑袋”变成“数据驱动”。

3.2 Agent编排：状态机不是终点，是起点

XXL-AI的Agent编排界面看起来像一个高级版状态机编辑器，但它背后是带时间戳的确定性执行引擎。每个节点（Node）不是简单的函数调用，而是包含四个必填字段：input_schema（输入契约）、output_schema（输出契约）、timeout_ms（超时阈值）、retry_policy（重试策略）。比如一个“支付确认”节点，input_schema强制要求包含order_id、user_id、amount_cents三个字段，output_schema规定必须返回{ "status": "success|failed", "receipt_url": "string" }。这种强契约带来两个好处：第一，编排可视化——画布上的连线不是随意拖拽，而是Schema兼容性校验通过后自动生成的；第二，故障可追溯——当某个订单支付失败，平台能精确定位到是哪个节点的output_schema校验没通过（比如返回了"status": "pending"这个非法值），而不是笼统地说“调用失败”。更关键的是，XXL-AI把“状态”本身变成了可编程对象。比如一个贷款审批Agent，需要记录“用户已上传身份证”、“征信报告已获取”、“风控模型已评分”三个状态。传统做法是在数据库里建状态表，XXL-AI的做法是：每个状态变更都是一个MCP消息，由专门的state-manager-skill接收并持久化。这样，状态流转就不再是隐藏逻辑，而是可审计、可回放、可干预的显式消息流。我在做保险理赔Agent时，就利用这个特性实现了“人工介入点”——当风控模型评分低于阈值，自动发一条intent: "escalate_to_human"的MCP消息，触发人工审核流程，整个过程在消息总线上一目了然。

3.3 工程化底座的三大支柱：可观测、可灰度、可回滚

所谓“工程化底座”，不是堆砌技术名词，而是把AI应用的生命周期管理做到和传统Web应用同等成熟度。XXL-AI用三个具体能力支撑这一点：

全链路可观测：不是只看API响应时间，而是追踪每个MCP消息的完整生命周期。从客服Agent发出第一条消息开始，到最终返回给用户，中间经过多少个SKILL、每个SKILL的耗时、RAG召回的Top3结果、模型调用的Token消耗、甚至SKILL内部的CPU/内存使用率，全部聚合在一张Trace图上。特别实用的是“语义Trace”功能——点击Trace里任意一个RAG节点，能直接看到它召回的原始文档片段和高亮匹配词；点击模型调用节点，能看到完整的Prompt和模型返回的Raw Text。这彻底改变了调试方式：以前要翻几十个日志文件找问题，现在在Trace图上点两下就定位到是RAG召回不准还是模型理解偏差。
渐进式灰度发布：SKILL上线不是“全量开关”，而是支持按user_id哈希、session_id前缀、甚至intent类型做流量切分。比如上线一个新的“智能投顾SKILL”，可以先对1%的VIP用户开放，同时监控它的推荐转化率、用户投诉率、与旧SKILL的指标对比。更狠的是“语义灰度”——只对特定类型的提问生效，比如intent: "investment_advice"且payload.risk_tolerance == "aggressive"的请求才走新SKILL。这种粒度，让AI能力迭代真正具备了互联网产品的敏捷性。
秒级回滚机制：SKILL的版本管理不是Git Tag，而是容器镜像+配置快照。每次发布，平台自动保存当前SKILL的Docker镜像ID、skill.yaml内容、依赖的RAG知识库版本号。回滚时，不是重启服务，而是把流量重新指向旧镜像，并恢复对应的配置。实测从发现问题到回滚完成，平均耗时2.3秒。在一次大促期间，我们发现新上线的“优惠券推荐SKILL”在高并发下内存泄漏，从告警到回滚，整个过程用户无感知——后台Trace图上只看到几秒钟的异常毛刺，然后立刻平滑回落。

4. 实操指南：从零搭建一个“设备故障诊断Agent”

4.1 环境准备与最小可行部署

XXL-AI的安装不是“一键脚本”，而是分层部署，确保每个组件职责清晰。官方推荐的最小生产环境是3台服务器：

Control Plane（1台）：运行MCP Registry、SKILL Manager、Trace Collector。配置要求不高，4核8G即可，关键是磁盘IO要稳（存储Trace数据）。
Compute Plane（2台）：运行SKILL Worker和Model Gateway。建议16核32G，GPU非必需（除非跑本地小模型），但SSD是刚需（RAG向量库读取频繁）。

部署步骤严格按顺序：

初始化Control Plane：

# 下载XXL-AI v2.3.0 Control Plane包 wget https://xxl-ai.org/releases/xxl-control-v2.3.0.tgz tar -xzf xxl-control-v2.3.0.tgz cd xxl-control # 修改config.yaml，重点配置： # - storage.type: "minio" （对象存储，存Trace和RAG索引） # - registry.backend: "etcd" （MCP服务发现） # - state_store.type: "redis" （状态存储） vim config/config.yaml # 启动（会自动拉起etcd、MinIO、Redis等依赖） ./start.sh

提示：首次启动会花5-8分钟，因为要初始化ETCD集群和MinIO桶。不要急着Ctrl+C，看logs/control-plane.log里出现MCP Registry ready on port 8080才算成功。

部署Compute Plane：

# 在另外两台机器上执行 wget https://xxl-ai.org/releases/xxl-compute-v2.3.0.tgz tar -xzf xxl-compute-v2.3.0.tgz cd xxl-compute # 配置指向Control Plane的地址 vim config/config.yaml # 修改：control_plane_url: "http://control-plane-ip:8080" # 启动Worker（会自动注册到MCP Registry） ./start-worker.sh

注意：Worker启动后，去Control Plane的Web UI（http://control-plane-ip:8080）的“Workers”页面，应该看到两台机器在线，状态为READY。如果显示REGISTERING超过2分钟，检查防火墙是否放行了8080（Control Plane）和9000（Worker通信端口）。

验证基础连通性：
用curl测试MCP Registry是否工作：

curl -X GET http://control-plane-ip:8080/api/v1/registry/services # 应该返回空数组 []，表示Registry干净

4.2 创建第一个SKILL：“设备型号识别”

这是整个故障诊断Agent的入口节点。目标：从用户描述中精准提取设备型号（如“S7-1200 PLC”、“ABB IRC5控制器”）。

步骤1：创建SKILL目录结构

mkdir -p device-id-skill/{src,config} touch device-id-skill/src/execute.py touch device-id-skill/config/skill.yaml

步骤2：编写核心逻辑（src/execute.py）

import re from typing import Dict, Any # 预定义设备型号正则（实际项目中应从数据库加载） MODEL_PATTERNS = [ (r'S7-\d{4}', 'Siemens S7'), (r'IRC5', 'ABB IRC5'), (r'UR\d+-\d+', 'Universal Robots'), (r'CRX-\d+', 'Fanuc CRX') ] def execute(mcp_message: Dict[str, Any]) -> Dict[str, Any]: # 1. 从MCP消息提取用户原始输入 user_input = mcp_message.get('payload', {}).get('text', '') # 2. 用正则匹配型号 matched_models = [] for pattern, vendor in MODEL_PATTERNS: matches = re.findall(pattern, user_input, re.IGNORECASE) for match in matches: matched_models.append({ "vendor": vendor, "model": match, "confidence": 0.95 if len(matches) == 1 else 0.8 }) # 3. 返回标准化结果 return { "detected_models": matched_models, "raw_text": user_input }

步骤3：定义SKILL契约（config/skill.yaml）

name: "device-id-skill" version: "1.0.0" description: "从用户描述中识别工业设备型号" intent: "identify_device_model" input_schema: type: "object" properties: text: type: "string" description: "用户输入的原始文本" output_schema: type: "object" properties: detected_models: type: "array" items: type: "object" properties: vendor: {type: "string"} model: {type: "string"} confidence: {type: "number"} raw_text: {type: "string"}

步骤4：打包并部署
```
# 在device-id-skill目录下执行 zip -r device-id-skill-1.0.0.zip src/ config/ # 用XXL-AI CLI部署（需先登录） xxl-cli login --url http://control-plane-ip:8080 --token your-admin-token xxl-cli skill deploy --file device-id-skill-1.0.0.zip
```
实操心得：第一次部署失败率很高，90%是因为output_schema和代码返回结构不一致。建议先用xxl-cli skill validate --file device-id-skill-1.0.0.zip本地校验，再部署。校验工具会模拟MCP消息，检查execute()返回值是否符合output_schema定义。

4.3 构建RAG知识库：“PLC故障代码手册”

设备型号识别出来后，下一步是查对应的手册。这里用XXL-AI的RAG Skill机制。

步骤1：准备数据
下载西门子S7-1200故障代码PDF（官网公开文档），用pdfplumber提取文本，按故障代码（如00000001）切分成段落，存为JSONL文件：

{"id": "F00000001", "title": "CPU STOP", "content": "CPU进入STOP模式。可能原因：程序错误、硬件故障...", "metadata": {"vendor": "Siemens", "model": "S7-1200"}} {"id": "F00000002", "title": "Watchdog Error", "content": "看门狗超时。可能原因：循环扫描时间过长...", "metadata": {"vendor": "Siemens", "model": "S7-1200"}}

步骤2：创建RAG Skill
新建plc-rag-skill目录，核心是search.py：

from milvus import MilvusClient import json # 初始化向量库客户端（XXL-AI会注入配置） client = MilvusClient( uri="http://milvus-service:19530", token="plc_rag_token" ) def search(query: str, top_k: int = 3, filter: dict = None) -> list: # 1. 向量化查询 vector = embedder.encode(query) # 2. 混合检索：先按metadata过滤（指定厂商和型号），再向量相似度排序 results = client.search( collection_name="plc_manuals", data=[vector], filter=f"vendor == '{filter.get('vendor')}' and model == '{filter.get('model')}'", limit=top_k, output_fields=["id", "title", "content"] ) return [ { "id": hit["id"], "title": hit["title"], "content": hit["content"], "score": hit["distance"] } for hit in results[0] ]

步骤3：注册RAG Skill
在plc-rag-skill/config/skill.yaml里声明：
```
name: "plc-rag-skill" version: "1.0.0" intent: "search_plc_manual" # ... 其他字段同device-id-skill
```
部署后，在Control Plane UI的“RAG Repositories”里，会看到rag://plc_manuals这个标识，这就是后续SKILL可以声明依赖的URI。

4.4 编排Agent：串联设备识别与故障查询

现在把前面两个SKILL串起来。在XXL-AI Web UI的“Agent Studio”里：

Node 1：Device ID Recognition
- Type:SKILL
- Skill:device-id-skill@1.0.0
- Input Mapping: 将用户输入的text字段映射到SKILL的payload.text
- Output Mapping: 提取detected_models[0].model作为下一个节点的输入
Node 2：PLC Manual Search
- Type:SKILL
- Skill:plc-rag-skill@1.0.0
- Input Mapping:
  - query: 来自Node 1的detected_models[0].model（如"S7-1200"）
  - filter.vendor:detected_models[0].vendor
- Output Mapping: 直接透传RAG返回的results
Node 3：Response Formatter（内置SKILL）
- Type:BUILT-IN
- Function:format_rag_response
- Input: Node 2的results
- Output: 生成自然语言回复，如“您提到的S7-1200 PLC，常见故障代码F00000001表示CPU STOP，可能原因：程序错误...”

常见问题排查：
问题：Node 2总是返回空结果
排查思路：
在Trace图里找到Node 2的调用，复制它的filter参数（如{"vendor": "Siemens", "model": "S7-1200"}）
登录Milvus控制台，执行SELECT * FROM plc_manuals WHERE vendor == 'Siemens' AND model == 'S7-1200'，确认数据存在
检查plc-rag-skill的search.py里，filter参数是否被正确拼接到Milvus查询条件中（注意字符串引号）
经验：Milvus的filter语法很严格，vendor == 'Siemens'正确，vendor = 'Siemens'会报错。XXL-AI的RAG Skill模板里已经加了自动引号包裹，但自定义SQL时容易踩坑。

5. 避坑指南：那些文档里不会写的实战教训

5.1 MCP消息体设计的三大反模式

我在五个项目里都踩过MCP消息设计的坑，总结出必须避开的三种写法：

反模式1：在payload里塞业务实体对象
错误示例：
```
"payload": { "order": { "id": "ORD-123", "items": [{"sku": "SKU-001", "qty": 2}], "customer": {"name": "张三", "phone": "138****1234"} } }
```
问题：Order对象结构会随业务演进不断变化，导致MCP契约频繁失效。正确做法是只传ID和必要字段：
```
"payload": { "order_id": "ORD-123", "required_fields": ["status", "estimated_delivery"] }
```
具体数据由SKILL自己通过内部服务查询。
反模式2：用intent做状态标记
错误示例："intent": "payment_confirmed"、"intent": "payment_failed"
问题：intent应该是动词性的能力声明（confirm_payment），而不是名词性的状态快照。状态应该用context.status字段传递。否则，当支付失败需要重试时，你得注册一个新的retry_paymentintent，契约爆炸。
反模式3：忽略context的时效性
很多人把context当成万能筐，塞用户画像、设备ID、会话ID……但没设TTL。结果一个3天前的会话ID被错误复用，导致RAG召回过期知识。XXL-AI的Context Store默认TTL是30分钟，超过自动清理。务必在context里加expires_at字段，并在SKILL里校验：
```
import time if time.time() > mcp_message.context.get("expires_at", 0): raise ValueError("Context expired")
```

5.2 RAG性能瓶颈的真实根源

别信“向量库慢”的鬼话。我优化过12个RAG项目，性能瓶颈90%不在Milvus，而在数据预处理和查询构造：

瓶颈1：Chunking策略错配
把50页PDF按固定512字符切块，导致故障代码和解决方案被切到不同chunk。正确做法是按语义切分：用NLP模型识别“故障代码：F00000001”作为分隔符，确保每个chunk包含完整的问题-原因-解决方案三元组。XXL-AI的RAG Skill模板里内置了semantic_chunker，但默认关闭，需要手动启用。

瓶颈2：Filter条件未建索引
Milvus的scalar字段（如vendor,model）默认不建索引，filter查询会全表扫描。必须在创建collection时显式声明：

from pymilvus import CollectionSchema, FieldSchema, DataType schema = CollectionSchema([ FieldSchema("id", DataType.INT64, is_primary=True), FieldSchema("vendor", DataType.VARCHAR, max_length=64, index=True), # 关键！ FieldSchema("model", DataType.VARCHAR, max_length=64, index=True), # 关键！ FieldSchema("vector", DataType.FLOAT_VECTOR, dim=768) ])

这个配置在plc-rag-skill的init_collection.py里，但新手常忘记执行。

瓶颈3：Embedding模型不匹配
用text-embedding-ada-002向量化中文PDF，效果必然差。XXL-AI的RAG Skill支持指定embedding模型，但默认是bge-m3。如果你的数据是纯英文技术文档，换成sentence-transformers/all-MiniLM-L6-v2，召回率提升27%。这个参数在plc-rag-skill/config/skill.yaml的embedding_model字段里配置。

5.3 多供应商灰度的致命细节

多供应商不是“AB测试”，而是带业务语义的流量调度。最容易忽略的三个细节：

细节1：模型能力评分的基准Query必须业务相关
别用GLUE benchmark的句子，用你的真实业务Query。比如对“故障诊断”场景，基准Query应该是：“CPU指示灯红色闪烁，触摸屏无响应，可能是什么故障？”——这种Query才能测出模型在工业领域的实际能力。XXL-AI的Model Profiler允许上传CSV格式的基准Query集，每行包含query和expected_intent。
细节2：路由策略的Fallback链必须闭环
设计路由时，不能只写“Qwen2-72B > Claude-3-Haiku”，要定义完整的Fallback链：Qwen2-72B → timeout → Claude-3-Haiku → rate_limit → local_phi3 → error。XXL-AI的路由配置里，每个模型后面必须跟fallback_to字段，否则超时后直接报错。
细节3：供应商密钥的轮换必须原子化
更新OpenAI API Key时，不能先删旧Key再加新Key，中间有毫秒级窗口所有请求失败。XXL-AI的Secret Manager支持“双Key模式”：新Key先激活，旧Key保留24小时，期间所有请求用新Key，旧Key只用于验证存量Token。这个功能在Settings > Secrets里开启，但默认关闭。

5.4 SKILL热更新的隐形陷阱

SKILL号称“热更新”，但实际有三个限制：

限制1：Schema变更必须向后兼容
如果device-id-skill的output_schema从{"model": "string"}改成{"model": "string", "confidence": "number"}，旧版Agent会因缺少confidence字段校验失败。解决方案：新版本用"confidence": {"type": ["number", "null"]}，并设默认值。
限制2：依赖RAG知识库的版本锁定
plc-rag-skill依赖rag://plc_manuals_v2，但rag://plc_manuals_v2本身在更新。XXL-AI默认绑定最新版，可能导致SKILL行为突变。必须在skill.yaml里写死：requires: [rag://plc_manuals_v2@20240520]，用日期戳锁定版本。
限制3：Worker进程的GC延迟
热更新后，旧SKILL的Python进程不会立刻退出，可能残留内存占用。XXL-AI的Worker有max_restarts_per_hour参数，默认5次，超过会强制Kill。建议在config/worker.yaml里调高到20，并监控/metrics接口的skll_worker_restart_total指标。