MooTool Next Compose 的 F06 配置工具接线与 Vault MCP 双库读取偏移:DIFF-570 技术解析
MooTool Next Compose 的 F06 配置工具接线与 Vault MCP 双库读取偏移:DIFF-570 技术解析
导读
DIFF-570 是 MooTool Next Compose 桌面端开发推进过程中的一个工程增量切片,聚焦三件事:将 F06 配置转换工具的按钮动作统一收敛到 ConfigWiringPresentation 层(消除 UI 直接调用引擎与分散的 runCatching);为 YAML 校验 Tab 补充两段 Compose 样式(mooConfigValidateLayout / mooConfigValidateActions);以及让 Vault MCP 的 notes 读取在"双库同会话授权"的前提下正确遵守 offset/length 分页参数。本文将从源码与测试出发,逐条还原 DIFF-570 的行为、实现依据与验证方式,帮助读者理解 MooTool Next Compose 的 Presentation 接线模式、CSS 对位手段与 MCP 参数边界语义。
1. 背景:DIFF-570 在整个推进序列中的位置
DIFF-570 明确声明"不重复" DIFF-569 已有的成果。DIFF-569 已交付:F18 时间工具的 TimeWiringPresentation.run* 接线、mooTimeQuickZones 样式、Vault MCP 双库 json read offset、Host 方案行证据 hint、Compose 帧 164。DIFF-570 在同一个"逐切片推进 parity"的节奏里补齐 F06 与双库 notes read offset,并将 Compose 证据帧推进到 165。
该切片仍列入 parity-gap 的未达成项包括:Electron 六套 CSS 逐选择器全量移植、产品主窗 Tab/IME/TCC 手工 PNG、P7 三平台安装验证(原文档)。
2. F06 配置 run* 接线:按钮不再直接触碰引擎
2.1 行为目标
DIFF-570 的核心行为定义:
ConfigWiringPresentation.runToYaml/runToProperties/runValidate/runFormat,并且ConvertOutcome对齐CronWiringPresentation.runPreview;ConfigConvertScreen的转换/校验/格式化按钮走 Presentation,不再直接ConfigEngine+ 分散runCatching。
也就是说,DIFF-570 把"引擎能力"与"UI 调用方式"之间的耦合解开:引擎仍是 ConfigEngine,但 UI 一律通过 ConfigWiringPresentation 调用,错误统一收敛为 ConvertOutcome。
2.2 源码中的实际实现
ConfigWiringPresentation 对外暴露四组 run* 入口(源码见 ConfigWiringPresentation.kt):
fun runToYaml(properties: String): ConvertOutcome =
runCatching { ConfigEngine.propertiesToYaml(properties) }.fold(
onSuccess = { ConvertOutcome.Success(it) },
onFailure = { ConvertOutcome.Failure(it) },
)
fun runToProperties(yaml: String): ConvertOutcome =
runCatching { ConfigEngine.yamlToProperties(yaml) }.fold(
onSuccess = { ConvertOutcome.Success(it) },
onFailure = { ConvertOutcome.Failure(it) },
)
fun runValidate(source: String): YamlValidation = ConfigEngine.validateYaml(source)
fun runFormat(source: String): ConvertOutcome =
runCatching { ConfigEngine.formatYaml(source) }.fold(
onSuccess = { ConvertOutcome.Success(it) },
onFailure = { ConvertOutcome.Failure(it) },
)
设计要点:
- 转换与格式化是"可能抛异常"的操作,因此用
runCatching{}.fold()收敛为ConvertOutcome.Success(output)/ConvertOutcome.Failure(error); - 校验
runValidate本身返回YamlValidation(valid, message),不抛异常(引擎内部已将 YAMLException 转为ConfigException("syntax", …)); - 同一文件中还包含导入/导出 IO 接线:
runReadImportFile(UTF-8 读取,返回ImportOutcome)与runWriteExportFile(UTF-8 写出,返回WriteExportOutcome),以及shouldToastConvertFailure/shouldToastIoFailure两个"是否弹 toast"决策点,供 UI 层统一处理失败反馈。
2.3 UI 侧接线:ConfigConvertScreen
ConfigConvertScreen.kt 中,所有动作按钮的 enabled 守卫与点击回调都只依赖 Presentation:
- 转换 Tab:
ConfigWiringPresentation.propertiesToYamlActionEnabled(session.properties)、yamlToPropertiesActionEnabled(session.yaml)决定按钮是否可用;点击后调用convert(...),内部经runToYaml/runToProperties执行; - 校验 Tab:
validateYamlActionEnabled/formatYamlActionEnabled守卫;点击后调用validate(...)/format(...),内部经runValidate/runFormat执行; - 导入/导出:
exportTextActionEnabled(session.properties / session.yaml)守卫导出按钮,导入/导出经runReadImportFile/runWriteExportFile落地。
成功路径会写通用历史(container.history.save(...),metadata 区分 convert/validate/format),失败路径走 notifyConfigFailure(...),内部依据 shouldToastConvertFailure / shouldToastIoFailure 决定是否弹 error toast。这正对应 DIFF-570 所述"不再直接 ConfigEngine + 分散 runCatching"。
2.4 测试印证
ConfigWiringPresentationTest.kt 覆盖了 DIFF-570 的关键语义:
convertDirectionsRequireSource:空串转换禁用(canToYaml("") == false,canToProperties("") == false);toolbarActionEnabledMatchesGuards:按钮守卫与run*前置条件一致,且空白内容导出禁用(exportTextActionEnabled(" ") == false);runToYamlRoundTrip:"a=b"→ YAML 含a:,再回转 Properties 仍含a=b(往返稳定);runValidateAndFormat:"a: 1"校验通过、"a: ["校验失败,格式化成功;runReadImportAndWriteExportRoundTrip与两个失败用例:读缺失文件、写不存在父目录都会得到Failure结果,印证 IO 失败路径被收敛到ImportOutcome/WriteExportOutcome。
3. 引擎层:ConfigEngine 的 Properties ↔ YAML 语义
DIFF-570 的接线层之上,真正的语义由 ConfigEngine 承担,理解它有助于解释 Presentation 为什么会得到 ConfigException:
- propertiesToYaml:逐行解析,跳过
#/!注释与空行;分隔符识别(=/:,支持\转义);点路径与[index]数组下标(pathToken正则([^\[\]]+)|\[(\d+)\]);标量数组按[0]、[1]展开;值解码支持\uXXXX转义、\n、\t、转义分隔符还原; - yamlToProperties:要求 YAML 根必须是对象(否则抛
ConfigException("root", …));递归扁平化时标量列表合并为逗号分隔(a=b,c),嵌套列表按key[index]展开; - 类型冲突显式报错:标量覆盖已有对象/数组时抛
ConfigException("conflict", …)——这正是 DIFF-570 后 UI 能展示"类型冲突"文案(config.error.conflict)的引擎依据; - validateYaml:空白输入视为合法;解析失败(SnakeYAML
YAMLException)转为ConfigException("syntax", …)并返回valid=false; - formatYaml:重新
dumpYaml(indent 2、BLOCK flow、允许 Unicode、显式开始/结束标记关闭)。
4. 样式(CSS 组件批次):两段 Compose 对位样式
DIFF-570 属于"CSS 组件批次",其目标是把 Electron 侧的选择器视觉密度移植到 Compose 端:
mooConfigValidateLayout(对齐 Electron F06.yaml-validate-layout的 14dp padding);mooConfigValidateActions(对齐.validate-actions160dp 中栏)。
源码定义位于 Controls.kt:
fun Modifier.mooConfigValidateLayout(): Modifier = padding(14.dp)
fun Modifier.mooConfigValidateActions(): Modifier = widthIn(min = 160.dp, max = 160.dp)
fun Modifier.mooConfigConvertActions(): Modifier = widthIn(min = 110.dp, max = 160.dp)
同文件还给出了转换 Tab 的中栏 mooConfigConvertActions(110–160dp 弹性区间)。在 ConfigConvertScreen 中:
- 校验 Tab 的三栏容器挂
mooConfigValidateLayout()(middleRatio = 0.32f、minRight = 220f); - 校验 Tab 中栏按钮列挂
mooConfigValidateActions(); - 转换 Tab 中栏挂
mooConfigConvertActions()(middleRatio = 0.28f、minRight = 240f)。
三栏宽度通过 IoThreePaneRow 支持拖动并持久化(DIFF-168 的 pane-import 链)。
5. Compose 证据帧 165:焦点环回归测试
DIFF-570 的验收包含一张 Compose 证据图:ConfigValidateCaptureTest → 165-compose-config-validate-tab-focus.png(非产品主窗)。
ConfigValidateCaptureTest.kt 的实现方式:
- 以 200×140 的
runDesktopComposeUiTest渲染 F06 校验 Tab 中栏:160dp 宽的mooConfigValidateActions()列,内含一个prominent = true的"校验"按钮(zh.t("config.validate")),按钮挂focusRequester; - 渲染后用
FocusRequester.requestFocus()触发焦点环,captureToImage().toAwtImage()写盘到docs/evidence/2026-09-15-inspector-screencapture/windows/165-compose-config-validate-tab-focus.png; - 断言焦点环像素:对期望的 accent 色
0x316DC0做逐像素计数,要求countRingPixels(...) >= 8,确保按钮确实绘制了可辨识的焦点外描边。
该图片的登记信息同时出现在 results.md("F06 YAML 校验 Tab「校验」按钮焦点环")与 acceptance.md 的 F06 行。注意:证据脚本明确注明这是 Compose 测试场景帧,产品主窗的校验 Tab 走查 PNG 仍需 runDistributable + 手工截图,两类图片不能互相替代。
6. Vault MCP stdio:双库同会话下的 notes read offset
6.1 行为目标
subprocessDualVaultNotesReadHonorsOffsetWhenJsonGranted:双库(notes + json)在同一个 access 会话下,notes 的 read 必须遵守 offset/length(区别于 DIFF-569 的双库 json read offset,以及 DIFF-567 的双库 notes search offset)。
其背后要防的回归是:当授权文件同时声明了 notes 与 json 两个库时,分页参数不能因"双库模式"被绕过或失效。
6.2 测试构造(AiIntegrationVaultMcpConnectionTest)
AiIntegrationVaultMcpConnectionTest.kt 中的 subprocessDualVaultNotesReadHonorsOffsetWhenJsonGranted:
- 准备 notes 库
page.md(frontmatter + 正文skip570tail)与 json 库doc.json; - 写 access 文件:
{"version":1,"notes":"<notes 根>","json":"<json 根>"}——同一份授权同时开放双库; - 通过
desktopTestMcpLaunch(accessFile)拉起当前 JVM 的MainKt --mcp --access-file ...作为 stdio 子进程,用StdioClientTransport+McpClient.sync建连; - 调用
mootool_notes_read,参数path=page.md, offset=4, length=7; - 断言返回正文包含
570tail、不包含skip——证明 offset 被真实跳过,而不是整段返回。
该测试类里 569/570 的关键区分链一目了然:subprocessDualVaultJsonReadHonorsOffsetWhenNotesGranted(569,json read)与 subprocessDualVaultNotesReadHonorsOffsetWhenJsonGranted(570,notes read)是对称的双向补丁。
6.3 实现侧:VaultMcpTools 与 VaultMcpReadService
VaultMcpTools.kt 暴露四把只读工具,其中 mootool_notes_read / mootool_json_documents_read 共用 readArgs:
| 参数 | 默认值 | 边界 | 说明 |
|---|---|---|---|
path |
必填 | ≤ 1000 字符、非空白 | 相对 Vault 根的文档路径 |
offset |
0 | 0 ~ 2_000_000 | 字符偏移起点 |
length |
20_000 | 1 ~ 50_000 | 本次读取字符数 |
参数解析采用严格边界(boundedInt 越界直接抛 IllegalArgumentException,不静默钳制),注释明确"对齐 Electron vaultTools.ts 中 searchSchema/readSchema(Zod strict 边界)"。
VaultMcpReadService.kt 的 read 是 offset 语义的执行点:
val end = minOf(document.content.length, offset + length)
return VaultMcpReadResult(
path = normalized,
title = document.title,
content = document.content.substring(offset, end),
modifiedAt = document.modifiedAt,
totalCharacters = document.content.length,
nextOffset = if (end < document.content.length) end else null
)
要点:
offset超出文档长度时substring(offset, end)会抛异常并被VaultMcpTools.call捕获为McpToolResult(isError=true),属于"边界错误而非静默截断";- 返回值携带
nextOffset(续读指针)与totalCharacters,支持客户端分页续读;subprocessNotesReadHonorsOffsetAndLength测试利用nextOffset完成两段拼接并断言合并正文包含MooTool fixture 🐮。
6.4 访问授权文件与安全边界
VaultMcpAccess.read(见 VaultMcpAccess.kt)对 access 文件本身做了多重校验,这也解释了 DIFF-570 测试为什么能安全地在临时目录搭建双库:
- 文件必须存在、是常规文件且不是符号链接;
- 大小上限 16_000 字节;
- JSON 严格解析(
ignoreUnknownKeys = false,未知字段拒绝),version必须为 1; - 任意非法情况统一抛
IllegalArgumentException("Invalid MooTool access settings")。
而 VaultMcpReadService.root 则要求:授权路径绝对、toRealPath() 等于原路径(拒绝符号链接别名根)、必须是目录;notes 或 json 未授权时抛"Read access ... is disabled. Enable it in MooTool Settings → AI integration"。这些边界与 Electron 侧 vaultAccess.test.ts / vaultTools.ts 是 parity 对齐关系(见 DIFF-461/DIFF-469 链)。
6.5 MCP 启动方式:McpLaunchResolver
生产侧客户端启动由 McpLaunchResolver 决定:
accessFile位于配置根的ai-integration/access.json;clientLaunch使用当前进程的 Java 可执行文件,参数为--mcp --access-file <path>;- 测试侧
desktopTestMcpLaunch(AiIntegrationConnectionTest.kt)以java -cp <classpath> com.rememberber.mootool.next.compose.MainKt --mcp --access-file <path>起子进程,保证"stdio 子进程端到端"真实走完 MCP initialize 协商与工具调用。
7. 证据脚本与工程验证入口
DIFF-570 的证据脚本为 mootool_evidence_print_config_validate_tab_focus_hint,在 product-evidence-common.sh 中定义,打印两行:
# Compose F06 YAML 校验 Tab 按钮焦点帧(非产品主窗): docs/evidence/2026-09-15-inspector-screencapture/windows/165-compose-config-validate-tab-focus.png
# 产品窗 F06 校验 Tab 走查 PNG 仍须 runDistributable + 手工截图
verify-product-evidence-prep.sh 是非交互式烟雾脚本,会依次:验证 Vault 外部冲突/git merge/rebase 冲突/编辑器 IME/托盘录屏等产品证据准备脚本的真实产物,然后 bash -n 语法检查 P7 打包脚本,最后 source 公共库并打印全部 hint(含 570 的 F06 帧 165 hint)。
DIFF-570 的验证命令:
./gradlew :composeApp:desktopTest --offline # JDK 21
涉及测试:ConfigWiringPresentationTest / AiIntegrationVaultMcpConnectionTest / ConfigValidateCaptureTest。工程入口与 JDK 21 前提在 acceptance.md 的"工程检查入口"一节也有记录。
8. 未做事项与后续边界
按 DIFF-570 原文档,本切片明确"未做":
- Electron 六套 CSS 逐选择器全量移植(
mooConfigValidateLayout/mooConfigValidateActions只是 F06 的组件批次对位,非逐选择器皮肤); - 产品主窗 IME/TCC 手工 PNG;
- P7 三平台安装/公证;
- 整产品完成,目标未达成。
后续切片(如 DIFF-575 导入导出接线、DIFF-576 导入失败可见 + mooConfigConvertActions、DIFF-578 导出失败 toast、DIFF-650 *ActionEnabled 与 tools.exportDirectory)在此之上继续补齐 F06 的按钮守卫与 IO 反馈链,读者可在 docs/diff 目录沿编号追踪完整演进。
9. 小结
DIFF-570 提供了三条可复用的工程范式:
- Presentation 接线:UI 动作统一走
*WiringPresentation.run*,错误收敛为 sealed outcome(ConvertOutcome/ImportOutcome/WriteExportOutcome),按钮守卫(*ActionEnabled)与执行入口同源,降低分散runCatching带来的重复与不一致; - CSS 对位组件批次:用 Compose Modifier 扩展(
mooConfigValidateLayout/mooConfigValidateActions/mooConfigConvertActions)把 Electron 选择器的关键密度参数(padding、中栏宽度)落成可复用的 UI 基建,并以焦点环像素断言(countRingPixels)守住回归; - MCP 参数语义:
offset/length的边界(search 的limit 1~50 / offset 0~2000,read 的offset 0~2_000_000 / length 1~50_000)在VaultMcpTools严格校验,在VaultMcpReadService严格执行,并通过 stdio 子进程端到端测试验证双库授权互不干扰、分页不被绕过。
关键源码路径速查:F06 接线 ConfigWiringPresentation.kt 与 ConfigConvertScreen.kt、引擎 ConfigEngine.kt、样式 Controls.kt、MCP VaultMcpTools.kt 与 VaultMcpReadService.kt、端到端测试 AiIntegrationVaultMcpConnectionTest.kt。