lineup/app
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat(runtime): establish miniapp kernel and sdk design

Browse Source
This commit is contained in:
kyugao
2026-08-05 00:46:16 +08:00
parent d8aa087bc8
commit 9fb8cd1598
86 changed files with 4615 additions and 1364 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tauri/README.md
+39 -20
View File
@@ -1,6 +1,15 @@
# LineUp Tauri Reference Host
这是 LineUp Mini Runtime 的第一版 Tauri 2 Reference Host。它独立于当前 `upstream/tangsengdaodao-android/` 快速实验工程，不替换或修改现有 Android 验证路径。
这是同一套 LineUp Runtime 的两种运行方式：Tauri 2 Desktop Host 和 Web Reference Host。
它们不是两个客户端，也不是两套聊天功能；两者加载相同的 Runtime 和 Chat Core App。
- **Tauri Desktop Host** 是正式桌面应用的外壳。它提供窗口，并在 Runtime 作出授权决定后
调用文件、通知等系统能力。
- **Web Reference Host** 是浏览器中的开发和验证入口。它方便通过 Vite 热更新、
Tailscale 联调和自动化测试，但受浏览器权限限制，不能替代桌面外壳。
无论使用哪种方式，AppServer 通信、消息同步、Store 和 Agent 协议都由 Runtime 管理。
当前不存在并行的独立 Android/Kotlin 或 Wails 客户端路线。
## 已实现的最小闭环
@@ -16,7 +25,7 @@ AppServer 已配置只允许 `tauri://localhost`、`https://tauri.localhost`、`
macOS 的 `src-tauri/Info.plist` 为当前 Tailscale / 私网 HTTP AppServer 配置了 `NSAllowsArbitraryLoadsInWebContent`。该例外仅作用于 Host 的 WKWebView 内容请求，使其能访问类似 `http://100.x.y.z:8090` 的地址，不放宽 Rust 原生网络层；待所有 AppServer 都迁移到 HTTPS 后应移除。
`ui.open / patch / close` 和 `app.call` 已被协议层识别，但目前安全降级为可见提示；它们是下一阶段 Mini Runtime Surface Host 与 Capability Registry 的实现范围，不能在当前 Host 页面中直接执行 Agent JavaScript 或直接授予设备能力。
Surface、Capability、签名 Bundle 与隔离 bridge 已有 M2～M4 的实现和测试基础，但它们不等于已开放的应用市场或通用 Installed App。当前 MVP-R1 的重点是 Runtime 托管 Chat：任何 Surface 或能力请求仍必须经过 Runtime 验证、受限 bridge、Capability Policy 和用户确认，不能在 Host 页面中直接执行 Agent JavaScript 或直接授予设备能力。
## Milestone 0 当前行为基线
@@ -24,14 +33,14 @@ macOS 的 `src-tauri/Info.plist` 为当前 Tailscale / 私网 HTTP AppServer 配
| 范围 | 当前行为 | 当前实现位置 | 重构后必须保持 |
|---|---|---|---|
| 登录 | 用户输入 AppServer 地址、手机号、验证码；登录请求 10 秒超时；地址仅保存到 localStorage | `src/main.ts`、`src/runtime/transport-adapter.ts` | 成功登录进入会话；失败原因对用户可见 |
| 登录 | 用户输入 AppServer 地址、手机号、验证码；登录请求 10 秒超时；地址仅保存到 localStorage | `src/main.ts`、`src/runtime/communication/transport-adapter.ts` | 成功登录进入会话；失败原因对用户可见 |
| 会话 | 当前只有一个 Agent channel；退出清空页面内消息并停止同步 | `src/main.ts` | 会话状态必须可由 Store 管理，不能依赖 DOM |
| 发送 | 用户消息先本地显示，再通过 Transport 调用 `/messages/send`；显示已发送或失败 | `src/main.ts`、`src/runtime/transport-adapter.ts` | 即时反馈、送达状态与失败可见性不退化 |
| 历史同步 | 首次从 cursor `0` 连续拉取到空页；之后以 `lastSeq + 1` 每 1.5 秒经 Transport 增量轮询 | `src/main.ts`、`src/runtime/transport-adapter.ts` | 保持包含式 cursor 语义，不能漏消息或无限热循环 |
| Agent 文本 | 将 `lineup.v1.text` 解码为 Markdown，使用 `marked + DOMPurify` 渲染 | `src/protocol.ts`、`src/runtime/trusted-dom-renderers.ts` | GFM、安全净化和外链防护不退化 |
| Agent 状态 | `thinking` 显示临时指示器；其他状态更新顶栏 presence | `src/protocol.ts`、`src/runtime/trusted-dom-renderers.ts` | 状态应更新已有状态项，而非无限追加气泡 |
| 进度和错误 | progress/error 目前以系统提示显示 | `src/protocol.ts`、`src/runtime/trusted-dom-renderers.ts` | 迁移后至少保持可见，M1 再升级为正式卡片 |
| 未实现扩展 | `ui.open / patch / close` 与 `app.call` 仅安全降级为提示，绝不执行不可信脚本或原生能力 | `src/protocol.ts`、`src/main.ts` | 在 M2/M3 完成前始终保持拒绝执行 |
| 发送 | 用户消息先本地显示，再通过 Transport 调用 `/messages/send`；显示已发送或失败 | `src/main.ts`、`src/runtime/communication/transport-adapter.ts` | 即时反馈、送达状态与失败可见性不退化 |
| 历史同步 | 首次从 cursor `0` 连续拉取到空页；之后以 `lastSeq + 1` 每 1.5 秒经 Transport 增量轮询 | `src/main.ts`、`src/runtime/communication/transport-adapter.ts` | 保持包含式 cursor 语义，不能漏消息或无限热循环 |
| Agent 文本 | 将 `lineup.v1.text` 解码为 Markdown，使用 `marked + DOMPurify` 渲染 | `src/runtime/protocol/lineup-v1.ts`、`src/core-apps/chat/trusted-dom-renderers.ts` | GFM、安全净化和外链防护不退化 |
| Agent 状态 | `thinking` 显示临时指示器；其他状态更新顶栏 presence | `src/runtime/protocol/lineup-v1.ts`、`src/core-apps/chat/trusted-dom-renderers.ts` | 状态应更新已有状态项，而非无限追加气泡 |
| 进度和错误 | progress/error 目前以系统提示显示 | `src/runtime/protocol/lineup-v1.ts`、`src/core-apps/chat/trusted-dom-renderers.ts` | 迁移后至少保持可见，M1 再升级为正式卡片 |
| 未实现扩展 | `ui.open / patch / close` 与 `app.call` 仅安全降级为提示，绝不执行不可信脚本或原生能力 | `src/runtime/protocol/lineup-v1.ts`、`src/main.ts` | 在 M2/M3 完成前始终保持拒绝执行 |
### M0 回归场景
@@ -52,7 +61,7 @@ M0-01～M0-08 已完成。Mac 经 Linux Tailscale Web Host `http://100.121.118.1
### M1-01 Tool Call 状态机（已完成）
`src/protocol.ts` 现可严格解码 `lineup.v1.tool.call`、`lineup.v1.tool.result`、`lineup.v1.tool.cancel`，只接受 `choice`、`confirm`、`input` 三种声明性请求。`src/runtime/tool-call-state.ts` 是独立于 UI、Storage、Transport、Tauri 与 Capability 的纯状态机；它以 `call_id` 为唯一关联键，只允许 `pending → submitted → completed / failed / cancelled / expired`，拒绝重复调用及非法状态跃迁。Interaction Kernel 仅投影这些状态，且只有已提交的 call 能接受 result。
`src/runtime/protocol/lineup-v1.ts` 现可严格解码 `lineup.v1.tool.call`、`lineup.v1.tool.result`、`lineup.v1.tool.cancel`，只接受 `choice`、`confirm`、`input` 三种声明性请求。`src/runtime/coordination/tool-call-state.ts` 是独立于 UI、Storage、Transport、Tauri 与 Capability 的纯状态机；它以 `call_id` 为唯一关联键，只允许 `pending → submitted → completed / failed / cancelled / expired`，拒绝重复调用及非法状态跃迁。Interaction Kernel 仅投影这些状态，且只有已提交的 call 能接受 result。
这不是可用的交互组件：M1-01 不渲染选项、不提供按钮/表单、不发送 tool result，也不修改 Hermes Adapter。可信 ActionGroup 留给 M1-02，Confirm/Input/Form 留给 M1-03。`npm test` 当前为 3 个文件 / 14 个测试通过，`npm run build` 通过。
@@ -82,11 +91,11 @@ Conversation Store v5 持久化任务快照，刷新或重新登录后仍只显
### 当前结构债务（M0 的改造对象）
`src/main.ts` 目前包含 App Shell、页面 DOM、会话 cursor、同步循环与 Runtime 编排；M0-05 已将登录、发送与同步 HTTP `fetch` 迁入 `src/runtime/transport-adapter.ts`，M0-06 已将所有可信 DOM renderer 迁入 `src/runtime/trusted-dom-renderers.ts`。在 M0 准入前不新增 Surface 或 Capability 功能。
该段记录的是 M0 历史结构债务。当前 MVP-R1 已将 Transport、Store、sync loop 与 outbox 收敛至 `src/runtime/coordination/lineup-runtime.ts`；HTTP 实现位于 `src/runtime/communication/transport-adapter.ts`，可信 Chat DOM Renderer 位于 `src/core-apps/chat/trusted-dom-renderers.ts`。现行目录与边界见 [src/README.md](src/README.md)。
### M0-02 协议模型（已完成）
`src/protocol.ts` 是目前唯一允许把 Transport 原始 payload 转换成可信表现模型的入口。它定义了 `JsonValue`、`Actor`、严格 `Envelope`、`ConversationItem`、`UserAction`、`DeliveryState` 与 `ProtocolFallback`，并提供：
`src/runtime/protocol/lineup-v1.ts` 是目前唯一允许把 Transport 原始 payload 转换成可信表现模型的入口。它定义了 `JsonValue`、`Actor`、严格 `Envelope`、`ConversationItem`、`UserAction`、`DeliveryState` 与 `ProtocolFallback`，并提供：
- `parseEnvelope(value)`：校验版本、消息类型、`id`、`conversation_id`、sender/target、timestamp 和 JSON payload；
- `parseEnvelopeJSON(raw)`：供不接受历史纯文本的 Transport / Kernel 路径把非法 JSON 明确归为 `invalid_json`；
@@ -96,9 +105,9 @@ Conversation Store v5 持久化任务快照，刷新或重新登录后仍只显
### M0-03 Interaction Kernel 与 Renderer Registry（已完成）
`src/runtime/interaction-kernel.ts` 是 Transport 与表现层之间的唯一入口：它将原始同步/实时 payload 解码为 `ConversationItem`，对有有效 LineUp `id` 的消息实施有界去重，并将 Agent status 投影为可读取的 presence 快照。它不执行 `ui.*`、`app.*` 或用户动作。
`src/runtime/coordination/interaction-kernel.ts` 是 Transport 与表现层之间的唯一入口：它将原始同步/实时 payload 解码为 `ConversationItem`，对有有效 LineUp `id` 的消息实施有界去重，并将 Agent status 投影为可读取的 presence 快照。它不执行 `ui.*`、`app.*` 或用户动作。
`src/runtime/renderer-registry.ts` 只根据已验证的 `ConversationItem.kind` 分派已注册的可信 renderer；renderer 的输入只有表现项与 View context，不会获得 Transport 或 Capability 对象。当前聊天页已通过该 Registry 渲染同步进入的标准项。历史上 M0-03 完成时具体 DOM renderer 仍在 `main.ts`；该 M0-06 迁移现已完成，当前可信 DOM renderer 位于 `src/runtime/trusted-dom-renderers.ts`。
`src/core-apps/chat/renderer-registry.ts` 只根据已验证的 `ConversationItem.kind` 分派已注册的可信 renderer；renderer 的输入只有表现项与 View context，不会获得 Transport 或 Capability 对象。当前聊天页已通过该 Registry 渲染同步进入的标准项。历史上 M0-03 完成时具体 DOM renderer 仍在 `main.ts`；该 M0-06 迁移现已完成，当前可信 DOM renderer 位于 `src/core-apps/chat/trusted-dom-renderers.ts`。
## 本地命令
@@ -127,7 +136,13 @@ npm run tauri build -- --debug
`npm run desktop:dev` 不生成 `.app`、`.dmg` 或安装包。前端 TypeScript / CSS / HTML 保存后会由 Vite 自动热更新；改动 `src-tauri/` 中的 Rust Host 代码时，Tauri 会重新编译并重启开发窗口。只有需要交付可安装文件时才执行 `tauri build`。
`npm run web:dev` 只运行同一份可信 Host Web UI，适合在浏览器中快速调试登录、消息和 Renderer。它监听 `0.0.0.0:1420`，Mac 通过 Tailscale 打开 `http://100.121.118.116:1420`，直接验证 Linux 工作区的 Vite 热更新；不需要为每次验证将源码同步到 Mac。它不具备 Tauri 原生能力，也不应作为第三方 Mini Runtime Surface 的安全验收环境。AppServer 仅对固定开发 Origin `http://127.0.0.1:1420` 和 `http://100.121.118.116:1420` 配置 CORS；若改动 Vite 端口或 Host 地址，必须同步收紧更新 AppServer 的 `client.allowedOrigins`，不得改为 wildcard。
`npm run web:dev` 是在浏览器里启动同一份可信 Host UI，适合快速检查登录、消息和
Renderer。它监听 `0.0.0.0:1420`；Mac 可经 Tailscale 打开
`http://100.121.118.116:1420`，直接看到 Linux 工作区的 Vite 热更新，无须把源码同步到
Mac。浏览器模式没有 Tauri 的原生能力，也不能用作第三方 Mini Runtime Surface 的安全验收
环境。AppServer 只对固定开发 Origin `http://127.0.0.1:1420` 和
`http://100.121.118.116:1420` 配置 CORS；若改动 Vite 端口或 Host 地址，必须同步更新并
保持收紧 AppServer 的 `client.allowedOrigins`，不得改成允许任意来源的 wildcard。
本项目的 `tauri` 与 `check:rust` npm 脚本会自动识别 Linux x86_64、macOS Apple Silicon、macOS Intel 的 Rust stable toolchain，并加入 `PATH`。因此不要直接执行裸 `tauri build`；统一使用 `npm run tauri build -- --debug`。如 Rust toolchain 安装在其他位置，可临时覆盖：
@@ -140,7 +155,7 @@ RUST_TOOLCHAIN_BIN=/path/to/rust/bin npm run tauri build -- --debug
- `npm run build`：已通过；
- Cargo/Tauri Rust crates：已下载并开始编译；
- Tauri Linux desktop build：已通过；debug 可执行文件和 Debian 包已生成；
- Android Spike：尚未开始。仍需要 Android NDK、Rust Android targets 与 Tauri Android 初始化。
- 独立 Android/Kotlin 与 Wails Host：不在当前或后续规划范围内。
Linux 桌面构建依赖以下系统开发库；本机已具备。新环境缺少时可安装：
@@ -156,17 +171,21 @@ src-tauri/target/debug/lineup-tauri
src-tauri/target/debug/bundle/deb/LineUp_0.1.0_amd64.deb
```
Tauri 构建产物位于 `src-tauri/target/`，已被 Git 忽略。图标源文件是 `src-tauri/icons/icon.svg`，其余 PNG/ICO/ICNS 与 Android/iOS 图标由 `npm run tauri icon src-tauri/icons/icon.svg` 生成。
Tauri 构建产物位于 `src-tauri/target/`，已被 Git 忽略。图标源文件是 `src-tauri/icons/icon.svg`；当前交付只面向 Tauri Desktop Host，其他图标派生产物不代表额外客户端路线。
## 目录边界
```text
tauri/
├── src/ # 可信 LineUp Host 前端
│ ├── main.ts # 会话 UI、AppServer transport、Renderer 调度
│ └── protocol.ts # 平台无关的 LineUp v1 → ConversationItem 解码
├── src/
│ ├── main.ts # 应用启动装配入口：连接 Host、Runtime 与默认 App
│ ├── core-apps/chat/ # Chat Shell、可信 Renderer 与样式
│ └── runtime/ # 按通信、协调、存储、应用、Surface、能力等分层
├── src-tauri/ # Tauri Rust Host 与 capability 配置
├── vite.config.ts # @/ → src/ 路径别名（Vite / Vitest）
└── package.json # Vite、Tauri CLI 与前端依赖
```
各 Runtime 子目录、依赖方向与新增模块约定见 [src/README.md](src/README.md)。
第三方 Agent Surface 未来必须运行于独立隔离执行域，只能经 LineUp Mini Runtime 事件桥与 Capability Gateway 通信；不得访问 Tauri `invoke`、Host DOM、登录态或本机特权。