@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/COMPATIBILITY.md

@@ -0,0 +1,53 @@
+# 兼容性与验证范围（15.0.1）
+
+12.0起采用文档驱动。模型分别按[行为流程](references/upgrade/upgrade-workflow.md)和[废弃流程](references/deprecated/deprecated-api-adaptation.md)完成业务判断、修改与交付，独立scanner和本地SDK、Hvigor、设备工具提供事实。文档步骤、结构校验和模型评估均不构成自动语义审计证明。
+
+## 开发工具与平台
+
+| 对象 | 当前范围 | 证据与限制 |
+| --- | --- | --- |
+| Codex | Agent Skills结构兼容 | 标准frontmatter，完整复制到`.agents/skills/`；既有版本使用Codex完成两类场景，本轮完成脚本复制验证，不能推定所有模型与工程均通过。 |
+| Claude Code | Agent Skills结构兼容 | 完整复制到`.claude/skills/`；未执行该宿主中的完整适配验收。 |
+| OpenCode | Agent Skills结构兼容 | 完整复制到`.opencode/skills/`；未执行该宿主中的完整适配验收。 |
+| macOS | 本机脚本回归及既有工具证据 | 本轮完成scanner、共享基础、维护及完整复制回归；既有版本完成过隔离工程适配与真实HAP构建，本轮未新增真实工程或设备验收。 |
+| Windows 10/11 x64 | 实验支持 | 保留跨平台路径、物理身份与进程回归；本次未在真实Windows环境运行SDK、构建或设备验收，不以macOS结果代替。 |
+| Node 20/24 | 持续维护兼容 | 不使用高于Node20的必需接口，保留跨平台基础测试；当前本机执行版本和结果以发布验收记录为准。 |
+
+不恢复远端四组合CI门禁。复制安装位置及发现规则见[README](README.md)，实际工程缺工具时按[排错与继续](references/common/troubleshooting.md)记录缺口。
+
+## 能力与实际验证
+
+| 能力 | 当前状态与既有验证依据 |
+| --- | --- |
+| 行为/废弃扫描 | 保留scanner原有算法、规则、显式模式和输出字段。扫描覆盖、超时及未解析项以每次真实诊断为准；零命中不自动表示业务安全。 |
+| 行为适配 | 模型阅读官方章节、准确SDK及源码后记录方案。实测小图144×144不满足Image超过5000万解码像素的变更条件，结论为无需修改；另在业务明确要求主动降采样的隔离工程加入`autoResize(true)`，真实构建并确认修改页编入HAP。 |
+| 行为本地取材 | 当前按变更条目由agent完整读取官方章节和准确SDK/源码，全部结果汇总spec；人工初核与二次分析必读层已退役。此前四变更取材验收属于旧流程，见[历史记录](docs/verification/2026-10-27-behavior-local-sources.md)，不作为新分派契约通过证明。 |
+| 废弃迁移 | 模型核对接收者、替代声明、上下文与最低版本。代表性`promptAction.showToast`迁移已完成真实构建和同范围复扫；保留回调、异常与业务文案。 |
+| 配置及低版本 | 模型回读所选product和准确声明。API26的配置值`26.0.0`与扫描值`26.0.0(26) Release`分开处理；实际低版本设备运行仍为未执行。 |
+| 用户决策 | 行为开始时选择目标与验证方式，全部变更评估返回后确认spec及修复/测试范围；只有原包构建、签名或归档不足才阻塞相关修改，有效原包归档后的设备阻断只影响验收。废弃维持方案批准及按需单次设备验证。实际证据以本轮验收记录为准。 |
+| HAR与原生 | 保留[HAR联合验证](references/upgrade/har-upgrade.md)及[原生上下文](references/common/native-adaptation.md)步骤与scanner能力；本次未新增真实HAR宿主或原生适配构建验收。 |
+| 设备与行为对比 | 行为选择对比时修改前归档before，修复后可生成用例再依次测试before/after并写test-report；仅修改后验证不构建before。归档、业务断言、设备测试及有效比较分别报告，历史运行不继承。 |
+| 交付目录与首页 | 新扫描使用布局4，原始表和adapted-results-<批次ID>.csv直接位于upgrade/或deprecated/，内部证据仍在批次.internal；不提供旧布局读取兼容，历史CSV可普通导入新批次。报告前置配置实际/计划状态及按CSV逻辑行统计的概括；行为按rowClassifications分三类，废弃按六类处理结果。路径、后端夹具与模板契约测试不证明模型完整适配或设备验收。见[验证记录](docs/verification/2026-10-27-delivery-layout.md)。 |
+| 结果与统计 | 保留原始行对应关系，分别表达评估、修改、编译和运行；废弃另记录复扫，行为另记录所选对比。622行案例完成613位置、161物理文件、286工作单元、19变更的数据核对；覆盖检查不能证明622行均已业务适配。 |
+| 旧运行记录 | 文件保持原样，仅只读核对事实。旧成功结论不继承为新流程证明；断点继续依据当前输入、实际差异和轻量进度重新核实。 |
+| 脚本与复制分发 | platform整体迁入scripts/shared/platform，扫描与维护分组归并；安装器、旧布局读取兼容和未接入包装已移除。完整复制后从不同工作目录验证CLI、资源和后端夹具，见[验证记录](docs/verification/2026-10-28-script-reorganization.md)。 |
+
+自动适用性/语义审计、适配CLI、事务账本、自动恢复回滚、配置事务、构建调度及报告引擎已退役。过去版本的自动保障不能延续到12.0；必要业务要求已迁入文档，见[步骤迁移表](docs/step-migration.md)。
+
+13.0.1拆分的是两类流程的步骤编排与业务决策，公共知识仍按同一份路径引用。流程阅读依赖、确认/停止与部分交付场景的本轮验证见[验收记录](docs/verification/2026-10-28-independent-workflows.md)；不据此新增真实工程构建或设备通过声明。
+
+## 测试边界
+
+`npm test`保留scanner及共享基础、资料维护和真实结构边界测试；相关引擎测试、专用helpers与孤立夹具已删除。`npm run validate`检查结构、版本、知识清单、评测资源及活动阅读链接，不判断业务方案正确性。
+
+14.0.1将[API保护与告警](references/common/compatibility.md)、[target升级兼容](references/upgrade/upgrade-compatibility.md)、[HAR宿主](references/upgrade/har-upgrade.md)与[行为代码示例](references/upgrade/upgrade-examples.md)按职责组织。行为按官方边界处理跨系统差异，仍不做通用接口版本可用性匹配或复扫，也不自动提高compatible或扩大设备范围；废弃不做修改前后对比。此前14.0职责变更和验证事实见[历史验收](docs/verification/2026-10-28-workflow-scope-v14.md)。
+
+本次场景只覆盖有限样例；其他模型、真实设备、最低设备系统及不同SDK/工程仍需按任务证据逐项确认。具体保留脚本及使用者见[职责清单](docs/script-responsibilities.md)。
+
+14.0.1的材料、SDK声明核对、测试结果及未执行范围见[兼容性文档重构验证](docs/verification/2026-10-29-compatibility-doc-refactor.md)。
+
+13.0.2将Context迁移专属知识归入废弃目录，Kit样例按准确SDK重整；本轮代码检查与验证边界见[验收记录](docs/verification/2026-10-28-deprecated-reference-cleanup.md)。
+
+15.0.0将行为评估与修复分离，以spec.md作为具体修复批准依据；开始时选择验证方式，选择对比时只要求修改前归档有效原包，设备测试可在修复后依次执行。初核维护链和二次分析必读层退役。当前结构回归、隔离模型走查及未执行范围见[行为流程重构验证](docs/verification/2026-10-29-behavior-assessment-repair.md)，旧验证事实不自动延续到新契约。
+
+15.0.1扩充[常见行为案例](references/upgrade/upgrade-examples.md)，增加[漏扫排错案例](references/upgrade/scanner-missed-cases.md)，仅真实构建错误或用户明确报告相关异常时查阅，不接入扫描候选或统计。示例SDK构建、诊断反例、隔离走查和未执行范围见[本轮验证](docs/verification/2026-10-29-upgrade-case-guidance.md)。

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

@@ -0,0 +1,123 @@
+# HarmonyOS API 升级适配 Skill
+
+12.0起全面采用文档驱动。模型依照两条独立的完整流程完成行为变更或废弃API适配，scanner提供真实扫描，SDK/Hvigor/设备工具提供检查事实。适配CLI、自动语义审计、账本与恢复程序及相关测试已退出。
+
+13.0将扫描、共享基础和维护脚本统一归入scripts，platform整体迁移至scripts/shared/platform。安装改为完整目录复制，旧脚本路径和旧批次读取入口不再保留；当前交付布局仍为4。
+
+行为与废弃采用两条独立流程：[行为完整流程](references/upgrade/upgrade-workflow.md)负责 U01–U09，[废弃完整流程](references/deprecated/deprecated-api-adaptation.md)负责 D01–D11。公共知识和工具说明只维护一份，入口见[SKILL](SKILL.md)。
+
+行为按变更条目分派只读评估，一个条目一个 agent；全部返回后由主 agent 合并冲突并生成 spec.md，取得用户确认后修复。少量文件由主 agent 完成，较多时按物理文件分派，同一文件一个修改者。默认尽量保持升级前体验，按官方行为边界和真实宿主 target 分析跨系统差异，保持 compatible、不做通用接口版本可用性匹配或行为复扫。废弃维持独立流程和按需单次设备验证。
+
+## 环境依赖
+
+| 依赖 | 要求与用途 |
+| --- | --- |
+| 操作系统 | macOS 或 Windows 10/11 x64；Windows 当前为实验支持 |
+| Node.js | 20 或以上，用于执行 Skill 自带脚本 |
+| Git | 用于下载和更新完整 Skill 仓库 |
+| Agent 开发工具 | 支持 Agent Skills 且能够执行本地脚本，例如 OpenCode、Codex、Claude Code |
+| DevEco Studio | 集成扫描和构建需要本地工具链；目标 API 26 要求 26.0.0+，目标 API 24 要求 6.1.1+ |
+| HarmonyOS SDK | 已安装的编译 SDK 不低于目标 target；例如 SDK 26 可以扫描、修复并构建 target 20 工程 |
+| 模拟器或设备 | 仅在需要运行验证时准备；HAR 场景还需要宿主工程及其可安装 HAP 的签名配置 |
+
+扫描器随 Skill 完整分发，无需单独安装。已有 CSV 时可先进行证据允许的静态分析与修复；修改前按功能阅读适用的[ArkTS编码规范](references/common/arkts-coding-standards.md)；废弃迁移另读[API保护与告警](references/common/compatibility.md)，行为读取[target升级兼容](references/upgrade/upgrade-compatibility.md)，HAR追加[宿主专题](references/upgrade/har-upgrade.md)。保护API与源码注解本身也须满足compatible门槛，不因编译SDK较新直接采用。每轮源码或构建配置修改后须真实完整构建；缺工具或编译失败时仅交付部分结果并保留待办，不能宣称适配完成。复扫和运行按功能及用户授权执行。工具优先发现 `DEVECO_SDK_HOME`、`DEVECO_HOME` 和本机安装信息，发现失败后再提供明确路径。各宿主、平台和模型的实际验证范围见[兼容性](COMPATIBILITY.md)。
+
+## Skill安装
+
+复制完整skill目录，包含SKILL.md、scripts、references、templates、agents；无需安装脚本。以下以OpenCode为例。
+
+**全局安装（推荐）**
+
+在下载目录的父目录执行：
+
+```sh
+mkdir -p ~/.config/opencode/skills
+cp -r harmonyos-api-upgrade-adapter ~/.config/opencode/skills/
+```
+
+**项目级安装**
+
+在HarmonyOS工程根目录执行，将源目录替换为实际下载位置：
+
+```sh
+mkdir -p .opencode/skills
+cp -r "<下载目录>/harmonyos-api-upgrade-adapter" .opencode/skills/
+```
+
+**Windows PowerShell**
+
+全局安装同样复制整个目录：
+
+```powershell
+New-Item -ItemType Directory -Force "$HOME/.config/opencode/skills" | Out-Null
+Copy-Item -LiteralPath .\harmonyos-api-upgrade-adapter -Destination "$HOME/.config/opencode/skills/" -Recurse
+```
+
+项目级安装在工程根目录执行：
+
+```powershell
+New-Item -ItemType Directory -Force .opencode/skills | Out-Null
+Copy-Item -LiteralPath "<下载目录>/harmonyos-api-upgrade-adapter" -Destination .opencode/skills/ -Recurse
+```
+
+| 开发工具 | 全局目录 | 项目级目录 |
+| --- | --- | --- |
+| OpenCode | ~/.config/opencode/skills/ | <工程>/.opencode/skills/ |
+| Codex | ~/.agents/skills/ | <工程>/.agents/skills/ |
+| Claude Code | ~/.claude/skills/ | <工程>/.claude/skills/ |
+
+目标目录下应直接出现harmonyos-api-upgrade-adapter/SKILL.md。同一工程只保留一份所需副本。更新时先替换旧副本，再完整复制新目录，避免目录合并残留已删除的脚本；不恢复旧安装参数或自动安装器。
+
+## 快速入门
+
+在支持Agent Skills的工具中打开工程，提供实际路径、功能、product、目标与验证范围。已有扫描CSV可先完成证据允许的静态工作，实际构建和设备仍需要真实工具链。
+
+### 行为变更
+
+```text
+使用harmonyos-api-upgrade-adapter，扫描并适配API行为变更。
+工程：<实际构建工程>，product：default
+目标target：26.0.0，扫描终点：26.0.0(26) Release
+起点：原target，缺失时取compatible；compatible保持原值
+验证：静态与完整构建；请开始时确认不运行、仅修改后验证或前后对比，spec阶段确认分类范围
+请先按变更分派评估，全部返回后生成spec.md并获取我的同意，再实施批准范围；选择对比时修改前归档before包，修复后生成用例，依次测试before/after，生成逐行结果、测试报告与业务报告。
+```
+
+目标target也可暂不填写，由模型核对原配置与工具链后提供候选并等待选择，SDK版本或CSV终点不代选目标。开始时选择验证方式，spec阶段选择三类任意组合或全部；已有答复不重问。只有前后对比构建before包：原包构建、签名或归档受阻时暂停相关修改并等待补齐或明确改变方式；原包有效归档后，设备暂不可用只影响设备验收。
+
+HAR补充项目类型、实际模块/目录、显式已适配from，按需提供宿主。库构建target、宿主target与设备API分开核对；C/C++使用真实编译上下文和ABI。详见[行为完整流程](references/upgrade/upgrade-workflow.md)、[HAR](references/upgrade/har-upgrade.md)、[原生](references/common/native-adaptation.md)。
+
+行为整理通过[本地索引](references/changelogs-index.json)定位准确章节和精确版本，评估 agent 自行完整阅读官方原文、SDK及实际源码；仅本地缺失、歧义或SDK冲突时有据补充官方网页。knowledge保留取材证据，逐文件reason/evidence保留真实判断，不读取人工初核，也不设二次解读必答清单。详见[变更评估说明](agents/upgrade-assess-change.md)、[修复说明](agents/upgrade-fix-file.md)及[常见案例](references/upgrade/upgrade-examples.md)。
+
+### 废弃API
+
+```text
+使用harmonyos-api-upgrade-adapter，仅扫描并迁移废弃API。
+工程：<实际构建工程>，product：default
+目标target：26.0.0；compatible保持原值；验证：静态、完整构建及复扫
+请先从准确SDK替代声明与工程上下文汇总迁移方案，获取我的同意后实施批准范围，保留低版本逻辑，生成逐行结果与业务报告。
+```
+
+废弃按目标全量查找，不用from限制废弃声明时间。现有应用入口可限定模块/目录，独立HAR废弃入口仍不在支持范围。详见[废弃迁移](references/deprecated/deprecated-api-adaptation.md)及[Context](references/deprecated/context-migration.md)。
+
+## 工具与交付
+
+只保留独立scanner CLI及资料和结构维护工具。两种扫描模式必须显式选择，scanner规则和算法保持，主扫描CSV按行为9列、废弃8列输出，完整证据保留在扫描JSON中；没有full模式或旧别名。模型直接组织真实Hvigor、SDK检查、HDC/工程测试，不再使用旧适配命令。
+
+```console
+node scripts/scanner/bin/harmony-api-scan.mjs help
+npm test
+npm run validate
+```
+
+默认输出根为任务启动目录.api-change-output，以真实scanner返回路径为准。新批次布局4直接在upgrade/或deprecated/下保存原始扫描、adapted-results-<批次ID>.csv、[轻量进度](templates/progress.md)、api-adapt-report.md及实际证据，不再增加adaptation层。行为原表为scan-results-<批次ID>.csv，废弃原表为apiChange_<批次时间戳>.csv；原始字节及批次.internal元数据保持原样，继续任务沿用同一12位随机批次ID。只支持当前布局4；历史CSV作为普通输入导入新批次，旧元数据不用于恢复任务，历史交付不自动迁移。两类报告首页均前置工程配置；行为按CSV逻辑行汇总三类适配必要性及待分类/范围外，废弃按六类处理结果汇总，重复行各自计数。详见[结果表](templates/results.md)、[行为模板](templates/upgrade-report.md)和[废弃模板](templates/deprecated-report.md)。 行为另保存spec.md和已选择设备验证时的test-report.md，模板见[方案](templates/upgrade-spec.md)与[测试报告](templates/upgrade-test-report.md)。
+
+行为结果表仅在原扫描列后追加处理结论、处理说明、后续事项，当前共12列；结论仅用无需适配、已适配、待决策，未评估/缺证据/待批准/范围外等在待决策的说明中区分。通过[共享格式化函数及文件调用](templates/results.md#格式化接口与文件调用)生成UTF-8 BOM、CRLF的CSV，保留原行和超链接。rowId、MODEL_ASSESSED、兼容分析、变更文件和验证证据保存在分组及报告，废弃结果格式保持。原Fixed字段保留，不再表示旧自动审计证明。记录、位置、唯一物理文件、变更与文件工作单元分开统计；评估、修改、语法检查、编译及实际要求的运行分别报告；废弃另列复扫，行为另列已选对比。缺工具、零命中、全无需修改或部分完成也交付实际文件。
+
+编译/构建报错，或用户明确报告混淆、发布包异常时，可按[漏扫案例索引](references/upgrade/scanner-missed-cases.md)结合真实日志排查；正常扫描或构建成功不因此新增主动核查。常见命中与业务误判见[行为案例](references/upgrade/upgrade-examples.md)，两份资料均不能替代真实SDK、工程证据与方案批准。
+
+## 开发维护
+
+保留scanner全量回归、跨平台基础/资源及文档完整性测试；旧适配引擎测试、专用helpers和孤立夹具随引擎删除。场景评测验证模型使用文档的实际效果，不把结构测试冒充语义正确性。evals/仅本地保留并由Git忽略，不随GitHub仓库分发；存在时校验其格式与资源，缺失时明确跳过，不影响测试或安装。自动测试必需夹具保存在测试目录。
+
+[步骤迁移表](docs/step-migration.md)列明原职责、新步骤、输入输出、判据、异常与退役边界；[保留脚本职责](docs/script-responsibilities.md)说明实际基础使用者。参考资料使用当前路径，官方原文哈希独立校验，不再维护整包manifest。发布同步版本、中文CHANGELOG及实际受影响的本地评测，执行npm test和npm run validate后提交推送。保持macOS/Windows与Node20/24实现兼容，不恢复远端四组合CI门禁。

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

@@ -0,0 +1,48 @@
+---
+name: harmonyos-api-upgrade-adapter
+description: 用于 HarmonyOS 废弃 API 扫描与迁移，以及 API 行为变更扫描与适配。升级 targetSdkVersion、调整 compatibleSdkVersion、处理扫描 CSV、ArkTS/ArkUI API 兼容或 HAR/原生行为变更时使用。模型依据官方知识、真实 SDK 和工程上下文逐文件完成最小修改、兼容分析、真实检查与业务报告；scanner 提供扫描事实，轻量文件保存进度。支持 HAP；HAR 与 C/C++ 行为按真实构建和宿主场景处理。
+metadata:
+  version: "17.0.0"
+---
+
+# HarmonyOS API 适配
+
+先确定调用方式。已有升级流水线调用 scanner 时，读取[流水线扫描接入](references/common/workflow-scan.md)，后续分析、修改、构建与报告沿用调用方流程。下面的完整流程用于独立适配任务。
+
+## 选择完整流程
+
+| 用户需求 | 唯一主流程 | 适用范围 |
+| --- | --- | --- |
+| API行为变更 | [行为完整流程](references/upgrade/upgrade-workflow.md)，U01–U09 | HAP、明确模块/目录的HAR及相关C/C++ |
+| 废弃API迁移 | [废弃完整流程](references/deprecated/deprecated-api-adaptation.md)，D01–D11 | 应用入口，可限定注册模块/目录；独立HAR入口不在支持范围 |
+
+行为先按变更条目分派只读评估，汇总 spec.md 并取得用户确认后修复；少量文件由主 agent 处理，较多时按物理文件分派。默认尽量保持升级前体验，保留跨系统行为分析、真实检查、构建及按需对比；不做通用接口版本可用性匹配，不自动调整compatible，也不复扫。废弃保留低版本迁移、构建和复扫，仅按明确要求做单次设备验证。
+
+两条流程分别定义范围与版本、扫描/导入、评估与批准、修改、验证、失败返回和交付。只加载当前功能的主流程，公共资料在流程指定节点按路径读取；不再先读一套共用步骤再拼接功能差异。目标选择、方案展示后的批准与设备授权以该流程为准，已明确的选择不重复询问。
+
+## 公共资料的使用
+
+公共资料只维护一份，不编排功能步骤：
+
+- [版本契约](references/common/sdk-versions.md)：统一配置/打包字段、设备API家族与扫描版本。
+- [API保护与告警](references/common/compatibility.md)服务废弃迁移；[target升级兼容](references/upgrade/upgrade-compatibility.md)服务行为流程，HAR追加[宿主专题](references/upgrade/har-upgrade.md)，具体修改参考[行为示例](references/upgrade/upgrade-examples.md)。
+- [编码规范](references/common/arkts-coding-standards.md)、[原生知识](references/common/native-adaptation.md)：按实际修改场景读取。
+- [真实验证方法](references/common/verification.md)、[功能取证](references/common/runtime-functional-tests.md)、[排错与继续](references/common/troubleshooting.md)：主流程决定何时执行、如何批准及返回哪里。
+- [通用进度](templates/progress.md)、[逐行结果格式](templates/results.md)：共享文件布局和基础字段；功能记录及报告组织由当前主流程定义。
+
+## 同时处理两类任务
+
+分别保存输入身份、原始行、批准范围、进度和报告，业务结论不互代。修改前记录两条任务共同的原target/compatible和源码基线，不能把先执行任务改后的target当作另一任务原基线。共享源码/配置的必要修改须纳入全部受影响方案的实际批准范围；获批前不实施。
+
+仅当行为任务选择前后对比时，先真实构建并归档原源码/原配置的 before 包，再实施影响基线的源码/配置修改，包括废弃任务的共享修改；设备测试可在修复后依次执行 before/after。原包构建或归档受阻时按行为主流程等待明确决定，有效原包已归档后的设备阻断不暂停修复；废弃单独任务不要求修改前基线。联合展示方案时分别记录答复及批准范围，不新增逐文件确认。
+
+最终源码、配置、SDK、product/target与库消费关系一致时，两类任务可关联同一次真实完整构建证据；之后任一相关修改都会使受影响的旧验证待复核。废弃真实复扫、行为适用性与分类、设备用例和两类报告仍分别核对，不用一个功能通过替代另一个。
+
+## 全程约束与交付
+
+- 读取准确官方知识、SDK声明和工程上下文；命中、文件变化或编译通过均不单独证明语义正确。
+- 保留原始扫描字节、全部逻辑行/重复行、SDK、依赖源码、官方原件及任务外改动。废弃按准确since和版本家族处理迁移，行为按官方触发条件和target隔离理解变化；保留返回/回调、异常传播和生命周期。
+- 真实工具结果保存命令、cwd、版本、退出码、日志与当前产物；模型自检、未执行、失败、证据不足分别表达；额外设备范围按当前功能与实际要求记录。修改后未真实完整构建成功只算部分完成；相关输入变化后重新验证。
+- 不需要新MCP或特定供应商工具才能进行可信静态工作；不恢复适配CLI、自动语义审计、事务账本或旧状态恢复。只在用户明确要求撤销时按实际差异安全撤销，不自动整文件回滚。
+
+交付位于本批次upgrade/或deprecated/：原始扫描、adapted-results-<批次ID>.csv、api-adapt-report.md、轻量进度及实际证据，布局4与批次.internal位置保持。行为另交付 spec.md 和按需生成的 test-report.md；报告分别使用主流程指定模板，原Fixed字段保留。行为结果只追加处理结论（无需适配/已适配/待决策）、处理说明、后续事项三列，使用共享纯格式化函数；rowId、MODEL_ASSESSED及详细证据保留在进度/分组/报告。废弃结果格式保持。零行、全无需修改、待批准、部分完成和停止均完成本功能的覆盖核对与实际文件交付；旧记录只读核对，不继承成功。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/agents/upgrade-assess-change.md

@@ -0,0 +1,37 @@
+# 单个行为变更的只读评估
+
+由[行为主流程 U04](../references/upgrade/upgrade-workflow.md#u04-按变更条目评估)调用。一个 agent 负责一个准确变更条目及其全部关联文件，文件多也不拆批、不抽样、不再分派 agent。只读工程源码和配置，不执行修复，不写共享 spec、进度或报告；结果返回主 agent 统一落盘。
+
+## 输入
+
+- 变更名称、规则身份、准确来源和保留 Beta/Release 的精确版本。
+- 本地官方章节路径及起始位置；必要时提供扫描 JSON 和原始行以核对身份。
+- 全部关联物理文件、调用位置、rowIds 和范围外说明，不能只给部分代表文件。
+- 工程/product/模块范围、真实 SDK 路径、原/目标 target、原 compatible，HAR 另有宿主和历史基线信息。
+- 业务目标及已知约束；默认尽量保持升级前的功能、视觉和交互体验。
+
+信息缺失先指出具体缺口，已有充分证据的独立文件仍可评估，不猜造未知取值。
+
+## 评估步骤
+
+1. **读取完整官方章节。** 按[资料定位](../references/upgrade/upgrade-workflow.md#官方资料定位)核对本条身份、版本和来源，读完原因、影响、生效条件、接口清单、指导和代码示例。记录工具实际读取的范围。同一任务内可以复用已读原文，主 agent 的摘要或链接不能代替本 agent 阅读。仅本地缺失/歧义/SDK冲突时记录原因并补充官方网页。
+2. **逐文件核对全部调用点。** 阅读相关文件完整上下文及必要调用链，核对实际组件/接收者、重载、实参、默认值、生命周期和业务用途；必要时读准确 SDK 声明。不要把同名业务封装当 SDK 对象，也不要因为没写某属性就推定未触发。调用行号可能过期，应核对真实代码；无法唯一定位则保留缺口。
+3. **判断影响并提出方案。** 按[分类依据](../references/upgrade/upgrade-workflow.md#分类与记录)逐调用分类，说明源码和官方依据。按[target 升级兼容](../references/upgrade/upgrade-compatibility.md)区分设备行为边界、target 隔离和接口起始版本；原显式参数已足够时不加分支。默认提出保持旧体验的最小方案，不能仅因默认变化就统一改代码。按需参考[常见正反例](../references/upgrade/upgrade-examples.md)，不逐项回答无关案例。
+4. **识别依赖和验证要求。** 列出共享配置/helper、跨文件影响、方案取舍、预期业务行为和需要的用例。HAR 读[宿主专题](../references/upgrade/har-upgrade.md)，C/C++ 读[原生专题](../references/common/native-adaptation.md)。无法确认来源/默认值/封装记 EVIDENCE_GAP，需要产品决定记 DECISION_REQUIRED，不强行分类。
+5. **核对覆盖并返回。** 所有关联文件和调用点均有结果或具体未完成原因；重复 rowIds 的原始行关联不丢失。模型评估不冒充真实语法检查、构建或设备通过。agent 失败/中断时列实际已处理与剩余范围，不返回虚假的全部完成。
+
+## 返回内容
+
+采用可由主 agent 合并的结构化结果，不规定额外状态协议：
+
+| 部分 | 必须包含 |
+| --- | --- |
+| 变更 | 名称、规则/来源/精确版本、官方旧新行为、触发条件与 target 隔离 |
+| knowledge | originalReference 保留扫描 JSON 或历史 CSV 的 Source Reference 原值并记录证据来源，缺失时留空；localReference 保存核实后的当前章节路径及行号，不转换旧路径；rawVersion/version 保留原始/规范化精确版本；实际 readRanges、官方补充及冲突。官方 URL 作为来源证据另存，不覆盖原始字段 |
+| 每个文件/调用 | 物理路径、实际位置和全部 rowIds、分类或缺口、reason、源码/SDK/原文 evidence |
+| 建议 | 最小修改或无需修改依据、跨系统处理、保留旧体验的成本与替代方案 |
+| 协调事项 | 共享修改、跨文件依赖、与其他变更可能冲突的方案、待决策项 |
+| 验证 | 可执行的业务预期、功能/视觉用例建议、尚未验证的边界 |
+| 覆盖 | 实际已评估与未完成文件/调用点，具体下一步 |
+
+主 agent 据此生成[spec](../templates/upgrade-spec.md)，取得批准后才进入独立修复阶段。已分类为必须适配也不能在本任务中直接修改。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/agents/upgrade-fix-file.md

@@ -0,0 +1,23 @@
+# 单个物理文件的获批行为修复
+
+供[行为主流程 U06](../references/upgrade/upgrade-workflow.md#u06-实施获批修复)调用。文件少时主 agent 直接按本说明处理；文件多时按物理文件分派，路径别名归为同一文件，每个文件只有一个修改者。不是按变更各自修改同一文件。
+
+## 输入与进入条件
+
+- 一个明确的物理文件，以及这个文件涉及的全部已批准变更、rowIds 和具体方案。
+- 当前 spec.md 的路径/相关内容、实际批准范围及来源；没有批准不实施修复。
+- 对应完整官方章节、准确 SDK、工程/product、原/目标 target、compatible 和业务约束。
+- 任务外改动、主 agent 协调的共享 helper/配置/跨文件接口及各自修改归属。
+- 已确认的验证方式；选择对比时，主 agent 已核实修改前 before 包有效归档。没有这个事实先报告，不自行跳过或降级。
+
+只负责分配的文件；不改共享 spec、总进度或报告，不改未经分配的配置/其他文件，不自行新建公共 helper。未明确的共享依赖交由主 agent 协调，不并发争抢文件。
+
+## 修复步骤
+
+1. **核对当前代码与方案。** 阅读文件及相关官方完整章节，必要时核对 SDK 和调用链，确认当前输入仍支持获批方案。保留用户与其他任务的改动；来源不明或实质方案变化时交回主 agent 更新 spec，不扩大范围。
+2. **实施最小修改。** 同一文件的全部获批变更一起处理，默认保持原功能、视觉与交互。按[编码规范](../references/common/arkts-coding-standards.md)保留返回/回调、同步异步、异常、资源身份和生命周期。按[行为兼容](../references/upgrade/upgrade-compatibility.md)采用确有必要的显式参数或新旧分支，不提高 compatible、不为消除扫描命中制造修改。HAR/原生按对应专题处理。
+3. **复核实际差异。** 检查每处差异对应的获批条目及 rowIds，避免重复 import、无关格式/日志修改和漏改调用。仅根 target、同文件无关变化不算本行修复；无需修改的条目返回具体依据。
+4. **执行可用文件检查。** 按[真实静态检查](../references/common/verification.md#通用静态复核)执行实际可用 SDK/IDE 检查，区分模型复核、工具未执行、历史错误和新增错误。修必要闭包，失败保留当前差异和诊断，不自动整文件回滚。完整工程构建由主 agent 统一组织，不在每个文件任务里重复触发。
+5. **返回结果。** 返回物理文件、关联方案/rowIds、真实修改及必要前后片段或哈希、业务理由、实际检查命令/退出码/日志、未完成项和需要主 agent 协调的内容。内部 MODIFIED 仅表示相关代码已改，不表示工程构建或设备验收通过。返回具体修改、作用及理由，供主 agent 填入行为 CSV 的处理说明；未编译、编译失败及实际所需人工验证写入后续事项。主 agent 统一使用格式化函数生成仅追加三列的结果表，子 agent 不另外增加CSV字段。
+
+主 agent 统一落盘结果，按[排错方法](../references/common/troubleshooting.md#定位与停止)协调失败和受影响范围；不能通过换 agent 重置同一错误的实质失败次数。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@local/harmonyos-api-upgrade-adapter",
+  "version": "17.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node scripts/test-suite.mjs all",
+    "test:adapter": "node scripts/test-suite.mjs adapter",
+    "test:scanner": "node scripts/test-suite.mjs scanner",
+    "scanner": "node scripts/scanner/bin/harmony-api-scan.mjs",
+    "validate": "node scripts/maintenance/validation/validate-skill.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}