一、移植失败的两种典型死法

先看两个反面教材，它们正是「逐行照抄」的两种结局：

1. 逻辑对、UI 不动（Coverflow 的教训）：距离公式、zIndex、无限循环取模，这些数学原样搬过来毫无问题；但 Flutter 的「父级算完 layout 塞进 Stack」在 ArkUI 里不成立——ForEach 复用节点不重绑 transform，于是「debug 文案对、卡片冻住」。

2. 效果像、但卡死（BorderBeam 的教训）：Web 的 filter: blur(8~22px) 是 GPU 一次糊整层，ArkUI 没有等价物，于是用「多层 radial soft fill」硬模拟 → 150~250 fills/帧 → 真机极卡。

这两种死法的共同点：没有区分「什么能搬、什么必须重做」。 方法论的价值，就是提前把这条界线划清楚。

---

二、核心原则的三个层次

2.1 「保留行为契约与数学结构」——什么原样搬

数学和契约，是可以（也应该）原样搬的。

组件	原样搬的「数学/契约」
FlowAvatar	FNV-1a 哈希 + xorshift PRNG + 六态速度倍率
Coverflow	距离公式、zIndex、无限循环双取模、snap
ThinkingOrbs	六态引擎（orbits/globe/rubik/wave/ribbon/morph）
GrokBot	25 表情 × 48 点、球面投影、弹簧
MetalFx	snoise/fbm/palette 的 GLSL shader

这些是「纯函数」，不依赖任何平台。所以能做成可单测的 Core。

为什么要「保留」而不是「重写」？ 因为「和上游行为一致」是一个可验证的目标——前提是你能用单测锁定它。FlowAvatar 的 fixture 测试就是最典型的例子：

expect(flowAvatarSeed('user@example.com')).assertEqual(2085630174);  // 和 Flutter 逐值对齐

这行测试就是「契约保留」的锚点。有了它，你才敢说「我搬对了」。

2.2 「替换平台基础设施」——什么必须重做

依赖平台能力的部分，必须换成 ArkUI 的等价物（或重做）。 这是移植里最花时间、也最需要「真机经验」的部分。

Flutter/Web 的能力	ArkUI 的替换/重做
CustomPainter + radial gradient	CanvasRenderingContext2D.createRadialGradient
AnimationController 0→1 repeat	连续相位（phase += dt·ω），见 FlowAvatar 篇
PageView 手势双层	全表面 onTouch（主轴上 windowX/Y）
Matrix4 + rad	.rotate + 度 + perspective 距离
clipOval / clipRRect	容器 borderRadius + clip(true)
CSS mask-composite / @property / filter: blur	Canvas destination-out/destination-in/createConicGradient 或 下沉 Native GPU
performance.now + rAF	Date.now + DisplaySync
IntersectionObserver	onVisibleAreaChange

关键判断：一行 Flutter/Web 代码，你要是问「它依赖的是平台的什么能力？」——

• 答案是「数学/纯逻辑」→ 原样搬（进 Core）。

• 答案是「渲染/handshake/CSS/GPU」→ 替换（重做）。

BorderBeam 的移植原则后半句写得很直白：

「像 blur」的观感与「少 fill」的帧率在当前实现路径上冲突——封板时优先可运行性，并记录冲突本身为 Finding。

这句话点破了「替换平台基础设施」的终极形态：有些 Web 能力在 ArkUI 上没有廉价等价物，替换会带来不可调和的成本冲突，这时「诚实记录冲突+封板」本身也是方法论的一部分。（更进一步，MetalFx 证明：当 Canvas 替换不动时，下沉 Native GPU 才是正解。）

2.3 「设备观感优先于源码同构」——什么必须真机重标定

参数常数不能照抄，要在真机上重新标定。

Coverflow 的实验文档里有最直接的一张表：

	Flutter	ArkUI
skew	rad（如 -0.35）	度（如 -20）
perspective	Matrix4 m[3][2] 小数	.rotate 观察距离（默认 480，↓ 更强）

同一个「-0.35」的 skew，在 Flutter 是弧度、在 ArkUI 是度，直接抄会歪到天上去。而 perspective 在 Flutter 是一个矩阵元素，在 ArkUI 是「相机距离」，语义完全不同，只能真机试出「480 这个值看起来 3D 感刚好」。

核心原则：数学结构可以搬，但常数（角度、间距、速度、模糊半径）必须真机标定，因为它们是「和具体渲染管线绑定的」。

---

三、为什么要「Pin 上游」？

这个项目几乎每个移植组件的文档里，都有一行「上游 pin SHA」：

thinking-orbs:  pin eda2d708（2026-07-21）
metal-fx:       pin be1bf89c
border-beam:    pin 50ebc240
flow_avatar:    pub 0.2.1
coverflow:      Flutter 2.0.1

Pin 上游有三个理由：

1. 可复现：上游更新后如果行为变了，你的「契约对齐」会失效；pin 住 commit，才能保证「我搬的是这个版本」。

2. 可追溯：出了问题能回上游对应 commit 查。

3. 合规：保留 MIT/BSD 的 license 和出处（项目里每个移植文件头部都有 Port of ... (MIT) 注释）。

这是「专业移植」和「抄代码」的分水岭——前者 pin 上游、留 license、写差异文档；后者直接复制粘贴。

---

四、移植的标准流程（可直接套用）

把方法论落地成一个可操作的流程：

1. Pin 上游（记录 commit + license）
        ↓
2. 拆「纯逻辑」vs「平台依赖」
   ├── 数学/契约 → 进 Core（纯函数）
   └── 渲染/手势/时钟 → 替换为 ArkUI 等价物
        ↓
3. Core 先写单测（锁定上游 fixture / 数学不变量）
        ↓
4. 接 Painter（一层，翻译数据为 Canvas 指令）
        ↓
5. 接 Component（生命周期 + DisplaySync/setInterval）
        ↓
6. 真机重标定常数（角度/间距/速度/模糊）
        ↓
7. 写差异文档（移植原则、替换了什么、改了什么常数、为什么）

每一步对应前面的方法论：

• 第 1 步 = Pin 上游

• 第 2~5 步 = 保留契约 + 替换平台（就是「分层范式」那篇的四层）

• 第 6 步 = 设备观感优先

• 第 7 步 = 诚实记录差异（FlowAvatar 的「连续相位是对上游 loop 模型的有意改进，不是疏漏」就是范本）

---

五、三个真实案例速览

5.1 FlowAvatar：契约对齐 + 有意改进

• 保留：FNV-1a 哈希 + xorshift PRNG（逐值对齐 Flutter fixture）。

• 改进：把上游的 AnimationController 0→1 loop 换成「连续相位」，因为多频率正弦叠加在 loop 边界会接缝跳变。文档明确写「这是有意改进，不是疏漏」——这就是「允许重构」的体现。

5.2 Coverflow：数学可搬，渲染必须重做

• 保留：距离公式、zIndex、无限循环取模（纯函数，可单测）。

• 重做：渲染绑定（Flutter 的父级 layout → ArkUI 的 CardNode @Watch → @State geo*）、手势源（PageView 双层 → 全表面 onTouch）、帧动画（ticker → createAnimator）。

5.3 BorderBeam → MetalFx：替换到「换路线」

• BorderBeam 证明：CSS filter: blur 用 Canvas soft fill 替换 → 冲突，封板。

• MetalFx 证明：同样的 blur/噪波，下沉 Native GPU（XComponent + EGL/GLES3 + shader）→ 编译链打通。

这两个连起来是方法论里最深刻的一课：「替换平台基础设施」本身也分层次——Canvas 替换不动时，还有 Native GPU 这一层。

---

六、一句话判断表

移植时，对每一行上游代码，问自己一句话，然后归类：

问句	归到
「它算的是什么数学？」	原样搬进 Core（可单测）
「它依赖什么平台能力？」	替换成 ArkUI 等价物
「这个常数是多少、单位是什么？」	真机重标定
「它和上游哪个版本对齐？」	Pin 上游

---

七、总结

「移植」这件事，表面是「把代码搬过来」，本质是一次对「平台差异」的系统性识别。这套方法论的价值，就是把这种识别从「凭感觉」变成「有流程」：

数学和契约原样搬，用单测锁定。
平台基础设施逐项替换，替换不动就换路线（甚至下沉 Native）。
参数常数真机重标定，别抄单位。
Pin 上游、留 license、写差异文档——这是专业移植的底线。

当你下次再被要求「把那个 Flutter/Web 组件搬到鸿蒙」，别急着打开源码抄。先 pin 上游，再按「纯逻辑 / 平台依赖 / 参数常数」三刀切开，然后才动手。你会发现，那些「看起来是 bug、其实是平台接入方式错了」的坑，大半会在动手前就被你避开。