feat(runtime): establish miniapp kernel and sdk design

2026-08-05 00:46:16 +08:00
parent d8aa087bc8
commit 9fb8cd1598
86 changed files with 4615 additions and 1364 deletions
@@ -0,0 +1,61 @@
+# Tauri / Web Reference Host 源码导航
+
+`src/` 是 LineUp 的前端实现目录。可以把它理解为三层协作：Runtime 负责连接、状态、
+存储和恢复；Chat 是用户首先看见的聊天功能；Tauri 或浏览器则是装载这套程序的运行外壳。
+同一份源码既可放进正式桌面窗口，也可在浏览器中用于开发和验证。
+
+`main.ts` 是应用启动时的装配入口：它把 Host 侧实现、`LineUpRuntime` 和默认 Core App
+接起来。它不负责网络收发、消息存储、同步循环或原始 Agent 消息解析；这些都由 Runtime
+统一管理。
+
+```text
+src/
+├── main.ts                         # 启动装配入口：连接 Tauri/Web Host、Runtime 与默认 App
+├── core-apps/
+│   └── chat/                       # 第一个可信 Core App
+│       ├── chat-app-host.ts         # Chat 的 Host 装配器：样式、Shell、Renderer 与 SDK
+│       ├── chat-shell.ts            # Chat 的 DOM Shell
+│       ├── trusted-dom-renderers.ts # 已验证消息 → 可信 DOM
+│       ├── renderer-registry.ts     # Chat Renderer 分派
+│       └── styles/                  # Chat 专属样式
+└── runtime/
+    ├── app-management/             # Core App Registry、Chat SDK、App Host
+    ├── artifacts/                  # Artifact 元数据与短生命周期内容缓存
+    ├── capabilities/               # Capability Registry、状态机、审计与执行器
+    ├── communication/              # AppServer Transport
+    ├── coordination/               # Runtime、Kernel、scope 路由、Tool/Task 状态
+    ├── inventory/                  # Agent 可见 Client/Tool Inventory
+    ├── persistence/                # Conversation Store、Outbox、App Inbox
+    ├── protocol/                   # LineUp v1 解码与 golden fixture
+    └── surfaces/                   # Surface Registry、实例、Bundle 与隔离 Host
+```
+
+## 谁可以依赖谁
+
+```text
+core-apps/chat ──ChatRuntimeSDK──► runtime/app-management
+                                      │
+      Host adapters ───────────────► runtime/coordination/LineUpRuntime
+                                      │
+              communication · persistence · protocol · capabilities
+                                      │
+                                    surfaces / inventory / artifacts
+```
+
+- App 不直接导入 `communication`、`persistence` 或原始协议解码模块；Chat 通过
+  `ChatRuntimeSDK` 接收已筛选的状态、消息和 Inbox，并以 Runtime Action 发起用户动作。
+  简单说，Chat 可以向 Runtime 说“请发送这段文字”，但不能自己连服务器或改数据库。
+- `CoreAppRegistry` 决定默认启动哪个应用；`CoreAppHostRegistry` 决定如何挂载这个应用。
+  当前注册的实现仍是 `chat`，但 `main.ts` 不再直接导入 Chat 的样式、Renderer 或 DOM
+  Shell。
+- Runtime 通过 `openApp(app_scope)` 打开对应的 SDK 投影；`openChatApp()` 只作为旧调用方的
+  兼容别名，新的 Core App Host 应使用注册表作用域打开 SDK。
+- `runtime/coordination/lineup-runtime.ts` 是 Transport、Store、sync loop 和 outbox
+  的唯一所有者。
+- 每个模块的测试与实现同目录放置；`runtime/protocol/golden/` 保存兼容协议 fixture。
+- `@/` 指向 `src/`，由 `tsconfig.json` 与 `vite.config.ts` 共同配置。新增代码应使用该
+  别名，避免跨层的相对路径依赖。
+
+未来新增 `voice`、`whiteboard` 等 Core/Installed App 时，应给它们各自的目录和 SDK
+投影；不能把页面、网络连接或持久化逻辑重新堆回 `main.ts`。这样新应用只增加自己的体验，
+不会破坏已有聊天和连接逻辑。