159 lines
9.9 KiB
Markdown
159 lines
9.9 KiB
Markdown
# LineUp Client 与 Mini Runtime 技术选型：原生 Android、Tauri 2 与 Wails v3
|
||
|
||
**版本：** 0.1（评审稿）
|
||
|
||
**状态：** 已确认第一阶段技术路线
|
||
|
||
**日期：** 2026-08-02
|
||
**关联设计：** [LineUp App 层架构设计方案](../设计/02.正式方案/lineup-app-layer-architecture.md)、[LineUp UI Surface 与 App Capability 协议](../设计/02.正式方案/lineup-ui-surface-protocol.md)
|
||
|
||
---
|
||
|
||
## 1. 决策问题
|
||
|
||
LineUp 已有可运行的 Kotlin Android 客户端，并完成 App Server、WuKongIM、Hermes Adapter 的连通。它的定位是快速验证 IM、协议、设备接入和交互闭环，不是长期多端客户端的唯一实现。
|
||
|
||
长期目标是在 App 层建立 LineUp 自定义的“小程序运行环境”：利用系统 WebView / WebKit 执行 HTML、CSS、JavaScript，但由 LineUp 定义小程序包、生命周期、受限桥接、事件协议、权限与审计模型。这里不实现浏览器或 JavaScript 内核；实现的是运行在系统 Web 内核之上的 **LineUp Mini Runtime**。
|
||
|
||
本次只讨论客户端实现载体；LineUp Envelope、Interaction Kernel、Surface 安全模型与 Capability Registry 的协议边界不因载体而改变。
|
||
|
||
## 2. 已确认的技术路线
|
||
|
||
| 选项 | 决策 | 定位 |
|
||
|---|---|---|
|
||
| 现有 Kotlin Android | **保留** | 稳定基线、原生能力参考实现和持续交付通道 |
|
||
| Tauri 2 | **第一优先开展独立 Spike** | LineUp Mini Runtime 的 Reference Host、安全与能力基线 |
|
||
| Wails v3 | **第二阶段按同一基线评估** | 利用 Go 主技术栈的长期 Host 候选 |
|
||
|
||
不直接重写或删除当前 Kotlin App。先通过 Tauri Spike 验证跨端 Host、小程序隔离、系统能力桥接和移动端恢复；再以完全相同的 Mini Runtime 协议与验收标准验证 Wails v3。这样可将技术选择从框架偏好转为可实证的交付能力比较。
|
||
|
||
### 2.1 为什么先验证 Tauri
|
||
|
||
Tauri 的团队、社区、桌面生态和移动端路径相对成熟，适合作为高标准的参考宿主。它先回答的不是“能否把现有 Android 聊天页换成 Web”，而是“可信 LineUp 主应用与不可信小程序 Surface 能否在多端稳定且安全地共存”。
|
||
|
||
Wails v3 与 Go 主技术栈更匹配，仍是重要的长期候选；但它应接受已验证的 Runtime 基线，而不是由它当前的 Beta 状态来定义平台边界。
|
||
|
||
## 3. 当前资产与迁移匹配度
|
||
|
||
Web Reference Host 已存在下列可复用资产：
|
||
|
||
```text
|
||
lineup-app-server/assets/chat/
|
||
├── interaction-kernel.js # ConversationItemFactory + RendererRegistry
|
||
└── index.html # GFM Markdown、安全净化、Surface Host、App Call UI
|
||
```
|
||
|
||
可复用的核心能力包括：
|
||
|
||
- `marked + DOMPurify` 的 GFM Markdown；
|
||
- `ConversationItem` 与 Renderer Registry；
|
||
- `lineup.v1.text`、`agent.status`、`agent.progress`、`error` renderer；
|
||
- `lineup.v1.ui.open / patch / close / event` 的 sandbox iframe Surface Host；
|
||
- `lineup.v1.app.call / result` 的用户确认交互；
|
||
- WebSocket 接入形态（服务端 WSS 尚待提供；当前 Android 是 HTTP 轮询）。
|
||
|
||
目前 Android 使用 OkHttp、RecyclerView、Clipboard、外链 Intent、Activity 生命周期和轮询，不依赖相机、蓝牙、音视频等重量级原生 SDK。故迁移“表现层与会话 UI”的阻力较低，但系统能力、推送和后台恢复仍必须有原生实现。
|
||
|
||
## 4. 方案对比
|
||
|
||
| 维度 | 当前 Kotlin Android | Tauri 2 | Wails v3 |
|
||
|---|---|---|---|
|
||
| Android UI | 原生 View / RecyclerView | Web 前端 + Android WebView | Web 前端 + 容器；移动端路径需进一步证实 |
|
||
| Markdown | 临时 regex + HtmlCompat，不完整 | 直接复用 GFM + sanitizer | 可复用 Web 实现 |
|
||
| LineUp Surface | 当前仅原生 Task Dashboard | 可复用 iframe sandbox Host | 需要专项验证 |
|
||
| 内置 Renderer / 标准组件 | 需逐个原生实现 | 可复用现有 Web Renderer | 可复用现有 Web Renderer |
|
||
| 系统能力 | Kotlin 直接调用 | Tauri Plugin / Kotlin bridge | Go bridge / 原生层，需专项验证 |
|
||
| Push、通知、后台、Deep Link | 路径最直接 | 仍需要原生 Plugin | 仍需要原生 bridge |
|
||
| Android 成熟度 | 已在项目真机运行 | 官方 Mobile 路径，作为首个真机 Spike | 官方 README 标为 v3 Beta，需以 Tauri 结果作对照 |
|
||
| 现有 Web 实现复用 | 低 | 高 | 高 |
|
||
| 推荐角色 | 稳定基线 | **Reference Host / 第一优先 Spike** | **Go 主栈长期候选 / 第二阶段对照实现** |
|
||
|
||
### 4.1 Tauri 2：Reference Host
|
||
|
||
Tauri 2 是当前最适合优先验证的跨端候选。官方 v2 文档覆盖 Android、iOS 与 Mobile；它能够复用已有 Web 表现层资产，同时仍允许通过原生插件承接 Android 系统能力。Tauri 在本项目中承担的是可信 LineUp 主应用与 Mini Runtime 的第一版参考实现，而不是第三方小程序本身。
|
||
|
||
它替换的是会话 UI、Markdown、Renderer、标准组件和 Surface Host，并非把 Android 原生层完全移除。Kotlin/Gradle 仍承担推送、通知、Deep Link、运行时权限、文件选择、分享、后台恢复，以及必要原生 Plugin。
|
||
|
||
### 4.2 Wails v3：Go Host 候选
|
||
|
||
Wails 的 Go 技术栈与 LineUp 的服务端、协议校验、同步、Outbox、Capability Policy 和审计逻辑高度匹配，长期上有明显的维护优势。官方 GitHub README 当前将 Wails v3 标记为 `Beta`；本次核验也没有取得足够的官方 Android 生产支持证据。因此不把它作为第一轮 Runtime 安全边界的验证载体，但在 Tauri 基线明确后，应以同一协议和验收范围做正式对照实现。
|
||
|
||
重点评估 Wails v3 是否能以 Go Host 达到 Tauri Reference Host 的小程序隔离、资源加载、桥接、生命周期、移动端系统能力与恢复标准；若能达到，Go 主栈优势将使其成为长期主方案的强候选。
|
||
|
||
## 5. LineUp Mini Runtime 与 Tauri Reference Host
|
||
|
||
```text
|
||
LineUp Tauri Reference Host
|
||
├── Web Frontend
|
||
│ ├── Chat UI / 虚拟列表
|
||
│ ├── CommonMark / GFM Markdown
|
||
│ ├── ConversationItem + Renderer Registry
|
||
│ ├── 标准组件库
|
||
│ ├── Surface Host
|
||
│ └── WebSocket + HTTP 补偿
|
||
├── Rust / Tauri Core
|
||
│ ├── 安全 capability policy
|
||
│ ├── 会话 / token 安全存储
|
||
│ └── 原生 bridge 管理
|
||
└── Android Kotlin 壳
|
||
├── Push / 通知 / Deep Link
|
||
├── 文件、权限、系统分享
|
||
└── 必要的原生 Plugin
|
||
```
|
||
|
||
Tauri 的 Web Frontend 与第三方 Surface 必须是两个不同的安全域。LineUp 自有前端可以调用受控原生能力；Agent 或第三方 Surface 只能通过经过校验的事件协议请求能力，绝不能获得 Tauri `invoke`、登录 token 或宿主 DOM 的直接访问权。
|
||
|
||
### 5.1 Mini Runtime 的框架无关边界
|
||
|
||
Mini Runtime 是可被 Tauri、Wails 或原生 Shell 实现的协议层，最小由以下模块组成：
|
||
|
||
```text
|
||
Package Manager app_id / version / manifest / integrity / allowlist
|
||
Instance Manager instance_id / open / ready / patch / close / restore
|
||
Secure Loader 不可变 bundle / 专用 origin / CSP / 网络与跳转限制
|
||
Event Bridge postMessage schema、大小、频率、来源与实例校验
|
||
Mini API ui.onPatch / ui.emit / app.call / app.result
|
||
Capability Gateway policy / 用户确认 / 平台 handler / audit
|
||
```
|
||
|
||
第三方小程序只能获得 Mini API，不能直接获得 Tauri 或 Wails 的原生调用对象。内置 Renderer 与标准组件可运行于可信主应用前端；小程序 Surface 则必须运行于隔离执行域。
|
||
|
||
## 6. 不可退让的安全约束
|
||
|
||
1. Agent bundle 与第三方 Surface 一律视为不可信输入。
|
||
2. Surface iframe 不得访问 Tauri invoke API、宿主登录态或宿主 DOM。
|
||
3. 仅允许完成实例、命名空间、事件名和消息大小校验的 `postMessage` bridge。
|
||
4. CSP 默认禁止未授权网络、远程脚本和危险跳转。
|
||
5. `ui.patch` 只能更新 JSON state，不能替换已验证 bundle。
|
||
6. 所有系统能力只允许走 `app.call → Capability Registry → 用户确认 → app.result`。
|
||
7. Android 的推送、通知、后台恢复与权限结果必须可审计、可恢复，不能依赖一个不受控网页生命周期。
|
||
|
||
## 7. Tauri Reference Host Spike 范围与验收
|
||
|
||
Spike 单独建立目录或模块，接入同一 App Server、WuKongIM、Hermes 与测试会话；不得改写当前 Kotlin Android 的可运行路径。先以桌面验证主应用与小程序双安全域，再进入 Android 真机验证。
|
||
|
||
- [ ] 真机登录现有 App Server；
|
||
- [ ] 兼容 HTTP `/messages/sync`，为服务端 WSS 留出接入点；
|
||
- [ ] 完整 GFM Markdown 与 DOMPurify 安全净化；
|
||
- [ ] 兼容 `text / status / progress / tool.call / tool.result`；
|
||
- [ ] 实现 `ui.open / patch / close / event` sandbox Surface；
|
||
- [ ] 实现 `app.open_url` 与 `clipboard.write` 的 Capability bridge；
|
||
- [ ] PJD110 真机安装、滚动性能、断线恢复与安全隔离通过；
|
||
- [ ] 与既有 Kotlin 客户端对照确认消息顺序、去重、用户操作回传一致。
|
||
|
||
Wails v3 的第二阶段 Spike 使用以上相同清单。其目标不是重定义协议，而是证明 Go Host 能够以相同小程序包和安全边界完成等价交付。
|
||
|
||
## 8. 本机构建级验证前置条件
|
||
|
||
| 条件 | 当前状态 |
|
||
|---|---:|
|
||
| Android SDK / Gradle / 项目内 JDK 17 | 已有 |
|
||
| Kotlin APK 构建与真机安装 | 已验证 |
|
||
| Rust / Cargo | 已安装；本机 Rustup proxy 有清单异常，直接工具链 bin 可用 |
|
||
| Tauri CLI | 已作为 `lineup-app/tauri/` 的 npm 开发依赖安装 |
|
||
| Wails CLI | 未安装 |
|
||
| Android NDK | 未安装 |
|
||
| Tauri / Wails 现有工程 | Tauri Reference Host 已建立于 `lineup-app/tauri/`；Wails 尚未建立 |
|
||
|
||
Tauri Spike 已进入实现阶段：前端生产构建、Linux debug 二进制和 Debian 包均已生成；Android 真机 Spike 仍需 Android NDK 与 Rust Android targets。当前 Kotlin Android 实验工程保持不变。
|