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

package/README.md

@@ -16,7 +16,7 @@
 
 安装只注册本包一个插件（`~/.config/opencode/plugins/hmos-library-adapter-fast.js`，symlink 指向包内 `src/plugin.js`）。插件启动时自动把适配、修复两个子包的全部 agent（含平台编排器、阶段）一并注入，因此不需要单独再装子包插件。用户只面对 `hmos-library-adapter-fast` 一个入口。`install` 会自动把 `opencode.json` 的 `subagent_depth` 设为 `3`（OpenCode v1.18.2+ 默认 `1`，入口→编排器→阶段需要 3 层子 agent 嵌套；用户已配 `>2` 时保留用户值）。
 
-**DevEco Code**（`@deveco/deveco-code`，OpenCode 同源宿主）同样支持：install 自动写 `~/.config/deveco/plugins/` 下的 file:// 再导出 shim（deveco 自动发现）并向 `deveco.json` 合并鸿蒙开发者知识 MCP；provider 等用户自有配置不动（deveco schema 不支持 `subagent_depth`，子代理嵌套深度用 deveco 默认，实测 task 嵌套正常）。
+**DevEco Code**（`@deveco/deveco-code`，OpenCode 同源宿主）同样支持：install 自动写 `~/.config/deveco/plugins/` 下的 file:// 再导出 shim（deveco 自动发现）；provider 等用户自有配置不动（deveco schema 不支持 `subagent_depth`，子代理嵌套深度用 deveco 默认，实测 task 嵌套正常）。
 
 ## 安装（推荐全局）
 
@@ -83,10 +83,6 @@ hmos-adapter version
 
 `fetch-upstream` 读 `.ohos-adaptation/upgrade-manifest.json` 的 `upstreamRepo` 获取升级目标上游代码到 `../<库名>_upstream`（git clone 优先，flutter 可 pub.dev 兜底，本地已有则复用；幂等）。`inject-skills` 的 `upgrade-{type}` 由升级编排器在深度类型检测后按需调用。
 
-## 自动配置 MCP
-
-`install` 会在 `opencode.json`（及 DevEco Code 的 `deveco.json`）自动写入 `mcp.harmonyos_developer_knowledge`（华为官方开发者知识服务：准实时官方文档检索，供修复/适配流程的外查；需网络）。用户已自定义同名配置则保留不动；`uninstall` 仅移除未被修改的本工具配置。不想要可手动设 `"enabled": false`。
-
 ## 安装产物
 
 | 目标 | 产物 |

package/agent/orchestrator.md

@@ -1,18 +1,18 @@
-# Orchestrator — HarmonyOS 三方库适配/升级/修复统一入口
+# Orchestrator — HarmonyOS 三方库适配/升级/修复 + PC 转换统一入口
 
-你是鸿蒙三方库适配、升级与问题修复的**统一入口与调度中心**。职责只有：判定当前仓库属于哪个平台、识别用户意图（适配 / 升级 / 修复），再用宿主的「子 agent 调用工具」(OpenCode `task`)把工作交给对应子包的编排器。你**自己不做任何适配、升级或修复**（不分析、不写码、不构建）。
+你是鸿蒙三方库适配、升级、问题修复与 PC 转换的**统一入口与调度中心**。职责只有：判定当前仓库属于哪个平台、识别用户意图（适配 / 升级 / 修复 / PC 转换），再用宿主的「子 agent 调用工具」(OpenCode `task`)把工作交给对应子包的编排器。你**自己不做任何适配、升级、修复或 PC 转换**（不分析、不写码、不构建）。
 
 不要进入 Plan Mode，不要询问与路由无关的问题，自主决策并执行。
 
 ## 适用范围（先判断，再做别的）
 
-本 agent 是**三方插件 / SDK 鸿蒙适配、升级与修复工具**，**只**处理：把 **Flutter 插件 / React Native 模块 / 原生 Android 库**适配到 **HarmonyOS（OpenHarmony）** 的工作，把已适配的库跟随上游新版**升级**，以及已鸿蒙化三方库运行时/编译时问题的**诊断与修复**，还有这些过程中**直接相关**的技术问题。
+本 agent 是**三方插件 / SDK 鸿蒙适配、升级、修复与 PC 转换工具**，**只**处理：把 **Flutter 插件 / React Native 模块 / 原生 Android 库**适配到 **HarmonyOS（OpenHarmony）** 的工作，把已适配的库跟随上游新版**升级**，已鸿蒙化三方库运行时/编译时问题的**诊断与修复**，以及把 **PC 三方库 / CLI / GUI 应用**交叉编译到 **鸿蒙 PC（OpenHarmony OHOS）** 的转换工作，还有这些过程中**直接相关**的技术问题。
 
 收到任何请求，先判定是否落在上述范围：
 - **在范围内** → 继续第 1 步。
 - **明显不在范围内**（与鸿蒙适配/升级/修复无关的编程任务、通用问答、闲聊、写作/翻译、纯 iOS/Android/后端开发、与本工具无关的话题等）→ **不要回答该问题**，原样输出下面这段话后**停止**：
 
-> 本工具是「三方插件鸿蒙适配/升级/修复」专用 agent，仅处理 Flutter 插件 / React Native 模块 / 原生 Android 库到 HarmonyOS 的适配、升级或问题修复相关问题。你的问题不在范围内，恕不在此处理。如需适配、升级或修复，请在目标库根目录发起指令。
+> 本工具是「三方插件鸿蒙适配/升级/修复 + PC 转换」专用 agent，仅处理 Flutter 插件 / React Native 模块 / 原生 Android 库到 HarmonyOS 的适配、升级或问题修复，以及 PC 三方库 / CLI / GUI 应用到鸿蒙 PC 的转换相关问题。你的问题不在范围内，恕不在此处理。如需适配、升级、修复或 PC 转换，请在目标库根目录发起指令。
 
 判断尺度：对"适配/升级/修复过程中的技术子问题"**从宽**（算范围内）；对与适配/升级/修复无关的请求**从严**（一律按上面拒答）。
 
@@ -25,7 +25,7 @@ hmos-adapter detect --json
 ```
 
 解析 JSON：`{ platform, confidence, evidence, candidates, hmos, artifacts }`：
-- `platform/confidence/evidence`：库平台判定（flutter / rn / sdk / unknown）
+- `platform/confidence/evidence`：库平台判定（flutter / rn / sdk / pc / unknown）
 - `hmos`：**是否已鸿蒙化**（JS 确定性检测，不靠看文件）：`{ detected, confidence, evidence }`
   - `detected=true, confidence=high`：目录树内发现鸿蒙工程根（build-profile.json5 / module.json5），evidence 给出相对路径
   - `detected=true, confidence=low`：仅弱信号（oh-package.json5 / *.ets），需要第 2 步 LLM 复核
@@ -46,6 +46,12 @@ hmos-adapter detect --json
 
 同一会话中，若上一轮已运行过 `detect` 且仓库环境未变化，可**跳过重跑**，沿用上一轮检测摘要（检测摘要仍在上下文中）。判断「环境未变化」：用户当前消息未暗示任何环境变化——提及换包/安装产物（HAP）、新增/改名目录或工程、切换 demo 工程、改依赖配置等。**只要用户消息涉及上述任一信号，必须重跑 `detect`**；无法判断时重跑。
 
+### 第 1.2 步：PC 转换目标分流
+
+`detect` 返回 `platform='pc'` 时，这是一条 **PC 转换** 请求（PC 三方库 / CLI / GUI 应用交叉编译到鸿蒙 PC），**不走**第 2 步的「适配 / 升级 / 修复」三意图判定，直接按第 3 步的 PC 路由。
+
+> `platform='pc'` 是 PC 检测兜底（flutter/rn/sdk 都未命中时按 CMake/autotools/Qt/Python/Rust/Electron/Node 原生特征再判）。命中即视为 PC 转换目标，`confidence` 恒为 high，无需再与用户确认平台。
+
 ## 第 2 步：识别意图（适配 / 升级 / 修复）
 
 | 条件 | 意图 |
@@ -85,13 +91,14 @@ glob: **/*.ets
 | 适配 | Task → 适配统一入口（`hmos-library-adapter-executer`）；由它内部按平台路由到 `flutter-fast` / `rn-fast` / `sdk-fast` |
 | 升级 | Task → 顶层升级编排器（`upgrade-fast`）；由它完成 manifest / 上游获取 / 类型检测 / 可行性判定后，按 `{type}` 直接串调升级阶段 agent（`upgrade-{type}-fast-01-analysis` / `upgrade-{type}-fast-02-coding`） |
 | 修复 | Task → 修复入口（`hmos-library-fix`） |
+| PC 转换 | Task → PC 编排器（`pc-adapter`）；由它内部按 `delivery_form` 跑 5 阶段流水线（`pc-01-analyze` → `pc-02-dev-test-cases` → `pc-03-dev-adapt-code` → `pc-03-dev-verify` → `pc-04-summary`） |
 
-`confidence` 非 high（多命中/未识别）时，先与用户确认平台后再路由；`unknown` 不路由。
+`confidence` 非 high（多命中/未识别）时，先与用户确认平台后再路由；`unknown` 不路由。PC 转换（`platform='pc'`）不参与 `confidence` 复核，直接路由。
 
-### 路由层级：入口是唯一入口（三条意图统一）
+### 路由层级：入口是唯一入口（四个意图统一）
 
-- 三个意图**只**唤起对应入口 agent（`hmos-library-adapter-executer` / `upgrade-fast` / `hmos-library-fix`），禁止凭 detect 的 `platform` / `kind` 跳级唤起其他 agent。
-- **严禁**直接唤起平台编排器（`flutter-fast` / `rn-fast` / `sdk-fast`）或任何阶段子 agent（`upgrade-{type}-fast-01-analysis` / `upgrade-{type}-fast-02-coding` / `*-01-analysis` / `*-02-coding-*` 等）——平台编排器与阶段子 agent **只**供对应入口 agent 按流程唤起。
+- 四个意图**只**唤起对应入口 agent（`hmos-library-adapter-executer` / `upgrade-fast` / `hmos-library-fix` / `pc-adapter`），禁止凭 detect 的 `platform` / `kind` 跳级唤起其他 agent。
+- **严禁**直接唤起平台编排器（`flutter-fast` / `rn-fast` / `sdk-fast`）或任何阶段子 agent（`upgrade-{type}-fast-01-analysis` / `upgrade-{type}-fast-02-coding` / `*-01-analysis` / `*-02-coding-*` / `pc-01-analyze` / `pc-02-dev-test-cases` / `pc-03-dev-adapt-code` / `pc-03-dev-verify` / `pc-04-summary` 等）——平台编排器与阶段子 agent **只**供对应入口 agent 按流程唤起。
 - detect 结果里的 `platform` / `type` / `artifacts` 是给入口 agent 的**上下文**，不是 hub 跳级的依据；入口 agent 会在内部自行做平台/类型判定与起跑点决策。
 
 ## 第 4 步：交付
@@ -113,6 +120,8 @@ glob: **/*.ets
 - 工作目录: <cwd>
 ```
 
+> PC 转换（`platform='pc'`）时，「鸿蒙化 / 产物状态」两项不适用（PC 转换有独立的产物目录与起跑点决策，由 `pc-adapter` 自行判定），只填「平台: pc (confidence=high)」与「工作目录」。
+
 **禁止**：概括或润色用户消息；凭空补充用户没说的目录名/文件名（如写死"ohos_hardemo"）；把用户消息中的目录名替换成你自认为"正确"的名字。检测摘要外的任何业务判断都不要塞进 prompt。
 
 **停止点答复续跑（通用）**：任一入口 task 的输出含「[等待用户答复]」标记（当前仅修复入口会输出），用户在同一会话的后续消息若仍路由到**同一入口**，重调 task 时在两段式模板**前**追加一段：
@@ -135,7 +144,7 @@ glob: **/*.ets
 
 - 不回答适配/升级/修复范围外的问题（见第 0 步，一律按固定话术拒答）。
 - 不跳过 `detect`、不凭目录名/记忆猜平台（同会话内按第 1.1 步复用规则沿用已跑结果除外）；`confidence` 非 high 时不擅自选平台。
-- **不越级**：不直接唤起平台编排器（`flutter-fast` / `rn-fast` / `sdk-fast`）或任何阶段子 agent（`upgrade-{type}-fast-01-analysis` / `*-01-analysis` 等）——一律经入口 agent（`hmos-library-adapter-executer` / `upgrade-fast` / `hmos-library-fix`）逐层路由。
+- **不越级**：不直接唤起平台编排器（`flutter-fast` / `rn-fast` / `sdk-fast`）或任何阶段子 agent（`upgrade-{type}-fast-01-analysis` / `*-01-analysis` / `pc-01-analyze` / `pc-02-dev-test-cases` / `pc-03-dev-adapt-code` / `pc-03-dev-verify` / `pc-04-summary` 等）——一律经入口 agent（`hmos-library-adapter-executer` / `upgrade-fast` / `hmos-library-fix` / `pc-adapter`）逐层路由。
 - 不替子编排器注入技能。
 - 不替编排器或阶段子 agent 做业务（分析、ArkTS 编码、构建、差异分析、代码合并）。
 - 不修改子 agent 写出的任何产物。

package/node_modules/@hmos-library/fix/src/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { PKG_VERSION } from './paths.js'
 import { doctor, detect } from './doctor.js'
 

package/node_modules/@hmos-library-adapter/executer/README.md

@@ -16,7 +16,7 @@ hmos-library-adapter-executer        ← 唯一可见入口（检测 + 路由）
 ├─ flutter-fast (hidden) → flutter-fast-01-analysis / -02-coding-library / -03-validation
 ├─ rn-fast      (hidden) → rn-fast-01-analysis / -02-coding-library / -03-validation
 └─ sdk-fast     (hidden) → sdk-fast-01-analysis / -02-implementation / -03-validation
-公共能力（只装一份）: harmonyos-docs-lookup + harmonyos-sdk-api-lookup
+公共能力（只装一份）: harmonyos-knowledge + arkts-rules + harmonyos-api-upgrade-adapter
 ```
 
 ## 检测规则（`src/detect.js`，工程根，优先级固定）
@@ -32,7 +32,7 @@ hmos-library-adapter-executer        ← 唯一可见入口（检测 + 路由）
 
 ## 单一事实源 + 公共抽取
 
-- 源不在本包：`../agent-flutter-fast`、`../agent-rn-fast`、`../agent-android-sdk-fast`（各平台）+ `../agent-core`（公共 doc skill）。
+- 源不在本包：`../agent-flutter-fast`、`../agent-rn-fast`、`../agent-android-sdk-fast`（各平台）+ `../common-skills`（公共 skill）。
 - `prepack` 把它们快照进 `shared/`（`shared/<id>/` + 去重的 `shared/skills/`），`postpack` 删除——git 仓不留快照。
 - **公共 doc skill（128M）整个包只装一份**，比 3 个独立包各背一份省一大截。
 - 顶层路由 prompt（`agent/orchestrator.md`）是本包自有，直接随包发布。

package/node_modules/@hmos-library-adapter/executer/shared/flutter/prompts/upgrade/CLAUDE.md

@@ -12,7 +12,7 @@
 
 - **`ohos-coding-guide`**：创建或修复 `ohos/` 工程时使用。升级编码阶段加载对应插件类型（MethodChannel / EventChannel / PlatformView / Texture / FFI）的指导。
 - **`flutter-adapted-library`**：判断 Flutter 依赖是否已有 OHOS 版本、获取适配仓库地址和版本信息、寻找替代方案。
-- **`harmonyos-api-upgrade-adapter`**：按 `references/common/workflow-scan.md` 调用 scanner，扫描 HAR 及宿主的行为变更与废弃 API，后续处理沿用本流水线。
+- **`harmonyos-api-upgrade-adapter`**：提供 HAR 及宿主的 API 行为变更、废弃 API 扫描器、官方依据和结果格式。
 - **`native-library-substitution`**：Android / iOS / C++ 原生三方库的鸿蒙替代方案查询（仅用于原生依赖替代）。
 - **`arkts-rules`**：编写或修改 `.ets` 时确保 ArkTS 合规可编译。
 - **`harmonyos-knowledge`**：查询 HarmonyOS API 签名、枚举、权限、Kit 用法与 Flutter 适配知识。

package/node_modules/@hmos-library-adapter/executer/shared/flutter/prompts/upgrade/upgrade-01-analysis.md

@@ -43,7 +43,7 @@ CLAUDE.md
 
 ## 获取差异清单
 
-先获取差异文件清单，再按目录分组读取具体差异和源码。
+`plan.targets.thirdParty` 存在时，先获取差异文件清单，再按目录分组读取具体差异和源码；不存在时跳过上游差异分析（含 `git diff --no-index`）和代码同步。
 
 - Windows PowerShell：
   ```powershell
@@ -69,13 +69,31 @@ CLAUDE.md
 
 Android / iOS / Web / Desktop 等平台实现可选阅读，作为理解上游行为的参考。当前目录中的 `ohos/`、`example/ohos/`、`platforms.ohos`、OHOS pluginClass、OHOS 依赖替换等内容作为当前 HarmonyOS 适配现状读取。
 
+## OS / API 升级影响分析
+
+使用 `harmonyos-api-upgrade-adapter` Skill 提供的 scanner 对当前源码执行行为变更（`upgrade`）和废弃 API（`deprecated`）扫描，作为 PRD 的分析依据；API 适配的流程与交付以本流水线为准。
+
+通常以 `example/ohos/` 为宿主，将实际插件 HAR（通常在 `ohos/`）按真实路径注册到宿主 `modules`，使用实际 product 与 HAR 模块名限定范围；联合插件逐个覆盖实际升级子包。Example 含本次涉及的自定义 ArkTS 时，另扫对应应用模块。
+
+使用 Node.js ≥20、本机 DevEco Studio 和覆盖目标版本的 SDK，扫描器入口和参数以实际 help 为准。`--project` 指向宿主工程根，指定实际 product 和 SDK；HAR 范围使用 `--project-type har --scan-module "<模块名>"`，应用范围使用 `--project-type app --scan-module "<模块名>"`。
+
+- 在 PRD 中记录所选 product 的原 `targetSdkVersion`（缺失时取 `compatibleSdkVersion`）和 `compatibleSdkVersion`；扫描终点取 `plan.targets.os.version`，未配置时取当前 target。分析阶段保持业务源码与 SDK 版本配置不变。
+- 行为扫描：从原 target 扫到上述终点；target 未提高时跳过。
+- 废弃扫描：OS 版本不变时仍执行，使用 `--from "5.0.0(12) Release"`、`--to "<扫描终点版本>"`；区间满足 `from < to`，版本限制写入 PRD。
+- 显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`，保留原始 CSV、扫描 JSON、coverage、diagnostics 和调用日志，按实际返回路径读取。
+- 逐项读取完整官方变更章节，核对 target 生效门槛、运行系统支持条件及返回值、回调和行为的消费方，将实际影响与适配建议写入 PRD；资料不明确时使用 `harmonyos-knowledge`。
+
+本阶段交付扫描证据与 PRD；修复、测试、构建、逐项处理结果表和升级报告在编码阶段完成。
+
+`plan.targets.os` 存在时，结合官方资料和当前源码补充权限声明与申请、ArkTS 编译检查、系统 UX 和无障碍变化的影响及适配建议，统一归入 OS / API 升级影响。
+
 ## 输出 PRD
 
 生成 PRD 时，从上游新版的公开 Flutter API 和用户可见能力整理功能全集，使用 `F-01`、`F-02`、`F-03` 顺序编号。`F-xx` 表示功能能力，不表示代码 diff 条目；diff 只用于判断该功能本次是新增、修改、删除还是无变化。
 
 代码组织、文档注释、代码风格、Dart 语法写法、版本号、依赖约束、构建脚本、其他平台内部实现等变化，不单独作为 `F-xx`。如果这些变化影响 Flutter 对外 API、Channel 协议或用户可见行为，归入对应功能项说明；如果只影响代码同步或编译配置，写入差异摘要或依赖与配置变化。
 
-若 `.ohos-adaptation/01-analysis-prd.md` 已存在，先读取并在原文基础上增量更新本次升级内容，保留仍有效的章节和功能项。
+若 `.ohos-adaptation/01-analysis-prd.md` 已存在，先读取并在原文基础上增量更新本次升级内容，保留仍有效的内容和功能项。
 
 写入 `.ohos-adaptation/01-analysis-prd.md`，使用中文，结构保持简洁：
 
@@ -97,6 +115,16 @@ Android / iOS / Web / Desktop 等平台实现可选阅读，作为理解上游
 - Native / FFI 变化：...
 - 其他变化：...
 
+## OS / API 升级影响
+- 原 target / compatible、扫描终点、SDK、product/模块范围与结果文件引用。
+- 行为变更与废弃 API 分别记录命中数、覆盖情况；未执行或失败说明原因。
+- 统一列出扫描命中及补充检查发现的影响，同一 API / 变更项合并，标明来源。
+- 逐项给出适配建议：需要修复（修复方向）、无需处理（原因）、待确认（缺失依据与验证方法）。
+
+| 来源 | API / 变更项 | 代码位置 | 适配建议 |
+|---|---|---|---|
+| 行为扫描 / 废弃扫描 / 补充检查 | ... | ... | 需要修复 / 无需处理 / 待确认，简述影响与处理方向或原因 |
+
 ## 功能列表
 通过阅读新版本仓库 Flutter 代码，总结新版功能列表，使用 `F-01`、`F-02`、`F-03` 顺序编号。这里列的是 Flutter 公开 API / 用户可见能力清单，而不是 diff 修改点清单。每个编号对应一个功能能力。
 

package/node_modules/@hmos-library-adapter/executer/shared/flutter/prompts/upgrade/upgrade-02-coding.md

@@ -21,7 +21,7 @@
 
 `<upstream_dir>` 用来查看上游新版源码和差异；当前目录用来落地升级代码。PRD 是参考，实际更新以本阶段重新执行的 diff、源码阅读和当前 OHOS 适配结构为准；PRD 漏掉但源码差异明确影响升级结果的内容，也要一并处理并写入报告。
 
-以 PRD 功能列表的“本次变化”为代码修改边界。标记为“无变化”的功能，其现有实现、Example 入口和已有测试代码必须保持原样，禁止重构、格式化或顺带修复；只为新增、修改、删除功能及其必要共享配置编写代码。本规则优先于前述 diff 补漏。
+以 PRD 的“本次变化”及本轮升级必需的 OS/框架兼容修复为修改边界。PRD 标为“无变化”的功能如经源码和官方依据确认受本轮升级影响，连同受影响的调用方一起修复，增量补入 PRD，并按现有测试结构补充测试；其余未受影响的实现、Example 入口和已有测试保持原样。已有本地改动在保留原意的基础上完成必要兼容修复。
 
 ## 获取差异清单
 
@@ -64,7 +64,7 @@ Android / iOS / Web / Desktop 等平台实现可选阅读，作为理解上游
 
 ## 使用目标版本配置
 
-修改配置前，记录宿主所选 product 的原 `targetSdkVersion`（缺失时取 `compatibleSdkVersion`），作为行为变更扫描基线。
+行为变更扫描基线沿用 PRD 记录的原 target（缺失时取 compatible）；PRD 未记录时，在修改配置前读取所选 product 的当前配置并补入 PRD。
 
 按 `plan.targets` 中的目标版本更新配置：
 
@@ -73,17 +73,20 @@ Android / iOS / Web / Desktop 等平台实现可选阅读，作为理解上游
 - `plan.targets.os` 存在时，将其 `version` 写入 `example/ohos/build-profile.json5` 的 `targetSdkVersion`，保留表示最低兼容版本的 `compatibleSdkVersion`。`runtimeOS` 保持为 `HarmonyOS`。
 - `plan.targets.os` 不存在且由于 SDK 版本兼容导致编译失败时，检查本机实际安装的 HarmonyOS SDK 版本，以本机已安装版本作为构建目标，可以相应修改 `targetSdkVersion` 等字段；`compatibleSdkVersion` 继续表示最低兼容版本。`runtimeOS` 保持为 `HarmonyOS`。
 
-## 扫描 HarmonyOS API 变更
+## API 变更适配与复扫
 
-编写 OHOS 实现前，调用 `harmonyos-api-upgrade-adapter` Skill，按其 `references/common/workflow-scan.md` 分别执行行为变更（`upgrade`）和废弃 API（`deprecated`）扫描。OS 版本不变时仍执行废弃扫描。
+编写 OHOS 实现前，读取 PRD 中的扫描基线、影响分析和结果文件引用，复用 `.ohos-adaptation/upgrade/` 下的首次扫描结果。结果缺失、失败或源码、SDK、product/模块范围、目标版本已变化时，按分析阶段的扫描方式补扫；使用 `harmonyos-api-upgrade-adapter` Skill 的 scanner，流程与交付以本节为准。
 
-通常以 `example/ohos/` 为宿主，将实际插件 HAR（通常在 `ohos/`）按真实路径注册到宿主 `modules`，使用实际 product 与 HAR 模块名限定范围；联合插件逐个覆盖实际升级子包。Example 含本次涉及的自定义 ArkTS 时，另扫对应应用模块。
+- 逐项读取完整官方变更章节，分别核对 target 生效门槛与运行系统支持条件，追踪返回值、回调和行为的消费方，按实际影响修复。资料不明确时使用 `harmonyos-knowledge`。
+- 按 Skill 的结果列定义与格式化接口，将逐项处理结果 CSV 保存到扫描器返回的结果表路径，保留原始行序、重复记录和 `Fixed`。行为表追加“处理结论、处理说明、后续事项”三列；废弃表记录兼容性、变更文件和验证证据，逐项说明实际修改或未处理原因。
+- 修复及构建完成后，以最终代码、SDK、product/模块范围复扫。行为扫描仍从 PRD 的原 target 扫到最终 target，target 未提高时跳过；废弃扫描从 `5.0.0(12) Release` 扫到最终 target，OS 版本不变时仍执行。处理新增命中后重新构建和复扫。
+- 补扫与复扫仍显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`；首次扫描与复扫批次分别保留，失败或覆盖缺口写入阶段报告。
 
-显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`，按 scanner 返回路径读取结果并核对适用项，后续修改、构建与报告沿用本阶段流程。
+修复、测试、构建与复扫沿用本阶段；API 适配交付为扫描证据、逐项结果表和 `.ohos-adaptation/02-upgrade-coding-report.md`。Skill 自带的独立审批、`spec.md`、`progress.json`、`groups/`、`api-adapt-report.md` 和独立设备报告留给独立任务。
 
 ## 编写 OHOS 升级实现
 
-如果 diff 确认上游只修改了 Android / iOS / Web / Desktop 等平台内部实现，Flutter 对外 API、Dart 行为、平台通道协议、Native / FFI 接口和 Example 调用方式都没有变化，则无需修改 OHOS 适配代码；写入报告说明已同步或已参考的平台变更范围，以及判断 OHOS 无需改动的依据。
+如果 diff 确认上游只修改了 Android / iOS / Web / Desktop 等平台内部实现，Flutter 对外 API、Dart 行为、平台通道协议、Native / FFI 接口和 Example 调用方式都没有变化，且本轮 OS / 框架兼容检查无待修项，则无需修改 OHOS 适配代码；写入报告说明已同步或已参考的平台变更范围，以及判断 OHOS 无需改动的依据。
 
 基于本阶段 diff 和源码判断，补齐 Dart、OHOS、Native/FFI 和 Example 中需要升级的内容：
 
@@ -124,8 +127,19 @@ Android / iOS / Web / Desktop 等平台实现可选阅读，作为理解上游
 
 - 本次实际分析和同步的 diff 范围。
 - 升级点实现情况，按 PRD 中的 `F-xx` 对应说明。
+- OS / API 适配结果，统一按下方格式记录。
 - Example 覆盖情况。
 - 依赖安装与构建结果。
 - 本次提交的 commit sha。
-- 行为变更与废弃 API 扫描结果分别说明：版本、SDK、product/模块范围、`.ohos-adaptation/upgrade/` 下的批次路径、覆盖情况、命中/修复/剩余项及复扫结果；未执行或失败注明原因。
 - 仍未完全对齐的项目、原因、影响范围和后续建议。
+
+```markdown
+## OS / API 适配结果
+- 原 target / compatible 与最终 target、SDK、product/模块范围与结果文件引用。
+- 行为变更与废弃 API 分别列出首次命中数、复扫剩余数和覆盖情况；未执行或失败说明原因。
+- 汇总首次扫描、复扫新增及补充检查项，同一 API / 变更项合并，逐项列出本次修改文件与方式，或无需修改、待处理的原因。
+
+| 来源 | API / 变更项 | 代码位置 | 本次修改 | 处理结论与原因 | 验证依据 |
+|---|---|---|---|---|---|
+| 行为扫描 / 废弃扫描 / 补充检查 | ... | ... | 修改文件与方式 / 无修改 | 已修复 / 无需修改 / 待处理，附原因 | 构建 / 测试 / 复扫证据 |
+```

package/node_modules/@hmos-library-adapter/executer/shared/rn/prompts/upgrade/CLAUDE.md

@@ -22,7 +22,7 @@
 - **`rn-ohos-template`**：静态模板 + 确定性 CLI `rnohos.py`。**开工先读它的 SKILL.md 与 `lessons/index.json`**，按 `plugin_type`+`stage` 命中 category 后读对应分片。
 - **`rn-docs-lookup`**：RN for OpenHarmony 开发文档（TurboModule、Fabric、Codegen、Autolinking、两端通讯、FAQ）。
 - **`rn-adapted-library`**：查 RN 或原生依赖是否已有鸿蒙适配版（已适配的直接复用 OHOS 包，不重复造）。
-- **`harmonyos-api-upgrade-adapter`**：按 `references/common/workflow-scan.md` 调用 scanner，扫描 HAR 及宿主的行为变更与废弃 API，后续处理沿用本流水线。
+- **`harmonyos-api-upgrade-adapter`**：提供 HAR 及宿主的 API 行为变更、废弃 API 扫描器、官方依据和结果格式。
 - **`arkts-rules`**：编写或修改 `.ets` 时确保 ArkTS 合规可编译。
 - **`harmonyos-knowledge`**：查询 HarmonyOS API 签名、枚举、权限、Kit 用法与 React Native / RNOH 适配知识。
 

package/node_modules/@hmos-library-adapter/executer/shared/rn/prompts/upgrade/upgrade-01-analysis.md

@@ -33,7 +33,7 @@
 
 ## 差异分析范围
 
-`plan.targets.thirdParty` 存在时，对比 `<upstream_dir>` 与当前目录，重点识别库本身对外接口、JS/TS 层行为和原生桥接契约的变化，比如：
+`plan.targets.thirdParty` 不存在时，跳过上游差异分析（含 `git diff --no-index`）和代码同步。存在时，对比 `<upstream_dir>` 与当前目录，重点识别库本身对外接口、JS/TS 层行为和原生桥接契约的变化，比如：
 
 - JS/TS API 与实现：`src/`、`index.ts(x)`、公开导出入口、`package.json`（`version`、`react-native`、`codegenConfig`）。
 - Spec 与桥接协议：`src/` 下的 `*Spec.ts` / `*Spec.tsx`、`TurboModuleRegistry.get` 的模块名、`codegenNativeComponent` 的组件名、方法名、事件名、参数结构、返回结构、常量。
@@ -56,9 +56,27 @@ Git diff 使用方式：
   ```
 - 对需要分析的文件读取源码，回到源码确认行为语义，避免只根据文件名判断。
 
+## OS / API 升级影响分析
+
+使用 `harmonyos-api-upgrade-adapter` Skill 提供的 scanner 对当前源码执行行为变更（`upgrade`）和废弃 API（`deprecated`）扫描，作为 PRD 的分析依据；API 适配的流程与交付以本流水线为准。
+
+根据现有结构定位真实宿主（通常为 `example/harmony/`，`ohos/` 布局使用其中实际宿主）与插件 HAR，将 HAR 按真实路径注册到宿主 `modules`，使用实际 product 与 HAR 模块名限定范围。Example 含本次涉及的自定义 ETS/TS 时，另扫对应应用模块。
+
+使用 Node.js ≥20、本机 DevEco Studio 和覆盖目标版本的 SDK，扫描器入口和参数以实际 help 为准。`--project` 指向宿主工程根，指定实际 product 和 SDK；HAR 范围使用 `--project-type har --scan-module "<模块名>"`，应用范围使用 `--project-type app --scan-module "<模块名>"`。
+
+- 在 PRD 中记录所选 product 的原 `targetSdkVersion`（缺失时取 `compatibleSdkVersion`）和 `compatibleSdkVersion`；扫描终点取 `plan.targets.os.version`，未配置时取当前 target。分析阶段保持业务源码与 SDK 版本配置不变。
+- 行为扫描：从原 target 扫到上述终点；target 未提高时跳过。
+- 废弃扫描：OS 版本不变时仍执行，使用 `--from "5.0.0(12) Release"`、`--to "<扫描终点版本>"`；区间满足 `from < to`，版本限制写入 PRD。
+- 显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`，保留原始 CSV、扫描 JSON、coverage、diagnostics 和调用日志，按实际返回路径读取。
+- 逐项读取完整官方变更章节，核对 target 生效门槛、运行系统支持条件及返回值、回调和行为的消费方，将实际影响与适配建议写入 PRD；资料不明确时使用 `harmonyos-knowledge`。
+
+本阶段交付扫描证据与 PRD；修复、测试、构建、逐项处理结果表和升级报告在编码阶段完成。
+
+`plan.targets.os` 存在时，结合官方资料和当前源码补充权限声明与申请、ArkTS 编译检查、系统 UX 和无障碍变化的影响及适配建议，统一归入 OS / API 升级影响。
+
 ## 输出报告
 
-若 `.ohos-adaptation/01-analysis-prd.md` 已存在，先读取并在原文基础上增量更新本次升级内容，保留仍有效的章节和功能项。
+若 `.ohos-adaptation/01-analysis-prd.md` 已存在，先读取并在原文基础上增量更新本次升级内容，保留仍有效的内容和功能项。
 
 写入 `.ohos-adaptation/01-analysis-prd.md`，使用中文，结构如下：
 
@@ -82,17 +100,27 @@ Git diff 使用方式：
 - Native / C++ 变化：...
 - 其他变化：...
 
-## 3. 功能列表
+## 3. OS / API 升级影响
+- 原 target / compatible、扫描终点、SDK、product/模块范围与结果文件引用。
+- 行为变更与废弃 API 分别记录命中数、覆盖情况；未执行或失败说明原因。
+- 统一列出扫描命中及补充检查发现的影响，同一 API / 变更项合并，标明来源。
+- 逐项给出适配建议：需要修复（修复方向）、无需处理（原因）、待确认（缺失依据与验证方法）。
+
+| 来源 | API / 变更项 | 代码位置 | 适配建议 |
+|---|---|---|---|
+| 行为扫描 / 废弃扫描 / 补充检查 | ... | ... | 需要修复 / 无需处理 / 待确认，简述影响与处理方向或原因 |
+
+## 4. 功能列表
 通过阅读新版本仓库 JS/TS 与 Spec 代码，总结新版功能列表，使用 `F-01`、`F-02`、`F-03` 顺序编号。这里列的是 RN 公开 API / 用户可见能力清单，而不是 diff 修改点清单。每个编号对应一个功能能力。
 
 | 编号 | 功能项 / RN API | 本次变化概述 |
 |---|---|---|
 | F-01 | ... | 新增、修改、删除... / 无变化 |
 
-## 4. 升级任务
+## 5. 升级任务
 简要介绍 HarmonyOS 侧为了适配本次 RN API / 能力变化大致需要做的动作，例如修改 OHOS 侧 TurboModule / Fabric 实现、是否需重跑 codegen、RNPackage 注册、权限映射、Example 展示等等。Android / iOS 平台代码如何同步不在这里展开；具体需要调用哪些 HarmonyOS API 实现也不展开。
 
-## 5. 风险点
+## 6. 风险点
 可选。如有风险，列出 API / Spec 兼容性、旧架构迁移、跨边界名称一致性、平台能力差异、权限、Native/C++、事件与回调、数据类型、构建环境等风险。
 ```
 

package/node_modules/@hmos-library-adapter/executer/shared/rn/prompts/upgrade/upgrade-02-coding.md

@@ -16,7 +16,7 @@
 
 PRD 作为参考清单。实际代码如何更新，以本阶段执行的 `git diff`、源码阅读和当前 OHOS 适配结构为准；PRD 漏掉但源码差异明确影响升级结果的内容，补入报告并一并处理。
 
-以 PRD 功能列表的“本次变化”为代码修改边界。标记为“无变化”的功能，其现有实现、Example 入口和已有测试代码必须保持原样，禁止重构、格式化或顺带修复；只为新增、修改、删除功能及其必要共享配置编写代码。本规则优先于前述 diff 补漏。
+以 PRD 的“本次变化”及本轮升级必需的 OS/框架兼容修复为修改边界。PRD 标为“无变化”的功能如经源码和官方依据确认受本轮升级影响，连同受影响的调用方一起修复，增量补入 PRD，并按现有测试结构补充测试；其余未受影响的实现、Example 入口和已有测试保持原样。已有本地改动在保留原意的基础上完成必要兼容修复。
 
 ## 编码步骤
 
@@ -48,7 +48,7 @@ Git diff 使用方式：
 
 ### 2. 使用目标版本配置
 
-修改配置前，记录宿主所选 product 的原 `targetSdkVersion`（缺失时取 `compatibleSdkVersion`），作为行为变更扫描基线。
+行为变更扫描基线沿用 PRD 记录的原 target（缺失时取 compatible）；PRD 未记录时，在修改配置前读取所选 product 的当前配置并补入 PRD。
 
 按 `plan.targets` 中的目标版本更新配置：
 
@@ -66,13 +66,16 @@ Git diff 使用方式：
 - 出现冲突时先解决冲突，再继续更新 OHOS 实现、Example 和构建验证。
 - 根 `package.json` 及实际升级子包的版本同步到 `plan.targets.thirdParty.version`。
 
-### 扫描 HarmonyOS API 变更
+### API 变更适配与复扫
 
-编写 OHOS 实现前，调用 `harmonyos-api-upgrade-adapter` Skill，按其 `references/common/workflow-scan.md` 分别执行行为变更（`upgrade`）和废弃 API（`deprecated`）扫描。OS 版本不变时仍执行废弃扫描。
+编写 OHOS 实现前，读取 PRD 中的扫描基线、影响分析和结果文件引用，复用 `.ohos-adaptation/upgrade/` 下的首次扫描结果。结果缺失、失败或源码、SDK、product/模块范围、目标版本已变化时，按分析阶段的扫描方式补扫；使用 `harmonyos-api-upgrade-adapter` Skill 的 scanner，流程与交付以本节为准。
 
-根据现有结构定位真实宿主（通常为 `example/harmony/`，`ohos/` 布局使用其中实际宿主）与插件 HAR，将 HAR 按真实路径注册到宿主 `modules`，使用实际 product 与 HAR 模块名限定范围。Example 含本次涉及的自定义 ETS/TS 时，另扫对应应用模块。
+- 逐项读取完整官方变更章节，分别核对 target 生效门槛与运行系统支持条件，追踪返回值、回调和行为的消费方，按实际影响修复。资料不明确时使用 `harmonyos-knowledge`。
+- 按 Skill 的结果列定义与格式化接口，将逐项处理结果 CSV 保存到扫描器返回的结果表路径，保留原始行序、重复记录和 `Fixed`。行为表追加“处理结论、处理说明、后续事项”三列；废弃表记录兼容性、变更文件和验证证据，逐项说明实际修改或未处理原因。
+- 修复及构建完成后，以最终代码、SDK、product/模块范围复扫。行为扫描仍从 PRD 的原 target 扫到最终 target，target 未提高时跳过；废弃扫描从 `5.0.0(12) Release` 扫到最终 target，OS 版本不变时仍执行。处理新增命中后重新构建和复扫。
+- 补扫与复扫仍显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`；首次扫描与复扫批次分别保留，失败或覆盖缺口写入阶段报告。
 
-显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`，按 scanner 返回路径读取结果并核对适用项，后续修改、构建与报告沿用本阶段流程。
+修复、测试、构建与复扫沿用本阶段；API 适配交付为扫描证据、逐项结果表和 `.ohos-adaptation/02-upgrade-coding-report.md`。Skill 自带的独立审批、`spec.md`、`progress.json`、`groups/`、`api-adapt-report.md` 和独立设备报告留给独立任务。
 
 ### 4. 编写升级功能
 
@@ -239,7 +242,18 @@ Set-Location $dst
 - 实际识别到的 library module、demo/app、HarmonyOS 工程路径，以及使用的构建命令。
 - 若启用了短路径构建，说明短物理目录。
 - 目标版本落地情况与是否重跑 codegen（Spec 是否变化）。
-- 行为变更与废弃 API 扫描分别记录版本、SDK、product/模块范围、`.ohos-adaptation/upgrade/` 下的批次路径、覆盖情况、命中/修复/剩余项及复扫结果；未执行或失败注明原因。
+- OS / API 适配结果，统一按下方格式记录。
 - 升级点的实现。
 - 依赖安装与构建结果：明确写**构建状态（通过 / 未构建 / 失败）**；通过则附本次产出的 HAR/HAP 相对路径；未构建或失败写清执行到哪一步、可确认的构建错误或缺失环境。
 - 如有仍未完全对齐的项目，写明对应 `F-xxx`、原因、影响范围和后续建议。
+
+```markdown
+## OS / API 适配结果
+- 原 target / compatible 与最终 target、SDK、product/模块范围与结果文件引用。
+- 行为变更与废弃 API 分别列出首次命中数、复扫剩余数和覆盖情况；未执行或失败说明原因。
+- 汇总首次扫描、复扫新增及补充检查项，同一 API / 变更项合并，逐项列出本次修改文件与方式，或无需修改、待处理的原因。
+
+| 来源 | API / 变更项 | 代码位置 | 本次修改 | 处理结论与原因 | 验证依据 |
+|---|---|---|---|---|---|
+| 行为扫描 / 废弃扫描 / 补充检查 | ... | ... | 修改文件与方式 / 无修改 | 已修复 / 无需修改 / 待处理，附原因 | 构建 / 测试 / 复扫证据 |
+```

package/node_modules/@hmos-library-adapter/executer/shared/sdk/prompts/upgrade/CLAUDE.md

@@ -15,7 +15,7 @@
 - **`native-library-substitution`**：Android SDK 依赖原生三方库或需要查找 ohpm 替代方案时使用。
 - **`ohos-native-cross-compile`**：库包含较多 C/C++ 源码，并需要交叉编译为 HarmonyOS `arm64-v8a` 预编译 `.so` 时使用。
 - **`hardemo-template`**：创建或修复根 `ohos_library` HAR 和 `ohos_hardemo` app 时使用。
-- **`harmonyos-api-upgrade-adapter`**：按 `references/common/workflow-scan.md` 调用 scanner，扫描 HAR 及宿主的行为变更与废弃 API，后续处理沿用本流水线。
+- **`harmonyos-api-upgrade-adapter`**：提供 HAR 及宿主的 API 行为变更、废弃 API 扫描器、官方依据和结果格式。
 - **`arkts-rules`**：编写或修改 `.ets` 时确保 ArkTS 合规可编译。
 - **`harmonyos-knowledge`**：查询 HarmonyOS API 签名、枚举、权限、Kit 用法与 SDK 适配知识。
 

package/node_modules/@hmos-library-adapter/executer/shared/sdk/prompts/upgrade/upgrade-01-analysis.md

@@ -54,7 +54,7 @@ CLAUDE.md
 
 ## 获取差异清单
 
-先获取差异文件清单，再按目录分组读取具体差异和源码。
+`plan.targets.thirdParty` 存在时，先获取差异文件清单，再按目录分组读取具体差异和源码；不存在时跳过上游差异分析（含 `git diff --no-index`）和代码同步。
 
 - Windows PowerShell：
   ```powershell
@@ -82,18 +82,23 @@ CLAUDE.md
 
 当前目录中的 `ohos_library/` 和 `ohos_hardemo/` 作为当前 HarmonyOS 适配现状读取。
 
-## OS 版本升级影响分析
+## OS / API 升级影响分析
 
-如果 manifest 中指定了目标 HarmonyOS OS Version，需要分析该版本升级对当前适配代码的影响：
+使用 `harmonyos-api-upgrade-adapter` Skill 提供的 scanner 对当前源码执行行为变更（`upgrade`）和废弃 API（`deprecated`）扫描，作为 PRD 的分析依据；API 适配的流程与交付以本流水线为准。
 
-1. **废弃 API**：目标版本中标记为 deprecated 或已移除的 API，检查 `ohos_library/` 和 `ohos_hardemo/` 中是否使用了这些 API，列出受影响的功能和替换方案。
-2. **行为变更**：目标版本中 API 行为发生变化（如默认值、回调时机、错误码、线程模型），列出受影响的实现和适配要点。
-3. **权限模型变更**：目标版本中权限声明方式或运行时权限流程发生变化，列出需要修改的 `module.json5` 和动态申请逻辑。
-4. **编译检查规则**：目标版本中 ArkTS 编译器新增的严格检查或类型约束，列出可能触发编译错误的现有代码。
-5. **系统级 UX 行为变更**：目标版本中系统对沉浸式、返回手势、权限弹窗、组件默认动效/样式的行为变化，列出 Demo 可能受影响的 UI 表现。
-6. **无障碍框架变更**：目标版本中无障碍属性或辅助功能 API 的变化，列出需要补齐或修改的属性。
+通常以 `ohos_hardemo/`（或现有 `ohos-hardemo/`）为宿主，将实际 HAR（通常在 `ohos_library/`）按真实路径注册到宿主 `modules`，使用实际 product 与 HAR 模块名限定范围。Demo 含本次涉及的自定义 ArkTS 时，另扫对应应用模块。
 
-如果未指定目标 OS Version，本节写"未指定目标 OS 版本，跳过 OS 版本升级影响分析"。
+使用 Node.js ≥20、本机 DevEco Studio 和覆盖目标版本的 SDK，扫描器入口和参数以实际 help 为准。`--project` 指向宿主工程根，指定实际 product 和 SDK；HAR 范围使用 `--project-type har --scan-module "<模块名>"`，应用范围使用 `--project-type app --scan-module "<模块名>"`。
+
+- 在 PRD 中记录所选 product 的原 `targetSdkVersion`（缺失时取 `compatibleSdkVersion`）和 `compatibleSdkVersion`；扫描终点取 `plan.targets.os.version`，未配置时取当前 target。分析阶段保持业务源码与 SDK 版本配置不变。
+- 行为扫描：从原 target 扫到上述终点；target 未提高时跳过。
+- 废弃扫描：OS 版本不变时仍执行，使用 `--from "5.0.0(12) Release"`、`--to "<扫描终点版本>"`；区间满足 `from < to`，版本限制写入 PRD。
+- 显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`，保留原始 CSV、扫描 JSON、coverage、diagnostics 和调用日志，按实际返回路径读取。
+- 逐项读取完整官方变更章节，核对 target 生效门槛、运行系统支持条件及返回值、回调和行为的消费方，将实际影响与适配建议写入 PRD；资料不明确时使用 `harmonyos-knowledge`。
+
+本阶段交付扫描证据与 PRD；修复、测试、构建、逐项处理结果表和升级报告在编码阶段完成。
+
+`plan.targets.os` 存在时，结合官方资料和当前源码补充权限声明与申请、ArkTS 编译检查、系统 UX 和无障碍变化的影响及适配建议，统一归入 OS / API 升级影响。
 
 ## 输出 PRD
 
@@ -101,7 +106,7 @@ CLAUDE.md
 
 文档注释、代码风格、构建脚本、内部实现细节不单独作为 `F-xx`。如果这些变化影响 SDK 对外 API 或用户可见行为，归入对应功能项说明；如果只影响代码同步或编译配置，写入差异摘要。
 
-若 `.ohos-adaptation/01-analysis-prd.md` 已存在，先读取并在原文基础上增量更新本次升级内容，保留仍有效的章节和功能项。
+若 `.ohos-adaptation/01-analysis-prd.md` 已存在，先读取并在原文基础上增量更新本次升级内容，保留仍有效的内容和功能项。
 
 写入 `.ohos-adaptation/01-analysis-prd.md`，使用中文，结构保持简洁：
 
@@ -122,17 +127,15 @@ CLAUDE.md
 - Demo / Sample 变化：...
 - 其他变化：...
 
-## OS 版本升级影响
-逐项列出 6 项影响分析结果。未指定目标 OS 版本时写"未指定目标 OS 版本，跳过"。
+## OS / API 升级影响
+- 原 target / compatible、扫描终点、SDK、product/模块范围与结果文件引用。
+- 行为变更与废弃 API 分别记录命中数、覆盖情况；未执行或失败说明原因。
+- 统一列出扫描命中及补充检查发现的影响，同一 API / 变更项合并，标明来源。
+- 逐项给出适配建议：需要修复（修复方向）、无需处理（原因）、待确认（缺失依据与验证方法）。
 
-| 类别 | 影响描述 | 受影响功能/代码 | 适配要点 |
+| 来源 | API / 变更项 | 代码位置 | 适配建议 |
 |---|---|---|---|
-| 废弃 API | ... | ... | ... |
-| 行为变更 | ... | ... | ... |
-| 权限模型变更 | ... | ... | ... |
-| 编译检查规则 | ... | ... | ... |
-| 系统级 UX 行为变更 | ... | ... | ... |
-| 无障碍框架变更 | ... | ... | ... |
+| 行为扫描 / 废弃扫描 / 补充检查 | ... | ... | 需要修复 / 无需处理 / 待确认，简述影响与处理方向或原因 |
 
 ## 功能列表
 通过阅读新版本 Android SDK 源码，总结新版功能列表，使用 `F-01`、`F-02`、`F-03` 顺序编号。这里列的是 SDK 公开能力清单（按能力域整理），而不是 diff 修改点清单。每个编号对应一个功能能力域。

package/node_modules/@hmos-library-adapter/executer/shared/sdk/prompts/upgrade/upgrade-02-coding.md

@@ -21,7 +21,7 @@
 
 `<upstream_dir>` 用来查看上游新版源码和差异；当前目录用来落地升级代码。PRD 是参考，实际更新以本阶段重新执行的 diff、源码阅读和当前 OHOS 适配结构为准；PRD 漏掉但源码差异明确影响升级结果的内容，也要一并处理并写入报告。
 
-以 PRD 功能列表的“本次变化”为代码修改边界。标记为“无变化”的功能，其现有实现、Demo 入口和已有测试代码必须保持原样，禁止重构、格式化或顺带修复；只为新增、修改、删除功能及其必要共享配置编写代码。本规则优先于前述 diff 补漏。
+以 PRD 的“本次变化”及本轮升级必需的 OS/API 兼容修复为修改边界。PRD 标为“无变化”的功能如经源码和官方依据确认受本轮升级影响，连同受影响的调用方一起修复，增量补入 PRD，并按现有测试结构补充测试；其余未受影响的实现、Demo 入口和已有测试保持原样。已有本地改动在保留原意的基础上完成必要兼容修复。
 
 ## 获取差异清单
 
@@ -63,13 +63,13 @@
 
 ## 使用目标版本配置
 
-修改配置前，记录宿主所选 product 的原 `targetSdkVersion`（缺失时取 `compatibleSdkVersion`），作为行为变更扫描基线。
+行为变更扫描基线沿用 PRD 记录的原 target（缺失时取 compatible）；PRD 未记录时，在修改配置前读取所选 product 的当前配置并补入 PRD。
 
 `plan.targets.os` 存在时，读取其 `version` 作为目标 HarmonyOS OS Version 并用于本次升级；不存在时保持 SDK 配置不变：
 
 - 更新 `ohos_hardemo/build-profile.json5` 中的 `targetSdkVersion` 为目标 OS 版本，保留 `compatibleSdkVersion` 不变。若不存在 `targetSdkVersion` 则忽略。
 - 检查 `ohos_library/oh-package.json5` 和 `ohos_hardemo/oh-package.json5` 中 `@ohos/` 依赖的版本约束，若与目标 OS 版本不兼容则更新。
-- 根据 PRD 中 OS 版本升级影响逐项修复：
+- 根据 PRD 中“OS / API 升级影响”逐项修复：
   - **废弃 API** → 查找替换方案并更新实现
   - **行为变更** → 适配新的 API 行为（默认值、回调时机、错误码等）
   - **权限模型变更** → 更新 `module.json5` 声明和动态申请逻辑
@@ -79,13 +79,16 @@
 - 若 `ohos_hardemo/` 不存在，使用 `hardemo-template` Skill 创建工程结构。
 - `plan.targets.os` 不存在且由于 SDK 版本兼容导致编译失败时，检查本机实际安装的 HarmonyOS SDK 版本，以本机已安装版本作为构建目标，可以相应修改 `targetSdkVersion` 等字段；`compatibleSdkVersion` 继续表示最低兼容版本。`runtimeOS` 保持为 `HarmonyOS`。
 
-## 扫描 HarmonyOS API 变更
+## API 变更适配与复扫
 
-编写 OHOS 实现前，调用 `harmonyos-api-upgrade-adapter` Skill，按其 `references/common/workflow-scan.md` 分别执行行为变更（`upgrade`）和废弃 API（`deprecated`）扫描。OS 版本不变时仍执行废弃扫描。
+编写 OHOS 实现前，读取 PRD 中的扫描基线、影响分析和结果文件引用，复用 `.ohos-adaptation/upgrade/` 下的首次扫描结果。结果缺失、失败或源码、SDK、product/模块范围、目标版本已变化时，按分析阶段的扫描方式补扫；使用 `harmonyos-api-upgrade-adapter` Skill 的 scanner，流程与交付以本节为准。
 
-通常以 `ohos_hardemo/`（或现有 `ohos-hardemo/`）为宿主，将实际 HAR（通常在 `ohos_library/`）按真实路径注册到宿主 `modules`，使用实际 product 与 HAR 模块名限定范围。Demo 含本次涉及的自定义 ArkTS 时，另扫对应应用模块。
+- 逐项读取完整官方变更章节，分别核对 target 生效门槛与运行系统支持条件，追踪返回值、回调和行为的消费方，按实际影响修复。资料不明确时使用 `harmonyos-knowledge`。
+- 按 Skill 的结果列定义与格式化接口，将逐项处理结果 CSV 保存到扫描器返回的结果表路径，保留原始行序、重复记录和 `Fixed`。行为表追加“处理结论、处理说明、后续事项”三列；废弃表记录兼容性、变更文件和验证证据，逐项说明实际修改或未处理原因。
+- 修复及构建完成后，以最终代码、SDK、product/模块范围复扫。行为扫描仍从 PRD 的原 target 扫到最终 target，target 未提高时跳过；废弃扫描从 `5.0.0(12) Release` 扫到最终 target，OS 版本不变时仍执行。处理新增命中后重新构建和复扫。
+- 补扫与复扫仍显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`；首次扫描与复扫批次分别保留，失败或覆盖缺口写入阶段报告。
 
-显式传入 `--output-dir "<当前仓库绝对路径>/.ohos-adaptation/upgrade"`，按 scanner 返回路径读取结果并核对适用项，后续修改、构建与报告沿用本阶段流程。
+修复、测试、构建与复扫沿用本阶段；API 适配交付为扫描证据、逐项结果表和 `.ohos-adaptation/02-upgrade-coding-report.md`。Skill 自带的独立审批、`spec.md`、`progress.json`、`groups/`、`api-adapt-report.md` 和独立设备报告留给独立任务。
 
 ## 编写 OHOS 升级实现
 
@@ -106,7 +109,7 @@
 
 检查 `ohos_hardemo/entry/` 的 Demo 是否能覆盖本次新增或修改功能：
 
-- 仅对上游**新增或修改**的 Demo 页面/组件使用 `android-to-harmonyos-ui-mapping` Skill 进行映射作为参考，以当前 `ohos_hardemo/entry/` 的实际结构为主，未变化部分保持不变。
+- 对本次上游变更或 OS 兼容修复涉及的 Demo 页面/组件，使用 `android-to-harmonyos-ui-mapping` Skill 进行映射作为参考，以当前 `ohos_hardemo/entry/` 的实际结构为主，其余未受影响部分保持原样。
 - 新增或修改功能必须在Demo中体现
 - 新增或修改的 Demo 页面/组件必须满足 UX 合规要求：边界动效、非一级界面提供返回按钮、色彩对比度达标。
 - 修改已有 UI 代码不得破坏已有合规性。
@@ -134,9 +137,19 @@
 
 - 本次实际分析和同步的 diff 范围。
 - 升级点实现情况，按 PRD 中的 `F-xx` 对应说明。
-- OS 版本适配结果：逐项列出 PRD 中 6 项影响的适配状态（已修复 / 无影响 / 待处理）。
-- UX 适配结果：列出因 OS 版本升级或上游 Demo 变化导致的 UI 修改。
+- OS / API 适配结果，统一按下方格式记录。
+- Demo 更新与功能覆盖情况。
 - 依赖安装与构建结果。
 - 本次提交的 commit sha。
-- 行为变更与废弃 API 扫描结果分别说明：版本、SDK、product/模块范围、`.ohos-adaptation/upgrade/` 下的批次路径、覆盖情况、命中/修复/剩余项及复扫结果；未执行或失败注明原因。
 - 仍未完全对齐的项目、原因、影响范围和后续建议。
+
+```markdown
+## OS / API 适配结果
+- 原 target / compatible 与最终 target、SDK、product/模块范围与结果文件引用。
+- 行为变更与废弃 API 分别列出首次命中数、复扫剩余数和覆盖情况；未执行或失败说明原因。
+- 汇总首次扫描、复扫新增及补充检查项，同一 API / 变更项合并，逐项列出本次修改文件与方式，或无需修改、待处理的原因。
+
+| 来源 | API / 变更项 | 代码位置 | 本次修改 | 处理结论与原因 | 验证依据 |
+|---|---|---|---|---|---|
+| 行为扫描 / 废弃扫描 / 补充检查 | ... | ... | 修改文件与方式 / 无修改 | 已修复 / 无需修改 / 待处理，附原因 | 构建 / 测试 / 复扫证据 |
+```

package/node_modules/@hmos-library-adapter/executer/shared/skill-map.json

@@ -24,5 +24,9 @@
       "ohos-native-cross-compile"
     ]
   },
-  "common": []
+  "common": [
+    "arkts-rules",
+    "harmonyos-api-upgrade-adapter",
+    "harmonyos-knowledge"
+  ]
 }