MooTool next-compose 开发分片实录:DIFF-574 的 Host 方案导入导出、diff 编辑器网格 CSS 与 Vault MCP 双库跨读链路

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

MooTool next-compose 开发分片实录:DIFF-574 的 Host 方案导入导出、diff 编辑器网格 CSS 与 Vault MCP 双库跨读链路

本文基于 MooTool 开源仓库中 next-compose/docs/diff/574-host-diff-mcp-css-slice.md 这一份开发分片(slice)工作记录,还原该切片实际落地的三块核心改动:F10「切换 Host」模块的方案导入/导出接线、F02 文本对比工具的 .diff-editor-grid 并排编辑区 CSS 组件,以及 Vault MCP stdio 服务在「notes search → json read」跨库调用链上对 body offset/length 的语义支持。文中会结合 Compose Multiplatform 桌面端源码与端到端测试,给出可验证的调用关系、参数边界与运行命令,帮助读者理解这套「分片推进 + 证据驱动」的开发流程,以及每条改动背后的源码依据。

一、分片背景:DIFF 系列切片与 574 的边界

next-compose 是 MooTool 的 Compose Multiplatform 桌面端实现,开发采用「逐条 DIFF 切片」方式推进功能对 Electron 版本的 parity(一致性)补齐。每条切片对应一组确定的 UI 组件、领域逻辑或 MCP 能力,并以编号帧的 Compose 截图作为交付证据。

DIFF-574 的定位非常明确:承接 DIFF-573 已完成的链路,不重复 573 的内容。573 已交付的包括:

  • F02 TextDiffPresentation.runReadImportFile(文本对比导入接线);
  • mooDiffToolbarOptions / mooDiffEditorPane(工具条选项与编辑区 10dp 内边距);
  • F10 HostWiringPresentation.runRestoreBackup(备份恢复接线);
  • Vault MCP 双库 json search → notes read 的 body offset;
  • Compose 帧 168。

574 则在 573 之上新增四条独立链路:F10 的方案导入/导出、F02 的 .diff-editor-grid 网格与中缝、Vault MCP 双库 notes search → json read 的 body offset,以及证据脚本与 Compose 帧 169。

值得强调的是,这一系列切片有一个贯穿始终的未完成目标(parity-gap):Electron 六套 CSS 逐选择器皮肤的全量移植、产品主窗 F02/F10/IME/TCC 手工 PNG、以及 P7 三平台安装/公证均仍未达成,574 同样如此。读者不应把本切片理解为某个完整功能的交付,而是整体 parity 迁移中的一个增量步骤。

二、F10 Host 方案导入/导出接线:从裸 I/O 到 Presentation 封装

2.1 为什么要把读写收口到 Presentation 层

574 之前在 Host 侧栏的导入/导出可能存在直接在 UI 中 readText() / writeText() 的做法。574 将该逻辑收口到 HostWiringPresentation 对象中,核心目的是:让文件 I/O 具备可单测性,同时把错误处理统一到状态栏与 Toast 通知链路,避免 UI 层直接抛出或吞掉异常。

在 HostWiringPresentation.kt 中新增的三个方法是本切片的重点:

fun inferImportProfileName(file: File, untitledKey: String): String =
    file.nameWithoutExtension.ifBlank { untitledKey }

fun runReadImportProfile(file: File): ImportProfileOutcome =
    runCatching {
        ImportProfileOutcome.Success(file.readText(StandardCharsets.UTF_8))
    }.getOrElse { ImportProfileOutcome.Failure(it) }

fun runWriteExportProfile(file: File, content: String): ExportProfileOutcome =
    runCatching { file.writeText(content, StandardCharsets.UTF_8) }.fold(
        onSuccess = { ExportProfileOutcome.Success },
        onFailure = { ExportProfileOutcome.Failure(it) },
    )

实现要点:

  • UTF-8 显式声明:runReadImportProfile 使用 StandardCharsets.UTF_8 读取,runWriteExportProfile 同样显式指定 UTF-8 写出。这样 hosts 方案中的中文注释等非 ASCII 内容不会因平台默认编码差异而损坏,与下方单测中的中文文本场景相呼应。
  • sealed Outcome 契约:ImportProfileOutcome.Success/Failure 与 ExportProfileOutcome.Success/Failure 将异常统一包装,UI 层通过 when 分支分别处理成功与失败,不再裸抛异常。
  • 文件名推断:inferImportProfileName 用 file.nameWithoutExtension 作为导入方案的默认名称,空名时回退到 UI 传入的 untitledKey(即「未命名」本地化文案)。

2.2 UI 接线与状态栏错误文案

在 HostScreen.kt 中,侧栏「导入」「导出」按钮的处理器全部改为走 Presentation:

  • 导入:runReadImportProfile(file) 成功后将内容写入 session.content,并用 inferImportProfileName 设置方案名;失败时调用 notifyHostFailure,状态栏文案使用 reformat.error.read,并附带失败消息或文件路径。
  • 导出:runWriteExportProfile(file, session.content) 成功时弹出「已导出」Toast;失败时状态栏写 reformat.error.write。

这里值得注意的是错误文案复用了 reformat.error.read / reformat.error.write 两个 i18n key——即与 F03 配置转换模块共用「读取失败/写入失败」的本地化文案,而不是为 Host 新建一套。这说明切片开发刻意追求文案复用与 UI 一致性,也是「不再裸 readText()/writeText()」的具体含义:所有 I/O 失败统一进入状态栏 + Toast 的既有反馈通道。

2.3 单测验证

HostWiringPresentationTest.kt 为本切片新增了两条关键测试:

  • runReadImportProfileReadsUtf8:写入 "127.0.0.1 localhost\n" 临时文件后断言 Success.content 与文件内容一致,且 inferImportProfileName 返回 file.nameWithoutExtension;
  • runWriteExportProfileWritesContent:导出后读回文件,断言内容为传入的 hosts 文本,且返回值为 ExportProfileOutcome.Success。

此外 profileAndFindActionEnabled 覆盖了导出按钮的使能规则(exportProfileActionEnabled:内容非空白才可导出),与 Electron 侧工具栏保存 disabled={!dirty} 的语义对齐。

三、F02 diff 编辑器网格:.diff-editor-grid 容器与中缝样式

3.1 组件定义与语义

574 在 Controls.kt 中为文本对比工具新增两个 Modifier 扩展:

/** Electron `.diff-editor-grid` 并排/统一编辑区容器。 */
fun Modifier.mooDiffEditorGrid(): Modifier = fillMaxWidth().heightIn(min = 280.dp)

/** Electron `.diff-editor-grid` 中缝(需配合 `background(borderSoft)`)。 */
fun Modifier.mooDiffEditorSeam(): Modifier = width(1.dp).fillMaxHeight()
  • mooDiffEditorGrid 对应 Electron .diff-editor-grid 容器:占满宽度并保证最小 280dp 高度,与同文件的 mooDiffWorkspace()(heightIn(min = 280.dp))保持一致的工作区最小高度。
  • mooDiffEditorSeam 对应 .diff-editor-grid 的纵向中缝分隔线:固定 1dp 宽、占满高度。它本身不带颜色,文档与源码注释均明确要求调用方配合 background(borderSoft) 使用,颜色由主题的 colors.borderSoft 提供。

本切片还沿用了 573 的 mooDiffEditorPane()(.diff-editor-grid > div / .diff-editor-pane 的 10dp 内边距),三者在 TextDiffScreen 中组合使用。

3.2 在 TextDiffScreen 中的实际组合

在 TextDiffScreen.kt 中:

  • 并排(side)模式:Row(Modifier.weight(1f).mooDiffWorkspace().mooDiffEditorGrid()) 作为容器,左 DiffEditorPane 固定宽度(width(leftPaneWidth.dp).widthIn(min = 240.dp)),中间放 VerticalPaneHandle 支持拖动调节栏宽,右 DiffEditorPane weight(1f) 自适应。
  • 统一(unified)模式:左右编辑区之间以 Box(Modifier.mooDiffEditorSeam().background(colors.borderSoft)) 分隔,统一视图面板(UnifiedPane)同样由中缝隔开。
  • 每个 DiffEditorPane 内部 Column 使用 mooDiffEditorPane()(10dp 内边距 + 7dp 行间距),标题 11sp、正文 13sp 等宽字体,滚动状态与 diff 高亮由 DiffHighlightTransformation 提供。

也就是说,mooDiffEditorGrid 定义的是编辑区整体布局骨架,mooDiffEditorSeam 是模式切换时始终存在的视觉分隔,而 mooDiffEditorPane 保证两个编辑面板在两种视图下拥有统一的内边距体验。

3.3 Compose 帧 169:Tab 焦点证据

TextDiffEditorGridCaptureTest.kt 用 runDesktopComposeUiTest(640x220) 渲染一个最小化的左右编辑区样例(左栏标题带 mooFocusClickable 焦点请求),输出到 next-compose/docs/evidence/2026-09-15-inspector-screencapture/windows/169-compose-text-diff-editor-grid-tab-focus.png。测试同时以像素计数断言焦点环颜色(0x316DC0 命中像素 ≥ 8),保证截图确实携带可见的 Tab 焦点高亮。该帧明确标注为非产品主窗证据,用于组件级 UI 验收。

Compose 文本对比 .diff-editor-grid 并排编辑区 Tab 焦点测试帧

四、Vault MCP stdio:双库 notes search → json read 的 body offset 链路

4.1 本切片新增的跨库链路

Vault MCP 是 MooTool 通过 stdio 子进程暴露给 AI 客户端的只读工具集,共四个工具:mootool_notes_search、mootool_notes_read、mootool_json_documents_search、mootool_json_documents_read(定义见 VaultMcpTools.kt)。工具调用统一由 McpBootstrap.kt 的 stdio 服务端分发,启动参数为 --mcp --access-file <path>,其中 access file 是一份授权 JSON,声明 notes / json 两个 vault 根目录(version: 1)。

此前各切片已逐条覆盖了同库 search→read、双库 read-only、双库 notes search、双库 json search 等组合(571~573)。574 新增的是「双库 notes search → json read」跨库组合:在同一授权会话内,先用 mootool_notes_search 在 notes vault 中做带 offset 的分页搜索定位文档,再拿定位结果到 json vault 中执行 mootool_json_documents_read,且 read 必须严格遵守 body offset/length。

对应测试为 subprocessDualVaultNotesSearchThenJsonReadHonorsBodyOffset(位于 AiIntegrationVaultMcpConnectionTest.kt)。测试构造两个临时 vault:notes 库含 alpha.md/beta.md(正文 skip574alpha / skip574574tail),json 库含 alpha.json({"tag":"574-alpha","body":"skip574"})与 beta.json({"head":"skip574","tail":"574-json"})。流程为:

  1. mootool_notes_search(query="574", limit=1, offset=1):断言命中 beta.md 而非 alpha.md,验证 notes search 的 offset 分页在双库场景下生效;
  2. mootool_json_documents_read(path="beta.json", offset=18, length=20):断言正文包含 574-json 且不包含 skip574,验证 json read 的 body offset/length 跳过头部位。

测试通过 StdioClientTransport 真实拉起子进程、McpClient.sync 完成 initialize 后调用工具,属于端到端验证而非 mock 单测。

4.2 参数边界与服务端语义

Vault MCP 的参数解析是严格边界校验(对齐 Electron 端 Zod strict schema,不静默钳制,VaultMcpTools.kt):

工具 参数 默认值 取值范围
*_search query "" 字符串,长度 ≤ 200
*_search limit 20 1~50
*_search offset 0 0~2000
*_read path 必填 非空,长度 ≤ 1000
*_read offset 0 0~2,000,000
*_read length 20000 1~50,000

底层实现在 VaultMcpReadService.kt:

  • search 安全上限:目录遍历深度 ≤ 24,访问条目 ≤ 4000,累计字节 ≤ 10MB;跳过点号开头文件与符号链接,遵守 .gitignore(文件须为普通文件且 < 100KB);命中片段截取 240 字符。返回结构含 entries、nextOffset(可分页续读)与 truncated 标记。
  • read 分页语义:文档大小上限 2MB;content 按 offset 到 min(len, offset+length) 截取,返回 totalCharacters 与 nextOffset(未读尽时指向下一页起点),与 notes 端的分页测试一致(subprocessNotesReadHonorsOffsetAndLength 中通过 nextOffset 拼接验证完整性)。
  • 权限与安全校验:授权路径必须为绝对真实目录(拒绝符号链接别名,realpath 与原路径必须一致),越界访问直接抛错;notes 类型还会解析 frontmatter,正文内容基于 content 字段做 offset 切片——这正是「body offset」一词的含义:切片针对文档正文而非原始文件字节。

五、证据脚本与验证命令

5.1 证据提示脚本

证据函数 mootool_evidence_print_text_diff_editor_grid_tab_focus_hint 定义于 product-evidence-common.sh,打印两行提示:

  • 帧 169 PNG 的存放路径(docs/evidence/2026-09-15-inspector-screencapture/windows/169-compose-text-diff-editor-grid-tab-focus.png),并标注「非产品主窗」;
  • 提醒产品主窗 F02 文本对比 Tab 的走查 PNG 仍需 runDistributable 后手工截图。

verify-product-evidence-prep.sh 在语法自检通过后会 source 公共库并逐一打印各帧 hint(帧 169 在其中),作为证据制备的清单确认。

5.2 验证命令

本切片文档列出的验证命令可直接在 next-compose 目录执行:

./scripts/verify-product-evidence-prep.sh   # 语法检查 + 证据 hint 打印
./gradlew :composeApp:desktopTest --offline   # 桌面端全部测试,需 JDK 21

覆盖本切片的三组测试类:

  • HostWiringPresentationTest —— 方案导入/导出/命名推断;
  • AiIntegrationVaultMcpConnectionTest —— Vault MCP stdio 端到端(含 574 的 notes search → json read 跨库链);
  • TextDiffEditorGridCaptureTest —— 帧 169 渲染与焦点环像素断言。

六、未做事项与本切片的边界

文档「未做」部分明确列出 574 之后的遗留工作,这些内容不应被理解为 574 的功能缺失,而是整个 parity 迁移计划的既有 backlog:

  1. Electron 六套 CSS 逐选择器全量移植:当前 mooDiffEditorGrid 等只是针对 .diff-editor-grid 等单选择器的移植,Electron 侧六套皮肤(theme)下的全部 CSS 选择器尚未逐条搬到 Compose;
  2. 产品主窗 F02/F10/IME/TCC 手工 PNG:帧 169 属于组件级证据,产品主窗内实际渲染效果的截图仍需 runDistributable 后人工走查补充;
  3. P7 三平台安装/公证:跨平台安装包与 macOS 公证流程未完成。

相应地,「整产品完成、目标未达成」是每个切片的固定收尾语:DIFF-574 只负责把上述三条链路补齐并给出证据,不承担整个 parity 目标的收口。

小结:从 DIFF-574 可以看到什么

next-compose/docs/diff/574-host-diff-mcp-css-slice.md 是一份高质量的分片工程记录,它体现了 MooTool 桌面端 parity 迁移的可执行方法论:每个切片收敛在少量可验证的 UI 组件 / 领域方法 / MCP 工具链上,用 runCatching + sealed Outcome 把 I/O 风险收口到可单测的 Presentation 层,用 stdio 子进程测试逐条验证工具链的组合语义,再用带像素断言的 Compose 截图帧作为视觉证据。 对读者而言,沿着这份记录可以依次索引到 HostWiringPresentation、mooDiffEditorGrid/Seam 与 VaultMcpReadService 三处源码,并复跑 desktopTest 与证据脚本验证其行为。

登录后查看全文
MooTool