docs: freeze runtime workspace iteration design
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
**版本：** 1.0（当前开发基线）
|
||||
**状态：** 当前 App 设计的唯一汇总入口
|
||||
**日期：** 2026-08-04
|
||||
**日期：** 2026-08-06
|
||||
**来源：** [App 层架构方案](lineup-app-layer-architecture.md)、[Runtime 与 App SDK 架构方案](lineup-runtime-sdk-architecture.md)、[UI Surface 与 App Capability 协议](lineup-ui-surface-protocol.md)
|
||||
|
||||
---
|
||||
@@ -50,7 +50,7 @@ AppServer / IM
|
||||
| App 生态阶段 | 当前只使用本地短作用域，如 `chat`、`whiteboard`、`draw-and-guess`；暂不引入供应商身份、反向域名 App ID 或全局命名空间。 |
|
||||
| 丰富交互 | 标准内容先用可信内建组件；复杂互动用受限 Surface；设备/系统动作只能经 Capability Gateway。 |
|
||||
| Agent 工具 | App 在 Manifest 声明方法，Runtime 汇总为动态 Inventory；Agent 只能调用当前 Inventory 中的方法。 |
|
||||
| Runtime SDK | SDK 提供状态订阅、Agent 消息订阅、Action、Tool、应用导航、Artifact、存储、Capability 和生命周期接口。 |
|
||||
| Runtime SDK | SDK 提供状态订阅、Agent 消息订阅、Action、Tool、应用导航、Artifact、instance 级业务状态快照、Capability 和生命周期接口。业务状态由 Runtime 持久化和隔离，App 不直接拥有存储。 |
|
||||
| Host | Tauri Desktop Host 与同代码的 Web Reference Host 是当前唯一实现/验收基线：前者是正式桌面外壳，后者是浏览器开发和验证入口；它们不是两个客户端。不规划独立 Android/Kotlin 客户端或 Wails Host。 |
|
||||
|
||||
本文件优先于来源文档中关于**后续 Runtime 重构**的结构描述。来源文档中的 M0～M4 完成记录、当前已实现字段和历史验收事实仍然有效；它们不自动成为新 Runtime 的长期模块边界。
|
||||
@@ -137,7 +137,7 @@ conversations
|
||||
conversation、关联 Agent、消息引用、任务、交互、Artifact 元数据。
|
||||
|
||||
apps
|
||||
App Registry、默认 App、运行实例、每个 App 的可靠 Inbox。
|
||||
App Registry、默认 App、运行实例、每个 App 的可靠 Inbox 与按 instance 隔离的业务状态快照。
|
||||
|
||||
tools
|
||||
Tool 声明、Inventory revision、调用记录、operation 与进度。
|
||||
@@ -449,7 +449,7 @@ interface LineUpAppRuntimeSDK {
|
||||
readonly tools: AppToolAPI;
|
||||
readonly apps: AppNavigationAPI;
|
||||
readonly artifacts: ArtifactAPI;
|
||||
readonly storage: ScopedStorageAPI;
|
||||
readonly instanceState: MiniAppInstanceStateAPI;
|
||||
readonly capabilities: CapabilityRequestAPI;
|
||||
readonly diagnostics: DiagnosticsAPI;
|
||||
}
|
||||
@@ -505,14 +505,57 @@ interface AppNavigationAPI {
|
||||
|
||||
App 只能提交声明性 Action，不能构造原始 Agent Envelope。跨 App 打开、聚焦和关闭也必须经 Runtime 校验目标 App 的启用状态、入口、展示模式和会话作用域。
|
||||
|
||||
### 6.3 Artifact、存储与 Capability
|
||||
### 6.3 MiniApp instance 业务状态、Artifact 与 Capability
|
||||
|
||||
Runtime 为每个 MiniApp instance 提供一份受限的业务状态快照。MiniApp 定义状态的业务语义和
|
||||
Manifest schema；Runtime 是持久化、隔离、并发裁决、恢复和清理的唯一所有者。它不是供 App 任意
|
||||
查询或读写的数据库，也不等同于 Conversation Store、Tool/operation Store、outbox 或 Artifact Store。
|
||||
|
||||
```ts
|
||||
interface MiniAppInstanceStateAPI<State extends JsonObject = JsonObject> {
|
||||
get(): Promise<{
|
||||
state: State | null;
|
||||
revision: number;
|
||||
}>;
|
||||
|
||||
replace(request: {
|
||||
state: State;
|
||||
expected_revision: number;
|
||||
}): Promise<{
|
||||
revision: number;
|
||||
}>;
|
||||
}
|
||||
```
|
||||
|
||||
每次调用的存储边界由不可伪造的 SDK context 推导：
|
||||
|
||||
```text
|
||||
app_scope + instance_id
|
||||
```
|
||||
|
||||
App 不得指定、读取或写入其他 App、其他 instance、Conversation Store 或 Runtime 内部记录。Runtime
|
||||
必须校验 Manifest 声明的 `state_schema`、`state_schema_version`、大小配额与 `expected_revision`；旧
|
||||
Surface、重复点击或并发写入不能覆盖较新的快照。刷新、Surface 重载和 Runtime 重启后，Runtime 向
|
||||
同一个可恢复 instance 投影最后一个有效快照。实例关闭、App 禁用/移除时，Runtime 按 Manifest 的
|
||||
retention policy 冻结、保留或清理快照，MiniApp 本身无权绕过生命周期复活旧状态。
|
||||
|
||||
第一版的 `retention` 只允许 `delete_on_close`（默认，关闭时删除）和 `retain_readonly`（关闭后
|
||||
保留为历史/新 instance 的受控上下文，但旧 instance 不可再写入）。App 禁用或移除时，Runtime 仍按
|
||||
用户确认和全局保留策略清理其快照；状态 schema 升级由新 App 版本通过受控读取/替换完成，Runtime 不执行
|
||||
任意 App 提供的迁移脚本。
|
||||
|
||||
业务状态快照不替代 Runtime operation。凡是会影响 Agent Tool 终态、deadline、outbox、焦点、权限或
|
||||
实例生命周期的动作，仍必须通过 Runtime Command / operation 原子裁决。例如 Pomodoro 的显示状态
|
||||
可以保存在自己的 instance snapshot，但 `ends_at` 到期、用户中断与唯一 Tool result 必须由 Runtime
|
||||
的 deadline operation 负责，不能由 MiniApp 自行完成或直接发送结果。
|
||||
|
||||
```text
|
||||
Artifact
|
||||
Runtime 管理元数据、受限读取、创建、会话引用、下载和用户保存。
|
||||
|
||||
Storage
|
||||
Runtime 为每个 app_scope 提供隔离 JSON 数据与 snapshot；管理配额、迁移和清理。
|
||||
Instance State
|
||||
Runtime 为每个 app_scope + instance_id 提供隔离的 JSON snapshot；管理 schema、revision、配额、
|
||||
恢复与生命周期清理。UI 动画、滚动位置等短暂渲染状态不必持久化。
|
||||
|
||||
Capability
|
||||
App 以 purpose + input 请求；Runtime 决定是否确认、调用 Host、审计并返回受控结果。
|
||||
@@ -617,7 +660,7 @@ iframe sandbox="allow-scripts"
|
||||
- 只经严格 postMessage / Surface Bridge SDK 通信
|
||||
```
|
||||
|
||||
Runtime/Host 必须验证 `event.source`、当前 `instance_id`、消息类型、事件名、JSON schema、消息大小和声明的投递策略。Surface 只能接收 state patch、触发已声明事件、处理已声明 Tool 调用、使用隔离存储和请求受控 Capability。
|
||||
Runtime/Host 必须验证 `event.source`、当前 `instance_id`、消息类型、事件名、JSON schema、消息大小和声明的投递策略。Surface 只能接收 state patch、触发已声明事件、处理已声明 Tool 调用、通过 Bridge 使用 Runtime 提供的自身 instance 状态快照和请求受控 Capability。
|
||||
|
||||
Surface 不能：
|
||||
|
||||
@@ -650,13 +693,20 @@ Surface 不能：
|
||||
"required_features": [
|
||||
"app.lifecycle.v1",
|
||||
"app.tools.v1",
|
||||
"surface.state.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"}
|
||||
@@ -685,7 +735,7 @@ lineup-app/
|
||||
│ ├── apps/ app registry、instance manager、default app
|
||||
│ ├── tools/ tool registry、inventory、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 类型
|
||||
@@ -771,6 +821,8 @@ F0 与 F1 中支撑图文聊天迁移的最小闭环已落地并经自动化回
|
||||
- 在 Runtime 连接与状态变化时同步 revisioned Inventory 给 Agent；Tool 可声明是否需要启动 App、是否要求前台以及结束后是否恢复原焦点；
|
||||
- 实现 Agent Tool → Runtime → App SDK → result/progress 的可靠闭环；
|
||||
- 将 MVP-R1 已实现的 Chat App Inbox、ACK、断线/崩溃恢复和拒绝码推广为所有受管理 App 的通用可靠投递机制。
|
||||
- 实现 `app.instance-state.v1`：按 `app_scope + instance_id` 隔离的 schema 校验状态快照、revision
|
||||
并发控制、配额、重启恢复与 lifecycle 清理；它不得替代 Tool/operation/outbox 的终态裁决。
|
||||
|
||||
### F4：第一个 Installed App
|
||||
|
||||
@@ -795,6 +847,9 @@ F0 与 F1 中支撑图文聊天迁移的最小闭环已落地并经自动化回
|
||||
工具与能力
|
||||
[ ] Agent 只能调用当前 Inventory 中、参数 schema 合法的 Tool。
|
||||
[ ] Tool 的 result/progress/error 经 Runtime 校验、持久化和审计。
|
||||
[ ] MiniApp 只能读取和替换自身 instance 的 schema 合法状态快照；旧 revision、越界 instance、超配额
|
||||
和非法 schema 均被 Runtime 拒绝，刷新/重启后仅恢复最后一个有效版本。
|
||||
[ ] 业务状态快照不能直接完成 Tool、写 outbox、改变焦点或绕过实例生命周期。
|
||||
[ ] App / Surface 无法绕过 Capability Gateway 获得系统权限。
|
||||
|
||||
安全
|
||||
|
||||
Reference in New Issue
Block a user