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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/347/247/201/346/234/211HNP/346/211/223/345/214/205/344/270/216exec/345/271/263/345/217/260/345/267/256/345/274/202.md

@@ -0,0 +1,120 @@
+---
+name: 鸿蒙PC-私有HNP打包与exec平台差异
+description: 私有 HNP 是 app 域 exec 用户 ELF 的唯一正路，但「包里能 exec」取决于 zip 内文件 mode 正确 + 目录条目齐全，且随系统版本摆荡（6.0 展平目录且不贴 private_hnp_file → EACCES；6.1 正常）；hvigor 不收 entry/hnp 需 zip 注入。触发词：私有 HNP、cli-hnp-runner、hnpPackages、hnpcli、zipfile、ExternalAttributes、0667、可执行位丢失、EACCES、execve、9568407、9568409、injectHnp、HNP 真实路径、符号链接农场。 9568407、9568409、9568269、injectHnp、HNP 设备真实路径、安装器剥离首段路径、pkg 前缀、目录条目先行、hnp_zip.c、HnpUnZip、布局契约、DEFLATE、0x801101、8392961、fopen 父目录
+metadata:
+  type: platform
+  source: new/PC（多轮 CLI 交付形态交叉编译实证）
+---
+
+# 鸿蒙 PC：私有 HNP 的打包与 exec 平台差异
+
+> 平台机制：只要交付形态是 **cli**（要在鸿蒙上落可执行文件并跑），就得打**私有 HNP** 经 app 域
+> `fork/execv` 执行（hdc shell 直跑是红线，见 E129 / [[鸿蒙PC-app域执行二进制与JIT限制]]）。
+> 但「打出了 HNP」≠「装上去能 exec」——本文件把打包与系统版本两个真实坑一次讲清。
+
+## 一、为什么 exec 成败只看 zip 内 mode，而不是链接期签名
+
+在 6.1+ 设备上，私有 HNP 里的 ELF 能否被 execve，**唯一决定因素是 HNP zip 内文件的 Unix 权限位（mode）**：
+链接期 `-Wl,--code-sign` 对 exec 路径**并非必需**（签名是另一条独立约束，自签能过）。所以打包阶段
+把 mode 搞丢，是一切「伪 SELinux EACCES」的最常见根因。
+
+## 二、HNP zip 打包的正确姿势（执行位 + 显式目录条目 + LF）
+
+两个宿主都有丢 mode 的坑：
+
+| 宿主 | 坑 | 修法 |
+|---|---|---|
+| Windows `hnpcli.exe` | zip entry `ExternalAttributes` 未设 Unix 可执行位（owner 缺 `+x`，表现为 `0x1B70000` 丢执行位），app 域 symlink 农场 exec 报 EACCES | 换 Linux/macOS 宿主 `chmod +x` 后打包；或执行器加「直接路径回退」：绕过 symlink 农场，直接 `stat/access X_OK` 确认二进制可执行 |
+| Python `zipfile` | `writestr` 默认 `0600`、`zz.write` 从 `os.stat` 取 `0666`，都丢执行位 | 见下「正确姿势」 |
+
+**正确姿势（Python zipfile 打包私有 HNP）**：
+1. 显式写 `pkg/`、`pkg/bin/` 目录条目；
+2. 每个文件 `ZipInfo.external_attr = (0o100667 << 16)`（含 owner/group/other 的 `+x`），并用 `writestr(zi, data)`；
+3. `hnp.json` 用 LF 行尾。
+
+打包后自查：`unzip -l <x>.hnp` 看文件 mode（右列应是含 x 的 0667/0755 而非 0600/0666）。
+
+## 三、HNP zip 布局契约：安装器剥首段路径 + 不建父目录（9568407 根因）
+
+装机报 `code:9568407 Failed to install the HAP because installing the native package failed`
+时，先用 `hdc shell "hilog -x" | grep APPSPAWN_HNP` 抓真因。源码
+（appspawn `service/hnp/base/hnp_zip.c` 的 `HnpUnZip()`）对每个 zip 条目做两件事：
+
+1. **剥掉条目的第一段路径**（`bin/x` → 版本目录根的 `x`）——官方 `hnpcli pack` 打出的
+   包全带 `pkg/` 前缀，剥离后正好落回 `bin/x`/`lib/x`。**自制 zip 若不带 `pkg/` 前缀，
+   bin/lib 会被平铺进版本目录根**（rpath `$ORIGIN/../lib` 失配、`.so` 全错位），
+   `share/xx/yy.dat` 类深层文件落成 `xx/yy.dat`；
+2. **`fopen("wb")` 解包、不建父目录**——目录只在「zip 里有对应目录条目（名以 `/` 结尾）
+   且先于内容出现」时由 `mkdir` 建立。目录条目写在文件后面、或根本没写，
+   深层文件解包即 `0x801101`（打开失败）→ bm install 层报 9568407。
+
+**自打包三件套**（Python zipfile 等价 hnpcli）：① 全条目 `pkg/` 前缀（含 `hnp.json`，
+剥离后正好落 HNP 根）；② 目录条目先于其内容写入（os.walk 天然序，**内存构造的夹具
+必须显式补父目录条目**）；③ `zi.compress_type = ZIP_DEFLATED`（官方包全 DEFLATE，
+STORED 未验证且体积大三倍）。装机后设备侧布局：
+`/data/app/<name>.org/<name>_<ver>/{bin,lib,...}`，`/data/app/bin/<tool>` 默认软链可用。
+完整判别脚本与修复代码见 [[pc-error-atlas]] E134。
+
+## 四、6.0 vs 6.1 版本差异（同一条通道，拨一下就通/不通）
+
+app 域 exec 用户二进制**只有私有 HNP 一条通道**，但这条通道**随系统版本摆荡**：
+
+| 系统版本 | 表现 |
+|---|---|
+| HarmonyOS 6.0（如 HAD-W24） | HNP 安装器把 `bin/` 展开到版本目录根级且**不贴 `private_hnp_file` SELinux 标签**，`execve` 返回 `errno=13 Permission denied`（3 种包结构变体均穷尽） |
+| HarmonyOS 6.1.0.135 | 同一条通道 exec 成功 |
+
+**处置**：私有 HNP `execve` 报 EACCES 时，先核对设备系统版本（6.0 有标签缺陷、6.1 正常），
+再投入包结构变体尝试；归因 `testenv-limited`（非库缺陷），CLI 载体验证需设备 6.1+ 或平台修复。
+
+**`execv` 返回 127 ≠ 平台限制**（与 EACCES 是两种现象；6.0.0.130 两轮实证）：
+单轮 exec 失败不足以下「平台限制」结论——先 `realpath` 验证 HNP 是否落地（`/data/app/bin/`
+符号链接农场是否建成、能否解析到 `/data/app/<pkg>.org/<pkg>_<ver>/bin/<tool>`）、复跑装机
+时序后再归因。曾有一轮 execv 127 被记为「6.0.0.130 私有 HNP exec 不可用」，真实原因是当轮
+装机时序问题（农场未建好）；同 OS 版本复测 openssl CLI 经私有 HNP fork/execv 加解密往返
+rc=0。另注意 errno 可能因执行器自身缺陷（如 dprintf-after-close）未留痕，不能只凭返回码归因。
+
+## 五、HNP 真实路径 vs 符号链接农场
+
+私有 HNP 装上后，app 域视角下：
+- `/data/app/bin/<tool>` 是符号链接农场；部分按机型/版本**被创建成普通文件拷贝（非 symlink）**，
+  其标签可能不是 `private_hnp_file` → 从农场路径 exec 被拒。
+- 真实路径是 `/data/app/<pkg>.org/<pkg>_<version>/bin/<binary>`，标签正确。
+
+**处置**：执行器取路径时 `realpath()` 解到 HNP 真实路径（版本目录）再 exec，别停在 `/data/app/bin/`
+农场路径上。
+
+## 六、HNP 塞进 HAP：hvigor 不收，要 zip 注入
+
+`module.json5` 声明 `hnpPackages`（type=private）只是 schema 认，**DevEco 6.x 的 hvigor
+`assembleHap` 不会自动收 `entry/hnp/*.hnp`**——需自定义 hvigor task 在 `PackingCheck` 之后、
+`SignHap` 之前把 `hnp/` 目录 `zip` 注入 unsigned HAP。注入器必须**在条目缺失时新增而非仅替换**
+（只替换会报 `9568409` extract failed，因目标 hnp 条目尚未存在）。
+
+## 七、HAP libs/ 与 HNP exec 的互斥（同 bundle 死锁）
+
+同 bundle 内 `entry/libs/` 出现**自编交叉 .so**（任何名字、去不去 `.codesign`）会毒化 HNP ELF 的
+exec 白名单——装机 success + in-process dlopen 正常 + 所有 HNP ELF exec 即 SIGSEGV（零输出无
+faultlog）。反向：`libs/` 干净时 exec 正常，但 in-process dlopen 无 so 来源（HNP bin/ 直读与
+沙箱拷贝全被 loader 拒）。**cpp-lib 双载体混跑的唯一共存形态：全部用例走 exec（bin 型）**。
+完整判定矩阵与误诊形态（「XPM per-bundle」）见 `pc-test-design/references/demo-wiring-pc.md`
+CLI 形态档的「常见坑」。
+
+## 八、内容完整性：程序运行时读取的间接资源也要随包
+
+私有 HNP 不能只装「运行时二进制 + 被测代码」——程序运行时经模块加载链 / 相对路径 / 配置文件
+读取的**间接资源文件**（Node 的 `require` 链引用的脚本与配置、CLI 启动时要读的技能脚本等）也要
+一并 stage 进 HNP。只拷主程序而漏掉间接依赖时：第一加载路径失败 → 回退路径也不在 HNP → 报
+`MODULE_NOT_FOUND`（Node require）或「文件不存在」。
+
+pc-web-tool 真机实证：测试链 `require` 了插件工程 `skills/pc-workspace-layout/scripts/version-detector.cjs`
+（HNP 之外资源），漏打后设备侧 7 个测试文件共 9 条名册用例 `MODULE_NOT_FOUND`；在 build 脚本里
+自动定位插件工程、把技能脚本 stage 进 `hnp-data/plugin/skills/…` 后转 pass。
+
+**判据**：装包前静态扫一遍 `require`/资源引用路径，逐个确认其目标文件已落在 HNP 内。别指望设备上
+还有 HNP 之外的资源可读——app 域够不到宿主的任何东西，一切运行时依赖都得随包自足。
+
+## 相关
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— app 域 exec 的四道关 + seccomp 黑名单。
+- [[鸿蒙PC-HNP二进制SELinux-exec限制]] —— 公共 HNP 二进制 exec 限制（另一面）。
+- `pc-error-atlas` E129 —— 私有 HNP exec 被拒的完整解法入口。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/347/252/227/345/217/243/345/207/240/344/275/225/346/216/247/345/210/266/346/227/240native/345/217/252ArkTS.md

@@ -0,0 +1,30 @@
+---
+name: 鸿蒙PC-窗口几何控制无native只ArkTS
+description: 鸿蒙 NDK 不暴露窗口几何控制（resize/move/min/max/fullscreen），只 ArkTS @ohos.window 有；native 只能经反向桥回调 ArkTS。附 Qt QPA 实证 + OH_WindowManager_* 子集
+metadata:
+  type: platform
+  source: new/PC
+---
+
+> 平台机制，与具体库无关：任何三方 native 代码想**程序化控制自己宿主窗口的几何**（改大小/移动/最小化/最大化/全屏/大小限制）在鸿蒙上都撞这堵墙。2026-07-01 给 GLFW 补窗口控制时穷举 NDK + 查 Qt 源码定位。
+
+## 结论：几何控制没有 native NDK 路径，只有 ArkTS `@ohos.window`
+- **能力在内部 C++ 里**：`@ohos.window` 的 `Window` 是系统内部类 `OHOS::Rosen::Window`（设备 `/system/lib64/libwm.z.so` + `libwms_broker_*` 经 IPC 找窗管服务 WMS）；ArkTS 的 `resize/moveWindowTo/minimize/maximize/recover/setWindowLayoutFullScreen/setWindowLimits`（全 Promise）是它的薄 napi 绑定。
+- **NDK 刻意不暴露几何**：穷举整个 sysroot（含 `arkui/`、`ability`）——**无任何几何控制的公共 C 函数**。`grep -rE 'OH_.*（Resize|Move|Minimize|Maximize|FullScreen|SetWindowMode）'` 只命中无关的 AI/AVScreenCapture/PiP。
+- **内部 `libwm.z.so` 三方够不着**：它在 `/system/lib64/` 但**不在** `/system/lib64/ndk/`——app 的 NDK linker 命名空间只解析 `ndk/`，三方 `.so` 既不能链也不能 dlopen（命名空间隔离 + C++ ABI 不稳 + WMS 权限/IPC）。硬走会崩，不可移植。
+- **设计意图**：托管式 OS 把窗口几何收拢给框架/WMS（合成/平铺/权限），不给 native 直接杠杆——与「无 native createWindow」同源（见 [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]]）。
+
+## Qt 鸿蒙 QPA 实证（决定性）
+鸿蒙 Qt 的 QPA 插件（`qtbase/.../platforms/openharmony`）：成熟生产级 QPA 的窗口控制**全部经 napi 调 `@ohos.window`**，`OH_WindowManager_*` 几何 API **零使用**。持有一个 `QJsWindow`（ArkTS Window 对象的 napi 引用）直调其方法：`qohnormalwindow.cpp` 的 `call("resize",{w,h})`/`call("moveWindowTo")`/`call("setWindowLimits")`；`qohnativewindow.cpp` 的 `showFullScreen`=`call("setWindowLayoutFullScreen",true)`+`call("maximize",immersive)`、`showMaximized`=`call("maximize")`、`showMinimized`=`call("minimize")`。连 Qt 都没有 native 几何路径 → 反向桥到 ArkTS 是唯一受控正路。
+
+## 有 native API 的那一小撮（`libnative_window_manager.so` / `OH_WindowManager_*`, API15+）
+不含几何，但这些**能纯 native**：`LockCursor/UnlockCursor`（= 光标锁定/相对运动，**@since 22**）、`GetWindowProperties`（真实 pos/size/id/isTransparent，`WindowManager_WindowProperties`）、`SetWindowTouchable`（passthrough）、`SetWindowKeepScreenOn/Brightness/Focusable/BackgroundColor`、`GetAllMainWindowInfo`（枚举 windowId）。要 windowId：`GetWindowProperties` 需先有 id，用 `GetAllMainWindowInfo`（单窗口取 [0]）或让 ArkTS 传 `getWindowProperties().id`（`WindowProperties.id: number` 确认存在）下来。
+- **坑**：`window_manager/oh_window.h` 误 `#include <cstddef>`（C++ 专用），**纯 C 无法包含**。改只包 C 安全的 `oh_window_comm.h`（拿结构体）+ 手动前置声明用到的 C-ABI 函数（`nm -D libnative_window_manager.so` 确认符号无 mangling）；`oh_window_comm.h` 用了 `bool` 但没包 stdbool，需先 `#include <stdbool.h>`。
+
+## 三方库/工具包怎么补窗口控制（反向桥套路，已在 GLFW 落地真机验证）
+native 库调用 → OWB 反向通道 → 宿主 NAPI 用 **`napi_threadsafe_function`**（marshal 到 JS 线程/JS 上下文，Qt 的 safeExec 同理）→ 直调 ArkTS `@ohos.window` Window 对象的方法。ArkTS 侧经 **`XComponentController.getXComponentContext()`**（`ets/component/xcomponent.d.ts` 确认）把 mainWindow 对象 + windowId 交给 native（**不用 import .so**，避开 [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]] 说的 @types/.so 坑）。真机实测 `glfwSetWindowSize(900,600)`→窗口 rect 真变 `[.. 900 600]`、maximize→`[0 0 3120 2080]`、recover→还原。详见 [[鸿蒙PC-通用视窗桥ohos_window_bridge]]、[[鸿蒙PC-GLFW视窗后端-EGL-XComponent]]。
+
+## 相关
+- [[鸿蒙PC-通用视窗桥ohos_window_bridge]] —— OWB 反向通道 + 窗口控制原语。
+- [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]] —— XComponent 是像素通道；窗口是另一层（@ohos.window）。
+- [[鸿蒙PC-进程视角与mount-namespace]] —— app NS 只解析 `/system/lib64/ndk/`，内部库够不着的根由。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/347/272/257C-TU/350/260/203C++-so/345/234/250OHOS/344/270/212init_array/346/234/237/344/277/241/345/217/267/347/273/210/346/255/242.md

@@ -0,0 +1,82 @@
+# 纯 C TU 调 C++ .so 在 OHOS 上 init_array 期信号终止
+
+> 面向场景：**在 OHOS app 域 execv 后，进程在 main() 之前无输出信号终止（rc=-2），而同库的 C++ 等效用例全过**。
+
+## 现象
+
+```
+# 补写的纯 C API 测试
+test_gen_renderer: rc=-2     (无任何 stdout/stderr 输出)
+# 已有的 C++ 等价测试
+test_gen_cpp_renderer: rc=0  (正常输出 ALL PASS)
+```
+
+- `rc=-2`：CLI 执行器的信号终止编码（`-signal_number * 10`，即信号 2 = SIGSEGV 或信号终止）。
+- 进程无任何输出：崩溃发生在 main() 之前，动态链接 / init_array 阶段。
+- 两种 TU 在同一 C API 上表现分歧，但 TU 本身没有显式调用 C++ 特性（只调 C 头文件）。
+
+## 根因
+
+**纯 `.c` TU 通过 `extern "C"` 头调 C++ 实现的 .so 时，两人语言形态差异导致 DT_NEEDED 不一致：**
+
+| 对比项 | 纯 C TU (.c) | C++ TU (.cpp) |
+|--------|-------------|---------------|
+| DT_NEEDED | libaribcaption.so, libc.so | libaribcaption.so, **libc++_shared.so**, libc.so |
+| init_array | 无 C++ 初始化 | 含 C++ 构造函数/静态初始化 |
+| 加载器行为 | 不链入 C++ 运行时 | 正确链入 C++ 运行时 |
+
+纯 C TU 编译时编译器不插入 `libc++_shared.so` 的 NEEDED，而目标 .so 的 `.init_array` 中注册了 C++ 全局/静态对象的构造函数——这些构造函数依赖 C++ 运行时初始化。当 libc++_shared.so 不在 NEEDED 表中时，加载器**可能**不会按正确顺序初始化它（或未加载），导致在 `dlopen`/`execv` 后的 init_array 扫描期间引用未初始化内存 → 信号终止。
+
+**注意 musl/lld 环境下无 libstdc++ 垫片时该现象更易暴露。** 在标准 glibc/Linux 上，`libstdc++` 作为 system lib 可能已被其他 DT_NEEDED 间接拉入，掩盖了问题。
+
+## 诊断方法
+
+```bash
+# 对比两个测试 ELF 的 DT_NEEDED
+readelf -d build/ohos/test_gen_renderer     | grep NEEDED
+readelf -d build/ohos/test_gen_cpp_renderer | grep NEEDED
+```
+
+良性对照应显示 C++ TU 多出 `libc++_shared.so` 的 NEEDED，且 `libaribcaption.so` 在两只 ELF 的 NEEDED 中间（而非末尾——中间位置表示在 libc++_shared 之前/之后加载有确定性顺序）。
+
+## 解决方案
+
+**把测试 TU 改为 `.cpp` 扩展名 + 对应编译标准即可**，不必改任何源代码逻辑（C API 头文件已有 `extern "C"` 保护，从 .c 改为 .cpp 不需要改 API 调用）：
+
+```cmake
+# CMakeLists.txt 中
+# 改前
+add_executable(test_gen_renderer test_gen_renderer.c)
+target_compile_features(test_gen_renderer PUBLIC c_std_11)
+
+# 改后
+add_executable(test_gen_renderer test_gen_renderer.cpp)
+target_compile_features(test_gen_renderer PUBLIC cxx_std_17)  # 对齐项目标准
+```
+
+改后 DT_NEEDED 自动包含 `libc++_shared.so`，与已知良好的 C++ 等效用例全等。
+
+## 进阶排查（若改 .cpp 后仍然崩溃）
+
+若 C++ TU 化后仍崩溃，说明非 init_array 期问题，需进入 SIGSEGV 三段定位法：
+1. 执行器信号编码上报确认终止信号类型
+2. 用例内挂 SIGSEGV handler + ucontext 打 fault_addr/PC/LR
+3. 离线 `llvm-addr2line`/`objdump` 反汇编崩点，对照 API 契约归因
+
+## 误判模式
+
+- 以为库逻辑有 bug，反复改库代码（其实同 C API 的 C++ 等效用例全过）
+- 怀疑是 musl/架构问题（其实是编译器对 TU 语言形态的 DT_NEEDED 推导差异）
+- 怀疑是二进制部署问题（签名/路径/权限）——但这些不影响 init_array 期
+
+## 适用性
+
+所有 C++ 实现的库的 C API 测试在 OHOS 上真机运行时都适用。在上游测试已为 .cpp 的库中，**新补写/生成的 C API 测试必须用 .cpp 编译**，不可退到 .c。
+
+## 关联
+
+- E159（本条目对应的错误图谱编号）：纯 C TU 在 OHOS 上链接 C++ 实现 .so → init 期信号终止
+- `pc-knowledge-base/adaptation/鸿蒙PC-libaribcaption-字体渲染C++库交叉编译与设备全量验证.md`（实例）
+- 信号终止编码约定：`rc=-10NN` = 信号 NN
+
+<!-- src: repos-pc/某库 适配实证（2026-09-15） -->

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/350/203/275/345/212/233/345/255/230/345/234/250/346/200/247/344/273/245SDK/345/243/260/346/230/216/344/270/272/345/207/206.md

@@ -0,0 +1,86 @@
+---
+name: 鸿蒙PC-能力存在性以SDK声明为准
+description: 判「鸿蒙有没有 X 能力」的唯一权威是 SDK 自带声明语料（ets/api 的 .d.ts + NDK 头），不是插件知识库。ohpt-agent knowledge -s 的 [sdk-api] 档；@since/@permission/@syscap 三要素读法；语料不可用≠没有
+metadata:
+  type: platform
+  source: extract-file-icon 案例（2026-07-31）
+---
+
+> 平台机制，与具体库无关：任何「鸿蒙没有 X 能力」的断言都适用。这类断言能一票终结适配流水线，
+> 所以它是**待证命题**而不是结论。
+
+## 结论：能力存在性问 SDK 声明，不问知识库
+
+**知识库/能力域库里没有 ≠ 鸿蒙没有。** 前者是本插件积累到哪儿了，后者是平台事实——两件事。
+
+判据语料是 SDK 自带的声明文件，每台装了 DevEco 的机器都有，机器可复核：
+
+| 语料 | 路径 | 规模（HarmonyOS 6.1.0 实测） |
+|---|---|---|
+| ArkTS 接口全集 | `$DEVECO_SDK_HOME/**/ets/api/**/*.d.ts` + `ets/kits/*.d.ts` | 764 个文件 |
+| NDK C API 全集 | `$DEVECO_SDK_HOME/**/native/sysroot/usr/include/**/*.h` | 1989 个文件 |
+| 合计声明 | | 16146 条，全量检索 **0.5 秒** |
+
+```bash
+ohpt-agent knowledge -s "<能力关键词/域名>"    # 知识库 + [sdk-api] 档一次出
+```
+
+`[sdk-api]` 档按**声明标识符**匹配（不是全文），命中给 `文件:行 + 声明原文 + @since + @permission`。
+
+## 三要素读法：命中 ≠ 够得着
+
+拿到命中先核三件事，缺一不可：
+
+1. **`@since`** —— 对不对得上目标设备。设备侧 `hdc shell param get const.ohos.apiversion`
+   （实测可调试鸿蒙 PC OpenHarmony 6.1.0.115 → **23**）。`@since 5.0.5(17)` 表示 API 17 起。
+2. **`@permission`** —— 普通应用够不够得着。查 `permissions_full.json` 的 `permission_level`：
+   - `normal` + `system_grant` → **声明即得**，不弹窗、不需要 `requestPermissionsFromUser`
+   - `system_basic` / `system_core`，或 `permission_type=restricted` → 需 ACL，**三方应用申不到**
+   - `user_grant` → 要弹窗授权
+   实证对比：`ohos.permission.GET_FILE_ICON` 是 open/system_grant/**normal**（能用）；
+   `ohos.permission.GET_ABILITY_INFO` 是 restricted/**system_basic**（够不着）。
+3. **`@syscap` + 设备形态** —— 文档里的 `Phone/PC/2in1/Tablet` 标注；有的 API 写明
+   「仅在 PC/2in1 中可正常调用，其他设备返回 201」。
+
+## 「语料不可用」与「未命中」是两回事
+
+没装 DevEco / `$DEVECO_SDK_HOME` 没设 → `ohpt-agent knowledge -s` 会明确打
+`[sdk-api] 语料不可用`，**不是**「无命中」。把「没得查」当成「没有」正是本篇要消灭的假阴性。
+门禁与验收在语料不可用时静默跳过——宁可不判，不可错判。
+
+## 分档：ArkTS 有 / native 无
+
+鸿蒙相当一部分能力**只在 ArkTS 侧**，NDK 刻意不暴露。native 库撞上时不是「不可行」，
+是**交付形态要迁移**（或反向桥回 ArkTS）：
+
+| 能力 | native | ArkTS | 出处 |
+|---|---|---|---|
+| 窗口几何控制 | 无 | `@ohos.window` | [[鸿蒙PC-窗口几何控制无native只ArkTS]] |
+| 系统文件图标 | 半条（`OH_Utd_GetIconFile` 只给资源名） | `fileManagerService.getFileIconSync` | `pc-capability-domains/system-file-icon.md` |
+
+判 `infeasible` 前先问：**是「换任何交付形态都做不到」，还是只是「原形态做不到」？** 后者是
+`feasible_with_effort` + 形态迁移。
+
+## 实证：这条不变量是怎么来的
+
+extract-file-icon 0.3.2 适配，阶段 1 判 `feasibility=infeasible`，B3 写「鸿蒙 PC 没有公开的系统文件
+关联图标查询能力」，gate 据此跳过阶段 2/3，全库零产物。
+
+复盘 `scan.log`：agent **查过**，正则是 `file.?icon|图标|icon|NSWorkspace|SHGetFileInfo|…`——
+但只 grep 了插件自带知识库。同一个词打到 SDK 声明语料上：**0.5 秒、4 条命中**，第一条就是
+`getFileIconSync`。不是模型偷懒，是**通道当时不存在**。
+
+真机复核（可调试鸿蒙 PC，OpenHarmony 6.1.0.115 / API 23）：最小 HAP 声明 `GET_FILE_ICON`，
+9 个后缀 **9/9 取到图标并真实上屏**。
+
+现在这条不变量由机器执法，两处同源判据：
+- 验收规则 `capability-absence-contradicted`（`harmony_status=unavailable` 与语料矛盾即告警）
+- `ohpt-agent gate` 的 infeasible 分支（矛盾则 `ask`，把签名摆给用户裁决）
+
+豁免走**已有的 `evidence[]`**：查过 SDK 后仍判不可用，就把命中的声明文件路径写进 evidence
+并说明为何不适用（权限 system_basic / @since 太高 / 语义不覆盖）。**路径编不出来，得真查才知道。**
+
+## 相关
+
+- [[鸿蒙PC-窗口几何控制无native只ArkTS]] —— 「能力在 ArkTS 侧，native 只能反向桥」的先例
+- [[鸿蒙PC-设备语言运行时探测与供给]] —— 同一不变量的**设备档**（「设备上没有 X」要标准位置探测痕迹）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/350/256/276/345/244/207Python/350/277/220/350/241/214/346/227/266.md

@@ -0,0 +1,58 @@
+---
+name: 鸿蒙PC-设备Python运行时
+description: 社区 Python 3.12 启动器 HNP 的安装路径、ABI（3.12.8/harmonyos-aarch64/.cpython-312.so）、pip 与预装包现状。⚠️ 商用机默认没装它、hdc shell 也够不到 hnppublic——这些 ABI 事实照样是自带 CPython 时的对齐依据
+metadata:
+  type: platform
+  source: new/PC
+---
+
+> ## ⚠️ 前置：商用机上够不到这个运行时
+>
+> 本篇记录的是**装了社区 Python 启动器的设备**上的事实。**鸿蒙 PC 商用机默认没有**；即便装了，
+> 它落在 `hnppublic`（`/data/app/el1/...`）——`hdc shell` 是 uid2000，**Permission denied**，
+> 既拉不到头文件也 exec 不了（2026-09-01 实测：无公共 HNP、用户目录下无 `usr`）。
+>
+> **所以设备侧要跑 Python，一律随交付物自带 CPython 私有 HNP**，见
+> [[鸿蒙PC-设备语言运行时探测与供给]] 与 [[鸿蒙PC-app域执行二进制与JIT限制]]。
+>
+> **下面的 ABI 事实与预装包清单仍然有用**——自带 CPython 时按同一套 ABI 对齐即可。
+
+某些设备上装有社区 Python 3.12 运行时（HAP 启动器，bundle 名 `com.develop.opensource.ohdpc.python.launcherforpython312`），把完整 CPython 以 **public HNP** 形式落地，用户在 HiShell 终端里直接 `python` 即可用。有它时可复用，不必从头重建 Python。
+
+## 关键路径（hnppublic，示例值——userId/层级因设备而异，**先探测勿硬编码**）
+
+> ⚠️ 下面的 `100` 是 **userId、因设备而异**。**别假设路径存在**——先按 [[鸿蒙PC-应用沙箱与物理路径映射]] 的「稳健定位」用 `find` 探出实际路径（`hdc shell` 看到的是物理路径视角，且 `/data/app` 对它不可读）。探不到 = 该设备未装 Python HNP 启动器 → 走 [[鸿蒙PC-设备语言运行时探测与供给]] 的判定程序（可部署则供给；确不可部署才记 blocker、`status=built-pending-verification`），别去 SDK 的 3.11 凑数。
+
+- python 根（下称 `$PYROOT`）：`/data/app/el1/bundle/<userId>/hnppublic/python.org/python_3.12`
+- 可执行（下称 `$PY`）：`/data/app/el1/bundle/<userId>/hnppublic/bin/python3.12`（**注意在 `hnppublic/bin`，不在 `python.org/` 下**；也有 `python`/`python3` 同目录）
+- 头文件：`$PYROOT/include/python3.12/Python.h`（设备上就有，交叉编译可拉到 Mac）
+- libpython：`$PYROOT/lib/libpython3.12.so` 和 `libpython3.12.so.1.0`
+- site-packages（**部署纯 Python 包 / 扩展 .so 的目标**）：`$PYROOT/lib/python3.12/site-packages`
+
+## ABI 事实（C 扩展交叉编译必须对齐）
+
+- 版本 **3.12.8**；`sysconfig.get_platform()` = `harmonyos-aarch64`（**无空格**，不踩 E036）
+- `EXT_SUFFIX` = `.cpython-312.so`，`ABIFLAGS` 为空 → 扩展文件名形如 `_pycosat.cpython-312.so`
+- libc = musl；交叉编译用 NDK clang `aarch64-unknown-linux-ohos-clang`
+
+## ⛔ 从 hdc shell 直呼这个 python：**商用机上走不通**
+
+`hnppublic` 在 `/data/app/el1/` 下，hdc shell（uid2000）**Permission denied**——既拉不到
+`Python.h`/`libpython3.12.so`，也 exec 不了解释器。**别在这条路上试探**，改为自带 CPython
+私有 HNP、由执行器 HAP 在 app 域跑（见上方前置）。
+
+> 一条与权限无关、自带运行时下同样适用的转义坑：**切勿把设备路径包成 `<…>` 尖括号**——
+> `<`/`>` 是 shell 重定向符，照抄即 `/bin/sh: syntax error`；先 `PY=<实际路径>` 再用 `$PY`。
+
+## 现成依赖（省去自己编）
+
+pip 24.3.1 可用，且**设备能联网 pip download**。已预装一大批含 C 扩展的包，重要的有：
+**numpy 2.2.1**、**Cython 3.0.11**、cffi 1.17.1、cryptography 44、bcrypt 4.2.1、av、Flask、contourpy/fonttools/matplotlib 系。
+→ PyWavelets 直接复用设备 numpy 头文件即可。**未装 pyzmq**（ipykernel 依赖，需另行解决，pyzmq 带 libzmq C 扩展）。
+
+## 怎么验证当前真在跑这个 python
+
+`$PY -c 'import sys,sysconfig; print(sys.version, sysconfig.get_platform())'`（`$PY` = 上面的可执行绝对路径）
+→ 应输出 `3.12.8 ... harmonyos-aarch64`。
+
+相关：[[鸿蒙PC-hdc能力边界与取证通道]]（够得到什么、取证怎么取）、[[鸿蒙PC-进程视角与mount-namespace]]（视角差异的排查路径）、[[鸿蒙PC-Python-C扩展交叉编译]]（具体编扩展的套路）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/350/256/276/345/244/207pip/351/203/250/347/275/262.md

@@ -0,0 +1,55 @@
+---
+name: 鸿蒙PC-设备pip部署
+description: 在设备 Python 上用 pip 装包的平台坑——只读 /tmp 与 /root、离线 wheel 安装、手动拷包无元数据
+metadata:
+  type: platform
+  source: new/PC
+---
+
+在鸿蒙 PC 的设备 Python（[[鸿蒙PC-设备Python运行时]]）上 `pip install` 有几个平台坑，和具体库无关，任何 Python 库部署都会撞上。
+
+> **前置**：本篇讲的是「在一个可用的设备 Python 上装包」。鸿蒙 PC 商用机默认**没有**设备 Python
+> （见 [[鸿蒙PC-设备Python运行时]]），此时 Python 随交付物自带成私有 HNP，包在**宿主侧**预置进
+> site-packages 再打包。**下面三个可写目录环境变量与离线 wheel 装法与运行时从哪来无关，照样适用。**
+
+## 三个必须重定向到可写目录的环境变量
+
+hdc root shell 里 `/tmp` 和 `/root`（HOME）都是**只读**，pip / 构建 / matplotlib 默认往那写就炸：
+
+| 变量 | 默认（只读）| 设成 | 不设的症状 |
+| --- | --- | --- | --- |
+| `TMPDIR` | `/tmp` | `/data/local/tmp` | `pip subprocess to install build dependencies did not run`（E002b）|
+| `HOME` | `/root` | `/data/local/tmp/home`（先 mkdir）| sdist 构建 `[Errno 30] Read-only file system: '/root'` |
+| `MPLCONFIGDIR` | `/root/.config/matplotlib` | `/data/local/tmp/mpl` | matplotlib import 慢 + 警告（不致命）|
+
+固定前缀：`export TMPDIR=/data/local/tmp HOME=/data/local/tmp/home MPLCONFIGDIR=/data/local/tmp/mpl; mkdir -p $HOME`
+
+## 设备网络不稳 → 离线 wheel 安装（最稳）
+
+设备能联网 pip，但**经常超时 / hash 不匹配**（`THESE PACKAGES DO NOT MATCH THE HASHES`）。稳妥做法是在 **Mac（网络好）下载 wheel 闭包再推送离线装**：
+
+```bash
+# Mac：下通用 wheel（注意 --python-version 3.12）
+pip download --only-binary=:all: --python-version 3.12 --no-deps -d wheels <pkgs...>
+# 无通用 wheel 的（tornado 等）取 sdist：
+pip download --no-binary=:all: --no-deps -d wheels tornado
+# 设备：离线装
+hdc file send wheels /data/local/tmp/
+hdc shell "export TMPDIR=/data/local/tmp HOME=/data/local/tmp/home
+  <py3.12> -m pip install --no-index --find-links=/data/local/tmp/wheels <pkgs>"
+# sdist 在 --no-index 下构建需复用设备 setuptools：加 --no-build-isolation
+```
+
+## 两个易踩的依赖元数据坑
+
+1. **手动拷进 site-packages 的包没有 `.dist-info` → pip 看不见它**。例如交叉编译的 pyzmq 直接 `cp zmq/` 进去，pip 解析 ipykernel 依赖时仍报 `pyzmq>=24 not found`。对策：装依赖它的包时加 **`--no-deps`**（依赖已人工确认 importable），或补一个 `.dist-info`。
+2. **Python 3.12 + 太新的库不兼容**：实测要避开
+   - `jupyter_client>=8.7`（用了 PEP 728 `TypedDict(extra_items=)`，3.12 不支持）→ 钉 **8.6.3**
+   - `ipython>=9`（要 `psutil>=7`，设备是旧版）→ 用 **8.30.0**
+   - 选 wheel 时优先成熟稳定版，别无脑最新。
+
+## 平台事实：解释器内 sys.platform
+
+设备 Python 里 `sys.platform == 'linux'`（C 层），而设备 Node 里 `process.platform == 'openharmony'`（见 [[鸿蒙PC-纯JS库部署到HNP-node]]）。两个运行时对"平台"的叫法不同，写跨语言判断时注意。
+
+配套实战：[[鸿蒙PC-ipykernel-Jupyter内核]]。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/350/256/276/345/244/207/350/257/255/350/250/200/350/277/220/350/241/214/346/227/266/346/216/242/346/265/213/344/270/216/344/276/233/347/273/231.md

@@ -0,0 +1,82 @@
+---
+name: 鸿蒙PC-设备语言运行时探测与供给
+description: 鸿蒙PC 上设备侧可执行（Java/Node/Python 运行时、git/ssh/构建工具皆同）一律随交付物自带——打进私有 HNP、随执行器 HAP 装机；设备上有没有不影响判定（app 域够不到别人的）。含产物来源表、自带程序、验身与状态语义。关键词 git ssh golang go rust 运行时 HNP 私有HNP 自带 供给
+metadata:
+  type: platform
+  source: new/PC + 实测(鸿蒙PC商用机, 2026-09-02)
+---
+
+# 鸿蒙 PC：设备侧可执行（含语言运行时）供给
+
+## 结论先行：**要用就自带，别去探设备上有没有**
+
+app 域进程只能 `execve` **自己私有 HNP** 里的东西（[[鸿蒙PC-app域执行二进制与JIT限制]]）。而：
+
+- 公共 HNP（`/data/service/hnp`）**在鸿蒙 PC 上不存在**；
+- 别的 App 私有 HNP 里的运行时在**人家的沙箱**里，你的进程够不到；
+- `/data/app/el1|el2` 对 `hdc shell`（uid 2000）是 **Permission denied**，连看都看不到。
+
+所以「设备上有没有 X」**不改变任何决策**——答案恒为「自带」。⛔ **别再按标准位置探测**
+（`which` / `/data/service/hnp/` / `hnppublic` / 应用私有 hnp 那套四段探测已从 `ohpt-agent env`
+删除）：那四个位置全部不可达，探测只会把「我够不到」写成「确缺」，正是 jansi / git-lfs 两案的
+假前提来源。**也绝不许以「设备没有 X」为由造 stub 顶替**（git-lfs 实证：fake-git 撑出 7/7 假绿）。
+
+> go/rust 没有「设备侧运行时」——交叉编译产物是自包含原生二进制，`not_required`。
+> 它们要看的是**宿主工具链有没有鸿蒙目标**：`ohpt-agent env --runtime go`（判据表见
+> pc-knowledge-base SKILL.md「通用约束」），两件事别混。
+
+## 判定程序（与 `runtime_provisioning.device_status` 一一对应）
+
+| 情况 | device_status | 动作 |
+|---|---|---|
+| 本库不需要设备侧运行时（cpp-lib 被 napi 壳 dlopen、静态链接 cli 等） | `not_required` | 正常流程，别为填字段硬造供给 |
+| 需要 → **默认自带** | `bundled` | 宿主侧拿到 aarch64-ohos 运行时产物 → 打进私有 HNP → 随执行器 HAP 装机 → 设备回归。`method` + `evidence[]` 必填（schema 强制） |
+| 需要但确实拿不到产物（无来源/体积超限/用户叫停） | `missing` | `status=built-pending-verification`（**不是 partial**——供给缺失是待验证，不是部分失败），blocker 记尝试过的来源与失败原因 |
+
+## 自带程序
+
+1. **拿产物**（宿主侧）。获取 URL **一律以 `harmonyos-pc-resources` 的
+   `references/aggregate/【运行时】开源运行时汇总.md` 为唯一权威**，本文只写仓名与程序，防链接漂移。
+   宿主侧克隆/下载/解包一律暂存 `$WORKSPACE/build/runtime-staging/`——工作区自包含纪律
+   （工作区外路径如 `/tmp` 会触发宿主权限拦截，非交互流水线会挂死等确认）。
+
+   | 生态 | 产物来源 | 备注 |
+   |---|---|---|
+   | Java | `BiShengJDKInstaller` 仓的 `hnp/arm64-v8a/*.hnp`（`.hnp` 即 zip，解包取 JDK 树）；或预编译 `bishengjdk17-ohos-aarch64-runtime.tar.gz` | 预编译包已自签，省一步 |
+   | Node | `DevNode-OH` 仓的 `hnp/arm64-v8a/`，形态同上 | 验身 `node -p process.platform` 应输出 `openharmony`（权威见 `pc-delivery-forms/references/languages/node.md`）。**官方构建已含 `.codesign` 段，解包提取 `bin/node` 后 app 域直接 exec 免自签**（pc-web-tool 真机实证）；避免自行交叉编译 Node 的重工具链 |
+   | Python | CPython 的 aarch64-ohos 构建（ABI 对齐事实见 [[鸿蒙PC-设备Python运行时]]，包部署见 [[鸿蒙PC-设备pip部署]]） | site-packages 在**宿主侧**预置好再打包 |
+
+   > 这几个仓原本是「装成公共 HNP 的启动器」。鸿蒙 PC 上**取它的产物、装进你自己的私有 HNP**，
+   > 不要走它的公共安装链路——装了你也用不了。
+
+2. **打包**：`hnpcli pack -i <运行时目录> -o <out>` 出 `.hnp`；`module.json5` 的 `module` 段加
+   `"hnpPackages":[{"package":"<name>.hnp","type":"private"}]`；`.hnp` 塞进 HAP 的 `hnp/arm64-v8a/`
+   （hvigor 不会自动收，需自定义 task 在 `PackingCheck` 后、`SignHap` 前注入）。
+   完整机制与三道关（exec 标签 / io_uring seccomp / JIT）见 [[鸿蒙PC-app域执行二进制与JIT限制]]；
+   现成骨架：`ohpt-agent scaffold --kind cli-hnp-runner`。
+
+3. **验身（在设备上，app 域内）**：`java -version` / `node -p process.platform` /
+   `python3 -c 'import sys,sysconfig; print(sys.version, sysconfig.get_platform())'`，
+   输出经 hilog 回传（取证顺序**先提级别再冷启动**，见 [[鸿蒙PC-hdc能力边界与取证通道]]）。
+
+4. **设备自验证**：按原库测试命令的**设备等价改写**跑（java 的 junit-console 跑法见
+   `pc-delivery-forms/references/languages/java.md`），计数口径取命名用例级。
+
+## 签名注意
+
+- 私有 HNP 里的 ELF 与 `.so` 一律要签：链接期 `-Wl,--code-sign`（post-link `strip` 会破坏签名段）。**链接期自签只针对自行交叉编译的产物**；官方预建的运行时产物（如上表 DevNode-OH 的 `node`）出厂已含 `.codesign` 段，别再签。
+- JVM 加载 JNI 库校验 `.codesign` 段：自签 `.so` 未签 = `Permission denied` → 见 pc-error-atlas E083。
+- 鸿蒙 PC 一律强制签名（无免签的机器）：见 [[鸿蒙PC-hdc能力边界与取证通道]]。
+
+## 与流水线的接口
+
+- `ohpt-agent env -w "$WORKSPACE" --runtime <eco>` → 00-env.json 的 `runtime_<eco>_host` 键
+  （**只探宿主工具链**；设备侧不探，理由见开头）
+- 03-adapt.json 填 `runtime_provisioning {ecosystem, device_status, method, evidence[], notes}`；
+  `bundled` 必带 method + evidence（schema 强制）
+- 设备回归完成后填 `target_path_covered`（设备侧覆盖度，阶段 4 优先采信 03）
+- 状态语义见 pc-schemas 的 `enum-semantics.md`
+
+## 相关
+- [[鸿蒙PC-app域执行二进制与JIT限制]]（唯一 exec 通道 + 三道关） · [[鸿蒙PC-hdc能力边界与取证通道]]（够得到什么、取证怎么取）
+- [[鸿蒙PC-设备Python运行时]]（Python ABI 事实） · [[鸿蒙PC-设备pip部署]]（包部署）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/350/277/233/347/250/213/350/247/206/350/247/222/344/270/216mount-namespace.md

@@ -0,0 +1,78 @@
+---
+name: 鸿蒙PC-进程视角与mount-namespace
+description: hdc shell 与应用进程的文件系统视图不同（各有独立 mount namespace）。诊断可读 /proc/<pid>/{environ,status,mountinfo}；但**跨视图操作用的 nsenter 在鸿蒙 PC 上 Permission denied**，要写应用能读到的位置只能让应用自己写
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：进程视角与 mount namespace
+
+## 核心结论
+**hdc shell（uid 2000）和应用进程看到的文件系统不是同一个视图**。同一条绝对路径可能：
+- 在 hdc shell 里 "No such file or directory"
+- 在应用进程里却是合法路径
+
+原因：每个应用进程有独立的 mount namespace，鸿蒙通过 hmdfs/sharefs 把它的 HOME、桌面等路径挂载到应用 namespace 里；hdc shell 不在那个 namespace。
+
+## 典型"看不见"的路径
+| 应用视角 | hdc shell 视角 |
+|---|---|
+| `/storage/Users/currentUser` | unreachable（`/proc/<pid>/cwd` 显示 `(unreachable)/...`）|
+| `/data/service/hnp/bin/` | No such file or directory |
+| `/data/service/hnp/opencode.org/...` | No such file or directory |
+
+## 定位映射关系
+```bash
+# 关键三件套
+cat /proc/<pid>/environ | tr '\0' '\n' | grep -E '^(HOME|PATH|XDG)'
+cat /proc/<pid>/status  | grep -E '^(Uid|Name|PPid)'
+cat /proc/<pid>/mountinfo
+```
+
+`mountinfo` 里能看到例如：
+```
+/storage/Users/currentUser → hmdfs /data/service/el2/100/hmdfs/account
+```
+**但物理路径写入 hmdfs 后端，不会自动出现在应用视图里**（hmdfs 是双向同步分布式文件系统，不是简单 bind mount）。要写应用能直接读到的位置，必须从应用的 namespace 写。
+
+## ⛔ 跨 namespace 写文件：**鸿蒙 PC 上做不到**
+
+`/bin/nsenter` 在设备上**存在**，但 hdc shell（uid 2000）用不了——
+`nsenter -t <pid> -m: /proc/<pid>/ns/mnt: Permission denied`（2026-09-01 实测）。
+**别在这条路上试探**，也别把"nsenter 失败"读成设备异常，它就是本域的边界。
+
+要让应用侧看到某个文件，只有两条路：
+
+1. **让应用自己写**——应用进程在自己的 namespace 里，想写哪儿写哪儿（沙箱内），
+   要给宿主看就写公共目录（申请 `READ_WRITE_DOCUMENTS_DIRECTORY`，见 [[鸿蒙PC-app访问PC用户目录]]），
+   宿主再从物理路径 `/storage/media/<userId>/local/files/Docs/…` 读回。
+2. **随交付物带进去**——打进 HAP / 私有 HNP，装机时就在应用视图里，见 [[鸿蒙PC-app域执行二进制与JIT限制]]。
+
+> 诊断能力不受影响：`/proc/<pid>/{environ,status,mountinfo}` **对 hdc shell 可读**（实测），
+> 所以"应用到底看到了什么"依然查得出来——**能诊断，不能代劳**。
+
+## 借用设备端运行时（如 Node）跑原生扩展测试
+
+设备上已安装的运行时（Node 等）通常也只在其应用的 mount namespace 内可达：进程明明在跑，hdc shell 直接执行其绝对路径却报 `inaccessible or not found`。
+
+```bash
+# 1. 找运行时进程，定位真实二进制路径
+ps -ef | grep node
+readlink /proc/<pid>/exe
+
+# 2. 进入其 namespace 执行（跑测试常加 -p 同入 pid namespace）
+nsenter -t <pid> -m -p -- <exe路径> /data/local/tmp/<pkg>/test.js
+```
+
+> ⛔ **这套「借设备端运行时」的跑法在鸿蒙 PC 上不可用**——它整段建立在 `nsenter` 之上（本域
+> Permission denied，见上节）。**正解是自带运行时**：把 Node/CPython 打进私有 HNP 随执行器 HAP 装机。
+> 历史来源：classic-level（HongMeng 1.12.0，Node 22.7.0，全量上游测试经此跑法通过）——记录保留，
+> 但**别照着试**。
+
+## 常见误判
+1. hdc shell 里 `ls /storage/Users/currentUser` 报错 ≠ 应用看不到 HOME。
+2. `hdc file send` 推到物理 hmdfs 后端 ≠ 应用立即可见。**而鸿蒙 PC 上 nsenter 用不了**，
+   所以送不进去——要么让应用自己读公共目录（`/storage/media/<userId>/local/files/Docs/…`，
+   宿主侧可写），要么把文件打进 HAP/私有 HNP 随装机带入。
+3. `which git` 在 hdc shell 找不到 ≠ 应用进程找不到。HNP 工具链在 `/data/service/hnp/bin/`，只挂载到应用 namespace。