替换旧系统第三方闭源组件，先把隐含契约和退出路径找出来

先按组件责任决定替换方式，不按“库还是服务”简单分类

适用边界：先判断替换的是实现、产品，还是一整套业务责任

本文面向维护 ERP、CRM、生产系统、APP 或小程序后台的产品、研发、测试、运维和采购负责人，适用于闭源 SDK、数据库驱动、报表控件、工作流、文档转换、搜索、消息、地图、支付或硬件中间件的退出。目标是可验证地接管责任，不承诺仅凭更换供应商就降低成本或提升性能。

先写清触发原因和期限：停止维护、操作系统或运行时不兼容、授权到期、供应商退出、安全修复不可得、接口能力不足，还是业务希望掌握数据与源码。原因不同，退出门槛也不同。仅因界面老旧，不一定需要替换底层组件；若组件仍受支持且替换风险高，可以先隔离调用、补监控和准备退出证据。

如果组件承担受监管决策、电子签名、支付清算、医疗或工业安全控制，通用软件测试不能代替相应专业认证和法务判断。若合同禁止逆向、样本含个人信息或导出行为会影响生产，先由授权负责人确认可执行范围。文章中的黑盒观察指使用合法调用、文档、配置和受控测试获取行为证据，不代表绕过许可或访问控制。

• 明确替换原因、最晚退出时间、业务负责人和不能中断的关键流程。
• 区分可暂时隔离的技术债与必须立即退出的安全、许可或停服风险。
• 涉及专业认证、合同限制或敏感数据时，把相应负责人纳入方案和验收。

建立组件、调用、数据、账号和人工操作五张清单

包管理器里的一个名称不是完整依赖。闭源组件可能被主程序、脚本、定时任务、安装程序、浏览器插件、桌面客户端、手机端和现场设备分别调用，还可能通过数据库表、许可证服务、字体、模板或本机驱动间接生效。

以实际构建产物和运行入口为准，记录组件名称、供应商、版本、散列或可验证标识、安装位置、加载方式、上游调用者、下游网络与存储、配置和秘密、权限、运行账号、许可范围、支持期限、升级与回退方式。CISA 的 SBOM 最小要素强调组件标识、版本、关系、覆盖范围和已知未知；闭源依赖无法展开时，也应明确标记未知或被供应商隐藏的层级，不能把空白当作没有子依赖。

第二张表列调用场景和频率，第三张表列组件拥有或派生的数据，第四张表列许可证、证书、域名、供应商控制台和回调账号，第五张表记录人工上传模板、清队列、补授权、重建索引、月末结算等操作。把每项关联到责任人、证据位置和迁移去向。SPDX 可表达组件、供应商、来源、完整性、许可证和关系，但是否采用该格式取决于现有工具；关键是清单可持续更新并能追到正在运行的版本。

• 从构建产物、运行流量、任务、脚本和现场操作交叉确认，避免只查源码引用。
• 对无法识别的传递依赖、动态下载和远程服务明确记录“未知”及确认计划。
• 把数据、许可、证书、账号、模板和人工操作纳入退出范围。

把文档接口补成可执行行为契约，尤其记录错误与副作用

供应商文档通常描述支持什么，却不完整描述旧系统依赖的实际细节。契约应覆盖请求、响应、状态变化和失败语义，而不是只证明新组件“能返回一个成功结果”。

为每个业务操作保存规范输入、调用身份、前置状态、期望输出、允许差异、副作用、错误分类、超时、重试和审计证据。样本覆盖正常、空值、最大最小值、多语言、编码、时区、精度、排序、重复调用、并发、部分失败、断网、许可证失效和恢复。对于 API，可用 OpenAPI 描述路径、操作、参数、模式、响应和安全要求，但官方规范也提示模式校验不能捕获全部规范或业务行为；因此还要运行代表性用例和业务断言。

无法读取源码时，从合法的调用边界记录必要字段并脱敏，使用固定黄金样本、特征测试和差异报告建立基线。不要把整个生产请求体长期复制到日志，也不要把供应商密钥、个人信息或文件原文放入测试仓库。历史缺陷若已被上游依赖，应明确选择“保持兼容”还是“修正并迁移调用方”，不能让新实现偶然继承，也不能静默改变。

• 契约同时描述成功、失败、结果未知、重试、副作用和可观测证据。
• 为精度、时区、编码、排序、空值和并发差异定义可接受范围。
• 接口描述、黄金样本与业务断言配套使用，敏感样本脱敏并限制访问。

先建立反腐层隔离供应商语义，再做无副作用影子比较

调用方直接认识供应商类名、状态码和数据模型时，每换一次组件都要改遍业务代码。先用本系统的业务语言定义稳定端口，再由旧、新适配器分别翻译协议和语义。

Microsoft 的反腐层模式建议在语义不同的子系统之间放置外观或适配层，并提醒这层会增加延迟、运维责任和潜在故障点。适配层只做鉴权、协议、字段、状态和错误转换，不偷偷堆入新的业务规则。为每次调用生成关联标识，记录适配器版本、选路结果、有限错误分类和耗时；秘密、完整负载和自由文本不进入普通指标标签。

对纯查询、渲染预览或确定性计算，可以让新旧适配器处理同一脱敏输入并比较规范结果。对写数据库、扣费、发通知、生成具有法律效力的文件、控制设备等副作用操作，影子只生成执行计划、请求摘要或在隔离环境运行，不能对真实目标双执行。差异按业务字段和严重度聚类，记录是旧缺陷、新缺陷、允许变化还是样本问题；未解释差异不能靠提高容差统一忽略。

• 业务代码只依赖稳定端口，供应商字段、错误码和凭据留在适配器内。
• 查询与确定性计算可双算比较，真实副作用只允许一个执行者。
• 差异有分类、负责人和处置证据，容差变更需要业务理由。

数据、许可和供应商账号要有可证明的退出路径

替代组件通过测试，不代表旧供应商已经可以关闭。历史模板、索引、加密材料、审批轨迹、设备绑定、许可证文件或云端数据如果仍只能由旧产品读取，系统仍然被锁定。

逐项确认数据主责、导出接口、格式版本、字符集、时区、附件和删除标记，保留导出批次、水位、数量、散列或业务汇总及异常清单。专有格式先导出到有文档、可重复解析的中间表示，再导入新组件；原始文件按约定只读保留到验收结束。无法导出的字段要明确业务影响、人工补录或受控留档方案，不能用截图数量代替数据完整性。

核对许可证能否并行使用、测试环境是否单独授权、旧版本是否允许继续运行、合同如何终止、支持数据如何导出、账号和子处理方如何删除。NIST SSDF 提供了与第三方沟通安全要求、来源和完整性证据的共同语言，但具体合同责任仍以双方协议和适用要求为准。新组件也建立组件来源、版本、完整性、许可、漏洞响应和替代预案，避免刚退出一个黑盒又制造下一个不可迁移黑盒。

• 每类历史数据都有可重复的导出、解析、导入、对账与异常处置证据。
• 并行期许可、终止通知、支持资料、账号关闭和数据删除由授权负责人确认。
• 新组件同步建立来源、版本、完整性、支持期限和再次退出方案。

实施步骤：按业务范围转移唯一调用主责，保留可执行回滚

切换单位应是能够独立判断和回退的业务范围，例如一个报表类型、内部组织、设备型号或只读能力，而不是笼统的“百分之十流量”。同一操作在任一时刻只能由一个适配器对真实目标负责。

第一步冻结清单、契约和退出条件；第二步引入稳定端口，让全部调用先经过旧适配器；第三步完成新适配器和隔离环境验证；第四步进行无副作用影子比较；第五步选低风险范围切到新主责，旧适配器对该范围主动拒绝执行；第六步观察完整业务周期并扩大；第七步停止旧任务、回调和人工入口，撤销凭据；第八步在确认没有调用者和未决事务后再卸载组件、终止许可与处理数据。

每个批次记录路由版本、范围、首尾业务标识、未决任务、数据水位、差异、开始时间、观察条件、回退负责人和回退截止点。回滚先恢复选路，不回写已由新组件完成且不可逆的副作用；这类结果由原适配器继续收敛，并用业务标识防止旧组件重复执行。若新格式已产生旧组件无法读取的数据，应预先准备反向转换或规定只能前滚的边界，不能等故障后才发现回滚会丢数据。

• 切换范围、唯一主责、未决操作和数据水位在执行前固定并留档。
• 旧入口在已切范围主动拒绝旁路，脚本、任务和人工操作同步收口。
• 回滚区分可逆选路与不可逆业务事实，并演练数据格式兼容。

验收与风险：证明功能等价、运行可控、退出完整，而非只看冒烟成功

上线验收至少覆盖业务结果、异常恢复、性能容量、安全权限、运维接管、数据对账和供应商退出。指标只说明现象，最终仍需用业务事实与代表性样本判断是否等价。

功能验收复跑契约样本并核对输出、副作用、审计和人工操作；故障验收覆盖超时、断网、许可证或凭据失效、组件崩溃、部分写入、重复调用、恢复和回滚；性能验收使用真实分布的受控负载，比较延迟、资源、队列和下游影响，不把单次最快结果当承诺。小程序、APP、智能体和后台各自验证错误提示、版本兼容与权限，避免只有主 Web 路径通过。

退出验收反向查找旧包、进程、端口、域名、数据库表、任务、回调、账号、密钥、许可证和人工手册，确认观察期内无合法调用且异常告警可解释。主要风险包括漏掉低频月末流程、专有数据无法回读、旧新错误语义不同、影子误触发真实副作用、路由旁路、旧凭据未撤销、合同提前终止导致无法回滚，以及新组件的传递依赖仍不透明。任何一项无法安全确认时，都应保留旧组件和“未完成替换”状态，不用卸载动作制造完成假象。

• 正常、边界、异常、重复、并发、恢复与回滚样本全部有业务断言。
• 多端调用、权限、性能、监控、值班手册和人工操作已由接管团队验收。
• 旧组件零合法调用、数据可追溯、凭据已撤销、账号与许可按批准计划退出。

需求讨论中的问题

关联服务与实施资料

下面的页面可继续核对相关技术边界、业务接入方式与项目交付条件。

• 旧系统运行时与依赖升级指南：继续处理语言运行时、包版本、构建环境与兼容矩阵。
• 旧系统逐模块替换指南：用稳定入口按业务模块推进绞杀式迁移与退役。
• 旧系统业务规则特征测试：把黑盒行为、历史缺陷与允许差异沉淀成回归证据。
• 旧系统历史数据迁移指南：处理全量回填、增量追平、删除语义和业务对账。
• API 重试风暴与幂等指南：治理第三方调用超时、结果未知、重试预算和重复副作用。
• AI Agent 智能体开发：让智能体只通过授权业务端口调用组件，并保留工具审计。
• 小程序与 APP 一体化开发：统一多端兼容、版本路由、错误提示和迁移后的业务入口。