docs(iteration): freeze sdk v1 contract fixtures
This commit is contained in:
@@ -0,0 +1,293 @@
|
||||
# LineUp App 迭代目标：Runtime Kernel 与应用编排
|
||||
|
||||
**迭代编号：** 01.kernel
|
||||
**状态：** 目标设计，待实现
|
||||
**日期：** 2026-08-04
|
||||
**前置基线：** [00.base.md](../00.base/00.base.md)
|
||||
|
||||
## 1. 迭代目标
|
||||
|
||||
本迭代要把 LineUp 从“Runtime 加载一个 Chat 页面”推进为“Runtime 管理一个应用工作区”。
|
||||
Runtime 不仅负责网络、消息和存储，还要负责应用实例、工具路由、前后台焦点和恢复；
|
||||
`Interaction App` 则负责用户与 Agent 的核心交互体验。
|
||||
|
||||
目标结构：
|
||||
|
||||
```text
|
||||
LineUp Runtime
|
||||
│
|
||||
├── Runtime Shell / Desktop
|
||||
│ ├── 应用启动
|
||||
│ ├── 应用切换
|
||||
│ ├── 前后台与焦点
|
||||
│ ├── 通知和安全恢复
|
||||
│ └── Host 挂载协调
|
||||
│
|
||||
├── Interaction App（Core App）
|
||||
│ ├── IM Mode：文字、图片、短消息
|
||||
│ ├── Audio Mode：实时语音
|
||||
│ ├── Video Mode：实时视频
|
||||
│ └── 标准交互原语：choice / confirm / input
|
||||
│
|
||||
└── Installed / Extension Apps
|
||||
├── Whiteboard
|
||||
├── Draw-and-Guess
|
||||
├── Task Dashboard
|
||||
└── 其他可安装应用
|
||||
```
|
||||
|
||||
当前代码中的 `chat` 继续作为兼容实现名称，产品概念上将其定位为：
|
||||
|
||||
```text
|
||||
Interaction App 的 IM 实现
|
||||
```
|
||||
|
||||
后续是否将目录和作用域从 `chat` 正式迁移到 `interaction`，另行作为命名迁移任务处理，
|
||||
不与本迭代的运行时编排重构混在一起。
|
||||
|
||||
## 2. 核心职责分工
|
||||
|
||||
### 2.1 LineUp Runtime
|
||||
|
||||
Runtime 是整个应用工作区的底层协调中心，拥有最终调度和安全决策权：
|
||||
|
||||
- 管理 App Registry、App Instance 和焦点栈；
|
||||
- 校验 Agent Tool Call、Manifest、Inventory、参数和作用域；
|
||||
- 决定调用应直接执行、启动 App、切换前台、等待用户交互还是创建异步任务；
|
||||
- 维护 App 的启动、运行、后台、挂起、恢复、关闭和失败状态；
|
||||
- 管理 Conversation、Store、App Inbox、outbox、权限和审计；
|
||||
- 在扩展 App 结束或启动失败时恢复原来的前台实例。
|
||||
|
||||
### 2.2 Runtime Shell / Desktop
|
||||
|
||||
Runtime Shell 是一个拥有特殊权限的内置工作区。它在产品体验上类似桌面或 Launcher，
|
||||
但最终的生命周期和安全决策仍由 Runtime Core 管理。
|
||||
|
||||
它负责：
|
||||
|
||||
- 把 App 实例挂载到 Tauri 或 Web Host；
|
||||
- 显示当前前台 App；
|
||||
- 管理应用切换、恢复和关闭；
|
||||
- 提供全局连接状态、通知和安全恢复入口；
|
||||
- 向 App 传递受限的 Host 能力。
|
||||
|
||||
普通 App 不能伪造 Runtime Shell，也不能直接修改焦点栈。
|
||||
|
||||
### 2.3 Interaction App
|
||||
|
||||
Interaction App 是默认的人与 Agent 交互应用，但不是整个应用生态的调度器。
|
||||
|
||||
它负责：
|
||||
|
||||
- 当前 Conversation 的主要交互体验；
|
||||
- IM、Audio、Video 等交互模式；
|
||||
- 选择框、确认框、输入框和进度卡片等标准交互原语；
|
||||
- 显示普通 Agent 消息、任务、Tool 结果和扩展 App 的结果；
|
||||
- 通过 SDK 提交用户动作。
|
||||
|
||||
它不负责：
|
||||
|
||||
- 直接连接 AppServer 或 Agent；
|
||||
- 决定其他 App 是否启动；
|
||||
- 管理其他 App 的前后台状态；
|
||||
- 直接执行未经 Runtime 授权的 Tool 或 Capability。
|
||||
|
||||
### 2.4 Extension App
|
||||
|
||||
扩展 App 与 Interaction App 是 Runtime 上的平级应用。画板、你画我猜和任务面板拥有
|
||||
自己的页面、状态、Tool、Surface 和实例生命周期，但必须使用 Runtime SDK。
|
||||
|
||||
扩展 App 可以请求：
|
||||
|
||||
```text
|
||||
启动自己
|
||||
创建 Surface
|
||||
进入前台
|
||||
进入后台
|
||||
提交结果
|
||||
请求关闭
|
||||
```
|
||||
|
||||
最终是否允许、如何持久化、是否需要用户确认，由 Runtime 决定。
|
||||
|
||||
## 3. 应用实例与焦点模型
|
||||
|
||||
App Registry 管理“有哪些应用”，App Instance Manager 管理“哪些应用正在运行”。两者
|
||||
不能混为一个状态。
|
||||
|
||||
```ts
|
||||
type AppInstanceRecord = {
|
||||
instance_id: string;
|
||||
app_scope: string;
|
||||
conversation_id?: string;
|
||||
state:
|
||||
| "starting"
|
||||
| "foreground"
|
||||
| "background"
|
||||
| "suspended"
|
||||
| "stopping"
|
||||
| "stopped"
|
||||
| "failed";
|
||||
parent_instance_id?: string;
|
||||
started_at: string;
|
||||
stopped_at?: string;
|
||||
error?: string;
|
||||
};
|
||||
```
|
||||
|
||||
Runtime 需要保存当前会话的焦点栈：
|
||||
|
||||
```text
|
||||
focus_stack:
|
||||
interaction:audio-001
|
||||
draw-and-guess:game-001
|
||||
|
||||
foreground:
|
||||
draw-and-guess:game-001
|
||||
|
||||
background:
|
||||
interaction:audio-001
|
||||
```
|
||||
|
||||
应用切换不会自动删除原实例。原实例可能进入 `background` 或 `suspended`，在新应用关闭、
|
||||
失败或用户返回时恢复。
|
||||
|
||||
## 4. Tool 调度模型
|
||||
|
||||
Tool 调度权在 Runtime，不在 Interaction App。
|
||||
|
||||
```text
|
||||
Agent Tool Call
|
||||
→ Runtime 校验 Envelope / Inventory / Manifest / 参数 / Scope
|
||||
→ Tool Router 判断处理方式
|
||||
→ App Orchestrator 创建或切换 App Instance
|
||||
→ Focus Manager 调整前后台
|
||||
→ Interaction App / Mode / Extension App 承接
|
||||
→ App 通过 SDK 返回 progress / result / error
|
||||
→ Runtime 校验、持久化、审计并回传 Agent
|
||||
```
|
||||
|
||||
Tool 的处理方式至少包括：
|
||||
|
||||
```text
|
||||
direct 直接由 Runtime 或受信 App 处理
|
||||
interactive 交给 Interaction App 等待用户选择/确认/输入
|
||||
launch 启动或唤醒一个扩展 App
|
||||
foreground 要求目标 App 进入前台
|
||||
operation 创建长时间运行的异步任务
|
||||
```
|
||||
|
||||
Interact 可以请求 Runtime 启动扩展 App，但不能直接加载 Bundle、切换其他 App 或执行
|
||||
系统能力。
|
||||
|
||||
## 5. 典型场景：语音切换到你画我猜
|
||||
|
||||
开始时：
|
||||
|
||||
```text
|
||||
Runtime Shell
|
||||
└── Interaction App
|
||||
└── Audio Mode（foreground）
|
||||
```
|
||||
|
||||
用户说：“我们来玩一局你画我猜吧。” Agent 发来启动请求后：
|
||||
|
||||
```text
|
||||
Agent launch(draw-and-guess)
|
||||
→ Runtime 检查 App 是否已安装、启用和兼容
|
||||
→ 校验 Tool、Manifest、Inventory、参数和权限
|
||||
→ 创建 draw-and-guess:game-001
|
||||
→ 保存 interaction:audio-001 的焦点位置
|
||||
→ Audio Mode 进入 background / suspended
|
||||
→ Draw-and-Guess 进入 starting → foreground
|
||||
```
|
||||
|
||||
游戏完成后：
|
||||
|
||||
```text
|
||||
Draw-and-Guess App
|
||||
→ 通过 SDK 提交 game.result
|
||||
→ Runtime 持久化并回传 Agent
|
||||
→ 游戏实例关闭或挂起
|
||||
→ Runtime 恢复焦点栈中的 Audio Mode
|
||||
→ Interaction App 显示游戏结果
|
||||
```
|
||||
|
||||
游戏和原来的语音交互使用同一个 `conversation_id`，但拥有不同的 `instance_id`。这样既
|
||||
能把结果归还给同一个 Agent 会话，也能独立管理每个应用实例。
|
||||
|
||||
## 6. 标准交互原语与扩展 App 的边界
|
||||
|
||||
以下内容属于 Interaction App 的内建能力，不需要安装独立 App：
|
||||
|
||||
```text
|
||||
choice
|
||||
confirm
|
||||
input
|
||||
progress
|
||||
error
|
||||
```
|
||||
|
||||
例如 Agent 请求选择框：
|
||||
|
||||
```text
|
||||
Agent tool.call(choice)
|
||||
→ Runtime 校验并持久化 pending Tool Call
|
||||
→ Interaction App 在 IM 中显示 Choice Card
|
||||
→ 用户选择
|
||||
→ Runtime 校验 call_id 并写入 outbox
|
||||
→ Choice Card 变为 submitted / completed，不再可操作
|
||||
→ IM 时间线显示“你选择了……”
|
||||
```
|
||||
|
||||
选择框可以从界面上退出可操作状态，但交互记录不能从 Store 中删除。这样才能支持刷新
|
||||
恢复、Agent 回声、幂等去重和审计。
|
||||
|
||||
画板、游戏和复杂任务面板则属于可安装扩展 App，拥有自己的 Tool 和 Surface。
|
||||
|
||||
## 7. 目标模块
|
||||
|
||||
```text
|
||||
runtime/app-management/
|
||||
├── app-registry.ts
|
||||
├── app-instance-manager.ts
|
||||
├── app-focus-manager.ts
|
||||
├── app-lifecycle-manager.ts
|
||||
└── runtime-app-host.ts
|
||||
|
||||
runtime/coordination/
|
||||
├── tool-router.ts
|
||||
├── app-orchestrator.ts
|
||||
└── interaction-orchestrator.ts
|
||||
|
||||
core-apps/interaction/（当前由 core-apps/chat 兼容实现）
|
||||
├── interaction-runtime.ts
|
||||
├── interaction-shell.ts
|
||||
├── interaction-mode-registry.ts
|
||||
├── modes/im/
|
||||
├── modes/audio/
|
||||
├── modes/video/
|
||||
└── primitives/
|
||||
|
||||
installed-apps/
|
||||
├── whiteboard/
|
||||
├── draw-and-guess/
|
||||
└── task-dashboard/
|
||||
```
|
||||
|
||||
`RuntimeAppHost` 负责实际挂载和卸载；App Instance、Focus、Lifecycle 和 Tool Router 负责
|
||||
状态和决策。这样不会把所有业务规则重新堆回 `main.ts`。
|
||||
|
||||
## 8. 本迭代验收目标
|
||||
|
||||
```text
|
||||
1. Runtime 能从 App Registry 选择默认 Interaction App。
|
||||
2. Runtime 能创建、前台化、后台化、挂起、恢复和关闭 App Instance。
|
||||
3. Agent 启动扩展 App 时，当前前台 App 能安全进入后台。
|
||||
4. 扩展 App 结束或失败后，Runtime 能恢复原来的焦点和交互模式。
|
||||
5. Tool 调用必须经过 Runtime 的 Inventory、Manifest、参数、作用域和权限校验。
|
||||
6. Interaction App 能处理 choice / confirm / input 等标准交互原语。
|
||||
7. 扩展 App 只能通过 SDK 返回结果，不能直接访问 Agent、Host DOM 或系统特权。
|
||||
8. 断线或重启后，App Instance、Tool Call、App Inbox、outbox 和焦点栈可以有界恢复。
|
||||
9. 00.base 中已经通过的 21 个测试文件、94 个测试和生产构建不能退化。
|
||||
```
|
||||
Reference in New Issue
Block a user