MooTool next-compose DIFF-581 切片解读:F17 二维码保存链路、双库 Vault MCP 分页偏移与 CSS 焦点帧验证

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

MooTool next-compose DIFF-581 切片解读:F17 二维码保存链路、双库 Vault MCP 分页偏移与 CSS 焦点帧验证

导读:本文以 MooTool next-compose 仓库的 DIFF-581 切片(581-qr-mcp-css-slice.md)为骨架,拆解其中三类交付物——F17 二维码预览区的「保存为 PNG」IO 链路与失败 toast、Vault MCP stdio 双库(Quick Notes + JSON 文档)的 notes read → notes search 同会话分页偏移语义、以及 Compose Tab 级截图帧 176 的自动化证据。读者可以借此掌握该仓库在 JDK 21 + ./gradlew :composeApp:desktopTest --offline 验证模式下的代码组织方式,理解一个 DIFF 切片如何由「范围声明 + 验证命令 + 证据帧」构成,并能够直接定位到对应源码与测试文件。

一、切片背景:DIFF 驱动下的增量交付模型

在阅读 DIFF-581 之前,先了解 MooTool next-compose 的增量开发约定。仓库 next-compose/README.md 与 docs/acceptance.md 展示了该工程以 DIFF 切片为单位推进功能验收的做法:每个切片用一个短文档记录「本次范围 + 不重复的基线 + 验证方式」,命名形如 581-qr-mcp-css-slice.md,序号递增,并在 acceptance.md 中汇总每个 DIFF 的 :composeApp:desktopTest 通过数(例如后续切片记录到 1342/1344 tests)。

DIFF-581 的基线与不重复边界都很明确:

  • 基线:DIFF-580(工作区,含 F01 随手记 QuickNote IO,见 580-quicknote-io-mcp-css-slice.md)。
  • 不重复 DIFF-580:F01 QuickNote IO / json read → json search / 帧 175,即本文不再触碰随手记 IO 与 JSON 侧的 read→search 链。
  • 验证命令:JDK 21 下执行 ./gradlew :composeApp:desktopTest --offline。

本文只聚焦 DIFF-581 声明的新增范围:

  1. F17:QrWiringPresentation.runWritePngFile;保存失败 reformat.error.write + error toast;mooQrPreviewActions。
  2. Vault MCP stdio:双库 notes read → notes search body offset(测试 subprocessDualVaultNotesReadThenNotesSearchHonorsBodyOffset)。
  3. 证据:QrPreviewActionsCaptureTest → 176-compose-qr-preview-save-tab-focus.png。

二、F17 二维码「保存为 PNG」:Presentation 层封装写盘 IO

2.1 为什么要把 file.writeBytes 收进 domain

DIFF-581 的第一个落点是让二维码页的保存操作不再裸调 java.io.File.writeBytes,而是统一经过 Presentation 层。新增方法位于 QrWiringPresentation.kt:

sealed interface WritePngOutcome {
    data object Success : WritePngOutcome
    data class Failure(val error: Throwable) : WritePngOutcome
}

fun runWritePngFile(file: File, pngBytes: ByteArray): WritePngOutcome =
    runCatching { file.writeBytes(pngBytes) }.fold(
        onSuccess = { WritePngOutcome.Success },
        onFailure = { WritePngOutcome.Failure(it) },
    )

这是该仓库贯穿 DIFF-570~582 系列的通用模式:所有工具页的读写 IO 都经由 *WiringPresentation 的 run* 方法,返回 sealed outcome 而非直接抛异常。同类切片可对照:

这种设计让写盘失败成为一等公民,UI 可以直接 when 分支处理成功/失败,而测试也能不启动窗口地验证写盘往返。

2.2 UI 接线:保存按钮 → 文件对话框 → 写盘 → 持久化导出目录

保存按钮的实际调用链在 QrCodeScreen.kt:

MooButton(container.t("common.save"), enabled = QrWiringPresentation.hasPngOutput(session.pngBytes), p5Toolbar = true, onClick = {
    val bytes = session.pngBytes ?: return@MooButton
    val file = pickSavePngFile(container, container.t("common.save")) ?: return@MooButton
    when (val outcome = QrWiringPresentation.runWritePngFile(file, bytes)) {
        QrWiringPresentation.WritePngOutcome.Success -> {
            persistToolsExportDirectory(container, file)
            session.notice = container.t("common.save")
            container.toastSuccess(container.t("common.save"))
            session.error = ""
        }
        is QrWiringPresentation.WritePngOutcome.Failure -> {
            notifyQrIoFailure(container, session, outcome.error, file.path, onChanged)
        }
    }
    onChanged()
})

关键点:

  • 启用条件:enabled = QrWiringPresentation.hasPngOutput(session.pngBytes),即无 PNG 输出时保存钮禁用,与 QrWiringPresentationTest.kt 中 hasPngOutput(null) == false 的断言对应。
  • 文件对话框默认名:pickSavePngFile 在 QrCodeScreen.kt 中通过 chooseFileWithExportDirectory(container, save = true, title = title, defaultFileName = "mootool-qrcode.png") 弹出 java.awt.FileDialog.SAVE 对话框,且若用户没有输入扩展名会自动补 .png(if (chosen.extension.isBlank()) File(chosen.path + ".png"))。
  • 导出目录记忆:保存成功后调用 persistToolsExportDirectory(container, file)。其实现位于 ToolsExportDirectory.kt:若 container.settings.value.tools.exportDirectory 与本次选择的父目录不同,则更新设置 tools.exportDirectory。这样下一次任何工具页(F08 导出、F17 二维码、F24 PDF 等)打开对话框时,都会默认定位到最近一次使用的导出目录。这也是 acceptance.md 中「tools.exportDirectory」批量接线系列的组成部分(DIFF-653~661)。

2.3 保存失败的文案与 error toast

DIFF-581 明确要求:保存失败写 reformat.error.write 文案键并弹 error toast。对应实现是 QrCodeScreen.kt 中的 notifyQrIoFailure:

private fun notifyQrIoFailure(container, session, error, path, onChanged) {
    val message = container.t(
        "reformat.error.write",
        mapOf("message" to (error.message ?: path)),
    )
    session.error = message
    session.notice = message
    if (QrWiringPresentation.shouldToastOperationFailure(error)) {
        container.toastError(message)
    }
    onChanged()
}

reformat.error.write 的文案在 Translator.kt(简体中文)与 Translator.kt(英文)中定义为:

  • 中文:保存失败,原文与结果均未改写。可修改后重试:{message}
  • 英文:Save failed; input and result were kept. Fix the path and retry: {message}

注意该键不止 F17 使用——reformat.error.write 是跨功能共用的「写盘失败」统一文案,HostScreen、JsonScreen、HttpScreen、ConfigConvertScreen、VariablesScreen、ReformatScreen 等均在使用,因此 DIFF-581 的「对齐」实质是把 F17 的失败反馈收敛到同一语义。

shouldToastOperationFailure(error) 当前恒定返回 true(见 QrWiringPresentation.kt),并由测试 shouldToastOperationFailure/shouldToastErrorMessage 锁定(QrWiringPresentationTest.kt)。同类 notifyQrFailure 的三态错误映射(QrException.code → qrcode.error.empty / capacity / image / notFound / large / generic)也在 QrCodeScreen.kt 中可见,这是 DIFF-589 才全面展开的 error toast 链的铺垫。

2.4 F17 的单元测试证据

runWritePngFile 的往返测试在 QrWiringPresentationTest.kt:

@Test
fun runWritePngFileRoundTrip() {
    val file = Files.createTempFile("qr-out-", ".png")
    try {
        val bytes = byteArrayOf(0x89.toByte(), 0x50, 0x4E, 0x47) // PNG 魔数
        val outcome = QrWiringPresentation.runWritePngFile(file.toFile(), bytes)
        assertTrue(outcome is QrWiringPresentation.WritePngOutcome.Success)
        assertEquals(bytes.size.toLong(), Files.size(file))
    } finally {
        Files.deleteIfExists(file)
    }
}

该测试验证了「写盘成功返回 Success 且字节数一致」。同一测试类还覆盖了 fromSettings 的尺寸钳制与纠错归一化(qrCodeSize = 20 → 120、"h" → QrErrorCorrection.H)、parseSizeField("360.4") → 360、generateSize(9999) → 2000(上限)等 Presentation 层行为。这些边界值来自 QrEngine.kt 的 DEFAULT_SIZE=300 / MIN_SIZE=120 / MAX_SIZE=2000,以及底层基于 ZXing QRCodeWriter 的 generatePng(含 ERROR_CORRECTION、UTF-8、MARGIN=4 hints)。

三、mooQrPreviewActions:预览区操作栏的 CSS 皮肤

DIFF-581 的第三个 F17 落点是 Compose 端为二维码预览区操作栏增加的 CSS 风格 Modifier。定义在 Controls.kt:

fun Modifier.mooQrPreviewActions(): Modifier = heightIn(min = 34.dp)

其应用点在 QrCodeScreen.kt:预览框下方放置「保存 / 复制图片」两个按钮的行,Row(Modifier.mooQrPreviewActions(), horizontalArrangement = Arrangement.spacedBy(8.dp))。其中:

  • 「保存」按钮:enabled = hasPngOutput(session.pngBytes),即 DIFF-581 的保存链路入口;
  • 「复制」按钮:session.notice = if (bytes != null) copyImage(bytes, container) else ...,底层通过 ImageIO.read + AWT systemClipboard.setContents(ImageSelection(image), null) 将 PNG 以图片 flavor 写入剪贴板(QrCodeScreen.kt)。

这类 moo* Modifier 是 next-compose 对齐 Electron 端 CSS 皮肤的命名约定(如 mooConfigValidateActions、mooConfigConvertActions),把最小高度等布局语义集中到 ui/components/Controls.kt 统一管理。

四、Vault MCP stdio:双库 notes read → notes search 的分页偏移

4.1 切片声明的测试语义

DIFF-581 的 MCP 侧交付是一条「链式」回归测试:在同一个 stdio MCP 会话中,先用 mootool_notes_read 读取某笔记的 body 内容,再用 mootool_notes_search 搜索并把 offset 推进到下一页,验证跨工具链的状态一致性。测试位于 AiIntegrationVaultMcpConnectionTest.kt:

@Test
fun subprocessDualVaultNotesReadThenNotesSearchHonorsBodyOffset() {
    val notesRoot = Files.createTempDirectory("mootool-mcp-vault-dual-notes-read-notes-search-notes-")
    val jsonRoot = Files.createTempDirectory("mootool-mcp-vault-dual-notes-read-notes-search-json-")
    val productRoot = Files.createTempDirectory("mootool-mcp-vault-dual-notes-read-notes-search-product-")
    try {
        notesRoot.resolve("alpha.md").writeText("---\ntitle: a\nsyntax: text/markdown\n---\n581needle-first")
        notesRoot.resolve("beta.md").writeText("---\ntitle: b\nsyntax: text/markdown\n---\n581needle-second")
        jsonRoot.resolve("stub.json").writeText("""{"tag":"581-stub"}""")
        val directories = AppPaths.resolve(productRoot.toString()).also { it.ensureCreated() }
        val accessFile = McpLaunchResolver.accessFile(directories).also { path ->
            path.parent.createDirectories()
            path.writeText("""{"version":1,"notes":"...","json":"..."}""")
        }
        val launch = desktopTestMcpLaunch(accessFile)
        val transport = StdioClientTransport(ServerParameters.builder(launch.command).args(launch.args).build(), McpJsonDefaults.getMapper())
        McpClient.sync(transport).requestTimeout(Duration.ofSeconds(15)).build().use { client ->
            client.initialize()
            val notesRead = client.callTool(CallToolRequest.builder()
                .name("mootool_notes_read")
                .arguments(mapOf("path" to "alpha.md", "offset" to 0, "length" to 11))
                .build())
            // 断言:read 返回的 body 含 "581needle"
            val search = client.callTool(CallToolRequest.builder()
                .name("mootool_notes_search")
                .arguments(mapOf("query" to "581needle", "limit" to 1, "offset" to 1))
                .build())
            // 断言:search 结果含 beta.md(581needle-second),不含 581needle-first
        }
    } finally { ... deleteRecursively ... }
}

该测试的双库语义体现在:access.json 同时授予了 notes 与 json 两个根目录({"version":1,"notes":...,"json":...}),而测试特意在 notes 库放两条 Markdown、在 json 库放一个 stub JSON,确保 read 与 search 都只命中 notes 库、且搜索的 offset=1, limit=1 能准确翻过第一条命中(581needle-first)拿到第二条(581needle-second / beta.md)——这就是「body offset」被验证的含义:search 的 offset 语义与 read 的 body 偏移在跨工具会话中同时成立。

4.2 参数边界:search 与 read 的 Zod 对齐

服务端参数校验位于 VaultMcpTools.kt,刻意与 Electron 端 vaultTools.ts 的 searchSchema / readSchema(Zod strict)保持一致:

工具 参数 默认值 允许范围
mootool_notes_search / mootool_json_documents_search query ""(空串全量扫描) 长度 ≤ 200
limit 20 1~50
offset 0 0~2000
mootool_notes_read / mootool_json_documents_read path 必填 相对路径,1~1000 字符
offset 0 0~2_000_000
length 20_000 1~50_000

注意注释「Zod strict 边界,不静默钳制」:越界参数会抛 IllegalArgumentException 并转为 isError=true,而不是悄悄修正。这与 parseIntStrict(仅接受整数语义的 Int/Long/整值 Double/Float/数字字符串)共同保证了与 Electron 端行为逐位一致。

4.3 底层读服务:搜索遍历与 read 分页

实际的扫描与分页逻辑在 VaultMcpReadService.kt:

  • search(L22-L85):从授权根目录开始 DFS 遍历,深度上限 24 层;访问条目数超过 4000、累计字节超过 10 MB 或命中数超过 offset+limit 时置 truncated=true 并停止;隐藏文件(. 前缀)与符号链接直接跳过;.gitignore 忽略的条目跳过;命中后截取正文中 needle 前 60 字符起、至多 240 字符的 excerpt,返回 entries.drop(offset).take(limit)、nextOffset = offset + limit(还有更多时)与 truncated。
  • read(L87-L105):end = minOf(content.length, offset + length),返回 content.substring(offset, end),并给出 totalCharacters 与 nextOffset(未读完时)。对 Markdown 笔记,正文会先经 NoteFrontmatter.parse 剥离 YAML front-matter(--- title / syntax ---),这解释了测试里 read 到的正文以 581needle-first 开头。
  • 安全边界:root(kind)(L107-L130)要求授权路径为真实目录且必须与 toRealPath() 一致(拒绝符号链接别名);单文档读取上限 2 MB(maxBytes);.gitignore 文件要求常规文件且 ≤ 100 KB;resolveUnderRoot 逐步解析相对路径并拒绝符号链接。这些约束与 Electron 端 vaultAccess.ts 及 SKILL.md 声明的「hidden, gitignored files and symlinks are excluded」「Do not read the underlying files through another route」一致。

4.4 access 文件与 MCP 启动方式

双库授权依赖的 access.json 结构定义在 VaultMcpAccess.kt:

{ "version": 1, "notes": "/绝对路径/notes库", "json": "/绝对路径/json库" }

读取校验(VaultMcpAccess.kt):必须是常规文件、非符号链接、大小 ≤ 16 KB、ignoreUnknownKeys=false(未知字段拒绝)、version 必须为 1。MooTool 会把它写到 configRoot/ai-integration/access.json(McpLaunchResolver.kt),并由 AiIntegrationService 在用户启用读取授权时原子写入。

MCP server 的拉起方式是 stdio 子进程复用当前 Java 可执行文件:McpLaunchResolver.clientLaunch(McpLaunchResolver.kt)构造 java --mcp --access-file <absPath> 参数;McpBootstrap(McpBootstrap.kt)解析 --mcp/--access-file 后,把 mootool_* 四个 vault 工具路由到 VaultMcpTools.call。这就是测试中 desktopTestMcpLaunch(accessFile) + StdioClientTransport 走通的完整链路。

五、证据帧 176:Compose Tab 级 UI 自动化

DIFF-581 的证据产物是 QrPreviewActionsCaptureTest 生成的 176-compose-qr-preview-save-tab-focus.png。测试位于 QrPreviewActionsCaptureTest.kt,是一个 runDesktopComposeUiTest(width = 260, height = 100) 的窗口内渲染测试:

  1. 用 Translator(AppLanguage.ZhCN) 渲染「保存 / 复制图片」两个 MooButton,套上 mooQrPreviewActions() Modifier;
  2. FocusRequester.requestFocus() 使保存钮获得焦点;
  3. captureToImage().toAwtImage() 截屏写入 docs/evidence/2026-09-15-inspector-screencapture/windows/176-compose-qr-preview-save-tab-focus.png;
  4. 用像素计数断言(countRingPixels(image, 0x316DC0) >= 8)验证焦点环颜色命中,即「保存钮获得可见焦点」。

证据帧截图如下(144×82 小图,来自 176-compose-qr-preview-save-tab-focus.png):

176 帧:二维码预览区保存按钮获得焦点时的 Compose Tab 渲染

该测试的注释「F17 二维码预览区保存钮 Compose Tab 焦点帧(非产品主窗)」说明它属于渐进式 UI 证据体系:不依赖完整产品窗口,只渲染被测组件并断言关键视觉特征(这里是焦点环),文件名序号(帧 176)与 DIFF 序号在 acceptance.md 的验收表中持续累进。此类证据由 scripts/verify-product-evidence-prep.sh 一类脚本做二次校验,最终服务于「Compose 端与 Electron 端逐个选择器对齐」的 parity-gap 目标。

六、如何在本仓库复现与继续阅读

运行 F17 与 MCP 相关测试(JDK 21、离线模式):

cd next-compose
./gradlew :composeApp:desktopTest --offline
  • QrWiringPresentationTest:尺寸/纠错归一化、生成、保存往返、toast 判定;
  • QrPreviewActionsCaptureTest:重新生成帧 176 并断言焦点环;
  • AiIntegrationVaultMcpConnectionTest:以 subprocessDualVaultNotesReadThenNotesSearchHonorsBodyOffset 为代表的全部双库链式偏移测试。

继续阅读的代码地图:

七、小结

DIFF-581 以极小的工作量把三类增量钉进了 next-compose 的验证体系:F17 保存链路通过 QrWiringPresentation.runWritePngFile 把写盘失败收敛为 reformat.error.write + error toast,并配以 mooQrPreviewActions 的 CSS 皮肤;Vault MCP 用 subprocessDualVaultNotesReadThenNotesSearchHonorsBodyOffset 验证了双库授权下 notes read → notes search 的分页偏移语义与参数边界;帧 176 则证明 Compose 端预览区保存按钮的焦点交互。理解这类切片文档,等于拿到了定位该仓库任何一项功能「实现 + 测试 + 证据」的入口索引——这正是 MooTool next-compose 以 DIFF 为单位做 parity 对齐的工程方法核心。

登录后查看全文
MooTool