原版

Voltra · React Native (Expo)

Callstack 孵化的开源库。JSX → JSON → SwiftUI / Glance。
~32,500 行代码，分成 7 个 package、一个 Expo config plugin、一组原生 Module。

这条管线（保持不变）

// JS 端
<Voltra.VStack>
  <Voltra.Text>Order #42</Voltra.Text>
</Voltra.VStack>
    ↓
renderLiveActivityToString()
    ↓
'{"type":"VStack","children":[…]}'
    ↓  // 跨过 bridge
// 原生侧 (Swift / Kotlin)
VoltraParser.parse(json) → SwiftUI.View

这是关键洞察。Bridge 很薄， 上下其他东西全是共享的。

为什么能行

Voltra 的组件只用 createElement 和 hooks， 从来不用 ReactDOM、也不调任何平台特定 API。

renderLiveActivityToString() 走一遍 React element tree 序列化成 JSON。这棵 tree 的形状不在乎到底是谁的 createElement 生产的。

它解锁了什么

Layer 0 走 npm 100% 复用。 不 fork、不 wrap、不 shim。

// 在 Lynx .tsx 文件里:
import { Voltra } from '@use-voltra/ios'

<Voltra.VStack style={{ padding: '16px' }}>
  <Voltra.Text>Order #42</Voltra.Text>
</Voltra.VStack>
// → 遍历、序列化、原生解析 → SwiftUI ✨

这个组件

// Lynx 侧
<voltra-preview
  width="170"
  height="170"
  payload={renderWidgetToString(jsx)}
/>

原生注册

LynxUIRegister.register(
  "voltra-preview",
  VoltraPreviewHostView.self
)

它干什么

把 Voltra SwiftUI 渲染到 Lynx app 内部， 不在桌面、不在锁屏。让 Testing Grounds 的页面直接看到 SwiftUI 输出， 而不是 JSON dump。

iOS 上包了一个 UIHostingController、Android 上是 ComposeView， 订阅 Lynx 传来的 width 变化，Payload 变了就重新渲染 SwiftUI。

9 个 testing-ground 页面被改造 App 内看到真实 SwiftUI

4 份 PRD

为什么这么干

一个 user story 是 对 agent 友好的工作单元: 能塞进一个 context window，有明确的验收标准让 agent 自检。

commit 后缀里的 (US-XXX) 变成永久审计线索: git log --oneline | grep US-053 就能找到 Positioning Screen 的改造。

context drift 成本降到零，每个 story 都从 PRD 这条 ground truth 重新出发。

$ git log --oneline | grep 'US-0' | wc -l
       61

这 5 条原则

+ 翻译表

| Expo 写法     | Lynx 对应    |
| AsyncFunction(...)
        → @LynxMethod fun(... callback: Callback)
| requireNativeModule<T>
        → createModuleAdapter<T>(NativeModules…)
| sendEvent(name)
        → lynxContext.sendGlobalEvent("voltra:" + name)
| Platform.OS → __PLATFORM__ build constant

复利效应

一个新 agent 拿到一个新 story 时，它不需要再去发现 bridge 是怎么工作的。它读三样东西: CLAUDE.md、 LYNX_PORT.md、对应的 PRD 段落，然后产出符合架构的代码。

个人 CLAUDE.md 还另外记录了过去踩过的坑:

交接文件

.claude/ralph-loop.local.md

---
active: true
iteration: 6
max_iterations: 0     # 不设上限
started_at: "2026-04-26T13:19:56Z"
---

按照 tasks/prd-voltra-lynx-android.md 实现 Voltra
Lynx 的 Android port。JS bridge 层已经完成。
用 Sparkling 搭 Android host app，实现
VoltraLynxModule.kt，验证全部 5 个 Android demo
端到端能跑。严格遵守 LYNX_PORT.md 里的
架构原则。

Ralph 完成了什么

为什么这里能用

架构上的接缝在 iOS 端已经验证过。Android 是同一个问题， 只是换了一套词汇，正好是 可预测、可并行 的工作，这是 loop 风格 agent 最擅长的。

模式: 平台 A 用手做一遍把 harness 立起来，让 loop 帮你搬到平台 B。

这份 deck 自己用过的 agent

经济性

Anthropic 的 prompt cache TTL 是 5 分钟。 主线程睡超过 300 秒就意味着下一次要冷读全部 context，又慢又贵。

Sub-agent 不共享这套 cache，所以分发它们等于免费， 而且主线程在它们工作的时候也能继续走。

经验法则: 2 个及以上互相独立的任务 (没共享状态、没顺序依赖) 就该并行跑。

// 一个 message · 3 个 tool call
<Agent description="loc audit" />
<Agent description="narrative" />
<Bash command="find ..." />

skills/voltra/ · 17 份参考文档

Agent 在相关触发条件下加载 SKILL.md，需要时再深入读对应的子文档。 tribal knowledge → 写到文件里 → 可复用。

~/.claude/projects/.../memory/

按项目的 memory 目录，条目有类型: user、feedback、project、reference。

当一个 session 学到了某个持久结论 (比如 “iOS host 用的是 CocoaPods Lynx 3.7.0，不是内部模板”) 它就写一条 memory。下个 session 启动时读到。

结果是: 第四周的 session 直接继承了第一周的突破， 不用重新付一次代价。

memory/
├── MEMORY.md                # 索引
├── lynx-host-setup.md       # project 类型
├── css-gotchas.md           # reference 类型
└── react-alias-pattern.md   # reference 类型

原则 1

说不清解决什么问题的改动，就不该做

如果你说不出一个具体能复现的 bug，就别动。 “更 robust”、“更标准”都不是理由。

来源: vue-lynx 迁移里一次“更干净”的 path-resolve 重构， 引入了一个新的 pnpm symlink bug。

原则 2

不要机械照搬上游的模式

问自己: 这个模式依赖什么前提？我的环境满足那个前提吗？

来源: lynx-stack vs vue-lynx， 同一个模式但架构不一样，照搬过来不能用。

原则 3

不要凭感觉判断“这是已有问题”

先 git stash。如果错误在父 commit 上能复现，那是已有的。 否则: 是你引入的。

来源: 一个构建错误，被怪在上游头上， 其实就是当前正在验证的改动自己引入的。

原则 4

编译过 ≠ 能用。要走一遍用户路径。

pnpm build 绿 + pnpm test 绿 ≠ 可发布。 要把 example 跑通、npm pack 出来、把 app 真的打开。

来源: 一次迁移单测都过了， 但 example app 在 runtime 挂掉。