主题
归属清单:从 reader-app 抽取到 lynx-aura
⚠️ 历史文档:完成抽取时的记录,部分内容已过时(
rust/engine已不存在、git 依赖模式已删除、build/已从templates/app/上移到仓库根)。现行结构以 architecture.md 为准。
目标:产出一个与业务无关的通用框架。 约束:不改动 reader-app,采取「快照 + 通用化」方式复制到新仓库。 本文档只做归属判定与顺序安排,不代表已开始实施。
一、判定规则
按顺序判断,命中即停:
- 名字或语义含
book / chapter / note / shelf / read / tts / stats / backup→ 业务 - 换一个完全不同的产品仍然需要 → kit(可依赖)
- 只在启动新项目时用一次,之后不再更新 → 脚手架(模板)
- 属于某端构建体系、必须是文件 → 脚手架(模板)
二、总览
| 区域 | 归属 | 处理方式 |
|---|---|---|
rust/aura/* | kit | 直接搬,去掉 reader 命名 |
rust/native/* | kit + 模板 | bridge/ffi/host/platform 进 kit;lib.rs 的 JNI 导出名参数化 |
rust/server/* | kit | dev 模式 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-macros | kit | 路由/导出宏,名字里的 reader 去掉 |
native/src/bridge.rs | kit | JNI → dispatch 转发 |
native/src/host.rs | kit | 宿主环境初始化 |
native/src/platform.rs | kit | Android/iOS/Harmony 平台实现 |
native/src/ffi.rs | kit | C ABI(iOS/鸿蒙) |
native/src/lib.rs | 模板 | JNI 符号与库名 reader_core 必须参数化 |
server/src/* | kit | 3456 dev 桥;与 app 的 handler 注册解耦 |
migration/src/lib.rs | kit | 迁移 runner |
migration/src/m* | 业务 | 具体表结构留项目 |
app/src/lib.rs | kit + 业务 | 现在一次性注册全部 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.ts | bridge-client/core |
utils/bridge/native.ts | bridge-client/native |
utils/bridge/events.ts | bridge-client/events |
utils/safeArea.ts | ui/runtime |
utils/backPress.ts | ui/runtime |
utils/appInfo.ts | bridge-client |
utils/logCapture.ts、debugLog | devtools |
utils/timeFormat.ts | core |
components/ui/TabBar | ui |
components/ui/ConfirmDialog | ui |
components/ui/SelectSheet | ui |
components/ui/Switch | ui |
components/ui/TextField | ui |
components/ui/StatusBar | ui |
components/ui/PullToRefreshScrollView | ui |
components/ui/ErrorBoundary | ui |
components/business/SubPage | ui(页面栈属于骨架) |
styles/theme.ts、fonts.css | theme |
i18n/index.ts + 加载逻辑 | i18n |
scripts/s2t.mjs | i18n(繁体生成) |
业务(不搬)
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.kt | kit devtools | 可选模块 |
android/.../{SplashAdView,TtsPlaybackService,CoverPicker,ReaderFonts,LocalFileImport,InputBehavior}.kt | 业务/可选 | 默认不进框架 |
android/.../WifiTransferService.kt | feature 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.mjs | kit | 字体子集与繁体生成 |
scripts/package.sh | 不进框架 | 已被 build/ 取代 |
七、依赖阻塞点(必须先解决)
抽取顺序不能按目录走,要先解开这几处耦合,否则会拖一堆业务代码进 kit。
| # | 阻塞点 | 现状 | 处理 |
|---|---|---|---|
| 1 | frontend/utils/bridge/index.ts | 直接 import 全部业务 API | 拆成 core + registry,业务在项目侧注册 |
| 2 | app/src/lib.rs | 一次性注册所有业务 handler | kit 暴露 register_handlers,项目传入自己的清单 |
| 3 | android/.../BridgeModule.kt | 反射调用固定业务名 | 改为从 kit 拿路由表 |
| 4 | JNI 符号 | Java_com_reader_app_* 与包名绑定 | 统一走 NativeCoreEntry,符号不再随包名变化 |
| 5 | 库名 / 数据库名 | reader_core、reader.db 硬编码 | 由 app.config.json 注入常量 |
| 6 | settings schema | 含阅读字号、翻页模式等业务字段 | 拆 base + business extension |
| 7 | aura | 可能含 TTS/通知等 reader 专属实现 | 拆成默认 feature,可关 |
| 8 | app 与 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.sh | iOS 实测: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 仅语法检查,鸿蒙待编译) |
九、风险与约定
- 不回流:reader 后续修复不会进入 framework,需要定期对照
extraction-map.md人工同步。 - 不追求一次到位:只搬第二个项目真正会用到的部分;拿不准的先留在业务侧。
- kit 禁止业务词:
book/chapter/note/read出现在 kit 即视为违规,CI 可加 grep 检查。 - 模板只生成一次:生成后的项目通过升级 kit 获取改进,不允许直接改模板副本。
- 大依赖不进 kit:sherpa/onnx/TTS 模型、阅读字体等保持可选,避免框架体积失控。
十、命名与分发约定(已定)
命名
| 对象 | 命名 |
|---|---|
| 仓库 | lynx-aura |
| Rust crate | aura、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] + inventory | aura-macros/src/lib.rs | crates/aura-macros + aura re-export | Aura::new() 自动收集 |
| 静态库链接兜底 | rust/app/src/lib.rs 的 init() | crates/aura 的 link_routes! | 显式引用宏路由 handler,防 iOS 裁符号 |
统一分发 Aura::dispatch | aura/src/aura.rs | crates/aura/src/aura.rs | 内核只保留异步分发 |
| Context | aura/src/context/context.rs | crates/aura/src/context.rs | request_id / path / params / body / platform / state / 翻译 / success / error |
| 中间件 + Next | aura/src/middleware/* | crates/aura/src/middleware.rs | 洋葱模型;内置 logger / timeout |
| 异步 Handler | aura/src/router/handler.rs | crates/aura/src/router.rs | RouteHandler + HandlerFuture |
| State | aura/src/state/state.rs | crates/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 |
| Platform | aura/src/platform.rs | crates/aura-platform | 增加 emit / open_url / vibrate / keep_screen_on / platform_name;log(level, tag, msg) 与 reader 对齐;业务专属能力未搬 |
| JSON 传输 | rust/native/src/bridge.rs | crates/aura-bridge | 只做载荷解析 / 序列化 / block_on,不含路由 |
| 原生入口 | rust/native/* | crates/aura-native | install() 注入 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。处理方式:
- 首选:业务 crate 用
aura::link_routes!(init: ping, ...)显式引用每个宏路由,并在Aura::new()之前调用init()(模板已内置,reader 的reader_app::init()同理); - 仍有缺失时,给 App target 加
-force_load <path>/lib<lib>.a; - 或在
build_router()里用aura.route(path, handler)/aura.register(path, handler)显式登记。
Android(cdylib)与鸿蒙(NAPI 动态库)整库加载,不受影响。模板同时给出宏路由与显式注册示例。