企业官网建设流程全解析

1. 从 Demo 到生产：Agent 落地最容易被低估的那道坎

做 Agent 的人大概都有过这种体验：本地跑一个 ReAct 循环，接上几个工具，问它“帮我查一下上个月的销售数据”，它噼里啪啦调几个 API 就把答案吐出来了，那一刻你会觉得通用智能体已经成了。可一旦把这个东西推到真实企业环境里，让它去对接 OA 的审批流、ERP 的采购单、CRM 的客户档案，画风立刻变了——模型还是那个模型，工具调用还是那套工具调用，但整个系统就是跑不起来，或者跑起来了也三天两头出问题。

这个项目标题里那句“难的不是模型，是把 OA、ERP 接进来”，说的就是这件事。Agent本身的能力边界，在过去一年里被各种框架和模型推得很快，但企业里真正值钱的数据和流程，几乎全部锁在OA、ERP这类老牌系统里。这些系统往往有十几年的历史，接口风格五花八门，权限模型复杂，字段命名自成一套黑话。你让一个通用 Agent 直接去理解“致远 OA 的会签节点”和“泛微 e10 的建模引擎”，它大概率会一脸茫然。

MCP（Model Context Protocol）的出现，本质上是想给这件事提供一个标准答案：把“模型怎么调用外部能力”这件事协议化，让工具提供方和模型消费方解耦。而FDE（Forward Deployed Engineer，前沿部署工程师）这个角色，恰恰就是站在“模型能力”和“企业现场”中间的那批人。他们既懂 Agent 的编排逻辑，又得钻进 OA、ERP 的泥潭里把数据捞出来。这个项目标题把 FDE、MCP、Blade 三个词放在一起，指向的其实是一套面向企业现场的 Agent 集成方法论。

这篇文章适合谁看？如果你正在做 Agent 的企业落地，或者你是那个被派去“把 AI 接进公司系统”的人，又或者你只是好奇 MCP 到底解决了什么真问题，那接下来的内容应该能帮你少走几个月的弯路。我会从整体设计思路讲到具体实操，把 OA、ERP 接入 Agent 时那些文档里不会写的坑，一个个摊开来说。

2. 整体设计思路：为什么是 MCP + FDE + Blade 这套组合

2.1 先搞清楚 MCP 到底在解决什么问题

很多人第一次接触 MCP，会把它和“又一个 Agent 框架”混为一谈。其实不是。MCP 是一个协议，你可以把它理解成“AI 世界的 USB-C 接口”。在 MCP 之前，每个 Agent 框架都有自己的工具定义方式：LangChain 有 Tool，OpenAI 有 Function Calling，各家 IDE 有各自的插件机制。结果是，你为一个框架写好的工具，换一个框架就得重写一遍。

MCP 把这件事拆成了三层：Host（承载模型的应用，比如 IDE、聊天客户端）、Client（协议客户端，负责和 Server 通信）、Server（能力提供方，暴露工具、资源、提示词）。模型通过 Host 发起调用，Client 把请求翻译成 MCP 协议消息，Server 执行完把结果返回。整个链路里，模型不需要知道工具背后是数据库还是 HTTP 接口，Server 也不需要知道调用它的是哪个模型。

这个解耦带来的直接好处是：你为企业 OA、ERP 写的 MCP Server，可以被任何支持 MCP 的 Host 复用。今天用 A 客户端，明天换 B 客户端，Server 不用动。对于 FDE 来说，这意味着一次集成投入，能覆盖多个 Agent 入口，ROI 一下子就上来了。

注意：MCP 是软件协议层面的概念，和硬件接口协议不是一回事。热词里有人问“mcp 是软件协议还是硬件协议那个概念叫什么来着”，答案就是它属于应用层协议，类比的是 LSP（Language Server Protocol）那种“编辑器与语言服务解耦”的思路。

2.2 FDE 这个角色为什么在企业 Agent 项目里不可替代

FDE 这个概念最早在 Palantir 那类公司被大量使用，核心职责是“带着工程能力冲到客户现场，把产品改造成客户真正能用的样子”。放到 Agent 项目里，FDE 要干的事非常具体：理解客户的业务流程、摸清 OA/ERP 的数据结构、设计工具边界、处理权限和审计、最后把 Agent 调到“业务人员敢用”的程度。

为什么模型工程师干不了这个活？因为模型工程师的舒适区是 prompt、评测集、推理链路，而 FDE 的战场是“致远 OA 的自定义控件怎么取数”“泛微 e10 的初始密码策略是什么”“ERP 进销存的手机版接口有没有开放”。这些问题的答案不在论文里，在客户的机房里、在厂商的私有文档里、在某个老员工的口头传承里。

标题里的Blade我理解为一套面向 FDE 的集成工具集或脚手架，它的价值在于把“重复的脏活”标准化：连接管理、鉴权、字段映射、错误重试、审计日志。FDE 不需要每次都从零写一个 OA 适配器，而是基于 Blade 提供的骨架，专注在业务语义的映射上。

2.3 为什么不能直接让 Agent 调 OA/ERP 的原生接口

有人会问：OA、ERP 本来就有 API，为什么不让 Agent 直接调？我试过，直接调的结果通常是灾难。原因有三层。

第一层是接口风格不统一。致远 OA 的自定义控件、泛微的建模引擎、ERP 的进销存模块，它们的接口可能是 SOAP、可能是 REST、可能是某种私有 RPC，参数命名一个用驼峰一个用下划线，时间格式一个用时间戳一个用字符串。Agent 每次调用都要重新理解一遍，token 消耗巨大且容易出错。

第二层是权限和审计。企业系统里的操作不是“能调就行”，而是要记录“谁在什么时间以什么身份调了什么”。如果 Agent 直接用超级管理员账号调接口，出了事根本没法追溯。MCP Server 这一层正好可以插入统一的身份透传和审计日志。

第三层是语义鸿沟。ERP 里的“采购订单”有几十个字段，Agent 需要的是“帮我看看哪些订单快逾期了”。这个转换如果让模型每次现场推理，既慢又不稳定。正确的做法是在 MCP Server 里把业务语义封装成高层工具，比如list_overdue_purchase_orders，模型只需要调这一个工具。

2.4 整体架构的分层设计

把这套东西画成架构，大概是这样的分层：

这个分层的关键在于适配层。它把“企业系统的脏乱差”全部吸收掉，向上暴露干净的 MCP 工具。FDE 的主要工作量也集中在这一层。下面我会把这一层的实操细节拆开讲。

3. 核心细节解析：OA、ERP 接入 Agent 的关键环节

3.1 工具边界的划分：什么该封装成 MCP 工具

这是最容易做错的一步。新手 FDE 常犯的错误是“一个接口一个工具”，结果 MCP Server 暴露了上百个工具，模型在选择时直接懵掉。正确的做法是按业务动作而不是技术接口来划分工具。

举个例子，ERP 里查采购订单可能涉及三个接口：查订单头、查订单行、查供应商信息。如果拆成三个工具，模型得先调第一个拿到订单号，再调第二个拿行项目，再调第三个拿供应商名，中间任何一步失败整个链路就断了。更好的做法是封装成一个get_purchase_order_detail工具，内部并行调三个接口再组装。

我一般用这个标准来判断：如果一个工具的名字需要用“然后”来连接两个动作，那它就应该被合并。比如“查订单然后查明细”应该是一个工具，“查订单”和“取消订单”应该是两个工具，因为后者是独立的业务动作。

实操心得：工具描述（description）比工具本身更重要。模型选工具全靠这段文字，所以要写清楚“什么时候用这个工具”“返回什么”“有什么限制”。我见过太多项目因为工具描述写得太潦草，导致模型该调的时候不调、不该调的时候乱调。

3.2 字段映射：OA 黑话到业务语义的翻译

OA 和 ERP 的字段命名往往带着强烈的历史痕迹。致远 OA 里可能叫fd_xxx，泛微里可能叫field_yyy，ERP 里可能是拼音缩写。Agent 不可能理解这些，所以必须在适配层做映射。

映射不是简单的改名，而是要处理几类特殊情况：

• 枚举值翻译：ERP 里订单状态可能是0/1/2/3，要翻译成“待审核/已审核/已发货/已完成”。
• 编码转名称：部门存的是编码，要关联到部门名称。
• 多值字段拆分：一个字段里塞了多个值用逗号分隔，要拆成数组。
• 空值语义：有些系统用null表示空，有些用空字符串，有些用-1，要统一。

我通常会在 Blade 里维护一份映射配置表，用 YAML 或 JSON 描述，这样业务变化时改配置就行，不用改代码。下面是一个简化的映射配置示例：

entity: purchase_order source: erp_purchase fields: - source: order_id target: orderId type: string - source: status target: status type: enum mapping: "0": pending_review "1": approved "2": shipped "3": completed - source: dept_code target: department type: lookup lookup: department_master

这份配置的好处是，FDE 在客户现场改字段时，不需要重新部署整个 Server，热加载配置即可。

3.3 鉴权与身份透传：别让 Agent 变成超级管理员

这是企业项目里最敏感的部分。Agent 调 OA、ERP 时，用谁的身份？如果用服务账号，那所有操作在审计日志里都是同一个“人”，出了问题查不到源头。如果用用户身份，那就要解决“Agent 怎么拿到用户凭证”的问题。

我的做法是双层鉴权：MCP Client 侧携带用户身份令牌，MCP Server 侧验证令牌后，用该用户的权限去调 OA/ERP。这样每个操作都能追溯到具体的人。具体实现上，令牌可以通过 MCP 的请求上下文传递，Server 在每次工具调用时从上下文里取出用户身份。

注意：千万不要把 OA/ERP 的管理员凭证硬编码在 MCP Server 里。我见过一个项目，Server 配置里明文写着泛微 e10 的初始密码，结果代码一提交到仓库，整个内网都知道了。凭证必须走密钥管理服务，且要定期轮换。

3.4 错误处理：Agent 最怕的不是失败，是沉默

OA、ERP 这类系统有个特点：它们经常“静默失败”。接口返回 200，但 body 里写着{"success": false, "msg": "..."}。如果 MCP Server 不处理这种情况，Agent 会以为调用成功了，然后基于错误的数据继续推理，最后给出一个看似合理实则荒谬的答案。

所以适配层必须做响应规范化：把所有系统的返回统一成{success, data, error}结构。失败时，error 里要带上足够的信息让模型能判断“是重试还是放弃”。比如“网络超时”可以重试，“权限不足”就不该重试，应该直接告诉用户。

我一般会把错误分成三类：

3.5 审计日志：出了事能说清楚

企业客户对 Agent 的信任是逐步建立的，而审计日志是建立信任的基础。每一次工具调用，都要记录：谁调的、什么时候调的、调了什么工具、参数是什么、返回了什么、耗时多久。

这些日志不能只存在 MCP Server 本地，要能对接到企业的日志平台。我通常会把日志同时输出到两个地方：一个是本地的结构化日志文件，方便 FDE 排查；另一个是企业的日志服务，方便合规审计。

日志里有个细节要注意：敏感字段要脱敏。比如客户手机号、身份证号，记录时要打码。但脱敏不能影响排查，所以我会保留字段的哈希值，需要时可以用哈希去比对。

4. 实操过程：从零搭一个能接 OA 和 ERP 的 MCP Server

4.1 环境准备与依赖选型

先说技术栈。MCP Server 的官方 SDK 有 Python 和 TypeScript 两个版本，我两个都用过，选哪个主要看团队背景。Python 版本生态更成熟，和数据处理库结合方便；TypeScript 版本类型定义更严格，适合大型项目。这个项目我以 Python 为例，因为 FDE 现场经常要快速写脚本验证。

依赖清单大概是这样：

pip install mcp httpx pydantic pyyaml python-dotenv

• mcp：官方 SDK，提供 Server 和 Client 的实现。
• httpx：异步 HTTP 客户端，用来调 OA/ERP 接口。
• pydantic：数据校验，定义工具参数和返回结构。
• pyyaml：读映射配置。
• python-dotenv：管理环境变量。

实操心得：httpx 一定要用异步版本。OA/ERP 接口响应慢是常态，同步调用会把整个 Server 堵死。我一开始用 requests，结果并发一上来就超时，换成 httpx.AsyncClient 后问题消失。

4.2 定义第一个 MCP 工具：查采购订单

先写一个最简单的工具，把 ERP 的采购订单查询封装起来。核心代码如下：

from mcp.server import Server from mcp.types import Tool, TextContent import httpx from pydantic import BaseModel class PurchaseOrderQuery(BaseModel): status: str | None = None department: str | None = None limit: int = 20 server = Server("erp-adapter") @server.list_tools() async def list_tools(): return [ Tool( name="list_purchase_orders", description="查询采购订单列表。当用户询问采购订单、采购进度、供应商订单时使用。支持按状态和部门过滤。", inputSchema=PurchaseOrderQuery.model_json_schema() ) ] @server.call_tool() async def call_tool(name: str, arguments: dict): if name == "list_purchase_orders": query = PurchaseOrderQuery(**arguments) async with httpx.AsyncClient(timeout=10.0) as client: resp = await client.get( f"{ERP_BASE_URL}/api/purchase/orders", params=query.model_dump(exclude_none=True), headers={"Authorization": f"Bearer {get_user_token()}"} ) data = resp.json() normalized = normalize_orders(data) return [TextContent(type="text", text=format_for_llm(normalized))]

这段代码有几个关键点。description里明确写了“什么时候用”，这是给模型看的。inputSchema用 Pydantic 自动生成，保证参数校验。返回前做了normalize_orders和format_for_llm，前者统一字段，后者把数据转成模型容易理解的文本格式。

4.3 接入致远 OA 的审批流

致远 OA 的审批流接入是另一个典型场景。OA 的接口通常需要先登录拿 session，再用 session 调业务接口。这个登录态管理如果放在每次工具调用里做，效率极低。我的做法是在 Server 启动时维护一个连接池，按用户维度缓存 session。

class OAConnector: def __init__(self): self._sessions: dict[str, tuple[str, float]] = {} async def get_session(self, user_id: str) -> str: cached = self._sessions.get(user_id) if cached and cached[1] > time.time(): return cached[0] session = await self._login(user_id) self._sessions[user_id] = (session, time.time() + 1800) return session async def _login(self, user_id: str) -> str: # 从密钥服务拿用户凭证，调 OA 登录接口 ...

这里有个坑：OA 的 session 过期时间往往不固定，有的 30 分钟，有的 2 小时，而且过期时不一定返回 401，可能返回一个“请重新登录”的 HTML 页面。所以除了缓存过期时间，还要在响应解析时检测这种“伪成功”，一旦发现就清缓存重登。

4.4 处理泛微 OA 的会签与非会签差异

泛微 OA 的会签和非会签流程在数据结构上差异很大。会签节点有多个审批人，每个人有独立的审批状态；非会签节点只有一个审批人。如果 Agent 不区分这两种情况，就会把会签流程误判为“还没审批”。

我的处理方式是在适配层做归一化：不管底层是会签还是非会签，统一暴露成approval_steps数组，每个元素包含approver、status、comment、timestamp。会签节点展开成多个元素，非会签节点就是一个元素。这样模型看到的永远是统一结构。

def normalize_approval(raw: dict) -> list[dict]: steps = [] for node in raw.get("nodes", []): if node.get("type") == "countersign": for approver in node.get("approvers", []): steps.append({ "approver": approver["name"], "status": map_status(approver["status"]), "comment": approver.get("comment", ""), "timestamp": approver.get("time") }) else: steps.append({ "approver": node["approver"]["name"], "status": map_status(node["status"]), "comment": node.get("comment", ""), "timestamp": node.get("time") }) return steps

4.5 用 Blade 脚手架管理多系统连接

当你要同时接 OA、ERP、CRM 三个系统时，代码会迅速膨胀。Blade 这类脚手架的价值就是把公共逻辑抽出来：连接管理、重试、日志、鉴权、字段映射。我一般会定义一个BaseConnector抽象类，各个系统的 Connector 继承它，只实现差异部分。

class BaseConnector(ABC): @abstractmethod async def _do_request(self, method: str, path: str, **kwargs) -> dict: ... async def request(self, method: str, path: str, **kwargs) -> dict: for attempt in range(3): try: resp = await self._do_request(method, path, **kwargs) return self._normalize(resp) except TransientError: if attempt == 2: raise await asyncio.sleep(2 ** attempt)

这样新增一个系统时，FDE 只需要写_do_request和_normalize两个方法，其他都是继承来的。实测下来，一个新系统的接入时间从两三天压缩到半天。

4.6 本地调试与联调技巧

MCP Server 的调试有个麻烦：它不像普通 HTTP 服务那样能用 curl 直接测。我的做法是写一个简单的 MCP Client 脚本，模拟 Host 发起调用：

from mcp.client import ClientSession, StdioServerParameters async def test(): params = StdioServerParameters(command="python", args=["server.py"]) async with ClientSession(params) as session: await session.initialize() tools = await session.list_tools() print("可用工具:", [t.name for t in tools.tools]) result = await session.call_tool( "list_purchase_orders", {"status": "pending_review", "limit": 5} ) print(result)

这个脚本能快速验证工具是否注册成功、参数是否正确、返回是否符合预期。联调阶段我一般会准备一批测试用例，覆盖正常查询、边界条件、错误场景，每次改完代码跑一遍。

实操心得：MCP Server 的日志一定要打到 stderr，不要打 stdout。因为 stdio 传输模式下 stdout 是协议通道，往里写日志会破坏协议帧，导致 Client 解析失败。这个坑我踩过一次，排查了大半天才发现是日志惹的祸。

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

5.1 工具调用失败的高频原因速查

下面这张表是我在实际项目中整理出来的，覆盖了八成以上的工具调用问题：

5.2 OA 接口“连接被阻止”类报错的排查

热词里有个问题很典型：“泛微 OA 添加外部地址作为目录报错连接被阻止，因为它是由公共页面启动的”。这类问题本质是 OA 的安全策略在拦截外部调用。排查思路是：先确认 OA 是否开启了白名单，再确认调用方的来源是否在允许列表里，最后看是不是 HTTPS 证书问题。

我的经验是，OA 这类系统的安全配置往往分散在多个地方：网关一层、应用一层、数据库一层。排查时要逐层确认，不要只盯着应用日志。有时候网关返回 403，但应用日志里什么都没有，因为请求根本没到应用。

5.3 Agent 执行中断的定位方法

“agent execution terminated due to error”这个报错很笼统，可能的原因包括：工具调用超时、上下文超长、模型返回格式错误、MCP 连接断开。定位时我一般按这个顺序排查：

1. 看 MCP Server 日志，确认工具调用是否正常返回。
2. 看 Host 日志，确认模型是否正常生成。
3. 看网络层，确认 MCP 连接是否稳定。
4. 看上下文长度，确认是否触发了截断。

其中最常见的是上下文超长。OA、ERP 返回的数据往往很冗长，如果不做裁剪直接塞给模型，很容易撑爆上下文。我的做法是在适配层做结果摘要：只返回模型真正需要的字段，长列表只返回前 N 条加总数。

5.4 权限相关的坑与规避

权限问题在企业项目里特别隐蔽。有一次 Agent 查采购订单一直返回空，排查半天发现是服务账号没有采购模块的查看权限。还有一次，Agent 能查但不能改，因为写操作需要额外的审批权限。

规避这类问题的办法是在 Server 启动时做权限自检：用配置的账号去调几个关键接口，确认权限正常，不正常就启动失败并告警。这样问题在部署阶段就暴露，而不是等到用户用的时候才发现。

注意：不同用户的权限可能不同，所以权限自检只能验证服务账号，用户维度的权限要在实际调用时处理。我的做法是，权限不足时返回明确的错误信息，让 Agent 告诉用户“你没有权限查看这个数据”，而不是返回空结果让用户困惑。

5.5 性能优化的几个实用手段

OA、ERP 接口慢是常态，优化手段主要有三个。第一是缓存：对于变化不频繁的数据（如部门列表、供应商列表），在 Server 侧缓存几分钟。第二是并行：一个工具内部需要调多个接口时，用asyncio.gather并行。第三是分页：大结果集不要一次拉全，按需分页。

我实测过一个场景：查一个部门的全部采购订单，串行调三个接口耗时 4.2 秒，改成并行后降到 1.6 秒，加上缓存后重复查询只要 0.1 秒。这个提升对用户体验的影响是决定性的。

5.6 上线前的检查清单

在把 MCP Server 推到生产前，我一般会过一遍这个清单：

• 所有工具都有清晰的 description 和 inputSchema。
• 所有下游调用都有超时和重试。
• 所有响应都做了规范化，没有静默失败。
• 鉴权走的是用户身份透传，没有硬编码凭证。
• 审计日志完整，敏感字段已脱敏。
• 权限自检通过，关键接口可访问。
• 有降级方案，MCP Server 挂了不影响主业务。
• 有监控告警，异常能第一时间发现。

这份清单看起来简单，但每一条背后都是踩过的坑。尤其是最后两条，很多项目上线时根本没考虑，结果 Server 一挂，整个 Agent 功能全废，用户直接失去信任。

6. 一些关于 FDE 和 Agent 落地的个人体会

做这类项目做多了，我越来越觉得 FDE 的核心能力不是写代码，而是翻译。把业务语言翻译成技术语言，把 OA 的黑话翻译成模型能懂的结构，把客户的模糊需求翻译成可执行的工具边界。MCP 和 Blade 这类工具能帮你省掉重复劳动，但翻译这件事，短期内还得靠人。

还有一个体会是，企业 Agent 项目的成败，往往不取决于模型多强，而取决于第一个月用户愿不愿意用。如果 Agent 第一次查数据就返回了错误结果，用户可能再也不会打开它。所以前期宁可工具少一点、场景窄一点，也要保证每个上线的工具都是稳的。我一般会先做一个“只读”版本的 Agent，让它稳定跑两周，建立信任后再逐步开放写操作。

最后分享一个实用的小技巧：在 MCP Server 里加一个health_check工具，返回各个下游系统的连通状态。这样 Agent 在遇到问题时，可以先调这个工具确认是系统故障还是自己的问题，避免盲目重试。这个工具看起来不起眼，但在排查问题时能省下大量时间。