MooTool next-compose 开发分片实录:DIFF-574 的 Host 方案导入导出、diff 编辑器网格 CSS 与 Vault 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支持拖动调节栏宽,右DiffEditorPaneweight(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 验收。
四、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"})。流程为:
mootool_notes_search(query="574", limit=1, offset=1):断言命中beta.md而非alpha.md,验证 notes search 的 offset 分页在双库场景下生效;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:
- Electron 六套 CSS 逐选择器全量移植:当前
mooDiffEditorGrid等只是针对.diff-editor-grid等单选择器的移植,Electron 侧六套皮肤(theme)下的全部 CSS 选择器尚未逐条搬到 Compose; - 产品主窗 F02/F10/IME/TCC 手工 PNG:帧 169 属于组件级证据,产品主窗内实际渲染效果的截图仍需
runDistributable后人工走查补充; - 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 与证据脚本验证其行为。
