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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-PixelTune-/345/255/220/350/277/233/347/250/213Python/345/272/224/347/224/250.md

@@ -0,0 +1,149 @@
+---
+name: 鸿蒙PC-PixelTune-子进程Python应用
+description: PixelTune（鸿蒙 PC 图像处理应用）——ArkTS-UI 应用内嵌 Python/Pillow 作计算后端的通用式（子进程 / 方案A）：HNP 打 Python+库 + forkpty 子进程 + NAPI execSync 桥 + argv/JSON-stdout 契约；把任意 Python 库封装成一组命令即可复用到别的库
+metadata:
+  type: adaptation
+  source: PixelTune 社区参考应用（gitcode OpenHarmonyPCDeveloper/PixelTune，从源码 + docs/TUTORIAL.md distill）
+---
+
+PixelTune（HarmonyOS Next / 2in1，API 23）用 **ArkTS 做 UI、Python + Pillow 做图像处理后端**：JPEG 压缩、格式转换、亮度/对比度/饱和度/旋转/水印/EXIF。它不链接 `libpython`，而是把 Python 打成 **HNP** 随应用分发，C++ 桥用 `forkpty` 拉起 `python` 子进程跑脚本，结果经 **stdout 约定 JSON** 回传——这是[嵌入 Python 运行时指南](../../harmonyos-pc-resources/references/contribute/develop-guide/鸿蒙应用嵌入Python运行时-ArkTS与CPython混合开发实战.md) **§七「方案 A：子进程调用」**的端到端落地样例。
+
+> ⚠️ **本案例知识 distill 自社区参考应用 PixelTune 的源码与教程，非本仓真机回归**（区别于 [[鸿蒙PC-pyGLFW-Python绑定库迁移]] 的真机端到端）。照此复刻后须自行在设备上验证。设备 Python 运行时/ABI 见 [[鸿蒙PC-设备Python运行时]]，子进程在 app 域执行二进制的约束见 [[鸿蒙PC-app域执行二进制与JIT限制]]，沙箱物理路径见 [[鸿蒙PC-应用沙箱与物理路径映射]]。
+
+**与"进程内嵌入"（方案B）和 pyGLFW 的分野**：方案B / pyGLFW 都在**本进程内** `Py_Initialize` 跑 Python（pyGLFW 还要 ctypes 回调驱动 OWB 窗口，属"绑定库"）；PixelTune 走**独立子进程**——Python 只当算子、崩溃不拖垮 UI，代价是每次调用一趟进程启动 + IPC。**"用某个 Python 库做一段计算/处理"的应用需求，绝大多数走这条。**
+
+## 通用式（任何"应用内用 Python 库做计算"照抄）
+
+把库能力封装成一组**命令行子命令**，用**进程边界 + JSON 文本**做接口，五步：
+
+1. **HNP 打包**：解释器 + 标准库 + 目标三方库（Pillow/…）装进一个目录 → `hnpcli pack` → `hnp/arm64-v8a/*.hnp`，随 HAP 分发、装机自解压。
+2. **C++ 桥**：`forkpty`/`fork` 起 `python` 子进程，`poll` 采集 stdout。
+3. **NAPI**：把"执行命令拿输出"包成一个同步方法 `execSync(cmd): string` 暴露给 ArkTS。
+4. **Python 契约**：脚本 `sys.argv` 分发子命令，`print(json.dumps(...))` 输出——**接口 = argv 入、JSON 出**。
+5. **ArkTS**：`rawfile` 脚本拷到 `filesDir` → 拼命令 `execSync` → `JSON.parse`。
+
+**换库只改第 1 步（HNP 里装什么）和第 4 步（脚本暴露哪些子命令）**，2/3/5 是死骨架。
+
+## 1. HNP 打包 Python + 三方库
+
+```bash
+# 目录内备好 python 可执行 + 标准库；装目标库（源用社区 PyPI，见 pc-registry central-registry）
+./python3.12 -m pip install Pillow \
+  --index-url https://pypi.cnb.cool/OpenHarmonyPCDeveloper/pypi/-/packages/simple
+# 打 HNP（放进工程 hnp/arm64-v8a/，hvigor 会随 HAP 打包、装机自解压到应用私有 HNP 目录）
+hnpcli pack -i <python_dir> -o <out_dir>
+```
+
+`hnp/arm64-v8a/python.hnp` 装机后解压，`python` 可执行进 PATH（经 `/bin/sh -c` 调用即可命中）。含 C 扩展的库（Pillow 的 `_imaging` 等）必须是**鸿蒙 aarch64 编译版**（ABI 见 [[鸿蒙PC-设备Python运行时]]）；纯 Python 库直接装。
+
+## 2. C++ 桥：forkpty 子进程 + PTY 采集
+
+```cpp
+// shell_exec.cpp（要点版）
+ExecResult shellExecSync(const std::string& command) {
+    int masterFd;
+    struct winsize ws = { .ws_col = 120, .ws_row = 40 };
+    pid_t pid = forkpty(&masterFd, nullptr, nullptr, &ws);
+    if (pid == 0) {                                  // 子进程
+        setenv("HOME", "/storage/Users/currentUser", 1);   // 探测 userId，勿硬编个人目录
+        execl("/bin/sh", "sh", "-c", command.c_str(), nullptr);
+        _exit(127);
+    }
+    // 父进程：poll(masterFd) 轮询——先 500ms 查子进程状态，再 100ms 收输出，直到退出
+    // 收完 close(masterFd)；PTY 会掺入控制字符 → cleanPtyOutput() 清洗后再回传
+    ExecResult result;
+    result.output = cleanPtyOutput(rawOutput);
+    return result;
+}
+```
+
+- 用 `forkpty` 而非裸 `fork`+pipe：许多 CLI 在非 tty 下缓冲策略不同，PTY 更贴近交互行为；代价是要 `cleanPtyOutput` 剥掉 ANSI/控制字符。**只要脚本输出规整 JSON，也可以用 `fork`+`pipe` 省掉清洗**（更简单，见指南 §7.2 骨架）。
+- 经 `/bin/sh -c` 而非直接 `execl(python,...)`：继承 HNP 注入的 PATH，直接写 `python ...` 即可。
+- app 域对 `exec` 有策略约束（见 [[鸿蒙PC-app域执行二进制与JIT限制]]）——HNP 内二进制在应用私有目录，属允许路径。
+
+## 3. NAPI 暴露给 ArkTS
+
+```cpp
+// napi_bridge.cpp（要点版）
+static napi_value ExecSync(napi_env env, napi_callback_info info) {
+    size_t argc = 1; napi_value args[1];
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+    char buf[4096]; size_t len;
+    napi_get_value_string_utf8(env, args[0], buf, sizeof(buf), &len);
+    ExecResult r = shellExecSync(std::string(buf, len));
+    napi_value ret; napi_create_string_utf8(env, r.output.c_str(), r.output.size(), &ret);
+    return ret;
+}
+static napi_module pixeltune_module = {
+    .nm_version = 1, .nm_register_func = Init, .nm_modname = "pixeltune_native",
+};
+```
+
+同步 `execSync` 够用（图像处理是一次性算子）；耗时任务应改异步 NAPI（`napi_create_async_work`）避免卡 UI 线程。
+
+## 4. Python 侧：argv 子命令 + JSON stdout 协议
+
+```python
+# image_processor.py（放 entry/src/main/resources/rawfile/）
+import sys, json
+def cmd_pipeline(input_path, output_path, config_path):
+    with open(config_path) as f: cfg = json.load(f)      # 复杂参数走 JSON 配置文件，绕开 argv 长度/转义
+    from PIL import Image
+    img = Image.open(input_path)
+    # ... Resize/Rotate/Flip/亮度对比度/滤镜/灰度/水印/Save ...
+    print(json.dumps({"success": True, "output": output_path, "steps": steps}))
+
+if __name__ == '__main__':
+    cmd = sys.argv[1]
+    if   cmd == 'info':     cmd_info(sys.argv[2])
+    elif cmd == 'compress': cmd_compress(sys.argv[2], sys.argv[3], sys.argv[4])
+    elif cmd == 'pipeline': cmd_pipeline(sys.argv[2], sys.argv[3], sys.argv[4])
+```
+
+**协议就是这层 argv/JSON**：简单参数直接 argv，复杂参数（一串处理步骤）写成 JSON 配置文件传路径。stdout 只吐一行 JSON，ArkTS `JSON.parse` 即得结构化结果。异常也应 `json.dumps({"success": False, "error": ...})` 而非抛栈，便于上层判定。
+
+## 5. ArkTS 侧：释放脚本 → 拼命令 → 解析
+
+```typescript
+import shellNative from 'libpixeltune_native.so';
+
+// 首次运行把 rawfile 脚本拷到可执行的 filesDir
+private prepareScript(): string {
+  const dest = this.context.filesDir + '/image_processor.py';
+  const content = this.context.resourceManager.getRawFileContentSync('image_processor.py');
+  const f = fs.openSync(dest, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
+  fs.writeSync(f.fd, content.buffer); fs.closeSync(f);
+  return dest;
+}
+
+// 复杂参数落成 JSON 配置文件，再拼命令
+const configPath = this.context.filesDir + '/pipeline_config.json';
+fs.writeSync(fs.openSync(configPath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE).fd, configJson);
+const cmd = `python "${scriptPath}" pipeline "${inputPath}" "${outputPath}" "${configPath}"`;
+const parsed = JSON.parse(shellNative.execSync(cmd).trim());
+```
+
+`inputPath`/`outputPath` 由 `DocumentViewPicker` 选出的 uri 转真实路径；产物落应用私有可写目录（如 `/data/storage/el2/base/files/`）。
+
+## 6. 权限（module.json5 ACL）与沙箱路径
+
+PixelTune 声明的 ACL（子进程 + HNP 独立库加载所需，**较激进，逐条评估必要性、能删则删**）：
+
+```json5
+"requestPermissions": { "acl": {
+  "ALLOW_EXTERNAL_NATIVE_CODE": true,   // 执行 HNP 内的 python 等外部原生二进制
+  "LOAD_INDEPENDENT_LIBRARY": true,     // 加载应用打包体系外的独立 .so（HNP lib）
+  "ALLOW_WRITABLE_CODE_MEMORY": true,   // 仅当子进程内有 JIT/可写代码页才需要（纯 CPython 解释执行通常可去掉）
+  "DISABLE_CODE_MEMORY_PROTECTION": true
+}}
+```
+
+关键沙箱路径：HNP `hnp/arm64-v8a/*.hnp`；脚本释放目标 `context.filesDir`（`/data/storage/el2/base/haps/entry/files/`）；产物 `/data/storage/el2/base/files/`。userId 因设备而异，`HOME` 等按设备探测，勿硬编个人目录（见 [[鸿蒙PC-应用沙箱与物理路径映射]]）。
+
+## 复用要点 / 边界
+
+- **迁到别的库**：第 1 步 HNP 里换成目标库（纯 Python 零成本；含 C 扩展的先按 `pc-delivery-forms/references/languages/python.md` 交叉编译好再装进 HNP），第 4 步把库能力拆成子命令。骨架 2/3/5 不动。
+- **选 A 还是 B**：需要与 ArkTS 高频双向调用、对每次进程启动 + IPC 开销敏感 → 方案B（进程内）；否则 A。图像/数据/AI 预处理这类"喂进去、算完拿回来"是 A 的甜区。
+- **同步 vs 异步**：重任务用异步 NAPI，别用 `execSync` 卡 UI。
+- **未验证项**：本案例未做本仓真机回归；`forkpty` 在 app 域的行为、Pillow C 扩展的鸿蒙 wheel 完整性需按目标设备实测。
+- **已真机实证的子集（2026-07-23，`ohpt-agent scaffold --kind python-app-subprocess` 模板）**：`fork`+pipe 经 `/bin/sh -c` 拉起 python 子进程、stdout JSON 回传 UI 全链路通过；且 **app 进程 PATH 含公共 HNP（`/data/service/hnp/bin/python3.12` 直接可达可 exec，无需 ACL、无需自带 HNP）**——设备已有公共 Python 时可跳过第 1 步 HNP 打包（要分发自己的库/解释器版本时仍走 HNP）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Poco-C++/347/261/273/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221/344/270/216/350/256/276/345/244/207/351/252/214/350/257/201.md

@@ -0,0 +1,94 @@
+---
+name: 鸿蒙PC-Poco-C++类库交叉编译与设备验证
+description: POCO C++ Libraries v1.15.3（30+ 组件大型 C++ 类库）交叉编译到鸿蒙 PC 并真机验证 9/9 testrunner 全过的完整经验：组件裁剪绕 OpenSSL、musl 线程亲和补丁、CMake toolchain 绕 Windows 路径空格、私有 HNP 执行器跑 9 个 CppUnit testrunner、可写 cwd / POCO_BASE 测试数据随包、static-init 崩溃（NamedEvent/NamedMutex 的 sem_open）、DirectoryWatcher inotify→轮询、进程/fork+exec/共享内存/命名 IPC/UDP 服务端/Unix 域套接字等平台受限测试跳过注册。触发词：Poco、POCO、CppUnit、testrunner、组件裁剪、OpenSSL 瓶颈、ENABLE_CRYPTO、FastLogger、Quill、pthread_setaffinity_np、命名信号量、sem_open、NamedEvent、NamedMutex、SharedMemory、DirectoryWatcher、inotify、可写 cwd、POCO_BASE、测试数据随包、static-init 崩溃、进程受限、fork exec、Unix 域套接字、SQLChannel。
+metadata:
+  type: adaptation
+  source: new/PC + Poco 1.15.3（2026-09）
+---
+
+# 鸿蒙 PC：Poco C++ 类库交叉编译与设备验证
+
+Poco 是一套 30+ 组件的大型 C++ 类库。本轮把核心 9 组件交叉编译到鸿蒙 PC 并在真机跑通全部 CppUnit testrunner。
+
+## 组件裁剪（绕开 OpenSSL 瓶颈）
+
+Poco 的 Crypto/NetSSL/JWT 三组件依赖 OpenSSL（未适配鸿蒙）。裁剪方案：
+`POCO_MINIMAL_BUILD=ON` + 关闭 `ENABLE_CRYPTO/NETSSL/JWT/PDF` + 逐组件开启 9 个核心组件
+（Foundation/Encodings/XML/JSON/Net/Util/Data/DataSQLite/Zip）。bundled 依赖
+（zlib/pcre2/utf8proc/expat/sqlite3/v8_double_conversion/pdjson/tessil/quill/cpptrace）自动 recipe-build，
+无需额外配置。FastLogger（Quill）因 Poco 顶层 CMakeLists 的 `CMAKE_SYSTEM_NAME` 平台自检自动关闭，无需补丁。
+
+- 关闭不合理默认 ON 的组件避免 OpenSSL 构建依赖；CMake 的 `find_package(OpenSSL)` 在关闭组件时不触发，不阻塞。
+- Crypto/NetSSL/JWT 套件进 exemptions[]（platform-exclusive-api），证据指向 `source/CMakeLists.txt:172 (find_package(OpenSSL))`。
+
+## 构建（CMake toolchain 绕路径空格）
+
+Windows 宿主 NDK 装在 `Program Files`（含空格），官方 `aarch64-unknown-linux-ohos-clang` 封装脚本
+`exec $SOURCE/clang` 未加引号断裂。改用 NDK 官方 `ohos.toolchain.cmake` 直调 clang.exe（CMake 内部处理引号）。
+
+```bash
+cmake -G Ninja -S source -B build/cmake-build \
+  -DCMAKE_TOOLCHAIN_FILE="<NDK>/build/cmake/ohos.toolchain.cmake" -DOHOS_ARCH=arm64-v8a \
+  -DPOCO_MINIMAL_BUILD=ON -DENABLE_TESTS=ON ...（9 组件 ON，Crypto/NetSSL/JWT/PDF 等 OFF）\
+  -DCMAKE_SHARED_LINKER_FLAGS="-Wl,--code-sign"   # 链接期自签，app 域 dlopen 必需
+```
+
+补丁：
+- `0001`：`pthread_setaffinity_np`→`pthread_gettid_np + sched_setaffinity`（musl 无 glibc 亲和扩展，功能保留替换）。
+- `0002`：测试内 file-scope `static NamedEvent/NamedMutex` 改 Meyers 懒构造（见下「static-init 崩溃」）。
+- `0004`：`DirectoryWatcher` OHOS 下 inotify→轮询（见下「inotify 崩溃」）。
+- `0005`：进程/fork+exec/共享内存/命名 IPC、UDP/HTTP 服务端/FTP/邮件/WebSocket/Unix 域套接字等平台受限套件 `#if !defined(__OHOS__)` 跳过注册；CoreTest 的 `osName=="Linux"` 断言放宽为 HarmonyOS。
+- `0006`：`cppignore.lnx` 补 SQLChannel/SQLLogger/Async、Unix 域套接字等 OHOS 受限用例。
+
+## 设备验证（私有 HNP 执行器跑 9 个 CppUnit testrunner）
+
+9 个 `*-testrunner` + `libPoco*.so`（含 SONAME 别名 `.so.123`）+ `libCppUnit.so.1` + `libc++_shared.so`
+打包进私有 HNP，经执行器 HAP 在 app 域 fork/execv 跑，输出经 hilog 回传。最终 9/9 全过
+（`OHPTCASE summary total=9 pass=9 fail=0`）。
+
+### 关键 harness 坑（按踩坑顺序）
+
+1. **只读 HNP bin cwd → 文件创建失败**：testrunner 默认在 HNP 只读 `bin/` 目录跑，测试往 cwd 写文件
+   （XML 的 `rss.xml`、Util 的 `TestConfiguration`、Zip 压缩产物、DataSQLite 的 `dummy.db`）报
+   `FileAccessDeniedException`。**每用例在应用沙箱可写目录（`files/pocorun-run/<case>/`）跑**，测试数据
+   （`cppignore.lnx`、`testdata.txt`）逐字节拷进该 cwd。
+2. **POCO_BASE 测试数据回退根**：JSON/Zip 测试在 cwd 找不到 `data/` 时回退
+   `$POCO_BASE/<Module>/testsuite/data/...`。设 `POCO_BASE` 指向 HNP 装机根，测试数据随包打在同构路径。
+3. **static-init 崩溃**：`static NamedEvent testEvent("TestEvent")` 在静态初始化期调 `sem_open`，app 域命名
+   信号量不可用→抛 SystemException 未捕获→进程在 `main()` 前 terminate。改函数局部 static（Meyers）延迟构造。
+   详见 [[鸿蒙PC-app域命名POSIX信号量受限]]。
+4. **DirectoryWatcher inotify 线程崩溃**：`DirectoryWatcher` 走 inotify，其内部线程抛未捕获异常崩溃。改用
+   `#if !defined(__OHOS__)` 走 Polling 策略即正常。⚠️ 这是 Poco 实现特有（inotify 错误路径在线程里 rethrow），
+   不代表 inotify 在 app 域一概可用/不可用（@parcel/watcher 用 inotify 成功）——本库改轮询是最省事的兜底。
+5. **大套件看门狗超时**：Foundation/DataSQLite 近千用例 + 多处 sleep，默认 90s alarm 不够 → 每用例可配
+   timeout（Foundation/DataSQLite 300s）。**孙进程持续输出挂死 worker**：Net 的 HTTP 服务端子进程在 alarm
+   杀父后仍周期写 stdout，poll 每次读到就重置超时永不到期——改**绝对截止**（alarm + 余量，不重置）。
+6. **hilog 缓冲过滤**：全量 RAW dump 会把 hilog 缓冲挤爆、早先用例的失败被滚掉。只回传「用例分界 + 失败/错误 + 汇总」行，
+   完整 raw 写 `run-raw.log`。
+7. **跳过 ≠ 忽略结果**：CppUnit 的 `-ignore` 只忽略失败/错误的**上报**、不阻止用例**执行**——挂死/崩溃类用例
+   必须 source 级 `#if !defined(__OHOS__)` 跳过 `suite()` 注册，靠 cppignore 拦不住崩溃。
+
+### 平台受限能力清单（app 域，全部跳过注册/豁免）
+
+进程（`Process::launch` fork+exec）、命名信号量（`sem_open`）、命名 IPC、
+UDP/HTTP 服务端监听、FTP/SMTP/POP3 外网、WebSocket、Unix 域套接字（AF_UNIX bind EPERM）、
+SQLChannel 异步。这些与 Crypto/NetSSL/JWT（OpenSSL）豁免同一套法：测试层明确跳过并留 evidence。
+（`SharedMemory` 随进程/IPC 套件一并跳过，但 `shm_open` 本身未证实受限——只有 `sem_open` 是实证受限的，见 [[鸿蒙PC-app域命名POSIX信号量受限]]。）
+
+## 测试线 demo 接线坑（cpp-lib-demo NAPI 壳，2026-09-12）
+
+主流程全绿后，测试线（阶段 6）的 cpp-lib-demo 功能验证跑出 6 处 checkpoint `ok=false`——**全部是 demo 接线对 POCO API 语义的理解错（harness-defect），不是库缺陷**（详情见 `pc-error-atlas` E155）：
+
+1. **`Poco::File::renameTo()` 就地更新对象路径**：rename 后原 `File` 对象的 `exists()` 仍 true。断言「旧路径不存在」要用独立构造的旧路径对象，别复用执行过 renameTo 的原对象（F-01-02）。
+2. **`DateTimeParser::parse` 返回 UTC**：`LocalDateTime` 格式化的字符串解析回后差一个时区偏移（UTC+8 = 8h）。回比前必须扣除 parse 回传的 `tzd`（F-01-05）。
+3. **`RegularExpression::match(string)` 是全串锚定**：对 `"date: 2026-09-12 ok"` 返回 false；部分搜索用带 pos 重载 `match(input, pos)`，或直接用 `extract()`（F-01-09）。
+4. **SQLite 持久化用例残留**：`CREATE TABLE IF NOT EXISTS` + 每次插入，重跑即行数翻倍（rows=4 而非 2）。setup 先 `DROP TABLE IF EXISTS` 或删 DB 文件（F-06-02）。
+5. **压缩率断言数据太小**：20B 文件 ZIP 后 142B（头部开销 ~100B+）。压缩率验证用 ≥1KB 数据（F-08-01）。
+6. **Glob 沙箱路径未命中**：`Glob::glob(base + "/*.txt")` 在 app 域沙箱返回 0 结果（F-01-03，根因未完全定性，用 DirectoryIterator + 后缀过滤兜底）。
+
+教训：demo 接线者要按「对象状态 / 时区 / 正则语义 / 持久化清理 / 数据量级」五维自查；这些已沉淀为 `pc-test-design/references/demo-wiring-pc.md` §4 通用防坑清单，下次同类库直接照单检查。
+
+## 归档
+
+关联：[[鸿蒙PC-POSIX系C++类库交叉编译与设备验证]]、[[鸿蒙PC-app域命名POSIX信号量受限]]、
+[[鸿蒙PC-app域测试前置条件矩阵]]、[[鸿蒙PC-真机跑官方测试套件]]、[[鸿蒙PC-私有HNP打包与exec平台差异]]。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-PyGObject-introspection/344/272/244/345/217/211/347/274/226/350/257/221/345/242/231.md

@@ -0,0 +1,32 @@
+---
+name: 鸿蒙PC-PyGObject-introspection交叉编译墙
+description: Zenmap 需要的 PyGObject/gobject-introspection 在 macOS→OHOS 交叉编译走不通的根因与可行替代
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+2026-06-26 推进 Zenmap（GTK3+PyGObject 应用）时确认：**在 macOS host 上交叉编译 gobject-introspection / PyGObject 到鸿蒙 OHOS 走不通**，这是 Zenmap-proper 落地的硬墙。先记下来避免重复撞。
+
+## 为什么走不通
+PyGObject(`gi` 模块) 运行需要 **gobject-introspection 的 `.typelib`** 文件（描述 GLib/GObject/Gio/Gtk-3.0/Gdk-3.0/Pango/GdkPixbuf/Atk 等的 API）。这些 typelib 由 `g-ir-scanner` 生成，而 g-ir-scanner：
+- 是 host 端 Python 工具，**import 一个 C 扩展 `_giscanner`**（必须在 build 机 = macOS 上能加载 → 必须是 macOS 原生 .so）；
+- 同时要**编译并运行一个 target probe** dump 目标库的枚举/类型值（→ 需要在设备上跑，exe_wrapper 可解决）。
+meson 交叉构建默认把 `_giscanner` 编成 **target(aarch64)**，host(macOS) 的 python 没法 import → 报 `Python dependency not found` / 找 `python-3.9.pc`（误用 host Xcode python）。这就是 GNOME 跨平台圈子公认最难的一块；Yocto/buildroot 靠大量 patch 或**原生 aarch64 Linux 环境**先编 gi 才绕过。
+
+## 两条本地路都堵死
+1. **macOS 交叉编译 gi**：host/target `_giscanner` 劈叉（上述），meson 原生不支持，需重度 patch。
+2. **设备上原生编译**：设备**没有可用 C 编译器**（`python -c sysconfig CC` 报 `cc` 但 `which cc` 不存在、`cc t.c` 报 inaccessible；与 [[鸿蒙PC-设备Python运行时]] "设备 clang wrapper 失效" 一致）。所以没法在设备上跑 g-ir-scanner 生成 typelib，也没法 pip 编 PyGObject（无 wheel：`pip download PyGObject` → no matching distribution）。
+
+## 已搭好但没用上的基础设施
+- exe_wrapper（`gtk-from-source/ohos-exe-wrapper.sh`）：把 target aarch64 二进制推设备跑、代理 stdout/exit，**本身工作正常**（trivial 程序验证 exit code 透传 OK）。可用于其他需要"跑 target 程序"的交叉构建步骤，只是解决不了 _giscanner 的 host/target 劈叉。
+- 设备 Python dev：`libpython3.12.so`+headers 已拉到 prefix，`python-3.12.pc`/`python3-embed.pc` 已造好。
+- libgirepository-2.0：glib 2.80+ 自带，已编进 prefix（运行时加载 typelib 用，但没 typelib 就没意义）。
+
+## 可行替代（交付"nmap 图形界面"的务实路线）
+GTK 这套 C 库栈本身在鸿蒙跑得很好（[[鸿蒙PC-GTK应用broadway-ArkWeb-HAP]] 已真机交互成功）。要给 nmap 做 GUI，绕开 PyGObject：
+- **A. GTK C 前端**：用 C/GTK3 写一个 Zenmap 式前端（target/ports 输入 → 调私有 HNP 的 nmap → 解析 XML → 展示），套进已验证的 broadway+ArkWeb 壳。是真正的 GTK GUI，无需 introspection。
+- **B. ArkUI 原生前端**：直接用 ArkTS 增强 [[鸿蒙PC-nmap-autotools交叉编译与真机扫描]] 里那个 HAP（已能扫描出结果），加 profile/拓扑/历史。最贴鸿蒙原生、最省事。
+- **C. 真 Zenmap**：需要一台**原生 aarch64 Linux**（Docker/VM/云）先把 gobject-introspection + 各库 typelib + PyGObject 编出来，再拷到设备。本会话环境(macOS)不具备，是独立前置工程。
+
+结论：**Zenmap 的 Python 代码本身不难，难在 PyGObject 的 typelib 依赖**。短期交付选 A 或 B；要原汁原味 Zenmap 走 C（需 aarch64 Linux 构建环境）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Python-C/346/211/251/345/261/225/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,42 @@
+---
+name: 鸿蒙PC-Python-C扩展交叉编译
+description: 用 OHOS NDK clang 把 CPython C 扩展交叉编译成 .cpython-312.so 部署到设备 Python 的通用套路，以 pycosat 为例
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+把 CPython 的 C 扩展（`Extension(sources=[...])`）适配到鸿蒙PC = 用 OHOS NDK clang 按设备 Python 3.12 的 ABI 交叉编译出 `.cpython-312.so`，推到设备 import。运行时是 [[鸿蒙PC-设备Python运行时]]（3.12.8，hnppublic HNP）。以 pycosat@0.6.6（封装 PicoSAT，`pycosat.c` 里 `#include picosat.c`，无外部依赖）为例，**1 处源码改动**，30 个官方测试真机全过。
+
+## 编译命令（核心）
+
+```bash
+NDK=$DEVECO_SDK_HOME/default/openharmony/native   # DEVECO_SDK_HOME 见 SKILL.md「定位 DevEco SDK」
+CLANG=$NDK/llvm/bin/aarch64-unknown-linux-ohos-clang
+PYINC=./device-python/include/python3.12   # 含 Python.h；从设备 hdc file recv 拉来（勿用尖括号占位）
+PYLIB=./device-python/lib                   # 含 libpython3.12.so
+
+$CLANG -fPIC -shared -O2 -DNDEBUG -I"$PYINC" \
+  module.c -L"$PYLIB" -lpython3.12 -o module.cpython-312.so
+$NDK/llvm/bin/llvm-strip module.cpython-312.so   # strip 收益可观（pycosat 80K）
+```
+
+## 关键要点（踩过/确认过）
+
+1. **头文件/libpython 从设备拉**：`hdc file recv $PYROOT/include/python3.12` 和 `$PYROOT/lib/libpython3.12.so` 到 Mac（`$PYROOT` 见 [[鸿蒙PC-设备Python运行时]]）。不要用 archives 里重建的，要和设备实际跑的 ABI 完全一致。
+2. **必须链接 `-lpython3.12`**：musl BIND_NOW 下扩展要显式链接 libpython（对应 archives 的 E078/BIND_NOW 经验）。产物 NEEDED 会有 `libpython3.12.so.1.0` + `libc.so`，运行时由已加载的解释器满足，import 正常。
+3. **EXT_SUFFIX 必须是 `.cpython-312.so`**：CPython 按这个后缀找扩展；命名错（如 `.so`）import 时找不到。设备 `sysconfig.get_config_var('EXT_SUFFIX')` 确认。
+4. **dlopen 的扩展无需 ELF 签名**：和可执行二进制不同，解释器 dlopen 加载的 `.so` 不需要 `binary-sign-tool`。pycosat 未签名直接 import 成功。（与 [[鸿蒙PC-HNP二进制SELinux-exec限制]] 的 exec 限制是两回事——那是 fork/exec，这是 dlopen。）
+5. **`<sys/unistd.h>` 不存在**：musl/OHOS 只有 `<unistd.h>`。这类 legacy BSD 头要 `#ifdef __OHOS__` 守卫切换（铁律 P-PATCH-002）。pycosat 唯一改动就是这个（picosat.c 的 NGETRUSAGE 块）。
+
+## 验证套路
+
+`hdc file send module.cpython-312.so /data/local/tmp/mymod/` → 设备上 `PYTHONPATH=/data/local/tmp/mymod $PY -c 'import x; ...'`（`$PY`=设备 python 绝对路径，见 [[鸿蒙PC-设备Python运行时]]）。
+有官方 `test_*.py` 就一并推上去 `PYTHONPATH=. python test_x.py` 整套跑——比手搓几个 case 更有底。
+
+## 反模式
+
+- ❌ 用 Mac/Linux 本地 python 的头文件编 → ABI 不符，import 时 `undefined symbol` 或段错。
+- ❌ 在设备上 `pip install`（源码包）现编 → 设备无 NDK，且会落到 manylinux 不匹配走 sdist 失败；交叉编译在 Mac 上做。
+
+下一步把 numpy 头文件也纳入同套路 → PyWavelets。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Qt6-CMake-GUI/345/272/224/347/224/250/347/247/273/346/244/215.md

@@ -0,0 +1,110 @@
+---
+name: 鸿蒙PC-Qt6-CMake-GUI应用移植
+description: 把 Qt6/CMake 桌面 GUI 程序（以 NotepadNext 为例）移植到鸿蒙 PC 并真机跑起来的完整套路：qt.toolchain.cmake 直接 CMake 交叉编译、patch Qt6CoreMacros 让 qt_add_executable 产出 dlopen 用的 .so、qrc 资源两连坑、复用模板打签名 HAP
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：Qt6 CMake GUI 应用移植要点
+
+来自把 **NotepadNext**（Qt6/CMake 的 Notepad++ 替代品）移植到鸿蒙 PC 并真机跑起来（2026-06-23，HUAWEI MateBook Pro / HarmonyOS 6.1）。
+
+下次把任意 **Qt6 + CMake 的桌面 GUI 程序**搬到鸿蒙 PC，按这套来。基础交叉编译坑见 [[鸿蒙PC-C++库交叉编译要点]]。
+
+> 前提：已有鸿蒙化 Qt 6.5.6（qtbase）安装在 `…/output/Qt6.5.6-ohos23-arm64-v8a/`，自带 `lib/cmake/Qt6/qt.toolchain.cmake`（链式加载 DevEco 的 `ohos.toolchain.cmake`，mkspec=`ohos-clang`）。calculator-ohos 是 .ets 模板 + QPA 插件样例。
+
+---
+
+## 1. 用 CMake 直接交叉编译，别转 qmake
+Qt 安装自带 `qt.toolchain.cmake` + 全套 Qt6 cmake config。配置：
+```
+<NDK>/native/build-tools/cmake/bin/cmake -S <app> -B build -G "Unix Makefiles" \
+  -DCMAKE_TOOLCHAIN_FILE=<QTOHOS>/lib/cmake/Qt6/qt.toolchain.cmake \
+  -DQT_HOST_PATH=<QtHost> -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_C_FLAGS=-Wno-unused-command-line-argument -DCMAKE_CXX_FLAGS=-Wno-unused-command-line-argument
+```
+- **用 NDK 自带 cmake（3.28.x），别用 Homebrew cmake 4.x**（对 Qt6.5/老 min-version 更稳）。无 ninja 就 Unix Makefiles。
+- `QT_HOST_PATH` 提供 moc/rcc/uic（交叉编译必需）。
+
+## 2. ⭐ 让 `qt_add_executable` 产出 `.so`（OHOS 靠 dlopen+dlsym(main) 加载）
+鸿蒙 app「可执行文件」其实是个被 QPA 插件 dlopen 的 **shared MODULE**，且 `main` 必须可见。
+- 这套 Qt 构建里 `lib/cmake/Qt6Core/Qt6CoreMacros.cmake` 的 `_qt_internal_create_executable` **OHOS 分支被注释掉了**，导致 `qt_add_executable` 产出普通可执行文件 → 加载不了。
+- **修复**：仿照其上方的 Android 分支启用 OHOS 分支：`add_library("${target}" MODULE …)` + `C/CXX_VISIBILITY_PRESET default` + 强制 `PREFIX "lib"`/`SUFFIX ".so"`（跳过未定义的 `qt6_openharmony_apply_arch_suffix`）。补丁见 `patches/0001-Qt6CoreMacros-*.patch`。
+- 验证：`llvm-readelf --dyn-syms libApp.so | grep ' main$'` 应为 `GLOBAL DEFAULT`。
+- （qmake 路线则是 mkspec 里 `TEMPLATE=lib; CONFIG+=dll`——calculator 当年走的这条。）
+
+## 3. 缺的 Qt 模块（如 Core5Compat）单独编后装进 prefix
+鸿蒙 Qt 当时只编了 qtbase；`Qt6Core5Compat`（`QTextCodec` 在此，Scintilla 等老库重度依赖做文件编码）等独立模块没有。
+- 源码在 Qt 检出的 `qt5compat/` 等子目录（版本随 qtbase）。standalone 编译：
+  ```
+  cmake -S qt5compat -B b -G "Unix Makefiles" \
+    -DCMAKE_TOOLCHAIN_FILE=<QTOHOS>/lib/cmake/Qt6/qt.toolchain.cmake -DQT_HOST_PATH=<QtHost>
+  cmake --build b --target Core5Compat
+  cmake --install b --prefix <QTOHOS>     # ← 装回 Qt prefix，find_package 才认
+  ```
+- 装回 prefix 后，app 的 `find_package(Qt6 COMPONENTS Core5Compat)` 直接通过。
+
+## 4. ⭐ Qt 安装被移动过 → 硬编码 host 工具路径失效
+Qt 当年在路径 A 构建，现在挪到路径 B：cmake config + 模块构建里**硬编码了旧 host 路径**（如 `…/qt6_build/host/qtbase/libexec/moc`），报 `No rule to make target …/moc`。
+- **修复**：建符号链接把旧路径指到新路径（`ln -s <新> <旧>`），一次性解决所有 baked 路径。
+
+## 5. ⭐ 依赖 X11/xcb 的 Qt 部件库（ads 等）：路由到非 X11 分支
+Qt-Advanced-Docking-System 把 `UNIX && !APPLE` 当 Linux+X11：源码 `#if defined(Q_OS_UNIX) && !defined(Q_OS_MACOS)` → `#include <xcb/xcb.h>`（找不到），CMake 里 `find_package(X11)`/`link xcb`/加 `linux/*.cpp`。
+- **修复**：所有该 `#if`（含个别 `#elif defined(Q_OS_UNIX)`）追加 **`&& !defined(Q_OS_OPENHARMONY)`**；CMake 的 `if(UNIX AND NOT APPLE)` 块加 **`AND NOT OHOS`**。OHOS 落到 Windows/mac 那样的非 X11 分支（浮动窗口退化为普通 QWidget，能用）。
+- 注意 ads 源码是 **CRLF**：`sed/perl` 用行尾 `$` 锚点会失配，用负向先行断言或不锚行尾。补丁 `patches/ads-ohos-no-x11.patch`。
+
+## 6. ⭐⭐ Qt 资源（qrc）在 dlopen MODULE 里两连坑
+症状：`QFile(":/...").open()` 失败 → 或 `QResource: error decompressing zlib content` → app `qFatal` 崩。
+- **坑 A：`-ffunction/-fdata-sections` + `--gc-sections` 把 rcc 的匿名命名空间静态初始化器（`namespace{ struct initializer{…} dummy; }`）回收了** → 资源没注册。修复：`main()` 里显式 `Q_INIT_RESOURCE(<qrc基名>)`（每个 .qrc 一行），强制引用+注册。
+- **坑 B：host rcc 的 zlib 压缩资源在设备 QtCore 上解压失败**（错误码是垃圾值）。修复：给目标加 `set_target_properties(App PROPERTIES AUTORCC_OPTIONS "--no-compress")`（资源改为不压缩存储）。
+- 两个都要打，缺一不可。
+
+## 7. 交叉链里没有的就跳过
+- `LinguistTools`（lupdate/lrelease，host 工具）→ OHOS 下 `if(QT_QMAKE_TARGET_MKSPEC STREQUAL "ohos-clang")` 跳过 `qt_add_translations`（UI 变英文，不影响跑）。
+- 桌面打包（AppImage/deb/NSIS，要 qmake）→ 跳过 `include(Packaging.cmake)`。
+
+## 8. 平台宏速查（实测）
+| 维度 | OHOS Qt 取值 |
+|---|---|
+| C++ 宏 | `Q_OS_OPENHARMONY` ✓、`Q_OS_LINUX` ✓、`Q_OS_UNIX` ✓ 同时定义 |
+| 编译器宏 | `__OHOS__` ✓、`__linux__` ✓ |
+| CMake | `OHOS` 为真、`CMAKE_SYSTEM_NAME=OHOS` |
+源码守卫优先用 `Q_OS_OPENHARMONY`，CMake 用 `OHOS`。
+
+## 9. 打 HAP：复用 calculator-ohos 模板
+- 复制 calculator-ohos → 改：`EntryAbility.ets`/`EntryEmbeddedAbility.ets` 的 `launchApplication="libApp.so"`、`MyAbilityStage.ets` 去掉 test_napi、app.json5 的 bundleName、string.json 标签；删 types/libtest_napi。
+- **依赖闭包**（`entry/libs/arm64-v8a/`）：app + `libplugins_platforms_qopenharmony.so`(QPA，扁平放，被 ArkTS import) + 链接到的 Qt6 库 + `libz.so`（**见 §11，必须用设备真库**）+ `libc++_shared.so` + 需要的插件子目录（`imageformats/`、`iconengines/`，HAP 会原样保留子目录并部署到 `/data/app/.../libs/arm64/imageformats/`）。其余（libEGL/GLESv2/uv/ace_napi…）设备自带，用 `llvm-readelf -d` 算 NEEDED 闭包，凡 Qt prefix `lib/` 里有的就打包。
+- **CLI 构建+部署**（无需开 GUI）：`DEVECO_SDK_HOME=…/sdk node …/hvigor/bin/hvigorw.js assembleHap -p product=default -p buildMode=release --no-daemon` → 出**已签名** HAP；`hdc install -r` + `hdc shell aa start -b <bundle> -a EntryAbility`。
+- **签名绑 bundleName**：DevEco 调试 profile 绑定具体 bundleName。想快速复用现成签名就沿用模板的 bundleName（如 `com.qt.calculator`，app 仍按 label 显示新名）；要独立 bundleName 得在 DevEco 里自动签名重签。
+
+## 10. ⭐ SingleApplication / QSharedMemory 残留共享内存（真机调试必踩）
+SingleApplication（单实例库）用 QSharedMemory，鸿蒙上落在 **`/mnt/sandbox/shm/100/app/<bundle>/qipc_sharedmemory_*`**——这层 tmpfs **`hdc uninstall` 不清、force-stop 不清、崩溃不清**。
+- 后果：上一个实例（哪怕已崩）残留 shm，新实例判定「primary 已在运行」→ 走 secondary 直接退出，**看着像装上点不开/一闪而退**，但其实根本没进 `init()`。
+- 排查：`hilog -b D` 提级别 + `aa force-stop` 冷启动后 `hilog -x -P <pid>`（顺序见 [[鸿蒙PC-hdc能力边界与取证通道]]），看到 `Primary instance already running. PID: <死PID>` + `Secondary instance closing` 就是它。
+- 清理：`hdc shell "rm -f /mnt/sandbox/shm/100/app/<bundle>/qipc_sharedmemory_*"`（或重启设备）。**每次重测前都删**。
+
+## 11. ⭐⭐ NDK sysroot 的 `.so` 是「链接桩」——别打进 HAP（图标全空/解压报错的根因）
+`$NDK/native/sysroot/usr/lib/aarch64-linux-ohos/*.so` 很多是**只供链接的桩(stub)**，不是真实运行时库。把它打进 HAP，运行时函数全是空操作/返回垃圾。
+- **本案**：打了 sysroot 的 `libz.so` → 运行时 `inflate/uncompress` 失效 →
+  ① `QResource: error decompressing zlib content`（qrc 压缩资源解压失败，曾误以为是 rcc 问题去加 `--no-compress`）；
+  ② **libpng 解 IDAT 也用 zlib** → 所有 PNG `QPixmap` 为 null → **工具栏图标全空、按钮只剩文字**。`QImageReader::supportedImageFormats()` 仍列出 `png`（handler 在），但 `QPixmap(":/x.png").isNull()==true` 是决定性信号。
+- **怎么一眼认出桩**：`llvm-nm -D libz.so` 看到 **所有函数符号是同一个地址**（如全 `0x2674 T`）→ 桩。真库每个函数地址不同。
+- **修法**：从设备 pull **真库**再打包：`hdc file recv /system/usr/lib/libz.so.1.2.13 ./libz.so`（真 zlib 1.2.13，SONAME `libz.so.1`，仅依赖 libc；按文件名 `libz.so` 放进 libs 即可满足 `DT_NEEDED libz.so`，SONAME 不匹配无妨）。设备真库候选还有 `/system/lib64/platformsdk/`、`/system/lib64/chipset-sdk-sp/`。
+- **通用结论**：凡要把某 system 库打进应用，先 `file`+`llvm-nm -D` 确认不是桩；优先 pull 设备真库，而不是拿 NDK sysroot 的。
+
+## 12. SVG 图标：插件能 dlopen 但 QImageReader 不认 → 退回 PNG
+`QIcon(":/x.svg")` 在鸿蒙上空白。排查链：`QCoreApplication::addLibraryPath("/data/storage/el1/bundle/libs/arm64")`（因 `applicationDirPath()` 在 OHOS 是 `/system/bin/appspawn`，Qt 默认搜不到 app 自己的插件目录）后，`QPluginLoader(qsvg).load()==true`、目录也扫得到，但 `supportedImageFormats()` **就是不含 svg**（QFactoryLoader 在 OHOS 上不接受该 imageformat 插件，原因未深究）。
+- **务实修法**：把用到的少量 SVG **栅格化成 PNG**（PNG 路径已验证完全可用）。lucide 类纯线条图标可用 PIL 直接按其 path 几何重绘（supersample 4x + LANCZOS 下采样，`stroke-width=2`→按比例、圆头端点）；代码里用 `#if defined(Q_OS_OPENHARMONY)` 把 `.svg` 路径换成 `.png`，桌面仍用 SVG。
+- `addLibraryPath` 那条仍建议保留（让 Qt 知道 app 库目录是对的）。
+
+---
+
+## 真机验证套路
+- `hdc shell aa start -b <bundle> -a EntryAbility` 后 `hdc shell pidof <bundle>` 看是否存活。
+- 崩溃栈：`hdc shell "ls -t /data/log/faultlog/faultlogger/cppcrash-<bundle>-*"` → `cat`，看 `LastFatalMessage` + backtrace（带 so 名和符号，非常准）。
+- 截图：`hdc shell snapshot_display -f /data/local/tmp/s.jpeg`（**后缀必须 .jpeg**）→ `hdc file recv`。
+- 应用自己的 qDebug/qInfo 在 hilog tag `A0F000/<bundle>`（QtForOpenHarmony）——**默认级别 W 会把 qDebug/qInfo 丢掉，取证前先 `hilog -b D`**。
+
+## 组件交叉编译省心程度（NotepadNext 实测）
+scintilla / lexilla / lua / uchardet / QSimpleUpdater / SingleApplication / editorconfig-core-qt **全部 0 改动**编过；只有 **ads 要去 X11**、**Core5Compat 要补编**。多数现代 Qt/C++ 库在 OHOS（同时 `__linux__`+`__OHOS__`）走 Linux 分支即可。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Qt6-qtdeclarative-QtQuick/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,52 @@
+---
+name: 鸿蒙PC-Qt6-qtdeclarative-QtQuick交叉编译
+description: 给鸿蒙 Qt6.5.6 补编 qtdeclarative(QtQml/QtQuick)+QuickControls2 的 6 个构建坑与修法；打 QtQuick HAP 要点
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：给 Qt6.5.6 补编 qtdeclarative(QtQml/QtQuick) + QuickControls2
+
+背景：鸿蒙化 Qt 6.5.6 当初**只编了 qtbase**（QML 被 skip）。为移植 VLC 原生 Qt 界面（100% QML）需补编 QtQml/QtQuick。2026-06-27 在 Qt 鸿蒙构建工程里全部跑通：cross `[4602/4602] 交叉编译成功`，prefix 出 `libQt6Qml.so`/`libQt6Quick.so`/`libQt6QuickControls2.so` 等全套，QtQuick 测试 app 打成签名 HAP。基础 Qt6 app 移植套路见 [[鸿蒙PC-Qt6-CMake-GUI应用移植]]，musl 坑见 [[鸿蒙PC-C++库交叉编译要点]]。
+
+> 构建命令：Qt 鸿蒙构建脚本 `python3 build-qt-ohos.py --exe_stage all`。host 阶段失败得快（~30min，macOS 上编 host 工具），cross 是长段（4602 目标，约 1–2h）。配置全在 `configure.json`（host=`qt6-host-config`、cross=`qt6-cross-config`）。
+
+## 总体：要改 4 处构建配置 + 1 个源码补丁，QuickControls2 白送
+
+### 1. 解 skip：configure.json 两处都要去
+`qt6-host-config` 和 `qt6-cross-config` 的 `-skip` 列表里把 **`qtdeclarative`、`qtshadertools` 都删掉**（host 给工具 qmlcachegen/qsb，cross 给目标库）。源码本就在 `qt6/qtdeclarative`、`qt6/qtshadertools`。
+
+### 2. ⭐ host cmake 配置只拷了 qtbase → cross 找不到 `Qt6::qsb`
+`build_qt/qt6_build.py` 的 `_install_cmake_configs()` 原本只从 `qtbase/lib/cmake`+`qtbase/{bin,libexec}` 拷。加 qtdeclarative/qtshadertools 后，它们的 `Qt6ShaderToolsTools`/`Qt6QmlTools` cmake 包 + 工具(qsb/qmlcachegen)没装进 host prefix → cross 配置报 `Failed to find host tool "Qt6::qsb"`。
+- **修**：把该函数改成 **遍历 `['qtbase','qtshadertools','qtdeclarative']`** 各自拷 `lib/cmake`+`{bin,libexec}`。
+
+### 3. ⭐ macOS host 链接 `AGL` framework 失败（SDK 26.4 已删 AGL）
+host 编 qsb 要 host QtGui，QtGui 默认链 `-framework AGL`，但新 macOS SDK 没 AGL → `ld: framework 'AGL' not found`。（原来只编 qtbase 工具不碰 QtGui 才没事。）
+- **修**：host 关 OpenGL → `qt6-host-config` 加 `"-opengl": "no"`（host 工具只需 `QShader`，不要 GL 运行时）。**注意 `build_qt/config.py` 的 `build_host_configure_options()` 原本根本不读 `-opengl`**，得先给它加上 `if tag_options.get('-opengl'): result += ['-opengl', ...]`，否则配了也不生效。
+
+### 4. ⭐ host `-developer-build` 注入 `-Werror`（clang21 vs Qt6.5.6 一堆告警变错）
+host 用系统 clang 21（很新），Qt6.5.6 老代码触发 `-Wunnecessary-virtual-specifier` 等，被 `-Werror` 提成错（Cocoa 插件 `.mm` 首当其冲）。`CMAKE_*_FLAGS` 里加 `-Wno-error` 没用——Qt 把 `-Wall -Wextra -Werror` 加在**我的 flag 之后**，顺序上赢了。`-Werror` 的源头是 **`-developer-build`**。
+- **修**：`qt6-host-config` 把 `"-developer-build": true` 改成 **`false`**，一刀清掉整类 warning-as-error。host 只要工具，不需要 developer-build 的私有头/-Werror。
+
+### 5. ⭐⭐ 源码补丁必须进 patch 仓，别直接改源码（会被 `git reset --hard` 冲掉）
+cross 编 qtshadertools 内置 **glslang** 报 `pthread_setcancelstate/setcanceltype undeclared`（OHOS musl 无 pthread 取消，同 VLC 那类坑）。`ossource.cpp` 已有 `#if __ANDROID__||__Fuchsia__` 走无取消路径，**加 `||defined(__OHOS__)` 即可**。
+- **但直接改源码不管用**：`build()` 在 host 之后会 `git reset --hard`(主仓+`submodule foreach reset --hard`) **再** `apply_patches`，把跟踪文件的改动全冲掉。
+- **正解**：丢进 patch 仓 `work/qt-ohos-patch/patch/v6.5.6/<module>.patch`，命名即模块名（`qtshadertools.patch` → 被 `git -C qt6/qtshadertools apply` 应用；`root.patch` 应用到主仓）。生成：改源码 → `git -C <submodule> diff > .../<module>.patch` → `git checkout` 还原 → `git apply --check` 验。**这是给本 Qt 加任何 cross 源码补丁的通用工作流。**
+
+### 6. QuickControls2 白送
+Qt6 里 **qtquickcontrols2 已并入 qtdeclarative**，编 qtdeclarative 直接出 `libQt6QuickControls2.so`/`QuickTemplates2`/`QuickLayouts`/`QuickShapes`/`QuickDialogs2` 等全套——无需单独 clone qtquickcontrols2。
+
+## 打 QtQuick 应用成 HAP（在 [[鸿蒙PC-Qt6-CMake-GUI应用移植]] 基础上多三件事）
+1. **Qt6CoreMacros.cmake 的 OHOS 分支被重编重置了**：重编 Qt 后 prefix 的 `lib/cmake/Qt6Core/Qt6CoreMacros.cmake` 里 `_qt_internal_create_executable` 的 `elseif(OHOS)` 又变回注释。要重新启用（仿 ANDROID 分支：`add_library MODULE`+`*_VISIBILITY_PRESET default`，并强制 `PREFIX "lib"`/`SUFFIX ".so"` 跳过未定义的 `qt6_openharmony_apply_arch_suffix`），`qt_add_executable` 才出 `lib*.so`(main 可见)。
+2. **V4 JS 引擎 JIT**：鸿蒙 app 域禁 JIT（见 [[鸿蒙PC-app域执行二进制与JIT限制]]）。`main()` 开头 `qputenv("QV4_FORCE_INTERPRETER","1")`，否则 QML 一执行就崩。
+3. **QML 模块要随 HAP 带**：把 prefix 的 `qml/QtQuick`、`qml/QtQml`、`qml/QtCore` 整树拷进 `entry/libs/arm64-v8a/qml/`（HAP 保留子目录，部署到 `/data/.../libs/arm64/qml/`），app 里 `engine->addImportPath("/data/storage/el1/bundle/libs/arm64/qml")`。依赖闭包：以 app+QPA+各 qml 插件为根做 `llvm-readelf -d` 的 DT_NEEDED BFS，凡 prefix `lib/` 里有的 Qt 库都扁平拷进 libs（脚本 `qtquick-spike/pack-hap-libs.sh`）。
+
+## 真机渲染验证（✅ 已通过 2026-06-27，go/no-go 绿灯）
+最小 QtQuick app（`Window`+渐变`Rectangle`+`Text`+`RotationAnimation`）真机**完整渲染**：原生窗口、导航蓝背景、橙色渐变卡片、文字、**旋转动画都动**——QPA→EGL→GLES→RHI→scene graph→QML 全链路通。证据图 `qtquick-spike/docs/shots/qtquick-rendering-on-harmonyos-pc.jpeg`。**移植 VLC 原生 Qt 界面这条路确认可行。** 中间踩两坑：
+
+1. **⭐⭐ stub libz → QtQuick scene-graph 着色器全空（"Empty shader passed to graphics pipeline"）**：症状=窗口标题/背景色对了但**任何图元都画不出**（背景能 clear、几何画不了）。根因同 [[鸿蒙PC-Qt6-CMake-GUI应用移植]] §11——QtQuick 的 `.qsb` 着色器是 **zlib 压缩**进 `libQt6Quick.so` 的 qrc，stub libz（NDK sysroot 的，8KB/3 个同址符号）`uncompress` 失效→着色器解出来是空。**修**：从设备 pull 真 libz（`/system/usr/lib/libz.so.1.2.13`，97KB/88 函数）改名 `libz.so` 进 HAP。**"窗口出来了、背景色对、就是不画东西" 几乎一定是 libz。**
+2. **⭐ hvigor 打 HAP 时把 libs/ 里的非 `.so` 全删了 → QML 模块的 `qmldir` 丢失**（`module "QtQuick.Window" is not installed`，插件 `.so` 在但没 qmldir 注册不了）。QML 解析插件是**相对 qmldir 目录**的，所以 qmldir 必须和插件 `.so` 同目录、且在可 dlopen 的已验证路径（bundle libs）。临时验证用 root 把 qmldir tar 推进设备 `/data/app/el1/bundle/public/<bundle>/libs/arm64/qml/`（数据文件，不触 XPM）。**正式打包仍需解**（候选：qmldir 嵌 qrc 的 `qt-project.org/imports` 并在 `plugin` 行写 libs 绝对路径；或找 hvigor 包含非 .so 的配置）——VLC 界面 HAP 会再遇到。
+
+## 改动落点
+- 改动落在 Qt 鸿蒙构建工程：`configure.json`(skip/opengl/developer-build/flags)、`build_qt/config.py`(读 -opengl)、`build_qt/qt6_build.py`(_install_cmake_configs 遍历模块)、`qt-ohos-patch/patch/v6.5.6/qtshadertools.patch`、prefix 的 `Qt6CoreMacros.cmake`(OHOS 分支)。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Rust-BoringSSL-quiche.md

@@ -0,0 +1,61 @@
+---
+name: 鸿蒙PC-Rust-BoringSSL-quiche
+description: 从 Mac 交叉编译依赖 BoringSSL 的 Rust 项目（quiche QUIC/HTTP3）到鸿蒙PC 的套路与三个坑
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+从 Mac 用官方 Rust OHOS target + DevEco NDK 交叉编译 quiche 0.29.1（Cloudflare 的 QUIC/HTTP3，默认用 `boring` crate 即 BoringSSL）。**源码零 patch**，真机 quiche-server + quiche-client loopback 完成 QUIC 握手 + HTTP/3 取回响应体。是 Rust 适配里最复杂的形态（带 C/C++/asm 的 BoringSSL）。
+
+## 基础：用官方 OHOS Rust target
+
+`rustup target add aarch64-unknown-linux-ohos`（tier-2，直接有 std）。比 ripgrep 当年的 `aarch64-unknown-linux-musl` + 手动 sysroot hack 干净。`.cargo/config.toml`：
+```toml
+[target.aarch64-unknown-linux-ohos]
+linker = "<NDK>/llvm/bin/aarch64-unknown-linux-ohos-clang"   # wrapper 自带 sysroot
+ar = "<NDK>/llvm/bin/llvm-ar"
+rustflags = ["-C", "link-arg=--target=aarch64-linux-ohos", ...]
+```
+注意调 cargo 时把 `~/.rustup/toolchains/stable-*/bin` 放进 PATH，否则 `cargo` 找不到 `rustc`。
+
+## 坑 1：bindgen 拿不到 sysroot（sys/types.h not found）
+
+boring-sys 用 **bindgen（libclang）** 从 BoringSSL 头生成 Rust 绑定。bindgen **不走 OHOS clang wrapper**，所以没有 wrapper 默认的 sysroot → `fatal error: 'sys/types.h' file not found`。
+对策：`export BINDGEN_EXTRA_CLANG_ARGS="--target=aarch64-unknown-linux-ohos --sysroot=<NDK>/sysroot"`。
+（cmake 编 BoringSSL 那部分用的是 wrapper clang，自带 sysroot，不用管。）
+
+## 坑 2：boring-sys 发 -lstdc++，OHOS 用 libc++
+
+链接报 `unable to find library -lstdc++`。OHOS/musl 的 C++ 运行时是 **libc++**（`libc++_shared.so`，设备 `/system/lib64/` 自带），没有 libstdc++。
+对策：建一个 shim 目录放 `libstdc++.so`，内容是 **linker script** `INPUT(<NDK>/llvm/lib/aarch64-linux-ohos/libc++.so)`，再用 `-L<shim>` 加进搜索路径。比改 boring-sys 源码省事。
+
+## 坑 3：sys crate 的 C 编译器环境变量
+
+build.rs/cc-rs 的 C 编译器走 `CC_aarch64_unknown_linux_ohos` / `CXX_...` / `AR_...`（**三元组用下划线**）。设好就行，cmake-rs（boring 编 BoringSSL）也吃这些。
+
+## 部署与验证
+
+产物是普通 ELF（NEEDED `libc++_shared.so` + `libc.so`，设备都有），strip 后推 `/data/local/tmp/`，运行时 `LD_LIBRARY_PATH=/system/lib64`。**exec 无需签名**。
+端到端：设备上 `quiche-server --listen 127.0.0.1:4433 --cert ... --key ... --root <docroot>` 后台起，`quiche-client https://127.0.0.1:4433/x --no-verify` 连接 → 取回 docroot 文件 = 完整 QUIC+BoringSSL TLS+HTTP3 栈通。证书在 `apps/src/bin/cert.{crt,key}`。
+
+## 通用结论
+
+任何"Rust + 依赖某 native C/C++ 库（尤其带 bindgen 的 -sys crate）"都套这三招：**OHOS target + BINDGEN_EXTRA_CLANG_ARGS 给 sysroot + libstdc++→libc++ shim**。和 [[鸿蒙PC-C++库交叉编译要点]] 的 libc++ 事实一脉相承。
+
+## 坑 4：跑测试套件时 `libc::msghdr` 结构体字面量在 musl/OHOS 编译失败
+
+`cargo test -p tokio-quiche --no-run --target ...ohos` 报 `cannot construct 'msghdr' with struct literal syntax due to private fields __pad1/__pad2`。glibc 的 `msghdr` 全公有字段，但 **musl/OHOS 的 `msghdr` 带私有 `__pad1`/`__pad2`**（为给 32 位长度成员按目标字节序排版），字面量构造直接编译错。
+对策：别用结构体字面量。改 `let mut h: libc::msghdr = std::mem::zeroed(); h.msg_name = ...; ...` 零初始化后只赋公有字段，glibc/musl 通吃。同理任何 `-sys`/socket 代码里直接字面量构造 libc POD 结构（`msghdr`/`cmsghdr`/`sockaddr_*`）在 musl 上都可能因私有 pad 字段炸，统一用 `zeroed()`+逐字段赋值。
+（quiche 仓库里是 `datagram-socket/src/mmsg.rs` 的 recvmmsg/sendmmsg，补丁 `patches/0002-datagram-socket-msghdr-musl-portable.patch`。）
+
+## 坑 5：测试里的证书绝对路径（同 h3，集成测试也中招）
+
+`tokio-quiche/tests/fixtures/mod.rs` 的 `TEST_CERT_FILE`/`TEST_KEY_FILE` 是 `concat!(env!("CARGO_MANIFEST_DIR"), "../quiche/examples/cert.crt")` 烘焙的绝对路径常量，交叉编译后设备上无此路径。修法同 [[#坑]] h3：`include_bytes!` 编译期内嵌 + 首次访问落 `$TMPDIR`（`LazyLock` 缓存返回 `&'static str` 保持原类型，调用点 `TEST_CERT_FILE` → `TEST_CERT_FILE()`）。补丁 `patches/0003-tokio-quiche-itest-cert-embed.patch`。**通用教训**：任何 Rust 库的 test fixture 凡用 `CARGO_MANIFEST_DIR` 拼资源路径，跨机跑都得改成 `include_bytes!` 内嵌。
+
+## 真机环境限制：HongMeng 内核无 Linux 的 `SO_RCVMARK`
+
+tokio-quiche 集成测试 21 个，真机 **20 passed / 1 failed**，唯一失败 `test_so_mark_receive_data` 是**环境限制非缺陷**：设备是 **HongMeng Kernel 1.12.0（`uname -a` 自报，不是 Linux）**，不支持 Linux 5.19+ 的 `SO_RCVMARK` sockopt（设它需 `CAP_NET_ADMIN`），内核 `recvmsg` 不投递 `SCM_MARK` cmsg → `initial_so_mark_data()` 返 `None` → 测试 `.unwrap()` panic。该用例的 QUIC 握手/HTTP3/200 响应都成功，只卡在 Linux 内核特有的 cmsg 断言。
+**教训**：鸿蒙 PC 设备网络栈是 HongMeng 内核而非 Linux，Linux 专属的 sockopt/cmsg（`SO_RCVMARK`、可能还有 `SO_TXTIME`/`UDP_GRO` 等）不保证可用；依赖这些的测试在真机失败属正常，按"平台/环境限制"归类，别误判为移植缺陷。tokio-quiche 自身对这些 sockopt 的 setsockopt 错误是 `let _ = ...` 吞掉的，所以功能不受影响、只有显式断言 cmsg 的测试会挂。
+
+集成测试交叉编译/真机执行的结果与失败归因见 [[鸿蒙PC-真机跑官方测试套件]]。