docs: freeze runtime workspace iteration design

迭代/plan.md

@@ -47,7 +47,7 @@ Runtime 已具备应用实例、焦点和生命周期的核心模型：
 `03.sdk_and_coreapp` 已完成并通过自动化测试和浏览器验收：
 
 - Interact 是唯一的 `system` MiniApp；
-- 番茄时钟、Task Dashboard 和 Whiteboard 都是普通 `bundled` MiniApp；
+- Task Dashboard 和 Whiteboard 都是普通 `bundled` MiniApp 的参考实现；
 - MiniApp 通过 SDK 接收 Inbox、Tool、进度、结果、生命周期、Surface 和 Capability 请求；
 - 标准 `notice / choice / confirm / input` 属于 Interact 的人与 Agent 交互，不是 MiniApp 内部表单；
 - App 子会话、交互归属、关闭收口、继续处理和重启恢复已有明确规则；
@@ -57,6 +57,10 @@ Runtime 已具备应用实例、焦点和生命周期的核心模型：
 
 ## 3. 第四次迭代：Runtime 工作区与应用闭环
 
+**设计状态：** 已冻结，待实施；冻结基线为
+[04.runtime_workspace.md](04.runtime_workspace/04.runtime_workspace.md) 及其
+[03.design_review.md](04.runtime_workspace/03.design_review.md)。
+
 建议迭代目录：
 
 ```text
@@ -70,12 +74,11 @@ Runtime 已具备应用实例、焦点和生命周期的核心模型：
 ```text
 进入 Interact IM
   → Agent 请求启动 Pomodoro 番茄时钟
-  → Runtime 创建 App instance 和 App 子会话
+  → Runtime 创建 App instance、App 子会话和 deadline operation
   → 番茄时钟进入前台，Interact 进入后台
-  → 计时在后台继续运行
-  → 用户可以暂停、继续、取消或回到 Interact
-  → 到时间后显示完成提醒并回传结果
-  → 用户关闭 App，Runtime 收口未完成操作
+  → 用户进行写作业、看书或冥想等固定时长专注；自动暗屏/锁屏不终止本轮
+  → 到时间完成，或用户主动离开 Pomodoro 工作区而中断
+  → Runtime 回传唯一结果并关闭 App
   → 子会话结束并在 IM 中折叠保存
   → Interact 恢复
   → 用户查看历史或继续开始下一轮
@@ -85,16 +88,21 @@ Runtime 已具备应用实例、焦点和生命周期的核心模型：
 
 1. **接通 App 工作区界面**
    - 显示当前前台 App；
-   - 支持 Interact、Pomodoro 番茄时钟、Whiteboard 的切换；
+   - 支持由 `pomodoro.start` 从 Interact 进入 Pomodoro，以及用户明确返回 Interact；
+     返回/切换会中断当前专注，不把 Pomodoro 作为通用后台计时器继续运行；
    - 显示后台、挂起、关闭和恢复状态；
    - App 启动失败时恢复 Interact；
    - 刷新或重启后恢复工作区。
 
+   Whiteboard 在第 04 次只保持第 03 次已有的 SDK/隔离回归，不接入本轮工作区切换或新的完整流程。
+
 2. **接通 App 生命周期**
    - 将 `AppLifecycleManager`、`AppFocusManager` 和 `AppOrchestrator` 接入真实 Host；
-   - 区分后台、挂起和真正关闭；
+   - 区分自动暗屏/锁屏、Surface 重载、工作区切换和真正关闭；前两者不终止专注，后两者中断专注；
+   - Runtime 使用持久化 `ends_at` 的 deadline operation，而不是 MiniApp UI 定时器；
    - 关闭后停止新 Tool 投递；
-   - 将未终态普通 Tool 收敛为 `cancelled(app_closed)`；
+   - 用户退出专注时先将 `pomodoro.start` 终结为 `interrupted`；其他未终态普通 Tool 才收敛为
+     `cancelled(app_closed)`；
    - 已提交结果继续通过 outbox 发送；
    - 关闭后恢复前一个有效前台 App。
 
@@ -113,39 +121,46 @@ Runtime 已具备应用实例、焦点和生命周期的核心模型：
    - Agent 可以通过 `interaction.dismiss` 远程取消交互。
 
 5. **让 Pomodoro 成为第一条完整用户流程**
-   - Agent 请求启动一个番茄钟；
-   - Runtime 创建计时实例和 App 子会话；
-   - 用户可以查看剩余时间、暂停、继续和取消；
-   - 番茄钟切到后台后仍能继续计时；
-   - 到时间后显示完成提醒并回传结果；
-   - 用户关闭番茄钟时，Runtime 正确取消未完成操作；
-   - 刷新或重启后根据 `ends_at` 恢复剩余时间；
+   - 用户在 IM 中以自然语言要求 Agent 开始或结束写作业、看书或冥想等专注；MiniApp 是 Agent 的业务工具，
+     而不是由用户自行操作业务状态的独立应用。未来 Voice 复用相同意图和 Tool 语义，但不属于本轮实现或验收；
+   - Agent 以 `pomodoro.start({ duration_seconds, activity? })` 创建长期 Tool operation，并以
+     `pomodoro.interrupt({})` 请求结束当前专注；
+   - 同一会话已有 `focusing` 专注时，不同调用的第二次 `pomodoro.start` 稳定拒绝为
+     `active_focusing_operation`，不创建新的 App、子会话或 deadline operation；
+   - Runtime 创建 Pomodoro instance、App 子会话和 deadline operation，Pomodoro 直接进入专注界面；
+   - 到时间得到 `completed`；Agent 调用 `pomodoro.interrupt`，或用户切回 Interact、切到其他 MiniApp、关闭
+     Pomodoro 时得到 `interrupted`；后者由 Runtime 的生命周期处理，不伪造 Agent Tool；不支持暂停、继续或恢复；
+   - 自动暗屏、锁屏与 Surface 重载不终止专注；刷新或重启后根据 `ends_at` 恢复或结算一次；
+   - 到时间后 Runtime 回传一次结果并立即关闭 Pomodoro，完成结果由 Interact / Agent 呈现；
    - 完成记录和子会话可以在 Interact 中查看。
 
    第一版只保留这些状态和数据：
 
    ```text
-   state = idle | running | paused | completed | cancelled
-   timer_id
+   state = focusing | completed | interrupted
+   operation_id
+   source_tool_call_id
+   activity?
    duration_seconds
    started_at
    ends_at
-   remaining_seconds
+   ended_at?
+   interruption_reason?
    ```
 
-   建议的最小 Tool：
+   最小 Agent Tool：
 
    ```text
-   pomodoro.start
-   pomodoro.pause
-   pomodoro.resume
-   pomodoro.cancel
-   pomodoro.status
+   pomodoro.start({ duration_seconds, activity? })
+   pomodoro.interrupt({})
    ```
 
-   番茄钟到时间后的普通完成提醒属于 MiniApp 自己的业务提示；如果以后需要系统通知，再通过
-   Runtime 的 Capability 请求，不能让 MiniApp 直接调用 Tauri 或操作系统接口。Agent 询问用户是否
-   开始下一轮时，仍然必须使用 Interact 的标准交互。
+   Pomodoro 使用 `app.instance-state.v1` 保存严格 schema v1、最大 4 KiB 的展示快照；关闭后采用
+   `retain_readonly`，旧快照只用于历史展示，不能再次写入或恢复为运行中的专注。
+
+   番茄钟到点后不保留 App 内完成提醒：Runtime 关闭 Pomodoro 并恢复 Interact，由 Interact / Agent 呈现
+   完成结果。如果以后需要系统通知，再通过 Runtime 的 Capability 请求，不能让 MiniApp 直接调用 Tauri
+   或操作系统接口。Agent 询问用户是否开始下一轮时，仍然必须使用 Interact 的标准交互。
 
 6. **补充端到端验收**
    - Web Reference Host 完整验收；
@@ -160,20 +175,23 @@ Runtime 已具备应用实例、焦点和生命周期的核心模型：
 - 多 Agent 连接、切换和多 Agent 会话列表；
 - Audio Mode 的真实媒体能力；
 - Video Mode 的真实媒体能力；
-- Whiteboard 的多人协作和复杂绘图能力；
+- Whiteboard 的工作区接入、切换、多人协作和复杂绘图能力；第 04 次只保持其已有回归；
 - Task Dashboard 的完整项目管理功能；
 - Pomodoro 的统计报表、多个计时器、日历和复杂提醒计划。
 
 ### 3.4 完成标准
 
 ```text
-用户可以从 Interact 启动 Pomodoro 番茄时钟；
-Runtime 可以正确创建、切换、后台化、关闭和恢复 App；
+用户可以在 IM 中请求 Agent 立即开始或停止 Pomodoro 专注；未来 Voice 只复用相同 Tool 语义；
+Runtime 可以正确创建、运行、中断、关闭和恢复 Pomodoro App；
 App 子会话能在 IM 中折叠、展开和继续处理；
 标准交互在不同前台 App 下仍归 Interact；
-关闭 App 时 Tool 和 outbox 收口正确；
-刷新/重启后 App、焦点、子会话、计时剩余时间和待处理交互按规则恢复；
+到点/中断竞争唯一终态，Tool 和 outbox 收口正确；
+到点后立即关闭 Pomodoro 并由 Interact / Agent 呈现完成结果；
+Pomodoro 关闭后的业务快照保留为只读历史，不能复活旧 instance；
+刷新/重启后 App、焦点、子会话、`ends_at` 专注状态和待处理交互按规则恢复；
 Web/Tauri 代表性流程通过端到端验收；
+Whiteboard 保持第 03 次回归，但不属于第 04 次工作区闭环或完成范围；
 所有 P0～P3 评审问题清零。
 ```
 
@@ -242,6 +260,24 @@ Task Dashboard 仍然保留为后续普通 `bundled` MiniApp，但不作为 Runt
 
 ## 7. 更后面的方向
 
+### Runtime Core 的 Rust 演进
+
+在 Runtime 工作区已跑通并积累 Web / Tauri 两个 Host 的性能数据后，单独评估是否将部分**无 UI 的 Runtime
+Core** 下沉到 Rust，以改善状态处理和原子收口的效率与一致性。这不是第 04 次迭代的工作，也不等于把整个
+MiniApp SDK 改写成 Rust：Web Reference Host、sandbox iframe、postMessage Bridge、DOM 和 UI 仍须保持在
+TypeScript / 浏览器侧。
+
+潜在的 Rust 候选范围：
+
+- instance state 的持久化、schema 校验和 revision 比较；
+- deadline operation 调度；
+- Tool / outbox 的原子终态裁决；
+- lifecycle 收口和审计。
+
+只有在 profiling 显示上述路径存在明确热点时，才建立独立设计与迁移迭代。评估必须同时测量状态快照读写、
+deadline / Tool 吞吐、主线程阻塞、Tauri IPC 往返、JSON 序列化成本，以及 Web / Tauri Host 的实际差异；
+并证明收益覆盖跨语言实现、测试、调试和错误边界所增加的复杂度。
+
 ### 多 Agent
 
 在单 Agent 工作区稳定后再设计：