Skip to content

Aura 框架架构 ​

一句话:一份 Rust 代码 = 三端的业务内核,一份 ReactLynx 代码 = 三端的界面,原生壳只负责起引擎和转发消息。

细节用法不在这里重复,按主题跳:quickstart(上手)、rust-side(路由/Context)、 frontend-side(bridge-client/主题/i18n)、core-guide(内核教程)、 wifi-bridge(可选传输能力)、extraction-map(抽取来源)。


1. 核心思想(先看这四句) ​

  1. 业务用 Rust 写一次,三端共用:Android / iOS / 鸿蒙加载的是同一份 Rust 代码编出来的库, 路由、存储、网络、文件、解析全在里面。
  2. 界面用 Lynx 写一次,三端共用:ReactLynx 渲染,一套页面三端跑。
  3. 原生只做壳:壳不写业务,只做四件事——起引擎、装页面、转发调用、提供系统能力。
  4. 双向通信:JS ⇄ Rust(调用 / 事件)、Rust ⇄ 系统(能力 / 回调);壳是中间人,但不做判断。

1.1 「一套 Rust 做三端」具体怎么落地 ​

业务 crate(生成项目的 rust/)同时产出三种 crate-type:

toml
[lib]
crate-type = ["cdylib", "staticlib", "rlib"]
crate-type产物谁用
cdyliblib<name>.soAndroid / 鸿蒙(运行期加载)
staticliblib<name>.aiOS(系统不允许随便加载自带动态库,只能静态链接)
rlib普通 Rust 库本机 cargo test、桌面 dev server

三端加载的是同一个业务 crate,所以「同一个接口在三端行为一致」是结构保证的,不是靠人肉对齐。

入口符号是固定的,不随应用包名变化:

平台固定入口
AndroidJava_com_aura_runtime_NativeBridge_nativeInit / nativeDispatch / nativeIsReady
iOS / 鸿蒙aura_core_init / aura_core_dispatch / aura_core_free_string / aura_core_is_ready

业务 lib.rs 只需在末尾放导出宏(export_jni!() / export_c_abi!()), router 注册、初始化、JSON 分发都由框架包装好。

1.2 「原生只做壳」的边界 ​

壳该做壳不该做
引擎初始化(LynxEnv.init)、加载 bundle业务路由判断、业务文案、业务存储
把 JS 的 path + json 转给 Rust在 Kotlin/Swift/ArkTS 里拼业务参数
把 Rust 的请求转成系统调用在壳里做页面跳转决策
生命周期、权限、安全区、前台服务直接读写业务数据库 / 文件

判断标准很直接:BridgeModule.dispatch(path, params) 里看不到任何业务路径字符串, 它只做「转发 + 错误兜底」。

1.3 双向通信有四条边 ​

text
                    ┌────────────────── App 进程(三端一致)──────────────────┐
   JS 线程           │                                                        │
   ReactLynx 页面 ───┼──① dispatch(path, json)──▶ 原生桥 ──②──▶ Rust 业务内核   │
        ▲            │                             (JNI/C ABI/NAPI)   │        │
        └────────────┼──③ emit(event, payload) ◀───────┘             │        │
                     │                                                │        │
                     │   ④ 系统能力(外链/通知/日志/长时任务)◀─────────┘        │
                     └────────────────────────────────────────────────────────┘
                                         ▲  ⑤ 生命周期(init / 通知栏停止按钮)
                                         └──────────── 系统
边方向用途AndroidiOS鸿蒙
① 同步调用JS → Rust绝大多数业务请求NativeModules.Bridge.dispatch() → JNIC ABI aura_core_dispatchNAPI dispatch
② 异步调用JS → Rust耗时操作不卡 UIdispatchAsync(Kotlin 线程池)C ABI + 业务自起线程NAPI(同左)
③ 事件推送Rust → JS进度 / 状态广播JNI NativeBridge.onNativeEvent → Lynx sendGlobalEventAuraHost.emitnapi_threadsafe_function
④ 系统能力Rust → 系统外链、通知、日志、震动、长时任务JNI 静态方法AuraHost 函数指针NAPI threadsafe
⑤ 生命周期系统 → Rust传 dataDir、通知栏「停止传输」nativeInit / dispatch("/wifi/stop")aura_core_initNAPI init

要点:

  • 只有 ① 是同步返回的,其余都是单向或异步。所以 handler 里不能做秒级阻塞(用 ②,或先返回再 ③ 推送结果)。
  • ③④ 的共同难点是线程:Rust 可能在任何线程回调,JS/系统调用必须在「对的线程」上执行(见 §2)。
  • 业务代码只感知两件事:bridge.call(path, params)(①②)和 ctx.emit(event, payload)(③); 它不知道也不需要知道当前是 JNI 还是 C ABI。

1.4 为什么不是「三端各写一套原生」 ​

维度三端各写一套Aura
业务逻辑3 份,行为容易漂移1 份,三端共用
业务单测依赖真机 / 模拟器cargo test 直接跑
新增一个接口改 3 处 + 3 次联调加一个 #[route]
系统差异散落在各处收敛到 Platform trait
换 Lynx 版本 / 适配新系统3 套壳各改只改壳,不碰业务

2. 线程与进程模型 ​

打包后(App):Rust 和 Lynx 在同一个进程里,但不在同一线程。

执行体说明
JS / UI 线程调 dispatch 时会同步等待 Rust 返回;重活必须走 dispatchAsync
Rust 调用线程同步分发就在调用方线程上跑;异步分发用线程池
Rust 后台线程例如 wifi-bridge 的 HTTP 服务(自带 tokio runtime),或业务起的线程
系统主线程前台服务启停、通知、requestPermissions 等必须在主线程做的事

跨线程的两条铁律:

  1. Rust → JS:必须投递回 JS 线程。Android 由 Kotlin 侧(sendGlobalEvent)保证; 鸿蒙必须走 napi_threadsafe_function,不能直接 call JS 函数。
  2. Rust → 系统:Android 用 attach_current_thread 后调静态方法;需要 UI 线程的(如申请权限) 由 Kotlin 侧自己 runOnUiThread,Rust 不关心。

dev 模式(桌面):Rust 是独立进程(aura-dev-server,默认 3456),前端通过 HTTP 调; 此时业务代码完全一样,只是桥从 JNI 换成了 HTTP。这就是为什么 dispatch_json 被抽成独立 crate (aura-bridge):同一套 JSON 契约,三种传输载体。


3. 分层与仓库地图 ​

text
业务层(生成的项目)   frontend/src/pages·components        rust/src/lib.rs(build_router)
                              │                                     │
前端内核 packages/            @aura/bridge-client  ─────────┐        │
                              @aura/theme / i18n / ui       │        │
                              │                             │        │
传输载体                      Lynx NativeModule / HTTP  ◀────┘        │
                              │                                      │
Rust 内核 crates/             aura(路由·Context·中间件·State)◀──────┘
                              aura-bridge(JSON ↔ 分发,三条载体共用)
                              aura-platform(Platform trait)
                              aura-settings / aura-storage
                              aura-native(JNI / C ABI 固定导出)
                              aura-dev-server / aura-wifi-bridge
                              │
原生壳 platforms/             Android(JNI) / iOS(C ABI) / 鸿蒙(NAPI)
目录内容
crates/Rust 内核(9 个 crate,见上)
packages/前端内核(bridge-client / theme / i18n / ui)
platforms/三端原生壳模板,生成时整体拷进项目
build/三端构建脚本与手册,生成时整体装配进项目的 framework/build/
templates/config/项目配置模板(env / version / store / signing),生成时复制到项目根 config/
templates/app/项目骨架:frontend/ + rust/ + docs/ + 根配置文件
features/<name>/可选能力:feature.json 清单 + 注入片段 + 资源(如 wifi-bridge 的 wifi-web 工程)
scripts/create.mjs生成器:占位符替换、core / link 模式、按 feature 注入
examples/demo-app内核自检样例

单向依赖:业务 → core;内核永不反向引用业务。


4. 一次调用到底发生了什么 ​

text
前端  bridge.call('/library/list', { limit: 20 })
  │
  ├─(App)  NativeModules.Bridge.dispatch(path, json)
  │        ├─ Android: JNI → Java_com_aura_runtime_NativeBridge_nativeDispatch
  │        ├─ iOS:     C ABI → aura_core_dispatch
  │        └─ 鸿蒙:    NAPI 包装层 → aura_core_dispatch
  │
  └─(dev)  POST http://<host>:3456/dispatch { path, params }

Rust  aura_bridge::dispatch_json(aura, path, payload)
  ①  解析 params(空串 / {} = 无参;非法 JSON → 400 响应)
  ②  路由匹配(宏路由与显式注册共用一张路由表)
  ③  构造 Context(params / platform / state / lang)
  ④  依次穿过中间件
  ⑤  handler(ctx) → Response
  返回 {"ok":true,"code":200,"data":...,"message":"success"}

响应信封统一为 { ok, code, data, message };bridge-client 在 ok=false 时抛 BridgeError。

路由两种注册方式:

方式场景
#[route("/path")] + link_routes!异步、需要 Context;编译期用 inventory 收集
aura.route("/path", handler)显式注册,适合简单 JSON 转换或控制顺序

iOS 是 staticlib,inventory 的链接期收集可能被裁掉。模板用 link_routes! 显式引用; 仍 404 时加 -force_load 或改用显式注册。


5. 平台抽象:差异只允许出现在一个 trait ​

aura-platform 定义宿主能力,内核只调 trait,不出现任何平台 API:

能力默认AndroidiOS鸿蒙
app_paths()当前目录JNI 传 dataDirC ABINAPI
log()stderrlogcatos_loghilog
emit()丢弃JNI 静态方法AuraHost.emitNAPI threadsafe
open_url()不支持IntentUIApplication.openstartAbility
set_transfer_server_active()空实现前台服务 + 通知未实现长时任务
vibrate() / set_keep_screen_on()空实现———

新增一项能力的四步:

  1. Platform trait 加带默认空实现的方法(三端不实现也能编译);
  2. Android:aura-native 里加 JNI 调用 → 固定类 com.aura.runtime.NativeBridge 上的 @JvmStatic 方法;
  3. iOS / 鸿蒙:AuraHost(crates/aura-native/include/aura_core.h)末尾追加函数指针字段;
  4. 各端壳接实现。

ABI 只能追加,不能重排——字段顺序错一位就是三端随机崩。


6. 为什么入口符号要「固定」 ​

应用包名是参数化的(com.acme.xxx),但 JNI 符号不能跟着变,否则框架没法预置导出。 所以约定:

  • Kotlin 侧永远有一个 com.aura.runtime.NativeBridge,不随业务包名重命名;
  • 业务代码通过 BridgeModule 间接使用它,业务包名可以随便改;
  • iOS / 鸿蒙走 C ABI,天然与包名无关;
  • 鸿蒙再多一层 aura_napi.cpp:Rust 的 cdylib 没有 napi_module_register,不能直接被 ArkTS import, 必须包一层真正的 NAPI 模块。

这三条合起来,才让「壳可以模板化、生成器只改包名/应用名」成立。


7. 前端内核包与三条硬约束 ​

包职责
@aura/bridge-client通道探测(native / http)、调用、超时、错误、事件订阅
@aura/theme亮暗语义 token
@aura/i18n语言包、插值、切换订阅(框架不内置业务文案)
@aura/uiTabBar / SubPage / ConfirmDialog,类名统一 aura- 前缀
  1. @aura/ui 发 TS 源码,由项目 Rspeedy 编译。预编译成 JS 会丢 style / className / bindtap。
  2. node_modules 里的 CSS 会被 Rspeedy 抽成独立文件,Lynx 运行时不加载。 生成项目会把 UI 样式复制到 frontend/src/styles/aura-ui.css 并在 App.tsx import。
  3. Lynx 样式的 px 是逻辑像素(dp)。原生 inset 是物理像素,传给前端前必须除以 density。

另外:Lynx 运行时没有页面 origin,相对路径 fetch 会直接抛异常 —— 真机调试要把电脑 IP 编进 bundle。


8. 项目生成与形态 ​

bash
# 交互式向导:逐项确认,回车取 app.config.json 里的默认值
node scripts/create.mjs

# 非交互(CI / 脚本):全部取默认值
node scripts/create.mjs ../my-app --yes

# 按需覆盖这一次的取值
node scripts/create.mjs ../my-app --name "我的应用" --bundle-id com.acme.myapp \
     --lib my_core --features wifi-bridge --web vue
  • 按 app.config.json + 命令行参数替换 __XXX__ 占位符(包名、库名、品牌色、功能开关…);
  • --features 按需注入(wifi-bridge 会加 Rust 依赖、/wifi/* 路由、wifi-web/、前台服务与 manifest 权限);
  • core(默认):把 crates/ + packages/ 复制进项目 framework/core/,自包含、可离线、可搬目录;
  • link:path 依赖指回本机框架(此时项目只有 framework/build/),仅框架开发者联调。
text
my-app/
├── frontend/      ReactLynx(Rspeedy)
├── rust/          业务 crate:build_router + link_routes + 导出宏
├── framework/     框架源码:core/(内核副本)+ build/(构建脚本)+ README.md
├── config/        项目配置:env / version / store / signing
├── platforms/     三端原生壳(已替换包名)
├── wifi-web/      可选:局域网传输 Web
└── dist/          构建产物与中间文件(不入库)

结构对应 §10.1 的目标布局,已由生成器落地。


9. 三端壳职责 ​

职责AndroidiOS鸿蒙
引擎初始化LynxEnv.inst().init()(必须,否则白屏)Lynx 初始化Lynx 初始化
页面容器MainActivity 全屏 LynxViewMainViewControllerLynxPage
bundle 加载assets + AppTemplateProvider + renderTemplateUrl同左同左
桥接JNI(固定 com.aura.runtime.NativeBridge)C ABI(AuraHost)NAPI 包装 + threadsafe function
系统栏edge-to-edge,inset → globalProps(dp)系统自动系统自动
调试原生调试浮层(默认隐藏,i 按钮)Xcode 日志hilog

Android targetSdk 35 强制 edge-to-edge:壳不再给内容让位,安全区由 SubPage.safeAreaTop / TabBar.safeAreaBottom 消化;position: fixed 的弹窗铺满整屏。


10. 构建与发布 ​

text
config/env/{dev,prod}.json  应用名后缀 / 包名后缀 / buildType / 混淆 / Rust profile
config/version.json         三端版本唯一来源
config/store/               商店目标 / 文案 / 图标素材
config/signing/             签名与导出材料(*.example 模板,本地副本 gitignore)
framework/build/scripts/    build-* / preflight / package-stores / gen-icons / sync-version / archive
dist/<platform>/<env>/<version>/   安装包 + SHA256SUMS + BUILD_INFO.txt
  • dev 与 prod 可同机共存(包名后缀 .dev);
  • prod 缺正式签名直接失败(本地验证可显式 ALLOW_DEBUG_SIGNING=1);
  • 产物按商店区分:Play → AAB,国内商店 → 分 ABI / universal APK,App Store → IPA + dSYM。

10.1 配置归属与升级边界(已实施) ​

原 build/ 里混了三类东西:执行层(scripts/)、默认值与环境(env/、version.json、stores.json、metadata/)、 项目数据(config/ 签名材料)。其中大量值本来就该由项目决定,和「build/ 是框架资产、可整体替换」的定位冲突; 一旦执行层收成不可见形态(CLI / npm 包),项目配置就没有合法落点。

四条原则:

  1. 代码与配置分离:框架源码目录(core/、build/)里不放项目数据。
  2. 升级语义按目录定死,不靠 README 口头约定。
  3. 机密只引用不内联:密码 / 证书不进受版本管理的配置文件。
  4. 校验逻辑单份实现:config.mjs 的 normalize / validate 只留一份,生成器与项目共用。

目标结构:

text
项目根
├── app.config.json           # 身份与构建目标:app / build / generator / runtime
├── config/                   # 项目资产(永不覆盖)
│   ├── env/{dev,prod}.json
│   ├── version.json
│   ├── store/{stores.json,listing.json,icon.json,assets/}
│   └── signing/{android,ios,harmony}/   # 实体 gitignore,仓库只留 *.example 与 README
├── framework/                # 只读框架源码(整体替换,core 与 build 同版本)
│   ├── core/                 # crates + packages(内核副本)
│   ├── build/                # 构建脚本(原 build/scripts)
│   └── README.md             # 内核教程(原 core/README.md)
├── platforms/                # 三端壳(项目可改)
├── frontend/  rust/          # 业务
└── dist/                     # 产物(不入库)

core/ 与 build/ 合并进 framework/ 的理由:两者升级节奏本就该一致, 分开会导致「core 整体替换、build 手动吸收」的版本漂移;合并后升级只做一件事——整体替换 framework/。 platforms/ 不进 framework/:它是项目可改的壳,收进去会破坏「framework 只读」的语义。

app.config.json 留在根目录(已定):它是声明式入口(决定生成什么、构建什么), 定位接近 package.json,与 config/ 里的数据型配置不同类;留在根目录既符合 package.json / tsconfig.json / Expo app.config.js 的惯例,也让生成器、未来 CLI、IDE 无需额外参数定位。 config/ 只放 env、version、store、signing 这类项目数据。

  • 已实施:app.config.json 增加 $schema,指向 framework/config.schema.json(core 模式), 编辑器即可补全字段、标红未知字段;link 模式不写(避免指向不存在的路径)。

归属与升级矩阵:

路径归属升级行为项目可编辑
app.config.json项目永不覆盖✅
config/**项目永不覆盖✅
framework/**框架源码(内核 + 构建脚本)update-core.mjs 整体替换❌
platforms/**项目壳手动吸收框架改动✅
frontend/**、rust/**业务不受影响✅
dist/**产物不参与升级生成物

合并后必须同步改的路径:

位置现在合并后
Rust 依赖../core/crates/*../framework/core/crates/*
前端 @aura/*file:../core/packages/*file:../framework/core/packages/*
脚本定位根dirname/../..再上一层
package.jsonbash build/scripts/*bash framework/build/scripts/*
生成器复制 core/组装 framework/{core,build}
升级脚本替换 core/替换整个 framework/(不碰 config/、platforms/)

读取约定:

  • 所有脚本只通过 framework/build/scripts/config.mjs 暴露的路径 / 值接口取配置,禁止硬编码 config/env/... 这类字符串。
  • 覆盖优先级:命令行参数 > 环境变量 > config/ > app.config.json > 框架默认值。

机密约定:

  • 受版本管理的配置只写路径或环境变量名,例如 "keystore": "config/signing/android/release.jks"、"storePasswordEnv": "ANDROID_KEYSTORE_PASSWORD"。
  • 证书、描述文件、API Key 实体一律 gitignore。

版本策略:

  • schemaVersion 为 3;低于 3 的旧结构(项目数据在 build/)直接报错,不做静默回退 ——旧布局的项目已不存在,留着兼容分支只会让「读出错值」比「报错」更难排查;
  • 高于 3 时报错并提示先升级框架;
  • create.mjs 只按当前结构生成。

与「不弹出」的关系:

  • 执行层不弹出时,framework/ 由 npm 包(如 @aura/build + 预构建内核)提供,项目只保留 app.config.json + config/ + frontend/ + rust/ + platforms/;
  • 配置位置与是否弹出无关:能隐藏的只有 framework/,配置永远在项目根。

实施记录(已完成):

  1. core/ + build/ 合并为 framework/,同步 Rust / 前端依赖路径与脚本定位;
  2. config.mjs 抽出路径解析(resolveProjectPaths);doctor / generate-check 覆盖新结构;
  3. 文件迁移,同步 create.mjs 与 templates/app,跑通生成器金丝雀;
  4. 更新 README、quickstart、build/README.md 中的路径说明;
  5. 确认没有旧布局项目后,删除 build/ 旧路径回退与旧 config 结构兼容分支(schemaVersion < 3 直接报错)。

10.2 后续优化清单(P0 / P1 / P2 均已实施或已评估) ​

按收益排序,P0 影响迭代速度,P1 补工程化能力,P2 清质量与文档债务。 逐条执行清单见 layout-migration-checklist.md。

P0 · 迭代速度

  1. 生成器拆分(已实施):scripts/create.mjs 由 772 行降到约 250 行, 逻辑拆到 scripts/lib/{args,ui,fs-utils,features,replacements,assemble}.mjs; 旧/新生成结果逐文件 diff 一致(仅时间戳不同)。
  2. feature 目录化(已实施):features/wifi-bridge/{feature.json, snippets/, web/} 声明 crate 依赖、 占位符片段、资源目录与钩子,生成器按清单装配(scripts/lib/features.mjs + assemble.mjs)。 新增 feature 只需加目录与 feature.json,不改生成主流程。 后续可把 privacy-consent / splash-ad 也迁入同一清单。

P1 · 工程化补齐

  1. CLI 入口(已实施):根 package.json 注册 bin: { aura } 并提供 pnpm aura 脚本, 支持 aura create <目录> / aura check,参数与既有脚本一致(scripts/cli.mjs 只做转发)。
  2. 配置强校验(已实施):config.mjs 新增 validateConfig(), config:check(sync-config --check)按严格模式校验类型、范围与枚举,失败退出码 1; 普通读取仍只告警。JSON Schema 源文件在仓库根 schema/app.config.schema.json, core 模式生成时装配到项目的 framework/config.schema.json,并在 app.config.json 写 "$schema": "./framework/config.schema.json";link 模式两者都不带。
  3. 发布入口统一(已实施):scripts/release.mjs 统一 package.json / app.config.json / Cargo.toml(含 aura* 依赖)的版本号,提交后打 vX.Y.Z tag;--check 校验四处版本与最新 tag 是否一致,--push 才推送。push.sh --tag 保留为临时标记,正式发布走 pnpm aura release; core/Cargo.toml 的版本改为从框架 Cargo.toml 读取,不再写死 0.1.0。
  4. 构建脚本上移(已实施):templates/app/build/ 的源文件移到仓库根 build/(与 crates/、packages/ 并列), 生成时由 installBuildScripts() 装配进项目的 framework/build/(脚本 ROOT 按 dirname/../../.. 推算); templates/app/ 只保留 frontend/、rust/、docs/ 与骨架文件。 scripts/lib/replacements.mjs 与 create.mjs 改为从根 build/scripts/config.mjs 导入。 §10.1 合并 framework/ 时,装配目标再从 build/ 改成 framework/build/(已实施)。

P2 · 质量与债务

  1. 金丝雀矩阵(已实施):generate-check.mjs 按「默认 / 全关 / 仅 wifi-bridge / 仅 privacy-consent / link 模式」五种组合各生成一个项目,分别断言 feature 开关落点(前端常量、Rust 常量、wifi-web 工程、 Android 清单权限与服务)、三端默认值、$schema 写入策略、依赖引用完整性与占位符残留; 默认组合还会跑一次 update-core 升级再校验,纯静态生成,秒级完成。 splash-ad 需要素材地址才会真正启用,默认配置没有 imageUrl,目前断言「无素材不启用」。 金丝雀不编译:全量 cargo check 在 Intel Mac 上代价很高,且使用者生成项目后本来就会 pnpm dev 编译一次。折中是静态校验 rust/Cargo.toml 的 path 依赖、frontend/package.json 的 file: 依赖、framework/core 的 workspace members 都真实存在——生成器改路径失效时, 这是最先炸的地方,而查目录成本几乎为零。
  2. 自检职责收敛(已评估:保留):examples/demo-app 与金丝雀不重叠。demo-app 走 cargo run,实际执行宏路由、register、中间件、State、i18n、settings 落盘、storage 打开与 bridge 分发的正常 / 错误 / 404 三种结果,是内核运行时行为的唯一自检;金丝雀只做静态生成检查, 不 cargo、不加载内核。删除 demo-app 会让「内核 API 还能跑」失去回归入口。
  3. 文档债务(已实施):docs/extraction-map.md 已标记为历史文档,现行结构以本文为准; 根目录 git.md 是本地草稿,已被 .gitignore 忽略,不入库。

以上条目不影响 §10.1 的规范结论;P0 / P1 / P2 均已实施或已评估。


11. 可选能力:wifi-bridge ​

它不参与主桥,而是一个独立的 axum 服务(默认 30000),与 App 通过 Platform 耦合:

text
App 前端 ──/wifi/start──▶ aura 路由 ──▶ WifiBridge::start(port)
                                          ├─ 起 axum(页面 `/`,接口 `/bridge/*`)
                                          ├─ Platform::set_transfer_server_active(true, url)
                                          └─ Android 前台服务 / 鸿蒙长时任务(后台保活 + 通知)
电脑浏览器 ──http://<手机IP>:30000──▶ 传输页面(wifi-web 产物,编译期嵌入 Rust)

详见 wifi-bridge.md。


12. 常见扩展怎么做 ​

想加什么改哪里
新接口业务 rust/src/*.rs 加 #[route](或 aura.route),前端 bridge.call
新平台能力Platform trait 加默认方法 → 三端实现(§5)
新 UI 组件packages/ui/src/<name>/ 并导出;业务项目同步 src/styles/aura-ui.css
新前端包packages/<name>/ + workspace;发 TS 源码时 main/types 指向 src/index.ts
新生成开关app.config.json + create.mjs 的 replacements

13. 验证与门禁 ​

bash
cargo test                      # 内核单测
cargo run -p demo-app           # 最小业务自检
pnpm -r build                   # 前端内核包
pnpm --dir frontend typecheck   # 业务前端类型(生成项目内)
pnpm preflight                  # 版本 / 签名 / 架构 / 商店元数据

改 crates/ 或 packages/ 后,要重新生成项目(或同步 core/)跑一遍 pnpm dev + pnpm build:android,才算端到端验证。


14. 已知边界 ​

边界说明
iOS 后台系统不允许本地 HTTP 服务长期后台运行,beginBackgroundTask 仅约 30 秒
Lynx CSS全局无作用域,组件类名必须带前缀(aura-)
position: fixed提升到根节点,坐标基准是屏幕而非父容器
宏路由 + iOS staticlib依赖 inventory,需 link_routes! 或 -force_load
dev 模式 bridge真机必须注入电脑局域网 IP,不能用相对路径

lynx-aura · 跨平台本地应用开发框架