MooTool Next Compose 演进切片 DIFF-573:F02/F10 run* 导入与恢复接线、diff CSS 组件与 Vault MCP 双库跨库 search→read

原创2026-10-15 19:38:102,307 阅读
文章标签:开发工具桌面应用MCP 服务

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 中的「恢复备份」工具栏按钮展示了完整的接线方式:

  1. 按钮 enabled = HostWiringPresentation.canRestoreBackup(session.lastBackup, session.applying)——仅当存在上次备份且未处于 applying 状态才可点击;
  2. 点击后置 session.applying = true 并持久化,切到 Dispatchers.IO 执行 runRestoreBackup;
  3. 回到主线程后按结果分叉: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 决策层 + 引擎原子操作 + 视觉断言」的流水线本身就是一份可借鉴的工程范式。

登录后查看全文
MooTool