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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L060.md

@@ -0,0 +1,83 @@
+<!-- 来源：fontmoa（Electron 字体管理器）鸿蒙 PC 适配（HAD-W32 / Electron-OH v34.8.5 / aarch64 真机实证 2026-10-19）| 证据链：主进程 readdir('/system/fonts')=263 成功 vs 渲染进程 stat 字体文件 EACCES（renderer console[3] Uncaught Error）→ 主进程拷贝系统字体到沙箱 userData/fonts → 渲染层扫沙箱 259 字体入库 + 搜索 HarmonyOS 命中
+evidence_level: E3
+summary_plain: Electron-OH 渲染进程（Chromium renderer 子进程）对系统分区文件（/system/fonts 等）stat/read 报 EACCES（readdir 可列目录、stat 文件被拒），主进程（app 域主进程）同路径可读——渲染进程沙箱更严（子进程 mount namespace 不完整 + SELinux 域限制）。统一修法=主进程拷贝系统资源到沙箱 userData/ 下（渲染层同 uid 可读），渲染层扫沙箱副本；纯 ArkTS 原生应用无主/渲染进程二分（单 app 域进程），不适用此差异。
+trigger: renderer console Uncaught EACCES, stat 系统路径, /system/fonts, 渲染进程读系统目录, 系统字体, readdir 能列 stat 失败, Chromium renderer 沙箱, 主进程可读渲染进程不可读, 系统资源拷贝沙箱
+verify: 渲染层扫描改指向沙箱拷贝目录后，fontkit 解析入库成功（font.data 非空）、界面搜索系统字体命中；hilog 不再出现渲染层 stat EACCES
+status: active -->
+一句话定位：Electron-OH 的**渲染进程（Chromium renderer 子进程）**与**主进程（app 域主进程）**对系统分区（`/system/fonts`）的读权限不同——**主进程能 readdir 263 个字体，渲染进程 stat 单个字体文件 EACCES**（readdir 可列目录、stat 被拒）→ 渲染层扫描中断、入库 0 条、UI 列表空；**纯 ArkTS 原生应用无主/渲染二分，不适用**。
+
+# L060: Electron-OH 渲染进程对系统分区文件 stat/read EACCES——主进程可读、渲染进程被拒（Chromium 子进程沙箱）
+
+> **严重度**: 3 blocking（功能静默失效：渲染层扫描系统资源全断） | **领域**: electron-oh / 沙箱权限 / 渲染进程 | **自动修复**: 主进程拷贝系统资源到沙箱 → 渲染层扫沙箱副本
+
+---
+
+## 问题现象
+
+Electron 应用渲染层直接 `fs` 访问**系统分区路径**（`/system/fonts`、`/vendor` 等）时：
+
+```
+renderer console[3]: Uncaught Error: EACCES: permission denied, stat '/system/fonts/Roboto-Regular.ttf'
+```
+
+特征：
+1. **`fs.readdirSync('/system/fonts')` 成功**（拿到全部 263 个文件名）——目录本身 755 可读；
+2. **`fs.statSync('/system/fonts/xxx.ttf')` EACCES**——文件元数据读取被拒（同步 stat 不吞错，当场抛未捕获异常 → 扫描中断、后续 fontkit 解析/入库全不执行）；
+3. **同一路径主进程（main.js）完全可读**（readdir 263 实证）；
+4. 表现：渲染层系统资源扫描静默失效、库空、UI 列表空——无崩溃、无其他报错，极难定位。
+
+## 根因
+
+| # | 误诊（排除过） | 真根因 |
+|---|---|---|
+| 1 | 「系统字体目录鸿蒙不存在」 | 不成立：`/system/fonts` 存在（263 字体 / 497MB / 755 + SELinux `system_fonts_file`）；主进程可读 |
+| 2 | 「应用沙箱读不了系统路径」 | 不成立：主进程（同 app 域 uid）readdir 263 成功 |
+| 3 | **渲染进程与主进程的沙箱不一致** | **渲染进程运行在 Chromium 沙箱中**，对系统目录的 `stat`/`open` 等文件系统系统调用被**沙箱策略拒绝（EACCES）**；**主进程不在 Chromium 沙箱内**，拥有完整 Node.js API 与应用沙箱权限 → 可读 `/system/fonts`（鸿蒙官方口径，2026-10）。辅助观察：渲染进程 APPSPAWN 子进程 mount 配置部分失败（`private mount ... errno 13`）与 SELinux 子进程域限制，与官方口径同向 |
+
+机制细节：
+- **主进程**：**不在 Chromium 沙箱内**——拥有完整 Node.js API 与应用沙箱权限，系统目录 `stat`/`open` 系统调用放行（鸿蒙官方口径，2026-10）；辅助观察：挂载完整、SELinux 域含系统字体读规则；
+- **渲染进程**：**运行在 Chromium 沙箱中**——对系统目录的 `stat`/`open` 等文件系统系统调用被**沙箱策略拒绝（EACCES）**（鸿蒙官方口径）；辅助观察：Electron fork 的 Chromium 子进程（`--type=renderer`）APPSPAWN 重新沙箱初始化时部分 private mount 失败（`/system/variant`、`storage/External` 等），与官方口径同向；
+- **readdir vs stat 的分裂**：目录的「列条目」放行（755 + dir search），文件的「读元数据/内容」被 Chromium 沙箱策略拒绝——「看得见目录条目、摸不到文件本体」；
+- **纯 ArkTS 原生应用不适用**：无主/渲染进程二分，整个应用是单一 app 域进程（UIAbility 同进程、ArkUI 渲染同进程），系统资源权限由该进程的 SELinux 域决定，不存在「子进程更严」这层。
+
+## 判别方法
+
+1. **主/渲染对照**：同一路径主进程 `readdirSync` 成功、渲染层 `statSync` EACCES → 命中本条；
+2. **readdir 通 + stat 断**：目录可列、文件元数据被拒，是子进程沙箱/SELinux 域的特征（区别于「整个路径不可见」）；
+3. 渲染层 hilog 特征：`renderer console[3]: Uncaught Error: EACCES: permission denied, stat '<系统路径>'`；
+4. 进程模型澄清：确认目标是 **Electron-OH**（有 renderer 子进程）而非纯 ArkTS（无此二分）。
+
+## 解决方案
+
+**统一修法 = 官方 IPC 方案**（鸿蒙官方推荐：主进程 `ipcMain.handle` 提供系统资源信息，渲染层 `ipcRenderer.invoke` 获取——渲染进程不在沙箱外读文件）：
+
+```
+主进程（不在 Chromium 沙箱内，可读系统分区）
+  ├─ ipcMain.handle('get-system-fonts', ...)        → 渲染层 invoke 拿字体列表
+  ├─ ipcMain.handle('get-system-font-file', ...)    → 渲染层 invoke 拿文件 Buffer（fontkit.create 解析/预览）
+  └─ ipcMain.handle('get-platform', ...)            → 渲染层 invoke 拿 process.platform（平台判定）
+渲染层（Chromium 沙箱，不直接碰系统文件）→ 经 platformBridge.getSystemFonts()/getSystemFontFile() 获取
+```
+
+落地要点（fontmoa 实证 2026-10-19）：
+1. **主进程**：`ipcMain.handle` 三件套——`get-system-fonts`（readdir + 扩展名过滤返回列表）、`get-system-font-file`（校验路径前缀 `/system/fonts/` 后 `readFileSync` 返回 Buffer）、`get-platform`（返回 `process.platform`——主进程判定可靠）；
+2. **渲染层**：平台桥封装 `getSystemFonts()`/`getSystemFontFile()`（isOHOS 分支走 `ipcRenderer.invoke`，非鸿蒙保持原路径）；`fontkit.create(Buffer)` 解析（IPC 传输的 Buffer 可能被序列化成 `{type:'Buffer',data:[...]}` 普通对象——渲染层统一 `Buffer.isBuffer(raw) ? raw : Buffer.from(raw.data||raw)` 转回）；
+3. **数据模型差异**：`fontkit.create(Buffer)` 返回的 font 与 `fontkit.open` 结构有差异（`subfamilyName` 可能非字符串、`name.records` 部分键缺失）——入库代码加类型保护（`String(subfamilyName)`、`records[key]` 判空）；
+4. **个别文件仍 EACCES**：部分系统字体文件（如 Roboto-Regular.ttf）对 app 域也 EACCES（readFileSync open 被拒）——createFont 跳过不致命（其余字体正常入库）；
+5. **首次入库慢**：259 个 ×（IPC 拉 Buffer + fontkit.create）≈ 每个 2~3 秒，全量约 9 分钟——列表陆续填充，可接受；空结果时延迟重扫兜底。
+
+**备选（预览等渲染层需直接读文件场景）**：主进程按需拷贝单个文件到沙箱并返回沙箱路径（只拷被预览的，不做全量拷贝）——全量拷贝沙箱是过度方案（占 497MB 且系统字体变可写副本），仅在渲染层必须直接读文件（@font-face 等）时按需使用。
+
+## 影响范围
+
+所有 `delivery_form=app` 的 Electron-OH 应用，凡**渲染层直接 fs 访问系统分区**（系统字体目录、系统配置、/vendor 资源等）——主进程能读、渲染进程 EACCES。**纯 ArkTS 原生应用不受此限**（无渲染进程子域）。触发关键词：系统字体枚举、系统目录扫描、渲染层读只读系统资源。
+
+## 关联
+
+- `pc-knowledge-base/electron/electron.md`（宿主机制；硬约束「渲染进程系统目录权限」）
+- `pc-knowledge-base/platform/鸿蒙PC-应用沙箱与物理路径映射.md`（沙箱路径↔物理路径；渲染进程挂载差异佐证）
+- 同族既有条目：L064（主→渲染 IPC 回传缺口）——同属「Electron-OH 渲染进程与主进程语义不一致」族；本条目是「文件系统权限」分支
+
+## 实证
+
+fontmoa（Electron 字体管理器，Electron-OH v34.8.5 / HAD-W32 / aarch64，2026-10-19）：主进程 `readdirSync('/system/fonts')` 263 个字体成功（含 HarmonyOS_Sans.ttf 等）；渲染层直接扫描 `statSync` 报 `EACCES: permission denied, stat '/system/fonts/Roboto-Regular.ttf'`（renderer console[3] Uncaught）→ 扫描中断、nedb font.data 0 条、UI 搜 HarmonyOS 为空。按官方 IPC 方案修复：主进程 `get-system-fonts`（返回 260 列表）+ `get-system-font-file`（Buffer）+ 渲染层 `fontkit.create(Buffer)` 解析入库（Buffer 反序列化 + subfamilyName/getLanguage 类型保护）→ `get-system-fonts returns 260`、渲染层 `sys-fonts ipc got 260`、逐个解析入库、界面搜 HarmonyOS 命中。个别文件（Roboto-Regular.ttf）主进程 `readFileSync` 也 EACCES——createFont 跳过不致命。Windows 桌面版（进程模型不同）无此问题——平台差异确认。中间探索过的「主进程全量拷贝到沙箱」（497MB）方案能通但不正统（占沙箱、系统字体变可写副本），已被官方 IPC 方案替代。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L061.md

@@ -0,0 +1,69 @@
+<!-- 来源：beekeeper-studio 1.0.0（Electron-OH v37.2.3）与 fontmoa 1.0.10（Electron-OH v34.8.5）鸿蒙 PC 适配（HAD-W32 / aarch64 真机实证 2026-10-17~19）| 证据链：同一 HAP 反复冷启动，主进程日志停在 new BrowserWindow 探针后（wb window-created 缺失）、WMS 层窗口已建（OhosWindow::AddWindow 成功）但 JS 构造不返回、Renderer 不启动；force-stop + 重启 1~3 次即过
+evidence_level: E3
+summary_plain: Electron-OH 的 new BrowserWindow 同步构造偶发永不返回（窗口系统竞态）：WMS 层窗口已创建、JS 构造函数卡死、后续页面加载与 Renderer 启动全停、进程存活但界面出不来；同一 HAP 多启动 1/3 成功率，force-stop + aa start 重启重试可过。引擎层竞态（v34/v37 双版本实证），非应用代码问题，改窗口参数/调用方式无效。
+trigger: new BrowserWindow 卡死, 窗口创建不出来, window built 缺失, Renderer 不启动, 进程活着窗口不出现, 启动偶发白屏无窗口, Electron 窗口竞态, wb before-new-window 后无 window-created
+verify: force-stop + aa start 重启 1~3 次后窗口正常创建（window built 日志出现、Renderer 子进程启动、页面可加载）；同 HAP 多次重启成功率 ~1/3 即命中引擎竞态（非应用逻辑）
+status: active -->
+一句话定位：Electron-OH 的 **`new BrowserWindow(...)` 同步构造偶发永不返回**——窗口系统竞态（WMS 层窗口已建、JS 构造函数等确认信号永远等不到）→ 后续页面加载/Renderer 启动全停、进程活着但界面出不来；**引擎层偶发 bug（v34/v37 双版本实证），force-stop + 重启重试即可**，不是应用代码问题。
+
+# L061: Electron-OH new BrowserWindow 偶发卡死——窗口系统竞态（进程活着但界面出不来）
+
+> **严重度**: 2 medium（启动偶发失败，重启可恢复；非数据/功能损坏） | **领域**: electron-oh / 窗口创建 / 引擎竞态 | **自动修复**: force-stop + `aa start` 重启重试（成功率 ~1/3，1~3 次必过）
+
+---
+
+## 问题现象
+
+应用冷启动时主进程执行到 `new BrowserWindow(...)`，**该行偶发永远执行不完**：
+
+```
+[MAIN] BKSRENDERER: wb before-new-window   ← 探针 A（new 之前）出现
+（无） BKSRENDERER: wb window-created       ← 探针 B（new 之后）缺失 → 卡在 new BrowserWindow 内部
+```
+
+特征：
+1. **进程存活**（pgrep 有主进程 + GPU/NetworkService，**无 Renderer**）；
+2. **WMS 层窗口已创建**（`OhosWindow::AddWindow` / `Get surface id` / `OnWindowSizeChange` 都出现）——系统视角窗口在，JS 视角构造不返回；
+3. 后续 `window built/created` 日志缺失、`loadURL` 未触发、**Renderer 子进程不启动**；
+4. **同一 HAP 反复启动，成功率 ~1/3**（约 3 次成功 1 次）——代码没变、行为随机；
+5. **换应用同样复现**（beekeeper v37.2.3、fontmoa v34.8.5 都卡）——跨应用、跨版本共性。
+
+## 根因
+
+**Electron-OH 引擎层的窗口创建竞态**（race condition）：`new BrowserWindow` 同步构造内部要等 OHOS 窗口系统（WMS）确认窗口就绪，**确认信号偶发丢失/晚到** → 构造函数永久挂起。
+
+| 误诊 | 排除依据 |
+|---|---|
+| 「应用窗口参数/代码问题」 | 不成立：同一 HAP 多启动 1/3 成功率（代码没变行为变）；改窗口参数（frame/titleBarStyle/webPreferences）无效；两个无关应用（beekeeper/fontmoa）同复现 |
+| 「设备卡顿/资源不足」 | 不成立：重启后立即成功；卡死时系统日志正常无资源告警 |
+| 「hilog 日志太多」 | 部分放大因素：hilog D 级/应用 logLevel=debug 的 stdout 背压会**显著放大**触发概率（几乎必卡，见 pc-device-verify 取证纪律 L 关联）；hilog W 级时回到 ~1/3 基线 |
+
+## 判别方法
+
+1. 主进程日志停在 `new BrowserWindow` 探针后（`wb before-new-window` 出现、`wb window-created` 缺失）；
+2. WMS 日志显示窗口已建（`OhosWindow::AddWindow`）但 Renderer 不启动；
+3. **force-stop + 重启 1~3 次能过** → 引擎竞态实锤（应用逻辑问题不会「重启就偶尔好」）。
+
+## 解决方案
+
+1. **force-stop + `aa start` 重启重试**（1~3 次内成功）——引擎层竞态，应用侧唯一处置；
+2. **取证时给 `new BrowserWindow` 前后各加一条 warn 探针**（`wb before-new-window` / `wb window-created`）——区分「卡在 new 内部」vs「后续逻辑问题」，避免误诊；
+3. **hilog 保持 W 级**（不要 `hilog -b D` 长时间取证）——D 级背压会把 ~1/3 成功率压到「几乎必卡」，掩盖真实基线；
+4. 启动失败重试逻辑（应用侧可选）：主进程监听窗口创建超时 → 自动 force-stop 重启（对用户透明）。
+
+## 影响范围
+
+Electron-OH 应用冷启动，**部分环境/设备/系统负载下偶发**（beekeeper v37.2.3 与 fontmoa v34.8.5
+真机实证；是否所有应用普遍触发**未经证实**——其他案例验证时重启重试即过、失败过程不落产物，
+可能被掩盖）。**引擎层问题，应用无法规避，只能重试**；配合 #4（hilog 背压）取证纪律把成功率
+拉回基线。触发频率观察：hilog D 级/应用 logLevel=debug 几乎必卡，hilog W 级回到 ~1/3。
+
+## 关联
+
+- `pc-knowledge-base/electron/electron.md`（启动排查清单；硬约束 #22 同属 Electron-OH 引擎层差异族）
+- `pc-device-verify`（取证纪律：hilog 级别背压放大、warn 探针锚点）
+- 同族既有条目：L063（多窗口实例启动失败）——同属「窗口/实例」启动失败族；本条是**单窗口首次创建**的引擎竞态
+
+## 实证
+
+beekeeper-studio 1.0.0（Electron-OH v37.2.3 / HAD-W32 / aarch64，2026-10-17）：连续 10+ 次冷启动约 1/5 成功，其余卡在 `new BrowserWindow`（`wb before-new-window` 后无 `window-created`；hilog D 级时连续 5+ 次全卡，降 W 级恢复 ~1/3）。fontmoa 1.0.10（Electron-OH v34.8.5，2026-10-19）：同样卡在 `createWindow enter` 后（`window created id=` 缺失），重启 1~3 次即过。**v34/v37 双版本共性，引擎竞态确认**。Windows 原生 Electron 无此问题——平台差异。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L062.md

@@ -0,0 +1,60 @@
+<!-- 来源：beekeeper-studio 1.0.0 鸿蒙 PC 适配（Electron-OH v37.2.3 / HAD-W32 / aarch64 真机实证 2026-10-17）| 证据链：utility.js 顶层 require('ssh2')（resfile 缺包）→ 主进程同步 require 永久挂起（无 MODULE_NOT_FOUND 抛错、事件循环占死）；内联进 bundle 后越过；resfile 有的 sqlite3 在 utility.js 顶层 require 也卡（函数内/TypeORM 惰性 require 成功）→ 同步 require 链内 require 不稳定
+evidence_level: E3
+summary_plain: Electron-OH 主进程对缺失模块的同步 require 不抛 MODULE_NOT_FOUND 而是永久挂起（事件循环占死、后续逻辑全停）；进一步，即使 resfile 存在的包（如 sqlite3 NAPI .node），在「同步 require 链」顶层（bundle 模块加载时）require 也可能卡，而函数内/异步 require 成功。统一修法：纯 JS 依赖内联进 bundle（esbuild externals 移除）、native 缺失/重依赖惰性化（函数内 require）、构建后校验 resfile 与 externals 清单闭合。
+trigger: require 挂起, require 卡死, MODULE_NOT_FOUND 不抛, 启动 loading 永不结束, resfile 缺包, 顶层 require 卡, in-process utility 初始化卡, 同步 require 链, externals 闭合
+verify: 缺失包内联进 bundle / 顶层 require 惰性化后，require 链越过该点（探针推进）、后续初始化完成、应用可用；构建脚本校验 externals 全闭包无缺失
+status: active -->
+一句话定位：Electron-OH 主进程的同步 `require` 对**缺失模块不抛错而是永久挂起**（`MODULE_NOT_FOUND` 不出现、事件循环占死、后续逻辑全停）；**同步 require 链内 require「存在的包」也可能卡**（函数内/异步 require 正常）。修法 = **纯 JS 内联进 bundle + native 缺失/重依赖惰性化 + resfile 与 externals 闭合校验**。
+
+# L062: Electron-OH 同步 require 缺失模块永久挂起（不抛 MODULE_NOT_FOUND）——内联/惰性化/闭合校验
+
+> **严重度**: 3 blocking（in-process utility 初始化卡死 → 应用启动 loading 永不结束） | **领域**: electron-oh / require 解析 / 依赖供给 | **自动修复**: 纯 JS 依赖内联（esbuild externals 移除）；native 缺失驱动惰性化（函数内 require）；构建校验 externals 闭合
+
+---
+
+## 问题现象
+
+Electron-OH 主进程执行 `require('ssh2')` / `require('cassandra-driver')`（resfile node_modules **没有这些包**）时：
+
+- **同步 require 永久挂起**——不抛 `MODULE_NOT_FOUND`、无任何错误日志、事件循环被占死；
+- 后续所有逻辑（窗口创建、渲染层、in-process utility 初始化）**全部停摆**；
+- 表现：应用启动后**一直 loading / 无响应**（渲染层在等 utility 的 IPC 请求，utility 卡在 require 上永不就绪），hilog 无报错——极难定位。
+
+**进一步（更隐蔽）**：即使 resfile **有**该包（如 `sqlite3` NAPI .node），在**同步 require 链顶层**（bundle 模块加载时，如 utility.js 的 `var x = require("sqlite3")`）也可能卡——而**函数内/异步 require 成功**（主进程 TypeORM 的 `case "sqlite3": return require("sqlite3")` 在 initBasics 时正常加载）。
+
+## 根因
+
+| # | 误诊（排除过） | 真根因 |
+|---|---|---|
+| 1 | 「缺包抛 MODULE_NOT_FOUND，应用没 catch」 | 不成立：正常 Node 会抛错可 catch；Electron-OH 是**挂起**（不抛、不返回、不报错） |
+| 2 | 「bundle 太大解析慢」 | 不成立：29MB bundle 解析推进快（探针显示各模块段快速越过），卡点是具体 require 调用 |
+| 3 | **Electron-OH 模块解析对缺失包挂起** | **沙箱下 require 路径扫描对缺失包不抛错而是挂起**（机制未完全确定：沙箱 fs/锁/扫描死循环，但行为确定性挂起） |
+| 4 | **同步 require 链内 require 不稳定** | 顶层（模块加载链内）require 存在的包（sqlite3 .node）也可能卡；函数内/异步 require 正常——与调用时机/上下文相关 |
+
+## 判别方法
+
+1. **探针二分**：在 require 调用前后加 warn 探针（`require 前` 出现、`require 后` 缺失 = 卡在该 require）；
+2. **对照**：同一包主进程函数内 require 成功、utility.js 顶层 require 卡 → 命中「同步 require 链」问题；
+3. **闭合校验**：列出 esbuild externals 清单 vs resfile node_modules——**缺失项**即嫌疑（缺失必挂）；
+4. 特征：hilog 无 error、无崩溃、进程活着但某条链（utility/初始化）永不就绪 → 优先怀疑 require 挂起。
+
+## 解决方案
+
+1. **纯 JS 依赖内联进 bundle**：esbuild `externals` 移除纯 JS 包（ssh2、cassandra-driver 等）→ 打进 bundle，运行时不再 `require`（beekeeper 实证：内联后越过卡点）；optional native（cpu-features 等）用 resolutions 中和为 empty-package 后再内联；
+2. **native 缺失驱动惰性化**：`@duckdb/node-api`、`sqlanywhere` 等 native 无鸿蒙制品 → 顶层 import 改函数内 `require`（仅运行时用到才触发，启动不卡）；
+3. **构建后校验 externals 闭合**：sync-payload / 组装脚本核对 externals 清单 ⊆ resfile node_modules（缺失项 fail-fast）——缺包必卡，装机前拦住；
+4. **顶层 external require 最少化**：bundle 顶层尽量不留运行时 external require（内联或惰性化），把 require 收敛到函数内。
+
+## 影响范围
+
+一切 Electron-OH 应用，凡**主进程/in-process utility bundle 顶层有运行时 external require**，且**依赖未随 resfile 闭合供给**——缺失必挂（不抛错）。9/29 交付「用户侧一直 loading」的深层根因之一（in-process utility require 链卡死）。**纯 ArkTS 应用不受此限**（无 Node require 机制）。
+
+## 关联
+
+- `pc-knowledge-base/electron/electron.md`（硬约束：运行时 require 缺失挂起——内联/惰性化/闭合校验）
+- `pc-error-atlas` L060（同属「Electron-OH 主进程 vs 渲染进程/沙箱语义差异」族；本条是模块解析分支）
+- 构建工具：`sync-payload`（--local 垫片声明；externals 闭合校验建议挂载组装脚本尾部）
+
+## 实证
+
+beekeeper-studio 1.0.0（Electron-OH v37.2.3 / HAD-W32 / aarch64，2026-10-17）：in-process utility 初始化卡死（渲染层 `$util.send` 排队永不 flush → 启动 loading）。探针二分定位 utility.js 顶层 `require('ssh2')`（resfile 缺）→ 挂起；内联 ssh2 后越过，又卡 `require('cassandra-driver')`（缺）→ 内联后越过，又卡 `require('sqlite3')`（resfile 有，utility.js 顶层也卡）→ 惰性化顶层 external + 主进程预热后链路通。**缺失包挂起 + 同步链内存在包也卡，双重实证**。Windows 原生 Electron（函数内/正常解析）无此问题——平台差异。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L063.md

@@ -0,0 +1,71 @@
+<!-- 来源：drawio-desktop 鸿蒙适配返修（HAD-W32 / OpenHarmony-7.0.0.105 / aarch64 真机实证 2026-10-16）
+evidence_level: E4
+summary_plain: Electron-OH 应用内多窗口（第二次 new BrowserWindow = 新 UIAbility 实例）启动失败——模板默认用 ATTACH_TO_STATUS_BAR_ITEM + startupVisibility 启动新实例，该模式要求调用方先向状态栏添加 item（托盘）；无托盘应用前置不满足，系统 16000067 拒绝，新窗口永不出现。
+trigger: 16000067, ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED, ATTACH_TO_STATUS_BAR_ITEM, 新建窗口无反应, CreateWindow wait timeout, LaunchHelper startAbility failed
+verify: 无托盘应用把 AppWindowAdapter.createWindow 的 StartOptions 成对删除 processMode 与 startupVisibility 后，应用内新建窗口能出现并加载；只删其一仍报 16000067 即未修到位。
+status: active -->
+一句话定位：Electron-OH 多窗口实例（应用内第二次及以上 `new BrowserWindow()` = 启动新 UIAbility 实例）默认经 `ProcessMode.ATTACH_TO_STATUS_BAR_ITEM` + `startupVisibility` 启动——该模式把 **Ability 进程附加到状态栏 item**（前置：调用方已添加状态栏 item、与调用方同 bundle），`startupVisibility` 与之**成对校验**；无托盘应用前置不满足 → **16000067（VISIBILITY_SETTING_DISABLED）** 拒绝 → 新实例永不创建 → 新建窗口无声失效。
+
+# L063: Electron-OH 多窗口实例启动——ATTACH_TO_STATUS_BAR_ITEM 进程附加模式前置不满足（无托盘形态）
+
+> **严重度**: 3 critical（核心交互功能整体失效） | **领域**: electron-oh / 多窗口 / 窗口管理 | **自动修复**: 无托盘应用成对删除 processMode 与 startupVisibility（模板注释 + 本条目指引；带托盘保持默认）
+
+---
+
+## 机制（多窗口实例方案）
+
+Electron-OH 中每个 BrowserWindow = 一个**新 UIAbility 实例**：主进程 `new BrowserWindow()` → native 分配 window_id → ArkTS 侧 `AppWindowAdapter.createWindow` 经 `LaunchWithOptions` 启动新实例（`launchType=specified` + `instanceKey=window_id` → `AbilityStage.onAcceptWant` 返回独立 key）。模板默认在 `StartOptions` 带：
+
+```ets
+processMode: contextConstant.ProcessMode.ATTACH_TO_STATUS_BAR_ITEM,   // = 3
+startupVisibility: param.show ? ...STARTUP_SHOW : ...STARTUP_HIDE,     // 与之成对
+```
+
+SDK 注释（`@ohos.app.ability.contextConstant.d.ts`）：该模式表示 Ability **不强制新进程**、**进程附加到状态栏 item**——调用方需先向状态栏添加 item、目标与调用方同 bundle。**粒度是进程不是窗口**；`startupVisibility` 与之**成对校验**（只删其一仍被拒）。
+
+## 问题现象
+
+应用内「新建窗口」（Ctrl+N / 菜单，主进程第二次 `new BrowserWindow()`）**无声失败**：无窗口、无崩溃。hilog 特征：
+
+```
+LaunchHelper startAbility failed. Cause: {"code":16000067,...}   // ABILITY_RUNTIME_ERROR_VISIBILITY_SETTING_DISABLED / StartOptions check failed
+XComponentManager::CreateWindow <id> wait timeout                // 新实例从未创建
+```
+
+已排除：系统占用快捷键（鼠标点击同链路失效）、IPC 断链（主进程 createWindow 被调）、native 窗口 id/want 参数丢失（字段完整）、系统多窗口限制（`aa start` 直启第二个实例成功）。
+
+## 判别方法
+
+1. hilog 冷启动抓 `LaunchHelper|AppWindowAdapter|XComponentManager|16000067`——新实例 `WebAbility onCreate` 未出现即实例未创建；
+2. `aa start -a EntryAbility -b <bundle>`（不同 instanceKey）直启第二实例成功 → 系统允许多实例，断点在 StartOptions；
+3. grep 主进程 `new Tray(`——无即无托盘形态。
+
+## 解决方案（按应用形态二选一）
+
+**无托盘形态**（主进程无 Tray）：`AppWindowAdapter.createWindow` 的 `StartOptions` **成对删除** `processMode` 与 `startupVisibility`，走默认 ProcessMode（独立前台窗口）：
+
+```ets
+let options: StartOptions = { windowLeft:..., windowTop:..., windowWidth:..., windowHeight:...,
+  startWindowIcon:..., startWindowBackgroundColor:... }   // 无 processMode/startupVisibility
+```
+
+验证：应用内新建出现第二个独立窗口、加载 webapp；可重复新建多窗口并存（独立 UIAbility 实例 + 独立渲染进程）；关闭新窗口不影响主窗口；主窗口可恢复聚焦。
+
+**带托盘形态**（主进程有 Tray）：**保持默认**——先添加状态栏 item 后，`ATTACH_TO_STATUS_BAR_ITEM` 是合法形态（进程附加托盘 item 生命周期）。
+
+**无效修法**：只删 processMode 或只删 startupVisibility——成对校验不过，同样 16000067。
+
+## 影响范围
+
+一切 Electron-OH 模板（convert-template / pc-recipe-electron-app `template/ohos_hap`）生成的 **app 形态应用**：凡主进程存在「应用内第二次及以上 `new BrowserWindow()`」（文件多开/文档多窗口/打开新窗口类）且**无托盘**，新建窗口功能必然整体失效。首窗（桌面启动）不走此路径、冒烟测不出——须有「应用内新建窗口」交互用例。
+
+## 关联
+
+- `pc-knowledge-base/electron/guides/migration-guide.md` §1.4（形态匹配检查点 + 真机核验义务）
+- 模板 `AppWindowAdapter.ets` 注释（无托盘成对删除指引）
+- `PSCAN-LOCAL-004`（prescan：命中 `new BrowserWindow(` 触发多窗口形态匹配检查）
+- 系统版本差异：该 StartOptions 校验随系统版本暴露（6.1.1.135 未走此路径、7.0.0.105 暴露）——窗口/启动类行为系统升级后必须重验
+
+## 实证
+
+Electron-OH v37.2.3 无托盘图表编辑器（HAD-W32 / OpenHarmony-7.0.0.105 / aarch64，2026-10-16）：「文件→新建」Ctrl+N 与鼠标点击均无反应；hilog 定位 16000067 + CreateWindow wait timeout；排除系统限制与参数丢失后，成对删除 processMode/startupVisibility → 多窗口创建成功、多窗口并存（独立实例 + 独立渲染进程）、主窗口可恢复聚焦、零崩溃。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/L064.md

@@ -0,0 +1,81 @@
+<!-- 来源：Electron 下载管理类应用鸿蒙适配返修（HAD-W32 / OpenHarmony-7.0.0.105 / aarch64 真机实证 2026-10-16）| 证据链：真机 hilog（REMOTE_RENDERER_CALLBACK sent by unexpected WebContents (undefined)）+ IPC 代理补丁 + 删除任务/改存储路径双功能同根因同时修复
+evidence_level: E3
+summary_plain: Electron 渲染层经 @electron/remote 直调 dialog.showMessageBox/showOpenDialog 等依赖跨进程回调返回值的 API，在 Electron-OH 上弹框/选目录正常但 Promise 永不 resolve、功能静默失效——根因是 Electron-OH 主进程→渲染进程回传通道（webContents.sendToFrame + REMOTE_RENDERER_CALLBACK）漏填 senderId；统一修法=应用侧 IPC 代理（ipcMain.handle + ipcRenderer.invoke）绕道，根治需 Electron-OH 引擎补 senderId。
+trigger: REMOTE_RENDERER_CALLBACK, sent by unexpected WebContents, senderId, @electron/remote, dialog.showMessageBox 没反应, showOpenDialog 选完没反应, 确认框点了没反应, 存储路径改不了
+verify: 渲染层 @electron/remote 回调类 API 全部改走 ipcRenderer.invoke 代理后，对应功能（确认框后逻辑/目录选择返回值）在真机正常执行；hilog 不再出现 REMOTE_RENDERER_CALLBACK 丢弃告警即修复到位
+status: active -->
+
+# L064: Electron-OH 上 @electron/remote 跨进程回调（REMOTE_RENDERER_CALLBACK）无法回传渲染层——dialog 弹框正常但 Promise 永不 resolve
+
+> **严重度**: 3 blocking | **领域**: electron / ipc | **自动修复**: 应用侧 IPC 代理（根治需引擎补 senderId）
+
+---
+
+## 问题现象
+
+Electron 应用**渲染层**经 `@electron/remote` 直调、且**依赖跨进程回调返回值**的 API（`dialog.showMessageBox` / `dialog.showOpenDialog` 等），在 Electron-OH 上的典型表现：
+
+```
+1. 确认框/选择框【能弹出】（Electron-OH DialogAdapter 正常，用户可交互）
+2. 用户点「是」/选完目录后【功能无反应】——删除任务不执行、存储路径改不了
+3. Windows 原生 Electron 上同样代码正常（可复现差异 = 平台）
+4. 渲染层 console 转发可见丢弃告警，但无 JS 异常、无崩溃
+```
+
+特征：**框弹得出来、交互正常、就是结果回不来**——容易被误判为「业务逻辑没触发」「点击事件丢失」。
+
+## 根因
+
+| # | 误诊（都排除过） | 真根因 |
+|---|---|---|
+| 1 | 「业务代码没写对 / 事件没绑上」 | 不成立：Windows 正常、代码原样 |
+| 2 | 「@electron/remote 库问题」 | 不成立：库在原生 Electron 上正常（上游 electron 22.x 测试通过） |
+| 3 | 「应用不该用 remote 直调」 | 不成立：标准写法，老架构 Electron 应用普遍如此 |
+| 4 | **Electron-OH 移植层 IPC 语义缺口** | **主进程→渲染进程回传通道漏填 `senderId`** |
+
+回传链路：@electron/remote 的 `server.js` 在用户交互后调用 `sender.sendToFrame(frameId, "REMOTE_RENDERER_CALLBACK", ...)` 把结果推回渲染层 → 渲染层监听回调时校验 `0 === n.senderId`（防非预期来源）→ **Electron-OH 在主→渲染方向漏填 senderId（undefined）→ 校验失败 → 消息被丢弃 → Promise 永不 resolve**。
+
+引擎内校验串实证：`Reply to ${t} sent by unexpected WebContents (${o.sender.id})`（libelectron.so 中），渲染层丢包日志：`Message REMOTE_RENDERER_CALLBACK sent by unexpected WebContents (undefined)`。
+
+## 判别方法
+
+1. hilog 特征串：`Message REMOTE_RENDERER_CALLBACK sent by unexpected WebContents (undefined)` 出现 = 命中本条；
+2. 功能分类：凡「弹框/选择器正常 + 点完/选完无反应」且 Windows 同代码正常 → 优先怀疑本条（对话框/文件选择器/目录选择器同属此族）；
+3. 源码定位：grep 渲染层 `@electron/remote` 直调且 `.then()` 取回传结果的地方（`dialog.showMessageBox` / `dialog.showOpenDialog` / `shell.showItemInFolder` 等回调类 API）；
+4. Windows 对照：同一 bundle 在原生 Electron 上正常 = 平台侧缺口（非应用逻辑）。
+
+## 解决方案
+
+**应用侧统一修法 = IPC 代理绕道**（不改业务调用参数/返回值/UI）：
+
+```js
+// ① 主进程（Application.js 或入口）注册原生 handler：
+ipcMain.handle('app:show-message-box', (e, options) => dialog.showMessageBox(options))
+ipcMain.handle('app:show-open-dialog', (e, options) => dialog.showOpenDialog(options))
+
+// ② 渲染层封装（ohos-dialog.js 类工具）：
+//    IS_OHOS 分支走 ipcRenderer.invoke（实证可用通道，get-app-config 同款）；
+//    非鸿蒙平台保持 @electron/remote 原路径（行为不变）。
+export function showMessageBox (options) {
+  return IS_OHOS ? ipcRenderer.invoke('app:show-message-box', options) : dialog.showMessageBox(options)
+}
+
+// ③ 业务组件只换 import：@electron/remote dialog → 封装函数；调用处参数/返回值一行不改
+```
+
+**根治路径**：向 Electron-OH 引擎（gitcode CPF-Electron/Electron）反馈——移植层主→渲染 IPC 需正确填充 senderId。应用侧代理是过渡 workaround，同类回调类 API（非仅 dialog）都可能踩同一缺口。
+
+## 影响范围
+
+所有 `delivery_form=app` 的 Electron 应用，凡渲染层使用 `@electron/remote`（或任何依赖 `webContents.sendToFrame` 回传的机制）且依赖回调返回值——弹框确认、文件/目录选择、shell 回调类功能均属此族。老架构应用（2019-2021 年 electron-vue 等，渲染层直调 remote 是常态）风险最高；主进程弹框（ipcMain 直接处理）或渲染层自定义 IPC（invoke）的应用不受影响。
+
+## 关联
+
+- `pc-knowledge-base/electron/electron.md`（宿主机制；渲染层 remote 回调类 API 需 IPC 代理为硬约束级适配点）
+- `pc-knowledge-base/electron/api-matrix-34.md`（dialog 承接：DialogAdapter → ArkUI CustomDialog；回传通道缺口是承接链的断点）
+- `PSCAN-LOCAL-*`（prescan 建议：命中渲染层 `@electron/remote` 且含 `dialog.show*` 时触发「需 IPC 代理」检查）
+- 同族既有条目：L057（多窗口实例）、白屏四层判据（加载链）——本条是「渲染层功能静默失效」族的回调回传分支
+
+## 实证
+
+Electron 下载管理类应用（Electron-OH v34.8.5 / HAD-W32 / OpenHarmony-7.0.0.105 / aarch64，2026-10-16）：删除任务确认框与下载目录选择器均「弹框正常、点完/选完无反应」；真机 hilog 实证 `Message REMOTE_RENDERER_CALLBACK sent by unexpected WebContents (undefined)`；以 IPC 代理（`app:show-message-box` / `app:show-open-dialog` 两 handler + `ohos-dialog.js` 封装 + 多个 .vue 组件换 import）修复后，删除任务与改存储路径**两个独立功能同时恢复正常**——同根因双实证。Windows 原生 Electron 同代码正常（平台差异确认）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-error-atlas/knowledge/local-errors/README.md

@@ -0,0 +1,126 @@
+# 本地实战沉淀（L 系列）
+
+本目录是**插件侧的本地实战沉淀**，与 `knowledge/` 下的同步生成物性质不同：
+
+- **手维护**：`local-errors/` 不随知识源同步覆盖，不进 `manifest.json`，`npm run sync:kb` 的全量重生成与 `--check` 校验均不涉及本目录。
+- **非生成物**：无「自动生成」头注释，允许手改。
+- **同索**：每次同步生成 `error-index.md` / `error-index.json` 时，本目录条目会以「本地补充条目（L 系列）」一节追加在索引尾部，检索时与 E 条目同索。**另：新条目写完经 `ohpt-agent knowledge -s` 立即可检索**（`knowledge-index.ts` 对 local-errors/ 做免 sync live 叠加，不等下次同步——客户机上 sync 需要知识源，不能依赖）。
+
+## 来源
+
+L 系列为插件侧本地实战沉淀，含两类条目：
+
+- **迁移条目**：源自插件团队实战原创（旧编号 E120–E180 区间），知识源同步覆盖后只存在于本目录——上游知识库从未收录；首部注释标注「原编号 E###」供追溯
+- **新增条目**：后续新增的本地实战沉淀（无原编号，直接按 `L<三位序号>` 连续编号）；首部注释标注「来源：…」
+
+条目编号按 L 序列**连续分配**（新增即取当前最大号 +1），不因条目迁移/删除而跳号复用；正文里裸文字提及的 E 编号保持原样，指旧编号语境。
+
+## 新增条目写法约定（2026-10-13 起）
+
+新条目沿用 `L<三位序号>` 编号与 `# L###: 标题` 首部格式，并在**文件最顶部**写一个 HTML 注释头——沿用存量条目的「来源注释」风格（不用 frontmatter，避免干扰检索索引对 frontmatter 的解析）：
+
+```
+<!-- 来源：<实战复盘出处/日期> | 原编号 E###（仅迁移条目）
+evidence_level: E2
+summary_plain: <一句话大白话，≤120 字：症状+原因，非技术读者也能复述>
+trigger: <匹配短语，≤160 字：报错里真正出现的片段/关键词，供检索与回想命中；不要写问句>
+verify: <可判定验收，≤200 字：能跑出 pass/fail 的判据——不会失败的判据不叫判据>
+status: active
+related: <可选：相关条目指针，如 E051——本条与其互补/细化的关系一句话> -->
+```
+
+**不写应用名（2026-10-16 起）**：条目正文与标题一律提炼为**通用能力/方案**表述（如「多窗口实例」「无托盘形态」），禁止以具体应用为主语、标题载体或正文案例主体；应用名仅可保留在头部「来源：」注释作追溯留痕。此约束**同样适用于模板注释、知识文档、扫描规则等一切适配经验沉淀**——保证跨应用可检索、可复用。
+
+`evidence_level` 证据等级：
+
+| 等级 | 含义 |
+|---|---|
+| E0 传闻 | 听来的、未亲自复现 |
+| E1 推断 | 由证据推理，未直接验证 |
+| E2 单点实证 | 一次实测确认 |
+| E3 多点实证 | 多个项目/场景复现确认 |
+| E4 反证过替代假设 | 排除过其他候选根因后确认 |
+
+`status` 三态与升降级（本地版冲突裁决）：
+
+- `active`：现行有效。
+- `superseded`：同一问题与 E 条目（知识源同步生成物）并存时，**E 条目为准**——L 标 `superseded` 并在头部加一行 `superseded_by: E###` 指过去；正文保留留痕。
+- `stale`：条目被验证失效时标 `stale` **不删**（留痕），头部注明失效原因与日期。
+
+`related`（可选）：相关条目指针与关系一句话（如「E051（通用机制，本条是实案与落地修法）」）——用于「互补/细化」而非取代的场景；确属重复的走 superseded 流程，不写 related。
+
+**存量 56 篇不强制回填**：新条目按此写；存量在下次触碰该条目时顺手补齐头部字段。
+
+## 映射表（E 旧号 → L 号）
+
+| E 旧号 | L 号 | 一句话标题 |
+|---|---|---|
+| E120 | [L001](L001.md) | HAP 安装签名信任链失败（fail to verify pkcs7） |
+| E121 | [L002](L002.md) | HAP 构建 00308018（SDK management mode changed / not writable）= runtimeOS 与本机 SDK 形态不匹配 |
+| E122 | [L003](L003.md) | QPlainTextEdit::appendPlainText 在 OHOS 上 SIGABRT |
+| E125 | [L004](L004.md) | CMake 默认生成器回退 MSVC，产物是 x86 .dll |
+| E127 | [L005](L005.md) | Scintilla 等 C++17 依赖编译失败 |
+| E128 | [L006](L006.md) | 链接 QPA 平台插件导致运行时加载失败 |
+| E129 | [L007](L007.md) | 设备侧执行用户二进制被拒（Permission denied / Operation not permitted / exit 126 / 127） |
+| E130 | [L008](L008.md) | 依赖运行时数据在目标机缺失（功能全绿但能力静默降级） |
+| E131 | [L009](L009.md) | OHOS musl 分支 iconv 缺失 CJK 编码方向（to=CJK EINVAL） |
+| E132 | [L010](L010.md) | 跨架构浮点微差 + libc 依赖的测试脚手架：同代码双架构一过一挂 |
+| E133 | [L011](L011.md) | Windows 宿主编码纪律：BOM 吞注释、ASCII 损坏源码、CRLF 毒化 sh/CTest |
+| E134 | [L012](L012.md) | HNP zip 布局违约装机失败（9568407 / 0x801101 / native package install failed） |
+| E135 | [L013](L013.md) | OpenSSL 3.x TLS 握手在 OHOS aarch64 平台级失败 |
+| E136 | [L014](L014.md) | meson `run_command('test', '-d', ...)` 在 Windows 宿主失败（无 `test` 命令） |
+| E137 | [L015](L015.md) | 可选能力降级模式下 API 入参为 NULL 未守卫 → 解引用 SIGSEGV |
+| E139 | [L016](L016.md) | 测试用例缺陷——断言/参数类型与真实平台契约不符（testcase-defect） |
+| E140 | [L017](L017.md) | Windows 宿主 `find_package(PkgConfig REQUIRED)` 配置失败（无 pkg-config） |
+| E141 | [L018](L018.md) | conan 头文件数据族版本不兼容（cimg/3.6.6 t_magenta 常量 vs 函数） |
+| E142 | [L019](L019.md) | CImg 家族 X11/Xlib.h not found（NDK sysroot 无 X11） |
+| E143 | [L020](L020.md) | NDK 目标封装脚本在带空格安装路径下失效（Windows 宿主） |
+| E144 | [L021](L021.md) | cmd `set "VAR=..."` 嵌套引号导致编译参数断裂（Windows 宿主） |
+| E145 | [L022](L022.md) | glib conan 包缺失 Unix 专有头（gio/gunixinputstream.h、gunixoutputstream.h） |
+| E146 | [L023](L023.md) | clang 15 前端 ICE —— concept 带模板模板实参的约束 auto 形参 |
+| E147 | [L024](L024.md) | std::ranges 算法报 no member named —— libc++ 15 门控需 -D_LIBCPP_ENABLE_EXPERIMENTAL |
+| E148 | [L025](L025.md) | clang 15 的 C++20 缺口组（P0960 / P0634 / CRTP 约束缓存 / libc++ 裁剪） |
+| E149 | [L026](L026.md) | demo 验证接线错——API 枚举/编码参数与模块生命周期（harness-defect） |
+| E150 | [L027](L027.md) | fork+execv 子进程信号继承——exec wrapper 未重置 SIG_IGN 处置与阻塞掩码，SIGINT 无法递送 |
+| E151 | [L028](L028.md) | 宿主工具脚本替代的解析保真度（comp_sql DELIMITER 状态机） |
+| E152 | [L029](L029.md) | static-init 期调 sem_open 失败——命名 POSIX 信号量在 app 域受限，进程 main() 前崩溃 |
+| E153 | [L030](L030.md) | provider 自检状态机卡 INIT —— OpenSSL 3.x 族 DRBG/RAND 全挂（03080006） |
+| E154 | [L031](L031.md) | corrupt patch 被 `|| echo 继续` 静默掩盖——补丁未打进产物但构建绿 |
+| E155 | [L032](L032.md) | demo 验证接线错——对象状态/时区/正则/持久化残留/压缩数据（harness-defect） |
+| E156 | [L033](L033.md) | demo 验证接线错——TLS/NTLS/密码学 API 握手与证书构造（harness-defect） |
+| E157 | [L034](L034.md) | cli-hnp-runner — 手编 C++ NAPI 缺 libc++_shared.so 导致全部用例「调用失败: {}」（cpp-napl-missing-shared） |
+| E158 | [L035](L035.md) | napi_stub exec 名与 HNP 二进制名不一致导致所有 CLI exec RC=127（exec-name-mismatch） |
+| E159 | [L036](L036.md) | 纯 C TU 在 OHOS 上链接 C++ 实现 .so → init 期信号终止 |
+| E160 | [L037](L037.md) | 生成/补写测试的断言必须锚定 API 契约——契约外 UB 断言真机必崩且不是库缺陷 |
+| E161 | [L038](L038.md) | 重生成保护的协议漂移——保留旧页面 + 新 runner = 签名错配 |
+| E162 | [L039](L039.md) | NAPI 函数内 `char[] == const char*` 指针比较——以字符串内容为目标的 caseId 校验永远不通过 |
+| E163 | [L040](L040.md) | napi 异步工作中 `g_case_busy` 清位顺序：store(false) 必须在 resolve_deferred 之前 |
+| E164 | [L041](L041.md) | HAP 装机签名校验失败（9568329）——zip 重复条目 / 证书不匹配 |
+| E165 | [L042](L042.md) | libc++abi: terminating due to uncaught foreign exception（aarch64-musl） |
+| E166 | [L043](L043.md) | Lua C API 负栈索引归一化公式：gettop + index + 1（不是 gettop - index + 1） |
+| E167 | [L044](L044.md) | HAP 内 fork 无 exec 隔离把可恢复错误放大成进程崩溃——受阻归因平台前先做进程内对照 |
+| E168 | [L045](L045.md) | 数据驱动测试二进制缺 testutil provider 位置参数——usage 退出零执行（harness-defect） |
+| E169 | [L046](L046.md) | testutil 选项置于位置参数之后——opt_next 提前 EOF，过滤静默失效（harness-defect） |
+| E170 | [L047](L047.md) | hilog 全量 RAW dump 自截断——TAP 证据被自己的日志挤掉，声称值遭验收驳回（harness-defect） |
+| E171 | [L048](L048.md) | 存量 test-demo 判定分叉——用例页永远「已出结果」零 result 行，一把执行页却出 pass（scaffold 版本偏移） |
+| E172 | [L049](L049.md) | `sign-demo` 不带 `--demo-dir test-demo` 签错包——装的是阶段 3 HAP，「改了没生效」 |
+| E173 | [L050](L050.md) | assert 型测试证据被 NDEBUG 整体编译掉——rc==0 退化为空证明，判定必须钉住 stdout 证据行（assert-evidence-vacuity） |
+| E174 | [L051](L051.md) | 计算类 demo 设备内存未初始化 + atomic_add 读改写——冷启过/暖复跑挂（harness-defect） |
+| E175 | [L052](L052.md) | OHOS NDK clang 15 libc++ 的 float from_chars 被标记为 deleted——复用 __APPLE__ 分支 strtod_l 兜底 |
+| E176 | [L053](L053.md) | ld.lld 的 .debug_gdb_scripts 段与 --fatal-warnings 冲突——重链加 codesign 场景 |
+| E177 | [L054](L054.md) | CTR-DRBG 创建后未设 CIPHER 参数——instantiate 静默失败（wrapper-only 错误码） |
+| E178 | [L055](L055.md) | 看门狗只杀直接子进程——孙进程持 pipe 致 run-all 挂死（孤儿进程现场） |
+| E179 | [L056](L056.md) | bash VAR=val 独立成行不 export——环境变量静默失效误诊平台限制 |
+| E180 | [L058](L058.md) | hilog 捕获过滤三坑——`-e` 拆管 / bundle 名缩写漏行 / 过滤失效全量噪声 |
+| —（新增） | [L059](L059.md) | Electron 打包目录重构导致相对路径错位——Cannot find module '../xxx' 解析出载荷根 |
+| —（新增） | [L060](L060.md) | Electron-OH 渲染进程对系统分区文件 stat/read EACCES——主进程可读、渲染进程被拒（Chromium 子进程沙箱）；修法=主进程拷贝到沙箱 |
+| —（新增） | [L061](L061.md) | Electron-OH new BrowserWindow 偶发卡死——窗口系统竞态（进程活着但界面出不来）；重启重试（v34/v37 双版本实证） |
+| —（新增） | [L062](L062.md) | Electron-OH 同步 require 缺失模块永久挂起（不抛 MODULE_NOT_FOUND）——内联/惰性化/闭合校验 |
+| —（新增） | [L063](L063.md) | Electron-OH 多窗口实例启动——ATTACH_TO_STATUS_BAR_ITEM 进程附加模式前置不满足（无托盘形态） |
+| —（新增） | [L064](L064.md) | Electron-OH 渲染层经 @electron/remote 直调回调（REMOTE_RENDERER_CALLBACK）无法回传渲染层——dialog 等 Promise 永不 resolve |
+
+注：E123/E124/E126/E138 等区间内空号当年即不存在（非遗失）。L003–L006 四篇原文无 src 标注（带 UTF-8 BOM，已保留），来源注释为迁移时补记。**新增条目**（迁移表之后、无旧编号）以「—（新增）」占位 E 旧号列；每新增一条本地沉淀，在映射表尾部追加一行并保持 L 序列连续。
+
+## 长期归宿
+
+L 系列的终局是**回写知识源、评审转正后并入 E 系列**——届时本目录条目删除、索引 L 节自动消失，本目录随之退役。转正前请在此目录手维护；新增本地条目沿用 `L<三位序号>` 编号与 `# L###: 标题` 首部格式。