@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/adaptation//351/270/277/350/222/231PC-meson-Conan-pkg-config/346/250/241/346/213/237/345/231/250/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,139 @@
+---
+name: 鸿蒙PC-meson-Conan-pkg-config模拟器交叉编译
+description: >-
+  meson 构建的纯 C/C++ 库（依赖 libusb/glib 等）从 Windows 宿主交叉编译到 OHOS 的全套方案：
+  ① meson cross-file（system=linux/cpu=aarch64/c=c_clang/cpp=cpp_clang/pkgconfig 路径）；
+  ② 中心仓 Conan 复用依赖（libusb/glib/pcre2/libffi 全部命中，免自建）；
+  ③ pkg-config 模拟器（Windows 宿主无 pkg-config，Python 脚本从 Conan 目录回填 .pc 数据）；
+  ④ 双载体验证（HAP dlopen 验库导出符号 + CLI 私有 HNP execv 跑全量测试二进制）；
+  ⑤ 目标路径覆盖盘点（组件 × 载体 = 覆盖矩阵）；
+  ⑥ 覆盖等价性分析（补写用例 vs 上游 glib gtest 用例逐条比对，标注缺口）。
+  触发词：meson、meson cross-file、Conan、conan install、libusb、glib、pcre2、libffi、
+  pkg-config 模拟器、pkg-config.py、Windows 宿主无 pkg-config、依赖复用、中心仓、
+  ohos-armv8、cross-file、meson compile、cpp-lib、纯 C 库、meson 库、双载体验证、
+  HAP dlopen、CLI HNP execv、覆盖矩阵、覆盖等价性、补写用例、libusbredirparser、
+  usbredir、依赖命中、c_clang。
+metadata:
+  type: adaptation
+  source: usbredir 0.15.0 适配实证（第 2/3 轮，2026-09）
+---
+
+# meson + Conan + pkg-config 模拟器：纯 C 库交叉编译全套方案
+
+## 适用场景
+
+一个 **meson 构建的纯 C/C++ 库**，依赖 libusb/glib/pcre2/libffi 等（Conan 中心仓有预编译
+交叉产物），宿主是 Windows，目标 OHOS aarch64。这套方案从依赖获取 → 编译 → 设备验证全链路
+打通，usbredir 0.15.0 实证：核心库（libusbredirparser.so）编得出、加载得了、11/11 测试全绿。
+
+## 1. 依赖获取：中心仓 Conan 复用
+
+```bash
+conan install --requires libusb/1.0.27 --requires glib/2.84.0 \
+  -pr:h ohos-armv8 -pr:b default
+```
+
+- 4 个依赖（libusb/glib/pcre2/libffi）全部命中中心仓，**免自建依赖库**。
+- 产物落 Conan 缓存，`PKG_CONFIG_PATH` 指向其 `lib/pkgconfig/`。
+- ⚠️ 中心仓 glib 只有 `.a` 静态库——见 platform 条目「glib gtest 静态链接 musl 启动崩溃」。
+
+## 2. 交叉编译：meson cross-file
+
+`ohos-cross.ini`（模板化写法，路径按本机替换）：
+
+```ini
+[binaries]
+c = '<NDK>/llvm/bin/clang.exe'
+cpp = '<NDK>/llvm/bin/clang++.exe'
+ar = '<NDK>/llvm/bin/llvm-ar.exe'
+ld = '<NDK>/llvm/bin/ld.lld.exe'
+pkg-config = '<ws>/build/bin/pkg-config.cmd'
+
+[host_machine]
+system = 'linux'        # 关键：meson 判定 host_system=='linux' 的分支才走 Linux 源码
+cpu_family = 'aarch64'
+cpu = 'aarch64'
+endian = 'little'
+
+[built-in options]
+c_args = ['-target', 'aarch64-linux-ohos', '--sysroot=<NDK>/sysroot', '-D__OHOS__', '-D__MUSL__']
+c_link_args = ['-target', 'aarch64-linux-ohos', '--sysroot=<NDK>/sysroot', '-Wl,--code-sign']
+```
+
+```bash
+meson setup source _build --cross-file build/ohos-cross.ini \
+  -Dfuzzing=disabled -Dtools=enabled -Dtests=enabled
+meson compile -C _build
+```
+
+> host_machine.system='linux' 是 E090 的对应做法：meson 项目 `if host_system == 'linux'`
+> 条件分支（Linux 特有源文件）在 OHOS 上必须命中，故 cross-file 里声明 system=linux。
+
+## 3. Windows 宿主无 pkg-config：模拟器
+
+Windows 原生无 pkg-config 命令。用 Python 模拟器从 `PKG_CONFIG_PATH`（Conan `lib/pkgconfig/`）
+读 `.pc` 回填 cflags/libs：
+
+- 模板位置：`<ohpt-agent>/templates/build-tools/pkg-config-shim/`（`pkg-config.py` + `.cmd`）。
+- cross-file `[binaries] pkg-config` 指向 `pkg-config.cmd`。
+- 已内置：递归 Requires/Requires.private 解析、`--define-prefix`（按 .pc 所在目录推算前缀）、
+  过滤 `-l:ld-musl*` 不兼容引用。
+
+详见「Windows 宿主构建环境四坑」坑 5 与 E136。
+
+## 4. 双载体验证
+
+同一批 .so 必须经**两条加载路径**都过才算验完：
+
+| 载体 | 验证什么 | 证据 |
+|------|---------|------|
+| HAP（`ohpt-agent scaffold --kind cpp-lib-demo`） | NAPI 壳 dlopen 库 + dlsym 全部导出符号 + 实调代表符号 | `build/demo-verify.json` + 截图（存档待人工验收） |
+| CLI（`ohpt-agent scaffold --kind cli-hnp-runner`） | 私有 HNP 打包，app 域 fork+execv 跑全部测试二进制 | `harmony-cli-runner/verify/demo-verify.json`（hilog 主证据） |
+
+```bash
+ohpt-agent scaffold --kind cpp-lib-demo -w <ws> --bundle com.<lib>.demo
+ohpt-agent scaffold --kind cli-hnp-runner -w <ws> --out harmony-cli-runner --tool <lib>-tests --bundle com.<lib>.runner
+bash build/build-hap.sh
+bash harmony-cli-runner/scripts/build-hap.sh
+ohpt-agent sign-demo -w <ws> --install
+ohpt-agent sign-demo -w <ws> --demo-dir harmony-cli-runner --hap harmony-cli-runner/dist/app/<tool>-runner-unsigned.hap --install
+```
+
+> 双载体是 verification-policy 的 `requiredCarriers` 强制项——HAP 进程 dlopen 与 ELF 链入
+> app 域子进程是两条加载路径，一条过不代表另一条过。scaffold 会提示缺的另一半命令。
+
+## 5. 目标路径覆盖盘点
+
+**组件 × 载体 = 覆盖矩阵**，逐格登记 covered/partial/exempt：
+
+usbredir 实证（4 组件 × 3 载体 = 12 格）：
+
+| 组件 | HAP 载体 | CLI 载体 | 结论 |
+|------|---------|---------|------|
+| libusbredirparser.so | dlopen 符号全过 | test-parser 11/11 | covered |
+| libusbredirhost.so | callLibHost 就绪待验 | test-host 7/8（1 product-defect 已修待重验） | partial |
+| usbredirect 二进制 | — | app 域 libusb_init 失败（/dev/bus/usb 不可达） | exempt（能力域 usb-host） |
+| test-filter/serializer | — | glib gtest 启动崩溃 | exempt（补写等价用例，等价性 partial） |
+
+## 6. 覆盖等价性分析（B-4）
+
+豁免不等于不补：每条豁免的 glib gtest 用例都要转写为纯 C 等价用例，并**逐条比对断言面**：
+
+- 上游 `string_to_rules` 29 路解析边界 → 补写 `usbredirfilter_check/print/verify` 面 19 断言（另一 API 面，缺口如实登记）。
+- 上游 serializer roundtrip 正向断言 → 补写负向三路（NULL/坏魔数/截断），正向 roundtrip 为已知缺口。
+- 补写用例以 `tests-generated/` 落盘 + 独立测试二进制 + CLI 载体上设备跑。
+
+## 7. 交叉编译暴露 API 契约违约（通用教训）
+
+`usbredirhost_check_device_filter(NULL, ...)` 在上游 Linux 上未触发（调用方有 UB 保护），
+交叉编译到 OHOS 后 SIGSEGV——函数未对 NULL dev 参数做守卫，libusb_get_device_descriptor
+在 NULL 指针上解引用。修复：入口加 `if (dev == NULL) return -EIO;`。
+
+**通用教训**：交叉编译（尤其 musl 库）能暴露上游的 UB/契约违约；修复后须反汇编确认修复分支
+生效（llvm-objdump 确认 `cbz` 短路分支 + `mov w0, #-5`，即 -EIO）。
+
+## 关联
+
+- [[鸿蒙PC-Windows宿主构建环境四坑]] —— 宿主侧全部坑（ld.lld 并行 / hvigor / run_command / pkg-config）。
+- [[鸿蒙PC-glib-gtest静态链接musl启动崩溃]] —— glib gtest 豁免归因。
+- pc-error-atlas E136（run_command test -d）/ E090（meson host_system）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-meson-Cython-numpy/346/211/251/345/261/225.md

@@ -0,0 +1,38 @@
+---
+name: 鸿蒙PC-meson-Cython-numpy扩展
+description: meson-python + Cython + numpy 的多模块科学计算扩展（如 PyWavelets）在鸿蒙PC 上手动 cythonize+交叉编译的套路与关键坑
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+meson-python 构建的科学计算库（含 Cython 扩展 + numpy）适配鸿蒙PC：**不要硬上 meson 交叉编译**（meson-python 找不到 target python、numpy 极易卡壳），改用"**手动 cythonize + OHOS clang 逐模块交叉编译**"，是 [[鸿蒙PC-Python-C扩展交叉编译]] 的放大版。以 PyWavelets 1.10（4 个 Cython 扩展 _dwt/_swt/_cwt/_pywt + 5 个 C 支撑源）为例，**源码零 patch**，4 个扩展全部真机跑通（DWT 往返误差 1.7e-15）。
+
+## 套路（5 步）
+
+1. **读 meson.build 抽出"模块→源文件"映射**：哪些 C 源编进公共静态库、每个扩展 = 哪个 .pyx + 链接什么。PyWavelets：5 个 C 源（common/convolution/cwt/wavelets/wt）做公共 obj，4 个扩展各自 `.pyx→.c` + 链上这 5 个 obj + numpy + libpython。
+2. **补 meson 构建期生成文件**（不是源码 patch，是 meson 的 `configure_file`/`custom_target` 产物，离线要自己生成）：
+   - `config.pxi`（Cython 编译期 DEF）← `config.pxi.in`
+   - `_c99_config.py`（运行期 `_have_c99_complex`）← `_c99_config.py.in`
+   - `version.py` ← `util/version_utils.py`（离线直接写死版本，别依赖 git）
+   - OHOS clang 支持 C99 complex（`complex.h` 的 `complex float`），相关标志全置真。
+3. **cythonize**：Mac venv 里 `cython -3 --fast-fail --include-dir <扩展目录>`。
+4. **交叉编译**：`aarch64-unknown-linux-ohos-clang -fPIC -shared -std=c17 -DPY_EXTENSION -DHAVE_C99_COMPLEX -DCYTHON_CCOMPLEX=1 -DNPY_NO_DEPRECATED_API=NPY_1_22_API_VERSION -I<py> -I<numpy> <ext>.c <5个obj> -lpython3.12 -lm` → `<ext>.cpython-312.so` → strip。
+5. **部署**：纯 py 包 + 4 个 `.so` 一起推（含 `pywt/data/` 小波系数目录！别漏数据文件），`PYTHONPATH` 指过去验证（numpy 仍从 site-packages 解析）。
+
+## 致命坑：numpy 2.x 的 pxd/header 必须配套
+
+设备 numpy 是 **2.2.1**。numpy 2.0 把 `PyArray_Descr` 的 `subarray/fields/names` 挪进了 `_PyArray_LegacyDescr`，直接 `descr->subarray` 在新头文件下报 **`no member named 'subarray'`**。
+- 根因：cythonize 时若 venv **没装 numpy**，Cython 退回自带的**过时 numpy.pxd**，生成的 C 对不上 numpy 2.2.1 头文件。
+- **解法：Mac venv 里装与设备完全同版本的 `numpy==2.2.1`**，让 `cimport numpy` 用 numpy 自带的配套 pxd。pxd 和 header 同版本就自洽，编译即过。
+- 同理 Cython 版本尽量对齐设备（设备 3.0.11）；但因为发的是预编译 `.so`、设备不再 cythonize，Cython 版本不必死磕，**numpy 版本必须死磕**。
+
+## 已知限制：复数 CWT 精度（真机测试发现）
+
+跑官方 `pytest pywt/tests` 时 **1031 passed / 4 failed / 2 skipped**，4 个失败全是**复数连续小波变换**（cgau/cmor 的 `test_cwt_complex`/`test_cwt_method_fft`/`test_accuracy_precomputed_cwt`，对 Matlab 参考 rms≈0.42）。复数小波函数 psi 本身正确、基本 cwt 输出有限合理，根因疑为 **musl 复数 libm / FFT 数值精度差异**。**实数 CWT + 全部 DWT/SWT/Wavelet/threshold 通过**，不影响实数小波分析。属已知限制，未深修。归因方法见 [[鸿蒙PC-真机跑官方测试套件]]。
+
+## 通用结论
+
+- 设备已预装的 C 扩展依赖（numpy/cffi/...）直接复用其头文件（`numpy.get_include()` 拉到 Mac），不用自己编 numpy。
+- meson-python 库的"适配"往往**不在源码兼容**（OHOS clang 兼容性好），而在**复刻 meson 的生成步骤 + 喂对 numpy 头**。
+

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-nmap-autotools/344/272/244/345/217/211/347/274/226/350/257/221/344/270/216/347/234/237/346/234/272/346/211/253/346/217/217.md

@@ -0,0 +1,52 @@
+---
+name: 鸿蒙PC-nmap-autotools交叉编译与真机扫描
+description: nmap/ncat/nping 交叉编译到鸿蒙PC的四个 autotools 坑 + root 域 raw socket 全功能实测
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+把 nmap 7.99SVN（含 ncat/nping，全内嵌依赖 libpcap/pcre2/zlib/libdnet/lua/liblinear）从 Mac 交叉编译到鸿蒙 PC（`aarch64-linux-ohos`），**C/C++ 源码零改动**，真机 hdc shell（root 域）`-sT/-sS/-O/-sV/NSE`、ncat、nping 全部跑通。基础坑见 [[鸿蒙PC-C++库交叉编译要点]]、[[鸿蒙PC-autotools-C二进制-goaccess]]。
+
+## 四个 autotools/host 工具坑（都不是源码兼容问题）
+
+1. **`config.sub` 不认 `ohos`** → `--host=aarch64-linux-ohos` 直接 `system 'ohos' not recognized`。
+   修法：`--host=aarch64-unknown-linux-gnu`（config.sub 认识的 linux 三元组即可，真正的编译器由 `CC/CXX=<NDK>/llvm/bin/aarch64-unknown-linux-ohos-clang(++)` 指定）。OHOS clang 自带 `__OHOS__`/`__linux__`/`__MUSL__`，走 Linux 分支，nmap 全程零源码改动。
+
+2. **nmap 只能 in-tree 构建**（Makefile 用裸文件名 `nmap.cc` 引用源码、无 VPATH）→ out-of-source（`$BUILD != $SRC`）会 `no such file or directory: 'nmap.cc'`。
+   修法：把 `src/` rsync 一份到 `build/nmap-build/` 里 in-tree 编，保持 src 干净以便 diff 补丁。
+
+3. **⭐ DevEco 的 `diff` 坏桩导致所有 `*_config.h` 不生成**（与 goaccess 坑 3 同根，已更正旧记忆）。
+   DevEco `toolchains/diff` 在 PATH 最前，对缺失文件返回 `exit 0`，config.status 误判 header "is unchanged" → nbase_config.h/nsock_config.h/nmap_config.h 一个都不写 → 编译 `'nbase_config.h' file not found`。
+   修法见坑 4 的 shim。
+
+4. **⭐ 内嵌 zlib 在 macOS host 上把归档器设成 `AR=libtool ARFLAGS=-o`**（zlib configure 的 Darwin 习惯），macOS `libtool` 只认 mach-o、无法归档 OHOS ELF .o → `libz.a` 为空 → 链接 `undefined symbol: zlibVersion/compress/...`。同理 bare `ar/ranlib/strip` 会命中 macOS BSD 版。
+   **统一修法（shim 目录）**：建 `build/.shim/` 放 PATH 最前，只覆盖几个 host 工具，其余仍走 DevEco/系统不污染：
+   ```sh
+   ln -sf /usr/bin/diff   .shim/diff      # 修坑 3（正确的 diff）
+   ln -sf $TC/llvm-ar     .shim/ar        # 修坑 4（归档 ELF）
+   ln -sf $TC/llvm-ranlib .shim/ranlib
+   ln -sf $TC/llvm-strip  .shim/strip
+   ln -sf $TC/llvm-nm     .shim/nm
+   export PATH="$PWD/.shim:$PATH"
+   ```
+   外加 configure 后 make 前 patch 内嵌 libz/Makefile：`sed 's/^AR=libtool/AR=…llvm-ar/; s/^ARFLAGS=-o/ARFLAGS=rcs/'`（zlib 的 AR 是它自己 Makefile 硬编码，不吃 shim 的 bare ar）。
+   > 教训：**别无脑 `export PATH=/usr/bin:$PATH` 去修 diff**——那样 bare `ar/ranlib` 又会变成 macOS BSD 版，把 ELF 归档搞坏。要用精准 shim 只覆盖目标工具。
+
+   交叉编译 AC_TRY_RUN 兜底：`--cache-file` 预置 `ac_cv_func_setvbuf_reversed=no` `ac_cv_func_{malloc,realloc}_0_nonnull=yes` `ac_cv_c_bigendian=no`。
+
+## 配置与依赖
+
+- 全内嵌：`--with-{libpcap,libpcre,libz,libssh2,libdnet,liblua,liblinear}=included`，`--without-zenmap --without-ndiff`（Python 前端另行处理）。
+- **libssh2 需要 openssl**：`--without-openssl` 时 configure 会自动连带禁掉 libssh2（不影响扫描主功能；要 ssh-brute 等 NSE 再补 openssl）。
+- 产物 NEEDED 极干净：仅 `libc++_shared.so`（设备 `/system/lib64/` 自带）+ `libc.so`（musl）。
+
+## ⭐ 真机实测：root 域 raw socket 全功能可用
+
+设备是 **HongMeng Kernel 1.12.0 + Toybox** 用户态（不是 Linux 内核），但 musl ELF 经兼容 ABI 跑，且 **hdc shell 默认 root 域下 raw socket / PF_PACKET 完全可用**：
+- `-sT` connect 扫描 ✅、`-sS` SYN 扫描（raw）✅、`-O` OS 指纹（raw，给出 aggressive guesses）✅、`-sV` 版本探测 ✅、NSE 脚本 ✅；ncat HTTP ✅；nping `--tcp` 收发 raw 包 ✅。
+- 部署：`hdc file send` 到 `/data/local/tmp/nmap/`（data_local_tmp 标签，exec 无需签名），`chmod +x`。
+- **数据文件路径**：`--datadir /data/local/tmp/nmap` 指到含 `nmap-services/nmap-os-db/nmap-service-probes/nmap-protocols`、`nse_main.lua`、`nselib/`、`scripts/` 的目录。NSE 缺 `nselib/lpeg-utility.lua` 会 `failed to initialize the script engine` 直接 QUITTING——**nselib/ 和 scripts/ 必须齐**。
+- **hdc 送目录会嵌套**：`hdc file send localdir /remote/nselib` 会落成 `/remote/nselib/nselib/...`。送到父目录或送完 `mv` 一层。
+
+> ⚠️ 这是 **root 域**（hdc shell / su 域）的结论。普通 HAP（app 域）申请不到 `ohos.permission.kernel.net.raw`（系统级），raw 功能会被拒，只剩 connect 子集——见 [[鸿蒙PC-app域执行二进制与JIT限制]]、HAP 形态要把 nmap 打成私有 HNP 才能 exec。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-numpy-OpenBLAS-armv8sve/345/244/215/346/225/260/347/202/271/347/247/257bug.md

@@ -0,0 +1,67 @@
+---
+name: 鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug
+description: 设备 numpy wheel 自带 OpenBLAS 在 armv8sve 上复数点积(zdotu/cdotu)内核返回错误实部，导致 np.dot/np.matmul/np.convolve 复数运算算错；OPENBLAS_CORETYPE=ARMV8 绕开
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+## 一句话
+设备 numpy（2.2.1，wheel 自带 OpenBLAS 0.3.27）在本机 CPU 上被自动识别为 **`armv8sve`**，其 **SVE 版复数点积内核 `zdotu`/`cdotu` 返回错误的实部（虚部正确）**。凡走 BLAS 复数点积的 numpy 运算结果实部全错。**和具体跑什么库无关**，是设备 numpy 的底层数值缺陷。设 `OPENBLAS_CORETYPE=ARMV8` 强制通用 NEON 内核即可绕开。
+
+**受害面（2026-07-16 逐项跨 env 实测于 root/可调试机，HongMeng 6.1.0.117）**——判据是「同一计算在默认 vs `OPENBLAS_CORETYPE=ARMV8` 下结果是否不同」，并以不走 BLAS 的 `np.sum(a*b)` 作真值锚（实测真值与 `ARMV8` 完全一致 → 默认错、`ARMV8` 对，不是两者皆漂）：
+
+| 中招 | 不中招 |
+|---|---|
+| `np.dot` · `np.vdot` · `np.inner` · `np.matmul`**（仅 1-D，等价 dot）** · `np.correlate` · `np.convolve` | `np.matmul`**（2-D 及以上，走 `zgemm` 不走 `zdotu`）** · `np.sum(a*b)` 等逐元素路径 |
+
+⚠️ **`np.matmul` 不可一概而论**：1-D 输入退化成 dot 才中招，2-D 矩阵乘走的是 `zgemm`，实测结果与 `ARMV8` 逐位相同。把 matmul 整个列为受害会让人误判矩阵乘。
+
+## 怎么认出来（最小复现）
+```python
+import numpy as np
+rng = np.random.RandomState(7)
+for n in [1,2,3,8,64,128]:
+    a = rng.randn(n)+1j*rng.randn(n); b = rng.randn(n)+1j*rng.randn(n)
+    print(n, abs(np.dot(a,b) - np.sum(a*b)))   # dot vs 逐元素求和
+```
+- 坏：n>=2 误差 ~1e-3 ~ 1e+1（随长度增大），且**只有实部错、虚部对**；n=1 正确。
+- 好（Mac / 设过 ARMV8）：全程 ~1e-15。
+- 关键判别：`np.sum(a*b)`（逐元素，不走 BLAS dot）永远正确 → 据此确认是 BLAS dot 内核而非 libm/精度问题。
+
+确认 BLAS 后端与被选内核：
+```python
+import numpy as np; print(np.show_config(mode='dicts')['Build Dependencies']['blas'])  # openblas 0.3.27
+import ctypes
+lib = ctypes.CDLL('.../numpy.libs/libopenblasp-r0-...0.3.27.so')
+lib.openblas_get_corename.restype = ctypes.c_char_p
+print(lib.openblas_get_corename())  # 默认 b'armv8sve'；设 ARMV8 后 b'armv8'
+```
+
+## 修复
+```bash
+export OPENBLAS_CORETYPE=ARMV8     # 或 generic，都回到 ~1e-15
+```
+必须在 **numpy/OpenBLAS 加载之前**生效。免改命令行：放一个 `sitecustomize.py`（site-packages 根或 PYTHONPATH 上），解释器启动时执行：
+```python
+import os
+os.environ.setdefault("OPENBLAS_CORETYPE", "ARMV8")
+```
+`sitecustomize` 在任何用户 import 之前运行，故能在 numpy 加载前设好。`OPENBLAS_NUM_THREADS=1` **不解决**（不是线程问题，是内核选择问题）。
+
+## 影响面（为什么放 platform/）
+任何在设备上用 numpy 做**复数** dot/matmul/conv/correlate 的库都会中招。已确认**两个独立受害库**：
+- **PyWavelets** 复数 CWT（`cwt(method='conv')` → `np.convolve` → `zdotu`，复数小波 cmor/cgau/shan/fbsp 系数实部全错，4 个官方测试失败、cgau1 precomputed rms 0.419、fbsp 最差 RMS 0.86）。
+- **python-control**（0.10.2）极点/零点：`TransferFunction.poles()` → `_common_den()` → `numpy.poly(poles)` → 内部复数 `np.convolve` → `zdotu`。极点被算成 ~1e30（真值 ~10）或 `numpy.roots`→`eigvals` 报 `LinAlgError: infs or NaNs`。**整套 `pytest control/tests` 64 failed → 0**（3903/0/396），control 源码改动 0 处。注意：这 64 个失败**既不是 matplotlib（基线已配 Agg 仍 64 failed）也不是 slycot（slycot 缺失只导致 SKIP、不导致 failed）**——遇到 numpy 系库的"诡异数值失败"先怀疑本 bug，别误归因到绘图后端或可选依赖。
+
+实数路径、`method='fft'`（pocketfft，不走 zdotu）不受影响。换 scipy/任何复数线代库同理。
+
+**额外坑（DYNAMIC_ARCH 自动派发才坏）**：显式设 `OPENBLAS_CORETYPE` 为**任意**值——哪怕设成自动选中的同名 `TSV110`——都让复数 dot 立即回正确。bug 只在**默认自动 CPU 派发到 `armv8sve`** 时出现，说明是 DYNAMIC_ARCH 运行期派发选错/SVE zdotu 内核本身缺陷，与具体核名无关，钉死 `ARMV8` 最稳。
+
+## 排错套路（复数结果"看着不对"时）
+1. 先 `np.dot(复数) vs np.sum(a*b)` 小测 → 锁定是不是 BLAS 复数点积。
+2. 看 `openblas_get_corename()` 是否 `armv8sve`。
+3. 设 `OPENBLAS_CORETYPE=ARMV8` 复测；好了就钉死这个 env（部署侧 sitecustomize 兜底）。
+4. 升级/更换 numpy wheel 后重跑步骤 1，确认新 wheel 的 SVE zdotu 是否已修。
+
+关联：[[鸿蒙PC-真机跑官方测试套件]]、[[鸿蒙PC-设备Python运行时]]、[[鸿蒙PC-meson-Cython-numpy扩展]]。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-opencode-HAP/345/214/226-Electron/345/243/263.md

@@ -0,0 +1,70 @@
+---
+name: 鸿蒙PC-opencode-HAP化-Electron壳
+description: 把 opencode 桌面端做成可双击 HAP（真机验证通过）：复用社区 OH-Electron 25 当窗口壳、HAP 自带 Node24 当 sidecar 跑 opencode serve、renderer loadURL 本地端口；含私有 HNP 打包 + hvigor 注入、main.js 壳逻辑
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：把 opencode 桌面端做成可双击的 HAP（OH-Electron 壳 + Node24 sidecar）
+
+> 目标：opencode 的 macOS/Windows 客户端（Electron 壳 + 本地 Node 服务）适配成鸿蒙 PC 上能 `hdc install` 的 **HAP**，双击即用、自包含。**已真机验证通过**（设备 `2FF197...`，HarmonyOS PC 6.1.0.117）：HAP 启动 → 内嵌 Node 24 拉起 `opencode serve` → Web 组件加载本地 UI → 完整 opencode 工作区可交互。
+
+## 架构（同构映射，不移植 Electron 本身）
+
+macOS 端是「Chromium 壳 + 主进程 Node 跑 opencode 服务」。鸿蒙端复用社区的 **OH-Electron 25**（其 `ohos/` 模板工程，Chromium 114 / 内置 Node 18 主进程）只当**窗口壳**，opencode 服务端（为 Node 24 编译、用 `node:sqlite`）当 **sidecar 子进程**跑在 HAP 自带的 Node 24 上，renderer `loadURL(http://127.0.0.1:<port>)`。
+
+```
+HAP (com.example.helloelectron, OH-Electron 模板)
+├─ libelectron.so 主进程(Node18) ── resfile/resources/app/main.js  ← 我们写的壳
+│     spawn ↓ (private HNP 的 node24)
+├─ ocnode.hnp(私有HNP): bin/node(113M) bin/rg lib/liburing_block.so
+│     node24 --jitless opencode.mjs serve --port → 127.0.0.1:4097
+└─ resfile/resources/app/opencode/{opencode.mjs(24M), web-ui/, package.json}
+   libs/arm64-v8a/node_modules/@parcel,@lydell  ← watcher.node / pty.node 预编译
+```
+
+为什么 sidecar 而不是让 OH-Electron 的 Node18 直接 require opencode.mjs：opencode bundle 是 `bun build --target=node` 出的、依赖 Node 22+ 的 `node:sqlite` 等，OH-Electron 主进程是 Node 18，跑不了；而且复用了已验证的 1.14.39 HNP 产物（`dist-hnp/`）零改动。
+
+## 落地步骤（可复现）
+
+1. **复制模板**：OH-Electron 的 `ohos/` 模板 → 自己的 `hap/project`（带 `web_engine/` HAR + `electron/` entry + 签名配置 `build-profile.json5`，签名材料在 `~/.ohos/config/`，bundleName 沿用 `com.example.helloelectron` 才匹配 profile 的 device-ids）。
+2. **塞 opencode 资产**：解 `dist-hnp/opencode-harmony-1.14.39.tar.gz`，`share/{opencode.mjs,web-ui,package.json}` → `resfile/resources/app/opencode/`；`lib/node_modules`（@parcel watcher + @lydell pty 预编译）→ `electron/libs/arm64-v8a/node_modules/`。删 AppleDouble `._*`。
+3. **拉 Node24 + 打私有 HNP**：`hdc file recv /data/app/el1/bundle/<userId>/hnppublic/node.org/node_v24.13.0/bin/node` + 把 `dist-hnp` 里的 `rg` + 编好的 `liburing_block.so` 一起 `hnpcli pack` 成 `ocnode.hnp`（结构 `ocnode/{bin/node,bin/rg,lib/liburing_block.so,hnp.json}`）。
+4. **声明 + 注入 HNP**：`module.json5` 加 `hnpPackages:[{package:"ocnode.hnp",type:"private"}]` + `extractNativeLibs:true` + `requestPermissions:[ohos.permission.INTERNET]`；hvigor 不自动收 `.hnp`，写自定义 task `injectHnp`（dependencies `default@PackingCheck`、postDependencies `default@SignHap`）把 `hnp-stage/hnp/arm64-v8a/ocnode.hnp` 用 `zip` 拼进 unsigned HAP，再让内建 SignHap 重新签。
+5. **写壳主进程** `main.js`（见下）。
+6. **构建**：`hvigorw assembleHap`（需设好 `DEVECO_SDK_HOME`，见 `SKILL.md` 的「定位 DevEco SDK」），产 `electron-default-signed.hap`（~248MB）。`hdc install` → `aa start -a EntryAbility -b <bundle>`。
+
+## main.js（壳逻辑）关键点
+
+- **找 sidecar 可执行**：依次试 `/data/app/bin/node`（私有 HNP，app 域可 exec）→ bundled libs（实测 exec 不了，仅诊断）→ 公共 HNP node 兜底。探活不能用 `spawnSync`（OH-Electron 主进程里成功 exec 会永久阻塞、子进程变僵尸），改异步 `spawn` + 「600ms 内无 `error` 事件＝exec OK」。
+- **sidecar 环境**：`HOME`/`TMPDIR`/`XDG_*` 落到 el2 沙箱 `files/opencode-home`（别用 `/data/local/tmp`，app 域写不了）；`NODE_PATH` 指 libs 的 node_modules（找 watcher/pty）；`OPENCODE_RG_PATH` 指 `/data/app/bin/rg`；`LD_PRELOAD` 指 `realpath(node)/../../lib/liburing_block.so`。
+- **清洗 env**：子进程**不能**继承 OH-Electron 的 `LD_PRELOAD=libappspawn_helper.z.so` 等（`/^(LD_|ELECTRON|OHOS_SOCKET|HNP_|MALI_|UBSAN_)/` 全剔掉），再叠加自己的。
+- **三关治理**（详见 [[鸿蒙PC-app域执行二进制与JIT限制]]）：私有 HNP 解 exec；`liburing_block.so` 拦 io_uring（否则 SIGSYS 425 秒杀）；`node --jitless` 解 V8 JIT 写不了可执行内存（否则 `Check failed: 12==errno` SIGTRAP）。
+- **生命周期**：`waitHealthy` 轮询 `GET /` 到 200 再 `loadURL`；`window-all-closed`/`before-quit`/`process.exit` 都 `kill` sidecar。日志 `fs.appendFileSync`（同步，崩溃也不丢）写到 `files/opencode-shell.log`、sidecar stdout 重定向到 `files/opencode-sidecar.log`。
+
+## 坑：jitless 连带禁用 WebAssembly ⇒ undici fetch 静默失败 ⇒ 对话无响应
+
+`node --jitless` 把 `WebAssembly` 也禁掉了，而 Node 内置 fetch（undici）用 **llhttp 的 wasm** 解析 HTTP 响应——所以 AI SDK 走全局 `fetch()` 调 LLM 时静默失败（启动日志只有一行 `WebAssembly is not defined rejection`，对话里助手消息 parts 恒为空、0 token、无 error part）。
+修复：在 `opencode.mjs` 顶部 post-prepend 一段——`if (typeof WebAssembly === "undefined")` 时把 `globalThis.fetch` 换成基于 `node:http(s)` 的实现（C++ HTTP 解析器，不用 wasm），用 `Readable.toWeb(res)` 当响应体、全局 `Response`/`Headers` 包装（这俩是纯 JS，不碰 wasm）。opencode 各处 `getOriginalFetch = () => globalThis.fetch` 运行时读全局，覆盖即生效。验证：`POST /session/:id/message` 能返回 reasoning+text part 且 tokens>0。
+> 另一个同源坑：app 域 stat 不了 `/bin/bash` 等（抛 **EACCES** 而非 ENOENT），opencode 的 shell 探测 `stat4()` 只吞 ENOENT 会把对话打断——把 `stat4` 包 try/catch 吞掉所有错误即可。
+> 这俩补丁都打在 bundle 产物 `resfile/resources/app/opencode/opencode.mjs` 上（不是源码 patch），升级 bundle 时要重打。
+
+## 坑：写文件"无响应" + 只能访问沙箱
+
+两个症状同源于权限：
+1. **写 PC 真实路径（如 Documents）卡住/失败**：默认 app 沙箱进程访问不了 `/storage/Users/currentUser/*`。解法见 [[鸿蒙PC-app访问PC用户目录]]——`module.json5` 申请 `READ_WRITE_DOCUMENTS_DIRECTORY`/`READ_WRITE_DOWNLOAD_DIRECTORY`（带 `reason`+`usedScene`），`EntryAbility.onCreate` 里 `requestPermissionsFromUser` 弹窗授权；授权后 opencode 用物理路径直接 fs 读写 Documents/Download 即可（Desktop 是 system_basic 够不着）。
+2. **write/edit/bash 工具"无响应"**：opencode 默认权限是 `"ask"`，工具调用挂在 `running` 等审批；且写**项目根目录外**的路径还要过 `external_directory` 这道闸。headless/API 下没人批就永久挂起。解法：`main.js` 在 HOME 自动写默认 `~/.config/opencode/opencode.json`（仅当不存在时），把 `permission: { edit/bash/webfetch/external_directory: "allow" }`——桌面端用户在自己 PC 上用，自动放行合理。
+3. **bash 工具里跑 `node xxx.js` 子进程崩溃**（`Check failed: 12 == errno`）：子 node 继承了 LD_PRELOAD（io_uring 已修）但没带 `--jitless`（那是 arg 不是 env），撞 JIT。解法：sidecar env 加 `NODE_OPTIONS=--jitless`（实测 NODE_OPTIONS 接受 --jitless），所有子 node 自动 jitless。
+
+## 验证 & 已知限制
+- `curl 127.0.0.1:4097/` → 200 + 本地 `index.html`；UI 显示绿点 `127.0.0.1:4097`、可开项目、聊天框/模型选择/Build 模式齐活。截图见任务记录。
+- jitless ⇒ 无 WebAssembly（opencode 的 web-tree-sitter 本就 stub，不冲突）；纯解释执行性能下降，IO/网络负载可接受。
+- 体积 248MB（node 113M + libelectron 151M + bundle 24M）。可裁 npm/AI provider，但 HAP 无硬性体积限制。
+- bundle 仍是 1.14.39；上游 1.17.3 的 rebase 是另一条线。
+
+## 相关
+- [[鸿蒙PC-app域执行二进制与JIT限制]] —— 私有 HNP exec / io_uring / jitless 三关的平台机制（本适配的核心拦路点）。
+- [[鸿蒙PC-opencode离线分发打包]] —— 1.14.39 HNP/tar 产物的来源（本 HAP 直接复用）。
+- [[鸿蒙PC-opencode本地WebUI重新嵌入]] —— web-ui 本地静态资源的由来（被本 HAP 打进 resfile）。
+- [[鸿蒙PC-opencode-rg-exec-denied]] —— rg exec 限制；本 HAP 改用私有 HNP 里的 rg + `OPENCODE_RG_PATH`，不再 cp 到 /data/local/tmp。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-opencode-rg-exec-denied.md

@@ -0,0 +1,59 @@
+---
+name: 鸿蒙PC-opencode-rg-exec-denied
+description: opencode 自带 rg 在 HNP 包路径下被 SELinux/`hmmac` 阻拦 exec（`Permission denied`，dmesg 无 avc）；把 rg `cp` 到 `/data/local/tmp/` 并通过 `OPENCODE_RG_PATH` 指过去
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：opencode 自带 rg `Permission denied` 与 OPENCODE_RG_PATH
+
+## 现象
+opencode 在鸿蒙 PC（HiShell + HNP 1.14.39）启动后，agent 触发任何 grep/glob 工具都报：
+```
+/bin/sh: /data/service/hnp/opencode.org/opencode_1.14.39/bin/rg: Permission denied
+```
+binary 实际是 4.6M static arm64 ELF、`-rwxr-xr-x root:root`、`ls -Z` 显示 `u:object_r:hnp_file:s0`，但 app 域 fork 的 `/bin/sh` 就是 exec 不动。
+
+## 根因
+这是 HNP 二进制的通用 SELinux/MAC exec 限制——`hnp_file:s0` 标签不允许 app 域子进程经 `/bin/sh` 再 exec，机制、`data_local_tmp` 物理拷贝修复、以及"软链无效/dmesg 无 avc"等通用细节，见 [[鸿蒙PC-HNP二进制SELinux-exec限制]]。
+
+opencode 专属的那一环：launcher (`/data/service/hnp/opencode.org/opencode_1.14.39/share/opencode-launcher.sh`) 默认把 `OPENCODE_RG_PATH` 写死成 `$DIR/../bin/rg`（即那个被 deny 的 hnp_file），所以即使 PATH 上有别的 rg 也用不上——必须显式覆盖这个环境变量。
+
+## 修复套路（opencode 专属）
+
+1. 按 [[鸿蒙PC-HNP二进制SELinux-exec限制]] 把 rg 物理拷贝到 `data_local_tmp` 标签目录：
+   ```bash
+   hdc shell "cp /data/app/el1/bundle/<userId>/hnppublic/opencode.org/opencode_1.14.39/bin/rg /data/local/tmp/rg-test/rg && chmod 755 /data/local/tmp/rg-test/rg"
+   ```
+
+2. 在 HiShell zsh 的 HOME 写 `.zshrc`，把 `OPENCODE_RG_PATH` 在 launcher 之前固定下来：
+   ```sh
+   export OPENCODE_RG_PATH=/data/local/tmp/rg-test/rg
+   ```
+   launcher 里那段
+   ```sh
+   [ -z "${OPENCODE_RG_PATH:-}" ] && [ -x "$DIR/../bin/rg" ] && export OPENCODE_RG_PATH="$DIR/../bin/rg"
+   ```
+   有 `[ -z ... ]` 保护，外部已经设了就不会被覆盖。
+
+3. 重启 opencode（关 HiShell tab 重开，或 `source ~/.zshrc` 后退出当前 opencode 进程再起）。验证：
+   ```bash
+   cat /proc/<opencode-pid>/environ | tr '\0' '\n' | grep OPENCODE_RG_PATH
+   # 应输出 /data/local/tmp/rg-test/rg
+   ```
+
+## HOME 在哪 / 怎么写 .zshrc
+- HiShell zsh `HOME=/storage/Users/currentUser`，但那是 app NS 视图。
+- 真实底层路径：`/data/service/el2/100/hmdfs/account/files/Docs/`（uid 20001006:file_manager）。
+- hdc shell 是 root，可以直接 `hdc file send /tmp/.zshrc /data/service/el2/100/hmdfs/account/files/Docs/.zshrc`，写完 `chown 20001006:file_manager` + `chmod 644`。
+- 同目录已有 `.zsh_history` 是 660 owned `20001006:file_manager`，但 zsh 进程实际是 app uid 20020107——hmdfs 的 ACL 把 file_manager 组对 app uid 等效放开，所以 644 / 660 都能读。
+
+## 跟现有记忆的关系
+
+- [[鸿蒙PC-HNP二进制SELinux-exec限制]] —— 本问题的底层平台机制（exec 限制 + 通用修复 + 反例）。
+- [[鸿蒙PC-HNP包与PATH]] —— HNP 物理路径与 app NS 视图、PATH 差异。
+- [[鸿蒙PC-进程视角与mount-namespace]] —— 为什么 `hdc shell` 直接 `ls /data/service/hnp/...` 看不到，要 `nsenter -t <opencode-pid> -m --`。
+
+## 旁路：自构建 opencode dist-harmony
+- harmony bundle 构建脚本生成的 `dist-harmony/run.sh` 是另一条线，跟 HNP 装的 1.14.39 不冲突；那条线如果要 exec rg 也需要把 rg 放进 `dist-harmony/` 同目录或外部用 `OPENCODE_RG_PATH` 覆盖，逻辑跟上面一样。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-opencode/346/217/222/344/273/266/351/203/250/347/275/262.md

@@ -0,0 +1,146 @@
+---
+name: 鸿蒙PC-opencode插件部署
+description: 把 opencode 插件目录部署到鸿蒙 PC 让本机 opencode 加载的套路：tar 推送 + 清 AppleDouble + 改 `.js` import 后缀为 `.ts`（Node 24 直读 `.ts` 不接受 `.js` 别名）+ 改 `opencode.json` 的 plugin 字段
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+> **前置（鸿蒙 PC 商用机）**：下文的 `/data/service/hnp/…`、`/data/app/el1/…` 路径与 `nsenter` **对 hdc shell（uid 2000）都够不到**——公共 HNP 目录不存在、应用沙箱 Permission denied、nsenter 被拒（2026-09-01 实测）。本篇适用于这些路径可及的环境；商用机上的等价做法是**把运行时与程序打进私有 HNP 随 HAP 装机**，见 [[鸿蒙PC-app域执行二进制与JIT限制]]、[[鸿蒙PC-hdc能力边界与取证通道]]。
+
+# 鸿蒙 PC 部署 opencode 插件
+
+把 macOS 端的 opencode 插件（如 `plugin/`）推到鸿蒙 PC 上让其本机 opencode 加载的完整套路。
+
+## 鸿蒙 PC 上 opencode 的位置（HNP 安装版，唯一）
+
+历史上鸿蒙 PC 同时存在两套 opencode（HNP 安装版 + hdc shell 手工部署版），2026-05-21 后**hdc shell 那套已删除**，只留 HNP 版。所有路径都在应用 mount ns 内，hdc shell 直接 ls 看不到，要 `nsenter -t <HiShell-PID> -m -- ...`：
+
+- 程序：`/data/service/hnp/opencode.org/opencode_<ver>/share/opencode.mjs`
+- 启动：同目录 `opencode-launcher.sh`（PATH 内 `opencode` 是它的软链；user 在 HiShell 里直接敲 `opencode` / `opencode web` 走的就是这个）
+- HOME：`/storage/Users/currentUser/`（HiShell 进程的 env HOME）
+- **XDG_CONFIG_HOME**：`/data/storage/el2/base/haps/entry/files`（HiShell 给 opencode 设的）
+- **配置文件真实位置**：`$XDG_CONFIG_HOME/opencode/opencode.json` = `/data/storage/el2/base/haps/entry/files/opencode/opencode.json`。
+  ⚠️ opencode 优先看 `XDG_CONFIG_HOME` 而非 `$HOME/.config`，所以**写到 `~/.config/opencode/opencode.json` 没用**——必须按 XDG 路径写。该目录已有 `models.json`、`node_modules/`、`package.json`，直接在里面建/合并 `opencode.json` 就行（已存在的 owner 是 uid `20020107`，nsenter 进 mount ns 后以 root 写没问题）。
+- 数据：`/storage/Users/currentUser/.local/share/opencode/`（含 SQLite）
+- HiShell 主进程 PID：`pgrep -f hishell` 第一行就是 `com.huawei.hmos.hishell` 主进程（uid `20020107`）。`nsenter -t <PID> -m` 用这个 PID。
+
+**已运行的 opencode 进程不会重读配置**：opencode 启动时一次性读 config，之后改 opencode.json 对当前进程**不生效**。必须让 user 在 HiShell 里 Ctrl-C 退出再重新 `opencode web`。所以推荐部署顺序：先 nsenter 写配置，再让 user 启动 opencode。
+
+**节点解释器**仍在 `/data/local/tmp/usr/local/bin/node`（HiShell ns 里也能看到），launcher 已经处理 XPM 签名 + `/lib/ld-musl-aarch64.so.1` 兜底。
+
+## 关键坑：插件源码不能放在 `/data/local/tmp/`
+
+`/data/local/tmp/` 在 HiShell 应用沙箱里**只有 `--x` 权限**（能 traverse 进入，但 `stat` / 列目录会失败）：
+
+```text
+/data/local/tmp/ -> drwxrwx--x shell shell
+```
+
+所以即使我们把 plugin 推到 `/data/local/tmp/PC/plugin/`，opencode 进程（uid `20020107`）尝试加载时会报：
+
+```text
+ERROR service=plugin error=EACCES: permission denied, stat '/data/local/tmp/PC/plugin/index.ts' failed to install plugin
+```
+
+**修复**：把 plugin 副本放到应用沙箱可读的目录里，比如 XDG_CONFIG_HOME 同级的 `plugins/` 子目录，并 chown 给 HiShell uid。`opencode.json` 的 `plugin` 字段相应改成这个路径。
+
+```sh
+hdc shell '
+  PID=$(pgrep -f hishell | head -1)
+  APP_DIR=/data/storage/el2/base/haps/entry/files/plugins/hmos-pc
+  nsenter -t $PID -m -- mkdir -p $APP_DIR
+  nsenter -t $PID -m -- cp -r /data/local/tmp/PC/plugin/. $APP_DIR/
+  nsenter -t $PID -m -- chown -R 20020107:20020107 $APP_DIR
+'
+# opencode.json 里写:
+# "plugin": ["file:///data/storage/el2/base/haps/entry/files/plugins/hmos-pc/index.ts"]
+```
+
+## 推送插件三步
+
+1. **打包并推送源码**（不要走 `hdc file send` 递归，先 tar）：
+
+   ```sh
+   tar --exclude='plugin/node_modules' --exclude='plugin/*.tgz' --exclude='plugin/.DS_Store' \
+     -czf /tmp/plugin.tar.gz plugin
+   hdc shell 'mkdir -p /data/local/tmp/PC && rm -rf /data/local/tmp/PC/plugin'
+   hdc file send /tmp/plugin.tar.gz /data/local/tmp/PC/plugin.tar.gz
+   hdc shell 'cd /data/local/tmp/PC && tar -xzf plugin.tar.gz && rm plugin.tar.gz'
+   ```
+
+2. **清理 macOS AppleDouble 文件**（macOS 的 BSD tar 默认把扩展属性写成 `._*`，鸿蒙 toybox tar 不识别 `--no-xattrs`，需要解压后手动删）：
+
+   ```sh
+   hdc shell 'find /data/local/tmp/PC/plugin -name "._*" -delete; find /data/local/tmp/PC/plugin -name ".DS_Store" -delete'
+   ```
+
+3. **写到 XDG_CONFIG_HOME 下的 opencode.json**（**不是** `~/.config/opencode/`），并改 owner 为 HiShell uid：
+
+   ```sh
+   # 本地准备 opencode.json 后：
+   hdc file send /tmp/opencode.json /data/local/tmp/opencode.json.tmp
+   hdc shell '
+     PID=$(pgrep -f hishell | head -1)
+     XDG=/data/storage/el2/base/haps/entry/files/opencode
+     nsenter -t $PID -m -- cp /data/local/tmp/opencode.json.tmp $XDG/opencode.json
+     # 必须改 owner 给 HiShell uid，不然 opencode 跑起来读不了：
+     # PermissionDenied: FileSystem.readFile (.../opencode.json)
+     nsenter -t $PID -m -- chown 20020107:20020107 $XDG/opencode.json
+     nsenter -t $PID -m -- chmod 644 $XDG/opencode.json
+     rm /data/local/tmp/opencode.json.tmp
+   '
+   ```
+
+   `/data/local/tmp/PC/plugin/` 在 HiShell mount ns 里也能直接看到，所以插件源码不必再拷一份到 HNP 路径下。**配置写入后让 user 重启 opencode 才生效**。
+
+   `nsenter` 切的只是 mount namespace，user namespace 没切——hdc shell 是 root，写出来的文件 owner 也是 root，HiShell 应用进程（uid `20020107`）读不到。chown 完才能让 opencode 加载。
+
+## 关键坑：`.ts` 插件的 import 后缀必须写 `.ts`
+
+opencode 在 HarmonyOS 上跑的是 Node 24 bundle，不是 Bun。Node 内置的 type-stripping 能直接加载 `.ts`，但 ESM 解析**要求 import 路径写真实存在的文件名**。
+
+TypeScript 项目里常见的写法 `import x from './foo.js'`（编译期会换成 `.js`）在 Node 直接读 `.ts` 时**会找不到 `.js`**，报：
+
+```text
+ERROR service=plugin error=Cannot find module '/.../src/paths.js' imported from /.../index.ts failed to load plugin
+```
+
+**修复方法**：把所有 plugin 内部相对 import 的 `.js` 改成 `.ts`（只动 device 上的副本就行，不污染本地源码）：
+
+```sh
+# 在 macOS 上改了之后再 hdc file send 推回去（toybox sed -i 不稳）
+sed -i '' "s|\.js'|.ts'|g; s|\.js\"|.ts\"|g" /tmp/index.ts /tmp/build-agents.ts /tmp/load-prompt.ts
+```
+
+每次重新打包推送都要再做一次这步——所以更长治久安的做法是在源码里就用 `.ts` 后缀，或者额外提供一份 `dist/*.mjs` 编译产物给 device 版用。
+
+## 验证
+
+让 user 在 HiShell 里 `opencode agent list`；或者从 hdc shell 走 HiShell mount ns + HOME 模拟：
+
+```sh
+hdc shell '
+  PID=$(pgrep -f hishell | head -1)
+  nsenter -t $PID -m -- sh -c "HOME=/storage/Users/currentUser opencode agent list" 2>&1 \
+    | grep -E "\((primary|subagent|all)\)"
+'
+```
+
+成功时除了 7 个内置 agent，还会看到自定义 agent（例如 `hmos-library-adapter-pc (primary)`）。
+
+加载失败时**不会**在 CLI 输出报错，要去 HiShell HOME 下的日志里抓：
+
+```sh
+hdc shell '
+  PID=$(pgrep -f hishell | head -1)
+  LOGDIR=/storage/Users/currentUser/.local/share/opencode/log
+  LATEST=$(nsenter -t $PID -m -- ls -t $LOGDIR | head -1)
+  nsenter -t $PID -m -- grep -iE "plugin|hmos|error" "$LOGDIR/$LATEST"
+'
+```
+
+## 相关
+
+- [鸿蒙PC-uid与文件归属.md](../platform/鸿蒙PC-uid与文件归属.md) — opencode 在 `/data/local/tmp/` 以 root 跑，文件归属与 sandbox 应用不同。
+- [鸿蒙PC-进程视角与mount-namespace.md](../platform/鸿蒙PC-进程视角与mount-namespace.md) — hdc shell 视角与应用进程视角差异。