app/迭代/03.sdk_and_coreapp_comment.md

03.sdk_and_coreapp 设计评审记录

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

1. 总体结论

03.sdk_and_coreapp 的主方向已经与架构基线基本一致，以下核心决策已正确写入：

• 产品层级保持为 LineUp App → LineUp Runtime → MiniApps；Runtime 没有被写成与 MiniApp 平级的 App。
• SDK 使用 sdk.ui，不再使用旧的 sdk.interactions。
• 标准交互属于 Runtime 提供的标准输入输出库；Runtime 负责记录、owner 注入、校验、恢复、审计、路由和呈现 Policy。
• owner 不是 MiniApp 调用参数，而是从 SDK 已绑定的 MiniAppContext 自动注入；MiniApp 不能伪造或访问其他 owner 的交互。
• Interact 是 Agent/IM 场景的默认可信 Renderer Provider，不拥有交互记录，也不直接把结果发送给 Agent。
• Task Dashboard 可验证 sdk.ui 的通用事务提示，且不应因提示强制切换到 Interact。
• Whiteboard 的文字编辑、画笔、颜色选择、拖放、工具栏等高频或私有 UI 留在自身 Surface，不走 Runtime 标准交互。
• 保留 lineup.v1.tool.call(choice | confirm | input) 兼容路径；不把 chat → interact 命名迁移放进本迭代。
• 本迭代不建设 AppServer Catalog、下载、安装、更新、市场、远程 Bundle 或真实媒体/文件能力。

但仍存在 1 个阻塞级信任模型冲突，以及若干会造成实现分叉或验收不可判定的重要契约缺口。建议在进入实现前完成收敛。

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 的 Renderer 行为与 legacy Agent Tool 完结行为

当前“Renderer 呈现标准交互记录”与“Interact 以 sdk.tools.complete/fail/cancel 结束 Tool”的表述容易混淆。

建议统一为：

Renderer → Runtime：完成 interaction record
Runtime → owner：sdk.ui 状态更新
owner（legacy Agent Tool 场景中为 Interact）→ sdk.tools.complete / fail / cancel

这样不会把一般 Renderer 误写成跨域 Tool 结果出口。

S4. 统一阶段编号

架构主文档当前既有 03.sdk_and_coreapp，又有后续 03.reference-miniapps，但前者已经将 Task Dashboard / Whiteboard 的实现和端到端验收列为目标。

需要二选一：

• 删除或合并 03.reference-miniapps 到当前 03.sdk_and_coreapp；或
• 当前 03 只做 SDK/Interact 核心，参考 MiniApp 另起新编号并顺延 Catalog 阶段。

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

建议在通用 Tool 闭环之后、适配 Interact 之前增加独立步骤：

1. 实现 standard-interaction-service：owner 注入、记录、状态机、结果校验、过期、恢复、owner-scoped query/subscription；
2. 实现 renderer registration 与 presentation policy；
3. 定义并测试 System IM renderer 与 isolated Surface renderer 的最小回传协议；
4. 再接入 legacy Tool mapping、Interact 与两个参考 MiniApp。

这样可以避免先把能力实现成 Chat 专用逻辑、后续再进行高风险重构。

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 专用旁路。