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

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

@@ -0,0 +1,399 @@
+---
+name: file-picker
+description: 文件选择器（Open/Save/目录选择）能力域。鸿蒙 partial，但偏向"免费可用"：应用自绘或调平台 API 的文件对话框，一律应换成系统 DocumentViewPicker（@ohos.file.picker）——系统进程碰文件系统、只回一个作用域 URI，不需要任何存储类 ACL 权限。按 GUI 栈与实际需要分四档：A 走 Qt 原生对话框（QPA 自动转发，零代码）→ B 加纯 NDK 持久授权（跨重启）→ C 自建 NAPI 桥（目录授予/占位文件控制）→ D Swing/AWT 经文件通道请 ArkTS 弹 picker。含判定顺序、ACL 对照、按栈检出方言与真机取证陷阱
+metadata:
+  type: capability-domain
+  source: 四档均有真机实证（Qt5/Qt6 零改动转发、纯 NDK 持久授权、自建 picker 桥、Swing/OH-AWT 文件通道），实证出处见第六节
+---
+
+# 能力域：file-picker（文件选择器 / Open·Save·目录对话框）
+
+**鸿蒙状态：`partial`**——但偏向"免费可用"的那一端：系统自带文件选择器（App Gallery 签发的任意 App 都能调），
+Qt 应用在大多数情况下**调原生对话框就自动拿到它**，不需要写一行适配代码、也不需要声明任何存储权限。
+其它 GUI 栈没有自动转发层，但都能按同一个思路接上（第二节四档）。
+
+> 典型触发：`File ▸ Open` / `Save As` / `Open Folder` 菜单项，任何自绘或调用平台 API 的"选个文件/选个目录"交互。
+
+## 零、这个域要解决什么问题——别先移植应用自己的文件浏览器
+
+常见的坑：上游自带一个自绘文件浏览器（或直接调 `QFileDialog`/`JFileChooser`/`wxFileDialog`
+之类的平台 API），把它原样编译到鸿蒙上。这类选择器在鸿蒙零售机上要么**够不到用户文件**
+（App 沙箱默认只看见自己的数据目录与按路径可读的少数目录，看不见 Downloads/桌面等处的用户文件），
+要么为了"够得着"就去申请大范围存储 ACL 权限（`ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY`、
+`ohos.permission.READ_MEDIA` 之类）——这类权限审核敏感、要多一次系统授权弹窗打断用户，交互风格也和系统别处不一致。
+
+**正确方向是反过来**：不要把自绘选择器"移植好"，而是把它**换成**鸿蒙系统自带的
+`DocumentViewPicker`（`@ohos.file.picker`）。系统选择器由**系统进程自己**碰文件系统，
+只把结果包成一个带作用域授权的 URI 还给应用——应用从未直接拿到越权的文件系统访问，
+所以**不需要申请任何存储类 ACL 权限**。省权限和风格统一其实是同一个选择，不是两件要分别争取的好处。
+
+这条结论不分 GUI 栈：纯 Java 的 `JFileChooser` 在鸿蒙的 AWT 运行时上**画得出来、也能点**，
+所以很容易被当成"已经可用"放过去——但它只能列出应用按路径读得到的目录，用户的大部分文件在外面。
+能画出来 ≠ 本域不命中。
+
+而且"读得到"也不等于"用户够得着"：实测一个 Qt 端口的自绘对话框停在 `/storage/Users/currentUser`，
+列表里只有一个 `Documents`——同一层的 `Download` 应用其实**读得到**（21 个文件），但上一级目录
+本身不可枚举，用户无法从界面走到那里。拿到了权限的目录照样可能在自绘浏览器里消失。
+
+## 一、怎么检出——按 GUI 技术栈分方言
+
+```bash
+# Qt (C++) ——（a）静态函数族
+grep -rlaiE "QFileDialog::(getOpenFileName|getOpenFileNames|getSaveFileName|getExistingDirectory|getOpenFileUrl|getOpenFileUrls|getSaveFileUrl|getExistingDirectoryUrl)" source/
+# Qt (C++) ——（b）QFileDialog 实例族：别漏！工程常自己封一层以便设 QDir 过滤位/名称过滤器，
+#            只查静态族时会只命中零星的目录选择、漏掉真正的 Open/Save 主路径
+grep -rlaiE "new QFileDialog|QFileDialog +[A-Za-z_][A-Za-z0-9_]* *\(" source/
+# GTK
+grep -rlaiE "gtk_file_chooser_(dialog_new|new)" source/
+# wxWidgets
+grep -rlaiE "wxFileDialog|wxDirDialog" source/
+# Java Swing/AWT
+grep -rlaiE "JFileChooser|java\.awt\.FileDialog" source/
+# Electron 主进程（壳层接线见 pc-knowledge-base 的 electron/ 技术域）
+grep -rlaiE "dialog\.(showOpenDialog|showSaveDialog|showOpenDialogSync|showSaveDialogSync)" source/
+# Win32 原生（通常是旧 MFC/纯 Win32 分支，鸿蒙口径下属平台条件编译死代码）
+grep -rlaiE "GetOpenFileNameW?|GetSaveFileNameW?|IFileOpenDialog" source/
+# 本端口是否已经接过系统选择器（接续轮次先查这条，别重复造）
+grep -rlaiE "@ohos\.file\.picker|@kit\.CoreFileKit|DocumentViewPicker|OH_FileShare_(Persist|Activate)Permission" .
+```
+
+`-a` 别省——`app-self-update.md` 记录过同一类坑（二进制判定的源文件被 grep 静默跳过、既不报错也不计数）；
+文件对话框代码常和资源字节一起塞进同一个 `.cpp`，更容易踩这个雷。
+
+**`source/` 不是唯一的被测面**——有的端口根本不 vendor 上游源码，只带一个预构建的载荷 jar 加一层
+launcher（实测一个 Java 端口：`source/` 是空目录，launcher 的 9 个类在 `harmony-app/java/` 下，
+应用本体在 `resfile/*.jar` 里）。对这类端口上面的 grep **全部返回零——不是本域不命中，是被测面不在那儿**。
+改查字节码，类名在常量池里是明文：
+
+```bash
+T=$(mktemp -d); unzip -q <payload>.jar -d "$T"
+grep -rla "JFileChooser" "$T" --include=*.class | sed "s|$T/||"
+```
+
+实测命中两类：上游的真入口（`org/jd/gui/controller/MainController`）与**本端口自己加的重定向补丁**
+（`.../launcher/HarmonyUiFixes`）。后者尤其值得看一眼——它通常正是第零节说的"把自绘选择器钉在一个
+能读的目录上"的那种权宜之计，是本域要换掉的东西，不是已经做好的适配。
+
+**已经在档 A 的端口，再查一眼权限**——这是最容易留下的尾巴：
+
+```bash
+grep -nE "READ_WRITE_(DOCUMENTS|DOWNLOAD|DESKTOP)_DIRECTORY|READ_MEDIA" harmony-app/entry/src/main/module.json5
+```
+
+走系统选择器的文件**不需要**这些（第三节）。它们通常是「先按桌面思路加权限、后来才换成 picker」留下的，
+除非确有不经选择器的按路径访问，否则该删——而且它们不是免费的：调试 profile 的 `allowed-acls` 为空时
+`READ_WRITE_DESKTOP_DIRECTORY` 这类 ACL 权限根本签不下去，安装直接 9568289（实测一个 Qt 端口在档 A
+上仍挂着三个存储权限，其中 DESKTOP 让签名前检查直接拦下）。
+
+**命中后先分三类，别直接动手改**：
+
+1. **真功能** —— 菜单项/按钮能走到它。按第二节选档。
+2. **平台条件编译死代码** —— Win32/Cocoa 分支（`#ifdef Q_OS_WIN` 之类）里的对话框，鸿蒙口径下根本不编。
+   记一笔即可，不要为它写适配。
+3. **已接过** —— 上一轮或上游已经接了系统选择器（最后一条 grep 命中）。先读现状再决定是否扩展，别重复造。
+
+## 二、替换方案——四档；判定顺序是"先假设在最省的那档，用设备证据才升档"
+
+| 档 | 什么时候用 | 典型代价 |
+|---|---|---|
+| **A** | GUI 栈有自动转发层（当前已知：Qt-for-OHOS 的 QPA），且只要"选一个文件/目录" | 0~1 行（parent） |
+| **B** | A 之上还要**跨进程/跨重启**保持对所选文件的访问（最近文件、会话恢复） | 纯 NDK 百行量级，无 ArkTS 侧 |
+| **C** | A/B 给不了的粒度：目录级授予、占位文件行为控制、同时要物理路径与 URI | 自建 NAPI 桥（C++ ↔ ArkTS）+ ArkTS 侧托管 |
+| **D** | GUI 栈没有自动转发层，且 UI 线程在非 ArkTS 侧（Swing/AWT、GTK、wx…） | 文件通道/桥 + 逐个调用点替换 |
+
+**新端口的走法**（按顺序，每一步都要设备证据才进下一步）：
+
+1. 第一节检出 + 分类；确定 GUI 栈。
+2. 栈是 Qt → 直接按档 A 冒烟（确认 parent 正确）。**不要在没有设备结论前先建桥**。
+3. 冒烟通过但发现"重启后打不开上次的文件" → 升档 B。
+4. 仍不够（要目录授予 / 要控制占位文件 / 要路径与 URI 成对） → 升档 C，并在 `03-adapt.json` 里写明是哪一行能力把你推上去的。
+5. 栈不是 Qt → 档 D；机制照 2.4 节的 7 条，工作量按调用点数量估。
+6. 不论哪档：按第七节改判测试用例，否则旧断言会把"换成系统选择器"报成功能回归。
+
+**排期（不是步骤，是约束）**：命中本域就是阶段 3 编码步骤里的**必做项**，与载体搭建同批做，不要排成
+「先原样验证、再升级」。原因在于这件事在宿主机上看不出来：名册里的文件对话框用例用自绘选择器照样全绿
+（`JFileChooser` 能画出来也能点），要等真机上点「打开」才发现它只看得见应用自己的沙箱目录。
+机器执法是验收规则 `file-picker-system-picker`（`ohpt-agent check` 可查）：交付物里找不到系统选择器调用即告警，
+只告警不阻塞；确实做不了时把原因与证据写进 `remaining_blockers`——那是被看见的取舍，但仍是缺口。
+判据与适用条件以规则本身为准，这里不重复。
+
+### 2.1 档 A（免费）：Qt 应用，原生对话框自动转发到系统选择器
+
+Qt 应用调标准 `QFileDialog`、未设 `QFileDialog::DontUseNativeDialog` 时走的是"原生对话框"路径。
+Qt-for-OHOS 的 QPA 插件在这条路径上实现了 `QOhNativeFileDialog`，底层直接用 NAPI 构造
+`@ohos.file.picker` 的 `DocumentViewPicker` 并调 `select(DocumentSelectOptions)` /
+`save(DocumentSaveOptions)`（经 `QtOh::runOnJsUIThreadNoWait` 切到 ArkTS JS 线程——
+`app-self-update.md` 第四节描述的 kit 助手，这里是它的另一个使用者）。也就是说：
+**只要应用走的是 Qt 的原生对话框路径，系统选择器是自动的，零适配代码，零 ACL 权限声明。**
+
+**静态函数不是唯一入口**：`QFileDialog` 实例 + `exec()`（`QFileDialog dialog(parent, ...); dialog.exec();`）
+走同一条原生路径，一样自动转发。工程里常见这种写法（为了拿到静态方法没暴露的 `QDir` 过滤位）。
+**不要因为 grep 只命中静态族就以为本域不命中**；反过来也别因为看见实例写法就先判要自建桥。
+
+唯一的平台约束是 parent。QPA 侧 `validContextAndWindow()` 有一条回退链：
+传入 parent → `QGuiApplication::focusWindow()` → 最后一个顶层窗口；三者全空才拿不到 context、
+picker 根本弹不出来。**回退链存在不等于可以不传**：回退命中的可能是隐藏窗口或错误的顶层窗口，
+于是选择器锚不到正确位置（模态链问题，与 `graphical-window.md` 的"隐藏 parent 破坏模态链"同一类）。
+所以档 A 的全部工作往往就是把 `NULL` parent 换成真实窗口：
+
+```cpp
+// 改前：file = QFileDialog::getOpenFileName( NULL, qtr( "Select File" ), ... );
+// 改后（宏在非鸿蒙平台保持原样，避免影响其它平台）：
+file = QFileDialog::getOpenFileName( APP_DIALOG_PARENT( NULL ), qtr( "Select File" ), ... );
+// #define APP_DIALOG_PARENT( p ) ( (p) != NULL ? (p) : ohosMainWindow() )   // 仅鸿蒙分支
+```
+
+源码本来就传 `this`/真实窗口的工程，档 A 是**零改动**。
+
+**档 A 的自动化判据**（避免把平台特性误判为缺陷）：
+
+> 原生 `QFileDialog` 唤起的是**系统 picker 应用**（另一个进程的窗口）；
+> Qt 侧留下的 `QWindow` 稳定停在 **100×30、`isExposed()` 恒为 false**——这是占位符的正常形态，
+> 不是故障。用 Qt 侧几何或 `isExposed` 判断原生对话框健康会误杀。真正坏掉的模态在 WMS 侧
+> 有明确特征（`ZOrd=-1` + `rect[0 0 0 0]`，`hidumper -s WindowManagerService -a -a` 可查），
+> 不要用 Qt 侧 API 判断。
+
+把同一个对话框分别以原生路径和 `DontUseNativeDialog` 打开一次，就得到一组**可自动判读的对照**
+（实测值，同一端口同一台设备）：
+
+| | `winGeom` | `exposed` | `qtChildWidgets` | `dontUseNativeDialogSet` |
+|---|---|---|---|---|
+| 系统选择器（档 A） | `100x30` | 0 | **0** | 0 |
+| Qt 自绘对话框 | `662x430` | 1 | **61** | 1 |
+
+`qtChildWidgets` 是最干净的判据：系统选择器在本进程里**没有任何子控件**。用它断言"确实走到了系统选择器"，
+不要用"对话框可见"——两种路径都报 `dialogVisible=1`。
+
+关于 `QEmbeddedUiExtensionAbility`：**不是档 A 的前置条件**——实测多个 Qt 端口的 `module.json5`
+没有声明它、照样拿到系统选择器；声明它的那个端口是因为自建桥（档 C）的 embeddedUI 需要。
+早期轮次留下的"Qt 要落到系统 Picker 必须声明 `QEmbeddedUiExtensionAbility`"是那一轮工程的局部结论，
+别当通用前置照抄。
+
+### 2.2 档 B：只是要"下次启动还能打开同一个文件"——纯 NDK，不要为此建桥
+
+**系统选择器的授权默认只活在选择它的那个进程里。** 重启后"最近文件 / 会话恢复"重开同一文件得 `EPERM`
+——这是默认语义，不是回归。但解决它**不需要离开档 A**：路径是原生对话框已经还给你的，
+持久化只是对这个路径再调两个 NDK 函数，全程在 C++ 侧，ArkTS 侧一行不用写。
+
+实现要点（百行量级，用平台宏守卫、其它平台留空实现）：
+
+1. `module.json5` 声明 `ohos.permission.FILE_ACCESS_PERSIST`（normal / system_grant，只需声明、无需 ACL；
+   较新的 Qt 版本生成的 `module.json5` 可能已自带，先查再加）。
+2. 选择器返回路径后：`OH_FileUri_GetUriFromPath()` 转 URI → `OH_FileShare_PersistPermission()`
+   （头文件 `filemanagement/file_uri/oh_file_uri.h`、`filemanagement/fileshare/oh_file_share.h`，
+   链接 `libohfileuri` / `libohfileshare`）。
+3. 下次启动重开前先 `OH_FileShare_ActivatePermission()`，再打开文件。
+4. **先试 `READ_MODE|WRITE_MODE`，失败再退到 `READ_MODE`**——否则重启后文件能读不能存。
+5. 收到 `ERR_DEVICE_NOT_SUPPORTED`（801，设备无 FolderAuthorization 能力）后**置位标记、不再重复调**。
+6. 应用沙箱自有路径（`/data/storage/` 前缀）跳过，本来不需要授权。
+7. 逐条策略的失败要打出 `uri` 与 `code`（NDK 以 `FileShare_PolicyErrorResult` 数组回报，
+   记得 `OH_FileShare_ReleasePolicyErrorResult`）；仍打不开时给用户明确提示
+   （如"访问可能已过期，请用 File ▸ Open 重新选择"），不要静默失败。
+
+**怎么在没有真人点选择器的情况下验收这一档**：对一个用户目录下的真实文件依次 `persist` → `activate` → 重开，
+把两次调用的 rc 打进日志即可——证据形状是
+
+```
+persist  1 uri(s) mode=3 rc=0      # mode=3 = READ_MODE|WRITE_MODE，第一档就成了，没退到只读
+activate 1 uri(s) mode=3 rc=0
+```
+
+`rc=0` 表示授权往返在这台设备上成立；`rc=801` 是设备没有 FolderAuthorization 能力（平台事实，不是端口缺陷）；
+其它值才是真失败。完整的"选择器选中 → 重启 → 最近文件重开"仍需真人操作，但机制本身到这里就已被证明。
+
+这一档是**档 C 判定的前置门槛**：看到"要持久授权"别直接跳去建桥。
+
+### 2.3 档 C：原生对话框接口给不了的粒度，才自建 NAPI 桥
+
+同样是 Qt 应用、同样命中 `qt-toolchain`（available），仍可能需要自建桥——
+**判据不是"档 A 不可用"，而是下面这几件事 `QFileDialog` 的路径返回式接口本身不暴露：**
+
+| 需要的能力 | 原生对话框给不了的原因 | 桥接方案 |
+|---|---|---|
+| 目录/批量授予（一次导出一组编号文件，单文件授权覆盖不了后续文件） | 原生对话框的授权粒度是"这一个文件"，没有文件夹模式的编程接口 | 走 `DocumentSelectMode.FOLDER`（folder-mode picker），拿到目录授权后在该目录下创建/写入 |
+| 占位文件行为控制（排队任务的输出文件还没产生内容前，不该出现一个 0 字节的假文件） | `DocumentSaveOptions.autoCreateEmptyFile` 默认 `true`，原生对话框不暴露这个开关 | 直连 `DocumentSaveOptions` 并显式置 `autoCreateEmptyFile=false` |
+| 同时要物理路径**与** URI（项目文件存物理路径、授权挂在 URI 上，两者要成对落盘对照） | 原生对话框只还一个本地路径字符串，URI 被封装掉了 | 桥同时回传两者；路径→URI 对照表落盘，启动时逐条 `Activate`（持久化本身仍是档 B 的 NDK 调用） |
+
+桥接的核心形状（C++ 侧，`dlopen` 探测 + 事件循环等结果）：
+
+```cpp
+// ArkTS 侧托管 DocumentViewPicker 实例，实际调用必须在 JS 线程；C++ 侧用 QEventLoop 等回调
+// （绝不阻塞 JS 线程——同一不变量见 app-self-update.md 第四节"两条路都必须切到 ArkTS UI 线程"）
+typedef int (*ohos_picker_request_t)(int mode, const char *name, const char *ext,
+                                     const char *hint, ohos_picker_cb cb, void *ctx);
+void *h = dlopen("lib<app>_ohospicker.so", RTLD_NOW);
+auto request = (ohos_picker_request_t)dlsym(h, "<app>_picker_request");
+// mode 的一种实用划分：0 open / 1 save / 2 dir / 3 fetch(uri→sandbox) / 4 commit(sandbox→uri)
+//                      / 5 download-dir / 6 commit-into-dir
+```
+
+**有了桥也不要保留自绘对话框作后备**：实证端口的结论是"系统选择器是本产品唯一的文件对话框"，
+桥失败时给错误提示，不回退到 widget 画的对话框——那条路径本就绕不开同一个沙箱限制，
+回退等于把问题留在原地，还会让取证时分不清用户走的是哪条路。
+
+### 2.4 档 D：UI 线程不在 ArkTS 侧的栈（Swing/AWT、GTK、wx…）——文件通道 + ArkTS 弹 picker
+
+`DocumentViewPicker` 只能从 ArkTS 侧弹起。没有 QPA 那样自动转发层的栈，要自己把"请求"送到 ArkTS 侧、
+把"结果"送回来。Java/Swing 栈上这条路已在真机验证过（第六节），机制七条：
+
+1. **一条文件通道**：应用沙箱里一个约定目录（如 `<filesDir>/<app>-control/`）。
+   宿主侧写请求文件（`pick-open` / `pick-save`），内容是后缀过滤器、起始目录、建议文件名（save）、
+   可选对象（文件/文件夹/两者）与数量上限。有些端口已为"重启/退出/打开方式"建过同一条通道，复用它。
+2. **写-改名，不要直接写**：先以另一个名字写完再 `rename`，ArkTS 侧的监听加上 `IN_MOVED_TO`——
+   否则监听器会读到半截文件。回传方向（`pick-result`）同样先写临时名再改名。
+3. **ArkTS 侧**（Ability 内）收到请求后构造 `picker.DocumentViewPicker`，
+   按请求调 `select`（过滤器 + 模式 + 数量）或 `save`（建议名 + 每类型一个后缀），
+   把所选路径写回结果文件；**取消要写一个空行**，别什么都不写（宿主侧会一直等）。
+4. **宿主侧在二级事件循环里等**（Swing 是 `SecondaryLoop`）——这样主窗口在选择器弹着时照常重绘；
+   期间来的第二个请求直接忽略（并发两个选择器是真实回归，见第五节）。
+5. **调用点替换成同签名的站位方法**：顶替原生 chooser 的同名方法，从 chooser 对象上取起始目录、
+   选择模式、是否多选、建议名；确认后把所选文件**写回 chooser 对象**并触发它的"已确认"回调
+   （Swing 是 `approveSelection()`），这样上游挂在 chooser 上的监听器照常跑；取消则不动 chooser。
+   这个形状让上游调用点改动最小，且能逐个调用点灰度。
+   **改不到上游调用点时还有第二种形状**：载荷是预构建 jar、拿不到上游源码时，钩子下在对话框本身——
+   在窗口打开事件（AWT 的 `WINDOW_OPENED`）里认出 chooser，把这个自绘对话框挪到屏幕外
+   （它仍然是模态的，照样挡住本应用的其它输入，只是用户看不见它），结果回来后
+   `approveSelection()` / `cancelSelection()`，上游的 `showOpenDialog()` 就带着正确返回值自然收尾。
+   实测可用，改动全在 launcher 侧，业务字节码零改动。
+6. **起始目录**：chooser 默认的 `user.home` 在鸿蒙上是应用私有目录，要换成用户可见目录
+   （应用自己的文档目录，或上次用过的目录）。
+7. **留一个开关**（配置项即可）切回原生 chooser——便于在同一台设备上做"自绘 vs 系统 picker"的 A/B 取证，
+   也是出问题时的运维退路。
+
+**工作量主要在调用点数量上，不在机制上**：机制只有这七条，之后是逐个对话框接。
+档 D 带来的语义差异必须一并处理（第五节「档 D 专有」），否则会出"功能退化"工单。
+
+> GTK / wxWidgets 栈：`@ohos.file.picker` 这个 ArkTS 入口本身是通用的，但这两个栈在本插件里
+> 还没有已验证样本，也没有对应的 GUI 工具链域条目。按本节思路自建（NAPI/JNI 视绑定层而定），
+> 完事后按第六节格式补一条现场记录；**不要凭 Qt 的经验直接断言"一样能自动转发"**。
+
+## 三、这就是为什么不要自己管权限——三条路线的 ACL 对照
+
+| 路线 | 需要声明的权限 | 谁碰文件系统 |
+|---|---|---|
+| 自绘文件浏览器 / 原生 chooser（自己遍历目录、列文件） | 想够到用户卷就得要 `ohos.permission.READ_WRITE_DOWNLOAD_DIRECTORY` / `ohos.permission.READ_MEDIA` 等大范围存储权限，且要用户在系统弹窗里显式同意；**不要就只能看见应用自己读得到的那一小块** | 应用自己，越权面=整个被授权的目录树 |
+| 系统 `DocumentViewPicker`（本域方案，档 A/D） | **不需要任何权限** | 系统选择器进程；应用只拿到一个作用域限定到"用户刚选的那个文件/目录"的 URI |
+| + 跨进程持久授权（档 B/C） | `ohos.permission.FILE_ACCESS_PERSIST`（normal/system_grant；仅为了让已经发生过的那次选择在重启后继续有效，不扩大选择范围） | 同上，持久化的仍是同一个 URI 的授权 |
+
+这张表是本域存在的理由：复刻一个自绘选择器几乎总是在拿一个更大的权限换一个更差的体验。
+
+## 四、判定分支（GUI 技术栈 × 实际需要）
+
+| GUI 栈 / 交付形态 | 判定 |
+|---|---|
+| Qt 应用（`qt-toolchain`=available），原生 `QFileDialog`（静态函数**或**实例 + `exec()`） | `feasible`，工作量 S——确认传了真实 parent，设备冒烟一次即可，多数情况零代码（档 A） |
+| Qt 应用，要跨重启保持访问（最近文件/会话恢复） | `feasible`，工作量 S——档 B，纯 NDK 持久授权，**不需要自建桥** |
+| Qt 应用，需要目录级授予 / 占位文件控制 / 路径与 URI 成对 | `feasible`，工作量 S-M——档 C 自建桥；**动手前先用设备冒烟证实档 A/B 确实不够** |
+| Swing/AWT 应用，GUI 在本端口已能上屏（鸿蒙 AWT 运行时，`awt.toolkit=sun.lwawt.harmonyos.*`） | `feasible`，工作量 **M——按调用点数量算**；档 D 有真机验证过的样板可照抄 |
+| 任何栈，但本端口 GUI 根本没跑起来 | 本域不是独立瓶颈，随该 GUI 栈的解法一并判定 |
+| GTK / wxWidgets 应用 | `feasible`（入口通用），工作量按是否需要自建桥判；本插件暂无已验证样本，按档 D 的思路做并补记录 |
+| Electron 应用 | 主进程 `dialog` 模块是否已对接系统选择器由壳层决定，不在本域展开——接线与机制见 `pc-knowledge-base` 的 `electron/` 技术域 |
+| `cli` / `pure-runtime` / `cpp-lib` | 没有窗口上下文，本域不适用——除非该交付物内部确实起了一个 GUI 子进程/子窗口 |
+
+> **判"GUI 没跑起来"必须用本端口的设备结论**，不要把别处的 GUI 栈状态当结论直接套。
+> 具体地：`swing-jdk-gui.md` 仍写着 `unavailable / infeasible`，而本插件已有多个 Swing/AWT 端口
+> 在厂商鸿蒙 AWT 运行时（`sun.lwawt.harmonyos.LWCToolkit` / `OHGraphicsEnvironment`）上真机跑起来
+> 并做完设备用例——那份判定早于这个运行时到场。本域按实测事实判；那个域条目本身需要单独一轮修订（见"相关"）。
+
+## 五、已知坑
+
+### 通用 / 原生对话框（档 A-C）
+
+- **别用 Qt 侧几何或 `isExposed()` 判断原生对话框是否正常**——系统选择器把本侧的
+  `QWindow` 留成固定 100×30 占位符，这是正常形态；真正坏掉的模态要查 WMS
+  （`hidumper -s WindowManagerService -a -a`，特征是 `ZOrd=-1` + `rect[0 0 0 0]`）。
+- **静态 `QFileDialog` 的嵌套事件循环无法被本进程 `close()`/`reject()` 从代码里拆开**——
+  自动化用例只能断言"选择器弹出来了"，真正验证"选完值落进了字段"要走 `uitest uiInput`
+  的真实输入路径，不能在代码里替用户关掉它。
+- **必须传真实 `parent`，不要传 `NULL`/`nullptr`**——QPA 的回退链（focusWindow → 最后一个顶层窗口）
+  可能锚到隐藏窗口或错误窗口，三者全空时选择器根本不弹。
+- **起始目录别用根路径**（`QDir::rootPath()` 之类）——否则真机面包屑从 `/` 开始，用户从系统
+  根目录里找不到自己的文件；改用应用数据目录或上次记住的目录。
+- **选择器授权默认是进程级、不是持久的**——同一个文件下次启动可能打不开，这不是回归，是
+  默认语义；需要跨会话时走档 B。
+- **持久授权要先试读写再退读**——只 `READ_MODE` 持久化的文件重启后能打开却存不回去。
+- **801（`ERR_DEVICE_NOT_SUPPORTED`）要置位后不再重复调**——部分设备没有 FolderAuthorization 能力，
+  持久授权永远不会成功；每次打开文件都重试会刷满日志且无意义。
+- **【取证陷阱】手打一个没经过选择器的新路径会被拒**——Qt 侧报
+  `"<path> is not writable. Please choose a different file name."`、文件不生成；同一功能改走
+  「浏览 → Picker → Save」即成功。写基线/复验记录时必须注明成功那次**走的是哪条路径**，
+  否则复验会被误判为回归（实证端口险些发生）。
+- **【取证陷阱】`hdc shell`（uid 2000）与 App 不在同一 mount namespace**——
+  应用视角的 `/storage/Users/currentUser` 在 shell 下不存在，同一文件 hdc 视角是
+  `/storage/media/100/local/files/Docs/...`。"shell 里读不到"不构成没写成的证据，
+  也不能据此判定文件已删除；要跨进程独立复核就用选择器自己去列目录。
+- **交互式选择器弹出时要挡住本应用的其它输入**，并拒绝第二个并发选择器请求——否则用户能在
+  选择器之外继续点别的按钮，叠出第二个选择器请求（实证端口的真实回归）。
+- **`DocumentSaveOptions.autoCreateEmptyFile` 默认创建空文件**——排队任务这类"现在选路径、
+  以后才写内容"的流程会在文件列表里留下一个能打开却是空的占位文件，除非显式关闭（档 C）。
+- **【Electron 实证】`dialog.showSaveDialog`（OH-Electron 接 `DocumentViewPicker.save`）预创建 0 字节
+  目标文件**——应用的「stat 存在性 / rev 比对」逻辑会把占位文件当成「已存在 / 磁盘更新版本」，
+  进而触发重载解析空文件（keeweb 实证：`Error FileCorrupt: not enough data`）。修法：在 `stat` 层把
+  0 字节文件按 notFound 处理，保存走新建写盘覆盖占位；与上文 `autoCreateEmptyFile` 是同一平台事实的
+  两种表现（Qt 档 C 关开关、Electron 壳层在 stat 侧兜底——有效 kdbx 文件永远不可能是 0 字节）。
+- **无扩展名的读请求，先让选择器给"全部文件"而不是默认类型过滤器**——默认类型过滤器
+  （如"仅视频"）会把同一个对话框需要选的其它文件类型（字幕/脚本/图片）挡在看不见的地方。
+
+### 档 D 专有（宿主侧 chooser 换系统选择器）
+
+- **系统"打开"对话框选不出还不存在的文件**——而自绘的打开对话框可以键入新名字，上游"写结果到文件 /
+  Browse"这类字段正依赖这一点。解法是**让那个 Browse 改用保存对话框**，而不是把字段改成只读。
+- **保存对话框会替你把文件创建出来**，于是下游"这个文件已存在"的逻辑会误判：
+  上游可能去加载它（报"加载失败"）、运行前问"追加/覆盖"、或者为这个空文件做备份。
+  走档 D 后这三处都要按"这是一个新文件"处理。
+- **应用自己的"是否覆盖？"确认要在这条路径上跳过**——系统保存对话框已经问过一次，不跳过就连问两次。
+- **后缀过滤器的第一项就是默认项**——把应用的各个类型逐个塞进选择器的过滤器列表时，选择器把第一项当
+  选中项，于是只认那一种后缀，用户真正要开的文件一个都不显示（实测：某端口 10 种可开类型逐个传入，
+  列表里只剩文件夹，一个文件都没有）。第一项必须是**覆盖全部类型的合并项**
+  （`"Supported|.jar,.class,.zip,…"`），单独的类型可以跟在它后面。这和"无扩展名请求给全部文件"
+  是同一个坑的两种犯法。
+- **建议文件名要带后缀**——宿主侧的类型过滤器常把不带后缀的名字清空，于是"另存为"不给建议名。
+- **选择器偶尔打开的是它上次停留的目录**，而不是应用请求的目录（请求目录确实到达了，日志可查）；
+  这不影响用户的选择结果，别当缺陷查。
+- **等待必须用二级事件循环**（Swing 的 `SecondaryLoop` 或等价物）——直接在 UI 线程上阻塞等回传，
+  主窗口会在选择器弹着的时候变成白板。
+- **把开关留着**——取证时要能在同一台设备上对照"自绘 chooser vs 系统 picker"两种行为。
+
+## 六、现场实证（本域四档各自的出处）
+
+记录"这一档被谁证过、证据在哪"，供接续轮次比对；**新端口按第二节判定，不要照抄某个端口的档位**。
+
+| 档 | 实证形态 | 改动量 | 出处 |
+|---|---|---|---|
+| A | Qt 5.15.17，URL 族静态 API；把 4 个调用点的 `NULL` parent 换成真实窗口 | 4 行 | vlc `patches/vlc-3.0.24-beta1-ohos-adaptation.patch` |
+| A | Qt 5.15.17，路径字符串族静态 API，源码本就传 `this` | **0** | ohos-cppcheck 源码 + 100×30 占位 `QWindow` 的平台事实记录 |
+| B | Qt 6.12，`QFileDialog` 实例族主路径 + 纯 NDK 持久授权，ArkTS 侧 0 行 | ~150 行（`OhosFileAccess.h`） | ohos-notepadnext `patches/0001`；TC-FILE-048..055（0.11 轮为 TC-FILE-037） |
+| B | Qt 5.15.17，静态族 + 纯 NDK 持久授权，接在「选择器返回」与「重开记忆路径」两端 | ~150 行（`ohosfileaccess.cpp`） | ohos-cppcheck；真机实测 `persist`/`activate` 均 `mode=3 rc=0`（读写档一次成），完整「选中→重启→最近文件重开」仍需真人操作 |
+| C | Qt 5，自建 `dlopen` 桥 + ArkTS 托管 picker + 持久授权 + folder 模式 | ~670 行 + ArkTS/NAPI 侧 | ohos-avidemux `patches/0014-ohos-user-file-picker.patch`，owner decision D14（2026-10-06）定为唯一文件对话框路线 |
+| D | Swing/AWT on 鸿蒙 AWT 运行时，文件通道 + ArkTS picker，11 个宿主类 + Ability | 调用点驱动 | ohos-jmeter `patches/ohos-adapt-031-system-file-picker/`，2026-10-08 真机验证 20 项，`build/device-results/system-file-picker/` |
+| Electron 壳层 | OH-Electron v37.2.3，`dialog.showSaveDialog`→`DocumentViewPicker.save` 预创建 0 字节目标；renderer `Storage.file.stat` 判 0 字节为 notFound（避免 rev 误判触发空文件重载解析） | 1 行 | keeweb 1.18.9 `patches/0006`（2026-10-16 真机验证通过） |
+
+## 七、可行性影响与测试用例改判
+
+**不要因为这个域判 `infeasible`，大概率也不该先判 `hard`。** 先按第二节的顺序试最省的那档：
+
+| 场景 | 判定 |
+|---|---|
+| 栈有自动转发层（Qt），原生对话框（静态或实例） | `feasible`，工作量 S；设备冒烟一次确认 parent 正确即可结案 |
+| 需要跨重启保持访问 | `feasible`，工作量 S；档 B 纯 NDK，不要为此建桥 |
+| 需要目录授予/占位文件控制/路径与 URI 成对 | `feasible`，工作量 S-M；档 C 自建桥，但先用设备证实档 A/B 确实不够 |
+| 栈无自动转发层但 GUI 已能上屏 | `feasible`，工作量 M（按调用点数量）；档 D |
+| 本端口 GUI 栈确实不可用（有本端口的设备结论） | 本域不是独立瓶颈，随该域解法一并判定 |
+
+**必须一并处理测试用例**——这是本域最容易出"假回归"的地方：
+
+- 断言"点了 Open 弹出**本应用的**对话框"的旧用例要改判：系统选择器弹出的是另一个应用的窗口，
+  断言要改走 WMS/uitest 侧的证据，不能再读本应用的 Qt 对象树 / 组件树。
+- 断言"选完文件/目录后字段被填充"的用例应保留，但验证路径换成真实输入注入 + 回读字段文本，
+  不要在代码里模拟选择器的返回（那等于只测了你自己的 mock）。
+- 档 D（第五节「档 D 专有」）还要改判两类上游用例：依赖"打开对话框能键入新文件名"的，和断言"应用自己问是否覆盖"的。
+- 复验"保存/导出/重开"类功能时，记录里必须写明走的是**手打路径还是经选择器**——
+  否则第五节那条取证陷阱会把平台约束报成回归。
+
+## 相关
+
+- `pc-recipe-qt-app` —— Qt 端口整体工具链栈状态；档 A 正是该工具链栈自带的能力，不需要单独声明
+- `app-self-update.md` —— 同一个 `QtOh::runOnJsUIThread*` kit 助手的另一个使用者；ArkTS-only API 跨到原生侧的两条路（链接 Qt 用 kit 自带能力 / 不链接 Qt 自写桥）同样适用于本域。档 D 的"文件通道"与该文件记录的 ArkTS↔宿主协作是同一类机制
+- `swing-jdk-gui.md` —— **状态待修订**：该文件仍判 `unavailable / infeasible`，而本插件已有多个 Swing/AWT 端口在厂商鸿蒙 AWT 运行时上真机跑通。本域按第四节注释的实测事实判，不要沿用那份状态；那份判定的修订影响整端口的 feasibility，需单独一轮处理
+- `pc-knowledge-base` 的 `electron/` 技术域 —— Electron 应用的 `dialog` 模块走壳层接线，不在本域展开
+- `system-file-icon.md` —— 同属"文件管理类交互"但判定独立：图标域管的是列表里怎么显示文件图标，本域管的是怎么选文件，两者不要合并判定

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gl-rendering/00-overview.md

@@ -0,0 +1,79 @@
+# 能力域：gl-rendering（GL/GLES 渲染）
+
+## 能力描述
+
+创建 GL 上下文并做立即模式渲染：GLUT 系库（freeglut/OpenGLUT）、`glRasterPos`+`glBitmap` 位图文字、`glBegin/glEnd` 立即模式绘制、`glColor4f`/`glOrtho`/矩阵栈固定管线、显示列表、GLU（quadrics/NURBS）。
+
+**典型触发**：依赖里出现 `glu.h`，或源码里有 `glRasterPos` / `glBitmap` / `glBegin` / `glColor4fv` / `glNewList` / `gluSphere` 调用。
+
+## 鸿蒙状态：partial（EGL/GLES 通路现成，立即模式功能面须重实现）
+
+| 子能力 | 状态 | 说明 |
+|---|---|---|
+| 上下文创建 | available | EGL（`OHOS_PLATFORM` 使 `EGLNativeWindowType` = `struct NativeWindow*`），表面来源见 graphical-window 域；上游带 egl 后端的库（freeglut `src/egl`）直接复用 |
+| GLES 库 soname | constrained | NDK sysroot 有 `libGLESv2.so`，但设备（实测 ≥6.1.1.135 HAD-W32）只有 `libGLESv3.so`，无 GLESv2。构建期 `FIND_LIBRARY(GLES2_LIBRARY NAMES GLESv2 ...)` 会优先选中 GLESv2 写入 NEEDED → 设备 dlopen 静默失败（无任何报错日志）。构图库一律优先/固定链 `GLESv3`（详见 `01-route-gles-vs-gl4es.md`「关键事实 3」、错误图谱 E167） |
+| 立即模式几何 | partial | 顶点缓冲 + shader（freeglut `fg_geometry.c` 的 GLES2 模式），attribute 槽经 `glutSetVertexAttribCoord3` 挂到应用 program |
+| 立即模式文字（glBitmap/glRasterPos） | partial | 内嵌字体数据 + shader 渲染，配方见 `02-imm-mode-font-menu.md`；度量函数纯数据读，零 GL 依赖 |
+| GLUT 菜单 | partial | 帧缓冲覆盖层 + swap 钩子，配方见 `02-imm-mode-font-menu.md` |
+| 固定管线状态（glColor/矩阵栈） | partial | GLES 无 current color、无矩阵栈可读可切；内部 uniform 颜色 + per-window 光标替代 |
+| GLU（tess/NURBS/quadrics/ScaleImage） | available（gl4es 路线）或 unavailable（纯 GLES 路线） | 配方见 `03-glu-cross-compile.md`；纯 GLES 路线仍 unavailable |
+
+## 替换方案
+
+| 原能力 | 鸿蒙替换 |
+|--------|---------|
+| GLX/WGL 上下文 | EGL context，表面经 graphical-window 域（OWB/XComponent） |
+| 立即模式几何 | 顶点缓冲 + shader，attribute 挂应用 program |
+| 立即模式文字 | 字体数据（顶点条带/1bpp 字形）+ shader 渲染，见 `02-imm-mode-font-menu.md` |
+| GLUT 菜单 | 帧缓冲覆盖层（swap 钩子前画入当前窗口），见 `02-imm-mode-font-menu.md` |
+| glColor / glRasterPos | 内部 uniform 颜色 + per-window 光标（每次 swap 重置） |
+| GLU | gl4es 路线：Mesa GLU 交叉编译（见 `03-glu-cross-compile.md`）；纯 GLES 路线裁剪声明，quadrics 可自写、细分用库内建回退 |
+| 显示列表 | gl4es 路线：翻译层承接；纯 GLES 路线裁剪声明 |
+| **多窗区域隔离**（子窗/平铺） | 共享 surface 上 per-window viewport+scissor 裁剪，见 `02-imm-mode-font-menu.md` |
+
+## 坐标契约（跨 API 迁移先读）
+
+GL/GLES/窗口之间有三套坐标系统，边界上的转换必须显式声明一次且仅一次：
+
+1. **窗口顶部原点 ↔ GL 底部原点**（Y 翻转）：窗口事件/参数以顶部为原点（resize、cursor），GL 光栅化以底部为原点；跨此边界必须翻转一次。调用方传入 GL 库/后端的坐标如已是 GL 原点，库内不得再翻转（否则二次翻转＝镜像）。**凡出现 `win_h - y` 的位置必须确认谁调用谁，确保翻转只在一边发生。**
+
+2. **GL 像素坐标 ↔ NDC**（`pos/wh*2-1`）：GLES shader 接收 NDC（-1..1），顶点数据需经 `pos/wh*2-1` 映射。**u_wh uniform 必须与帧缓冲实际像素宽高一致**，不能取窗口请求值（窗口异步 resize 后可能不同步）。
+
+3. **断言读回区必须锚定实际输出坐标系**：`glReadPixels` 以底部为原点，断言用的区域坐标必须匹配此坐标系。用请求窗口尺寸计算读回点可能导致「大图形命中、小图形落空」的幻影——应以 `eglQuerySurface(EGL_DRAW)` 实际宽高为准。
+
+**验证锚定**：迁移后先画一个已知位置/形状，读回中心与角点像素验证落点，不只验有像素。
+
+## 可行性影响
+
+- 命中本域的库编得出 `.so`，但立即模式功能面不可用（partial）。上游 GLES 构建已 stub 的功能面，属"上游既定裁剪"，不按适配失败计。
+- 有本域配方时工作量已知：文字渲染约 860 行、菜单覆盖层约 300 行、上下文走 EGL 近乎零改（上游 egl 路径现成）——**known-cost adaptable**。
+- 仍须裁剪声明（纯 GLES 路线）：显示列表、硬件 overlay 层；GLU 在 gl4es 路线下可用（见 `03-glu-cross-compile.md`），纯 GLES 路线仍裁剪。
+- 与 graphical-window 域的分工：窗口、表面、事件归 graphical-window；GL 语义层（上下文版本、立即模式、文字、菜单渲染）归本域。两域常同时命中。
+
+## ⚠ 宿主验证载体的 .so 加载约束（6.1.1.135 起 XComponent libraryname）
+
+**结论（freeglut 2026-09-17 实验实证，HAD-W32/6.1.1.135）**：XComponent `libraryname` 加载的宿主 .so（如 `lib<demo>.so`），其 NEEDED 链**只能含系统库 + OWB**；**不允许指向 HAP libs 内另一枚共享库**（如 `libfreeglut-gles.so.3`）。存在这种共享链时，整个 dlopen 静默失败——零日志、worker 线程不创建、app 空转存活。
+
+对照实验（每步都在 6.1.1.135 真机验证）：
+
+| 配置 | 结果 |
+|------|------|
+| 共享链 `demo.so → libfreeglut-gles.so.3` + RUNPATH(Windows 绝对路径) | ❌ 不加载 |
+| 共享链 + `CMAKE_SKIP_RPATH`（去掉 RUNPATH） | ❌ 仍不加载 |
+| **静态链** `libfreeglut-gles.a` 编进 demo.so（无共享链） | ✅ 加载成功，FGD 日志出现 |
+
+隔离结论：
+- ❌ **不是 RUNPATH**：去掉后仍失败
+- ❌ **不是 libGLESv2 soname**（E167）：修链 GLESv3 后仍失败；设备确实无 libGLESv2.so，但那是另一层独立问题
+- ✅ **是共享 NEEDED 链本身**：只要 demo.so 依赖 HAP libs 内另一枚共享库，6.1.1.135 的 XComponent 加载器就解析不了
+
+**对适配的要求**：GL/渲染库做宿主上屏 demo 时，优先把被验证库**静态链接进宿主壳 .so**（glfw-triangle 形态：`libglfw3.a` 静态编入 `libglfw_demo.so`），不要做成 demo.so → 库.so 的两层共享链。若必须共享部署，宿主壳 .so 与库 .so 的 SONAME 解析路径要在设备上实测确认（当前已知 6.1.1.135 不可用）。
+
+**相关**：错误图谱 E167（libGLESv2 缺失，另一层独立问题）。
+
+## 判定要点（scan 阶段）
+
+- 识别立即模式依赖：源码里出现 `glRasterPos`/`glBitmap`/`glBegin`+文字、`glColor4f`、`glOrtho`+覆盖绘制、`glu*.h`、显示列表 API；判定 `gl-rendering=partial`。
+- 文字、菜单子面按本域配方给 known-cost 提级，replacement 写明场景化方案文件，不再 scope_out。
+- **GLU 依赖**：走 gl4es 路线时按方案 A 处理（`03-glu-cross-compile.md`）；纯 GLES 路线才 scope_out。
+- evidence 必须来自生产代码（file:line），指向立即模式调用处与上下文创建处。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gl-rendering/01-route-gles-vs-gl4es.md

@@ -0,0 +1,80 @@
+# GL 渲染能力域：路线决策（纯 GLES vs gl4es）
+
+命中 gl-rendering 域的库有两条路线可选：**纯 GLES 路线**（不引入 gl4es）与 **gl4es 翻译层路线**。选错路线的适配几乎不会成功——gl4es 的 INIT_ARRAY 构造函数在 OHOS app 域加载时 SIGSEGV（E100），且 gl4es 冷启动有非确定性挂起（E101）。以下判据用于在 scan 阶段做对选择。
+
+## 关键事实：鸿蒙只有 EGL + OpenGL ES 2.0/3.x
+
+上游的 GLX/WGL 路径、`glBitmap`/`glRasterPos` 光栅操作、`glBegin`、固定管线、矩阵栈、显示列表在**纯 GLES 路线**下全部不存在；**gl4es 翻译层路线**下这些由翻译层承接。两条路线按下方『路线决策判据』选择，**不得按库的宿主形态默认选择**。上游 GLES 构建若已整体 stub（如 freeglut 的 `gles_stubs.c`），属上游既定裁剪而非适配失败。
+
+## 关键事实：OHOS PC 镜像自带双 GL/EGL 栈，选择开关是 app 级 `NEED_OPENGL`
+
+- 两套栈：① 闭源 Maleoon GLES（`glGetString(GL_VERSION)` 报 `"OpenGL ES 3.2 B289"`，**默认**）；② Mesa 25.0.1（Zink over Vulkan，Vulkan 设备即 Maleoon 916，报 `"OpenGL ES 3.2 Mesa 25.0.1 (git-…)"`）。Mesa 栈是镜像组件不是外挂：`/system/lib64/libEGL_mesa.so` 与系统 `libEGL.so` 同批打包，经 `libvulkan.so` → Zink → Maleoon Vulkan ICD。
+- 切换方式：载体 `AppScope/app.json5` → `"appEnvironments": [{"name":"NEED_OPENGL","value":"1"}]`。**无任何系统设置或 hilog 提示当前用的哪套栈**——必须在代码里独立 tag 打 `glGetString(GL_VERSION/GL_RENDERER)` 留证。
+- 构建系统门槛：hvigor 在 `compileSdkVersion` < 6.x 时**静默丢弃** appEnvironments——必须 `compileSdkVersion: "6.1.1(24)"`；`compatibleSdkVersion` 保持 `"5.0.0(12)"`，否则 minAPIVersion 升为 60101024 装机报 `error 9568297`。**验收必须解包 HAP 读 module.json 确认 appEnvironments 非空**。
+- 选栈判据（freeglut 载体实测）：B289 栈在本载体 OWB/XComponent→EGL 调用方式下**呈现链不通**（eglSwapBuffers 返回成功、合成器收全零帧=纯黑屏）；Mesa 栈同代码路径正常呈现。遇到上屏黑屏，第一差分动作就是切 `NEED_OPENGL` 重装对照，再谈别的归因。
+- 别人设备有没有 Mesa 栈，一分钟探测：`grep -c NEED_OPENGL /system/lib64/libEGL.so`（≥1=开关在）+ `ls /system/lib64/libEGL_mesa.so`（在=栈在）。镜像版本依赖：6.x PC 镜像才有。
+- 设备型号以 `param get const.product.software.version` 为准。
+
+## 关键事实：GLES soname 构建期 ≠ 运行期（freeglut 2026-09-17 实测，HAD-W32/6.1.1.135）
+
+NDK sysroot 有 `libGLESv2.so`（链接桩），但设备 `/system/lib64` **只有 `libGLESv3.so`，无 `libGLESv2.so`**（6.1.1.135 起移除）。后果：构建期 `FIND_LIBRARY(GLES2_LIBRARY NAMES GLESv2 GLESv3)` 会优先找到 sysroot 的 GLESv2 并写入 NEEDED → 设备 `dlopen(lib<demo>.so)` 解析 `libfreeglut-gles.so` → 再解析 `libGLESv2.so` 找不到 → **整条链静默丢弃**（XComponent libraryname 不报任何找不到库的日志，只见 app 活着、零原生日志、worker 线程未创建）。
+
+修复要点：
+- OHOS 分支固定链 `GLESv3`（GLESv3 向后兼容 ES2 API），或 `FIND_LIBRARY(GLES2_LIBRARY NAMES GLESv3 GLESv2)` 让 GLESv3 优先。
+- 旧版 .so 同时 NEEDED `libGLESv2.so`+`libGLESv3.so`（老设备有 GLESv2），故兼容旧设备；新设备只给 GLESv3，必须对齐。
+- 差分判定：`hdc file recv /system/lib64/libGLESv2.so <out>` 报 `no such file or directory` = 设备无此库；`llvm-readelf -d lib*.so` 看 NEEDED 有没有 `libGLESv2.so`。
+- 设备侧判定参考错误图谱 E167。
+
+## 路线决策判据（scan 阶段必查）
+
+### 判据 1（一票否决）：上游自带 GLES 构建选项
+
+```
+IF 库的构建系统（CMakeLists.txt / configure / meson）提供 GLES 构建选项或 EGL 后端路径
+  → 强制走纯 GLES 路线
+  → gl4es 不允许加入 library_dependencies（连 optional 都不列）
+  → 因为此类库的上游 GLES 路径已处理了上下文创建和 API 子集差异，
+    gl4es 的 INIT_ARRAY 构造在 app 域必定崩溃，没有例外。
+```
+
+**正例（自己就是 GL 抽象层）：** freeglut（`FREEGLUT_GLES=ON` + `src/egl/`）、GLFW（`GLFW_USE_EGL=ON` + OWB 后端）、SDL（`SDL_VIDEO_DRIVER_EGL=ON`）。这类库不论源码里用了多少桌面 GL API，都不应走 gl4es——它们自身就是 GL 抽象层。
+
+**反例验证（freeglut 2026-09-14 实证）：** 同一设备 HAD-W32，gl4es 路线 0/24 失败（E100+E101），纯 GLES 路线 37/37 全过。
+
+### 判据 2（必须走 gl4es）：纯桌面 GL 库，无 GLES 构建路径
+
+```
+IF 库仅提供桌面 GL 构建路径（GLX/WGL），源码大量使用固定管线
+  （glBegin/glEnd/glRasterPos/glBitmap/glNewList/glu*），
+  且上游无 GLES/EGL 构建选项
+  → 必须走 gl4es 翻译层路线
+  → library_dependencies 列 gl4es（scope=runtime）
+  → adapt 阶段须处理 gl4es bootstrap（NOEGL+NO_INIT_CONSTRUCTOR 形态）、
+    EGL 头守卫（EGL_NO_X11=1 EGL_NO_PLATFORM_SPECIFIC_TYPES=1）、
+    NEED_OPENGL=1 切 Mesa 栈
+  → 验证体优先用真窗口表面（Coin 案实证 gl-rendering-lib-host）
+```
+
+**正例：** Coin3D（无 GLES 构建选项，200+ 桌面 GL 调用，GLU NURBS 依赖）。
+
+### 判据 3（自行判断）：既有 GLES 路径又用桌面 GL 专用 API
+
+```
+IF 库有 GLES 构建选项但源码中混合使用 GLES3 API 和桌面 GL 专用 API
+  且桌面 GL API 用量少（<10 处）可通过 GLES2 等价替换或 shim 覆盖
+  → 优先纯 GLES 路线 + 针对桌面 GL API 逐一 patch
+  → 仅在桌面 GL API 过于密集时才考虑 gl4es
+```
+
+### 判据速查表
+
+| 场景 | 路线 | gl4es | 典型库 |
+|------|------|-------|--------|
+| 库自身是 GL 抽象层（有 EGL/GLES 构建选项） | 纯 GLES | 禁止 | freeglut、GLFW、SDL |
+| 纯桌面 GL 库，无 GLES 路径 | gl4es | 必须 | Coin3D、OSG（无 EGL 时） |
+| 混合使用，少量桌面 GL API | 纯 GLES + patch | 不引入 | 个别绑骨骼引擎 |
+| 库依赖 GLU（libGLU） | 取决于宿主路线 | — | GLU 本身是纯数据 C 库，不驱动路线选择 |
+
+## 注册复用的边界
+
+gl4es 虽然已在 registry 登记为 reuse，**仅对判据 2（必须走 gl4es）的库开放复用**。对判据 1 的库，gl4es 不得列进 library_dependencies，registry 命中也应跳过。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-capability-domains/references/capability-domains/gl-rendering/02-imm-mode-font-menu.md

@@ -0,0 +1,47 @@
+# GL 渲染能力域：立即模式文字与菜单的 shader 重实现
+
+真机验证过的配方（2026-09 在 HAD-W24 上实现，名册 29/29 全通过、含逐字形像素断言；实现规模：字体渲染约 860 行、菜单覆盖层约 300 行——规模即工作量锚点）。
+
+## 轮廓字体
+
+字体数据天然按条带拆分（如 `SFG_StrokeChar.Strips[]`，'B' 3 条带、'O' 1 条带），逐条带独立 `glDrawArrays(GL_LINE_STRIP)`；把全部顶点并成一个 VBO 会让内外轮廓错误连线。字符推进与换行用内部 2D 光标替代 `glTranslatef`。
+
+## 位图字体
+
+1bpp 字形（MSB-first、行按字节补齐）一次性解码为 POT 尺寸图集（256×512，shelf packing），字形画两三角形纹理 quad；fragment shader 对未置位像素 `discard`，等价 glBitmap 位掩码语义且不触碰 blend 状态。
+
+**纹理格式注意**：
+- `GL_ALPHA` 采样 `.r` 恒为 0——用 `GL_LUMINANCE` 配 `.r`，或 `GL_R8`（ES 3+）配 `.r`。各 GLES 版本/驱动对单通道格式支持不一致，**务必按运行上下文实测采样值**，不能想当然。
+- 上传时 `GL_UNPACK_ALIGNMENT` 置 1 并保存恢复。
+- 图集打包时 rowbytes 必须逐字形计算 `ceil(w/8)`（比例字体各字宽不同，不能用首字形推导）。
+- 光标语义 = glBitmap 基线（字形图像行 `#font->yorig` 对齐光标、像素向上延伸、推进量 `face[0]`）。
+
+## 绘制通路硬约束（Maleoon/Zink 实测，违反即静默不出片、无 GL 错误）
+
+1. **位置 attribute 绑 location ≥1**，不能用 0（attrib 0 的绘制不产生任何 fragment）。
+2. 顶点流必须经 **VBO**（`glBufferData` 上传后以 offset 0 挂 attribute），client 内存指针数组同样静默无像素。
+3. 字体 ID 判断用宏地址 `font == GLUT_BITMAP_9_BY_15`（即 `&glutBitmap9By15`），误传变量值会匹配失败静默返回。
+
+## 度量函数
+
+`Width/Height/Length` 是纯数据读取，与绘制分离、无条件编译；字体对象（`glutStrokeRoman` 等）须在库里定义并指向真实内嵌数据，否则应用引用 `GLUT_STROKE_ROMAN` 类宏即链接失败。
+
+## 菜单覆盖层
+
+菜单窗口降级为无上下文逻辑对象（平台 OpenWindow 对 IsMenu 提前返回，不等表面、不抢 surface ownership、不开 WorkMask，菜单可先于首窗口创建）；渲染挂 swap 钩子，`eglSwapBuffers` 前把菜单框、高亮条、子菜单箭头（实心三角形）与标签文字画入当前帧缓冲；**桌面顶向下菜单坐标统一转换为 GL 窗口坐标（`y_gl = win_h - y_topdown`）——坐标转换只在此处发生一次，见 `00-overview.md` 坐标契约**；鼠标 DOWN/UP 先过菜单（菜单吞事件不达应用回调）、MOVE 走高亮更新，与桌面后端同款。
+
+## 状态卫生
+
+库内部自有 program 绘制时保存恢复 current program、ARRAY_BUFFER 绑定、active texture、unit0 纹理绑定、attrib 使能、cull face、UNPACK_ALIGNMENT；uniform 是 per-program 状态不互扰；GLES 无矩阵栈，无矩阵状态可破坏。多逻辑窗口各有 EGL context，GL 对象按 `eglGetCurrentContext()` 比对懒重建，close 时仅 context current 才真删。
+
+## 内部 program 提前初始化 + priming 帧
+
+在应用 program 已使用之后再惰性编译库的第二段 program，会使后续所有批量 draw/clear（含应用几何）静默无 fragment（Zink/Maleoon pipeline-cache 时序怪癖）。修法：窗口创建（InitWork）时即初始化全部内部 program/纹理，并渲染一帧 priming（真实画一个字 + `glReadPixels(1×1)`）强制驱动完全实例化渲染目标；初始化时同时预建全部字体图集。
+
+## 区域裁剪兜底与刷新时机
+
+apply-region 裁剪后若 w/h≤0，绝不能保留 0×0 viewport/scissor（0 尺寸 scissor 盒使该上下文后续一切 draw **和 clear** 静默失效），必须回退全画幅；`glutSetWindow` 对已是当前窗口的调用会 early-return 跳过 make-current，区域/状态刷新不能只挂在 make-current 上，需在主循环泵末尾对 current window 补一次 apply-region。
+
+## 子窗区域隔离
+
+共享 surface 上每个窗口有独立矩形区域，子窗绘制与清屏经 viewport+scissor 硬裁剪到该矩形。子窗 State（Xpos/Ypos/W/H）必须在创建时立即写入（calloc 零初始化后无其他写入源），区域计算依赖它。子窗切换由平台 setwindow 触发 apply-region（viewport+scissor 同步设为子窗矩形，GLUT 顶向下 Y 转换为 GL 底向上 `y_gl = sh - y_topdown - h`）。顶层窗口不裁剪——顶层 State 几何驱动宿主异步缩放（WOP_SIZE），与 GL 层裁剪形成反馈环。