@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/common/arkts-coding-standards.md

@@ -0,0 +1,53 @@
+# ArkTS 编码规范
+
+修改 ArkTS 或 ArkUI 前阅读，修改后按实际差异复核。按当前主流程指定范围使用本页；已有无关风格问题不扩大整改。真实编译要求见[完整构建与产物](verification.md#完整构建与产物)。
+
+## 项目约定与作用域
+
+- 先读取工程 AGENTS、formatter/linter 配置及邻近实现，保留公开接口、框架规定名称和现有依赖边界。项目具体约定优先于下面的通用格式；兼容性与真实验证仍须满足主流程要求。
+- 生产源码检查命名、格式、类型、API 安全、资源、常量、日志与异常。ohosTest 和本地测试同样保持类型与 API 安全，但不机械提取等待时间、断言值或夹具数据，不开展无关颜色整改。
+- 所选 SDK 声明、ArkTSCheck 和构建输出决定接口、类型与语法是否可用。不用普通 TypeScript 工具通过代替目标 SDK 的检查，也不要求安装其他 Skill 或新工具才能阅读规则。
+
+## 命名与格式
+
+- 类、接口、枚举、组件及类型使用 PascalCase；变量、字段、函数和参数使用 camelCase；常量及枚举值使用 UPPER_SNAKE_CASE；自定义组件 id 使用 kebab-case。遵守项目及框架已有的必要例外，不改名破坏消费者。
+- 名称表达业务意图；布尔值使用 is/has/can/should 等明确前缀，避免拼音、无上下文缩写和双重否定。
+- 优先遵循工程 formatter 与邻近代码。没有规定时，默认空格缩进2格、续行4格、单引号、120列；URL、命令和不可拆分的错误信息可例外。
+- 对象属性超过4个时逐项换行；不在同一行声明多个变量。控制语句使用大括号，保持 `} else {`、`} catch {`，运算符与逗号留适当空格，不手工用连续空格对齐。
+- 注释解释版本限制、生命周期或业务原因；修改行为时更新失效注释，不复制与实现不符的迁移说明。
+
+## 类型、语法与 ArkUI
+
+- 使用所选 SDK 支持的准确类型、参数和返回形态，保持强类型；普通数组优先 `T[]`。只有真实互操作边界需要时才使用 SDK 允许的 any/ESObject，并说明边界，不能用宽泛类型或不安全断言消除真实错误。
+- 对可空值先核对来源并在有效控制流中收窄，不以非空断言、虚构空对象或默认成功值掩盖获取失败。
+- 构造器按 SDK 支持的显式字段声明和赋值处理，不直接套用 TypeScript 参数属性；新增函数、helper、IIFE 和异步返回须符合实际 ArkTS 检查要求。
+- 保持原 ArkUI 状态管理范式、数据所有权和组件生命周期，不为迁移一处 API 整体切换 V1/V2。
+- 不在条件表达式中赋值；使用 `Number.isNaN` 判断 NaN。`finally` 不引入会覆盖原结果或异常的 return、break、continue、throw。
+- 转换、过滤、查找优先考虑 map/filter/find/some；索引、提前结束或性能要求更明确时保留循环，不为形式统一重写有效业务。
+
+## 资源、常量与日志
+
+- 本次新增或修改的 UI 优先复用真实存在的语义颜色资源和项目 token，核对文本、图标、背景、边框用途；不虚构 SDK 资源，不顺带替换整页配色。
+- 对重复或承载业务/布局含义的数字提取有意义常量。简单0/1、哨兵值与合理测试夹具可保留，不机械给每个字面量命名。
+- 新日志先查已有 Logger/hilog、domain、tag 和安全错误格式化函数，按真实签名复用。不得新增 console、无关日志模块或依赖。
+
+## 异常、异步与 API 迁移
+
+- 修改前从准确 SDK 声明、实际检查输出及调用上下文确认 throws、Promise 和废弃状态。已有有效异常处理可保留，不因担心而为每个调用增加 catch。
+- 新增获取链、调用或同步转异步时，按最小且语义完整的边界处理失败，保留原返回值、reject/resolve、回调次数及同身份 on/off。
+- await 流程可沿用语义一致的外层 try/catch；未 await 的 Promise 必须有明确的失败传播或处理。catch 应明确恢复、记录后继续或重抛，不吞错、不返回猜测的成功值。
+- 复用项目错误记录方式，保留必要错误信息；不通过强制类型转换假定未知错误形态，不添加空 catch 或无业务作用的捕获后原样重抛。
+- 新调用的类型、参数和返回契约按真实SDK声明核对；废弃迁移的接口保护按[API保护指南](compatibility.md)；行为跨系统差异按[target升级兼容](../upgrade/upgrade-compatibility.md)选择必要分支，不扩展为通用接口可用性匹配。
+
+### 迁移中的表达式与失败出口
+
+- 等价替换未扩大风险时，保留有效原catch、原异常传播与后续业务，不因SDK有throws就给每次UI调用复制try/catch；继承风险单独说明。新增获取链、可空来源或不同异常形态仍独立核对。
+- 在完整语义边界处理失败。void函数只在原允许结束的失败路径return；正常调用后还有业务语句时不新增return。原函数返回false、枚举或其他失败结果时保留既有出口，不制造空串、undefined、零值或ArrayBuffer/void联合来绕过类型错误。
+- 保留参数求值、await、可选链及回调顺序。同一语句多个替换先判断能否安全合成；只有变量需要跨try/catch或版本分支使用时，才拆成准确类型局部变量，不引入无返回类型IIFE或额外控制层。
+- Promise迁移同时核对所有消费者。原await/then的结果、外层return/resolve/reject与回调次数须连续保留；不能替换成只在内部处理却让外层Promise悬空的调用。未await的Promise不能由外层同步try/catch单独处理拒绝，空catch、默认成功和重复无效日志不算失败处理。
+
+## 修改后的复核
+
+检查实际差异是否满足以上适用规则，再执行可用 SDK/IDE 检查与真实完整构建。源码、配置或 SDK 再变更时重新验证；模型复核、提示性扫描与日志文件存在不能关闭编译待办。缺工具或编译失败时保留可信修改与原因，按[部分交付](troubleshooting.md#部分交付)报告。
+
+官方入口：[ArkTS 编码规范](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-coding-style-guide)。具体 API 与语法仍以本次工程真实使用的 SDK 和工具链核实。

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

@@ -0,0 +1,207 @@
+# API 兼容性保护与告警屏蔽
+
+废弃 API 迁移按本页选择接口保护、告警处理和低版本回退；target 升级引起的行为差异见[升级兼容专题](../upgrade/upgrade-compatibility.md)。本页不编排行为适配步骤。配置字段、版本格式、API 家族和设备查询统一见[版本契约](sdk-versions.md)。
+
+本页提炼自 2026-08-28 官方兼容性指导快照。机制的起始版本以准确 SDK 声明为准，编译器与 IDE 须配套；样例只表达保护方式，业务回退必须替换为工程原有的真实处理。
+
+## 先检查保护机制自身的版本
+
+本流程新增使用兼容性 API 和源码注解时，**compatibleSdkVersion 必须达到该机制自身的起始版本**，并且实际编译 SDK、编译器和 IDE 均支持。仅 compile/target 达到 API23 或 API26 不满足选用条件；不能为了使用保护机制提高 compatible。
+
+| 机制 | 自身起始版本及本流程 compatible 门槛 | 其他条件与作用 |
+| --- | --- | --- |
+| `deviceInfo.apiAvailable` | `26.0.0`，compatible ≥ `26.0.0` | 真实设备版本判断；核对 SDK 声明和编译器识别范围 |
+| `@Available` | API22，compatible ≥ API22 | 源码级版本声明，参与编辑/编译检查，不生成运行时分支 |
+| `@SuppressWarnings`、`SuppressWarningsType.COMPATIBILITY` | API23，compatible ≥ API23 | 兼容告警屏蔽还要求支持该能力的工具链；快照为 DevEco Studio 6.1.0 Beta2 起 |
+
+上表是本流程的选用约束；源码注解的编译检查作用与运行时能力分开理解。C/C++ 的 `APIAVAILABLE` 宏、弱引用和弱库按下文的编译器与加载规则选择，不统一套用 ArkTS API 的门槛。
+
+例如 compile/target=26、compatible=13 时，不新增 `apiAvailable`、`@Available` 或 `@SuppressWarnings` 来保护 API18。应按准确家族使用最低版本已支持的 `sdkApiVersion` 或 `distributionOSApiVersion`，分别核验查询属性自身的 since，保留旧业务。不能用 `apiAvailable` 调用自身来证明它在旧设备可用，也不能用屏蔽告警替代实际保护。
+
+## ArkTS 接口保护
+
+### compatible 较低时使用已有版本属性
+
+底座接口按 `deviceInfo.sdkApiVersion` 判断；旧格式 HarmonyOS 专有接口按 `deviceInfo.distributionOSApiVersion` 判断，家族与编码见[版本契约](sdk-versions.md#api-家族与设备查询)。以下以已经核实属于底座、API18 起可用的替代能力为例，适用于查询属性已满足工程最低版本的场景：
+
+```ts
+import { deviceInfo } from '@kit.BasicServicesKit';
+
+if (deviceInfo.sdkApiVersion >= 18) {
+  // 执行已核实 API18 起可用的替代调用。
+} else {
+  // 保留工程原有的低版本业务。
+}
+```
+
+### apiAvailable 的参数与识别边界
+
+仅在上表门槛满足时使用 `deviceInfo.apiAvailable(version: string | number): boolean`。入参是**被保护能力的版本**，与该查询 API 自身的起始版本是两项事实。
+
+| 被保护版本 | 参数示例与限制 |
+| --- | --- |
+| API26 及以后 | `'26.0.0'`；语义化 `X.Y.Z`，`0 ≤ Y,Z ≤ 99`，OpenHarmony 要求 `X ≥ 26` |
+| API26 前 OpenHarmony 底座 | 整数字面量，如 `22`，范围 `0 < X < 26`；不把整数 `26` 当通用写法 |
+| API26 前 HarmonyOS 专有接口 | 如 `'5.0.1'` 或 `'5.0.1(13)'`；主版本小于26时须是工具链支持的 HarmonyOS 版本 |
+
+下例仅展示 compatible ≥ 26.0.0 且工具链支持时的直接 `if` 写法：
+
+```ts
+import { deviceInfo } from '@kit.BasicServicesKit';
+
+if (deviceInfo.apiAvailable('26.0.0')) {
+  // 执行该版本可用的能力。
+} else {
+  // 按业务保留必要的回退。
+}
+```
+
+快照中的告警消除只识别直接传版本字面量的 `if`，不识别变量版本参数、缓存布尔结果、自定义封装、三元表达式或 `&&`、`||`、`!` 复合条件。例如：
+
+```ts
+const available: boolean = deviceInfo.apiAvailable('26.0.0');
+if (available) {
+  // 不能据此声称编译器已识别保护。
+}
+```
+
+这是兼容检查的识别限制，不等于普通布尔运算无效；变量版本参数还可能触发编译诊断。需要业务条件时先直接判断版本，再在分支内判断业务，并执行实际检查。
+
+依据：[ArkTS API 兼容保护](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/arkts-api-compatibility-warning-elim)、[apiAvailable 参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-device-info#deviceinfoapiavailable)。
+
+## 版本注解与告警屏蔽
+
+### @Available 声明约束
+
+仅在 compatible ≥ API22 且工具链支持时新增此注解。它将最低版本约束传给调用方，不执行运行时分支或生成回退。下面只展示源码声明：
+
+```ts
+import { Available } from '@kit.BasicServicesKit';
+
+@Available({ minApiVersion: 'OpenHarmony 22' })
+class Feature22 {}
+```
+
+可标注变量、类型、函数、命名空间、注解声明及 struct/class/interface 成员，不能标注任意 `if`、调用等非声明语句。HarmonyOS 工程支持如 `'22'`、`'OpenHarmony 22'`、`'HarmonyOS 6.0.2'`；API26 语义格式如 `'26.0.0'` 还须核对工具链支持。OpenHarmony 工程不能标为 HarmonyOS。注解参数表示被标注声明的最低可用版本，不改变工程 compatible，也不证明调用方设备安全。
+
+### 局部屏蔽告警
+
+只有已有充分保护但工具不能识别时，才按上表 API23 门槛和配套工具能力选择屏蔽，并记录局部理由。屏蔽只改变诊断，不补齐 API 或业务回退；不能批量屏蔽后宣称适配完成。
+
+声明注解写法：
+
+```ts
+import { SuppressWarnings, SuppressWarningsType } from '@kit.BasicServicesKit';
+
+@SuppressWarnings({ rules: [SuppressWarningsType.COMPATIBILITY] })
+function protectedBusiness(): void {
+  // 此处必须已有真实保护；注解不替代它。
+}
+```
+
+非声明元素使用告警行上方的单行注释，不能把注解表达式原样当作单行屏蔽语法：
+
+```ts
+// @SuppressWarnings compatibility
+```
+
+将该指令紧贴实际告警调用行的上方。它是工具指令，不是运行时 API；本流程同样仅在 compatible ≥ API23 且支持该屏蔽能力时新增。不得为了屏蔽而扩大声明范围或删除告警所提示的业务分支。
+
+依据：[ArkTS 注解说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/arkts-api-compatibility-warning-elim)、[兼容性告警屏蔽](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/compatibility-warning-suppress)。
+
+## UI 自定义组件隔离
+
+版本相关的装饰器和状态管理需要隔离组件实现，在**创建组件的位置**选择，不能只保护同一个高版本组件内部的方法调用。
+
+例如 API18 的 `@ReusableV2` 方案兼容 API12：分别提供高版本 `ReuseComponentV2` 与低版本 `V1Component`，在 `LazyForEach` 的创建处按真实底座 API 选择。以下为创建片段，两个组件由工程按对应声明实现：
+
+```ts
+if (deviceInfo.sdkApiVersion >= 18) {
+  ReuseComponentV2({ num: item })
+} else {
+  V1Component({ num: item })
+}
+```
+
+公共显示可抽取复用；低版本路径自身不能依赖不支持的装饰器、状态模型或初始化。分别检查两侧的显示、状态更新、复用与生命周期；编译通过或页面可打开不能替代这些证据。
+
+依据：[UI 自定义组件兼容指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-ui-component)。
+
+## 迁移调用的版本与回退
+
+旧接口 since、deprecated since、替代接口 since 分别核对到接收者、成员、参数及重载。不能因旧接口在API18废弃，就给实际自API10/11可用的替代链统一加18分支；错误码、atomicservice、crossplatform 标签不代替 since。
+
+替代调用及每个新增获取链、参数类型、枚举、回调能力分别核实最低版本，组合路径满足全部实际门槛。高于 compatible 时选择最低版本可用的保护机制，保留原有非空业务回退，不提高 compatible 或删除仍支持设备的逻辑。
+
+订阅、取消及读取按同一生命周期核对接收者、回调身份和保护分支，不只保护一半。合法低版本回退可能仍被扫描命中，按废弃流程解释，不能为清零删除。模型复核、真实检查和设备事实分别记录，方法见[验证](verification.md#废弃迁移兼容复核)和[单次设备验证](runtime-functional-tests.md#废弃单次设备验证)。
+
+## 原生低版本兼容参考
+
+以下知识用于废弃迁移涉及的原生调用保护；行为任务的 C/C++ 版本分支见[target 升级兼容](../upgrade/upgrade-compatibility.md#arkts-与-c-行为分支)，不因行为适配自动启用弱引用。
+
+### 加载与符号保护
+
+版本概念按[版本契约](sdk-versions.md)。下面的原生规则提炼自 2026-08-28 官方快照，工具链条件必须在真实 SDK/IDE 上核实。
+
+默认 C API 引用为强引用。动态加载器可能在库加载时就解析符号，旧设备缺少符号会在业务分支执行前中止应用；仅在强引用调用外加设备版本 `if` 不能消除加载风险。
+
+#### 显式加载与查询
+
+`dlopen` 检查库是否成功加载，`dlsym` 检查准确符号是否存在，再通过与 SDK 声明完全一致的函数指针调用。库不存在和符号不存在都保留原业务回退；不能在其他初始化或调用点继续强引用同一高版本符号。
+
+下面是基于官方定位接口的加载片段，类型、头文件和 `requestConfig` 来自真实 SDK 与工程；失败分支须接入实际回退，不可直接复制空处理：
+
+```c
+void *handle = dlopen("liblocation_ndk.so", RTLD_LAZY);
+if (handle != NULL) {
+    typedef Location_ResultCode (*StartLocating)(const Location_RequestConfig *);
+    StartLocating startLocating = (StartLocating)dlsym(handle, "OH_Location_StartLocating");
+    if (startLocating != NULL) {
+        Location_ResultCode result = startLocating(requestConfig);
+        // 按原契约处理 result，并保存 handle 的所有权。
+    } else {
+        // 符号缺失：执行既有低版本方案。
+    }
+} else {
+    // 库加载失败：执行既有低版本方案。
+}
+```
+
+句柄须活到最后一次函数指针调用及相关异步操作/回调完成，随后由明确的所有者 `dlclose`；失败路径也须释放已取得且不再使用的句柄。不能查完符号立即关闭库，或把临时指针保存到已卸载库之外。符号存在仍需满足权限、设备能力及接口业务前置条件。
+
+依据：[C API 兼容保护](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/c-api-compatibility-warning-elim)。
+
+#### 弱引用、弱库与 APIAVAILABLE
+
+SDK API22 起的快照方案允许配套编译器启用 C API 弱引用，未解析的弱符号可以为空，因此仍须用准确的可用性保护和回退。弱符号解决“库中缺符号”；当整个依赖库在旧设备上不存在时，还要核对弱库机制。快照明确 **API22 以下设备不支持弱库**，这不是所有弱符号方案的统一设备下限；支持更低设备时应评估显式加载等可用方案。
+
+快照中的 Hvigor 配套条件如下，不能据此假定后续 IDE 都沿用同样参数：
+
+| DevEco Studio 条件 | 快照中的配置要求 |
+| --- | --- |
+| 大于 `6.0.2.640 Release`，且不是 `6.1.0.830` | 模块 `build-profile.json5` 的原生编译参数传入 `-DOHOS_COMPATIBLE_SDK_VERSION=x.x.x` |
+| `6.1.0.830` | 自动根据工程 compatible 开启；已有显式参数必须同步 compatible，或在确认支持后移除 |
+
+上述旧格式 `HarmonyOS X.Y.Z(N)` 或 OpenHarmony `N` 将最低兼容版本传为 `N.0.0`，如 `6.0.2(22)` 对应 `22.0.0`。该映射不作为 API26 及以后编码的通用规则；检查真实构建参数，避免工程 compatible 已变而 LLVM 目标仍旧。
+
+`APIAVAILABLE` 是 `__builtin_available` 的封装。从真实 SDK 引入提供它的头文件，确认宏与编译器可用后，按准确接口版本使用，例如以下 API22 门槛片段：
+
+```c
+if (APIAVAILABLE(22, 0, 0)) {
+    // 调用已核实在此门槛可用的新接口。
+} else {
+    // 保留低版本业务。
+}
+```
+
+按真实头文件的家族与版本映射选阈值，不能把行为变更版本当接口 since，也不能自行复制宏冒充工具链支持。
+
+依赖库必须完整：
+
+- 系统旧版本已有库但缺少新符号时，仍在 `target_link_libraries` 配置该 API 的真实依赖，不能只启用弱引用。
+- 整库在旧系统不存在且设备支持弱库时，同时配置真实链接依赖及 `-Wl,--ohos-weak-library=libxxx.so`；库名按 SDK 确认，不只加 weak 标记。
+- 弱引用可能掩盖漏配依赖。按真实构建能力临时关闭弱化检查链接，确认依赖齐全后恢复配置；这一步不能代替设备上实际调用验证。
+
+非 Hvigor（如 Bazel）构建同样须把 compatible 传到 LLVM，并核对 `-Wunguarded-availability` 和 `libdeviceinfo_ndk.z.so` 依赖。快照的 `--target=aarch64-linux-ohosx.x.x` 只是单 ABI 示例，其中旧版本映射同上；按工程各 ABI 的真实目标三元组处理，不固定 aarch64，不丢弃其他 ABI。保存 `compile_commands`/`build.ninja` 等实际传参证据。
+
+依据：[C API 兼容保护高阶用法](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/c-api-compatibility-warning)。

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

@@ -0,0 +1,21 @@
+# C/C++行为适配专题
+
+本页提供行为任务的真实扫描上下文、SDK声明理解、必要修改及ABI构建方法。设备行为差异按[target升级兼容](../upgrade/upgrade-compatibility.md#arkts-与-c-行为分支)处理；不增加通用接口可用性匹配、弱引用迁移或自动最低系统验收，保留已有有效逻辑。
+
+## 扫描与输入边界
+
+保留scanner逐模块DevEco后端、真实compileNative/Ninja上下文、nativePasses、超时和完整性诊断。一模块超时不丢弃其他模块或ArkTS结果；零行或数量相同不能证明完整，不能用grep或伪造AST兜底。
+
+ArkTS/TS和C/C++使用各自源码及声明；HAR/HAP/HSP/ABC、.so/.a/.o等二进制只核对构建/依赖字节，不输入文本或AST。额外头文件/源码路径限注册和授权范围。
+
+## 逐调用判断
+
+读取准确SDK C声明和实际上下文，理解参数、返回值、错误码、内存/线程/生命周期、官方行为触发条件；按真实ABI、宏及编译条件复核，不用一个ABI结果代表全部。
+
+函数指针、间接调用、复杂宏或声明冲突无法可靠确定时保留具体证据缺口或业务决定，不按同名函数强改。实际差异不等于语义正确，必要的新旧行为分支按官方边界处理，不引入独立的接口版本匹配或弱引用迁移。
+
+## 修改与真实构建
+
+只改必要调用、头文件及真实构建配置，保持ABI和原业务；不删ABI、缩范围或改宏隐藏错误。只需更新NDK重编译时可NO_CHANGE，保存真实工具链及ABI构建日志。
+
+使用工程真实Hvigor/Ninja/clang检查，保存编译参数、链接依赖、命令、退出码、日志与当前产物；真实错误按[排错方法](troubleshooting.md)修必要范围。若用户选择设备验证，检查当前实际包中的业务调用、返回/回调和相关ABI，按[通用功能取证](runtime-functional-tests.md#通用功能取证)保存证据，只在已有授权覆盖行为边界时记录两侧结果，不自动扩展最低系统或接口可用性验收。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/references/common/runtime-functional-tests.md

@@ -0,0 +1,62 @@
+# 功能取证与设备验证方法
+
+各功能主流程只加载适用小节，验证范围由实际用户要求决定；本页不新增设备授权、通用接口版本匹配或自动最低系统验收。工具先读真实help，不安装新工具或恢复内置执行器。
+
+## 通用功能取证
+
+明确实际HAP、设备/系统、当前源码与配置及所选rowIds，记录用例、前置数据、操作、预期与实际值/回调。所选NO_CHANGE条目也验证正常功能，未选和缺口不缩小原始行分母。组件截图不能替代实际返回值、回调或持久化；Dialog取消不证明确认按钮回调，同页不代表覆盖所有原始行。
+
+HDC目标需核对连接类型、端口及实例映射；歧义或不在线停止该设备操作，不默认第一台或切换其他实例。真实冷启动有界等待，不同步等待长期Emulator进程退出。工具缺失时保留具体UI能力缺口，不凭Canvas等实现猜测无法操作。
+
+### 实际执行与采集
+
+逐用例保存完整命令、退出码、操作序列、实际值/断言、采集时间和图片/日志；可在轻量分组记录中记录。既不以外部脚本退出0，也不以图片存在直接标功能通过。模型无法读取图片或视觉工具中断时视觉结果未验证，不冒充产品缺陷。
+
+固定密码输入/确认/Toast等场景限定Dialog容器、控件类型和唯一可见目标；不能把多个TextInput或重复文案串错。500ms防连点和1500ms Toast使用设备实际支持的连续操作及时捕获；主机多次往返导致瞬态消失时保存耗时与受阻事实，不放宽预期，不把另一次触发的截图当同一次证据。
+
+非视觉功能可没有截图，但必须有真实功能证据。图片只关联其实际用例和原始行；起始图、诊断图不能填满无关业务行。若用短路径副本，保留原来源与哈希，真实格式是JPEG就使用.jpeg，不把任意文件改扩展名装PNG。
+
+
+## 废弃单次设备验证
+
+仅按用户明确要求验证当前构建产物，不采集修改前阶段，不要求比较或基线降级选择。实际功能与所请求设备范围分别报告；没有要求设备时保持NOT_RUN，不主动询问或启动。
+
+下列矩阵仅用于废弃任务已要求的兼容设备范围，按真实执行列通过/未验证，不为行为增加最低系统任务，也不自动扩大当前设备授权。
+
+### 废弃设备覆盖参考
+
+已授权设备验证时，按每条变更实际门槛选择下列组合，记录设备 API、包的 `targetAPIVersion`/`minAPIVersion`、相关 ABI、入口与原始 rowIds。版本含义和规则见[共用兼容指南](compatibility.md)，不按 ROM 名称或静态型号推断覆盖。
+
+| 验收位置 | 必须取得的证据 |
+| --- | --- |
+| 最低 compatible | 本次包可安装、冷启动/初始化成功，低版本业务及回退实际可用；库加载也在此验证 |
+| 接口边界 | 在支持范围内覆盖门槛以下最近可用版本与门槛版本或其上首个可用版本，分别触发旧/新路径；不同门槛分别核对，不能只测 target 对应系统 |
+| 新接口实际调用 | 高版本设备真正执行到新增方法/参数/回调并验证结果；API 刚引入的边界与所选编译 SDK 对应系统的路径均需考虑，仅启动不算覆盖 |
+| HAR/集成态 HSP | 宿主实际消费本次依赖、完成初始化并走到库调用；HAR 按真实宿主 target，HSP 按各包 target 核验，保留失败处理证据 |
+| C/C++ 与 UI 隔离 | 相关 ABI 的加载/链接及新旧调用路径；UI 的两个组件实现、状态更新、复用与生命周期分别验证 |
+
+若门槛以下已低于包的安装下限，记录该组合不在支持范围及依据；缺少最低版本、边界设备、宿主或某 ABI 时列出具体未验收项，不能以高版本冒烟、弱引用编译通过或一台设备替代。未要求设备验证时保持 NOT_RUN，并将这些组合列为建议验收，不擅自启动设备。
+
+该矩阵结合 2026-08-28 [历史版本兼容验证指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/compatibility-verification)与[原生兼容验证要求](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/c-api-compatibility-warning)提炼；实际执行仍按下面的阶段包与功能证据规则。
+
+
+## 行为前后对比
+
+仅在行为任务选择对比时，按[阶段包方法](verification.md#行为前后对比)在任何相关修改前真实构建并归档原源码/原配置 before 包，after 使用最终修改后的真实构建。归档不是设备测试，原包有效归档后设备不可用不再阻塞获批修复；原包构建、签名或归档受阻才返回主流程等待明确决定。
+
+修复后可以依据 spec 的业务预期和已选范围生成用例，将操作、前置数据、复位方法和断言保存到 evidence。优先使用两个阶段包都支持的外部操作；新增应用内测试入口、埋点或辅助源码不会出现在原包中，不能假设支持，须调整用例或报告覆盖缺口。
+
+对比按顺序执行：核对归档 before 身份与实际安装结果，执行用例并保存原始观测；复位约定数据，再核对 after 的安装和身份，执行同语义用例。同设备/系统、原始 rowIds、有效阶段包和可复位数据才可比较，实际安装受阻或不同包的运行状态不能靠计划推定成功。
+
+按[测试报告模板](../../templates/upgrade-test-report.md)生成 test-report.md，逐用例分别写业务预期、before/after 实际值及断言、原始日志/图片/时间和前后差异。两个包表现相同不表示符合业务预期；零用例、缺证据、异系统、缺包、数据不可复位、入口不兼容或模型中断分别保留不可比/未执行。所选无需适配条目仍测试正常功能，不制造代码差异。
+
+仅修改后验证执行同样的功能取证但只测试 after，不伪造 before；不运行则不启动设备。代码/配置变化后重新构建 after 并重测受影响用例，before 归档不改、不回退工程补造。测试或设备失败保留可信修复，明确实际受阻阶段。跨系统范围按已有授权分别记录，见[target 升级兼容](../upgrade/upgrade-compatibility.md#记录与验证边界)，不将异系统运行称为有效 before/after 对比，不自动扩大最低设备任务。
+
+## 清理与共享证据
+
+失败先保存可取得的hilog、布局和截图，说明传输、安装、启动、进程稳定或业务断言哪个阶段受阻；不能凭shell echo成功断言HAP传输正常，进程未稳定不凭猜测归咎快照损坏。不原样重试相同确定性阻断。
+
+先保存现场，再清理临时传输目录并停止本次新启动的模拟器，核对实际退出码和已停止状态；失败后不启动另一台。已有实例与真机不关闭，停止失败单独报告，不能覆盖功能事实。Windows PowerShell本地路径保持原生，HDC远端/data/local/tmp路径不做Windows转换，接收文件指定真实cwd和文件名，保留图片实际格式；shell echo成功不证明HAP传输成功；Git Bash仅为单条HDC设置必要MSYS_NO_PATHCONV，不永久改全局环境。
+
+
+旧材料只读，不恢复旧执行器或继承旧通过。一次真实宿主用例可关联库与应用，但逐项说明当前库消费、原始行与实际功能证据；行为对比还须对应两个有效阶段。交付按所选主流程分别填写实际覆盖、功能、视觉及清理，行为另列有效对比，废弃不生成比较状态。

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

@@ -0,0 +1,77 @@
+# SDK 版本与扫描参数
+
+## 配置、设备与打包字段
+
+| 信息 | 工程字段 | 打包字段 | 判断用途 |
+| --- | --- | --- | --- |
+| 编译 SDK | `compileSdkVersion` | `compileSdkVersion` | 提供声明与工具链；核对实际使用的 SDK，不能仅看配置 |
+| 目标版本 | `targetSdkVersion` | `targetAPIVersion` | 系统对明确按 target 隔离的行为选择新旧语义 |
+| 最低兼容版本 | `compatibleSdkVersion` | `minAPIVersion` | 安装门槛；设备 API 低于包中最低要求时不能安装 |
+| 设备 API | 不属于工程配置 | 不由应用包设定 | 当前系统实际提供的能力与行为版本 |
+
+保持 `compatible ≤ target ≤ 实际编译 SDK`，按实际 API 版本顺序比较，不比较版本字符串的字典序。回读所选 product 和最终包，确认没有采用其他 product 或默认值。升级编译 SDK 不要求同步抬高 target；按主流程保留未要求改变的 compatible，不降低原 target/compatible。降低安装门槛不能补齐旧系统缺失的能力。
+
+API26 起采用 `X.Y.Z` 语义化格式；此前 HarmonyOS 常用 `X.Y.Z(N)`，OpenHarmony 常用 API Level `N`。例如 `26.0.0` 晚于 `6.1.1(24)`，不能把 `6` 与 `26` 当成同一家族主版本直接比较。配置值与下文 scanner 的精确阶段表达式分别处理。
+
+## API 家族与设备查询
+
+按准确声明及 SDK 所属路径区分 OpenHarmony 底座与 HarmonyOS 专有接口。旧格式下，底座 `since N` 对应 `deviceInfo.sdkApiVersion`；专有 `since X.Y.Z(N)` 对应 `distributionOSApiVersion` 的平台版本。旧平台数值按 `X * 10000 + Y * 100 + Z` 编码，例如 `5.0.2` 对应 `50002`，不能与 API Level `14` 直接比较。此编码仅用于已核实采用该定义的字段和旧格式，不推广到 API26 及以后的字段或返回值。
+
+设备“设置 → 关于本机”应查 **API 版本**，也可对明确设备使用 HDC 查询 `const.ohos.apiversion`、`const.product.os.dist.apiname`、`const.product.os.dist.apiversion`，或读取真实 deviceInfo 属性。面向消费者的 ROM 版本以及 `distributionOSVersion`、`displayVersion`、设备型号不能证明 API 版本。查询接口本身也须在工程最低版本可用。
+
+废弃迁移的调用保护见[API 兼容保护](compatibility.md)；行为变化及设备边界见[target 升级兼容](../upgrade/upgrade-compatibility.md)，行为门槛不能从接口 since 推导。设备支持范围结合实际业务和设备证据决定；[设备支持查询](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/support-device)与[设备 API 分布查询](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/sdk-version-percentage)只作当次参考，记录查询时间。
+
+以上版本背景提炼自 2026-08-28 官方快照：[兼容性介绍](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-intro)、[兼容性关键信息](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/app-compatibility-influence-factor)、[API26 版本格式](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/version-number-26)。具体属性和工具能力仍核对实际 SDK。
+
+## 配置与扫描
+
+配置版本不含 SDK 通道。SDK 26.0.0 Beta1、Beta2、Release 均可写入 `targetSdkVersion: "26.0.0"`。配置覆盖、宿主覆盖和运行范围不得用 Beta/Release 排序拒绝同平台 target。
+
+扫描参数包含精确通道。同 API 默认起点按 Beta 数字升序后 Release；终点反向选择，并受工具链真实 SDK 上限约束。显式完整 from/to 不自动重选，超出 SDK 上限则拒绝扫描，不能静默降级。
+
+| SDK | 用户输入 | 配置 target | 精确 from | 精确 to |
+|---|---|---|---|---|
+| 26.0.0 Beta1 | 22 → 26 | 26.0.0 | 6.0.2(22) Beta1 | 26.0.0(26) Beta1 |
+| 26.0.0 Beta2 | 23 → 26 | 26.0.0 | 6.1.0(23) Beta1 | 26.0.0(26) Beta2 |
+| 26.0.0 Release | 23 → 26 | 26.0.0 | 6.1.0(23) Beta1 | 26.0.0(26) Release |
+
+内置目录来自 DevEco 26.0.0.821 的规则目录和 project-api-change-assistant JAR，两份版本清单一致，共 30 个精确版本，来源清单和版本数据均带 SHA256。运行时合并当前工具链目录及 JAR 发现的版本。API13 从 Beta3 开始，API20 包含 Beta5；不能编造 Beta4 或当前目录没有的 API25。目录不代表全部历史 SDK 发版。
+
+运行记录和报告分别保留 `configuredTargetSdkVersion`、`scanFromSdkVersion`、`scanToSdkVersion`、`compileSdkVersion`、原始输入和解析依据。HAR 已配置 target26 时仍可提供原适配基线 `--from 22`，无需回退工程配置；通道展开后的 from 必须小于 to。
+
+## 可选扫描版本列表
+
+下表按时间顺序列出内置规则目录支持的 30 个精确版本，供 `--from`、`--to` 使用。扫描区间为 `(from,to]`；配置 target 不带通道，扫描终点仍受本机实际 SDK 和规则包覆盖限制。运行时还会发现当前工具链提供的版本。
+
+| 序号 | 精确扫描版本 | 说明 |
+| --- | --- | --- |
+| 1 | `5.0.1(13) Beta3` | API 13 Beta3 |
+| 2 | `5.0.1(13) Release` | API 13 Release |
+| 3 | `5.0.2(14) Beta1` | API 14 Beta1 |
+| 4 | `5.0.2(14) Release` | API 14 Release |
+| 5 | `5.0.3(15) Beta1` | API 15 Beta1 |
+| 6 | `5.0.3(15) Beta2` | API 15 Beta2 |
+| 7 | `5.0.3(15) Release` | API 15 Release |
+| 8 | `5.0.4(16) Release` | API 16 Release |
+| 9 | `5.0.5(17) Beta1` | API 17 Beta1 |
+| 10 | `5.0.5(17) Release` | API 17 Release |
+| 11 | `5.1.0(18) Release` | API 18 Release |
+| 12 | `5.1.1(19) Beta1` | API 19 Beta1 |
+| 13 | `5.1.1(19) Release` | API 19 Release |
+| 14 | `6.0.0(20) Beta1` | API 20 Beta1 |
+| 15 | `6.0.0(20) Beta2` | API 20 Beta2 |
+| 16 | `6.0.0(20) Beta3` | API 20 Beta3 |
+| 17 | `6.0.0(20) Beta5` | API 20 Beta5 |
+| 18 | `6.0.0(20) Release` | API 20 Release |
+| 19 | `6.0.1(21) Beta1` | API 21 Beta1 |
+| 20 | `6.0.1(21) Release` | API 21 Release |
+| 21 | `6.0.2(22) Beta1` | API 22 Beta1 |
+| 22 | `6.0.2(22) Release` | API 22 Release |
+| 23 | `6.1.0(23) Beta1` | API 23 Beta1 |
+| 24 | `6.1.0(23) Beta2` | API 23 Beta2 |
+| 25 | `6.1.0(23) Release` | API 23 Release |
+| 26 | `6.1.1(24) Beta1` | API 24 Beta1 |
+| 27 | `6.1.1(24) Release` | API 24 Release |
+| 28 | `26.0.0(26) Beta1` | API 26 Beta1 |
+| 29 | `26.0.0(26) Beta2` | API 26 Beta2 |
+| 30 | `26.0.0(26) Release` | API 26 Release |

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

@@ -0,0 +1,54 @@
+# 失败处理、断点继续和安全撤销
+
+本页说明定位、尝试、证据有效性、继续和撤销的方法。具体等待节点、返回步骤和下一步由当前功能主流程负责。遇到问题先保存实际输入/命令/日志/当前差异，再决定返回哪个步骤；不改原CSV、SDK、知识或结果分母绕过问题。
+
+## 定位与停止
+
+| 情况 | 保存与核对的方法 |
+| --- | --- |
+| 范围/版本/声明不明 | 保留实际候选及缺失证据；局部缺口不阻断独立单元 |
+| 授权/方案待答复或实质变化 | 保存原方案、真实答复与变更范围；按当前主流程确认，不以超时或初始自动请求代选 |
+| 行为原包归档受阻 | 保存构建、签名或归档原因及原源码/配置，暂停相关修改并等待补齐或明确改变验证方式 |
+| 原包已归档但设备/用例受阻 | 保留有效 before 包和具体测试缺口，可继续获批修复，不声称已经取得 before 实测证据 |
+| SDK/IDE不足或路径无效 | 保存真实元数据与已检查路径，不默换SDK或把Beta当Release |
+| 扫描超时/INCOMPLETE | 保留JSON、coverage、diagnostics与可信部分，不用grep冒充扫描 |
+| 代码/ArkTS错误 | 阅读真实 build error、准确声明及依赖，按[案例索引](../upgrade/scanner-missed-cases.md#按错误或异常检索)查找可能原因，核实后只修必要范围 |
+| 依赖/签名/安装/进程/超时 | 保存实际退出码、日志尾部及连接/签名状态；仅阻断条件变化后重试 |
+| HDC_READY或目标歧义 | 保存真实target列表和实例映射，不换设备、不强停已有实例 |
+| 产物缺失/陈旧 | 核对本次任务、product/target、日志和生成情况，不沿用旧包 |
+| 功能失败/视觉模型中断 | 分别保存结论；截图不替代功能，中断不冒充缺陷或通过 |
+| 验证后SDK/配置/源码变化 | 保留原证据，核对新身份及影响范围，相关旧成功标待复核 |
+
+每个实际错误及受影响的源码/依赖范围独立记录尝试。最多三种实质源码失败方案；同一失败输入不原样重试，第三种失败或连续三次无实质源码进展就停止该修复，继续独立组或交付可信部分。格式、空语句、日志文字、扩大范围或改错误消息不算新方案；另一个错误消失不重置仍失败错误的次数。
+
+环境、依赖、网络、签名、工具崩溃和超时不消耗源码方案次数，但不能在相同确定性阻断下空重试。不设隐性总体时间上限；遇到可验证新条件再继续。记录失败方案、真实原因和下一步，不需要事务账本或自动预算状态机。
+
+## 按报错或明确异常查阅案例
+
+只有出现真实编译/构建错误，或用户明确报告混淆失效、发布包异常时，才按[漏扫案例](../upgrade/scanner-missed-cases.md)检索相关条目；不在正常扫描、CSV零行或构建成功时主动通读、核查全表，也不把缺少固定报错的混淆变化编造成 build error。
+
+保存完整日志，从错误主句、错误码、符号/类型和文件位置提取线索；只有 BUILD FAILED、任务失败或退出码时先找实际诊断。用户报告产物异常时核对真实构建模式、工具链和产物身份。按本页索引得到的只是候选原因，须回读准确官方说明、SDK及工程依赖验证，未匹配则继续常规排错，不强行套用。
+
+同一获批方案内的必要实现修正可沿用批准；新增业务方案、模块依赖、共享配置或修改范围须按当前主流程更新方案并确认。没有CSV对应行的问题只记录在实际编译日志、现有进度和报告说明中，不生成扫描行/rowId或改变原始行统计，不添加补充候选协议。原包归档、重建和失败次数仍按原规则处理。
+
+## 断点继续
+
+1. 读取轻量progress总览、当前分组、原CSV与来源身份。核对工程/product/版本/范围，没有把adapted副本当较小原基线。
+2. 回读当前实际文件和已存在diff，核对相关SDK声明、配置、包与证据是否仍对应。模型自己写过“完成”不是验证凭据；输入或相关文件变化时将对应结果改待复核，保留原说明。
+3. 核对结果行与原始逻辑行/重复记录、实际答复与方案批准范围。工程/product/目标/范围及方案仍适用时沿用已明确选择，不逐文件重问；旧记录缺必要目标、批准或已要求的验证范围时只补缺项，不默认已批准。部分批准只继续获批项；实质方案变化重新确认受影响部分。行为已选对比且原包构建/签名/归档仍受阻时维持暂停相关修改，不能自行改为仅after；原包有效归档后的设备阻断只影响测试，不阻止获批修复。行为批准以当前 spec 为依据，全部评估返回后方可汇总确认；已停止的错误不通过新目录或重置尝试绕过。
+4. 旧版本的manifest、model-store、source-state和报告只作只读来源；不解析继承旧账本、不迁移其凭据、不把旧Fixed/编译PASS当当前成功。需要处理时从原始扫描及当前工程重新评估。
+5. 保留用户改过的报告、源码和历史证据。未知来源的签名/配置变化先说明，不刷新原事实来消除冲突。
+
+无法证明原输入或修改归属时，明确缺口并交付可信部分。行为缺原包时保留基线缺口，不回退工程制造before；废弃仅核对当前包，不产生before门槛。
+
+## 安全撤销
+
+失败默认保留当前源码和诊断，先修复必要片段，不自动整文件回滚。只有用户明确要求撤销时：读取当前文件、原任务差异及后续编辑，定位本任务可证明归属的片段；仅撤销这些片段并复核其他内容。共享helper仍被其他已完成修改使用时不能删除。
+
+存在未知归属、重叠后续修改或用户同文件编辑时，保留现场并说明无法安全自动撤销的范围。不要使用整仓checkout、stash、换行重写、复制旧文件或伪造哈希覆盖用户改动。
+
+## 部分交付
+
+任何阻断都不免除当前功能流程的覆盖核对与交付。保留全部原始行，分别填写当前模型结论、工具实际结果、停止原因和待补证据；未构建、未运行及本功能实际要求的其他未验证项各自写明，不用“全部完成”掩盖。文件实际存在、可回读并带完整路径后再回复。
+
+源码或构建配置已修改，但缺少当前输入对应的真实编译成功时，必须明确部分完成/待编译或编译失败。允许交付可信修改和分析，MODIFIED不代表已验证完成；环境修复后按当前主流程重新完整构建，代码或SDK再次变化时重新检查受影响结果，不沿用旧成功。

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

@@ -0,0 +1,79 @@
+# 真实验证与工具操作
+
+本页提供环境、检查、构建、产物和设备操作方法，由所选功能主流程确定执行时机、授权与完成判据。工具提供事实，模型组织任务和解释结果；不新增固定构建/审计执行器。每次验证记录完整参数、cwd、所用版本、退出码、日志和对应输入/产物。
+
+## 环境与依赖
+
+### 找到并核对工具
+
+先使用用户路径、DEVECO_SDK_HOME、DEVECO_HOME和已知本机安装，实际回读SDK与IDE元数据，不遍历磁盘猜版本。SDK根及default目录按scanner真实help支持输入；API26需实际能覆盖目标的IDE26+，API24需6.1.1+。Node20+，Java17+。编译SDK可以高于配置target，二者分别记录。
+
+常见安装位置仅用于定位候选，执行前必须确认文件实际存在：
+
+| 工具 | macOS DevEco安装内候选 | Windows安装内候选 |
+| --- | --- | --- |
+| Java | `jbr/Contents/Home/bin/java` | `jbr/bin/java.exe` |
+| Hvigor | `tools/hvigor/bin/hvigorw` | `tools/hvigor/bin/hvigorw.bat` |
+| ohpm | `tools/ohpm/bin/ohpm` | `tools/ohpm/bin/ohpm.bat` |
+| HDC | 实际SDK的toolchains内hdc | 实际SDK的toolchains内hdc.exe |
+
+在工程目录逐项检查 `node --version`、真实Java的`-version`、ohpm的`-v`、Hvigor的`-v`；记录DEVECO_SDK_HOME，并将选定Java/ohpm/Node目录放入本次进程PATH、设置对应JAVA_HOME，不永久改用户环境。路径带中文/空格/引号时使用参数数组与node:path，不拼接shell命令；Windows .bat/.cmd可复用保留的platform/process安全封装，不能把JSON.stringify当shell转义。
+
+scanner 的 index 后端不必然支持 scanFilePaths；无法准确限定请求目录时停止并报告范围不受支持，不删除参数扩大扫描。
+
+IDE 内构建与命令行构建分别核对实际 SDK 路径/元数据、编译器及构建工具版本，确认是配套工具链且与任务目标一致。不能因命令名称相同或 IDE 已升级，就推断流水线/终端也切换了 SDK；设置环境后回读实际使用路径与构建日志。此配套要求提炼自 2026-08-28 [官方工具链升级指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/upgrade-tool-chain)，不固定沿用其中面向 API20 的旧安装版本。
+
+依赖缺失时按工程约定在真实根运行ohpm install，保存输出与退出码；不自动安装或下载新的开发工具/MCP，不改签名、证书或依赖源码。ohpm 参数以实际 help 为准，确认前只用基本 install；只有工具明确支持 keep-lockfile 时才考虑保留锁文件的清理，不擅自丢锁或换依赖。锁文件变化要说明是否由真实安装产生；安装失败不能继续假称构建通过。网络/环境问题归排错，不算源码修复尝试。更多Hvigor选项见[工具手册](../toolchain/hvigor.md)。
+
+## 通用静态复核
+
+按当前主流程核对实际diff、原始行及SDK声明，理解准确接收者、参数、重载、返回/回调、默认值与官方行为触发条件。此节承担代码及语法/类型正确性；行为另按[target升级兼容](../upgrade/upgrade-compatibility.md#记录与验证边界)复核新旧行为语义，不新增通用接口版本可用性匹配任务。
+
+修改ArkTS/ArkUI前按[编码规范](arkts-coding-standards.md)复核必要差异，不开展无关风格整改。检查公开接口、可空来源、异常/Promise、回调次数与同身份on/off、资源释放和生命周期；原生按准确头文件、真实ABI、宏与构建上下文检查。
+
+回读实际product配置，保持原compatible；例如API26配置写26.0.0，精确扫描终点使用26.0.0(26) Release，两者不混写。SDK/IDE可用检查执行后保留真实命令/输出、历史与新增诊断；新增错误为0不等于全工程检查通过，缺工具不写自动通过。真实编译错误依所属流程修复，不把诊断自动扩展成通用接口可用性迁移；必要的跨系统行为处理仍按行为专题复核。
+
+## 废弃迁移兼容复核
+
+废弃任务另按[兼容指南](compatibility.md)逐准确接收者/重载核对接口与参数since、辅助链、真实版本保护和回退，不用错误码或跨平台标签代替since。同步复核通用静态检查、成对on/off与未保护残留。模型评估、SDK检查、编译与设备结论分开记录，不以消除诊断替代语义安全。
+
+## 完整构建与产物
+
+每轮源码或构建配置修改后必须执行真实完整构建，验证本轮最终输入。构建后相关源码、配置或SDK再次变化时，旧相关通过标为待复核，必须重新构建。缺工具可保留有依据的修改，但进度、结果说明及报告只能标部分完成/待编译；编译失败保留实际原因。MODIFIED、模型检查、提示性扫描、废弃复扫或旧产物不能关闭本轮编译待办。
+
+在所选构建工程目录、明确工具环境下执行。占位符必须替换为已核实的实际路径与product；模块target按根注册和模块build-profile读取，不以模块目录名猜测。
+
+```console
+"<Hvigor实际路径>" --mode project -p product=<product> assembleApp --analyze=normal --parallel --no-incremental --no-daemon
+"<Hvigor实际路径>" --mode module -p product=<product> -p module=<HAR模块>@<模块target> assembleHar --analyze=normal --parallel --no-incremental --no-daemon
+```
+
+Windows关闭daemon；不要等待长期运行的守护/模拟器启动进程退出。HAP完整项目构建使用assembleApp；库与宿主的组织顺序由实际功能流程及其专题确定。原生需要时使用工程真实compileNative/Ninja上下文，不改变ABI以躲避失败。
+
+构建前记录当前源码diff/必要配置、目标模块和既有产物情况。构建后读取完整输出特别是ANSI错误后的日志尾部，核对真实退出码、任务是否执行及本次实际生成的产物，不能仅看前段成功任务/WARN或目录中存在旧包。
+
+HAP/HAR一般在模块 `build/<product>/outputs/<target>/`，以真实工程输出为准。多入口、多target、多产物必须明确选择，核对AppScope/module身份、大小和SHA-256，保存可回读副本与构建日志。优先本次对应签名HAP；没有签名能编译也不代表可以安装。相同产物字节可能来自确定性重构建，仍须有本次生成/构建证据；没有产物或仅旧包不能通过。
+
+分别记录编译、产物、签名/安装、库和宿主结果。真实新增编译问题修复后重跑必要步骤，依赖/签名/超时等按[排错](troubleshooting.md)。构建失败保留当前源码，不自动回滚；不得将根本没启动Hvigor写为编译失败或成功。
+
+## 单次设备验证
+
+只在废弃主流程收到用户明确要求时执行；使用本次构建的当前HAP，不要求原包、修改前采集或基线决定。未要求写未执行，不主动启动或安装。
+
+实际HDC列出并核对目标设备、系统、连接与实例归属；有歧义不换另一设备。核对当前HAP身份/哈希和安装日志，执行用户要求的真实功能、返回/回调/异常用例，按[通用功能取证](runtime-functional-tests.md#通用功能取证)保存证据。仅当请求覆盖低版本业务时按[废弃设备范围](runtime-functional-tests.md#废弃单次设备验证)记录实际覆盖及未验收项，不额外开启设备。
+
+先持久保存hilog、布局、截图和原始行关联，再只清理本次启动的模拟器；已有实例/真机保留，清理失败单列，不覆盖业务事实。具体子命令先读真实help，布局/截图保留原格式，HDC远端路径不转成本地路径。
+
+## 行为前后对比
+
+行为主流程 U02 先确认不运行、仅修改后验证或前后对比，U05 随 spec 确认分类范围。仅选择对比时在 U06 任何相关源码、target、配置或测试辅助源码修改前，使用原源码/原配置真实构建并归档 before 包；不要求此时就操作设备或执行用例。仅修改后验证不构建 before，不运行则不操作设备。
+
+归档使用[完整构建与产物](#完整构建与产物)的方法：保存本次真实命令、cwd、工具链、product/模块、日志/退出码、原源码/配置基线、包身份/签名及 SHA-256。原包复制到本批次 evidence 中不会被构建覆盖的位置，单 HAP 使用 before.hap，最终修改包使用 after.hap；多模块以 before/after 阶段目录保留实际包集合和身份清单，避免重名覆盖。路径按 node:path 构造。来源不明的旧包、仅目录中存在产物或未证明的签名不能作为有效基线。
+
+HAR 归档原库、宿主实际消费依据和可运行宿主 HAP；HAR 文件本身不能代替宿主。联合任务先归档共同原始基线，再实施会影响它的共享修改。原包构建、签名或归档不足以支持对比时，暂停相关修改并等待补齐条件或用户明确改为仅修改后验证/不运行；不能自行降级。有效原包已归档后，设备暂时不可用只阻塞设备验收，不阻塞获批修复。
+
+U07 对修改后的真实输入完整构建并归档 after，不覆盖 before。U08 可在修复后依据 spec 预期生成用例，先测试归档 before 包，复位约定数据后再测试 after 包；同设备/系统、同语义用例及可复位数据才可比较。先核对两个包都支持测试方式，不能假定原包具有新增测试入口或埋点。包归档、包测试、业务断言和有效对比分别记录。
+
+按[功能取证](runtime-functional-tests.md#行为前后对比)生成 test-report.md；缺包、换系统、零用例、不可复位数据、入口不兼容或模型中断均保留具体缺口。两个阶段表现相同仍要分别满足业务预期。源码/配置变化后重建 after 并重测受影响用例，before 归档保持不变，不回退源码补造。已有授权覆盖多个系统时分别记录，不将异系统运行当作同系统 before/after 对比，不自动增加最低设备或接口可用性验收。
+
+清理与现场保存采用单次设备操作相同方法，测试报告使用[行为测试模板](../../templates/upgrade-test-report.md)。