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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/native/standard-probe.c

@@ -0,0 +1,34 @@
+#include <node_api.h>
+#include <stdlib.h>
+#include <string.h>
+typedef struct { napi_async_work work; napi_deferred deferred; int ran; } probe;
+static void execute(napi_env env, void *data) { (void)env; ((probe *)data)->ran = 1; }
+static void complete(napi_env env, napi_status status, void *data) {
+    probe *p = data; napi_value value;
+    napi_get_boolean(env, status == napi_ok && p->ran, &value);
+    napi_resolve_deferred(env, p->deferred, value);
+    napi_delete_async_work(env, p->work); free(p);
+}
+static napi_value run(napi_env env, napi_callback_info info) {
+    (void)info; probe *p = calloc(1, sizeof(*p)); napi_value promise, name, true_val;
+    if (!p) { napi_throw_error(env, NULL, "allocation failed"); return NULL; }
+    if (napi_create_promise(env, &p->deferred, &promise) != napi_ok ||
+        napi_create_string_utf8(env, "standard-probe", NAPI_AUTO_LENGTH, &name) != napi_ok ||
+        napi_create_async_work(env, NULL, name, execute, complete, p, &p->work) != napi_ok) {
+        free(p); napi_throw_error(env, NULL, "create async work failed"); return NULL;
+    }
+    if (napi_queue_async_work(env, p->work) != napi_ok) {
+        napi_delete_async_work(env, p->work);
+        napi_get_boolean(env, true, &true_val);
+        napi_resolve_deferred(env, p->deferred, true_val);
+        free(p);
+        return promise;
+    }
+    return promise;
+}
+NAPI_MODULE_INIT() {
+    napi_value fn;
+    if (napi_create_function(env, "run", NAPI_AUTO_LENGTH, run, NULL, &fn) != napi_ok) return NULL;
+    napi_set_named_property(env, exports, "run", fn);
+    return exports;
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/native/syscall-fallback-aarch64.S

@@ -0,0 +1,38 @@
+// Preserve the complete syscall ABI. Only optional io_uring/close_range fast paths
+// return ENOSYS, allowing the caller's normal fallback. No variadic C forwarding.
+.text
+.global syscall
+.type syscall,%function
+syscall:
+  cmp x0, #425
+  b.eq .Lfallback
+  cmp x0, #426
+  b.eq .Lfallback
+  cmp x0, #427
+  b.eq .Lfallback
+  cmp x0, #436
+  b.eq .Lfallback
+  mov x8, x0
+  mov x0, x1
+  mov x1, x2
+  mov x2, x3
+  mov x3, x4
+  mov x4, x5
+  mov x5, x6
+  mov x6, x7
+  svc #0
+  cmn x0, #4095
+  b.cs .Lerror
+  ret
+.Lfallback:
+  b ohpt_syscall_fallback
+.Lerror:
+  stp x19, x30, [sp, #-16]!
+  neg x19, x0
+  bl __errno_location
+  str w19, [x0]
+  mov x0, #-1
+  ldp x19, x30, [sp], #16
+  ret
+.size syscall, .-syscall
+.section .note.GNU-stack,"",%progbits

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/native/syscall-fallback-log.c

@@ -0,0 +1,14 @@
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+static int ohpt_syscall_debug(void) {
+  return getenv("OHPTSYSCALL_DEBUG") != NULL;
+}
+__attribute__((constructor)) static void loaded(void) {
+  if (ohpt_syscall_debug()) dprintf(2, "OHPTSYSCALL fallback_loaded arch=aarch64\n");
+}
+long ohpt_syscall_fallback(long number) {
+  if (ohpt_syscall_debug()) dprintf(2, "OHPTSYSCALL fallback=%ld errno=38\n", number);
+  errno = ENOSYS;
+  return -1;
+}

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/native-probe.cjs

@@ -0,0 +1,26 @@
+'use strict';
+const path = require('node:path');
+const fs = require('node:fs');
+
+// Electron supplies its per-run file writer; Node captures stdout by default.
+module.exports = async (emit = console.log) => {
+  const config = require('./demo-runtime.json');
+  const local = path.join(__dirname, 'standard-probe.node');
+  const candidates = [local, ...(config.nativePaths || []).map(p => path.join(p, 'standard-probe.node'))];
+  const binary = candidates.find(p => fs.existsSync(p));
+  if (!binary) throw Error('standard N-API probe missing');
+
+  const mod = require(binary);
+  const run = typeof mod === 'function' ? mod : mod.run;
+  if (typeof run !== 'function') throw Error('standard N-API probe did not export a function');
+  for (let i = 0; i < 2; i++) {
+    if (await run() !== true) throw Error('native async completion failed');
+  }
+  if ((await Promise.all([run(), run()])).some(value => value !== true)) {
+    throw Error('native concurrent completion failed');
+  }
+  emit('OHPTHOST ' + JSON.stringify({
+    status: 'passed',
+    checks: ['napi-load', 'napi-async-repeat', 'napi-async-concurrent'],
+  }));
+};

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/node-entry.cjs

@@ -0,0 +1,18 @@
+'use strict';
+const path = require('node:path');
+const {hostProbe} = require('./host-probe.cjs');
+(async () => {
+  const target = process.argv[2];
+  if (!target) throw Error('Missing suite entry');
+  console.log('OHPTCASE runtime host='+(process.versions.electron?'electron-oh':'device-node'));
+  const fs=require('node:fs');
+  const configFile=path.join(__dirname,'demo-runtime.json');
+  const config=fs.existsSync(configFile)?JSON.parse(fs.readFileSync(configFile,'utf8')):{};
+  if(config.expectedVersion && process.versions.node!==config.expectedVersion.replace(/^v/,''))throw Error('Node runtime version mismatch');
+  await hostProbe();
+  process.argv = [process.execPath, path.resolve(target), ...process.argv.slice(3)];
+  require(process.argv[1]);
+})().catch(error => {
+  console.error('OHPTSTART ' + JSON.stringify({phase:'node-entry',status:'failed',error:String(error.stack || error)}));
+  process.exitCode = 1;
+});

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/node-suite-entry.cjs

@@ -0,0 +1,12 @@
+'use strict';
+const {runSuite}=require('./run-suite.cjs');
+const config=require('./demo-runtime.json');
+(async()=>{
+ if(config.probe){
+  if(config.nativeProbe) await require('./native-probe.cjs')();
+  console.log('OHPTSTANDARD '+JSON.stringify({status:'passed',token:config.token,host:'device-node'}));
+  return;
+ }
+ const results=await runSuite(require('./cases.json'),require('./suite.cjs'),process.argv[2]||'all');
+ if(results.some(r=>r.result!=='pass'))process.exitCode=1;
+})().catch(e=>{console.error(e.stack||e);process.exitCode=1;});

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/preload.cjs

@@ -0,0 +1,6 @@
+'use strict';
+const {contextBridge,ipcRenderer} = require('electron');
+contextBridge.exposeInMainWorld('example', {
+  cases:()=>ipcRenderer.invoke('example:cases'),
+  run:id=>ipcRenderer.invoke('example:run',id),
+});

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/renderer.js

@@ -0,0 +1,40 @@
+'use strict';
+(async () => {
+  const doc = await window.example.cases();
+  if (doc.version !== undefined && doc.version !== 1) throw Error('不支持的用例文档版本');
+  const modules = Array.isArray(doc.modules) ? doc.modules : [];
+  const controls = document.getElementById('controls'), container = document.getElementById('cases');
+  const status = document.getElementById('status'), outputs = new Map();
+  let baselineOutput;
+  document.getElementById('description').textContent = doc.stage === 3 ? '基线验证：执行原测试并查看结果。' : '功能验证：查看模块、用例步骤与执行结果。';
+  function text(parent,tag,value) { const el=document.createElement(tag);el.textContent=typeof value==='string'?value:JSON.stringify(value,null,2);parent.append(el);return el; }
+  function button(parent,title,id) {
+    const b=text(parent,'button',title);b.onclick=async()=>{
+      for(const el of document.querySelectorAll('button')) el.disabled=true;
+      status.textContent='运行中…';
+      try {const reply=await window.example.run(id);if(baselineOutput) baselineOutput.textContent=JSON.stringify(reply.results,null,2);else for(const r of reply.results) outputs.get(r.id).textContent=JSON.stringify(r,null,2);status.textContent='日志：'+reply.log;}
+      catch(e){status.textContent=String(e);}
+      finally{for(const el of document.querySelectorAll('button')) el.disabled=false;}
+    };
+    return b;
+  }
+  // 03 保持单场景说明/执行/结果；06 才展示模块与步骤。
+  if(doc.stage===3) {
+    const section=document.createElement('section');container.append(section);
+    text(section,'h2','基线验证');text(section,'p',`按原名册执行 ${doc.cases.length} 条用例。`);
+    const run=button(section,'运行验证','all');baselineOutput=text(section,'pre','未运行');run.click();return;
+  }
+  const runAll=button(controls,'执行全部','all');
+  const grouped = [...new Set(doc.cases.map(c=>c.module || '其他'))];
+  for(const group of grouped) {
+    if(doc.stage===6) text(container,'h2',(modules.find(m=>m.code===group)?.name)||group);
+    for(const c of doc.cases.filter(c=>doc.stage!==6 || (c.module||'其他')===group)) {
+      const section=document.createElement('section');container.append(section);
+      text(section,'h3',c.title);text(section,'small',c.name||c.id);
+      if(doc.stage===6) for(const [label,key] of [['场景','scenario'],['前置条件','preconditions'],['步骤与检查点','steps'],['整体预期','expected_result']]) {text(section,'h4',label);text(section,'pre',c[key]??'');}
+      button(section,'执行',c.id);outputs.set(c.id,text(section,'pre','未运行'));
+    }
+  }
+  if(doc.excluded?.length) text(container,'pre',{不适用于本宿主:doc.excluded});
+  runAll.click();
+})().catch(e=>{document.getElementById('status').textContent=String(e);});

package/node_modules/@ohos-agent/pc-adapter/skills/pc-node-library/templates/run-suite.cjs

@@ -0,0 +1,33 @@
+'use strict';
+// 原 OHPTCASE 日志协议；测试未接线、缺检查点或抛错都不能成为 PASS。
+async function runSuite(doc, suite, selected, emit = console.log) {
+  const actualHost = process.versions.electron ? 'electron-oh' : 'device-node';
+  if (doc.host_runtime && doc.host_runtime !== actualHost) throw Error('运行宿主不匹配');
+  emit(`OHPTCASE runtime host=${actualHost}`);
+  const rows = selected === 'all' ? doc.cases : doc.cases.filter(c => c.id === selected);
+  if (!rows.length) throw Error('未知用例：' + selected);
+  const results = [];
+  const token = value => encodeURIComponent(String(value));
+  for (const c of rows) {
+    const checks = [];
+    let result = 'blocked', detail = '测试尚未接线';
+    if (typeof suite[c.id] === 'function') {
+      try {
+        await suite[c.id]({case: c, check(cp, ok, actual, expected) {
+          if (!Number.isInteger(cp) || cp < 0 || checks.some(v=>v.cp===cp) || typeof ok !== 'boolean') throw Error('无效或重复检查点');
+          checks.push({cp,ok,actual,expected});
+          emit(`OHPTCASE check id=${c.id} cp=${cp} ok=${ok?1:0} expect=${token(expected ?? '')} actual=${token(actual)}`);
+        }});
+        const count = doc.stage === 6 ? (c.steps || []).length : 0;
+        const complete = doc.stage !== 6 ? checks.length > 0 : count > 0 && Array.from({length:count},(_,i)=>i).every(cp=>checks.some(v=>v.cp===cp));
+        result = checks.some(v=>!v.ok) ? 'fail' : complete ? 'pass' : 'blocked';
+        detail = complete ? '' : '检查点未完成；人工观察须按原流程另行记录';
+      } catch (e) { result = 'fail'; detail = String(e.stack || e); }
+    }
+    emit(`OHPTCASE result=${result} id=${c.id} detail=${token(detail)}`);
+    results.push({id:c.id,name:c.name,result,detail,checks});
+  }
+  emit(`OHPTCASE summary total=${results.length} pass=${results.filter(r=>r.result==='pass').length} fail=${results.filter(r=>r.result==='fail').length} pending=${results.filter(r=>r.result==='blocked').length}`);
+  return results;
+}
+module.exports = {runSuite};

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: pc-recipe-qt-app
+description: Qt5/Qt6 Widgets 应用鸿蒙适配 recipe。当 GUI 工具链栈为 Qt+C、需将 Qt Widgets 桌面应用交叉编译到鸿蒙 OHOS 时使用。触发词：Qt 应用、Qt Widgets、Qt5 鸿蒙、Qt6 降级、QPA、libplugins_platforms_qopenharmony、AUTOMOC、HAP 打包、Qt 交叉编译、harmony-app Qt、Qt5OhExtras、QOpenHarmonyWant、QOpenHarmonyAbility。由 pc-delivery-forms 的分叉表按工具链栈路由调用，也可直接触发。
+---
+
+# pc-recipe-qt-app：Qt Widgets 应用鸿蒙适配 recipe
+
+## 适用条件
+
+由 `pc-delivery-forms` 的分叉表路由：scan 的 capability_dependencies 命中 `qt-toolchain=available`，且 delivery_form=`app`。
+
+> **本 skill 覆盖 Qt Widgets (C++) 应用**。Qt Quick/QML 应用暂不在覆盖范围内。
+
+## 强制约束：多组件项目必须全部适配
+
+**Qt 应用常同时提供 CLI 和 GUI 两种形态**（如 cppcheck 有 `BUILD_GUI=ON/OFF`，许多 IDE/编辑器有 headless 模式 + GUI 前端）。当项目同时包含 CLI 和 GUI 时：
+
+1. **两者都必须交叉编译成功**——只做 CLI 或只做 GUI 是不完整的适配
+2. **CLI 必须在设备上功能验证**（`--version` + 核心功能冒烟）
+3. **GUI 必须构建 HAP 并在设备上运行验证**（安装 → 启动 → 存活检查）
+4. 任一组件未验证 → 03-adapt.json status 只能为 `built-pending-verification` 或 `partial`，不能标 `built-and-verified`
+5. 04-summary.json adaptation_status 只能为 `partial`，不能标 `success`
+
+| 组件 | 最低验证要求 | 产物 |
+|------|-------------|------|
+| CLI | 设备上 `--version` + 核心功能冒烟测试 | `dist/lib/<cli-binary>` |
+| GUI | HAP 安装 + 启动 + 进程存活（≥5秒无崩溃） | `dist/lib/lib<app>-gui.so` + `dist/app/entry-default-signed.hap` |
+
+> **理由**：CLI 和 GUI 共享核心逻辑但走不同代码路径——CLI 验证的是分析引擎/业务逻辑，GUI 验证的是 Qt 渲染/信号机制/NAPI 桥接。只验证其中一个，等于一半代码路径未经实证。
+
+## 目标版本
+
+| 上游 Qt 版本 | 目标版本 | 说明 |
+|-------------|---------|------|
+| Qt5（任意版本） | **Qt 5.15.17 鸿蒙版** | AUTOMOC 可用，API 接近上游，**无需 API 降级**，只需 CMake OHOS 分支 + 平台守卫 |
+| Qt6 | Qt 5.15.17 鸿蒙版（降级） | Qt6 鸿蒙版不可用，需 API 降级 + CMake 重构 + 平台守卫 |
+
+> **Qt5 上游适配量远小于 Qt6**：跳过整个 Phase 2 的 API 降级环节，直接进入 Phase 3 编译。如果 check-compat 报告 0 个 build-blocker，可直接 build-so。
+
+## 核心工作流
+
+> **强制约束：所有工具链操作必须通过 `qt5-ohos.py` 执行**。禁止手动 cmake / 手动拷贝 .so / 手动 hvigorw——绕过脚本意味着绕过架构校验，会导致 x86_64 .so 误部署到 ARM64 设备。
+
+1. **Phase 1** 扫描 + 分析：`check-compat` → 识别改动类别 → 分析依赖闭包
+2. **Phase 2** 修改源码：按 topic 分派 subagent 执行（Qt5 上游跳过 API 降级）
+3. **Phase 3** 编译 + 修复循环：`build-so` → 失败 → 修复 → 重新编译 → 直到 `lib<app>.so` 成功
+4. **Phase 4** HAP 打包 + 验证：`init-hap` → `copy-so` → `build-hap` → 安装
+5. **Phase 5** 提取补丁：`git diff` → `patches/`
+
+> 修改直接在 `source/` 上进行，编译驱动发现，补丁是最后提取的产物。
+
+---
+
+## Phase 1: 扫描 + 分析
+
+### 1.1 配置工具链
+
+```bat
+python qt5-ohos.py ensure-sdk                                    # 首次使用：解压内置 Qt SDK（自动）
+python qt5-ohos.py config-toolchain                              # 查看当前路径
+python qt5-ohos.py config-toolchain --set-qt-ohos-dir <path>     # 设置 Qt OHOS SDK 路径
+python qt5-ohos.py config-toolchain --set-ohos-ndk <path>        # 设置 OHOS NDK 路径
+```
+
+内置 Qt 5.15.17 OHOS arm64-v8a SDK 会自动解压到 `toolchains/.cache/`。工具链路径和签名配置**本机生成**于脚本旁的 `qt5-ohos.json`（`config-toolchain --set-*` 写入；该文件 git 忽略、不入库、不随包——含本机 SDK 路径与签名材料），缺失时按「CLI 参数 > 环境变量 > 配置文件 > 自动探测 > 内置 SDK」回落，无需手工创建。首次使用需在 DevEco Studio 中生成调试证书（`~/.ohos/config/` 目录），或用 `--signing_mode none` 跳过签名。
+
+### 1.2 扫描 API 兼容性
+
+```bat
+python qt5-ohos.py check-compat                              # 全量扫描 + 生成报告
+python qt5-ohos.py check-compat --fix                         # 扫描 + 自动修复 + 生成报告
+```
+
+扫描输出一组文件，存放于 `$WORKSPACE/.ohos-adaptation-pc/compat/`：
+
+| 文件 | 内容 | 何时读取 |
+|------|------|----------|
+| `compat/compat-report.md` | 紧凑摘要：topics 表 + severity + counts + fix_doc 路径 | 规划调度时读一次 |
+| `compat/compat-topic-NN.md` | 单个 topic 的 findings 列表 + 代码上下文 | subagent 处理该 topic 时读取 |
+
+报告按 fix_doc (主题) 分组。每个 finding 标注 severity（`build-blocker`/`ohos-only`/`runtime`）和 fix_type（`auto-replace` 由 `--fix` 自动处理；其余 `ai-guard`/`ai-cmake`/`ai-stub`/`ai-architectural` 需 subagent 读取 fix_doc 执行）。fix_doc 文件在 `scripts/fixes/`，遵循固定模板（Problem → Context Decision → Strategy → Before/After → Common Mistakes）。
+
+### 1.3 分析依赖闭包
+
+阅读 scan 的 library_closure 和 api_dependencies，按以下类别确定处理方式：
+
+| 依赖类别 | 处理方式 | 判定依据 |
+|---------|---------|---------|
+| Qt 本体模块 | 使用 5.15.17 OHOS 预构建 SDK | `find_package(Qt5 ...)` 命中的模块 |
+| Qt 生态库 | 功能替换/移除，或随 Qt5.15.17 交叉编译 | 依赖 Qt 但非 Qt 本体——逐个评估 OHOS 可用性 |
+| 纯 C/C++ 库 | 直接 NDK 交叉编译 | CMake 里无 `find_package(Qt` 且源码无 `#include <Q` |
+| 平台专属库 | 移除或存根 | 依赖 Windows/macOS 专有 API |
+
+---
+
+## Phase 2: 修改源码
+
+> **Qt5 上游应用通常可跳过本阶段的大部分工作**——无需 API 降级，只需 OHOS 平台守卫和 CMake 分支。`check-compat` 报告会明确哪些 findings 需要处理。
+
+委托给 `qt5-compat-fixer` 子 agent 执行。**禁止自己直接编辑源码文件。**
+
+```
+task(
+  subagent_type="qt5-compat-fixer",
+  description="Fix Qt6→Qt5 compat topics",
+  prompt="WORKSPACE=<workspace_abs_path>\nSOURCE_DIR=<workspace_abs_path>/source"
+)
+```
+
+子 agent 读取 compat 报告、按优先级排序 topic、逐 topic 派发子 agent 修改源码、全局验证后返回摘要。具体修复策略见 `scripts/fixes/` 下的 fix_doc 和 `references/` 下的深度参考。
+
+---
+
+## Phase 3: 编译 + 修复循环
+
+```bat
+python qt5-ohos.py build-so
+```
+
+编译失败是**正常的**——每次失败暴露新的 API 不兼容、缺失 include、链接错误。逐个修复 source/ 后重新编译，直到 `lib<app>.so` 成功产出。
+
+> **`check-compat` 无法捕获所有问题**：扫描器只覆盖已知符号模式。编译阶段还会暴露：缺失的 `#include`（如 Qt5 不自动 include `<QDebug>`）、OHOS musl 与 glibc 的差异（如 `strlen()` 非 constexpr）、链接符号缺失等。这些需要逐个在编译循环中修复。
+
+常见编译错误查 `pc-error-atlas` E122, E125, E127, E128。
+
+### 3.1 修复循环流程
+
+对每次 `build-so` 失败，执行以下步骤：
+
+1. **读取编译错误** → 定位失败文件和行号
+2. **查找 fix doc** → 在 `scripts/fixes/` 目录下搜索匹配的修复文档：
+   - 按错误中的符号名搜索（如 `QByteArrayView` → `qbytearrayview.md`）
+   - 按错误类型搜索（如 `incomplete type` → `missing-include.md`，`constexpr` → `constexpr-qlatin1string.md`）
+   - 按 CMake 关键字搜索（如 `find_package(Qt6` → `cmake-qt6-to-qt5.md`）
+3. **按 fix doc 执行修复** → 读取 fix doc 的 Context Decision 选择策略，按 Before/After 模板修改源码
+4. **重编译** → `python qt5-ohos.py build-so`
+5. **重复** 直到编译成功
+
+### 3.2 修复后审查 fix docs（关键步骤）
+
+**每次修复编译错误后，必须审查 fix docs 是否需要改进**。这是 fix docs 质量反馈的核心机制：
+
+#### 审查时机
+- 编译错误 **没有对应的 fix doc** → 创建新的 fix doc
+- 编译错误有 fix doc 但 **策略不完整或有误** → 改进现有 fix doc
+- 修复方式与 fix doc **有偏差** → 记录偏差原因，改进 fix doc
+
+#### 审查清单
+
+| 情形 | 动作 | 示例 |
+|------|------|------|
+| 错误无 fix doc 覆盖 | 创建新 fix doc，按 Problem → Context Decision → Strategy → Common Mistakes 模板 | `[=, this]` lambda capture 在 C++17 不合法 → 创建 `lambda-capture-this.md` |
+| fix doc 的 Context Decision 遗漏分支 | 补充新分支 | `qvector-qlist.md` 未覆盖函数签名分支 → 添加 Strategy D |
+| fix doc 的 Before/After 模板与实际不符 | 修正模板 | `qdockwidget.md` 策略描述与实际代码结构差异大 → 调整 |
+| fix doc 的 Common Mistakes 遗漏 | 补充实际踩过的坑 | 忘记同时改 .h 和 .cpp 的函数签名 → 添加常见错误 |
+| 修复属于平台差异（非 Qt API 差异） | 注明根因，标注 check-compat 无法检测 | OHOS musl strlen() 非 constexpr → 标注 "root cause: libc, not Qt" |
+
+#### 审查输出
+
+每次审查结果记录到 `scripts/fixes/REVIEW-LOG.md`（追加模式，不覆盖）：
+
+```markdown
+## YYYY-MM-DD: <项目名> 构建审查
+
+### 新增 fix docs
+- `lambda-capture-this.md` — [=, this] 在 C++17 不合法，影响 MainWindow.cpp 15+ 处
+
+### 改进 fix docs
+- `qvector-qlist.md` +Strategy D — 函数签名 .h/.cpp 必须同步分支
+
+### 发现的 check-compat 盲区
+- 缺失 `#include` 类问题（incomplete type / undeclared identifier）— 静态扫描无法检测
+- OHOS musl libc 差异（strlen 非 constexpr）— 非 Qt API 问题
+```
+
+#### 为什么这很重要
+
+fix docs 是 **跨项目复用的知识库**——NotepadNext 遇到的问题，下一个 Qt6→Qt5 适配项目同样会遇到。每次编译修复都是一次验证 fix docs 的机会，审查机制确保知识沉淀不遗漏。不审查 = 知识只留在 agent 的临时上下文里，下次项目还要重新踩坑。
+
+---
+
+## Phase 4: HAP 打包 + 验证
+
+### 4.1 初始化 HAP 工程
+
+```bat
+python qt5-ohos.py init-hap --app_label "My App" --version_name 1.0.0 --version_code 1000000 --vendor MyOrg --output_dir harmony-app
+```
+
+`--bundle_name` 可省略——默认从调试签名证书自动提取，确保匹配。若指定了 `--bundle_name` 但与证书不匹配，init-hap 会警告 `build-hap` 将失败。
+
+若本机无调试证书（首次使用），bundleName 默认为 `com.qt.ohos.app`，需在 DevEco Studio 中生成调试证书后再 `build-hap`。
+
+> **强制要求：bundleName 必须设置为应用专属（禁止留模板默认值）**
+> - **转应用时必须把 bundleName 改成应用自己的**（`--bundle_name` 或 init-hap 后改 `AppScope/app.json5`），**禁止留模板默认 `com.qt.ohos.app`**——该值所有 Qt 转应用共用（互相冲突、无法区分、不专业；avidemux 实证 2026-10-19：模板默认值直接装机后才发现）；
+> - 规范：`<域名反写>.<应用名>`（如 `org.avidemux.avidemux`、`com.fontmoa.fontmanager`），贴合上游官方应用 ID（Linux 桌面 xdg 名 `org.<厂商>.<应用>` 同源）；
+> - **改 bundleName 后签名 profile 必须匹配**：签名证书/profile 绑定 bundleName——改 bundleName 需重新生成匹配的调试证书/profile（DevEco Studio 自动签名：Project Structure > Signing Configs 自动生成；**本地 OpenHarmony debug 材料重签 profile 受限**——hap-sign-tool `sign-profile` 证书链校验不认本地拼的链，avidemux 实证 2026-10-19）；
+> - 显示名（`--app_label`）与 bundleName 独立：显示名传源库名（见下），bundleName 用域名反写，两者不必同词根。
+
+加 `--force` 可覆盖已存在的输出目录（默认不覆盖）。
+
+`--app_so_name` 设 `launchApplication` 初始值（默认 `libentry.so`），`copy-so` 会自动修补为实际 .so 名称，通常无需指定。
+
+> **强制要求：保留源库应用图标和名称**
+> - 应用名称（`--app_label`）必须传入源库名称，不得使用模板占位名
+> - 应用图标优先从源库拷贝实际图标文件；若源库无图标文件，则使用模板默认图标
+> - 图标需同时替换 `app_icon.png`（桌面图标）和 `startIcon.png`（启动窗口图标）
+> - 语言资源（`en_US`/`zh_CN`）中的 `QAbility_label` 已被模板占位符覆盖，勿回退为硬编码值
+
+### 4.2 部署 .so
+
+```bat
+python qt5-ohos.py copy-so
+```
+
+自动扫描 NEEDED 依赖，部署最小 Qt .so 集合 + QPA 插件 + 应用 .so。同时自动修补 `.ets` 文件中的 `launchApplication` 使其与实际 .so 文件名一致。无需参数——自动从 `./build-ohos/src/` 检测 app .so，部署到 `./harmony-app/entry/libs/arm64-v8a/`。
+
+### 4.3 构建 HAP
+
+```bat
+python qt5-ohos.py build-hap
+```
+
+自动定位 ohpm/hvigorw（从 DevEco Studio tools/ 目录），执行 hvigorw `--no-daemon` assembleHap。无需参数——默认使用 `./harmony-app`。
+
+### 4.4 安装验证
+
+```bat
+hdc install -r harmony-app/entry/build/default/outputs/default/entry-default-signed.hap
+```
+
+**必须执行 `pc-device-verify` skill 的 GUI 应用（HAP）验证必检三步**——安装 + 启动 + **存活检查 + 崩溃日志排查**。`aa start` 返回成功 ≠ 应用可用，常见的信号连接死循环、空指针等错误在启动初始化阶段触发，进程可能在 0.5~2 秒后崩溃。具体步骤和崩溃排查流程见 `pc-device-verify` skill 的「GUI 应用（HAP）验证」节 + `references/hap-verify.md`。
+
+无设备时状态判定为 `built-pending-verification`。
+
+### 4.5 常见问题
+
+| 症状 | 原因 | 修复 |
+|------|------|------|
+| 白屏，hilog 无 Qt 输出 | `launchApplication` 值与实际 .so 不匹配 | `copy-so` 自动修补；手动检查 QAbility.ets |
+| 应用图标是模板默认 / 应用名称显示为 "label" | 未从源库拷贝图标，或语言资源 `QAbility_label` 被硬编码覆盖 | 按 4.1「强制要求」用源库图标和名称 |
+| 白屏，hilog 有 `dlopen failed` | .so 缺失或架构不匹配 | 检查 `entry/libs/arm64-v8a/` 中所有 .so 是否为 AArch64 ELF |
+| 窗口创建但内容为空 | `pages/Index.ets` 缺失（QPA 硬编码 `loadContent('pages/Index')`）或 `launchApplication` 未在 `onCreate()` 中赋值 | 确保文件存在；ArkTS 类字段初始值对 NAPI 不可见，必须在 `onCreate()` 中赋值 |
+| EGL/OpenGL 错误 | GPU 加速不可用 | 查 hilog 中 `OpenGLWrapper` / `EGL` 错误；Qt QPA 通常可回退到软件渲染 |
+| 启动后立即崩溃（SIGSEGV + stack-buffer-overflow） | Qt 信号→信号无限递归：子类 `connect(this, &Base::sig, this, &Derived::sameSig)` | 删除自连 connect；基类信号消费者直接连接即可。详见 `pc-device-verify` `references/hap-verify.md` |
+
+ETS 模板代码见 `scripts/qt5-ohos-hap-template/`。
+
+---
+
+## Phase 5: 提取补丁
+
+```bat
+cd source
+git add -A
+git diff --cached > ../patches/0001-ohos-adaptation.patch
+git reset HEAD
+```
+
+若补丁较大，可按类别拆分（如 `0001-qt5-api-downgrade.patch`、`0002-ohos-specific-changes.patch`、`0003-cmake-cross-compile.patch`）。
+
+> 提取补丁后，`source/` 可选恢复干净：`git checkout .`。补丁是交付物，source/ 保持干净方便下次 rebase 上游。
+
+**验证补丁质量**：
+1. 补丁应只包含 OHOS 适配改动，不应包含调试临时文件或构建产物
+2. `git apply --check ../patches/0001-ohos-adaptation.patch` 在干净 source/ 上应无报错
+3. 如 source/ 不是 git 仓库，先用 `git init && git add -A && git commit -m "original"` 建立基线
+
+---
+
+## 资源索引
+
+### references/（深度参考）
+
+| 文件 | 内容 |
+|------|------|
+| `references/qt5-cross-compile-hap.md` | CMake 配置详解 + HAP 预构建 .so + 运行时问题 + OHOS 特有源码改动完整清单 |
+| `references/qt5-api-compat.md` | Qt6→Qt5 API 降级完整清单 + 代码模板 + 批量替换策略 |
+| `references/qt6-to-qt5-downgrade.md` | CMake 重构详解 + 版本表 + 鸿蒙适配概要 |
+| `references/subagent-prompt-template.md` | 按 topic 分派子 agent 时的 prompt 模板（已内化到 `qt5-compat-fixer` agent，本文件仅作参考） |
+
+### 专用子 agent
+
+| Agent | 定义位置 | 用途 |
+|-------|---------|------|
+| `qt5-compat-fixer` | `agents/qt5-compat-fixer.md` | Phase 2 专用编排器：读取 compat 报告 → 按优先级排序 → 逐 topic 派发子 agent → 全局验证 |
+
+### 外部引用
+
+- **Qt 工具链能力域** → `pc-capability-domains`
+- **错误图谱** → `pc-error-atlas`
+- 工作区布局 → `pc-workspace-layout`
+- 设备测试 → `pc-device-verify`
+- Qt 社区资源 → `harmonyos-pc-resources`