# 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 实验工程保持不变。