app/迭代/03.sdk_and_coreapp/01.design_review.md

03.sdk_and_coreapp 第 1 次设计评审记录

评审日期：2026-08-05 评审编号：01 评审基线：APP架构设计.md 评审对象：03.sdk_and_coreapp.md 评审方式：独立子 agent 只读评审；本文件记录评审意见，不代表已采纳或已实现。

后续决议（2026-08-05）： MiniAppManifest.kind 收敛为 system | bundled。Task Dashboard 与 Whiteboard 均为非系统级 bundled MiniApp，必须采用与一般 MiniApp 相同的受限 Surface / Bridge 模型；“参考”仅描述它们在本迭代验证 SDK 的目的。下文的 bundled-reference 为评审时的 历史术语，已由此决议取代。

后续决议（2026-08-05）： notice / choice / confirm / input 始终是 Interact 的人与 Agent 会话交互，不属于 MiniApp SDK，也不用于 MiniApp 内部业务逻辑。当前 bundled MiniApp 位于前台时， Interact / Shell 可在其上方显示同一会话的交互层；请求与答案仍只属于 Interact、当前会话和 Agent。

后续决议（2026-08-05）： 每个启动的 App instance 在主 IM 中创建或恢复一个 App 子会话；其中 只保留人与 Agent 围绕该 App 的提问、回答和简洁结果。App 的内部按钮、表单、画布编辑等业务操作 不进入子会话。后台化不结束子会话；真正结束时保留折叠历史；新的 instance 创建新的子会话。

后续决议（2026-08-05）： 已结束的 App 子会话可以在主 IM 中只读展开。用户选择“继续处理”时， Runtime 创建新的 App instance 和新的子会话；新会话可引用旧会话或 App 数据，但不能续写旧记录或 复活旧问题。

后续决议（2026-08-05，已更新）： App 子会话只在 AppLifecycleManager.close 使对应 instance 停止或失败时结束；前后台切换、暂停和 Agent Tool 完成都不结束子会话。关闭时，Runtime 向 Agent 可靠发送 App 已关闭事件；尚未回答的 Interact 交互不自动取消，Agent 可 remote dismiss，或让其继续 在主 IM 中等待用户回答/超时。子会话保留为主 IM 历史。

后续决议（2026-08-05）： MVP 中一个 LineUp Runtime 只连接一个 Agent。每条标准交互和 App 子会话仍保存当前 agent_uid 作为 agent_id，但本迭代不实现多个 Agent 的连接、切换、 会话列表、outbox 或路由。

问题清单（Outline）

状态标记： ✅ 已解决并回填设计； 🟡 待产品/架构决策； 🔵 待在契约中细化； ⚪ 待实施编排或文档整理； — 不再适用。

本清单是当前有效视图；后文保留评审时的原始问题、分析和建议作为依据。每次确认一个决策或完成 回填时，应先更新此处状态，再更新对应正文和验收项。

状态	编号	问题	当前结论 / 下一步
✅	B1	Task Dashboard 的信任级别与 UI 容器	已确认：Task Dashboard、Whiteboard 均为非系统级 kind = bundled MiniApp，必须运行于受限 Surface / Bridge，不能使用可信 Host DOM。
✅	I1	bundled-reference / bundled-development 命名歧义	已确认：Manifest 枚举为 system | bundled；“参考”仅描述当前迭代的工作目的。
✅	I2	标准交互由谁显示、答案如何回传	已确认：Interact / Shell 显示人与 Agent 的交互；bundled MiniApp 前台时可被该交互层覆盖。结果由 Runtime 可靠回传 Agent，不交给 MiniApp。
✅	I3	标准交互与 Agent Tool Call 的关系	已确认：标准交互仅由 Agent Tool 调起并创建交互记录；MiniApp 不存在 sdk.ui.request，不会自行创建 Agent Tool Call。
✅	I4	标准交互结果的返回通道	已确认：用户答案先回 Runtime，再可靠回传 Agent；不经 MiniApp Inbox、Tool 订阅或 MiniApp SDK 返回。
✅	I5	Request/Result schema、状态机、幂等与错误码	已确认第一版：notice 非阻塞；confirm 二选一且默认取消；choice 只支持 2～6 项单选；input 只支持一个文本输入；首次有效回答终结交互；默认 15 分钟超时，可在 1 分钟～24 小时内调整。
✅	I6	敏感输入的持久化、恢复、审计和日志边界	已确认：未提交草稿仅存在当前运行期间，重启即清空；已提交的人与 Agent 答案保留在所属主 IM 或 App 子会话中，随父 IM 会话处理；二者均不写日志、Telemetry 或普通审计明文。
✅	I7	App 子会话与主 IM 的关系	已确认：每个 App instance 创建/恢复一个子会话；后台保留，真正结束后在主 IM 中折叠存档，新 instance 独立。仅记录人与 Agent 围绕 App 的交互，不记录 App 内部业务操作。
✅	I8	已结束 App 子会话的查看与继续处理	已确认：旧子会话可只读展开；继续旧工作创建新 instance / 新子会话，可引用旧上下文，但不追加旧记录或复活旧问题。
✅	I9	App 子会话何时结束	已确认：仅 AppLifecycleManager.close 导致 instance stopped/failed 时结束；前后台切换、暂停、Agent Tool 完成不结束。关闭时 Runtime 向 Agent 发送 App 已关闭事件，但不自动取消未回答的 Interact 交互。
✅	I10	MVP 的 Agent 身份范围	已确认：Runtime 仅连接一个 Agent；交互和 App 子会话保存该 agent_id，但不实现多 Agent 连接、切换或路由。
—	S1	parent_call_id 的关联校验与父 Tool 终止后的处置	不再适用：MiniApp 不再发起标准交互；标准交互直接绑定 Agent call 与 conversation。
✅	S2	交互层显示与恢复规则	已确认：原 App 前台时显示交互层；切换到其他 App/IM 时收起并在子会话标记“等待你的回答”；用户可在 IM 或回到原 App 后回答；关闭 App 只移除覆盖层并通知 Agent，不自动取消交互。
✅	S3	Interact 呈现与 Agent Tool 回传的分层	已确认：Interact / Shell 只显示并把用户动作/答案交给 Runtime；Runtime 根据已保存的交互上下文校验、持久化和可靠回传 Agent；不经过 MiniApp。
✅	S4	阶段编号重复	已确认：Task Dashboard / Whiteboard 的端到端参考实现属于 03.sdk_and_coreapp；移除重复的 03.reference-miniapps，后续应用分发阶段保持为 04.app-delivery-registry。
✅	S5	实施步骤顺序	已确认：先完成通用 Tool 闭环，再完成 Runtime 独占的 Agent interaction service 和 Interact 回传契约，之后才适配 Interact、实现两个 bundled 参考 MiniApp，最后端到端验收。

1. 总体结论

这份文件保留了首次评审时提出的问题和建议，方便追溯讨论过程；其中涉及 sdk.ui、MiniApp 发起 标准交互、owner 注入等早期设想，均已被本文件顶部的“后续决议”和问题清单中的最终结论取代，不能作为 实施依据。

当前已经收敛的核心结论是：

• 产品层级是 LineUp App → LineUp Runtime → MiniApps，Runtime 不是与 MiniApp 平级的产品 App。
• notice / choice / confirm / input 是 Interact 中人与 Agent 对话的一部分，不是 MiniApp SDK，也不能由 bundled MiniApp 发起、读取、提交或取消。
• Interact / Shell 只呈现和收集用户答案；Runtime 保存交互归属、校验首次有效回答、写入可靠 outbox，并 向当前唯一 Agent 回传结果。
• Task Dashboard 与 Whiteboard 都是 kind = bundled；它们使用一般 MiniApp 的受限 Surface、Bridge、 生命周期和 SDK，只保留自身的业务 UI。
• 保留 lineup.v1.tool.call(choice | confirm | input) 的 Agent 交互兼容入口；不在本迭代迁移 chat → interact 命名。
• 本迭代不建设 AppServer Catalog、下载、安装、更新、市场、远程 Bundle、真实媒体/文件能力或多 Agent Runtime 连接。

本轮评审问题均已得到设计结论，后续进入实现时应以 03.sdk_and_coreapp.md 和 APP架构设计.md 为准。

2. 阻塞问题

B1. Task Dashboard 的可信 DOM / Host adapter 权限突破了当前信任模型

架构基线在 APP架构设计.md 的 MiniApp 信任模型中明确：

• Interact / System MiniApp 可使用可信内建 DOM 组件；
• Installed MiniApp 必须经隔离 iframe / Surface Bridge 运行。

而 03.sdk_and_coreapp.md 同时写了：

Task Dashboard 可由受信 Host adapter 挂载；Whiteboard 必须走受限 Surface

并将 Task Dashboard 定义为：

kind = bundled-reference

且说明它可使用“随 LineUp 发布的受信 Host adapter”。

问题： 当前权威架构没有明确授权 bundled-reference 获得与 System MiniApp 相同的可信 DOM 容器。若 Host adapter 可执行或挂载 Task Dashboard 的 UI，而未经过受限 Surface，隔离边界、SDK 受限视图和“禁止访问 Host DOM”就无法以同一安全模型证明。

需要冻结的决策（二选一）：

1. 保守方案，且最符合当前权威基线： Task Dashboard 和 Whiteboard 都是非 System MiniApp，必须经隔离 Surface / Bridge 运行。Host adapter 仅作为 Runtime/Shell 的不可见装配层，不向 MiniApp 提供可直接操作的可信 Host DOM。
2. 若产品确实需要 Task Dashboard 使用可信原生 DOM： 将其升级为 kind = system，并在架构主文档新增或明确“bundled trusted system MiniApp”信任层、发布来源、可用 DOM 权限和审计边界；不能继续称其为普通 bundled-reference。

建议验收：

• 若维持 bundled-reference，Task Dashboard 无法获得 Host 根 DOM、Tauri invoke 或未授权 Host adapter。
• 若改为 system，仍要验证其特权只限 Runtime SDK，不能取得 Transport、Store 或 Agent 访问权。

3. 重要问题

I1. bundled-development 与 bundled-reference 的术语、Manifest 枚举未建立映射

迭代文档把“内置”解释为 bundled-development，但冻结的 MiniAppManifest.kind 只有：

kind: "system" | "bundled-reference";

架构主文档也使用了“参考 MiniApp 在此阶段可以是 bundled-development”的表述。

这两个词可以共存，但必须明确它们不是互相竞争的 kind 枚举值。

建议补充最小映射表：

概念	建议语义
bundled-development	本迭代的交付/加载方式：随开发 Host 预置，不下载、不安装、不经服务端 Catalog。
kind = bundled-reference	Manifest 身份：参考 MiniApp，决定 SDK / Surface 信任策略。
kind = system	随产品发布、代码可信的系统 MiniApp，例如 Interact。

并明确：bundled-development 不是 MiniAppManifest.kind 的第三个取值。

I2. sdk.ui 缺少 Renderer 如何安全提交用户结果给 Runtime 的闭环契约

当前公开 API 只有：

request(...)
get(...)
subscribe(...)
cancel(...)

但未定义：

• Runtime 如何把被 Policy 选中、可呈现的 interaction record 交给 renderer；
• renderer 如何提交 submitted、result 或 cancelled；
• Runtime 如何校验 interaction_id、owner、renderer binding、状态迁移、一次性提交和结果 schema；
• 在 opaque-origin iframe / Surface Bridge 内，呈现和回传采用何种受限消息协议；
• renderer 与 owner 是同一 MiniApp 时，是否通过 sdk.ui 提交，还是只能通过 Runtime/Shell 私有 Renderer API 提交。

建议冻结 Runtime 私有 Renderer Contract / 最小 Bridge Contract：

Runtime 分配 interaction_id + renderer_binding + presentation container/surface
→ renderer 仅接收 presentation-safe request projection
→ renderer 向 Runtime-owned endpoint 提交 action/result
→ Runtime 校验：
  - 被分配的 renderer / container
  - interaction_id
  - owner binding
  - 当前状态与一次性提交
  - result schema
  - expiry
→ Runtime 持久化状态迁移，并向 owner-scoped ui 订阅发出更新

隔离 Surface 至少还要限定消息白名单、surface_id / instance_id 绑定和 nonce 或等效关联方式；不得只凭 origin 信任。

I3. 标准交互与 RuntimeToolCallRecord 的关系不清晰

当前文档同时规定：

• MiniApp 可调用 sdk.ui.request(...)；
• owner 的 source 可为 agent_tool | miniapp_tool | runtime_policy；
• 所有标准交互“必须映射为 Runtime 统一的 interactive Tool Call / StandardInteractionRecord”。

因此会产生问题：Task Dashboard 在没有 Agent Tool Call、例如用户点击“关闭未完成任务”时调用 sdk.ui.request(confirm)，Runtime 是否必须凭空创建 Agent-facing RuntimeToolCallRecord？

建议明确拆成三条路径：

来源	Runtime 记录	与 Agent Tool 的关系
Agent / legacy lineup.v1.tool.call(choice/confirm/input)	RuntimeToolCallRecord + StandardInteractionRecord	交互终态受控驱动该 Tool 的后续处理。
MiniApp sdk.ui.request(...)	owner-bound StandardInteractionRecord	不自动创建新的 Agent Tool；若提供合法 parent_call_id，只建立关联。父 Tool 的完成由 owner 经 sdk.tools.* 决定。
Runtime Policy 自发提示	runtime_policy owner 的 interaction record	需明确其是否绑定某一 Capability / lifecycle request。

没有 parent Tool 的交互只改变 MiniApp 本地工作流，不应制造 Inventory、Agent 回传或 outbox 语义。

I4. 结果投递位置与公开 API 不一致

流程写“结果仅投递回 owner MiniApp 的 Tool/Inbox”，但 SDK 已公开 sdk.ui.get/subscribe。

否则实现可能分叉成：

1. 结果通过 sdk.ui.subscribe 的 record update 返回；
2. 结果作为 Inbox 消息；
3. 结果通过 parent Tool 的 SDK Tool event 返回。

建议冻结为：

sdk.ui.get / sdk.ui.subscribe
= owner 获取标准交互状态与结果的唯一 UI-domain 通道

sdk.inbox
= Agent / Runtime 入站消息；不复用为 interaction result transport

sdk.tools.complete / fail / cancel
= owner 根据 UI result 自行决定是否推进关联 parent Tool

还需定义：订阅是否立即回放 owner 当前 pending records、终态保留/清理策略、断线重连后的重放及去重语义。

I5. Schema、状态机、幂等规则不足以支持安全验收

已有四类 request 及基础状态，但还需要明确：

• StandardInteractionResult 与 InteractionReceipt 的类型；
• choice.actions[].id 的唯一性、最大数量、空数组是否允许，以及 single/multi/button 的选择基数；
• input.fields[].id 的唯一性、字段数上限、必填、数值解析、空字符串、长度和范围的适用规则；
• notice 的“只读”与 acknowledged 的精确定义：是否需要用户确认、是否自动完成、是否可超时；
• request、submit、cancel、超时、恢复之间的合法状态迁移；
• 并发提交、重放、重复取消、跨 Surface 重放的确定性返回；
• 交互专用稳定拒绝码。

建议至少增加：

interaction_not_found
interaction_owner_mismatch
interaction_state_invalid
interaction_expired
interaction_result_invalid
interaction_renderer_mismatch
parent_call_invalid

I6. 持久化、审计与敏感输入的日志最小化约束尚未衔接

input 可以含用户自由文本；标准交互要求持久化、恢复和审计，但架构文档又要求日志不得包含身份、会话、消息正文、Tool 参数、token 或 artifact 内容。

建议明确：

• 恢复所需的受保护 operational state、审计最小元数据、日志/Telemetry 三者的分层；
• input 草稿和结果的保留期、终态清理策略，以及是否加密；
• 审计仅记录 interaction ID、kind、受保护 owner 标识、状态迁移和错误码；
• title、prompt、字段值和 action label 不进入日志、指标、错误详情或普通审计明文；
• 验收增加日志负向断言。

4. 建议完善项

S1. 扩大 parent_call_id 校验条件

除“属于当前实例且状态允许关联”外，Runtime 至少应校验：

同 app_scope
同 instance_id
同 conversation_id
父 Tool 非终态
不存在跨 owner 关联

还要定义父 Tool 被取消或超时时关联 interaction 的处理：自动取消、保留为独立操作，或交由 Policy 决定。否则恢复后容易遗留孤儿卡片。

S2. 将 presentation policy 写成可判定矩阵

至少应覆盖：

owner 状态 / 容器	建议行为
Agent IM / Interact 有效	Interact IM timeline/card。
owner 前台且存在合法 renderer	owner 容器或已绑定 Surface 的标准 modal/sheet/card。
owner 后台或 suspended	保持 pending；通知/唤醒仅经 Policy，不得抢占焦点。
Surface 已关闭或失效	不向旧 Surface 投递；恢复、降级或安全失败。
renderer 不可用	保持 pending 或返回稳定拒绝码；不能把 payload 注入 Host DOM。
系统能力确认	走 Capability Gateway，禁止降级为普通 confirm。

S3. Interact 呈现与 Agent Tool 回传的分层

已确认（2026-08-05）： 用户在 Interact 中回答时，Interact 只负责显示问题、收集用户动作并把 答案交给 Runtime。它不是 Agent 的消息发送端，也不负责判断答案属于哪个 Agent、哪个会话或哪个 App 子会话。

Interact / Shell 显示问题
→ 用户作答
→ Interact 向 Runtime 提交「interaction_id + 用户动作/答案」
→ Runtime 从已保存的交互记录取得 agent_id、conversation、App 子会话和 Agent Tool 归属
→ Runtime 核对 Interact 实例、展示位置、状态、期限、答案格式和首次提交
→ Runtime 持久化会话记录与终态，并写入可靠 outbox
→ Runtime 向当前唯一 Agent 回传一次结果

提交端不能传递或覆盖 agent_id、conversation_id、call_id、app_session_id 等归属信息；这些 只能由 Runtime 创建交互时保存。重复点击、刷新后的旧页面、无效展示位置、过期或已结束问题的提交都 必须被拒绝，且不能改变已经保存的结果或再次通知 Agent。Task Dashboard、Whiteboard 等 bundled MiniApp 始终不参与这条链路，也读不到问题或答案。

S4. 统一阶段编号

已确认（2026-08-05）： Task Dashboard 与 Whiteboard 是 03.sdk_and_coreapp 中用来验证 SDK 的 bundled 参考 MiniApp，本阶段就完成其端到端路径。因此删除重复的 03.reference-miniapps；后续阶段 保持为 04.app-delivery-registry，不需要整体重编号。

S5. 在实施步骤中拆出标准交互服务和 renderer/Bridge 契约

已确认（2026-08-05）： 实施顺序已调整为：

1. 冻结契约与测试样本；
2. 实现 Runtime 通用 Tool 闭环；
3. 实现 Runtime 独占的 Agent interaction service，以及 Runtime ↔ Interact 的最小呈现/提交契约；
4. 再适配 Interact IM 和 App 子会话；
5. 最后通过 Task Dashboard、Whiteboard 验证一般 bundled MiniApp 路径，并进行端到端验收。

这样标准交互不会先被做成 Chat 专用或 MiniApp SDK 能力；Interact 只是第一个使用 Runtime 私有交互 契约的系统级呈现者，两个 bundled MiniApp 则只验证各自的 Tool、Surface 和业务 UI 边界。

5. 建议新增的最小验收场景

1. A 实例提交属于 B 实例、不同 conversation 或已终态 Tool 的 parent_call_id 时，Runtime 拒绝且不创建 record。
2. A 创建 interaction 后，B 无法 get、订阅、取消、提交，或通过伪造 interaction_id 获得任何 payload/result。
3. 同一 interaction 的两次 renderer submit 只有一次成功；第二次得到稳定终态错误且不改变已持久化结果。
4. 旧 lineup.v1.tool.call(choice|confirm|input) 创建关联 Tool Call 和 owner 为 Interact IM context 的 interaction；用户结果先由 Runtime 落库，再由 Interact 以 owner 身份完成 Tool。
5. Task Dashboard 无 parent Tool 的 sdk.ui.request(confirm) 不创建 Agent-facing Tool Call、不写 Agent outbox；带合法 parent Tool 时仅关联，不自动完成该 Tool。
6. Task Dashboard 前台时，标准 modal/sheet/card 在其合法容器显示，焦点栈与 Interact background 状态不被改写。
7. Whiteboard 在 Surface reload、关闭、旧 iframe 重放提交时，surface_id 与 renderer binding 都被验证，旧 iframe 消息被拒绝。
8. 非法 input、重复/未知 choice action、过期 interaction、跨 owner cancel 都被拒绝且不写错误结果。
9. 标准交互输入值、提示正文、选择标签不出现在日志、Telemetry 或 Audit 明文中；重启恢复仅保留设计允许的最小数据。
10. 若维持 bundled-reference，Task Dashboard 不能直接挂载可信 Host DOM；若改为 system，必须有对应的 manifest/source-trust 回归用例。

6. 建议的阅读和决策顺序

明天继续时，建议按以下顺序决策和回填：

1. 先决定 B1：Task Dashboard 的信任级别与 UI 容器；
2. 冻结 I2：Renderer → Runtime 的提交/Bridge 契约；
3. 冻结 I3/I4：StandardInteractionRecord 与 Tool Call 的关系，以及 UI result 的唯一返回通道；
4. 细化 I5/I6：schema、状态机、幂等、错误码、持久化与日志最小化；
5. 把 S1～S5 与第 5 节的验收场景回填入 03.sdk_and_coreapp.md 和必要的 APP架构设计.md。

在上述收敛前，不建议开始 standard-interaction-service 或参考 MiniApp 的实现，以免重新形成 Chat / Interact 专用旁路。