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

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

评审编号：02 评审日期：2026-08-05 评审对象：03.sdk_and_coreapp.md、01.design_review.md 评审方式：独立子 agent 只读复核 结论：核心方向已收敛；没有 P0 阻塞问题。以下 P1 项需在开始编码前逐项确认并回填主定义文档。

问题清单（Outline）

状态标记： ✅ 已确认并回填设计； 🟡 待产品/架构决策； 🔵 待在契约中细化； ⚪ 文档或实施编排建议； — 不适用或无此问题。

本清单是本次评审的当前有效视图。后文保留每个问题的背景和建议；在问题被确认前，建议不是实施依据。 确认后应先更新本清单，再回填 03.sdk_and_coreapp.md 的契约、实施步骤和验收项。

状态	编号	问题	当前结论 / 下一步
—	P0	阻塞级架构冲突	本次未发现需要推倒既有模型的 P0 问题。
✅	P1-1	Task Dashboard 示例中 Tool 完成后关闭 App	已回填：Tool 完成只回传 Agent；App 保留、后台或关闭由用户动作、requestClose 或 Lifecycle Policy 决定，只有真正 AppLifecycleManager.close 才结束 App 与子会话。
✅	P1-2	interactive Tool 的专用路由	已回填：interactive 是 Runtime 自己处理的 Agent 交互分支，不创建/复用业务 MiniApp instance，不调整业务 App 焦点，也不进入任何 MiniApp SDK Tool Inbox；Runtime 私有契约交给 Interact / Shell 呈现。
—	P1-3	展示位置切换后的提交资格	不再适用：展示位置不是交互 owner 或提交权限。切换 App 前后台、关闭 App 或改在 IM 显示不改变同一 interaction_id 的归属；Runtime 只接受首次有效回答，之后才拒绝重复/重放。
✅	P1-4	Tool 与交互的取消、超时和并发提交	已回填：用户回答、Agent dismiss、到期和 Runtime 失败竞争同一唯一终态；Runtime 第一个原子状态写入获胜，Tool 跟随同一结果，且只写一条 outbox。interactive Tool 仅使用交互 expires_at，不维护独立超时。
✅	P1-5	notice 的 Tool 完成时点与结果	已回填：notice 必须保留为 Interact / IM 的只读卡片，可选同时 Toast 数秒；Runtime 持久化卡片并安排呈现后，立即以 { outcome: "accepted" } 完成并回传，不表示用户已阅读。
—	P2-1	将普通标准交互统一当作敏感秘密输入	不再适用：notice / choice / confirm / input 按普通 IM 会话内容与日志基线处理；本迭代不为它们另设秘密输入契约或专门负向扫描。未提交草稿仍只在运行期存在，重启清空。
⚪	P4-1	首次评审中的历史提案可读性	遗留问题： 不阻塞本迭代；建议在下一次文档整理或新评审时，进一步突出其中 sdk.ui、owner、parent_call_id 等旧提案仅供追溯、不可实施。
⚪	P4-2	password-input 秘密输入原语	遗留问题： 当前不阻塞 03；真正出现密码、卡密、私钥或临时 token 的 Agent 交互需求时，单独定义该原语及其不显示明文、不进入普通 IM 正文/日志/Telemetry/审计、可靠传递与清理等安全契约。

通过项

• 标准交互已经清楚限定为 Interact 中的人与 Agent 会话交互，而非 MiniApp SDK；公开 SDK 不包含 sdk.ui。
• Task Dashboard、Whiteboard 已收敛为 kind = bundled，必须走受限 Surface / Bridge，不能取得可信 Host DOM、Tauri、Transport、Store、Agent 或其他 MiniApp 数据。
• 用户答案经 Interact 交给 Runtime；Runtime 保存交互归属、校验、持久化并可靠回传当前唯一 Agent，bundled MiniApp 不参与。
• App 子会话正确区分了人与 Agent 的记录和 MiniApp 内部业务操作；前后台、关闭、历史只读和“继续处理”的总体规则一致。
• MVP 单 Agent 边界明确，没有提前引入多 Agent 连接、切换或路由。

P0：阻塞问题

无。

P1：开始编码前需要确认的事项

P1-1：Tool 完成不应自动关闭 Task Dashboard

已解决（2026-08-05）： 主定义文档已经确认“Agent Tool 完成不自动关闭 App，也不结束 App 子会话”。Task Dashboard 示例与验收现已统一为该规则。

当前规则：

Tool 完成
→ Runtime 持久化并回传 Agent
→ App 是否保持前台、进入后台或关闭，取决于用户动作、MiniApp requestClose 或 Lifecycle Policy
→ 只有真正执行 AppLifecycleManager.close，才结束 App 与 App 子会话

验收已要求：Tool 成功回传后 Dashboard 可继续使用；只有真正关闭才结束子会话。

P1-2：interactive Tool 必须不进入 MiniApp SDK Tool Inbox

已解决（2026-08-05）： 通用 Tool 路由、实施步骤和验收已明确拆开 interactive 与一般 Tool。 notice / choice / confirm / input 不会投递到 App Orchestrator、业务 MiniApp instance、SDK Tool Inbox 或 sdk.tools.subscribe。

当前规则：

handling = interactive
→ 不投递任何 MiniApp SDK Tool Inbox
→ Runtime Agent interaction service 创建 StandardInteractionRecord
→ Runtime 私有契约交给 Interact / Shell 呈现
→ Interact 提交 interaction_id + 用户动作/答案
→ Runtime 校验、持久化、outbox 回传 Agent

handling = direct / launch / foreground / operation
→ 才进入 App Orchestrator、SDK Tool Inbox、MiniApp tools.* 路径

验收已要求：Agent 发起的四类标准交互不得出现在任何 MiniApp Inbox 或 sdk.tools.subscribe。

P1-3：切换展示位置后，旧页面必须失去提交资格

不再适用（2026-08-05）： 该问题错误地把 App 上方覆盖层或 IM 卡片当成了交互的 owner。标准交互 始终属于 Interact / 主 IM；app_session_id 只保留与哪段 App 工作相关的上下文，不形成 UI 父子关系。

切换 App 前后台、关闭 App 或改变展示位置不改变同一个 interaction_id 的归属，也不需要用 presentation_id / presentation_revision 废止旧页面的回答资格。只要用户仍处于有效 LineUp / Interact 会话且交互尚未终态，Runtime 可接受该交互的首次有效回答；以后到达的重复、重放或迟到提交 因交互已经终态而被拒绝。Shell 可以避免用户看到重复视觉卡片，但这是体验策略，不是结果正确性的依据。

验收应覆盖：交互从 Whiteboard 覆盖层改在 IM 中显示、Whiteboard 关闭后交互仍 pending 时，任一有效 Interact 页面提交的第一份答案只产生一次持久化结果和一次 Agent 回传；后续提交不改变结果。

P1-4：Tool 与交互的取消、超时和并发提交需要收敛规则

已解决（2026-08-05）： Runtime 是标准交互的唯一终态裁决者。用户回答、Agent dismiss、到期和 Runtime 失败都竞争同一条交互的唯一结果。

当前规则：

Runtime 对仍为 pending / presented 的 interaction 执行原子状态写入
→ 第一个成功写入的动作获胜
→ 用户回答：持久化答案，Tool 得到 answered
→ Agent dismiss：交互与 Tool 得到 cancelled
→ expires_at 到期：交互与 Tool 得到 expired
→ Runtime 失败：交互与 Tool 得到 failed
→ 同一事务或等价原子动作中只创建一条 Tool 结果 outbox

任何后到的回答、dismiss、取消或超时处理
→ interaction_already_final
→ 不覆盖结果，不创建第二条 outbox

MVP 中 interactive Tool 没有另一套独立 timeout；其期限就是交互 expires_at。Agent 主动停止等待必须走 dismiss，不走独立的通用 Tool 取消路径。

P1-5：notice 的完成时点和 Tool 结果需要固定

已解决（2026-08-05）： notice 是 Interact / IM 中持久保留的只读卡片；Toast 只是同一条 notice 记录的可选短暂提醒，不是没有历史的独立消息。

Runtime 校验并持久化 notice 卡片
→ 交给 Interact 呈现
→ 当前前台界面可同时 Toast 数秒
→ Runtime 立即以 { outcome: "accepted" } 完成并回传一次 Tool 结果

accepted 只表示 Runtime 已接受、保存并安排呈现，不表示用户已看见或阅读。Toast 自动消失、用户忽略 Toast 或收起 notice 卡片，均不产生新的 Agent 结果；持久化或安排呈现前 Runtime 失败时，结果为 failed。

P2：本迭代验收前必须处理（本次无未决项）

P2-1：将普通标准交互统一当作敏感秘密输入

不再适用（2026-08-05）： 此问题把所有标准交互一概当成秘密输入，边界过重且不符合产品语义。 notice、choice、confirm 与普通 input 是人与 Agent 的正常 IM 会话内容：已提交的内容按普通 IM 会话历史、保留与日志基线处理，不在 SDK v1 中额外定义为密码或秘密。全局日志基线仍然有效，不能因此 随意打印会话正文、Tool 参数或 token。

未提交的 input 草稿仍只能存在于当前运行期；重启后清空，不自动提交、发送或进入 outbox。这是恢复 和正确性要求，不代表普通 input 已升级为秘密输入能力。

P4：遗留问题（不阻塞当前迭代）

P4-1：首次评审中的历史提案可读性

延期原因： 顶部 Outline 和总体结论已经说明早期 sdk.ui、owner、parent_call_id 等提案不再是 实施依据；这不影响当前 SDK、Runtime 或验收实现。

建议在下一次文档整理或新的设计评审时，将原始评审正文加上“仅供追溯，禁止作为实现、测试或验收依据” 的更醒目标识，或移至附录。当前有效结论始终以主定义文档和评审记录顶部的 Outline 为准。

P4-2：password-input 秘密输入原语

延期原因： 当前 03 要完成的是 notice / choice / confirm / input 的 SDK v1 与会话交互闭环； 目前没有真实的密码、卡密、私钥或临时 token 输入场景。把秘密输入仅做成普通 input 的掩码样式，不能 解决内容怎样保留、传递、重试和清理的问题，因此不在本迭代仓促实现。

重新评估条件： Agent 确实需要向用户收集密码、卡密、私钥、临时 token 或同类秘密时，启动单独设计。 届时 password-input 应作为与 input 并列的 Agent 交互原语，由 Runtime 按 kind 强制执行安全契约， 而不是允许 Agent 用普通 input 自行约定保护方式。至少要明确：界面不显示明文；主 IM 只保留“已提交 敏感信息”等替代记录；内容不进入普通日志、Telemetry 或审计；可靠 outbox 的暂存、加密（如需要）、 Agent 接收后的清理、重启、失败、重试与一次性传递规则。