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,159 @@
+# LineUp App 程序文件清单与功能说明
+
+> 最后核验：2026-08-04（Asia/Shanghai）
+>
+> 本文是 `lineup-app/` 的客户端源码导航，覆盖 Tauri/Desktop Host、Web Reference Host、
+> `LineUpRuntime`、Interact MiniApp（当前兼容名 Chat）与客户端测试。跨项目的 AppServer、Hermes Adapter、
+> WuKongIM 和运行配置见[根程序文件清单](../程序文件清单与功能说明.md)。
+
+## 1. 当前客户端怎样运行
+
+LineUp 不是“聊天页面直接连 Agent”。用户首先打开的是一个运行外壳：正式交付时是 Tauri
+桌面窗口，开发和联调时可在浏览器中打开 Web Reference Host。两种外壳都会启动同一个
+Runtime；Runtime 再加载默认 Chat，并负责 Chat 与 AppServer / Remote Agent 之间的全部
+通信。
+
+```text
+Tauri Desktop Host / Web Reference Host
+  → main.ts（启动时把 Host、Runtime 与默认 App 接起来）
+  → LineUpRuntime
+  → CoreAppRegistry → chat Core App
+  → ChatRuntimeSDK
+  → AppServer / Remote Agent
+```
+
+当前唯一的客户端实现与验收基线是 Tauri 2 Desktop Host + Web Reference Host。两种 Host
+复用同一份 TypeScript Runtime 与 Chat Core App，不是两套客户端。`main.ts` 只在启动时把
+Host、`LineUpRuntime` 和默认 App 接起来；网络传输、消息存储、同步循环、待发送队列、
+scope 路由和旧 `lineup.v1` 兼容都由 Runtime 统一管理。
+
+## 2. 工作区顶层文件
+
+| 文件 / 目录 | 功能 |
+|---|---|
+| `README.md` | LineUp App 工作区入口、当前实现摘要、开发与文档导航。 |
+| `程序文件清单与功能说明.md` | 本文：客户端源码与测试导航。 |
+| `APP架构设计.md` | LineUp App、Runtime、MiniApp SDK、Surface/Capability 安全、发布约束和后续路线。 |
+| `tauri/` | Tauri Desktop Host 与 Web Reference Host 的工程目录。 |
+
+## 3. Tauri/Web 工程入口
+
+目录：`tauri/`
+
+| 文件 / 目录 | 功能 |
+|---|---|
+| `package.json` | Vite、Vitest、Tauri CLI 与开发/构建脚本。 |
+| `vite.config.ts` | Vite/Vitest 的 `@/ → src/` 源码别名。 |
+| `tsconfig.json` | TypeScript 严格检查与同一 `@/` 路径别名。 |
+| `index.html` | Vite 页面入口。 |
+| `scripts/tauri.sh` | Tauri/Rust 工具链包装脚本。 |
+| `src/` | TypeScript Host、Runtime、Core App 与测试。 |
+| `src-tauri/` | Tauri Rust Host、窗口配置、能力声明和图标。 |
+| `README.md` | Tauri/Web Host 的运行、构建、回归和历史里程碑。 |
+
+## 4. TypeScript Runtime 与 Chat Core App
+
+目录：`tauri/src/`。完整依赖方向见 [src/README.md](tauri/src/README.md)。
+
+### 4.1 Host 组合与 Chat Core App
+
+| 文件 / 目录 | 功能 |
+|---|---|
+| `main.ts` | 应用启动装配入口：创建 Runtime，并请求通用 `RuntimeAppHost` 根据 App Registry 挂载默认 Core App。它不直接导入 Chat Renderer，也不拥有网络传输、消息存储、同步循环或待发送队列。 |
+| `core-apps/chat/chat-shell.ts` | Chat Core App 的可信 DOM Shell。 |
+| `core-apps/chat/chat-app-host.ts` | Chat Core App 的 Host 装配器：集中加载 Chat 样式、Shell、Renderer、DOM 上下文和 Chat SDK，避免这些细节进入 `main.ts`。 |
+| `core-apps/chat/trusted-dom-renderers.ts` | 已验证消息到可信 DOM：Markdown、消息、交互卡、任务、执行摘要、Surface、Capability、Artifact 与 fallback。 |
+| `core-apps/chat/renderer-registry.ts` | 按受信任 `ConversationItem.kind` 分派 Chat Renderer。 |
+| `core-apps/chat/styles/` | Chat Shell、能力卡片、执行摘要样式。 |
+
+### 4.2 App 管理、SDK 与 Runtime 协调
+
+| 文件 | 功能 |
+|---|---|
+| `runtime/coordination/lineup-runtime.ts` | Runtime 唯一协调器：持有 Transport、Conversation Store、sync loop、outbox、scope 筛选、`lineup.v1` 兼容、可靠 App Inbox 与 Chat SDK 投影。 |
+| `runtime/app-management/app-registry.ts` | 本地 Core App Registry；当前静态注册默认/恢复 `chat`。 |
+| `runtime/app-management/app-sdk.ts` | 当前 Chat/IM Runtime SDK：Core App 与 Runtime 之间的受限接口；提供状态/消息订阅、Inbox ACK、Runtime Action、Tool/Task 投影。Runtime 通过 `openApp(app_scope)` 选择对应 SDK。 |
+| `runtime/app-management/runtime-app-host.ts` | 从 Runtime App Registry 解析默认 App，再通过 Core App Host Registry 找到对应装配器并挂载可信 Core App。 |
+| `runtime/coordination/interaction-kernel.ts` | 无副作用协议入口：decode、重复抑制、Agent 状态、Tool/Task 投影。 |
+| `runtime/coordination/runtime-envelope.ts` | 内部 `RuntimeEnvelope`、`app_scope + conversation_id` 校验及旧协议作用域映射。 |
+| `runtime/coordination/tool-call-state.ts` | `choice / confirm / input` 交互状态机。 |
+| `runtime/coordination/task-state.ts` | `agent.progress` 按 `operation_id` 聚合。 |
+| `runtime/coordination/execution-progress-state.ts` | 按 `execution_id` 关联 ACP 实时步骤。 |
+
+### 4.3 通信、持久化与协议
+
+| 文件 | 功能 |
+|---|---|
+| `runtime/communication/transport-adapter.ts` | HTTP Transport：登录、发送、同步、超时和响应校验。 |
+| `runtime/persistence/conversation-store.ts` | 会话持久化：cursor、消息、typed outbox、App Inbox、Tool/Task、摘要、Surface/Capability 快照。 |
+| `runtime/protocol/lineup-v1.ts` | LineUp v1 受限协议模型与解析边界。 |
+| `runtime/protocol/golden/lineup-v1.json` | `lineup-v1-golden-1` Runtime compatibility fixture。 |
+
+### 4.4 Surface、能力、Artifact 与 Inventory
+
+| 文件 | 功能 |
+|---|---|
+| `runtime/surfaces/surface-registry.ts` | 开发期 Surface Manifest 与本地启用注册表；仅精确 app id/version 可用。 |
+| `runtime/surfaces/surface-instance-manager.ts` | `open / ready / patch / close / restore` 的纯状态生命周期、幂等与冲突拒绝。 |
+| `runtime/surfaces/isolated-surface-host.ts` | opaque-origin iframe 宿主；`sandbox="allow-scripts"`、严格 CSP、仅受限 bridge。 |
+| `runtime/surfaces/production-surface-manifest.ts` | 生产 Manifest：immutable artifact、版本、大小、SHA-256、Ed25519、key id、最小 Host、权限 allowlist。 |
+| `runtime/surfaces/production-surface-policy.ts` | production admission policy：只允许已验证的精确 app/version 创建实例。 |
+| `runtime/surfaces/surface-bundle-cache.ts` | HTTPS 下载、Ed25519 验签、大小/SHA-256 校验、verified cache、失效与回滚。 |
+| `runtime/inventory/client-inventory.ts` | 生成 revisioned `lineup.v1.client.inventory`。 |
+| `runtime/capabilities/capability-registry.ts` | 能力声明、风险等级、可见性与参数 schema 校验。 |
+| `runtime/capabilities/capability-call-state.ts` | 能力调用状态机：`pending → approved → executing → terminal`。 |
+| `runtime/capabilities/capability-executor.ts` | 调用 Host handler，并将结果归约为安全确定的 `app.result`。 |
+| `runtime/capabilities/capability-audit.ts` | 最小审计：call id、能力、风险、处置、时间；不保存敏感参数。 |
+| `runtime/artifacts/artifact-state.ts` | Artifact 元数据状态：名称、MIME、大小、完整性。 |
+| `runtime/artifacts/artifact-content-cache.ts` | Host-owned 易失内容缓存；内容不进入 Conversation Store。 |
+
+## 5. Tauri Rust Host
+
+目录：`tauri/src-tauri/`
+
+| 文件 | 功能 |
+|---|---|
+| `src/main.rs` | Tauri 桌面二进制入口。 |
+| `src/lib.rs` | Tauri 应用构造与运行库入口。 |
+| `tauri.conf.json` | 窗口、应用元数据与构建配置。 |
+| `capabilities/default.json` | Tauri 权限声明；当前只保留核心默认能力。 |
+| `Info.plist` | macOS WebView / ATS 兼容配置。 |
+| `build.rs` | Tauri/Rust 构建脚本入口。 |
+
+## 6. 客户端测试与构建
+
+各 `src/runtime/**` 模块的 `.test.ts` 与实现同目录放置，主要覆盖 Runtime/SDK、协议与
+Kernel、Store/App Inbox、Tool Call、Task、执行摘要、Surface、Capability、Artifact、
+生产 Bundle 与 golden fixture。
+
+`runtime/coordination/lineup-runtime.test.ts` 覆盖 MVP-R1 的 Core App Registry、scope
+筛选、`lineup.v1` 兼容、App Inbox 恢复、去重和 Runtime Action 边界；
+`runtime/app-management/runtime-app-host.test.ts` 验证默认 Chat 由 Runtime Registry 加载。
+
+```bash
+cd lineup-app/tauri
+
+# Runtime / SDK / Renderer 自动化回归
+npm test -- --run
+
+# TypeScript 检查与 Web production build
+npm run build
+
+# Web Reference Host（Tailscale 开发）
+npm run web:dev
+
+# Tauri Desktop Host
+npm run desktop:dev
+```
+
+当前验证基线：23 个测试文件、99 个测试通过，`npm run build` 通过。
+
+## 7. 相关文档
+
+- [工作区 README](README.md)：产品基线、MVP-R1、开发入口与文档导航。
+- [迭代基线与目标](迭代/00.base.md)：`00.base` 已实现内容和 `01.kernel` Runtime Kernel 目标。
+- [APP 架构设计](APP架构设计.md)：LineUp App、Runtime、MiniApp SDK、发布安全与后续阶段。
+- [Tauri/Web 源码导航](tauri/src/README.md)：目录边界与依赖方向。
+- [Tauri/Web Host README](tauri/README.md)：Host 运行、构建、行为回归与历史记录。
+- [根程序文件清单](../程序文件清单与功能说明.md)：AppServer、Hermes、WuKongIM 和运行配置。
+- [App 最终设计方案](../设计/02.正式方案/app_final_design.md)：架构决策的唯一汇总入口。