企业官网建设流程全解析

1. 不是又一个“AI平台”：XXL-AI的底层定位与真实战场

你打开一个叫“XXL-AI”的项目仓库，README第一行写着“AI应用开发平台”，心里大概已经划过三类预设：要么是套壳ChatUI的前端玩具，要么是封装了OpenAI API的简易调用器，要么是又一个试图用低代码拖拽掩盖工程复杂度的PaaS幻觉。但如果你真花20分钟跑通它的最小可运行示例——比如用它把一份PDF技术文档切片、嵌入、再让Agent基于RAG回答“如何配置MCP协议的流式响应头？”——你会立刻意识到：这东西不是来凑热闹的，它是冲着AI工程落地的硬骨头来的。

XXL-AI的核心关键词——Agent编排、多供应商、MCP + SKILL + RAG扩展、工程化底座——每一个都不是装饰性标签，而是直指当前AI应用开发中四个最痛的关节：

• Agent编排解决的是“多个AI能力如何像齿轮一样咬合运转”，而不是单个LLM调用；
• 多供应商意味着它不绑定OpenAI或某家大模型API，而是把模型调用抽象成可插拔的“供应商插槽”，你在config里换一行配置就能从Qwen切到Claude，甚至接入本地部署的Phi-3；
• MCP + SKILL + RAG不是堆砌术语，而是一套分层扩展机制：MCP（Model Control Protocol）负责定义AI能力的标准化接口契约，SKILL是可复用、可测试、可版本管理的原子能力单元（比如“解析Excel表格”或“调用GIS空间分析API”），RAG则被设计成可插拔的知识增强模块，支持文本、表格、甚至结构化JSON Schema的混合检索；
• 工程化底座才是它真正的护城河——它内置了完整的CI/CD流水线模板、带trace ID的全链路日志、基于Prometheus的指标埋点、以及生产级的Agent状态持久化方案（支持Redis和PostgreSQL双后端）。

我第一次在客户现场部署XXL-AI时，他们正为一个“智能工单助手”项目卡在第三周：前端团队写不出稳定的Agent状态管理逻辑，后端团队抱怨RAG检索结果忽好忽坏，算法团队每次改完embedding模型都要手动重跑整个pipeline。而XXL-AI的xxl-agent-cli init --template=service-ticket命令，直接生成了一个包含Docker Compose、GitHub Actions CI脚本、Prometheus监控配置、以及预置了MCP-SKILL-RAG三层结构的完整骨架。我们只用了两天就完成了从零到上线——不是因为功能多炫酷，而是因为它把那些本该由SRE、DevOps、架构师共同填的坑，提前铸进了底座里。

它不承诺“三天上线AI应用”，它承诺“上线后三个月不因架构缺陷推倒重来”。这才是它和市面上90%所谓“AI平台”的本质区别：前者卖的是愿景，后者卖的是止损成本。

2. MCP协议：让AI能力像USB设备一样即插即用

很多人看到“MCP”第一反应是查“Unreal Engine 5.8 MCP”或者“Altium Designer AI接口MCP”，以为这是某个垂直工具的私有协议。但在XXL-AI语境下，MCP（Model Control Protocol）是一个轻量级、HTTP-based、面向AI能力服务化的接口规范，它的设计哲学非常朴素：让任何AI能力——无论是调用大模型、执行Python脚本、还是调用企业内部ERP接口——都能以统一方式被发现、被调用、被编排。

MCP的核心不是复杂，而是克制。它只定义三个必选字段：

POST /mcp/invoke HTTP/1.1 Content-Type: application/json { "skill_id": "gis-spatial-analysis-v2", "input": { "geometry": "POLYGON((...))", "buffer_distance_km": 5 }, "metadata": { "trace_id": "req-abc123", "timeout_ms": 30000 } }

响应也极简：

{ "status": "success", "output": { "area_km2": 124.7, "intersected_roads": ["G102", "S312"] }, "metadata": { "latency_ms": 2416, "model_used": "qwen2.5-72b" } }

为什么这个设计能解决实际问题？举个真实场景：某制造企业需要一个“设备故障诊断Agent”，它必须串联三个能力：1）用OCR识别维修手册PDF中的电路图；2）调用内部知识库（RAG）匹配历史相似故障案例；3）调用MES系统API查询该设备最近72小时的传感器时序数据。如果每个能力都用不同SDK、不同鉴权方式、不同错误码体系，编排逻辑会迅速变成意大利面条。而MCP强制所有能力提供者遵守同一契约——你不需要知道OCR服务是用PaddleOCR还是LayoutParser实现的，只需要确认它暴露了/mcp/invoke端点，并返回符合schema的output。

XXL-AI的MCP Server组件（默认集成在xxl-core服务中）做了三件关键事：

• 自动注册发现：当一个新SKILL服务启动时，它会向XXL-AI的Consul或Nacos注册自己的skill_id和健康检查端点，无需人工维护服务列表；
• 超时熔断与重试：在metadata.timeout_ms超时后自动中断请求，并根据配置策略（如指数退避）重试，避免单个慢服务拖垮整个Agent流程；
• 标准化错误处理：所有MCP响应必须包含status字段，error_code需映射到统一枚举（如MCP_ERR_TIMEOUT=1001,MCP_ERR_AUTH_FAILED=1002），编排引擎据此决定是降级、重试还是终止流程。

提示：MCP不是RPC框架，它不解决序列化性能问题，也不替代gRPC。它的价值在于“契约统一”而非“性能极致”。我们在压测中发现，MCP带来的HTTP开销约增加3~5ms延迟，但换来的是跨团队协作效率提升300%——运维不再需要为每个AI服务单独配置反向代理，前端不再需要为每个能力写不同的错误提示文案，算法团队交付一个新SKILL时，只需提供Docker镜像和MCP接口文档，编排工作由产品同学用可视化画布完成。

一个常被忽略的细节是MCP的skill_id命名规范。XXL-AI强制要求skill_id采用domain-category-name-version格式，例如finance-invoice-extract-v1.3。这看似琐碎，实则解决了两个致命问题：一是避免不同团队开发的同名SKILL（如都叫pdf-parser）在注册中心冲突；二是为后续的灰度发布打下基础——编排引擎可以按version路由流量，比如将10%请求发给v1.4，90%留在v1.3。

3. SKILL：可测试、可复用、可审计的AI原子能力单元

在XXL-AI里，“SKILL”不是一段Python函数，也不是一个LangChain Chain，而是一个严格定义的、带生命周期管理的工程化单元。它的目录结构被强制约定：

my-skill/ ├── skill.yaml # SKILL元信息：id, version, description, input_schema, output_schema ├── Dockerfile # 必须基于xxl-skill-base镜像构建 ├── main.py # 入口文件，必须实现mcp_invoke(input: dict) -> dict ├── tests/ # 单元测试目录，必须覆盖边界case └── docs/ # 使用说明、性能基准、依赖清单

这个结构背后是深刻的工程考量。我们曾接手一个客户项目，其原有AI能力散落在十几个Jupyter Notebook里，每个Notebook都用不同版本的transformers库，参数硬编码在注释里，没有测试用例。当需要将“合同条款抽取”能力迁移到新环境时，光是解决依赖冲突就花了四天。而XXL-AI的SKILL机制，从源头上杜绝了这种混乱。

skill.yaml是SKILL的“身份证”。它强制声明input_schema和output_schema，使用JSON Schema语法。例如一个RAG检索SKILL的schema可能长这样：

input_schema: type: object properties: query: type: string minLength: 1 maxLength: 500 top_k: type: integer minimum: 1 maximum: 100 default: 5 output_schema: type: object properties: results: type: array items: type: object properties: content: type: string score: type: number source_id: type: string

这个schema的价值远不止类型校验：

• 编排时自动生成表单：可视化编排器读取schema后，自动为query字段渲染文本输入框，为top_k渲染滑块，默认值5直接显示；
• 测试用例生成：xxl-skill-test工具能基于schema自动生成边界测试用例（如空字符串query、负数top_k），并验证output是否符合约束；
• 文档自动同步：xxl-doc-gen命令扫描所有SKILL的yaml，一键生成Swagger风格的API文档站，连curl示例都自动生成。

Dockerfile的强制要求更是关键。XXL-AI提供官方xxl-skill-base:python3.11基础镜像，预装了PyTorch、transformers、langchain等常用库，并固化了/app/skill挂载路径。这意味着：

• 所有SKILL在相同环境中运行，消除了“在我机器上能跑”的魔咒；
• 镜像大小被严格限制（≤800MB），通过多阶段构建剔除build-time依赖；
• 安全扫描成为标准流程——CI流水线会自动用Trivy扫描镜像CVE漏洞，高危漏洞（CVSS≥7.0）直接阻断发布。

最体现工程思维的是tests/目录。XXL-AI要求每个SKILL必须包含三类测试：

1. 单元测试（unit test）：验证main.py中mcp_invoke函数逻辑，mock外部依赖（如向向量数据库发起请求）；
2. 集成测试（integration test）：在真实Docker容器中启动SKILL，调用其MCP端点，验证端到端行为；
3. 性能基线测试（benchmark test）：测量在标准硬件（4c8g）上，处理1000条样本的P95延迟和内存占用，结果存入Git LFS，作为后续版本对比基准。

注意：XXL-AI的CI流水线会拒绝合并任何未通过全部测试的PR。我们曾因一个SKILL的集成测试偶发超时（P95=1201ms，阈值1200ms）而回滚发布——这看起来严苛，但正是这种“不妥协”让线上故障率下降了76%。因为你知道，任何一个上线的SKILL，都经过了和生产环境一致的验证。

SKILL的版本管理也遵循语义化版本（SemVer）。v1.2.0表示向后兼容的功能增强，v2.0.0表示破坏性变更（如input_schema结构调整）。编排引擎支持按版本精确引用，例如skill_id: "rag-knowledge-search-v1.2"，避免了“最新版”带来的不可控风险。

4. RAG扩展：不只是文本检索，而是多模态知识协同中枢

当别人还在争论“RAG知识库能不能存图片”时，XXL-AI的RAG扩展模块已经把这个问题拆解成了三个可独立演进的子系统：文本切片器（Text Splitter）、多模态嵌入器（Multimodal Embedder）、混合检索器（Hybrid Retriever）。它不假设你的知识源只有PDF，也不预设你只用OpenAI的text-embedding-3-large——它的设计目标是：让知识增强能力像乐高积木一样，按需组合。

先说最常被问的“图片存储”问题。XXL-AI的RAG不直接存储原始图片二进制，而是走一条更工程化的路径：

• 图片预处理SKILL：一个独立的SKILL，接收图片URL或base64，调用CLIP模型生成图像嵌入向量，并用OCR提取文字描述，最终输出结构化JSON：

  { "image_id": "img_abc123", "embedding_vector": [0.12, -0.45, ...], "ocr_text": "设备型号：XYZ-7000，序列号：SN20240001", "caption": "工业机器人控制面板特写，显示红色报警灯" }

• 向量数据库：存储embedding_vector，用于相似图片检索；
• 关系型数据库：存储ocr_text和caption，用于关键词精确匹配；
• 混合检索器：收到用户查询“报警灯亮起怎么办？”时，同时发起向量相似度搜索（找相似图片）和全文检索（找含“报警灯”的文本段落），再用加权融合算法（如RRF）合并结果。

这种分离设计带来了巨大灵活性。比如客户想替换OCR引擎，只需更新image-preprocessSKILL，不影响RAG核心逻辑；想升级CLIP模型，只需更换嵌入器SKILL，向量库自动兼容新向量维度。

XXL-AI的RAG扩展还深度集成了知识图谱（KG）能力。它允许你将结构化知识（如设备维修手册的XML Schema、ERP系统的实体关系图）导入，生成三元组（subject-predicate-object），并存入Neo4j。检索时，RAG引擎能自动触发图查询：当用户问“XYZ-7000型号的备件有哪些？”时，引擎不仅检索文本，还会遍历KG找到<XYZ-7000, hasSparePart, SP-123>关系，将SP-123的详细规格文本一并召回。

更关键的是RAG的可观测性。XXL-AI在RAG流程中埋点了五个关键指标：

• retriever_latency_ms：从发起检索到拿到结果的时间；
• retriever_recall_rate：召回结果中真正相关片段的比例（通过人工标注样本计算）；
• reranker_score_variance：重排序后分数的标准差，反映结果质量一致性；
• chunk_overlap_ratio：切片重叠率，过高说明切片策略有问题；
• embedding_dimension_mismatch：向量维度不匹配告警（如旧库用768维，新模型用1024维）。

这些指标实时推送至Prometheus，运维人员能在Grafana看板上一眼看出：是切片策略导致召回率低，还是嵌入模型退化导致向量漂移。我们曾用此定位到一个客户知识库的“瓶颈”——不是模型问题，而是PDF解析SKILL将表格内容转成了无意义的空格分隔字符串，导致embedding丢失关键结构信息。修复解析逻辑后，召回率从52%跃升至89%。

提示：XXL-AI的RAG调试模式（--debug-rag）会在日志中打印每一步的中间结果：原始PDF页、切片后的文本块、每个块的embedding向量哈希、检索到的top5 chunk ID及原始内容、重排序后的分数。这比任何“黑盒”RAG框架都更容易定位问题根源。

5. Agent编排：从流程图到可执行状态机的跨越

XXL-AI的Agent编排不是简单的“拖拽节点连线条”，而是将业务逻辑编译成可持久化、可中断、可审计的状态机。它的编排DSL（Domain Specific Language）设计得像伪代码一样直白，却暗含对分布式系统可靠性的深刻理解。

一个典型的工单诊断Agent编排定义（agent.yaml）如下：

name: "ticket-diagnosis-v3" description: "诊断设备故障工单，联动OCR、RAG、MES" states: - name: "extract-circuit-diagram" type: "skill" skill_id: "ocr-pdf-extract-v1.1" input: pdf_url: "{{ .ticket.attachments[0].url }}" timeout: 30s retry: max_attempts: 2 backoff: "exponential" - name: "search-fault-history" type: "rag" input: query: "{{ .circuit_diagram.caption }}" top_k: 3 fallback: to_state: "fallback-to-human" - name: "fetch-sensor-data" type: "skill" skill_id: "mes-sensor-query-v2.0" input: device_id: "{{ .ticket.device_id }}" hours: 72 timeout: 45s transitions: - from: "extract-circuit-diagram" to: "search-fault-history" condition: "{{ .status == 'success' }}" - from: "search-fault-history" to: "fetch-sensor-data" condition: "{{ len(.results) > 0 }}" - from: "search-fault-history" to: "fallback-to-human" condition: "{{ len(.results) == 0 }}"

这个DSL的关键创新在于状态（state）与转换（transition）的分离。每个state定义了要执行什么（skill或rag）、输入是什么、超时重试策略；而transitions定义了“成功后去哪”、“失败后去哪”、“满足什么条件去哪”。这种分离让编排逻辑既清晰又健壮。

为什么这比传统流程图更可靠？因为XXL-AI的编排引擎会将这个DSL编译成一个状态快照（State Snapshot），每执行完一个state，就将当前上下文（包括所有变量、临时结果、trace_id）序列化存入PostgreSQL。这意味着：

• 如果Agent在fetch-sensor-data步骤因网络抖动失败，引擎不会重跑整个流程，而是从该state恢复，重试最多2次；
• 运维人员可在后台查看任意工单的完整执行轨迹，精确到每个state的开始时间、结束时间、输入参数、输出结果、错误堆栈；
• 审计合规要求“所有AI决策可追溯”时，只需导出该工单的状态快照链，就是一份天然的审计日志。

编排引擎还内置了动态条件路由能力。condition字段支持Jinja2模板语法，但XXL-AI对其做了安全加固：禁止eval、import等危险操作，只开放len()、==、>等基础函数。更重要的是，它支持异步等待（async wait）。例如，当MES系统API返回“数据正在生成，请稍后查询”时，编排引擎不会轮询，而是将state标记为WAITING，设置一个wait_until时间戳（如5分钟后），届时自动唤醒继续执行。这避免了无谓的资源消耗。

我们曾用这套编排机制重构了一个保险理赔Agent。旧系统用Python脚本硬编码流程，一次重大故障导致3000+工单积压，排查耗时17小时。新系统上线后，同样故障发生时，运维人员登录后台，筛选出所有状态为WAITING的工单，批量修改wait_until为立即执行，5分钟内全部恢复——因为每个环节都是解耦的、可观察的、可干预的。

6. 工程化底座：让AI应用像传统Web服务一样可靠

XXL-AI的“工程化底座”不是一堆锦上添花的工具集合，而是一套贯穿开发、测试、部署、运维全生命周期的强制性实践规范。它不教你怎么写prompt，而是确保你写的prompt无论在哪台服务器上运行，行为都完全一致。

底座的第一道防线是环境一致性。XXL-AI强制所有服务（core、agent、rag、skill）使用同一套Docker Compose模板，其中：

• networks定义了xxl-net，所有服务必须加入此网络，禁用host网络；
• volumes预定义了/data/rag-indexes、/data/skill-logs等标准化路径；
• secrets通过Docker Swarm或K8s Secret注入敏感配置，禁止明文写入env文件。

第二道防线是可观测性三位一体：

• Logging：所有服务必须使用xxl-logger库，自动注入trace_id、span_id、service_name，日志格式为JSON，字段名统一（如level、msg、duration_ms）；
• Metrics：暴露/metrics端点，指标命名遵循xxl_<component>_<operation>_<status>_total规范（如xxl_rag_retrieve_success_total），所有counter、gauge、histogram都预定义了label（service,skill_id,model）；
• Tracing：集成Jaeger，每个MCP调用、每个RAG检索、每个Agent state都生成span，父子关系通过trace_id关联。

第三道防线是发布与回滚自动化。XXL-AI的CI/CD流水线（基于GitHub Actions）包含七个强制阶段：

1. lint：检查YAML、Python代码风格；
2. test：运行所有SKILL单元测试、集成测试、性能基线测试；
3. scan：Trivy镜像扫描、Semgrep代码安全扫描；
4. build：构建Docker镜像，打sha256摘要标签；
5. push：推送到私有Harbor仓库；
6. deploy-staging：部署到预发环境，自动运行Smoke Test（调用健康检查端点）；
7. deploy-prod：人工审批后，滚动更新生产环境，旧版本镜像保留7天供回滚。

最体现工程深度的是状态持久化设计。XXL-AI的Agent状态不存于内存，而是存于PostgreSQL的agent_state表，结构如下：

这个设计让“长周期Agent”成为可能。例如一个需要等待用户邮件回复的审批Agent，它可以进入WAITING状态，数小时后由邮件监听SKILL触发唤醒，从断点继续执行。而传统内存型Agent在此场景下必然丢失状态。

经验分享：我们曾在一个政务项目中，因PostgreSQL连接池配置不当（max_connections=100），导致高并发时Agent状态写入超时，引发连锁失败。解决方案不是简单调大连接数，而是引入连接池中间件PgBouncer，并将agent_state表按tenant_id分表。这印证了XXL-AI底座的价值——它不隐藏复杂性，而是把复杂性暴露出来，逼你用工程方法解决。

底座还包含生产就绪的监控告警规则。Prometheus预置了23条告警规则，例如：

• XXL_RAG_RETRIEVER_LATENCY_HIGH：RAG检索P95延迟 > 3s持续5分钟；
• XXL_SKILL_FAILURE_RATE_HIGH：某SKILL失败率 > 5%持续10分钟；
• XXL_AGENT_STATE_STUCK：WAITING状态超过24小时未更新。
  这些告警直接对接企业微信/钉钉机器人，附带快速跳转链接，直达Grafana看板和日志查询页面。

7. 实战复盘：从零搭建一个“GIS空间分析Agent”

现在，让我们用一个具体案例，把前面所有概念串起来：用XXL-AI快速构建一个“城市内涝风险分析Agent”。这个Agent接收市民上传的积水照片，自动识别位置，叠加GIS地图数据，分析周边排水设施承载力，并生成处置建议。

7.1 环境准备与骨架生成

首先，确保已安装Docker、Docker Compose v2.20+、Python 3.11+。然后执行：

# 安装XXL-AI CLI工具 pip install xxl-ai-cli # 初始化项目骨架（选择gis-template） xxl-ai-cli init --name="flood-risk-agent" --template=gis # 目录结构自动生成 flood-risk-agent/ ├── docker-compose.yml # 预配core、rag、postgres、redis ├── xxl-config/ # 配置中心，含mcp、skill、rag等配置 ├── skills/ # 存放所有SKILL │ ├── gis-location-extract/ # 从图片提取GPS坐标 │ └── gis-drainage-analysis/ # 分析排水设施承载力 ├── rag/ # RAG知识库配置 │ └── drainage-specs/ # 排水管道规格文档 └── agents/ # Agent编排定义 └── flood-risk.yaml

7.2 开发第一个SKILL：gis-location-extract

进入skills/gis-location-extract，编辑skill.yaml：

skill_id: "gis-location-extract-v1.0" version: "1.0.0" description: "从积水照片EXIF中提取GPS坐标" input_schema: type: object properties: image_url: type: string format: "uri" output_schema: type: object properties: latitude: type: number minimum: -90 maximum: 90 longitude: type: number minimum: -180 maximum: 180 confidence: type: number minimum: 0 maximum: 1

main.py实现核心逻辑（使用exifread库）：

def mcp_invoke(input: dict) -> dict: import exifread import requests from io import BytesIO # 下载图片 resp = requests.get(input["image_url"]) img_bytes = BytesIO(resp.content) # 解析EXIF tags = exifread.process_file(img_bytes, details=False) lat = tags.get("GPS GPSLatitude") lon = tags.get("GPS GPSLongitude") if lat and lon: # EXIF坐标是度分秒格式，需转换 def dms_to_dd(dms): degrees = float(dms.values[0].num / dms.values[0].den) minutes = float(dms.values[1].num / dms.values[1].den) / 60 seconds = float(dms.values[2].num / dms.values[2].den) / 3600 return degrees + minutes + seconds lat_dd = dms_to_dd(lat) if lat.values[0].num > 0 else -dms_to_dd(lat) lon_dd = dms_to_dd(lon) if lon.values[1].num > 0 else -dms_to_dd(lon) return { "latitude": round(lat_dd, 6), "longitude": round(lon_dd, 6), "confidence": 0.95 } else: return { "latitude": 0.0, "longitude": 0.0, "confidence": 0.0, "error": "No GPS data found" }

编写测试用例tests/test_main.py，验证EXIF缺失时返回默认值。运行xxl-skill-test通过后，构建镜像：

docker build -t xxl-skill-gis-location-extract:v1.0 .

7.3 构建RAG知识库：排水设施规格

将《城市排水管网设计规范》PDF放入rag/drainage-specs/，运行初始化命令：

# 启动RAG服务 docker-compose up -d rag # 初始化知识库（自动切片、嵌入、入库） xxl-ai-cli rag init --path="./rag/drainage-specs" --name="drainage-specs" --embedding-model="bge-m3"

bge-m3是XXL-AI推荐的多语言、多粒度嵌入模型，特别适合处理含表格、公式的工程文档。

7.4 编排Agent：flood-risk.yaml

编辑agents/flood-risk.yaml：

name: "flood-risk-analysis" description: "分析积水照片，评估内涝风险" states: - name: "extract-location" type: "skill" skill_id: "gis-location-extract-v1.0" input: image_url: "{{ .input.image_url }}" timeout: 20s - name: "query-drainage-capacity" type: "rag" input: query: "距离({{ .extract-location.latitude }}, {{ .extract-location.longitude }})500米范围内，排水管道的设计最大流量是多少？" top_k: 1 fallback: to_state: "use-default-capacity" - name: "analyze-risk" type: "skill" skill_id: "gis-drainage-analysis-v1.0" input: location: lat: "{{ .extract-location.latitude }}" lon: "{{ .extract-location.longitude }}" capacity: "{{ .query-drainage-capacity.results[0].content }}" transitions: - from: "extract-location" to: "query-drainage-capacity" condition: "{{ .extract-location.confidence > 0.5 }}" - from: "extract-location" to: "use-default-capacity" condition: "{{ .extract-location.confidence <= 0.5 }}" - from: "query-drainage-capacity" to: "analyze-risk" - from: "use-default-capacity" to: "analyze-risk" input: capacity: "200 L/s"

7.5 部署与验证

# 启动全部服务 docker-compose up -d # 注册SKILL（自动发现） curl -X POST http://localhost:8080/mcp/register \ -H "Content-Type: application/json" \ -d '{"skill_id":"gis-location-extract-v1.0","endpoint":"http://gis-location-extract:8000/mcp/invoke"}' # 调用Agent curl -X POST http://localhost:8080/agent/flood-risk-analysis \ -H "Content-Type: application/json" \ -d '{"input":{"image_url":"https://example.com/flood.jpg"}}'

返回结果将包含风险等级、建议措施、以及所有中间步骤的trace_id，便于全链路追踪。

这个案例展示了XXL-AI如何将“AI能力碎片”组装成“可交付业务价值”。它不追求炫技，而是用工程化手段，把AI从实验室玩具变成产线上的可靠零件。

8. 避坑指南：那些只有踩过才懂的实战细节

在数十个XXL-AI项目交付中，我们总结出五条血泪教训，它们不会出现在官方文档里，却是决定项目成败的关键：

8.1 MCP超时设置的“黄金三角”

很多团队在配置MCPtimeout_ms时，习惯性设为“足够大”，比如10秒。但这是陷阱。正确做法是建立黄金三角关系：

• MCP timeout=SKILL内部处理超时+网络RTT+缓冲余量
• SKILL内部处理超时必须小于MCP timeout，否则MCP层无法捕获超时；
• 网络RTT在跨AZ部署时可能达200ms，需实测；
• 缓冲余量建议设为500ms，用于应对瞬时抖动。

我们曾在一个金融项目中，将MCP timeout设为5000ms，而SKILL内部超时设为4800ms。结果在流量高峰时，SKILL因GC停顿超时，但MCP层未及时中断，导致线程堆积，最终OOM。解决方案是：SKILL内部超时设为4000ms，MCP timeout设为4500ms，余量500ms。

8.2 RAG切片策略的“语义完整性”陷阱

默认的RecursiveCharacterTextSplitter按字符切分，极易把表格、代码块、公式切成两半。XXL-AI推荐使用MarkdownHeaderTextSplitter或HTMLHeaderTextSplitter，但前提是你的PDF必须先转成高质量HTML（用pdf2htmlEX而非pdfminer）。我们曾用pdfminer解析一份设备手册，表格被转成无序的<p>标签，切片后完全丢失结构。换成pdf2htmlEX后，表格保留<table>标签，切片器能识别<h2>标题，确保每个切片包含完整章节。

8.3 SKILL镜像的“依赖地狱”规避法

requirements.txt中写transformers>=4.30.0看似合理，但不同SKILL可能依赖不同版本的torch，导致镜像构建失败。XXL-AI底座要求：

• 所有SKILL必须使用pyproject.toml而非requirements.txt；
• pyproject.toml中[build-system]指定requires = ["setuptools>=45", "wheel"]；
• dependencies中禁止使用>=，必须写死版本（如transformers = "4.38.2"）；
• CI流水线会检查pip list输出，拒绝任何未声明的包。

8.4 Agent状态持久化的“事务边界”

agent_state表的更新必须与业务操作在同一数据库事务中。例如，在analyze-riskSKILL成功后，不仅要更新agent_state，还要在ticket表中标记“已分析”。如果这两个操作不在同一事务，