企业官网建设流程全解析

过去两年我一直在折腾 AI 应用开发。最早的项目很简单，一个聊天窗口接上大模型 API，再丢几篇文档进向量库，一天就能看到效果。可等你想把它从“能跑的 Demo”变成“团队每天都在用的生产系统”，问题立刻就变味了：Agent 编排逻辑应该写在哪一层？同时接了三家模型厂商的 Key，限流和成本怎么统一管？MCP、SKILL、RAG 这些扩展到底是各做各的，还是应该收拢到一个平台体系里？没有工程底座兜底，AI 应用越多，烂账越多。

XXL-AI 是我今年持续推进的一个 AI 应用开发平台项目，目标是把 Agent 编排、多供应商模型接入、「MCP + SKILL + RAG」扩展能力，以及权限、观测、灰度发布这类工程化底座都收拢到一个平台里。这篇文章不打算做概念科普，我想以一个开发者的视角，拆解这类平台在设计时真正花时间的地方在哪，方案是怎么取舍的，以及落地过程中踩过哪些坑。适合两类人看：一类是想自建 AI 应用平台的团队，另一类是正在集成 Agent、MCP、RAG 但总觉得代码越写越乱的开发者。

1. 当 AI 应用从“单次对话”走向“Agent 任务流”，平台要解决的第一个问题不是模型

很多人以为做 AI 应用平台，第一步是选模型。实际不是。模型能力当然重要，但平台和 Demo 的区别，首先体现在“让一次调用变成一条可稳定执行的任务链路”。

1.1 从“对话应用”到“任务应用”：复杂度发生的是数量级变化

一个聊天机器人，你只需要维护一个上下文窗口，模型回什么就是什么。但一旦进入 Agent 场景，系统要自己规划步骤、调用工具、根据结果决定下一步动作，复杂度会爆炸式增长。

我在 XXL-AI 里最先做的一件事，不是写模型调用代码，而是给“一次 Agent 执行”定义清晰的执行模型。简单说，就是解决三个问题：

• Agent 拿到用户目标后，如何拆解出执行计划；
• 计划中的每一步调什么工具、用什么模型、传什么参数；
• 模型判断错误或工具执行失败时，系统如何重试、降级，还是终止。

这三个问题之所以不能散落在业务代码里，是因为它们出现的频率太高。每个 Agent 应用都会遇到，而且处理逻辑高度相似。如果每个应用各写一套，后面排错会非常痛苦。

在 XXL-AI 里，我把 Agent 执行抽象成一个循环器（Agent Loop），核心思路是：让模型产出结构化决策，由平台执行决定，平台执行结果再回传给模型继续决策。这样做的好处是编排逻辑可以被统一观测，坏处是需要严格约束模型的输出格式，否则解析那一关就会挂掉。

1.2 XXL-AI 的总体模块划分：四层模型加一条扩展总线

如果给 XXL-AI 画一张架构简图，大概是这样的分层：

再加上一条横向的“多供应商模型网关”，它不隶属任何一层，而是所有层都需要调用的基础服务。这个划分并不是一开始就定的，是在做了两三个业务应用之后，发现重复代码全挤在一起，才被迫拆出来的。

我把经验总结成一句话：AI 应用平台的架构工作，本质上是给“模型的不可预测性”上保险，而不是把模型能力包得越薄越好。模型调用只是起点，决定平台上限的是编排、扩展和工程底座。

2. Agent 编排层：控制流、状态机与多 Agent 协作

Agent 编排是整个 XXL-AI 最核心也最容易写乱的部分。这里我展开讲讲用到的三种关键机制：编排循环、协作模式和状态管理。

2.1 编排的本质：把“模型决策”变成“可执行计划”

我见过不少团队的 Agent 代码，其实就是在一个 while 循环里反复调模型，把工具调用结果拼进 prompt，然后等模型下一次输出。这种写法在小 demo 里没问题，但 Production 环境需要更严格的表达。

XXL-AI 的编排循环大致长这样：

def run_agent(task, context): plan = planner.plan(task, context) # 第一步：模型产出计划 for step in plan.steps: if step.type == "tool": result = execute_tool(step.tool_name, step.params) # 平台执行工具 context.add_step_result(step.id, result) elif step.type == "llm": output = call_llm(step.prompt, context) # 模型生成内容 context.add_step_result(step.id, output) # 每次步骤结束后，允许模型修正后续计划 plan = planner.plan_with_feedback(task, context, plan) return plan.final_answer

这段话简化了，但你看到了重点：计划、执行、反馈、再计划，这个循环就是编排的本质。平台需要做的是给这个循环提供稳定的承载，而不是让每个 Agent 都自己实现一遍。

如果模型返回的工具调用意图不清晰，我会在解析层多做一次校验，必要时直接中断执行而不是盲目重试。这能避免很多脏数据。

2.2 多 Agent 协作的三种模式：顺序、路由、层级

多 Agent 编排是热门词里高频出现的概念，但很多人把多 Agent 想得太玄。实际落地时，XXL-AI 里最常用的是三种协作模式：

• 顺序协作：Agent A 的输出传给 Agent B，适合流水线式处理，比如先写大纲再写正文再润色。
• 路由分发：一个路由器 Agent 根据用户意图把任务分给不同的专家 Agent，比如客服场景分给退款、售后、技术咨询这三个子 Agent。
• 层级协作：主管 Agent 拆解目标后，分派给多个工人 Agent 并行执行，最后汇总结果。适合研究分析类任务。

这三种模式我一开始都想在编排引擎里做成可视化拖拽，后来放弃了。原因很现实：可视化编排适合固定流程，但 Agent 的特点是流程会动态变化。最终方案是“固定骨架 + 动态步骤”：骨架可以用可视化配置，具体步骤由模型在运行时决定。

2.3 状态管理与会话记忆：必须独立的存储结构

Agent 跑起来之后，最容易被忽视的就是状态管理。一个任务执行到第三步，模型输出了一段中间结果，这时用户断开连接，你怎么办？进程重启了怎么办？

XXL-AI 的状态存储我采用的是独立会话仓储，不放在内存里，而是落库，包含这几个字段：

这里有个细节：context_window 不直接存全部历史消息，而是存“摘要 + 关键消息引用”。因为多步执行后，完整对话历史会超过模型上下文长度，全量塞回去既浪费 token 又拉慢响应。我会提供一个压缩器，在每轮后检查长度，超限就生成摘要并丢弃中间细节。这个设计让长任务能稳定跑下去，不会跑着跑着就“记忆溢出”。

3. 多供应商模型网关：统一接口后面的工程账本

标题里写了“多供应商”，这绝对是平台类项目里绕不开的硬骨头。XXL-AI 在接入模型供应商上的原则是：对业务层隐藏供应商差异，对运维层暴露全部细节。

3.1 供应商抽象层：接口、鉴权、流控、配额

业务代码最怕的就是下一代模型出了，到处要改参数。XXL-AI 的模型网关对外提供一个统一接口，字段覆盖主流供应商的公共语义：

{ "model": "provider_model_name", "messages": [{"role": "user", "content": "你好"}], "temperature": 0.7, "max_tokens": 2048, "tools": [], "stream": false }

返回结构同样统一，包括 content、tool_calls、usage(tokens)、latency_ms 等字段。

在网关内部，每个供应商都有一个适配器，负责做三件事：

• 鉴权：每个供应商的 Key 独立加密存储，网关统一注入，业务层永远拿不到原始 Key；
• 流控：按供应商和模型维度做令牌桶限流，避免一个应用的突发流量打爆另一个应用；
• 配额：根据团队或项目的月度预算做配额控制，超限后自动降级或拒绝。

这套设计的核心价值不在于省事，而在于可审计。谁在什么时间用哪个模型调了多少 token，全部有记录。没有这道墙，成本失控只是一夜之间的事。

3.2 路由、自动降级与按任务分发策略

多供应商最容易犯的错误是“平均主义”——这个模型便宜就全部用它，那个模型聪明就全切过去。实际上应该按任务类型分发。

XXL-AI 支持路由策略配置，常用的一种做法是标签路由：

网关在检测到首选供应商超时或返回特定错误码时，自动切换到降级链路；同时把降级事件写入监控日志。这个机制上线之后，我用一个深夜流量高峰测试过：首选供应商持续报错 5 分钟，平台整体成功率只掉了 2%，因为大部分请求都被自动切到了备选链路。

3.3 成本观测：token 计量和按项目分摊

说了半天模型，最后必须回到钱。XXL-AI 中有一个成本看板，按项目维度统计每天的 token 消耗、费用估算和调用量趋势。这个看板的数据来源就是网关里每一笔请求的 usage 字段。我们会把字段归一化为统一的 token 单位，再按供应商的报价表计算费用。

这块的坑在于：供应商对 token 的计费口径不一样，有的按字符，有的按 token，有的按图像尺寸。归一化如果不做，成本看板就是一堆对不上的数字。我这里主张在网关出口就完成归一化，而不是把原始账丢给上层自行折算。另外，token 浪费往往出在“无用的长上下文”：我会定期拉出 token 消耗 Top 10 的会话，看看到底是业务需要长上下文，还是代码里把历史消息无脑全塞了。每次都优化出不少成本。

4. MCP 扩展：让 Agent 不挑工具的协议标准

MCP（Model Context Protocol）是“工具太多、各自为政”这个困境的产物。接入 XXL-AI 之前的教训是：每个 Agent 都定义自己的一套工具 JSON Schema，同一个搜索引擎功能，在客服 Agent 里写一遍，在数据分析 Agent 里又写一遍，维护成本直线上升。

4.1 MCP 到底解决什么问题

MCP 把工具调用协议标准化了：Agent 平台和外部工具之间通过统一协议通信，工具方只要实现一个 MCP Server，任何支持 MCP 的客户端都能直接调用它。听起来很简单，但意义很大，因为它让“工具生态”不再是某个 Agent 的私有资产，而是平台级的公共资源。

在 XXL-AI 里，我把 MCP 接入设计成一个独立网关服务，而不是直接写在 Agent 代码里。这样 Agent 和工具之间是解耦的，Agent 只知道工具名和入参，不知道工具部署在哪里、怎么鉴权。

4.2 MCP Server 接入设计：生命周期、工具列表拉取、调用转发

接入一个 MCP Server，大致流程如下：

1. 在平台后台录入 MCP Server 的连接信息（SSE、Stdio 或 Streamable HTTP）；
2. 网关主动拉取 Server 声明的工具列表，缓存下来并生成统一工具描述；
3. Agent 运行时加载工具列表，把工具描述注入模型 Prompt 或作为 function schema；
4. Agent 发起工具调用请求，网关转发给目标 Server，拿到结果后回传给 Agent。

这里我遇到过最大坑是连接类型。很多入门教程只讲本地 Stdio 模式，也就是从进程子进程拉起一个脚本，适合开发和单机部署。但生产环境里，工具往往分布在不同的服务器上，必须用 HTTP/SSE 模式。我们后来把 Stdio 模式限定在开发环境，线上全部走 HTTP，否则服务一多，网关的进程管理会变成噩梦。

4.3 实操中容易翻车的三个细节

• 超时设定：MCP 工具调用不像本地函数，外部服务可能很慢。如果不设超时，Agent 会一直在等待工具返回，整个任务卡死。我在网关层统一设了默认 30 秒超时，长任务可以配置到 2 分钟，超时后返回一个工具执行失败的错误给 Agent。
• 鉴权令牌的过期问题：MCP Server 常用短期令牌认证,令牌过期后网关不会自动知道。所以网关必须捕获 401/403 状态码并触发重新认证流程,而不是直接当作工具调用失败。
• JSON Schema 与模型的兼容性：MCP 工具描述里的入参 Schema 可能非常复杂，但模型对复杂嵌套 JSON Schema 的理解力有限。最好在网关层做一次 Schema 简化，只暴露必填参数和简单枚举。这个步骤看着简单，却能让工具调用的成功率提高一大截。

5. SKILL 机制：把可复用的“能力包”做成一等公民

MCP 解决的是“工具被别人调用”的问题，SKILL 解决的是“把一段常用能力沉淀下来”的问题。在 XXL-AI 中，SKILL 是比 Tool 更上层的抽象，它可能包含 Prompt、代码、参数校验和示例。

5.1 什么是 SKILL：从提示词片段到能力包

最早的 SKILL 其实就是团队内部沉淀的提示词模板。比如“代码审查提示词”“竞品分析框架”，每个成员复制到自己的项目里，改一改就能用。问题是没有版本管理，改了一版之后，别人还在用旧版，效果参差不齐。

后来我们把 SKILL 做成一个可加载、可版本化、可组合的资源包。一个 SKILL 不只是一段文本，它可以包含执行逻辑。比如“SQL 生成技能”，这套 SKILL 内部可以定义生成步骤：先判断数据表结构、再生成 SQL、再用校验器检查 SQL 是否包含危险操作、最后输出给用户。这些步骤完全由 SKILL 的代码决定。

SKILL 的目录结构通常长这样：

skill_sql_generator/ ├── SKILL.md # 技能描述、适用场景、参数定义 ├── main.py # 技能主逻辑，可调用模型与工具 ├── validators.py # 输出校验（如 SQL 安全检查） ├── examples/ # few-shot 示例 ├── assets/ # 额外资料、参考文档 └── metadata.json # 版本、作者、依赖 SKILL 列表

引入这套规范后，团队里“贡献技能”变得特别自然。谁写成了一套好的分析 Prompt，顺手就能打包成一个 SKILL 放到仓库里，别人直接引用，不需要看内部实现。

5.2 SKILL 与 MCP、RAG 如何协同

SKILL 不是孤立的。一个标准的数据分析 SKILL，内部很可能会调用 MCP 暴露的数据库查询工具，也可能会检索 RAG 知识库里存放的企业指标口径文档。这就是我把三者放在同一标题下的原因——它们是平台“扩展层”的三个支柱：

• MCP 管“能调什么”；
• SKILL 管“怎么调才能稳定产出”；
• RAG 管“模型不知道但业务需要的知识从哪来”。

实现上，XXL-AI 在 Agent 运行时会对 SKILL 做依赖注入：SKILL 声明它需要哪些 MCP 工具和哪个知识库，运行时由平台自动装配。这样业务开发者写技能时不用关心 MCP Server 在哪、知识库索引怎么建，只用声明式写法挂依赖即可。

5.3 SKILL 市场与权限控制

SKILL 多了之后，需要做市场化的管理。我们建了内部技能市场，展示技能列表、版本、作者和调用成功率。权限上，每个 SKILL 可以指定可见范围，按项目组隔离。这块经验是：默认不公开，显式授权才可见，省去很多安全审核的麻烦。

6. RAG 扩展：知识库管线里最容易被高估的是“向量检索”

RAG（检索增强生成）几乎是 AI 应用开发平台的标配，但多数人对 RAG 的理解停留在“文档切碎 -> 向量化 -> 向量检索 -> 拼进 Prompt”。真正落地时，这条链路每一步都有坑，而且向量相似度只是检索质量的下限保障。

6.1 文档摄入链路：解析、清洗、分块、嵌入、元数据

XXL-AI 的知识库模块，文档进入后的第一步不是切块，而是解析和清洗。以 PDF 为例，很多 PDF 是扫描件，不先做 OCR 就切块，进去的全是乱码。Word 和 HTML 同样有格式噪声需要消除，比如页眉页脚、导航栏、广告区块。

我自定义了一套摄入管线，主要节点覆写了这几个能力：

• 解析：按文档类型选择解析器，PDF/Word/HTML/Markdown 各自独立处理；
• 清洗：去掉页眉页脚、重复段落、乱码字符、无用超链接；
• 分块：优先按语义边界（标题、段落）分块，而不是固定的 512 字硬切；
• 增强元数据：每块记录来源文档、页码、标题路径、更新时间；
• 嵌入：按供应商能力选择 embedding 模型，支持批量向量化；
• 异步索引：文档更新后增量刷新索引，而不是全库重建。

分块是其中对效果影响最大的环节。我试过很多分块策略，最终参考的指标是“检索命中后的问答效果”，而不是分块字符数。有些场景固定分块比较好，有些场景语义分块更好，所以 XXL-AI 把分块策略做成可配置项，不同的知识库可以用不同策略。

6.2 检索增强的隐藏问题：召回、排序和重排

只做向量检索是不够的。向量检索对同义改写效果不错，对专有名词和精确 ID 却常常失误。比如用户搜索“XXL-AI 的离线任务重启 API 参数”，如果文档里写的是“restart_job(pool_name, job_id)”，向量检索很可能召不回来，但关键词检索能直接命中。所以生产系统普遍采用混合检索：向量召回 + 关键词召回（BM25），再做融合。

XXL-AI 的检索管线目前是：

1. 同时执行向量检索和关键词检索，各自取 Top N；
2. 用 RRF（Reciprocal Rank Fusion）或加权打分合并结果；
3. 关键场景再上一路 Reranker 模型，对候选结果重新排序；
4. 按最终分数截断 TopK，再拼进 Prompt。

很多人问：Reranker 是不是必须的？我的经验是：如果知识库规模小，Top 20 以内直接拼 Prompt 也能接受；但知识库一旦上千篇文档，不重排就有大量低质量片段混入上下文，模型会被错误信息带偏。Reranker 带来的提升不是一点半点。

6.3 图片能进 RAG 知识库吗

热门词里专门有人问“RAG 知识库能不能存图片”，这是个好问题。答案是能存，但要想清楚存什么。

图片直接存二进制没有意义，RAG 检索的是文本空间。当前可行的做法有两类：

• 图片 + 描述文本：为每张图片生成说明文字，检索时只匹配描述文本；回答时把图片URL和描述一起给模型；
• 多模态嵌入：用多模态模型同时把图片和文字映射到向量空间，实现图文混合检索。

第一种实现成本低，检索精度可控；第二种效果上限高，工程复杂度和成本也明显更高。XXL-AI 当前默认走第一种，图片入库时会自动调用视觉模型生成一段结构化描述，并把图片地址作为元数据存储。这样既解决了检索问题，又保留了图片本身。

6.4 结构化知识为什么需要不同姿势

纯文档型知识适合向量库，但表格、条目、知识图谱这类结构化数据，硬塞进向量库会失真。这就是“Ontology RAG”和“GraphRAG”这类方向的出发点。我们的经验是：不要迷信一种方案，很多企业知识库最大痛点恰恰是“文档里的表格字段对不上”，这时候应该先做结构化抽取，把表结构转成可检索的字段记录，再配合文本检索一起进上下文。GraphRAG 适合关系密集型知识，但对大多数团队来说，第一版没有必要上这么重。

7. 工程化底座：权限、可观测、灰度与发布，才是“平台”和“Demo”的分水岭

这一章讲的是那些不性感但绝不能少的部分。Agent 应用比传统应用多了一层不确定性：模型输出不可预期、外部工具不可控、知识库持续更新。没有工程底座，任何一个不可预期都可能引发线上事故。

7.1 统一工作空间、项目隔离与角色权限

多个团队共用平台，隔离是第一优先。XXL-AI 的资源模型是：平台 -> 团队 -> 项目 -> 应用/知识库/技能。每个项目有独立空间，项目成员按角色分配权限：

权限控制的粒度可以讨论，但底线原则是“开发权限和发布权限分离”。否则开发改了一段编排，顺手就推到线上，没有任何把关，AI 应用的更新就会变成事故制造机。

7.2 调用链追踪与可观测性

Agent 应用的可观测性和普通接口不同。一个用户请求进来，可能触发三四个模型调用、五六个工具调用、两三次知识库检索，最后才生成答案。如果链路不能完整追踪，故障排查基本靠猜。

我在 XXL-AI 里强制要求：每个 Agent 执行链路生成一个 trace_id，所有模型调用、工具调用、知识库检索都带上这个 ID。日志中心按 trace_id 聚合，就能看到“用户在 14:32 发起提问，14:32:05 触发模型 A，14:32:06 触发工具 MCP-B，14:32:08 检索知识库 C，14:32:09 返回结果”。任何一步慢或失败，都能快速定位。

另外，还需要记录“模型输入了哪些上下文”。Agent 类应用的很多问题，根源不是模型笨，而是上下文中拼入的检索片段本身就是错的。有了 trace 就能回看当时模型到底看到了什么，排查效率完全不一样。

7.3 灰度发布、版本管理与回滚

Agent 应用的发布，最怕“改了提示词导致对话质量下降”。这类质量问题是隐性的，单元测试覆盖不到。所以 XXL-AI 必须支持版本化发布：

1. 开发的 Agent 应用每次保存都生成新版本并附 Release Note；
2. 发布时将流量按百分比灰度到新版本，比如先 5% 再 50%；
3. 灰度期间对比新旧版本的核心指标，包括调用成功率、工具调用成功率、平均耗时、用户反馈标记；
4. 指标异常自动回滚到上一稳定版本。

这里的关键是：灰度指标必须有“质量面”，不能只看“系统没报错”。我会让灰度应用的用户追加一个“这次回答满意吗”的反馈按钮，即使只有 1% 的点击率，也比没有任何反馈的指标强得多。AI 应用的可用性，最终取决于使用者的主观感受，这一点越早认识到越好。

8. 落地几个月后，我复盘的几个真实教训

如果把这几个月在 XXL-AI 上的经历浓缩成几句话，我想说是下面几条。它们不是理论推演，都是被线上问题逼出来的。

8.1 “能力不是越多越好”：MCP 工具和 SKILL 产生决策噪声

最初我们把 MCP Server 和 SKILL 一股脑全接进 Agent，认为能力越全越聪明。结果模型面对几十个工具描述时，经常选错工具或者犹豫不决。后来改成“按场景最小化注入”，系统为每个 Agent 应用配置一份白名单，只注入可能用到的工具和技能。效果立竿见影，工具选择准确率明显回升。做平台要多提供可能性，但 Agent 运行时要做减法。

8.2 模型供应商“平均主义”行不通

多供应商不是简单地把每个模型接入进来就完事。不同模型在代码、推理、摘要、工具调用上的表现差异很大。我在平台上维护了一个“模型能力评分表”，按任务类型定期更新，路由策略尽量基于这个评分表而不是价格。曾经为了省成本，把代码生成流量全切到一个便宜模型上，结果工具调用成功率跌了三成，用户反馈全是“答非所问”。后来加回质量导向的模型，整体体验才回来。省钱要从 token 优化里省，不能从模型质量上省。

8.3 测试 Agent 应用不能只测端到端

Agent 应用输出是概率性的，同样的输入可能得到不同的回答，传统“一个测试用例管一条路径”的方式完全不适用。我现在的经验是分层测试：

• 单元层：测试工具函数本身、Prompt 渲染逻辑、Skill 的校验器；
• 确定性测试：用固定模型参数和历史快照，验证输出结构是否稳定；
• 回放测试：收集线上真实请求，用新版本跑一遍，对比旧版本的回答质量和工具调用；
• 人工评测：抽检灰度的对话记录，按标准打分。

最后一项虽然最费人力，但也最有价值。单纯依赖自动化，测不出回答“合理但平庸”和“精准且优秀”的差别。

8.4 平台建设是持续工程，不是一次性项目

XXL-AI 做到现在，功能列表已经比最初设想的多了两倍。回头看，真正让平台有价值的不是某个炫酷功能，而是“能力沉淀 + 规范约束 + 可观测”这三件事。Agent 应用开发的门槛正在快速降低，但把它做成能长期稳定运行的系统底座，依然需要持续投入。

如果你正在规划类似平台，我个人的建议是：先跑通一个最小闭环，再逐层补位。先把单一供应商、单一 MCP 工具、一个知识库跑起来，不要急着追求大而全。等慢慢感受到“东西多了以后到底哪里疼”，再决定平台该往哪个方向延伸，那时候加的功能才真正能消化掉。