三方库升级最麻烦的环节，往往不是修改一个版本号，而是确认它是否改变了应用已经依赖的行为。同一个方法继续存在，并不意味着错误码、异步结束时机、回调次序和资源清理规则仍然相同。LibraryBridge此前已经把业务页面与动画实现隔离：页面只认识AnimationBridge，适配器由RegistryAnimationAdapter选择，bridge_utils承担数据规范化。现在要在这个基础上给依赖升级建立一道可以复核的门禁，避免候选版本直接覆盖稳定配置。

一、先保留上一阶段的工程状态

依赖画像仍为revision 1，entry声明@ohos/lottie的版本范围^2.0.0，本地bridge_utils由file:../bridge_utils关联。此前的资源租约已经完成取消，asset-hero停留在epoch 6，活跃租约为0，已释放资源记录为1；静态海报路线STATIC_POSTER继续保留。升级流程应继承这些状态，而不是另建一个没有历史约束的依赖清单。

在本章的数据清单中，稳定解析版本标记为2.0.0，待评估版本标记为2.1.0。两个字符串是供兼容检查使用的候选输入，真正采用哪个包仍由工程依赖解析与锁文件控制。尤其需要区分声明范围和解析结果：^2.0.0是允许版本范围的描述，2.1.0是候选值，两者不能相互替代。把候选值写入报告，并不等于让构建环境立即改用该版本。

模块边界沿用entry/src/main/ets/adapter/、model/和coordinator/的目录组织。此次增加checks/DependencyDiff.ts与checks/ContractReview.ts，只对数据快照和接口行为进行比较。业务页面依旧通过统一结果对象读取状态，不需要了解外部包的私有字段。这样即使升级被拒绝，原有页面与资源状态也不受影响。

二、把版本变化拆成可比较的记录

升级审查需要至少三份信息：当前稳定记录、待评估候选记录、应用期望契约。稳定记录保存解析版本、声明范围、适配器名称和契约摘要；候选记录保留其来源、版本及需审查的变更；期望契约则给出必须维持的结果字段和错误类型。若只有“旧版本、新版本”两个字段，就很难定位为什么升级会改变业务语义。

下面先定义精简的数据结构，保留两个独立版本以及五个检查项。bridge_utils属于本地模块，仍保持原路径；本次变更集中在动画适配路径，不把本地模块误写成远端升级对象。

const upgrade = {
  project: 'LibraryBridge', dependencyRevision: 1,
  packageName: '@ohos/lottie', declaredRange: '^2.0.0',
  baseline: '2.0.0', candidate: '2.1.0',
  localModule: 'file:../bridge_utils',
  assetId: 'asset-hero', currentEpoch: 6,
  posterRoute: 'STATIC_POSTER', activeLeases: 0,
  checks: ['version', 'interface', 'result', 'cancel', 'error']
};
function parseVersion(value) {
  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
  if (!match) throw new Error('版本格式不符合要求');
  return match.slice(1).map(Number);
}
function matchesMajorTwo(version) {
  const [major, minor, patch] = parseVersion(version);
  return major === 2 && (minor > 0 || patch >= 0);
}
console.log(upgrade.checks.length, matchesMajorTwo(upgrade.candidate));

上述matchesMajorTwo服务于本章固定的^2.0.0审查条件，不打算覆盖全部语义化版本表达式。遇到先行版本、范围组合或预发布标签，应交由具备完整语义规则的依赖管理过程处理。检查程序拒绝不满足输入格式的版本字符串，避免按词典顺序比较得到错误结论。对于候选记录里的来源、包名和本地路径，也应按原始依赖画像逐项核对。

三、区分接口兼容与行为兼容

适配器接口保持load、play、stop等业务方法名称，只能说明调用入口仍被保留。实际回归还应检查统一结果是否含有ok、code、assetId和epoch，检查取消后的回调是否可能改写新会话，以及在动画资源不足时是否可以继续显示静态海报。把所有条件简化为“方法存在”会遗漏最难排查的错误映射变化。

本章安排五项检查：版本范围、接口签名、结果字段、取消幂等、错误映射。前三项和取消路径在候选数据中满足期望；错误映射存在一处差异：原有ADAPTER_NOT_READY被候选映射为UNKNOWN_FAILURE。这两个类别对应不同的处置策略，前者可以引导选择静态海报，后者通常进入通用故障处理。直接放行会让用户界面出现不同提示，因此即便其他四项通过，升级门禁仍须保持HOLD。

const expected = {
  fields: ['ok', 'code', 'assetId', 'epoch'],
  notReadyCode: 'ADAPTER_NOT_READY',
  cancelIdempotent: true
};
function reviewCandidate(item) {
  const steps = [
    { name: 'version', pass: matchesMajorTwo(item.version) },
    { name: 'interface', pass: item.methods.join(',') === 'load,play,stop' },
    { name: 'result', pass: expected.fields.every(k => item.resultFields.includes(k)) },
    { name: 'cancel', pass: item.cancelIdempotent === true },
    { name: 'error', pass: item.notReadyCode === expected.notReadyCode }
  ];
  return {
    checks: steps,
    passed: steps.filter(v => v.pass).length,
    review: steps.filter(v => !v.pass).length,
    gate: steps.every(v => v.pass) ? 'READY' : 'HOLD'
  };
}

这里的通过条件代表业务契约自身的规则，并不替代平台安装过程或三方包的源码评估。回归输入必须保留足够的上下文，特别是错误归类之前的状态、当前资源路线和调用代次。维护人员看到error一项待复核时，应该能追溯到两个错误码的转换差异，而不只是看到一个红色标记。

四、将回归结果接入升级决策

候选检查完成后，应把结果写成单独的判定对象，避免修改依赖画像本身。READY可以进入下一步复核，HOLD要求先处理不一致项，再重新评估。对于已经发布的稳定配置，无论候选检查运行多少次，都不应该自动改变其版本引用。这个约束也让排错过程更清楚：业务实际使用的是基线，报告分析的是候选。

const candidate = {
  version: '2.1.0', methods: ['load', 'play', 'stop'],
  resultFields: ['ok', 'code', 'assetId', 'epoch'],
  cancelIdempotent: true, notReadyCode: 'UNKNOWN_FAILURE'
};
const report = reviewCandidate(candidate);
const decision = {
  ...report, stableVersion: upgrade.baseline,
  candidateVersion: upgrade.candidate,
  currentEpoch: upgrade.currentEpoch,
  activeLeases: upgrade.activeLeases,
  route: upgrade.posterRoute,
  promoted: report.gate === 'READY'
};
console.log(decision.passed, decision.review, decision.gate);
// 4 1 HOLD

判定对象应与依赖清单分开保存，保存时记录稳定版本和候选版本，避免只写入一个currentVersion造成歧义。对于HOLD状态，promoted保持false，原有适配器选择与静态海报继续沿用旧配置。若修订了错误映射，应重新执行五项检查，而不是手工把剩余问题数量改为0。需要复核的差异必须由新的候选快照和明确的变更内容来消除。

五、检查界面应该展示什么

界面最重要的不是醒目的升级按钮，而是清晰的版本关系。左侧固定显示基线2.0.0，右侧显示候选2.1.0，上方展示依赖名与声明范围，下方列出五项契约检查。四项显示PASS，错误映射显示REVIEW，总门禁显示HOLD。这一组结果与asset-hero的静态海报路线并不冲突：旧会话已经释放资源，新候选仍在审查，两条状态线应分开呈现。

要特别检查无效输入、空依赖清单和多次提交。缺少候选版本时返回输入错误，缺少历史快照时应提示先建立基线；重复提交同一候选不能重复增加检查条目。界面侧按packageName + baseline + candidate建立稳定的比较标识，可以避免用户快速切换候选造成报告错位。旧epoch回调若晚于新报告返回，也不能覆盖正在查看的结果。

六、与依赖管理工具形成闭环

Huawei开发者文档介绍了oh-package.json5中的生产依赖、开发依赖和本地模块引用方式，也说明ohpm list可以列出当前安装的依赖关系，而ohpm update根据语义化版本约束更新三方库。实际工程可在隔离分支中核对依赖树和锁文件差异，再把解析结果输入本章的契约复核过程。应留存锁文件变更前后的摘要与解析清单，确保报告使用的是可追溯的依赖版本，而不是手工填写的期望值。

参考文档：

• 添加依赖项
• ohpm list
• ohpm update

还有一个容易被遗漏的操作：完成版本差异比较后，需要让错误映射的调整回到适配层，而不是在每个页面分别修补。业务代码持续依赖AnimationBridge，局部回退只需调整RegistryAnimationAdapter的映射策略。这样下一篇讨论依赖来源完整性和许可证清单时，仍能基于同一个依赖画像继续工作。

七、收束到可解释的升级决策

版本范围兼容是升级的入口，接口稳定、结果结构稳定、取消路径与错误语义一致才是放行条件。LibraryBridge本阶段形成五项回归检查，四项满足预期，一项待复核；稳定版本和STATIC_POSTER路线保持不变。由此，版本审查从一次修改配置变成了可重复比较的工程过程，后续补齐错误映射后可以继续推进候选评审，而不需要重新设计业务页面。