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

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

@@ -0,0 +1,219 @@
+# 按Kit分类的废弃API迁移说明与样例
+
+由废弃流程D05/D07按准确命中接口读取。Context/UIContext的获取、注入、服务及全局UI接口替换集中于[Context迁移专题](context-migration.md)。
+
+以下代码分别展示迁移前后模块或函数，只表示已满足替代版本前提的接口变化；完整低版本处理引用[兼容指南](../common/compatibility.md#迁移调用的版本与回退)，异常/Promise/失败传播引用[编码规范](../common/arkts-coding-standards.md#异常异步与-api-迁移)。表中版本对应准确接口与重载，不能将废弃版本当作替代起点。片段不表示设备验证通过。
+
+| Kit | 接口条目 |
+| --- | --- |
+| ImageKit | [ImagePacker编码](#imagepacker编码) |
+| AudioKit | [音量订阅与取消](#音量订阅与取消)、[音量读取](#音量读取) |
+| LocalizationKit | [Intl日期格式化](#intl日期格式化)、[ResourceManager媒体资源](#resourcemanager媒体资源) |
+
+## ImageKit
+
+### ImagePacker编码
+
+#### 接口说明
+
+适用：ImagePacker对PixelMap编码的Promise重载。
+
+| 旧接口 | 替代接口 | 版本信息 |
+| --- | --- | --- |
+| `packing(source: PixelMap, option: PackingOption): Promise<ArrayBuffer>` | `packToData(source: PixelMap, options: PackingOption): Promise<ArrayBuffer>` | 旧since8、deprecated13，新since13 |
+
+ImageSource另有对应Promise重载（新since13）；旧callback重载不能只换方法名，须按真实消费者另行迁移。`packing(Picture, ...)`不是本条旧PixelMap重载，不据同名批量替换。
+
+#### 迁移前
+
+```ts
+import { image } from '@kit.ImageKit';
+
+function encodeImage(packer: image.ImagePacker, source: image.PixelMap): Promise<ArrayBuffer> {
+  const options: image.PackingOption = { format: 'image/jpeg', quality: 1 };
+  return packer.packing(source, options);
+}
+```
+
+#### 迁移后
+
+```ts
+import { image } from '@kit.ImageKit';
+
+function encodeImage(packer: image.ImagePacker, source: image.PixelMap): Promise<ArrayBuffer> {
+  const options: image.PackingOption = { format: 'image/jpeg', quality: 1 };
+  return packer.packToData(source, options);
+}
+```
+
+#### 接口差异
+
+此重载仍返回Promise<ArrayBuffer>；编码参数、源PixelMap、返回数据和调用方的await/then/外层返回契约保持。packer由调用方持有，释放顺序不因替换改变；不在异步编码完成前释放PixelMap。新声明存在准确throws，按公共规范及原调用边界核对，不能把名字替换当异常等价证明。
+
+## AudioKit
+
+### 音量订阅与取消
+
+#### 接口说明
+
+适用接收者均为`audio.AudioVolumeManager`，不是AudioVolumeGroupManager。
+
+| 旧接口 | 替代接口 | 版本信息 |
+| --- | --- | --- |
+| `on('volumeChange', Callback<VolumeEvent>)` | `on('streamVolumeChange', StreamUsage, Callback<StreamVolumeEvent>)` | 旧since9、deprecated20，新since20 |
+| `off('volumeChange', Callback<VolumeEvent>?)` | `off('streamVolumeChange', Callback<StreamVolumeEvent>?)` | 旧since12、deprecated20，新since20 |
+
+#### 迁移前
+
+```ts
+import { audio } from '@kit.AudioKit';
+import { Callback } from '@kit.BasicServicesKit';
+
+function watchVolume(manager: audio.AudioVolumeManager, consume: (volume: number) => void): () => void {
+  const changed: Callback<audio.VolumeEvent> = (event: audio.VolumeEvent): void => {
+    consume(event.volume);
+  };
+  manager.on('volumeChange', changed);
+  return (): void => {
+    manager.off('volumeChange', changed);
+  };
+}
+```
+
+#### 迁移后
+
+```ts
+import { audio } from '@kit.AudioKit';
+import { Callback } from '@kit.BasicServicesKit';
+
+function watchVolume(manager: audio.AudioVolumeManager, consume: (volume: number) => void): () => void {
+  const changed: Callback<audio.StreamVolumeEvent> = (event: audio.StreamVolumeEvent): void => {
+    consume(event.volume);
+  };
+  manager.on('streamVolumeChange', audio.StreamUsage.STREAM_USAGE_MUSIC, changed);
+  return (): void => {
+    manager.off('streamVolumeChange', changed);
+  };
+}
+```
+
+#### 接口差异
+
+示例只适用于原业务需要媒体流音量的场景；具体usage按业务选择。订阅新增StreamUsage，取消接口不接受该参数。返回的清理函数继续使用同一manager、同一回调对象；调用方在原生命周期调用它，不能另建回调取消。旧事件与新事件是不同类型，不用断言互转。原有handleVolumeProgressChange、音量归一化和UI更新留在consume或其原位置，音量归一化使用原业务规则，不统一除以固定值。枚举选择非废弃的STREAM_USAGE_MUSIC，不新增已废弃STREAM_USAGE_MEDIA。
+
+### 音量读取
+
+#### 接口说明
+
+适用：原默认音量组中的媒体音量，可以按真实业务改为媒体usage读取；自定义音量组或其他AudioVolumeType不能机械套用。
+
+| 旧接口与接收者 | 替代接口与接收者 | 版本信息 |
+| --- | --- | --- |
+| `AudioVolumeGroupManager.getVolumeSync(AudioVolumeType): number` | `AudioVolumeManager.getVolumeByStream(StreamUsage): number` | 旧since10、deprecated20，新since20 |
+
+#### 迁移前
+
+```ts
+import { audio } from '@kit.AudioKit';
+
+async function readMusicVolume(manager: audio.AudioVolumeManager): Promise<number> {
+  const group = await manager.getVolumeGroupManager(audio.DEFAULT_VOLUME_GROUP_ID);
+  return group.getVolumeSync(audio.AudioVolumeType.MEDIA);
+}
+```
+
+#### 迁移后
+
+```ts
+import { audio } from '@kit.AudioKit';
+
+async function readMusicVolume(manager: audio.AudioVolumeManager): Promise<number> {
+  return manager.getVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC);
+}
+```
+
+#### 接口差异
+
+新方法放在AudioVolumeManager上，不加到旧group接收者。两个读取方法自身都同步返回number；此示例保留外部函数原有Promise<number>契约，不强制改变全部调用者。其他同步调用位置仍保持同步形态，不为了复用本例额外异步化。原音量值消费者和失败传播继续保留。
+
+## LocalizationKit
+
+### Intl日期格式化
+
+#### 接口说明
+
+适用：现有静态缓存用`zh-CN`、`weekday: 'short'`并调用format的具体日期格式化场景。旧Kit导出intl，新接口属于语言内置Intl，不能从Kit导入另一个同名对象。
+
+| 旧接口 | 替代接口 | 版本信息 |
+| --- | --- | --- |
+| `new intl.DateTimeFormat(locale, options)` | `new Intl.DateTimeFormat(locales, options)` | 旧有参构造since6、deprecated20；替代为语言内置Intl.DateTimeFormat |
+
+语言内置Intl不使用同一HarmonyOS @since标注，不能假定统一的API起始版本。[OpenHarmony4.1上游runtime具体用例](https://raw.githubusercontent.com/openharmony/arkcompiler_ets_runtime/OpenHarmony-4.1-Release/ecmascript/builtins/tests/builtins_date_time_format_first_test.cpp)仅支持此限定用法的证据分析，不冒充商业API13最低设备验收；当前SDK声明及编译也不替代最低设备运行。
+
+#### 迁移前
+
+```ts
+import { intl } from '@kit.LocalizationKit';
+
+class WeekFormatter {
+  private static formatter: intl.DateTimeFormat =
+    new intl.DateTimeFormat('zh-CN', { weekday: 'short' });
+
+  static format(date: Date): string {
+    return WeekFormatter.formatter.format(date);
+  }
+}
+```
+
+#### 迁移后
+
+```ts
+class WeekFormatter {
+  private static formatter: Intl.DateTimeFormat =
+    new Intl.DateTimeFormat('zh-CN', { weekday: 'short' });
+
+  static format(date: Date): string {
+    return WeekFormatter.formatter.format(date);
+  }
+}
+```
+
+#### 接口差异
+
+缓存身份、初始化时机、locale/options、输入日期及字符串消费者不变。移除该具体场景不必要的探测函数、双缓存、weekdayMap或仍使用小写intl的旧回退；不泛化到其他locale、options、Intl接口或加载方式。商业最低设备仍列待验收，未知版本事实不伪造。
+
+### ResourceManager媒体资源
+
+#### 接口说明
+
+适用于将Resource参数重载迁移为资源ID重载的媒体资源读取；原已使用数字ID的调用无需重复修改。
+
+| 旧接口 | 替代接口 | 版本信息 |
+| --- | --- | --- |
+| `getMediaContent(resource: Resource): Promise<Uint8Array>` | `getMediaContent(resId: number): Promise<Uint8Array>` | 两者since9；旧deprecated20，新非废弃 |
+| `getMediaContent(resource, density): Promise<Uint8Array>` | `getMediaContent(resId, density): Promise<Uint8Array>` | 两者since10；旧deprecated20，新 |
+| 对应Resource+callback重载 | 对应resId+callback重载 | 无density两者since9，带density两者since10；保持原callback形态 |
+
+#### 迁移前
+
+```ts
+import { resourceManager } from '@kit.LocalizationKit';
+
+function readMedia(manager: resourceManager.ResourceManager, media: Resource): Promise<Uint8Array> {
+  return manager.getMediaContent(media);
+}
+```
+
+#### 迁移后
+
+```ts
+import { resourceManager } from '@kit.LocalizationKit';
+
+function readMedia(manager: resourceManager.ResourceManager, media: Resource): Promise<Uint8Array> {
+  return manager.getMediaContent(media.id);
+}
+```
+
+#### 接口差异
+
+原Resource对应同一个Resource.id，不能改成其他业务对象的ID；manager、资源选择和Uint8Array消费者保持。带density及callback的调用保留原density、回调、错误边界和返回形态，不改成Promise或丢参数。跨bundle/module的Resource不能只丢弃定位信息：确认当前manager能解析该ID，否则改用实际匹配资源管理器或保留待决策/缺口，不机械抽取id。准确Resource和参数类型以SDK及真实调用为准。

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

@@ -0,0 +1,50 @@
+# Hvigor and device verification reference
+
+This provider-neutral reference is derived from the local `harmonyos-hvigor` skill used during authoring. DevEco, Hvigor, and device checks are verification capabilities: their absence must not block API impact analysis or safe source edits.
+
+## Environment checks
+
+Check these independently and record every result:
+
+- Java runtime; Hvigor requires Java 17 or newer.
+- Node.js runtime.
+- `ohpm`.
+- `hvigorw`.
+- `DEVECO_SDK_HOME`.
+- `hdc` and Emulator when runtime verification is requested.
+
+Do not modify global environment variables. A discovered DevEco bundled JDK may be used only for the spawned verification process.
+
+## Build sequence
+
+When the environment is compatible:
+
+1. Run `ohpm install` in the project root when dependencies are absent or installation is requested.
+2. For focused diagnostics, build an affected module with its project-defined target.
+3. Run the project build:
+
+```text
+hvigorw --mode project -p product=<product> assembleApp --analyze=normal --parallel --no-incremental --no-daemon
+```
+
+Use `--no-daemon` on Windows. This skill uses it on both Windows and macOS for deterministic process cleanup.
+
+Success requires exit code 0 and expected APP/HAP artifacts. Preserve complete logs in the run directory.
+
+## Device and emulator smoke verification
+
+1. Discover targets with `hdc list targets`.
+2. Read the bundle name from `AppScope/app.json5` and entry ability/module from the entry module's `module.json5`.
+3. Prefer a signed HAP on a physical device; an unsigned HAP may work on an emulator.
+4. Push the HAP to a unique directory under `data/local/tmp`.
+5. Install with `hdc shell bm install -p <remote-directory>`.
+6. Start with `hdc shell aa start -a <ability> -b <bundle> -m <module>`.
+7. Check process/lifecycle logs and capture a screenshot when the Emulator CLI supports it.
+8. Clean up the remote temporary directory and stop only the emulator instance started by this run.
+
+No matching emulator is a skipped verification result, not an adaptation failure.
+
+
+## Independent builds for HAR and its host
+
+For HAR scope use `--mode module -p product=<product> -p module=<module>@<target> assembleHar --no-incremental --no-daemon`. Build the selected host entry with assembleHap after verifying its local source/HAR dependency. A pure HAR project cannot use assembleApp. Bind both outputs to their actual build inputs; do not search other products for a stale signed HAP. Record host compilation and runtime separately from the library build.

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

@@ -0,0 +1,60 @@
+# HAR 行为适配与宿主集成
+
+本页供行为流程处理三方 HAR 被不同宿主集成时的特殊性。U01/U02确定库范围和扫描基线，U04/U05分析宿主差异并确认spec，U06归档所选原包及修复，U07/U08组织库、宿主构建及功能证据。通用设备行为边界与分支选择见[target 升级兼容](upgrade-compatibility.md)，本页不重复 API 保护机制或建立通用接口可用性匹配任务。
+
+## 范围与版本
+
+读取含products和模块注册的真实工程，确认HAR类型；scanner使用project-type har和明确scan-module/scan-dir，同类选择并集、不同类型交集，可支持已注册工程外模块。没有授权不扩大到宿主源码，联合升级分别保存原始输入、范围、计划和结果。
+
+库历史已适配from显式提供，可早于当前构建target；已target26可用原from20补齐行为，不回退配置。真实编译SDK、库target、宿主target、扫描基线与实际运行系统分别记录，不将其中任一项代替其余事实。
+
+## 宿主 target 与初始化
+
+HAR 合入应用后使用真实宿主 target。即使库构建 target=14，宿主 target=13 与14也可能使同一条已隔离行为呈现不同语义；库构建 target不证明已触发变化，历史已适配from也不能代替宿主target。若库公开契约要求一致行为，优先由库对实际宿主差异进行归一；不能无条件把新行为处理套给旧语义。无法在库内完成时明确应用侧所需调整及授权范围。
+
+需要运行时查询时，从真实 `getBundleInfoForSelf` 返回的 `BundleInfo.targetVersion` 取得值。例如以下片段只获取原始target，失败由Promise向调用方传播：
+
+```ts
+import { bundleManager } from '@kit.AbilityKit';
+
+async function readHostTargetVersion(): Promise<number> {
+  const info = await bundleManager.getBundleInfoForSelf(
+    bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION
+  );
+  return info.targetVersion;
+}
+```
+
+读取接口和标志本身按实际SDK及最低版本核对。复用库内已有初始化，在首次消费前等待完成，并按工程约定协调并发初始化和缓存。查询失败保留公开失败/恢复契约，不能将未就绪0或猜测target带入业务判断。按真实SDK返回编码解释门槛，不硬编码26，也不把官方旧样例的 `targetVersion % 100` 当成通用解码。
+
+设备具备新行为与宿主target达到隔离门槛分别判断，不能只查其中一项。通过新旧宿主测试归一结果时，也须满足[target 升级兼容](upgrade-compatibility.md#行为版本与-target-隔离)中的设备条件。
+
+## 集成版本约束
+
+以下规则提炼自 2026-08-28 [三方 HAR 兼容指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-third-har)，集成时回读库元数据、宿主配置和真实工具链：
+
+| 信息 | 需要核对的约束 |
+| --- | --- |
+| 源码 HAR 的 compile | 应用编译 SDK 不低于库编译 SDK |
+| 字节码 HAR 的 compile | 不套用源码 HAR 的同一版本比较限制；仍核对实际字节码、工具链和原生 ABI 要求 |
+| compatible | 应用 compatible 不低于库声明的 compatible；库内部版本分支不能消除打包约束 |
+| target | 合入后的行为按真实宿主 target 判断，不能用库 target 替代 |
+
+例如应用compatible12、库compatible13时，不能仅加一个运行时 `if` 解决集成错误。保持库/宿主原compatible，说明真实冲突和支持范围；需要调整依赖或配置时纳入获批方案，不自动提高应用compatible或无依据把库改成12。缺少依赖源码时保留边界，不擅自修改第三方包。
+
+集成态HSP只作为现有依赖关系知识，不新增独立扫描入口；其包可有独立target，不能一律套宿主值。实际包关系见[集成态 HSP 官方说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-share-hsp)。
+
+## 构建与宿主消费
+
+1. U07按真实注册target先对所选库assembleHar，保留本次产物、日志和退出码，纯库不运行assembleApp。
+2. 核对根/模块oh-package及实际解析依赖；源码依赖证明物理位置是本次库，HAR文件依赖核对路径与字节哈希，再按授权同步本地副本。不能只改声明却继续消费旧oh_modules内容。
+3. 明确唯一宿主product/entry和签名，真实构建宿主HAP，分别保存库/宿主输入状态、命令、日志及产物。宿主编译成功不自动证明实际消费本次库。
+4. 已选择设备验证时安装当前宿主包，核对真实业务调用/返回/回调到库的路径并关联rowIds；有多个已授权宿主组合时分别记录target、设备和结果，不用同页截图泛称覆盖，不自动增加最低系统矩阵。
+
+多入口明确实际选择，独立宿主由用户提供或真实依赖确定，不猜相邻Demo。缺宿主仍可交付库构建事实及未执行范围，依赖/签名/安装失败与库已编译分别表达。
+
+## 行为对比与联合任务
+
+只有行为任务选择对比才在修改前真实构建并归档原库及实际消费它的宿主 before 包，不能用 HAR 文件代替可运行宿主。修复后生成用例，先测试归档 before，再复位数据测试 after；库消费关系、同设备系统、同语义用例和可复位数据须可核对，缺基线不回退工程补造。取证方法见[行为对比](../common/runtime-functional-tests.md#行为前后对比)。
+
+共用工程/product时协调原配置与源码基线，影响行为基线的修改须等待原包有效归档或用户明确改为其他验证方式；原包已归档后设备不可用只影响测试，不再阻塞修复。实际一次宿主测试可分别关联库/应用，但须说明具体消费关系、阶段与原始行，不恢复自动联动状态机或构建缓存。

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

@@ -0,0 +1,171 @@
+# Scanner 可能漏报的编译与工程案例
+
+本页用于出现真实 build error，或用户明确报告混淆失效、发布包异常时按线索查阅。它不是扫描后的主动核查清单；正常扫描、CSV 零行、构建成功且没有异常报告时，不自动通读或逐项检查。官方目录存在某项变更也不代表接口匹配式 scanner 能发现工程里的具体用法；不同工具版本的覆盖以真实结果为准。
+
+## 按错误或异常检索
+
+| 错误/异常特征 | 对应案例 | 匹配限制 |
+| --- | --- | --- |
+| The V1 decorator … cannot be applied to a Function-type variable | [状态管理 V1 函数字段](#状态管理-v1-函数字段) | 必须确认诊断中的装饰器、字段及真实函数类型 |
+| The service widget file contains one or more references to HSPs | [卡片引用 HSP](#卡片引用-hsp) | 结合卡片入口和直接/传递依赖，普通应用使用 HSP 不等于该问题 |
+| Property 'getState' is missing … CustomDialogController | [控制器字面量初始化](#customdialogcontroller-字面量初始化) | 其他类型的同名缺失属性不能套用 |
+| 用户报告依赖混淆开关失效、升级后发布包混淆结果或运行行为变化 | [依赖混淆规则合并](#依赖混淆规则合并) | 无固定 build error；不能只因发布失败或包变大就认定 |
+
+## 使用方法
+
+1. 保存真实命令、工具版本、退出码和完整日志，提取具体错误主句、符号/类型、文件位置及前置上下文；只有 BUILD FAILED、任务名或退出码不足以匹配。
+2. 按错误的稳定短语/符号检索本页索引，只读相关案例。错误中的装饰器、字段名或路径可不同，但必须核对完整语义，不按一个关键词自动定因。
+3. 回读对应官方完整说明、准确 SDK、实际源码/配置与依赖链，区分升级变化、本次引入错误、既有问题和工具/签名等环境故障。未匹配或证据不足时继续[常规排错](../common/troubleshooting.md#定位与停止)，不强行套用。
+4. 核对获批方案和实际修改范围；同一获批方案的必要实现修正可继续，新增业务方案、共享配置或范围变化需更新 spec 并取得相关批准。匹配案例本身不是修复授权。
+5. 按真实差异记录诊断、依据、修复与重建结果。没有 CSV 对应行的错误保存在编译日志和现有进度/报告说明，不伪造扫描记录、rowId 或分类统计，不新增补充项协议。正常构建与设备测试沿用当前流程，失败次数不因查到案例而重置。
+
+## 状态管理 V1 函数字段
+
+**来源与条件**：[6.1.0(23) 官方完整章节](../changelogs/6.1.0(23)/changes-for-all-apps.md#新增状态管理v1校验报错)。该条增加编译校验：自定义组件 struct 中，状态管理 V1 装饰器不能装饰 Function/函数签名类型字段。按真实编译器诊断确认，不拿装饰器自身 since 或 target 隔离推定是否报错。
+
+**错误特征**：
+
+```text
+The V1 decorator '@State' cannot be applied to a Function-type variable 'callback'.
+```
+
+装饰器和字段名以实际日志为准。官方范围包括 State、Prop、Link、Provide、Consume、StorageLink、LocalStorageLink、StorageProp、LocalStorageProp、ObjectLink；Watch 是状态观察机制，不能当作可统一替换的另一种函数状态字段。
+
+**确认影响**：定位字段声明及推导类型，核对类型别名、初始化、赋值与调用者。诊断为非函数类型错误、方法参数或无关对象时不能套用本例；没有 V1 函数字段时不据此迁移整个状态管理体系。
+
+下例是明确的错误用法：
+
+```ts
+@State callback: (input: number) => void = (input: number): void => {};
+```
+
+如果它是本组件普通回调，移除不受支持的状态装饰器，保留函数签名和业务体。下面只展示修复后的组件字段及调用：
+
+```ts
+@Entry
+@Component
+struct CallbackExample {
+  @State value: number = 0;
+  private callback: (input: number) => void = (input: number): void => {
+    this.value = input;
+  };
+
+  build() {
+    Button('调用回调')
+      .onClick(() => {
+        this.callback(1);
+      })
+  }
+}
+```
+
+**边界与验证**：Prop/Link、父子绑定、存储同步或外部重新赋值的字段不能只删装饰器就认定语义等价，须重新确认回调传递和更新方案；不将函数字段与 V2 的方法装饰器混为一谈，不强制全量迁移 V2。重新完整构建，验证初始化、调用次数、参数、父组件更新后调用的实际函数及资源清理；编译通过不单独证明父子语义保留。
+
+## 卡片引用 HSP
+
+**来源与条件**：[官方构建变更条目](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/ide-changelogs-501#section162648113588)。以实际 DevEco/Hvigor 的校验及对应版本说明为准，不把 API target 当工具版本门槛，不无依据硬编码精确 IDE 起点。
+
+**错误特征**（须与真实日志核对）：
+
+```text
+The service widget file contains one or more references to HSPs.
+```
+
+**确认影响**：沿编译器指出的文件回查真实卡片配置、入口页面、import/导出、模块元数据和解析依赖。检查直接引用，以及如下传递依赖；不能只看卡片页面没有 HSP import 就排除。
+
+```text
+卡片页面 → 公共 HAR → HSP
+```
+
+没有卡片，或卡片实际依赖闭包不包含 HSP 时，不套用本例。不要与“卡片调用未标识卡片能力的 API”这一运行时能力限制混为一谈。
+
+**最小方案**：已有满足卡片能力的 HAR 时改用真实 HAR 依赖；HSP 同时供普通页面使用时，优先抽取卡片可用的公共 HAR，让卡片依赖闭包不再包含 HSP，原应用入口按原契约使用 HSP。按真实 module.json5、模块注册、Hvigor 插件、oh-package 及消费产物核对方案，不给出“只在 build-profile.json5 把 type 改成 har”即完成迁移的通用步骤。
+
+```text
+卡片页面 → 卡片公共 HAR（依赖闭包不含 HSP）
+应用普通页面 → 原 HSP → 可复用的公共 HAR
+```
+
+第三方 HAR 间接依赖 HSP 时，不改 oh_modules 或第三方二进制冒充修复；评估可用的库版本/替代实现，缺源码或卡片能力不明时保留缺口。模块拆分和其他入口影响须纳入批准范围。
+
+**验证**：真实完整构建，确认具体诊断消失及实际依赖/产物确已变化；按授权回归卡片渲染、刷新、点击跳转及依赖初始化，普通入口和原 HSP 也保留回归范围。只改 import 文本或改配置字段不能证明实际消费已切换。
+
+## CustomDialogController 字面量初始化
+
+**来源与条件**：[6.0.0(20) Beta1 官方完整章节](../changelogs/6.0.0(20)/beta1-os-api-behavior-changes.md#使用字面量初始化customdialogcontroller类实例导致的编译行为变更)。类新增成员后，原先 `{ open() {}, close() {} }` 形式不能满足真实类声明；根据当前 SDK 与诊断判断，不用运行时版本分支掩盖编译类型错误。
+
+**错误特征**：
+
+```text
+Property 'getState' is missing in type '{ open(): void; close(): void; }' but required in type 'CustomDialogController'.
+```
+
+核对接收者确为 SDK CustomDialogController。无关接口也缺 getState、普通业务对象或真实 SDK 与文档不一致时，不自动套用。
+
+**最小方案**：使用真实构造器并保留原 builder、取消回调和显示配置。下面是具有 builder 的最小示例，而不是无参 new 或补空 getState：
+
+```ts
+@CustomDialog
+struct ExampleDialog {
+  controller: CustomDialogController;
+
+  build() {
+    Column() {
+      Text('示例弹窗')
+      Button('关闭')
+        .onClick(() => {
+          this.controller.close();
+        })
+    }
+  }
+}
+
+@Entry
+@Component
+struct DialogExample {
+  private dialogController: CustomDialogController = new CustomDialogController({
+    builder: ExampleDialog()
+  });
+
+  build() {
+    Button('打开')
+      .onClick(() => {
+        this.dialogController.open();
+      })
+  }
+}
+```
+
+**误匹配与验证**：不要给对象补空 getState、伪造返回值或强转为类来消除报错；也不能将原本的测试替身/业务接口强行变成真实 UI 弹窗，应按该场景重设类型边界。构建后核对打开、关闭、取消、重复打开和原生命周期/资源清理，不因使用构造器而覆盖原弹窗配置。
+
+## 依赖混淆规则合并
+
+**来源与条件**：[5.1.0(18) 官方完整章节](../changelogs/5.1.0(18)/os-api-behavior-changes.md#默认不合并依赖混淆规则变更说明)。以真实编译工具链规则为准，不能把章节中的接口起始 API10 当行为门槛，也不能仅凭 target 值判断混淆合并规则。
+
+**异常特征**：没有固定编译报错。这项变化可能在构建通过后改变发布产物的混淆效果；仅在用户明确报告相关异常时查阅，不因没有 error 就认定不受影响，也不为本例编造错误码。
+
+**确认影响**：核对本次构建模式、模块是否实际启用混淆、实际加载的当前模块规则，以及依赖 HAR 的 consumer 规则/三方库导出规则。变更前合并依赖的所有混淆配置，变更后默认只合并依赖的保留选项；当前模块自己的开关不因此消失。依赖没有相关开关、混淆未启用或产物并非本次构建时，不能直接断言是本条原因。
+
+下面的依赖规则包含开关与保留项，二者需要分开看：
+
+```text
+-enable-property-obfuscation
+-keep-property-name
+publicName
+```
+
+**方案一：显式保留需要的混淆效果。** 已核实业务需要属性混淆且其他依赖开关不应继承时，在当前编译模块实际加载的规则文件中显式配置所需选项；其余业务保留项不删除。例如：
+
+```text
+-enable-property-obfuscation
+```
+
+**方案二：恢复全部依赖开关合并。** 确实需要旧合并行为且已审查依赖开关影响时，按官方指导在当前编译模块的 obfuscation-rules.txt 增加：
+
+```text
+-enable-lib-obfuscation-options
+```
+
+此开关会恢复依赖的全部混淆选项，不只是某一个缺失选项。官方变更本就为避免三方库开关意外影响应用，不能机械地对所有模块加该开关，也不能为保留原业务而引入依赖中的非预期配置。只修改实际获批的工程规则，不改第三方原件。
+
+**验证**：使用真实启用混淆的发布构建，保存版本、模式、有效规则和本次产物，核对目标开关效果与依赖保留名；按授权验证导出接口、反射/动态访问和实际运行。Debug 构建通过、HAP 体积增大或字符串变化只能提供线索，不能单独定因或证明已修复。多模块按真实消费和各自规则分别核验，不把一个模块的设置当全工程生效。

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

@@ -0,0 +1,112 @@
+# target 升级后的行为兼容
+
+本页供行为流程 U02、U04、U05、U06、U07、U09 使用：应用升级 `targetSdkVersion`，而 `compatibleSdkVersion` 仍覆盖较低系统时，按官方行为边界保留各系统所需业务。配置与版本背景见[版本契约](../common/sdk-versions.md)，HAR 追加[宿主专题](har-upgrade.md)，具体业务修改示例见[行为代码示例](upgrade-examples.md)。
+
+本页提炼自 2026-08-28 [升级 target 兼容低版本指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-upgrade)及[兼容性关键信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-influence-factor)。适配依据是命中条目的完整官方说明和真实工程，不因 target 高于 compatible 就给所有调用增加分支。
+
+## 行为版本与 target 隔离
+
+分别记录以下事实，不能相互替代：
+
+| 事实 | 用途 |
+| --- | --- |
+| 接口起始版本 | 说明接口何时存在；不作为行为变化的门槛 |
+| 行为变更版本与触发条件 | 判断设备是否具有该变化，以及当前业务是否受影响 |
+| 官方 target 隔离门槛 | 仅在官方明确隔离时，结合真实应用或宿主 target 选择语义 |
+| compatible 与设备 API | 确认仍需支持哪些系统，以及当前设备实际采用的行为 |
+
+对明确按 target 隔离的变更：
+
+| 设备和 target 条件 | 应理解的行为 |
+| --- | --- |
+| 设备早于行为变更版本 | 设备保留旧行为；提高 target 不会使旧设备获得新实现 |
+| 设备已有变更，真实 target 低于隔离门槛 | 按官方隔离规则采用旧语义 |
+| 设备已有变更，真实 target 达到隔离门槛 | 在满足官方触发条件的调用上采用新语义 |
+
+未按 target 隔离的变更，不能靠保持旧 target 规避；仍按设备行为版本和具体影响范围判断。隔离状态未明确时保留证据缺口，不假设存在隔离。
+
+例如接口自API12存在，API14发生行为变化，target升至26而compatible保持13：需要判断的是API13设备上的旧行为与API14及以后设备上的新行为，不能按接口since12统一执行新方案，也不能把行为门槛统一写成目标26。若某条另有target门槛，继续按它的官方条件及实际宿主判断。
+
+## 先判断是否需要版本分支
+
+若原接口已支持的显式参数可以在整个支持范围内保持所需效果，优先直接设置，不增加无意义分支。例如大图确需保留原图解码时显式 `autoResize(false)`；固定小图未触发默认值变化时可无需修改。
+
+只有新旧行为需要不同业务处理时，才按准确设备边界保留原低版本逻辑，并将方案纳入 U05 汇总批准。回调、订阅/取消、初始化及清理跨越同一行为时保持分支和资源身份一致，不能仅保护其中一个调用。
+
+这属于本次行为的跨系统处理，不恢复废弃流程中的通用接口可用性匹配或最低设备任务。保持原 compatible，不新增行为复扫；真实语法、类型和完整构建仍须执行。
+
+## ArkTS 与 C 行为分支
+
+以下片段仅说明**旧格式API14行为边界**，两侧注释须接入工程真实业务。API家族由准确声明和SDK来源确认，判断阈值取该条行为变化版本，而非接口since。
+
+### OpenHarmony 底座接口
+
+确认查询接口本身满足工程最低版本后，ArkTS 使用 `sdkApiVersion`，C 使用 `OH_GetSdkApiVersion()`：
+
+```ts
+import { deviceInfo } from '@kit.BasicServicesKit';
+
+if (deviceInfo.sdkApiVersion >= 14) {
+  // 执行官方指导要求的 API14 及以后业务处理。
+} else {
+  // 保留此调用原有的低版本业务。
+}
+```
+
+```c
+#include <deviceinfo.h>
+
+void HandleBaseBehavior(void) {
+    if (OH_GetSdkApiVersion() >= 14) {
+        // 执行该行为变化后的业务处理。
+    } else {
+        // 保留原业务。
+    }
+}
+```
+
+### HarmonyOS 专有接口
+
+旧格式 `5.0.2(14)` 的平台版本数值为 `50002`。ArkTS 使用 `distributionOSApiVersion`，C 使用 `OH_GetDistributionOSApiVersion()`：
+
+```ts
+import { deviceInfo } from '@kit.BasicServicesKit';
+
+if (deviceInfo.distributionOSApiVersion >= 50002) {
+  // 执行该专有接口在 5.0.2(14) 变化后的业务处理。
+} else {
+  // 保留原业务。
+}
+```
+
+```c
+#include <deviceinfo.h>
+
+void HandleDistributionBehavior(void) {
+    if (OH_GetDistributionOSApiVersion() >= 50002) {
+        // 执行该行为变化后的业务处理。
+    } else {
+        // 保留原业务。
+    }
+}
+```
+
+`50002` 不是 API Level14，不能与 `sdkApiVersion` 互换。设备属性只解释设备行为；HAR 的宿主 target 仍按[宿主专题](har-upgrade.md#宿主-target-与初始化)另行取得。
+
+### API26 及以后的机制选择
+
+先核对行为版本的粒度、实际SDK属性的含义及工程最低版本。不能把旧平台编码、只比较主版本或旧 `targetVersion % 100` 当作适用于后续所有版本的规则；同一主版本内的变化尤其不能只看主版本。
+
+`sdkMinorApiVersion`、`sdkPatchApiVersion` 自身也从26.0.0引入，不能直接加到compatible13的公共判断路径中。新增版本查询属性与查询函数一样，先核对其自身门槛。
+
+本流程新增 `apiAvailable`、`@Available`、`@SuppressWarnings` 时，同样要求 compatible 满足各自起始版本（分别为26.0.0、API22、API23），并核对配套工具链。compile/target=26、compatible=13时，不能直接调用 `apiAvailable` 来判断设备，也不能用它保护自身。使用最低版本已支持且能准确表达行为边界的属性或既有判断；没有足够版本证据时保留 EVIDENCE_GAP，不猜公式、不提高 compatible。上述机制的完整语法只在[API 保护专题](../common/compatibility.md#先检查保护机制自身的版本)维护，行为无需整体加载废弃迁移规则。
+
+C/C++ 的设备行为判断也不消除高版本符号的加载风险；不因行为任务自动启用弱引用或改写链接方案。若新方案依赖额外高版本能力，先明确能否在当前支持范围实施，存在缺口时调整方案或保留具体问题，不能把版本 `if` 当作加载安全证明。
+
+## 记录与验证边界
+
+U04 在现有 reason/evidence 中评估行为版本、target隔离、实际设备范围和分支必要性；U05汇总spec并取得批准，U06实施，U07复核两侧语义、真实target及compatible未变。无需分支时说明显式参数或原调用为何覆盖所需业务。
+
+U09使用现有 `files.compatibility` 和报告记录完整兼容结论；行为CSV只在处理说明中写相关修改、作用及理由，未解决或待人工验证的事项写入后续事项，不追加兼容性说明列或新状态。存在跨系统差异时写清已处理内容与尚缺证据；没有相关差异时不强制逐API生成兼容性清单。
+
+设备操作继续使用用户已选范围和授权。只做高版本设备验证时，低版本运行写未验证；未选设备不启动或安装。已有授权明确覆盖行为边界时，分别保存各系统实际结果；同设备同系统的before/after对比只证明该系统上的变化，不能代替跨系统覆盖，也不为此自动增加最低系统矩阵。