hmharness 是一个开源的 HarmonyOS/OpenHarmony 开发智能体框架（MIT）：把工程创建、检查、构建、签名、安装、启动、日志读取和结果验证接成本地工具链，让 AI 不只是生成代码，还要用本机环境证明结果；自进化行为受审批、预算、canary 和回滚约束。它不是 DevEco Studio 的替代品，而是开发智能体和鸿蒙工具链之间的验证层。本文讲一个看起来不起眼、但把「能落地」砸实了的功能：KaihongOS 板端一键安装器。
为什么要在开发板上跑 AI 智能体
越来越多真实的鸿蒙设备开发发生在板端而不是 IDE 里：ssh 上一块 KaihongOS（OpenHarmony 5.0）的板子，在设备旁边让智能体读日志、跑工具链、验证结果。但板端环境给工具分发出了十道难题，我们一道一道踩了过去。
坑 1：板上没有 npm，也没有 Python
npm install -g 直接不可用。解法是 vendor 安装：hmharness 全部第一方包都是零第三方运行时依赖的官方 tarball，Node 核心模块下载、busybox tar 解包，全程不需要 npm。断网时回退内置已知良好版本，包清单动态发现。
坑 2-3：Node 藏在工具目录 + 根分区只读
裸 shell 敲 node 是 not found——安装器自己搜候选路径，启动器永远绝对路径调 Node。往 /usr/local/bin 写文件直接 EROFS——remount 读写、写入、再 remount 只读；有 dm-verity 的板走用户目录方案。
坑 4（最大的坑）：命名空间终端看不到 /usr
KaihongOS 上部分终端运行在独立 tmpfs 挂载命名空间：根目录是内存盘，根本没有 /usr。装在 /usr/local/bin 的启动器这类终端永远找不到。解法：启动器同装三位置，/system/bin 经 bind-mount 对两类终端都可见——唯一全覆盖的位置。诊断：对比 readlink /proc//ns/mnt 就知道谁和谁不在一个世界里。
一条命令做六件事
找到可用 Node、解析版本集、下载解包到可写分区（暂存→校验→原子切换，旧版保留备份）、三位置装启动器、装自愈层、首跑自动初始化。装完只剩一步：把密钥填进 config.json，然后 hmh tui（下图是六件事与最狠四坑的全景）。
自愈层：升级缺包的终结
起因是真实故障：安装器硬编码包清单滞后，每次自动升级后缺包崩溃（Cannot find package @hmharness/cognitive）。修复不只是动态发现：0.23.34 起发布流水线自动把 FALLBACK_PINS 兜底版本钉到每个发布版，断网安装也能拿到自洽版本集。十坑全部写进 docs/KAIHONGOS.md（156 行踩坑实录，每条附诊断命令）。
设计哲学
嵌入式环境的工具分发，不该假设「一个正常的 Linux」。不装全局依赖、不动系统包、断网也能装——这三个「不」比任何功能列表都更能说明一个工具是否真的下过板。
口径：板级安装器对应 npm @hmharness/cli 0.23.16 起（FALLBACK_PINS 自动同步 0.23.34）；实测 KaihongOS 5.0 · x86_64 · Node v24；与华为、开放原子、深开鸿无隶属关系。
GitHub：github.com/swsgbl/hmha…
