docs: freeze runtime workspace iteration design

2026-08-06 14:39:19 +08:00
parent aff5c8e3aa
commit 91982fac33
8 changed files with 849 additions and 119 deletions
@@ -1,30 +1,35 @@
 # LineUp App 迭代定义：Runtime 工作区与 Pomodoro MiniApp

 **迭代编号：** 04.runtime_workspace
-**状态：** 草稿，待设计评审
+**状态：** 设计已冻结，待实施
 **日期：** 2026-08-06
 **前置基线：** [03.sdk_and_coreapp.md](../03.sdk_and_coreapp/03.sdk_and_coreapp.md)
 **总体计划：** [plan.md](../plan.md)
 **权威架构：** [APP架构设计.md](../../设计/APP架构设计.md)

+**冻结说明：** 本定义以 [03.design_review.md](03.design_review.md) 关闭后的决议为实施基线；后续若调整
+Pomodoro Tool、Runtime 终态、状态快照或本迭代范围，须通过新的设计评审记录确认。
+
 ## 1. 迭代目标

 前三次迭代已经完成 Runtime、Interact、MiniApp SDK v1 和参考 MiniApp 的基础契约。本迭代不再扩展
-复杂的业务应用，而是把这些基础接到真实的 Web/Tauri 工作区界面，证明用户可以启动、切换、后台化、
-关闭、恢复一个 MiniApp，并在 Interact 中查看对应的子会话。
+复杂的业务应用，而是把这些基础接到真实的 Web/Tauri 工作区界面，证明用户可以启动、运行、关闭、恢复
+一个 MiniApp，并在 Interact 中查看对应的子会话。

-本迭代选择一个极简的 **Pomodoro 番茄时钟 MiniApp** 作为 Runtime 验证应用。番茄时钟只负责倒计时和
-自己的完成提醒，不负责任务、项目或复杂业务管理。
+本迭代选择一个极简的 **Pomodoro 番茄时钟 MiniApp** 作为 Runtime 验证应用。它服务于写作业、看书、
+冥想等单次专注活动：第 04 次中用户通过 **IM** 请求 Agent 立即开始或停止一段固定时长的专注；未来 Voice
+复用相同意图与 Tool 语义，但不属于本轮实现或验收。Pomodoro 只负责低干扰显示，不负责任务、项目、统计或
+通用烹饪/家务倒计时。

 ```text
 Interact IM
  → Agent 请求启动 Pomodoro
-  → Runtime 创建 App instance 和 App 子会话
+  → Runtime 创建 App instance、App 子会话和 deadline operation
  → Pomodoro 进入前台，Interact 进入后台
-  → 计时在后台继续运行
-  → 用户暂停、继续、取消或回到 Interact
-  → 到时间显示完成提醒并回传结果
-  → 用户关闭 App，Runtime 收口并恢复 Interact
+  → 用户专注；自动暗屏或锁屏不改变本轮计时
+  → 到时间完成，或用户主动离开专注工作区而中断
+  → Runtime 回传结果并立即收口关闭 App，恢复 Interact
+  → Interact / Agent 呈现本次专注完成结果
  → 子会话在 IM 中折叠保存
  → 重启后按规则恢复或继续处理
 ```
@@ -35,7 +40,7 @@ Interact IM

 Interact 仍然是系统级 `system` MiniApp，负责人与 Agent 的交互：

- Agent 请求启动或控制番茄钟；
+- Agent 通过 `pomodoro.start` 请求立即开始一段专注，也可以通过 `pomodoro.interrupt` 结束当前专注；
 - Agent 向用户询问是否开始下一轮；
 - Agent 需要用户确认时使用 `notice / choice / confirm / input`；
 - 交互记录属于 Interact 和对应会话，不属于 Pomodoro 的内部 UI。
@@ -47,7 +52,8 @@ Runtime 负责最终裁决和可靠性：
 - 创建和管理 Pomodoro App instance；
 - 管理前台、后台、挂起、关闭和恢复；
 - 校验 Tool、作用域、实例和会话上下文；
- 保存计时状态和工作区快照；
+- 为每个 App instance 保存 schema 校验、revision 控制的业务状态快照；
+- 管理通用 deadline operation：持久化 `ends_at`、裁决完成/中断唯一终态并写唯一 outbox；
 - 处理刷新、断线和重启恢复；
 - 关闭 App 时停止新 Tool 投递，并收口未完成操作；
 - 通过 outbox 可靠回传结果；
@@ -60,11 +66,10 @@ Capability 规则。

 它只负责：

- 显示倒计时；
- 响应暂停、继续和取消；
- 根据 Runtime 提供的状态刷新界面；
- 到时间显示自己的完成提醒；
- 通过 SDK 报告状态和结果。
+- 显示活动名称、倒计时和低干扰专注界面；
+- 根据 Runtime 投影的 operation 与 instance state 刷新界面；
+- 接收 Runtime 路由的 Agent Tool 和状态投影；不以界面按钮直接改变专注业务状态；
+- 通过 SDK 保存自身展示所需的业务状态快照；

 它不能：

@@ -75,46 +80,159 @@ Capability 规则。

 ## 3. Pomodoro 最小模型

-第一版只保留以下状态：
+Pomodoro App instance 和一次专注 operation 不是同一个对象：`app_session_id` 表示 Interact 中围绕该
+instance 的子会话，`instance_id` 表示 MiniApp 实例，`operation_id` 才表示一次实际专注。第一版由
+`pomodoro.start` 同时创建它们；它们不在数据模型上互为同义词。
+
+一次专注 operation 只保留以下状态：

 ```text
-idle       尚未开始
-running    正在计时
-paused     已暂停
-completed  已完成
-cancelled  已取消
+focusing     正在专注
+completed    到达约定时长
+interrupted  用户明确离开、切换工作区或关闭 App 后中断
 ```

-最小数据：
+最小 operation 数据：

 ```text
-timer_id
+operation_id
+source_tool_call_id
+activity?
 duration_seconds
 started_at
 ends_at
-remaining_seconds
 state
+ended_at?
+interruption_reason?
 ```

-建议的最小 Tool：
+运行中只以 `ends_at` 作为时间事实；`remaining_seconds` 是 Pomodoro UI 从 `ends_at - now` 派生的显示值，
+不单独持久化。Pomodoro 的 instance snapshot 可以保存活动名称、`operation_id`、`started_at`、`ends_at`
+与展示状态；它不替代 Runtime operation 的 Tool 终态和 outbox。
+
+Pomodoro 在 Manifest 中声明以下两个由 Agent 调用的 Tool。MiniApp 是 Agent 的业务工具：用户在 IM 中以
+自然语言表达开始、停止等意图（未来同样适用于 Voice），由 Agent 决定并调用 Tool；Pomodoro 的界面不提供
+暂停、继续或“结束专注”的业务按钮。

 ```text
-pomodoro.start
-pomodoro.pause
-pomodoro.resume
-pomodoro.cancel
-pomodoro.status
+pomodoro.start({ duration_seconds, activity? })
+pomodoro.interrupt({})
 ```

-Runtime 不解释“番茄钟”业务，只管理一个有生命周期的计时操作。计时完成后，Pomodoro 可以显示普通
-完成提示；如果 Agent 要询问用户是否开始下一轮，必须回到 Interact 的标准交互。
+`pomodoro.start` 是长期 Tool operation：Agent 调用成功后立即进入 `focusing`，只在 `completed` 或
+`interrupted` 时回传一次业务结果。`pomodoro.interrupt({})` 是短 Tool：Tool Router 只从该 Agent 调用所在的
+`conversation_id` 中绑定当前唯一的 `focusing` Pomodoro operation；调用者不能传入或伪造 `instance_id`、
+`app_scope`、`operation_id` 或其他会话目标。Runtime 将调用路由给该 Pomodoro instance，并在同一原子裁决中
+将 `pomodoro.start` 收口为 `interrupted`。若 Surface 已卸载，Runtime 仍必须完成裁决；Surface 存在时只接收
+最终状态投影。`pomodoro.interrupt` 的稳定回执为 `interrupted`、`no_active_focusing_operation` 或
+`operation_already_final`；重复或迟到调用不得重写终态或新增 outbox。用户不需要在 App 内再次点击“开始”，
+也没有暂停、继续或恢复入口。
+
+用户切回 Interact、切到其他 MiniApp 或关闭 Pomodoro 时，属于 Runtime 生命周期事件：Runtime 以同一原子
+中断规则收口，但不伪造 Agent Tool。自动暗屏、锁屏和 Surface 重载不等于退出。到点、Agent 调用
+`pomodoro.interrupt` 与生命周期关闭竞争同一个终态，先成功者生效；后续调用只得到上述稳定回执。到点取得
+`completed` 后，Runtime 先原子写入唯一结果/outbox，再立即关闭 Pomodoro、结束子会话并恢复 Interact；
+Pomodoro 不显示独立完成提示，完成结果由 Interact / Agent 呈现。如果 Agent 要询问用户是否开始下一轮，
+必须回到 Interact 的标准交互。
+
+两个 Tool 的 v1 Descriptor 如下。Runtime 只发布通过 Manifest、Inventory revision、会话作用域和输入 schema
+校验的 Tool；校验失败、过期 Inventory 或不存在的目标均稳定拒绝，且不启动或唤醒 Pomodoro。
+
+| Tool | 调用模型与启动策略 | 输入 | 输出 / 稳定拒绝 | 幂等、超时与路由顺序 |
+|---|---|---|---|---|
+| `pomodoro.start` v1 | 长期 `operation`；Runtime 创建 instance、App 子会话和 deadline operation 后将 Pomodoro 前台化。 | `{ duration_seconds: 正整数, activity?: 字符串 }`；拒绝额外字段。 | 最终成功结果：`{ state: "completed" \| "interrupted", operation_id, started_at, ends_at, ended_at, interruption_reason? }`；若同一会话已有其他 `focusing` 专注，稳定拒绝 `active_focusing_operation`。 | `source_tool_call_id` 是幂等键：同一调用重试返回既有 operation/既有最终结果；不同调用由同一个 conversation 的活动专注记录作原子 compare-and-set。没有 Host/UI 临时超时，运行期限以持久化 `ends_at` 为准，重启后继续恢复或结算。 |
+| `pomodoro.interrupt` v1 | 短 Tool；不启动、唤醒或等待 Pomodoro Surface。 | 空对象 `{}`；不接受 `instance_id`、`operation_id`、`app_scope` 或其他目标字段。 | `{ status: "interrupted" \| "no_active_focusing_operation" \| "operation_already_final", operation_id? }`。 | `source_tool_call_id` 是幂等键。Runtime 从调用的 `conversation_id` 绑定当前唯一 `focusing` operation，原子写其 `interrupted` 终态与长期 start 的唯一结果/outbox，再返回短 Tool 回执；Surface 存在时才接收终态投影，不能以回执决定或补写终态。 |
+
+上表中的输入/输出 schema 冻结为以下 JSON Schema；Runtime 在将 Descriptor 发布到 Agent Inventory 前验证它们。
+
+```json
+{
+  "pomodoro.start": {
+    "input_schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["duration_seconds"],
+      "properties": {
+        "duration_seconds": {"type": "integer", "minimum": 1},
+        "activity": {"type": "string", "maxLength": 256}
+      }
+    },
+    "result_schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "operation_id", "started_at", "ends_at", "ended_at"],
+      "properties": {
+        "state": {"enum": ["completed", "interrupted"]},
+        "operation_id": {"type": "string"},
+        "started_at": {"type": "string"},
+        "ends_at": {"type": "string"},
+        "ended_at": {"type": "string"},
+        "interruption_reason": {"type": "string"}
+      }
+    }
+  },
+  "pomodoro.interrupt": {
+    "input_schema": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "result_schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "enum": ["interrupted", "no_active_focusing_operation", "operation_already_final"]
+        },
+        "operation_id": {"type": "string"}
+      }
+    }
+  }
+}
+```
+
+同一 `conversation_id` 第一版只允许一个 `focusing` Pomodoro operation。不同 `source_tool_call_id` 的第二次
+`pomodoro.start` 必须稳定拒绝为 `active_focusing_operation`，且不得创建 instance、子会话、deadline operation、
+焦点变更或 outbox；Agent 必须先调用 `pomodoro.interrupt({})`，或等待旧 operation 已成为终态后再开始。
+
+Pomodoro 必须声明 `app.instance-state.v1`，其最小 Manifest 契约如下。该快照只服务界面恢复和关闭后的历史
+展示，不替代 operation 的终态、deadline 或 outbox 事实。
+
+```json
+{
+  "features": ["app.instance-state.v1"],
+  "instance_state": {
+    "state_schema_version": 1,
+    "state_schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operation_id", "started_at", "ends_at", "display_state"],
+      "properties": {
+        "operation_id": {"type": "string"},
+        "activity": {"type": "string"},
+        "started_at": {"type": "string"},
+        "ends_at": {"type": "string"},
+        "ended_at": {"type": "string"},
+        "display_state": {"enum": ["focusing", "completed", "interrupted"]},
+        "interruption_reason": {"type": "string"}
+      }
+    },
+    "max_bytes": 4096,
+    "retention": "retain_readonly"
+  }
+}
+```
+
+关闭后的旧 snapshot 只能和只读 App 子会话一起用于历史展示：旧 instance 不可再次写入、不可恢复为
+`focusing`，也不能作为新一轮专注的运行状态；“继续处理”始终创建新的 instance、子会话和 operation。

 ## 4. 工作内容

 ### 4.1 工作区界面

 - 显示当前前台 App；
- 支持 Interact 和 Pomodoro 之间切换；
+- 支持由 `pomodoro.start` 从 Interact 切入 Pomodoro，以及用户显式返回 Interact；返回/切换会中断当前
+  专注 operation，而不是把它作为通用后台计时器继续运行；
 - 显示 App 前台、后台、挂起、关闭和恢复状态；
 - App 启动失败时恢复 Interact；
 - 刷新或重启后恢复工作区快照。
@@ -122,38 +240,51 @@ Runtime 不解释“番茄钟”业务，只管理一个有生命周期的计时
 ### 4.2 生命周期接入

 - 将 `AppLifecycleManager`、`AppFocusManager` 和 `AppOrchestrator` 接入真实 Host；
- 区分后台、挂起和真正关闭；
- 后台运行时保持计时；
+- 区分自动暗屏/锁屏、Surface 重载、工作区切换和真正关闭：前两者不终止专注，后两者中断专注；
+- Runtime 用持久化 `ends_at` 而非 MiniApp UI 定时器管理 deadline；到点、用户中断和关闭竞争同一唯一终态；
+- deadline 取得 `completed` 后，Runtime 依次提交唯一结果/outbox、立即关闭 Pomodoro、结束子会话并恢复
+  Interact；完成提示由 Interact / Agent 呈现，不保留 Pomodoro 完成展示窗口；
 - 关闭后停止向该 instance 投递新 Tool；
- 将未终态普通 Tool 收敛为 `cancelled(app_closed)`；
+- 用户退出专注时先将 `pomodoro.start` 终结为 `interrupted` 并提交结果；随后关闭不会将该已终态 Tool 改写为
+  `cancelled(app_closed)`。其他未终态普通 Tool 仍按 `cancelled(app_closed)` 收口；
 - 已提交结果继续通过 outbox 发送；
 - 关闭后恢复前一个有效前台 App。

 ### 4.3 子会话和 Interact 交互

- 创建 Pomodoro instance 时创建或恢复 App 子会话；
+- 创建 Pomodoro instance 时创建 App 子会话；只有恢复同一个未结束 instance 时才恢复同一个子会话；
 - 在主 IM 中显示可折叠的 Pomodoro 子会话；
 - 子会话只记录人与 Agent 围绕该番茄钟的交互和结果；
- 倒计时、暂停按钮、继续按钮等 App 内部操作不写入 IM；
+- 倒计时和退出按钮等 App 内部操作不写入 IM；
 - App 前台时，Interact 的标准交互可以显示在其上方；
 - 展示位置变化不改变交互归属；
- 已结束子会话只读；“继续处理”创建新的 instance 和新的子会话。
+- 已结束子会话只读；“继续处理”创建新的 instance 和新的子会话；关闭时仍 pending 的 Interact 标准交互
+  不自动取消，保留在主 IM / Interact 中等待回答、dismiss、超时或 Runtime 失败，且不能再追加到已结束子会话。

 ### 4.4 恢复和提醒

- 重启后根据 `ends_at` 重新计算剩余时间；
+- 重启后根据 `ends_at` 重新计算剩余时间；若已到点，Runtime 原子转为 `completed` 并只写一次结果/outbox；
 - 不允许重启后无条件重新开始完整时长；
- 明确后台、暂停、关闭和完成的区别；
- 第一版只实现 App 内完成提示；
+- 不承诺 Runtime / Host 完全未运行时的即时系统提醒；下次恢复时必须按已到期状态结算，不能重置或重复回传；
+- 来电等外部打断预留 `host_interruption` 语义，但第 04 次不实现电话检测、免打扰或静音能力；
+- 明确自动暗屏/锁屏、工作区离开、关闭、完成和中断的区别；
+- 第一版不实现 Pomodoro App 内完成提示；完成结果由 Interact / Agent 呈现；
 - 系统通知作为后续 Capability 验证，不允许 MiniApp 直接调用系统 API。

 ### 4.5 自动化和真实验收

- 覆盖 Pomodoro 状态机和 Tool 调用；
- 覆盖前后台切换、关闭和恢复；
- 覆盖重启后剩余时间恢复；
+- 覆盖 `focusing → completed / interrupted` 状态机、`pomodoro.start` 长 Tool、Agent 调用的
+  `pomodoro.interrupt` 与 Runtime 生命周期中断；
+- 覆盖 Tool Descriptor 的合法/非法输入、Inventory 过期、同 call 重试、同会话重复/并发 start、start 与
+  interrupt/deadline 并发，以及 Surface 缺席时 Runtime 仍可收口；
+- 覆盖自动暗屏/锁屏不终止、工作区切换/关闭中断、重复/迟到退出和到点与中断并发时只产生一个终态；
+- 覆盖重启前未到点恢复、重启后已到点结算和一次 outbox；
+- 覆盖 `completed` 后立即关闭 Pomodoro、子会话只读、Interact 呈现完成结果，以及完成与关闭并发时终态不可改写；
+- 覆盖 `app.instance-state.v1` schema、4 KiB 配额与 `retain_readonly`：关闭后的快照只读，不能复活为
+  `focusing` 或写入新状态；
 - 覆盖 App 子会话创建、折叠、只读和继续处理；
- 覆盖 Interact 标准交互在 Pomodoro 前台时仍归 Interact；
+- 覆盖 Interact 标准交互在 Pomodoro 前台时仍归 Interact，以及 Pomodoro 关闭后 pending 交互仍可在主 IM
+  回答但不改写只读子会话；
 - 通过 Web Reference Host 完成完整浏览器验收；
 - 在 Tauri Desktop Host 完成至少一条代表性流程；
 - 检查生命周期、Tool、交互、恢复和拒绝路径日志。
@@ -165,23 +296,37 @@ Runtime 不解释“番茄钟”业务，只管理一个有生命周期的计时
 - 多 Agent 连接和 Agent 切换；
 - Audio Mode 和 Video Mode 的真实媒体能力；
 - Pomodoro 统计报表、多个计时器、日历和复杂提醒计划；
+- 通用倒计时（如烹饪、停车、家务）以及用户预设后手动开始的 timer 模式；
+- 电话检测、系统专注模式、免打扰、静音和系统通知；
 - Task Dashboard 的任务、项目、优先级、标签和历史管理；
- Whiteboard 的多人协作、云端同步和复杂绘图工具。
+- Whiteboard 的工作区接入、切换、完整用户流程、多人协作、云端同步和复杂绘图工具；第 04 次只保持第
+  03 次已有的 SDK / 隔离回归。
+- 将 MiniApp SDK 或 Runtime SDK 的实现迁入 Rust；本轮保持现有 TypeScript Runtime / Web Bridge 基线，
+  未来仅在 profiling 证明 Runtime Core 存在性能热点后另行评估。

 ## 6. 验收目标

 ```text
-1. 用户可以从 Interact 启动 Pomodoro。
-2. Runtime 创建真实 App instance、焦点记录和 App 子会话。
-3. Pomodoro 进入前台后，Interact 可以退到后台。
-4. Pomodoro 在后台仍然正确计时。
-5. 用户可以暂停、继续和取消计时。
-6. 到时间后 Pomodoro 显示完成提示，并通过 Runtime 回传结果。
-7. 用户关闭 Pomodoro 后，未完成操作正确取消，Interact 恢复前台。
-8. 子会话在主 IM 中折叠保存，已结束内容只读。
-9. 用户选择继续处理时，Runtime 创建新的 instance 和新的 App 子会话。
-10. 刷新或重启后，剩余时间、App 状态、焦点和子会话按规则恢复。
-11. Agent 的标准交互始终由 Interact 负责，Pomodoro 不伪造交互组件。
+1. 用户可以在 **IM** 中请求 Agent 立即开始或停止一段固定时长的写作业、看书或冥想专注；未来 Voice 必须
+   复用同一意图和 Tool 语义，但不属于本轮实现或验收。
+2. `pomodoro.start` 创建真实 App instance、焦点记录、App 子会话和 deadline operation，并直接进入 `focusing`。
+3. Pomodoro 进入前台后，Interact 可以退到后台；自动暗屏、锁屏和 Surface 重载不终止专注。
+4. 用户以 IM / Voice 要求 Agent 停止时，Agent 调用 `pomodoro.interrupt({})`；用户返回 Interact、切到其他
+   MiniApp 或关闭 Pomodoro 时，Runtime 直接处理生命周期中断。两类路径的本轮唯一终态均为 `interrupted`，
+   随后 Interact 恢复前台；Pomodoro 不作为通用后台计时器继续运行。
+5. 到 `ends_at` 时，本轮唯一终态为 `completed`；Runtime 提交唯一结果/outbox 后立即关闭 Pomodoro、结束子会话
+   并恢复 Interact，由 Interact / Agent 呈现完成结果；到点和中断并发时只接受第一个原子终态。
+6. Runtime 只回传一次 `pomodoro.start` 的 `completed` 或 `interrupted` 结果；`pomodoro.interrupt` 不可伪造
+   目标、只能绑定当前会话中活动的 `focusing` operation，并对重复/迟到调用给出稳定回执；关闭流程不得将已提交
+   终态改写。
+7. 同一 `conversation_id` 不会同时存在两轮 `focusing` Pomodoro；不同调用的第二次 `pomodoro.start` 稳定拒绝为
+   `active_focusing_operation`，不创建任何新的 App 或 operation 资源。
+8. 刷新或重启后，未到点的本轮按 `ends_at` 恢复；已到点的本轮结算一次而不重置完整时长或重复回传。
+9. 子会话在主 IM 中折叠保存，关闭后只读；新的“继续处理”创建新的 instance / 子会话，pending Interact
+   交互仍可在主 IM 回答但不能向已关闭子会话追加记录。
+10. Agent 的标准交互始终由 Interact 负责，Pomodoro 不伪造交互组件。
+11. Pomodoro 的 `app.instance-state.v1` 快照符合 schema v1 与 4 KiB 配额；关闭后保留为只读历史，不能写入或
+    复活旧 instance。
 12. MiniApp 无法访问 Transport、Store、Agent、Host DOM、Tauri 或任意系统 API。
 13. `npm test -- --run`、`npm run build` 和 Web/Tauri 代表性验收全部通过。
 14. P0～P3 设计和验收问题清零。