# LineUp App 层架构与迁移记录

**版本：** 2.0（Runtime 基线）
**状态：** 当前实现边界与历史迁移记录
**日期：** 2026-08-04
**最终决策入口：** [LineUp App 最终设计方案](app_final_design.md)

## 1. 当前结论

LineUp 是运行在用户设备上的协作 Runtime，不是某个平台上的独立聊天客户端。可以把
Runtime 理解为本地协调中心：它负责连接、消息、存储和恢复；`chat` 是它首先加载的可信
内置功能。未来的语音、画板、游戏和应用中心也必须使用同一套 Runtime / SDK 边界，不能
各自再建立一条到 Agent 的通信链路。

当前唯一实现与验收基线：

```text
Tauri 2 Desktop Host + Web Reference Host
```

这两个 Host 是同一套 TypeScript Runtime 的两种外壳：Tauri Desktop Host 用于正式桌面
交付及受控系统能力；Web Reference Host 用于浏览器开发、Tailscale 联调和自动化测试。
它们不是两套产品，Web 版也不能替代桌面版的系统能力。独立 Android/Kotlin 客户端与
Wails Host 均不在当前或后续规划范围内；早期实验细节仅保留在 Git 历史，不构成架构或
验收依据。

## 2. App 层边界

```text
Remote Agent / AppServer
          │  lineup.v1 wire protocol
          ▼
┌────────────────────────────────────────────────────────┐
│                     LineUpRuntime                       │
│ Transport · sync loop · Store · Outbox · App Inbox      │
│ scope 路由 · Compatibility Adapter · Tool · Capability  │
└─────────────────────┬──────────────────────────────────┘
                      │ Runtime SDK
                      ▼
┌────────────────────────────────────────────────────────┐
│                  Core / Installed App                   │
│         chat · app-registry · voice · whiteboard        │
└────────────────────────────────────────────────────────┘
```

| 层 | 必须负责 | 不得负责 |
|---|---|---|
| `LineUpRuntime` | 处理 AppServer/Agent 通信、会话、原始协议兼容、scope 筛选、Store、sync、outbox、App Inbox、Tool 路由、App 实例和前台焦点、权限与恢复。 | 具体业务页面 DOM。 |
| Interaction Core App | 用户实际使用的主交互界面：当前是 Chat/IM，未来包含 Audio/Video 模式、标准交互原语和扩展结果投影。 | 直连 AppServer、维护 cursor、解析 Agent 原始包、调度其他 App 或直接写 Runtime Store。 |
| Runtime SDK | App 与 Runtime 之间唯一的受限接口：提供 snapshot、订阅、Agent 消息、Inbox ACK、Runtime Action、App 导航和生命周期请求。 | 把 Transport、token、Host 特权 API 暴露给 App。 |
| Tauri/Web Host | 把 Runtime 放进桌面窗口或浏览器，并提供对应的 DOM/系统能力。 | 解释协议、决定 App 调度、绕过 Runtime 路由和策略。 |
| Surface | 在隔离执行域呈现已验证 Bundle，并经受限 bridge 上报事件。 | 访问 Host DOM、登录态、Tauri API、任意网络。 |

## 3. MVP-R1：Runtime 托管 Chat

当前 MVP 已完成并以 Tauri/Web 自动化回归验证以下八项条件：

| 条件 | 当前事实 |
|---|---|
| MVP-01 | `LineUpRuntime` 唯一创建并持有 Transport、`ConversationStore`、sync loop 与 outbox。 |
| MVP-02 | Runtime 从本地 `CoreAppRegistry` 解析默认 `chat`，`RuntimeAppHost` 负责挂载其 Shell；`main.ts` 不创建聊天页面。 |
| MVP-03 | Chat 只经 `ChatRuntimeSDK` 订阅 Agent 消息、状态和 Chat-safe Runtime 事件，并以 Action 发送文本、交互、结果与取消。 |
| MVP-04 | Runtime 向 Chat 投递前验证 `app_scope = chat` 与当前 `conversation_id`；非法/不匹配消息被拒绝。 |
| MVP-05 | Compatibility Adapter 在 Runtime 内将旧 `lineup.v1` 映射为内部 `RuntimeEnvelope`；远端无须同步重写。 |
| MVP-06 | 登录、同步、发送、本地回显、Markdown、Agent 状态、Tool/Task 与刷新恢复保持回归。 |
| MVP-07 | Store 持久化每个 App 的 Inbox；运行时重建后未 ACK 消息可恢复，`message_id` 去重。 |
| MVP-08 | `npm test -- --run` 通过 21 个文件 / 94 个测试；`npm run build` 通过。 |

源代码目录和依赖方向见 [Tauri/Web 源码导航](../../tauri/src/README.md)。

## 4. 当前源码归属

```text
lineup-app/tauri/src/
├── main.ts                         # 启动装配入口：连接 Tauri/Web Host、Runtime 与默认 App
├── core-apps/chat/                 # 当前 Interaction App 的 IM 实现、Renderer、样式
└── runtime/
    ├── app-management/             # Registry、App Instance、焦点、生命周期、Host
    ├── communication/              # Transport Adapter
    ├── coordination/               # Runtime、Kernel、Envelope、Tool/Task/交互编排
    ├── persistence/                # Conversation Store、Outbox、App Inbox
    ├── protocol/                   # lineup.v1 解码与 golden fixture
    ├── surfaces/                   # Surface 生命周期、Bundle、隔离 Host
    ├── capabilities/               # Registry、执行、审计
    ├── artifacts/                  # Artifact 元数据与缓存
    └── inventory/                  # Agent 可见 Inventory
```

依赖必须保持单向：

```text
core-apps/interaction（当前 chat） → runtime/app-management SDK → runtime/coordination
                                         └→ communication / persistence / protocol
Host adapters → runtime/coordination
Surface → restricted bridge → Runtime Action / Capability Gateway
```

## 5. 历史迁移的保留价值

早期 M0～M4 工作建立了当前 Runtime 的可复用安全基础。它们是迁移记录，不是新的功能
排期或平行客户端路线：

| 历史阶段 | 保留成果 | 当前归属 |
|---|---|---|
| M0 | HTTP Transport、Conversation Store、协议解码、Markdown、基础回归 | `communication`、`persistence`、`protocol`、Chat Renderer |
| M1 | Tool Call、Task、可靠交互结果、受限执行摘要 | `coordination`、Chat SDK 投影 |
| M2 | 本地 Surface Registry、实例生命周期、隔离 iframe 与恢复 | `surfaces` |
| M3 | Capability Registry、用户确认、审计与受限 Host 执行 | `capabilities` |
| M4 | 签名 Manifest、Bundle 校验/缓存/回滚、golden fixture | `surfaces`、`protocol/golden` |

早期文档中的阶段性“尚未实现”或旧目录路径不得用来判断当前能力；需要审计细节时通过
Git 历史检索。

## 6. 后续阶段

```text
F2  持久化 App Registry、App Instance/Focus Manager、默认 App 切换
F3  Runtime Tool Router、动态 Inventory、可靠 App SDK Tool 闭环
F4  Interaction App 的 IM/Audio/Video 模式边界与第一个 Installed App
```

未来 App 必须复用 `app_scope + conversation_id`、Runtime SDK、Tool/Capability、Artifact、
Store、outbox 与恢复机制；禁止新建独立 Agent 通信通道。

## 7. 文档关系

| 文档 | 用途 |
|---|---|
| [app_final_design.md](app_final_design.md) | 当前产品、Runtime、App、SDK 与实施优先级的唯一汇总入口。 |
| [lineup-runtime-sdk-architecture.md](lineup-runtime-sdk-architecture.md) | Runtime / SDK 的详细接口与未来 App Manager 契约。 |
| [lineup-ui-surface-protocol.md](lineup-ui-surface-protocol.md) | Surface sandbox、bridge、Capability 和 Bundle 安全协议。 |
| 本文件 | 当前实现边界、源码归属与 M0～M4 的迁移价值。 |