@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-/350/277/236/346/216/245/350/256/276/345/244/207/344/270/216hdc/345/237/272/347/241/200.md

@@ -0,0 +1,81 @@
+---
+name: 鸿蒙PC-连接设备与hdc基础
+description: 连接/验证鸿蒙 PC 设备并用 hdc 做适配所需的全部操作——找设备、传文件、端口转发、拉设备 Python 头文件、推产物到设备跑用例、无设备时如何降级。适配验证阶段交叉编译完后必须靠 hdc 把产物和用例送设备测试。
+metadata:
+  type: platform
+  source: new/PC
+---
+
+# 鸿蒙 PC：连接设备与 hdc 基础（适配验证必读）
+
+`hdc` 是鸿蒙设备调试桥（类比 adb），随 HarmonyOS SDK 提供（在 `sdk/.../toolchains/` 下，需在 PATH）。**本机只做交叉编译；编完的产物 + 用例一律靠 hdc 送设备跑**（产物是 aarch64-ohos/musl，本机跑不起来）。
+
+## 1. 找设备 / 验证在线
+
+```bash
+hdc list targets                 # 列出在线设备 serial；输出 [Empty] 或空 = 无设备
+hdc shell echo ok                # 单设备直接验证；返回 ok 即连通
+hdc -t <serial> shell uname -a   # 多设备时用 -t <serial> 指定
+```
+
+- **多设备**：所有命令加 `-t <serial>`（serial 取 `hdc list targets` 第一列）。
+- **无线/网络连接**（如设备不在 USB）：`hdc tconn <ip>:<port>`（需设备先开 TCP 调试且与主机同网段）。注意设备 wlan0 多是 `100.125.x.x` 华为 CGNAT 段，**主机直连该 IP 多半不通**——访问设备上的服务要用端口转发（见 [[鸿蒙PC-从Mac访问设备网络服务]]）。
+- **找不到 hdc**：确认 HarmonyOS SDK 的 toolchains 目录在 PATH。
+
+## 2. 文件传输（适配的命脉）
+
+```bash
+hdc file send <本地路径> <设备路径>     # 主机 → 设备（推产物、用例）
+hdc file recv <设备路径> <本地路径>     # 设备 → 主机（拉 Python 头文件/库）
+```
+
+- 设备**可写暂存目录**：`/data/local/tmp/`（跑测试就放这）。
+- 传整个目录慢：**打包成单文件 send 过去，再在设备 `tar -xzf` 解压**，快得多。
+- 路径视角：`hdc shell` 是 root 看到的是**真实路径**（如桌面 `/storage/media/<userId>/local/files/Docs/Desktop`），与电脑端逻辑路径（`/storage/Users/currentUser/Desktop`）不同；详见 [[鸿蒙PC-进程视角与mount-namespace]]。`/storage/cloud/<userId>/...` 是云镜像，**不要写入**。
+
+## 3. 设备 shell（默认 root）
+
+```bash
+hdc shell "<命令>"               # 默认 root 身份
+```
+
+- root 的 PATH 不含 HNP，**自动化里一律用绝对路径**调设备程序（如 `/data/app/el1/bundle/<userId>/hnppublic/bin/python3.12`）。
+- 子进程 exec HNP 二进制可能被 SELinux 拦（见 [[鸿蒙PC-HNP二进制SELinux-exec限制]]）；dlopen 的 `.so` 不受此限。
+
+## 4. 端口转发（访问设备服务/调试端口）
+
+```bash
+hdc fport tcp:<端口> tcp:<端口>          # 把设备端口转发到本机 127.0.0.1
+hdc fport ls                            # 查看现有转发
+hdc fport rm tcp:<端口>                  # 移除
+hdc shell "netstat -tlnp" | grep LISTEN # 看设备上谁在监听哪些端口
+```
+
+转发后本机连 `127.0.0.1:<端口>`（如 `sftp -P 60022 ohos@127.0.0.1`）。**本机若有系统代理（Clash 等），连 127.0.0.1 也可能被劫持**——先关代理或 `--noproxy '*'`。详见 [[鸿蒙PC-从Mac访问设备网络服务]]。
+
+## 5. 适配验证里 hdc 的标准三步
+
+```bash
+# (1) 交叉编译前：从设备拉 Python 3.12 头/库到 CWD 内 staging（拿正确 ABI + 避开外部读权限）
+hdc file recv /data/app/el1/bundle/<userId>/hnppublic/python.org/python_3.12/include/python3.12 \
+  .ohos-adaptation-pc/build/device-python/include
+hdc file recv /data/app/el1/bundle/<userId>/hnppublic/python.org/python_3.12/lib/libpython3.12.so \
+  .ohos-adaptation-pc/build/device-python/lib/
+
+# (2) 编完：推产物 + 纯代码包 + 阶段2用例 到设备暂存
+hdc file send dist/_dwt.cpython-312.so /data/local/tmp/pywt-test/pywt/_extensions/
+hdc file send tests-generated /data/local/tmp/pywt-test/tests-generated
+
+# (3) 设备上跑（用设备 python 绝对路径 + PYTHONPATH）
+hdc shell "cd /data/local/tmp/pywt-test && PYTHONPATH=. \
+  /data/app/el1/bundle/<userId>/hnppublic/bin/python3.12 -m pytest baseline -q"
+```
+
+设备关键路径速查见 [[鸿蒙PC-设备Python运行时]]（python3.12 绝对路径、site-packages、ABI）。
+
+## 6. 无设备时怎么办
+
+`hdc list targets` 为空 = 没设备。**不要在本机硬跑目标产物**。本机交叉编译照常出产物（`build_status=pass`），把 `test_run.executed=false`、`status=partial`、`remaining_blockers` 记「无鸿蒙设备，未做设备回归」，正常输出 `03-adapt.json` 结束——产物仍有价值，待有设备再回归。
+
+## 相关
+- [[鸿蒙PC-设备Python运行时]] · [[鸿蒙PC-从Mac访问设备网络服务]] · [[鸿蒙PC-进程视角与mount-namespace]] · [[鸿蒙PC-HNP二进制SELinux-exec限制]]

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/351/232/217/345/214/205wrapper/350/204/232/346/234/254shebang/350/207/252/346/214/207/344/270/216busybox-seccomp.md

@@ -0,0 +1,40 @@
+# 随包 wrapper 脚本 shebang 自指与 busybox seccomp
+
+> 一句话：随包工具树里的 wrapper 脚本 shebang 写 `#!/bin/bash` 在设备上必死（rc=126，无标准 FHS）；而 busybox applet 在 app 域 seccomp 下部分调用会被 SIGSYS 击杀——工具树要么 shebang 自指 HNP 内 bash、要么用交叉编译的真 GNU 工具替换关键 applet。
+
+## 症状（真机实证 2026-09-18）
+
+1. **shebang 死**：HNP 里随包的 wrapper 脚本（busybox/coreutils 的 applet 链接脚本：grep、find、tar、patch、file…全家族）首行 `#!/bin/bash`。设备上 `/bin/bash` 不存在 → kernel 找解释器失败：
+   `/data/app/<pkg>.org/<pkg>_<ver>/bin/grep: /bin/bash: bad interpreter: No such file or directory`，退出码 **126**。
+   凡用例体、被测框架、调度脚本调到这些工具 → rc=126 全失败。典型掩盖：框架**先打印版本/头信息（纯 echo 目标正常）再调 wrapper 工具**，看似"跑起来了"实则半路死。
+2. **busybox SIGSYS**：把 wrapper 换成 `exec busybox xxx` 后部分场景被 seccomp 击杀——**rc=159（128+SIGSYS）**。某框架的配置加载步骤（shell 函数库内 `set | grep -E '^…'` 管道）触发，GNU grep 同调用则通过。busybox 是多合一二进制，其 syscall 组合不在 app 域 seccomp 白名单内的概率更高。
+3. **网络下载链路同样中招（某交叉工具链工程 实证 2026-09-20）**：`exec busybox wget` 下载源码包直接 SIGSYS/Bad system call，下载路径全灭——文本处理类（grep）之外，**凡走 seccomp 敏感 syscall 组合的 applet（网络 connect/摘要大文件流式读）都按此判**。摘要工具 busybox sha512sum 同理换 GNU coreutils ELF 后校验路径全通。
+
+## 修法（已内置于 cli-hnp-runner 模板 `build-hap.sh`，手改工程照抄）
+
+1. **shebang 自指**（打包期，pkg 树成形后）：
+   ```bash
+   # /data/app/<name>.org/<name>_<version>/bin/bash 是 HNP 固定装机路径
+   find "$pkg" -type f -print0 | while IFS= read -r -d '' f; do
+       # 首行为 #!/bin/bash / #!/usr/bin/bash / #!/usr/bin/env bash 三形态 → 重写
+       #（ELF 头 12 字节是 \x7fELF，天然不匹配，无需排除）
+       … printf '#!%s\n' "$hnp_bash" | cat - body > "$f"
+   done
+   ```
+   - ⚠️ **不要写 `#!/usr/bin/env bash`**：设备无 env 的标准路径。
+   - ⚠️ `#!/bin/sh` 保留可（设备有 /bin/sh），但**bash 特性脚本（PIPESTATUS/数组/local）必须 bash**——用 HNP 内 bash 绝对路径。
+   - **调度类脚本别依赖 shebang**：runner 侧用「bash ELF 全路径 + 脚本路径」子进程方式显式执行（见 pc-device-verify runner 接线篇），shebang 只是兜底。
+2. **关键 applet 用真 GNU 工具替换**：验证链路上的 grep/diff/sed 等高频工具，优先交叉编译对应 GNU 包（低版本 GNU 工具对交叉友好，`./configure` + NDK clang 即可）替换 busybox wrapper。判据：设备上复现 rc=159 且被杀调用在管道文本处理里 → 换真工具，不要逆向 seccomp 白名单。
+   - **网络下载类替换模式（wget → curl shim，某交叉工具链工程 patch 0004 实证）**：被测框架只会调 `wget <opts> -T <sec> -O <file> <url>` 时，不必找交叉 wget——写一个 bash shim 翻译参数到中心仓 curl ELF（`.codesign` 自签）：`-T`→`--connect-timeout`、`-O`→`-o`，统一加 `--location --fail`；`CURL_CA_FALLBACK=1`（+ `--insecure` 兜底）规避空 CA 信任锚——**下载完整性由包摘要（sha512）把关，不依赖 TLS 验证**。摘要工具（sha512sum/md5sum/sha256sum）同样换 GNU coreutils ELF。实证：替换后 download + digest-mismatch 全路径真机通过（2026-09-20 终验轮）。
+3. **自查口令**（装机前）：
+   ```bash
+   grep -rlE '^#!/(usr/)?bin/(ba)?sh$' pkg | xargs grep -L "data/app"   # 期望空（全部已自指）
+   ```
+
+## 关联
+
+- `pc-knowledge-base/platform/鸿蒙PC-app域执行二进制与JIT限制.md`（seccomp 白名单大图）
+- `pc-knowledge-base/platform/鸿蒙PC-交叉libcurl空CA信任锚与SSL_CERT_FILE.md`（wget shim 的 CURL_CA_FALLBACK 依据）
+- `pc-knowledge-base/platform/鸿蒙PC-随包数据树LF归一与configure生成物补齐.md`（同一打包期检查的另一半）
+- `pc-device-verify/references/runner-script-wiring.md`（runner 侧子进程调用协议）
+- cli-hnp-runner 模板 `build-hap.sh` 的 shebang 修正段（scaffold 生成即带）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/platform//351/270/277/350/222/231PC-/351/232/217/345/214/205/346/225/260/346/215/256/346/240/221LF/345/275/222/344/270/200/344/270/216configure/347/224/237/346/210/220/347/211/251/350/241/245/351/275/220.md

@@ -0,0 +1,48 @@
+# 随包数据树 LF 归一与 configure 生成物补齐
+
+> 一句话：Windows 宿主 git clone 的源码树直接打 HNP，设备端**声明式配置解析器与 shell 框架脚本会因 CRLF 全线崩**；且 git 树里**缺构建系统生成物**（bootstrap/configure 才产出的数据文件），打包前必须补齐。两类问题都是"随包数据完整性"，一次打包期检查全部兜住。
+
+## 症状（真机实证 2026-09-18，两连坑叠加）
+
+1. **CRLF 污染**：随包数据树里的文本（`.in` 配置树、`.mk`、框架函数库（无扩展名）、测试清单）带 `\r`，设备端解析器逐行报
+   `xxx.in:N: warning: ignoring unsupported character '\r'` → 文本段落被误判为语句（`unknown statement "..."`）→ `syntax error` → 配置文件生成不了 → **所有依赖配置的用例连锁失败**（一损俱损，10+ 例）。
+2. **生成物缺失**：`configure`/`bootstrap` 才生成的数据（choice/版本菜单类配置片段、安装路径脚本、版本符号清单）**不进 git**。git clone 打包 → 设备端加载该文件时按文件名硬报 `Not found: xxx` → 框架以 abort 类错误终止。
+3. 连锁表象：框架头信息能打出（version 类纯 echo 目标正常），但凡走到「读配置 → 校验 → 写 .config」的正路径用例全败；否定路径用例（预期 rc≠0 的守卫类）反而全过——**pass 集全是否定路径 = 正路径坏的强信号**。
+
+## 根因
+
+- 宿主 Windows 的 `core.autocrlf=true`：clone 时所有文本被改写为 CRLF。源码编译不受影响（编译器容忍），**但随包数据文件是被设备端解释器逐字节消费的**。
+- release tarball 里有 bootstrap 产物，git 树里没有——「从 git 构建」与「从 tarball 构建」的输入集合不同。
+
+## 修法（已内置于 cli-hnp-runner 模板 `build-hap.sh`，手改工程照抄）
+
+1. **打包期递归 LF 归一化**（在 `pack_hnp` 内、`pkg` 树成形后执行）：
+   ```bash
+   # NUL 字节判二进制跳过（ELF/图片），其余一律去 CR；单进程 python 全树遍历
+   "$py" - "$pkg" <<'PYEOF'
+   import os, sys
+   root = sys.argv[1]
+   for base, _dirs, names in os.walk(root):
+       for n in names:
+           p = os.path.join(base, n)
+           with open(p, 'rb') as f: data = f.read()
+           if b'\x00' in data: continue
+           if b'\r' in data:
+               with open(p, 'wb') as f:
+                   f.write(data.replace(b'\r\n', b'\n').replace(b'\r', b'\n'))
+   PYEOF
+   ```
+   ⚠️ **禁止白名单扩展名**：无扩展名文本（框架函数库、符号清单）与未列举子目录正是重灾区。数据驱动测试的 fixture（`*.cnf/*.txt`）同理覆盖（既有实证：向量文件行尾 `\r` 致 9/9 fail）。
+2. **生成物补齐**：构建 dist 数据树时核对 release tarball 与 git 树的文件清单差异（`diff <(tar tzf 官方tarball | sort) <(find dist树 | sort)`），缺失的生成物二选一：
+   - 在宿主跑一次 `bootstrap`+`configure --enable-local` 后拷生成物（上游模板引擎对 CRLF 零容忍——bootstrap 脚本与模板文件也要先 LF 化，`#!if` 类标记行尾带 `\r` 会报 token unpaired）；
+   - 或从**包集一致的相邻构建**复用已生成的生成物（前提：新旧符号/包集合 diff 确认无删除项；上游校验类清单若只查"被删符号"，复用旧生成物只会缺新符号、不会误报）。
+3. **自查口令**（装机前）：
+   ```bash
+   find pkg -type f ! -name '*.so*' -exec grep -lP '\r' {} +   # 期望空
+   ```
+
+## 关联
+
+- `pc-knowledge-base/platform/鸿蒙PC-随包wrapper脚本shebang自指与busybox-seccomp.md`（同一次打包期修法的另一半）
+- `pc-knowledge-base/platform/鸿蒙PC-私有HNP数据exec平台限制.md`（打包格式/执行位）
+- cli-hnp-runner 模板 `build-hap.sh` 的 CRLF 归一化段（scaffold 生成即带）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/references/README.md

@@ -0,0 +1,22 @@
+<!-- 本文件由同步脚本自动生成，请勿手改。如需修正请更新知识源数据后重新运行 `npm run sync:kb`。 -->
+
+# 参考文档（知识库同步生成物）
+
+本目录文档由同步管道从知识源拷贝（文内指向上游位置的相对链接已剥离或改写，其余内容保持原文）。
+
+| 文件 | 内容 | 备注 |
+|---|---|---|
+| [iron-rules.md](iron-rules.md) | 构建/补丁/流程铁律手册（R1–R52） | 其中 Conan/积分赛流程类条款（R19–R22、R27–R37 等）属知识源工作流上下文，下游仅作参考 |
+| [musl-glibc-developer-impact.md](musl-glibc-developer-impact.md) | musl/glibc 差异对开发者的影响分析 |  |
+| [musl-glibc-full-comparison-gnu-linux.md](musl-glibc-full-comparison-gnu-linux.md) | musl vs glibc（GNU/Linux）逐接口对照表 |  |
+| [musl-glibc-full-comparison-iso-posix.md](musl-glibc-full-comparison-iso-posix.md) | musl vs glibc（ISO/POSIX 标准面）逐接口对照表 |  |
+| [musl-compat.md](musl-compat.md) | musl 兼容要点速查 |  |
+| [operations/build-systems.md](operations/build-systems.md) | 构建系统（autotools/cmake/meson 等）平台差异 |  |
+| [operations/filesystem-analysis.md](operations/filesystem-analysis.md) | 文件系统机制分析（HMDFS/erofs 等） |  |
+| [operations/ptrace-alternatives.md](operations/ptrace-alternatives.md) | ptrace 受限下的调试替代方案 |  |
+| [operations/ohos-adaptation-patterns.md](operations/ohos-adaptation-patterns.md) | OHOS 适配模式（__OHOS__ 守卫边界与决策流程） |  |
+| [operations/dependencies.md](operations/dependencies.md) | 依赖处理机制（拓扑序/冲突判定） |  |
+| [operations/debug-methodology.md](operations/debug-methodology.md) | 调试方法论（归因路径与证据链） |  |
+| [operations/dual-build-system-parity-model-data.md](operations/dual-build-system-parity-model-data.md) | 双构建系统对等检查模型数据 |  |
+
+知识源 commit：`70926181cd`。