@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/L042.md

@@ -0,0 +1,42 @@
+<!-- 来源：C++/Lua 绑定库两轮适配实证（2026-09） | 原编号 E165 -->
+> 适用性：交叉编译 + 设备运行均适用
+
+# L042: libc++abi: terminating due to uncaught foreign exception（aarch64-musl）
+
+**分类**: L1 平台机制 + 认识论（先查代码 bug，再归因平台）
+**严重性**: 🔴 阻塞
+**影响软件**: 一切在 OHOS musl libc++abi 上跑 C++ 异常的库
+
+## 问题现象
+
+设备侧进程崩溃，hilog / stderr：
+
+```
+libc++abi: terminating due to uncaught foreign exception
+```
+
+exit code 表现为 `rc=-2`（SIGABRT）。崩溃点通常落在 catch/rethrow 或异常穿越 C 帧（如 Lua longjmp / lua_error）之后。
+
+## 根因分析（两段式，顺序不能反）
+
+**第一步：先当普通代码 bug 查，别急着归因平台。** 两轮对照实证：
+
+- 第一轮曾归因「musl libc++abi 的 `__cxa_eh_globals` 在嵌套 rethrow 后状态损坏」（exceptionClass 编码不是 `CLNCC++\0` → personality 返回 `_URC_FOREIGN_EXCEPTION_CAUGHT` → terminate），并尝试了 noexcept 析构修复、全链路 `-fasynchronous-unwind-tables`、嵌入式脚本解释器改编译为 C++——**全部无效**。
+- 真实根因是**两个上游代码 bug**：①基于 `boost::iterator_facade` 的迭代器比较运算符 ADL 自递归（显式写 `boost::operator==(x,y)` 仍经 ADL 回指自身 → 无限递归）；②C API 负索引归一化公式笔误（见 E166）。两个 bug 造成栈损坏/UB，其崩溃表象恰好是 foreign exception。
+- 修掉这两个代码 bug 后，同一设备同一 libc++abi 上名册全绿——**「平台 EH 限制」整案撤销**。
+
+**第二步：代码无懈后才考虑真平台 EH 问题。** 真平台问题的特征：最小复现里无任何 UB/递归/越界、纯 C++ try/catch/throw 序列也稳定复现、且与 C 帧（longjmp）交错强相关。此时缓解方向是把嵌入式解释器编译为 C++（throw 取代 longjmp）消除 C 帧穿越。
+
+## 解决方案
+
+1. 写最小复现 + diag 打点，二分定位到最后一个正常打点之后的具体操作。
+2. 重点排查：运算符重载自递归（凡 `return boost::operator op(x,y)` / `return x op y` 写法都要怀疑——正确写法是 static_cast 到 facade 基类再比较，如 `static_cast<boost::iterator_facade<...> const&>(x) == ...`）、索引/指针错位、越界读写。
+3. 修代码 bug 后复测；仅当确认代码无问题，才按平台 EH 路径处理。
+
+## 注意事项
+
+- `uncaught foreign exception` ≠ `uncaught exception of type X`：后者是 noexcept 析构等普通违规（先修那个），前者才是 exceptionClass 不识别。
+- 归因「平台限制」前必须做对照实验证伪（分阶段复刻 + 纯 API 对照组），否则会把可修的代码 bug 误判为不可修的平台缺陷，整块功能被错误放弃。
+
+---
+**发现于**: 某 C++/Lua 绑定库两轮适配（第一轮误归因平台、第二轮代码修复后名册全绿，HAD-W32 OpenHarmony-6.1.1.135）

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

@@ -0,0 +1,44 @@
+<!-- 来源：C++/Lua 绑定库两轮适配实证（2026-09） | 原编号 E166 -->
+> 适用性：交叉编译 + 设备运行均适用
+
+# L043: Lua C API 负栈索引归一化公式：gettop + index + 1（不是 gettop - index + 1）
+
+**分类**: L2 语言机制（Lua C API）
+**严重性**: 🟠 高（静默错位，不报错但行为漂移）
+**影响软件**: 一切手写 Lua C 绑定/扩展层（各代绑定库同理）
+
+## 问题现象
+
+在「先 push 新值、再用之前拿到的负索引」的代码路径里，读到错误的栈槽位。实证过的两种表现：
+
+- 弱引用实现漂移到锚定弱表自身，`get()` 永不为 nil（断言 `lua_isnil` 失败）；
+- 参数对象的负索引越界读空，叠加迭代器问题后崩溃（见 E165）。
+
+## 根因分析
+
+Lua 栈 1-based，负索引 `-1` 指栈顶。把负索引归一化为绝对索引的正确公式（即 `lua_absindex` 语义）：
+
+```c
+abs = lua_gettop(L) + index + 1;   /* 加号 */
+```
+
+误写成 `lua_gettop(L) - index + 1` 时对 `-1` 得到 `gettop + 2`，越界。另一类同族错误：先压一个表再 `lua_pushvalue(L, index)` 使用旧负索引——压栈后负索引整体偏移 1，静默指错槽位。
+
+## 解决方案
+
+凡是「先 push 再用旧负索引」或「把负索引存起来稍后使用」的代码，先归一化：
+
+```c
+if (index < 0 && index > LUA_REGISTRYINDEX)  /* 伪索引除外 */
+    index = lua_gettop(L) + index + 1;
+```
+
+伪索引（`LUA_REGISTRYINDEX` 及更负的值，含 upvalue 伪索引）**不做**归一化。
+
+## 注意事项
+
+- 该 bug 不崩溃时极难发现：值「差不多对」或漂移到一个同类型槽位，测试偶发失败。
+- 上游老牌绑定库也有这笔误（修正公式 + 弱表归一化两处补丁后相关用例全绿）——别默认上游代码可信。
+
+---
+**发现于**: 某 C++/Lua 绑定库适配（HAD-W32 OpenHarmony-6.1.1.135）

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

@@ -0,0 +1,34 @@
+<!-- 来源：C++/Lua 绑定库测试线受阻用例二分实证（2026-09） | 原编号 E167 -->
+> 适用性：交叉编译 + 设备运行均适用
+
+# L044: HAP 内 fork 无 exec 隔离把可恢复错误放大成进程崩溃——受阻归因平台前先做进程内对照
+
+**分类**: L1 平台机制 + 测试方法学
+**严重性**: 🟠 高（会把可修的接线 bug 误判成不可修的平台缺口）
+**影响软件**: 一切在 HAP app 进程内用 `fork()`（无 exec）隔离跑异常密集用例的 demo 载体
+
+## 问题现象
+
+HAP demo 用 `fork()` 隔离子进程跑崩溃风险用例：子进程被 SIGABRT(6) 杀死（`libc++abi: terminating due to uncaught foreign exception`），父进程存活。同一份被测库在 cli 载体（fork+execv 独立 ELF）全部通过。表象直指「hap-dlopen 载体平台 EH 限制」。
+
+## 根因分析
+
+二分对照（给 demo 加一个**进程内直跑旁路**，如 caseId 前缀开关，同一用例不 fork 直接跑）证伪平台归因：
+
+1. **进程内直跑不崩溃**——暴露出被崩溃掩盖的真实错误。实证两条受阻用例的真因都是 demo 接线 bug：一条是断言写错（把绑定层返回的 userdata 断言成 table、给无参 API 传了参），一条是「默认实现」接线误把覆盖分派器当成默认实现传入（正确模式是传一个显式调用基类实现的静态函数）。
+2. **fork 无 exec 是放大器**：多线程 ArkTS app 进程 fork 出的子进程继承整张进程状态（ArkRuntime/GC/hilog 锁与 EH 现场），子进程里一条本可恢复的错误传播路径撞上继承来的不一致状态 → foreign exception → SIGABRT。「子进程崩了」于是成了「载体不行」的假证据。
+3. cli 载体不受影响：fork+**execv** 后是全新进程镜像，无继承状态。
+
+## 解决方案
+
+1. demo 里给隔离机制留一个**进程内直跑旁路**（如 caseId 前缀开关），受阻用例先跑对照：直跑也崩才是载体问题，直跑不崩就是隔离机制或用例代码的问题。
+2. per-case 拉起的 harness（`aa start --ps caseId` 逐条拉起）本身就提供崩溃隔离——进程内跑崩了 harness 会拉下一条，fork 隔离不是必须的；要保留 fork 隔离时，崩溃结论必须经直跑对照复核再归因。
+3. 归因「平台 EH 限制」的纪律同 E165：先代码后平台。
+
+## 注意事项
+
+- 「同一 .so cli 载体过、hap 载体崩」不构成平台缺口的充分证据——两载体差的不只是 dlopen，还有 fork 语义（exec 与否）、进程线程模型。
+- 测试线 `capability_gaps` 条目一旦写错归因会把假知识带进终态（实证两条 gap 全部翻正为 pass）；翻正后须同步修订产物，别让错误归因沉淀。
+
+---
+**发现于**: 某 C++/Lua 绑定库测试线受阻二分（HAD-W32 OpenHarmony-6.1.1.135）

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

@@ -0,0 +1,66 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E168.md | 原编号 E168 --> 一句话定位：OpenSSL 家族数据驱动测试二进制（ssl_test/quicapitest 等 testutil 系）只传 conf 文件单参数上设备，`setup_tests()` 里的 `test_arg_libctx(..., argn=1, ...)` 取不到 provider 模块名直接 `TEST_error("usage:…")` 退出——症状是 rc=1 且输出只有一行 usage、逐用例零执行，实为**少传一个位置参数（harness-defect）**，补 `default` 即愈。
+
+# L045: 数据驱动测试二进制缺 testutil provider 位置参数——usage 退出零执行（harness-defect）
+
+> **严重度**: 2 major（整条用例零执行，易误判为环境问题）| **领域**: test-wiring | **自动修复**: none（按 README 手动跑法补参数）
+
+---
+
+## 问题现象
+
+```
+--- test_ssl_new/01-simple.cnf (rc=1) ---
+usage: ssl_test <conf> <provider>
+ok=0/7（每个 .cnf 都是 rc=1、输出极短）
+```
+
+特征：**每个配置文件 rc 完全一致、输出只有 usage 行**，没有任何测试断言输出——测试根本没开始跑。TEST_CERTS_DIR/CTLOG_FILE 已设、数据文件已在盘，修环境变量无效果。
+
+## 根因
+
+OpenSSL 3.x testutil 框架的数据驱动二进制，`setup_tests()` 标准形状：
+
+```c
+if (!test_skip_common_options()) return 0;
+if (!TEST_ptr(conf = NCONF_new(NULL))
+        || !TEST_int_gt(NCONF_load(conf, test_get_argument(0), NULL), 0) ...)
+        return 0;
+if (!test_arg_libctx(&libctx, &defctxnull, &thisprov, 1, USAGE))  // ← argn=1 必需
+        return 0;
+```
+
+`test_arg_libctx()`（`test/testutil/provider.c`）从 `test_get_argument(1)` 取 **provider 模块名**：传 `none`/`smtc`（某国密 OpenSSL 分支）则直接返回走默认 libctx；传 `default` 则显式加载 default provider。**该参数无缺省**，缺了就 usage 退出。
+
+## 判别方法
+
+1. rc=1 且 raw 输出只有一行 usage（或 TEST_error 行），无任何测试 TAP/断言行；
+2. 宿主上 `make test` 正常（Perl harness 自动把 `default` 拼进 argv）——只有手工直跑才踩；
+3. 比对上游 recipe 的调用形状：`test(["ssl_test", <conf>, ...])`——80-test_ssl_new.t 经 harness 传参、`test/README.ssltest.md` 手动跑法明确写着 `ssl_test <conf> default`。
+
+三条全中 → E168，补位置参数。
+
+## 解决方案
+
+按 `test/README.ssltest.md` 的手动跑法对齐 argv：
+
+```
+ssl_test <ssl-tests/xx.cnf> default          # 第 2 位置参数 = provider 模块名
+quicapitest default <default.cnf> <certs> <data-dir>   # 第 1 参数就是模块名（同机制）
+```
+
+优先用 `default`（显式加载、语义与 harness 一致）；构建含特殊 provider 时按 README 用 `none`/`smtc` 跳过显式加载。runner 里必须以独立 argv 条目传入。
+
+## 影响范围
+
+OpenSSL/某国密分支/BoringSSL 衍生库的所有 testutil 系数据驱动二进制：ssl_test、quicapitest、evp_test（-config 之外另有参数时）、版本相关的 fips_version_test 等。**宿主 make test 全绿 ≠ 手工直跑参数齐**——凡绕过 Perl harness 在设备上直跑，先对 README 手动跑法核 argv。
+
+## 关联
+
+- E167：CRLF 数据污染（同族打包侧坑，两者叠加时症状互相掩盖）
+- E169：testutil 选项（-test）位置语义——选项必须在位置参数之前
+- `pc-knowledge-base/platform/鸿蒙PC-真机跑官方测试套件.md`——官方测试套件上设备的接线权威
+- 实现依据：`source/test/testutil/provider.c` 的 `test_arg_libctx`（缺参 usage 退出）
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2（2026-09-17）：r2 轮 ssl_test 族 4 条（ssl_new/tls13messages/tls13hrr/ntls）在 CRLF 修复后仍 ok=0/N；grep `test_arg_libctx` 确认 argn=1 必需，补 `default` 第 2 参数后 r3 轮全过（`build/test-device-raw-r3.log` ok 30/46/47/48）。

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

@@ -0,0 +1,62 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E169.md | 原编号 E169 --> 一句话定位：给 OpenSSL testutil 系测试二进制传过滤选项（如 sslapitest 的 `-test <子测试名>`）时把它拼在位置参数之后——`opt_next()` 遇到第一个非 `-` 开头的位置参数即返回 EOF，选项**静默不被解析**，全量子测试照跑、在 app 域沙箱挂死组合上 rc=1；实为**选项顺序错（harness-defect）**，选项移到位置参数之前即愈。
+
+# L046: testutil 选项置于位置参数之后——opt_next 提前 EOF，过滤静默失效（harness-defect）
+
+> **严重度**: 2 major（过滤失效但无任何报错，最隐蔽）| **领域**: test-wiring | **自动修复**: none（调整 argv 顺序）
+
+---
+
+## 问题现象
+
+sslapitest 明明加了 `-test test_large_message_tls` 过滤，rc 却仍 = 1，raw 输出显示跑的是**全量子测试**（106 个里 app 域会挂的 TLS1.2 组合照样执行）：
+
+```
+--- test_sslapi (rc=1) ---
+（无任何「未知选项/解析失败」报错——选项只是被当没看见）
+```
+
+特征：**加了过滤选项和不加的结果一模一样**，没有任何解析错误提示。
+
+## 根因
+
+OpenSSL testutil 的参数解析走 `opt_next()`（getopt 风格逐 argv 扫描）：**遇到第一个不以 `-` 开头的参数即判定位置参数序列开始、返回 EOF**——其后所有 `-` 开头的 argv 不再被当作选项。
+
+```
+sslapitest <certs> <passwd> <tmp> default <cnf> <dh> <data> -test test_large_message_tls
+                                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^ 位置参数之后 → 不解析
+```
+
+## 判别方法
+
+1. 同一二进制去掉过滤选项重跑，rc 与输出**逐字节一致**——证明选项没生效；
+2. 该选项在宿主 `make test` / README 手动跑法里是放在**前面**的；
+3. raw 里子测试数量是全量而非过滤后的子集。
+
+三条全中 → E169，调 argv 顺序。
+
+## 解决方案
+
+选项放全部位置参数之前，且 `-test` 与子测试名必须是**两个独立 argv 条目**（合并成一个含空格的参数串同样失效）：
+
+```cpp
+std::vector<std::string> args = {
+  "-test", "test_large_message_tls",   // ← 选项对在最前
+  certs_dir, passwd_txt, tmpfile, "default", cnf, dhparams, datadir,
+};
+```
+
+旧版 B05/E149 已实证该过滤在 app 域的价值：全量 106 子测试挂于 `test_large_app_data` 第 8 次迭代（TLS1.2+DONT_INSERT_EMPTY_FRAGMENTS+NO_ENCRYPT_THEN_MAC），而 TLS1.3 内存 BIO 子测试组稳定通过——过滤跑子集是合法的 test-method 等价构造（断言体不变）。
+
+## 影响范围
+
+所有 testutil 系二进制的选项过滤：`-test <name>`（sslapitest/evp_test 等任意单测过滤）、`--<option>` 通用选项。getopt 风格解析的其它测试框架同理（选项必须先于位置参数的约定在 GNU getopt 里是可选的、在 opt_next 里是强制的）。
+
+## 关联
+
+- E168：testutil provider 位置参数（同一 argv 的另一半——`default` 是**位置**参数必须在后，`-test` 是**选项**必须在前）
+- E149：demo 验证接线错（harness-defect 同门：改测试侧不改库）
+- 旧版实证：B05（sslapitest -test 过滤 + 选项必须在位置参数之前的完整论证）
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2（2026-09-17）：r2 轮 sslapitest 带 `-test` 仍 rc=1（选项在尾部未生效、全量照跑）；前移后 r3 轮 ok 31 test_sslapi（`build/test-device-raw-r3.log`）。

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

@@ -0,0 +1,56 @@
+<!-- 来源：〈外部知识库仓〉/knowledge/doc/E170.md | 原编号 E170 --> 一句话定位：cli-runner 跑完全套后在收尾把全量 RAW 输出逐行灌进 hilog（数千行），环形缓冲回卷 + 进程级流控把先前实时打的 TAP 行挤出/截断——宿主抓到的日志无 TAP 计划行、无 PASS/FAIL 汇总行、无完成标记，声称的 total/pass_rate 因此**整体不可信被验收驳回**；实为**取证通道自毁（harness-defect）**，收尾重排（失败段限流 + TAP 尾部重放）即愈。
+
+# L047: hilog 全量 RAW dump 自截断——TAP 证据被自己的日志挤掉，声称值遭验收驳回（harness-defect）
+
+> **严重度**: 1 critical（测试可能真全过，却拿不出证据）| **领域**: forensics/hilog | **自动修复**: partial（模板收尾已重排）
+
+---
+
+## 问题现象
+
+套件在设备上跑完（甚至全过），宿主抓 `hilog -x` 却发现：
+
+1. 日志在 RAW 中段戛然而止（如 2939 行、时间戳冻结在同一秒），**无完成标记**；
+2. **无 TAP 1..N 计划行、无 PASS/FAIL 汇总行**——实时打过的 TAP 行不在缓冲里；
+3. 声称失败的用例名在全部日志中**零出现**，声称的汇总字符串（如 `PASS=33 FAIL=15`）全文 0 匹配。
+
+独立验收按「日志无完成标记 → total_cases/pass_rate 全不可信」整体驳回，测试白跑。
+
+## 根因
+
+| # | 机制 | 后果 |
+|---|---|---|
+| 1 | hilog 环形缓冲按**总量**回卷：收尾一次性灌数千行 RAW，把**先前**实时打的 TAP 行从缓冲尾部挤到头部再冲掉 | 宿主只看到「开头 + 中段截断」，计划行/逐条 TAP/汇总行全消失 |
+| 2 | hilog 进程级流控：单进程短时间灌入超限即丢行 | RAW dump 自己在中途断流（行数停在远小于 cap 的位置、时间戳同秒） |
+| 3 | 依赖「跑完后抓一次 hilog」的时序：抓取点越晚，早期 TAP 被冲掉越多 | 证据完整性取决于抓取时机——不确定的证据等于没有证据 |
+
+**不变量**：hilog 是环形缓冲 + 流控的**有损通道**，任何「全量转储」策略在它上面都不成立；证据设计必须保证**关键行位于缓冲尾部**（最后写入 = 最不可能被冲掉）。
+
+## 判别方法
+
+1. 抓到的日志有 RAW 无 TAP / 有开头无结尾 / 行数卡在某个 cap 前的整数——三者任一即实锤；
+2. 对照 runner 侧落盘文件（run-tap.log/run-raw.log 写在应用沙箱，零售机 hdc 读不到，但逻辑上存在）——盘上 TAP 齐全而 hilog 缺失，通道问题而非测试问题；
+3. 完成标记（如 `=== xxx-runner end ===`）缺失。
+
+## 解决方案
+
+runner 收尾按**环形缓冲尾部自证原则**重排（权威实现在 `templates/hap/cli-hnp-runner/entry/src/main/cpp/napi_stub.cpp` 的 `dump_failure_sections` + 两处收尾，2026-09-17 已入模板）：
+
+1. **RAW 只回传失败段落**：raw 段头 `--- <id>[ <cmd>] (rc=…) ---` 切段，段名与失败用例名前缀匹配，每段 head 60 + tail 20 行、总量 2000 行 cap、每 200 行 usleep(20ms) 避流控；全过打 `(none — all cases passed)` 占位（证明取证段执行过）；
+2. **TAP 尾部重放**：收尾最后把 tap_log（逐条 ok/not ok + `1..N` 计划行 + `PASS/FAIL/SKIP` 汇总行）全量重打一遍——缓冲尾部必有四要素；
+3. **完成标记收尾**：end 标记永远最后打；
+4. **抓取侧配合**：`hilog -G 2M` 扩缓冲 + `hilog -x` 一次性快照（而非持续流）。
+
+## 影响范围
+
+所有经 hilog 回传证据的设备侧 runner（cli-hnp-runner、gui demo 的 RAW 通道）。特征触发词：验收驳回「日志无完成标记」「声称值与盘上日志对不上」「失败名零出现」。
+
+## 关联
+
+- E158：exec 名不一致 rc=127（同为 runner 侧取证/执行问题，但那是执行、本条是回传）
+- `pc-device-verify/references/cli-batch-exec.md`——TAP 回传与取证收尾的权威章节
+- 验收规则 `suite-completeness`（completed 字段缺失/为 false 的判定）与 pc-03-verify 的「完成标记判据」——本条是它们要拦的病灶本身
+
+## 实证
+
+某国密 OpenSSL 分支 8.5.0-pre2（2026-09-17）：r1 轮全量 RAW dump（cap 20000 行）在 2939 行处截断于 ECDSA KAT 迭代 276、时间戳同秒 13:15:59——TAP 计划行/汇总行/完成标记全缺失，15 条声称失败名全日志 0 匹配，独立验收驳回 48/33/15 全部声称值；收尾重排后 r3 轮日志 103 行四要素齐全（`TAP| 1..48` + `PASS=48 FAIL=0 SKIP=0` + end 标记 + `RAW-FAIL| (none)`）。

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

@@ -0,0 +1,69 @@
+<!-- 来源：libaribcaption test-demo 判定分叉实证（2026-09-17） | 原编号 E171 -->
+> 适用性：一切经 `ohpt-agent scaffold --test-cases` 生成页面树的存量工作区（arkts 驱动档）
+
+# L048: 存量 test-demo 判定分叉——用例页永远「已出结果」零 result 行，一把执行页却出 pass（scaffold 版本偏移）
+
+**分类**: L3 测试线 demo 页面判定
+**严重性**: 🟠 高（两个入口结论不一致，测试同学按用例页执行得到错误的呈现；用例页路径还丢了机器可读的 `result=` 行）
+**影响软件**: 模板修复前生成的存量 test-demo（`OhptCaseRunner.ets` + `OhptRunAllPage.ets` + case 页面树）
+
+## 问题现象
+
+- 用例页点「执行本用例」：结果区状态停在**「已出结果」**，不出 pass/fail；hilog 有 native 的
+  `OHPTCASE check id=… cp=… ok=…` 行，但**没有**页面打的 `result=pass|fail id=…` 行；
+- 同一条用例在「全部执行」页却显示 pass——**两个入口结论不一致**；
+- `--ps caseId` 机器直达路径同样受影响（verify-demo 的逐条对账缺页面侧结果行）。
+
+**镜像变体（「失败」叙事词毒化）**：runner 已返回 true、用例页已 √/× 正确（单条执行 pass），
+唯独 RunAll 页 `step()` 仍是旧「非空且不含失败」启发式——预期文本含「失败」**叙事词**的用例
+（如「命令行会话以失败告终」「读取以失败告终」，本是正确描述异常行为的预期，而非失败结论）
+被扫到「失败」误判 fail，于是 run-all 出 fail、单条页出 pass，方向与上一种相反
+（某图像库相关用例实证 2026-09-21）。
+
+## 根因
+
+| # | 机制 | 后果 |
+|---|---|---|
+| 1 | 旧版 scaffold 生成的 `OhptCaseRunner.ets` 中 `ohptRunnerAutoJudges()` 返回 **false**，而 case 页模板的 √/× 判定分支整个被 `if (ohptRunnerAutoJudges())` 挡住 | carrier=cli（ArkTS 拿得到同步返回值、native 返回 CaseReport √/× 多行报告）本该由页面判 √/× 行，分支却永不执行 |
+| 2 | CaseReport 报告**没有** TAP 行（`ok `/`not ok `），页面落到 TAP 分支不命中 → 兜底 `state='已出结果'`，且**不打** `ohptReportCaseResult` | 判定缺失 + 机器对账丢行 |
+| 3 | 同时代码里 RunAll 页用「非空且不含失败」启发式自行判定，native `finish()` 为迁就它特意打「用例通过/失败」尾行 | 两入口**判据不同源**：RunAll 有结论、用例页没有 |
+| 4 | 新版模板已修（carrier=cli 的 runner 返回 true；RunAll 判定改 √/× 优先），但 scaffold 对 runner/RunAll/case 页走「内容有差异即保留」策略（阶段 6 接线点保护） | **重跑 scaffold 也不会对齐**——旧文件被点名保留，模板升级 ≠ 存量已修 |
+
+**不变量**：同一判据只允许一份实现——用例页与一把执行页必须同谓词（√/× 判定点行优先，「失败」字样启发式只兜底），且都只从被测物的真实返回解析。
+
+## 判别方法
+
+1. grep `ohptRunnerAutoJudges`：carrier=cli（`demo.callLib` 同步返回）的 runner 返回 false 即实锤；
+2. hilog：跑一条用例只有 `OHPTCASE check` 行、无 `result=` 行；
+3. 用例页结果区状态停在「已出结果」而全量执行页能出 pass/fail；
+4. 镜像变体：runner 已 true，但 `OhptRunAllPage.ets` 的 `step()` 判定仍是
+   `out !== '' && out.indexOf('失败') < 0`（无 √/× 优先分支），且误判为 fail 的用例集中在
+   预期文本含「失败/异常/终止」等叙事词的异常类用例上——「失败叙事词毒化」实锤。
+
+## 解决方案
+
+1. `entry/src/main/ets/common/OhptCaseRunner.ets`：`ohptRunnerAutoJudges()` 改返回 **true**（carrier=cli 档）——24 个用例页的 √/× 判定分支随之全部生效，无需逐页改；
+2. `entry/src/main/ets/pages/OhptRunAllPage.ets` 的 `step()` 判定改为 √/× 优先（与用例页同谓词）；
+3. 重跑 `ohpt-agent scaffold --test-cases`：被保留的文件会被**点名**，按点名手工合并；确认无定制可丢弃时 `--force` 重生成；
+4. 重构建装机（`build-hap.sh` → `ohpt-agent sign-demo -w <ws> --demo-dir test-demo --install`，见 E172）。
+
+## 影响范围
+
+一切存量 test-demo 的 arkts 驱动档（cpp-lib/carrier=cli 等）。特征触发词：用例页「已出结果」「两个入口结果不一致」「hilog 有 check 无 result 行」「用例页点了没 pass/fail」。
+
+## 关联
+
+- E172：同场景装机侧的「改了没生效」（sign-demo 缺省 demoDir 签错包）
+- `pc-test-design/references/demo-wiring-pc.md` §5「结果区报告格式（页面显示线）」——判定同源与存量偏移的规范表述
+- E161：TAP 格式契约（同为 OHPTCASE 结果行协议族）
+
+## 实证
+
+libaribcaption 1.1.2 test-demo（2026-09-17，HAD-W32 真机）：24 个用例页全部命中（每页同一段模板代码，runner 返回 false 一个开关挡死全部）；runner 翻 true + RunAll 判定对齐 + 重构建装机后，`--ps caseId F-01-01` 与 `F-05-02` 均打出 `result=pass id=…`，与「全部执行」结论一致。
+
+某图像库 test-demo（2026-09-21，HAD-W32 真机）：镜像变体实证——runner 与用例页均已随新版模板对齐
+（runner 返回 true、用例页 √/× 优先），但 `OhptRunAllPage.ets` 被 scaffold「内容有差异即保留」策略点名
+保留在旧版，`step()` 仍是「非空且不含失败」启发式。F-01-03（预期「命令行会话以失败告终，退出状态为非零」）、
+F-02-01（预期「读取以失败告终（报错误、无图像产出），不崩溃」）两句预期文本含「失败」叙事词，native 全绿
+却被 run-all 扫到「失败」误判 fail（单条页 pass）。改 RunAll `step()` 为 √/× 优先 + `build-hap.sh` 重建 +
+`sign-demo --demo-dir test-demo` 装机后，run-all 一把跑 13/13 pass，与单条结论一致。

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

@@ -0,0 +1,63 @@
+<!-- 来源：libaribcaption test-demo 装机包错位实证（2026-09-17） | 原编号 E172 -->
+> 适用性：同工作区并存阶段 3 演示工程（harmony-demo/harmony-app）与阶段 6 test-demo 的场景
+
+# L049: `sign-demo` 不带 `--demo-dir test-demo` 签错包——装的是阶段 3 HAP，「改了没生效」
+
+**分类**: L3 测试线装机流程
+**严重性**: 🟠 高（改动验证被旧包顶替，表现为修复无效，浪费一轮真机复测还可能误判修复方案错误）
+**影响软件**: 一切手工执行 `ohpt-agent sign-demo -w <ws>` 时省略 `--demo-dir` 的装机
+
+## 问题现象
+
+- 改了 test-demo 源码、`build-hap.sh` 重构建、`sign-demo -w <ws> --install` 显示签名+装机成功，
+  真机行为**没有变化**（新增的 `result=` 行不出现、新逻辑不生效）；
+- 签名输出路径在 `<ws>/dist/app/entry-default-signed.hap`（工作区顶层），而不是
+  `<ws>/test-demo/dist/app/`；
+- **镜像症状**（cximage 2026-09-20 实证）：`--hap` 显式指到 `test-demo/dist/app/*.hap`（对象没错）
+  但仍漏传 `--demo-dir` → bundleName 回退读 harmony-demo → **profile bundle-name 与 HAP 实际
+  bundle 不一致** → 签名与 verify-app 全绿，装机报 `9568329 verify signature failed`
+  （卸载重装也一样）。前一种「装错包」静默通过，这一种直接硬炸——同一漏参、两种症状。
+
+## 根因
+
+`sign-demo` 的 `--demo-dir` **缺省按 `['harmony-demo', 'harmony-app']` 探测**（阶段 3 的演示工程，
+CLI option 注释明示「阶段 5 传 test-demo」）。测试线工作区同时存在 `harmony-demo/` 与 `test-demo/`
+时，缺省命中 harmony-demo——签的是**阶段 3 的 HAP**，装完后 `com.ohpt.<lib>.test_demo` bundle 上的
+旧包原封未动。命令自身不报错（签名、装机都成功），错误静默传导到真机验证才发现。
+
+## 判别方法
+
+1. 看 `sign-demo` 输出的 `signedHap` 路径父级：`<ws>/dist/app/` = 签错对象；`<ws>/test-demo/dist/app/` = 正确；
+2. 装机后 `hdc shell bm dump -n <bundle>` 看 installTime/updateTime 是否刷新；
+3. 改动带可观测标志（如新增结果行）时，装机后先验证标志出现再下结论；
+4. 看**构建产物落点**：`sign-demo`/`verify-demo` 从 `<demo-dir>/dist/app/` 取 HAP（`build-hap.sh` 的约定落点）；
+   直接裸跑 `hvigorw assembleApp`（不跑 `build-hap.sh`）产物落在 `entry/build/default/outputs/default/`，
+   `dist/app/entry-default-unsigned.hap` **不更新** → 签名装机装的是上一轮的旧 HAP，「改了没生效」且 `installTime`
+   照常刷新、极难排查（rttr 2026-09-18 实证：真机跑了三轮旧行为，核对 `dist/app` 里的 HAP 字节才定位）。
+
+## 解决方案
+
+- 测试线装机一律显式带子目录：`ohpt-agent sign-demo -w <ws> --demo-dir test-demo --install`；
+- scaffold 输出的「下一步」命令串已自带该 flag（`steps.push(`ohpt-agent sign-demo -w ${workspace}${demoFlag} --install`)`），照抄执行即可——**手工重敲时最容易省掉**；
+- **CLI 守卫（2026-09-20 起）**：签名前比对 `--hap` 里 module.json 的 `app.bundleName` 与推断 bundleName（`readHapBundleName()`，oh-signing.ts），不一致直接拒签并提示补 `--demo-dir`——镜像症状（9568329）在签名侧即拦；`templates/hap/cli-hnp-runner/scripts/build-hap.sh` 的「下一步」提示同步补上了 `--demo-dir __OUT__`；
+- `verify-demo` 同理：`--demo-dir test-demo` 必须与装机对象一致，否则对账的是另一棵子树；
+- 构建走 `build-hap.sh`（它 build 完把 HAP 拷进 `dist/app/`）；若已裸跑过 `hvigorw assembleApp`，把新 HAP 拷到
+  `<demo-dir>/dist/app/entry-default-unsigned.hap` 再 `sign-demo`——别让 `dist/app` 里躺着上一轮的旧包。
+
+**不变量**：装机验证前先对账「装上去的字节」——signedHap 路径必须落在被验证的 demo 子树内；「命令成功」≠「装对了包」。
+
+## 关联
+
+- E171：同场景页面侧的判定分叉（本次实证两坑叠加：先签错包复测一轮无效，重签后才见到修复生效）
+- `pc-test-design/references/demo-wiring-pc.md` §0「标准命令序」——三条命令都带 `--demo-dir test-demo`
+- `pc-device-verify`：设备验证双通道
+
+## 实证
+
+libaribcaption 1.1.2（2026-09-17，HAD-W32 真机）：修复判定分叉后首次装机走缺省路径，signedHap 落在
+`<ws>/dist/app/`（harmony-demo 的 HAP），真机复测仍旧行为；`--demo-dir test-demo` 重签重装后
+`result=pass id=F-01-01` 如期出现。
+
+cximage 1.0.0（2026-09-20，HAD-W32 真机）：镜像症状实证——pypi-service 修复后重签漏传 `--demo-dir`，
+`--hap` 明确指向 test-demo 产物，签名/自验全绿但装机 `9568329`；用 mpg123 同日签出的 HAP 对照装机
+成功排除设备信任链后定位到 profile bundle-name 错位。守卫据此加入。

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

@@ -0,0 +1,65 @@
+<!-- 来源：转译器类 C++ 库测试线评审实证（2026-09-17） | 原编号 E173 -->
+> 适用性：一切「测试 ELF 自带 assert 自证 + 接线体只判 rc」的用例（cli-hnp-runner 单测试二进制与富用例体两形态都受）
+
+# L050: assert 型测试证据被 NDEBUG 整体编译掉——rc==0 退化为空证明，判定必须钉住 stdout 证据行（assert-evidence-vacuity）
+
+**分类**: L3 测试线 demo 接线
+**严重性**: 🟠 高（判定链全绿但证据为零：被测语义坏了也一样 rc=0，评审/测试同学拿不到任何可与预期比对的内容）
+**影响软件**: stdout 零输出、仅靠 `assert()` 自证的测试 ELF + 只判 `rc == 0` 的接线体
+
+## 问题现象
+
+- 用例 result=pass，但 `OHPTCASE check` 的 `actual` 只有「test_xxx 退出码 0，xx 语义生效」这类**宣称**，
+  没有任何可观测值；原始输出段里测试程序 stdout 为空或无关键信息；
+- 评审/测试同学无法核对「实际发生了预期里的什么」——预期与实际之间缺比对素材；
+- 同一测试程序若实现被掏空（空 stub）或语义回退，**判定结果不变**（照样 rc=0 全绿）。
+
+## 根因
+
+| # | 机制 | 后果 |
+|---|---|---|
+| 1 | 测试 ELF 的正确性证据只写在 `assert()` 里，构建侧带 `-DNDEBUG`（release 惯配；设备侧 hvigor CMake 默认就带）时 assert 被**整体编译掉** | 证据不存在了，rc=0 变成「进程活着走完」这一条信息 |
+| 2 | 接线体把 `out` 捕获回来却不用，`ok` 只判 `rc == 0`，`actual` 写「退出码 0，语义生效」 | 判定链上每一环都没有内容可比对——这本身违反「断言钉内容」纪律，且比空 stub 更隐蔽：测试程序是**真的**，证据却仍是空的 |
+| 3 | 被验的是**编译期语义**（const/不可变/类型推导形态/某重载不可达），本来就没有运行时可观测值 | 这类断言连「跑一下看返回值」的通常出路都没有，纯 assert 之外无从取证 |
+
+**不变量**：证据的存在性不得依赖断言是否启用——判定比对的是 stdout 里的**内容**，退出码只是附带信号。
+
+## 判别方法
+
+1. 看构建命令：交叉/设备侧 CXXFLAGS 是否含 `-DNDEBUG`（含则 assert 型证据全部失效）；
+2. 看 `device-raw.log` / 结果区：被测测试 ELF 的 stdout 有无逐断言的值流水；只有 `rc=0` 一行即实锤；
+3. 看 `actual`：写了「正确/生效/一致」却没有引用任何观测行原文；
+4. 抽查用例：把断言语义想成「如果实现坏了，这条判定还会变吗」——不会变的就是空证据。
+
+## 解决方案
+
+1. **测试程序把关键推导结果打成结构化证据行**（值用实际观测，不写死预期）：
+   `PROBE|对象|标签|实际值`（如 `PROBE|x|deduced-type|int const&&`）——NDEBUG 下证据行照打，
+   同时供 runner 机器比对与测试同学人工核对；
+2. **编译期语义用 SFINAE + static_assert 探针**：以「赋值替换失败」这类 trait 探针把
+   「不可变/不可达」写成可执行事实，`static_assert` 执法（它**编不掉**——const 丢了 ELF 自己就构建失败），
+   探针结论照常 printf 成证据行。c++14 无 `std::void_t`，本地别名 `template <class...> using void_sink = void;` 代替；
+3. **接线体逐行锚定比对 + 分层判定点**：一层证据一个 `OHPT_CHECK`（产物行/探针行/类型名行各占一个 cp），
+   `actual` 引用本层观测行原文；比对带上行尾 `\n` 防子串误配（`int const&` 是 `int const&&` 的前缀，
+   裸 contains 会把 const 右值引用形态误判成 const 左值引用形态）；被测工具自身能产出该产物时（转译/生成类），
+   先在设备上真跑一步产出、再验性质——端到端证据优于纯预编二进制。
+
+## 影响范围
+
+一切测试线用例的证据强度，与交付形态无关（cli-hnp-runner / cpp-lib-demo 同受）。特征触发词：
+「退出码 0」「类型推导正确」「语义生效」「stdout 没有内容」「NDEBUG」「assert 被编译掉」。
+
+## 关联
+
+- `pc-test-design/references/anti-fake-checklist.md` §10（反造假清单同源条目）
+- `pc-test-design/references/demo-wiring-pc.md` §「证据行与编译期探针」（配方：证据行格式/探针写法/分层判定点）
+- E155/E156：同为 demo 接线语义缺陷家族（那两条是「断言写错对象」，本条是「断言没有证据」）
+- `pc-test-design` SKILL.md §「断言要件覆盖」——弱断言的另一半（要件缺失 vs 证据缺失）
+
+## 实证
+
+转译器类 C++ 库测试线（2026-09-17，真机）：某「声明语句经包装获得不可变语义」用例只判 rc==0，
+`actual` 宣称「类型推导正确、const 语义生效」；评审点名「既没展示声明语句的产物、也没展示不可变本身」。
+修复 = 三层证据（设备上真转译一份含声明的输入看产物行 / static_assert 赋值探针 blocked + 未包装对照组
+allowed / 三种输入的推导类型名逐行比对），修后 `actual` 第一次可被人工逐项核对，全套 19/19 pass 不变——
+判定结论没变，变的是「结论有了证据」。

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

@@ -0,0 +1,58 @@
+<!-- 来源：OpenCL-SDK test-demo 直方图暖复跑脏内存实证（2026-09-20） | 原编号 E174 --> 一句话定位：demo 验证阶段给计算类 API（OpenCL/CUDA/Vulkan/GL compute）接线时，kernel 对输出缓冲做**读-改-写**（`atomic_add` 原子累加 / 桶计数 / 归约写回），但输出缓冲用 `CL_MEM_WRITE_ONLY + nullptr` 创建**未初始化**——冷进程驱动恰好分配零页、从 0 累加恰好对，暖进程复用上一轮脏内存、累加到垃圾值，症状表现为「全部执行（串跑）/暖复跑挂某条，单条/冷启动过」，实为 **harness 接线错（harness-defect）**，改 stub 不改库。
+
+# L051: 计算类 demo 设备内存未初始化 + atomic_add 读改写——冷启过/暖复跑挂（harness-defect）
+
+> **严重度**: 2 major | **领域**: test/contract + compute | **自动修复**: none（改 demo stub 的输出缓冲初始化，不动库；依据回指 kernel 对缓冲的读写模式）
+
+---
+
+## 问题现象
+
+demo 验证阶段（`napi_stub.cpp` 接线）给 GPU/计算 kernel 接线时，同一条用例表现出**顺序依赖 + 复跑依赖**的假失败：
+
+```
+OHPTCASE: check id=F-04-04 cp=0 ok=0 expect=直方图结果与主机串行统计的分布一致 actual=部分不一致
+```
+
+- 冷启动「全部执行」→ 过；
+- **不 force-stop 同进程再跑一遍「全部执行」（暖复跑）→ 挂**；
+- 单点「执行本用例」（通常冷进程上下文）→ 过。
+
+表象像「串跑状态泄漏」「驱动内存态不稳」，实为输出缓冲未初始化。
+
+## 根因
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| 1 | 暖复跑挂、冷启/单条过，且挂的判定点是对「kernel 输出 vs 主机参考」的比对 | kernel 对输出缓冲做**读-改-写**（`atomic_add` 累加 / 桶计数 / `atomic_or` 打位 / 归约），但缓冲用 `CL_MEM_WRITE_ONLY + nullptr` 创建未初始化。**冷进程**：驱动分配器恰好返回零页 → 从 0 累加 → 结果对；**暖进程**：分配器复用上一轮用过的脏内存 → 累加到垃圾值 → 结果错。零页是驱动懒清零的优化，不是契约 | 输出缓冲用 `CL_MEM_COPY_HOST_PTR` + **已清零的宿主向量**做源（或建完先 `clEnqueueFillBuffer` 填 0 再入队 kernel），保证每轮从确定性 0 开始 |
+
+**不变量**：与 E149/E155/E160 一致——「改测试侧不改库」的 harness-defect。判断点在于**该 kernel 的读写模式**：凡是 kernel 里出现对输出缓冲的 `atomic_*`（原子累加/原子或）、或「先读回再写回」的归约/桶计数/计数器写法，输出缓冲就必须初始化；「纯写覆盖」（每个 work-item 写互不重叠的槽位，且不读旧值）才允许未初始化。与 E155 的「持久化状态残留」分界：E155 是 **CPU 侧**（DB/文件/对象）旧状态残留，本条是 **设备内存侧**未初始化 + 读改写。
+
+## 判别方法
+
+1. 报错点在 **demo stub（napi_stub.cpp）** 内部，不在库函数入口（E137 才在库入口）；
+2. 症状是**顺序依赖 + 复跑依赖**（串跑挂/单条过、暖复跑挂/冷启过），不是每次稳定失败——稳定失败才去查 kernel 逻辑或库；
+3. 该 kernel 对输出缓冲做**读-改-写**（源码里搜 `atomic_add` / `atomic_or` / `atomic_xchg` / 对输出 buffer 先 load 后 store 的归约），而 `clCreateBuffer` 创建该缓冲时用了 `CL_MEM_WRITE_ONLY + nullptr`（未初始化）。
+
+三条全中 → 归因 harness-defect（设备内存未初始化），改 stub 的输出缓冲初始化，不是库 bug。
+
+## 解决方案
+
+1. **输出缓冲一律初始化**：凡 kernel 读-改-写，创建缓冲时 `CL_MEM_COPY_HOST_PTR` + 已清零宿主向量（`std::vector<T> v(n, 0)` 或 `memset` 后 `v.data()`），或建完 `clEnqueueFillBuffer(queue, buf, &zero, sizeof(zero), 0, n*sizeof(T), ...)` 先填 0。
+2. **归约/桶计数/计数器类用例**在接线时就该问一句「这缓冲要不要从确定值开始」——任何依赖「设备内存恰好清零」的假设都是脆弱假设，冷启零页是驱动优化不是 API 契约。
+3. **回归口径**：修复后**连跑多轮暖复跑**验证幂等（冷 1 + 暖 ≥2），别只跑一轮冷启就定稿——这类 bug 只在暖复跑暴露。
+
+## 影响范围
+
+所有「demo 验证阶段给计算类 API 接线」的场景：OpenCL / CUDA / Vulkan / WebGPU / GL compute shader / HIP。凡 kernel 做原子累加、桶计数、原子打位、前缀和、归约写回输出缓冲者，输出缓冲都必须初始化。跨框架同样适用（CUDA 的 `cudaMemset`、Vulkan 的 `vkCmdFillBuffer`、WebGPU 的 buffer 初始化）。
+
+## 关联
+
+- E155：demo 接线语义陷阱——持久化状态残留（CPU 侧 DB/文件/对象）；本条是设备内存侧未初始化 + 读改写，两者同属「重跑状态残留」但载体不同
+- E149 / E160：harness-defect 分界（改 stub 不改库）
+- E173：测试证据强度（同门「接线后要真证据」，本条是「接线要自包含/幂等」）
+- `pc-test-design/references/demo-wiring-pc.md` §4 —— 库形态接线防坑（含本条「输出缓冲初始化」）
+
+## 实证
+
+OpenCL-SDK 2026.05.29 测试线 demo 验证（2026-09-20）：F-04-04「执行 Histogram Kernel」在暖进程二次「全部执行」时挂 `check id=F-04-04 cp=0 ok=0 actual=部分不一致`（`mismatch buckets: X/100`），冷启与单条均过。根因：`run_F_04_04` 的直方图输出缓冲 `dout` 原用 `clCreateBuffer(g_ctx, CL_MEM_WRITE_ONLY, bins*sizeof(cl_uint), nullptr, &err)` 未初始化，而 `histogram_shared` kernel 用 `atomic_add(&histogram[ch], ...)` 读-改-写累加；冷进程驱动零页恰好从 0 累加，暖进程复用脏内存累加到垃圾值。修：`clCreateBuffer(g_ctx, CL_MEM_WRITE_ONLY | CL_MEM_COPY_HOST_PTR, bins*sizeof(cl_uint), gpu_hist.data(), &err)`（`gpu_hist` 已 `(bins,0)` 清零）作源。修复后 1 冷 + 3 暖四轮 34/34 全过。