app/迭代/04.runtime_workspace/04.runtime_workspace.md

LineUp App 迭代定义：Runtime 工作区与 Pomodoro MiniApp

迭代编号： 04.runtime_workspace 状态： 设计已冻结，待实施 日期： 2026-08-06 前置基线： 03.sdk_and_coreapp.md 总体计划： plan.md 权威架构： APP架构设计.md

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

1. 迭代目标

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

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

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

2. 产品和架构边界

2.1 Interact

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

• Agent 通过 pomodoro.start 请求立即开始一段专注，也可以通过 pomodoro.interrupt 结束当前专注；
• Agent 向用户询问是否开始下一轮；
• Agent 需要用户确认时使用 notice / choice / confirm / input；
• 交互记录属于 Interact 和对应会话，不属于 Pomodoro 的内部 UI。

2.2 Runtime

Runtime 负责最终裁决和可靠性：

• 创建和管理 Pomodoro App instance；
• 管理前台、后台、挂起、关闭和恢复；
• 校验 Tool、作用域、实例和会话上下文；
• 为每个 App instance 保存 schema 校验、revision 控制的业务状态快照；
• 管理通用 deadline operation：持久化 ends_at、裁决完成/中断唯一终态并写唯一 outbox；
• 处理刷新、断线和重启恢复；
• 关闭 App 时停止新 Tool 投递，并收口未完成操作；
• 通过 outbox 可靠回传结果；
• 需要系统通知时通过 Capability Gateway 处理。

2.3 Pomodoro MiniApp

Pomodoro 是普通 bundled MiniApp，必须使用与其他非系统级 MiniApp 相同的 SDK、受限 Surface 和 Capability 规则。

它只负责：

• 显示活动名称、倒计时和低干扰专注界面；
• 根据 Runtime 投影的 operation 与 instance state 刷新界面；
• 接收 Runtime 路由的 Agent Tool 和状态投影；不以界面按钮直接改变专注业务状态；
• 通过 SDK 保存自身展示所需的业务状态快照；

它不能：

• 直接访问 AppServer、Transport、Conversation Store 或 Agent；
• 直接调用 Tauri、系统通知或其他 Host 能力；
• 发起 Interact 标准交互；
• 修改 Runtime 的焦点、Registry 或其他 App 数据。

3. Pomodoro 最小模型

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

一次专注 operation 只保留以下状态：

focusing     正在专注
completed    到达约定时长
interrupted  用户明确离开、切换工作区或关闭 App 后中断

最小 operation 数据：

operation_id
source_tool_call_id
activity?
duration_seconds
started_at
ends_at
state
ended_at?
interruption_reason?

运行中只以 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 的界面不提供 暂停、继续或“结束专注”的业务按钮。

pomodoro.start({ duration_seconds, activity? })
pomodoro.interrupt({})

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 前验证它们。

{
  "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 事实。

{
  "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；
• 支持由 pomodoro.start 从 Interact 切入 Pomodoro，以及用户显式返回 Interact；返回/切换会中断当前 专注 operation，而不是把它作为通用后台计时器继续运行；
• 显示 App 前台、后台、挂起、关闭和恢复状态；
• App 启动失败时恢复 Interact；
• 刷新或重启后恢复工作区快照。

4.2 生命周期接入

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

4.3 子会话和 Interact 交互

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

4.4 恢复和提醒

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

4.5 自动化和真实验收

• 覆盖 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，以及 Pomodoro 关闭后 pending 交互仍可在主 IM 回答但不改写只读子会话；
• 通过 Web Reference Host 完成完整浏览器验收；
• 在 Tauri Desktop Host 完成至少一条代表性流程；
• 检查生命周期、Tool、交互、恢复和拒绝路径日志。

5. 不在本迭代范围

• 应用市场、服务端 App Catalog 和远程下载；
• 第三方 MiniApp 发布和在线更新；
• 多 Agent 连接和 Agent 切换；
• Audio Mode 和 Video Mode 的真实媒体能力；
• Pomodoro 统计报表、多个计时器、日历和复杂提醒计划；
• 通用倒计时（如烹饪、停车、家务）以及用户预设后手动开始的 timer 模式；
• 电话检测、系统专注模式、免打扰、静音和系统通知；
• Task Dashboard 的任务、项目、优先级、标签和历史管理；
• Whiteboard 的工作区接入、切换、完整用户流程、多人协作、云端同步和复杂绘图工具；第 04 次只保持第 03 次已有的 SDK / 隔离回归。
• 将 MiniApp SDK 或 Runtime SDK 的实现迁入 Rust；本轮保持现有 TypeScript Runtime / Web Bridge 基线， 未来仅在 profiling 证明 Runtime Core 存在性能热点后另行评估。

6. 验收目标

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 设计和验收问题清零。

7. 后续定位

本迭代完成后，Whiteboard 可以作为下一条 Surface、Artifact 和隔离边界验证应用；Task Dashboard 保留 为后续普通 bundled MiniApp，等 Runtime 工作区、SDK 和生命周期稳定后，再单独定义任务管理业务模型。