MooTool Next Flutter 多窗口架构实践:基于 ADR 002 的会话所有权移交、分离与持久化设计
MooTool Next Flutter 多窗口架构实践:基于 ADR 002 的会话所有权移交、分离与持久化设计
导读
本文以 MooTool 开源仓库中 next-flutter 的架构决策记录 ADR 002:多窗口 为骨架,结合 Flutter 桌面端源码、持久化实现与单元测试,系统讲解多窗口场景下"会话写所有权"如何安全移交、工具如何"分离/收回"、以及分离状态如何通过 workspace.json 跨重启保持。读完本文,你将掌握一个基于"单写者 + revision 快照 + ACK 确认"的会话交接协议设计,并了解如何在 Flutter 桌面应用中预留第二引擎窗口、同时保证任务服务不随窗口迁移的架构取舍。
注意:本 ADR 状态为"部分采纳",
desktop_multi_window的多引擎方案尚未实机验证,文章会严格区分"已实现"与"规划/未验证"两部分。
一、决策背景:为什么要引入多窗口,以及"部分采纳"意味着什么
MooTool 是一个面向开发者的多功能工具箱,Flutter 版(next-flutter)基于单窗口承载全部工具(JSON、随手记、HTTP、Host、运行环境、翻译等)。当用户希望把某个工具"拉出"主窗口独立显示(例如一边编辑 JSON、一边发 HTTP 请求)时,就需要多窗口能力。
ADR 002 的核心结论包含两层:
- 会话所有权(ownership)必须是单写者模型:同一时间,一个会话(如某个 JSON 文档)只允许一个窗口拥有写入权,避免多窗口并发写导致状态撕裂。
- "部分采纳":决策中"同一 engine 内完成分离状态"的部分已落地;而"每个窗口独立 Flutter engine"(
desktop_multi_window)的完整方案,因当前开发机只有 Command Line Tools、无法实机验证真实第二 engine 的插件注册,仍停留在规划阶段。
从源码结构看,<a href="https://link.gitcode.com/i/f40032db39d064979d5d51d54743e763" target="_blank">session_transfer.dart</a> 即为已采纳部分的实现载体,而 app_controller.dart 的 detachTool / dockTool 方法只完成了"拒绝分离 + 预留收回流程"。
二、核心决策:会话写所有者与严格的分离/收回协议
ADR 决定原文:
SessionCoordinator是会话写所有者。分离/收回必须:结束 composition → 锁定 session → 提交 revision 快照 → 目标 ACK 同一 revision → 切换唯一 owner。失败则 abort 并恢复源窗口。
这等价于一个带锁的"两阶段提交"(begin → ack → 切换 owner),每一步都有失败回退路径。下面逐层拆解。
2.1 SessionCoordinator:单写者协议的状态机
实现位于 next-flutter/lib/core/window/session_transfer.dart,类注释明确写着:"Single-writer session transfer used before a second Flutter engine is shown",即它是在第二 engine 出现之前、主窗口内完成的单写者会话移交实现。
核心数据结构:
| 成员 | 类型 | 作用 |
|---|---|---|
windowId |
String |
当前协调器所在窗口标识,默认 'main' |
_owners |
Map<String, String> |
每个 sessionId 当前唯一的写所有者窗口 |
_locks |
Map<String, TransferRequest> |
正在进行的移交锁,同一会话同一时刻至多一个移交 |
对外 API 与协议阶段一一对应:
ownerOf(sessionId):查询会话当前写所有者,未声明时回落到windowId;claim(sessionId):启动时声明主窗口拥有某会话;beginTransfer(request):上锁阶段——若会话已在移交中返回失败;若发起方不是当前写所有者返回失败;否则登记锁;ack(sessionId, targetWindowId, revision):确认阶段——校验锁存在、目标窗口匹配、revision 匹配后,才把 owner 切换到目标窗口并释放锁;abort(sessionId):回退阶段——丢弃锁,owner 保持不变(源窗口仍是所有者)。
2.2 失败路径:abort 与"恢复源窗口"
ADR 明确要求"失败则 abort 并恢复源窗口"。从代码看,两种失败都会被拦截:
- 会话已在移交中:
beginTransfer返回'session is already transferring'; - 发起方不是写所有者:返回
'source is not the write owner'; - ACK 时 revision 或目标不匹配:
ack返回'revision or target mismatch',此时_locks保留、owner 不变,调用方应执行abort。
2.3 测试验证:revision 不匹配必须拒绝
core_samples_test.dart 用一条测试完整走了一遍协议:
coordinator.claim('json')后主窗口持有json会话;beginTransfer(source=main,target=other,revision=3)成功;- 用错误 revision(2)调用
ack被拒绝(ok=false),证明"目标 ACK 同一 revision"是硬约束; abort成功,且ownerOf('json')仍为'main'——即源窗口恢复所有者。
这条测试同时印证了 ADR 中"失败则 abort 并恢复源窗口"的可验证性。
2.4 为何要"提交 revision 快照"
TransferRequest 携带 revision、text、selectionStart、selectionEnd、undoDepth 五项负载。revision 是文档的版本号:只有目标窗口确认的 revision 与锁定时的快照一致,才允许切换 owner,从机制上杜绝"交接途中源窗口又改了一版、目标窗口拿旧快照成为新主人"的竞态。selection 与 undo 深度随快照迁移,保证切窗后光标位置与撤销栈不回退。
三、P2 落地范围:同一 engine 内的分离状态与 workspace.json 持久化
ADR 对 P2 的定义:
P2 在同一 Flutter engine 内完成分离状态(主区显示占位,会话对象不重建)。分离的 toolId 写入
workspace.json,重启后仍显示占位并可收回。
3.1 分离状态的载体:detachedToolIds
在 app_controller.dart 中定义了:
final Set<String> detachedToolIds = {};
这是一个工具 id 集合,表示"已分离到独立窗口"的工具。由于当前第二 engine 未实机验证,实际运行时该集合在 load() 里被清空,detachTool 也只弹出提示"独立窗口尚未实现"(见 detachTool)。
3.2 主区占位与收回入口(workbench 交互)
在 workbench.dart 中,导航项根据 detachedToolIds 显示一个"新窗口打开"角标(Icons.open_in_new);长按导航项触发分离/收回;当活动工具处于分离态时,主区渲染为占位页(workbench.dart),显示 tool.detached("已在独立窗口打开")文案与"收回"按钮,点击调用 dockTool。
本地化文案集中在 next-flutter/lib/l10n/strings.dart:中文 window.detachUnavailable 为"独立窗口尚未实现,工具仍留在主窗口",tool.dock 为"收回",tool.detach 为"分离窗口",并同步提供英文与日文翻译。
3.3 收回协议:dockTool 已实现的两阶段移交
尽管分离功能被禁用,收回路径 dockTool 已经完整实现了 ADR 协议(app_controller.dart):
void dockTool(String id) {
final session = id == 'json'
? json.document
: id == 'quickNote'
? note.document
: draftFor(id);
final begin = coordinator.beginTransfer(TransferRequest(
sessionId: id,
sourceWindowId: 'detached-$id',
targetWindowId: 'main',
revision: session.revision,
text: session.text,
selectionStart: session.selectionStart,
selectionEnd: session.selectionEnd,
undoDepth: 0,
));
if (begin.ok) coordinator.ack(id, 'main', session.revision);
detachedToolIds.remove(id);
scheduleSave();
notifyListeners();
}
这里清晰呈现了 ADR 的语义:分离窗口以 'detached-$id' 作为窗口标识参与移交,source 是分离窗口、target 是 'main',begin 成功后再 ack 到同一 revision,最后把工具 id 从 detachedToolIds 移除并触发持久化。可以看到,分离/收回的"会话对象"来自 json.document / note.document / draftFor(id)——会话对象不重建,这正是 ADR 所说"会话对象不重建"的实现基础。
3.4 持久化:detachedToolIds 写入 workspace.json
toJson() 将 detachedToolIds 序列化进 workspace 快照(app_controller.dart);scheduleSave() 使用 400ms 防抖定时器触发 persist(),保证分离/收回后状态落盘。workspace.json 的物理路径由 app_paths.dart 定义为数据根目录下的 workspaceFile,其默认数据根目录在 macOS 为 ~/Library/Application Support/<applicationId>、Windows 为 %APPDATA%\MooToolNextFlutter、Linux 为 $XDG_DATA_HOME(缺省 ~/.local/share/mootool-next-flutter)。
启动时 _restoreWorkspace 会恢复 activeToolId、各会话数据等(app_controller.dart),随后 detachedToolIds.clear() 并 coordinator.claim('json'/'quickNote') 重新建立主窗口的所有者声明——重启后主窗口重新拥有全部会话,这与 ADR"重启后仍显示占位并可收回"的目标一致,只是当前未验证阶段重启后集合从空开始。
此外,workspace.json 是 snapshot_backup.dart 中 backupNames 之一,会被纳入"快照备份/恢复"清单,说明多窗口分离状态与备份体系天然集成。
四、任务留在应用级服务:窗口只更换订阅者
ADR 的收尾决策:
任务与 HTTP 运行仍应留在应用级服务;窗口只更换订阅者。HTTP 等任务留在 AppController,分离不重新执行。
这条决策的意义在于:窗口是"视图订阅者"而非"任务执行者"。HTTP 发送、运行环境执行、翻译请求等有副作用或耗时的任务,生命周期绑定在 AppController(即应用进程),而不是某个窗口。窗口分离/收回只切换"谁在显示/编辑会话",绝不会因为窗口重建而重放或中断任务。
实现佐证:AppController 中集中维护 HttpSession、RuntimeSession、TranslationSession、HostSession 等应用级会话(app_controller.dart),HTTP 请求由控制器发起并等待结果,而 p6_window_test.dart 验证了"分离被拒绝时 HTTP 任务仍在继续":first.http.sending = true 后调用 detachTool('http'),断言 http.sending 仍为 true、detachedToolIds 为空、ownerOf('json') 未被改成 detached-json。
这也解释了为什么 ADR 说"分离不重新执行":任务状态不在窗口里,即便未来真正的第二 engine 窗口打开,detachedToolIds 里也只会记录"该工具显示在别处",任务照常由应用级服务跑完。
五、未验证项:真实第二 engine 的边界与风险清单
ADR 明确列出的三个未验证问题,是从"单引擎占位"走向"真正多窗口"前必须补课的清单:
- 真实第二 Flutter engine 的插件注册:
desktop_multi_window让每个窗口持有独立 engine,这意味着每个窗口都要独立注册 MethodChannel 插件(如桌面宿主通道com.rememberber.mootool.next.flutter/desktop,见 desktop_host.dart)。当前开发机只有 Command Line Tools,无法完成实机验证,所以 ADR 状态为"部分采纳"。 - 与
window_manager同时使用时的关闭/焦点:Flutter 桌面端通常由window_manager承担窗口管理职责(Linux 侧入口在 my_application.cc),多引擎窗口与window_manager并存时,关闭事件、焦点切换、置顶等行为尚无实证。 - 100 次分离/收回的内存曲线:频繁分离/收回是否造成 engine、快照或会话对象的内存泄漏,缺少压力测试数据。
顺带说明,单窗口的"关闭行为"策略是已有的对照基线:WindowPolicy 会根据托盘可用性把 hide 行为降级为 ask(window_policy.dart),避免窗口"藏得起来却找不回";startMaximized 仅在启动时应用一次(p6_window_test.dart)。这些单窗口策略未来需要与多窗口关闭/焦点规则统筹。
六、总结:已采纳与待验证的边界
用一张表收束 ADR 002 的落地情况:
| ADR 决策点 | 状态 | 源码依据 |
|---|---|---|
SessionCoordinator 是会话写所有者 |
已实现 | session_transfer.dart |
| 分离/收回走 begin→ack→owner 切换、失败 abort | 已实现 | session_transfer.dart、dockTool |
| revision 快照强校验 | 已实现并有测试 | core_samples_test.dart |
| 同一 engine 内分离状态、主区显示占位 | 已实现(分离入口禁用) | workbench.dart |
分离 toolId 写入 workspace.json |
已实现 | app_controller.dart |
| 任务留在应用级服务、分离不重新执行 | 已实现并有测试 | p6_window_test.dart |
真实第二 engine 插件注册 / window_manager 协同 / 内存曲线 |
未验证 | ADR "未验证" 清单 |
对想要在 Flutter 桌面应用实现多窗口的开发者,这套"单写者会话 + revision 快照 + ACK 确认 + 应用级任务下沉"的设计可以直接借鉴;对 MooTool 项目本身,session_transfer.dart 与 dockTool 的协议骨架已经就位,后续只需在 desktop_multi_window 实机验证通过后,把 detachTool 从"拒绝"切换为真实创建第二窗口即可。更完整的窗口与托盘、备份等策略可继续阅读 next-flutter 下的 lib/core/desktop 与 lib/core/storage 相关实现。