docs(iteration): freeze sdk v1 contract fixtures
This commit is contained in:
+115
-56
@@ -225,7 +225,6 @@ interface LineUpMiniAppSDK {
|
||||
|
||||
inbox: MiniAppInboxAPI;
|
||||
tools: MiniAppToolAPI;
|
||||
ui: StandardInteractionAPI;
|
||||
lifecycle: MiniAppLifecycleAPI;
|
||||
surfaces: MiniAppSurfaceAPI;
|
||||
capabilities: MiniAppCapabilityRequestAPI;
|
||||
@@ -270,38 +269,79 @@ interface MiniAppToolAPI {
|
||||
`call_id` 的实例归属、合法状态迁移、输入/输出 schema、幂等性和权限，然后持久化、审计并
|
||||
写入 outbox。
|
||||
|
||||
### 7.3 标准交互、Lifecycle、Surface 与 Capability
|
||||
一旦 Runtime 接受某个 App instance 的关闭，关闭表示释放该 instance，不是把它留在后台：Runtime 停止
|
||||
向它投递新普通 Tool，将仍为 `received / routing / waiting_for_app / running` 的绑定 Tool 原子收敛为
|
||||
`cancelled(app_closed)`，每条 Tool 只写一条 cancelled outbox；已 `submitted` 的结果不可改写，继续可靠发出。
|
||||
然后才关闭 Surface、停止 instance、结束 App 子会话并恢复焦点。普通 Tool 的完成或失败本身不关闭 App。
|
||||
标准交互是例外：App 关闭只通知 Agent，不自动取消仍 pending 的人与 Agent 交互。
|
||||
|
||||
Runtime 通过 `sdk.ui` 提供 `notice`、`choice`、`confirm`、`input` 四种标准交互原语。这是由
|
||||
Runtime 统一拥有的标准输入输出库：Runtime 创建和持久化交互记录，注入 owner、校验请求/结果、
|
||||
负责恢复、审计与路由，并依照 Shell Policy 决定呈现位置。
|
||||
### 7.3 人与 Agent 标准交互、Lifecycle、Surface 与 Capability
|
||||
|
||||
`owner` 不属于 SDK 调用参数。Runtime 仅从 SDK 已绑定的 `MiniAppContext` 注入
|
||||
`app_scope`、`instance_id`、`conversation_id`，并可带有已验证的 `parent_call_id`、`surface_id` 与
|
||||
来源；MiniApp 不可伪造、覆盖或访问其他 owner 的交互。`presentation` 只能作为 `inline`、`modal`
|
||||
或默认形式的偏好，最终仍由 Runtime/Shell 决定。
|
||||
`notice`、`choice`、`confirm`、`input` 是 Interact 的人与 Agent 交互组件，与 IM 消息同属于
|
||||
当前会话；它们不是 MiniApp SDK，也不用于 MiniApp 自己的业务表单、确认或输入。Agent 通过
|
||||
标准 Tool 交互请求发起它们，Runtime 校验、持久化、恢复、审计并可靠回传结果，Interact 负责呈现。
|
||||
|
||||
Runtime 内部至少持久化以下归属信息：
|
||||
这四种是普通的人与 Agent 会话交互，不在 SDK v1 中统一定义为密码或秘密输入。已提交内容遵循普通 IM
|
||||
的会话历史、保留和日志基线；尤其不能因为它们是普通输入，就突破全局“日志不记录会话正文、Tool 参数、
|
||||
token 等内容”的约束。未提交 `input` 草稿仅保留在当前运行期，重启清空。密码、卡密、私钥、临时 token
|
||||
等真正秘密输入留待未来作为独立的 `password-input` 原语设计；届时 Runtime 必须按类型强制其展示、记录、
|
||||
传递和清理规则，Agent 不能用普通 `input` 绕过这些保护。
|
||||
|
||||
```ts
|
||||
type StandardInteractionOwner = {
|
||||
app_scope: string;
|
||||
instance_id: string;
|
||||
conversation_id: string;
|
||||
parent_call_id?: string;
|
||||
surface_id?: string;
|
||||
source: "agent_tool" | "miniapp_tool" | "runtime_policy";
|
||||
};
|
||||
```
|
||||
每条人与 Agent 的标准交互都必须在 Interact / IM 中留下相应的卡片、气泡或结果记录。`notice` 是只读
|
||||
IM 卡片；当前界面可同时短暂 Toast 提醒，但 Toast 只是同一条记录的辅助呈现，不能作为唯一消息或用户
|
||||
已阅读的证明。Runtime 成功持久化 notice 卡片并交给 Interact 呈现后，即可向 Agent 返回 `accepted`。
|
||||
|
||||
Agent 在 IM 中的提问由 Interact 作为默认可信 Renderer Provider 呈现在 IM 时间线/卡片内。前台
|
||||
MiniApp 自己请求的低复杂度事务提示，可在该 MiniApp 的有效容器或 Surface 中以 Runtime 批准的
|
||||
标准 modal、sheet 或 card 呈现，不能因此强制切换到 Interact。结果始终先返回 Runtime，再仅投递
|
||||
给 owner MiniApp；MiniApp 不可自行创建 Host 弹窗或直接将结果发送给 Agent。
|
||||
MVP 中，一个 LineUp Runtime 只连接一个 Agent，当前登录会话的 `agent_uid` 作为每条交互和
|
||||
App 子会话的 `agent_id`。此处保存 Agent 身份是为了让答案按创建时的上下文回到正确对象；本阶段
|
||||
不实现多 Agent 连接、切换、会话列表、outbox 或跨 Agent 路由。
|
||||
|
||||
复杂、高频或私有的业务 UI（例如 Whiteboard 画布文字编辑、画笔、颜色选择、拖放和工具栏）留在
|
||||
MiniApp 自己的 Surface 内，不使用标准交互库。系统权限确认（文件、麦克风、通知等）则属于
|
||||
Runtime/Host Capability Gateway，而不是普通 `confirm`。
|
||||
Agent 发 interactive Tool 时，未带经过 Runtime 验证的 `app_session_context.app_session_id`，一律归入主 IM；
|
||||
Runtime 绝不能按当前前台 App 猜测归属。若带有该上下文，Runtime 只接受同一 Agent、同一父会话的真实
|
||||
App 子会话；已经关闭的子会话可保留为历史上下文，但不复活旧 App。Runtime 创建子会话时会可靠告知 Agent
|
||||
其稳定 ID，非法或跨会话的引用直接拒绝且不创建交互。
|
||||
|
||||
当 Interact 位于前台时，标准交互显示在 IM 时间线/卡片中；当 bundled MiniApp 位于前台时，
|
||||
Interact / Shell 可以在当前 App 之上显示同一会话的交互层。视觉位置不改变归属：请求和结果始终
|
||||
属于当前 conversation、Agent call 与 Interact instance，结果经 Runtime 回传 Agent，而不交给
|
||||
前台 MiniApp。
|
||||
|
||||
用户作答时，Interact 只把“交互 ID + 用户动作/答案”交给 Runtime，不直接把答案发送给 Agent。Runtime
|
||||
从创建时保存的记录取得 Agent、主会话、App 子会话和 Tool 的归属，并核对当前 LineUp / Interact 会话、
|
||||
有效期、答案格式和是否已结束。只有第一次有效回答可以写入会话历史和可靠 outbox；后续重复或重放提交
|
||||
不得改变结果，也不得再次通知 Agent。展示位置不是交互的 owner 或提交权限：App 前后台切换、关闭或从
|
||||
覆盖层改在 IM 显示，都不改变交互归属。客户端不能提交或改写 Agent、会话、Tool 或 App 子会话的归属字段。
|
||||
|
||||
用户回答、Agent remote dismiss、到期和 Runtime 失败都只能竞争同一条交互的唯一终态。Runtime 以第一个
|
||||
成功完成的原子状态写入为准，并同时持久化唯一 Tool 结果/outbox；后来到达的动作不得覆盖结果或再次通知
|
||||
Agent。MVP 中 interactive Tool 的等待期限与交互的 `expires_at` 相同，Agent 主动停止等待必须走 Runtime
|
||||
私有的 `interaction.dismiss(control_id, call_id)`：Runtime 从受认证 Envelope 推导 Agent 和会话，以 `call_id`
|
||||
定位交互。重放或目标已终态只返回稳定幂等回执，绝不再写 outbox；该控制契约不属于 MiniApp SDK。
|
||||
|
||||
启动一个 App instance 会在主 IM 会话中创建或恢复与之关联的 App 子会话，并可靠向当前 Agent 发送
|
||||
`app_session.opened`，提供 `agent_id`、`conversation_id`、`app_session_id`、`app_scope` 与 `instance_id`。
|
||||
主 IM 将其显示为可展开的
|
||||
折叠组，记录 Agent 的提问、用户回答和 Agent 的简洁结果；它不记录 App 内部业务操作，例如用户在
|
||||
Task Dashboard 点击按钮或填写 App 自己的表单、在 Whiteboard 绘制和编辑内容。App 进入后台时，
|
||||
子会话仍继续；Agent Tool 完成也不自动结束子会话。只有 Runtime 的 `AppLifecycleManager.close` 使
|
||||
instance 进入 stopped 或 failed、并从 focus stack 移除时，子会话才结束但保留为主 IM 的历史。新的
|
||||
App instance 必须创建新的子会话，不接续旧实例记录。
|
||||
|
||||
已结束子会话可在主 IM 中只读展开，但不会重新启动 App、重新执行操作或复活未回答的问题。用户选择
|
||||
“继续处理”旧工作时，Runtime 启动新的 App instance 和新的子会话；新子会话可以引用旧会话、artifact
|
||||
或已保存的 App 状态作为上下文，但不能向旧子会话追加记录。
|
||||
|
||||
若 App 子会话关联等待回答的 Agent 问题，App 位于前台时 Interact 可在其上方显示提问层；用户切换到
|
||||
其他 App 或普通 IM 时，该层收起但问题继续等待，主 IM 的对应折叠组标记“等待你的回答”。用户既可
|
||||
展开该组直接回答，也可回到原 App 后回答。Shell 可避免用户看到重复的视觉卡片，但展示位置不改变交互
|
||||
归属或提交资格；Runtime 通过首次有效回答和终态检查防止重复结果。真正关闭 App 会按普通 Tool 的
|
||||
`app_closed` 规则先收敛未终态 Tool，随后移除该 App 上方的展示层并结束 App 子会话。Runtime 将关闭事件
|
||||
（含仍 pending 的 interaction call_id）可靠通知 Agent；问题本身仍属于 Interact / 主 IM，直到 Agent 远程
|
||||
dismiss、用户回答、到期或 Runtime 失败才结束。
|
||||
|
||||
因此 bundled MiniApp 不能发起、读取、提交或取消这类 Agent 交互，也不因其显示在自身上方而获得
|
||||
Host DOM 或会话数据。复杂、高频或私有业务 UI（例如 Task Dashboard 的“新建任务”表单、Whiteboard
|
||||
画布文字编辑、画笔、颜色选择、拖放和工具栏）必须留在 MiniApp 自己的 Surface 内。系统权限确认
|
||||
（文件、麦克风、通知等）则属于 Runtime/Host Capability Gateway，而不是普通 `confirm`。
|
||||
|
||||
```ts
|
||||
interface MiniAppLifecycleAPI {
|
||||
@@ -311,8 +351,8 @@ interface MiniAppLifecycleAPI {
|
||||
}
|
||||
```
|
||||
|
||||
MiniApp 只能请求生命周期变化；Runtime 决定是否允许，处理 pending Tool/Surface，并负责
|
||||
焦点恢复。
|
||||
MiniApp 只能请求生命周期变化；Runtime 决定是否允许。若接受关闭，则按上面的 `app_closed` 收敛普通 Tool、
|
||||
处理 Surface 并恢复焦点；若用户只想暂时离开，应请求后台化。
|
||||
|
||||
Surface 与 Capability 也只能请求：
|
||||
|
||||
@@ -331,20 +371,26 @@ MiniApp requestOpenSurface / requestCapability
|
||||
MiniApp 只能在 Manifest 中声明 Tool；Agent 只能调用当前 Runtime 已公布 Inventory 中的 Tool。
|
||||
|
||||
```ts
|
||||
type ToolDescriptor = {
|
||||
type ToolDescriptorBase = {
|
||||
id: string; // 例如 task-dashboard.open
|
||||
version: 1;
|
||||
handling: "direct" | "interactive" | "launch" | "foreground" | "operation";
|
||||
target: {
|
||||
app_scope: string;
|
||||
requires_foreground: boolean;
|
||||
restore_previous_focus: boolean;
|
||||
};
|
||||
input_schema: JsonSchema;
|
||||
output_schema: JsonSchema;
|
||||
permissions?: readonly string[];
|
||||
timeout_ms?: number;
|
||||
};
|
||||
|
||||
type ToolDescriptor = ToolDescriptorBase & (
|
||||
| { handling: "interactive"; target?: never }
|
||||
| {
|
||||
handling: "direct" | "launch" | "foreground" | "operation";
|
||||
target: {
|
||||
app_scope: string;
|
||||
requires_foreground: boolean;
|
||||
restore_previous_focus: boolean;
|
||||
};
|
||||
timeout_ms?: number;
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
统一调度路径：
|
||||
@@ -354,15 +400,19 @@ Agent Tool Invoke
|
||||
→ Runtime 校验 Envelope、Inventory revision、Tool Descriptor、参数、scope、App 状态和权限
|
||||
→ 创建可持久化 Tool Call / 审计记录
|
||||
→ Tool Router 判定 direct / interactive / launch / foreground / operation
|
||||
→ 投递到目标 MiniApp instance
|
||||
├── interactive：不使用 target、不创建业务 instance，只由 Runtime 建立 Interact 会话交互
|
||||
└── 其他 handling：投递到目标 MiniApp instance
|
||||
→ MiniApp SDK 报告 progress / result / error
|
||||
→ Runtime 校验输出 schema、持久化、更新焦点、写 outbox
|
||||
→ Agent 收到可靠结果
|
||||
```
|
||||
|
||||
`notice`、`choice`、`confirm`、`input` 是 Runtime 的统一 `interactive` Tool/交互记录能力。
|
||||
Interact 提供 Agent/IM 场景的默认 Renderer，而不拥有记录或绕过统一 Tool Call、持久化和结果路径；
|
||||
其他 MiniApp 只能通过 `sdk.ui` 在自身有效容器使用 Runtime 批准的标准 Renderer。
|
||||
`notice`、`choice`、`confirm`、`input` 是 Agent 调起的 Runtime 统一 `interactive` Tool/交互记录
|
||||
能力。Interact 提供会话语义和呈现，Runtime 持有记录与可靠结果路径；其他 MiniApp 只能作为当前
|
||||
前台界面被 Interact 交互层覆盖，不能调用、实现或取得该交互的内容与结果。
|
||||
|
||||
可回答交互的请求以相对 `expires_in_ms` 指定期限；Runtime 计算和持久化 `expires_at`，缺省 15 分钟，
|
||||
仅接受 1 分钟至 24 小时。notice 不等待回答，也不接受期限。
|
||||
|
||||
建议稳定拒绝码至少包括：
|
||||
|
||||
@@ -466,7 +516,7 @@ tauri/src/core-apps/chat/
|
||||
### 10.3 下一阶段：03.sdk_and_coreapp
|
||||
|
||||
下一阶段不是应用市场，也不是立即建设服务端下载目录。目标见
|
||||
[03.sdk_and_coreapp.md](迭代/03.sdk_and_coreapp.md)：定义并验证 MiniApp SDK v1：
|
||||
[03.sdk_and_coreapp.md](迭代/03.sdk_and_coreapp/03.sdk_and_coreapp.md)：定义并验证 MiniApp SDK v1：
|
||||
|
||||
```text
|
||||
冻结 AppManifest、ToolDescriptor、Tool Call、App Context、Result/Progress/Error 和错误码
|
||||
@@ -476,17 +526,15 @@ tauri/src/core-apps/chat/
|
||||
→ Whiteboard 验证受限 Surface、状态 patch、Artifact 与 Capability 请求
|
||||
```
|
||||
|
||||
参考 MiniApp 在此阶段可以是 `bundled-development`：随开发 Host 内置、有 Manifest 和 Runtime
|
||||
注册记录，但不依赖服务端 Catalog、远程下载或第三方发布。
|
||||
参考 MiniApp 在此阶段使用 `kind = bundled`：随开发 Host 内置、有 Manifest 和 Runtime 注册记录，
|
||||
但不依赖服务端 Catalog、远程下载或第三方发布。`bundled` 不是系统级信任；参考只描述这些
|
||||
MiniApp 在当前阶段用于验证 SDK 的工作目的，不是 Manifest 类型名称。
|
||||
|
||||
### 10.4 后续阶段
|
||||
|
||||
MiniApp SDK 与参考实现稳定后，再按顺序推进：
|
||||
|
||||
```text
|
||||
03.reference-miniapps
|
||||
→ 完成 Task Dashboard / Whiteboard 的端到端参考实现
|
||||
|
||||
04.app-delivery-registry
|
||||
→ Catalog Entry、Manifest/Bundle 下载、验签、安装、启用、禁用、更新、回滚、移除
|
||||
|
||||
@@ -494,6 +542,9 @@ MiniApp SDK 与参考实现稳定后，再按顺序推进：
|
||||
→ 搜索、分类、发布者、安装 UX、组织分发与可能的商业能力
|
||||
```
|
||||
|
||||
`03.sdk_and_coreapp` 已经包含 Task Dashboard 和 Whiteboard 的端到端参考实现；不再另设
|
||||
`03.reference-miniapps`，以免把同一批工作拆成两个编号。
|
||||
|
||||
“市场”属于最后的产品分发层，不能反向决定 Runtime、SDK、Tool 或安全模型。
|
||||
|
||||
## 11. 验收与发布门槛
|
||||
@@ -508,19 +559,27 @@ npm run build
|
||||
对于 SDK/参考 MiniApp，还必须有以下证据：
|
||||
|
||||
1. 合法与非法 Manifest、Inventory revision、Tool 输入/输出 schema 的自动化测试；
|
||||
2. Tool 启动 MiniApp、前后台切换、结果回传、失败回焦和重启恢复的场景测试；
|
||||
3. Interact 的 `notice / choice / confirm / input` IM 呈现不退化，且覆盖 owner 自动注入、跨 owner
|
||||
访问/提交拒绝、owner 结果回路与 MiniApp 容器内呈现的测试；
|
||||
4. Installed MiniApp 无法取得 Host DOM、Tauri invoke、token、任意网络或其他 MiniApp 数据；
|
||||
5. 有头浏览器验证登录、同步、本地回显和代表性 MiniApp 路径；
|
||||
6. 对生产 Bundle，验证签名 `open → patch → close → rollback`、隔离 Bridge 和 Capability 拒绝路径；
|
||||
7. `git diff --check` 无格式错误，日志不得包含身份、会话、消息正文、Tool 参数、token 或
|
||||
2. Tool 启动 MiniApp、前后台切换、结果回传、失败回焦和重启恢复的场景测试；接受关闭后，未终态普通 Tool
|
||||
仅产生一次 `app_closed` 取消、已 submitted 结果继续 outbox，随后才关闭 Surface / instance 并恢复焦点；
|
||||
3. Interact 的 `notice / choice / confirm / input` 会话呈现不退化，覆盖 IM 内联与前台 bundled
|
||||
MiniApp 上交互层的显示、conversation/call 绑定、结果可靠回传 Agent、默认/越界交互期限、非法
|
||||
`app_session_context` 拒绝、`interaction.dismiss` 幂等重放，以及 bundled MiniApp 无法访问或提交交互的测试；
|
||||
4. MVP 的单 Agent 身份随交互和 App 子会话持久化；不新增多 Agent 连接、切换、会话列表或路由；
|
||||
5. App instance 的子会话创建、后台/暂停保留、`AppLifecycleManager.close` 后结束折叠、重启恢复和新 instance 隔离可验证；创建时会可靠向 Agent
|
||||
提供 `app_session_id`，关闭时会发出包含仍 pending interaction call_id 的可靠 App 已关闭事件，但不会自动
|
||||
取消 Interact 交互；子会话只包含人与 Agent 的交互，不包含 MiniApp 的内部业务操作；
|
||||
6. 已结束子会话可只读查看；“继续处理”旧工作会创建新 instance / 新子会话，可引用旧上下文但不复活旧问题；
|
||||
7. App 切换时未回答问题从前台 App 上方收起并在对应子会话标记；用户可在 IM 或回到原 App 后回答，且同一问题不可重复提交；
|
||||
8. Installed MiniApp 无法取得 Host DOM、Tauri invoke、token、任意网络或其他 MiniApp 数据；
|
||||
9. 有头浏览器验证登录、同步、本地回显和代表性 MiniApp 路径；
|
||||
10. 对生产 Bundle，验证签名 `open → patch → close → rollback`、隔离 Bridge 和 Capability 拒绝路径；
|
||||
11. `git diff --check` 无格式错误，日志不得包含身份、会话、消息正文、Tool 参数、token 或
|
||||
artifact 内容。
|
||||
|
||||
## 12. 相关文档与源码导航
|
||||
|
||||
- [迭代/00.base.md](迭代/00.base.md)：Runtime 托管 Interact IM 的稳定基线。
|
||||
- [迭代/01.kernel.md](迭代/01.kernel.md)：Runtime Kernel 与 MiniApp 编排目标和验收。
|
||||
- [迭代/00.base/00.base.md](迭代/00.base/00.base.md)：Runtime 托管 Interact IM 的稳定基线。
|
||||
- [迭代/01.kernel/01.kernel.md](迭代/01.kernel/01.kernel.md)：Runtime Kernel 与 MiniApp 编排目标和验收。
|
||||
- [tauri/src/README.md](tauri/src/README.md)：当前源码目录和依赖方向。
|
||||
- [tauri/README.md](tauri/README.md)：Tauri/Web Host 的运行、回归与历史实施细节。
|
||||
- [程序文件清单与功能说明.md](程序文件清单与功能说明.md)：实现文件和功能说明。
|
||||
|
||||
Reference in New Issue
Block a user