FDE 交付实战营

Appearance

5.4 遗留系统集成与 MCP 适配层 ​

承前：本体和语义层把"世界应该长什么样"定义好了，但青禾的世界有一半活在遗留系统里：老 CRM 只有半本人肉维护的接口文档，POS 机的数据格式五年没统一过，还有一台跑了八年的库存服务器没人敢碰。这一节讲 FDE 在这类环境里的生存术——怎么用 MCP（Model Context Protocol）在遗留系统和 Agent 之间架一层适配器，怎么划安全边界，以及"负债区/隔离区/资产区"的代码分层纪律。

5.4.1 遗留系统的真实面貌 ​

"接口文档缺失、格式不统一"这八个字，落到现场是这样的：

  • 老 CRM 的"接口"是一个每晚跑的存储过程，导出 CSV 到共享盘。CSV 表头中英文混杂，字段数量随版本漂移（最新一版比文档多了 3 列没人知道是什么）；
  • POS 数据三个版本共存：老门店的 POS 同步到 pos_sync 库格式是 A，新门店是 B，还有 12 家加盟店走 Excel 周报邮件；
  • 那八年库存服务器：原厂集成商已失联，唯一懂它的人离职时留了半页交接文档。

FDE 的直觉反应可能是"推动客户升级改造"——打住。**你的项目周期是十二周，遗留系统的替换周期是五年。**你既没有预算也没有授权去动它们。正确的姿态是：承认遗留系统是长期存在物，在它前面架一层适配器，把它变成 Agent 可消费的服务。

5.4.2 MCP：AI 世界的 USB-C ​

MCP（Model Context Protocol）是 Anthropic 于 2024 年 11 月开源的协议，用于把外部工具、数据源、提示词模板以标准化方式接入 LLM 应用——业内常被称作"AI 的 USB-C"：以前每接一个系统都要定制一根线，现在统一成一个口。协议核心原语三个：Tools（可调用的操作，含副作用）、Resources（可读取的数据源）、Prompts（可复用的提示模板）。据 Anthropic / modelcontextprotocol.io 官方文档。

为什么它恰好是遗留系统适配层的理想形态？把 MCP 的设计意图和你的困境对照看：

  • 统一接口描述：每个遗留暴露物（一张表、一个 CSV 管道、一个存储过程）包装成一个 MCP server，声明自己的工具清单和参数 schema——"格式不统一"的病，被"协议统一"的药正面治；
  • 客户端解耦：Agent 底座只对 MCP 协议编程，不关心背后是 MySQL、共享盘还是那台库存服务器——遗留系统的替换、改造被隔离在 server 内部，Agent 侧零改动；
  • 权限与审计挂在协议层：工具声明里带权限模型，调用走统一日志——这正好是下一节安全边界的载体。

青禾的落地形态：老 CRM 包装成 mcp-legacy-crm server，暴露 query_member_legacy（只读 Resource）、flag_sync（回写标记 Tool）；POS 双格式包装成 mcp-pos-adapter，内部做 A/B 格式归一。那台库存服务器先只包一个只读的 get_stock_level 工具——第一周不贪多，打通一条细链路。

遗留系统集成 · 架构图（连线即清单）

Agent底座 ──MCP── mcp-pos-adapter ──→ pos_sync(格式A/B归一)
        │
        ├─MCP──── mcp-legacy-crm ──→ 老CRM(存储过程+CSV)
        │                └─回写──→ flag_sync
        └─MCP──── mcp-stock-legacy ─→ 库存服务器(只读get_stock_level)
                  （每条连线 = 集成清单上的一项 = 一个验收点）

这张图的纪律是：架构图上的每条连线都落进集成清单——连线的两端系统、负责人、暴露的工具、权限级别、验收方式。评审会上客户 IT 拿到的不是"我们会集成你们的老系统"这种口号，而是一张可以逐条打钩的清单。

5.4.3 安全边界：哪些数据能暴露给 Agent ​

MCP 让接系统变容易，也把"接错了"的代价放大——AI Agent 的安全模型和传统 API 完全不同：传统 API 由开发者决定每次调用；MCP 场景下，是 LLM 在读工具描述后自己决定调什么、传什么参数。这意味着工具描述本身就是攻击面。OWASP 已发布 MCP 安全速查表，列出的头部风险包括：工具投毒（在工具描述里藏恶意指令）、Rug Pull（服务器在获得信任后偷偷改工具行为）、跨服务器工具干扰、供应链投毒。据 OWASP Cheat Sheet Series。

FDE 落到青禾的三条实操边界：

一、数据分级 × 工具分级的矩阵。会员手机号、实名信息标"敏感"（5.2 节本体里已分级），对应规则：敏感数据不出现在工具返回值里，MCP server 侧做脱敏（返回 138****5678 或聚合值），明文只在客户内网的传统权限体系里流转。Agent 永远拿不到它不需要的东西——这是"最小暴露"原则，比"事后检测泄漏"便宜一个数量级。

**二、写操作走人工确认。**只读工具（查询类）Agent 自由调用；带副作用的工具（回写老 CRM 的 flag_sync）设置 human-in-the-loop：首次执行或异常参数必须人工点确认。对应 OWASP 的建议——高影响动作要求显式用户确认。

**三、遗留回写是单向阀门。**老 CRM 是三套系统里最脆弱的（没人敢动的另一面是没人懂它），回写策略设计成：新主数据为准，老 CRM 只接收"同步标记"（告诉它这条记录已被新系统接管），永远不从老 CRM 的接口做写操作。脆弱系统只读不写，是遗留集成的保命规则。

5.4.4 三个动作：第一周做什么 ​

集成不可能十二周做完所有系统，三个动作控制节奏：

动作一：架构图连线落清单（如上，评审会交付物）。每条连线约定：负责人双方签字、暴露工具清单、权限级别、验收标准。这条纪律的隐藏价值：把"集成"从形容词变成名词——清单上第几条、状态如何，周会可以过。

**动作二：第一周打通一条细链路。**选最小、最有演示价值的一条：mcp-pos-adapter 的"查询某会员近 90 天有效订单数"。它细到一周能通，又完整到穿过格式归一、语义层指标引用、Agent 表达三层——细而全的链路是给客户 IT 的定心丸："最老的门店 POS 数据，Agent 已经能问了，格式是我们归一的，数字是按你们签认口径算的。"

这条链路还有个挑选标准值得写明：优先选"老数据、低风险、高曝光"的组合。老（老门店的格式 A 数据）证明最难的环境都能接；低风险（只读查询）不需要走审批，一周内能上；高曝光（运营经理日常真的会问的问题）让演示自然发生而不是彩排。三者交集就是第一链路——选错了任何一个维度，"定心丸"就变成"风险展示"。

动作三：迁移先彩排 + 对账标准。未来老 CRM 下线、数据全量迁到主数据——这件事在试点期不做，但要彩排：抽一个门店的全量数据走一遍迁移脚本，产出对账报告。对账标准三件套：记录数一致、关键字段抽样比对（500 对全对才过）、双端算同一指标（复购率）误差 <0.5 个百分点。对账标准先于迁移确立——将来真迁移时，标准是现成的、双方签认过的，而不是迁移完再吵"差多少算正常"。

5.4.5 负债区 / 隔离区 / 资产区：代码分层纪律 ​

集成代码最容易烂成一锅粥——三个月后没人分得清哪段是垫给老系统的补丁、哪段是核心资产。青禾项目的仓库分区纪律：

仓库结构（三分区）

qinghe-agent/
├── assets/        资产区：本体定义、语义层注册、Action规范
│   ├── ontology/  # 5.2节的YAML——客户长期资产，走评审
│   ├── semantics/ # 指标注册——口径资产，版本化管理
│   └── actions/   # 动作定义——业务规则资产
├── adapters/      隔离区：MCP适配层——每个遗留系统一个目录
│   ├── mcp-pos-adapter/      # 含格式归一逻辑+完整测试
│   ├── mcp-legacy-crm/       # 含回写阀门逻辑
│   └── mcp-stock-legacy/     # 只读壳，内嵌"不得写入"注释与检查
└── debt/          负债区：明知是权宜之计的东西，全部显式登记
    ├── HARDCODED_STORE_MAP.md  # 12家加盟店的临时手工映射
    ├── TODO_stock_field_guess.md # 那3列未知字段的猜测性处理
    └── WORKAROUND_csv_header.md  # CSV表头漂移的容错补丁

三条分区规则：

  • **隔离区的一切不得泄漏进资产区。**资产区代码（本体、语义层）不知道"格式 A/B"的存在——归一化被挡在 adapter 内部。检验方法：未来替换老 CRM 时，资产区零改动。这就是"隔离"的字面意义。
  • **负债区必须有登记文档。**每个 workaround 一个 markdown：为什么这么做、什么条件下能撤、撤的动作是什么。没有登记的 workaround 是地雷；登记过的是有偿还计划的债。
  • **负债区只增不改不删注释。**代码里的 hack 注释保留原始信息（"2026-03 因加盟店Excel无门店编码，手工映射如下"），历史是排障线索。

这个分层的远期价值在交接时兑现：W12 项目移交，客户接手团队面对的不是一团乱麻，而是"资产区是你的、隔离区随遗留系统退役、负债区有清单有偿还计划"——一座已分好类的房子。

5.4.6 与客户 IT 的谈判要点：遗留集成的政治学 ​

技术方案再漂亮，遗留集成的生死往往取决于和客户 IT 负责人的关系。三个谈判要点：

**一、把"风险转移"说破。**IT 负责人 W3 时的诉求是"不担责任"。遗留系统是他最敏感的区域——你动他的老 CRM，出了事是他的锅。谈判语言应该是："适配层全部在我们这边（乙方代码），你的系统零改动；所有对老系统的访问只读走审计，回写只有标记同步一种且双向留痕。"系统零改动 + 全量审计，这是 IT 能签的字。

**二、给"未知"留位置。**那 3 列没人认识的字段、那台八年服务器——集成清单上要有显式的"未知项"条目，标注"需客户方原厂商/离职员工支援，暂以猜测方案运行（见 debt/TODO_stock_field_guess.md）"。把未知显式化，未知就是双方共同的待办；藏着，未知就是你一个人的雷。

**三、退役路线图是礼物不是威胁。**别让"老 CRM 将来下线"听起来像你要废掉对方十年的资产。框架反转：集成清单的终点是"迁移彩排通过"，这意味着老 CRM 的历史使命光荣完成——你是在帮他"体面退役"，不是在拆他的台。同一件事，两种叙事，合作和对抗的差别就在这里。

5.4.7 要点总结 ​

  • 遗留系统的正确姿态不是改造而是适配：MCP（Anthropic 2024 年开源，Tools/Resources/Prompts 三原语）把"格式不统一"的病用"协议统一"的药治，Agent 侧与遗留替换解耦。
  • 安全边界三条：数据分级×工具分级矩阵（敏感数据 server 侧脱敏）、写操作 human-in-the-loop、脆弱系统只读不写——工具描述即攻击面（OWASP：工具投毒/Rug Pull），最小暴露优于事后检测。
  • 三个动作控制节奏：架构连线落清单（集成从形容词变名词）、第一周打通一条细而全的链路、迁移先彩排+对账标准前置。
  • 仓库三分区纪律：资产区（本体/语义/动作）不知晓隔离区（MCP 适配器）的存在、负债区 workaround 全部登记在案有偿还计划。

参考资料 ​