# 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 个测试和生产构建不能退化。
```