MooTool next-compose DIFF-581 切片解读:F17 二维码保存链路、双库 Vault MCP 分页偏移与 CSS 焦点帧验证
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 声明的新增范围:
- F17:
QrWiringPresentation.runWritePngFile;保存失败reformat.error.write+ error toast;mooQrPreviewActions。 - Vault MCP stdio:双库
notes read → notes searchbody offset(测试subprocessDualVaultNotesReadThenNotesSearchHonorsBodyOffset)。 - 证据:
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 而非直接抛异常。同类切片可对照:
- 580-quicknote-io-mcp-css-slice.md 的
QuickNoteWiringPresentation.runWriteExportText; - 577-host-env-diff-mcp-css-slice.md 的
HostWiringPresentation.runWriteExportProfile; - 582-image-pdf-mcp-slice.md 的
ImageSvgWiringPresentation.runWriteSvgFile。
这种设计让写盘失败成为一等公民,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+ AWTsystemClipboard.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) 的窗口内渲染测试:
- 用
Translator(AppLanguage.ZhCN)渲染「保存 / 复制图片」两个MooButton,套上mooQrPreviewActions()Modifier; FocusRequester.requestFocus()使保存钮获得焦点;captureToImage().toAwtImage()截屏写入docs/evidence/2026-09-15-inspector-screencapture/windows/176-compose-qr-preview-save-tab-focus.png;- 用像素计数断言(
countRingPixels(image, 0x316DC0) >= 8)验证焦点环颜色命中,即「保存钮获得可见焦点」。
证据帧截图如下(144×82 小图,来自 176-compose-qr-preview-save-tab-focus.png):
该测试的注释「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为代表的全部双库链式偏移测试。
继续阅读的代码地图:
- 二维码领域与 UI:QrEngine.kt、QrWiringPresentation.kt、QrCodeScreen.kt;
- MCP 服务:VaultMcpTools.kt、VaultMcpReadService.kt、VaultMcpAccess.kt、McpBootstrap.kt;
- Electron 对应实现:vaultTools.ts、skill/SKILL.md;
- 切片链:580-quicknote-io-mcp-css-slice.md(前序基线)、582-image-pdf-mcp-slice.md(后序同类)、acceptance.md(验收汇总)。
七、小结
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 对齐的工程方法核心。
