# LineUp UI Surface 与 App Capability 协议

**版本：** 1.0（提案）
**状态：** 已有 Web Chat Reference Host
**日期：** 2026-08-02

> **汇总入口：** 本文保留 Surface 与 Capability 的协议和安全细节。后续 Runtime、SDK、App 管理及旧 `app.id` 字段的兼容迁移以 [LineUp App 最终设计方案](app_final_design.md) 为准。

## 1. 目标

LineUp 的 Agent 不应只能回一段文本，也不应获得在宿主 App 任意执行代码的权限。本协议定义一个类似“小程序表现层”的受控扩展模型：

```text
Agent / Adapter
  ├─ lineup.v1.ui.open / patch / close  ─────→  UI Surface Host
  │                                             └─ sandbox HTML + CSS + JS
  ├─ lineup.v1.app.call                 ─────→  App Capability Registry
  │                                             └─ 用户确认 / 系统权限 / 本机执行
  ←─ lineup.v1.ui.event / app.result    ──────  用户动作或受控调用结果
```

它有两层，不可混用：

| 层 | 作用 | 能做什么 | 不能做什么 |
|---|---|---|---|
| `UI Surface` | 呈现交互界面 | 显示 HTML/CSS/JS、收集用户事件、接收状态更新 | 读取宿主登录态、直接访问设备能力、直接调用 IM / 网络 |
| `App Capability` | 调用宿主上层应用能力 | 在能力注册、权限和用户确认后打开链接、写剪贴板、选文件、调用原生模块等 | 由 Surface 脚本绕过权限直接调用 |

标准 Markdown、文本、状态、进度、choice、confirm、input 等仍应优先由宿主内置渲染器实现。Surface 适用于仪表盘、地图、复杂表单、图表、可视化编辑器等无法由内置组件良好表达的界面。

## 2. 安全模型（不可省略）

1. Agent 的 UI bundle 被视为**不可信内容**，不是 App 代码的一部分。
2. Web Host 必须使用独立 origin 的 `iframe sandbox="allow-scripts"`。禁止 `allow-same-origin`、`allow-top-navigation`、`allow-popups`、`allow-forms`。
3. Surface 的 CSP 至少为 `default-src 'none'; connect-src 'none'; img-src data: blob:; style-src 'unsafe-inline'; script-src 'unsafe-inline'`。默认不得联网、加载远程脚本、访问摄像头或地理位置。
4. 宿主与 Surface 仅用 `postMessage` 通信；宿主必须同时验证 `event.source`、消息命名空间、`instance_id`、事件名、JSON 类型与大小。
5. Surface 事件只是“用户意图”回传。任何上层 App / 原生能力都必须由 Agent 另行发送 `app.call`，再由宿主依据注册表、风险等级和用户授权执行。
6. Content 不得写入宿主 DOM。Markdown 使用解析器后仍须 sanitizer；HTML Surface 只能放进 sandbox `srcdoc`。
7. 生产环境应只接受已签名或在 Agent allowlist 中的 bundle hash；Reference Host 先以严格 sandbox 保障隔离，并保留 `app.integrity` 字段用于升级。

## 3. 消息类型

所有消息均使用既有 `lineup.v1` 信封。`conversation_id`、`id`、`sender`、`target` 的规则不变。

| Type | 方向 | 含义 |
|---|---|---|
| `lineup.v1.ui.open` | Agent → Client | 创建或替换一个 Surface 实例 |
| `lineup.v1.ui.patch` | Agent → Client | 向已打开实例推送新的状态；不可注入或替换代码 |
| `lineup.v1.ui.close` | Agent → Client | 关闭实例 |
| `lineup.v1.ui.event` | Client → Agent | Surface 中的用户事件或用户关闭事件 |
| `lineup.v1.client.inventory` | Client → Agent | 当前 Host 的 revisioned 最小接口清单：标准组件、应用中心已启用 app Surface 与 policy 筛选后的 capability |
| `lineup.v1.app.list` | Client → Agent | 可选的兼容 capability-only 投影；不得替代完整 inventory 或宣称安装/授权 |
| `lineup.v1.app.call` | Agent → Client | 请求调用一个声明过的 capability |
| `lineup.v1.app.result` | Client → Agent | 调用完成、拒绝、失败或不支持的结果 |

未知的 `ui.*` 或 `app.*` type 只能安全显示或回复 `unsupported`，不得执行。

## 4. UI Surface 合约

### 4.1 打开

```json
{
  "v": 1,
  "id": "msg_ui_01",
  "type": "lineup.v1.ui.open",
  "conversation_id": "conv_01",
  "sender": {"kind": "agent", "id": "agent_hermes_main"},
  "payload": {
    "instance_id": "weather.dashboard.01",
    "app": {
      "id": "com.lineup.weather.dashboard",
      "name": "天气面板",
      "version": "1.0.0",
      "integrity": "sha256-BASE64_DIGEST",
      "html": "<main><button id='refresh'>刷新</button></main>",
      "css": "main { padding: 16px }",
      "js": "document.querySelector('#refresh').onclick=()=>LineUpSurface.event('refresh',{unit:'c'})"
    },
    "state": {"city": "北京", "temperature": 22}
  }
}
```

约束：

- `instance_id` 在一个会话内唯一，格式为 `[A-Za-z0-9._:-]{1,128}`；相同 ID 的 `ui.open` 表示替换旧实例；
- `app.id` 为反向域名风格的稳定应用 ID，`version` 为 SemVer；
- `html`、`css`、`js` 是 Surface bundle；单个 bundle 的生产上限建议为 160 KiB，资源应使用经过 Artifact 管理和签名的本地引用，禁止任意公网 URL；
- `state` 必须是 JSON object。UI bundle 将在 `ready` 后和每次 `ui.patch` 收到它；
- **`ui.patch` 只能更新 `state`，绝不能更新 HTML/CSS/JS。** 若要升级 bundle，关闭旧实例并以新 `version` 打开新实例。

### 4.2 Surface bridge

Host 注入唯一的全局对象：

```js
LineUpSurface.event('refresh', { unit: 'c' })
LineUpSurface.onState((state) => render(state))
LineUpSurface.resize(document.documentElement.scrollHeight)
```

它只允许以下上行消息：

```json
{
  "namespace": "lineup.surface.v1",
  "type": "event",
  "event": "refresh",
  "data": {"unit": "c"}
}
```

Host 将其转换为：

```json
{
  "type": "lineup.v1.ui.event",
  "payload": {
    "instance_id": "weather.dashboard.01",
    "event": "refresh",
    "data": {"unit": "c"}
  }
}
```

`event` 采用 `[A-Za-z][A-Za-z0-9._:-]{0,63}`，`data` 必须为小于 16 KiB 的 JSON object。Surface 不拥有 `app.call` bridge。

### 4.3 状态更新与关闭

```json
{"type":"lineup.v1.ui.patch","payload":{"instance_id":"weather.dashboard.01","state":{"city":"上海","temperature":28}}}
```

```json
{"type":"lineup.v1.ui.close","payload":{"instance_id":"weather.dashboard.01","reason":"completed"}}
```

用户主动关闭时 Client 应回送 `ui.event`，其中 `event` 为 `close`。

## 5. App Capability 合约

### 5.1 动态 Client Inventory

客户端在会话建立完成后，以及应用中心的 app 启用/停用/升级、Host policy 或 capability 可见性变化时，向**对应 Agent 会话**发送 `client.inventory`。它有单调递增或不可复用的 `revision`；Agent 必须用最新 revision 决定可请求的组件、Surface 和能力。收到撤销后的旧 app id、Surface 或 capability 引用时，Client 只返回确定的 `unsupported / revoked` 结果，绝不回退到执行或加载远端 bundle。

```json
{
  "type": "lineup.v1.client.inventory",
  "payload": {
    "revision": "catalog-42",
    "standard_components": [
      {"id":"choice","version":"1"},
      {"id":"confirm","version":"1"},
      {"id":"input","version":"1"}
    ],
    "applications": [
      {
        "id":"com.lineup.svg-canvas",
        "version":"1.0.0",
        "surfaces":[{"id":"canvas","events":["draw","resize","snapshot"]}]
      }
    ],
    "capabilities": [
      {"name":"artifact.save","version":"1.0","risk":"user_confirmation"}
    ]
  }
}
```

`applications` 只能列出应用中心中**已启用且已在本地完成相应阶段验证**的应用，不包含 bundle 源码、安装来源、登录态、文件路径或用户内容。SVG 画板这样的 app 只允许 Agent 以 app id 创建受限 Surface，并通过用户触发的 `ui.event(draw / resize / snapshot)` 获取声明性画布事件；inventory 不授予远程脚本注入、读取宿主 DOM 或本机能力权限。

### 5.2 Capability 声明（`app.list` 兼容投影）

客户端可在 inventory 之后或 capability 变化时发送 `app.list` 作为仅包含 capability 的兼容投影。只有 inventory / app.list 中声明且仍未被撤销的 `capability` 才能被请求；声明从不等同于授权。

```json
{
  "type": "lineup.v1.app.list",
  "payload": {
    "capabilities": [
      {"name":"app.open_url","version":"1.0","risk":"user_confirmation","input_schema":{"type":"object","required":["url"]}},
      {"name":"clipboard.write","version":"1.0","risk":"user_confirmation","input_schema":{"type":"object","required":["text"]}},
      {"name":"device.pick_file","version":"1.0","risk":"system_permission","input_schema":{"type":"object"}}
    ]
  }
}
```

风险必须是下列之一：`display_only`、`user_confirmation`、`system_permission`、`restricted`。后两者不能被记住为永久授权，且必须经过原生系统权限或额外身份校验。

### 5.3 调用与结果

```json
{
  "type": "lineup.v1.app.call",
  "payload": {
    "call_id": "call_open_docs_01",
    "capability": "app.open_url",
    "reason": "打开部署文档供你核对",
    "expires_at": "2026-08-02T12:10:00Z",
    "arguments": {"url": "https://example.com/docs"}
  }
}
```

Client 必须向用户说明 capability 和 `reason`，收到确认后再执行，随后使用相同 `call_id` 回传：

```json
{
  "type": "lineup.v1.app.result",
  "payload": {
    "call_id": "call_open_docs_01",
    "status": "completed",
    "result": {"opened": true}
  }
}
```

`status`：`completed | rejected | cancelled | expired | unsupported | failed`。同一 `call_id` 必须幂等；调用记录与授权决定应由 Gateway 审计。

## 6. Reference Host 当前实现与阶段边界

截至 2026-08-03，Tauri Reference Host 已完成 M0 和 M1-01～M1-03：严格 Envelope / Kernel / Store / Renderer 边界，Markdown、status/progress/error、choice、confirm、input 的可信原生渲染与本地状态恢复。它**尚未**实现 `client.inventory` 发送、应用中心、`ui.open / patch / close` 的 Surface Host、远端或本地 app bundle 加载、`app.call` 执行、Capability Registry 或 `app.result` 网络回传。

因此，这份协议中的 Surface、inventory 与 Capability 段落是后续 M2～M4 的正式契约，不是当前 Web Chat 已开放的功能。M2 建立应用中心本地启用注册表与隔离 Surface；M3 才生成/更新并通知 `client.inventory`，再实施 Capability policy；M4 负责下载、完整性校验、缓存、回滚与 Host 一致性。当前只以 Tauri Desktop Host 与同代码 Web Reference Host 实现这些边界；不规划独立 Android/iOS/Wails 客户端。