@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/common/workflow-scan.md

@@ -0,0 +1,41 @@
+# 流水线扫描接入
+
+已有升级流水线使用本说明调用 scanner，分别扫描行为变更与废弃 API；代码修改、构建和阶段报告仍由原流水线负责。
+
+## 工程与版本
+
+- 使用 Node.js ≥20、本机 DevEco Studio 及覆盖目标版本的 HarmonyOS SDK。SDK 26 扫描需要 DevEco 26 或更高版本；Windows 支持状态见 scanner README。
+- `--project` 指向包含 `app.products` 和 `modules` 的宿主工程根目录，`--product` 使用实际 product 名。HAR 源码目录本身通常不是宿主工程。
+- HAR 使用 `--project-type har --scan-module "<HAR模块名>"`。模块须已注册于宿主 `build-profile.json5.modules`，且 `module.json5` 中类型为 `har`；`oh-package.json5` 的 `file:` 依赖不等于模块注册。缺少注册时，按实际源码路径补充最小宿主模块配置，保留原有源码布局。
+- 宿主含本次涉及的自定义 ArkTS 时，另外以 `--project-type app --scan-module "<应用模块名>"` 扫描该范围。多个 HAR 可重复传入 `--scan-module`。
+- 修改 SDK 配置前记录原 target、compatible 和 product。行为扫描起点使用升级前的 target（缺失时取 compatible，已有明确的历史适配基线时用该基线）；终点使用本次最终生效的 target。`plan.targets.os` 存在时采用其 `version`，否则读取实际工程配置。
+- 行为扫描仅在 target 实际提高时执行；版本不变则跳过行为扫描，废弃 API 扫描仍执行。版本和通道取值见[版本契约](sdk-versions.md)，保留明确的 Beta/Release，不凭空替换起止版本。
+
+## 执行命令
+
+Windows、macOS 均使用以下 Node 命令，参数填入实际路径与版本。`<仓库绝对路径>` 始终是本次升级的代码仓库，`--sdk` 使用实际 HarmonyOS SDK 路径。
+
+行为变更：
+
+```text
+node "<Skill目录>/scripts/scanner/bin/harmony-api-scan.mjs" scan --mode upgrade --project "<宿主工程绝对路径>" --product "<product名>" --project-type har --scan-module "<HAR模块名>" --sdk "<SDK路径>" --from "<原target版本>" --to "<本次target版本>" --output-dir "<仓库绝对路径>/.ohos-adaptation/upgrade"
+```
+
+废弃 API：
+
+```text
+node "<Skill目录>/scripts/scanner/bin/harmony-api-scan.mjs" scan --mode deprecated --project "<宿主工程绝对路径>" --product "<product名>" --project-type har --scan-module "<HAR模块名>" --sdk "<SDK路径>" --from "5.0.0(12) Release" --to "<本次target版本>" --output-dir "<仓库绝对路径>/.ohos-adaptation/upgrade"
+```
+
+两种模式的 CLI 都要求 `from < to`。废弃扫描以 API12 作为规则区间起点，ArkTS 废弃判定读取目标 SDK 声明；此参数不修改工程 compatible。目标不高于该起点时，记录版本限制。
+
+按需使用 `--deveco-home "<DevEco安装目录>"` 指定工具链。两类扫描分别执行、记录命令与退出码；一类失败后仍尝试另一类。缺少工具链、有效宿主或扫描失败时，在阶段报告记录未完成范围与原因。
+
+## 结果读取与修复
+
+- 所有扫描产物、调用日志均放在目标仓库的 `.ohos-adaptation/upgrade/`。scanner 在该根目录下自动新建时间戳批次，分别包含 `upgrade/` 或 `deprecated/` 及 `.internal/`。
+- 成功响应为 `{ "ok": true, "result": { ... } }`。按 `result.outputCsv`、`scanJson`、`coverageJson`、`diagnosticsJson` 的实际路径读取文件；失败响应为 `ok: false`。产物名称由 scanner 生成。
+- CSV 的 `Api Definition`、`Code Location`、`Changed in SDK`、`Change Type` 定位候选项；`Title` 可含官方文档超链接。行为结果另有 `Affected Versions`、`Rule ID`，废弃结果另有 `Replacement API`。详细证据从扫描 JSON 补充；JSON 也保留被过滤条目，处理范围以 CSV 和适用性核对结果为准。
+- 行为候选逐项核对官方触发条件、target 门槛与实际调用场景；废弃项核对接收者、参数及替代 API，保留最低版本兼容、返回值、回调、异常和生命周期。资料不明确时使用 `harmonyos-knowledge`，修改 `.ets` 时使用 `arkts-rules`。
+- 按本轮升级范围修复适用项，并在阶段报告记录无需修改及未处理项的依据。废弃修复后用相同范围复扫；构建期间实际 target 变化时，按最终版本重新执行受影响的扫描。
+- 阶段报告分别汇总两类扫描的版本、SDK、product/模块范围、产物路径、命中及修复情况，并读取 coverage/diagnostics 说明实际覆盖范围。

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

@@ -0,0 +1,274 @@
+# Context与UIContext废弃接口迁移
+
+仅由废弃流程D05/D07在命中上下文或全局UI接口迁移时加载；完整任务顺序见[废弃主流程](deprecated-api-adaptation.md)。先读准确旧/替代SDK声明，再按下面顺序选择来源。通用[异常与异步规则](../common/arkts-coding-standards.md#异常异步与-api-迁移)、[版本保护](../common/compatibility.md#迁移调用的版本与回退)只维护在公共专题。
+
+阅读顺序：[类型与选择](#类型与迁移选择顺序) → [四种来源](#四种上下文来源) → [接口对照](#全局接口到uicontext接口) → [迁移代码](#按场景迁移代码) → [约束复核](#迁移后的约束复核)。没有对应来源时保留具体缺口，不能因为普通类没有this就直接跳过。
+
+## 类型与迁移选择顺序
+
+| 类型 | 来源及用途 | 不能推断的事实 |
+| --- | --- | --- |
+| `common.Context` | 文件目录、资源等所需的最小宿主能力；UIContext.getHostContext可返回undefined | 不证明是UIAbilityContext，也不提供UI窗口归属 |
+| `common.UIAbilityContext` | 真实UIAbility实例的this.context；用于Ability专有操作 | 不能从普通HostContext强制转换获得 |
+| `UIContext` | 实际组件或Window所属的UI实例；执行路由、弹窗等UI操作 | 不能当作普通Ability Context，也不能套用到任意窗口 |
+
+选择顺序：组件自身UIContext → 已有参数/成员/真实Window → 完整内部调用链传入最小Context或值 → 仅在已有依赖及归属/生命周期可证明时使用受控服务。每个来源核对准确SDK、可空性和初始化时机，不为统一模式增加模块、依赖或全局服务。
+
+组件getUIContext自API11起可用；ComponentV2装饰器自12起。Window.getUIContext自10起，WindowStage.getMainWindowSync自9起；UIContext.getHostContext自12起且可空。它们是不同声明，不能统一标API12，更不能把deprecated18当作替代起点。完整调用链门槛还包含所用组件/下游方法；真实任务始终重新核对所选SDK。
+
+## 四种上下文来源
+
+### 组件实例
+
+@Component或@ComponentV2实例方法和词法this箭头回调中可使用this.getUIContext；普通function回调、静态方法及早期字段初始化不能据此推断安全。同文件有UIContext不证明每个函数拥有该实例。
+
+### 已有Window或WindowStage
+
+优先复用调用路径已有、具SDK类型和生命周期证据的Window；WindowStage先取得真实主窗口。公开类可复用已有窗口而不改签名，PUBLIC_API只阻止破坏公开签名的注入。不要将WindowStage当作Window，也不要到处复制AppStorage的WindowStage获取链。
+
+### 内部调用链参数传递
+
+仅在全部调用点可静态核对且不破坏公开HAR/HSP消费者时追加参数；声明、构造器/普通调用及所有相关文件同时处理。只需filesDir等值时传common.Context或最小值，不先注入UIContext再断言HostContext非空。保留可选/默认参数与位置；可选参数后增加必需参数时逐项调整调用，不遗漏需要补undefined的旧参数。可空函数类型的括号不改变。
+
+### 既有依赖内的受控服务
+
+前三种来源不能满足且Ability/窗口/初始化归属可证明时才考虑。优先已有公共模块及最短已声明依赖链，不覆盖现有ContextUtils，不在各模块复制Provider。可用带Ability/窗口键的现有服务时优先使用，不能把多窗口变成“最后激活窗口”。下面代码只适用于已核实单个活动Ability、单主窗口的场景，不作为多实例通用方案。
+
+## 全局接口到UIContext接口
+
+表中接收者均为先前获取的真实`uiContext`。版本列只表示该UIContext成员的准确since，不替代获取链、返回对象方法、参数/重载的独立门槛核查；不是对所有同名全局调用的自动替换证明。
+
+| 原入口/调用 | UIContext成员 | 成员起始版本 | 差异/边界 |
+| --- | --- | --- | --- |
+| `@ohos.animator` | `uiContext.createAnimator(...)` | 10；18 | AnimatorOptions起点10；SimpleAnimatorOptions重载18 |
+| `@ohos.arkui.componentSnapshot` | `uiContext.getComponentSnapshot(...)` | 12 | 再核对返回对象的get等具体重载 |
+| `@ohos.arkui.componentUtils` | `uiContext.getComponentUtils(...)` | 10 | 按返回对象操作，不混用实例 |
+| `@ohos.arkui.dragController` | `uiContext.getDragController(...)` | 11 | 按返回对象的具体方法核对参数 |
+| `@ohos.arkui.inspector` | `uiContext.getUIInspector(...)` | 10 | 按实际观察器成员迁移 |
+| `@ohos.arkui.observer` | `uiContext.getUIObserver(...)` | 11 | 订阅与取消保持实例/回调身份 |
+| `@ohos.font` | `uiContext.getFont(...)` | 10 | 字体注册等使用返回对象 |
+| `@ohos.measure` | `uiContext.getMeasureUtils(...)` | 12 | measureText返回宽度；measureTextSize返回尺寸，不能混换 |
+| `@ohos.mediaquery` | `uiContext.getMediaQuery(...)` | 10 | 保留查询条件和监听生命周期 |
+| `@ohos.promptAction` | `uiContext.getPromptAction(...)` | 10 | showToast/showDialog/openCustomDialog/closeCustomDialog/showActionMenu仍核对各自签名 |
+| `@ohos.router` | `uiContext.getRouter(...)` | 10 | 保留路由参数、返回值与异步形态 |
+| `AlertDialog.show` | `uiContext.showAlertDialog(...)` | 10 | 保留按钮和用户回调 |
+| `ActionSheet.show` | `uiContext.showActionSheet(...)` | 10 | 保留选项及选择回调 |
+| `CalendarPickerDialog.show` | 待具体接口核验 | —（未提供直接替代） | 本条不提供可直接套用的UIContext替代；不等价替成DatePickerDialog，查具体控件/SDK并留证据缺口 |
+| `DatePickerDialog.show` | `uiContext.showDatePickerDialog(...)` | 10 | 保留日期参数和回调 |
+| `TimePickerDialog.show` | `uiContext.showTimePickerDialog(...)` | 10 | 保留时间参数和回调 |
+| `TextPickerDialog.show` | `uiContext.showTextPickerDialog(...)` | 10；20 | 基础重载10；TextPickerDialogOptionsExt重载20 |
+| `ContextMenu` | `uiContext.getContextMenuController(...)` | 12 | 以实际旧成员（如close）及返回控制器成员配对 |
+| `focusControl` | `uiContext.getFocusController(...)` | 12 | 保留请求焦点的真实目标 |
+| `cursorControl` | `uiContext.getCursorController(...)` | 12 | 保留光标相关参数 |
+| `getContext` | `uiContext.getHostContext(...)` | 12 | 返回common.Context或undefined；不能据此强转UIAbilityContext |
+| `LocalStorage.getShared` | `uiContext.getSharedLocalStorage(...)` | 12 | 返回LocalStorage或undefined，保留原存储身份 |
+| `animateTo` | `uiContext.animateTo(...)` | 10 | 保留动画参数和同步闭包 |
+| `animateToImmediately` | `uiContext.animateToImmediately(...)` | 23 | 提供对应UIContext成员，since23 |
+| `vp2px` | `uiContext.vp2px(...)` | 12 | 保留单位及数值，不用一项转换代替另一项 |
+| `px2vp` | `uiContext.px2vp(...)` | 12 | 保留单位及数值，不用一项转换代替另一项 |
+| `fp2px` | `uiContext.fp2px(...)` | 12 | 保留单位及数值，不用一项转换代替另一项 |
+| `px2fp` | `uiContext.px2fp(...)` | 12 | 保留单位及数值，不用一项转换代替另一项 |
+| `lpx2px` | `uiContext.lpx2px(...)` | 12 | 保留单位及数值，不用一项转换代替另一项 |
+| `px2lpx` | `uiContext.px2lpx(...)` | 12 | 保留单位及数值，不用一项转换代替另一项 |
+
+## 按场景迁移代码
+
+代码在各自适用场景使用，不把互不相干片段拼成同一函数。只展示支持版本上的接口迁移；最低版本保护按公共兼容指南实施。导入、Logger/hilog、TAG及失败出口沿用实际工程，不复制空catch或虚构默认成功。
+
+### 组件UIContext与HostContext
+
+迁移前（组件原有点击回调）：
+
+```ts
+import { promptAction } from '@kit.ArkUI';
+
+Button('保存').onClick(() => {
+  promptAction.showToast({ message: '保存成功' });
+});
+```
+
+迁移后（相同组件/业务回调）：
+
+```ts
+Button('保存').onClick(() => {
+  this.getUIContext().getPromptAction().showToast({ message: '保存成功' });
+});
+```
+
+getContext迁到HostContext时，保留实际消费者及可空处理。例如在原本允许失败后结束的void实例方法中：
+
+```ts
+const context = this.getUIContext().getHostContext();
+if (!context) {
+  hilog.error(0x0000, 'ContextMigration', 'Host context is unavailable');
+  return;
+}
+const filesDir = context.filesDir;
+```
+
+filesDir继续交给原消费者，不改为cacheDir；原函数需返回false/枚举等失败值时沿用那个出口，不能复制上述void return掩盖契约。
+
+### 已有Window与WindowStage
+
+```ts
+import { UIContext, window } from '@kit.ArkUI';
+
+function fromWindow(currentWindow: window.Window): UIContext {
+  return currentWindow.getUIContext();
+}
+
+function fromWindowStage(stage: window.WindowStage): UIContext {
+  return stage.getMainWindowSync().getUIContext();
+}
+```
+
+两种来源分别核对异常声明及调用方既有边界，不为了复制示例吞掉获取失败。它们代表真实已有对象，不表示应新增全局窗口查找链。
+
+### 参数注入与最小上下文
+
+迁移前：
+
+```ts
+import { promptAction } from '@kit.ArkUI';
+
+function showSaved(message: string): void {
+  promptAction.showToast({ message });
+}
+```
+
+迁移后：
+
+```ts
+import { common } from '@kit.AbilityKit';
+import { UIContext } from '@kit.ArkUI';
+
+function showSaved(message: string, uiContext: UIContext): void {
+  uiContext.getPromptAction().showToast({ message });
+}
+
+function makePath(filename: string, context: common.Context): string {
+  return context.filesDir + '/' + filename;
+}
+```
+
+组件调用点使用showSaved('保存成功', this.getUIContext())；makePath只接收已判空的真实Context。构造器注入用显式字段/赋值，覆盖全部new调用，不用ArkTS不支持的参数属性简写；动态调用或公开消费者无法证明时，不破坏签名。
+
+### 受控ContextUtils与同归属清理
+
+以下单份服务置于真实已有共享模块，类名仅示例。AbilityContext来自真实Ability，UIContext由已确认loadContent加载的入口组件注册；getter保持可空，旧页面令牌不能清除新页面注册。
+
+```ts
+import { common, UIAbility } from '@kit.AbilityKit';
+import { UIContext } from '@kit.ArkUI';
+
+export class ContextUtils {
+  private static owner: UIAbility | undefined = undefined;
+  private static ability: common.UIAbilityContext | undefined = undefined;
+  private static ui: UIContext | undefined = undefined;
+  private static nextToken: number = 1;
+  private static currentToken: number = 0;
+
+  static registerAbility(owner: UIAbility, context: common.UIAbilityContext): void {
+    if (ContextUtils.owner && ContextUtils.owner !== owner) {
+      throw new Error('Context service requires a single active Ability');
+    }
+    ContextUtils.owner = owner;
+    ContextUtils.ability = context;
+  }
+
+  static setUIContext(uiContext: UIContext): number {
+    if (!ContextUtils.owner) {
+      throw new Error('Ability context is not registered');
+    }
+    const token = ContextUtils.nextToken++;
+    ContextUtils.ui = uiContext;
+    ContextUtils.currentToken = token;
+    return token;
+  }
+
+  static clearUIContext(token: number): void {
+    if (ContextUtils.currentToken === token) {
+      ContextUtils.ui = undefined;
+      ContextUtils.currentToken = 0;
+    }
+  }
+
+  static clearWindow(owner: UIAbility): void {
+    if (ContextUtils.owner === owner) {
+      ContextUtils.ui = undefined;
+      ContextUtils.currentToken = 0;
+    }
+  }
+
+  static clearAbility(owner: UIAbility): void {
+    if (ContextUtils.owner === owner) {
+      ContextUtils.clearWindow(owner);
+      ContextUtils.ability = undefined;
+      ContextUtils.owner = undefined;
+    }
+  }
+
+  static get globalContext(): common.Context | undefined {
+    return ContextUtils.ability;
+  }
+
+  static get globalUIAbilityContext(): common.UIAbilityContext | undefined {
+    return ContextUtils.ability;
+  }
+
+  static get globalUIContext(): UIContext | undefined {
+    return ContextUtils.ui;
+  }
+}
+```
+
+在真实UIAbility.onCreate首句调用ContextUtils.registerAbility(this, this.context)，原生命周期逻辑继续保留；onWindowStageDestroy调用clearWindow(this)，onDestroy调用clearAbility(this)。不要把HostContext强转成UIAbilityContext，也不要只登记UIContext就伪造AbilityContext。
+
+已核实的入口组件使用同一份ContextUtils，保存注册令牌；导入从实际已有模块路径取得：
+
+```ts
+private contextToken: number = 0;
+
+aboutToAppear(): void {
+  this.contextToken = ContextUtils.setUIContext(this.getUIContext());
+}
+
+aboutToDisappear(): void {
+  ContextUtils.clearUIContext(this.contextToken);
+}
+```
+
+消费者按可空结果及原失败出口处理，不使用as、非空断言或空字符串/零值消除缺失。不把请求/事件/页面临时对象缓存到服务。多Ability、specified模式或多窗口无法证明归属时，使用显式参数/窗口键方案，不套用本例。
+
+公共模块需要跨已有依赖导出时，仅沿实际存在的依赖链转发唯一符号；例如已有phone→business_mine→module_feedback，可由module_feedback导出带模块名的ContextUtils，business_mine再转发。不要增加新依赖或重复创建Provider。
+
+### 单位转换与组件截图
+
+旧px2vp(10)对应uiContext.px2vp(10)，返回值继续交给原消费者：
+
+```ts
+const uiContext = this.getUIContext();
+const logicalWidth = uiContext.px2vp(10);
+```
+
+旧componentSnapshot.get的接收者迁为当前实例，保留同一id、回调与图像消费者：
+
+```ts
+import { UIContext } from '@kit.ArkUI';
+import { image } from '@kit.ImageKit';
+import { AsyncCallback } from '@kit.BasicServicesKit';
+
+function capture(uiContext: UIContext, id: string, callback: AsyncCallback<image.PixelMap>): void {
+  uiContext.getComponentSnapshot().get(id, callback);
+}
+```
+
+callback使用原有实现，保留实际错误处理、PixelMap消费者与释放顺序；文本测量分别使用getMeasureUtils().measureText和measureTextSize，按所需的宽度或尺寸选择，保留真实返回类型。
+
+## 迁移后的约束复核
+
+- 组件this绑定、原窗口、早期字段初始化、Ability/页面令牌及生命周期分别核实；只有aboutToAppear不证明早期字段可改。
+- 保留公开HAR/HSP接口和已有依赖，不能仅为统一形式新增服务或复制WindowStage链。
+- 真实获取/替代链门槛逐项核对，不能由弃用版本反推since；完整兼容处理见公共兼容指南。
+- 可空返回使用已有失败契约，表达式求值顺序、参数、同步/异步和返回形态保持；通用规则见公共编码规范。
+- 调用位置、原始行、真实修改与未解决项按废弃主流程记录；设备取证/清理由既有公共验证专题承担，不在此重复定义。

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

@@ -0,0 +1,157 @@
+# 废弃API完整迁移流程
+
+本页独立组织deprecated任务，从应用范围与准确SDK声明到完整构建、残留分析和逐行交付。按D01–D11推进，公共专题在需要操作时引用；条件步骤记录执行、跳过或阻断原因。现有入口支持HAP及注册模块/目录范围，不扩展为独立HAR废弃入口。
+
+## 用户决策与确认
+
+D05先汇总全部可评估范围的迁移方案，列符号/重载、文件/rowIds、必要配置、兼容风险、方案选择/推荐、验证及未解决项；展示后请求批准全部、指定部分或暂不修改，再实施代表调用。初始“自动修复/全部处理”不能替代方案展示后的同意，不能先试改再补批。仅分析或全无需修改且无配置调整时不请求无意义的修改批准。
+
+优先使用宿主交互工具，无工具则给清晰选项等待文本答复；推荐、预选、沉默和超时不是批准。部分批准须唯一对应方案和必要共享修改，影响未批准范围先澄清。同一批准方案的实现细节可继续；新增范围、目标或实质迁移/兼容方案变化时，展示差异并重新确认受影响部分。
+
+设备验证只按用户明确要求安排，不主动增加设备询问。单次设备验证只使用本次修改后构建产物，不要求修改前包或采集基线。修改批准与设备授权分开记录；恢复只补缺项、不默认历史已批准，不逐文件重问。
+
+## D01 确定应用与迁移范围
+
+- **适用条件**：全部废弃任务与断点继续。
+- **输入**：用户目标、应用工程、已有CSV、实际源码及未提交改动。
+- **动作**：读取根build-profile.json5和模块module.json5，按实际JSON5解析；确定product、deprecated、应用入口和授权注册模块/目录。同类取并集、不同类型取交集，按物理路径核对junction/符号链接及工程外注册模块，记录已有改动，不猜目录。
+- **输出**：唯一工程/product/物理范围、修改/验证目标和已有改动。
+- **完成判据**：可准确限定扫描与修改范围；独立HAR输入不自动扩大本入口支持。联合任务协调共享文件/配置，不互代两类结果。
+- **异常处理/下一步**：候选有歧义列实际选项询问，无法限定停止该范围并保留事实；明确后D02。
+
+## D02 核对SDK与迁移目标
+
+- **适用条件**：所有任务，实际扫描/构建前核对。
+- **输入**：所选product原target/compatible、用户指定目标与工具路径。
+- **动作**：按[版本契约](../common/sdk-versions.md#配置设备与打包字段)及[环境核查](../common/verification.md#环境与依赖)读取真实SDK/IDE和配套Node/Java/ohpm/Hvigor。确定目标SDK/target与原compatible；from仅为scanner要求的版本参数，不限制废弃声明出现时间。配置API26写26.0.0，扫描参数保留准确通道，未要求调整的compatible保留。
+- **输出**：实际旧/目标配置、准确扫描参数、编译SDK/IDE与工具位置、缺口及必要用户答复。
+- **完成判据**：按目标全量废弃检测，SDK可高于target，compatible≤target≤编译SDK，不擅自升级/降低配置或混淆Beta/Release。无法由任务和工程唯一确定目标时询问，不靠工具安装版本代选。
+- **异常处理/下一步**：路径无效不偷偷换SDK；缺工具可继续已有CSV的可信静态分析，不能虚构扫描/构建成功。目标/SDK覆盖不足暂停相关工具步骤，可信部分仍交付D11；可执行时D03。
+
+scanner当前两种模式均要求from<to。废弃任务没有显式from时，使用scanner认可且早于目标的最早技术基线；当前内置基线为`5.0.0(12) Release`，执行前按实际版本解析确认。目标已为26时也可使用12→26，不制造26→26区间、不回退工程配置。这个技术起点不代表工程原target/compatible，不限制目标SDK中的废弃声明时间。用户显式from须保留并验证；无效或不早于目标时报告并澄清，不静默换值。没有合法早于目标的基线则停止扫描，保留可信静态部分。
+
+## D03 扫描或导入废弃记录
+
+- **适用条件**：新扫描、已有/历史CSV及零命中。
+- **输入**：D01/D02及原始CSV、扫描JSON、coverage/diagnostics。
+- **动作**：先执行scanner真实help，再用下方deprecated命令。默认输出根为任务启动目录.api-change-output，用户路径优先；按[目录与原件](../../templates/progress.md#建议目录)使用布局4的返回路径。导入复制原字节及伴随证据到新批次，不以较小adapted表为原基线、不搬动原表、不恢复旧账本/批次状态。
+- **输出**：原件/副本路径与SHA-256，deprecated交付目录、真实退出码、覆盖/诊断与来源边界。
+- **完成判据**：区分全量覆盖、未解析/依赖、后端失败和CSV_ONLY。保留全部原始列和逻辑行。新 CSV 的 Replacement API 仅作替代提示；API Symbol ID、列号、废弃时间、Replacement Source 和 Detection Source 从同批次扫描 JSON 读取，不要求它们出现在精简 CSV 中。
+- **异常处理/下一步**：失败保留已扫描可信部分及未覆盖范围，不用grep代替后端；原件变化先核查。可处理行进D04，完全受阻仍D11；排错方法见[公共专题](../common/troubleshooting.md)。
+
+```console
+node "<skill-root>/scripts/scanner/bin/harmony-api-scan.mjs" help
+node "<skill-root>/scripts/scanner/bin/harmony-api-scan.mjs" scan --mode deprecated --project "<工程>" --sdk "<SDK>" --deveco-home "<IDE>" --from "<真实版本参数>" --to "<目标SDK精确版本>" --product "<产品>" --output-dir "<输出根>"
+```
+
+## D04 解析并按准确符号归组
+
+- **适用条件**：全部原始行，包含重复、范围外和零行。
+- **输入**：原始CSV、伴随扫描JSON、准确声明身份与实际物理范围。
+- **动作**：按[逐行结果](../../templates/results.md)可靠解析CSV，用输入SHA-256+逻辑数据行序号构造rowId，保留原列/原序/全部重复行；范围外/其他功能标原因不删除。按SDK符号、接收者、声明/重载及物理文件归组，身份不明独立保留；类与成员双命中分别编号。新批次按 JSON actionGroups 的顺序核对 CSV 行及可见字段，读取 occurrences 中的完整身份；同一行多调用和显示相同的记录仍逐条保留。只有 CSV 时按完整签名、代码位置、接收者和真实 SDK 声明补证，不能唯一确认的保留 EVIDENCE_GAP，不凭方法名合并。初始化[通用进度](../../templates/progress.md)和本页[迁移记录](#废弃迁移记录)。
+- **输出**：原始行→SDK符号→物理文件/工作单元与局部证据缺口。
+- **完成判据**：不按模糊名称或方法名子串合并；原始行、位置、物理文件、符号和工作单元分别统计，不套用行为三类分类。
+- **异常处理/下一步**：解析/身份/文件缺失保留具体问题，不吞重复、不删未完成组；零行D11，其余D05。
+
+## D05 逐文件制定并批准迁移方案
+
+- **适用条件**：每个废弃候选及关联调用文件。
+- **输入**：SDK旧/替代声明、接收者与重载、全部实际调用/消费者、业务与已有依赖。
+- **动作**：按[声明与替代](#声明与替代)和[迁移选择顺序](#迁移选择顺序)核对准确useinstead、各新增调用/参数since、来源/可空/生命周期、返回/回调/异常契约。修改前读[兼容](../common/compatibility.md)和适用[编码规范](../common/arkts-coding-standards.md)；Context命中读[Context迁移](context-migration.md)。先分析代表调用与其他文件前提，写逐文件方案/验证并汇总，取得本页要求的批准后才试改。
+- **输出**：准确替代依据、逐文件计划、必要配置/兼容/验证、实际批准范围或待决定/缺口。
+- **完成判据**：覆盖关联声明和消费者，不因非组件没有this或旧API低版本可用而跳过。准确SDK可提供替代事实，不要求必须有changelog；已评估与已解决分开。
+- **异常处理/下一步**：局部声明/业务证据不足分别记录EVIDENCE_GAP/DECISION_REQUIRED，独立单元可继续。未获展示后方案批准不修改；无修改计划不要求批准。获批后直接D06，暂不修改则D11交付可信分析。
+
+## D06 实施获批迁移与跨文件修改
+
+- **适用条件**：已有方案展示后的实际批准；无需修改、未批准和缺口行也保留结果。
+- **输入**：逐文件方案、批准范围、当前源码和已有用户改动。
+- **动作**：先在获批范围修改代表调用，再按相同前提推广到全部关联文件；声明/内部调用链/必要导入同步最小修改，不破坏公开接口或新增依赖。按[异常与异步](#异常和异步契约)保留参数求值、返回/resolve/reject/回调及生命周期，核对替代链since和真实低版本回退；定点修改所选product获批必要配置，保留签名/其他产品。每文件更新差异/结果，编译置待执行。
+- **输出**：真实源码/必要配置差异、逐行结果和迁移进度。
+- **完成判据**：每个MODIFIED有相关实质差异与兼容依据；一个修改覆盖类/成员多行须分别解释。日志/格式/根配置或同文件其他修改不算该行修复，未批准不记NO_CHANGE/MODIFIED，原Fixed保留。
+- **异常处理/下一步**：实质方案/范围/目标变化回D05/D02确认受影响部分；未知归属与缺上下文保留，不覆盖任务外改动/整文件回滚。完成D07。
+
+## D07 复核迁移语义与配置
+
+- **适用条件**：修改后及相关输入再次变化。
+- **输入**：实际diff、准确SDK、所有调用者、旧新配置及工程约定。
+- **动作**：按[通用静态复核](../common/verification.md#通用静态复核)及[废弃迁移兼容复核](../common/verification.md#废弃迁移兼容复核)检查准确接收者、参数/返回、辅助链since、低版本回退、成对on/off、可空性、异常/Promise/失败出口；回读配置并执行实际可用SDK/IDE检查，区分新增与历史诊断。
+- **输出**：模型复核与工具通过/失败/未执行分别记录，配置实际值及待修闭包。
+- **完成判据**：原业务和失败出口保留；不使用不安全转换、空catch或虚构默认值掩盖迁移问题。模型复核或仅新增错误为0不代替全量检查通过。
+- **异常处理/下一步**：源码失败仅修必要范围后回D06/D07，最多三种实质源码失败方案；工具缺失明确保留。可构建D08，受阻D11部分交付。
+
+## D08 完整构建并确认当前产物
+
+- **适用条件**：每轮源码/构建配置修改后必须执行；未修改按任务验证范围安排。
+- **输入**：本轮最终源码/配置、真实配套SDK/Java/ohpm/Hvigor、product和模块。
+- **动作**：按[完整构建](../common/verification.md#完整构建与产物)安装必要依赖并完整构建HAP，保留实际参数/cwd/版本/日志/退出码，核对本次新产物身份、大小/哈希及副本，不能只看日志前部成功任务。
+- **输出**：当前输入对应的编译、产物与签名/安装事实。
+- **完成判据**：真实构建成功且有对应本次产物；模型检查、废弃复扫、旧包或命令未启动均不代替成功。后续源码/配置/SDK变化后相关成功失效需重建，高版本编译不证明低版本设备通过。
+- **异常处理/下一步**：代码失败回D06/D07，环境/依赖/签名/超时不消耗源码方案次数，条件未变不空重试。未构建成功到D11部分完成/待编译交付，保留现场。成功D09。
+
+## D09 真实复扫与残留分类
+
+- **适用条件**：废弃修改后必须；未修改时按验证安排说明实际执行或未执行。
+- **输入**：原始扫描、当前源码、相同deprecated模式/product/目标/范围及SDK。
+- **动作**：用D03真实scanner生成新批次，保留原件和真实覆盖/诊断；按准确符号、迁移归属和当前调用位置对应rowIds，分别解释未迁移、合法受保护低版本回退、依赖问题、工具缺口与新引入问题。行号移动不机械按旧数字匹配。
+- **输出**：复扫路径、覆盖/诊断、各类残留及关联原始行。
+- **完成判据**：原候选均有解释，新废弃/未保护残留已修或列待办；合法回退不为清零删除，依赖源码不改。数量下降或归零不证明迁移语义正确，不缩小范围制造完成。
+- **异常处理/下一步**：复扫失败/不完整明确缺口，不关闭残留验收；实际问题回D05/D06-D09并重新验证，独立可信部分保留。然后D10或D11交付。
+
+## D10 按要求验证实际迁移功能
+
+- **适用条件**：用户明确要求设备/业务验证；未要求则记录NOT_RUN并跳过，不额外询问。
+- **输入**：当前构建HAP、明确设备/系统、迁移rowIds与用例/前置数据。
+- **动作**：按[单次设备验证](../common/verification.md#单次设备验证)和[通用功能取证](../common/runtime-functional-tests.md#通用功能取证)安装本次构建产物，执行用户要求的功能用例，保存实际调用、返回/回调/异常、设备/系统、日志与图片。验证范围按实际请求记录；先保存现场，再只清理本次启动实例并确认状态。
+- **输出**：本次运行、功能、视觉、实际覆盖与清理的独立结论和原始证据。
+- **完成判据**：每个通过结论有本次真实操作与相关观测，不以仅启动、截图或零用例代替功能；代码或产物变化后相关结果须重新验证。
+- **异常处理/下一步**：设备歧义不换实例，已有实例保留，启动/停止失败与模型中断分别记录，不冒充业务失败/通过。全部结局D11，缺设备或低版本列具体未验收。
+
+## D11 核对迁移覆盖并交付
+
+- **适用条件**：正常、零命中、全无需修改、待批准、证据不足、失败或停止。
+- **输入**：全部原始行、准确替代依据、批准、实际差异、进度及检查/构建/复扫/设备证据。
+- **动作**：按[逐行结果](../../templates/results.md)回读每行唯一对应和全部重复；按[废弃报告](../../templates/deprecated-report.md)在deprecated目录交付，先展示product/范围与配置实际旧→目标及实施状态，再按六类处理结论逐行概括。逐符号/文件说明替代依据、迁移、兼容、残留、批准/未实施、失败与下一步，核对原件哈希和文件实际可读。
+- **输出**：原扫描、adapted-results-<批次ID>.csv、api-adapt-report.md、轻量进度及证据的完整路径。
+- **完成判据**：六类合计等于原始逻辑行数，重复单列计数；记录/位置/物理文件/符号与工作单元不混。评估、修改、编译、复扫、运行和最低版本分开；遗漏/过期/未成功编译只能部分完成，扫描工具缺口单独说明。
+- **异常处理/下一步**：交付被用户修改另存版本，不覆盖；任何失败仍保留可信成果。按[继续与撤销](../common/troubleshooting.md)核对当前输入、实际批准与旧证据，回到受影响D步骤；不重置停止次数、不继承旧Fixed成功或恢复旧账本。
+
+## 声明与替代
+
+按目标SDK全量检测废弃调用；扫描from不是废弃声明时间下限。保留原始行；从扫描 JSON 或历史 CSV 读取 API Symbol ID、Replacement API/Source、Detection Source，标明来源及缺口，不要求新 CSV 包含已移出的字段。相同调用同时命中废弃类和成员时，两行分别保留并解释同一次修改如何覆盖。
+
+从真实SDK读取旧声明、准确接收者、重载、useinstead及替代声明；不能把业务同名方法当SDK、匹配方法名子串或按所有重载取最大since。替代例子没有写在changelog不等于无法迁移，优先核对SDK提供的替代事实；声明真正冲突才留局部缺口。
+
+since必须来自调用绑定的准确接口/成员/参数声明。错误码、crossplatform、atomicservice等标签不是接口起始版本。保留HMS平台版本、整数API和原文，无法解析说明具体标签/声明问题，不直接写“SDK没有since”。
+
+## 迁移选择顺序
+
+先分析代表调用并核对其他文件是否满足相同前提，将逐文件迁移、必要配置、兼容风险与验证安排汇总，按[用户决策与确认](#用户决策与确认)取得批准后才修改和验证代表调用，再沿批准范围批量落地；每个原始文件和行仍有独立结果。不能先试改代表调用再请求批准，也不能只因“旧API低版本可用”或“不是组件没有this.getUIContext”跳过分析。
+
+上下文命中必须读取[Context迁移](context-migration.md)：组件自身UIContext → 已有参数/成员/真实Window → 完整内部调用链传入最小Context → 仅在已有依赖与生命周期可证明时复用受控服务。保护公开HAR/HSP接口，不为了统一方案新增模块依赖，不在各文件复制AppStorage WindowStage链。
+
+实例/构造器替代保留原locale/options、缓存身份、参数默认值、回调和生命周期；构造器注入采用显式字段/赋值，遵循ArkTS限制。读取[废弃迁移样例](deprecated-api-examples.md)中实际命中的章节，不能把示例前提套到所有文件。
+
+## 兼容与残留
+
+替代调用/辅助链的since及低版本完整方案按[公共迁移兼容要求](../common/compatibility.md#迁移调用的版本与回退)核对；准确接收者和方法差异读按Kit样例。
+
+合法低版本回退中仍有旧调用可以解释为受保护残留，不能只为复扫清零删除回退。替代方案不得引入其他废弃API。依赖告警保留来源/升级建议，不修改oh_modules或把外部依赖当本工程修复成果。
+
+## 异常和异步契约
+
+迁移前后准确throws、获取失败和所有消费者按[公共编码规范](../common/arkts-coding-standards.md#异常异步与-api-迁移)及其表达式/失败出口要求复核；通用规则与示例不在本流程重复维护。真实SDK替代、组件/窗口来源和迁移代码分别读[Context专题](context-migration.md)与[按Kit样例](deprecated-api-examples.md)。
+
+## 验证与结果
+
+修改及必要配置只在D05汇总方案已获批准的范围实施，遵守共用兼容与适用编码规范；部分批准、暂不修改或待答复分别记录，未批准不实施，不当作无需修改。实质方案变化回D05确认，仍适用的批准不逐文件重问。随后D07真实可用检查、D08完整构建、D09真实复扫；按用户要求D10设备验证，任何结局都D11按[废弃报告模板](../../templates/deprecated-report.md)交付，突出方案答复、SDK替代声明、逐文件迁移与残留分类。修改后未真实编译成功时只能标部分完成/待编译或失败，不能用复扫清零替代。
+
+每个结果写MODEL_ASSESSED，MODIFIED说明相关真实差异与兼容理由；NO_CHANGE、DECISION_REQUIRED、EVIDENCE_GAP和未处理分别报告。语义判断、编译和最低设备验收独立，不用文件变化、构建通过、残留清零或旧Fixed推定自动证明。
+
+## 废弃迁移记录
+
+使用同一份[通用进度](../../templates/progress.md)和[逐行结果](../../templates/results.md)。decisions.repair记录汇总方案、实际答复及approvedItems；decisions.target保存目标来源，runtime按实际请求记录未要求、不运行或单次设备验证，不强制等待未要求的设备选择。
+
+组identity使用准确SDK符号、接收者/重载与声明位置，files.evidence关联旧/替代声明、各辅助链since和实际源码；plan写最小迁移及兼容/验证安排。跨文件声明、调用者及共享修改一并关联，类/成员双命中保留各rowId与覆盖解释。
+
+在现有reason/evidence/next保留复扫对应、未迁移/合法回退/依赖/工具缺口/新问题及下一步；不增CSV列，不填写行为knowledge、rowClassifications或三类分类。报告首页按NO_CHANGE、MODIFIED、DECISION_REQUIRED、EVIDENCE_GAP、PENDING、OUT_OF_SCOPE逐逻辑行核对。