Skip to content

归属清单:从 reader-app 抽取到 lynx-aura ​

⚠️ 历史文档:完成抽取时的记录,部分内容已过时(rust/engine 已不存在、git 依赖模式已删除、 build/ 已从 templates/app/ 上移到仓库根)。现行结构以 architecture.md 为准。

目标:产出一个与业务无关的通用框架。 约束:不改动 reader-app,采取「快照 + 通用化」方式复制到新仓库。 本文档只做归属判定与顺序安排,不代表已开始实施。

一、判定规则 ​

按顺序判断,命中即停:

  1. 名字或语义含 book / chapter / note / shelf / read / tts / stats / backup → 业务
  2. 换一个完全不同的产品仍然需要 → kit(可依赖)
  3. 只在启动新项目时用一次,之后不再更新 → 脚手架(模板)
  4. 属于某端构建体系、必须是文件 → 脚手架(模板)

二、总览 ​

区域归属处理方式
rust/aura/*kit直接搬,去掉 reader 命名
rust/native/*kit + 模板bridge/ffi/host/platform 进 kit;lib.rs 的 JNI 导出名参数化
rust/server/*kitdev 模式 HTTP 桥,通用
rust/migration/*kit只保留迁移执行器,迁移内容留在项目
rust/app/services/*业务不搬
rust/app/handlers/*kit + 业务路由注册机制进 kit,具体 handler 留项目
rust/app/entity/*业务不搬
rust/ebook/*业务不搬
rust/engine/*⚠️ 待拆分db/http_server 可能通用,parser/TTS 是业务
rust/i18n/*kit(可选)原生侧语言查询
rust/core、rust/handlers、rust/web⚠️ 待确认疑似历史遗留目录,抽取前先确认是否仍被引用
frontend/utils/bridge/{core,http,native,ws,events}kit传输层,抽成 bridge-client
frontend/utils/bridge/{library,reader,stats,tts,backup,font,server,settings}业务不搬;settings 的 schema 可抽基座
frontend/utils/{safeArea,backPress,appInfo,logCapture,devLog,timeFormat}kit通用运行时
frontend/components/ui/*kit(部分)见下表
frontend/components/business/*业务不搬
frontend/pages/*业务仅保留 1 个示例页进模板
frontend/styles/*、frontend/src/i18n/*kit + 模板主题与加载器进 kit,语言包骨架进模板
frontend/App.tsx、index.tsx、lynx.config.ts模板参数化 bundle 名与调试开关
android/、ios/、harmony/模板壳工程参数化,业务 Service 不搬
build/模板整套复制,仅替换项目名/包名相关常量
scripts/(根目录开发脚本)模板(部分)见下表
web-admin/、web-reader/业务不搬
assets/、design/、archive/、backup/、covers/不搬各自项目资产

三、Rust 明细 ​

模块归属说明
aura/aura/src/{path,file,network,log,notification,audio}kit platform需把 TTS 播放拆成 feature
aura/aura-macroskit路由/导出宏,名字里的 reader 去掉
native/src/bridge.rskitJNI → dispatch 转发
native/src/host.rskit宿主环境初始化
native/src/platform.rskitAndroid/iOS/Harmony 平台实现
native/src/ffi.rskitC ABI(iOS/鸿蒙)
native/src/lib.rs模板JNI 符号与库名 reader_core 必须参数化
server/src/*kit3456 dev 桥;与 app 的 handler 注册解耦
migration/src/lib.rskit迁移 runner
migration/src/m*业务具体表结构留项目
app/src/lib.rskit + 业务现在一次性注册全部 handler,需拆成「注册入口」与「业务注册」
app/src/handlers/*业务保留在项目侧
app/src/services/{book,parser,reader,stats,tts,backup,...}业务不搬
app/src/entity/*业务表结构随业务
ebook/**业务电子书解析/写出,reader 专有
engine/src/{db,pagination}⚠️ 可能通用与 app 职责重叠,抽取前先确认调用方
engine/src/{parser,http_server}⚠️ 业务TTS/解析相关

四、前端明细 ​

kit(可直接通用) ​

文件/目录去向
utils/bridge/core.tsbridge-client/core
utils/bridge/native.tsbridge-client/native
utils/bridge/events.tsbridge-client/events
utils/safeArea.tsui/runtime
utils/backPress.tsui/runtime
utils/appInfo.tsbridge-client
utils/logCapture.ts、debugLogdevtools
utils/timeFormat.tscore
components/ui/TabBarui
components/ui/ConfirmDialogui
components/ui/SelectSheetui
components/ui/Switchui
components/ui/TextFieldui
components/ui/StatusBarui
components/ui/PullToRefreshScrollViewui
components/ui/ErrorBoundaryui
components/business/SubPageui(页面栈属于骨架)
styles/theme.ts、fonts.csstheme
i18n/index.ts + 加载逻辑i18n
scripts/s2t.mjsi18n(繁体生成)

业务(不搬) ​

  • components/ui/{BookCover,FolderCover,ModeBadge}
  • components/business/*(WifiTransfer 可作为可选模块,但默认不进 kit)
  • pages/* 全部
  • utils/bridge/{library,reader,stats,tts,backup,font,server,settings}
  • utils/fonts.ts(阅读字体)
  • i18n 中的业务 key

模板(每项目一份) ​

  • App.tsx、index.tsx、main.lynx.bundle 命名
  • lynx.config.ts(bundle 名、HIDE_DEBUG_PANELS、入口)
  • 一个列表示例页 + 一个设置示例页

五、三端壳明细 ​

文件归属说明
android/.../MainActivity.kt模板LynxView 容器;WebView 选区/视频全屏接管属可选能力
android/.../ReaderApp.kt模板LynxEnv.init 必须在
android/.../AppTemplateProvider.kt模板bundle 名参数化
android/.../BridgeModule.kt模板反射分发;路由清单改为 kit 注册
android/.../NativeCoreEntry.kt模板稳定入口,用来隔离 JNI 符号与包名
android/.../DebugView.ktkit devtools可选模块
android/.../{SplashAdView,TtsPlaybackService,CoverPicker,ReaderFonts,LocalFileImport,InputBehavior}.kt业务/可选默认不进框架
android/.../WifiTransferService.ktfeature wifi-bridge已移入 platforms/android,生成时随 feature 注入;JNI 启停需手动接线
android/app/src/main/res/**模板图标由 gen-icons.py 生成
android/.../build.gradle.kts模板应用名/包名/签名/ABI 参数化
ios/ReaderApp/{AppDelegate,ViewController,AppTemplateProvider,NativeBridge}.swift模板同上
ios/ReaderApp/SplashAdView.swift可选开屏广告非必需
ios/Podfile、build/config/ios/project.yml模板XcodeGen
harmony/AppScope、entry/src/main/module.json5模板包名/权限参数化
harmony/.../reader_core_napi.cpp模板库名与模块名参数化

六、build/ 与根 scripts/ ​

实施时做了简化:框架根目录不保留 build/。三端构建脚本放在 templates/app/scripts/,随生成项目落到该项目的 scripts/;图标、签名、 版本同步等尚未进框架,需要时按本表再补。

文件归属说明
build/scripts/build-android.sh模板直接复制,改名/包名常量抽到配置
build/scripts/build-ios.sh、gen-ios-project.sh模板同上
build/scripts/build-harmony.sh、build-harmony-hap.sh模板同上
build/scripts/gen-icons.py模板与业务无关
build/scripts/sync-version.mjs模板三端版本同步
build/scripts/verify-android.sh、list-dist.sh模板自检与产物汇总
build/config/**模板全部保留(*.example 为模板)
build/docs/**模板文档随框架走
build/version.json模板版本唯一来源
scripts/clean-cache.sh、prune-target.sh、run-emulator.sh、debug-phone.sh、perf-locator.sh模板开发辅助
scripts/fonts.sh、s2t.mjskit字体子集与繁体生成
scripts/package.sh不进框架已被 build/ 取代

七、依赖阻塞点(必须先解决) ​

抽取顺序不能按目录走,要先解开这几处耦合,否则会拖一堆业务代码进 kit。

#阻塞点现状处理
1frontend/utils/bridge/index.ts直接 import 全部业务 API拆成 core + registry,业务在项目侧注册
2app/src/lib.rs一次性注册所有业务 handlerkit 暴露 register_handlers,项目传入自己的清单
3android/.../BridgeModule.kt反射调用固定业务名改为从 kit 拿路由表
4JNI 符号Java_com_reader_app_* 与包名绑定统一走 NativeCoreEntry,符号不再随包名变化
5库名 / 数据库名reader_core、reader.db 硬编码由 app.config.json 注入常量
6settings schema含阅读字号、翻页模式等业务字段拆 base + business extension
7aura可能含 TTS/通知等 reader 专属实现拆成默认 feature,可关
8app 与 engine 职责重叠均有 db/http先确认调用方,再决定哪些上移

八、实施顺序 ​

阶段内容验收
P0 ✅新仓库骨架:Cargo workspace + npm workspace + examples/demo-app 自检cargo test 全绿、cargo run -p demo-app 跑通(前端构建推迟到 P3)
P1 ✅platform / settings / storage 落地(阻塞点 5、6 直接在新仓按契约重写,不搬业务字段)aura-storage 真实建库、aura-settings 文件持久化,demo 已跑通
P2 ✅aura-bridge 统一响应信封 + aura-dev-server + @aura/bridge-client已跑通:Node 客户端 → HTTP → demo 路由,取到 {echo:"hi"}、404 正确
P3 ✅@aura/theme / @aura/i18n / @aura/ui(TabBar、SubPage、ConfirmDialog)三包 tsc 构建通过;theme/i18n 已用 Node 冒烟验证;页面联调放到 P4 生成器
P4a ✅templates/app(前端 + Rust)+ scripts/create.mjs(link / core / git 三模式)生成的项目 cargo check、tsc --noEmit、rspeedy build 全部通过
P4b ✅Android 壳参数化(platforms/android:App / MainActivity / BridgeModule / TemplateProvider)生成项目 gradle :app:assembleDebug 成功,产出 13MB APK
P5a ✅Android 全链路:scripts/build-android.sh(前端 bundle → Rust .so → APK)APK 内含 assets/main.lynx.bundle 与 lib/arm64-v8a/libmy_core.so,.so 导出 3 个固定 JNI 符号
P4c ✅iOS / HarmonyOS 壳(platforms/ios XcodeGen + platforms/harmony DevEco)生成项目可出 Xcode 工程;鸿蒙 JSON5/资源引用通过校验(本机无 DevEco,未出 HAP)
P5b ✅iOS / 鸿蒙链路 + 文档:build-ios.sh / build-harmony.shiOS 实测:release 静态库 → XCFramework(含 4 个 C ABI 符号)→ 工程可生成;鸿蒙脚本已跑通 bundle/头文件部分,Rust 交叉编译需 OHOS SDK(本机未装)
P5c ✅iOS / 鸿蒙 NativeModules.Bridge 通道iOS Swift LynxModule(BridgeModule.swift)+ 鸿蒙 ArkTS LynxModule;@aura/bridge-client 的 native 模式在三端可用(iOS 仅语法检查,鸿蒙待编译)

九、风险与约定 ​

  1. 不回流:reader 后续修复不会进入 framework,需要定期对照 extraction-map.md 人工同步。
  2. 不追求一次到位:只搬第二个项目真正会用到的部分;拿不准的先留在业务侧。
  3. kit 禁止业务词:book/chapter/note/read 出现在 kit 即视为违规,CI 可加 grep 检查。
  4. 模板只生成一次:生成后的项目通过升级 kit 获取改进,不允许直接改模板副本。
  5. 大依赖不进 kit:sherpa/onnx/TTS 模型、阅读字体等保持可选,避免框架体积失控。

十、命名与分发约定(已定) ​

命名 ​

对象命名
仓库lynx-aura
Rust crateaura、aura-macros、aura-platform、aura-bridge、aura-storage、aura-settings、aura-native、aura-dev-server
前端包@aura/bridge-client、@aura/ui、@aura/theme、@aura/i18n、@aura/devtools
生成的项目由 app.config.json 决定,模板内统一使用 __APP_NAME__ / __APP_IDENT__ / __BUNDLE_ID__ / __LIB_NAME__ 占位

选 aura- 前缀是延续 reader 里既有的 aura 平台抽象,抽取后由其收敛为框架的底座。

目录映射:reader 的 rust/aura/* → 本仓库 crates/aura-*(统一 aura- 前缀); rust/native/* → crates/aura-native;rust/server/* → crates/aura-dev-server。 只有生成的项目里才有 rust/,放该项目的业务 crate。

分发模式 ​

场景模式
框架自身开发、demo 验证link(path 依赖)
正式项目日常git tag 依赖(Cargo git dep + npm git dep)
交付外部、离线构建core(复制源码)

link 只用于同机联调,不作为分发形态。

项目内版本标记 ​

生成的项目在 app.config.json 中记录:

json
{
  "frameworkVersion": "0.1.0"
}
  • frameworkVersion:kit 的 git tag,升级时改这里与依赖声明

同步策略(三类分开) ​

变更类型同步方式自动化
内核代码(crates / packages)升 tag → 项目改 pin → CI 编译高
模板文件(build/、docs/)按 CHANGELOG 手动吸收中
壳工程(三端)不同步。框架只提供基础壳,项目自行扩展,升级靠手动回归无

壳工程不做自动合并是刻意选择:项目已改包名、签名、权限与业务 Service,自动覆盖的失败成本高于手动。

修改内核的规则 ​

项目若必须改 kit 源码,不走长期 core 分叉,而是:在框架内加能力或 feature flag → 发版 → 项目升级回来。core 只作为交付形态存在。

十一、微内核能力对齐(P6 ✅) ​

早期 P0–P5 只落了一张同步路由表,reader 里 rust/aura/aura + aura-macros 的微内核能力 (宏路由 / Context / 中间件 / State / i18n / Platform 能力)没有迁过来。P6 已全量补齐, 并按职责拆 crate:内核 aura,传输 aura-bridge,入口 aura-native。

能力reader 位置本仓库位置说明
宏路由 #[route] + inventoryaura-macros/src/lib.rscrates/aura-macros + aura re-exportAura::new() 自动收集
静态库链接兜底rust/app/src/lib.rs 的 init()crates/aura 的 link_routes!显式引用宏路由 handler,防 iOS 裁符号
统一分发 Aura::dispatchaura/src/aura.rscrates/aura/src/aura.rs内核只保留异步分发
Contextaura/src/context/context.rscrates/aura/src/context.rsrequest_id / path / params / body / platform / state / 翻译 / success / error
中间件 + Nextaura/src/middleware/*crates/aura/src/middleware.rs洋葱模型;内置 logger / timeout
异步 Handleraura/src/router/handler.rscrates/aura/src/router.rsRouteHandler + HandlerFuture
Stateaura/src/state/state.rscrates/aura/src/state.rs类型擦除全局状态
i18n(目录加载)aura/src/translator/*crates/aura/src/translator/*AuraI18n:JSON / TOML / YAML、语言规范化、fallback 链
i18n(内存/内嵌)rust/i18n(I18nBundle)crates/aura 的 I18nBundle对应 reader 的 i18n crate,去掉业务文案,支持 load_json/yaml/toml
Platformaura/src/platform.rscrates/aura-platform增加 emit / open_url / vibrate / keep_screen_on / platform_name;log(level, tag, msg) 与 reader 对齐;业务专属能力未搬
JSON 传输rust/native/src/bridge.rscrates/aura-bridge只做载荷解析 / 序列化 / block_on,不含路由
原生入口rust/native/*crates/aura-nativeinstall() 注入 NativePlatform,JNI / C ABI 符号不变

对外契约(未变) ​

  • JNI:Java_com_aura_runtime_NativeBridge_{nativeInit,nativeDispatch,nativeIsReady}
  • C ABI:aura_core_{init,dispatch,free_string,is_ready},AuraHost 三字段顺序不变
  • HTTP:POST /dispatch({path, params})
  • 信封:{ ok, code, data, message }(成功 code = 200)

iOS 静态库(已给兜底) ​

inventory 是链接期收集。iOS 用 staticlib 链进 App 时,未被引用的 object 可能被裁掉, 表现为 #[route] 定义的路由 404。处理方式:

  1. 首选:业务 crate 用 aura::link_routes!(init: ping, ...) 显式引用每个宏路由,并在 Aura::new() 之前调用 init()(模板已内置,reader 的 reader_app::init() 同理);
  2. 仍有缺失时,给 App target 加 -force_load <path>/lib<lib>.a;
  3. 或在 build_router() 里用 aura.route(path, handler) / aura.register(path, handler) 显式登记。

Android(cdylib)与鸿蒙(NAPI 动态库)整库加载,不受影响。模板同时给出宏路由与显式注册示例。

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