把纯 JS/TS 的 npm 库搬到 OpenHarmony/HarmonyOS,最后通常要产出一个能在 ArkTS 严格模式下编译的 HAR。真正容易出问题的不是语法改写,而是移植顺序和验证链:先查重、先让上游测试跑起来、编译报错逐条处理、差分对照分清哪些结论可信。下面以 fast-diff 为例,复盘 harmony-js-lib-port 这份 Skill 在实操中暴露的问题和修正。
一、先钉死移植目标:语义一致优先
harmony-js-lib-port 是一份写给 AI 编程助手的操作手册,但它约束的其实是人的流程。目标只有一句话:ArkTS 严格模式编得过,行为和上游一模一样;性能优化、新 API、示范界面都放到移植之后。这个顺序来自 jsonrepair 那次的教训:一边移植一边做优化,差分测试要同时兜住语义和性能,出问题很难定位。
Skill 把流程拆成六步:查重,固定上游版本,搭工程,先搭差分测试再改代码,逐个文件移植,最后过验证闸门。闸门就是每一步结束时必须通过的检查,过不了不往下走。HAR 是鸿蒙的静态库包;codelinter 是命令行代码检查工具;hdc 用来连接设备。
二、查重和工程准备
fast-diff 是在 ohpm 中心仓查重后选定的。ohpm 是鸿蒙三方库中心仓,类似 npm。check-ohpm.sh 会按精确包名和关键词同时搜索。compare-versions 和 ms 已经有人移植,fast-diff 和 diff-match-patch 搜不到;按 text diff 搜到的 diff 7.0.0 是另一个库 jsdiff 的移植,算法和 API 都不同,不算重复。
fast-diff 适合做验证样本:纯 JS 实现,Apache-2.0 许可证,自带测试,不依赖浏览器 DOM 和 Node 内置模块,整个库只有一个 1138 行文件。它按字符比对两段文本差异,Quill 编辑器的 delta 依赖它,算法来自 google-diff-match-patch。
工程脚手架也暴露过问题。scaffold.sh 负责一键生成工程骨架,但它先替换占位符、后复制差分测试模板,导致 prepare.mjs 里的 __HAR__ 没有被替换。问题不大,却说明脚本必须自己完整跑一遍,不能只写进 Skill 就算完成。
三、先让上游测试跑在移植代码上
Skill 要求先打通测试管道,再改语法。v1 默认上游测试用 vitest 或 jest 这类框架,改 import 就能接上;fast-diff 不是。它的测试是一个 398 行的 Node 脚本,用 CommonJS 的 require('./diff.js') 引入库,依赖 lodash 和 seedrandom,出错就 throw,全部通过时打印 Success!。它还会读取 diff.INSERT 这种挂在函数对象上的属性,并且每次运行都换随机种子。
接法只替换 require 那一行,测试文件其余部分不动;再用 DIFF_TARGET=upstream 让同一份测试先跑 npm 原包,证明管道本身没问题。diff-shim.cts 把移植版包一层,把 INSERT、DELETE、EQUAL 三个常量挂回去。这样后面差分再出红灯,就只可能是移植代码的问题。
四、编译策略:先直译,再按报错改
v1 的规则表要求把 var 改成 let、补类型、把正则字面量换成 new RegExp,还要求把嵌套函数改成私有类。实际操作中,两个内层函数没有使用任何外层变量,助手直接把它们挪到了模块顶层。第一次编译只报 4 条:三条 arkts-no-any-unknown 出在 new Array(v_length) 上,改成 new Array<number>(v_length) 即可;剩下一条是可空类型收窄,上游靠逻辑保证不会为空,但 TypeScript 推断不出来。
- // 改写后:分支一一对应,不用 as 和 !
- if (hm1 !== null && hm2 !== null) {
- hm = hm1[4].length > hm2[4].length ? hm1 : hm2;
- } else if (hm1 !== null) {
- hm = hm1;
- } else if (hm2 !== null) {
- hm = hm2;
- } else {
- return null;
- }
复制代码
改完再编译就过了。但带标签的代码块、往函数上挂属性的写法、把对象当布尔值用的写法,编译器都没有报错。于是又写了一个探针文件,把上游常见写法逐个放进去编译。被拒的有嵌套函数、var、索引签名、没声明类型的对象字面量、函数表达式、解构赋值,以及给函数挂函数类型的属性;正则字面量不在其中。v1 要求改正则字面量,是照旧资料写的,在现在的工具链上并不需要改。
所以第 4 步改成先直译、后按报错改。编译器没报的写法不要为了“看起来像 ArkTS”去改,每多改一处,就多一处要靠差分测试兜底。
codelinter 也不能替代编译。探针文件里明明有 11 处 ArkTS 语法错误,codelinter 却报 Errors:0,只提示 ForEach 缺 keyGenerator、启动图标太大。它不检查 ArkTS 语法,只能作为补充闸门。
五、差分对照要比较结果或异常
第一版差分测试写成 expect(port(a, b)).toEqual(upstream(a, b)),emoji 那一组当场栈溢出。调用栈全在移植版里,看起来像递归被改坏了。换成 run() 包住两边调用后才发现,npm 原包在同样输入上也栈溢出。
- type Outcome = { ok: true; out: unknown } | { ok: false; err: string }
- function run(f: () => unknown): Outcome {
- try { return { ok: true, out: f() } } catch (e) { return { ok: false, err: (e as Error).name + ': ' + (e as Error).message } }
- }
- // const want = run(() => upstream(a, b, c, cleanup))
- // expect(run(() => port(a, b, c, cleanup)), `case ${n}`).toEqual(want)
复制代码
根因在随机输入生成器。一个 emoji 在 JS 字符串里占两个 UTF-16 码元,生成器按码元切字符串,把 emoji 从中间切开,留下孤立代理项。fast-diff 假定输入是合法 Unicode 字符串,所以这不是移植 bug,而是上游遇到非法输入时的原有行为。Skill 里有一条规矩:不要顺手修上游的怪行为。移植版保持和上游一致,这个行为写进 README 的已知限制。
之后差分拆成两组。合法输入按完整字符切,要求输出完全一致,且原包一次都不能抛异常;专门按码元切的那组,只要求两边失败方式相同。5000 次调用里原包失败了 126 次,移植版在同样输入上也失败。
上游 test.js 换了 6 个随机种子各跑一次,都通过。它覆盖 7 组回归用例、两轮各 10000 次随机模糊测试、72 条光标用例,每条光标用例再派生 6 种变体,另外还有 emoji 用例和语义整理。原包差分用了 DNA 序列、带换行英文、emoji、中英混排四种字母表,每种 2500 对输入,cleanup 开关各跑一次,共 20000 次调用,结果逐项一致。
测试全绿还不够,还要确认它们真能抓到错。突变测试故意改坏两处:把语义整理里的 score >= bestScore 改成 >,以及删掉计算公共前缀时防止把 emoji 切成两半的那一步。两处都被测试抓到,改回去恢复全绿。这一步后来成为闸门 G4b。
六、调用方验证和设备边界
HAR 自己能编译,只能说明库内部合法;别的 ArkTS 模块按正常写法调用它行不行,是另一回事。编译生成的类型声明文件里,diff.INSERT 会变成 declare namespace diff { var INSERT: number };CursorInfo 这种联合类型参数,调用方传对象字面量时必须用导出的 interface 标注类型。因此又加了一个最小 entry 模块,把每个导出都调用一遍,diff.INSERT 也读一次。这一步成为闸门 G1b。
设备验证没做成。本机 HarmonyOS 7.0 模拟器一开始因 /dev/kvm 权限问题起不来;处理完能启动后,两次冷启动都在 72 秒左右出事:系统核心服务 foundation 崩溃,系统 panic 重启,hdc list targets 一直查不到设备。entry 里已经写好方舟上的自检:先在电脑上用 npm 原包对 400 条固定输入算好结果,打包进应用后逐条比对,再按上游 test.js 的规则校验 3000 次随机 diff。这段代码编译过了,但没在方舟运行时上跑过。所以文章里的“通过”,只限于电脑上的测试和编译层面,不能等同于 ArkTS 运行时验证。
七、这套方法能复用什么
v2 一共改了 11 处,完整清单在仓库的 references/changelog.md。最管用的是顺序:查重放在挑库阶段,差分管道放在第一次编译之前,编译一过马上知道行为对不对;不要顺手修上游,否则移植版和原包输出对不上,差分反而变红。
需要人判断的地方也不少:挑哪个库、栈溢出到底是生成器问题还是移植问题、diff.INSERT 留不留。这里选择保留 diff.INSERT 以保持 API 一致,同时另外导出 DIFF_INSERT 常量。包名定成 @lwcwam/fast-diff,还没发布到 ohpm,当前只能按本地路径引用。Skill 也只在两个纯算法库上用过,碰到依赖 Buffer、正则后行断言或大量动态属性的库,估计还要再改一轮。
仓库在 https://atomgit.com/lwcwam/fast-diff-arkts,Skill 位于 skills/harmony-js-lib-port 目录,每道闸门的命令和结果记录在 docs/VERIFY.md。 |