@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-opencode/346/234/254/345/234/260WebUI/351/207/215/346/226/260/345/265/214/345/205/245.md

@@ -0,0 +1,96 @@
+---
+name: 鸿蒙PC-opencode本地WebUI重新嵌入
+description: 让 `opencode web` 不再反代到 app.opencode.ai：build 脚本里 embed 静态资源 + post-prepend `fs.promises.exists` polyfill + 经 HiShell mount ns nsenter 进 HNP 包路径替换
+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 bundle 重新嵌入本地 Web UI
+
+让 opencode 在鸿蒙 PC 上 `opencode web` / `opencode serve` 的浏览器界面**不再反代到 https://app.opencode.ai**，而是走本地嵌入的静态资源。
+
+## 缘起
+
+`build-harmony.ts` 早期把 web UI 资源剥离了，bundle 里 `import("opencode-web-ui.gen.ts")` 模块缺失，server 加载失败后 fallback 到 [`https://app.opencode.ai`](https://app.opencode.ai) —— 浏览器看到的 UI 是云端版本（左上角带 DEV badge，且会跟随 cloud 滚动更新）。
+
+## 关键发现
+
+1. **server UI 路由**：`packages/opencode/src/server/shared/ui.ts` 与 `server/routes/ui.ts` 都用 `import("opencode-web-ui.gen.ts")`。这个模块**没有源码**——官方 build 时由 `script/build.ts` 的 `createEmbeddedWebUIBundle()` 临时生成成 `Record<filename, absPath>`。
+
+2. **embed 的实际 web 包不是 `packages/web`，是 `packages/app`**（Solid + Vite）。`bun run --cwd packages/app build` 出 `dist/`，里面 535 个文件（不含 .map 大约 18 MB）。
+
+3. **Node target 不能用 Bun 的 `with { type: "file" }` import attribute**。harmony bundle 是 `Bun.build({ target: "node" })`，所以官方那套 stub 直接搬不通。可行做法：写一个 ESM stub 模块，用 `import.meta.url` 在 runtime 拼绝对路径，server 自己用 `fs.readFile(absPath)` 读出来。
+
+4. **Node 没有 `fs.promises.exists`**。`server/routes/ui.ts` 调了 `fs.promises.exists(path)`——这是 Bun 扩展 API。bundle 跑到 web 路由时会 throw `TypeError: fs16.exists is not a function`。需要在 bundle 头部 polyfill：
+   ```js
+   import { promises as __fp } from "node:fs"
+   if (!__fp.exists) __fp.exists = async p => { try { await __fp.access(p); return true } catch { return false } }
+   ```
+
+5. **`Bun.build` banner 里塞多余 ESM import 会让 build 静默 abort**（exit 1，无 stderr，只有 "Bun v1.3.14 (macOS arm64)" 一行）。把 polyfill 放到 banner 里会让整个 build 崩。绕开：build 完成后用 `readFileSync/writeFileSync` 把 polyfill **post-prepend** 到产物里。
+
+6. **Bun.build 在 monorepo 内部目录跑会随机 abort**（同样是上面那种静默 exit 1）。从 monorepo 外部（如 `/`）跑就稳。建议在 `harmony-deploy.sh` 里 `cd /` 或 `cd "$HOME"` 后再调 bun。
+
+## 部署落点：是 HNP 包，不是 `/data/local/tmp/opencode-harmony/`
+
+`opencode` CLI 实际是从 HNP 安装包跑的：
+
+```text
+/data/service/hnp/opencode.org/opencode_<ver>/share/opencode.mjs
+/data/service/hnp/opencode.org/opencode_<ver>/share/opencode-launcher.sh
+/data/service/hnp/opencode.org/opencode_<ver>/share/web-ui/    # ← 我们新加的
+```
+
+- 这个路径**在 hdc shell 视角下不可见**（应用 mount namespace 私有）——参考 [鸿蒙PC-进程视角与mount-namespace.md](../platform/鸿蒙PC-进程视角与mount-namespace.md)。
+- 通过任一 HiShell 关联进程的 PID 走 `nsenter -t <PID> -m -- ...` 就能读写。`com.huawei.hmos.hishell` 主进程是稳定 PID。
+- 应用进程的 mount ns 里也能看到 `/data/local/tmp/...`，所以可以先 `hdc file send` 推到 `/data/local/tmp/`，再 nsenter 进 ns `cp` 到 HNP 路径。
+
+## 完整重建 + 部署套路
+
+```sh
+# 从 opencode 适配工程根目录起步（含 src/ 上游 checkout、build/ 构建脚本、dist-harmony/ 产物）
+ROOT="$(pwd)"                        # 绝对路径：step 2 要 cd / 走，不能用相对的
+
+# 1) 在 macOS 上 build web UI
+cd "$ROOT"/src
+bun install                          # monorepo 一次
+bun run --cwd packages/app build     # → packages/app/dist/
+
+# 2) build harmony bundle（cwd 必须在 monorepo 外，否则 Bun.build 会静默 abort）
+cd /
+OPENCODE_SKIP_MODELS_SNAPSHOT=1 \
+  bun "$ROOT"/build/build-harmony.ts
+# 产物：dist-harmony/{opencode.mjs, web-ui/, run.sh, package.json, README.md}
+
+# 3) 推到 device 中间区
+cd "$ROOT"/dist-harmony
+tar --exclude='._*' -czf /tmp/web-ui.tar.gz web-ui
+hdc file send opencode.mjs       /data/local/tmp/opencode-harmony/opencode.mjs
+hdc file send /tmp/web-ui.tar.gz /data/local/tmp/opencode-harmony/web-ui.tar.gz
+hdc shell 'cd /data/local/tmp/opencode-harmony && rm -rf web-ui && tar -xzf web-ui.tar.gz && rm web-ui.tar.gz'
+hdc shell 'find /data/local/tmp/opencode-harmony/web-ui -name "._*" -delete'
+
+# 4) 透过 HiShell mount ns 复制进 HNP 路径
+hdc shell '
+PID=$(pgrep -af com.huawei.hmos.hishell | head -1 | awk "{print \$1}")
+HNP=/data/service/hnp/opencode.org/opencode_1.14.39/share
+nsenter -t $PID -m -- cp /data/local/tmp/opencode-harmony/opencode.mjs $HNP/opencode.mjs
+nsenter -t $PID -m -- rm -rf $HNP/web-ui
+nsenter -t $PID -m -- cp -r /data/local/tmp/opencode-harmony/web-ui $HNP/web-ui
+'
+
+# 5) 让 user 在 HiShell 里重启 opencode web；浏览器应当不再反代到 app.opencode.ai。
+```
+
+## 验证
+
+`curl -sv http://127.0.0.1:<port>/` 拿到的 `content-length` 应当是几 KB 数量级的 HTML（embedded `index.html`），而不是 cloud 那种几十 KB / 带 `app.opencode.ai` 的 cookie 痕迹。`/assets/*.js` 直接 200 且来自本地。
+
+## 相关
+
+- [鸿蒙PC-opencode插件部署.md](鸿蒙PC-opencode插件部署.md) — 同一 opencode 实例里加载自定义插件的套路（`opencode.json` 配置 + `.ts` import 后缀坑）。
+- [鸿蒙PC-进程视角与mount-namespace.md](../platform/鸿蒙PC-进程视角与mount-namespace.md) — nsenter 跨 mount ns 操作的通用方法。
+- [鸿蒙PC-HNP包与PATH.md](../platform/鸿蒙PC-HNP包与PATH.md) — HNP 包安装位置与 PATH 差异。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-opencode/347/246/273/347/272/277/345/210/206/345/217/221/346/211/223/345/214/205.md

@@ -0,0 +1,95 @@
+---
+name: 鸿蒙PC-opencode离线分发打包
+description: 把适配好的 opencode 打成 `.hnp`/`.tar.gz` 给他人安装：HNP 本质是 ZIP（无强制 manifest/签名）；普通用户装不了第三方 HAP（只能用户级安装到 `$XDG_CONFIG_HOME/`）
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：opencode 离线分发打包（pack-hnp.sh）
+
+把适配好的 opencode bundle 打成可分发给其他鸿蒙 PC 用户安装的 `.hnp` / `.tar.gz` 包，接收方在 HiShell 本机跑 `install.sh` 即可装好。
+
+## 路线选择：为什么不走 HAP / 系统 HNP
+
+调研结论（见 `docs/zh-cn/application-dev/tools/bm-tool.md` 错误码 `9568401`）：
+
+- **第三方 HAP 普通用户根本装不了**：侧载禁止；debug 签名仅在"开发者模式 + USB 调试"设备上工作；`bm install` 只在 hdc shell 用；release 签名要走应用市场审核（需华为开发者资质）。
+- **HNP 公共安装路径 `/data/app/el1/bundle/<userId>/hnppublic/...`** 需要 root 写权限，HiShell 用户进程（uid `20020107`）写不进去。
+- **官方 `hnpcli` 工具**仓库在 gitcode 但文档极少，未广泛开放给三方使用。
+
+所以"普通鸿蒙 PC 用户拿到一个文件就能装"在当前生态下唯一可行的路线就是：**ZIP 包 + 用户级安装到 `$XDG_CONFIG_HOME/`**，完全绕开系统安装器。
+
+## HNP 包就是 ZIP，无强制签名/manifest
+
+- 鸿蒙 HNP 规范本质是 **ZIP 格式归档**（见 `docs/zh-cn/application-dev/security/hapsigntool-errorcode.md`：包大小 ≤ 4GB、符合 ZIP 规范）。
+- **没有强制 manifest**（不像 HAP 那样必需 `module.json5`/`pack.info`），公共 HNP 也没有。
+- **签名可选**：`hapsigntool` 支持给 HNP 签名，但用户级安装走 `unzip + 脚本` 路线根本不过签名校验，零签名工程量。
+- HiShell 默认 toybox **不一定带 `unzip`**，所以打包同时产出 `.tar.gz` 兜底。
+
+## 安装落点：用户级三处
+
+| 路径 | 内容 | 来源 |
+|---|---|---|
+| `$XDG_CONFIG_HOME/opencode-harmony/` | bin/、share/、lib/ 全套资产 | install.sh 拷贝 |
+| `$HOME/.local/bin/opencode` | 启动脚本软链 | install.sh 创建，需用户加 PATH |
+| `/data/local/tmp/opencode-harmony/rg` | rg fallback 副本 | **仅当**包内 rg 被 SELinux 拒 exec 才生成 |
+
+opencode 用户配置仍走 `$XDG_CONFIG_HOME/opencode/opencode.json`（不是 `~/.config/opencode/`，见 [[鸿蒙PC-opencode插件部署]]）。
+
+## pack-hnp.sh 工作流
+
+打包脚本 `pack-hnp.sh` 做的事：
+
+1. 读 `src/packages/opencode/package.json` 拿版本
+2. 拷 `dist-harmony/{opencode.mjs, package.json, web-ui/}` 到 stage 的 `share/`
+3. 拷 ripgrep aarch64 fallback 到 `bin/rg`
+4. 拷 launcher 模板 `installer/opencode-launcher.sh.tpl` 到 `bin/opencode`（保留 `__OPENCODE_RG_PATH__` 占位符，给 install.sh 装机期填）
+5. 可选 watcher / node-pty prebuild 拷到 `lib/node_modules/`
+6. install.sh / README 模板做 `__OPENCODE_VERSION__` 替换
+7. 同时打 `.hnp`（zip）和 `.tar.gz`，并出 sha256
+
+产物每个版本约 **12MB 压缩 / 47MB 未压缩**（含 24M bundle + 18M web-ui + 4.4M rg）。
+
+## install.sh 的关键设计：rg exec 自检 + fallback
+
+包内 rg 默认放 `bin/rg`，install.sh 装完做一次 `$INSTALL_DIR/bin/rg --version`：
+- **成功** → launcher 里 `OPENCODE_RG_PATH` 写死指 `$INSTALL_DIR/bin/rg`，路径最自包含
+- **失败**（SELinux 标签问题）→ 自动 `cp` 到 `/data/local/tmp/opencode-harmony/rg` 并改写 launcher
+
+launcher 本身不在运行时探测，性能更稳。`sed -i.bak ... && rm *.bak` 兼容 BSD/GNU sed。
+
+## 跨平台 sed 坑
+
+`pack-hnp.sh` 在 macOS（BSD sed）和 Linux（GNU sed）都要跑。`sed -i ''` 是 BSD 写法，`sed -i` 是 GNU。统一封装：
+
+```sh
+sedi() {
+  if sed --version >/dev/null 2>&1; then sed -i "$@"; else sed -i '' "$@"; fi
+}
+```
+
+## 端到端验证
+
+主机端：
+```sh
+./build/pack-hnp.sh                           # 走已有 dist-harmony
+./build/pack-hnp.sh --build                   # 重新 build bundle 再打包
+ls dist-hnp/                                  # opencode-harmony-X.Y.Z.{hnp,tar.gz,sha256}
+```
+
+设备端（HiShell）：
+```sh
+tar -xzf opencode-harmony-1.14.39.tar.gz
+cd opencode-harmony-1.14.39 && ./install.sh
+export PATH=$HOME/.local/bin:$PATH            # 加到 .zshrc
+opencode --version                            # → 1.14.39
+opencode serve --port 4096                    # 本地 web-ui 应直接出 200
+```
+
+## 相关
+
+- [[鸿蒙PC-opencode插件部署]] — 同一 opencode 实例加载 plugin（本包不带插件，按需后装）
+- [[鸿蒙PC-opencode本地WebUI重新嵌入]] — web-ui 是 build-harmony.ts 的产物，本包直接复用
+- [[鸿蒙PC-opencode-rg-exec-denied]] — rg fallback 路径设计的依据
+- [[鸿蒙PC-HNP包与PATH]] — 解释了为什么不走系统 HNP 路径

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-pyGLFW-Python/347/273/221/345/256/232/345/272/223/350/277/201/347/247/273.md

@@ -0,0 +1,38 @@
+---
+name: 鸿蒙PC-pyGLFW-Python绑定库迁移
+description: pyGLFW（GLFW 的纯 Python ctypes 绑定）鸿蒙化——语言绑定库通用公式：原生库共享化 + PYGLFW_LIBRARY 类加载缝 + 解释器线程壳（嵌入 CPython 于 OWB worker 线程）；pyGLFW 本体零补丁
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+pyGLFW（v2.10.0，GLFW3 的**纯 Python ctypes 绑定**，零 C 扩展）迁鸿蒙 PC。2026-07-02 **真机端到端跑通**（HAD-W32：CLI smoke `import glfw; init:1; version 3.5.0 OHOS EGL`；HAP 内纯 Python 旋转三角形 `GL_VERSION OpenGL ES 3.2`；tap→Python 回调 `glfw.set_window_size(900,600)`/`maximize_window` 窗口真变；CPU 14.8% 状态 S 无忙等；force-stop 无 cppcrash）。这是"**语言绑定库**"通用方案的第一个实例，坐在 [[鸿蒙PC-通用视窗桥ohos_window_bridge]] + [[鸿蒙PC-GLFW视窗后端-EGL-XComponent]] 之上。
+
+## 通用公式（任何 ctypes/FFI 绑定库照抄）
+
+**绑定库不需要新后端——它发出的就是 C 调用。** 三步：
+
+1. **原生库共享化**：ctypes 只能 `CDLL` 共享库。GLFW 加一轮 `-DGLFW_LIBRARY_TYPE=SHARED` 出 `libglfw.so`；**必须以 .so 动态链接 OWB**（CMake 新增 `OHOS_WINDOW_BRIDGE_LIBRARY` 变量）——库和宿主壳要共享**同一个** OWB 实例，注册表/事件队列是进程级状态，**静态嵌两份 OWB 会各持一份状态直接坏**（本次最重要的架构守则）。
+2. **加载缝**：优先找绑定库自带的"指定库路径"机制。pyGLFW = `PYGLFW_LIBRARY` 环境变量（源码核实：该分支直接 `ctypes.CDLL(路径)`，**不走 subprocess 版本探测**）→ **pyGLFW 零补丁**。subprocess 探测那条默认路径在 app 沙箱必死（[[鸿蒙PC-app域执行二进制与JIT限制]]），所以鸿蒙上**必须设 PYGLFW_LIBRARY**。
+3. **解释器线程壳**：`ohos_window_bridge/napi/owb_ohos_python_app.h` —— 线程壳（[[鸿蒙PC-通用视窗桥ohos_window_bridge]] 的 owb_ohos_app.h）的语言运行时变体：worker 的 main() = `setenv(PYTHONHOME)` → `Py_Initialize` → `PySys_SetArgvEx(updatepath=1)` → `PyRun_SimpleFileEx(main.py)`（社区 CPython 嵌入指南同款）。一行 `OWB_OHOS_PYTHON_APP("模块名","app/main.py")` 就是 HAP 全部 native 侧。脚本经 ctypes 调 glfw 时与 C 应用走**完全相同**链路：create_window 阻塞 `OWB_WaitForSurface`、输入走队列、set_window_size 走 TSFN。**OWB/GLFW 全栈零改动。**
+
+## 打包要点（demo HAP）——三个真机踩出的坑（黑屏三连环）
+
+1. **依赖闭包要递归查到底**：`libpyglfw_demo.so → libpython3.12.so.1.0 → libintl.so.8 → libiconv.so.2`；lib-dynload 扩展再要 `libffi.so.8`(_ctypes)/`libz/libbz2/liblzma/libsqlite3/libreadline/libtinfow/libgdbm/libuuid/libssloh/libcryptooh`。**少任何一个 = MUSL-LDSO "Error loading shared library" → napi 模块加载失败 → 黑屏且无任何自家日志**（hilog 搜 `MMG.*load module.*failed` / `MUSL-LDSO` 定位）。全套 .so 从设备 HNP python lib/ 拉。
+2. **hvigor 打包 `libs/` 只收 `.so`**：stdlib 的 `.py` 放 libs 下被**静默过滤** → `Py_Initialize` 找不到 encodings。→ `.py` 树放 **resfile**（原样打包），`PYTHONHOME=/data/storage/el1/bundle/entry/resources/resfile/Python`。社区指南的"stdlib 放 libs"布局在此版 hvigor 不成立。
+3. **resfile 不可执行映射**：`lib-dynload/*.so` 放 resfile 里 dlopen 报 `ImportError: ... No error information`。→ 扩展 .so 拆回 **`libs/lib-dynload/`**（libs 下子目录的 .so 会被打包），壳 `setenv PYTHONPATH=<libs>/lib-dynload`，import 按 sys.path 命中。
+
+其余：
+- `resfile/pyglfw-app/`：`main.py` + `site-packages/glfw/`；脚本头三行接线：`sys.path.insert(site-packages)` + `os.environ['PYGLFW_LIBRARY']=/data/storage/el1/bundle/libs/arm64/libglfw.so` + `import glfw`。
+- `module.json5` **`extractNativeLibs: true`**。
+- Python 运行时从设备 HNP 拉（[[鸿蒙PC-设备Python运行时]]，3.12.8 ABI 已实测；ohos-python-release 同源）；Mac 端缓存 `.tmp/device-python/`（include/libpython/pylib/stdlib 全套，重放不再要设备）。
+- Python 的 print/异常：壳把 stdout/stderr freopen 到 `/data/storage/el2/base/files/owb_python.log`（真机排障入口，本次三个坑全靠它+hilog 定位）。
+
+## demo 的 GL 怎么解
+
+设备 app NDK 命名空间只有裸 `libGLESv3.so`（无 v2/无 .1，同 GLFW dlopen 坑）→ demo 的 main.py **内嵌 ~50 行 ctypes GLES shim**（直接 `CDLL("libGLESv3.so")` 声明 glClear/shader 系列），不依赖 PyOpenGL（其库名假设不成立，列 stretch）。
+
+## 已知边界
+
+- `get_x11_window`/`get_cocoa_window` 等平台句柄 API 无对应（分析报告 unadaptable）——不调用即可。
+- CLI（HNP python）只能 smoke `import glfw; glfw.init()`；出窗口必须 HAP 进程（WindowStage/XComponent 只在应用进程）。

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

@@ -0,0 +1,44 @@
+---
+name: 鸿蒙PC-pyzmq-libzmq扩展
+description: 适配依赖第三方 native 库(libzmq)的 Python 扩展——先 CMake 交叉编译 libzmq 静态库，再 cythonize+静态链接，以 pyzmq 为例
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+pyzmq（ipykernel 的硬依赖）= Cython 扩展 + 依赖 native 的 **libzmq**（C++）。这是 [[鸿蒙PC-Python-C扩展交叉编译]] 的最复杂形态：扩展本身要链一个第三方 native 库。套路是"**先把那个 native 库 CMake 交叉编译成静态库，再把它静态链进扩展**"，避免运行时再拖一个 .so。pyzmq 26.2.0 + libzmq 4.3.5，**源码零 patch**，真机 PUSH/PULL socket 往返通过。
+
+## 为什么设备端原生编译走不通
+
+设备 HNP bin 里虽有 `clang` wrapper，但它指向 **未安装的 ohos-sdk HNP**（`/data/service/hnp/ohos-sdk.org/ohos-sdk_26.0.0.18/.../clang-15` inaccessible）→ 设备上 `pip install pyzmq`（源码包）必然失败。**一切 C/C++ 交叉编译都在 Mac 用 DevEco NDK 做**。
+
+## 三段式
+
+1. **CMake 交叉编译 libzmq 静态库**（同 cpprestsdk 的 CMake 套路）：
+   ```bash
+   cmake -S libzmq -B build-ohos -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/ohos.toolchain.cmake \
+     -DOHOS_ARCH=arm64-v8a -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
+     -DBUILD_SHARED=OFF -DBUILD_STATIC=ON -DBUILD_TESTS=OFF \
+     -DENABLE_DRAFTS=OFF -DENABLE_CURVE=OFF -DWITH_TLS=OFF -DWITH_LIBSODIUM=OFF
+   ```
+   - **E103**：libzmq 的 `cmake_minimum_required` < 3.5，新 CMake 直接拒。加 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`（比 patch CMakeLists 更省）。
+   - 关掉 CURVE/TLS/libsodium，免得再拖加密依赖；只要 socket 基础能力。
+2. **cythonize**：pyzmq 26 用 Cython **纯 py 模式**，后端是单模块 `zmq/backend/cython/_zmq.py`(+`.pxd`)。`cython -3 --include-dir <src根>` 让 `zmq/...` 的 pxd 能解析。
+3. **交叉编译 + 静态链接**：
+   ```bash
+   aarch64-unknown-linux-ohos-clang++ -fPIC -shared -I<py> -I<libzmq>/include \
+     _zmq.c <libzmq-install>/lib/libzmq.a -lpython3.12 -o _zmq.cpython-312.so
+   ```
+   - **必须用 clang++**（不是 clang）：libzmq 是 C++，链接器要带 C++ 运行时。
+   - NEEDED 会含 **`libc++_shared.so`**——设备自带（见 [[鸿蒙PC-C++库交叉编译要点]]），不用额外推。
+   - libzmq 静态链入后，扩展运行时只依赖 libpython/libc++_shared/libc，无额外 .so。
+
+## 部署
+
+整个 `zmq/` 纯 py 包 + 编好的 `_zmq.cpython-312.so` 一起进 site-packages（设备 site-packages 可写）。验证：`import zmq; zmq.zmq_version()` + 一个 inproc PUSH/PULL 往返。
+
+## 适用面
+
+任何"Cython/C 扩展 + 依赖某个 native C/C++ 库"的 Python 包都套这个三段式（lxml→libxml2、cryptography→openssl 已预装可跳过、pyzmq→libzmq）。native 库优先 CMake 交叉编译成**静态库**再链入，运行时最干净。
+
+是 [[鸿蒙PC-ipykernel-Jupyter内核]] 的关键依赖。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-systeminformation-/345/271/263/345/217/260/345/210/206/346/224/257.md

@@ -0,0 +1,33 @@
+---
+name: 鸿蒙PC-systeminformation-平台分支
+description: 适配靠 process.platform 分支 + 系统命令/proc 取信息的纯 JS 库（systeminformation）到鸿蒙PC 的套路
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+systeminformation 5.31.7（零依赖纯 JS，靠子进程调系统命令 + 读 /proc /sys 取硬件信息）。这类库**编译零问题**，难点全在**运行时平台判断 + 命令兼容**。核心套路：把 `openharmony` 当 linux，再逐个修 toybox 命令差异。13 个主函数真机全部可用。是 [[鸿蒙PC-纯JS库部署到HNP-node]] 的进阶（那个零改动，这个要改平台分支）。
+
+## 坑 1（必发）：process.platform === 'openharmony' 不被识别为 linux
+
+systeminformation 每个模块都有 `const _linux = _platform === 'linux' || _platform === 'android'`。设备 node 的 `process.platform === 'openharmony'`（见 [[鸿蒙PC-纯JS库部署到HNP-node]]）→ `_linux` 全 false → 所有 Linux 分支跳过 → **函数返回空对象/默认值，但不报错**（最隐蔽，容易误判"跑通了"）。
+修：17 个文件的 `_linux` 赋值统一加 `|| _platform === 'openharmony'`。鸿蒙内核 Linux 兼容（/proc、/sys、toybox），当 linux 处理是对的。
+**通用规律**：任何按 `process.platform === 'linux'` 分支的 Node 库，移植鸿蒙都要补 `openharmony` 分支——优先 grep `process.platform` / `=== 'linux'` 把分支点全找出来。
+
+## 坑 2：toybox 命令缺 GNU flag（以 df 为例）
+
+设备 coreutils 是 **toybox**，flag 子集比 GNU 小。systeminformation 的 fsSize 用 `df -kPTx squashfs`，但 **toybox df 不支持 `-T`（类型列）和 `-x`**（`df: Unknown option`）→ fsSize 返回 0 mounts。
+修（filesystem.js 单开 `_ohos` 分支）：
+- 命令换成 `df -kP`（toybox 支持 `-aHhikP -t TYPE`），输出 5 列（无类型列，布局同 macOS）。
+- 文件系统**类型从 `/proc/mounts` 取**（`fs -> type` 映射），该库本就读 /proc/mounts 做 rw 检测，顺手建映射。
+- parseDf 的列解析：6 列（GNU `-T`）vs 5 列（toybox）要分开，引入 `_col6 = (_linux && !_ohos) || _freebsd...`。
+**通用规律**：库调系统命令报"Unknown option / 返回空"时，先 `<cmd> --help` 看 toybox 支持哪些 flag，降级到子集 + 必要时改解析。
+
+## 平台固有限制（非 bug，记下别白费劲）
+
+设备缺 `lscpu` / `dmidecode` / `who` / `/etc/os-release` / `getprop`(hdc root 不可达) → cpu manufacturer/brand、osInfo distro、baseboard、users 拿不全/为空。这是平台没暴露这些信息源，不是适配缺陷。**核心指标全对**：CPU 核数(20)/频率/负载、内存(33GB)、磁盘(fsSize 23 挂载)、网络流量、进程数、机型(HUAWEI KIRINX90，走 /sys)。
+
+## 验证要点
+
+纯 JS 库"不报错"≠"取到数据"——必须**逐函数看返回值是否非空且合理**（写个遍历所有 API 打印摘要的 device-test.js），否则坑 1 那种静默返回空会被漏掉。
+

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-usbredir-USB/351/207/215/345/256/232/345/220/221/345/267/245/345/205/267/351/231/215/347/272/247/351/200/202/351/205/215.md

@@ -0,0 +1,137 @@
+# 适配经验：usbredir 0.15.0 — USB 重定向工具降级适配
+
+## 摘要
+
+usbredir 是 SPICE 协议的 USB 重定向实现，包含三个组件：
+- `libusbredirparser`（纯 C 协议解析库，无外部依赖）
+- `libusbredirhost`（主机端库，依赖 libusb-1.0）
+- `usbredirect`（CLI 工具，依赖 libusb-1.0 + glib/glib/glib）
+
+适配验证时，`usbredirect` 的 `main()` 在 `parse_opts()` **之前**调用 `libusb_init(NULL)`，导致在 HAP 应用域（USB 设备访问不可达）下所有功能——包括 CLI 参数解析、TCP 连接/监听、设备标识格式校验——全部被阻塞。
+
+## 方案：降级重构
+
+### 问题文件
+
+`source/tools/usbredirect.c` 的 `main()` 函数。
+
+### 原始流程
+
+```
+main() {
+    ① libusb_init(NULL)              ← 失败即 exit(1)
+    ② parse_opts(&argc, &argv)       ← 永远走不到
+    ③ open_usb_device()
+    ④ usbredirhost_open_full()
+    ⑤ TCP 客户端/服务端模式
+    ⑥ g_main_loop_run()
+}
+```
+
+### 改造后流程
+
+```
+main() {
+    ① parse_opts(&argc, &argv)       ← 先解析 CLI（设备标识/地址/端口）
+    ② libusb_init(NULL)              ← 非致命，设 have_usb 标志
+    ③ if (have_usb) { USB 初始化 }   ← 用标志守卫
+    ④ TCP 客户端/服务端模式          ← 不依赖 USB，照常执行
+    ⑤ g_main_loop_run()
+}
+```
+
+### 修改点
+
+| 修改 | 位置 | 说明 |
+|------|------|------|
+| `parse_opts()` 提前 | main() 开始处 | 设备标识解析、TCP 地址/端口解析不再被 USB 阻塞 |
+| `libusb_init` 非致命 | main() 第 2 步 | 失败时设 `have_usb=FALSE`，走降级模式 |
+| `if (have_usb)` 守卫 | 全部 USB 依赖段 | log_cb、open_usb_device、event_thread、usbredirhost_open、log level、event 清理、end/err_init 清理 |
+| `create_watch` 守卫 | TCP 客户端模式 | 无 USB 时不安装 IO 回调（usbredirhost 为空） |
+| NULL 守卫 | `update_watch()` | 无 usbredirhost 时直接返回 |
+| NULL 守卫 | `connection_handle_io_cb()` | 无 usbredirhost 时跳过 USB 读写 |
+| 成功日志 | TCP 客户端连接后 | `g_message("Connected to server %s:%d")` |
+| 成功日志 | TCP 服务端监听后 | `g_message("Listening on %s:%d")` |
+
+### 补丁文件
+
+```
+patches/0003-usbredirect-degrade-libusb-init.patch
+```
+
+## 验证结果
+
+### 编译
+
+交叉编译零告警零错误（`-Werror` 下）：
+
+```
+ninja -C build/_build tools/usbredirect
+```
+
+### 降级模式下各路径行为
+
+| 用例 | 路径 | 改造前 | 改造后 |
+|------|------|--------|--------|
+| F-04-01 step2（不可达服务器） | TCP 客户端连接失败 | 死在 libusb_init | **√ 真正走到 TCP connect 失败分支，非零退出码 + 正确错误信息** |
+| F-04-02 step2（端口被占用） | TCP 服务端绑定失败 | 死在 libusb_init | **√ 真正走到 bind 失败分支，非零退出码 + 正确错误信息** |
+| F-04-03 step3（非法设备标识） | parse_opts 拒绝 | 死在 libusb_init | **√ parse_opts 直接返回 NULL → exit 1 + "Failed to parse device"** |
+| F-04-03 step1/2（合法设备标识） | parse_opts 接受 | 死在 libusb_init | **√ 通过 parse_opts 校验，不再误报 libusb 错误** |
+| F-04-01 step1（可达服务器） | TCP 客户端连接成功 | 不可达 | **√ 建立 TCP 连接 + 打印成功日志 + 进程驻留 main_loop** |
+| F-04-02 step1（空闲端口监听） | TCP 服务端监听成功 | 不可达 | **√ 监听成功 + 打印成功日志 + 进程驻留 main_loop** |
+
+## 后续遗留
+
+1. **F-04 用例接线**：`test-demo/cli-runner/entry/src/main/cpp/napi_stub.cpp` 的 kCases[] 表需填 + `test-demo/cases.json` 的 F-04 需切到 cli-runner 通道
+2. **TCP 对端**：F-04-01 成功路径需要可达的 TCP 监听端
+3. **成功路径看门狗**：`main_loop` 驻留行为需测试侧用 alarm(90) 或 SIGTERM 结束后检查日志
+4. **F-03 仍受 usb-host 能力域限制**：usbredirhost 功能（libusb_init 返回 -99）无法绕过，需签名 HAP + USB DDK 授权
+## 库级 API 语义（真机 test-demo 实证，24/24 用例通过）
+
+无 USB 硬件的鸿蒙 PC 上，libusbredirparser/libusbredirhost 的可验证语义与两个平台事实：
+
+1. **协议方向性静默丢弃**：`usbredirparser_send_*` 反方向发送（如 guest 解析器发 device_disconnect）在 `usbredirparser_queue` 里静默 return——不入队、无返回码。host→guest 命令的用例必须给解析器加 `usbredirparser_fl_usb_host`。
+2. **报文头长度随能力协商变化**：device_connect 的 type header 在双方协商 `usb_redir_cap_connect_device_version` 后为 10 字节（否则 8）；测试向量构造报文用 `sizeof(结构体)`，勿写魔数。**读侧同理**：本地未声明 `usb_redir_cap_64bits_ids` 时写出的是 12 字节（32-bit id）头，按 `sizeof(usb_redir_header)`（16 字节）读会让 id 字段错位、报文内容断言全错——测试 setup 先 `usbredirparser_caps_set_cap(caps, usb_redir_cap_64bits_ids)` 与生产路径对齐。
+3. **`usbredirfilter_string_to_rules("")` 返回 0（0 条规则）**，不是 -EINVAL——空串在上游是合法的「无规则」。
+4. **降级 host（`usbredirhost_open` 传 NULL 句柄）上 `usb_redir_reset` 是 no-op**：`usbredirhost_reset` 入口 `if (host->disconnected || host->reset) return;`，`usbredirhost_read_device_lost(-4)` 路径需真实设备 reset 失败才可达。
+5. **conan libusb 1.0.27（libusb-1.0.so.0.4.0，OHOS 交叉编译）对 `libusb_get_device_descriptor(NULL, ...)` 无空指针守卫**：`usbredirhost_check_device_filter(rules, n, NULL, 0)` 直接 `SIGSEGV(SEGV_MAPERR)@0x8`（faultlogger 实证）。头文件注释承诺的 -EIO/-ENOMEM 仅在 libusb 带 NULL 守卫的构建上成立。做 NULL 入参观测必须 fork 子进程隔离，且 waitpid 用 WNOHANG + ~1.2s 时限 + SIGKILL 兜底（子进程崩溃后 processdump 对孤儿态转储可无限期挂起，阻塞 waitpid 实测 121s）。
+
+用例级细节与修法见 `pc-test-design/references/c-lib-upstream-semantics-checklist.md` 的修复对照表。
+
+## 测试线缺陷修复：F-04-01 假绿 + 执行中再点按钮 ANR（2026-09-16）
+
+`test-demo`（cpp-lib-demo，bundle com.ohpt.usbredir.test_demo）真机 24/24 pass 后，用户手测发现两个机器验收（autoRun + hilog 结果行判定）无法覆盖的缺陷。
+
+### 缺陷 A：F-04-01 非法参数退出码未打印（假绿）
+
+**现象**：第 3 步「非法设备标识 → stderr 报错且以非零退出码退出」显示 `actual=zero-but-err` 但 `ok=1 / result=pass`，结果行只打 `rc=0`，非零退出码从未出现。
+
+**根因**（两层）：
+1. **断言弱化**：`napi_stub.cpp` 写成 `(rc != 0 || cap.find("error") != string::npos)`——把「报错 **且** 非零退出」的 AND 契约弱化为 OR，rc=0 但输出含 error 即判过；
+2. **黑盒 helper 吞 rc**：`f04-01-client` helpers（源码不在工作区，是 test-demo-cli 轮遗留的黑盒二进制）只回整体 rc=0，usbredirect 每步的真实退出码在链路上被吞掉。
+
+**修复**：弃用黑盒 helper，`run_redirect_step` 每步独立 fork/exec usbredirect、分管捕获 stdout/stderr；cp 断言收紧为 AND（该步 rc != 0 **且** stderr 含错误提示）；步骤真实退出码打进 check 行 actual 与结果行 detail。实测被测物本身无缺陷——`usbredirect 0123:GHIJ` 真实退出码 rc=1，纯链路问题。
+
+### 缺陷 B：执行中再点按钮 →「应用未响应」ANR
+
+**现象**：用例页执行过程中再次点击「执行本用例」，demo 弹「应用未响应」对话框。
+
+**根因**：`OhptCaseRunner.ets` 在 ArkTS 主线程同步调 `demo.callCase`（NAPI 同步入口），native 侧含 fork/exec + waitpid/usleep 轮询（exec_capture 超时上限 30s）。执行期主线程被阻塞，第二次点击的输入事件排队超时 → 系统看门狗弹 ANR。页面层已有 running 守卫 + `enabled(!running)`，但主线程阻塞时守卫来不及生效。
+
+**修复**：native 侧改 `napi_async_work` + Promise，主线程只做 Promise 派发；OHPTCASE hilog 行仍由 `run_case` 单点发出（时序不变，日志 tid 变为 worker 线程）。冒烟：执行中用 `uitest uiInput click` 注入两次按钮点击 → 仅一轮结果、无排队重跑、ANR 行 0、进程存活。
+
+### 红线总结（已沉淀到 pc-test-design/references/anti-fake-checklist.md §9 与 demo-wiring-pc.md §4）
+1. 多步 CLI 用例禁止用包装器整体 rc 顶替单步 rc，每步独立捕获真实退出码；
+2. 错误契约断言禁止用 OR 弱化 AND（按上游契约原语义）；收紧后发现被测物缺陷不许改断言迁就，必须先实测确认；
+3. NAPI 壳/ArkTS 驱动档禁止主线程同步调 native 跑用例——必须异步（napi_async_work / Worker），否则执行中点按钮 ANR。
+
+## 第二轮复跑（2026-09-17）：终态从 partial 收敛到 success 的四条增量
+
+同一库、同一设备、同一条 B-01（app 域无 /dev/bus/usb），首轮判 partial、次轮判 success——分野不在平台，在判定口径与用例设计：
+
+1. **partial 能力域的硬件路径必须显式进 `prd.scope_out`**（本轮补登「usbredirhost 物理 USB I/O 待 DDK 桥接」+「usbredirtestclient 非交付物」）。scope_out 留空时同一路径算「该覆盖没覆盖」→ `target_path_covered=partial` → 终态 partial；收编后算「范围外」→ covered → success。验收规则 `scope-out-coverage-consistent` 已把「二选一」机器化。
+2. **host 库用例不要挂在 `libusb_init` 上**：app 域 `libusb_init(NULL)` 实测返回 **-99**（非标准枚举值），但 `usbredirhost_open(NULL, NULL)` 直接成功——open_full 对空设备引用走降级路径，hello/读写/断开由 parser 持有，全部可判。首轮 F-02 五条因 init 门控全 blocked，改走降级构造后全 pass（glib g_test 二进制同理：init 失败 `g_test_skip`，勿 `g_test_fail`）。
+3. **CLI 用例可以不起第二个工程**：把 usbredirect + glib/libusb 依赖打进 cpp-lib-demo 自己的私有 HNP（`module.json5` 的 `hnpPackages` type=private + 构建脚本 zip 注入 `hnp/arm64-v8a/`），native 侧 `fork/execv("/data/app/bin/usbredirect")` 直跑——与库用例同一次 run-all 完成。细则已沉淀到 demo-wiring-pc.md §4「混合载体」。
+4. **run-all 页判定别扫「失败」字样**：预期/实际文本里的叙事词（「返回解析失败且不崩溃」「连接失败」）会被误判 fail 并打第二条结果行，fail>pass 合并后毒化真结果（首轮重跑 18/21 的 3 条 fail 全属此类）。判据要用 native 报告的 √/× 结构行——模板已修（scaffold-pages.ts，与用例页同源）。
+
+本轮结果：05 重设计 8 条（F-02 降级路径 + F-04 降级模式 CLI）→ 06 一次 run-all **21/21 pass**，`adaptation_status=success`、测试终态「测试通过」。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-/345/233/276/345/203/217/345/244/204/347/220/206/345/272/223-CImg/345/233/276/345/203/217/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,109 @@
+---
+name: 鸿蒙PC-图像处理库-CImg图像库交叉编译
+description: >-
+  某图像库（CImg 家族的图像处理库 + CLI）交叉编译到鸿蒙 PC 的完整实证。
+  覆盖：Windows 宿主 + OHOS NDK clang + CMake(Ninja) 交叉编译骨架；pkg-config 缺失处理
+  （PkgConfig REQUIRED→QUIET + 可选依赖裁剪）；CImg 头文件版本锁（conan cimg/3.6.6 API 不兼容，
+  须用与 某图像库_version 匹配的 GitHub master CImg.h）；cimg_display=0 禁 X11 显示后端；
+  conan libz.a 静态链入规避 NDK sysroot 桩库；OpenMP 禁用 + pthread 兜底保运行时依赖面最小；
+  Windows 宿主大文件下载用 BITS（Start-BitsTransfer）替代 curl；conan 多依赖 zlib 版本冲突的
+  处置（统一版本或跳过非 REQUIRED 可选依赖）。构建侧全闭环、可复现（build/recipes/ohos-cross.sh），
+  设备侧验证因设备掉线未跑（proceed-degraded 降级收尾，adaptation_status=partial）。
+  触发词：某图像库、某图像库、CImg、lib某图像库、cimg_display、图像处理库、CMake 交叉编译、PkgConfig QUIET、
+  zlib 桩库、静态链 zlib、conan 版本冲突、BITS 下载、Windows 宿主下载超时、OpenMP 禁用、pthread 并行兜底。
+metadata:
+  type: adaptation
+  source: 某图像库（2026-09-08 适配实证，GitHub GreycLab/某图像库）
+  delivery_form: cpp-lib（主）+ cli（副）
+  build_status: pass（设备验证未闭环 → partial）
+  relates_to: 鸿蒙PC-C++库交叉编译要点.md（NDK sysroot 桩库识别/CMAKE_FIND_ROOT_PATH）、
+    鸿蒙PC-Windows宿主构建环境四坑.md（pkg-config 缺失）、
+    pc-capability-domains graphical-window.md（cimg_display=0 降级实证）、
+    pc-error-atlas E140/E141/E142
+---
+# 鸿蒙 PC：某图像库（CImg 图像库）交叉编译
+
+某图像库 = 某图像库 图像处理框架（库 `lib某图像库` + CLI `某图像库`），CImg 头文件库家族。交付形态
+**cpp-lib（主）+ cli（副）**，策略=OHOS NDK clang aarch64-unknown-linux-ohos + CMake(Ninja) +
+`ohos.toolchain.cmake`。可复现脚本：`build/recipes/ohos-cross.sh`（工作区产物）。
+
+## 1. 构建骨架
+
+```bat
+set DEVECO_SDK_HOME=C:\Program Files\Huawei\DevEco Studio\sdk
+set NDK=%DEVECO_SDK_HOME%\default\openharmony\native
+cmake -S source -B build/ohos -G Ninja ^
+  -DCMAKE_TOOLCHAIN_FILE=%NDK%\build\cmake\ohos.toolchain.cmake ^
+  -DOHOS_ARCH=arm64-v8a -DCMAKE_BUILD_TYPE=Release ^
+  -DBUILD_LIB=ON -DBUILD_LIB_STATIC=ON -DBUILD_CLI=ON ^
+  -DCMAKE_DISABLE_FIND_PACKAGE_OpenMP=TRUE ^
+  -DZLIB_LIBRARY=<conan>/lib/libz.a -DZLIB_INCLUDE_DIR=<conan>/include ^
+  -DCMAKE_FIND_ROOT_PATH_MODE_INCLUDE=BOTH -DCMAKE_FIND_ROOT_PATH_MODE_LIBRARY=BOTH -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH
+ninja -C build/ohos
+```
+
+## 2. 关键改造与坑（均实证）
+
+### 2.1 pkg-config 缺失（Windows 宿主）→ E140
+`find_package(PkgConfig REQUIRED)` 直接配置失败。某图像库 的所有 `pkg_check_modules`
+（FFTW/CURL/X11）**全部针对可选依赖** → 改 `REQUIRED` 为 `QUIET` 即可让配置通过、
+对应功能自然裁剪；对非 REQUIRED 的 `find_package(PNG/JPEG/TIFF)` 保持原样。
+落地：`patches/0001-某图像库-ohos-cross-compile-adaptations.patch`。
+判别口诀：先核对每个 `pkg_check_modules` 是否都服务可选依赖，是才敢 QUIET。
+
+### 2.2 CImg 头文件版本锁 → E141
+conan 仓的 `cimg/3.6.6` 将 `t_magenta()/t_bold()/t_normal()` 定义为**常量而非函数**，
+与 某图像库_version 405 编译期不兼容（20+ 编译错）。**头文件数据族依赖必须与宿主库版本锁死**：
+CImg.h 从 GitHub master 拉（对应 某图像库 405），某图像库_stdlib_community.h 从
+`https://某图像库.eu/某图像库_stdlib_community405.h` 拉（8.15MB）。
+
+### 2.3 X11 显示后端 → E142 / cimg_display=0
+CImg.h 在非 Windows 平台默认 `#include <X11/Xlib.h>`，NDK sysroot 无 X11 → 编译失败。
+编译标志加 `-Dcimg_display=0` 显式禁显示后端（比靠探测不命中更稳）；某图像库 的 `display`
+命令在 某图像库.cpp:6557 有 cimg_display 可用性检查、禁用后自动报 unsupported；
+图像处理核心与 CLI 批处理完全不受影响。
+
+### 2.4 NDK sysroot 桩库 → 静态链 conan libz.a
+sysroot 内 `libz.so` 是桩（`llvm-nm -D` 全符号同址、运行时不可用）。某图像库 修法：
+conan 中心仓 `zlib/1.3.1.1` 的 `libz.a` 静态库，经 `-DZLIB_LIBRARY=<path>/libz.a`
+静态链入产物。最终 `lib某图像库.so` 运行时**仅依赖设备自带 libc++_shared.so + libc.so**，
+零额外运行时依赖（免去随包带设备库）。与「从设备 pull 真 libz」互为两条路：
+cpp-lib 不想随包时首选静态链入。
+
+### 2.5 OpenMP 禁用 + pthread 兜底
+设备无 libomp.so（在位性未确认）→ `-DCMAKE_DISABLE_FIND_PACKAGE_OpenMP=TRUE` 关闭探测，
+避免产物引入 libomp.so 运行时依赖；并行能力由库自带 pthread 兜底承接（某图像库.h:281-284
+`某图像库_is_parallel`）。适用：支持 pthread/OpenMP 双路并行的 C++ 库。
+
+### 2.6 conan 多依赖 zlib 版本冲突
+libpng 依赖 zlib/1.3.2、libtiff 依赖 zlib/1.3.1.1，无法同时安装（中心仓 hit ≠ 可安装）。
+可选依赖（find_package 非 REQUIRED）直接跳过：libpng/libjpeg/libtiff/fftw/libcurl 全 skipped，
+仅保留 zlib/1.3.1.1 + BMP 原生 I/O。**功能被裁剪时同步裁剪验证用例**（24 条全用 BMP），
+避免断言不存在的功能。
+
+### 2.7 Windows 宿主大文件下载用 BITS
+GitHub/某图像库.eu 直连超时（3.4MB CImg.h、8.15MB stdlib 头均失败），
+`Start-BitsTransfer -Source <url> -Destination <tmp>` 一次成功。
+
+## 3. 设备验证（未闭环，如实记录）
+
+24 条名册用例（17 库侧 + 7 CLI 侧）全部就绪（`tests-generated/`，库侧已交叉编译为
+aarch64-ohos ELF）但未跑：设备在构建期间断开 → `env-decision.json=proceed-degraded` 降级收尾，
+`03-adapt.json status=built-pending-verification`、verify-verdict verified=false（诚实未虚报）。
+补跑 runbook 见 `04-summary.json remaining_todos[]`：scaffold cpp-gui-owb-demo +
+cli-hnp-runner → sign-demo --install → hdc 推送 → 24 条逐条采集（取证前 `hilog -b D` 冷启动）。
+
+## 4. 可复用资产
+
+- `patches/0001-某图像库-ohos-cross-compile-adaptations.patch`：核心补丁（PkgConfig QUIET +
+  cimg_display=0），版本升级可 `git am` 复用。
+- `patches/0001-make-pkgconfig-optional.patch`：单点变体（仅 PkgConfig 一行），供其他 CMake 库参考。
+- `build/recipes/ohos-cross.sh` + `README.md`：全流程可复现脚本与 runbook。
+
+## 关联
+
+- [[鸿蒙PC-C++库交叉编译要点]] §6（桩库识别 llvm-nm -D）/ §8（CMAKE_FIND_ROOT_PATH）
+- [[鸿蒙PC-Windows宿主构建环境四坑]] 坑 5（pkg-config 缺失：meson 模拟器 + 本条 CMake QUIET 变体）
+- `pc-capability-domains` graphical-window（CImg 家族显示后端降级实证）
+- `pc-error-atlas` E140 / E141 / E142
+- `pc-registry` central-registry（hit ≠ 可安装：依赖树级验证）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-/345/256/277/344/270/273/346/227/240GNU-make/347/232/204/347/241/256/345/256/232/346/200/247/346/236/204/345/273/272/351/251/261/345/212/250.md

@@ -0,0 +1,61 @@
+# 鸿蒙 PC 宿主无 GNU make 的确定性构建驱动
+
+> **一句话**：宿主（尤其 Windows）没有 GNU make/WSL 时，别手工转译几百条命令、也别现场装环境——
+> 写一个**确定性构建驱动**（Python 脚本）解析上游 makefile 树（include/变量/ifdef/静态清单），
+> 复现其编译器档位语义、直接驱动 NDK clang，产物与 `make` 等价且可复现。
+
+## 什么时候撞上
+
+- 上游是**纯 makefile 工程**（无 CMake/meson 生成器）：GNU 风格 `.mak` include 树
+  （`makefile.gcc` + `var_*.mak` + `cmpl_*.mak`）、`Makefile` 变量覆盖式构建。
+- 宿主是 Windows（PowerShell + Git Bash）：Git Bash 不带 GNU make，装 make/开 WSL 会引入
+  环境漂移与新的不确定性（还有路径转换坑）。
+- makefile 型仓库的构建入口常在**子目录深处**（如 7zip 的 `CPP/7zip/`），且构建变量按
+  架构/编译器分文件组织——手抄命令极易漏一个条件分支。
+
+## 决策序（先穷尽更便宜的）
+
+1. 上游有没有别的官方构建入口（CMakeLists/meson/MSVC 工程）？→ 有就优先用（交叉编译骨干见
+   pc-knowledge-base「构建系统 → 鸿蒙调用方式」表）。
+2. 上游 makefile 是否**简单到**几十条规则、无 include 树？→ 直接手写等价命令清单进 build/ 脚本。
+3. 都不满足（include 树 + 变量矩阵 + 数百编译单元）→ 本文的**确定性构建驱动**。
+
+## 确定性构建驱动怎么做（7zip 26.02 实证）
+
+写一个 Python 脚本（放 `build/`，作为可复现交付物），职责四件事：
+
+1. **解析 makefile 树**：递归解析 `include`、变量赋值与展开（`$(VAR)`）、`ifdef/ifndef`、
+   静态对象清单（`OBJS = a.o b.o …` 的展开结果）。不追求通用 make 求值器——只求值**这个仓库
+   用到的子集**，遇到不认识的语法 fail-fast 而不是静默猜。**同一原则适用于脚本内嵌的替换式
+   补丁**：`if 'xxx' in line: line.replace(...)` 这类字符串替换，替换后必须复读断言目标串
+   真的变了（命中计数为 0 / 目标代码仍在 → 立即报错退出），不许静默继续。
+2. **变量注入交叉工具链**：`CC/CXX/AR` 指到 NDK clang/clang++/llvm-ar，复现上游
+   `cmpl_clang_arm64.mak`/`var_clang_arm64.mak` 的编译器档位语义（-march 见
+   platform/鸿蒙PC-aarch64指令档位与运行时分发.md）。上游 `-Werror` 系告警策略与 NDK clang
+   版本不匹配时整档降级（-Werror→-Wall -Wextra）并核验零告警，别零散压制（E063）。
+3. **直接驱动编译**：逐编译单元 `clang -c`（`.S` 汇编走 clang 集成汇编器）→ `llvm-ar` 归档 →
+   `clang++` 链接（`-Wl,--code-sign` 自签）。**源码零污染**：在临时区或全 out-of-tree 编，
+   `git -C source status --porcelain` 收尾必须干净（改动才配进 patches/）。
+4. **可复现性记账**：打印编译单元总数、逐单元日志、产物哈希；重跑输出逐字节一致。
+
+反模式（都实际发生过）：
+- ❌ 手抄 323 条编译命令——漏一个 `#ifdef` 分支，链接期才炸，排查一小时；
+- ❌ 替换式补丁不打命中断言——匹配条件要求行含 `ifdef` 而源码是 `#if defined(...)`，替换
+  静默未命中，后续全部诊断都建立在「补丁已生效」的假象上（libbsd 实证：两轮排障白烧）；
+- ❌ 现场装 make / 切 WSL——环境漂移引入新变量，构建失败原因从「配置错」变成「环境错」；
+- ❌ 拿驱动脚本去改上游源码文件（生成 config.h 之类）——必须写进临时区，`source/` 保持锁定
+  commit 的原始状态。
+
+## 交付物形态
+
+- `build/build-<lib>-ohos.py`：驱动脚本本体（进最小交付包，社区使用者重建产物靠它）；
+- `build/build-<lib>-ohos.log`（或 notes 里记录）：编译单元数与关键变量取值——验收对账用。
+
+## 实证案例（7zip 26.02）
+
+- 触发：宿主 Windows 无 GNU make/WSL；上游为 `CPP/7zip/Bundles/Alone2` + `makefile.gcc` +
+  `7zip_gcc.mak` + `cmpl_clang_arm64.mak` include 树，323 个编译单元（含 ARM64 LZMA 汇编
+  `LzmaDecOpt.S`）。
+- 结果：迷你 make 求值器（include/ifdef/静态清单求值）+ 变量注入复现 clang arm64 档位语义，
+  323 单元零告警编通；`source/` 全程 pristine（git status clean）；真机 39/39 名册用例通过。
+- 同型适用：任何「无生成器、变量矩阵复杂、编译单元数百」的 makefile 型 C/C++ 上游。