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

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

@@ -0,0 +1,63 @@
+# 生态：Python 库验证（pip → 签名 → import → pytest）
+
+> **前置**：本篇假定**设备上已有 Python 启动器**（DevBox / Python HNP）。鸿蒙 PC 商用机默认没有
+>（实测：无公共 HNP、用户目录下无 `usr`）——那种情况下把 CPython 随交付物自带成私有 HNP，
+> 走 `ohpt-agent scaffold --kind cli-hnp-runner`。下面的**工程结论（OPENBLAS/pytest 版本/
+> --no-deps/basetemp）与运行时从哪来无关，照样适用**。
+
+`scripts/device_verify.py` 的流程与依据。**通用、幂等、可续跑、双通道**：设 `PKG`/`WHL` 即可，已能 import 就跳过安装+签名直奔测试；`FORCE=1` 强制重装重签。
+
+> 目前**只有 Python 生态有现成脚本**。其他生态的真机跑法（cargo test / UnitTest++）见 `pc-knowledge-base` 的 `platform/鸿蒙PC-真机跑官方测试套件.md`，传输可复用本 skill 的 `hs_exec`（语言无关），但没有对应的 `*_verify.py`。
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `PKG` | （必填） | import 名，如 `pywt` |
+| `WHL` | 空 | 设备上 wheel 路径；留空=跳过安装 |
+| `PY` | `python3.12` | hdc shell 域 PATH 里没有 python，**须传绝对路径** |
+| `WORK` | 按域自动 | hdc shell 域: `/data/local/tmp/pc-adapt-verify`；app 域: 桌面隐藏工作区 |
+| `RUN_TESTS` | `1` | `0`=只冒烟 import |
+| `FORCE` | `0` | `1`=强制重装+重签 |
+| `SIGN` | `auto` | 鸿蒙 PC 一律要签；`1` 强制；`0` 不签 |
+
+## 关键点与依据
+
+**`OPENBLAS_CORETYPE=ARMV8`（脚本已自动设，且必须早于任何 numpy 加载）**
+设备 numpy 自带 OpenBLAS 0.3.27 被派发到 `armv8sve`，复数点积内核 `zdotu`/`cdotu` **实部全错**。2026-07-16 实测复现：`n=64` 实部误差 4.09，而**虚部恒 1e-16 正确**，且 **`n=1` 恰好正确**——极易漏判。受害面：`dot`/`vdot`/`inner`/`matmul(1-D)`/`correlate`/`convolve`；`matmul(2-D)` 走 zgemm 不受影响。权威：`pc-knowledge-base` 的 `adaptation/鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug.md`。
+⚠️ **裸用 `hs_exec` 跑 python 时脚本管不着**，得自己带上这个 env。
+
+**`--no-deps`（脚本已带）**
+设备**没有可用 NDK**——HNP 里那个 `clang` wrapper 指向未安装的 ohos-sdk，任何 sdist 回退编译**必然失败**。依赖只能预装或另行交叉编译。设备已预装 numpy 2.2.1 / Cython 3.0.11 / cffi / cryptography / matplotlib 等（实测）。
+
+**`-p no:cacheprovider`（脚本已带）**
+否则 pytest 往只读的 `/` 写 `.pytest_cache`。
+
+**`--basetemp=<WORK>/_pt_<PKG>`（脚本已带）**
+默认 tmp 目录属主与当前 uid 不符 → `OSError: temporary directory ... is not owned by the current user`，相关 `*_pickle` 用例 setup 即 error（**非功能失败**）。新建一个当前域自有的目录即可。
+
+**pytest 版本要配库**
+老库（nose 风格 `setup()` 模块函数）在 **pytest 8+ 上全局 fixture 不启动**，产出一片 `NoneType` 假失败。ipykernel 6.29.5 实测：钉 `pytest==7.4.4` 后 23 failed → 44 passed。⚠️ **设备预装的是 pytest 9.0.3**（2026-07-16 实测），比出问题的 8.x 还新一代——老库基本都要钉版本。
+
+**测试数据目录要一起推**
+库自带测试数据（如 `pywt/tests/data`）不在 wheel 里时要单独推，否则一片 file-not-found。
+
+**页对齐只留证、不拦截**
+见 `references/failure-triage.md`。
+
+## 产出：填 `03-adapt.json`
+
+脚本末尾直接打出可誊写的字段块：
+
+```
+=== test_run（03-adapt.json 字段，直接誊写）===
+  executed=true
+  test_command=...
+  total_cases=N  passed=N  failed=N  skipped=N
+  pass_rate=...
+```
+
+- `pass_rate = passed / (passed + failed)`，**skipped 不计入分母**（否则带可选依赖 skip 的库永远够不到 1）。
+- `test_source` / `regressions[]` **须由 agent 填**——脚本不知道用例是原库自带还是本阶段补写的。
+- **通过与否以「原库用例逐条真跑过且全通过」为准，不以某个绝对数字为准。**
+- 全过 → `03-adapt.json` 的 **`status=built-and-verified`**（不是 `success`——那是 `04-summary.json` 的 `adaptation_status` 的值，串了会被 PostWrite Hook 拒）。语义权威：`pc-knowledge-base` 的「状态语义」段。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/runner-script-wiring.md

@@ -0,0 +1,86 @@
+# 随包脚本型 runner 接线（子进程调用 / RAW 分级回传 / fixture 真实性）
+
+> 适用：多例调度以**随包 shell 脚本**承载（每例 = 脚本入口函数 + 参数）的 cli-hnp-runner 工程。接线、判定、取证三层的铁律，全部来自真机返工实证（2026-09-18，一轮适配多轮返工的全部教训；2026-09-21 某交叉工具链工程测试线多轮续增：环境传递陷阱、进程组看门狗、心跳防 stalled、夹具注入）。
+
+## 1. 调用协议：必须子进程，禁 source
+
+**正确**（runner 的富用例体内）：
+
+```cpp
+// tool = tool_path()（bash ELF 全路径）；roster = pkg/bin/<调度脚本>
+const std::vector<std::string> args = {roster, id};          // 解释器 + 脚本 + 参数
+int rc = run_cmd(tool, args, sandbox, o, 300);
+const bool ok = (rc == 0) && o.find("PASS " + id) != std::string::npos;
+```
+
+**禁止** `. source` 进当前 shell 再调内部函数（`bash -c ". script; run_single x"`），三连坑实证：
+
+| 坑 | 机理 | 表象 |
+|---|---|---|
+| 入口块误触发 | source 时脚本读到的 `$#` 是外层 bash -c 的 **0**，凡 `$#=0 → 跑全量` 形态的入口都会整套重跑 | 单例耗时 ×N（20 例全跑一遍再跑目标例） |
+| 退出码方言 | sourced 函数 return 值经 bash 退出码传播，musl bash 上 FAIL 例被观测为 rc=0 | `FAIL xxx (rc=0)` 伪象——rc 与 PASS/FAIL 前缀互相矛盾，判定失真 |
+| CRLF/权限次生 | source 失败后 `;` 顺序继续执行未定义函数 | rc=127 与 rc=0 混杂 |
+
+判定公式保持 `rc==0 && stdout 含 "PASS <id>"` 双要件：任一要件单独都不可靠（rc 方言、PASS 行被脚本 bug 吞）。
+
+## 2. RAW 取证：失败例全量、pass 例折叠
+
+runner 末尾把 raw 逐行打 hilog 时，**不要全量**（整表 20 例 ×（DIAG+输出）远超 hilog 缓冲/行数窗口，中后段用例的失败细节全部丢失——排障时"日志里没有设备执行痕迹"就是这么来的）。模板 `dump_failure_sections()` 已内置正确策略：按 `--- <id>[ <cmd>] (rc=…) ---` 分段，只回放失败段（head 60 + tail 20 行、总 cap 2000），段尾全量 TAP 重放兜底。自写 runner 照此实现；失败段的 `stdout.log` dump（`dump_case_logs`）与 RAW 都要在。
+
+**长 exec 期间打心跳行，防捕采被判 stalled（某交叉工具链工程多轮实证 2026-09-21）**：捕采侧（verify-demo 三停轮询）以「hilog 一段时间无新行」判挂死提前收工——ct-ng/构建/下载类用例的 run() 可以安静数分钟，两轮捕采均停在某功能点附近（`stopped_by=stalled`），用例其实活着。修法：native runner 的 `run_cmd` 内起心跳线程，每 10s 打一行 `OHPTCASE heartbeat id=<caseId> elapsed=<s>`——**形状必须避开 result=/check=/summary 关键字**（逐条解析器按形状认行，见 OhptCases.ets 协议注释），RAII join、短命令（<10s）零污染。
+
+## 3. 断言对齐产品真实行为（三层自检）
+
+写用例预期前，每个断言过一遍：
+
+1. **断言静态符号，不断言派生符号**：配置文件里的派生量（组合出 target 元组类）写法随 kconfig 推导时序变化；`grep '^CT_静态项=y'` 级别的实写行才稳定。
+2. **断言文本取自当前 commit 的实际输出**：框架 help/usage 的分组名、命令清单随 commit 漂移（旧版有"Preconfigured toolchains"分组、新版没有；`olddefconfig` 命令存在但 help 不再列出）——**先在设备/host 上抓一次实际输出，再抄 keyword**。
+3. **排除运行时变量**：像 `CT_VCHECK`（按当前 make 目标注入 save/load）这类**非配置**变量不参与内容等价断言；roundtrip 类断言比较 **CT_ 设置集合**（`grep '^CT_' | sort | diff`，落临时文件——musl app 域 `/dev/fd` 进程替换 Permission denied）而非字节 diff。
+
+## 4. fixture 必须真实有效；前置不足判 blocked
+
+- 「tarball 已存在则跳过下载」类用例，fixture 必须是**完整且 digest 匹配**的真实包：0 字节/半截文件会被下载器判损坏并**重新下载**（网络受限沙箱 → rc≠0 → 假失败）。
+- **要测「校验失败」路径，预置 corrupt 文件无效——必须从下载通道注入（某交叉工具链工程 实证 2026-09-21）**：下载框架的 digest 校验只在「**下载成功后**」运行（CT_GetFile 对已存在文件走 skip-existing，不校验），本地预置 corrupt tarball 永远到不了校验逻辑。通解：给下载工具加 env 触发的夹具分支（如 `CTNG_FIXTURE_CORRUPT=<包名模式>` → wget shim 对命中 URL 返回 corrupt 内容、exit 0）→ 框架照常走「下载→校验」，sha512 mismatch 真实触发。夹具分支要**精确匹配包名模式**，防止污染真下载。
+- **dist/ 树加了夹具资源必须重编 HAP**：夹具随 HNP `share/`（如 `testdata/m4-1.4.20.tar.xz`）分发、设备侧 `cp` 预置——旧 HAP 里没有新夹具时 cp 静默失败（`2>/dev/null` 吞掉是帮凶），预置落空**回落真实网络下载**，原本已摆脱的网络依赖悄悄复活（fix4 轮 stalled 的直接根因：testdata 10:48 才放入 dist，10:28 构建的 HAP 不含它）。装机前对账：`unzip -l <hap>.hnp | grep testdata`。
+- 设备上无法预置有效 fixture（网络受限、需外网）→ 该例判 **blocked（precondition-unmet）**，打 `result=blocked` 行——与 scope_out 类同等，**不要塞 fail**（把环境限制记成产品缺陷）。
+- blocked 也要打 OHPTCASE 结果行（fail-closed 协议），why 字段写清缺什么前置。
+
+## 5. 环境传递与超时看门狗（某交叉工具链工程多轮实证 2026-09-21）
+
+**VAR=val 前缀赋值必须直接修饰命令，不能独立成行**：
+
+```bash
+# ✗ 错：独立行只设 shell 变量，不 export、不进子进程环境
+cd "$d" && http_proxy=http://127.0.0.1:1 CTNG_FIXTURE_CORRUPT='m4-' \
+  && make -f ct-ng.in source     # curl 拿不到代理/夹具变量 → 静默直连真网
+# ✓ 对：前缀赋值直接修饰命令（每段命令各自带上）
+cd "$d" && http_proxy=http://127.0.0.1:1 https_proxy=http://127.0.0.1:1 \
+  ftp_proxy=http://127.0.0.1:1 all_proxy=http://127.0.0.1:1 \
+  make -f ct-ng.in source
+```
+
+危害不成比例：`bash -c` 里 `VAR=val && cmd` 语义合法但**变量只活在当前 shell**——proxy 断网模拟空转成 rc=0、下载夹具不触发、断言假绿；更险的是**误诊**：现象被记成「app 域 seccomp 限制出网」这类平台能力缺口（本轮 capability_gaps 错误归因即由此来）。ftp:// 场景 curl 只认 `ftp_proxy`，http 系代理变量拦不住。判别口令：设备上 `cat /proc/<pid>/environ | tr '\0' '\n' | grep VAR` 查子进程**实际**环境，别查 shell 的。
+
+**超时看门狗必须杀进程组**：`alarm(N)` 默认 SIGTERM 只杀**直接子进程**（bash 映像）；`bash -c "make → sh -c → curl"` 链里的孙进程被孤儿化后**持有 stdout pipe**，父侧 `read()` 永不返回 → 该用例挂死数分钟（实证：F-02-01 挂 6 分钟，设备进程树见孤儿 curl）。修法（native runner `run_cmd` 模板）：
+
+```cpp
+// 子进程：进程组自首（fork 后、execv 前）
+setpgid(0, 0);
+// 父进程：poll() 1s 粒度计时，超时杀全组——不用 alarm
+if (elapsed > timeout_sec) { kill(-pid, SIGKILL); waitpid(pid, &st, 0); }
+```
+
+> **✅ 已固化进模板（2026-10-13，spec-设备名册执行器总能收尾）**：`cli-hnp-runner` /
+> `cpp-terminal-demo` / `python-app-subprocess` 三份模板的 exec 均已改为本实现（setpgid +
+> 非阻塞 drain + poll 计时 + 超时 `kill(-pid, SIGKILL)` + killed 标记），并新增**名册总预算**
+> （20min，对齐租约上限）作富用例 `tmo=0` 显式豁免的唯一安全网——豁免 ≠ 无兜底。
+> 本节片段从「应然实现」转为「实然描述」；E178 失效模式 2（blocked 掩码屏蔽信号）同由该
+> 实现反制。模板改动依据与验证记录见 `.spec/spec-设备名册执行器总能收尾（basis_universal+vulkan实证）.md`。
+
+## 6. 排障口令
+
+- summary 里 **pass 集全是否定路径（预期 rc≠0 的守卫类）→ 正路径必坏**，先看框架级失败（配置解析/工具链）再逐例。
+- `FAIL xxx (rc=0)` = 退出码传播断裂信号，查 runner 调用方式（source vs 子进程）；**整表恒 PASS 且失败例也对 PASS** → 查调度包装函数是否 echo 完固定 `return 0`（v1 roster 实证：report()/run_single() 不透传 rc，13 条失败全被误判 PASS；v2 逐层 `return ${rc}` + 子进程调用根退出码才落账）。
+- **设备进程树里出现「不该存在的真联网进程」**（如绕过代理的孤儿 curl）→ 环境变量没传进子进程（§5 VAR=val 陷阱），先查 environ 再怀疑平台网络策略。
+- RAW 里中后段用例无痕迹 = 回传截断，改 dump 策略而不是重跑。
+- 设备侧单跑一例定位：`aa test` 带参数进页面单例，或宿主等价复现断言（脚本逻辑可在 MSYS/host 用假命令替换被测工具验证调度与退出码）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/references/terminal-buffer-assert.py

@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""终端上屏验证 · 屏幕 buffer 断言脚本（pyte 重放 PTY 落盘流，语义级机判）。
+
+职责与边界（权威分层见 pc-device-verify SKILL「权威边界」）：
+  - 判定方法权威：pc-capability-domains/references/capability-domains/terminal-render.md
+  - 本脚本只做「把落盘的 PTY 原始流重放成屏幕 buffer，按断言清单逐条核对」——
+    「序列在场」≠「上屏效果正确」，本脚本是语义级判据的落地。
+
+用法（宿主机执行，非设备）：
+  python3 terminal-buffer-assert.py --case-file <cases.json> --out build/buffer-assert.json
+
+cases.json 形态（每用例一条）：
+  [
+    { "id": "F-04-03",
+      "stream": "build/device-runs-ncurses/F-04-03.log",     # 裸 PTY 流（不带 hilog 前缀/时间戳）
+      "width": 80, "height": 24,                              # 断言锚定的窗口尺寸（须与用例设置一致）
+      "feeds": [ {"file": "...resize.log", "width": 60} ],    # 可选：SIGWINCH 后续喂入（逐段 resize）
+      "assertions": [
+        {"type": "line_contains",   "line": 0, "text": "W1> "},
+        {"type": "wrap_col",        "text": "xxx", "col": 40},   # text 从第 col 列开始（折行位置）
+        {"type": "cursor_after",    "text": "bot> "},            # 光标紧跟 text 末次出现之后
+        {"type": "cursor_at",       "x": 5, "y": 0},
+        {"type": "has_color"}                                    # buffer 内有非默认前景/背景色
+      ] }
+  ]
+
+产出：--out 指定的 JSON（验收规则按 build/ 下 *buffer*.json 识别）+ stdout 打
+  result=pass/fail total=N passed=M（供日志机器判读）。断言不过 exit 1；pyte 缺失 exit 2。
+"""
+import argparse
+import datetime
+import json
+import sys
+
+try:
+    import pyte
+except ImportError:
+    print("pyte 未安装：宿主执行 `pip install pyte`（缺失时本断言降级为「序列在场」机判，见 pc-device-verify 操作节）")
+    sys.exit(2)
+
+
+def replay(feeds):
+    """按 (流文件, 宽) 序列喂入；段间 resize 模拟 SIGWINCH。返回 (screen, screen_history)。"""
+    first_w = feeds[0]["width"]
+    h = feeds[0].get("height", 24)
+    screen = pyte.Screen(first_w, h)
+    stream = pyte.ByteStream(screen)
+    history = []
+    for seg in feeds:
+        if seg["width"] != screen.columns or seg.get("height", 24) != screen.lines:
+            screen.resize(seg.get("height", 24), seg["width"])
+        with open(seg["file"], "rb") as f:
+            stream.feed(f.read())
+        history.append({"file": seg["file"], "width": seg["width"], "display": list(screen.display)})
+    return screen, history
+
+
+def check(case, screen, history):
+    """返回失败明细列表（空 = 该用例全过）。断言语义见模块 docstring。"""
+    display = list(screen.display)
+    flat = "\n".join(display)
+    failures = []
+    for a in case.get("assertions", []):
+        t = a.get("type")
+        if t == "line_contains":
+            line = int(a["line"])
+            if not (0 <= line < len(display)) or a["text"] not in display[line]:
+                failures.append({"assertion": a, "detail": f"第 {line} 行不含 {a['text']!r}；该行={display[line] if 0 <= line < len(display) else '<越界>'!r}"})
+        elif t == "wrap_col":
+            hit = next((i for i, l in enumerate(display) if l[a["col"]:].startswith(a["text"])), None)
+            if hit is None:
+                failures.append({"assertion": a, "detail": f"没有行在第 {a['col']} 列起出现 {a['text']!r}（折行位置不符）"})
+        elif t == "cursor_after":
+            pos = flat.rfind(a["text"])
+            if pos < 0:
+                failures.append({"assertion": a, "detail": f"屏幕上找不到 {a['text']!r}"})
+                continue
+            line = flat.count("\n", 0, pos)
+            col = pos - (flat.rfind("\n", 0, pos) + 1) + len(a["text"])
+            if not (screen.cursor.y == line and screen.cursor.x == col):
+                failures.append({"assertion": a, "detail": f"光标在 ({screen.cursor.x},{screen.cursor.y})，期望 ({col},{line})"})
+        elif t == "cursor_at":
+            if not (screen.cursor.x == a["x"] and screen.cursor.y == a["y"]):
+                failures.append({"assertion": a, "detail": f"光标在 ({screen.cursor.x},{screen.cursor.y})，期望 ({a['x']},{a['y']})"})
+        elif t == "has_color":
+            colored = any(c.fg not in (None, "default") or c.bg not in (None, "default")
+                          for row in screen.buffer.values() for c in row.values())
+            if not colored:
+                failures.append({"assertion": a, "detail": "buffer 内无任何非默认前景/背景色（SGR 未生效或未发）"})
+        else:
+            failures.append({"assertion": a, "detail": f"未知断言类型 {t!r}"})
+    return failures
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--case-file", required=True)
+    ap.add_argument("--out", default="build/buffer-assert.json")
+    args = ap.parse_args()
+
+    with open(args.case_file, "r", encoding="utf-8") as f:
+        cases = json.load(f)
+
+    results, total, passed = [], 0, 0
+    for case in cases:
+        feeds = case.get("feeds") or [{"file": case["stream"], "width": case["width"], "height": case.get("height", 24)}]
+        try:
+            screen, history = replay(feeds)
+            failures = check(case, screen, history)
+        except Exception as e:  # 单用例重放失败不拖垮整批——记失败继续
+            failures = [{"assertion": None, "detail": f"重放异常：{e}"}]
+            history = []
+        total += 1
+        passed += 1 if not failures else 0
+        results.append({"id": case.get("id"), "ok": not failures, "failures": failures,
+                        "screen_head": history[-1]["display"][:6] if history else None})
+
+    out = {"generated_at": datetime.datetime.now().isoformat(), "pyte": getattr(pyte, "__version__", "?"),
+           "summary": {"total": total, "passed": passed, "failed": total - passed}, "cases": results}
+    with open(args.out, "w", encoding="utf-8") as f:
+        json.dump(out, f, ensure_ascii=False, indent=2)
+    print(f"result={'pass' if total == passed else 'fail'} id=__screen_buffer__ "
+          f"total={total} passed={passed} failed={total - passed} → {args.out}")
+    sys.exit(0 if total == passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/scripts/device_verify.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+# 通用鸿蒙 PC 设备端验证（幂等/可续跑/双通道）：已装好且能 import 就跳过安装+签名，直接跑 pytest。
+# 两条通道共用本脚本，差异（工作区/域 env/是否签名）按 uid 自动判定，见 skill 的 references/channel-*.md：
+#   hdc shell 域直连：hdc shell "PKG=pywt WHL=... python3.12 <本脚本>"
+#   HiShell（零售机）：    由 hishell_driver.sh 的 hs_verify 驱动
+# 结果写 <WORK>/<PKG>_verify.log；FORCE=1 强制重装+重签。
+import os
+
+# ── 必须早于任何 numpy/OpenBLAS 加载 ────────────────────────────────────────
+# 设备 numpy 自带的 OpenBLAS 0.3.27 会被派发到 armv8sve，其复数点积内核
+# zdotu/cdotu 返回错误实部（虚部正确）→ dot/vdot/inner/matmul(1-D)/correlate/
+# convolve 的复数结果全错。实测 n=64 实部误差 4.09，且 n=1 恰好正确、极易漏判。
+# 权威：pc-knowledge-base/adaptation/鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug.md
+os.environ.setdefault("OPENBLAS_CORETYPE", "ARMV8")
+
+import glob, re, shutil, struct, subprocess, sys, sysconfig, traceback
+
+PKG = os.environ.get("PKG", "").strip()                       # import 名，必填，如 pywt / numpy
+WHL = os.environ.get("WHL", "").strip()                       # 设备上 wheel 路径；留空=跳过安装
+RUN_TESTS = os.environ.get("RUN_TESTS", "1") == "1"
+FORCE = os.environ.get("FORCE", "0") == "1"                   # 强制重装+重签（默认幂等跳过）
+PY = os.environ.get("PY", "python3.12")
+SIGN = os.environ.get("SIGN", "auto")                         # auto/1=签（鸿蒙 PC 恒需签，与 uid 无关） / 0=不签
+
+# ── 通道/域判定：uid 决定工作区、可写目录、是否需要签名 ──────────────────────
+# 两个域的可写目录【正好相反】，混用必炸：
+#   root 域：/ 与 /root 只读，须把 TMPDIR/HOME/MPLCONFIGDIR 指到 /data/local/tmp
+#            （权威：pc-knowledge-base/platform/鸿蒙PC-设备pip部署.md）
+#   App 域：/data/local/tmp 是 shell(uid2000) 的目录，App 写不进去，用默认的
+#            /storage/Users/currentUser/... 即可
+#            （权威：pc-knowledge-base/platform/鸿蒙PC-不可调试设备用HiShell自动化测试.md）
+IS_ROOT = (os.geteuid() == 0)
+if IS_ROOT:
+    DOMAIN = "root(可调试)"
+    WORK = os.environ.get("WORK", "/data/local/tmp/pc-adapt-verify")
+    # 这里【不能】用 setdefault：hdc shell 已把 HOME 设成 /root、TMPDIR 默认 /tmp，
+    # 而 root 域下这两个目录【只读】——继承来的坏默认值正是要修的对象，setdefault
+    # 见 key 存在就跳过，等于什么也没做。实测不改直接炸：
+    #   OSError: [Errno 30] Read-only file system: '/root'
+    # 故：坏默认值一律替换，调用方【显式】给的值才尊重。
+    if os.environ.get("HOME") in (None, "", "/root"):
+        os.environ["HOME"] = "/data/local/tmp/home"
+    if os.environ.get("TMPDIR") in (None, "", "/tmp"):
+        os.environ["TMPDIR"] = "/data/local/tmp"
+    os.environ.setdefault("MPLCONFIGDIR", "/data/local/tmp/mpl")
+    os.makedirs(os.environ["HOME"], exist_ok=True)
+else:
+    DOMAIN = "app(HiShell/零售)"
+    WORK = os.environ.get("WORK", "/storage/Users/currentUser/Desktop/.pc-adapt-verify")
+
+os.makedirs(WORK, exist_ok=True)
+LOG = os.environ.get("LOG", "%s/%s_verify.log" % (WORK, PKG or "device"))
+BASETEMP = "%s/_pt_%s" % (WORK, PKG or "x")                   # 新建、当前域自有，绕开 pytest 属主校验
+
+_out = []
+def p(*a):
+    line = " ".join(str(x) for x in a)
+    _out.append(line)
+    print(line, flush=True)                       # 同时打到 stdout，便于 hs_exec 用 .cmd.out 收全
+    with open(LOG, "w", encoding="utf-8") as f:
+        f.write("\n".join(_out) + "\n")
+def sh(c):
+    r = subprocess.run(c, shell=True, capture_output=True, text=True)
+    return r.returncode, (r.stdout + r.stderr).strip()
+def try_import():
+    try:
+        return __import__(PKG)
+    except Exception:
+        return None
+
+def max_load_align(path):
+    """纯 Python 解析 ELF64 program header，取 PT_LOAD 的最大 p_align。
+    不 shell 出去调 llvm-readelf——root 域 PATH 上根本没有它（工具链只挂在 app
+    mount namespace）。设备是 4KB 页，0x10000 对齐的 .so 会在 dlopen 时【裸
+    SIGSEGV、无任何报错】，比签名失败更难查。
+    权威：pc-knowledge-base/platform/鸿蒙PC-64KB页对齐so崩溃.md"""
+    try:
+        with open(path, "rb") as f:
+            head = f.read(64)
+            if head[:4] != b"\x7fELF" or head[4] != 2:        # 仅处理 ELF64
+                return None
+            e = "<" if head[5] == 1 else ">"
+            phoff, = struct.unpack_from(e + "Q", head, 32)
+            phentsize, phnum = struct.unpack_from(e + "HH", head, 54)
+            f.seek(phoff)
+            ph = f.read(phentsize * phnum)
+            aligns = []
+            for i in range(phnum):
+                off = i * phentsize
+                if struct.unpack_from(e + "I", ph, off)[0] == 1:      # PT_LOAD
+                    aligns.append(struct.unpack_from(e + "Q", ph, off + 48)[0])
+            return max(aligns) if aligns else None
+    except Exception:
+        return None
+
+if not PKG:
+    p("ERROR: 必须设置环境变量 PKG=<import 名>"); sys.exit(0)
+
+p("PKG=%s | domain=%s | uid=%d | platform=%s | EXT_SUFFIX=%s | FORCE=%s"
+  % (PKG, DOMAIN, os.geteuid(), sysconfig.get_platform(),
+     sysconfig.get_config_var("EXT_SUFFIX"), FORCE))
+# 记录【实际】运行时，而不是信任任何硬编码路径（python 布局因设备而异：
+# 零售+DevBox 在 /storage/Users/currentUser/usr/local/bin，本机 hnppublic 布局则不然）
+p("runtime: %s | %s" % (shutil.which(PY) or PY, sys.version.split()[0]))
+p("env: OPENBLAS_CORETYPE=%s TMPDIR=%s HOME=%s"
+  % (os.environ.get("OPENBLAS_CORETYPE"), os.environ.get("TMPDIR"), os.environ.get("HOME")))
+p("WORK=%s" % WORK)
+
+# —— 幂等：已能 import 就跳过安装+签名（续跑直奔测试）——
+mod = None if FORCE else try_import()
+if mod is not None:
+    p("RESUME: %s 已可 import (v%s)，跳过安装+签名" % (PKG, getattr(mod, "__version__", "?")))
+else:
+    if WHL:
+        # --no-deps：设备无可用 NDK（HNP 里的 clang 指向未安装的 ohos-sdk），
+        # 任何 sdist 回退编译必然失败；依赖须预装或另行交叉编译。
+        rc, o = sh('%s -m pip install "%s" --force-reinstall --no-deps' % (PY, WHL))
+        p("pip install rc=%d :: %s" % (rc, o.splitlines()[-1] if o else ""))
+    sp = sysconfig.get_paths()["purelib"]
+    sos = sorted(glob.glob(os.path.join(sp, PKG, "**", "*.so"), recursive=True))
+
+    # —— 页对齐留证（【不】作判据，只在 import 前把嫌疑写进磁盘日志）——
+    # 为什么只留证不判死：实测本设备 418 个自带 .so 中 345 个就是 0x10000 对齐，
+    # numpy/ctypes/ssl/_decimal 全部 import 正常 —— 所以 64KB【不必然】崩，拿它当
+    # 判据会把 numpy 这类好库误杀。它只是个相关信号，真实成因未定论。
+    # 真正的价值：p() 每次都落盘，故即便下一步 import 被 SIGSEGV 打死（进程直接没
+    # 了、什么都来不及打印），这份嫌疑名单也已经在日志里了。
+    big = [(so, a) for so, a in ((s, max_load_align(s)) for s in sos)
+           if a is not None and a > 0x1000]
+    if big:
+        p("页对齐：%d/%d 个 .so 是 >4KB 对齐（设备 4KB 页）" % (len(big), len(sos)))
+        for so, a in big[:10]:
+            p("  · %s p_align=0x%x" % (os.path.basename(so), a))
+        p("  ↑ 非判据（本机自带 .so 多数也是 0x10000 且正常）。但若紧接着的 import"
+          " 【直接段错误、无任何输出】，优先怀疑这批：重编时加 -Wl,-z,max-page-size=0x1000"
+          "（patchelf 改不了 p_align）。见 pc-knowledge-base/platform/鸿蒙PC-64KB页对齐so崩溃.md")
+    else:
+        p("页对齐：%d 个 .so 均 <=0x1000" % len(sos))
+
+    # —— 签名：鸿蒙 PC 强制代码签名，【与 uid/设备档无关】（设备分档轴已废弃）——
+    # 设备侧自签需要 DevBox 的 binary-sign-tool，商用机上【根本没有】(/data/service/hnp 不存在)。
+    # 探不到就【明确报出来】，不静默跳过、更不当成已签——那正是"扫到 0 当干净"的假阴性。
+    # 正路是宿主链接期自签 LDFLAGS='-Wl,--code-sign'（post-link strip 会破坏签名段）。
+    if SIGN == "0":
+        p("=== 签名：跳过（SIGN=0，调用方显式关闭）===")
+    elif shutil.which("binary-sign-tool") is None:
+        p("=== 签名：设备侧【无 binary-sign-tool】（本机无 DevBox；商用机的常态）===")
+        p("  → 未签的 .so import 会报 Permission denied。修法：回宿主用 "
+          "LDFLAGS='-Wl,--code-sign' 重新链接（别在 post-link strip），或改走私有 HNP "
+          "执行器 HAP（ohpt-agent scaffold --kind cli-hnp-runner）。见 pc-error-atlas E077/E129。")
+    else:
+        p("=== 签名 %d 个 .so（设备侧 binary-sign-tool 自签）===" % len(sos))
+        for so in sos:
+            sh('llvm-objcopy --remove-section .codesign "%s"' % so)
+            rc, _ = sh('binary-sign-tool sign -inFile "%s" -outFile "%s" -selfSign 1' % (so, so))
+            sh('chmod +x "%s"' % so)
+            p("  %s rc=%d codesign=%s" % (os.path.basename(so), rc, b".codesign" in open(so, "rb").read()))
+
+    mod = try_import()
+    if mod is None:
+        p("IMPORT FAIL:"); p(traceback.format_exc())
+        p("归因见 skill 的 references/failure-triage.md")
+        p("RESULT: FAIL"); print("done"); sys.exit(0)
+    p("=== import %s OK, version=%s ===" % (PKG, getattr(mod, "__version__", "?")))
+
+# —— 全量 pytest（库自带测试在 wheel 内时）——
+if RUN_TESTS:
+    sh("rm -rf " + BASETEMP)
+    # -p no:cacheprovider：否则 pytest 往只读的 / 写 .pytest_cache
+    cmd = '%s -m pytest --pyargs %s -q -p no:cacheprovider --no-header --basetemp=%s' % (PY, PKG, BASETEMP)
+    rc, o = sh(cmd)
+    lines = o.splitlines()
+    fails = [l for l in lines if "FAILED" in l or (" ERROR" in l and "setup" not in l)]
+    p("--- FAILED (%d) ---" % len(fails))
+    for l in fails[:50]:
+        p(l)
+    p("--- tail ---")
+    for l in lines[-8:]:
+        p(l)
+
+    # —— 证据字段化：直接对应 03-adapt.json 的 test_run 子字段，agent 誊写即可 ——
+    def _n(kind):
+        m = re.search(r"(\d+) %s" % kind, o)
+        return int(m.group(1)) if m else 0
+    passed, failed, skipped, errors = _n("passed"), _n("failed"), _n("skipped"), _n("error")
+    denom = passed + failed
+    p("=== test_run（03-adapt.json 字段，直接誊写）===")
+    p("  executed=true")
+    p("  test_command=%s" % cmd)
+    p("  total_cases=%d" % (passed + failed + skipped))
+    p("  passed=%d" % passed)
+    p("  failed=%d" % failed)
+    p("  skipped=%d" % skipped)
+    # pass_rate 定义见 pc-knowledge-base 的「状态语义」：skipped 不计入分母。
+    # pass_rate 仅作报告数值，不是 built-and-verified 的判据——判据是【用例真跑过且全通过】（见下方注释）
+    p("  pass_rate=%s" % ("%.4f" % (passed / denom) if denom else "null"))
+    if errors:
+        p("  # 另有 %d 个 error（多为框架/环境，非功能失败）" % errors)
+    p("  # test_source / regressions[] 须由 agent 填——")
+    p("  #   通过与否以【原库用例逐条真跑过且全通过】为准，不以某个绝对数字为准")
+    p("RESULT: %s (pytest rc=%d)" % ("PASS" if rc == 0 else "CHECK", rc))
+    if rc != 0:
+        p("失败别默认当真实平台缺陷——先按 references/failure-triage.md 三分类归因")
+else:
+    p("RESULT: import-only PASS")
+print("done")

package/node_modules/@ohos-agent/pc-adapter/skills/pc-device-verify/scripts/hishell_driver.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# 通过 hdc + uitest/uinput 远程驱动鸿蒙 PC 的 HiShell 终端。source 本文件后用下面的函数。
+# 适用：需要 App 上下文时的手动兜底（hdc shell=uid2000 进不去 App 沙箱，但能驱动 HiShell GUI）。
+# 自动化首选是私有 HNP 执行器 HAP（ohpt-agent scaffold --kind cli-hnp-runner），本脚本是兜底。
+# 依赖：hdc 在 PATH；设备已连接（hdc list targets 有目标）。Git Bash 下已处理 MSYS 路径改写。
+# 注意：推送到设备的 .sh/.py 必须是 LF 换行，CRLF 会导致 zsh 报语法错误/heartbeat 不出现。
+set -o pipefail
+
+HS_BUNDLE="com.huawei.hmos.hishell"
+HS_ABILITY="EntryAbility"
+# 桌面是 hdc 与 App 唯一的双向桥（App 的 Documents/Download/tmp 等都是沙箱私有，hdc 看不到）。
+# 用桌面下的【隐藏专用目录】.pc-adapt-verify 当工作区——不污染可见桌面，且双向可读写。
+# userId【因设备而异】（常见 100，务必核实——见 pc-knowledge-base 的
+# platform/鸿蒙PC-应用沙箱与物理路径映射.md）。要改就在 source 本文件【之前】
+# export HS_USERID=<值>；不确定就跑 hs_probe_userid 探。
+HS_USERID="${HS_USERID:-100}"
+HS_DESK_PHYS="/storage/media/$HS_USERID/local/files/Docs/Desktop"  # 桌面，hdc 视角（物理）
+HS_DESK_LOGI="/storage/Users/currentUser/Desktop"                 # 桌面，App 视角（逻辑）
+HS_WORK_NAME=".pc-adapt-verify"
+HS_WORK_PHYS="$HS_DESK_PHYS/$HS_WORK_NAME"                        # 工作区 hdc 视角
+HS_WORK_LOGI="$HS_DESK_LOGI/$HS_WORK_NAME"                        # 工作区 App 视角（脚本里用它拼路径）
+HS_KEY_ENTER=2054
+HS_KEY_CTRL=2072
+HS_KEY_SPACE=2050
+
+# 启动 HiShell 终端
+hs_launch() { hdc shell "aa start -b $HS_BUNDLE -a $HS_ABILITY" >/dev/null 2>&1; sleep 2; }
+
+# 探测设备实际 userId（多用户设备取第一个）
+hs_probe_userid() {
+  hdc shell "ls -d /storage/media/*/local/files/Docs/Desktop" 2>/dev/null \
+    | tr -d '\r' | head -1 | sed -n 's|.*/storage/media/\([0-9][0-9]*\)/.*|\1|p'
+}
+
+# 建工作区并【显式校验】（推任何文件前先调一次）
+# 为什么非校验不可：hdc shell 即使远端命令失败通常也返回 0，叠加 >/dev/null 2>&1
+# 吞掉 stderr，出错会【无声通过】，随后每一步都以难懂的方式炸。
+# 校验必须【先于】mkdir -p：mkdir -p 会把不存在的父目录一路造出来，userId 写错时
+# 会在 /storage/media/<错值>/ 下凭空长出一棵垃圾树，事后再查“目录在不在”永远是“在”
+# ——等于没查（实测 HS_USERID=999 照样 mkdir 成功）。
+hs_init() {
+  if ! hdc shell "[ -d $HS_DESK_PHYS ] && echo __OK__" 2>/dev/null | grep -q __OK__; then
+    echo "[hs_init 失败] 桌面路径不存在：$HS_DESK_PHYS" >&2
+    local real; real="$(hs_probe_userid)"
+    if [ -n "$real" ]; then
+      echo "  探到设备实际 userId=$real（当前 HS_USERID=$HS_USERID）。重来：" >&2
+      echo "    export HS_USERID=$real && source <本文件>" >&2
+    else
+      echo "  没探到任何 userId。自查：hdc list targets 有设备吗？" >&2
+      echo "    hdc shell \"ls -d /storage/media/*/local/files/Docs/Desktop\"" >&2
+    fi
+    return 1
+  fi
+  hdc shell "mkdir -p $HS_WORK_PHYS" >/dev/null 2>&1
+  hdc shell "[ -d $HS_WORK_PHYS ] && echo __OK__" 2>/dev/null | grep -q __OK__ && return 0
+  echo "[hs_init 失败] 桌面在、但工作区建不出来：$HS_WORK_PHYS（权限？）" >&2
+  return 1
+}
+
+# 跑完清理工作区（含日志/wheel/临时件）
+hs_clean() { hdc shell "rm -rf $HS_WORK_PHYS" >/dev/null 2>&1; }
+
+# 点终端聚焦（默认点中间；坐标可传参）
+hs_focus() { hdc shell "uitest uiInput click ${1:-1404} ${2:-936}" >/dev/null 2>&1; }
+
+# 切换输入法（Ctrl+Space 是切换非确保，可能越切越乱；hs_exec 用循环+检测自纠错）
+hs_ime_toggle() { hdc shell "uitest uiInput keyEvent $HS_KEY_CTRL $HS_KEY_SPACE" >/dev/null 2>&1; sleep 1; }
+# 旧名兼容
+hs_ime_en() { hs_ime_toggle; }
+
+# 本地路径转 Windows 形式（hdc.exe 需要；远端 /storage 路径靠 MSYS_NO_PATHCONV 保持原样）
+_hs_win() { cygpath -w "$1" 2>/dev/null || echo "$1"; }
+
+# 推文件到工作区：hs_push <本地路径> <设备文件名>
+hs_push() { MSYS_NO_PATHCONV=1 hdc file send "$(_hs_win "$1")" "$HS_WORK_PHYS/$2"; }
+
+# 从工作区取文件：hs_pull <设备文件名> <本地路径>
+hs_pull() { MSYS_NO_PATHCONV=1 hdc file recv "$HS_WORK_PHYS/$1" "$(_hs_win "$2")" 2>/dev/null; }
+
+# 截屏到本地（仅 UI 调试用，正常流程不需要）：hs_cap <本地png>
+hs_cap() { hdc shell "uitest screenCap -p /data/local/tmp/_hs.png" >/dev/null 2>&1; MSYS_NO_PATHCONV=1 hdc file recv /data/local/tmp/_hs.png "$1" 2>/dev/null; }
+
+# ★★ 可靠执行（非持久 / 不截图 / 自纠错）★★
+# hs_exec '<shell命令>' [总超时秒=600] [本地结果文件=./.hs_out]
+# 机制：① 命令写进工作区 .cmd.sh + 固定 .runner.sh（claim 后跑、把 stdout/stderr/退出码写 .cmd.out）
+#       ② 冷启 HiShell（force-stop+start 保证开窗 + 新 shell）→ 切英文 → 点焦点
+#       ③ 打【固定短命令】zsh .../.runner.sh + 回车
+#       ④ 判定靠【输出文件】不靠截图：
+#          .runner.sh 先写 .heartbeat=Y（证明 runner 自身启动成功）再执行 cmd
+#          .cmd.out 一出现=触发成功（runner 起来了）→ 只等 __EXIT__=
+#          若 ~12s 内 .heartbeat 没出现（中文乱码/没回车）→ 切英文+重发，最多 5 次
+#          若 .heartbeat 出现但 .cmd.out 始终没有 → runner.sh 内部报错，拉取 .runner.log 排查
+hs_exec() {
+  local cmd="$1" timeout="${2:-600}" local_out="${3:-./.hs_out}"
+  local trig="zsh $HS_WORK_LOGI/.runner.sh" tmp_r tmp_c i waited
+  hs_init || return 1
+  tmp_r="$(mktemp 2>/dev/null || echo /tmp/_hs_runner.sh)"; tmp_c="$(mktemp 2>/dev/null || echo /tmp/_hs_cmd.sh)"
+  {
+    echo '__d='"$HS_WORK_LOGI"
+    echo 'echo Y > "$__d/.heartbeat"'
+    echo '[ -f "$__d/.cmd.sh" ] || { echo "NO_CMD" > "$__d/.cmd.out"; exit 0; }'
+    echo 'mv "$__d/.cmd.sh" "$__d/.cmd.run" 2>/dev/null || { echo "CLAIM_FAIL" > "$__d/.cmd.out"; exit 0; }'
+    echo 'zsh "$__d/.cmd.run" > "$__d/.cmd.out" 2>&1'
+    echo 'echo "__EXIT__=$?" >> "$__d/.cmd.out"; rm -f "$__d/.cmd.run"'
+  } > "$tmp_r"
+  printf '%s\n' "$cmd" > "$tmp_c"
+  hdc shell "rm -f $HS_WORK_PHYS/.cmd.out $HS_WORK_PHYS/.cmd.run $HS_WORK_PHYS/.heartbeat" >/dev/null 2>&1
+  MSYS_NO_PATHCONV=1 hdc file send "$(_hs_win "$tmp_r")" "$HS_WORK_PHYS/.runner.sh" >/dev/null 2>&1
+  MSYS_NO_PATHCONV=1 hdc file send "$(_hs_win "$tmp_c")" "$HS_WORK_PHYS/.cmd.sh"     >/dev/null 2>&1
+  # 冷启，保证开窗 + 全新 shell
+  hdc shell "aa force-stop $HS_BUNDLE" >/dev/null 2>&1; sleep 2
+  hdc shell "aa start -b $HS_BUNDLE -a $HS_ABILITY" >/dev/null 2>&1; sleep 3
+  hs_focus
+  for ((i=1;i<=5;i++)); do
+    # 第1次不切输入法（可能已经是英文），第2次起切换重试
+    ((i >= 2)) && { hs_ime_toggle; hs_focus; }
+    hdc shell "uitest uiInput keyEvent $HS_KEY_ENTER" >/dev/null 2>&1            # 清残留行
+    hdc shell "uinput -K -t '$trig'" >/dev/null 2>&1; sleep 1
+    hdc shell "uitest uiInput keyEvent $HS_KEY_ENTER" >/dev/null 2>&1
+    waited=0
+    while ((waited < 15)); do sleep 3; waited=$((waited+3))
+      if hdc shell "[ -f $HS_WORK_PHYS/.heartbeat ] && echo Y" 2>/dev/null | grep -q Y; then
+        # runner 已启动，等 cmd 输出
+        waited=0
+        while ((waited < timeout)); do
+          if hdc shell "[ -f $HS_WORK_PHYS/.cmd.out ] && echo Y" 2>/dev/null | grep -q Y; then
+            hs_pull .cmd.out "$local_out"
+            grep -q "__EXIT__=" "$local_out" 2>/dev/null && { echo "[hs_exec ok, ${i}次触发]"; return 0; }
+            grep -q "NO_CMD\|CLAIM_FAIL" "$local_out" 2>/dev/null && { echo "[hs_exec runner 报错: $(cat "$local_out")]"; return 1; }
+          fi
+          sleep 5; waited=$((waited+5))
+        done
+        echo "[hs_exec 超时：runner 已启动但 ${timeout}s 内 cmd.out 未完成，拉取已有结果]"; hs_pull .cmd.out "$local_out"; return 2
+      fi
+    done
+    echo "[hs_exec 第${i}次触发未生效（runner 未启动，疑似中文 IME / 没回车），切换输入法重试]"
+  done
+  echo "[hs_exec 失败：5 次触发均未起（.heartbeat 始终未出现）；可 hs_cap 截图人工排查]"; return 1
+}
+
+# 一步到位跑通用验证脚本（需先 hs_push device_verify.py 与 wheel）
+# 用法：hs_verify <PKG> <工作区里wheel文件名|空> [本地结果文件]
+hs_verify() {
+  local pkg="$1" whl="$2" out="${3:-./${1}_verify.out}" whlpath=""
+  [ -n "$whl" ] && whlpath="$HS_WORK_LOGI/$whl"
+  hs_exec "WORK=$HS_WORK_LOGI PKG=$pkg WHL=$whlpath python3.12 $HS_WORK_LOGI/device_verify.py" 900 "$out"
+  echo "--- 设备结果 ($out) ---"; cat "$out" 2>/dev/null
+}