docs: freeze runtime workspace iteration design
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
**版本：** 0.1（架构基线）
|
||||
**状态：** 已确认的 Runtime / SDK 方向；尚未完全落地到当前 Tauri 实现
|
||||
**日期：** 2026-08-04
|
||||
**日期：** 2026-08-06
|
||||
**关联方案：** [LineUp App 层架构设计方案](lineup-app-layer-architecture.md)、[LineUp UI Surface 与 App Capability 协议](lineup-ui-surface-protocol.md)
|
||||
|
||||
> **汇总入口：** 本文是 Runtime / SDK 初稿的详细来源。后续设计以 [LineUp App 最终设计方案](app_final_design.md) 为准；后者收敛了本地 `app_scope`、兼容迁移和实施顺序。
|
||||
@@ -71,6 +71,8 @@ AppServer / IM Transport
|
||||
6. **系统能力由 Runtime 独占。** Agent 和 App 只能请求 Capability；文件、麦克风、通知、剪贴板、窗口、密钥等均不得直接访问。
|
||||
7. **应用状态、消息和副作用分离。** Event 是已发生事实，Command 是请求动作，Effect 是 Runtime 执行的受控副作用。
|
||||
8. **UI 是 Runtime 状态的投影。** App 重启、断网或 Surface 回收后，Runtime 能依据持久化状态恢复到可解释的协作状态。
|
||||
9. **MiniApp 业务状态由 Runtime 托管。** App 只能通过 SDK 保存其当前 instance 的、Manifest schema
|
||||
声明的状态快照；不能直接访问浏览器/Host 存储、Conversation Store、Tool/operation Store 或其他 App 数据。
|
||||
|
||||
## 3. 运行时分层
|
||||
|
||||
@@ -431,7 +433,7 @@ interface LineUpAppRuntimeSDK {
|
||||
readonly tools: AppToolAPI;
|
||||
readonly apps: AppNavigationAPI;
|
||||
readonly artifacts: ArtifactAPI;
|
||||
readonly storage: ScopedStorageAPI;
|
||||
readonly instanceState: MiniAppInstanceStateAPI;
|
||||
readonly capabilities: CapabilityRequestAPI;
|
||||
readonly diagnostics: DiagnosticsAPI;
|
||||
}
|
||||
@@ -542,18 +544,48 @@ App，但不能直接决定其他 App 的生命周期。
|
||||
|
||||
Artifact、媒体与文件通过 Runtime Artifact Store 暴露元数据、受限读取、创建、会话引用和用户保存；App 不取得任意路径或跨 App 文件访问权。
|
||||
|
||||
### 8.5 存储与 Capability
|
||||
### 8.5 MiniApp instance 状态与 Capability
|
||||
|
||||
每个 App 使用 Runtime 管理的作用域隔离存储：
|
||||
每个 MiniApp instance 使用 Runtime 管理的、按实例隔离的业务状态快照：
|
||||
|
||||
```text
|
||||
app-data/chat/
|
||||
app-data/app-registry/
|
||||
app-data/voice/
|
||||
app-data/whiteboard/
|
||||
app_scope + instance_id
|
||||
→ 一份 schema 校验的 JSON state snapshot
|
||||
→ revisioned replace
|
||||
→ 恢复同一个未结束 instance 时投影给该 App
|
||||
```
|
||||
|
||||
SDK 中的 `storage` 提供 JSON 数据和可恢复 snapshot，Runtime 负责配额、升级迁移、禁用和移除时的清理。Capability 必须通过统一请求接口：
|
||||
这不是通用文件系统、键值数据库或跨 instance 查询接口。App 负责定义状态的业务含义；Runtime 负责
|
||||
根据 Manifest 校验 schema、schema version、大小配额和保留策略，并保证调用方只能操作当前 SDK context
|
||||
中的 instance。Runtime 也负责 revision 比较、原子写入、重启恢复以及禁用、移除和关闭时的冻结/保留/清理。
|
||||
第一版 `retention` 仅支持 `delete_on_close`（默认）与 `retain_readonly`；后者只保留历史或向新 instance
|
||||
提供受控上下文，不能让已关闭 instance 再次写入。App 禁用或移除后的最终清理由 Runtime 按用户确认和全局
|
||||
保留策略执行；状态 schema 升级只能经新 App 版本的受控读取/替换完成，Runtime 不执行 App 提供的迁移脚本。
|
||||
|
||||
```ts
|
||||
interface MiniAppInstanceStateAPI<State extends JsonObject = JsonObject> {
|
||||
get(): Promise<{
|
||||
state: State | null;
|
||||
revision: number;
|
||||
}>;
|
||||
|
||||
replace(request: {
|
||||
state: State;
|
||||
expected_revision: number;
|
||||
}): Promise<{
|
||||
revision: number;
|
||||
}>;
|
||||
}
|
||||
```
|
||||
|
||||
`expected_revision` 不匹配时 Runtime 返回稳定的 `state_revision_conflict`；非法 schema、越过实例边界或
|
||||
超出配额时分别返回 `state_invalid`、`state_scope_mismatch`、`state_quota_exceeded`。App 不得用状态
|
||||
快照直接完成 Agent Tool、写 outbox、改变焦点或执行 Capability。涉及 deadline、Tool 终态、outbox、焦点
|
||||
或生命周期的业务命令仍要走 Runtime 的 Command / operation 路径；Runtime 可在同一原子事务中更新
|
||||
operation 与 instance state，但两者保持不同的事实来源。
|
||||
|
||||
MiniApp 的短暂渲染状态（动画、滚动位置、临时 loading）不要求保存；Conversation / App 子会话保存人与
|
||||
Agent 可见的静态交互和结果，也不是 MiniApp 业务状态的事实来源。Capability 必须通过统一请求接口：
|
||||
|
||||
```ts
|
||||
interface CapabilityRequestAPI {
|
||||
@@ -573,7 +605,7 @@ Runtime 检查 Manifest 声明、App 启用状态、Host 支持、前台要求
|
||||
| 层级 | 例子 | 可用接口 | 明确禁止 |
|
||||
|---|---|---|---|
|
||||
| Core App | Chat、App Registry、Settings | 完整 App Runtime SDK（仍受 Scope 和 Capability 约束） | 直接绕过 Transport/Capability Gateway。 |
|
||||
| Installed App | 白板、语音、游戏 | 受限 Surface Bridge SDK：状态、已声明 Tool、事件、隔离存储、Capability request | Tauri invoke、父 DOM、token、任意网络、其他 App 数据。 |
|
||||
| Installed App | 白板、语音、游戏 | 受限 Surface Bridge SDK：状态、已声明 Tool、事件、当前 instance 的 Runtime 状态快照、Capability request | Tauri invoke、父 DOM、token、任意网络、其他 App 数据。 |
|
||||
| Host Provider | Tauri Desktop / Web Reference Host 实现 | Runtime 内部 Host Provider API | 向 Runtime 提供系统能力；不直接暴露给 Agent/Surface。 |
|
||||
|
||||
下载型 App 使用 `iframe sandbox="allow-scripts"` 或等价隔离容器；不包含 `allow-same-origin`。它经严格 CSP、来源验证和消息 schema 校验的桥接访问 Surface SDK。第一版不支持市场下载包执行本地 Rust、Node、Shell 或任意浏览器特权代码。
|
||||
@@ -589,12 +621,18 @@ Runtime 检查 Manifest 声明、App 启用状态、Host 支持、前台要求
|
||||
"version": "1.2.0",
|
||||
"runtime_sdk": {
|
||||
"api_version": "1",
|
||||
"required_features": ["app.lifecycle.v1", "app.tools.v1", "surface.state.v1"],
|
||||
"required_features": ["app.lifecycle.v1", "app.tools.v1", "surface.state.v1", "app.instance-state.v1"],
|
||||
"optional_features": ["artifact.create.v1"]
|
||||
},
|
||||
"entrypoints": [
|
||||
{"id": "canvas", "kind": "contextual", "default_eligible": false}
|
||||
],
|
||||
"instance_state": {
|
||||
"state_schema_version": 1,
|
||||
"state_schema": {"type": "object", "additionalProperties": false},
|
||||
"max_bytes": 65536,
|
||||
"retention": "delete_on_close"
|
||||
},
|
||||
"agent_subscriptions": [
|
||||
{"type": "lineup.app.state.patch", "scope": "instance"},
|
||||
{"type": "lineup.tool.invoke", "scope": "conversation"}
|
||||
@@ -622,6 +660,7 @@ identity 用户、设备、认证会话
|
||||
connection AppServer 状态、cursor、重试、outbox
|
||||
conversations Agent 映射、消息引用、任务、交互、Artifact 元数据
|
||||
apps App Registry、默认 App、运行实例、App Inbox
|
||||
app_state 按 app_scope + instance_id 隔离的业务状态快照与 revision
|
||||
tools 已声明 Tool、可见性、调用与 operation
|
||||
capabilities 授权、执行状态、最小审计
|
||||
```
|
||||
@@ -648,7 +687,7 @@ lineup-app/
|
||||
│ ├── apps/ App Manager、Registry、Instance、Focus、Lifecycle Manager
|
||||
│ ├── tools/ Tool Registry、Inventory、Router、call lifecycle
|
||||
│ ├── capabilities/ Capability Gateway
|
||||
│ └── persistence/ Runtime Store、App Inbox、Artifact metadata
|
||||
│ └── persistence/ Runtime Store、App Inbox、instance state snapshot、Artifact metadata
|
||||
├── runtime-sdk/
|
||||
│ ├── app.ts Core App SDK 类型
|
||||
│ ├── manifest.ts App/Tool/Subscription Manifest 类型
|
||||
@@ -699,6 +738,8 @@ lineup-app/
|
||||
- 将动态 Inventory 同步给 Agent；
|
||||
- 实现 Agent `tool.invoke` → Runtime → App SDK → `tool.result` 的可靠闭环；
|
||||
- App 未运行时持久化 Inbox，恢复后可幂等补读。
|
||||
- 实现 `app.instance-state.v1`：Manifest schema / schema version / quota / retention 校验、instance 隔离、
|
||||
revisioned replace、刷新/重启恢复与关闭/禁用/移除清理；Tool/operation/outbox 不得由该 API 直接改写。
|
||||
|
||||
### R4：第一个 Installed App 闭环
|
||||
|
||||
@@ -716,6 +757,8 @@ lineup-app/
|
||||
5. 下载型 App 无法访问 Tauri invoke、Host DOM、token 或未授予 Capability；
|
||||
6. 默认 App 不可用时 Runtime 自动进入 chat Recovery App；
|
||||
7. 所有 Tool 调用、权限拒绝与终态结果均可按 app_scope、conversation_id、call_id 审计和测试。
|
||||
8. MiniApp 只能读写自身当前 instance 的状态快照；非法 schema、旧 revision、跨 instance、超配额以及
|
||||
关闭后的写入均被稳定拒绝，重启只恢复最后一个有效快照。
|
||||
```
|
||||
|
||||
## 14. 与已有正式方案的关系
|
||||
|
||||
Reference in New Issue
Block a user