@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-/344/273/216Mac/350/256/277/351/227/256/350/256/276/345/244/207/347/275/221/347/273/234/346/234/215/345/212/241.md

@@ -0,0 +1,113 @@
+---
+name: 鸿蒙PC-从Mac访问设备网络服务
+description: 设备 `100.125.x.x` 从 Mac 不可达，用 `hdc fport` 把端口转发到本机；FTP PASV 通道踩坑要走 SFTP；Mac curl 默认走 socks5 代理要绕过
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 从 Mac 访问鸿蒙 PC 上的网络服务（hdc fport + 实际案例）
+
+跟随[鸿蒙PC-进程视角与mount-namespace.md](鸿蒙PC-进程视角与mount-namespace.md) 之后的另一条"跨域访问"主题：
+设备文件系统访问要走 nsenter，**设备网络服务访问要走 `hdc fport`**。
+
+## 核心结论
+
+1. **鸿蒙 PC wlan0 上的 IP 多半是 `100.125.x.x`，从 Mac ping 不通**。这是华为内部 CGNAT 段，不在公网也不在普通办公局域网，Mac 不会跟它在同一二层。直接 `ping/curl/ssh <设备IP>:port` 全部超时。
+2. **正确姿势：用 `hdc fport tcp:<本地端口> tcp:<设备端口>`** 把设备端口转发到 Mac `127.0.0.1`，然后所有客户端工具都连 `127.0.0.1`。`hdc fport ls` 查看现有转发。
+3. **UI 上的"占位符文案"不等于配置值**：FtpNextServer 设置页里 `请输入 FTP 端口` 这种灰色文字只是 placeholder，实际端口要靠 `netstat -tlnp` 或 `ss -tlnp` 在设备 shell 里看监听情况。
+4. **Mac 上的 curl 会走 socks5 代理**（很多人本机装了 ClashX/Stash 之类），即便连 `127.0.0.1` 也会被代理"劫持"导致 connect timeout。**必须加 `--noproxy '*'`** 或先 `unset all_proxy http_proxy https_proxy ALL_PROXY HTTP_PROXY HTTPS_PROXY`。
+
+## 实操案例：连接 FtpNextServer
+
+设备上 FtpNextServer 应用（`com.develop.opensource.ftpnext_server`）的实际服务进程是 **proftpd**，监听三个端口（**不是 21/22/990**，要从 netstat 实测）：
+
+| 协议 | 默认实际端口 | 备注 |
+|---|---|---|
+| FTP   | 60021 | 控制通道 |
+| SFTP  | 60022 | SSH 通道，单一端口 |
+| FTPS  | 60023 | TLS over FTP |
+
+工作目录默认是 `/storage/Users/currentUser/Desktop`（电脑端逻辑路径，对应 hdc shell 的 `/storage/media/<userId>/local/files/Docs/Desktop`）。
+
+### 步骤
+
+```bash
+# 1. 建立端口转发（一次即可，hdc 重启会丢）
+hdc -t <serial> fport tcp:60022 tcp:60022
+hdc fport ls   # 验证
+
+# 2. SFTP 登录（推荐，单端口够用）
+sftp -P 60022 ohos@127.0.0.1
+# 输入密码，进入后 ls/get/put 都正常
+```
+
+### ⚠️ FTP 协议的 PASV 数据通道坑
+
+如果非要用 FTP（60021）而不是 SFTP，会**列目录直接失败**：
+
+```text
+< 229 Entering Extended Passive Mode (|||50226|)
+* connect to 127.0.0.1 port 50226 failed: Connection refused
+```
+
+**原因**：FTP 的 PASV 模式要求客户端再开一条数据连接到 server 通告的随机端口（FtpNextServer 默认被动端口范围 50000~51000）。这 1000 个端口都没经过 hdc fport 转发，所以连不上。
+
+**对策按优先级**：
+
+1. **首选用 SFTP（60022）**，没有数据通道问题，单连接搞定。
+2. 一定要用 FTP：在 FtpNextServer UI 把"被动端口"范围改小（例如 50000~50010），然后用脚本把这 10 个端口都 `hdc fport` 转一遍。
+3. 主动模式（`curl --ftp-port -`）在这里也不行，因为设备需要从 `100.125.50.84` 反连客户端，而 Mac 不在同一网段。
+
+## 自检/调试套路
+
+```bash
+# 设备 IP（wlan0）
+hdc -t <serial> shell "ifconfig | grep -A1 wlan0 | grep inet"
+
+# 设备上谁在监听哪些端口（认准 PID/Program Name 列）
+hdc -t <serial> shell "netstat -tlnp" | grep LISTEN
+
+# Mac 这一侧验证转发是否生效
+nc -zv 127.0.0.1 60022
+
+# 别忘了关代理（如果用 curl 测）
+curl --noproxy '*' -v ftp://user:pass@127.0.0.1:60021/
+```
+
+## Mac → 设备批量传文件的坑：tar 的 AppleDouble 元数据
+
+要把 Mac 上 git clone 下来的仓库整体推给设备（比如桌面 `C++/` 下放 `cpprestsdk`），推荐流程是：
+**打包 → `hdc file send` 单文件传到 `/data/local/tmp` → 设备上解压到目标路径 → 清理临时包**。
+13MB 的压缩包 hdc 大约 30MB/s，比 sftp put 整个目录快得多。
+
+⚠️ **macOS 的 `tar -czf` 默认会把文件的扩展属性（ResourceFork/Finder Info）以 AppleDouble 形式打包进去**，
+解压到非 macOS（鸿蒙、Linux）就会得到一堆 `._xxx` 影子文件（每个真实文件旁边都有一份）。
+两种对策（任选）：
+
+```bash
+# 方案 A：打包前禁用 macOS 元数据（推荐）
+COPYFILE_DISABLE=1 tar -czf cpprestsdk.tar.gz cpprestsdk
+# 或 GNU/bsd 现代 tar 也支持 --no-mac-metadata
+
+# 方案 B：先按默认方式打包传过去，解压后在设备侧扫一遍清理
+hdc -t <serial> shell "cd /目标路径 && find . -name '._*' -type f -delete"
+```
+
+完整套路示例：
+
+```bash
+# Mac 端
+COPYFILE_DISABLE=1 tar -czf /tmp/repo.tar.gz repo
+hdc -t <serial> file send /tmp/repo.tar.gz /data/local/tmp/repo.tar.gz
+
+# 设备侧（hdc shell 路径是真实路径，不是逻辑路径）
+hdc -t <serial> shell "cd /storage/media/<userId>/local/files/Docs/Desktop/C++ \
+  && tar -xzf /data/local/tmp/repo.tar.gz \
+  && rm /data/local/tmp/repo.tar.gz"
+```
+
+## 相关
+
+- [鸿蒙PC-进程视角与mount-namespace.md](鸿蒙PC-进程视角与mount-namespace.md) — 文件系统跨域用 nsenter；本文是网络跨域用 fport。两套机制独立。
+- [[鸿蒙PC-应用沙箱与物理路径映射]] — 桌面物理路径映射，FtpNextServer 工作目录就是桌面。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/345/256/232/345/210/266git/350/241/214/344/270/272.md

@@ -0,0 +1,65 @@
+---
+name: 鸿蒙PC-定制git行为
+description: 鸿蒙改了 global gitconfig 路径到 `$HOME/.ohos_git/.gitconfig`，跨 uid 仓库需要 `safe.directory` 放行
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：定制 git 行为
+
+## 已知与上游不同的点
+
+### 1. global gitconfig 路径被改了
+鸿蒙 PC 上 HNP 装的 git 把 `--global` 配置文件改成：
+```
+$HOME/.ohos_git/.gitconfig
+```
+不是标准的 `~/.gitconfig`。
+
+验证方法：
+```bash
+git config --global --list   # 会报 unable to read '$HOME/.ohos_git/.gitconfig'
+```
+
+写入 global 配置要写到这个位置；直接放 `~/.gitconfig` **无效**。
+
+### 2. safe.directory 跨 uid 拦截
+鸿蒙 PC 上 file_manager 服务（uid 20001006）拥有桌面/HOME 下所有文件，
+应用进程一般是其它 uid（如 OpenCode 是 20020107）。Git ≥ 2.35.2 的
+[CVE-2022-24765](https://github.blog/2022-04-12-git-security-vulnerability-announced/)
+防御会拒绝跨 owner 的仓库：
+```
+fatal: detected dubious ownership in repository at '/storage/.../xxx'
+```
+
+修复（**必须在应用 namespace 下执行**，因为要写到应用 HOME 的 `.ohos_git/`）：
+```bash
+nsenter -t <pid> -m -- env HOME=/storage/Users/currentUser \
+  /data/service/hnp/bin/git config --global --add safe.directory '*'
+# 或显式列举：
+#   --add safe.directory /storage/Users/currentUser/Desktop/node/<repo>
+```
+
+写出来的文件长这样：
+```
+$ cat /storage/Users/currentUser/.ohos_git/.gitconfig
+[safe]
+	directory = *
+```
+**别用 printf 手拼**——常见踩坑是把 `\n`、`\t` 当字面量写进去，git 会报
+`bad config line 1 in file ...`。要么用 `git config` 命令，要么写 here-doc。
+
+## 验证修复链路（OpenCode 等 HNP web 应用同样适用）
+```bash
+nsenter -t <pid> -m -- env HOME=/storage/Users/currentUser \
+  /data/service/hnp/bin/git -C <repo> rev-parse --is-inside-work-tree
+# 期望: true
+
+nsenter -t <pid> -m -- env HOME=/storage/Users/currentUser \
+  /data/service/hnp/bin/git -C <repo> status --short
+```
+
+## 持久性提醒
+`.ohos_git/.gitconfig` 写在 hmdfs 用户视图里，**应用更新或恢复出厂会丢**。
+桌面项目反复出现"非 git 仓库"误判时，重跑同样命令即可。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/345/272/224/347/224/250/346/262/231/347/256/261symlink/347/246/201/344/273/244/344/270/216aa/346/215/242/344/273/243/350/257/255/344/271/211.md

@@ -0,0 +1,63 @@
+---
+name: 鸿蒙PC-应用沙箱symlink禁令与aa换代语义
+description: OHOS 应用沙箱内 symlink() 返回 EACCES（安全策略，rootless 进程创建符号链接被禁）——依赖 symlink 的功能/单测须按平台限制豁免或改 hardlink/复制；'aa start' 对已存 Ability 只拉前台不重建（napi 侧不会重跑用例），换代重测必须 bm uninstall + bm install 冷启动；'aa force-stop' 在部分零售镜像报 10104002 不可用。触发词：symlink、EACCES、Permission denied、ln -s、符号链接、aa start 不重跑、force-stop、10104002、冷启动、重装、旧实例、Ability 复用、只拉前台
+metadata:
+  type: platform
+  source: new/PC（杀毒引擎单测 symlink 用例 + 阶段 6 逐用例拉起实证，2026-09-07）
+---
+
+# 鸿蒙 PC：应用沙箱 symlink 禁令与 aa 启动的换代语义
+
+> 两条高频踩坑的 app 域行为差异：**文件系统层 symlink 被禁**、**aa 启动是「换代
+> 不重跑」**。都是「在宿主/Linux 上天经地义、到沙箱里静默变质」的典型。
+
+## 一、应用沙箱内 symlink() 直接 EACCES
+
+app 域进程（rootless uid）调用 `symlink(target, linkpath)` 返回 `-1/EACCES`
+（安全策略，非路径权限问题——目标与链接都在自己可写目录里也一样）。影响面：
+
+- 依赖 symlink 的功能（wrapper 链接、版本目录切换、libcheck 单测里的
+  「替换符号链接」用例）在设备上**必失败**；
+- 单测处置：按平台限制豁免（exemptions 里归因 sandbox-policy，非适配缺陷）；
+- 功能替代：复制文件、或 hardlink（`link()` 可用性待各镜像验证，别赌）。
+
+注意与 hdc shell 域的区分：shell 域里 `ln -s` 走的是另一套策略（HMDFS 上另有
+E079 硬链接限制），不要拿 shell 域行为推断 app 域。
+
+## 二、aa start 只「拉前台」，不重新 onCreate
+
+`aa start -a EntryAbility -b <bundle>` 对**已在运行**的应用只把 Ability 拉到前台
+（onForeground），**不会销毁重建**——NAPI 侧的用例执行（通常挂在 onCreate/
+aboutToAppear）就此不会重跑。症状：明明改了 runner 代码重装了 HAP，启动后 hilog
+里却一条新的用例输出都没有；`ps -ef` 里进程 start 时间还是旧的。
+
+**换代重测的正确姿势**（按破坏性递增）：
+
+```bash
+# ① 首选：卸载重装（冷启动，最干净）
+hdc shell "bm uninstall -n <bundle>"
+hdc shell "bm install -p /data/local/tmp/<hap>"
+hdc shell "aa start -a EntryAbility -b <bundle> -m entry"
+
+# ② 'aa force-stop' 在零售镜像上常报错不可用（Error Code:10104002
+#    Failed to retrieve specified package information），别依赖它；
+#    报这个错 ≠ 应用没装，只是该命令路径失灵。
+```
+
+另：同 bundle 覆盖安装（不卸载）对已存进程同样「不重启」——设备上验证新产物，
+**uninstall + install 是唯一可靠序列**。
+
+## 三、逐用例拉起模式下的配套
+
+阶段 6 逐用例验证（`aa start --ps caseId <id>`）每次都依赖「新进程读新 caseId」：
+- runner 侧从 Want 参数取 caseId 后**落盘一份**（native 读不到 Want），
+  路径用应用私有沙箱 filesDir，每轮覆盖写；
+- 宿主侧若发现用例结果不更新，先 `ps -ef | grep <bundle>` 看进程 start 时间，
+  旧进程活着就是本条第二节的问题。
+
+## 相关
+
+- [[鸿蒙PC-HNP包与PATH]] `/data/app/bin/<tool>` 软链接是**安装器**（特权域）建的，
+  app 域只是使用方——与 app 自建 symlink 被禁不矛盾
+- E018（ln/symlink wrapper）是宿主/构建域的同族问题
+- [[鸿蒙PC-应用沙箱与物理路径映射]] 沙箱可写区总表（TEMP/TMPDIR/HOME 落点同篇）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/345/272/224/347/224/250/346/262/231/347/256/261/344/270/216/347/211/251/347/220/206/350/267/257/345/276/204/346/230/240/345/260/204.md

@@ -0,0 +1,79 @@
+---
+name: 鸿蒙PC-应用沙箱与物理路径映射
+description: 鸿蒙应用沙箱路径与系统/hdc 视角物理路径的对应关系，以及据此在设备上稳健定位 HNP 运行时（如 Python 3.12）的方法。解决"hdc shell 在假设路径下找不到设备 Python"的问题——路径因设备/userId/安装方式而异，必须 discover 而非硬编码。
+metadata:
+  type: platform
+  source: 华为官方文档「应用沙箱目录」+ new/PC 实测
+---
+
+# 鸿蒙 PC：应用沙箱路径 ↔ 物理路径映射（定位设备运行时必读）
+
+## 核心机制（官方）
+
+- 每个应用有专属「应用沙箱目录」，**应用视角的「沙箱路径」与系统进程/hdc 视角的「物理路径」不同**，且**非 1:1**——沙箱路径**总是少于**系统视角可见的物理路径，部分物理路径在沙箱里没有对应。
+- **hdc shell 默认 root = 系统视角，看到的是物理路径**（更全）；应用进程看到的是沙箱路径（更少、被挂载隔离）。所以"应用装了某文件，但 hdc shell 在某路径找不到"往往是**看错了路径层**，不是没装。
+
+## 沙箱路径 ↔ 物理路径对照（官方表，摘要）
+
+| 应用沙箱路径 | 物理路径（hdc shell/系统视角） |
+|---|---|
+| `/data/storage/el1/bundle` | 应用安装包：`/data/app/el1/bundle/public/<PACKAGENAME>` |
+| `/data/storage/el1/base` | el1 数据：`/data/app/el1/<USERID>/base/<PACKAGENAME>` |
+| `/data/storage/el2/base` | el2 数据：`/data/app/el2/<USERID>/base/<PACKAGENAME>` |
+| `/data/storage/el1/database` | `/data/app/el1/<USERID>/database/<PACKAGENAME>` |
+
+> 关键：**应用安装包物理路径是 `/data/app/el1/bundle/public/<PACKAGENAME>`（是 `public`，不是 userId）**；而**数据目录**才带 `<USERID>`（主用户常见 100）。两者别混。
+
+## 鸿蒙 PC 的 HNP 运行时落地
+
+社区 Python/Node 等运行时是 HAP **启动器应用**，把完整运行时以 **public HNP** 形式落地、供命令行复用：
+- HNP public 物理路径（实测设备）：`/data/app/el1/bundle/<USERID>/hnppublic/...`（如 `.../hnppublic/python.org/python_3.12`、`.../hnppublic/bin/python3.12`）。**USERID 因设备而异（常见 100，务必核实）**。
+- HNP 的 bin 会暴露进**用户交互 shell 的 PATH**（`/data/app/bin`、`/data/service/hnp/bin`）；但 **`hdc shell <cmd>` 是非登录 root shell，PATH 不含 HNP** → 直接 `python3.12` 报找不到，要用**绝对路径**或先 discover。
+
+## 稳健定位设备运行时（别硬编码路径！）
+
+> ⛔ **前置：下面这套探测在鸿蒙 PC 商用机上跑不出结果**——`/data/app/el1` 对 hdc shell（uid 2000）
+> 是 Permission denied，`/data/service/hnp` 根本不存在（2026-09-01 实测）。**探不到不是"没装"，
+> 是"够不到"**，两者绝不可混为一谈（这正是 jansi / git-lfs 那类假前提的来源）。
+> 商用机上设备侧要跑的运行时**一律随交付物自带成私有 HNP**，见
+> [[鸿蒙PC-设备语言运行时探测与供给]]。下面这套保留给够得到 `/data/app` 的环境。
+
+`hdc shell` 里按顺序探测（任一命中即用其绝对路径）：
+
+```bash
+# 1) 先确认 userId（数据目录下的数字目录名）
+hdc shell "ls /data/app/el1/bundle"                      # 看有没有 hnppublic / 数字 userId / public
+hdc shell "ls /data/app/el1"                              # 看 userId（如 100）
+
+# 2) 直接找可执行 / 库（最可靠，不依赖路径假设）
+hdc shell "find /data/app/el1/bundle -maxdepth 5 -name 'python3.12' -type f 2>/dev/null"
+hdc shell "find /data/app/el1/bundle -maxdepth 6 -name 'libpython3.12.so*' 2>/dev/null"
+hdc shell "find /data/app/el1/bundle -maxdepth 6 -name 'Python.h' 2>/dev/null"
+
+# 3) HNP 注册/链接位置
+hdc shell "ls -l /data/service/hnp/bin /data/app/bin 2>/dev/null | grep -i python"
+
+# 4) 安装包本体（确认启动器是否装了）
+hdc shell "ls /data/app/el1/bundle/public 2>/dev/null | grep -i python"   # 含 python launcher 包名即已装
+```
+
+- **找到** → 用其**绝对路径**做 `hdc file recv`（拉 include/python3.12 + libpython3.12.so）与运行验证。
+- **完全找不到** → 该设备**未安装 Python 3.12 HNP 启动器**（或版本不符）。这是**环境前置缺失**，不是适配缺陷：在 `03-adapt.json` 记 blocker「设备未装 Python 3.12 运行时，需先安装对应 HNP 启动器 HAP」，`status=partial`，产物仍交付。**不要**去 SDK 的 `llvm/python3`（那是工具链自带 3.11）凑数。
+
+## 相关
+- [[鸿蒙PC-进程视角与mount-namespace]]（root 看不到应用态文件时用 nsenter 进应用挂载视图）
+- [[鸿蒙PC-设备Python运行时]]（设备 Python ABI/site-packages 等细节）
+- [[鸿蒙PC-连接设备与hdc基础]]（hdc 连接/传输/跑测试）
+- [[鸿蒙PC-HNP包与PATH]]（HNP 如何进 PATH）
+
+## 渲染进程与主进程的沙箱不一致（Electron-OH 特有，2026-10-19 实证）
+
+> 上面是「应用 vs 系统视角」的沙箱映射；**Electron-OH 内部还有一层「主进程 vs 渲染进程」的权限差**（fontmoa 实证，详见 error-atlas L060）：
+
+- **主进程**：**不在 Chromium 沙箱内**——拥有完整 Node.js API 与应用沙箱权限，系统目录 `stat`/`open` 系统调用放行（鸿蒙官方口径 2026-10）——`readdir('/system/fonts')` 263 个字体可读（fontmoa 实证）；
+- **渲染进程**：**运行在 Chromium 沙箱中**——对系统目录的 `stat`/`open` 等文件系统系统调用被**沙箱策略拒绝（EACCES）**（鸿蒙官方口径）——**`readdir` 能列目录（755 + dir search 放行）、`stat`/`read` 文件 EACCES**（`renderer console[3]: Uncaught Error: EACCES: permission denied, stat ...`）；辅助观察：APPSPAWN 对子进程重新沙箱初始化时部分 private mount 失败（`/system/variant`、`storage/External` 等），与官方口径同向；
+- **结论**：渲染层要访问系统资源（系统字体目录、/vendor 等），**用官方 IPC 方案**——主进程
+  `ipcMain.handle('get-system-fonts'/'get-system-font-file'/'get-platform')` 提供列表/文件
+  Buffer/平台判定，渲染层 `ipcRenderer.invoke` 获取（渲染层不直接碰系统文件）；个别系统文件
+  对 app 域也 EACCES（如 Roboto-Regular.ttf）——IPC 读失败时跳过即可。
+- **纯 ArkTS 原生应用不适用**：无主/渲染进程二分，整个应用单一 app 域进程，系统资源权限由该进程 SELinux 域决定。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/345/272/224/347/224/250/346/262/231/347/256/261/344/270/264/346/227/266/347/233/256/345/275/225/350/257/255/344/271/211/344/270/216libcheck-TEMP/351/200/211/345/235/200.md

@@ -0,0 +1,91 @@
+---
+name: 鸿蒙PC-应用沙箱临时目录语义与libcheck-TEMP选址
+description: OHOS musl 把 tmpfile() 改写到 /data/local/tmp/tmpfile_XXXXXX（应用沙箱不可写），P_tmpdir 同值；libcheck（check_msg.c）fork 通信临时文件选址优先级 TEMP > P_tmpdir > TMPDIR > '.'——设备跑 libcheck 单测必须给子进程设 TEMP 指可写沙箱目录，否则 mkstemp 失败 eprintf exit(2) 且 stdout 无任何用例输出。触发词：libcheck、check_clamav、check_msg.c、Unable to create temporary file for communication、exit 2 无输出、单测不输出、mkstemp、tmpfile、P_tmpdir、TEMP、TMPDIR、/data/local/tmp 不可写、fork 通信
+metadata:
+  type: platform
+  source: new/PC（杀毒引擎 CLI 全家桶 libcheck 单测设备实跑实证，2026-09-07）
+---
+
+# 鸿蒙 PC：应用沙箱的临时目录语义与 libcheck 的 TEMP 选址
+
+> 平台约束：**任何把「临时文件落哪」交给 libc 默认值的程序，在 OHOS 应用沙箱里都可能
+> 静默失败**。默认落点 `/data/local/tmp` 对 app 域不可写，而主流库的临时目录选址
+> 环境变量优先级各不相同——设错变量等于没设。
+
+## 一、OHOS musl 的 tmpfile/P_tmpdir 都指向 /data/local/tmp
+
+OHOS 的 musl（third_party_musl）把 `tmpfile()` 硬编码改写到
+`/data/local/tmp/tmpfile_XXXXXX`（上游 musl 是 `/tmp`），`P_tmpdir` 宏同值。
+`/data/local/tmp` 是 shell/debug 域地盘，**app 沙箱进程 open 它直接 EACCES**——
+`tmpfile()` 返回 NULL。应用沙箱里也不存在 `/tmp`（sandbox 配置只给
+CUSTOM_SANDBOX_HAP 特权应用挂 /tmp）。
+
+## 二、libcheck 的选址优先级：TEMP > P_tmpdir > TMPDIR > '.'
+
+libcheck（Check 单测框架）fork 模式的父子通信临时文件（`check_msg.c` 的
+`open_tmp_file()`）按序取：
+
+```c
+tmp_dir = getenv("TEMP");        // ① Windows 风格变量，优先级最高
+#ifdef P_tmpdir
+if (!tmp_dir) tmp_dir = P_tmpdir; // ② OHOS 上 = /data/local/tmp（不可写！）
+#endif
+if (!tmp_dir) tmp_dir = getenv("TMPDIR");  // ③ 常规 Unix 变量
+if (!tmp_dir) tmp_dir = ".";               // ④ 当前目录兜底
+mkstemp("<tmp_dir>/check_XXXXXX")
+```
+
+**关键陷阱**：只设 `TMPDIR` 没用——`P_tmpdir` 在 OHOS 上有定义且优先级更高，
+把 ③ 挡死了。失败路径：`mkstemp` EACCES → `eprintf("Unable to create temporary
+file for communication...")` → **exit(2)**，且此时一个测试用例都还没跑，stdout
+往往只剩一行框架 banner（缓冲输出可能全丢）——表现为「rc=2、无输出、像玄学崩溃」。
+
+## 三、修复（一行）
+
+给单测进程（及其 fork 出的子进程）设 `TEMP=<可写沙箱目录>`：
+
+```c
+// runner（NAPI fork+execv 载体）里，exec 前统一设：
+setenv("TEMP", cwd.c_str(), 1);    // cwd = /data/storage/el2/base/haps/entry/files/<run-dir>
+setenv("TMPDIR", cwd.c_str(), 1);  // 顺手设上，覆盖其他库的常规路径
+```
+
+验证：修复后 libcheck 正常输出 `Running suite(s): ...` 与 `xx%: Checks: N,
+Failures: M`；若仍 exit(2)，抓 stderr 看 `check_msg.c` 行号。
+
+## 四、推广：三类常见临时目录策略的对症
+
+| 程序行为 | OHOS 沙箱里的结果 | 对策 |
+|---|---|---|
+| `tmpfile()` / `P_tmpdir` 直用（musl 硬编码 /data/local/tmp） | EACCES / NULL | 无法用 env 重定向的，需程序自己改路径或预建不了（只读区）——只能改代码 |
+| `mkstemp("$TMPDIR/…")`（读 TMPDIR） | 未设 TMPDIR 时多回退 `/tmp`（不存在） | 设 `TMPDIR=<沙箱可写目录>` |
+| Windows 风格 `TEMP`/`TMP` 优先（libcheck、部分 Perl/Python 荧惑） | 同上 | 设 `TEMP`（及 `TMP`） |
+
+**实践**：app 域执行器把 `HOME/TMPDIR/TEMP` 三件套统一指到
+`/data/storage/el2/base/haps/entry/files/<run-dir>` 一劳永逸。
+
+## 相关
+
+- [[鸿蒙PC-应用沙箱与物理路径映射]] 沙箱路径总表
+- [[鸿蒙PC-POSIX-NDK能力探针矩阵]] mkstemp/tmpfile 能力面
+- `pc-error-atlas` E002（configure 阶段 TMPDIR）是同一主题在构建期的镜像
+
+## 五、测试套预判清单：真机跑官方测试套前的快速排查
+
+真机跑 C 库测试套前，**先 grep 源码**预判临时目录相关失败，省去设备上线→发现失败→排查→修代码→重打包的 1~2 轮返工：
+
+```bash
+# 在 source/ 目录运行
+grep -rn 'tmpfile\(' --include='*.c' --include='*.h'
+grep -rn '"/tmp' --include='*.c' --include='*.h'
+grep -rn 'mkdtemp' --include='*.c' --include='*.h'
+grep -rn 'P_tmpdir' --include='*.c' --include='*.h'
+```
+
+命中后：
+1. **确定失败模式**：`tmpfile()` 硬编码 /tmp（musl 改写为 /data/local/tmp）→ 返回 NULL（EACCES）；`mkdtemp("/tmp/...")` 同理 → 创建失败。
+2. **注意静默吞断言**：setjmp/longjmp 或 `abort()` 被 signal handler 吞掉时，测试可能返回 rc=1 但无任何 stderr 输出（不是「挂住」也不是「通过」——是断言失败被吞了）。排查时先用 `TMPDIR=<沙箱可写目录>` 跑一次，看退出码变化。
+3. **补丁模式**（libetpan 实证 0001）：`tmpfile()` 回退为 `TMPDIR/mkstemp + fdopen("w+b") + unlink`，确保 TMPDIR 由 runner 注入。
+4. **生成用例也要预查**：阶段 2 补写的用例可能硬编码 `/tmp`（libetpan 实证 4/16 生成用例 mkdtemp 写死 /tmp/libetpan-*），应在生成时 lint 拦截。
+
+**阳性对照**：先用一个已知干净的文件（如简单的 `printf("hello\n")` 的二进制）确认执行通道本身没问题，再排查临时目录问题——避免把通道问题误判为临时目录问题。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/347/234/237/346/234/272SIGSEGV/344/270/211/346/256/265/345/256/232/344/275/215/346/263/225/344/277/241/345/217/267/347/274/226/347/240/201ucontext/347/246/273/347/272/277/347/254/246/345/217/267/345/214/226.md

@@ -0,0 +1,121 @@
+# 真机 SIGSEGV 三段定位法：信号编码 → ucontext handler → 离线符号化 + 契约/反汇编核对
+
+> 面向场景：**C/C++ 库的 CLI 测试 ELF 在 OHOS app 域 execv 后信号终止，如何从 rc 码到根因逐层剥离**。
+
+## 方法概述
+
+```mermaid
+graph TD
+    A[execv 后 rc=-10NN] --> B[信号 NN 确定崩溃类型<br>SIGSEGV/SIGABRT/SIGBUS...]
+    B --> C[用例内挂 handler<br>ucontext 取 fault_addr/PC/LR/x0]
+    C --> D[离线符号化<br>llvm-addr2line + objdump]
+    D --> E[对照 API 头文件契约<br>判断归因: 测试侧 vs 库侧]
+```
+
+## Step 1: 信号号编码
+
+CLI 执行器（cli-hnp-runner）统一将信号终止编码到退出码中：
+
+| 退出码 | 含义 |
+|--------|------|
+| `rc=0` | 正常退出 |
+| `rc=-2` | 信号 2（SIGSEGV 或 SIGINT，看上下文） |
+| `rc=-6` | 信号 6（SIGABRT） |
+| `rc=-11` | 信号 11（SIGSEGV） |
+| 约定 | `rc = -10 * NN` 或 `rc = -(100 + NN)` |
+
+**注意**：musl/OHOS 上 SIGSEGV = 11，但某些执行器用 `WTERMSIG(status)` 取值后可能编码不同。实证中 test_gen_renderer rc=-2（无输出），经 ucontext handler 回显确认为 SIGSEGV——信号 11 在 -10NN 编码下映射为 -110 而非 -2，实操以 WTERMSIG 为准。
+
+## Step 2: ucontext handler 取现场信息（关键一步）
+
+在用例的 main 函数开头挂 handler：
+
+```c
+#include <signal.h>
+#include <ucontext.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+static void sigsegv_handler(int sig, siginfo_t *info, void *ucontext_raw) {
+    ucontext_t *uc = (ucontext_t *)ucontext_raw;
+    fprintf(stderr, "=== SIGSEGV ===\n");
+    fprintf(stderr, "fault_addr=%p\n", info->si_addr);
+    fprintf(stderr, "PC=0x%lx\n", uc->uc_mcontext.pc);
+    fprintf(stderr, "LR=0x%lx\n", uc->uc_mcontext.regs[30]);
+    fprintf(stderr, "SP=0x%lx\n", uc->uc_mcontext.sp);
+    fprintf(stderr, "x0=0x%lx\n", uc->uc_mcontext.regs[0]);  // 第一参数
+    _exit(139);
+}
+
+int main(void) {
+    struct sigaction sa = {
+        .sa_sigaction = sigsegv_handler,
+        .sa_flags = SA_SIGINFO,
+    };
+    sigaction(SIGSEGV, &sa, NULL);
+    sigaction(SIGABRT, &sa, NULL);
+    // ... 逻辑代码
+}
+```
+
+**关键寄存器含义**：
+- `PC`：崩溃发生的指令地址
+- `LR`（x30）：返回地址（调用链中谁调了崩点）
+- `x0`：第一参数（看是否是 NULL 入参导致的 NULL 解引用）
+- `fault_addr`：SIGSEGV `si_addr` 字段，`SEGV_MAPERR=MAPERR`（非映射地址）vs `SEGV_ACCERR`（无访问权限）
+
+## Step 3: 离线符号化
+
+```bash
+# 查看二进制符号表
+llvm-nm -C build/ohos/test_gen_renderer | grep <PC附近符号>
+
+# addr2line 将 PC 地址转源码位置（注意去掉 ASLR 偏移）
+# 如果可执行是 PIE，需要确认二进制基址
+llvm-addr2line -e build/ohos/test_gen_renderer -a 0x<PC>
+
+# 反汇编看崩点上下文
+llvm-objdump -d build/ohos/test_gen_renderer --start-address=0x<PC-0x10> --stop-address=0x<PC+0x10>
+```
+
+**反汇编核对要点**（来自实证）：
+```
+# 空指针解引用模式：ldr x0,[x0,#24]  → x0=0 → fault_addr=0x18
+  3578: mov x0, xzr           # x0 = NULL
+  │
+  └─→ 跳入 .so 的 image_cleanup
+      ldr x0, [x0, #24]      # 访问 NULL+24 = 0x18 → SIGSEGV
+```
+
+`fault_addr=0x18` + 操作数 `[x0, #24]` + x0=0 → **NULL 入参无保护，且头文件契约不保证 NULL 容忍** → 归因为测试侧，不是库缺陷。
+
+## 归因判定树
+
+```
+SIGSEGV 信号终止
+├─ fault_addr 很接近 0 (0x10/0x18/0x28)
+│  ├─ 入参为 NULL → 查 API 头文件契约是否保证 NULL 容忍
+│  │  ├─ 头文件/源码未特别说明 → 归因: 测试侧（契约外断言）
+│  │  └─ 头文件/源码有 NULL 守卫说明 → 归因: 库侧（NULL 保护缺漏）
+│  └─ 非 NULL 入参 → 指针损坏/越界
+│     ├─ 偏移量计算错误（手搓数据）→ 归因: 夹具数据错误
+│     └─ 内存踩踏（越界写）→ 归因: 缓冲区溢出/生命周期
+├─ fault_addr 为合理地址 (0x7xxx...)
+│  ├─ 访问对象已析构 → use-after-free → 库侧
+│  └─ 执行了 UB 指令（sigill）→ musl 分歧
+└─ 无输出（main 之前崩）
+   └─ init_array 期崩溃
+      └─ 对比 DT_NEEDED → C TU 缺 libc++_shared → 测试侧
+```
+
+## 适用性
+
+适用于任何 C/C++ 库 CLI ELF 在 OHOS 真机信号终止的定位。本方法一次实证拆解了三段截然不同的根因（TU 形态 init 崩溃 / 手搓数据 decode 崩 / 契约外 NULL 断言崩），验证了此方法的对抗能力。
+
+## 关联
+
+- E159：纯 C TU 链接 C++ 实现 .so 在 OHOS 上 init 期信号终止
+- E160：生成测试的断言必须锚定 API 契约——契约外 UB 断言真机必崩且不是库缺陷
+- `pc-knowledge-base/adaptation/鸿蒙PC-libaribcaption-字体渲染C++库交叉编译与设备全量验证.md`
+
+<!-- src: repos-pc/某库 适配实证（2026-09-15） -->

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/347/234/237/346/234/272/350/267/221/345/256/230/346/226/271/346/265/213/350/257/225/345/245/227/344/273/266.md

@@ -0,0 +1,53 @@
+---
+name: 鸿蒙PC-真机跑官方测试套件
+description: 在鸿蒙PC 真机上跑三方库官方测试套件（Python pytest / Rust cargo test / C++ UnitTest++）的套路与失败归因方法
+metadata:
+  type: platform
+  source: new/PC
+---
+
+适配完一个库，"编译过 + 冒烟过"不等于"官方测试套件过"。本条沉淀**怎么把各语言的官方测试套件真正在设备上跑起来**，以及**怎么把失败归因**（真实平台缺陷 vs 测试框架/环境/可选依赖）。本轮 9 库实测，~6100+ 官方用例真机通过，只有 1 处真实平台缺陷。
+
+> ## 前置：**怎么把测试送上设备并跑起来**
+>
+> 下面各语言的「`hdc file send` 推上去 → `./<testbin>` 直接跑」是**旧传输姿势**，在鸿蒙 PC 上不成立：
+> hdc shell 是 uid 2000，`/data/local/tmp` **可写但不可执行**（noexec + 代码签名）。
+> **正解**：测试可执行与其依赖 `.so` 打成**私有 HNP**，随执行器 HAP 装机，在 app 域 `fork/execv` 跑，
+> 输出经 hilog 回传——`ohpt-agent scaffold --kind cli-hnp-runner`
+>（机制见 [[鸿蒙PC-app域执行二进制与JIT限制]]，取证顺序见 [[鸿蒙PC-hdc能力边界与取证通道]]）。
+>
+> **传输方式换了，下面的归因方法与各语言的用例组织方式一个字都不用改**——它们与怎么送上设备无关。
+
+## 通用原则：失败必须逐一归因
+
+测试失败先分三类，别一律当"库坏了"：
+1. **真实平台缺陷**——被测库在鸿蒙PC 上算错/崩。要修或记已知限制。
+2. **测试框架/环境**——pytest 版本、缺测试依赖、fixture、只读目录。换环境就过。
+3. **交叉编译测试产物**——测试硬编码构建机路径、需要在 host 跑的东西。结构性，非功能。
+曾以为的"唯一真实缺陷"PyWavelets 复数 CWT（4/1037）**后来定位清楚并不是 musl libm/FFT 精度，而是设备 numpy wheel 自带 OpenBLAS 在 armv8sve 上的复数点积内核 bug**（`np.dot/convolve` 复数实部全错），设 `OPENBLAS_CORETYPE=ARMV8` 即修，整套变 1035/0/2。见 [[鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug]]。教训：误差"巨大且只错一半（实部/虚部）"是粗错信号，别一上来归因成"精度漂移"——必须上真机量出实际数字。其余几十上百个失败全是 2/3 类。
+
+## Python（pytest）
+
+- **pytest 版本要配库**：ipykernel 6.29.5 的测试用 nose 风格 `setup()` 模块函数，**pytest 8+ 已移除** → 全局 fixture（如全局内核 KC）不启动，一片 `NoneType` 假失败。**钉 pytest==7.4.4** 就从 23 failed 变 44 passed。教训：库老就用配套老 pytest。
+- **可写目录三件套**（见 [[鸿蒙PC-设备pip部署]]）：`HOME=/data/local/tmp/home TMPDIR=/data/local/tmp MPLCONFIGDIR=/data/local/tmp/mpl`，外加 pytest cache：`-p no:cacheprovider`（否则写只读 `/` 失败）。
+- **可选依赖**：python-control 缺 slycot → 极点配置类测试失败；属环境，不是平台。能装就装，不能装就 `--deselect`/`--ignore` 并在报告里说明。
+- 包要可 import：装进 site-packages 或 `PYTHONPATH`；测试数据目录（如 pywt/tests/data）要一起推。
+
+## Rust（cargo test 跨机）
+
+- `cargo test --target aarch64-unknown-linux-ohos --release --no-run` 只编不跑 → 产物在 `target/.../release/deps/<crate>-<hash>`（挑没 `.d` 后缀的 ELF）→ 连同依赖打进私有 HNP、由执行器 HAP 跑（见上方前置；`LD_LIBRARY_PATH=/system/lib64` 仍需带）。
+- **测试加载资源的路径坑**：
+  - cwd 相对路径（如 `examples/cert.crt`）→ 在设备对应 cwd 放好文件即可（quiche 传输层 949 个这样过的）。
+  - **`env!("CARGO_MANIFEST_DIR")` 烘焙的是构建机绝对路径**（Mac 的 `/Users/...`），`canonicalize().unwrap()` 在设备上 panic，且设备 `/` 只读无法重建 → 这类测试（quiche h3 80 个）在跨机执行下结构性失败，**不是功能缺陷**（HTTP/3 已端到端验证）。
+
+## C/C++（以 cpprestsdk Casablanca UnitTest++ 为例）
+
+- 测试架构常是"**测试模块 `.so` + 一个 test_runner，dlopen 加载**"。要 `-DBUILD_TESTS=ON` 重配 CMake（复用已编依赖），分别编 `<mod>_test`（→ `lib<mod>_test.so`）和 `test_runner`。
+- **测试 harness 可能依赖库本体没用到的东西**：cpprestsdk 库本身不用 boost::filesystem（OHOS 适配特意从 boost 组件里删了），但 test_runner 的 module loader 用它 → 链接报一堆 `boost::filesystem::detail::*` undefined。**补编 boost filesystem 单模块**（b2 `--with-filesystem`，复用现成 toolset），并把它加回 `find_package(Boost COMPONENTS ... filesystem)`。
+- 运行：把 `test_runner` + `lib<mod>_test.so` + `libcpprest.so` + `libunittestpp.so` + `libcommon_utilities.so` **一起打进私有 HNP**（见上方前置），在 app 域执行 `LD_LIBRARY_PATH=.:/system/lib64 ./test_runner lib<mod>_test.so`。
+- **CppUnit 1.15.x API 迁移**：上游套件按 CppUnit 1.10 写的失败处理代码在 1.15.1 下编不过——`thrownException()->message().shortDescription()` 返回 `std::string`（非 `const char*`）、`sourceLine().lineNumber()` 返回 `int`（非 `long`）、`sourceLine().fileName()` 返回 `std::string`（需 `.c_str()`）。改调用方适配，别为套件降级 CppUnit。
+- 无网络模块（json/uri/utils/pplx）可直接全跑；网络模块（httpclient/listener/websocket）需起服务，用 demo 覆盖。
+
+## 归档
+
+关联：[[鸿蒙PC-hdc能力边界与取证通道]]、[[鸿蒙PC-设备pip部署]]、[[鸿蒙PC-Rust-BoringSSL-quiche]]、[[鸿蒙PC-C++库交叉编译要点]]、[[鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug]]。