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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gl-rendering/03-glu-cross-compile.md

@@ -0,0 +1,17 @@
+# GL 渲染能力域：GLU 依赖的方案 A——Mesa GLU 交叉编译
+
+GLU（libGLU：tessellator/NURBS/quadrics/mipmap/投影）**不是 GL 翻译层的组成部分，也不需要它是**——它是纯用户态 C/C++ 库，只依赖 libc/libm/libGL。所以"gl4es 不含 libGLU"≠"GLU 不可适配"，自编即可。
+
+**判定分叉（scan 阶段）**：中心仓 `glu*` miss 时，先问"该依赖是否纯用户态库"——是则走 fresh-adapt 自编，**不得 scope_out**（Coin 案教训：registry 层已判 fresh-adapt 却被能力域的 unavailable 压成 scope_out，适配期白白走了降级路径）。
+
+**构建配方**（完整模板见 Coin 工作区 `deps/glu-9.0.3/build/`，可登记复用）：
+- 源：Mesa glu 9.0.3（archive.mesa3d.org）；`src/meson.build` 即权威源清单（libutil 5 c + libtess 10 c + libnurbs ~75 cc）
+- CMake + `ohos.toolchain.cmake`（`OHOS_ARCH=arm64-v8a OHOS_STL=c++_shared`），宏 `-DLIBRARYBUILD NDEBUG`
+- include 四路：上游 `include/`、**上游 `src/include/`（gluos.h 在这，漏了编译即败）**、`src/libnurbs/{internals,interface,nurbtess}`、gl4es include
+- 导出面：`-fvisibility=hidden` + 版本脚本 `{ global: glu*; local: *; };`（libnurbs C++ 内部符号全隐藏，Coin 实测导出 59 个全 `glu*`）
+- 签名：`-Wl,--code-sign`——漏了 `.codesign` 段，设备上 dlopen/加载直接失败
+- 链接：gl4es `libGL.so.1` + `m`；产物 DT_NEEDED 须为 `libGL.so.1 + libc++_shared.so + libc.so`
+- **前置检查**：目标 gl4es 的 libGL.so.1 必须导出 GL evaluators（`glMap1f/glMap2f/glEvalCoord2f/glEvalMesh2`）——GLU NURBS 全建在这组 API 上，用 `llvm-nm -D` 核验后再动手
+- 接入：dlopen 型 wrapper 按候选名 `libGLU.so`→`libGLU.so.1` 探测，或环境变量指定库名，**零改动命中**；部署进 HNP `pkg/lib` + `LD_LIBRARY_PATH` 自举，链时型消费者直接 `-lGLU`
+- 验收证据模式：wrapper 测试 available 分支的 check 数 delta + NURBS 渲染像素 diag；导出面审计 + readelf 核 DT_NEEDED/codesign
+- 已知限制：gl4es 的 `GL_AUTO_NORMAL`/`glGetMap`/`glIsEnabled` 为 TODO——NURBS 自动法线着色可能与宿主有差（Coin 曲线白 vs 宿主黄，像素断言仍过）；需要时在 gl4es 侧补偏导叉积小 patch

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gl-rendering/04-verification-pitfalls.md

@@ -0,0 +1,36 @@
+# GL 渲染能力域：验证要点与关键陷阱
+
+## 关键陷阱
+
+1. 桌面 GL 专用函数体必须预处理器整段排除：GLES 头无 `GL_QUAD_STRIP` 常量与 `glBegin/glColor4f/glOrtho` 声明，运行时跳过不够，会 implicit declaration 编译错。
+2. 无上下文逻辑窗口收到 `DISPLAY_WORK` 会在重绘处理处 `eglMakeCurrent(EGL_NO_SURFACE)` fatal——工作掩码必须在源头掐灭，不给逻辑窗口任何 WorkMask。
+3. 上游 API 隐性契约：某些库函数无 NULL 保护（桌面调用方总是先初始化），stub 语义时代的测试代码直接调用会 SIGSEGV。
+4. 上游 GLES 构建整体 stub 字体/菜单的库，名册里钉住的 `==0` stub 契约在重实现后需按 fixed-test amendment 同步升级，并排查其余 stub 时代断言的误伤。
+5. 窗口坐标/尺寸的 State 镜像是泵时的（DesiredPos → pump → 平台位置尺寸工作 → State）——内联测试代码须显式 `glutMainLoopEvent()` 刷新后才读 State，否则区域裁剪使用旧值。
+6. 共享 surface 上顶层窗口的 `glClear` 不受子窗 scissor 影响——顶层 full-canvas clear 会覆盖子窗内容；子窗必须与父窗同帧重绘（GLUT 应用常态）。
+7. 名册用例隐式假设 current 窗口——前序用例切换 current 后，后续绘制用例必须显式 `glutSetWindow` 恢复，否则区域裁剪跟随错误的窗口。
+8. `glutSetWindow` 对已是当前窗口的调用 early-return，跳过 make-current——依赖 make-current 副作用的路径会漏跑，需在主循环泵末尾补刷。
+9. 0×0 scissor 盒（窗口 State 越出 surface 后被 clamp 出的退化矩形）会让该上下文后续一切 draw **和 glClear** 静默失效且无 GL 错误——apply-region 必须把退化矩形兜底回全画幅。
+10. 内部 program 惰性编译时序陷阱：在应用 program 投入使用之后再编译库的第二段 program，Zink/Maleoon 上会使后续所有批量绘制静默无 fragment——内部 program/图集须在窗口创建时初始化并跑一帧 priming（见 `02-imm-mode-font-menu.md`）。
+11. 像素级故障诊断三板斧：清屏后立即回读计数可区分"clear 未落地"与"绘制错位"；唯一色清屏探读回字节序——呈现格式 BGRA 时 R/B 互换；逐格回读画内容分布图定位残留来源。hilog 取证必须流式捕获（`hilog -T Tag > file`），环形缓冲 ~100K 行/百秒，事后 `-x` dump 会被系统日志冲掉。
+12. EGL 上下文默认 client version 是 **ES1**：后端不显式设版本时 `glGetString(GL_VERSION)` 报 `"OpenGL ES-CM 1.1"`，此时 `glCreateProgram` 返回 0 且报 `GL_INVALID_OPERATION(0x502)`——**一切 shader 几何/文字静默全灭**。修法：`glutInitContextVersion(2,0)`（或后端默认 ES3）必须先于 `glutCreateWindow`。
+13. `eglGetProcAddress` 在**上下文创建前**预取的 GL 函数指针：闭源 GLES 栈上可用、**Mesa 栈上全部静默失效**。任何模块加载期（constructor）绑定 GL 裸指针做转发的 shim，在 Mesa 下会毒杀全进程绘制。指针必须上下文就绪后再取，或直接链系统库让符号解析走 NEEDED。
+14. **GL 视口跟随 surface 初始尺寸，不跟随请求窗口尺寸**：surface 按某固定尺寸创建后经异步 resize 缩窗，视口不更新——按请求尺寸算读回点会出现幻影。读回/像素断言坐标一律按 `eglQuerySurface(EGL_DRAW)` 实际宽高换算。
+
+## 验收要点（adapt 阶段）
+
+命中本域的重实现（文字/菜单），验收除常规上屏取证外加像素级断言：
+
+1. **正对照**：swap 重置保证已知光标起点，读已知字形区命中像素数大于 0（位图按字宽和与字高取带，轮廓按 cap 高度取带）。
+2. **负对照**：字形带区外保持背景色（抓误定位、跨条带错连、缩放漂移）。
+3. **度量一致性**：Length 与逐字 Width 之和相等（无字距库严格相等；容差 1% 为保守方向）。
+4. **子窗区域隔离**：区域内=子窗色、区域外=父窗色、边界两侧像素不同——三段对照缺一不可。
+5. **验证载体优先级**：真窗口表面 > surfaceless+FBO 离屏。只有真窗口表面能证「画到屏幕」的呈现语义。scan 标 `verification_surface: window` 的库不得以离屏证据替代。
+
+## 验证载体优先级
+
+渲染类验证的载体选择：**真窗口表面 > surfaceless+FBO 离屏**。
+- **真窗口表面**（XComponent SURFACE→OHNativeWindow→`eglCreateWindowSurface`）：gl4es 首帧即稳、无需 warmup。只有它能证「画到屏幕」的呈现语义（FB0 backing + swap）。
+- **surfaceless+FBO 离屏**：可用替身（pbuffer 在 OHOS 空壳化时的降级路径），但存在 gl4es 冷启动不稳定。离屏逐像素断言通过 ≠ 上屏能力验证；scan 标 `verification_surface: window` 的库不得以离屏证据替代。
+- 消费者 TU 编译守卫：gl4es include 目录自带 `EGL/` 头会拉 X11——须定义 `EGL_NO_PLATFORM_SPECIFIC_TYPES=1 EGL_NO_X11=1`。
+- GL 渲染库宿主完整配方：`../solutions/ohos-window-bridge/examples/gl-rendering-lib-host/`。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gl-rendering/05-coordinate-contract.md

@@ -0,0 +1,48 @@
+# GL 渲染能力域：坐标系契约（跨 API 迁移先读）
+
+> **定位**：GL/GLES/窗口三套坐标系统在迁移边界上的通用规则。任何把桌面 GL/GLUT 库迁到 GLES 的适配
+> 必须先定坐标系契约；违反本契约的症状是「渲染发生了但位置不对」（镜像/偏移），且无 GL 错误可查。
+>
+> 实例与更细的陷阱见 `00-overview.md` 的坐标契约节、`02-imm-mode-font-menu.md`（菜单/字体坐标转换）、
+> `04-verification-pitfalls.md`（视口跟随、ES1 默认版本）。
+
+## 三套坐标系统
+
+| 坐标系 | 原点 | 使用方 |
+|---|---|---|
+| **窗口坐标** | 顶部为原点，Y 向下 | 窗口 API（resize/cursor）、事件回调、GLUT 顶向下菜单参数 |
+| **GL 像素坐标** | 底部为原点，Y 向上 | `glVertexAttrib`/顶点数据、`glReadPixels` 读回区 |
+| **NDC** | 中心 (0,0)，范围 [-1,1] | shader `gl_Position` |
+
+## 三问（迁移任何 GL 库前必答）
+
+1. **调用方传入坐标是什么语义**？——窗口顶部原点 / GL 底部原点 / NDC
+2. **库内渲染管线（shader/光栅化）期望什么语义**？——GL 底部原点 / NDC
+3. **翻转在哪一层发生、发生几次**？
+
+## 翻转唯一性
+
+跨边界只允许一次翻转；两侧语义相同则不翻；语义不同则**恰好翻一次**。
+任何「传进来的坐标又被库翻一次」= 二次翻转 = 镜像。
+
+**判断法**：沿着一条坐标值从调用方走到 shader，数它经过了几次 `win_h - y` / `wh - y` 类翻转。
+`0` 或 `1` 次 = 契约自洽；`2` 次 = 镜像 bug。
+
+**实证**（freeglut 2026-09）：demo 传 `fgFontGLESSetCursor(x, win_h - y_ui)`（已翻一次成 GL 原点），
+库内 `glutBitmapString` 又 `wh - y` 翻一次 → 文本镜像到底部，字形区断言零命中、无 GL 错误。
+
+## 断言锚定
+
+用例断言区必须锚定「库实际输出的坐标系」，不是「假设的坐标系」。
+
+- `glReadPixels` 以**底部**为原点——断言区域坐标须与之一致。
+- 窗口请求尺寸 ≠ surface 实际尺寸（异步 resize 后视口不跟随）——读回坐标以 `eglQuerySurface(EGL_DRAW)` 实际宽高为准，否则出现「大图形命中、小图形落空」幻影。
+
+## 自检探针（迁移后第一步）
+
+画一个已知位置/已知大小的形状（如单色矩形或一个字形），`glReadPixels` 读回中心与四角像素：
+- 中心=形状色 → 位置正确
+- 中心=背景色、但有别的区域命中 → 位置偏移（多半翻转/视口问题）
+- 全帧=背景 → 没画出来（查 shader/attrib/纹理，见 `04-verification-pitfalls.md`）
+
+不能只看「有像素」——要看像素在预期位置。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gpu-compute.md

@@ -0,0 +1,77 @@
+# 能力域：gpu-compute（GPU 通用计算）
+
+> 方案细节（ICD 注入 / cwd 可写 / 事件回调限制）见 `pc-knowledge-base`：`adaptation/鸿蒙PC-OpenCL-SDK-app域适配补充.md`、`platform/鸿蒙PC-HNP执行器cwd不可写与沙箱写入方案.md`、`platform/鸿蒙PC-HNP数据资源文件打包EXTRA_DATA.md`。
+
+## 能力描述
+
+GPU 通用计算能力：OpenCL/GPGPU 程序通过 OpenCL ICD 加载器发现并调用 GPU 驱动，在 GPU 上执行 kernel 程序进行异构计算。典型场景包括 AI 推理后端（OpenCL 路径）、图像/视频处理管线、科学计算等。
+
+## 鸿蒙状态
+
+**partial** — 基础 GPU 计算可用，但事件回调和文件写入受限。
+
+| 子能力 | 状态 | 说明 |
+|--------|------|------|
+| 平台/设备枚举（clGetPlatformIDs/clGetDeviceIDs） | available | 通过 ICD 加载器 + OCL_ICD_FILENAMES 正常发现 HUAWEI OpenCL 3.0 平台和 Maleoon 916 GPU |
+| kernel 编译与执行（clCreateProgramWithSource/clEnqueueNDRangeKernel） | available | 基础 kernel（saxpy/copybuffer/reduce/histogram）执行正常，结果校验通过 |
+| 事件回调（clSetEventCallback） | **unavailable** | vendor ICD 驱动在 app 域创建 cqEvent 失败（`token timeout!`/`Failed to create cqEvent: postEvent.`），返回 CL_OUT_OF_HOST_MEMORY（-6） |
+| 程序二进制写出/读回（cl_util_write_binaries） | partial | C++ 版正常（OpenCL C++ wrapper 内部实现走 fstream 可写路径），C 版 fopen_s 因 cwd(HNP pkg/bin/) 在 app 域不可写失败 — 已通过 runner chdir 至沙箱可写目录解决 |
+| 文件 I/O（cl_util_read_text_file 等读路径） | available | 读路径全部正常（.cl kernel 文件随 HNP 数据文件打包可达） |
+| GPU 内存分配与数据传输（clCreateBuffer/clEnqueueWriteBuffer/ReadBuffer） | available | 基础内存操作全部正常 |
+
+## 替换方案
+
+**核心方案**：通过 OCL_ICD_FILENAMES 环境变量指定 vendor ICD（华为 Maleoon 916 驱动路径为 `/vendor/lib64/passthrough/libOpenCL.so`），让 OpenCL ICD Loader 在 app 域发现 GPU 驱动。
+
+**约束条件**：
+1. 华为不提供标准 `/etc/OpenCL/vendors/*.icd` 配置文件，必须用 `OCL_ICD_FILENAMES` 环境变量注入（`OPENCL_VENDOR_PATH` 不工作）
+2. app 域事件回调不可用 — vendor ICD 内部 `cqEvent` 创建被 app 域安全机制拦截（疑似 SELinux 或 mount namespace 限制 GPU 驱动事件通知通路）
+3. 文件写入类操作需确保 cwd 在 app 域可写（HNP pkg/bin/ 只读，需 chdir 至 `/data/storage/el2/base/temp/`）
+
+**验证方式**：
+1. **hap 载体**（cpp-lib-demo）：NAPI 壳 dlopen 验证库加载链路
+2. **cli 载体**（cli-hnp-runner）：私有 HNP fork+execv 逐条跑用例，OCL_ICD_FILENAMES 在 fork+execv 的 child_pre_exec 阶段 setenv
+
+## 可行性影响
+
+- 纯 OpenCL 计算（无事件回调需求）→ **feasible** — 基础 GPU 计算路径全部可用
+- 需事件回调/通知的 OpenCL 应用 → **hard** — 需评估能否通过驱动更新或 app 域权限调整解锁 cqEvent
+- 需在 app 域写入程序二进制持久化的 C 应用 → **feasible with workaround** — runner 侧 chdir 至可写目录即可
+
+## GPU 设备发现与驱动通路（域内通用子面）
+
+**子能力面（通用）**：本域鸿蒙状态表第一行"平台/设备枚举"依赖的底层机制——**发现并装载厂商 GPU 驱动、把上层 API 调用分派过去**。OpenCL ICD Loader 是已实证的一例；其他 GPU API 的驱动加载器（清单→`dlopen` 驱动→协商接口版本→枚举设备→vendor/layer 分派链）与它**同一形态**，命中时共用本节规则。
+
+### 命中触发规则（按源码特征，不按 API 名称）
+
+scan 发现库源码含以下任一特征，即命中本子能力面：
+
+- 驱动清单解析：`*.icd` 文件读写、manifest/JSON 里的 `library`/`library_path` 字段、驱动注入类环境变量读取（如 `OCL_ICD_FILENAMES`/`OPENCL_VENDOR_PATH`/`VK_DRIVER_FILES`）
+- 驱动装载：`dlopen`/`dlopen_ext` 一个运行时按清单解析出的非自身 `.so`
+- 接口版本协商：`negotiate`/`GetInterfaceVersion`、ICD 前缀符号（`vk_icd*`/`cl_icd*`）
+- 设备枚举/分派：`EnumeratePhysicalDevices`/`EnumerateDevices`/`GetDeviceIDs`、`GetInstanceProcAddr` 式 proc 索引 + 转发
+- layer/vendor 扩展链：`VK_LAYER_PATH` 等分派链组装
+
+### 鸿蒙通用规则
+
+1. **真驱动注入靠环境变量，不靠标准配置文件**：华为不提供 `/etc/OpenCL/vendors/*.icd` 类标准清单，真机厂商驱动必须用环境变量指定（OpenCL 实证：`OCL_ICD_FILENAMES=/vendor/lib64/passthrough/libOpenCL.so`；`OPENCL_VENDOR_PATH` 不工作）。各 API 的注入变量见下表。
+2. **厂商驱动随系统/Mesa 供给**：设备上真 GPU 驱动已随镜像/Mesa 栈存在（未随待适配库），loader 只要能发现即可用，无需自带驱动。
+3. **app 域事件/同步类路径受限**：vendor ICD 在 app 域创建驱动内事件/同步对象会失败（OpenCL 实证：cqEvent 创建 → `CL_OUT_OF_HOST_MEMORY`；疑似 SELinux/mount namespace 拦截驱动事件通道）。所有"厂商驱动在 app 域的驱动内事件/同步类路径"共享此风险，验证时把 `testenv-limited / platform-divergence` 与真实缺陷分开。
+4. **清单搜索路径按 OHOS 对齐**：系统搜索路径指向 `/system/etc:/vendor/etc`（SYSCONFDIR），不能沿用上游桌面默认路径。
+
+### 实例对照（已证实的例子；规则按上方触发条件走，不限于下表）
+
+| 机制 | OpenCL（实证，2026-09-15 OpenCL-SDK） | 其他 GPU API（同构，按各自 API 的对应物落位） |
+|------|------------|-------------|
+| 真驱动注入 | `OCL_ICD_FILENAMES=/vendor/lib64/passthrough/libOpenCL.so` | 各 API 的驱动清单环境变量（以官方文档为准） |
+| 设备真实驱动 | HUAWEI OpenCL 3.0 / Maleoon 916 | Maleoon 916 GPU 家族驱动（Mesa 栈经 `libvulkan.so`→Zink→Maleoon 一例见 `gl-rendering/01-route-gles-vs-gl4es.md`） |
+| app 域事件/同步 | 事件回调 unavailable（cqEvent 失败） | 同源风险，按各 API 的事件/同步通路验证 |
+| 扩展/layer 链 | vendor 加载器分派 | 各 API 的 layer/vendor 机制（若有） |
+
+**互操作规则**：同一库同时走多种 GPU API（如 OpenCL+Vulkan 互操作）时，各驱动发现路径按各自 API 的注入变量与 layer 机制处理，不互相套用配置。GPU 渲染呈现（surface→swapchain→present）不属本域，见 `pc-knowledge-base` Vulkan 上屏通路条目。
+
+## 典型库怎么接
+
+1. 依赖 OpenCL 的非 GUI 计算库（如 AI 推理后端、图像处理管线）→ 接 ICD Loader + OCL_ICD_FILENAMES
+2. 依赖 OpenCL 事件回调的库 → 评估 libevent/polling 替代方案，或记录为已知平台限制
+3. 走 GPU 互操作（OpenGL/Vulkan）的库 → scope out（OpenCL-SDK 的该功能默认 OFF）；互操作的驱动发现按上方「GPU 设备发现与驱动通路」规则，渲染呈现按 `pc-knowledge-base` Vulkan 上屏通路条目

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/graphical-window.md

@@ -0,0 +1,66 @@
+# 能力域：graphical-window（图形窗口栈）
+
+## 能力描述
+
+创建窗口、管理窗口生命周期、接收窗口事件（resize/close/focus）、窗口系统后端对接。PC 上通常由 Win32 / X11 / Wayland / Cocoa 提供，库通过对应后端实现（GLFW 的 `src/win32_*`/`src/x11_*`/`src/wl_*`/`src/cocoa_*`，SDL 的 video 子系统，Qt 的 QPA 平台插件）。
+
+## 鸿蒙状态
+
+**partial（自绘像素类库经 OWB 场景化方案）/ unavailable（深度窗口系统 API 依赖）**
+
+- 鸿蒙 PC **没有** Win32/X11/Wayland/Cocoa 这套传统窗口系统后端。
+- 鸿蒙窗口模型是 **ArkUI Window + XComponent**：应用通过 ArkUI 创建窗口、XComponent 提供自绘表面与事件回调。
+- 对"只想拿个窗口跑 GL/自绘"的库：可经 **XComponent + EGL** 桥接，拿到 GL 上下文 + 自绘表面 + 输入事件 → **partial**。
+- 对"依赖完整窗口系统 API（窗口装饰、多窗口管理、桌面集成、Win32 消息循环）"的库：鸿蒙无对应 → **unavailable**。
+
+## 替换方案
+
+| 原能力 | 鸿蒙替换 |
+|--------|---------|
+| 创建窗口 | ArkUI Window + XComponent 组件 |
+| GL/EGL 上下文 | XComponent 提供 EGLSurface，经 EGL 创建 context（见 `gl-context` 能力域） |
+| 窗口事件（resize/close/focus） | XComponent 的 onLoad/onDestroy 等回调 + ArkUI 窗口事件 |
+| 输入事件（键鼠/触控） | 鸿蒙输入子系统经 XComponent 分发（见 `input` 能力域） |
+| 窗口装饰/标题栏/多窗口管理 | 鸿蒙应用窗口模型，无传统窗口装饰；桌面集成走应用框架 |
+
+## 可行性影响（填 capability_dependencies.impact）
+
+- **库本身是窗口抽象层 / 自绘像素类（GLFW/SDL video/GTK/Qt raster/ImGui/bgfx）**：为库写一层 OWB L3 后端（见下方场景化方案），库即可在鸿蒙拿 surface、收事件、上屏——GLFW 已按此真机端到端跑通。**feasibility: feasible_with_effort**。仅当库深度依赖完整窗口系统 API（窗口装饰/多窗口管理/桌面集成/Win32 消息循环）时仍 **hard/unavailable**。
+
+> **上屏验证前置（必读）**：目标路径只能靠**装 demo HAP 上屏**验证（机器判定依据 demo-verify.json 的拉起/日志字段，截图存档待人工验收），而 `hdc install` 校验 PKCS7 信任链——自签**野 CA** 必拒。**直接 `ohpt-agent sign-demo -w <ws> --install`**：用 SDK 自带 OpenHarmony 材料 headless 自签（零账号、任意 bundle，设备信任 OpenHarmony 根，真机实测通过）。程序/兜底见 `pc-knowledge-base` platform/鸿蒙PC-HAP调试签名与设备安装信任链.md；连 SDK 都没有才降级 `built-pending-verification`。
+- **应用用 GLFW/SDL 创建窗口**：不走 GLFW/SDL 后端，改用 ArkUI Window + XComponent 重建应用窗口入口，应用主体渲染/逻辑保留。**feasibility: feasible_with_effort ~ hard**（取决于应用对窗口 API 的耦合深度）。
+- **Qt 底层窗口（QPA）**：Qt 已有鸿蒙 QPA 插件（见 `qt-toolchain` 能力域），窗口层由 QPA 适配，应用层不直接碰窗口后端。**feasibility: available**（经 Qt 鸿蒙移植版）。
+
+## 场景化方案：ohos_window_bridge（OWB）——自绘像素类库的统一答案
+
+真机验证过的可复用方案，vendored 于 **`../solutions/ohos-window-bridge/`**：README 速览 → `docs/PORTING_KIT.md` 按库配方（GLFW/SDL/GTK/Qt-raster/ImGui + 语言绑定库公式）→ **上屏 demo 直接拷 [`examples/glfw-triangle/`](../solutions/ohos-window-bridge/examples/glfw-triangle/)**（L0 `Index.ets` + L1 渲染本体，真机验证、**正确 MVP 矩阵已内建**——**别从零写渲染**，全黑窗十有八九是矩阵坑〔`m[15]=0`/行列主序〕而非 EGL/GL 环境，改 `render()` 为你库的绘制即可）→ L3 后端起步 `templates/skeleton-backend/`。适配时整目录拷贝到目标工作区 `deps/ohos-window-bridge/` 构建。**Python 绑定库的验证 demo 工程一键生成：`ohpt-agent scaffold --kind python-gui-owb -w <ws>`**（真机实证模板，自动装配 OWB 到 deps/；app 内嵌 Python 后端另有 python-app-embedded / python-app-subprocess，`ohpt-agent scaffold --list` 详）。GLFW（GPU/EGL）与 pyGLFW（ctypes 绑定）已端到端跑通；GL/Vulkan 上下文同经其 GPU 路径（`OWB_GetNativeWindow` → EGL / `vkCreateSurfaceOHOS`），窗口几何控制经其双向桥（NDK 无窗口几何 C API）。
+
+**域边界（window 域只到 surface 为止）**：窗口域的 Vulkan 职责 = `OWB_GetNativeWindow(sid)` 拿到真实 OHNativeWindow → `vkCreateSurfaceOHOS`（须启用 `VK_KHR_surface` + `VK_OHOS_surface` 两扩展；`window` 指针空必须判空——契约是错误码而非崩溃；`flags=0`、`pNext=nullptr`）。**surface 之后的 swapchain/present、系统 swapchain layer、驱动 ICD 分派不属窗口能力**，属 GPU 设备通路与渲染呈现机制——见 `gpu-compute.md`（GPU 驱动/设备发现通用规则）与 `pc-knowledge-base` platform/鸿蒙PC-Vulkan上屏通路（swapchain→present 端到端机制）。
+
+### Qt 底层
+- Qt 经 QPA（Qt Platform Abstraction）插件抽象窗口后端。鸿蒙有 QPA 插件 → Qt 应用不直接碰窗口后端，走 `qt-toolchain` 能力域（Qt raster 类才涉 OWB CPU-blit 形态）。
+
+## scan 判定要点
+
+- 识别窗口后端依赖：源码里出现 `X11`/`wayland`/`win32`/`cocoa`/`GLFW`/`SDL_CreateWindow`/`QWindow` 等。
+- **Vulkan surface 触发特征（窗口子面）**：源码出现 `vkCreateSurfaceOHOS`/`VK_OHOS_surface`/`VK_KHR_surface`/`VkSurfaceCreateInfoOHOS` → 命中本域窗口职责（到 surface 为止）；swapchain/present 调用（`vkCreateSwapchainKHR`/`vkAcquireNextImageKHR`/`vkQueuePresentKHR`）→ 属设备通路/渲染机制，见 `gpu-compute.md` 与 `pc-knowledge-base` Vulkan 上屏通路条目。
+- **EGL 窗口子面触发特征**：源码出现 `eglCreateWindowSurface`/`EGLNativeWindowType`/`OHNativeWindow` → 命中 OWB GPU/EGL 路径。
+- 区分"自绘像素类（走 OWB，feasible_with_effort）" vs "深度窗口系统 API 依赖（hard/unavailable）" vs "Qt 经 QPA"（available）。
+- evidence 必须来自生产代码（file:line），指向窗口后端调用处。
+
+## 降级实证：CImg/某图像库 家族显示后端禁用（`-Dcimg_display=0`）
+
+CImg 家族（CImg.h、某图像库 等）在非 Windows 平台默认 `#include <X11/Xlib.h>`，
+NDK sysroot 无 X11 导致编译失败。**不需要走 OWB 桥接**——因为 CImg 的显示后端完全是
+**可选的交互式预览功能**（`display` 命令），图像处理核心与 CLI 批处理完全不依赖它。
+
+落地手法：编译标志加 `-Dcimg_display=0` 显式禁显示后端，比靠探测不命中更稳；
+某图像库 的 `display` 命令在 某图像库.cpp:6557 有 `cimg_display` 可用性检查、禁用后
+自动报 unsupported。核心功能不受影响。
+
+**适用场景**：待适配库的图形窗口依赖是**可选的交互式预览**，而非核心渲染/编辑功能。
+判定依据：scan 阶段确认 `graphical-window` 能力域仅被可选的 display 命令引用，
+不在核心图像处理管线中。
+
+> 实证：某图像库（2026-09-08），`delivery_form=cpp-lib`，`feasibility=feasible_with_effort`。
+> 详见 [[鸿蒙PC-图像处理库-CImg图像库交叉编译]] §2.3。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/input.md

@@ -0,0 +1,25 @@
+# 能力域：input（输入事件）
+
+## 能力描述
+
+键盘/鼠标/触控事件的接收与注入。分两类本质不同的能力：**窗口内输入**（本应用窗口收到的事件）与**全局输入**（跨应用的系统级监听 hook / 事件注入）。PC 上由 Win32 hook、X11 XTEST/XRecord、Linux evdev/uinput、macOS Quartz/ApplicationServices 提供。
+
+## 鸿蒙状态（按部署模型分档——禁一刀切）
+
+| 场景 | 状态 | 通道与前提 |
+|------|------|-----------|
+| 窗口内输入（本应用） | available | XComponent 分发键鼠/触控/滚轮/焦点——OWB 事件队列即现成封装（`../solutions/ohos-window-bridge/`） |
+| 全局监听/注入 · 三方应用沙箱 | unavailable | 无面向三方应用的公开 API |
+| 全局监听/注入 · 系统应用 | partial | `@ohos.multimodalInput` inputMonitor / injectEvent 为 system-api，需系统应用 + 权限 |
+| 注入 · 开发者通道 | partial | uitest / hdc（UiDriver 注入）可用，仅调试/自动化场景 |
+| 监听+注入 · root 调试机 | partial | 内核 evdev/uinput 节点存在（root 可访问 /dev/input）；需交叉编译 evdev 类 C 扩展；不适用于发布形态 |
+
+## scan 判定要点
+
+- **必须按 enum-semantics.md「部署模型」分档下结论**：三方应用形态判 unavailable 没错，但工具链/自动化/root 场景要单列（pynput 案例教训：一刀切 infeasible 抹掉了 evdev/uitest 路径）。
+- 只用窗口内输入的库（游戏/GUI 框架的 input 子系统）：available，经 XComponent/OWB，不构成阻塞。
+- 依赖全局 hook/注入的库（pynput/pyautogui/keyboard）：按目标部署模型逐档给 blocker + adaptability，replacement 写明上表对应通道，evidence 指向后端选择代码（file:line）。
+
+## 典型库
+
+pynput / pyautogui / keyboard（全局监听+注入）；GLFW/SDL 等框架的 input 子系统（窗口内，经 OWB）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/media-capture.md

@@ -0,0 +1,35 @@
+# 能力域：media-capture
+
+> 来源：AFFiNE 适配实证（2026-09-29，media_capture Rust 模块仅 macOS/Windows 实现）。命中共存场景：屏幕录制/系统音频采集/会议录制类功能。
+
+## 能力描述
+
+应用捕获屏幕画面与系统音频（录屏、录课、会议录制）。PC 平台语义下走各 OS 原生捕获 API（macOS ScreenCaptureKit、Windows cpal/WGC）。
+
+## 鸿蒙状态
+
+**unavailable（无对应原生捕获能力，按上游平台守卫裁剪）**：
+
+- 鸿蒙 PC 无 ScreenCaptureKit/桌面级屏幕捕获对应能力；应用自带的平台分支（如 AFFiNE `media_capture` Rust 模块仅 macOS `screencapturekit` / Windows `cpal` 实现）在鸿蒙上**无实现可接**；
+- 上游已有平台守卫（如 `checkRecordingAvailable` 非 macOS/Windows 返回 false）时，**录制入口自动隐藏**——无需适配动作，按 scope_out 裁剪、不参与验证；
+- 注意区分：CAMERA/MICROPHONE（摄像头/麦克风采集）权限虽可能被扫描声明，但录制入口隐藏后**不会被触发**——与屏幕/系统音频捕获是两回事。
+
+## 替换方案
+
+1. **优先按上游平台守卫裁剪**（scope_out）：功能入口自动隐藏即零适配成本；
+2. 上游无守卫、录制入口在鸿蒙仍可达时：加平台守卫隐藏入口（`process.platform !== 'openharmony'` 或等价判定），避免用户点进去后报错；
+3. 未来若平台提供屏幕捕获 Kit，再评估重开——当前按不可用处理。
+
+## 可行性影响
+
+**feasibility 不降档**（守卫裁剪属上游既有扩展点）；录制功能列入 scope_out 并写入 PRD 降级说明。反例警示：若应用把录制当核心旅程（录课软件），unavailable 直接命中核心功能 → feasibility 降档并如实报 hard。
+
+## 典型库怎么接
+
+- 应用含屏幕录制/系统音频采集能力，评估鸿蒙可行性与裁剪方案时：先 grep 上游平台守卫（`checkRecordingAvailable`/`isSupported`/平台分支），有守卫 → scope_out 零动作；无守卫 → 加守卫隐藏入口；
+- 别把 CAMERA/MICROPHONE 权限申请与屏幕捕获混为一谈——入口隐藏后 user_grant 弹窗不会被触发。
+
+## 实证锚
+
+- AFFiNE：media_capture 仅 macOS/Windows 实现，`checkRecordingAvailable` 平台守卫自动隐藏入口，scope_out 裁剪不参与验证（01-scan scope_out；04-summary sediment media-capture 条）
+- 权限语义：`app-permissions.md`（同目录，CAMERA/MICROPHONE 属 user_grant）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/network.md

@@ -0,0 +1,56 @@
+# 能力域：network（TCP/UDP 网络通信）
+
+## 能力描述
+
+标准套接字网络通信：`socket` / `connect` / `bind` / `listen` / `accept` / `send` / `recv` /
+`select` / `poll` / `getaddrinfo` 等 BSD/POSIX socket API。PC 上由 Winsock / BSD socket 提供。
+
+**典型触发**：依赖里出现 `libapr` / `asio` / `libevent` / `libuv`，或源码里有
+`socket()` / `connect()` / `recv()` 调用。
+
+## 鸿蒙状态：available
+
+鸿蒙 musl/POSIX 提供完整 socket API，TCP/UDP 通信**无需替换**。实测证据（`鸿蒙PC-POSIX-NDK能力探针矩阵`）：
+45/46 项网络相关 API 可用；MQTT/AMQP 客户端的网络层经 APR + 原生 POSIX socket 实现 TCP 连接，
+源文件交叉编译全通过，设备侧 app 域（私有 HNP fork/execv）真跑 TCP 连接与消息收发冒烟用例通过。
+
+## 替换方案
+
+无需替换。标准 socket 直接复用。
+
+## 可行性影响
+
+不降级。评估为 least_effort 类能力——命中本域不构成适配障碍。
+
+## 判定要点（scan 阶段）
+
+1. 命中本域 ⇒ `harmony_status: available`、`replacement: 标准 POSIX socket 直接复用`、
+   `solution_source: builtin-asset`、`asset_ref: pc-capability-domains/network.md`。
+2. 仅当库依赖裸机层网络能力（raw socket / AF_PACKET / netfilter）时另判——raw socket 在
+   hdc shell 域实测全通（见相关适配案例），但 app 域受
+   seccomp/SELinux 额外限制，需按部署模型分档。
+3. **判了 available 就别在构建期关掉**：`-DNETWORK=OFF` / `--disable-network` 之类开关会把
+   本域整体编译出去，下游依赖它的功能点只能 blocked（实例实证：scan 判 network
+   available，阶段 3 却 `-DNETWORK=OFF`，导致网络相关功能自残式缺口）。验收规则
+   `build-flags-disable-declared-domain` 在 03-adapt.json 落盘时即拦。
+
+## ArkTS 侧补充：网络流接收 ≠ 网络流解析（coverage 判定要点）
+
+coverage 判网络能力时**必须拆开两个概念**（流媒体播放场景实证）：
+
+- **网络流数据接收**：ArkTS/HarmonyOS **有开箱 API**，判 available，不进 capability_gaps：
+  | 场景 | 模块 | 关键 API | 收到的数据 |
+  |------|------|---------|-----------|
+  | TCP/UDP/TLS | `@ohos.net.socket` | `constructTCPSocketInstance()` 等 → `on('message')` | `ArrayBuffer` |
+  | TCP 服务端 | `@ohos.net.socket` | `constructTCPSocketServerInstance()` → `on('connect')`，连接对象 `on('message')` | `ArrayBuffer` |
+  | WebSocket | `@ohos.net.webSocket` | `createWebSocket()` → `on('message')` | `string \| ArrayBuffer` |
+  | HTTP 流式响应 | `@ohos.net.http` | `requestInStream()` + `on('dataReceive')` / `on('dataEnd')` | `ArrayBuffer` 分片 |
+  - 注意：`@ohos.request` 的 `downloadFile()`/`uploadFile()` + `on('progress')` 是文件
+    上传下载进度，**不是**通用网络流接收，别拿它抵接收能力。
+- **网络流解析**：协议解析、抓包解析、NetFlow/sFlow/IPFIX、TCP 粘包/拆包状态机等，
+  ArkTS **无开箱能力**，仍须进 `coverage.capability_gaps`。`on('message')` 给的只是
+  数据块，粘包/拆包与协议状态机要自己实现。
+
+## 典型库
+
+asio / libevent / libuv / curl 类网络库、MQTT/AMQP 客户端等。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/qt-toolchain.md

@@ -0,0 +1,48 @@
+# 能力域：qt-toolchain（Qt 工具链栈）
+
+## 能力描述
+
+基于 Qt 框架的 GUI 应用所需的能力栈：Qt 库本身（Widgets/Quick/QPA）、Qt 构建工具（moc/rcc/uic/qmake/CMake Qt 模块）、Qt 运行时（QPA 平台插件、渲染后端）、语言绑定（PyQt/PySide 的 Python 绑定层）。
+
+## 鸿蒙状态
+
+**available**（Qt 已有鸿蒙移植版）
+
+- Qt for HarmonyOS 已存在：Qt 核心模块 + Qt Widgets/Quick + 鸿蒙 QPA 插件（对接 ArkUI Window/XComponent）。
+- Qt 应用可经鸿蒙 Qt 移植版运行：窗口经 QPA、事件经鸿蒙输入子系统、渲染经 EGL。
+- **绑定层是单独问题**：PyQt/PySide 的 Python 绑定层需单独处理（sip/shiboken 生成的绑定 C 扩展要针对鸿蒙 Qt 版本重新构建）。
+
+## 替换方案
+
+| 原能力 | 鸿蒙替换 |
+|--------|---------|
+| Qt 库（QtCore/QtWidgets/QtQuick 等） | 鸿蒙 Qt 移植版（同 API，QPA 走鸿蒙） |
+| QPA 平台插件 | 鸿蒙 QPA 插件（随 Qt 移植版提供） |
+| 窗口/事件 | 经 QPA 对接 ArkUI Window/XComponent + 鸿蒙输入（应用层不直接碰，见 `graphical-window`） |
+| Qt 构建工具（moc/rcc/uic） | 主机端跑（生成代码），交叉编译产物 |
+| PyQt/PySide 绑定 | 绑定层 C 扩展针对鸿蒙 Qt 版本重编为 `.cpython-312.so`（见 `pc-knowledge-base`） |
+
+## 可行性影响
+
+- **Qt + C/C++ 应用**：`delivery_form=app`，`capability_dependencies` 命中 `qt-toolchain=available` → **feasibility: feasible_with_effort**。工作集中在应用打包 + Qt 鸿蒙集成（`harmony-app/` 工程 + `build/` 配 Qt 鸿蒙工具链），非重写。
+- **Python + PyQt5/PySide 应用**：`delivery_form=app`，命中 `qt-toolchain=available`，但**额外需处理绑定层**（PyQt/PySide 的 C 扩展重编）→ **feasibility: feasible_with_effort**（绑定层处理是增量工作，非阻塞）。
+- **Qt 库本身（非应用，如某个 Qt 依赖库）**：经鸿蒙 Qt 移植版复用或重编，`delivery_form` 按库性质定，`qt-toolchain=available` 不构成阻碍。
+
+## 典型场景怎么接
+
+### Qt+C 应用
+1. scan 判 `delivery_form=app`、`capability_dependencies=[qt-toolchain:available]`。
+2. adapt 阶段（`pc-delivery-forms` 的 app 形态）：在 `harmony-app/` 建鸿蒙应用工程，配 Qt 鸿蒙工具链；应用源码（`source/`）经 `patches/` 适配性改动后接入；编出 hap 落 `dist/app/`。
+3. `harmony-demo/` 不需要（应用本身就是交付物，用 `harmony-app/`）。
+
+### Python+PyQt5 应用
+1. scan 判 `delivery_form=app`、`capability_dependencies=[qt-toolchain:available]`；依赖闭包含 PyQt5 → 标 `native-extension`（绑定层 C 扩展）。
+2. adapt：① PyQt5 绑定 C 扩展针对鸿蒙 Qt 重编（走 `pc-knowledge-base` 的 Python C 扩展交叉编译）；② 应用主体 Python 代码部署到设备 Python；③ `harmony-app/` 建鸿蒙应用工程承载窗口入口。
+3. 注意 PyQt 与 Qt 版本必须配套（Python 绑定 C 扩展与宿主运行时版本必须死磕的原则）。
+
+## scan 判定要点
+
+- 识别 Qt 使用：源码/构建里出现 `QApplication`/`QWidget`/`QtQuick`/`qmake`/`find_package(Qt6)`/`import PyQt5` 等。
+- 区分 Qt 应用（`app`）vs 依赖 Qt 的库（按库性质定 delivery_form）。
+- PyQt/PySide 应用：依赖闭包里把绑定层标 `native-extension`，记 `harmony_adapted` 据登记表。
+- evidence 来自生产代码的 Qt 调用处。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/runtime-data-assets.md

@@ -0,0 +1,176 @@
+# 能力域：runtime-data-assets（依赖运行时数据资产）
+
+## 能力描述
+
+依赖库的**代码**链接进产物后，运行时还会去**系统路径读取数据**才能完整工作——这份数据
+是发行版/系统提供的，不属于编译产物。典型数据族：
+
+| 数据族 | 读它的符号族 | 系统路径（Linux 惯例） | 缺失后果 |
+|---|---|---|---|
+| terminfo/termcap（终端能力描述） | `tgetent` / `tgetstr` / `tgetnum` / `tgetflag` / `tiget*` | `/usr/share/terminfo`、`/etc/terminfo` | 终端能力查询失败 → 静默降级为哑终端 |
+| locale/翻译（.mo） | `bindtextdomain` / `textdomain` / `dcngettext` | `/usr/share/locale` | 回退原文（通常可接受的降级） |
+| TLS 信任库 | `X509_STORE_load_*` / `SSL_CTX_*` | `/etc/ssl/certs` | TLS 校验全线失败 |
+| 可加载模块/插件数据 | `dlopen`（对数据/插件路径） | `/usr/lib/<lib>/...` | 对应功能不可用 |
+| fontconfig 字体配置与字体文件 | `FcConfigCreate` / `FcInitLoadConfigAndFonts` / `FcConfigGetFilename`（`FONTCONFIG_FILE`/`FONTCONFIG_PATH` 覆盖） | `/etc/fonts/fonts.conf`、`/etc/fonts/conf.d/`、`/usr/share/fonts` | 字体发现失败 → 渲染不出字形（静默假绿，见下实例） |
+| 用户级配置目录（`~/.config/<lib>/` 一类） | `path_rc` / `init_rc` / `mkdir`（基于 HOME/XDG） | `$HOME/.config/<lib>`、`$XDG_CONFIG_HOME/<lib>` | 配置目录初始化失败 → `init_rc()` 返回 false、目录内资源读写往返为空 |
+| OpenSSL 配置（openssl.cnf） | `CONF_modules_load*` / 编译期 `OPENSSLDIR` | `$OPENSSLDIR/openssl.cnf`（编译期写死，常为 `/usr/local/ssl`） | provider/引擎配置缺失 → 默认行为（多数可接受）或特性不可用 |
+| 模块完整性自检文件（provider 读自身 .so 做自检） | `ossl_prov_is_running()` 背后的自检状态机（fips/国密 SMTC 族） | 读自身模块文件（`/usr/lib/<lib>/...`） | **自检状态机卡 INIT → provider 运行态不成立 → 全部标准算法 EVP init 失败**（见 E153），且形态是"能 fetch 不能 init"，最隐蔽 |
+
+**典型触发**：产物 `nm -D` 出现上述符号族；或源码闭包里有 `"/etc/`、`"/usr/share/` 字面量；
+或设备运行时日志出现对系统数据路径的 ENOENT。
+
+## 鸿蒙状态：unavailable（零售机无系统级数据目录）
+
+**关键事实（零售不可调试机实测，2026-09-03）**：`/etc/terminfo`、`/usr/share/terminfo` 均不存在
+（`ls` 实证）。鸿蒙 PC 不携带 Linux 发行版惯例的系统数据目录——任何依赖"系统提供数据"的
+运行时读取，在这台设备上**必然落空**，且多数实现是**静默降级**（返回失败码/空值，不报错）。
+
+## 判定方法：三步证据链（通用步骤，不依赖具体库名）
+
+> **核心判定问题**：产物在目标机运行时，是否会读取一个"本应由系统提供"的数据路径，
+> 而 OHOS PC 上该路径不存在，且缺失造成**可观察的行为退化**？
+
+| 步 | 做什么 | 证据形态 | 回答什么 |
+|---|---|---|---|
+| **E1 静态·符号面** | 对最终产物 `nm -D`，匹配上表"读它的符号族" | 符号清单 | 有没有可能读外部数据——未命中直接出局 |
+| **E2 动态·路径面** | ① 源码闭包 grep `"/etc/`、`"/usr/share/` 字面量；② 设备侧确认路径缺失（`ls` / hilog ENOENT） | **缺失路径清单** | 平台缺的到底是什么——这份清单同时是查本库的检索键 |
+| **E3 行为·差分面** | 按下方方案随包 + 自举后，跑行为级差分用例，要求输出**前后可区分** | 行为差异证据 | 数据真影响行为（→必须随包）还是无影响（→纯文档/可选资源，不随包） |
+
+三步全过 ⇒ 随包是交付前提；E3 无差异 ⇒ 不随包。**判定全程不出现依赖名——见到的
+是"符号、路径、行为差"三个客观证据。**
+
+## 替换方案：数据随包 + 环境自举
+
+1. **随包**：数据目录打进 HNP（如 `pkg/share/terminfo`，装机后位于
+   `/data/app/<domain>/<name>_<ver>/share/terminfo`）。构建侧参照
+   `pc-knowledge-base` readline 案例的 `build-hap.ps1` terminfo 步骤。
+2. **自举**：ncurses 类按数据族设环境变量，在第一次相关调用前：
+
+   ```c
+   setenv("TERMINFO", "<hnp-root>/share/terminfo", 0);   /* 终端能力族 */
+   setenv("TERM", "xterm-256color", 0);                  /* 配套的型号名 */
+   ```
+
+   cli 载体按 `argv[0]` 相对路径自举（`<hnp-root>/bin/<tool>` → `../share/...`），
+   HAP 载体用 HNP 装机绝对路径。
+
+   配置目录族（`path_rc`/`init_rc`）的自举（某图像库 实证）：设备沙箱把 `HOME` 映射到
+   `/storage/Users/currentUser`（app 域不可写），库据此拼 `~/.config/<lib>/` 时
+   `mkdir` 失败 → `init_rc()` 返回 false。**在首次相关调用前把 `XDG_CONFIG_HOME`
+   指到沙箱可写目录**（HAP 的 `files/` 或 HNP 可写 cwd）：
+
+   ```c
+   setenv("XDG_CONFIG_HOME", "<沙箱可写目录>", 0);   /* 用户级配置目录族 */
+   ```
+
+   注意：自举是否生效取决于库是读 `$XDG_CONFIG_HOME` 还是硬编码 `$HOME/.config`
+   （某图像库 读 HOME，故还需视库实际读法决定 `setenv("HOME", …)` 还是改 XDG 变量——
+   以库源码里 `path_rc` 的实现为准，别想当然）。
+3. **验证**：三段式行为差分用例（模板见 `pc-test-design/case-design-methods.md` §6）：
+   数据可达 / 能力真实（非空、非恒定值）/ 行为级证据（输出可区分）。
+
+## 可行性影响
+
+- **不是"编不出"，是"编得出但能力是空的"**——与本库 audio 域同一陷阱形态：链接期自包含
+  ≠ 运行期可用。且降级是**静默**的：功能点用例照常全绿（断言锚在库内状态，不锚渲染/环境），
+  这正是 E130 记录的假绿形态。
+- 有本条目时：判定与方案是机械步骤，feasibility 不降级；漏判而硬交付 → 交付的是
+  "能力退化版"，验收若依赖行为级证据即打回。
+
+## 判定要点（scan 阶段）
+
+1. scan **不做**逐库数据探针（信噪比差、判不准）。本域的发现时机是 **port/delivery 的产物
+   特征检查**（见 `pc-delivery-forms` 交付必做项表："产物动态符号命中数据访问族"行），
+   证据是产物自身的符号，不是依赖名。
+2. scan 只需在依赖闭包含**已知数据族依赖**（ncurses/gettext/openssl/curl…）时，
+   `capability_dependencies[]` 里加一条本域记录，`solution_source: builtin-asset`、
+   `asset_ref: pc-capability-domains/runtime-data-assets.md`，提示 delivery 阶段执行三步链。
+
+## 模块完整性自检族（SSL/TLS 库 FIPS/国密分支）特别说明
+
+「读自身模块文件做完整性自检」是本域最隐蔽的一族——它的"数据"不是外部数据文件，而是
+**库自己的 .so**，所以 E1 静态符号面不一定命中（自检走内部符号，不出现 `fopen("/etc/…")`
+字面量）；它也不像 terminfo 那样"缺失→降级"，而是**缺失→provider 运行态不成立→所有
+依赖该 provider 的算法全挂**。判别关键：
+
+- 症状指纹：`fetch 全通 + init 全败`（`OSSL_PROVIDER_available()=1`、`EVP_MD_fetch=OK`、
+  但 `EVP_RAND_CTX_new` 报 03080006、`RAND_bytes=0`），错误码阶梯 0308010C→03000086→
+  03080006 是反向定位线索（见 `pc-error-atlas` E153）。
+- 处置路线（二选一，按部署 config 是否激活该 provider 分叉）：
+  1. **部署不激活自检 provider**（config 只激活 default 系）→ 在自检 run-once 初始化里
+     直接置状态 RUNNING（跳过的自检不触发 `SELF_TEST_post`，安全）。已有实例走此路。
+  2. **部署依赖该 provider 的自检语义**（FIPS 场景）→ 自检数据随包：把模块文件/摘要数据
+     打进 HNP，让自检在沙箱内能读到完整文件再算摘要。
+- 随包形态与验证同 E1/E2/E3 三步链；`03-adapt.json` 必须记录处置分支与依据（issues_resolved）。
+
+## 验收要点（adapt 阶段）
+
+命中本域的交付，`03-adapt.json` 必须记录：缺口清单（E2 产出）、随包路径、自举方式、
+行为差分用例结果。**缺任何一项不得标完整交付态**（"链接成功 ≠ 交付可用"）。
+
+## 真机事实（实例实证）
+
+- 零售机（OpenHarmony 6.0.2.130）无 `/etc/terminfo`、`/usr/share/terminfo`。
+- 中心仓 conan 制品自带 `lib/terminfo/`（数千条目，~3.1MB）——
+  数据随包的现成来源，无需自建。
+- HNP 打包数据文件后装机正常；HNP 在应用首次启动时由应用域解包
+  （装机当下不出现，host 侧 `hdc shell ls /data/app/...` 因 uid 隔离恒不可见——**以应用内
+  diag 日志为准**，见 `pc-error-atlas` E130 关联的取证注意）。
+- 实证结果：`tgetent("xterm-256color")` ret=1、`tgetstr("cm")` 返回真实转义序列、
+  PTY 渲染输出捕获到控制序列（原降级行为恢复）；用例全过，PRD 无回归。
+
+## fontconfig 字体数据族（libaribcaption 1.1.2 实证，2026-09-15）
+
+**新数据族实证**：libaribcaption 渲染器经 fontconfig 做字体发现，零售机无
+`/etc/fonts/fonts.conf`、`/usr/share/fonts/` → 真机渲染位图失败（静默假绿形态：
+链接自包含 ≠ 运行期可用，与 E130 同族）。
+
+**随包方案（真机验证通过）**：
+1. **来源**：Conan fontconfig 包提取 `etc/fonts/` 下 `fonts.conf` + `conf.d/`；CJK 字体
+   （NotoSansSC-VF / msgothic / YuGothR）从宿主系统字体目录拷贝；
+2. **打包**：随 HNP `share/` 目录（`share/fontconfig/fonts.conf` + `share/fontconfig/conf.d/`
+   + `share/fonts/*.tt[fc]`）；`fonts.conf` 的 `<dir>` 指向设备安装绝对路径
+   （`/data/app/<pkg>/share/fonts`）；
+3. **自举**（cli 载体 execv 前，hap 载体 NAPI 初始化时）：
+   ```c
+   setenv("FONTCONFIG_FILE", "<hnp-root>/share/fontconfig/fonts.conf", 0);
+   setenv("FONTCONFIG_PATH", "<hnp-root>/share/fontconfig/conf.d", 0);
+   setenv("HOME", "<沙箱可写临时目录>", 0);
+   setenv("XDG_CACHE_HOME", "<沙箱可写临时目录>", 0);   /* fontconfig 缓存目录 */
+   ```
+4. **验证**：真机 `test_fontconfig_freetype` rc=0（字体查找成功 800x120 位图）、
+   `test_gen_renderer` 渲染器全链（含字体后端）rc=0。
+
+**⚠️ bundle 路径一致性陷阱（连锁失败实证）**：`fonts.conf` 内 `<dir>` 写的是
+**设备安装绝对路径**（如 `/data/app/<pkg>/share/fonts`），其中 `<pkg>` = HAP 的 bundle 名。
+**换了 HAP 名 / bundle 名（如 test-demo 与 harmony-cli-runner 的 bundle 不同）后必须同步改
+`fonts.conf` 的 `<dir>`**，否则字体发现指向旧路径、渲染器初始化失败，**该 HAP 内全部渲染
+类用例连锁失败**（libaribcaption test-demo 实证：6 条渲染用例因 fonts.conf `<dir>` 指向
+错误 bundle 路径全部失败，改对后同批恢复）。排查顺序：单条渲染失败先验 fonts.conf 的
+`<dir>` 与当前 bundle 装机路径一致，再查字体文件是否真的随包到达。
+
+**可行性影响**：有本实例后，依赖 fontconfig 的库（渲染/绘图族）随包 + 自举是机械步骤，
+不降级 feasibility；漏判则交付"渲染不出字形"的退化版（验收若含行为级渲染断言即打回）。
+
+## 系统字体目录 /system/fonts 的可读性分层（fontmoa 实证，2026-10-19）
+
+`/system/fonts` **存在**（263 个字体 / 497MB / `drwxr-xr-x` 755 + SELinux `system_fonts_file`），
+含 HarmonyOS_Sans.ttf 全系（SC/TC/Italic/Condensed/Digit/Naskh_Arabic）+ 方正中文系列
+（FZHei/FZKai/FZFang/FZLi 等）+ Noto 多语言 + FTAero/DejaVu 等。能否访问**取决于进程域**
+（分层，不是一刀切）：
+
+| 进程域 | 读 /system/fonts | 实证 |
+|---|---|---|
+| fontconfig / CLI / HNP 域 | ✅（fonts.conf `<dir>/system/fonts</dir>` 直接可用） | GTK broadway 案例（鸿蒙PC-GTK应用broadway-ArkWeb-HAP） |
+| Electron-OH **主进程**（不在 Chromium 沙箱内，完整 Node API + 应用沙箱权限） | ✅ `readdirSync` 263 个 | fontmoa（L060 实证；鸿蒙官方口径 2026-10） |
+| Electron-OH **渲染进程**（运行在 Chromium 沙箱中，系统目录 stat/open 被沙箱策略拒绝） | ❌ **readdir 可列、stat/read 文件 EACCES** | fontmoa `Uncaught Error: EACCES: permission denied, stat '/system/fonts/...'`（L060；官方口径） |
+| 纯 ArkTS 应用进程 | 由 app 域 SELinux 规则决定（无主/渲染二分，单一进程域） | —（官方推荐走系统字体框架，不直接 fs 扫） |
+
+**修法按域选**：
+1. **Electron 渲染层要读系统字体**：**官方 IPC 方案**——主进程 `ipcMain.handle('get-system-fonts'/'get-system-font-file')` 提供列表/文件 Buffer，渲染层 `ipcRenderer.invoke` 获取 + `fontkit.create(Buffer)` 解析（fontmoa 落地：260 列表、逐个入库、搜索命中；IPC Buffer 需反序列化转回、个别文件仍 EACCES 跳过）；
+2. **fontconfig/CLI 域**：`fonts.conf` 的 `<dir>` 直接指 `/system/fonts`（GTK 已实证）或随包字体（本文件 fontconfig 族方案二选一）；
+3. **纯 ArkTS**：走系统字体能力，不直接 fs 扫描。
+
+**可行性影响**：依赖系统字体的应用（字体管理/预览/文档渲染）**不降级**——`/system/fonts` 存在且
+主进程/CLI 域可读；唯一约束是 Electron 渲染进程需主进程拷贝桥（机械步骤，见 L060）。
+