docs(lineup-app): organize current design documents

2026-08-06 11:34:51 +08:00
parent 81470ffea7
commit 7e94713174
14 changed files with 1947 additions and 26 deletions
@@ -0,0 +1,132 @@
+# 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 的迁移价值。 |