docs(iteration): define runtime workspace milestone
This commit is contained in:
@@ -0,0 +1,193 @@
|
||||
# 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)
|
||||
|
||||
## 1. 迭代目标
|
||||
|
||||
前三次迭代已经完成 Runtime、Interact、MiniApp SDK v1 和参考 MiniApp 的基础契约。本迭代不再扩展
|
||||
复杂的业务应用，而是把这些基础接到真实的 Web/Tauri 工作区界面，证明用户可以启动、切换、后台化、
|
||||
关闭、恢复一个 MiniApp，并在 Interact 中查看对应的子会话。
|
||||
|
||||
本迭代选择一个极简的 **Pomodoro 番茄时钟 MiniApp** 作为 Runtime 验证应用。番茄时钟只负责倒计时和
|
||||
自己的完成提醒，不负责任务、项目或复杂业务管理。
|
||||
|
||||
```text
|
||||
Interact IM
|
||||
→ Agent 请求启动 Pomodoro
|
||||
→ Runtime 创建 App instance 和 App 子会话
|
||||
→ Pomodoro 进入前台，Interact 进入后台
|
||||
→ 计时在后台继续运行
|
||||
→ 用户暂停、继续、取消或回到 Interact
|
||||
→ 到时间显示完成提醒并回传结果
|
||||
→ 用户关闭 App，Runtime 收口并恢复 Interact
|
||||
→ 子会话在 IM 中折叠保存
|
||||
→ 重启后按规则恢复或继续处理
|
||||
```
|
||||
|
||||
## 2. 产品和架构边界
|
||||
|
||||
### 2.1 Interact
|
||||
|
||||
Interact 仍然是系统级 `system` MiniApp，负责人与 Agent 的交互：
|
||||
|
||||
- Agent 请求启动或控制番茄钟；
|
||||
- Agent 向用户询问是否开始下一轮；
|
||||
- Agent 需要用户确认时使用 `notice / choice / confirm / input`；
|
||||
- 交互记录属于 Interact 和对应会话，不属于 Pomodoro 的内部 UI。
|
||||
|
||||
### 2.2 Runtime
|
||||
|
||||
Runtime 负责最终裁决和可靠性：
|
||||
|
||||
- 创建和管理 Pomodoro App instance；
|
||||
- 管理前台、后台、挂起、关闭和恢复；
|
||||
- 校验 Tool、作用域、实例和会话上下文；
|
||||
- 保存计时状态和工作区快照；
|
||||
- 处理刷新、断线和重启恢复；
|
||||
- 关闭 App 时停止新 Tool 投递，并收口未完成操作；
|
||||
- 通过 outbox 可靠回传结果；
|
||||
- 需要系统通知时通过 Capability Gateway 处理。
|
||||
|
||||
### 2.3 Pomodoro MiniApp
|
||||
|
||||
Pomodoro 是普通 `bundled` MiniApp，必须使用与其他非系统级 MiniApp 相同的 SDK、受限 Surface 和
|
||||
Capability 规则。
|
||||
|
||||
它只负责：
|
||||
|
||||
- 显示倒计时；
|
||||
- 响应暂停、继续和取消；
|
||||
- 根据 Runtime 提供的状态刷新界面；
|
||||
- 到时间显示自己的完成提醒；
|
||||
- 通过 SDK 报告状态和结果。
|
||||
|
||||
它不能：
|
||||
|
||||
- 直接访问 AppServer、Transport、Conversation Store 或 Agent；
|
||||
- 直接调用 Tauri、系统通知或其他 Host 能力；
|
||||
- 发起 Interact 标准交互；
|
||||
- 修改 Runtime 的焦点、Registry 或其他 App 数据。
|
||||
|
||||
## 3. Pomodoro 最小模型
|
||||
|
||||
第一版只保留以下状态：
|
||||
|
||||
```text
|
||||
idle 尚未开始
|
||||
running 正在计时
|
||||
paused 已暂停
|
||||
completed 已完成
|
||||
cancelled 已取消
|
||||
```
|
||||
|
||||
最小数据：
|
||||
|
||||
```text
|
||||
timer_id
|
||||
duration_seconds
|
||||
started_at
|
||||
ends_at
|
||||
remaining_seconds
|
||||
state
|
||||
```
|
||||
|
||||
建议的最小 Tool：
|
||||
|
||||
```text
|
||||
pomodoro.start
|
||||
pomodoro.pause
|
||||
pomodoro.resume
|
||||
pomodoro.cancel
|
||||
pomodoro.status
|
||||
```
|
||||
|
||||
Runtime 不解释“番茄钟”业务，只管理一个有生命周期的计时操作。计时完成后，Pomodoro 可以显示普通
|
||||
完成提示；如果 Agent 要询问用户是否开始下一轮，必须回到 Interact 的标准交互。
|
||||
|
||||
## 4. 工作内容
|
||||
|
||||
### 4.1 工作区界面
|
||||
|
||||
- 显示当前前台 App；
|
||||
- 支持 Interact 和 Pomodoro 之间切换；
|
||||
- 显示 App 前台、后台、挂起、关闭和恢复状态；
|
||||
- App 启动失败时恢复 Interact；
|
||||
- 刷新或重启后恢复工作区快照。
|
||||
|
||||
### 4.2 生命周期接入
|
||||
|
||||
- 将 `AppLifecycleManager`、`AppFocusManager` 和 `AppOrchestrator` 接入真实 Host；
|
||||
- 区分后台、挂起和真正关闭；
|
||||
- 后台运行时保持计时；
|
||||
- 关闭后停止向该 instance 投递新 Tool；
|
||||
- 将未终态普通 Tool 收敛为 `cancelled(app_closed)`；
|
||||
- 已提交结果继续通过 outbox 发送；
|
||||
- 关闭后恢复前一个有效前台 App。
|
||||
|
||||
### 4.3 子会话和 Interact 交互
|
||||
|
||||
- 创建 Pomodoro instance 时创建或恢复 App 子会话；
|
||||
- 在主 IM 中显示可折叠的 Pomodoro 子会话；
|
||||
- 子会话只记录人与 Agent 围绕该番茄钟的交互和结果；
|
||||
- 倒计时、暂停按钮、继续按钮等 App 内部操作不写入 IM；
|
||||
- App 前台时，Interact 的标准交互可以显示在其上方；
|
||||
- 展示位置变化不改变交互归属；
|
||||
- 已结束子会话只读；“继续处理”创建新的 instance 和新的子会话。
|
||||
|
||||
### 4.4 恢复和提醒
|
||||
|
||||
- 重启后根据 `ends_at` 重新计算剩余时间；
|
||||
- 不允许重启后无条件重新开始完整时长；
|
||||
- 明确后台、暂停、关闭和完成的区别；
|
||||
- 第一版只实现 App 内完成提示；
|
||||
- 系统通知作为后续 Capability 验证，不允许 MiniApp 直接调用系统 API。
|
||||
|
||||
### 4.5 自动化和真实验收
|
||||
|
||||
- 覆盖 Pomodoro 状态机和 Tool 调用；
|
||||
- 覆盖前后台切换、关闭和恢复；
|
||||
- 覆盖重启后剩余时间恢复；
|
||||
- 覆盖 App 子会话创建、折叠、只读和继续处理；
|
||||
- 覆盖 Interact 标准交互在 Pomodoro 前台时仍归 Interact；
|
||||
- 通过 Web Reference Host 完成完整浏览器验收；
|
||||
- 在 Tauri Desktop Host 完成至少一条代表性流程；
|
||||
- 检查生命周期、Tool、交互、恢复和拒绝路径日志。
|
||||
|
||||
## 5. 不在本迭代范围
|
||||
|
||||
- 应用市场、服务端 App Catalog 和远程下载；
|
||||
- 第三方 MiniApp 发布和在线更新；
|
||||
- 多 Agent 连接和 Agent 切换；
|
||||
- Audio Mode 和 Video Mode 的真实媒体能力；
|
||||
- Pomodoro 统计报表、多个计时器、日历和复杂提醒计划；
|
||||
- Task Dashboard 的任务、项目、优先级、标签和历史管理；
|
||||
- Whiteboard 的多人协作、云端同步和复杂绘图工具。
|
||||
|
||||
## 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 不伪造交互组件。
|
||||
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 和生命周期稳定后，再单独定义任务管理业务模型。
|
||||
Reference in New Issue
Block a user