@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.1

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/references/upgrade/upgrade-examples.md

@@ -0,0 +1,289 @@
+# 行为变更的常见适配案例
+
+按对应的完整官方章节、准确 SDK 和真实业务判断，扫描命中不等于必须修改。本页按需要选读，不是逐项必答清单；默认尽量保持升级前的功能、视觉和交互。跨系统处理见[target 升级兼容](upgrade-compatibility.md)，HAR 见[宿主专题](har-upgrade.md)。
+
+编译错误或用户明确报告的混淆/发布包异常，另按[漏扫案例](scanner-missed-cases.md)的错误索引排查；正常扫描、CSV 零行或构建成功时不因此增加主动核查。
+
+## 案例索引
+
+| 主题 | 主要判断与易错点 |
+| --- | --- |
+| [Image 解码](#imageautoresize显式保留所需解码策略) | 像素门槛、动态资源及是否保留原图细节 |
+| [GridRow/GridCol](#gridrow--gridcol显式保留断点补全结果) | 断点补全、显式配置与真实窗口宽度 |
+| [Text 选择菜单](#text-选择菜单) | copyOption 默认值、封装和实际选择能力 |
+| [Button 热区](#button-热区) | 组件尺寸与实际可点击范围不是同一件事 |
+| [Dialog/Toast 材质](#dialog-与-toast-材质) | 已有样式、局部需求与应用级开关的影响范围 |
+| [内置文本](#内置文本布局) | 系统语言、完整组件范围及固定布局裁切 |
+| [页面退出](#页面退出与组件释放) | aboutToDisappear 前移不等于全部清理都迁移 |
+| [转场属性](#消失节点的转场属性) | 节点开始消失前更新，不能用延时猜测渲染时机 |
+| [无限循环动画](#无限循环动画) | 显式动画闭包与同步布局回调分别处理 |
+| [HEIF/HEIC](#heif-与-heic-mime) | 参数、返回值和已兼容接口分别核对 |
+| [Video 拖入](#video-拖入播放) | 数据读取、空记录、播放准备与异常路径 |
+| [List 首次定位](#list-首次定位) | initialIndex 与布局前滚动竞争，不猜测布局完成 |
+| [参数扩展](#参数扩展与重编译) | 能力扩展不强制替换原实参，重编译不制造源码修改 |
+
+## Image.autoResize：显式保留所需解码策略
+
+官方API26说明：未设置autoResize时，解码后宽×高超过5000万像素的图片由原默认false改为true，开启降采样；判断依据是像素尺寸，不是文件大小或格式。来源见[官方变更正文](../changelogs/26.0.0/release-changes-for-all-apps.md#image组件autoresize属性默认行为变更)。
+
+### 需要保留原图细节时修改
+
+业务需要放大查看原图细节，且真实资源满足大图门槛：
+
+```ts
+// 修改前：依赖旧默认值。
+Image($r('app.media.large_image'))
+```
+
+```ts
+// 修改后：显式保留按原图尺寸解码的业务要求。
+Image($r('app.media.large_image'))
+  .autoResize(false)
+```
+
+仍须评估原图解码的内存与稳定性成本，真实构建不能证明画质、缩放或内存表现。该参数在原接口已支持，不为显式false额外增加版本分支。
+
+### 主动选择降采样时修改
+
+业务已确认接受降采样以控制内存时，可以明确设置：
+
+```ts
+Image($r('app.media.large_image'))
+  .autoResize(true)
+```
+
+这表达业务选择，不表示保留旧默认false；涉及原图质量取舍时先取得相应方案决定。
+
+### 小图未触发时无需修改
+
+真实资源固定为144×144且没有动态替换为大图时：
+
+```ts
+Image($r('app.media.startIcon'))
+```
+
+尺寸未超过门槛，可按具体证据记录NO_CHANGE。不因为扫描命中统一补true；动态图片或封装资源尺寸未知时保留具体缺口，不能用一张小图推断全部调用。
+
+## GridRow / GridCol：显式保留断点补全结果
+
+API20调整columns/span默认值及部分断点的补全规则，官方明确target≥6.0.0(20)时生效。来源见[官方变更正文](../changelogs/6.0.0(20)/beta1-os-api-behavior-changes.md#gridrow组件columns参数和gridcol组件span参数默认值变更)。
+
+### 业务需要原布局时可显式配置
+
+修改前只提供md/lg，旧补全规则下xs/sm的columns=12、span=1；新规则会从更大断点补全为4：
+
+```ts
+GridRow({ columns: { md: 4, lg: 8 } }) {
+  GridCol({ span: { md: 4, lg: 8 } }) {
+    Text('内容')
+  }
+}
+```
+
+需要维持原各断点结果时，显式补齐：
+
+```ts
+GridRow({ columns: { xs: 12, sm: 12, md: 4, lg: 8, xl: 8, xxl: 8 } }) {
+  GridCol({ span: { xs: 1, sm: 1, md: 4, lg: 8, xl: 8, xxl: 8 } }) {
+    Text('内容')
+  }
+}
+```
+
+这里保持原组件和内容，仅调整本条变化涉及的参数。若业务接受新布局、原本已完整配置或当前宿主未触发生效条件，可说明依据后NO_CHANGE；不能把官方“无需适配”理解为不用核对所需布局效果。验证覆盖实际受影响窗口宽度和交互，不借此重构整页或迁移状态管理。
+
+## Text 选择菜单
+
+来源：[API26 材质变更](../changelogs/26.0.0/beta1-ux-style-and-effect-changes.md#dialogtoastalphabetindexer和文本选择菜单默认开启沉浸式系统材质)。该条材质变化明确按 target≥26.0.0 隔离；是否存在选择菜单还需核对真实 Text/Span、完整属性链和封装。
+
+**影响判断**：准确 SDK 的 Text.copyOption 默认值为 CopyOptions.None；真实普通 Text 未设置且封装也未启用复制时，可以说明该调用未触发“选择菜单材质”场景，但不能把这一结论套到其他 Text、RichEditor 或所有文本变化。已有选择能力的调用还要检查菜单样式和业务要求。
+
+下面表示原本就需要本机复制的调用，不是为了消除命中强制开启复制：
+
+```ts
+Text('允许复制的内容')
+  .copyOption(CopyOptions.LocalDevice)
+```
+
+**易错与验证**：不能统一补 None 来“适配”，这会关闭已有业务；InApp、LocalDevice 等范围不能混用。验证长按、菜单、选择回调和剪贴板，不只截图 Text。默认值或跨文件封装不明时保留具体缺口，不凭没写属性就直接 NO_CHANGE。
+
+## Button 热区
+
+来源：[表单类组件触摸热区最小高度变更](../changelogs/26.0.0/beta1-ux-style-and-effect-changes.md#表单类组件触摸热区最小高度变更)。target≥26.0.0 时，官方范围内组件的默认最小热区高度从28vp变为32vp。
+
+**影响判断**：核对真实 Button、Button 模式 Toggle、Select、Chip/ChipGroup，以及显式宽高、约束、状态样式和自定义热区。只有业务需要恢复与组件实际大小一致的热区时，才参考官方方式：
+
+```ts
+Button('操作')
+  .responseRegion(undefined)
+```
+
+**不受影响与易错**：已有高度/热区配置按真实规则判断，不因一个数值或“不是小按钮”直接排除；不要为保留旧热区统一缩小组件高度。跨组件封装或条件尺寸不明时说明缺口。
+
+**验证**：点击组件边缘及扩展区域，核对相邻控件命中、事件次数和可访问性；页面布局正常不能证明热区一致。
+
+## Dialog 与 Toast 材质
+
+来源：[默认开启沉浸式系统材质](../changelogs/26.0.0/beta1-ux-style-and-effect-changes.md#dialogtoastalphabetindexer和文本选择菜单默认开启沉浸式系统材质)。target≥26.0.0 时，指定 Dialog、Toast、AlphabetIndexer 和文本选择菜单默认开启该效果。
+
+**影响判断**：先核对准确 SDK API/重载、实际选项和主题。官方说明主动设置背景色、背景模糊、阴影或边框时，默认材质不会生效；真实样式已覆盖时可说明无需修改，不为“看起来更新”删除原样式。
+
+**局部与全局方案**：只影响个别组件时先评估局部参数，新增 systemMaterial/uiMaterial 等能力需核对自身 SDK 声明和支持范围。只有业务明确要求应用级关闭时，才将下面 metadata 合并到现有 entry 模块的 module.json5，不整文件替换或覆盖其他 metadata：
+
+```json
+{
+  "name": "ohos.arkui.UIMaterial.state",
+  "value": "disable"
+}
+```
+
+该配置影响范围不是某一个弹窗，应纳入 spec 的共享修改批准。不要把同名业务 Dialog 当作 SDK 弹窗，也不要为局部问题直接关闭整个应用的材质。
+
+**验证**：确认/取消、显示/关闭、Toast 内容及回调分别验证；检查原主题和已授权设备效果，不能用取消成功证明确认按钮回调正确。
+
+## 内置文本布局
+
+来源：[内置文本的组件文本样式优化](../changelogs/26.0.0/beta1-ux-style-and-effect-changes.md#内置文本的组件文本样式优化)。target≥26.0.0 时，官方组件清单中的孤字换行、小语种行高及音节换行规则发生变化。
+
+**影响判断**：普通 Text/Button 不能直接与官方列举的内置文本组件混为一类。应用只显示短中文仍不能排除系统切到藏语或缅甸语后的行高变化；检查真实组件、系统语言、长度、尺寸约束和辅助显示设置。
+
+**适配与反例**：已证实固定高度导致裁切时，局部调整约束或文本布局；没有裁切、业务接受且实测满足要求时可以无需修改。不能统一固定行高、截断内容或关闭全部文本优化来消除命中，也不能以编译成功代替显示证据。
+
+**验证**：在相关系统语言和代表性长短内容下检查换行、行高、按钮命中及周边布局；缺设备或内容证据时明确待验证范围。
+
+## 页面退出与组件释放
+
+来源：[页面退出场景自定义组件删除前移](../changelogs/5.1.0(18)/os-api-behavior-changes.md#页面退出场景自定义组件删除前移)。官方按 target≥5.1.0(18) 隔离，限 Router/Navigation 页面的默认退出动画场景：aboutToDisappear 前移到动画过程中，onDisappear 仍在退出动画结束后执行。
+
+**受影响场景**：全局复用的自定义节点在 aboutToDisappear 中被移除或重新挂载，操作与退出动画发生竞争。没有默认退出动画，或该回调只做不依赖节点移除时机的工作，不能直接认定需要同样修复。
+
+**最小方案**：仅把确需等待退出完成的节点操作迁移到工程实际可用的退出完成/脱树时机，官方举例为 onDetach；核对具体回调及 SDK 支持范围，保持节点所有权与资源身份。不要把所有订阅取消、定时器和业务清理整体搬到另一生命周期，也不要用固定延时冒充退出完成。
+
+**验证**：记录回调顺序，覆盖正常返回、连续出栈、快速退出和节点复用；核对动画、重复挂载及资源释放，未受影响页面保留原逻辑。
+
+## 消失节点的转场属性
+
+来源：[禁止在转场动画过程中更新消失节点属性](../changelogs/5.0.1(13)/beta3-os-api-behavior-changes.md#禁止在转场动画过程中更新消失节点的属性)。target≥5.0.1(13) 时，正在消失的节点不再响应该阶段的属性更新。
+
+**影响判断**：仅修改出现节点或稳定在树节点，不属于同一场景；检查条件渲染/列表删除、属性状态和转场的实际顺序。
+
+下面是组件已有状态方法中的关键片段，业务需要“先变色，再开始退出”时，将两项工作分开；实际工程仍须核对状态刷新和节点下树顺序：
+
+```ts
+// this.isVisible、this.textColor 是组件已有状态。
+this.getUIContext().animateTo({}, () => {
+  this.textColor = Color.Blue;
+});
+this.getUIContext().animateTo({}, () => {
+  this.isVisible = false;
+});
+```
+
+**易错与验证**：不要只颠倒同一闭包里的两行就认定更新已渲染，不要额外加固定 setTimeout。删除相关数据时保留仍在转场节点需要的有效内容，不能因节点未立即销毁而访问已清空对象。覆盖快速切换、ForEach 删除及不同转场，分别核对业务状态和消失过程。
+
+## 无限循环动画
+
+来源：[无限循环动画行为变更](../changelogs/5.0.1(13)/release-os-api-behavior-changes.md#动画接口在播放次数为无限循环时的行为变更)。官方描述首次布局同步回调被意外纳入无限循环动画的修正，不等于所有动画或全部 onFinish 都改变。
+
+**受影响场景**：业务依赖 onSizeChange 等同步回调中的副作用被带入 iterations=-1 动画。若真正希望某个状态循环变化，应将它显式放在动画闭包；不需要循环的布局/业务状态在闭包外处理：
+
+```ts
+// 组件已有状态示意：布局变化不参与循环，旋转参与循环。
+this.contentWidth = 200;
+this.getUIContext().animateTo({ iterations: -1, playMode: PlayMode.Alternate }, () => {
+  this.rotateAngle = 90;
+});
+```
+
+**不受影响与易错**：有限循环、无相关同步回调依赖的调用按实际条件判断，不统一修改 iterations。不要把“退后台导致有限动画提前触发 onFinish”的另一条变化与本条混用；也不能为保留偶然效果把所有回调更新搬入无限循环。
+
+**验证**：核对预期参与动画的属性、非动画布局、重复触发和既有停止/清理路径。日志或单帧截图不能证明无限循环及终止语义。
+
+## HEIF 与 HEIC MIME
+
+来源：[image 接口 Heif 格式类型变更](../changelogs/5.0.2(14)/os-api-behavior-changes.md#image接口heif格式类型变更)。官方按 target≥5.0.2(14) 隔离，必须区分六类接口：
+
+| 接口/用途 | 官方变化与处理 |
+| --- | --- |
+| OH_PackingOptions_SetMimeType | 按准确声明将相关 HEIF 格式参数改为 image/heic |
+| OH_PackingOptions_GetMimeType | 相关返回值改为 image/heic，检查消费方判断 |
+| ImageSource.supportedFormats | 查询解码支持列表的返回格式变化，检查业务解析 |
+| ImagePacker.supportedFormats | 查询编码支持列表的返回格式变化，检查业务解析 |
+| image.PackingOption | 官方兼容 image/heif 和 image/heic，不因旧实参出现就强制替换 |
+| OH_PackingOptions 结构体 | 官方兼容两种值，与上述 C 函数的参数/返回不能混为一谈 |
+
+需要消费不同支持系统的查询结果时，可在业务识别处兼容两种字符串：
+
+```ts
+function isHeifMimeType(mimeType: string): boolean {
+  return mimeType === 'image/heif' || mimeType === 'image/heic';
+}
+```
+
+**反例与验证**：不全局替换日志、文件扩展名、协议字段和所有编码参数。修改设置值前核对设备行为及真实重载；编解码分别测试，读取实际 MIME/文件并回读内容，不能只用输出文件名判断格式。
+
+## Video 拖入播放
+
+来源：[Video 不再默认解析并播放拖入资源](../changelogs/5.0.1(13)/release-os-api-behavior-changes.md#video组件不再默认解析并自动播放拖拽信息中的视频资源)。官方明确在 ROM 5.0.0.123 引入，不把接口 since10 或应用 target 当作设备行为门槛。
+
+**影响判断**：应用不需要拖入即播放时不为恢复旧默认强行开启；业务需要时，在原 Video 链路显式完成“识别视频记录 → 更新 src → 准备完成后启动”。
+
+下面是已有 Video 属性链的事件处理片段；videoSrc/controller 是原组件字段，另有普通字段 pendingDroppedVideoUri: string | undefined，初值 undefined，用资源URI记录本次有效拖入的播放意图。此片段只展示单次拖入链路，复杂切源须复用工程已有资源状态管理。LOG_DOMAIN/LOG_TAG 和 hilog 由工程既有日志约定提供，统一数据类型从 @kit.ArkData 导入 unifiedDataChannel、uniformTypeDescriptor：
+
+```ts
+.onDrop((event: DragEvent) => {
+  try {
+    const records = event.getData().getRecords();
+    for (const record of records) {
+      if (record.getType() === uniformTypeDescriptor.UniformDataType.VIDEO) {
+        const video = record as unifiedDataChannel.Video;
+        if (video.videoUri.length > 0) {
+          this.pendingDroppedVideoUri = video.videoUri;
+          this.videoSrc = video.videoUri;
+        }
+        return;
+      }
+    }
+  } catch (error) {
+    this.pendingDroppedVideoUri = undefined;
+    hilog.error(LOG_DOMAIN, LOG_TAG, 'Read dropped video failed: %{public}s', String(error));
+  }
+})
+.onPrepared(() => {
+  const pendingUri = this.pendingDroppedVideoUri;
+  this.pendingDroppedVideoUri = undefined;
+  if (pendingUri !== undefined && this.videoSrc === pendingUri) {
+    this.controller.start();
+  }
+})
+.onError((error) => {
+  this.pendingDroppedVideoUri = undefined;
+  hilog.error(LOG_DOMAIN, LOG_TAG, 'Video loading failed: %{public}s', String(error));
+})
+```
+
+**易错**：原组件构造字段是 controller，不是 ontroller；不直接取 records[0]、不把图片/文本当视频、不在资源尚未准备好时调用 start。getData 的读取异常须有明确处理，复用工程原错误边界，不吞掉无关业务失败。取消拖入或切到非拖入来源时，须在原入口先清空 pendingDroppedVideoUri，再执行原切源逻辑，不能等下一次准备回调。加载失败时清理意图并保留原错误反馈。同源重复拖入不能假设每次赋值都会重新触发准备回调；连续异步切源还需关联实际资源身份或串行协调，不能仅比较当前URI就证明某个回调属于本次资源。如果原业务已有 onPrepared/onError 或自动播放条件，应合并处理，不能覆盖原回调或让所有来源无条件自动播放。
+
+**验证**：视频、非视频、空记录/不可读取数据、拖入加载失败后普通切源、取消、快速连续切源和既有控制事件分别测试；核对 onDrop→src→onPrepared→start，保留原资源权限和失败反馈，不能只以播放器显示一帧作为完整通过。
+
+## List 首次定位
+
+来源：[首次布局的 Scroller 优先级变更](../changelogs/5.0.2(14)/os-api-behavior-changes.md#list组件首次创建布局时scroller控制器的跳转方法优先级变更为高于initialindex的优先级)。target≥5.0.2(14) 时，首次布局前 scrollToIndex、scrollToItemInGroup、scrollEdge 的定位优先于 initialIndex。
+
+**受影响场景**：同时依赖 initialIndex 和首次布局前的滚动命令；只有 initialIndex 或滚动发生在另一个明确业务阶段时，按实际调用判断。
+
+**最小方案**：如果业务要求初次显示 initialIndex 指定位置，优先消除初始化阶段的另一条定位命令；后续确有滚动需求时，再在可证明符合业务的时机执行。若原本就希望滚动命令优先，可保留并记录依据。不要把 onAppear、onDidBuild 或固定延时直接当“布局已完成”的通用证明，也不要删除用户触发的滚动功能。
+
+**验证**：覆盖非零 initialIndex、对齐方式、分组、空列表、动态数据和后续滚动，观察首次可见位置与业务状态。只测最终停留位置可能漏掉初始化闪跳。
+
+## 参数扩展与重编译
+
+来源示例：[接口增加 Resource 类型支持](../changelogs/6.0.0(20)/beta1-os-api-behavior-changes.md#文本与输入信息展示按钮与选择滚动与滑动图形绘制组件接口支持resource类型)。核对真实旧实参、继承类型及准确 SDK 声明，类型扩展不自动要求将现有 string 参数改成资源，也不证明所有派生接口无需调整。
+
+旧调用仍满足声明、业务不需新能力时可有据 NO_CHANGE；确需新增资源能力时只修改相关类型/实参。官方要求仅重编译时记录真实重编译需求，不制造源码差异。接口和参数名没变也可能发生语义变化，仍按本条完整指导判断。
+
+## 修改结果与代码证据
+
+MODIFIED 必须关联本行真实业务差异，不能把日志、格式、根 target 或同文件无关变化算作 API 修复。NO_CHANGE 写清实际取值和未触发/已满足指导的理由。编译错误查到漏扫案例也不表示 scanner 命中，不向原 CSV 补行或改变分类分母。
+
+代码块用于说明本条差异；片段须合入已有组件和业务上下文，不是统一替换模板。按[编码规范](../common/arkts-coding-standards.md)保留返回、回调、异常和生命周期，模型评估、真实构建、功能和视觉结果分别记录。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/references/upgrade/upgrade-workflow.md

@@ -0,0 +1,122 @@
+# 行为变更完整适配流程
+
+按 U01–U09 执行：扫描整理 → 按变更评估 → 确认 spec → 修复 → 构建与按需测试 → 交付。评估与修复分离，默认尽量保持升级前的功能、视觉和交互体验。处理 API Behavior Change、UX Visual Layout Change、UX Interaction Behavior Change 及 API Definition Change，支持 HAP、明确模块/目录的 HAR 和相关 C/C++。
+
+行为按[官方行为边界与 target 隔离](upgrade-compatibility.md)处理跨系统差异，不做通用接口版本可用性匹配、不自动调整 compatible、不做行为复扫。scanner 提供扫描事实，模型负责业务判断；命中、字段齐全、修改或编译通过均不单独证明适配正确。
+
+## 用户决定
+
+| 时机 | 需要的决定 | 未答复时 |
+| --- | --- | --- |
+| U02，目标未明确 | 从真实配置和工具链支持的候选中选择 target，允许自行填写 | 不代选目标或扫描区间，可继续独立环境核查 |
+| U02，验证方式未明确 | 不运行、仅修改后验证、前后对比 | 不修改可能需要归档基线的源码和配置；可继续扫描与只读评估 |
+| U05，spec 已形成 | 全部批准、明确部分或暂不修改；选择设备验证时同时确认测试分类范围 | 不修改源码或配置，不把初始“自动适配”当作具体方案批准 |
+
+优先使用宿主提问工具，缺少工具时等待明确文本答复。推荐、预选、沉默和超时均不是同意。真实答复及来源写入[进度](../../templates/progress.md)，已明确且仍适用的决定不重复询问。仅分析或全部无需修改且没有配置修改计划时，spec 用于展示评估结论，不额外请求不存在的修复批准，仍补齐已选择设备验证的范围。
+
+部分批准须唯一映射到条目、rowIds 和共享修改。共享修改涉及未批准范围时先澄清；范围、目标或实质方案改变时更新 spec 并重新确认受影响部分，同一获批方案的实现细节不逐文件重问。未批准的拟修复项保留 DECISION_REQUIRED，不能写成 NO_CHANGE 或范围外。
+
+## U01 确定工程与范围
+
+读取真实根 build-profile.json5 的 products、模块注册及 module.json5，按 JSON5 解析，不整文件重写。明确 product、模块/目录、工程类型、已有改动与验证范围；同类选择并集、不同类型交集，按物理路径核对符号链接、junction 和工程外注册模块。不能唯一限定时列出实际候选，等待范围明确。
+
+HAR 先读[库与宿主](har-upgrade.md)，取得明确库范围和历史已适配基线，不用库当前构建 target 代替 from。保存原 target、compatible 和任务外改动；联合任务共享原始基线，不把另一任务改后的配置当原值。范围明确后进入 U02。
+
+## U02 核对环境、目标与验证方式
+
+按[版本契约](../common/sdk-versions.md#配置设备与打包字段)和[环境核查](../common/verification.md#环境与依赖)核对 SDK/IDE 元数据、Node、Java、ohpm、Hvigor 和实际路径。区分编译 SDK、目标 target、compatible、精确扫描版本和设备行为版本；不丢 Beta/Release，不凭 CSV 终点或“最新 SDK”代选 target。compatible≤target≤编译 SDK，不降低版本；API26 配置使用 26.0.0，扫描保留精确通道。
+
+应用 from 默认原 target，缺失取原 compatible；HAR 显式提供历史 from。扫描使用 (from,to]，原 target 为 API12 时仍以12为起点以覆盖 API13，不因此提高 compatible。保留原 target 且没有可信新增区间时，记录无新增扫描区间，处理已有证据，不调用空或反向区间，不回退配置。
+
+开始时确认不运行、仅修改后验证或前后对比；U05 再依据实际分类确认用例范围。显式工具路径无效时不偷偷替换。环境缺口不妨碍有充分依据的静态评估，构建和设备未执行须保留缺口。目标明确后进入 U03。
+
+## U03 扫描或导入并整理任务
+
+先读取 scanner 真实 help，再使用实际支持的参数。记录启动目录，默认输出根为其 .api-change-output，用户指定路径优先。使用[布局4与原件保护](../../templates/progress.md#建议目录)的实际返回路径；导入建立新批次，复制原始字节与伴随证据，不用较小 adapted 表替代原始基线，不搬动扫描后的原表或恢复旧运行状态。
+
+```console
+node "<skill-root>/scripts/scanner/bin/harmony-api-scan.mjs" help
+node "<skill-root>/scripts/scanner/bin/harmony-api-scan.mjs" scan --mode upgrade --project "<工程>" --sdk "<SDK>" --deveco-home "<IDE>" --from "<精确起点>" --to "<精确终点>" --product "<产品>" --output-dir "<输出根>"
+```
+
+HAR 补充 --project-type har 及明确 --scan-module/--scan-dir；原生按实际能力准备编译上下文。保存退出码、coverage、diagnostics 和超时/未扫描范围，区分无规则、未命中、后端失败和 CSV_ONLY，不把零行说成官方全覆盖。
+
+按[结果格式](../../templates/results.md)可靠解析 BOM、CRLF、引号、单元格换行和 HYPERLINK。用原始输入 SHA-256＋逻辑数据行序号建立 rowId，保留原列、全部行及重复行。按规则身份/可验证来源＋精确版本归组，关联物理文件和调用点；未知身份、冲突、缺文件及范围外原因分别保留。按[官方资料定位](#官方资料定位)建立章节对应，不进行人工初核。
+
+初始化通用进度、分组和逐行结果，分别统计原始行、位置、物理文件、变更和工作单元。行为结果表只在原扫描列之后追加处理结论、处理说明、后续事项，处理结论仅用无需适配、已适配、待决策；未评估和缺口暂列待决策，并说明原因及下一步。rowId、MODEL_ASSESSED和准确内部状态保留在分组与报告，不追加到CSV。零行进入 U09；可信独立候选进入 U04，局部扫描失败不吞掉已取得结果，完全受阻仍进入 U09 交付。
+
+## U04 按变更条目评估
+
+按[变更评估 agent](../../agents/upgrade-assess-change.md)分派只读任务：展示变更名称，内部保留准确规则、来源和版本，每个变更条目一个 agent，按宿主实际并发能力排队。大条目也不按文件拆分，不抽样，不向下分派。传入完整关联文件/调用点和 rowIds、章节路径及工程上下文，不能只传主 agent 摘要。
+
+agent 自行完整阅读官方章节，逐文件、逐调用分析并返回分类、证据、方案及缺口。评估阶段不改工程源码或配置；主 agent 统一保存分组与结果，子 agent 不写共享 spec、进度和报告。失败或中断保留具体未完成范围，可继续其他独立条目；补齐或明确记录未完成后，等待全部任务返回再进入 U05。无子 agent 能力时明确说明能力缺口，不假称已分派或默认跳过评估。
+
+## U05 汇总 spec 并取得确认
+
+主 agent 按[spec 模板](../../templates/upgrade-spec.md)在本批次 upgrade 目录生成 spec.md，汇总全部已返回结果及未完成项。检查同一文件、公共 helper、配置和跨文件依赖的方案冲突，必要时回到对应 agent 补充，不能直接拼接矛盾建议。
+
+spec 写清分类、业务影响、逐文件修改方案或无需修改依据、保留原体验的方式与成本、共享修改、风险/替代方案、预期行为和验证安排。缺证据或业务决定的条目显式保留 EVIDENCE_GAP/DECISION_REQUIRED；全部 agent 返回不表示全部问题解决。
+
+展示 spec 后按[用户决定](#用户决定)取得修复批准。设备测试范围支持[三类](#分类与记录)任意组合及全部，建议全部但等待实际答复；所选无需适配条目仍测试正常功能。测试范围不改变修复批准范围或评估分母。取得必要答复后进入 U06；暂不修改或只分析时，可执行已授权验证并进入 U09，不以未批准代替无需修复。
+
+## U06 实施获批修复
+
+有源码或配置修改时，仅在 spec 相关方案已获批准且验证方式明确后实施；无需修改时沿用已授权的测试安排，不要求不存在的修复批准。选择前后对比时，先按[阶段包方法](../common/verification.md#行为前后对比)在原源码、原 target/配置下真实构建并归档 before 包，先于相关源码、配置和测试辅助源码修改。包构建、签名或归档不足以支持对比时保存现场，等待补齐或用户明确改为仅修改后验证/不运行；不自行降级。
+
+before 包有效归档后不要求先运行设备测试，设备暂时不可用只影响 U08。联合任务先归档共同原始基线包，再实施影响它的共享修改。不运行或仅修改后验证不构建 before。无需修改的对比任务同样保留原包，但不制造源码差异。
+
+依据实际待修改物理文件数、复杂度和并发能力选择主 agent 直接修复或按[单文件修复说明](../../agents/upgrade-fix-file.md)分派，简记理由，不设固定数量阈值。同一物理文件只有一个修改者，该文件全部获批变更一起处理；共享 helper、配置和跨文件接口由主 agent 协调。主 agent 直接修复时执行相同说明。
+
+保留任务外改动和原 compatible，按[编码规范](../common/arkts-coding-standards.md)、[行为兼容](upgrade-compatibility.md)及相关 HAR/原生资料实施最小修改。主 agent 统一更新结果，内部 MODIFIED 必须有与该行相关的实质业务差异；行为 CSV 显示已适配，处理说明同时写明修改内容、作用及理由，不能只有触发原因。未编译、编译失败或人工验证尚未完成写入后续事项，不把已适配当作验收通过。实质方案变化返回 U05，不整文件回滚。完成后进入 U07。
+
+## U07 复核与完整构建
+
+主 agent 按[静态复核](../common/verification.md#通用静态复核)核对实际 diff、SDK 声明、官方触发条件、资源/回调身份、异常和生命周期及配置；模型复核与真实语法/类型结果分别记录。原生核对实际 ABI 和构建上下文，HAR 核对宿主 target 和真实消费。
+
+每轮源码或构建配置修改后，按[完整构建](../common/verification.md#完整构建与产物)组织真实工程构建，不让各文件 agent 重复触发整工程构建。保存命令、日志、退出码和本次对应产物；设备验证使用最终 after 包，归档副本不覆盖 before。HAR 先库、证明本次消费、再构建宿主。未修改时按已选验证范围安排必要构建。
+
+代码失败只修必要闭包后回 U06/U07，按[排错](../common/troubleshooting.md#定位与停止)限制实质失败方案；环境阻断不消耗源码方案次数。未成功只可部分完成交付，不继承旧包或旧通过。选择设备验证进入 U08，否则进入 U09。
+
+## U08 按需测试与报告
+
+按[功能取证](../common/runtime-functional-tests.md#行为前后对比)从 spec 预期与已选范围生成用例，保存到 evidence 目录。对比模式先测试归档 before 包，复位约定数据后测试 after 包；仅修改后验证只测试 after。两个阶段使用同设备/系统、同语义用例和可复位数据，优先使用两个包都支持的外部操作，不假定 before 含有新增测试入口或埋点。
+
+按[测试报告模板](../../templates/upgrade-test-report.md)生成 test-report.md，逐用例关联 rowIds、包身份、业务断言、实际值、日志/图片和差异。表现相同不等于业务正确，截图或启动不代替功能证据。包缺失、数据不可复位、测试入口不兼容、设备或工具不可用时分别报告实际阶段及不可比范围，不回退源码补造 before。保存证据后只清理本次启动实例。
+
+之后源码/配置变化时重建 after 并重测受影响用例，before 归档保持原样。设备和测试失败保留可信修复，不冒充对比通过；所有结局进入 U09。
+
+## U09 覆盖核对与交付
+
+按[行为结果格式](../../templates/results.md#行为结果只追加三列)，使用 formatUpgradeResults 和[文件调用示例](../../templates/results.md#格式化接口与文件调用)生成结果表；提供原扫描字节及带rowId的三列判断，不自行猜测CSV接口。统一UTF-8 BOM与CRLF，原扫描不变。回读确认结果仅追加三列、中文结论合法、原字段和重复计数完整，再回读原始行、分组和文件证据，核对来源/精确通道、完整章节实际阅读范围、分类、批准和真实差异，所有重复行分别保留。三类＋待分类＋范围外＝原始逻辑行数；原始行、位置、物理文件、变更和工作单元分别统计，不以同文件变化替代每行结论。
+
+按[行为报告](../../templates/upgrade-report.md)生成 api-adapt-report.md，引用 spec.md 和按需生成的 test-report.md，交付原扫描、adapted-results-<批次ID>.csv、进度和实际证据的完整路径。首页展示实际配置旧→目标及实施状态。评估、修改、包归档、完整构建、设备测试和有效对比分开；未编译成功、遗漏、未解决或过期证据不宣称全部完成。
+
+零行、全部无需修改、待批准、中断或工具缺失也交付真实结果。用户修改过的交付件另存版本，不覆盖。继续任务按[恢复方法](../common/troubleshooting.md#断点继续)核对当前输入及实际批准，不继承历史成功。
+
+## 官方资料定位
+
+新扫描 CSV 保留 Rule ID 和 Changed in SDK，详细 Source Reference 从同批次扫描 JSON 读取；按每组真实记录取得，不统一取整表首行。读取[本地索引](../changelogs-index.json)，仅按 documents.path 的当前路径定位；文件部分相对本 skill 的 references/changelogs，保留章节行号，兼容分隔符并用 node:path 构造物理路径，不转换历史路径或别名。可复用 loadChangelogIndex 和现有版本函数，不新增取材执行器。
+
+核对 CSV 与 JSON 的批次、模式、可见字段及重复次数；upgrade 的 findings 保持扫描行序，不能因删去列号而合并同位置记录。仅有 CSV 时使用 Title 的官方链接、规则身份、精确版本和源码补证；历史 CSV 有 Source Reference 时保留原值，只有当前路径可直接定位。无法唯一确认章节时记录 EVIDENCE_GAP，不猜造映射。
+
+核对准确标题、来源及保留 Beta/Release 的版本。7.0.0(26) Beta1、26.0.0 Beta1 可按现有版本能力归一到 26.0.0(26) Beta1，不等价于 Beta2 或 Release。无规则 ID 时只接受唯一可验证来源；标题只辅助定位。身份冲突保留原行和缺口，不强行合并。
+
+完整章节包含原因、影响、生效条件、接口清单和适配指导，读取直到代码围栏外下一个同级或更高级标题。scanner 读过资料、CSV 链接或摘要不等于评估 agent 已读正文。仅本地缺失、歧义或与真实 SDK 冲突时补充官方网页，记录本地已查路径/范围、缺口、准确 URL、实际阅读范围、补充内容及差异；保留本地原件，未解决仍为 EVIDENCE_GAP。
+
+## 分类与记录
+
+| 分类 | 依据 |
+| --- | --- |
+| 无需适配 | 未触发、已符合指导、原调用满足要求或仅需重编译，有具体源码和官方依据。 |
+| 可选适配 | 接受新行为或保留旧体验均符合已知业务要求；默认提出保留旧体验的方案并说明成本，交由 spec 确认。 |
+| 必须适配 | 已有证据表明会破坏所需业务、契约或编译正确性，需要具体修复；分类不等于批准。 |
+
+内部六类处理状态独立于 CSV 展示：NO_CHANGE→无需适配，MODIFIED→已适配，PENDING/DECISION_REQUIRED/EVIDENCE_GAP/OUT_OF_SCOPE→待决策，后者在处理说明和后续事项区分原因。保留原始rowId、内部状态、MODEL_ASSESSED及完整证据，不从三个展示值反推适配必要性或验收状态。
+
+同变更不同文件、同文件不同调用可分类不同。来源/条件/源码不明保留 EVIDENCE_GAP，业务决定缺失保留 DECISION_REQUIRED，不强行三分。用户明确接受新行为且符合业务约束时可依真实依据 NO_CHANGE，拒绝修改授权本身不能推定无需修复。
+
+复用[通用进度](../../templates/progress.md)：decisions.repair.plan 指向实际 spec.md，answer/approvedItems 保存真实批准；runtime 保存方式、分类范围、答复和必要 baselineDecision。包路径/哈希、构建和实测证据分别关联 evidence；归档不等于已测试。未答复保持 null，未执行保持 NOT_RUN。
+
+各组的 knowledge.originalReference 保留实际输入证据中的 Source Reference 原值并注明来自扫描 JSON 或历史 CSV；没有该字段时留空。localReference 保存已核实的当前章节路径及行号，官方 URL 另存来源证据；rawVersion/version 保留原始/规范化精确版本，并保存实际 readRanges 和 supplements；readRanges 只登记工具真实读取的 path/startLine/endLine，空值不表示已读。补充时记录 reason/url/readRange/content/difference。各文件 reason/evidence 保存实际实参/默认值、触发判断、SDK 和源码位置，参考[案例](upgrade-examples.md)但不逐项填无关问答；尚未处理保持 PENDING。
+
+rowClassifications 按 `{ "category": "无需适配", "rowIds": ["<输入sha256>:1"] }` 记录，每行至多一个分类，不包含未知或范围外 rowId。文件 adaptationCategory 仅在全部行分类一致时填写，否则为 null；三类统计以逐行分段为准。原 Fixed 和历史自动适用性只保留为输入，不继承为本次证明。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/references/generate-behavior-policy.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs, requireString } from '../../shared/format/args.mjs';
+import { parseCsv } from '../../shared/format/csv.mjs';
+import { atomicWrite, resolveInside, sha256 } from '../../shared/io/fs-utils.mjs';
+import { behaviorSourceHash } from '../../scanner/behavior/behavior-policy.mjs';
+import { loadChangelogIndex } from '../../shared/platform/changelog-index.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const catalogPath = path.resolve(requireString(args, 'catalog'));
+const referencesRoot = path.resolve(requireString(args, 'references'));
+const outputPath = path.resolve(requireString(args, 'output'));
+const catalogText = await readFile(catalogPath, 'utf8');
+const { rows } = parseCsv(catalogText);
+const changelogIndex = await loadChangelogIndex(referencesRoot);
+const indexedPaths = new Set(changelogIndex.documents.map(document => document.path.replaceAll('\\', '/')));
+
+function apiLevel(row) {
+  const directory = row['Source Reference'].replaceAll('\\', '/').split('/')[0];
+  const api = directory.match(/\((\d+)\)/);
+  if (api) return Number(api[1]);
+  if (directory === '26.0.0') return 26;
+  throw new Error(`Cannot derive API level: ${row['Source Reference']}`);
+}
+
+function policyId(row, sourceReference) {
+  let anchor = '';
+  try {
+    const url = new URL(row['Source URL']);
+    if (url.hash) anchor = decodeURIComponent(url.hash.slice(1)).toLowerCase();
+  } catch {
+    // Use the deterministic fallback below.
+  }
+  const suffix = sha256(sourceReference).slice(0, 8);
+  return `${anchor || 'behavior'}-${suffix}`;
+}
+
+const fileHashes = new Map();
+const entries = [];
+for (const row of rows) {
+  const level = apiLevel(row);
+  if (level < 13) continue;
+  const sourceReference = row['Source Reference'].replaceAll('\\', '/');
+  const reference = sourceReference.match(/^(.*):(\d+)$/);
+  if (!reference) throw new Error(`Invalid source reference: ${row['Source Reference']}`);
+  if (indexedPaths.size && !indexedPaths.has(reference[1]))
+    throw new Error(`Unknown changelog source: ${row['Source Reference']}`);
+  if (path.posix.isAbsolute(reference[1]) || path.win32.isAbsolute(reference[1])
+    || reference[1].split('/').some(part => !part || part === '.' || part === '..'))
+    throw new Error(`Invalid changelog source path: ${row['Source Reference']}`);
+  const sourceFile = resolveInside(referencesRoot, reference[1]);
+  let sourceHash = fileHashes.get(sourceFile);
+  if (!sourceHash) {
+    sourceHash = behaviorSourceHash(await readFile(sourceFile));
+    fileHashes.set(sourceFile, sourceHash);
+  }
+  entries.push({
+    policyId: policyId(row, sourceReference),
+    sourceAnchor: (() => {
+      try { return decodeURIComponent(new URL(row['Source URL']).hash.slice(1)).toLowerCase(); }
+      catch { return ''; }
+    })(),
+    title: row.Title,
+    sourceReference,
+    sourceUrl: row['Source URL'],
+    sourceFileHash: sourceHash,
+    changedInSdk: row['Changed in SDK'],
+    apiLevel: level,
+    affectedVersions: row['Affected Versions'],
+    affectedDeviceTypes: row['Affected Device Types'],
+    scope: row.Scope,
+    documentConclusion: row['Requires Adaptation'],
+    changeType: row['Change Type'] === 'UX Style/Effect Change' ? 'UX Visual Layout Change' : row['Change Type'],
+    triggerEvidence: row['Adaptation Guidance'] || row['Adaptation Basis'],
+    rationale: row['Adaptation Basis'],
+  });
+}
+
+entries.sort((left, right) => left.apiLevel - right.apiLevel
+  || left.policyId.localeCompare(right.policyId)
+  || left.sourceReference.localeCompare(right.sourceReference));
+const counts = entries.reduce((result, entry) => {
+  result[entry.changeType] = (result[entry.changeType] ?? 0) + 1;
+  return result;
+}, {});
+const output = {
+  schemaVersion: 1,
+  sourceCatalog: path.basename(catalogPath),
+  sourceCatalogHash: sha256(catalogText),
+  entryCount: entries.length,
+  counts,
+  entries,
+};
+await atomicWrite(outputPath, `${JSON.stringify(output, null, 2)}\n`);
+process.stdout.write(`${JSON.stringify({ outputPath, entryCount: entries.length, counts }, null, 2)}\n`);

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/references/references.mjs

@@ -0,0 +1,9 @@
+// Canonical text hashes used by official source regression tests.
+import path from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {sha256,sha256File} from '../../shared/io/fs-utils.mjs';
+const textExtensions=new Set(['.md','.json','.json5','.txt','.csv','.tsv']);
+export const isTextReference=file=>textExtensions.has(path.extname(file).toLowerCase());
+export async function referenceDigest(file) {
+  return isTextReference(file)?sha256((await readFile(file,'utf8')).replace(/^\ufeff/,'').replace(/\r\n?/g,'\n')):sha256File(file);
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/regression/compare-deprecated.mjs

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseDeprecatedBuildLog } from '../../scanner/deprecated/build-log.mjs';
+import { parseJson5 } from '../../shared/format/json5.mjs';
+import { parseArgs, requireString } from '../../shared/format/args.mjs';
+import { sha256 } from '../../shared/io/fs-utils.mjs';
+import { fileURLToPath } from 'node:url';
+import { relativePathInside, samePath, comparableCodeLocation, portablePath } from '../../shared/platform/paths.mjs';
+
+export async function compareDeprecated({ project, buildLog, scanJson, buildProjectRoot = project, buildEvidence = null, platform = process.platform }) {
+  const profile = parseJson5(await readFile(path.join(project, 'build-profile.json5'), 'utf8'));
+  const modules = profile.modules.map(item => ({ name: item.name, directory: portablePath(item.srcPath).replace(/^\.\//, '') }));
+  const scan = JSON.parse(await readFile(scanJson, 'utf8'));
+  const logText = await readFile(buildLog, 'utf8');
+  const gold = parseDeprecatedBuildLog(logText);
+  function location(relative) {
+    const module = modules.find(item => comparableCodeLocation(relative, null, platform).startsWith(`${comparableCodeLocation(item.directory, null, platform)}/`));
+    return module ? module.name + relative.slice(module.directory.length) : relative;
+  }
+  const rows = scan.findings.filter(item => item['Change Operation'] === 'API_DEPRECATED');
+  const records = gold.map(item => {
+    const relative = item.file ? relativePathInside(buildProjectRoot, item.file, platform) : null;
+    if (!relative) return { ...item, outcome: 'UNMAPPED_LOCATION' };
+    const codeLocation = `${location(relative)}:${item.line}`;
+    const matched = rows.find(row => comparableCodeLocation(row['Code Location'], null, platform) === comparableCodeLocation(codeLocation, null, platform) && Number(row.Column) === item.column
+      && [row.sdkEvidence?.name, row.sourceSymbol, row.compilerEvidence?.symbol].includes(item.symbol));
+    return { ...item, codeLocation, sourceScope: relative.split('/').includes('oh_modules') ? 'DEPENDENCY' : 'PROJECT',
+      outcome: matched ? 'MATCHED' : relative.split('/').includes('oh_modules') ? 'DEPENDENCY_EXCLUDED' : 'MISSING',
+      occurrenceId: matched?.occurrenceId ?? null };
+  });
+  const matchedIds = new Set(records.map(item => item.occurrenceId).filter(Boolean));
+  const evidence = buildEvidence ? JSON.parse(await readFile(buildEvidence, 'utf8')) : null;
+  const verified = evidence?.sourceSnapshot === scan.sourceSnapshot && evidence?.sdkSnapshot === scan.deprecationCoverage?.sdkSnapshot
+    && evidence?.buildProfileHash === scan.buildProfileHash
+    && evidence?.nonIncremental === true && evidence?.status === 'PASSED' && evidence?.logHash === sha256(logText)
+    && evidence?.targetSdk === scan.deprecationCatalog?.targetSdk && typeof evidence?.projectRoot === 'string'
+    && samePath(evidence.projectRoot, buildProjectRoot, platform);
+  return { schemaVersion: 1, evidenceStatus: verified ? 'MATCHED_BUILD_SNAPSHOT' : 'UNVERIFIED_HISTORICAL_LOG',
+    goldCount: records.length, projectGoldCount: records.filter(item => item.sourceScope === 'PROJECT').length,
+    dependencyGoldCount: records.filter(item => item.sourceScope === 'DEPENDENCY').length,
+    matchedCount: records.filter(item => item.outcome === 'MATCHED').length,
+    projectMissingCount: records.filter(item => item.outcome === 'MISSING').length,
+    unmappedCount: records.filter(item => item.outcome === 'UNMAPPED_LOCATION').length,
+    scannerOnlyCount: rows.filter(item => !matchedIds.has(item.occurrenceId)).length,
+    // Compiler silence is not a negative label; these require declaration evidence, not deletion.
+    scannerOnly: rows.filter(item => !matchedIds.has(item.occurrenceId)).map(item => ({
+      codeLocation: item['Code Location'], column: item.Column, sdkEvidence: item.sdkEvidence, outcome: 'SCANNER_ONLY_NOT_AUTOMATICALLY_FALSE_POSITIVE' })),
+    records };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = parseArgs(process.argv.slice(2));
+  const result = await compareDeprecated({ project: requireString(args, 'project'), buildLog: requireString(args, 'build-log'),
+    scanJson: requireString(args, 'scan-json'), buildProjectRoot: args['build-project-root'] || args.project, buildEvidence: args['build-evidence'] || null });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (result.projectMissingCount || result.unmappedCount) process.exitCode = 1;
+}