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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-delivery-forms/references/languages/python.md

@@ -0,0 +1,245 @@
+# Python C 扩展适配
+
+适用：Python 库含 C/C++/Cython 扩展（numpy/pywt/cffi/cryptography/pycosat/pyzmq 等）。交叉编译骨干（NDK/sysroot/签名/部署/musl/HMDFS/状态语义）见 `pc-knowledge-base`。
+
+> **上游分叉**：本页解决“把库**适配成设备可 import 的 wheel**”（跑在设备 CPython 上，供命令行或其它库用）。若目标是**做一个应用、在应用内用 Python 驱动这个库**（如 ArkTS 界面 + Pillow 图像处理），那是 **app 交付形态** → 见 `pc-delivery-forms` 形态表与 `harmonyos-pc-resources` 运行时嵌入指南（方案 A 子进程 / 方案 B 进程内），不必按下面的交叉编译分层走。
+
+> **纯 py 包（无扩展）部署别漏数据文件**：`pip install`/`PYTHONPATH` 只铺 `.py` 时，包内数据目录（如 `pywt/data/`）
+> 会漏，import 得到但一用就报缺文件。设备 Python 路径与部署程序见 `pc-knowledge-base` platform/鸿蒙PC-设备Python运行时.md
+> 与 platform/鸿蒙PC-设备pip部署.md（**userId 因设备而异，探测得来，别硬编码**）。
+
+## 构建决策流程（分层降级）
+
+Python 三方库适配按以下顺序逐层判定，命中即执行，不命中降级：
+
+```
+Layer 1: 社区 PyPI 源有现成 wheel？
+  → 是：设备 pip install（零编译），查 pc-registry 社区分发源
+  → 否 ↓
+
+Layer 2: 纯 Python 包（无 .c/.pyx/.so）？
+  → 是：pip download 离线装设备（零编译），见 `pc-delivery-forms` 的 pure-runtime 形态
+  → 否（有原生扩展）↓
+
+Layer 3: crossenv（仅 Linux/Mac + QEMU 可用）
+  → setuptools 简单 C 扩展：crossenv 内 pip wheel 自动交叉编译
+  → Windows 用户跳过此层（crossenv 需运行目标 Python 二进制，
+     ARM64 鸿蒙二进制在 Windows 无法执行）
+  → meson / maturin 不认 crossenv → 降级 Layer 4
+  → 否 ↓
+
+Layer 4: 手动 cythonize + NDK clang 逐模块编译
+  → meson-python + Cython、maturin/PyO3、crossenv 不适用的复杂构建
+  → Windows 用户的实际路径（已验证：pycosat/pywt/pyzmq）
+  → 否 ↓
+
+Layer 5: Docker ARM64 容器内本机编译
+  → 兜底，容器内是原生 ARM64 鸿蒙环境，所有构建系统都正常
+  → 需 Docker（详见 pc-knowledge-base 编译场景节）
+```
+
+> agent 按目标库情况从 Layer 1 开始判定，命中即停。多数库在 Layer 1-2 解决（纯 Python 或社区已有 wheel），只有含原生扩展的库才需要 Layer 3-5。
+
+## 交叉编译路径（Linux/Mac → 鸿蒙）
+
+### 设备 Python 运行时
+
+鸿蒙 PC 已装社区 Python 3.12 运行时。C 扩展的头/库**从设备拉**，不要去 SDK 或项目外找（SDK 的 `llvm/python3` 是工具链自带 3.11，不是目标运行时）。
+
+**设备路径（用 `hdc file recv` 拉到工作区 `build/device-python/`）**：
+- python 根：`/data/app/el1/bundle/<userId>/hnppublic/python.org/python_3.12`
+- 可执行：`/data/app/el1/bundle/<userId>/hnppublic/bin/python3.12`
+- 头文件：`<root>/include/python3.12/Python.h`
+- libpython：`<root>/lib/libpython3.12.so`
+- site-packages：`<root>/lib/python3.12/site-packages`
+
+**ABI 事实（必须对齐）**：版本 3.12.8；`sysconfig.get_platform()` = `harmonyos-aarch64`；`EXT_SUFFIX` = `.cpython-312.so`（命名错则 import 找不到）；libc=musl；NDK clang `aarch64-unknown-linux-ohos-clang`。设备已预装 numpy 2.2.1 / Cython 3.0.11 / cffi / cryptography 等——直接复用。
+
+### 无可调试设备时：主机本地 OHOS Python（env `OHOS_PYTHON_HOME`）
+
+设备 release/不可调试或无设备时，改用主机已解压的 OHOS Python 3.12 离线交叉编译——产物照样编出来（设备验证待后）：
+
+**探测 OHOS_PYTHON_HOME**（若环境变量未设，自动探测）：
+```bash
+if [ -z "${OHOS_PYTHON_HOME:-}" ]; then
+  for d in "$WORKSPACE/../PythonApp/downloads/python-extracted" "$WORKSPACE/../ohos-python-3.12" "$WORKSPACE/ohos-python-3.12"; do
+    [ -f "$d/include/python3.12/Python.h" ] && { OHOS_PYTHON_HOME="$d"; break; }
+  done
+fi
+[ -n "$OHOS_PYTHON_HOME" ] || { echo "未找到 OHOS Python 3.12（含 include/python3.12/Python.h），需设置 OHOS_PYTHON_HOME 环境变量"; }
+```
+
+- `OHOS_PYTHON_HOME` 指向主机本地 OHOS Python（含 `include/python3.12/Python.h` + `lib/libpython3.12.so`，aarch64-ohos 目标 ABI）。
+- 交叉编译直接 `-I`/`-L` 指过去——**clang 自己读（OS 级，不走 Read 工具、不受外部目录限制、不需要 hdc）**：
+  ```bash
+  PYINC="$OHOS_PYTHON_HOME/include/python3.12"
+  PYLIB="$OHOS_PYTHON_HOME/lib"
+  # -I"$PYINC" ... -L"$PYLIB" -lpython3.12 -o x.cpython-312.so
+  ```
+- numpy 头：用**同设备版本** host venv（`pip install numpy==2.2.1` 后 `numpy.get_include()`）——C-API 头跨平台，版本对齐即可。
+- host Python 装不了对应 numpy（如 host 3.14 无 cp314 wheel）：`pip download numpy==2.2.1 --no-deps --only-binary :all: --python-version 312 --platform manylinux2014_aarch64 --abi cp312 -d <dir>` 下任意平台 wheel，`unzip` 出 `numpy/_core/include`（C 头给 clang `-I`）与 `numpy/__init__.pxd`（给 cython `--include-dir`）。
+- 编完 `build_status=pass`；无设备 → `test_run.executed=false`、`status=built-pending-verification`（不是 partial/failed），blocker 记"无设备，未做设备回归"。
+
+### 主机 Python 与设备 Python：严格隔离
+
+| | 主机 Python（Windows/构建机） | 设备 Python（鸿蒙 PC，目标） |
+|--|--|--|
+| 用途 | **仅**代码生成：cythonize、跑构建脚本 | 真正运行库的目标；交叉编译 ABI 基准 |
+| 头/库 | **不参与**最终链接 | `Python.h`/`libpython3.12.so` 从设备 `hdc recv` |
+| 跑测试 | 不在此跑目标库测试 | 用例只在设备跑 |
+| 隔离 | 专用 venv（`build/host-venv`），用完即弃 | 设备文件拉进 `build/device-python/` |
+
+**红线**：①主机侧一律专用 venv，绝不动全局 Python，装与设备对齐的 Cython + numpy==设备版本；②交叉编译 `-I`/`-L` 只指设备拉来的 include/lib，绝不用主机 Python.h；③numpy 版本必须 == 设备版本（否则 pxd/header 不配套，`no member named 'subarray'`）；④产物后缀用设备的 `.cpython-312.so`；⑤验证只在设备，不在主机 import 目标 `.so`。
+
+### EXT_SUFFIX 必须读目标 Python（别硬编码）
+
+扩展后缀**必须等于目标 Python 的 EXT_SUFFIX**。不同 OHOS Python 构建后缀不同：`.cpython-312.so` 或 `.cpython-312-aarch64-linux-ohos.so`。从 `OHOS_PYTHON_HOME` 读真值：
+```bash
+grep -oE "'EXT_SUFFIX':[^,]*" "$OHOS_PYTHON_HOME"/lib/python3.12/_sysconfigdata*.py
+ls "$OHOS_PYTHON_HOME"/lib/python3.12/lib-dynload/ | head -1   # 设备自带扩展命名即标准
+```
+
+### Layer 3: crossenv（仅 Linux/Mac + QEMU）
+
+crossenv 创建"欺骗性"虚拟环境，让 pip 以为运行在目标板上，自动解析目标平台依赖、调用交叉编译器。
+
+**平台限制**：crossenv 需**运行目标 Python 二进制**提取 sysconfig。鸿蒙 Python 是 aarch64-ohos musl 二进制：
+- Windows x86_64 → 无法执行 → **跳过此层，直接走 Layer 4**
+- Mac（Intel/Apple Silicon）→ 无法执行（OS 不同）→ **跳过此层**
+- Linux x86_64 + QEMU user-mode → 可执行 → **可用**
+
+**前置条件**（Linux x86_64 + QEMU）：
+- 主机 Python 3.12（从 python.org 装，版本必须 == 设备 3.12）
+- `OHOS_PYTHON_HOME` 指向鸿蒙 Python 3.12（含 `bin/python3.12`）
+- OHOS NDK clang 配置好（`ohos-cross.ini`）
+
+**创建和使用**：
+```bash
+pip install crossenv
+python -m crossenv $OHOS_PYTHON_HOME/bin/python3.12 cross_venv
+source cross_venv/bin/activate
+
+# 配置交叉编译器
+export CC="${OHOS_NDK_HOME}/llvm/bin/clang --target=aarch64-linux-ohos"
+export CXX="${OHOS_NDK_HOME}/llvm/bin/clang++ --target=aarch64-linux-ohos"
+export CFLAGS="--sysroot=${OHOS_NDK_HOME}/sysroot"
+export LDFLAGS="--sysroot=${OHOS_NDK_HOME}/sysroot"
+
+# 构建（crossenv 内 pip 自动解析目标平台依赖）
+pip wheel . --no-build-isolation -w dist/
+```
+
+**覆盖范围**：setuptools 纯 C 扩展（CC 环境变量即可注入的场景）。
+
+**不覆盖**（降级到 Layer 4）：
+- meson-python（meson 交叉编译找不到 target python/numpy）
+- maturin/PyO3（maturin 平台检查不认 crossenv）
+- 需要手动 cythonize 的复杂构建
+
+### Layer 4: 手动编译（Windows 实际路径）
+
+**纯 setuptools 单文件扩展**：
+```bash
+$CLANG -fPIC -shared -O2 -I"$PYINC" module.c -L"$PYLIB" -lpython3.12 -o module.cpython-312.so
+```
+PYINC/PYLIB 从设备 `hdc recv` 拉或 `OHOS_PYTHON_HOME`（见上）。
+
+**meson-python + Cython + numpy（如 pywt）**：**不要硬上 meson 交叉编译**（找不到 target python/numpy）。改用「手动 cythonize + OHOS clang 逐模块交叉编译」：
+1. 读 `meson.build` 抽「模块→源文件」映射
+2. 补 meson 构建期生成文件（`config.pxi`/`_c99_config.py`/`version.py`，版本写死不依赖 git）
+3. venv 里 `cython -3` 生成 `.c`（**在真实包结构里 cythonize**，避免模块名被目录前缀污染；numpy 版本必须 == 设备版本，否则 pxd/header 不配套）
+4. `$CLANG -fPIC -shared -std=c17 -DPY_EXTENSION -DHAVE_C99_COMPLEX -DCYTHON_CCOMPLEX=1 -DNPY_NO_DEPRECATED_API=NPY_1_22_API_VERSION -I"$PYINC" -I"$NPINC" <ext>.c <公共obj> -L"$PYLIB" -lpython3.12 -lm -o <ext>.cpython-312.so`
+5. 手动组装 wheel（见下）
+
+**pip wheel --no-build-isolation**：标准 Python 构建命令，鸿蒙交叉编译时用环境变量注入工具链（CC/CXX/CFLAGS/LDFLAGS 指向 OHOS NDK clang + sysroot）。`--no-build-isolation` 必须加——否则 pip 创建隔离环境，外部配好的鸿蒙环境变量全部丢失。
+
+### Layer 4b: SWIG 绑定（Windows 宿主实证）
+
+库用 SWIG 生成 CPython 绑定（如 IfcOpenShell 的 `ifcopenshell_wrapper`）时，SWIG 只在**宿主侧**跑代码生成，`.so` 本体走 Layer 4 同款交叉编译——链路已在 Windows 宿主端到端实证：
+
+1. **宿主 SWIG**：`pip install swig==4.5.0`（Windows 宿主直接可用，无需 MSYS2）；
+2. **CPython 头/库来源**：设备拉取之外还有第三条路——**Conan 中心仓 `python/3.12.9` 包**给出完整 OHOS aarch64 CPython 运行时（`bin/python3.12` + `libpython3.12.so` + `Python.h` + 全标准库），无设备/离线编译时用它当 `PYINC`/`PYLIB`（见 `pc-registry` 的 central-registry.md 实证清单）；
+3. **链接**：NDK clang++ `-I$PYINC -L$PYLIB -lpython312 -shared -Wl,--code-sign -o _<mod>wrapper.cpython-312.so`（后缀必须读目标 Python 的 EXT_SUFFIX，见上节）；
+4. **SWIG 生成的 `.py` 壳层一起部署**：SWIG 产物是「C 模块 + Python 壳层」两件套，只装 `.so` 不装生成的 `.py` 会 import 不到高层 API。
+
+**壳层陷阱（测试/用例接线必看）**：SWIG 生成的 `.py` 里的高层类（如 `class file(file_mixin)`）**不在 C 模块导出符号里**——C 模块只导出 `file_initialize`/`file_by_type` 等底层函数。测试脚本直调 `_ifcopenshell_wrapper.file()` 会 `AttributeError: module '_ifcopenshell_wrapper' has no attribute 'file'`，这是**接口层级用错**（harness-defect），不是绑定缺失：测试要么 import Python 壳层模块（`import ifcopenshell_wrapper`），要么走库顶层 API（`import ifcopenshell; ifcopenshell.file(...)`）。判别法：`llvm-nm -D <ext>.cpython-312.so | grep <缺失符号>` 无该符号而生成的 `.py` 里有同名类 → 壳层类。
+
+### 打包 wheel（交叉编译手动组装）
+
+设备上 `setup.py bdist_wheel` 不可行。交叉编译后手动组装：纯 py 包 + 数据文件 + 改好后缀 `.so` + `dist-info/{METADATA,WHEEL,RECORD,top_level.txt}`。平台 tag = `cp312-cp312-ohos_aarch64`，`WHEEL` 里 `Root-Is-Purelib: false`、`Tag: cp312-cp312-ohos_aarch64`。装：`pip install <whl> --force-reinstall --no-deps`。
+
+> **Wheel 平台标签**：鸿蒙 Python 识别 `ohos_aarch64`，不识别 `linux_aarch64`。`pip wheel` 生成的 wheel 若标签为 `linux_aarch64`，需重命名。用 `python3 -m pip debug --verbose | grep "Compatible tags"` 查设备支持的标签。abi3 标签同理：`cp312-abi3-ohos_aarch64`。
+
+### 特有坑
+
+**abi3 版本不匹配**：库声明 `abi3>=3.8`（如 PyO3 的 `abi3-py37`），编译时找 `libpython3.7m`，但鸿蒙只有 Python 3.12 → `unable to find library -lpython3.7m`。解法：改 `abi3-py312` 或移除 abi3 限制。
+
+**运行时找不到系统库**：编译时 `-L` 找到了 libcrypto.so，但运行时动态链接器不知道去哪找 → `ImportError: libcrypto.so: cannot open shared object file`。解法：`LD_PRELOAD` / `LD_LIBRARY_PATH` / 系统库集成（详见 `pc-knowledge-base`「运行时库加载」）。
+
+**鸿蒙 OpenSSL 非标准符号**：鸿蒙版 OpenSSL 含 `OPENSSL_sk_set_thunks` 等标准 OpenSSL 没有的符号 → `undefined symbol`。解法：在构建时注入兼容定义或补 stub。详见 `pc-error-atlas` 错误图谱。
+
+**OpenSSL legacy provider 加载失败**：编译时自定义 OpenSSL 未加 `enable-legacy` → 运行时 `legacy provider failed to load`。解法：重编 OpenSSL 加 `enable-legacy`，或 `export CRYPTOGRAPHY_OPENSSL_NO_LEGACY=1` 禁用。
+
+## 本机编译路径（鸿蒙PC上直接编）
+
+> ⏳ 扩展口：部分知识已填入，构建命令和特有坑待补。
+
+### 环境准备
+
+**Python 安装**（注意：如已装"Python 安装器"应用需先卸载）：
+```bash
+curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- python 3.12.9
+```
+
+**pip 安装**：
+```bash
+python3 -m ensurepip
+```
+
+**pip 源配置**（端点/备选源/降级规则权威见 `pc-registry` 的 `references/central-registry.md`；宿主侧建议 `--extra-index-url https://pypi.org/simple` 官方兜底,volces 为网络受限备选）：
+
+方式一（命令行配置）：
+```bash
+pip3 config set global.index-url https://pypi.cnb.cool/OpenHarmonyPCDeveloper/pypi/-/packages/simple
+pip3 config set global.trusted-host pypi.cnb.cool
+```
+
+方式二（配置文件）：
+```bash
+mkdir -p /storage/Users/currentUser/.pip
+cat > /storage/Users/currentUser/.pip/pip.conf << 'EOF'
+[global]
+index-url = https://pypi.cnb.cool/OpenHarmonyPCDeveloper/pypi/-/packages/simple
+trusted-host = pypi.cnb.cool
+EOF
+```
+
+**Harmonybrew 包管理**（可选，用于安装 clang/rust 等工具链）：
+```bash
+brew install python ohos-pip-autosign    # Python + 自动签名
+brew install rust llvm-gcc-compat         # Rust + OHOS SDK 工具链
+```
+
+### 构建命令
+
+（待补：`python3 setup.py bdist_wheel` / `pip wheel . --no-build-isolation`，本机 Python 直接可用，无需交叉编译工具链）
+
+### 特有坑
+
+（待补：subprocess PATH 不继承 → 用 sys.executable、musl 显式 -lpython3.12、EXT_SUFFIX 本机值为 `.cpython-312-aarch64-linux-ohos.so`）
+
+## 库落地经验索引
+
+| 库 | 文件 | 要点 |
+|----|------|------|
+| pycosat | `references/adaptation/鸿蒙PC-Python-C扩展交叉编译.md` | 单文件 C 扩展交叉编译套路 |
+| pywt | `references/adaptation/鸿蒙PC-meson-Cython-numpy扩展.md` | 手动 cythonize + 逐模块交叉编译 |
+| pyzmq + libzmq | `references/adaptation/鸿蒙PC-pyzmq-libzmq扩展.md` | 依赖 native 库的 Python 扩展：先编 libzmq 再链接 |
+
+> 这些文件在 `pc-knowledge-base/adaptation/` 目录下（跨语言共享核心的案例库）。照着对当前工作区 source/ 复刻/重建，不要用 Read 读案例里指向的项目外路径。
+
+## 资源引用
+
+- 交叉编译骨干（工具链/ABI/签名/部署/离线兜底/状态语义/运行时库加载/RUNPATH）→ `pc-knowledge-base`
+- 社区 PyPI 源（已适配 wheel 直接装）→ `pc-registry`
+- 报错定位 → `pc-error-atlas` 错误图谱

package/node_modules/@ohos-agent/pc-adapter/skills/pc-delivery-forms/references/languages/rust.md

@@ -0,0 +1,68 @@
+# Rust / PyO3 扩展适配
+
+适用：Rust cdylib、Python Rust 扩展（cryptography/pydantic-core/orjson/ruff 等）。交叉编译骨干见 `pc-knowledge-base`。
+
+> Rust/PyO3 项目不适用 crossenv（Python 的 Layer 3），直接走 Layer 4 手动流程。因为 maturin 平台检查不认 crossenv 环境。详见 `python.md` 构建决策流程。
+
+## 交叉编译路径（Linux/Mac → 鸿蒙）
+
+### 环境配置
+
+```bash
+rustup target add aarch64-unknown-linux-ohos
+
+# .cargo/config.toml
+[target.aarch64-unknown-linux-ohos]
+linker = "/opt/ohos-sdk/linux/native/llvm/bin/clang"
+rustflags = ["-C", "link-arg=--target=aarch64-linux-ohos",
+             "-C", "link-arg=--sysroot=/opt/ohos-sdk/linux/native/sysroot"]
+```
+
+### 构建命令
+
+- 纯 Rust 项目：`cargo build --target aarch64-unknown-linux-ohos --release`
+- Python Rust 扩展（PyO3）：
+  - 标准：`maturin build --target aarch64-unknown-linux-ohos --release -o dist/`
+  - 若 maturin 平台检查报错（见下），绕过 maturin：直接 `cargo build --release` + 手动打包 wheel（平台 tag `cp312-cp312-ohos_aarch64`）
+
+### 特有坑
+
+**maturin 平台检查不匹配**：maturin 检查 `platform.system()` 与 Rust target 是否一致——Python 返回 `"HarmonyOS"`，Rust target `os="Linux"` → `platform.system() don't match ಠ_ಠ`。解法：绕过 maturin，直接 `cargo build` + 手动打包 wheel（复制 .so → 改后缀 `.cpython-312-aarch64-linux-ohos.so` → ELF 签名 → 组装 wheel）。
+
+**PyO3 abi3 版本不匹配**：Cargo.toml 声明 `abi3-py37` 需链接 `libpython3.7m`，但鸿蒙只有 Python 3.12 → `unable to find library -lpython3.7m`。解法：改 `abi3-py312`：
+
+```toml
+# 修改前
+pyo3 = { version = "0.26", features = ["abi3-py37", "auto-initialize"] }
+# 修改后
+pyo3 = { version = "0.26", features = ["abi3-py312", "auto-initialize"] }
+```
+
+**aws-lc-sys ASM 符号缺失**：aws-lc-sys（cryptography 的 Rust 依赖）cmake 构建时无法识别 HarmonyOS → ARM neon 汇编代码未编译 → 运行时 `ChaCha20_ctr32_neon: symbol not found`。解法：在 aws-lc-sys 的 `cmake_builder.rs` 中加 `cmake_cfg.define("OPENSSL_NO_ASM", "1")`，禁用汇编改用纯 C 实现（性能降约 10-20%，功能完整）。
+
+**扩展后缀**：`.cpython-312-aarch64-linux-ohos.so`（从 `cargo build` 产物 `lib<name>.so` 改名）。
+
+## 本机编译路径（鸿蒙PC上直接编）
+
+> ⏳ 扩展口：待补充。预留以下结构骨架。
+
+### 环境准备
+
+（待补：本机 rustc 默认 host = aarch64-unknown-linux-ohos、Harmonybrew 安装 rust）
+
+### 构建命令
+
+（待补：本机无需 --target 参数、maturin 平台检查绕过方式可能不同）
+
+### 特有坑
+
+（待补：jemalloc 构建/global_allocator 运行时崩溃/Rust 版本降级）
+
+## 依赖源
+
+鸿蒙 crate（hilog/hilog-sys 等）与已适配依赖优先走中心制品仓 Cargo 库：`~/.cargo/config.toml` 配 `[registries.ohpcd]` 后按包 `--registry ohpcd`。端点/判读/注意事项权威见 `pc-registry` 的 `references/central-registry.md`（⚠️ 该 index 对任意路径 200，判存在必须解析内容）。
+
+## 资源引用
+
+- 交叉编译骨干 → `pc-knowledge-base`
+- 报错定位 → `pc-error-atlas` 错误图谱

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: pc-device-verify
+description: 在真实鸿蒙 PC 设备上验证交叉编译产物的可复用流程：产物随交付物自带成私有 HNP，经执行器 HAP 在 app 域 fork/execv 真跑，证据走 hilog（**取证前必须 `hilog -b D` 提级别 + `aa force-stop` 冷启动**，否则 INFO 在写入时即被丢）与截图（截图仅存档待人工验收，机器判定走日志）。含 Python 生态成套脚本（推送 → pip 安装 → ELF 自签 → import 冒烟 → 跑全量 pytest → 产出 03-adapt.json 的 test_run 字段）与 GUI 应用 HAP 验证（安装 → 启动 → 存活检查 → 崩溃排查）与失败归因（真实平台缺陷/测试框架环境/交叉编译产物 三分类）。触发词：设备验证、上设备、真机测试、device test、跑用例、pytest on device、ELF 签名、Permission denied、code sign、binary-sign-tool、hdc shell、私有 HNP、执行器 HAP、hilog 取证、日志为空、段错误、SIGSEGV、页对齐、OPENBLAS_CORETYPE、复数算错、失败归因、HAP 验证、应用冒烟、启动崩溃、栈溢出、stack-buffer-overflow、cppcrash、进程存活、HiShell、demo 反馈、测试同学反馈、实际与预期不符、预期不符、旧文案、用例表漂移、cases-sha256、demo-casetable-synced、fork 无 exec、隔离子进程崩溃、进程内直跑对照、受阻归因、foreign exception。
+---
+
+# pc-device-verify：鸿蒙 PC 设备端验证（可复用）
+
+真机验证交叉编译产物：**推送 → 安装 →（按需签名）→ import 冒烟 → 跑全量用例 → 产出可誊写的证据**。换库只改 `PKG`/`WHL`。
+
+## 何时用我
+
+- `pc-03-dev-adapt-code` 已交叉编译出产物（见 `pc-knowledge-base`），需要**在真机回归**。
+- 报 `ImportError: ... .so: Permission denied`（ELF 未签）时——**默认修法是回宿主用 `-Wl,--code-sign` 重新链接**；设备侧 `binary-sign-tool` 自签只在装了 DevBox 的机器上可行，商用机没有。
+- 真机用例失败要**归因**时 → `references/failure-triage.md`。
+
+> **边界（别过度承诺）**：`hs_exec` 传输通道**语言无关**，可跑任意命令；但成套 verify 脚本（`hs_verify` / `device_verify.py`）**只有 Python 生态有**。其他生态的真机跑法（cargo test / UnitTest++）见 `pc-knowledge-base` 的 `platform/鸿蒙PC-真机跑官方测试套件.md`，传输可复用本 skill 的通道。
+
+## 第 0 步：设备就绪自检
+
+```bash
+hdc list targets                # 有目标
+hdc shell "uname -m"            # 须 aarch64
+hdc shell id                    # uid=2000(shell)——鸿蒙 PC 的常态，不是异常
+```
+
+**设备侧跑用户二进制只有一条路**：产物打成**私有 HNP**、随执行器 HAP 装机、在 app 域
+`fork/execv`（`ohpt-agent scaffold --kind cli-hnp-runner`）。`hdc shell` 是 shell 用户、
+够不到应用沙箱，`/data/local/tmp` 可写但**不可执行**，公共 HNP 不存在——能力边界与取证通道的
+权威是 `pc-knowledge-base` 的 `platform/鸿蒙PC-hdc能力边界与取证通道.md`。
+
+> ⚠️ **装 HAP 要真签名**：`bm install` 校验 PKCS7 profile 信任链，自签必拒（`code:9568257`）。
+> 用 `ohpt-agent sign-demo`（SDK 自带 OpenHarmony 材料 headless 自签），
+> 见 `pc-knowledge-base` platform/鸿蒙PC-HAP调试签名与设备安装信任链.md。
+
+## 设备是独占资源
+
+一次捕获周期里的三件事都是**设备全局副作用**：`hilog -r` 清整机缓冲、`aa start` 抢前台、
+`snapshot_display` 截整屏。两个任务交叠时，A 明明跑通了，却因为 B 清了缓冲而拿不出证据
+（`log_channel=muted` → 用例判 `blocked`），且日志**不可复原**。
+
+所以设备操作走**租约**（`~/.ohos-agent-pc-adapter/locks/device.lock`，`ohpt-agent` 自动持有）：
+
+| 操作 | 持锁 |
+|---|---|
+| `verify-demo`（单次捕获 / 逐用例整轮）、`sign-demo --install`、`device shot` / `device triage` | ✅ 自动排队 |
+| `env --device-only`、`device log/ps/crash/files/exec` 等只读观测 | ❌ 无副作用，不排队 |
+
+**不碰设备的阶段照旧并行**（扫描、用例集、汇总、测试设计都不碰设备）——只有碰设备的那段串行。
+排队时会打一行 `[device-lease] 设备被 … 占用`；持有者进程死掉或超 20 分钟即被抢占（防死锁优先）。
+
+**已知限制**（租约兜住，但并发时仍需留意）：
+
+- 私有 HNP 的 `/data/app/bin/<tool>` 是设备全局符号链接，**同一个库的两个工作区（如两个版本）会撞**——
+  给其中一个传 `--tool <名字带版本>` 区分。
+- HiShell 通道（`hishell_driver.sh`）的 `.cmd.out` 轮询文件与 `.pc-adapt-verify` 工作区是固定名，
+  结构上就是单任务的；`hs_clean` 会 `rm -rf` 整个共享目录。
+- 多设备并行**不支持**：所有 `hdc` 调用不带 `-t <udid>`，多设备时 `getUdid` 会失败退出（fail-closed）。
+
+## 索引（按需读，不必全读）
+
+| 文件 | 内容 | 状态 |
+|---|---|---|
+| `references/domain-hdc-shell.md` | hdc shell 域：能做什么/够不到什么、可写目录三件套、认域不认路径 | ✅ 已有 |
+| `references/channel-hishell.md` | HiShell 手动兜底：`hs_exec` 工程化、IME 自纠错、隐藏工作区、宿主机坑 | ✅ 已有 |
+| `references/python-verify.md` | Python 生态：env、OPENBLAS、pytest 钉版本、产出字段 | ✅ 已有 |
+| `references/failure-triage.md` | 失败归因四分类（平台缺陷/框架环境/测试产物/语义分歧）+ 症状分流表 + 行为分歧三向对照 + missing-capability 证伪程序 + fast-path/fallback 三级回退决策树 | ✅ 已有 |
+| `references/hap-verify.md` | GUI 应用（HAP）验证：安装→启动→存活检查→崩溃日志排查→归因 | ✅ 已有 |
+| `references/terminal-buffer-assert.py` | 终端上屏 buffer 断言脚本（pyte 重放 PTY 落盘流，语义断言折行/光标/SIGWINCH） | ✅ 已有 |
+| `references/cli-batch-exec.md` | 多二进制批量测试执行：EXTRA_BIN/EXTRA_LIB/EXTRA_DIR 打包 + per-case cwd 契约 + 90s 看门狗 + TAP 实时 hilog（libetpan 37 ELF 实证） | ✅ 已有 |
+| `references/runner-script-wiring.md` | 随包脚本型 runner 接线：**子进程调用**（禁 `. source`——`$#=0` 误触发全量 + musl bash 退出码方言归 0）、RAW 失败例全量/pass 折叠回传 + **长 exec 心跳行防捕采 stalled**、断言对齐当前 commit 实际输出（help 分组漂移/派生符号/运行时变量）、fixture 必须真实有效 + **校验失败路径从下载通道注入**（预置 corrupt 被 skip-existing 绕过）+ dist 加夹具必重编 HAP、**VAR=val 前缀赋值直接修饰命令**（独立成行不 export → env 断链误诊平台限制）、**看门狗杀进程组**（setpgid+kill(-pid)——alarm 只杀 bash 映像，孙进程持 pipe 挂死）、前置不足判 blocked（2026-09-18 一轮 6/20→19/19 返工实证；2026-09-21 某交叉工具链工程 fix3→fix6 续增） | ✅ 已有 |
+
+## 断点续跑（被切轮次总能接上）
+
+**执行输出协议**（用例侧，阶段 2 写用例时就落——见 pc-roster-generation 的宿主自证节）：每用例
+`[CASE-BEGIN id]` / `[CASE-END id verdict]` 逐行落、逐行 flush；verdict 三态 pass/fail/blocked
+与执行器 blocked 映射一致。这是被切轮次 partial 数据可恢复的前提。
+
+**results-partial.json**（被切轮次标准遗留物，`.ohos-adaptation-pc/` 下）：`completed[]` +
+`pending[]` + `last_alive` + `residual` + `ended_by`（budget_total/budget_case/watchdog/manual）。
+契约权威 = 本节；pc-workspace-layout 产物表登记文件位置。执行器落文件参数下批次落地，本轮编排层先消费契约。
+
+**续跑流程**：
+1. **验尸三问**：卡哪条（last_alive）→ 病因分级（单条超时 vs 总预算 vs 残留干扰）→ 有无残留
+   （设备进程树/临时文件）。答案进下一轮 notes，缺失点名。
+2. **构造续跑集**：跳过 passed（零重跑）、blocked 默认跳过（翻案走 human-review）、pending 按
+   验尸结论处置。
+3. **选集续跑** → **跨轮合并**（results-partial + 本轮新结果）→ **missing=0 对账**
+   （ran + exempt + blocked + missing = 名册总数）。
+
+**防退化三条**：续跑轮同受总预算管辖；同条目 killed×2 强制 human-review；worker 启动清上一轮
+残留（进程/临时文件——basis 七轮盲跑五轮死于残留）。
+
+**豁免率告警**：单库豁免率 >15% 或 testenv-limited 超名册 1/4 → 人工复核（防真缺陷批量洗成
+环境限制，与 enum-semantics 豁免终态语义「不存在豁免但仍然 FAIL 的终态」联动）。
+
+## 机器验收的交互盲区（人工冒烟必须补）
+
+`verify-demo` 的机器验收走 autoRun + hilog `OHPTCASE` 结果行判定——**它从不点页面按钮、不操作 UI**。
+因此只依赖「结果行存在 + pass」的**交互路径缺陷在机器验收下永远全绿**：
+
+- 执行中重复点击 → 「应用未响应」ANR；
+- 按钮防重入失效 / 排队重跑；
+- 结果区不展示真实返回值（写死文案 / 聚合数字）。
+
+实证（usbredir test-demo，2026-09-16）：F-04-01 假绿（断言 OR 弱化 + 黑盒 helper 吞单步 rc）与
+执行中再点按钮 ANR，均在机器验收 24/24 pass 之后由用户手测发现。机器判据只认 hilog 结果行是
+**设计使然**，不是 bug——缺的环节是人工冒烟。
+
+每次验收跑完全量用例后，补一轮交互冒烟并留痕（写进 06-testdemo-report / 交付说明）：
+
+1. 关键用例页点「执行」→ 执行中**快速连点**按钮 → 无「应用未响应」、无排队重跑、结果只出一轮；
+2. 结果面板能看见**真实返回值 / 退出码**（不是写死文案）；
+3. 主线程不阻塞的间接证据：hilog 里 OHPTCASE check/result 行的 tid ≠ 主线程 tid（usbredir 实证）。
+
+## GUI 应用（HAP）验证
+
+> **关键原则：「启动 ≠ 存活」**——`aa start` 返回成功只说明 AMS 创建了进程，应用可能在 0.5~2 秒后崩溃。必须做存活检查 + 崩溃日志排查。
+
+### 必检三步（所有 GUI 应用必做）
+
+```bash
+hdc install -r <hap_path>
+hdc shell "hilog -b D"                      # ← ① 先提级别：商用机默认 W，应用的 INFO 写入时就被丢
+hdc shell "aa force-stop <bundle_name>"     # ← ② 必须冷启动：已在跑的应用 aa start 只切前台、不重打日志
+hdc shell hilog -r
+hdc shell aa start -a <ability_name> -b <bundle_name>
+sleep 5
+PID=$(hdc shell "ps -ef | grep <bundle_name> | grep -v grep" | awk '{print $2}')   # 必须返回进程行
+hdc shell "hilog -x -P $PID"                # ← ③ 按 pid 取本应用全部日志（比全量 grep 稳）
+hdc shell "hilog -x -P $PID | grep -iE 'SIGSEGV|SIGABRT|signal 11|signal 6|FAULT|cppcrash'"  # 必须无输出
+```
+
+> ①②③ **顺序不能换**，换了就会拿到空日志并把它误读成"应用没跑/适配造假"。等价物是
+> `ohpt-agent verify-demo`（已内置这套顺序并产出 `log_channel` 通道健康字段）。
+> 机制与实证见 `pc-knowledge-base` 的 `platform/鸿蒙PC-hdc能力边界与取证通道.md`。
+
+### 慢用例捕获：轮询结果行，别用固定窗口
+
+> ⚠️ 轮询救不了**超 appfreeze 看门狗**的用例：app 域线程阻塞 >3s/`THREAD_BLOCK_3S`、
+> >6s/`THREAD_BLOCK_6S` 后 `processExit:1` 杀进程（mpg123 sweeper/noise 实证豁免）。
+> `--case-timeout` 再大也没用——长耗时用例在设计期拆分或取证豁免，详见
+> `references/cli-batch-exec.md` 执行与取证节。
+
+固定 4s 捕获窗对慢用例（基准/加密/大归档/多线程测试——实测有 39s/87s 级用例）会截出
+**「无结果行」的假证据**：用例实际通过了，但取证时结果还没打出来，机器判据 fail-closed 判
+blocked。`ohpt-agent verify-demo --cases` 已内置轮询：等 `OHPTCASE result=…` 结果行**出现即收**
+（`--case-timeout <sec>` 调单条上限，默认 120s；cases.json 条目 `timeout_sec` 可逐条覆盖；
+产物 `poll.stopped_by` 区分 `result-line`/`process-gone`/`timeout`）。手写捕获脚本时照抄这个
+三停模式：
+
+1. **结果行出现** → 立即取整段 hilog 收证（别多等——等越久缓冲越可能被后续日志挤出）；
+2. **进程消失**（崩溃/自退出）→ 取证收尾，再等也不会有结果行；
+3. **超时** → 如实记录 `timeout`，不要假装没跑过。
+
+**hilog 缓冲滚失**的补证法（取证后想补 raw 全文时）：同序列**冷启动重捕获**（`aa force-stop`
+→ `aa start` → 等结果行 → 立即 `hilog -x -P <pid>`），别指望滚掉的缓冲能恢复。长套件的 RAW
+输出会整段挤掉早先的 TAP 行——执行器侧应**逐条实时打日志**（见 cli-hnp-runner 模板的
+`Tap::add` 即时 hlog），而不是跑完一锅端。
+
+**长跑捕获（小时级全量套件）防灌爆**：跑全量名册（千条级 pytest/测试 ELF）时，宿主侧
+`hdc shell hilog` **全量无过滤**捕获会灌爆——系统日志全量流入，实测 3 分钟写满 2.3GB
+（IfcOpenShell 名册全量实证），磁盘吃满后取证通道直接失能。长跑必须**设备侧过滤**捕获：
+
+```bash
+hdc shell "hilog | grep <包名/tag>" > build/test-device-raw.log   # 管道在设备侧执行，宿主只收过滤后输出
+```
+
+（引号必须把整条管道包住——宿主侧管道解释易碎见 `references/failure-triage.md`；hilog 自身
+`-e <tag>` 等价可用）。前置纪律不变：`hilog -b D` 提级别 + `aa force-stop` 冷启动；套件跑完
+以结束标记（如 runner 的 `=== ...-runner end ===`）为收证信号，逐条 TAP/PYTEST 行记账。
+
+**两步都通过才可判定 `built-and-verified`**。崩溃排查、cppcrash 日志拉取、常见崩溃模式与归因 → `references/hap-verify.md`。
+
+## 终端上屏验证（terminal-render 域命中时）
+
+> **触发**：manifest 能力域命中 `terminal-render`（判定权威：`pc-capability-domains/references/capability-domains/terminal-render.md`——三通道判定与纪律在那里，本节只管操作）。
+> **核心认知：「序列在场」≠「上屏效果正确」**——降级/渲染 bug 都不报错，必须对渲染结果做语义断言。
+
+**流程四步**（渲染类名册用例逐条走）：
+
+1. **捕获**：PTY 宿主（上屏 demo 或 CLI 载体内嵌 forkpty）把每条用例的 master 侧输出流
+   **原样落盘** `build/device-runs*/<用例>.log`——必须是**裸 PTY 流**，不带 hilog 前缀/时间戳
+   （pyte 只认转义序列）；键序注入等子进程就绪后再发，段间留节奏
+2. **断言锚定**：用例显式设窗口宽（`stWinsize`/COLUMNS），断言里的列号全部锚定这个已知值
+3. **重放断言**（宿主机，pyte 只在本机跑、设备零依赖）：
+
+   ```bash
+   # 前置：pip install pyte（env 探测项 host_pyte；缺失时降级为「序列在场」机判 + 截图人工看）
+   python3 <本技能绝对路径>/references/terminal-buffer-assert.py \
+     --case-file build/buffer-assert-cases.json --out build/buffer-assert.json
+   ```
+
+   断言类型：`line_contains`/`wrap_col`（折行位置）/`cursor_after`/`cursor_at`/`has_color`；
+   SIGWINCH 重排用 `feeds` 多段喂入（段间自动 resize）
+
+**宿主侧 hilog 回传（渲染流落到宿主的唯一通道，四步一个命令块，缺一必挂）**：
+hilog 环形缓冲被系统日志 ~10MB/s 刷屏（事后 `hilog -x` 看不到应用行），且 hilog 传不了 ESC 等
+控制字节——渲染流必须走 B64 分块回传。零售机查应用日志用 `hilog -x -D 0x1 | grep <tag>`。
+
+```powershell
+# ① 挂起（先于拉起应用）
+$p = Start-Process hdc -ArgumentList 'shell','hilog' -RedirectStandardOutput build\term-stream.log -PassThru
+# ② 拉起应用（aa start …）
+# ③ 轮询等完成标记 PTY-B64-END（demo 侧 B64 分块，300 字符/行）
+while ((Get-Date) -lt $deadline) { Start-Sleep 5; if (Select-String build\term-stream.log -Pattern 'PTY-B64-END' -Quiet) { break } }
+# ④ 杀掉捕获进程（【必做】同一条命令内）——留着它，子进程握住工具调用的输出管道，
+#    bash 调用永不返回、会话挂死（实证坑 2026-09-07，port 会话冻结 1.5h 的根因）
+Stop-Process -Id $p.Id
+# ⑤ 按 B64| 行重装原始流（python: base64.b64decode 逐行拼接）→ 喂 pyte 断言
+```
+
+4. **落账**：`build/buffer-assert.json` + PTY 捕获 + 上屏截图（`verify-demo`）三件路径全部
+   列入 `03-adapt.json` 的 `artifacts[]`——验收规则 `terminal-render-visual-evidence` 逐一核对
+
+**归因铁律**：buffer 断言失败 → **第一嫌疑 E130**（terminfo 等数据未随包 → 静默降级），
+补随包重测；数据随包+自举完备仍失败 → 才是渲染缺陷（或 scan 误判，分诊）。
+
+## 端到端（Python）
+
+> **前置**：下面这套走的是**设备上已装 Python 启动器**（DevBox / Python HNP 启动器）的路子。
+> **鸿蒙 PC 商用机默认没有**（实测：无公共 HNP、用户目录下无 `usr`）——没有就别硬找，
+> 把 CPython 随交付物自带成私有 HNP，走 `ohpt-agent scaffold --kind cli-hnp-runner`。
+
+设备已装 Python 启动器时：
+
+```bash
+PKG=pywt
+WHL=PyWavelets-1.10.0.dev0-cp312-cp312-ohos_aarch64.whl
+source <本技能绝对路径>/scripts/hishell_driver.sh
+
+hs_init                                        # 建隐藏工作区；会显式校验，失败时给出正确的 HS_USERID
+hs_push '<主机 wheel 绝对路径>' "$WHL"          # 本地路径自动 cygpath -w
+hs_push <本技能绝对路径>/scripts/device_verify.py device_verify.py
+hs_verify "$PKG" "$WHL"                        # 冷启→签名→import→pytest，结果直接打印
+# hs_clean                                     # 可选：清理工作区
+```
+
+不限于验证——任意命令都能可靠跑：
+`hs_exec 'python3.12 -c "import pywt; print(pywt.__version__)"' 120 ./out.txt`
+
+## 结果怎么读
+
+**`RESULT: PASS` 不等于「通过」**——判据是**原库用例逐条真跑过且全通过**，不是绝对数字。失败了**先归因，别默认当真实平台缺陷**：`pc-knowledge-base` 实测 9 库 ~6100+ 用例，曾以为的"唯一真实缺陷"最后查明是设备 numpy 的 OpenBLAS bug，**真实平台缺陷实为 0**。分流表见 `references/failure-triage.md`。
+- **探针完备性**：下「零到达/无输出/没实现」类结论前，必须在**所有可能通路**上布正向探针（每个事件通道、每层传递都要有无条件日志）——单通道静默不构成「不存在」。实证：某 GUI 载体被误判「输入事件零到达」，实为探针只覆盖了未投递的 MOUSE 通道，漏掉了实际投递的 TOUCH 通道。本条是「断言即索证 / 同头文件启发」（R1/R2，见 `pc-knowledge-base/platform/鸿蒙PC-能力存在性以SDK声明为准.md`）在设备诊断侧的姊妹规则。
+
+脚本末尾直接打出 `=== test_run ===` 块，誊进 `03-adapt.json`（字段：`executed`/`test_command`/`test_source`/`total_cases`/`passed`/`failed`/`skipped`/`pass_rate`/`regressions`/`notes`）。
+
+- `pass_rate = passed/(passed+failed)`，**skipped 不计入分母**。
+- `test_source` 记用例来源（`reused`=原库自带、`generated`=本阶段补写的冒烟用例、`mixed`）、`regressions[]` 记设备侧未通过的用例——**这两个才是通过与否的真判据**（schema 要求终态时 `total_cases ≥ 1` 且 `regressions` 为空）。
+- 全过 → `03-adapt.json` 的 **`status=built-and-verified`**。
+  ⚠️ **不是 `success`**——那是 `04-summary.json` 的 `adaptation_status` 的值，**两套 enum 别串**，串了会被 PostWrite Hook 的 schema 校验直接拒。语义权威：`pc-knowledge-base` 的「状态语义」段。
+
+## 权威边界
+
+- **平台事实**「设备是什么样」（HiShell 为何可行、uitest/uinput 原语、签名规则、路径映射、各语言跑测试套件的套路）→ 归 `pc-knowledge-base`，本 skill **只引用不重述**。
+- **工程实现**「脚本怎么可靠地用它」（通道自纠错、幂等续跑、证据落盘）→ 归本 skill。
+
+## 资源引用
+
+交叉编译 / wheel / 签名规则 / 状态语义 → `pc-knowledge-base`；其 `platform/` 下另有本 skill 依赖的四篇平台事实：`鸿蒙PC-hdc能力边界与取证通道.md`（**能做什么/取证怎么取，先读这篇**）· `鸿蒙PC-app域执行二进制与JIT限制.md`（私有 HNP 是设备侧 exec 的唯一通道）· `鸿蒙PC-应用沙箱与物理路径映射.md`（路径/userId）· `鸿蒙PC-真机跑官方测试套件.md`（各语言跑法与归因）。HiShell 手动兜底见 `鸿蒙PC-不可调试设备用HiShell自动化测试.md`。