MooTool Next Compose 的 F06 配置工具接线与 Vault MCP 双库读取偏移:DIFF-570 技术解析

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

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-actions 160dp 中栏)。

源码定义位于 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 提供了三条可复用的工程范式:

  1. Presentation 接线:UI 动作统一走 *WiringPresentation.run*,错误收敛为 sealed outcome(ConvertOutcome / ImportOutcome / WriteExportOutcome),按钮守卫(*ActionEnabled)与执行入口同源,降低分散 runCatching 带来的重复与不一致;
  2. CSS 对位组件批次:用 Compose Modifier 扩展(mooConfigValidateLayout / mooConfigValidateActions / mooConfigConvertActions)把 Electron 选择器的关键密度参数(padding、中栏宽度)落成可复用的 UI 基建,并以焦点环像素断言(countRingPixels)守住回归;
  3. 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。

登录后查看全文
MooTool