MooTool Next Compose 演进切片 DIFF-573:F02/F10 run* 导入与恢复接线、diff CSS 组件与 Vault MCP 双库跨库 search→read
MooTool Next Compose 演进切片 DIFF-573:F02/F10 run* 导入与恢复接线、diff CSS 组件与 Vault MCP 双库跨库 search→read
导读
本文解析 MooTool Next(Compose Desktop 版)逐日开发切片文档 DIFF-573 的技术全貌:它完成了文本对比工具(F02)左右导入与 Host 工具(F10)备份恢复的 run* 接线重构、两枚 diff 样式组件的逐选择器移植,以及 Vault MCP 双库会话中「JSON 库搜索 → 笔记库读取」跨库链路与 Compose 帧 168 证据。读完你将掌握 MooTool Next 中 Presentation 层如何统一文件 IO 与异常呈现、Host 引擎的指纹冲突保护、MCP 工具参数严格边界,以及该项目以测试与截图驱动 parity(对 Electron 参考实现的对齐)的工程方法。
背景:自 DIFF-571/572 延续的逐日 parity 推进
MooTool Next Compose 以 DIFF 切片方式逐日推进功能实现,DIFF-573 不是孤立的:它明确承接 DIFF-572 已完成的三条链——F03 ReformatWiringPresentation.runReadSourceFile / runWriteResult / inferTypeFromFileName、mooFileDropRow 样式组件、Vault MCP 双库 notes search→read body offset,以及 Compose 帧 167;再往前,DIFF-571 完成了 F04 JsonWiringPresentation.run*、mooJsonInspectorSectionResult / mooJsonInspectorPathActions 与双库 json search→read、帧 166。DIFF-573 明确声明不重复上述链,只在其后追加新一批接线与证据。
同批切片的 parity-gap(与 Electron 参考实现的差距清单)仍记录着三项目标:六套 CSS 逐选择器皮肤、产品主窗 Tab/IME/TCC 的 PNG 截屏、P7 三平台安装产物——这些在 next-compose/docs/diff/573-diff-host-mcp-css-slice.md 的「未做」节均有留底,是理解本切片边界的前提。
F02 文本对比:run* 导入接线与状态栏错误呈现
runReadImportFile:把裸 readText() 收敛进 Presentation
DIFF-573 为 F02 文本对比工具引入的 TextDiffPresentation.runReadImportFile,其实现位于 TextDiffPresentation.kt:
sealed interface ImportOutcome {
data class Success(val content: String) : ImportOutcome
data class Failure(val error: Throwable) : ImportOutcome
}
fun runReadImportFile(file: java.io.File): ImportOutcome =
runCatching { file.readText() }.fold(
onSuccess = { ImportOutcome.Success(it) },
onFailure = { ImportOutcome.Failure(it) },
)
关键点在于语义封装:左侧/右侧编辑器导入文件不再由 UI 直接 readText() 裸读并自吞异常,而是统一走 Presentation 返回密封类型 ImportOutcome,成功时携带正文、失败时携带 Throwable,为后续 UI 层按结果分支处理提供稳定契约。同对象的 shouldToastImportFailure 恒为 true,表示导入失败一律需要 toast 提示。
调用点:TextDiffScreen.importSide 的成败分叉
UI 侧接线位于 TextDiffScreen.kt。importSide(container, session, side, onDone) 先通过 chooseFileWithExportDirectory 弹窗取文件,再调用 TextDiffPresentation.runReadImportFile(file):
- 成功分支:把
outcome.content写入对应侧(session.left/session.right),重置session.navIndex = -1,持久化导出目录,并 toast「已导入」; - 失败分支:将错误消息以
reformat.error.read语言键(携带outcome.error.message或文件路径)写入session.notice状态栏,同时通过notifyDiffImportFailure触发toastError——这正是文档所述「失败写reformat.error.read状态栏(不再裸readText())」的确切含义。
配套守卫与自动对比 debounce
同一 Presentation 对象还承载了 F02 的其他可测逻辑(从源码结构看,均用于对齐 Electron 输入后短延迟重算的交互语义):AUTO_COMPARE_DEBOUNCE_MS = 160L,在 TextDiffScreen.kt 中通过 LaunchedEffect 对输入变化做 160ms 延迟后触发 runCompare;nextNavIndex 以模运算循环差异导航索引;canManualCompare、canNavigateDiffs、copyPatchActionEnabled 分别约束「两侧皆空时禁用手动比较」「无可见差异时禁用上下跳转」「无 unified 补丁时禁用复制」。对应断言集中在 TextDiffPresentationTest.kt,覆盖 debounce 常量、导航索引边界、守卫矩阵、导入成功与文件缺失失败四条路径。
F10 Host:备份恢复经 Presentation 的完整链路
runRestoreBackup:读系统 + 恢复的原子化封装
DIFF-573 为 F10 Host 工具新增的 HostWiringPresentation.runRestoreBackup,实现在 HostWiringPresentation.kt:
sealed interface RestoreOutcome {
data class Success(val result: HostApplyResult) : RestoreOutcome
data class Failure(val error: Throwable) : RestoreOutcome
}
fun runRestoreBackup(config: HostApplyConfig, backupPath: String): RestoreOutcome =
runCatching {
val current = HostEngine.readSystem(config)
HostEngine.restore(config, backupPath, current.fingerprint)
}.fold(
onSuccess = { RestoreOutcome.Success(it) },
onFailure = { RestoreOutcome.Failure(it) },
)
这条链不再由 UI 内联 runCatching:恢复动作被定义为「先 HostEngine.readSystem 取得当前系统 hosts 的 SHA-256 fingerprint,再以该指纹作为期望指纹调用 HostEngine.restore」的两步原子序列,失败统一落入 RestoreOutcome.Failure。
HostEngine 底层:指纹冲突保护与备份校验
底层的 HostEngine.kt 提供了机制细节:
readSystem(L116-L128)读取系统 hosts(文件不存在按空内容处理)、探测可写性,并计算fingerprint(UTF-8 字节的 SHA-256 十六进制);restore(L154-L160)先校验备份路径存在且为常规文件(否则抛HostErrorCode.MISSING),然后以validateEntries = false调用apply——恢复场景信任备份自身内容,不做条目级校验;apply(L130-L152)内部再比对expectedFingerprint:若系统 hosts 在「上次读取」之后被第三方改动(fingerprint(before) != expectedFingerprint),直接抛HostErrorCode.CONFLICT,拒绝覆盖,这就是并发修改保护;HostApplyConfig(L41-L66)以工厂方法production按平台选择默认 hosts 路径(Windows 下%SystemRoot%\System32\drivers\etc\hosts,macOS/Linux 下/etc/hosts),并默认开启allowElevation与flushDns。
UI 接线:busy 守卫、IO 切换与成功态回填
HostScreen.kt 中的「恢复备份」工具栏按钮展示了完整的接线方式:
- 按钮
enabled = HostWiringPresentation.canRestoreBackup(session.lastBackup, session.applying)——仅当存在上次备份且未处于 applying 状态才可点击; - 点击后置
session.applying = true并持久化,切到Dispatchers.IO执行runRestoreBackup; - 回到主线程后按结果分叉:
Success回填systemPath / systemContent / systemWritable / systemFingerprint / applyDiff,并置状态栏host.restored;Failure走notifyHostFailure(含messageFor对HostException.code的中文化)。
这种「Presentation 提供可单测决策 + 引擎提供原子 IO + Screen 只做编排」的三层结构,正是本切片 run* 系列重构的统一模式。守卫矩阵与 IO 结果的断言见 HostWiringPresentationTest.kt。
diff CSS 组件批次:逐选择器对齐 Electron 皮肤
本切片新增两枚样式组件(文档注明「CSS 组件批次,非 572」),定义在 Controls.kt:
| 组件 | Electron 源选择器 | 实现 | 用途 |
|---|---|---|---|
mooDiffToolbarOptions(L1409) |
.diff-toolbar__options |
heightIn(min = 34.dp) |
高亮/忽略空白选项行,34dp 最小行高对齐 Electron 工具栏 |
mooDiffNavCluster(L1405) |
差异导航簇 | heightIn(min = 34.dp) |
并排/统一视图分行导航区 |
mooDiffEditorPane(L1800) |
.diff-editor-grid > div / .diff-editor-pane |
padding(10.dp) |
并排/统一编辑区单元格内边距,供 DiffEditorPane 使用 |
它们与同文件既有的 mooDiffEditorGrid(fillMaxWidth().heightIn(min = 280.dp))、mooDiffEditorSeam(1dp 中缝)共同构成 diff 编辑区布局族。消费点在 TextDiffScreen.kt:选项行(L260)、导航簇(L284)、编辑面板(L416)。这种「以 Electron 类名逐选择器建模为 Compose Modifier 扩展」的方式,是 MooTool Next parity 工作维护六套 CSS 皮肤一致性的基本单元。
Vault MCP stdio:双库 + 跨库 search→read 边界验证
场景定义:JSON 库搜索 → 笔记库读取
DIFF-573 的 MCP 增量是一个新的跨库组合测试 subprocessDualVaultJsonSearchThenNotesReadHonorsBodyOffset,位于 AiIntegrationVaultMcpConnectionTest.kt。它验证的链路是「同一 MCP stdio 会话内,先对 JSON 文档库执行带 offset 的搜索,再对笔记库执行带 body offset/length 的读取」——文档明确区分这与 571/572 的同库 search→read 链、以及 566 的双库 read-only 链不同。
测试夹具的关键要素:
- 三个临时目录分别充当笔记库(
alpha.md/beta.md,正文含skip573前缀与573tail尾部)、JSON 库(alpha.json/beta.json,含573-alpha/573-beta标记)与产品目录; - 通过
McpLaunchResolver.accessFile写入双库 access 文件,内容形如{"version":1,"notes":"<notesRoot>","json":"<jsonRoot>"}; - 以
StdioClientTransport拉起 MCP 服务器,先调用mootool_json_documents_search(query=573, limit=1, offset=1,断言结果命中beta.json/573-beta),再调用mootool_notes_read(path=beta.md, offset=7, length=7,断言读到的 body 含573tail且不含skip573)。
工具注册与参数严格边界
工具分发在 VaultMcpTools.kt:toolNames 注册四个 mootool_* 工具(notes/json 各自的 _search 与 _read),call 按名称路由到 VaultMcpReadService 的 search/read。参数解析采用对齐 Electron vaultTools.ts 的 Zod strict 语义——越界即抛错,不静默钳制:
- searchArgs:
query可选、最大 200 字符、默认"";limit默认 20、范围1..50;offset默认 0、范围0..2000; - readArgs:
path必填、最大 1000 字符、不允许空白;offset默认 0、范围0..2_000_000;length默认 20_000、范围1..50_000。
数值参数只接受整数形态(Int/Long/整值 Double/Float/可解析字符串),保证 MCP JSON 参数类型不暧昧。配套的引导文档 SKILL.md 则规定了 Agent 使用约定:先 _search 再按返回相对路径 _read、跟随 nextOffset 翻页、truncated 时收窄查询而非声称穷举、笔记正文不含 YAML 元信息头。启动侧由 McpLaunchResolver.clientLaunch 以 ["--mcp", "--access-file", ...] 参数拉起,McpBootstrap 据此把 Vault 工具路由到 VaultMcpTools.call。
证据与验证体系:Compose 帧 168 与脚本 hints
本切片同时落地两类可复核证据:
1. Compose 截图帧(非产品主窗):TextDiffHighlightModeCaptureTest.kt 在 920×120 的 runDesktopComposeUiTest 中渲染「忽略空白 / 同时高亮 / 逐字符高亮」三枚按钮(复用 mooDiffToolbarOptions 修饰符与 MooTheme),通过 FocusRequester 把焦点落在「同时高亮」按钮后 captureToImage,写出 168-compose-text-diff-highlight-options-tab-focus.png 到 docs/evidence/2026-09-15-inspector-screencapture/windows,并断言焦点环色 0x316DC0 的像素数 ≥ 8——用焦点环像素断言守住「Tab 可聚焦 + 焦点环可见」两个 UI 契约。
2. 证据准备脚本:verify-product-evidence-prep.sh 对全部证据准备脚本做 bash -n 语法检查,随后 source lib/product-evidence-common.sh 并批量打印各功能模块的截屏提示,其中 mootool_evidence_print_text_diff_highlight_options_tab_focus_hint(L80)即本切片新增的 F02 帧 168 提示。
完整验证矩阵(照录切片文档并对应到源码):
TextDiffPresentationTest/HostWiringPresentationTest(Presentation 层单测,见上文)AiIntegrationVaultMcpConnectionTest(stdio 双库跨库链路)TextDiffHighlightModeCaptureTest(帧 168 视觉断言)./scripts/verify-product-evidence-prep.sh(语法 + hint)./gradlew :composeApp:desktopTest --offline(JDK 21 下离线跑全套 desktopTest)
未做与边界
DIFF-573 明确未覆盖、留待后续切片的内容包括:Electron 六套 CSS 逐选择器全量移植(本切片仅做了 mooDiffToolbarOptions / mooDiffEditorPane 两枚)、产品主窗 F02/F10/IME/TCC 的手工 PNG(帧 168 只是隔离测试帧)、P7 三平台安装与公证,以及整产品完成度目标。这些清单从 DIFF-573 文档 的「未做」节可完整追溯,也印证了该系列切片「当日闭合、差距留痕」的推进纪律。
小结
DIFF-573 是 MooTool Next Compose 对 Electron 参考实现做 parity 迁移的一个典型最小切片:F02 导入与 F10 恢复两条 run* 接线把文件 IO 与系统级写操作收敛进可单测的 Presentation 层并统一错误呈现;两枚 diff 样式组件延续「Electron 类名 → Compose Modifier」的逐选择器移植;Vault MCP 则以带 body offset 的双库跨库 stdio 测试守住 search→read 的严格边界;最后以截图像素断言与脚本 hints 闭环交付帧 168 证据。对于想在 Kotlin Multiplatform 桌面上复刻 Electron 工具链的开发者,这条「切片文档 + Presentation 决策层 + 引擎原子操作 + 视觉断言」的流水线本身就是一份可借鉴的工程范式。