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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-glib/345/255/220/350/277/233/347/250/213/347/233/221/346/216/247app/345/237/237/345/215/241/346/255/273.md

@@ -0,0 +1,90 @@
+---
+name: 鸿蒙PC-glib子进程监控app域卡死
+description: >-
+  glib 2.88 在鸿蒙 app 域用 pidfd 监控子进程（g_child_watch_add / g_spawn_async_with_pipes
+  内部），沙箱限制使 pidfd 路径行为异常，gmain 主循环进入无限阻塞：子进程 IO 回调不被调度、
+  GSocketService accept 阻塞永不返回。对策：测试壳/工具侧从 glib 事件循环改写为纯 POSIX 原语
+  （fork/execv/pipe/poll/waitpid + 裸 socket 替代 GSocketService/GSocketClient）。另附设备侧
+  spawn 交叉编译 CLI 二进制时的环境三项注意（.exe 后缀假设、g_spawn envp=NULL 丢 LD_LIBRARY_PATH）。
+  触发词：pidfd、g_child_watch_add、g_spawn_async_with_pipes、g_spawn_sync、gmain、主循环卡死、
+  事件循环阻塞、GSocketService、GSocketClient、accept 阻塞、子进程 IO 不调度、glib 2.88、app 域、
+  fork、execv、pipe、poll、waitpid、裸 socket、LD_LIBRARY_PATH、envp、.exe 后缀、ENOENT、TMPDIR。
+metadata:
+  type: platform
+  source: usbredir 0.15.0 适配实证（gen-cli-tcp 测试壳改写，2026-09）
+---
+
+# 鸿蒙 PC：glib 在 app 域用 pidfd 监控子进程导致 gmain 卡死
+
+> 平台机制，与具体库无关：任何在鸿蒙 app 域用 glib 的 `g_child_watch_add` / `g_spawn_async_with_pipes`
+> 派生并监控子进程的库或测试程序，都会踩中。usbredir 0.15.0 补写的测试壳 `gen-cli-tcp`（用 glib
+> 事件循环 spawn `usbredirect` + GSocketService 起 TCP 对端）实测卡死，改写纯 POSIX 后跑通。
+
+## 现象
+
+测试壳在设备 app 域运行后**无限阻塞**，具体三条症状：
+
+1. `g_spawn_async_with_pipes` 派生的子进程其 **stdout/stderr IO 回调不被调度**——子进程在跑，父进程收不到输出；
+2. `GSocketService` 的 `accept` **阻塞永不返回**——TCP 客户端已连上，服务端 accept 不触发；
+3. 测试壳被 90s `alarm` 杀时，`signal=SIGALRM`（说明是 watchdog 硬杀，不是正常退出）。
+
+## 根因
+
+glib 2.88 在鸿蒙 app 域用 **pidfd**（Linux 5.3+ 的进程 fd，创建/等待用到 `close_range`/`syscall 436`
+一族系统调用）监控子进程存活。app 沙箱对这些 syscall 有限制（见 [[鸿蒙PC-app域执行二进制与JIT限制]]
+关卡④ close_range），导致 pidfd 路径行为异常——`gmain.c:6133` 进入无限循环，主循环从此不再调度任何
+新事件（子进程 IO 回调、socket accept 全被饿死）。
+
+> 与 [[鸿蒙PC-app域执行二进制与JIT限制]] 的 close_range 关卡同源：那边是 SIGSYS 秒杀（进程直接死），
+> 这边 glib 的 pidfd 等待走的是「忙等/未唤醒」路径，表现为**无限阻塞而非崩溃**——更隐蔽，看不到
+> SIGSYS 报错，只能看到「卡住」。
+
+## 判定方法
+
+1. 现象：glib 事件循环程序在 app 域**卡死不退**，子进程 IO 收不到、socket accept 不触发；
+2. 确认是 glib 子进程监控路径：代码里用了 `g_child_watch_add` / `g_spawn_async_with_pipes` / `GSocketService`；
+3. 排除崩溃：faultlog 无 SIGSYS（区别于 io_uring/close_range 秒杀）——它是**挂起不是死**；
+4. watchdog（alarm/SIGTERM）能杀掉 = 进程还活着只是主循环不调度。
+
+四条全中 → 归因「glib pidfd 子进程监控 app 域异常」，走对策。
+
+## 对策
+
+### 首选：测试壳/工具侧从 glib 事件循环改写为纯 POSIX 原语
+
+不依赖 glib 的子进程与 socket 封装，全部手写：
+
+- **子进程**：`fork()` + `execv()` + `pipe()`（接 stdout/stderr）+ `poll()` 读管道 + `waitpid()` 手工回收；
+- **socket**：裸 `socket()` / `bind()` / `listen()` / `accept()` / `connect()` 替代 `GSocketService` / `GSocketClient`。
+
+usbredir 的 `gen-cli-tcp` 实测：改写后 TCP 重定向对端建立、子进程 IO 正常回收、`waitpid` 拿退出码，
+用例全绿。这套 fork/execv/pipe/poll/waitpid + 裸 socket 的原语写法，与私有 HNP exec 路径的 runner
+（[[鸿蒙PC-私有HNP打包与exec平台差异]]）同构，可直接复用。
+
+### 备选：等 glib 提供鸿蒙侧修正或共享库选项
+
+中心仓 glib 若后续修复 pidfd 在鸿蒙的退化路径（或提供 `.so`），可回退到 glib 事件循环。当前不可行。
+
+## 附带：设备侧 spawn 交叉编译 CLI 二进制的环境三项
+
+写「在设备上 spawn 一个交叉编译出来的 CLI 二进制」的测试壳时，除上述 pidfd 坑，还有两条易踩（usbredir
+`gen-cli-basic`/`gen-cli-tcp` 实证）：
+
+1. **`.exe` 后缀假设**：宿主编译（Windows）时测试壳里写死了 `usbredirect.exe` 搜索路径，设备侧没有
+   `.exe` 后缀 → `execv`/`g_spawn` 报 `ENOENT`。修法：搜索路径数组把 `./usbredirect`、`usbredirect`
+   放首位，`.exe` 变体靠后。本质是「宿主与设备可执行文件命名不同」，跨平台测试壳都要留意。
+
+2. **`g_spawn_*` 的 `envp` 传 `{NULL}` 丢环境**：`g_spawn_sync`/`g_spawn_async_with_pipes` 传
+   `envp = {NULL}` 会给子进程一个**空环境**，导致 `LD_LIBRARY_PATH`/`TMPDIR` 全丢，子进程动态链接
+   报 `Error loading shared library`。修法：`envp` 传 `NULL`（继承父进程环境，含 runner 设的
+   `LD_LIBRARY_PATH`/`TMPDIR`），不要传空数组。
+
+> 三项合起来就是「鸿蒙 app 域 CLI 测试壳落地的最小经验集」：进程/socket 用 POSIX 原语、路径别假设
+> `.exe`、`envp` 传 NULL 继承环境。可与 [[鸿蒙PC-app域测试前置条件矩阵]] 一起当测试壳开工清单。
+
+## 关联
+
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— close_range(syscall 436) 关卡④，pidfd 异常的同源 syscall 族
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— fork/execv 在私有 HNP 上的 runner 写法
+- [[鸿蒙PC-glib-gtest静态链接musl启动崩溃]] —— 同为「glib 在鸿蒙」的问题，但那是 musl assert 崩溃、本条是 pidfd 卡死
+- `pc-device-verify/references/cli-batch-exec.md` —— CLI 名册批量执行 + SONAME 别名坑

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-hdc/346/235/203/351/231/220/344/270/216/345/217/257/350/260/203/350/257/225/347/211/210/351/231/220/345/210/266.md

@@ -0,0 +1,44 @@
+---
+name: 鸿蒙PC-hdc权限与可调试版限制
+description: 【已收敛】鸿蒙PC 只有商用机一种形态：hdc shell 恒为 uid2000、够不到 /data/app、无法提权，且这是 ROM 属性不是开发者选项。曾经的四条旁路（模拟器/换可调试机/out-of-band 取头文件/HiShell 手动跑）在鸿蒙 PC 上均不适用，正解是设备侧验证在本机做——私有 HNP 执行器 HAP
+metadata:
+  type: platform
+  source: 实测(鸿蒙PC商用机) + 华为沙箱文档
+---
+
+# 鸿蒙 PC：hdc 权限（已收敛为单一形态）
+
+> **本篇只剩两件事**：说清 hdc shell 的权限事实，以及**标死那四条曾经把人带进死胡同的旁路**。
+> 能做什么、取证怎么取 → **[[鸿蒙PC-hdc能力边界与取证通道]]（权威，先读它）**。
+
+## 权限事实
+
+`hdc shell` 恒为 **`uid=2000(shell)`**（SELinux `u:r:sh:s0`）：够不到 `/data/app` 应用沙箱
+（Permission denied）、`hdc smode` 报 `Cannot set root run mode in undebuggable version` 无法提权。
+
+> **这是 ROM 属性，不是开发者选项开关**——出厂即如此，设置里打不开。
+
+## ⛔ 四条旁路：在鸿蒙 PC 上**一条都不适用**
+
+这一节保留的唯一目的是**拦住它们**。历史上模型严格沿着这张链接图走，四条全试一遍、耗掉一轮
+适配也没产出（mkspiffs 案）。看到这四条中的任何一条，**不要试**：
+
+| 旁路 | 为什么不适用 |
+|---|---|
+| 用 DevEco 模拟器 | 工具只面向鸿蒙 PC 真机；x86 模拟器也跑不了 aarch64 GPU/GL |
+| 换一台可调试 / eng 设备 | 没有这种设备可换——测试设备全是商用机 |
+| 头文件/库 out-of-band 拿到主机 | 只解决**交叉编译**，设备验证照样没着落，且设备上本就没有那套运行时可对齐 |
+| 设备测试走 HiShell 手动跑 | 手动、不可 hdc 自动化，只能当人工排查兜底（见 [[鸿蒙PC-不可调试设备用HiShell自动化测试]]） |
+
+## ✅ 正解：设备侧验证在本机就能做
+
+**够不到 `/data/app` ≠ 设备侧验证做不了。** 产物打成**私有 HNP**、随执行器 HAP 装机、
+在 app 域 `fork/execv` 真跑——`ohpt-agent scaffold --kind cli-hnp-runner`，全程 hdc 可驱动。
+机制见 [[鸿蒙PC-app域执行二进制与JIT限制]]，取证顺序（**先提级别再冷启动**）见
+[[鸿蒙PC-hdc能力边界与取证通道]]。
+
+设备上没有的运行时（Python / JDK / node）**一律随交付物自带**，别去找、也别据"找不到"判死——
+见 [[鸿蒙PC-设备语言运行时探测与供给]]。
+
+## 相关
+- [[鸿蒙PC-hdc能力边界与取证通道]] · [[鸿蒙PC-app域执行二进制与JIT限制]] · [[鸿蒙PC-应用沙箱与物理路径映射]] · [[鸿蒙PC-连接设备与hdc基础]]

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-hdc/350/203/275/345/212/233/350/276/271/347/225/214/344/270/216/345/217/226/350/257/201/351/200/232/351/201/223.md

@@ -0,0 +1,101 @@
+---
+name: 鸿蒙PC-hdc能力边界与取证通道
+description: 鸿蒙PC上hdc shell是uid2000、够不到/data/app与faultlog、/data/local/tmp不可执行；hilog取证的要害是商用机全局可打印级别默认Warning，INFO/DEBUG在写入时就被丢且事后不可追溯——取证必须"先设级别再冷启动"，另有截图与公共目录两条辅助通道；宿主侧转存走字节直写（PowerShell管道GBK解码致乱码假告警）、证据解析按bundle tagpath+时间窗双过滤（共享设备缓冲混流）
+metadata:
+  type: platform
+  source: 实测(鸿蒙PC商用机 HarmonyOS 6.1.0.135 / API 24 / aarch64, 2026-09-01)
+---
+
+# 鸿蒙 PC：hdc 能力边界与设备侧取证通道
+
+> 平台机制，与具体库无关。**先读这条再设计任何设备验证**——取证姿势错了，跑通了也拿不出证据。
+
+## 一、hdc shell 是什么身份
+
+`uid=2000(shell)`，`context=u:r:sh:s0`，组里有 **1006(file_manager)** 与 **1007(log)**。不是 root，也提不了权。
+
+| 目标 | 结果 |
+|---|---|
+| `/data/app/el1`、`/data/app/el2`（应用沙箱） | Permission denied |
+| `/data/service/hnp`、`/data/app/bin`（公共 HNP） | No such file or directory —— **公共 HNP 在鸿蒙 PC 上不存在** |
+| `/data/log/faultlog/faultlogger`（崩溃日志） | Permission denied —— **cppcrash 文件取不回**，崩溃只能从 hilog 的信号行推 |
+| `/data/local/tmp` | 可读可写，**但不可执行**（`Permission denied`，XPM/代码签名） |
+| `/storage/media/<userId>/local/files/Docs/` | **可读可写**（靠 file_manager 组）——Desktop / Documents / Download 都在此 |
+| `aa` `bm` `hilog` `snapshot_display` `uitest` `param` `hidumper` `atm` | 全部可用 |
+
+## 二、要害：hilog 的默认可打印级别是 **Warning**，INFO 在写入时就被丢
+
+商用机（打开开发者模式后）**全局可打印级别默认 W**。应用用 `LOG_INFO`/`LOG_DEBUG` 打的日志
+**根本没进缓冲**——不是读不到，是没写。所以：
+
+- **事后设级别救不回**已经发生的日志（不可追溯）；
+- `hilog -x -t app` 返回 0 行**完全可能只是级别问题**，不代表应用没跑、更不代表适配造假。
+
+**实证 A/B（同一 HAP、同一用例，重复两轮）**：
+
+| 设的全局级别 | 目标 tag 的 TAP 行数 |
+|---|---|
+| `W` | **0** |
+| `D` | 4 |
+| `W` | **0** |
+| `I` | 4 |
+
+被测对象是私有 HNP 执行器 HAP，`OH_LOG_Print(LOG_APP, LOG_INFO, …)` 逐行打 TAP；级别够时
+`A00001/<bundle>/<tag>: TAP| ok 1 …` 一行不少。
+
+### 正确取证姿势（顺序不能换）
+
+```bash
+hdc shell "hilog -b D -T <你的tag>"       # ① 先提级别。优先级 tag > domain > global，只提自己的 tag 噪声最小
+hdc shell "aa force-stop <bundle>"        # ② 必须冷启动——已在运行的进程不会重走 onCreate，也就不再打日志
+hdc shell "hilog -r"                      # ③ 清缓冲
+hdc shell "aa start -a <Ability> -b <bundle> -m entry"
+sleep 5
+hdc shell "hilog -x -T <你的tag>"          # ④ 按 tag 取；也可 -P <pid> / -D <domain> / -e <regex>
+```
+
+- `-b` 是**临时配置，重启后失效**；要跨重启用 `hilog -b D --persist`。
+- 别只依赖 `-x` 全量 dump 再 grep：系统日志量大，目标行可能已被挤出缓冲。用 `-T`/`-P`/`-D` 精确取，
+  必要时 `hilog -G 16M` 加大缓冲。
+- 日志级别设置**在应用启动之前**完成才有意义（②③ 都要在 ① 之后）。
+- 过滤优先 `-T <tag>`（无 shell 特殊字符）；必须 `-e` 正则时**表达式整体加引号**（裸传 `a|b`
+  会被设备 shell 拆成管道，raw 出现 `/bin/sh: xxx: inaccessible or not found` 即中招），且别按
+  bundle **全名**匹配（hilog 缩写 tagpath）、必含 `OHPTCASE` tag，捕获进程记 pid 收尾——三坑
+  详解见 `pc-error-atlas` E180。
+
+### 宿主侧转存与解析的两个坑（某交叉工具链工程 证据轮实证 2026-09-21）
+
+1. **Windows 宿主管道转码乱码**：`hdc shell "hilog -x" | Out-File xx.log`（或任何经 PowerShell 管道
+   的重定向）会按系统 GBK 解码 hilog 的 UTF-8 输出再落盘——中文 check 行全变 mojibake 且不可逆。
+   危害不止难看：证据解析按 `check id=… expect=… actual=…` 形状配对，乱码字节让配对失效，
+   34 条判定点只解析出 21 条 → 06-testdemo 被 Hook 点名「checks 未覆盖全部判定点」的**假告警**。
+   修法：**字节直写**——`node -e "spawnSync('hdc',['shell','hilog -x'],{encoding:'buffer'})"` 拿 stdout
+   buffer 直接 `fs.writeFileSync`，不经任何文本解码。
+2. **共享设备的 hilog 缓冲混流**：hilog 缓冲按设备共享，各工作区的 demo 都用 `OHPTCASE` 约定 tag——
+   `hilog -r` 只清掉**之前**的日志，防不了取证窗口**期间**别的会话在同一台设备上跑的 demo
+   （本轮 30MB 缓冲里混进另一工作区 13 条的跑，F-04/F-05/F-06 用例行混入解析）。证据解析必须
+   **双过滤**：`tagpath` 以本工作区 bundle 结尾 **且** 时间窗限定在本轮冷启动到 summary 之间；
+   否则逐用例证据会串库。设备是独占资源，正式取证建议走设备租约错峰。
+
+## 三、另外两条取证通道
+
+- **屏幕截图（零交互、零权限）**：`hdc shell "snapshot_display -f /data/local/tmp/x.jpeg"` +
+  `hdc file recv`，实测 3120×2080 可拉回。是像素、机器规则读不了内容，但**带视觉的验收方能判读**。
+  让被验证程序把结论也画到屏幕上（CLI 形态渲染 TAP 汇总），日志与截图互为佐证——两条通道同时失手的概率远低。
+- **公共目录文件（机器可读、需一次授权）**：应用申请 `READ_WRITE_DOCUMENTS_DIRECTORY` /
+  `READ_WRITE_DOWNLOAD_DIRECTORY`（normal 级但 **user_grant**，首启弹窗），把原始输出写进
+  Documents/Download；宿主侧读物理路径 `/storage/media/<userId>/local/files/Docs/…`
+  （**userId 因设备而异，glob 探测别硬编**）。做法见 [[鸿蒙PC-app访问PC用户目录]]，
+  授权状态查 `hdc shell "atm dump -t -b <bundle>"`（grantStatus 0=已授予）。
+
+## 四、判定要点
+
+- **"日志为空" ≠ "没跑" ≠ "造假"**。先自查三件事：级别提了吗？是冷启动吗？tag/domain 过滤对得上吗？
+  三者都成立仍为空，才谈得上是适配问题。
+- 判"跑没跑"最稳的是 `ps -ef | grep <bundle>` + 截图；判"跑对没跑对"看日志原文或截图内容。
+- **公共 HNP 与别的 App 私有 HNP 里的运行时都够不到**：设备侧要跑的二进制**一律随交付物自带成私有 HNP**
+  （唯一 exec 通道，见 [[鸿蒙PC-app域执行二进制与JIT限制]]）。
+
+## 相关
+- [[鸿蒙PC-app域执行二进制与JIT限制]]（设备侧 exec 唯一通道） · [[鸿蒙PC-app访问PC用户目录]]（公共目录通道的权限做法）
+- [[鸿蒙PC-应用沙箱与物理路径映射]] · [[鸿蒙PC-连接设备与hdc基础]]

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-musl/344/270/216BSD-glibc/350/257/255/344/271/211/345/210/206/346/255/247/350/241/250.md

@@ -0,0 +1,82 @@
+---
+name: 鸿蒙PC-musl与BSD-glibc语义分歧表
+description: 鸿蒙 NDK musl libc 与 BSD/glibc 的固有行为分歧清单（errno 文案/stdio 语义/locale 多字节/数值解析边界/时间格式化/堆处置 UB 六族）——写测试预期先查这张表：断言平台特定字面量（错误文案、字节序列、换行处理、多字节编码行为、日期时区字面量）或 UB 类操作结果（double-free 后进程状态）时按 musl 实际行为写，不要照抄 BSD/glibc 的 man 手册或上游测试。触发词：musl 分歧、glibc 差异、BSD 行为、errno 文案、strerror 不一致、错误文案断言失败、多字节编码、EILSEQ、locale 行为、stdio 语义、fopencookie、行缓冲差异、测试预期失败、预期不符、platform divergence、语义分歧表、strftime、时区缩写、EDT、日期断言、double-free、二次释放、SIGTRAP、堆处置、UB 预期、未定义行为、不崩溃断言。
+metadata:
+  type: platform
+  source: libbsd 0.12.2 外部一致性测试（22 项 FAIL 实证，2026-08）；堆处置族 libidn2 真机实证（2026-09）
+---
+
+# musl 与 BSD/glibc 语义分歧表
+
+## 这张表怎么用
+
+鸿蒙 NDK 的 libc 是 **musl**。任何「在 Linux 上跑得好好的测试」拿到鸿蒙上，断言**平台特定字面量**时都可能撞分歧——错误文案、字节序列、换行处理、多字节编码行为——这些不是产物缺陷，是两个 libc 的固有差异。
+
+**判定原则**：断言失败时先问「预期值从哪来」——来自 BSD/glibc 的 man 手册或上游测试 ≠ musl 的事实行为。契约级断言（返回码语义、错误码枚举值）保留；平台字面量按 musl 重写。三向对照的完整分诊程序见 `pc-device-verify/references/failure-triage.md` 的「行为分歧」档。
+
+**表的纪律**：只收**已实证**的条目（每条带证据来源）；未做三向对照的不入表——猜测入库会被下一轮照抄（历史教训：未实测的因果推断曾污染知识库）。v1 全部条目来自一次 C 实用函数库的外部一致性测试（frontmatter source 所注）。
+
+## 族 1：errno 文案（strerror 系）
+
+| 断言对象 | BSD/glibc 预期 | musl 实际 | 断言改写法 |
+|---|---|---|---|
+| `strerror(errno)` 返回文案 | BSD 有历史文案变体（`Interrupted system call` 等） | musl 文案集自成一套，与 BSD 部分不同 | **别断言文案字面量**——断言 `strerror` 返回非 NULL、`errno` 数值本身；必须比文案时按 musl 源码（musl `src/errno/strerror.c`）抄实际值 |
+| err/warn 族输出的错误行 | 同上 | 同上（文案最终经 strerror） | 同上 |
+
+适用面：一切「错误码 → 文案」断言的测试（错误处理族全适用）。errc/warnc/vwarn 风格 API 与自写测试都一样。
+
+## 族 2：stdio 语义（fopencookie/funopen 系）
+
+| 断言对象 | BSD 预期 | musl 实际 | 断言改写法 |
+|---|---|---|---|
+| funopen 流的 fclose 是否触发 close 回调 | BSD 触发 | musl fopencookie 实现下关闭时内部 fd 状态不同，可能带 `EBADF` | 断言回调**被调用过**（计数器），不断言 errno 状态 |
+| fgetln 返回行的换行包含语义 | BSD `len` 含 `\n` | musl 底层 stdio 缓冲行为存在差异 | 断言「内容前缀匹配 + len 与实测一致」，用返回值自身的 len 而非硬编码长度 |
+| fpurge 后流状态 | BSD 清空缓冲 | musl `__fpurge` 语义有实现差异 | 只断言返回值 0/非 0 |
+
+适用面：一切 stdio 封装/自定义流库（cookie 流、行读取器、格式化读写的测试）。
+
+## 族 3：locale / 多字节（宽字符转换系）
+
+| 断言对象 | BSD 预期 | musl 实际 | 断言改写法 |
+|---|---|---|---|
+| 高位非法字节（0x80-0xFF）的编码处理 | BSD 按 locale 逐字节处理 | musl C locale 下 `mbrtowc` 返回 `EILSEQ(84)`，编码类函数走错误路径 | 涉及多字节转换的 API，预期里**显式声明 C locale 前提**；非法输入的用例断言「错误路径被触发」（返回值/errno），不断言输出字节序列 |
+| 可视化编码（转义类）对高位字节的输出 | BSD 变体间本就不同 | 依赖底层 mbrtowc 行为 | 同上——断言往返一致性（编码再解码等于原文）比断言字面输出更可移植 |
+
+适用面：一切编码/转义/多字节处理库（vis 系、base64 系、mime 系、宽字符工具）。
+
+## 族 4：数值解析边界（strtol 底层系）
+
+| 断言对象 | BSD 扩展预期 | musl 实际 | 断言改写法 |
+|---|---|---|---|
+| 空串/尾随垃圾的扩展错误码（如 `ENOTSUP`） | NetBSD 系 strtoi/strtou 有扩展状态 | musl 只提供底层 strtol 语义，扩展状态码由各库自带实现决定 | 先查该 API 是**库自带实现还是 libc 提供**（`readelf --dyn-syms` 查产物与 sysroot libc）；库自带时按其源码写预期，libc 提供时按 musl 手册 |
+| 解析边界（LLONG_MIN/MAX 邻域）的 errstr 文案 | 上游测试硬编码文案 | 自带实现文案遵循上游，但边界取值可能与编译器/long 位数相关 | 边界用例断言 errstr 非 NULL + 数值语义，文案比对按上游源码 |
+
+适用面：一切数值解析/格式化库的边界测试。**注意**：本族多数 FAIL 的根因是「预期来源方不明」而非真分歧——分诊时必须先过三向对照（见 failure-triage.md），确认后把结论补进本表。
+
+## 族 5：时间/日期格式化（strftime 系）
+
+| 断言对象 | glibc 预期 | musl 实际 | 断言改写法 |
+|---|---|---|---|
+| 含时区缩写的日期字面量（`%c`/`%Z` 输出，如 `Wed Sep 23 15:56:14 EDT 2015`） | 上游测试硬编码构建机时区输出（`EDT` 等缩写） | 设备上 strftime 的时区/格式输出与 glibc 宿主不一致（实测断言失败），具体值依赖设备时区数据 | 改**时间无关的结构验证**：非空、长度、含年份、含 `:`、空格数；不断言具体日期/时区值 |
+
+适用面：一切格式化时间输出的测试（日志时间戳、`Date::toString` 类）。证据：C++ 消息库设备全量跑实证（2026-09），改写后通过。
+
+## 族 6：堆处置（UB 类确定性处置，free 系）
+
+| 断言对象 | glibc 预期 | musl 实际 | 断言改写法 |
+|---|---|---|---|
+| `free()` 同一指针两次后的进程状态 | 检测到即 `abort()` 终止（SIGABRT + stderr `free(): double free detected`）；旧版本/未覆盖路径可能静默通过 | **SIGTRAP(TRAP_BRKPT) 确定性终止执行释放的进程** | double-free 是 C 标准未定义行为、无契约保证——**两个 libc 都终止进程，分歧仅在信号形态**。预期写平台确定性处置（判定点只判「执行释放的子进程被信号终止」），**禁止断言「不崩溃/不输出段错误/程序存活」**；执行须子进程隔离（释放方进程必被终止），父进程按子进程退出信号判定；库若为 free 透传封装（如 libidn2 的 `idn2_free`），行为 100% 委托平台 libc，上游零此类断言 |
+| 野指针/use-after-free 触碰后的进程状态 | 视堆布局，可能静默腐坏或崩溃 | 同为未定义，musl 堆检测路径的处置形态与 glibc 不同 | 同上——UB 场景预期只锚「确定性处置被触发」（进程终止/信号到达），不断言具体信号值或存活 |
+| 依赖「free 后同尺寸块残留内容」的读回/比对逻辑（demo 接线代码或库自身） | 桌面 ptmalloc 系复现不可靠——同模式 Windows 宿主连跑 4 轮均不翻转（实测），「桌面看着正常」不构成证据 | 同尺寸释放块在**热进程内被回收再利用**：依赖残留内容的判定冷启动首轮可能侥幸通过、同进程第二轮起翻转 | 不依赖 free 后内存：库内部缓冲**先快照再跨调用比对**；「输出应不同」的断言用**非退化输入**让差异落在确定写入的数据位。判读「冷跑 pass、热跑翻车」＝堆状态依赖信号，唯一可靠复现面是真机同进程反复执行 |
+
+适用面：一切释放类/UB 类用例（free 族 API、生命周期管理的测试）。证据：libidn2 F-01-03 真机实测（2026-09，HAD-W32/OpenHarmony-6.1.1.135，`test-demo/verify/F-01-03.json`：二次释放子进程被 SIG5(SIGTRAP) 终止，round-1 用 glibc 容忍前提写「不崩溃」预期被判用例设计缺陷）；libogg 阶段 6 F-01-04（2026-09，HAD-W32/OpenHarmony-6.1.1.135）：demo 悬垂比对 + 全 1 位型输入，冷启动 run-all 判「不同」通过、人工同进程多轮点击翻成「相同」——块复用与脏块循环两种机理都以热进程为前提，接线红线见 pc-test-design 的 demo-wiring-pc「判定确定性」。
+
+## 何时新增条目（准入线）
+
+跑三向对照程序确认「实现一致、预期来自其他平台」→ 以「族 + 断言对象 + 双方行为 + 改写法」四栏格式补行，并在证据里注明 musl 源码位置或实测命令输出。**没做对照的不收**——表的价值在每条都可信，宁缺毋滥。
+
+## 相关条目
+
+- [鸿蒙PC-app域执行二进制与JIT限制.md](鸿蒙PC-app域执行二进制与JIT限制.md) — SIGSYS/seccomp 类（行为分歧之外的另一类 FAIL 根因）
+- [鸿蒙PC-app域测试前置条件矩阵.md](鸿蒙PC-app域测试前置条件矩阵.md) — 测试前置不可满足类（第三类根因）
+- `pc-device-verify/references/failure-triage.md` — 三向对照分诊程序（本表的判定入口）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-ohpt-sign-demo/345/277/205/351/241/273/344/274/240demo-dir/345/217/202/346/225/260.md

@@ -0,0 +1,51 @@
+---
+name: ohpt-sign-demo-demo-dir参数必填避免9568329验签失败
+description: ohpt-agent sign-demo 根据 --demo-dir 指定工程的 AppScope/app.json5 读取 bundleName 生成签名 profile；若为 test-demo 工程签名时必须传 --demo-dir test-demo，否则读到默认工程（harmony-demo）的 bundleName，生成的 profile 与 HAP 实际 bundle 不符，安装时报 code:9568329 verify signature failed。
+metadata:
+  type: platform
+  source_lib: openocd
+  source_commit: bedefa238476ad852b1fafd927230e38e2092282
+  proposed_at: 2026-09-15T15:58:00.000Z
+---
+
+## 现象
+
+`ohpt-agent sign-demo -w <ws> --hap test-demo/dist/app/xxx-unsigned.hap --install` 执行后报告签名成功（生成 signed.hap），但 `hdc install` 时报 `code:9568329 verify signature failed`。
+
+使用 `--json` 模式可以看到输出的 bundleName 与实际 HAP 不匹配。
+
+## 根因
+
+sign-demo 的 bundleName 获取逻辑（`Ft()` 函数）按优先级依次查找：
+
+1. 如果传了 `--demo-dir`，读取该目录下 `AppScope/app.json5` 的 `bundleName`
+2. 如果没传，默认查找 `harmony-demo/AppScope/app.json5`
+3. 其次 `harmony-app/AppScope/app.json5`
+
+如果使用 `test-demo` 工程但未传 `--demo-dir test-demo`，sign-demo 会读到 `harmony-demo` 的 bundleName（如 `com.ohpt.openocd.harmony_demo`），与 `test-demo` HAP 的实际 bundle（如 `com.ohpt.openocd.test_demo`）不符 → 签名 profile bundleName 不匹配 → 安装时设备验签失败。
+
+## 修复
+
+签名 test-demo 工程时必须显式传 demo-dir：
+
+```
+ohpt-agent sign-demo -w <ws> --demo-dir test-demo --hap test-demo/dist/app/xxx-unsigned.hap --install
+```
+
+## CLI 守卫（2026-09-20 起）
+
+sign-demo 在签名前会用 `readHapBundleName()` 解析 `--hap` 里 module.json 的 `app.bundleName`，
+与推断出的 bundleName 对账，不一致直接拒绝签出（不再全绿放行到装机才炸）：
+
+```
+[sign-demo] ✗ --hap 的 module.json bundleName（com.ohpt.cximage.test_demo）与签名 bundle（com.ohpt.cximage.harmony_demo）不一致——
+profile bundle-name 不匹配装机必报 9568329 verify signature failed（见 pc-error-atlas E172）。用 --demo-dir 指向该 HAP 所属的 demo 工程（如 --demo-dir test-demo）后重签
+```
+
+同时 `templates/hap/cli-hnp-runner/scripts/build-hap.sh` 的「下一步」提示已自带 `--demo-dir __OUT__`
+（旧工作区已生成的脚本副本不会自动更新，重跑 scaffold 才会刷新）。
+
+## 检出条件
+
+- 产线或 demo 验证流程中使用了名称不是 harmony-demo 的工程目录（如 test-demo）
+- 看到 9568329 验签错误但签名本身看起来成功

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-openocd-Tcl/346/234/215/345/212/241/345/231/250/345/215/217/350/256/256/345/221/275/344/273/244/345/210/206/351/232/224/347/254/246Ctrl-Z.md

@@ -0,0 +1,32 @@
+---
+name: 鸿蒙PC-openocd-Tcl服务器协议命令分隔符Ctrl-Z
+description: openocd 的 Tcl 服务器（tcl_server.c）使用 \x1a（Ctrl-Z）作为命令结束符，与 Telnet 服务器（telnet_server.c）使用 \r\n 不同。忽视此差异会导致 Tcl 命令永不执行、shutdown 不触发、父进程因 pipe read 永久阻塞。
+metadata:
+  type: platform
+  source_lib: openocd
+  source_commit: bedefa238476ad852b1fafd927230e38e2092282
+  proposed_at: 2026-09-15T15:58:00.000Z
+---
+
+## 现象
+
+通过 TCP 连接向 openocd Tcl 端口（默认 6666）发送命令时，openocd 不执行任何命令，日志无响应。发送 echo hello\r\n 无效，但连接本身建立成功。如果等待后发送 shutdown 也不退出。
+
+若用例在与 Tcl 端口交互后通过 read(pipe) 等待子进程标准输出 EOF，将永久阻塞。
+
+## 根因
+
+openocd 使用不同的 TCP 服务器组件，各自的命令结束符不同：
+
+- **Telnet**（telnet_server.c:782）：0xd/0xa（CR/LF，\r\n）触发命令执行
+- **Tcl**（tcl_server.c:221）：0x1a（Ctrl-Z，\x1a）触发命令执行
+
+Tcl 服务器的输入处理循环（tcl_input）逐个字节读入并缓存；只有收到 \x1a（Ctrl-Z）时才调用 command_run_line。其他所有字节（包括 \r、\n）都只是追加到缓冲区，永不执行。
+
+## 修复
+
+发送 Tcl 命令时使用 \x1a 替代 \r\n 作为结束符。命令结果通过 Jim_GetString(Jim_GetResult(interp)) 获取（Jim 命令的返回值，不是 stdout 输出），后跟 \x1a 终止符。
+
+## 适用场景
+
+任何通过 TCP 连接与 openocd Tcl 端口交互的程序（自动化测试脚本、调试助手等）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-uid/344/270/216/346/226/207/344/273/266/345/275/222/345/261/236.md

@@ -0,0 +1,40 @@
+---
+name: 鸿蒙PC-uid与文件归属
+description: file_manager 与应用 uid 体系、HOME/桌面文件归属、为什么不能绕过 FilePicker 硬写物理路径
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：uid 体系与文件归属
+
+## 关键 uid
+| uid | 身份 | 说明 |
+|---|---|---|
+| `0` | root | hdc shell 默认身份 |
+| `20001006` | file_manager（系统服务） | 拥有 `/storage/Users/currentUser` 整个 HOME 树（Desktop/Documents/.ssh/.ohos_git/...）以及 `/storage/media/<userId>/local/files/Docs/Desktop` 物理路径下所有文件 |
+| `200xxxxx` | 普通应用 | 每个 HNP/HAP 应用一个独立 uid，例如 OpenCode = `20020107` |
+
+uid 计算规则推断：
+```
+uid = 100 * 200000 + appId
+20020107 = 100 * 200000 + 20107   # user 100 的应用 appId 20107
+```
+
+## 桌面/HOME 文件目录权限模式
+典型权限：
+```
+drwxrws--x 20001006 file_manager   # setgid（s 位），others 只有 x
+-rw-rw---- 20001006 file_manager   # 文件 660
+```
+
+**普通应用 uid 在标准 POSIX 权限下 既不能 read 也不能 ls**。但应用实际能访问，是因为：
+1. HarmonyOS 通过 FilePicker / SAF（Storage Access Framework）/ ACL 给应用授权后端访问能力。
+2. hmdfs/sharefs 在挂载时附加 `hmmac=use_task` 等扩展安全模块，按 task 维度判定权限。
+
+> 这是为什么"硬编码物理路径写文件"经常翻车——绕过了授权层。应用应走 FilePicker/SAF，不要硬编码物理路径。
+
+## 排查清单
+- 写文件失败 / 应用读不到：先确认 uid 和 owner 是否一致。
+- 应用进程能访问但 hdc shell root 写后不见：不是权限问题，是 namespace 视图问题（见 `鸿蒙PC-进程视角与mount-namespace.md`）。
+- Git 报 dubious ownership：基本就是 uid 不一致触发的安全策略，用 `safe.directory` 放行（见 `鸿蒙PC-定制git行为.md`）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/344/270/215/345/217/257/350/260/203/350/257/225/350/256/276/345/244/207/347/224/250HiShell/350/207/252/345/212/250/345/214/226/346/265/213/350/257/225.md

@@ -0,0 +1,68 @@
+---
+name: 鸿蒙PC-不可调试设备用HiShell自动化测试
+description: hdc shell(uid2000) 进不去 App 沙箱跑不了 Python，可用 uitest/uinput UI 自动化驱动 HiShell 终端，配合"脚本写日志→hdc 取日志"远程闭环。pywt 实测全流程 PASS。**前提**：本篇的 Python 与 binary-sign-tool 都来自该机装的 DevBox，鸿蒙 PC 商用机上没有——那里走私有 HNP 执行器 HAP，签名走宿主链接期。
+metadata:
+  type: platform
+  source: 实测（零售/不可调试机，HongMeng 1.12.0）
+---
+
+# 鸿蒙 PC：不可调试设备用 HiShell 自动化做远程测试/签名
+
+> ⚠️ **先看前提，别照搬**：本篇成立的机器**装了 DevBox**（源：HongMeng 1.12.0 那台）。鸿蒙 PC 商用机上 `/data/service/hnp` **根本不存在**（[[鸿蒙PC-hdc能力边界与取证通道]]），HiShell 里既没有那个 `python3.12`、也没有 `binary-sign-tool`——**这不是"从 hdc 侧看不见"，是真没有**。
+> 商用机上**也不需要**它们：设备侧要跑的东西一律自带成私有 HNP、随执行器 HAP 装机
+>（`ohpt-agent scaffold --kind cli-hnp-runner`，见 [[鸿蒙PC-app域执行二进制与JIT限制]]）；
+> ELF 签名走宿主链接期 `LDFLAGS='-Wl,--code-sign'`，HAP 装机签名走 `ohpt-agent sign-demo`。
+> **"设备上没有 DevBox" 从来不是阻塞理由，更不是换设备的理由。**
+
+不可调试设备 `hdc shell`=uid2000、进不去 App 沙箱（见 [[鸿蒙PC-hdc权限与可调试版限制]]），**但可用 UI 自动化驱动 HiShell 终端**——在**装了 DevBox 的**机器上，HiShell 跑在 App 上下文里，PATH 上有 Python（`/storage/Users/currentUser/usr/local/bin/python3.12`）+ **DevBox 工具链**（`/data/service/hnp/bin/` 下 `binary-sign-tool`/`llvm-objcopy`/`clang`）。shell 用户即可用 `uitest`/`uinput`/`aa`/`hidumper`（`/bin/` 下）。
+
+## 驱动 HiShell（uitest/uinput）
+
+```bash
+aa start -b com.huawei.hmos.hishell -a EntryAbility      # 启动终端
+uitest uiInput click <x> <y>                             # 点终端聚焦（坐标先 screenCap/dumpLayout 找）
+uitest uiInput keyEvent 2072 2050                        # Ctrl+Space 切输入法到英文（关键！）
+uinput -K -t '<命令文本>'                                 # 输入命令文本
+uitest uiInput keyEvent 2054                             # Enter 执行
+uitest screenCap -p /data/local/tmp/s.png                # 截屏
+uitest dumpLayout -b com.huawei.hmos.hishell -p ...      # 拿 UI 树找控件坐标
+```
+
+**致命坑：中文输入法**。默认 IME 是中文，`uinput -t` 的 ASCII 会被转成拼音乱码（`python3.12`→`跑一趟候鸟2`、`$`→`￥`），Enter 还只确认候选不执行。**先 `keyEvent 2072 2050`(Ctrl+Space) 切英文**（屏幕右下 IME 角标变"英"），之后才正常。
+
+## 最佳实践：脚本写日志 → hdc 取日志（别读截图）
+
+截图 OCR 又慢又不准。改成：**写 python 脚本把结果写进桌面日志文件 → HiShell 跑脚本 → hdc 取日志读精确文本**。
+
+```bash
+# 桌面：逻辑 /storage/Users/currentUser/Desktop = 物理 /storage/media/<userId>/local/files/Docs/Desktop
+# hdc 对桌面物理路径【可读写】（shell 在 file_manager 组）；Git Bash 调 hdc 要 MSYS_NO_PATHCONV=1
+MSYS_NO_PATHCONV=1 hdc file send <脚本/wheel> /storage/media/<userId>/local/files/Docs/Desktop/
+# 在 HiShell 里（用 uinput 输入）：python3.12 /storage/Users/currentUser/Desktop/<脚本>.py
+MSYS_NO_PATHCONV=1 hdc file recv /storage/media/<userId>/local/files/Docs/Desktop/<日志> <本地>
+```
+脚本内 `subprocess` 跑命令、把 stdout/stderr/判定写进 `open('/storage/Users/currentUser/Desktop/x.log','w')`。
+
+## 完整闭环（pywt 实测 PASS）
+
+1. **主机交叉编译**出 `.so`（用 `OHOS_PYTHON_HOME` + numpy wheel 头，见 pc-transform），打成 `cp312-cp312-ohos_aarch64` wheel。
+2. `hdc file send` wheel + 测试脚本到桌面。
+3. HiShell 里 `python3.12 -m pip install <wheel> --force-reinstall --no-deps`（设备 pip 用 OHOS 官方索引，tag `ohos_aarch64` 被接受；numpy 等依赖已预装）。
+4. **签名**：ELF 强制代码签名，未签 `.so` import 报 `Permission denied`。**默认首选是宿主链接期自签**
+   `LDFLAGS='-Wl,--code-sign'`（post-link `strip` 会破坏签名段）；**仅当该机确有 DevBox** 时，才有下面这条设备侧自签的可选路径（逐个签 site-packages 里的 `.so`）：
+   ```bash
+   llvm-objcopy --remove-section .codesign "$so"      # 先去旧签名段
+   binary-sign-tool sign -inFile "$so" -outFile "$so" -selfSign 1   # 自签（rc=0, add codesign section success）
+   chmod +x "$so"
+   ```
+   **`-selfSign 1` 自签即可被该设备接受**（无需 keystore）。未签名 `.so` import 报 `Permission denied`；签名后正常加载。
+5. `import pywt` + 跑用例 → 写日志 → hdc 取日志判定。pywt：`idwt roundtrip max-err 1.78e-15`、dwt2/wavedec 均 OK → **PASS**。
+6. **全量官方用例**：`python3.12 -m pytest --pyargs pywt -q` → **1036 passed, 2 skipped**（2 skip 是可选依赖，同上游），92s 跑完。
+
+## 设备上跑 pytest 的坑
+- **App python ≠ shell 用户**：启动器里的 python 跑在 App uid，**写不了 `/data/local/tmp`**（那是 hdc shell 用户 uid2000 的目录，`drwxrwx--x shell shell`）→ 别把 TMPDIR/HOME 指到 `/data/local/tmp`，用 App 能写的 `/storage/Users/currentUser/...`。
+- **pytest tmp 属主校验**：默认 `/storage/Users/currentUser/tmp/pytest-of-100` 属 uid100、与当前 App uid 不符 → pytest 报 `OSError: temporary directory ... is not owned by the current user`，相关 `*_pickle` 用例 setup 即 error（非功能失败）。**修法**：`--basetemp=/storage/Users/currentUser/Desktop/_pt`（新建、App 自有）→ 4 个 pickle 用例全过。
+
+## 相关
+- [[鸿蒙PC-hdc权限与可调试版限制]] · [[鸿蒙PC-应用沙箱与物理路径映射]] · [[鸿蒙PC-设备Python运行时]]
+- [[鸿蒙PC-hdc能力边界与取证通道]]（商用机的能力面权威） · [[鸿蒙PC-app域执行二进制与JIT限制]]（无 DevBox 时的 exec 通道）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/344/272/244/345/217/211libcurl/347/251/272CA/344/277/241/344/273/273/351/224/232/344/270/216SSL_CERT_FILE.md

@@ -0,0 +1,65 @@
+---
+name: 鸿蒙PC-交叉libcurl空CA信任锚与SSL_CERT_FILE
+description: 交叉构建的 libcurl（OpenSSL 后端）默认不读 SSL_CERT_FILE/SSL_CERT_DIR——未设 CURLOPT_CAINFO 且构建未开 CURL_CA_FALLBACK 时 X509_STORE 为空（源码 infof "no trust anchors configured"），HTTPS 全部 curl error 60（SSL peer certificate or SSH remote key was not OK）。修复：重建 libcurl 开 CURL_CA_FALLBACK=ON 使 X509_STORE_set_default_paths 生效（此后 SSL_CERT_FILE 可用），应用侧随包 CA bundle 并设环境变量。OHOS 应用沙箱无系统 CA 库（/system/etc 对 hdc shell 也拒读），服务端证书链无法自证。触发词：curl error 60、SSL peer certificate、SSL_CERT_FILE、CURL_CA_FALLBACK、X509_STORE、no trust anchors configured、CAINFO、证书校验失败、HTTPS 下载失败、freshclam、curl 交叉编译、CA bundle、certifi
+metadata:
+  type: platform
+  source: new/PC（杀毒引擎 freshclam 设备 HTTPS 更新排查实证，2026-09-07；libcurl vtls/openssl.c 源码核对）
+---
+
+# 鸿蒙 PC：交叉 libcurl 的空 CA 信任锚陷阱
+
+> 平台约束：**「宿主上 curl 能过 HTTPS」对设备零参考价值**。交叉构建的 libcurl
+> 大概率没烤入任何 CA、也没编默认信任路径逻辑——到设备上 HTTPS 一律 error 60，
+> 且 `SSL_CERT_FILE` 环境变量在默认构建下**根本不生效**。
+
+## 一、根因（libcurl vtls/openssl.c 源码）
+
+`ossl_load_trust_anchors()` 只在 `CURLOPT_CAINFO/CAPATH`（或 CAINFO_BLOB）设定时
+加载信任锚；两者都空时**不调** `X509_STORE_set_default_paths`——只有构建宏
+`CURL_CA_FALLBACK` 打开时才有空库回退到 OpenSSL 默认信任路径（后者才吃
+`SSL_CERT_FILE`/`SSL_CERT_DIR` 环境变量）：
+
+```c
+if (ssl_cafile || ssl_capath) { /* X509_STORE_load_file/path ... */ }
+#ifdef CURL_CA_FALLBACK
+if (octx->store_is_empty) { X509_STORE_set_default_paths(store); ... }
+#endif
+if (octx->store_is_empty) infof(data, "  no trust anchors configured");  // ← 默认构建的终态
+```
+
+**辨别已编入的构建**：二进制里同时有 `no trust anchors configured` 与
+`X509_STORE_set_default_paths`（导入符号）→ 开了 FALLBACK；只有前者 → 没开。
+预编译分发（conan 中心仓等）的 OHOS 包默认**不带** CA bundle 路径也不开 FALLBACK。
+
+## 二、OHOS 侧加压：应用沙箱没有系统 CA 库
+
+- 沙箱内 `/etc` → `/system/etc`，其下没有 OpenSSL 约定目录（`/etc/ssl/certs` 等）；
+- `hdc shell ls /system/etc` 本身就 Permission denied——**连「服务端证书链是否被
+  MITM」都无法用 openssl 工具自证**（设备日志里 curl verbose 是唯一信息源，抓法：
+  给上层程序开 debug/verbose 让 curl 吐 `CAfile:`/`CApath:` 行）。
+
+## 三、修复链（两步，缺一不可）
+
+1. **重建 libcurl 开 `CURL_CA_FALLBACK=ON`**（cmake 选项，链接期生效；同时建议
+   `CURL_USE_LIBPSL=OFF` 等裁剪省依赖）。此后 X509 默认信任路径可用；
+2. **应用侧自带 CA bundle 并指路**：把 certifi/系统 ca-bundle.crt 随 HNP 打包
+   （如 `share/cacert.pem`），执行器给子进程设
+   `SSL_CERT_FILE=<hnp>/share/cacert.pem`（OpenSSL 3 在 `OPENSSL_CONF` 未改时
+   读该 env）。
+
+验证：设备上跑真实 HTTPS 下载（如 freshclam 对 database.clamav.net），成功日志含
+`updated (version: …)`；仍 error 60 且 verbose 无 `CAfile:` 行 = 第 1 步没生效。
+
+## 四、弯路备忘
+
+- 只设 `SSL_CERT_FILE` 不重建 curl → 无效（默认构建不读它）；
+- `CURL_CA_BUNDLE` 是构建期烤路径的环境探测变量（configure 检测宿主 CA 路径），
+  与运行期 `SSL_CERT_FILE` 是两回事，别混；
+- curl error 60 vs error 6（Could not resolve hostname）：60 是 TLS 层证书问题，
+  6 是 DNS——网络面归因时先分流。
+
+## 相关
+
+- [[鸿蒙PC-ClamAV杀毒引擎CLI真机适配]] 本条的首发案例（freshclam 更新）
+- [[鸿蒙PC-HNP包与PATH]] CA bundle 随 HNP 打包的落点
+- E017 镜像源/网络类错误（构建期下载）与本题设备运行期 HTTPS 是不同阶段