@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/scripts/shared/test/upgrade-results.test.mjs

@@ -0,0 +1,140 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import os from 'node:os';
+import path from 'node:path';
+import { parseCsv, stringifyCsv, UPGRADE_HEADERS } from '../format/csv.mjs';
+import { formatUpgradeResults } from '../format/upgrade-results.mjs';
+import { sha256 } from '../io/fs-utils.mjs';
+
+const root = fileURLToPath(new URL('../../../', import.meta.url));
+const addedHeaders = ['处理结论', '处理说明', '后续事项'];
+const scanRow = {
+  'Api Definition': 'run(value: "中文,参数"): void\n声明续行', Language: 'ArkTS',
+  'Changed in SDK': '26.0.0(26) Beta1', 'Affected Versions': 'ALL',
+  Title: '=HYPERLINK("https://example.test/a,b","标题""引号")',
+  'Code Location': 'entry/中文 空格/A.ets:12', Fixed: 'Unfixed',
+  'Change Type': 'API Behavior Change', 'Rule ID': 'CH123',
+};
+
+function result(bytes, index, conclusion = '无需适配') {
+  return { rowId: `${sha256(bytes)}:${index}`, '处理结论': conclusion,
+    '处理说明': '具体理由,中文\n含"引号"及 C:\\工程 空格\\A.ets', '后续事项': '' };
+}
+
+for (const bom of [false, true]) for (const newline of ['\n', '\r\n']) {
+  test(`upgrade results preserve cells and duplicate rows from bom=${bom}, newline=${JSON.stringify(newline)}`, () => {
+    const input = Buffer.from(stringifyCsv(UPGRADE_HEADERS, [scanRow, scanRow, scanRow], { bom, newline }));
+    const before = Buffer.from(input);
+    const results = ['无需适配', '已适配', '待决策'].map((conclusion, i) => result(input, i + 1, conclusion));
+    results[1]['处理说明'] = '已按批准修改 metadata，保留旧视觉';
+    results[1]['后续事项'] = '需人工验证；设备验证未选择';
+    results[2]['后续事项'] = '证据不足，补齐实际调用后再判断';
+    const output = formatUpgradeResults(input, [...results].reverse());
+    const parsed = parseCsv(output);
+    assert.ok(output.startsWith('\ufeff'));
+    assert.ok(output.endsWith('\r\n'));
+    assert.deepEqual(parsed.headers, [...UPGRADE_HEADERS, ...addedHeaders]);
+    assert.equal(parsed.headers.length, 12);
+    assert.deepEqual(parsed.rows.map(row => Object.fromEntries(UPGRADE_HEADERS.map(header => [header, row[header]]))),
+      [scanRow, scanRow, scanRow]);
+    assert.deepEqual(parsed.rows.map(row => row['处理结论']), ['无需适配', '已适配', '待决策']);
+    assert.equal(parsed.rows[0]['处理说明'], results[0]['处理说明']);
+    assert.equal(parsed.rows[1]['后续事项'], results[1]['后续事项']);
+    assert.deepEqual(input, before);
+    assert.equal(results[0].rowId, `${sha256(input)}:1`);
+  });
+}
+
+test('zero-row scans keep the original headers and exactly three result headers', () => {
+  const bytes = Buffer.from(stringifyCsv(UPGRADE_HEADERS, []));
+  assert.deepEqual(parseCsv(formatUpgradeResults(bytes, [])), { headers: [...UPGRADE_HEADERS, ...addedHeaders], rows: [] });
+});
+
+test('historical raw scan columns remain intact without exporting result metadata', () => {
+  const headers = [...UPGRADE_HEADERS, 'Source Reference'];
+  const row = { ...scanRow, 'Source Reference': '26.0.0/source.md:3', 'Code Location': 'C:\\工程 空格\\A.ets:12' };
+  const bytes = Buffer.from(stringifyCsv(headers, [row]));
+  const output = parseCsv(formatUpgradeResults(bytes, [{ ...result(bytes, 1), '处理来源': 'MODEL_ASSESSED', evidence: '日志' }]));
+  assert.deepEqual(output.headers, [...headers, ...addedHeaders]);
+  assert.equal(output.rows[0]['Source Reference'], row['Source Reference']);
+  assert.equal(output.rows[0]['Code Location'], row['Code Location']);
+  assert.ok(!output.headers.includes('rowId'));
+  assert.ok(!output.headers.includes('处理来源'));
+});
+
+test('missing, duplicate and foreign row identities fail instead of merging equal scan rows', () => {
+  const bytes = Buffer.from(stringifyCsv(UPGRADE_HEADERS, [scanRow, scanRow]));
+  assert.throws(() => formatUpgradeResults(bytes, [result(bytes, 1)]), /缺少.*rowId/);
+  assert.throws(() => formatUpgradeResults(bytes, [result(bytes, 1), result(bytes, 1)]), /重复.*rowId/);
+  assert.throws(() => formatUpgradeResults(bytes, [result(bytes, 1), result(bytes, 3)]), /未知.*rowId/);
+  const other = Buffer.from(stringifyCsv(UPGRADE_HEADERS, [scanRow, scanRow], { bom: false }));
+  assert.throws(() => formatUpgradeResults(bytes, [result(other, 1), result(other, 2)]), /未知.*rowId/);
+});
+
+test('invalid results and malformed scan input fail before producing a CSV', () => {
+  const bytes = Buffer.from(stringifyCsv(UPGRADE_HEADERS, [scanRow]));
+  for (const conclusion of ['NO_CHANGE', 'MODIFIED', 'DECISION_REQUIRED', 'EVIDENCE_GAP', 'PENDING', 'OUT_OF_SCOPE', '', undefined])
+    assert.throws(() => formatUpgradeResults(bytes, [{ ...result(bytes, 1), '处理结论': conclusion }]), /处理结论/);
+  for (const explanation of ['', ' \r\n ', null])
+    assert.throws(() => formatUpgradeResults(bytes, [{ ...result(bytes, 1), '处理说明': explanation }]), /处理说明/);
+  assert.throws(() => formatUpgradeResults(bytes, [{ ...result(bytes, 1), '后续事项': null }]), /后续事项/);
+  assert.throws(() => formatUpgradeResults(bytes, [null]), /rowId/);
+  assert.throws(() => formatUpgradeResults(bytes, null), /数组/);
+  assert.throws(() => formatUpgradeResults(bytes.toString(), []), /Buffer/);
+  assert.throws(() => formatUpgradeResults(Buffer.alloc(0), []), /表头/);
+  assert.throws(() => formatUpgradeResults(Buffer.from([0xff]), []), /UTF-8/);
+  assert.throws(() => formatUpgradeResults(Buffer.from('a,b\r\n1\r\n'), []), /Malformed CSV/);
+  assert.throws(() => formatUpgradeResults(Buffer.from('a\r\n"unterminated'), []), /Malformed CSV/);
+});
+
+test('duplicate headers and result column collisions require the original scan table', () => {
+  assert.throws(() => formatUpgradeResults(Buffer.from('Title,Title\r\na,b\r\n'), []), /重复表头/);
+  for (const header of addedHeaders) {
+    const bytes = Buffer.from(stringifyCsv([...UPGRADE_HEADERS, header], [{ ...scanRow, [header]: '旧结果' }]));
+    assert.throws(() => formatUpgradeResults(bytes, []), /原始扫描表/);
+  }
+});
+
+test('the documented file-based writer supports quoted Unicode paths and reports a locked output', async t => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "行为 CSV '单引号 & $路径-"));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const skill = path.join(directory, "skill '副本");
+  await mkdir(path.join(skill, 'scripts'), { recursive: true });
+  await cp(path.join(root, 'scripts', 'shared'), path.join(skill, 'scripts', 'shared'), { recursive: true });
+  const guide = await readFile(path.join(root, 'templates', 'results.md'), 'utf8');
+  const example = guide.match(/```javascript\r?\n([\s\S]*?)\r?\n```/);
+  assert.ok(example, 'results guide contains an executable JavaScript writer');
+  const script = path.join(directory, "生成 '结果.mjs");
+  await writeFile(script, example[1]);
+  const scan = path.join(directory, "扫描 '原件.csv"), input = path.join(directory, '逐行结果.json');
+  const output = path.join(directory, "adapted-results '结果.csv");
+  const bytes = Buffer.from(stringifyCsv(UPGRADE_HEADERS, [scanRow]));
+  await writeFile(scan, bytes);
+  await writeFile(input, `\ufeff${JSON.stringify([result(bytes, 1, '已适配')])}`);
+  const run = target => spawnSync(process.execPath, [script, skill, scan, input, target], {
+    cwd: directory, encoding: 'utf8', shell: false, timeout: 30_000,
+  });
+  const generated = run(output);
+  assert.ifError(generated.error);
+  assert.equal(generated.status, 0, generated.stderr);
+  assert.equal(parseCsv(await readFile(output, 'utf8')).rows[0]['处理结论'], '已适配');
+  const original = await readFile(output);
+  const overwritingScan = run(scan);
+  assert.equal(overwritingScan.status, 1);
+  assert.match(overwritingScan.stderr, /原始扫描/);
+  assert.deepEqual(await readFile(scan), bytes);
+  // Simulate a persistent Windows lock without skipping the test on macOS.
+  const originalUtilities = pathToFileURL(path.join(root, 'scripts', 'shared', 'io', 'fs-utils.mjs')).href;
+  await writeFile(path.join(skill, 'scripts', 'shared', 'io', 'fs-utils.mjs'),
+    `export { sha256 } from ${JSON.stringify(originalUtilities)};\n`
+    + "export async function atomicWrite() { throw Object.assign(new Error('locked'), { code: 'EPERM' }); }\n");
+  const locked = run(output);
+  assert.equal(locked.status, 1);
+  assert.match(locked.stderr, /EPERM/);
+  assert.match(locked.stderr, /关闭.*原路径重试/);
+  assert.deepEqual(await readFile(output), original);
+  assert.deepEqual(await readFile(scan), bytes);
+});

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/test-suite.mjs

@@ -0,0 +1,29 @@
+// Explicit file arguments work on both cmd.exe and POSIX shells; no shell glob.
+import { readdir } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const suites = { adapter: ['scripts/shared/test', 'scripts/maintenance/test'], scanner: ['scripts/scanner/test'] };
+const requested = process.argv[2];
+if (requested !== 'all' && !Object.hasOwn(suites, requested)) throw new Error('Specify all, adapter or scanner test suite');
+const selected = requested === 'all' ? Object.keys(suites) : [requested];
+process.exitCode = 0;
+for (const name of selected) {
+  console.log(`[tests] ${name}`);
+  try {
+    const files = [];
+    for (const relative of suites[name]) {
+      const directory = path.join(root, relative);
+      files.push(...(await readdir(directory)).filter(file => file.endsWith('.test.mjs')).sort().map(file => path.join(directory, file)));
+    }
+    if (!files.length) throw new Error('No test files found');
+    const result = spawnSync(process.execPath, ['--test', '--test-concurrency=1', ...files], { stdio: 'inherit', shell: false });
+    if (result.error) throw result.error;
+    if (result.status !== 0) process.exitCode = requested === 'all' ? 1 : result.status ?? 1;
+  } catch (error) {
+    console.error(`[tests] ${name}`, error);
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,86 @@
+# 废弃 API 报告模板
+
+仅供 `deprecated` 的 D11 使用。按[废弃交付要求](../references/deprecated/deprecated-api-adaptation.md#d11-核对迁移覆盖并交付)核对统计与证据，使用[逐行结果](results.md)关联原始行。报告写入本功能目录的 `api-adapt-report.md` 并实际回读；真实路径替换占位符，按场景删除不适用的小节。
+
+```markdown
+# 废弃 API 迁移报告
+
+功能：deprecated
+工程：<实际工程>；product：<产品>；范围：<模块/目录>
+compatibleSdkVersion：<实际值；有变化时写原值→当前值或计划值及状态>
+targetSdkVersion：<原配置值> → <目标值>（<已实施/计划/保持不变>）
+处理结果（CSV逻辑行）：无需修改 <N>；已修改 <N>；待决策 <N>；证据不足 <N>；未处理 <N>；范围外 <N>
+原始行数：<N>
+总体结论：<已完成/无需修改/部分完成/待用户确认/待编译/编译失败/待业务决定；按实际证据填写>
+
+## 任务与输入
+
+- 已有用户改动及保护情况；工程、product、范围及配置现状见首页
+- 真实编译 SDK/IDE与扫描依据；from 不限制废弃声明出现时间，不用扫描from或编译SDK替代首页配置变化
+- 原 CSV 与副本的完整路径、SHA-256、逻辑行数；本次已授权验证范围
+
+## 方案确认与实施范围
+
+- 展示的迁移汇总方案、SDK符号、关联文件/rowIds、必要配置调整、兼容风险及验证安排
+- 用户全部/部分批准或暂不修改的实际答复及来源；明确获批部分、共享修改与未批准项
+- 实际修改与批准范围的对应；实质方案变化后的重新确认，断点继续沿用批准的依据
+- 未批准或待回答保留未实施原因，不当作无需适配或已修复；单次设备验证仅按明确要求记录
+
+## 扫描与证据边界
+
+- 实际扫描或仅导入 CSV，原扫描 JSON、coverage、diagnostics 路径
+- SDK_STATE、编译日志或 DevEco 等真实检测来源及覆盖限制
+- 后端超时、声明缺失、依赖告警与未扫描范围；零命中不作为全部安全的证明
+
+## 处理统计
+
+- 原始、选中、已评估、实际修改、无需修改、待决策、证据不足、未处理与范围外行数
+- 去重位置、唯一物理文件、SDK 符号组与符号文件工作单元分别统计
+- 重复行、类与成员重叠命中各有 rowId，说明同一次修改的对应关系；评估与问题解决分开
+
+## 废弃符号：<扫描JSON中的API Symbol ID、准确接收者与重载；CSV_ONLY说明补证来源或缺口>
+
+### 旧声明与替代依据
+
+<扫描JSON或历史CSV中的身份及替代证据、真实 SDK 文件/行、旧声明、deprecated/useinstead、Replacement API/Source、替代接口和辅助获取链各自的 since；声明冲突或无替代时说明事实>
+
+### 迁移与失败契约
+
+<实际业务调用、上下文来源、参数与返回值、同步/异步、回调和资源身份；解释版本保护及低版本回退>
+
+### 逐文件结果
+
+| 文件、原始位置与 rowIds | 结论 | 实际替代或无需修改依据 | 兼容、上下文及异常处理 | 验证与待办 |
+| --- | --- | --- | --- | --- |
+
+## 修改后复扫与残留
+
+- 新扫描路径、实际 SDK、product、模式与范围，以及完整性诊断
+- 按准确符号和迁移归属关联原始行，分别列出：未迁移、合法低版本受保护回退、依赖告警、工具/声明缺口和新增废弃问题
+- 保留各类残留位置、理由和下一步；不以数量下降、清零或缩小范围代替逐行核对
+
+## 编码与独立验证
+
+| 项目 | 结果 | 实际证据与限制 |
+| --- | --- | --- |
+| 兼容与适用编码规范复核 | 已评估/待复核 | 逐项依据；MODEL_ASSESSED |
+| 真实 SDK 语法/类型检查 | 通过/失败/未执行 | 工具、版本、命令、日志，历史与新增问题分开 |
+| 当前源码完整编译 | 通过/失败/未执行/待复核 | product/target/ABI、输入状态、退出码、日志、产物路径/大小/SHA-256 |
+| 废弃复扫 | 完成/不完整/未执行/不适用 | 新扫描与逐原始行残留分析；未修改时说明实际安排 |
+| 已授权业务及最低版本验证 | 通过/失败/未执行/部分 | 设备/API、真实调用、用例、返回值/回调及日志/图片 |
+| 本次实例清理 | 已清理/失败/未执行 | 仅清理本次启动实例，先保存证据，再核对停止结果 |
+
+有源码或构建配置修改时，未取得对应当前输入的真实编译成功，只能填写部分完成、待编译或失败。源码、配置或 SDK 再变化时，旧相关成功须重新验证。MODIFIED、残留清零、旧 Fixed 或编译通过均不能替代其余独立验收。
+
+## 后续事项与交付
+
+- 业务决定、声明/上下文缺口、待编译、复扫残留及最低版本待办，明确下一步
+- deprecated目录中的apiChange_<批次时间戳>.csv、adapted-results-<批次ID>.csv、本报告、轻量进度，以及批次.internal和实际验证证据的完整路径
+- 文件已回读核对；用户修改过的交付件另存，不覆盖
+```
+
+零命中、全 NO_CHANGE、工具缺失、部分完成或停止也使用此模板。保留输入旧 Fixed 字段，不将本次模型判断写成自动 SDK/语义证明。
+
+首页配置状态来自实际回读，未实施的目标写计划，target未变如实注明保持不变。首页六类分别对应结果表的NO_CHANGE、MODIFIED、DECISION_REQUIRED、EVIDENCE_GAP、PENDING和OUT_OF_SCOPE，按CSV逻辑行统计并核对合计等于原始行数，重复行分别计数；不套用行为三类适配分类。未知统计写原因，零行时六类均为0并保留结果表表头；MODIFIED数量不表示已完成构建或业务验收。
+
+本报告只记录当前包的单次设备验证，不设置修改前基线、比较方式、阶段对照、可比性或基线降级字段。

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

@@ -0,0 +1,150 @@
+# 通用轻量进度格式
+
+在所选功能主流程要求的节点初始化和更新，供逐文件记录、核对交付及断点继续使用。本页只定义共用布局和基础字段；业务决策、分类、特定证据字段与完成判据由各主流程定义。总览保持简短，当前分组按需读取；没有运行脚本、冻结协议或自动可信账本。
+
+## 建议目录
+
+```text
+<实际扫描批次>/
+  .internal/                           # 批次元数据与scanner证据，位置不变
+  upgrade/                             # deprecated任务使用deprecated/，不另加adaptation层
+    scan-results-<批次ID>.csv           # deprecated原表为apiChange_<批次时间戳>.csv
+    adapted-results-<批次ID>.csv
+    progress.json
+    groups/b001.json                    # 组号只用ASCII字母数字和短横线
+    api-adapt-report.md
+    spec.md                            # 仅行为：全部评估返回后汇总，作为修复批准依据
+    test-report.md                     # 仅行为已选择设备验证：实际测试或阻断报告
+    evidence/                          # 仅放实际生成或保留的日志、包信息、图片
+```
+
+新批次采用outputLayout.schemaVersion=4，原表直接写入deliveryDirectory；原表与结果表均按scanner返回路径使用，不在扫描后搬动原表。两类结果表均为adapted-results-<批次ID>.csv，复用本批次12位随机ID，继续任务不重新命名；由模型组织结果写入，scanner不预填模型结果；行为通过[格式化函数与文件示例](results.md#格式化接口与文件调用)只追加三列，rowId、内部状态、MODEL_ASSESSED及完整证据继续保存在进度、分组和报告中，废弃结果列保持原有格式。
+
+scanner原CSV字节及内部元数据不修改。导入先创建新时间戳批次，可复用scripts/shared/platform/artifact-layout.mjs的createScanBatch分配唯一ID和功能目录，将原字节复制到rawCsv，记录原件位置与哈希；结果写入adaptedCsv。不提供旧布局1/2/3读取兼容；历史CSV作为普通输入导入新批次，旧元数据不恢复运行状态，历史adaptation目录不自动移动、重命名或迁移。已有同名交付被用户修改时另存新版本并记录实际路径，不生成新的批次ID来冒充原任务。路径按node:path及实际物理模块定位，Windows不用POSIX绝对路径假设。
+
+导入的伴随JSON、coverage、diagnostics及旧批次元数据仅作为输入证据保留在新批次.internal/imported/并记录原来源；不覆盖新scan-batch.json，也不把旧扫描的batchId改成本次交付ID或冒充重新扫描。scanEvidence明确标注导入来源与实际证据路径。
+
+交付文件名保持api-adapt-report.md，具体报告由功能流程指定。每轮源码或构建配置修改后编译记录回到NOT_RUN并按当前主流程安排完整构建；后续输入变化保留历史证据，相关通过须重新验证。未编译成功时总览和next明确部分完成/待编译或失败原因。
+
+## 总览示例
+
+```json
+{
+  "mode": "<当前功能>",
+  "batchId": "<本批次12位随机ID>",
+  "delivery": {
+    "directory": "<批次>/<功能>",
+    "adaptedCsv": "<批次>/<功能>/adapted-results-<批次ID>.csv",
+    "report": "<批次>/<功能>/api-adapt-report.md"
+  },
+  "project": "<真实工程绝对路径>",
+  "product": "default",
+  "scope": {
+    "modules": [],
+    "directories": []
+  },
+  "source": {
+    "originalPath": "<原件>",
+    "copyPath": "<字节副本>",
+    "sha256": "<实际计算>",
+    "inputRows": 0
+  },
+  "versions": {
+    "oldTarget": "<旧值>",
+    "compatible": "<最低>",
+    "target": "<目标>",
+    "from": "<精确起点>",
+    "to": "<精确终点>",
+    "compileSdk": "<真实版本或未知>"
+  },
+  "decisions": {
+    "target": {
+      "answer": null
+    },
+    "repair": {
+      "plan": "<本次汇总方案位置>",
+      "answer": null,
+      "approvedItems": []
+    },
+    "runtime": {
+      "mode": "<当前主流程确定的方式或未要求>",
+      "answer": null,
+      "scope": []
+    }
+  },
+  "scanEvidence": {
+    "origin": "IMPORTED_CSV",
+    "coverage": "UNKNOWN",
+    "files": [],
+    "gaps": []
+  },
+  "groups": [
+    {
+      "id": "b001",
+      "identity": "<准确规则和版本或SDK符号>",
+      "record": "groups/b001.json",
+      "status": "PENDING"
+    }
+  ],
+  "statistics": {
+    "records": 0,
+    "locations": 0,
+    "physicalFiles": 0,
+    "workUnits": 0,
+    "changes": 0
+  },
+  "verification": {
+    "static": "NOT_RUN",
+    "compile": "NOT_RUN",
+    "runtime": "NOT_RUN"
+  },
+  "next": "<下一具体步骤或缺口>"
+}
+```
+
+0与占位字符串必须换成真实事实。scanEvidence保存实际来源、coverage/diagnostics路径与超时/缺规则/CSV_ONLY边界；官方规则缺口与业务待办分开。
+
+所有decisions记录真实答复和可定位对话来源，null为未取得，不能补造。repair.plan指向本次汇总方案；行为使用实际spec.md路径，全部变更评估任务返回后由主agent合并冲突再写入。approvedItems只列确已批准条目及必要共享修改，空数组不表示批准全部。未批准项、验证未选/未要求、当前功能实际要求的缺口分别保存，不改写成范围外或已解决。必要功能字段和验证范围格式见当前主流程。
+
+## 分组示例
+
+```json
+{
+  "id": "b001",
+  "identity": {
+    "ruleOrSymbol": "<准确身份>",
+    "version": "<精确版本>",
+    "reference": "<官方文件/章节或声明位置>"
+  },
+  "overview": "<当前符号/变更及业务影响>",
+  "files": [
+    {
+      "path": "<物理文件或模块相对路径>",
+      "rowIds": [
+        "<输入sha256>:1"
+      ],
+      "locations": [
+        "<原始Code Location>"
+      ],
+      "plan": "<修改前方案及当前功能的验证安排>",
+      "outcome": "PENDING",
+      "reason": "<实际判断，不从标题推测>",
+      "compatibility": "<废弃接口保护或行为跨系统处理；无相关差异可留空>",
+      "changes": [],
+      "evidence": [],
+      "attempts": [],
+      "next": "<未完成事项>"
+    }
+  ]
+}
+```
+
+同一准确符号/变更与物理文件构成一个工作单元，一个文件多变更分别登记，原始重复行各自保留。按真实物理文件核对路径与范围。文件状态可为PENDING/PROCESSING/REVIEWED；REVIEWED只表示当前已评估，DECISION_REQUIRED/EVIDENCE_GAP仍未解决。组内不同结果分别记录，不用整组一次修改替代每行结论。
+
+reason记录真实判断，evidence关联实际读到的声明/资料/源码或工具结果，尚未处理保持PENDING。涉及特定分类或取材时按当前功能流程补充，不在本通用格式中预填。
+
+逐文件记录真实差异和必要前后哈希/片段来源供安全继续，不复制整工程或建立blob/head/签名回执。attempts按[排错方法](../references/common/troubleshooting.md#定位与停止)保留同一错误的实质失败方案及环境阻断，不通过换组/目录重置次数。输入、源码、配置、SDK或包变化后核对影响，旧结论保留历史说明并标待复核，不继承通过。
+
+行为评估和修复agent只返回结果，主agent统一更新本进度、分组、spec和报告，避免并发覆盖。包归档与设备实测证据分别保存在evidence并关联实际路径/哈希，before归档成功不表示before测试通过；修复后变化仅重建after并重测受影响用例，不覆盖原before。
+
+按功能补充验证状态：行为可记录所选对比及原包归档受阻时的baselineDecision，跨系统处理与缺口使用现有compatibility和reason/evidence，不创建复扫或自动最低设备状态；废弃记录真实rescan及明确要求的单次runtime，不创建比较方式、阶段基线或降级字段。已退役项不生成NOT_RUN待办，历史记录只读，按当前动作与范围核对后继续。

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

@@ -0,0 +1,110 @@
+# 逐行结果与统计模板
+
+在当前主流程解析后建立，每文件处理后更新，交付时回读核对。两类结果均保存为功能目录中的新文件adapted-results-<批次ID>.csv，以outputLayout.adaptedCsv为准；复用扫描批次的12位随机ID，继续任务保持同名，不再新建results.csv。原始扫描表单独保留在同一功能目录，字节不改；保留原字段、逻辑行序和全部重复记录，不改原Fixed为旧自动审计证明。目录、导入与历史输入规则见[进度模板](progress.md#建议目录)。
+
+## 扫描输入列与完整证据
+
+新行为扫描表保留9列：Api Definition、Language、Changed in SDK、Affected Versions、Title、Code Location、Fixed、Change Type、Rule ID。新废弃扫描表保留8列：Api Definition、Language、Changed in SDK、Title、Code Location、Fixed、Change Type、Replacement API。以下处理列追加在实际输入原列之后；不补回移出的扫描列，历史输入则保留其全部原列。
+
+详细来源、列号、符号、废弃时间和替代依据从同批次扫描 JSON 读取；核对批次、模式、可见字段及重复计数。rowId 仍由原始字节哈希和逻辑行序号产生，行为只在内部进度、分组和报告中保存，废弃继续保留 CSV 的 Row ID 列；不用精简后的显示值去重。仅有 CSV 时按当前功能补证，无法唯一确认则记录证据缺口。
+
+## 行为结果：只追加三列
+
+在实际 scan-results-<批次ID>.csv 原列之后，仅按以下顺序追加三列；当前9列扫描表对应12列结果表。保留原始字段值、Fixed、逻辑行序和全部重复记录，不向 CSV 导出 Row ID、处理来源、业务影响、兼容性说明、变更文件、验证证据或内部状态。
+
+| 列 | 内容 |
+| --- | --- |
+| 处理结论 | 仅填写无需适配、已适配、待决策 |
+| 处理说明 | 必填本调用的具体理由；已适配同时说明已实施的相关修改及其作用 |
+| 后续事项 | 待答复、待补证据、编译或人工验证的具体事项；没有待办时留空 |
+
+内部状态与 CSV 展示分别维护，模型完成逐行判断后按下表提供结果；格式化函数不推断业务结论。
+
+| 内部状态 | 行为CSV处理结论 | 说明要求 |
+| --- | --- | --- |
+| NO_CHANGE | 无需适配 | 已核实未触发、已符合要求、仅需重编译，或用户明确接受新行为 |
+| MODIFIED | 已适配 | 已实施本行相关的获批修改；根target或无关改动不计入；不代表编译或设备通过 |
+| PENDING / DECISION_REQUIRED / EVIDENCE_GAP / OUT_OF_SCOPE | 待决策 | 说明未评估、待批准、证据不足、范围外或其他未完成原因，并写清下一步；内部状态仍分别保留 |
+
+已适配但未编译、编译失败或所需验证未完成时，在后续事项明确记录；总报告仍为部分完成。设备验证未选择时如实说明未执行，不冒充验收通过，也不擅自扩大范围。MODEL_ASSESSED、rowId、业务影响、兼容分析、变更文件和详细证据保留在进度、分组及报告中；必要的修改理由写入处理说明，未解决事项写入后续事项，不因删列丢失事实。三类适配必要性与内部六类处理状态的统计保持，不能从三个展示值反推。
+
+### 格式化接口与文件调用
+
+复用 [formatUpgradeResults](../scripts/shared/format/upgrade-results.mjs)：`formatUpgradeResults(scanBytes, results)` 返回 CSV 文本。scanBytes 必须是直接 readFile 得到的 UTF-8 原始 Buffer；results 是对象数组，每项含 `rowId`、`处理结论`、`处理说明`、`后续事项`。rowId 为该 Buffer 的完整 SHA-256 加 `:` 和从1开始的逻辑数据行序号。结果输入可以乱序，输出始终跟随扫描行序；重复扫描行仍需不同 rowId。缺失、重复、未知身份、非法结论、空理由、重复表头或已有同名处理列均报错，不能加前缀生成更多列。
+
+模型按已保存的逐行判断准备 results；可临时存为 UTF-8 JSON 数组（可带BOM）供下方文件示例读取，不建立新的适配状态协议。不要自行把 parseCsv 的 `{headers, rows}` 当二维数组，也不要用物理文本行计数。输出统一为 UTF-8 BOM 和 CRLF；输入没有 BOM 或采用 LF 时在报告注明格式规范化，原扫描字节不改，单元格内容及超链接公式保持。
+
+将下面示例保存为任务目录中的 `write-upgrade-results.mjs`，通过参数传入 skill 根目录、原扫描、逐行结果 JSON 和 outputLayout.adaptedCsv；使用 Node20/24 执行文件，避免复杂 node -e 引号和手拼 file:/// 路径。
+
+```javascript
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const [skillRoot, scanPath, resultsPath, outputPath] = process.argv.slice(2);
+if (![skillRoot, scanPath, resultsPath, outputPath].every(Boolean))
+  throw new Error('需要 skill根目录、原扫描、逐行结果JSON、输出CSV 四个路径参数');
+const shared = path.join(path.resolve(skillRoot), 'scripts', 'shared');
+const { formatUpgradeResults } = await import(pathToFileURL(path.join(shared, 'format', 'upgrade-results.mjs')).href);
+const { atomicWrite } = await import(pathToFileURL(path.join(shared, 'io', 'fs-utils.mjs')).href);
+const { samePath } = await import(pathToFileURL(path.join(shared, 'platform', 'paths.mjs')).href);
+const sourceIdentity = await realpath(path.resolve(scanPath));
+const outputIdentity = await realpath(path.resolve(outputPath)).catch(error => {
+  if (error.code === 'ENOENT') return path.resolve(outputPath);
+  throw error;
+});
+if (samePath(sourceIdentity, outputIdentity)) throw new Error('不能覆盖原始扫描表');
+const scanBytes = await readFile(scanPath);
+const results = JSON.parse((await readFile(resultsPath, 'utf8')).replace(/^\ufeff/, ''));
+const csv = formatUpgradeResults(scanBytes, results);
+try {
+  await atomicWrite(path.resolve(outputPath), csv);
+} catch (error) {
+  if (['EACCES', 'EBUSY', 'EPERM'].includes(error.code))
+    console.error(`写入失败 ${error.code}；请关闭 Excel/WPS 等占用程序后按原路径重试：${outputPath}`);
+  throw error;
+}
+```
+
+调用形式：`node "<任务目录>/write-upgrade-results.mjs" "<skill根目录>" "<原扫描CSV>" "<逐行结果JSON>" "<outputLayout.adaptedCsv>"`。调用工具时使用独立参数数组，不拼接 shell 命令。复用现有原子写入和短暂占用重试；持续失败保留旧结果及错误，不删旧表、不换批次ID、不宣称写入成功。已有结果被用户修改时仍按[原件保护](progress.md#建议目录)另存并记录真实路径。
+
+## 废弃结果：保留原有新增列
+
+| 列 | 内容 |
+| --- | --- |
+| Row ID | 输入原始CSV实际SHA-256 + 从1开始的逻辑数据行序号，不含表头 |
+| 处理结论 | PENDING / MODIFIED / NO_CHANGE / DECISION_REQUIRED / EVIDENCE_GAP / OUT_OF_SCOPE |
+| 处理来源 | MODEL_ASSESSED；不是自动SDK或语义证明 |
+| 业务影响 | 本业务中的具体变化 |
+| 处理说明 | 实际修改、无需修改理由或缺什么 |
+| 兼容性说明 | 废弃迁移的接口保护 |
+| 变更文件 | 实际相关差异，不把根target更新当每条API修复 |
+| 验证证据 | 真实命令日志、复扫、包信息或用例/截图路径；未执行写明 |
+| 后续事项 | 业务决定、证据缺口或未完成验证 |
+
+废弃输入已存在同名结果列时使用本次运行ID作为新增列前缀，明确记录，不能覆盖旧列。重复表头、格式不完整时报告并保留原件，不让Object映射静默吞列。CSV含引号、逗号、单元格换行和HYPERLINK时使用可靠解析器，可复用scripts/shared/format/csv.mjs；不要按行号拆文本或split(',')。废弃输出保持原BOM/换行格式或明确记录可验证的格式转换，语义和行序不变。
+
+## 内部状态与废弃CSV结论规则
+
+- MODIFIED：模型完成与该行相关的实质修改，有具体差异及兼容理由；仅表示已修改，不表示已验证完成。只有格式/日志/根配置变化不算该API修复。
+- NO_CHANGE：已读准确来源与真实代码，说明未触发、已符合指导或仅需重编译；不是省略用户要求的功能验证。
+- DECISION_REQUIRED：具体业务取舍、方案和影响等待决定。
+- EVIDENCE_GAP：缺来源/声明/源码/上下文或真实工具证据，说明已检查和下一步。
+- PENDING：尚未处理或相关证据/文件变化后待复核；不能用旧通过补齐。
+- OUT_OF_SCOPE：其他功能、区间或选择范围之外，明确原因，不删行。
+
+## 核对与口径
+
+输出逻辑行数必须等于输入，内部 rowId 唯一，原列逐行对应；废弃另核对 CSV 的 Row ID 列，行为不导出该列。选中范围的每行恰有当前结果，不遗漏重复行、不代填未知行。可以在任务目录临时解析/统计；行为格式化函数只校验和序列化已评估结果，不承担适配状态、业务判断或报告执行。
+
+分别报告原始行、选中行、已评估行、待处理/待决策/缺口、范围外行、去重Code Location、唯一物理文件、准确变更数和变更文件工作单元。已评估包括有明确决定或缺口的行，但问题解决数不能把这些行算成功。唯一文件按实际物理路径归一，工作单元按变更身份/版本+物理文件；注册名与srcPath不一致时按实际根配置映射。
+
+各功能只记录当前职责要求的验证状态，行为记录必要的跨系统处理及证据缺口，不新增复扫、通用接口版本匹配或自动最低设备待办；废弃无阶段比较字段。
+
+报告首页概括按CSV逻辑行统计，重复行分别计数；具体业务分类、批准记录和报告组织由所选功能主流程定义。处理结论与业务分类分别记录，不增加CSV分类列，不从MODIFIED/NO_CHANGE猜造适配必要性。
+
+零命中仍写表头与报告，编译/运行没执行就是NOT_RUN。622行可移植案例的口径为613位置、161文件、286单元、19变更；数据夹具只验证口径，不证明其所有业务适配正确。
+
+不额外增加CSV字段：行为使用处理说明和后续事项，详细编码/兼容复核及验证证据保留在分组和报告；废弃继续使用处理说明、验证证据和后续事项。有源码或构建配置修改而未成功编译时，说明部分完成/待编译或失败原因；后续源码、配置或SDK变化后，相关旧验证标待复核并安排重新构建。使用当前主流程指定的报告模板。
+
+未选择设备验证的行保留原评估结论并说明NOT_RUN，不改为OUT_OF_SCOPE。等待批准或用户暂不修改的拟修复行保留DECISION_REQUIRED及未实施原因，不因未获授权推定无需修复；具体批准与继续条件由当前主流程负责。

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

@@ -0,0 +1,105 @@
+# 行为变更报告模板
+
+仅供 `upgrade` 的 U09 使用。按[行为交付要求](../references/upgrade/upgrade-workflow.md#u09-覆盖核对与交付)核对统计与证据，使用[逐行结果](results.md)关联原始行。报告写入本功能目录的 `api-adapt-report.md` 并实际回读；真实路径替换占位符，按场景删除不适用的小节。
+
+```markdown
+# API 行为变更适配报告
+
+功能：upgrade
+工程：<实际工程>；product：<产品>；范围：<模块/目录>
+compatibleSdkVersion：<实际原值；本流程保持不变>
+targetSdkVersion：<原配置值> → <目标值>（<已实施/计划/保持不变>）
+调用点评估（CSV逻辑行）：无需适配 <N>；可选适配 <N>；必须适配 <N>
+待分类：<N>；范围外：<N>；原始行数：<N>
+总体结论：<已完成/无需修改/部分完成/待用户确认/待编译/编译失败/待业务决定；按实际证据填写>
+
+## 任务与输入
+
+- 已有用户改动及保护情况；工程、product、范围及配置现状见首页
+- 精确行为评估区间 (from,to]、HAR历史已适配基线、真实编译 SDK/IDE；历史from不能代替首页原target配置值
+- 原 CSV 与副本的完整路径、SHA-256、逻辑行数；本次已授权验证范围
+
+## 用户决定与批准范围
+
+- 目标候选及依据、用户最终目标与实际答复来源；已明确目标的沿用情况
+- 全部评估任务的返回及未完成情况、主agent合并冲突后的spec.md；全部/部分批准或暂不修改的答复；获批文件、rowIds与必要配置，未批准项及原因
+- 无需适配、可选适配、必须适配的工作单元及判断依据；未分类的业务决定和证据缺口单列
+- 已选验证方式（不运行/仅修改后验证/前后对比）、实际设备范围及用户选择的分类组合；选择全部时展开三类，未选中项保留未验证说明
+- 原before包构建/签名/归档受阻及暂停相关修改、补齐/改变验证方式的实际答复；原包已归档后的设备阻断只影响测试，分别记录
+- 方案实质变化后的重新确认，或断点继续时仍适用的历史批准；修改批准与设备选择分别记录
+
+## 扫描与覆盖边界
+
+- 实际扫描或仅导入 CSV，原扫描 JSON、coverage、diagnostics 路径
+- 后端、超时、未解析或规则缺口；规则可用性与项目命中分别说明
+- 不将零命中或当前规则集合表述为官方全量覆盖
+
+## 处理统计
+
+- 原始、选中、已评估、实际修改、无需修改、待决策、证据不足、未处理与范围外行数
+- 去重位置、唯一物理文件、变更数及变更文件工作单元分别统计
+- 全部重复行有独立 rowId；评估完成与问题解决分别说明，列出遗漏和过期结论
+
+## 行为变更：<准确规则身份、标题与版本>
+
+### 官方变化与业务触发
+
+<官方来源，旧/新行为，变更类型，受影响设备和实际消费功能；官方行为触发条件与target隔离分别说明>
+
+### 官方取材与评估
+
+- 本组规则身份、扫描JSON或历史CSV中的原始Source Reference及证据来源、Changed in SDK，当前本地章节及保留Beta/Release的精确版本；缺失来源说明实际补证与缺口
+- 本地正文实际阅读路径与行范围，覆盖原因、影响、生效条件、接口清单和适配指导；缺失范围及已检索内容另列
+- 有官方网页补充时记录本地缺口原因、准确URL、实际阅读范围、补充内容及差异；无补充说明本地资料是否满足及未补充原因，未解决冲突保留EVIDENCE_GAP
+
+### 逐文件结果
+
+| 文件、原始位置与 rowIds | 适配分类 | 处理结论 | 实际差异或无需修改依据 | 上下文及异常处理 | 验证与待办 |
+| --- | --- | --- | --- | --- | --- |
+
+逐文件关联分组reason/evidence，写出SDK默认值、属性链、实参/回调及实际触发条件的依据，未核实项列具体缺口。按需参考案例，不逐项填无关问答，不用编译成功替代业务或视觉判断。
+
+### 跨系统行为与宿主（存在相关差异时）
+
+<设备行为版本与官方target隔离分别说明；实际应用/宿主target、原compatible、必要分支或显式参数方案及理由；关联现有兼容性说明与reason/evidence，列出已验证系统和未取得的证据，不以构建通过代替低版本运行>
+
+### 业务决定与缺口
+
+<具体影响、候选方案、缺少什么及已核查内容；MODIFIED 只表示实际修改>
+
+## 编码与独立验证
+
+| 项目 | 结果 | 实际证据与限制 |
+| --- | --- | --- |
+| 行为及适用编码规范复核 | 已评估/待复核 | 逐项依据；MODEL_ASSESSED |
+| 真实 SDK 语法/类型检查 | 通过/失败/未执行 | 工具、版本、命令、日志，历史与新增问题分开 |
+| 当前源码完整编译 | 通过/失败/未执行/待复核 | product/target/ABI、输入状态、退出码、日志、产物路径/大小/SHA-256 |
+
+有源码或构建配置修改时，未取得对应当前输入的真实编译成功，只能填写部分完成、待编译或失败。修改后再次改动源码、配置或 SDK 时，旧相关成功须重新验证。编译通过不代替业务验收。
+
+## 按需场景验证
+
+- HAR：本次库产物、真实宿主 target、依赖消费路径/哈希、库与宿主构建的独立结果
+- C/C++：相关 ABI、实际编译命令、加载/链接与实际调用结果
+- 已授权设备/功能/视觉：设备与系统 API、用例和 rowIds、实际值及相关日志/图片
+- 所选分类与实际覆盖、未选中和未分类缺口分别统计；无需适配的已选条目仍报告正常功能结果，不改变原始行及修复分母
+- 包归档、before实测、after实测及有效对比分别记录；引用test-report.md、用例和原始证据，同设备系统及可复位数据方可比较
+- 修复后可生成用例并依次测试已归档before和最终after；不把两个阶段表现相同等同业务正确，新增埋点/入口及不可复位数据的限制单列
+- 本次模拟器清理给出实际结论；未执行如实说明
+
+## 后续事项与交付
+
+- 未处理、业务决定、证据不足、编译与实际功能/视觉待办，明确下一步
+- 功能目录中的原始扫描表、adapted-results-<批次ID>.csv、spec.md、按需生成的test-report.md、本报告、轻量进度，以及批次.internal和实际验证证据的完整路径
+- 文件已回读核对；逐组来源与原始行对应，已检查错误复用首行来源、丢失通道、空理由、遗漏证据与过期状态；用户修改过的交付件另存，不覆盖
+```
+
+行为 CSV 仅包含原扫描列及处理结论、处理说明、后续事项；NO_CHANGE 展示为无需适配，MODIFIED 展示为已适配，其余内部状态展示为待决策并说明具体原因。rowId、MODEL_ASSESSED、内部六类状态、兼容分析、修改文件及验证证据保留在本报告和分组中，不向结果 CSV 补列。已适配不代表已验收；待编译、编译失败或人工验证未完成须写明实际后续事项。
+
+零命中、全 NO_CHANGE、工具缺失、部分完成或停止也使用此模板。未修改场景可说明评估完成，未执行的编译或设备验证仍保留真实状态。
+
+结构校验、模型评估与工具实际执行分别说明。分组字段或报告段落齐全不能证明已读取资料；复测本skill时以实际工具调用及产物检查阅读顺序，未运行模型复测明确未实测，不把静态测试写成模型或设备验收通过。
+
+首页配置状态来自本次实际回读，尚未实施的目标写计划，保持不变如实注明，不把编译SDK或HAR历史基线当成配置升级前值。首页数量按[分组rowClassifications](../references/upgrade/upgrade-workflow.md#分类与记录)逐rowId统计，保留重复行，不从处理结论推断分类；三类＋待分类＋范围外＝原始行数。未取得统计时写未知及原因，不用占位0冒充零命中；零行时五类均为0，仍保留结果表表头与独立验证状态。
+
+行为报告记录[target升级兼容](../references/upgrade/upgrade-compatibility.md)涉及的实际处理与证据缺口，不设置复扫、通用接口版本可用性或自动最低设备任务。有跨系统差异时在分组及本报告写清兼容性说明，处理说明保留相关修改及理由，未解决部分写入后续事项，不追加兼容性CSV列；未授权设备验证写未执行，不自动扩大设备范围。