@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-CGAL/351/253/230/346/250/241/346/235/277/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221/345/210/206/346/211/271/347/255/226/347/225/245.md

@@ -0,0 +1,51 @@
+---
+name: 鸿蒙PC-CGAL高模板库交叉编译分批策略
+description: CGAL 等高模板化 C++ 库交叉编译的 AOT 模板实例化时间管理：单文件 15-30 分钟、整族数小时——用 ninja -j1 的可中断续编特性分多批次完成，GMP/MPFR 静态库直取 Conan 中心仓 cgal 包不自编；批间产物落盘即锚点，中断后 ninja 从断点续编不重来。触发词：CGAL、模板实例化、编译时间、15-30 分钟、分批、AOT、计算几何、ninja 续编、libgmp、libmpfr、IfcOpenShell
+metadata:
+  type: adaptation
+  source: new/PC（IfcOpenShell 0.9.0 geometry mapping 交叉编译实证，2026-09-20）
+---
+
+# 鸿蒙 PC：CGAL 高模板库交叉编译的分批策略
+
+> 适用判定：目标依赖 CGAL 或同量级高模板化 C++ 库（大量 header-only 模板、
+> `#include` 展开后单 TU 数万行），交叉编译单文件 15-30 分钟、整族 >2 小时。
+> **问题不是「编不编得过」而是「时间怎么管」**——本篇是时间管理配方。
+
+## 时间现实（先接受再规划）
+
+- CGAL 模板 AOT 实例化：单 TU 15-30 分钟是常态（几何内核模板在头文件里全量展开）；
+- IfcOpenShell geometry mapping 实测 101 个 CGAL 模板源文件，串行预估 ~2h；
+- 加上 kernels（cgal/cgalsimple/opencascade/passthrough，~4h）与 trees（opencascade_brep/trianglebvh，~1h），
+  全族一次跑完要 6-7 小时连续供电供电稳定的构建窗口——**别按这个假设排期，按分批排**。
+
+## 分批配方
+
+1. **依赖零自编**：`libgmp.a`/`libmpfr.a` 直取 Conan 中心仓 `cgal/6.2` 包（`deps/cgal-6.2/dist/lib` 在盘即可链），
+   不要源码自编 GMP/MPFR——那是再搭一天工期的无谓支线（见 `pc-registry` central-registry.md 实证清单）。
+2. **驱动器选 ninja -j1**：ninja 的构建图记录每个目标的完成状态，**中断后重跑同一命令从断点续编**，
+   已完成的 TU 不重来。Windows 宿主无 GNU make 时更没得选（见 `鸿蒙PC-宿主无GNU-make的确定性构建驱动.md` 的决策序——
+   有官方 ninja 构建图时优先 ninja）。
+3. **按产物分组批**：批 = 一组目标 .so（如按 schema：ifc2x3 / ifc4 / ifc4x1 / ifc4x2 / ifc4x3 各算一批）。
+   批间产物落盘即锚点——`dist/lib/*.so` 在盘的批次不用再碰，时间预算按「下一批 N 个 TU × 15-30 分钟」算。
+4. **每批收尾做增量校验**：产物 `llvm-readelf` 查 `.codesign` 段（漏签及时补链，见 E176 重链配方）、
+   退出码回读（E154 fail-fast 纪律）——别攒到最后一批才发现第 3 批就断了。
+5. **排程建议**：连续 >4h 的批次放 CI runner 或不断电工作站；交互式会话里只排 ≤1h 的批，
+   中断就走续编，不要因「怕断」把批次切得太碎（批间人工检查也有开销）。
+
+## 反模式
+
+- **串行跑全族一次定胜负**：中途任何抖动（会话中断/休眠/USB 拔插）都浪费全部进度——
+  恰恰是 ninja 构建图能免费给你的续编能力别放弃。
+- **并行拉满（-j8+）**：模板实例化是内存大户（单 TU 峰值数 GB），Windows 宿主并行过高会 OOM/卡死；
+  另见 `鸿蒙PC-Windows宿主构建环境四坑.md` 的 ld.lld 并行链接崩溃（0xC0000005）降 -j1 先例。
+- **自编 GMP/MPFR**：中心仓制品可用时就别自建（跨轮 404 重探测铁律见 central-registry.md，
+  但 cgal/6.2 本体实证在盘，直接取）。
+
+## 实证规模
+
+IfcOpenShell 0.9.0（2026-09-20）：geometry mapping 4×3 目标 101 个 CGAL 模板源文件按批编出，
+`dist/lib/ifcopenshell_geometry_mapping_{ifc2x3,ifc4,ifc4x1,ifc4x2,ifc4x3}.so` 五个 schema 产物全在盘；
+kernels/trees 按同法续编。依赖侧 `deps/cgal-6.2/dist`（含 libgmp.a/libmpfr.a）来自 Conan 中心仓。
+
+<!-- src: new/PC（IfcOpenShell geometry mapping 分批实证 2026-09-20） -->

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-CLI/350/260/203/350/257/225/345/231/250-autotools-autosetup/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,60 @@
+---
+name: 鸿蒙PC-CLI调试器-autotools-autosetup交叉编译
+description: autotools 主工程 + autosetup 子模块的 CLI 调试器交叉编译配方：--enable-internal-<内嵌脚本引擎> + 禁用 Linux 专属适配器、autosetup 子模块跨编译需显式导出 CC_FOR_BUILD、外部依赖（串口/总线类）走中心仓复用；另收内嵌脚本引擎 EvalFile 在 MinGW 下 stat=0 静默失效根因与 CLI 用例设计要点。续修轮追加：SIGINT 信号重置（E150 runner 侧 child_pre_exec + 产品侧 foreground patch）与 USB 后端 DDK 评估结论（usbfs 后端 app 域不可用 / NDK libusb_ndk.z.so / ohos_libusb 空仓 / 桥接前置）。触发词：openocd、sigint-graceful、child_pre_exec、信号重置、SIG_IGN、sigprocmask、USB DDK、OH_Usb_、libusb_ndk、ohos_libusb、usbfs、调试探针、JTAG、SWD、dummy 适配器、CC_FOR_BUILD、autosetup、EvalFile、stat st_size=0。
+metadata:
+  type: adaptation
+  source: new/PC（嵌入式调试 CLI 实证）
+---
+
+# autotools + autosetup 子模块的 CLI 调试器交叉编译
+
+来自某嵌入式调试 CLI 工具（「autotools 主工程 + autosetup 子模块（内嵌 Tcl 脚本解释器）+ 多可选后端」）适配。
+
+## 1. 鸿蒙交叉编译配方
+
+```bash
+./configure --host=aarch64-unknown-linux-ohos \
+  --enable-internal-<内嵌脚本引擎> --enable-dummy --disable-werror \
+  --disable-<Linux 专属适配器：sysfsgpio / linuxgpiod / linuxspidev / bcm2835gpio / parport / dmem / giveio / \
+             ep93xx / at91rm9200 / imx_gpio / xlnx-pcie-xvc / rshim（按库实际开关裁剪）>
+```
+
+- **autotools 前置补丁**：config.guess/config.sub 加 `aarch64-unknown-linux-ohos` 三元组识别（E007/E072）。
+- **内嵌脚本引擎子模块**：`git submodule update --init` 拉取；release tarball 自带完整子模块源码也可直接拷入。
+- **外部依赖复用**：串口/USB 访问类依赖（libusb-1.0 / hidapi 等）从中心仓 Conan 复用（pkg-config 路径需手动指定），
+  见 `pc-registry` 与能力域 `usb-host` / `serial-port`。
+- **结果**：26 条名册 25 PASS / 0 FAIL / 1 SKIP（sigint-graceful 一度 SKIP，续修轮 runner 侧信号重置后待下次名册确认转 PASS，见下）。
+
+## 2. autosetup 子模块跨编译：显式导出 CC_FOR_BUILD
+
+autosetup（非 autotools）跨编译时不从 `CC` 自动推导 `CC_FOR_BUILD`，编译期工具链检测失败。
+修法：configure 前 `export CC_FOR_BUILD=$CC`，同时 config.guess/config.sub 加 HarmonyOS 识别。
+（这类「有 build/host 双用工具」的构建系统通用，见 E116 的「自举 codegen 工具先 host 编」同类坑。）
+
+## 3. 根因缺陷：内嵌脚本引擎 EvalFile 在 MinGW 下 stat st_size=0（宿主自证用）
+
+- **现象**：`<工具> -f xxx.cfg` / `<引擎解释器> script.tcl` / `source file` **静默不执行**——无报错、RC=0、
+  配置不生效；`-c` 内联命令、stdin、`eval [read ...]` 正常。
+- **定位**：脚本引擎的 `EvalFile` 内 `stat()` 返回 `st_size=0`（文件实际 39 字节），命中
+  `if (sb.st_size == 0) return JIM_OK` 静默早退——属该编译单元内结构体/宏映射异常的 ABI 问题。
+- **修复（仅宿主验证构建用）**：`EvalFile` 改为 fopen + fread 循环读到 EOF，不信 stat 尺寸。
+- **教训**：脚本引擎「静默失效」会把所有基于配置文件的验证架空且不报错——上游多条用例最初
+  FAIL 的 "适配器未指定" 就是 cfg 未执行的下游症状。**验证 CLI 工具前先用 bogus-command 文件探针确认脚本加载链路真的工作。**
+
+## 4. CLI 用例设计要点（名册 6 PASS → 25 PASS）
+
+1. 输出通道：echo/版本/帮助/命令列表常走 **stderr**，断言只 grep stdout 必挂——断言器 stdout+stderr 合并匹配。
+2. 命令模式：EXEC 阶段命令在 config 阶段调用报 invalid，需 `init` 后执行。
+3. 命令名以源码为准：别信文档/记忆（某版本是 `debug_level`，**没有** `log_level`）。
+4. 内置 dummy 后端返回伪数据（寄存器读不出/内存 dump 退出）——**不是用例失败**，对 init 后用例用
+   「输出匹配、不限退出码」断言；远程服务用日志 `Listening on port <端口>` 做启动证据。
+5. 远端控制协议：命令需 `\x1a` 终止，`version`/`echo` 输出走 LOG 通道不进响应负载——协议往返断言用引擎表达式。
+6. 后台服务清场：残留进程占端口 → 后续用例连锁 bind 冲突（表面 exit=127）。跑名册前停干净、用例间 sleep。
+7. 信号与物理链路（USB/串口）天然不在宿主验证范围（见 [[鸿蒙PC-app域执行二进制与JIT限制]] 关卡⑥、能力域 `usb-host`/`serial-port`）。
+8. **SIGINT 信号重置（E150）**：app 域 NAPI fork+execv 启动的子进程继承宿主 `SIG_IGN` 处置与阻塞信号掩码，即使工具已 `signal(SIGINT, handler)` 注册 handler，掩码屏蔽使信号永远 pending。修复 = 两处：① runner 侧 `child_pre_exec()` execv 前 `signal(SIG_DFL)` + `sigprocmask(SIG_SETMASK, &empty)`（**掩码清空比 SIG_IGN 重置更关键**）；② 产品侧 `__OHOS__` patch 去 `tcgetpgrp` 前台门控（app 域无控制终端语义）。详见 E150。
+9. **USB 后端**：中心仓 libusb 为 usbfs 后端（符号核实），app 域不可用；NDK 有 `libusb_ndk.z.so`（`OH_Usb_*` DDK API）；社区 ohos_libusb 空仓，无现成 libusb→DDK 桥接。DDK 桥接需 `ohos.permission.ACCESS_DDK_USB`（system_basic）+ `requestRight` + 物理探针。见 `pc-capability-domains/usb-host.md` 适配实证。
+
+## 相关
+- [[鸿蒙PC-autotools库CMake替代交叉编译]] —— autotools 库的 CMake 替代 fallback。
+- `pc-capability-domains` —— `serial-port` / `usb-host` 能力域（物理链路）。
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— cli 交付形态验证闭环（私有 HNP + 执行器 HAP + hilog 取证）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-CMake-FetchContent/345/244/232/344/273/223/345/272/223C++/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,32 @@
+---
+name: 鸿蒙PC-CMake-FetchContent多仓库C++库交叉编译
+description: 基于 CMake FetchContent 拉取多子仓库依赖的 C++ 库/CLI 交叉编译策略：zlib 用上游 fork 拿 ZLIB::ZLIBSTATIC 别名、其中一层工具库打 pthread_cancel 补丁、全静态链接 + 链接期 ELF 自签。
+metadata:
+  type: adaptation
+  source: new/PC（多仓库 CMake 工程实证）
+---
+
+# 基于 CMake FetchContent 的多仓库 C++ 库交叉编译
+
+来自某媒体信息解析 CLI（依赖闭包「主库 → 工具基础库 → zlib」经 **CMake FetchContent** 自动获取）适配。
+
+## 交叉编译要点
+
+1. **zlib 用上游 fork**（非官方仓库）——拿到 `ZLIB::ZLIBSTATIC` CMake 目标别名（官方库不导出该别名，
+   FetchContent 链接会 NOTFOUND）。
+2. **其中一层工具库打 `pthread_cancel` 补丁**：musl 不实现 `pthread_cancel`（返回 ENOSYS）。若源码已有
+   `__ANDROID_API__` 守卫，追加 `&& !defined(__OHOS__)` 即可；这是跨平台通用守卫式（见 E085/E020）。
+3. **全静态链接**（开启 CLI 静态链接开关），避免运行时 `.so` 加载与查找问题（CLI 单二进制）。
+4. **链接期 ELF 自签**：`-Wl,--code-sign`（见 [[鸿蒙PC-OpenSSL系密码库交叉编译]] §1）。
+
+## 可复用经验
+
+- **musl 缺 `pthread_cancel` 的通用守卫**：`#if defined(__ANDROID_API__) && !defined(__OHOS__)` ——
+  下次撞到 `undefined reference to pthread_cancel` 时先加这个守卫。musl 常见缺失一览见
+  `pc-knowledge-base/SKILL.md` §musl 兼容（`pthread_cancel`/`pthread_attr_setaffinity_np`/`secure_getenv` 等）。
+- **Windows 宿主 HNP 打包丢执行位**：Windows 下 `hnpcli.exe` 打包 HNP，zip entry `ExternalAttributes`
+  未设 Unix 可执行位，app 域 exec 报 EACCES——见 [[鸿蒙PC-私有HNP打包与exec平台差异]] §二。
+
+## 相关
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— 打包执行位与 exec 差异。
+- [[鸿蒙PC-OpenSSL系密码库交叉编译]]、[[鸿蒙PC-autotools库CMake替代交叉编译]] —— 同批次 CLI 交付形态案例。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-CMake/345/256/277/344/270/273/344/273/243/347/240/201/347/224/237/346/210/220/345/267/245/345/205/267/344/272/244/345/217/211/347/274/226/350/257/221/346/233/277/344/273/243.md

@@ -0,0 +1,63 @@
+---
+name: 鸿蒙PC-CMake宿主代码生成工具交叉编译替代
+description: 大型 C/C++ 项目交叉编译时，CMake CUSTOM_COMMAND 依赖的宿主代码生成器（lexer/hash/错误表/SQL 解析/protoc 等）被编成目标架构 ELF 却在宿主机执行而失败。三条解法按序取舍：Python 重写（输出逐结构对齐上游工具）/ 宿主原生二进制替代（protoc.exe 等）/ 先宿主编出该工具再复用；每个替代必须 grep build.ninja 证实被真实引用、产物与上游输出逐字节对齐。Windows 宿主附加坑：Python open() 必须显式 encoding='utf-8'。触发词：host tool、宿主工具、代码生成器、交叉编译 CUSTOM_COMMAND、cannot execute binary file、protoc、comp_err、gen_lex_hash、bison 生成、execvp format error、目标架构 ELF 宿主执行
+metadata:
+  type: adaptation
+  source: new/PC（mysql-server 26.7.0 Innovation 交叉编译实证，2026-09，commit 23e360a7）
+---
+
+# 鸿蒙 PC：CMake 宿主代码生成工具的交叉编译替代
+
+> 场景：CMake 项目里 `add_custom_command(COMMAND <tool> ...)` 的 `<tool>` 是本项目
+> 自建的代码生成器。交叉编译时 CMake 把它编成**目标架构** ELF，却在**宿主机**上
+> 直接执行 → `cannot execute binary file` / `%1 is not a valid Win32 application`。
+> 与 Rust build.rs 的宿主泄漏（见
+> `鸿蒙PC-Rust-build-script宿主cfg泄漏与OHOS交叉链接.md`）是同一不变量的
+> CMake 形态：**构建期工具必须跑在宿主，产物必须跑在目标**。
+
+## 三条解法按序取舍
+
+1. **宿主原生二进制替代**（最省事，有官方发行版时首选）：protoc 下载 Windows 版
+   `protoc.exe`、gawk 拷 `gawk.exe` 到**无空格路径**，把 CMake 变量指过去
+   （`PROTOBUF_PROTOC_EXECUTABLE` 等；注意若缓存里写的是裸名字 `protoc`，
+   靠 PATH 解析——构建时把工具目录 prepend 进 PATH 再跑 ninja）。
+2. **Python 重写**（工具逻辑简单但输出格式复杂时）：按上游 C++ 工具的输出
+   **逐结构对齐**——struct 数组布局、宏定义形态、section 划分、错误编号方案
+   全部对齐，否则下游编译炸（MySQL 案：`ER_*/WARN_*` 未声明级联几百个错误）。
+   把 CUSTOM_COMMAND 的 COMMAND 改成 `python3 <script>`，通常包一层
+   `IF(CMAKE_CROSSCOMPILING)` 分支，不污染原生构建。
+3. **先宿主编出该工具再复用**（工具逻辑复杂、不值得重写时）：参考错误图谱
+   E116 的 bin2c 做法——先 `make CC=clang LDADD= LIBS= <tool>` 编宿主版，
+   再让目标构建指向它。
+
+## 验收两条硬规
+
+- **每个替代必须被 build.ninja 真实引用**：`grep <script> build.ninja` 能看到
+  CUSTOM_COMMAND 行才算接线成功——只改了 CMakeLists 没重新配置、或改了没被
+  引用到的分支，都是假修。
+- **生成产物与上游工具输出逐字节/逐结构对齐**：至少抽一个下游消费点编译验证
+  （如 mysqld_error.h 被 sql 层 include 后能过编译）。
+
+## 解析保真度：编译能过 ≠ 语义对齐（comp_sql DELIMITER 实证）
+
+「与上游输出逐结构对齐」的最高危反例：转换器带**解析状态机**时（comp_sql 内嵌
+sql_bootstrap.cc 的 read_bootstrap_query），天真简化（按分号切分、忽略指令行）
+产出的 C 数组格式完全合法——编译链接全过，直到设备上跑到那段 SQL 才炸
+（bootstrap 1064，错文含 DELIMITER 残留）。对账标准因此必须下沉到
+**解析语义级**：DELIMITER 指令切换与剥离规则、引号/注释状态机、分隔符保留/
+剥离差异、同行多语句 unget 回扫，逐条对齐。编号冻结类产物（digest token、
+错误码段）同理——错了不炸，静默错。详见错误图谱 E151。
+
+## Windows 宿主附加坑
+
+Python 脚本读上游源文件（UTF-8）时**必须显式 `open(..., encoding='utf-8')`**——
+Windows 系统默认 GBK，读到 UTF-8 源文件直接 UnicodeDecodeError 或静默写坏产出。
+
+## MySQL 26.7 实证规模
+
+7 类宿主工具全部落地：uca9dump/gen_lex_hash/gen_lex_token/gen_keyword_list/
+comp_sql/comp_err/comp_client_err 走 Python 重写（gen_uca900_tables.py /
+gen_sql_host_tools.py / gen_comp_err.py / host_tools_proxy.py），protoc 走
+Windows 原生二进制。产出 mysqld_error.h（6590 错误码 10 sections）/
+mysqld_ername.h / mysqld_errmsg.h / errmsg.sys / lex_hash.h / lex_token.h /
+keyword_list.h，全部被 build.ninja 引用、下游编译通过。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-CMocka/345/244/264/346/226/207/344/273/266uintptr_t/346/235/241/344/273/266/345/256/217/347/274/272__MUSL__/345/256/210/345/215/253/351/207/215/345/244/215/345/256/232/344/271/211.md

@@ -0,0 +1,58 @@
+---
+name: 鸿蒙PC-CMocka头文件uintptr_t条件宏缺__MUSL__守卫重复定义
+description: CMocka 交叉编译鸿蒙 aarch64-musl：头文件 uintptr_t 条件宏缺 __MUSL__ 守卫导致重复定义编译失败。修法是在条件宏中追加 `&& !defined(__MUSL__)`。经验可推广到其他含 'typedef unsigned long uintptr_t' 回退逻辑的头文件（cJSON 等同样易踩）。触发词：CMocka、uintptr_t、__MUSL__、重复定义、交叉编译、aarch64-musl、musl 头文件兼容、_UINTPTR_T、HAVE_UINTPTR_T、类型回退 typedef。
+metadata:
+  type: adaptation
+  source: libcbor 0.14.0（交叉编译 CMocka 测试依赖时实证）
+  relates_to: E129-E131
+  supersedes: []
+---
+
+# 鸿蒙 PC：CMocka 头文件 uintptr_t 条件宏缺 __MUSL__ 守卫导致重复定义
+
+## 现象
+
+交叉编译依赖 CMocka 的 C/C++ 库到鸿蒙（aarch64-musl）时，编译报 `uintptr_t` 重复定义。其根因是：
+
+musl aarch64 已通过 `<stdint.h>` 定义 `uintptr_t` 为 `unsigned long`，但 CMocka 头文件里面含**平台兜底 typedef**——当条件宏未命中时，它会自行 `typedef unsigned long uintptr_t`，与 stdint 版本冲突。
+
+## 根因
+
+CMocka 头文件的条件守卫链（`_UINTPTR_T` / `_UINTPTR_T_DEFINED` / `HAVE_UINTPTR_T`）**未包含 `__MUSL__` 分支**。musl 确实定义了 `uintptr_t`（通过 stdint），但它不定义这些校验宏——所以 CMocka 回退逻辑误以为 `uintptr_t` 不存在，从而再次 typedef，导致重复定义。
+
+## 修复
+
+在守卫条件中追加 `&& !defined(__MUSL__)`：
+
+```c
+// CMocka 头文件（如 cmocka.h）内的平台兜底 typedef 处
+#if !defined(_UINTPTR_T) && !defined(_UINTPTR_T_DEFINED) && !defined(HAVE_UINTPTR_T) && !defined(__MUSL__)
+typedef unsigned long uintptr_t;
+#endif
+```
+
+也可在编译命令行注入 `-D__MUSL__`（鸿蒙 NDK 工具链本身已定义 `__MUSL__`，通常无需额外注入——需确认 CMocka 的构建系统是否在预处理时清掉了这个宏）。
+
+## 推广
+
+这种「条件宏兜底下定义平台基础类型」的模式在多款 C 库的头文件中存在（不止 CMocka），凡含以下特征的头文件在 musl 系平台上均易踩：
+
+- 自行 `typedef unsigned long uintptr_t`（或其他基础整数类型回退）
+- 守卫条件依赖 `_UINTPTR_T` / `_UINTPTR_T_DEFINED` / `HAVE_UINTPTR_T` 等非 musl 传统宏
+- 同时允许 `__MUSL__` 通过而不拦截
+
+已知受影响库：CMocka、cJSON（含类似类型回退宏）。移植 musl 系平台时应在 patch 阶段 grep 排查 `typedef.*uintptr_t` 条件守卫。
+
+## 排查 grep
+
+```bash
+# 在依赖头文件目录（sysroot 或 build/_deps）
+grep -rn 'typedef.*uintptr_t' --include='*.h' | grep -v 'stdint'
+grep -rn '__MUSL__' --include='*.h'  # 确认 musl 守卫是否已存在
+```
+
+## 相关
+
+- `pc-error-atlas` E129-E131（交叉编译头文件/宏冲突类错误）
+- [[鸿蒙PC-Windows宿主构建环境四坑]] — NDK 封装脚本引号问题同样会掩盖此类宏定义
+- [[鸿蒙PC-OpenSSL系密码库交叉编译]] — 另有平台类型守卫经验

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-ClamAV/346/235/200/346/257/222/345/274/225/346/223/216CLI/347/234/237/346/234/272/351/200/202/351/205/215.md

@@ -0,0 +1,88 @@
+---
+name: 鸿蒙PC-ClamAV杀毒引擎CLI真机适配
+description: ClamAV（C+CMake 主体 + libclamav_rust cargo 子构建）交叉编译到 aarch64-unknown-linux-ohos 全链路：CMAKE_FIND_ROOT_PATH 聚合依赖、-DDATABASE_DIRECTORY 绝对路径直通 DATADIR（默认库目录烘焙到设备 HNP 落点）、UT_SRCDIR/UT_OBJDIR 设备路径覆盖、-ltime_service_ndk 补 iana-time-zone 符号、conan check 包要 -DLIBCHECK_INCLUDE_DIR/-DLIBCHECK_LIBRARY 显式指包否则 ENABLE_TESTS=ON 报 Could NOT find Libcheck；设备侧五坑——EICAR 必须精确 68 字节（hdb md5 按 68B 样本算）、宿主 Defender 拦 EICAR 落盘（夹具内存构造直写 zip 条目）、CVD_CERTS_DIR 须指 signing/verify 且测试 CA 与生产证书（上游 certs/clamav.crt）分管测试夹具与真实 CDN 验签、freshclam.conf 无 LogFile 选项（用 UpdateLogFile）、交互式示例 scanf EOF 死循环（--script 非交互）；阶段 6 采集窗口工程化——bytecode.cvd 小库做真实 HTTPS 更新、MaxAttempts 1 砍重试等待。触发词：ClamAV、clamscan、clamd、freshclam、sigtool、libclamav、杀毒、病毒库、EICAR、hdb、CVD、clamav.hdb、check_clamav、libcheck、LIBCHECK_INCLUDE_DIR、LIBCHECK_LIBRARY、Could NOT find Libcheck、ENABLE_TESTS、bytecode、clamav.crt、certifi、--update-db、MaxAttempts、ex_scan_callbacks、--info、Verification OK
+metadata:
+  type: adaptation
+  source: new/PC（ClamAV 1.6.0-devel 全家桶 CLI 形态真机 19/19 + 阶段 6 16/16 实证，2026-09-07）
+---
+
+# 鸿蒙 PC：ClamAV 杀毒引擎 CLI 全家桶真机适配
+
+> ClamAV 1.6.0-devel（clamscan/clamd/clamdscan/freshclam/sigtool/clamconf/clambc/
+> clamsubmit + libclamav.so/libfreshclam.so + libclamav_rust + examples + libcheck
+> 单测）交叉到 `aarch64-unknown-linux-ohos`，私有 HNP 部署零售机真跑：阶段 3 名册
+> 19/19（含 check_clamav 1344 子项 99%）、阶段 6 PRD 用例 16/16。
+> 通用骨架见 [[鸿蒙PC-C++库交叉编译要点]]，本文只记 ClamAV 特有的坑与对策。
+
+## 一、构建侧（CMake 主体 + cargo 子构建）
+
+| 关键项 | 做法 |
+|---|---|
+| 依赖根聚合 | `-DCMAKE_FIND_ROOT_PATH=<每个 deps/<name>/dist 的绝对路径>`（ohos.toolchain.cmake 设了 FIND_ROOT_PATH_MODE ONLY，漏一个就 find_package 失败） |
+| 默认病毒库目录 | `-DDATABASE_DIRECTORY=<设备HNP>/share/clamav` **绝对路径直通**（CMakeLists 支持 IS_ABSOLUTE 分支；ex_basic_scandesc 等示例用 cl_retdbdir() 默认加载）。别指望 CMAKE_INSTALL_PREFIX——绝对 DATABASE_DIRECTORY 才是正路 |
+| 单测路径 | `-DUT_SRCDIR=<设备HNP>/share/ut -DUT_OBJDIR=<沙箱>/utobj`（补丁加 UT_ 覆盖分支：SRCDIR 走 HNP 只读区、OBJDIR 走应用可写区） |
+| 链接 | `-DCMAKE_SHARED_LINKER_FLAGS='-ltime_service_ndk -Wl,--code-sign'`（iana-time-zone 要 OH_TimeService_GetTimeZone）+ `-DCMAKE_INSTALL_RPATH=$ORIGIN/../lib` |
+| Rust 子构建 | 见 [[鸿蒙PC-Rust-build-script宿主cfg泄漏与OHOS交叉链接]]（build.rs 两处 CARGO_CFG_TARGET_OS 补丁 + windows-gnu 宿主三件套） |
+| libcheck | conan check/0.15.2 复用；设备跑单测的 TEMP 前置见 [[鸿蒙PC-应用沙箱临时目录语义与libcheck-TEMP选址]] |
+| libcheck 检测坑 | 自定义 minimal toolchain（不含 conan_toolchain.cmake）没把 check 包加进 `CMAKE_FIND_ROOT_PATH`，`FIND_ROOT_PATH_MODE_LIBRARY/PACKAGE=ONLY` 下 `find_package(Libcheck)` 落空 → `ENABLE_TESTS=ON` 时 configure 报 `Could NOT find Libcheck (missing: LIBCHECK_INCLUDE_DIR LIBCHECK_LIBRARY)`。修法：显式 `-DLIBCHECK_INCLUDE_DIR=<conan-pkg>/p/include -DLIBCHECK_LIBRARY=<conan-pkg>/p/lib/libcheck.a`（conan 包哈希形如 `~/.conan2/p/check<12位>/p`）。同理适用于任何「conan 中心仓 + 自定义 minimal toolchain」组合里 Find<X> 找不到的测试框架库（gtest/catch/…） |
+
+## 二、EICAR 三坑（漏检排查第一现场）
+
+1. **精确 68 字节**：官方 EICAR 串 + 换行 = 69 字节 → md5 与 `44d88612…:68` 签名
+   失配 → **静默漏检**（扫描 rc=0 "OK"）。夹具必须无尾换行；zip/tar.gz 内嵌的
+   EICAR 同理从 68B 源构造；
+2. **宿主 Defender 拦截**：Windows 实时防护对落盘的 EICAR 文本「可写不可读」
+   （Errno 22）——夹具在打包脚本里**内存构造、直写 zip 条目**，全程不落盘；
+   HNP 打包脚本里放 `assert len(EICAR) == 68` 防回归；
+3. **签名名断言**：非官方 hdb 检出的名字带 `.UNOFFICIAL` 后缀
+   （`Eicar-Test-File.UNOFFICIAL`），断言用子串 `Eicar-Test-File`。
+
+## 三、CVD 验签：测试 CA 与生产证书是两套
+
+- libclamav 的 Rust codesign `Verifier::new(certs_dir)` **非递归**读目录内
+  `.crt/.pem`（子目录里的证书不算数）——`CVD_CERTS_DIR` 必须直指
+  `<unit_tests>/input/signing/verify`（上游单测同款）才能验签测试夹具 test-1.cvd；
+- **真实 CDN 的 daily/bytecode CVD 是 PKCS7 codesign 签名**，测试 CA 验不了——
+  用上游随源码分发的生产证书 `source/certs/clamav.crt`（Linux 安装到 CERTSDIR 的
+  那份）随 HNP 打包，跑真实更新时把 `CVD_CERTS_DIR` 切到它；
+  （daily.cvd 另有 legacy RSA 硬编码公钥兜底，所以「只下 daily」时即使证书没配
+  也可能过——bytecode.cvd 没有 legacy 兜底，是验证书配置的更严判据）；
+- 设备上没有系统 CA 库，freshclam HTTPS 另需 libcurl `CURL_CA_FALLBACK` 重建 +
+  certifi bundle 随包 + `SSL_CERT_FILE`，全链见
+  [[鸿蒙PC-交叉libcurl空CA信任锚与SSL_CERT_FILE]]。
+
+## 四、freshclam.conf 与用例窗口工程
+
+- **freshclam 没有 `LogFile` 选项**（那是 clamd 系的；freshclam 用 `UpdateLogFile`），
+  conf 里写 LogFile 直接 `Parse error: Unknown option`；
+- **逐用例采集窗口约 4s**（设备验证单用例拉起的固定节奏）：
+  - 大库全量更新（daily.cvd 约 23MB、20s+）超窗——用 `--update-db=bytecode`
+    （百余 KB，DNS+TLS+下载+PKCS7 验签全真，2-3s 完成）作等价判据，全量更新
+    证据另在整轮跑里补；
+  - 网络报错用例设 `MaxAttempts 1` 砍掉 3 次重试 × 5s 的等待；
+  - DNS 探测能拿到 remote version 说明网络面通，error 60 才是证书面问题。
+- freshclam/clamd 都要**可写 DatabaseDirectory**（HNP 落地区只读）——执行器先把
+  hdb 拷到应用沙箱再指过去。
+
+## 五、交互式示例与其他
+
+- `ex_scan_callbacks` 是交互式示例：无 stdin 时 `scanf` EOF → `getchar()` 立即
+  返回 → `printf("Invalid input")` **无限递归爆栈**。设备跑必须 `--script <文件>`
+  非交互（脚本耗尽干净 CL_BREAK 中止；脚本行 2=继续扫、3=认可告警）；
+- `ex_basic_scandesc` 只收 file 参数、库从编译期 DATADIR 加载——这就是第一节
+  DATABASE_DIRECTORY 绝对路径的动因；
+- check_clamav 的 OBJDIR/input 需要**构建期反混淆**出的扫描样本（源树只有
+  `.xor` 混淆版，de-xor 产物在 build/unit_tests/input）——随 HNP 携带、执行器
+  拷进沙箱 utobj/input/ 还原构建目录形态；
+- 单测里 symlink 用例（替换符号链接）在沙箱必失败——按
+  [[鸿蒙PC-应用沙箱symlink禁令与aa换代语义]] 豁免；
+- bytecode 的 arith.cbc 合成压力夹具：aarch64 无 ClamAV JIT 后端（仅
+  x86/PPC/ARM32），解释器 interp_op 映射不支持 >65 操作数指令形态（stderr 见
+  `unknown inst type: 96/67`）——该族失败按已知平台限制豁免，真实场景字节码
+  （lsig/pdf/inflate/apicalls…）全过。
+
+## 相关
+
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] + E134：装机 9568407 的 zip 布局契约
+- [[鸿蒙PC-Rust-build-script宿主cfg泄漏与OHOS交叉链接]] Rust 侧全配方
+- [[鸿蒙PC-交叉libcurl空CA信任锚与SSL_CERT_FILE]] freshclam HTTPS 的前置

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-C/345/272/223/350/256/276/345/244/207/351/252/214/350/257/201/346/265/213/350/257/225/350/256/276/350/256/241.md

@@ -0,0 +1,62 @@
+---
+name: 鸿蒙PC-C库设备验证测试设计
+description: C/C++ 库设备验证的测试设计方法——上游套件优先（source/ 有测试必须移植执行，手写冒烟仅在无上游套件时合法，含上游测试编进 NAPI 壳的通用手法）、按 API 族组织的边界用例模板库（数值解析族/编码往返族/fd 生命周期族/流操作族）、API 族三分法（纯函数全测/syscall 族按矩阵分流/交互族失败路径）。触发词：上游测试、自带测试套件、测试移植、main 宏改名、NAPI 壳、测试壳、边界用例、LLONG 边界、空串、尾随垃圾、往返一致、缓冲截断、关闭后操作、多流轮转、测试覆盖面、自选用例、happy path、冒烟用例、测试设计、用例模板。
+metadata:
+  type: adaptation
+  source: libbsd 0.12.2 外部一致性测试对照实证（上游 25 用例 vs 手挑 25 个，2026-08）
+---
+
+# 鸿蒙 PC：C 库设备验证的测试设计    
+
+## 为什么需要这页
+
+设备验证的测试面如果靠手挑，会产生系统性盲区——一次对照实证：某 BSD 实用函数库的设备验证手挑了 25 个 API 写冒烟壳全绿收工，而同库的外部一致性测试（上游 25 个官方用例的完整移植 + 系统性边界用例）抓出 **72 个 FAIL/CRASH**：手挑壳恰好没选中的 stringlist 族、上游测试恰好覆盖的 strtonum 全部边界。手挑的「全绿」证明不了产物正确，只证明了被测的那部分正确。
+
+三节回答三个问题：**测什么**（上游套件优先）→ **怎么测全**（边界模板库）→ **怎么分配投入**（API 族三分法）。
+
+## §1 上游套件优先原则
+
+**source/ 下存在测试 → 必须移植执行**（`test_source=reused/mixed`）；原库没有测试套件，才允许在 `tests-generated/` 补写冒烟用例（`generated`，并在 notes 写明为何无上游可用）。手写弱替上游测试 = 自选分母。
+
+**上游测试编进 NAPI 壳的通用手法**（零售机 app 域跑不了裸 ELF，测试须编进 demo 库）：
+
+1. 上游 `test/*.c` 的 `main()` 宏改名（`#define main test_foo_main`），编进验证 demo 库的同款 NAPI 壳工程；
+2. 壳的 `CallLib()` 逐个调用改名后的入口，捕获其输出/退出码——上游测试多自带 `static int fail` 计数器与逐条打印，直接透传给 hilog；
+3. 上游测试若 `exit()`/`abort()`，包一层 `fork`+`waitpid` 或改 patch 成返回值（改动落 patches/）；
+4. 断言输出经 hilog 落盘 `build/test-device-raw.log`，**必须以完成标记结尾**（03-adapt.json 的 `test_run.completed`）。
+
+收益实证：上游 strtonum 测试 64 行恰好覆盖该 API 全部边界场景（LLONG 邻域、超限、超长数字串、区间倒置）——手写冒烟只测了 2 个 happy path。**上游测试比手写的更懂这个库该测什么。**
+
+## §2 边界用例模板库（按 API 族组织）
+
+无上游套件或上游覆盖有缺口时，按族取模板补齐——这些族是可枚举的，不是灵感：
+
+| API 族 | 必测边界 | 适用 API 形态 |
+|---|---|---|
+| **数值解析族** | LLONG/INT64 边界邻域、超上限/低于下限、空串、尾随垃圾字符、非法字符、上下限倒置、超长数字串 | 任何 `strto*`/`ato*` 风格解析函数、带范围的校验器、数值单位换算（expand/dehumanize 系） |
+| **编码往返族** | 编码→解码往返一致、高位非法字节（多字节语义，先查 [[鸿蒙PC-musl与BSD-glibc语义分歧表]]）、缓冲截断不越界、flags 组合产生可观测不同输出、空输入 | 可视化编码/转义/base64/mime 系 |
+| **fd 生命周期族** | 关闭后再操作（EBADF）、句柄重建后一致性、重复关闭、写入后读回一致 | pidfile/flopen/closefrom 等一切持 fd 的 API（fd 测试的目录选择见 [[鸿蒙PC-app域测试前置条件矩阵]] HMDFS 节） |
+| **流操作族** | 多流轮转缓冲不串扰、读空流/EOF 后行为、自定义回调流（read/write/seek/close 逐个触发） | fgetln/fparseln/funopen 等 stdio 封装（musl fopencookie 语义差异先查分歧表族 2） |
+| **格式化族** | 格式串与实际类型不符（fmtcheck 类）、输出缓冲恰好不够/恰好够、负数/零/极大值格式化 | 任何 printf 风格校验/格式化 |
+
+模板用法：对目标库的每个公开 API，问「它属于哪个族」→ 族内边界逐条造用例。断言写法遵循分歧表的改写原则：**契约级断言（返回值语义/错误码）保留，平台字面量按 musl 写**。
+
+**断言前必须打印实际值**：每条 `assert` 前一行 `printf("<被测函数名> → %<格式符>\n", <变量>);`——测试程序不只是判定器，也是**证据生产者**。静默 assert 型在设备上是黑盒：rc=0 只证明"没挂"，测试同学看不到值、无法人工核对（libbsd 2026-09 测试同学实证反馈："叙述像标题+步骤+预期摘抄，无法实际判断"）。注意格式串里**只放函数名/变量名，不放参数原文**——参数含引号/`%` 会注入 printf 格式串（编译错或输出错乱）；循环内断言用下标标注（`printf("[i=%d] %d\n", i, arr[i])`）。
+
+**printf 行带步骤锚点**：值行的格式串前加 `[cp:N]` 前缀（N = 该断言对应的 `steps[].checkpoint` 下标，0 起）——`printf("[cp:1] _time_to_time32 → %d\n", t32);`。**收尾自查：每条 checkpoint 至少有一个锚点行**（锚点数 ≥ checkpoint 数）。锚点一举两得：①页面结果区里值行与用例步骤**人眼可归属**（对上"这行验证的是第几步"）；②自查即覆盖对账——漏测某步会被"该步无锚点"当场暴露（libbsd F-14-01 反例：第二步超范围转换被静默跳过，叙述只体现第一步，测试同学人肉对出才发现，2026-09）。
+
+## §3 API 族三分法（测试投入分配）
+
+| 族 | 判定 | 测试策略 |
+|---|---|---|
+| **纯函数族** | 入参是值/枚举/位掩码，无 IO | **全测**——零环境依赖、零成本，一次外部对照里 60+ 个此类符号可全部覆盖 |
+| **syscall 触碰族** | fd/socket/进程/信号/批量 IO | 查 [[鸿蒙PC-app域测试前置条件矩阵]] 分流：前置可满足 → 按等价构造法测；被 seccomp/SELinux 拦 → 走 failure-triage 的三级回退决策树（patch 回退优先于验证降级） |
+| **交互终端族** | /dev/tty、交互式输入 | 失败路径必测（返回 NULL + errno），成功路径判豁免并归 testenv-limited |
+
+三分法同时回答「归因往哪走」：纯函数族 FAIL 多半是 product-defect 或预期来源错（无环境噪声）；syscall 族 FAIL 先过 seccomp/SELinux 关卡排查；交互族按豁免程序走。
+
+## 相关条目
+
+- [鸿蒙PC-musl与BSD-glibc语义分歧表.md](../platform/鸿蒙PC-musl与BSD-glibc语义分歧表.md) — 断言改写权威（模板造出的用例怎么写预期）
+- [鸿蒙PC-app域测试前置条件矩阵.md](../platform/鸿蒙PC-app域测试前置条件矩阵.md) — 前置可行性权威（syscall 族测试怎么落地）
+- `pc-device-verify/references/failure-triage.md` — FAIL 归因分诊（四分类 + 三级回退决策树）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-GLFW/350/247/206/347/252/227/345/220/216/347/253/257-EGL-XComponent.md

@@ -0,0 +1,55 @@
+---
+name: 鸿蒙PC-GLFW视窗后端-EGL-XComponent
+description: 给 GLFW 加鸿蒙(OHOS)平台后端的完整套路——填 _GLFWplatform vtable、EGL 访问器返回值、Vulkan VK_OHOS_surface、平台ID双白名单坑、musl _DEFAULT_SOURCE
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+给 GLFW（3.5, commit ed6452b）加一个鸿蒙原生后端 `_GLFW_OHOS`，跑在 XComponent→OHNativeWindow 缝上，EGL/GLES 渲染。2026-07-01 **真机端到端跑通**（HAD-W32/API23）：桌面窗口内旋转彩色三角形连续渲染（`GL_VERSION=OpenGL ES 3.2`），VSync 帧回调驱动、无崩溃。本机 DevEco NDK 交叉编译出 `libglfw3.a`(OHOS+Null 双后端) + 签名 HAP，三 `.so` 均 4KB 对齐。后端坐在 [[鸿蒙PC-通用视窗桥ohos_window_bridge]] 上，不直接碰 XComponent/NativeWindow。
+
+## 加后端 = 5 新文件 + 4 处上游改动（全可 patch 重放）
+- **新文件**（照抄 `null_*` 骨架 + `wl_*` 作 EGL-only 模板）：`src/ohos_platform.h`（4 个 `GLFW_OHOS_*_STATE` 宏 + `_GLFWwindowOhos`(存 `OHNativeWindow*`/surfaceId) + 全部 `_glfw*Ohos` 声明）、`ohos_init.c`（`_glfwConnectOhos` 填 vtable + init/terminate + OHOS键码映射）、`ohos_window.c`（创建窗口=OWB取surface+`_glfwInitEGL`/`_glfwCreateContextEGL`；事件泵 `OWB_PollEvent`→`_glfwInput*`；EGL 三访问器；Vulkan surface；其余窗口op stub）、`ohos_monitor.c`（单显示器）、`ohos_joystick.c`（stub）。
+- **上游改动**：`include/GLFW/glfw3.h`(+`GLFW_PLATFORM_OHOS 0x00060006`)、`src/platform.h`(OHOS `#include` 块 + 4 个聚合宏加 `GLFW_OHOS_*_STATE`)、`src/platform.c`、`src/CMakeLists.txt`+顶层`CMakeLists.txt`(`GLFW_BUILD_OHOS` 选项/源/`_GLFW_OHOS`宏)。
+
+## 五个必踩的坑（按血泪程度排）
+1. **平台ID 要加进两处白名单**（不止 supportedPlatforms[]）：`platform.c` 的 `_glfwSelectPlatform`(~L66) **和** `glfwPlatformSupported`(~L146) 各有一张硬编码 `desiredID != GLFW_PLATFORM_*` 校验表；只注册 connect 而不加白名单，`glfwInit(GLFW_PLATFORM_OHOS)` 直接报 "Invalid platform ID 0x60006"。
+2. **musl 严格 c99 隐藏 POSIX 时钟**：GLFW 用 `C_STANDARD 99 / C_EXTENSIONS OFF`（→`-std=c99`），而 GLFW 的 `_DEFAULT_SOURCE` workaround 只在 `CMAKE_SYSTEM_NAME==Linux` 时加。OHOS 的 `CMAKE_SYSTEM_NAME==OHOS`，于是 `posix_time.c` 里 `CLOCK_MONOTONIC`/`clock_gettime` undeclared。修：`GLFW_BUILD_OHOS` 块里 `target_compile_definitions(glfw PRIVATE _GLFW_OHOS _DEFAULT_SOURCE)`（自写的 OWB `bridge.c` 同理，顶部 `#define _POSIX_C_SOURCE 200809L`）。
+3. **64KB 对齐会崩，要 4KB**：见 [[鸿蒙PC-64KB页对齐so崩溃]]。链接 `.so` 加 `-Wl,-z,max-page-size=0x1000`（**0x1000 好、0x10000 崩**，别记反）。libglfw3.a 是静态库(.a)无 LOAD 段不受影响；受影响的是最终 `libglfw_demo.so`/`libohos_window_bridge.so`。hvigor 默认出 0x1000，但显式加保险。
+4. **EGL context 默认是 desktop GL**：`glfwWindowHint(GLFW_CLIENT_API, GLFW_OPENGL_ES_API)` 必设，否则请求 desktop OpenGL 在鸿蒙拿不到。默认 `GLFW_CONTEXT_CREATION_API=NATIVE`——OHOS 后端把 NATIVE 与 EGL 都走 `_glfwInitEGL`（同 Wayland）。且 `glfwGetEGLContext` / `glfwGetEGLSurface` / `glfwGetEGLConfig` 三访问器要求 `context.source == EGL`，创建前须**同时** `glfwWindowHint(GLFW_CONTEXT_CREATION_API, GLFW_EGL_CONTEXT_API)`，否则上下文起来了、访问器却恒返空。
+5. **EGL/GLES soname 对不上（真机才暴露）**：GLFW `egl_context.c` 在 Linux 分支默认 dlopen `libEGL.so.1` 与 `libGLESv2.so*`，但设备 app NDK 命名空间里只有**裸** `libEGL.so` + `libGLESv3.so`（无 `.1`、无 GLESv2）。于是 `_glfwInitEGL` dlopen 失败 → `glfwCreateWindow` 返回 NULL（hilog: `load libEGL.so.1 failed ... glfwCreateWindow failed`）。修：`-D_GLFW_EGL_LIBRARY=\"libEGL.so\" -D_GLFW_GLESV2_LIBRARY=\"libGLESv3.so\"`（GLFW 支持这俩覆盖宏）。这是构建期链 `libEGL.so`（NEEDED 对）掩盖不了的——GLFW 是运行时 dlopen 拿自己的 handle，名字必须对上。
+
+## EGL 三访问器返回值（`egl_context.c` 只经这 3 个钩子，本体不改）
+- `_glfwGetEGLPlatformOhos` → **返回 0**（无 `EGL_PLATFORM_*_EXT`，走 `eglGetDisplay`+`eglCreateWindowSurface` 平凡路径）。
+- `_glfwGetEGLNativeDisplayOhos` → **`EGL_DEFAULT_DISPLAY`**。
+- `_glfwGetEGLNativeWindowOhos` → **`(EGLNativeWindowType)window->ohos.nativeWindow`**（OHNativeWindow*，创建窗口时从 OWB 取、存进 `ohos` 状态；SURFACE_CHANGED 更新、销毁释放——生命周期对齐 Wayland 的 `wl.egl.window`）。
+
+## 上屏排障：设备 GL 开箱即用，别编造根因（2026-07-22 复现 + 修）
+真机 `GL_VERSION=OpenGL ES 3.2 / GL_RENDERER=Maleoon 916`（华为 GPU，硬件渲染），framebuffer 2090×1324——**EGL/GLES 开箱即用，无需 `NEED_OPENGL`，无 `libiGraphicsCore` 之说**（那是某次跑「窗口出来但没渲染」时**没抓日志/截图、凭空编的设备 GL 栈根因**，全属虚构：设备 `/system/lib64` 有 `libEGL.so`/`libGLESv3.so`，`find` 根本无 `libiGraphicsCore`）。
+- **铁律**：demo 没渲染时，**先 `DLOG` 打 `glGetString(GL_RENDERER/GL_VERSION)` + shader `GL_COMPILE_STATUS` + `snapshot_display` 截图**，拿到实据再归因；红色 `glClearColor` 一试就知道 GL 到没到屏。别把「三角形没画出来」写成「EGL 初始化失败」。
+- **demo 矩阵坑（全黑窗真凶）**：`m[15]=0`→顶点 `w=0` 裁到无穷远、或 C 行主序喂 GLSL 列主序——**别从零写渲染 demo**。正解与告警的**权威在 vendored 上屏 demo**：`pc-capability-domains` 的 `solutions/ohos-window-bridge/examples/glfw-triangle/cpp/glfw_triangle.cpp`（真机验证、照抄它改 `render()` 即可），本处不复述。
+- **动画不动 = 计时基准写成了帧间隔**：旋转/位移 demo 若「静帧」，查计时基准——**累计时间在渲染循环外取一次、循环内只读不重置**（`angle = now - t0` 持续增长 → 连续旋转）。若把 `t0 = now` 写进循环内，`angle` 恒等于帧间隔（~16ms），每帧画同一角度 → 静帧。计时逻辑以 vendored `glfw-triangle` 参考 demo 为准，勿自行改写。
+- 签名装机走 **`ohpt-agent sign-demo -w <ws> --install`**（SDK OpenHarmony 材料，见 platform/鸿蒙PC-HAP调试签名与设备安装信任链.md）。构建用 DevEco 全局 `$DEVECO_SDK_HOME/../tools/hvigor/bin/hvigorw assembleApp --mode project`（工程内 `./hvigorw` 可能被 clean 掉）。
+
+## Vulkan：VK_OHOS_surface 可用（NDK 已确认），非 stub
+`vulkan/vulkan_ohos.h` 有 `vkCreateSurfaceOHOS(inst, &VkSurfaceCreateInfoOHOS{.window=OHNativeWindow*}, ...)`，`VK_STRUCTURE_TYPE_SURFACE_CREATE_INFO_OHOS=1000685000`。GLFW 自带精简 Vulkan typedef，**别 include vulkan_ohos.h**（会和 GLFW 的定义打架）——在 `ohos_window.c` 里自定义一个 ABI 兼容的 `{int sType; const void* pNext; uint32_t flags; void* window;}` 局部结构 + 用 `vkGetInstanceProcAddr(inst,"vkCreateSurfaceOHOS")` 动态取函数指针。`getRequiredInstanceExtensions` 返回 `VK_KHR_surface`+`VK_OHOS_surface`（GLFW 的 `_glfw.vk` 不认识 OHOS_surface 字段，别引用它，只 gate `_glfw.vk.KHR_surface`）。
+
+## 事件翻译（OWB → GLFW）
+`_glfwPollEventsOhos` 排空 `OWB_PollEvent`，按 surfaceId 找 `_GLFWwindow`（遍历 `_glfw.windowListHead`）。OWB 的 mods 位掩码与 GLFW 的 `GLFW_MOD_*` **数值一致**可直传；action 要翻（OWB_ACTION_DOWN→GLFW_PRESS 等，REPEAT 值不同）。OHOS 键码在 2000 段（`KEY_A=2017..Z` 连续、`KEY_0=2000..9`、`ESCAPE=2070`、方向键 `DPAD_*=2012-2015`），写个 `_glfwMapOhosKeyCode`。触摸映射成 cursor+左键。
+
+## 窗口控制（2026-07-01 补，真机验证 resize/maximize/restore）
+`ohos_window.c` 的窗口 op stub 换真，全经 OWB：
+- 几何（`setWindowSize/Pos/iconify/maximize/restore/limits/fullscreen/title`）→ `OWB_RequestWindowOp(...)` → 反向桥 → ArkTS `@ohos.window`（**无 native 路径**，见 [[鸿蒙PC-窗口几何控制无native只ArkTS]]）。真机实测 `glfwSetWindowSize(900,600)` 窗口 rect 真变、`glfwMaximizeWindow` 全屏、`glfwRestoreWindow` 还原。
+- 光标（`setCursorMode(DISABLED)`→`OWB_LockCursor(sid,0)`、`CAPTURED`→`LockCursor(sid,1)`、`NORMAL`→`UnlockCursor`）+ `rawMouseMotionSupported`→TRUE；`getWindowPos`→`OWB_GetWindowRect`（Tier A 纯 native `OH_WindowManager_*`）。
+- `setWindowMonitor`（全屏切换）→ `OWB_WOP_FULLSCREEN`；记得 `window->monitor = monitor`。
+- **demo 触发**：`DispatchTouchEvent` 里点击循环 resize→maximize→restore；`uinput -T -c x y` 注入 tap 真机验证。
+
+## 线程壳适配（2026-07-02 补，真机验证）——bindSurface 等 surface
+为让存量桌面应用**原样 `int main(){…while(!glfwWindowShouldClose)…}`** 跑在鸿蒙（worker 线程壳，见 [[鸿蒙PC-通用视窗桥ohos_window_bridge]] 的 owb_ohos_app.h），GLFW L3 只补一处：`bindSurface`（`ohos_window.c`）首轮扫不到空闲 surface 时 `OWB_WaitForSurface(10.0)` **阻塞等** JS 线程 `OnSurfaceCreated` 登记，再扫一轮。因为线程壳里 `glfwCreateWindow` 跑在 worker 线程，可能早于 JS 线程建 surface——不等就直接 `glfwCreateWindow failed`。这一处外加 OWB 的 `OWB_WaitForSurface`，GLFW 就能被"零改动 main()"消费。demo 已改成纯桌面 `int main()`（删掉自带 XComponent 回调/OnFrame）+ `glfwSwapInterval(1)`（eglSwapBuffers vsync 节流，替代 OnFrame 驱动）。
+
+## 相关
+- [[鸿蒙PC-窗口几何控制无native只ArkTS]] —— 几何为什么走 ArkTS + 反向桥套路 + Qt 实证。
+- [[鸿蒙PC-通用视窗桥ohos_window_bridge]] —— 后端坐的公共缝层（本条只讲 GLFW 侧）。
+- [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]] —— 同一道缝的 CPU 变体 + 原始 XComponent 接法。
+- [[鸿蒙PC-64KB页对齐so崩溃]] —— 坑 3。
+- [[鸿蒙PC-C++库交叉编译要点]] —— OHOS NDK/ohos.toolchain.cmake 通用要点。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-GTK/345/272/224/347/224/250broadway-ArkWeb-HAP.md

@@ -0,0 +1,42 @@
+---
+name: 鸿蒙PC-GTK应用broadway-ArkWeb-HAP
+description: 把 GTK3 应用打成鸿蒙 HAP 的完整可行方案——broadwayd 渲染到浏览器 + ArkWeb Web 组件显示，真机交互成功
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+2026-06-26 **打通并真机验证**：一个完整、可交互的 GTK3 应用跑在鸿蒙 PC 的普通 HAP 里。机制 = GTK broadway 后端把界面渲染到内置 HTTP/WebSocket 服务(`broadwayd`)，HAP 用 ArkWeb `Web` 组件加载 `http://127.0.0.1:8082` 显示。点击按钮 → label 变 "clicked 2 times"，**双向通路(渲染+输入)全通**。前置：整套 GTK 栈从源码交叉编译（见 [[鸿蒙PC-cmd-pkgs预编译GTK栈不可用]]）、64KB 页对齐崩溃已解（见 [[鸿蒙PC-64KB页对齐so崩溃]]）。
+
+## 架构（一句话）
+```
+GTK app (GDK_BACKEND=broadway) ──unix socket──> broadwayd ──HTTP/WS :8082──> ArkWeb Web组件
+        ↑________________________ 点击/键盘事件反向回传 ________________________↓
+```
+- broadwayd 与 GTK app 都是 NDK 交叉编译的 ELF，打进**私有 HNP**随 HAP 分发，app 域原生模块 `fork/execve` 启动（见 [[鸿蒙PC-app域执行二进制与JIT限制]]）。**broadwayd 是自己编的 → app 域可直接 exec**（cmd-pkgs 预编译的 broadwayd 会被 XPM 拒）。
+- ArkWeb 是 Chromium 内核，`Web({src:'http://127.0.0.1:8082/'})` 直接连本地 broadwayd，**无需端口转发/外网**，只要 `ohos.permission.INTERNET`。
+
+## 关键落地点
+1. **HNP 内容**：`bin/{broadwayd,gtkapp}` + `lib/`（整套 GTK .so，全部 4KB 对齐，stripped）+ `lib/gdk-pixbuf-2.0/`（loaders）+ `etc/fonts/fonts.conf`。`hnpcli pack` 打包，module.json5 声明 `hnpPackages` type=private，hvigor 自定义 task 注入 .hnp（抄 nmap-hap/opencode）。
+2. **原生启动器**（napi 模块）：`realpath(/data/app/bin/broadwayd)` 解私有 HNP 真实根 → 设 env → `fork/execve` 先起 `broadwayd :2`、睡 ~900ms、再起 GTK app。env 必备：
+   - `LD_LIBRARY_PATH=<hnp>/lib`
+   - `GDK_BACKEND=broadway`、`BROADWAY_DISPLAY=:2`（:2 → HTTP 端口 8082 = 8080+display）
+   - `FONTCONFIG_FILE=<hnp>/etc/fonts/fonts.conf`（内容 `<dir>/system/fonts</dir>` 用设备字体；缺了字体加载失败、GTK 文字不显示甚至 "infinite surface size"）
+   - `XDG_RUNTIME_DIR/HOME/TMPDIR/XDG_CACHE_HOME` 指 app 可写目录 `/data/storage/el2/base/haps/entry/files/run`（broadwayd 的 unix socket、fontconfig cache 落这）
+   - `GDK_PIXBUF_MODULEDIR=<hnp>/lib/gdk-pixbuf-2.0/2.10.0/loaders`
+3. **ArkUI 页面**：`aboutToAppear()` 调原生 `startGtk()` 启动 broadwayd+app；`Web({src:'http://127.0.0.1:8082/', controller})` 占满窗口。带一个"重新加载"按钮（broadwayd 起得慢时 reload 一下）。
+4. **app 域 shm**：broadway 用 `/dev/shm`（app 域可写，1GB tmpfs）。残留 `bdw-*` 段会让下次 `map_named_shm` 断言失败——启动器或重测前 `rm /dev/shm/bdw-*`（app 域能删自己建的）。
+
+## 验证结果（真机 HarmonyOS PC）
+- `pidof com.qt.calculator` / `broadwayd` / `gtkdemo` 三个进程都活在 **app 域**。
+- ArkWeb 窗口里显示完整 GTK3 窗口（标题栏 + label「Hello from GTK3 broadway 鸿蒙 PC」+ 按钮，字体正常）。
+- `uinput -T -c x y` 点按钮 → label 变「clicked 2 times」→ 证明输入回传 + 重绘闭环。
+
+## 实战交付：nmap GTK 图形前端（Zenmap 式，C 实现）
+基于此壳交付了真正的 nmap 图形界面 `nmapgtk.c`（GTK3 C 程序，~180 行）：target/ports 输入 + 扫描类型下拉 + `GtkTextView` 结果区；点"扫描" → `g_subprocess_newv` 异步起 nmap（路径/数据目录由启动器经 `NMAP_BIN`/`NMAP_DATADIR` env 传入）→ `g_subprocess_communicate_utf8_async` 回调把输出灌进 TextView。**nmap 与 GTK 前端打进同一个私有 HNP**（前端 exec nmap，二者都在 `<hnp>/bin/`）。真机点"扫描"扫 scanme.nmap.org → 显示 `22/tcp open ssh / 80/tcp open http / 443/tcp closed`。产物 `dist/nmap-gtk-hap/nmap-gtk-scanner.hap`(30MB)。这条路**完全绕开 PyGObject/introspection**（那是 Zenmap-Python 的墙，见 [[鸿蒙PC-PyGObject-introspection交叉编译墙]]），是鸿蒙上做"C 库 GUI 工具"的可复制模板。
+
+## 对 Zenmap/nmap GUI 的意义
+Zenmap 就是 **GTK3(PyGObject) 应用** → 走完全相同的 broadway→ArkWeb 通路。剩下只是：设备 Python 运行时（已有，见 [[鸿蒙PC-设备Python运行时]]）+ PyGObject + gobject-introspection typelib（交叉编译硬骨头）+ Zenmap 平台分支（nmap 路径指向私有 HNP，见 [[鸿蒙PC-nmap-autotools交叉编译与真机扫描]]）。**纯 C 的 GTK 这条路已完全证明**，Python 层是下一步。
+
+## 与 XComponent 直绘路线对比
+另有 gdk-ohos 后端把 Cairo 直绘进 XComponent（缝已验证 [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]]），原生无 browser 开销，但要从零写数千行 GDK 后端。**broadway 路线零后端代码、已跑通**，是当前首选；gdk-ohos 留作性能优化退路。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Java-JNI/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221/344/270/216/350/256/276/345/244/207/345/233/236/345/275/222-jansi.md

@@ -0,0 +1,41 @@
+---
+name: 鸿蒙PC-Java-JNI库交叉编译与设备回归-jansi
+description: 首个 Java JNI 库完整案例（jansi）：NDK 直编复用上游 Makefile 变量、OSInfo os.name 两策略映射、musl termios 字段名、自签加载、jar 重打包验证、junit-console 设备全量回归（115 用例 0 回归）
+metadata:
+  type: adaptation
+  source: jansi 2.4.4-SNAPSHOT 案例（debuggable 鸿蒙 PC，HongMeng 1.12.0 aarch64）
+---
+
+# 鸿蒙 PC：Java JNI 库交叉编译与设备回归（jansi 案例）
+
+适用：Java 库带 JNI 原生层（jansi/jline 类终端库、及一切「jar 内嵌多平台 .so」形态）。骨干见 pc-knowledge-base 主文档；本文只写 Java JNI 特有增量，已有知识全用指针。
+
+## 配方总览（六步）
+
+1. **交叉编译 JNI .so**：不给上游构建系统打交叉编译补丁——用 OHOS NDK 的 `aarch64-unknown-linux-ohos-clang` 直编，**复用上游 Makefile 的平台变量**（jansi：`OS_NAME=Linux OS_ARCH=arm64`），让产物落进上游既有的资源目录命名。JNI 头：宿主机 JDK 的 `include/ + include/linux/`；加 `-Wl,-z,max-page-size=0x1000`（4KB 页设备硬要求，见 platform/64KB 页对齐条目）。
+2. **os.name 识别补丁**：见下节两策略判定。
+3. **musl 结构体字段补丁**：JNI C 代码直写 `struct termios` 的，musl 字段名为 `__c_ispeed/__c_ospeed`（glibc 为 `c_ispeed/c_ospeed`）——按 `__MUSL__` 宏切换字段名，Java 端字段 ID 不变。winsize 等同理必查。
+4. **jar 重打包与验证**：`.so` 嵌回 jar 对应资源目录后，**必须验证**：`jar tf <jar> | grep <so 路径>` 确认在位 + `unzip -p <jar> <so 路径> | sha256sum` 与交叉编译产物一致（防打包旧产物）。
+5. **签名与加载**：BiSheng JDK 对 `System.load()` 的 `.so` 校验 `.codesign` 段——用设备上的 `binary-sign-tool -selfSign 1` 自签后再嵌 jar/加载。机制与全套修复见 pc-error-atlas **E083**；手动编译+加载全范式（JNA 例）见 **E084**。
+6. **设备全量回归**：设备 JDK 探测/借用/供给见 platform/鸿蒙PC-设备语言运行时探测与供给.md（jansi 实测：JDK 在 CodeArts 应用私有 HNP 内，`<userId 因设备而异>`）；junit-console 跑法见 `pc-delivery-forms/references/languages/java.md`。计数口径取命名用例级；Windows-only 用例设备侧跳过属预期，不计未通过。
+
+## os.name 两策略（判定要点：上游多平台资源目录结构能否直接复用）
+
+鸿蒙 JDK `os.name` 报告 OpenHarmony/HarmonyOS，多数库的 OS 探测不识别 → loader 找不到内嵌 native 库。
+
+| 策略 | 做法 | 适用 | 案例 |
+|---|---|---|---|
+| A 映射复用 | 补丁库的 OS 探测（jansi 为 `OSInfo.translateOSNameToFolderName`），把含 OpenHarmony/HarmonyOS 的 os.name 映射到 `Linux` 目录，直接复用上游 `Linux/arm64` 资源结构 | 上游已有完整多平台目录、且按目录名分发 | jansi（本案例） |
+| B 新增目录 | 保留检测值，jar 内新增 `harmonyos-aarch64` 资源目录放 .so | 库的平台检测值参与运行时逻辑、或不便改 OS 探测 | JNA（见 E084） |
+
+策略 A 补丁最小（一处映射函数）、上游资源结构零改动，优先；验证：宿主机反射调映射函数应返回 Linux 目录名。
+
+## 踩坑速查
+
+- `System.load` 报 `Permission denied` 而 C 程序 `dlopen` 同一 `.so` 正常 → E083（JVM 校验 .codesign），不是权限/路径问题。
+- 设备无 Maven/Gradle 属常态：宿主机 `mvn test-compile dependency:copy-dependencies` 备齐 classes/test-classes/依赖 jar 推设备，junit-platform-console-standalone 单 jar 复跑（详见 java.md）。
+- 设备 `HOME`/`TMPDIR` 指向不可写位时 JVM/JUnit 会异常，跑前 `export HOME=/data/local/tmp TMPDIR=/data/local/tmp`。
+
+## 实测结论
+
+debuggable 鸿蒙 PC（HongMeng 1.12.0 aarch64）：上述配方全量回归 115 用例，113 通过 + 2 跳过（Windows-only，与原平台基线一致）、0 回归；JansiLoader 从 jar 内 `Linux/arm64/libjansi.so` 提取自签产物加载成功。