MooTool Next Compose Vault Git 提交/推送前刷新编辑器:`GitEditorFlushPolicy` 的 flush 语义与实现

原创2026-10-14 12:42:301,325 阅读
文章标签:开发工具桌面应用MCP 服务

MooTool Next Compose Vault Git 提交/推送前刷新编辑器:GitEditorFlushPolicy 的 flush 语义与实现

导读

本文深入剖析 MooTool Next Compose 版本(next-compose 模块)中 Vault 仓库的 Git 操作前编辑器刷新机制:在 commit(提交)、push(推送) 等写操作执行之前,VaultGitDialog 会强制调用 onFlush() 将 JSON Vault / 随手记(QuickNote)编辑器的未保存缓冲区写盘,确保 Git 操作针对的是磁盘上的真实内容而非内存草稿。读完本文,你将掌握 GitVaultFlushAction 枚举与 GitEditorFlushPolicy 的判定策略、各 Git 动作的 flush/刷新矩阵、与 Electron 版 prepareGitAction 的对齐关系,以及相关的验证测试与演进历史。


一、背景:为什么 Git 操作前必须先"刷新"编辑器

MooTool 的 Vault(JSON 片段库与随手记)采用"编辑器缓冲区 + 磁盘文件"双轨模型。用户在编辑器里输入的内容默认保存在内存中(session.editor.text),仅在自动保存(250ms 空闲)、用户显式保存或执行特定操作时才落盘。而 Vault Git 面板(VaultGitDialog)通过 GitEngine 直接执行真实的 git CLI 命令,Git 本身只认磁盘文件:

  • git add 暂存的是磁盘内容;
  • git diff、git status 展示的是磁盘与 HEAD 的差异;
  • git commit 打包的是暂存区(staging area)内容。

因此,如果用户在编辑器中修改了笔记但尚未落盘,此时直接提交,Git 看到的仍是被 git add 过的旧内容,提交产物与用户所见缓冲区不一致——这正是 DIFF-184 要解决的问题:在 commit / push 这类依赖工作区内容的操作执行前,先通过 onFlush() 把缓冲区刷新到磁盘,保证"所见即所提交"。

关联文档:DIFF-184:Vault Git 提交/推送前刷新编辑器


二、核心设计:GitVaultFlushAction + GitEditorFlushPolicy

整个 flush 策略被集中封装在两个类型中,位于领域层:

2.1 GitVaultFlushAction:Vault Git 操作的动作枚举

enum class GitVaultFlushAction {
    Pull,
    Discard,
    AbortMerge,
    ResolveConflict,
    ContinueOperation,
    Commit,
    Push,
}

这个枚举覆盖了 Vault Git 面板的全部工作区动作。值得注意的是它只包含会改变工作区或依赖工作区内容的操作,而 fetch、init、配置 remote(setRemote)等操作不携带 GitVaultFlushAction(调用时传入 null),因此不触发额外 flush。

2.2 shouldFlushEditor:执行前是否需要刷新缓冲区

fun shouldFlushEditor(action: GitVaultFlushAction?): Boolean = when (action) {
    GitVaultFlushAction.Discard,
    GitVaultFlushAction.AbortMerge,
    GitVaultFlushAction.ResolveConflict -> false
    GitVaultFlushAction.Pull,
    GitVaultFlushAction.ContinueOperation,
    GitVaultFlushAction.Commit,
    GitVaultFlushAction.Push -> true
    null -> false
}

判定规则可以整理成一张清晰的决策表:

操作 执行前 flush 编辑器? 成功后台后刷新 Vault 树?
Commit(提交) ✅ 是 ❌ 否
Push(推送) ✅ 是 ❌ 否
Pull(拉取) ✅ 是 ✅ 是
ContinueOperation(继续合并/变基) ✅ 是 ✅ 是
Discard(丢弃更改) ❌ 否 ✅ 是
AbortMerge(中止合并) ❌ 否 ✅ 是
ResolveConflict(解决冲突) ❌ 否 ✅ 是
null(fetch / init / setRemote / 面板打开) ❌ 否 ❌ 否

2.3 refreshesVaultAfterSuccess:操作成功后是否刷新 Vault 树

fun refreshesVaultAfterSuccess(action: GitVaultFlushAction?): Boolean =
    action in setOf(
        GitVaultFlushAction.Pull,
        GitVaultFlushAction.Discard,
        GitVaultFlushAction.AbortMerge,
        GitVaultFlushAction.ResolveConflict,
        GitVaultFlushAction.ContinueOperation,
    )

这条规则回答了一个对称的问题:哪些动作会改变磁盘上的 Vault 文件内容,从而需要刷新打开中的编辑器文件。

  • 会刷新:Pull(远端覆盖本地)、Discard(丢弃本地改动)、AbortMerge(中止合并)、ResolveConflict(写入 ours/theirs 解析结果)、ContinueOperation(合并/变基推进后工作区被 Git 改写)。这些动作都可能让当前打开文件的磁盘内容与缓冲区不一致,因此成功后需调用 onVaultRefresh() 重新加载。
  • 不会刷新:Commit 与 Push 本身不改变文件内容(只是打快照、上传),提交成功后 afterSuccess = { onVaultRefresh() } 刷新的是变更列表而非重新加载文件内容。

从源码结构看,这种"刷新树/刷新文件"的双通道设计正是为了让 Git 面板状态(changes 列表、冲突数、ahead/behind)与 Vault 树、打开文件始终保持一致。


三、集成点:VaultGitDialog.runAction 中的 flush 时序

flush 策略的真正落地在 Git 面板对话框 VaultGitDialog.kt 的 runAction 函数中:

fun runAction(
    workingTree: GitVaultFlushAction? = null,
    afterSuccess: (() -> Unit)? = null,
    remoteOverrideAfterReload: String? = null,
    block: () -> GitActionResult,
) {
    scope.launch {
        busy = true
        try {
            if (GitEditorFlushPolicy.shouldFlushEditor(workingTree)) {
                val flushed = onFlush()
                if (flushed != null) {
                    notifyVaultGitFlushBlocked(container, flushed)
                    return@launch
                }
            }
            val result = withContext(Dispatchers.IO) { block() }
            if (result.success) {
                container.toastSuccess(container.t("git.done"))
                afterSuccess?.invoke()
                if (GitEditorFlushPolicy.refreshesVaultAfterSuccess(workingTree)) {
                    onVaultRefresh()
                }
            } else {
                notifyVaultGitActionFailure(container, result)
                if (workingTree == GitVaultFlushAction.Pull) {
                    onVaultRefresh()
                } else {
                    return@launch
                }
            }
            // ... 重新拉取 status / history,同步 remote 字段,触发 onGitStatusChanged()
        } catch (error: Exception) {
            notifyVaultGitPanelFailure(container, error)
        } finally {
            busy = false
        }
    }
}

这里的关键时序(flush → 执行 → 结果处理)可以概括为:

  1. 前置 flush:若 shouldFlushEditor(workingTree) 为 true,调用 onFlush()。onFlush() 返回 String?:返回 null 表示刷新成功(或缓冲区本就干净,无需写盘),可继续执行 Git 操作;返回非 null 表示刷新被阻塞(如文件未命名、写盘失败),此时通过 notifyVaultGitFlushBlocked 弹出错误 toast 并中止 Git 操作(return@launch)。
  2. 后台执行:block() 在 Dispatchers.IO 线程池中执行真实 Git 命令(GitEngine 封装)。
  3. 成功处理:toast 成功提示 → afterSuccess?.invoke() → 若 refreshesVaultAfterSuccess 则 onVaultRefresh()。
  4. 失败处理:弹出失败 toast;Pull 操作失败时仍刷新 Vault(因为 pull 可能已部分改变工作区),其余动作直接中止。
  5. 收尾:重新拉取 GitEngine.status(root) 与 GitEngine.history(root),同步 remote 字段,并调用 onGitStatusChanged() 同步工具栏上的 Git 变更数角标(对齐 Electron 的 refreshGitChangeCount)。

3.1 各按钮的挂载方式

面板中每个操作按钮都通过 workingTree 参数声明自己的动作类型(VaultGitDialog.kt):

按钮 workingTree 参数 底层 Git 操作
提交(commit) GitVaultFlushAction.Commit GitEngine.commit(root, message, identity())
推送(push) GitVaultFlushAction.Push GitEngine.push(root, token = token())
拉取(pull) GitVaultFlushAction.Pull GitEngine.pull(root, token = token())
继续(continue) GitVaultFlushAction.ContinueOperation GitEngine.continueOperation(root, identity())
丢弃(discard) GitVaultFlushAction.Discard GitEngine.discard(root, discardPath)
中止(abort) GitVaultFlushAction.AbortMerge GitEngine.abortMerge(root)
解决冲突(ours/theirs) GitVaultFlushAction.ResolveConflict GitEngine.resolveConflict(root, path, "ours"/"theirs")
拉取远端(fetch) 不传(null) GitEngine.fetch(root, token = token())
初始化(init) 不传(null) GitEngine.init(root, identity())
保存/删除 remote 不传(null) GitEngine.setRemote(root, committed)

fetch / init / setRemote 不传 workingTree,shouldFlushEditor(null) 返回 false,因此不会在操作前打扰正在编辑的缓冲区——这与"打开面板时 load() 不 flush"共同构成了"只在必要时刷新"的克制原则。


四、onFlush() 的两个实际实现:JSON Vault 与随手记

VaultGitDialog 本身不关心编辑器细节,onFlush 是外部传入的回调(onFlush: () -> String?)。项目里两个调用方分别注入各自的刷新逻辑。

4.1 JSON Vault:jsonGitFlushBeforeAction

入口在 JsonScreen.kt,实现于 JsonVaultSession.kt:

internal fun jsonGitFlushBeforeAction(
    container: AppContainer,
    session: JsonSession,
    monitor: VaultRevisionMonitor?,
    onConflict: (VaultConflictState) -> Unit,
): String? {
    val editorHasUserDraft =
        session.editor.text.isNotBlank() && session.editor.text != JsonSession.SAMPLE_JSON
    JsonVaultFooterPresentation.gitUntitledBlockKey(session.currentFile, editorHasUserDraft)?.let {
        return container.t(it)
    }
    if (JsonVaultFooterPresentation.gitFlushSkipsWhenClean(session.currentFile, session.isVaultEditorDirty())) {
        return null
    }
    return saveJsonVault(container, session, monitor, showToast = false, onConflict = onConflict)
        .fold(
            onSuccess = { null },
            onFailure = { it.message ?: container.t("json.notice.failed") },
        )
}

它的三层守卫逻辑(对齐 Electron prepareGitAction):

  1. 未命名文件守卫:若 currentFile 为空且编辑器里有非示例的用户草稿,返回未命名提示文案,阻止 Git 操作——因为一个未命名文档无法确定写盘目标。
  2. 干净文档跳过:已命名文件且 editor.text == savedText(即缓冲区与磁盘一致,例如刚经过 250ms 自动保存),直接返回 null,不写盘,避免多余 IO 与不必要的 toast 打断(对应 DIFF-332)。
  3. 脏内容才写盘:调用 saveJsonVault(..., showToast = false),静默写盘避免 Git 操作前出现重复的"保存成功"提示;写盘失败则返回错误文案,Git 操作随之中止。

4.2 随手记(QuickNote):quickNoteGitFlushBeforeAction

入口在 QuickNoteScreen.kt,实现于 QuickNoteVaultContext.kt:

internal fun quickNoteGitFlushBeforeAction(
    container: AppContainer,
    session: QuickNoteSession,
    vault: NoteVault,
    monitor: VaultRevisionMonitor?,
    onConflict: (VaultConflictState) -> Unit,
): String? {
    QuickNoteVaultFooterPresentation.gitUntitledBlockKey(
        session.currentFile,
        session.editor.text,
        QuickNoteSession.SAMPLE,
    )?.let { return container.t(it) }
    if (QuickNoteVaultFooterPresentation.gitFlushSkipsWhenClean(session.currentFile, quickNoteDirty(session))) {
        return null
    }
    if (!quickNoteVaultSaveIfNeeded(container, session, vault, monitor, onConflict)) {
        return session.error.ifBlank { container.t("quickNote.saveFailed") }
    }
    return null
}

与 JSON 版本结构一致,唯一差异在脏判定:随手记使用 quickNoteDirty(session),它会同时考虑正文与 metadata(对应 DIFF-366),而 JSON 侧使用 session.isVaultEditorDirty()。两者共同保证了 "Git flush 跳过干净文档" 的语义在两条产品线上的一致性。

4.3 与 Electron 版 prepareGitAction 的对齐

Compose 的这份策略并非凭空设计,而是与 Electron 版本逐点对齐。Electron 端 JSON Vault 面板的对照实现位于 JsonVaultPanel.tsx:

async function prepareGitAction(action: VaultGitAction): Promise<boolean> {
  if (!dirty) return true
  if (action === 'pull' || action === 'continue-operation') return saveSelected()
  return true
}

对照结论:

  • 对齐点:pull / continue-operation 都刷新编辑器;!dirty(缓冲区干净)时放行不写盘。
  • 增强点(Compose 独有):Compose 在 commit / push 前也刷新编辑器(Electron 只在 pull/continue 前保存)。这是 DIFF-184 的关键增强——Git 提交/推送前强制 flush,保证"staged files 与编辑器缓冲区一致"。GitEditorFlushPolicy 源码注释明确记录了这一点:"Electron prepareGitAction saves before pull/continue only. Compose additionally flushes before commit/push so staged files match the editor buffer."
  • 共同边界:discard / abort-merge / resolve-conflict 在两侧都不刷新编辑器(DIFF-110 对齐结论)。

五、被刷新之后:GitEngine 的真实 Git 命令链

onFlush() 保证磁盘内容就绪后,VaultGitDialog.runAction 里的 block() 才真正执行。底层由 GitEngine.kt 封装(全部通过 ProcessBuilder 调用 git CLI,并以 root.toAbsolutePath() 为 key 加锁串行化,避免并发 Git 进程冲突)。

各操作对应的核心命令(有源码依据):

GitEngine 方法 执行的核心命令 前置校验
commit → commitLocked(L467-L485) git add --all 后 git commit -m <message> 消息非空(截断 300 字符)、仓库已初始化、无进行中合并、存在变更
push(L255-L265) git push -u origin HEAD 仓库已初始化、无进行中合并/冲突、存在 origin remote
pull(L242-L253) git pull --no-rebase origin 仓库已初始化、非 merging、无冲突、配置了 remote
fetch(L238-L240) git fetch --prune origin 需 origin remote
discard(L267-L287) 未跟踪文件用 git clean -f;已跟踪文件用 git restore --staged --worktree --source=HEAD(失败回退 git reset + git checkout) 路径存在且在工作区变更中

其中 commit 的身份参数值得注意(identityArgs,L487-L491):

private fun identityArgs(identity: GitIdentity): List<String> = listOf(
    "-c", "user.name=${identity.name.ifBlank { "MooTool Next Compose" }}",
    "-c", "user.email=${identity.email.ifBlank { "next-compose@local" }}",
    "-c", "commit.gpgsign=false"
)

即每个 commit 都以 -c 注入 user.name / user.email(从设置中的 vault.gitUsername 派生,未配置时使用默认占位值),并显式关闭 GPG 签名(commit.gpgsign=false),避免本机全局 Git 配置干扰 Vault 提交的确定性。


六、演进历史:从"无条件 flush"到"策略化按需 flush"

这一节整理 flush 语义在 next-compose/docs/diff 系列文档中的演进脉络,理解它有助于把握当前设计的边界:

  1. DIFF-110「Git 面板 P5 与 flush 语义」:确立 discard / abort-merge / resolve-conflict 执行前不再调用 onFlush(对齐 Electron prepareGitAction);pull / continue-operation 仍先 flush。参见 110-git-panel-p5-flush.md。
  2. DIFF-184「提交/推送前刷新编辑器」(本文主体):把 flush 面扩展至 commit / push,并将全部规则收敛到 GitEditorFlushPolicy + GitVaultFlushAction。原文档当时还提到"打开面板时 load() 仍会 flush 一次"。
  3. DIFF-198「Git 面板打开/刷新不再隐式 flush」:后续修订撤销了 load() 中的无条件 onFlush()——Electron 的 load 仅拉取 status/history,不调用 prepareGitAction;Compose 对齐后,打开面板、点刷新按钮都不再触发保存/toast,只在真正执行 pull / continue / commit / push 时才 flush。参见 198-git-panel-load-no-flush.md。
  4. DIFF-332「JSON Vault Git flush 跳过已保存文件」 与 DIFF-366「随手记 Vault Git flush 跳过干净文档」:进一步优化 onFlush 内部实现,缓冲区与磁盘一致时跳过写盘、脏时才静默保存,避免多余 IO 与重复 toast。参见 332-json-git-flush-skip-clean.md 与 366-quicknote-git-flush-skip-clean.md。

最终形成的设计原则可以概括为:flush 只发生在"即将执行依赖磁盘内容的写操作"之前,且只在"缓冲区确实脏"时落盘;不刷新编辑器的操作(discard/abort/resolve)与不依赖工作区内容的操作(fetch/init/setRemote/面板打开)一律不打扰用户。


七、验证方式:单元测试与全量桌面测试

DIFF-184 给出的验证手段有两层,均可在仓库中复现。

7.1 GitEditorFlushPolicyTest

策略的单元测试位于 GitEditorFlushPolicyTest.kt,包含三个用例:

@Test
fun flushBeforePullCommitPushNotBeforeDiscard() {
    assertTrue(GitEditorFlushPolicy.shouldFlushEditor(GitVaultFlushAction.Pull))
    assertTrue(GitEditorFlushPolicy.shouldFlushEditor(GitVaultFlushAction.Commit))
    assertTrue(GitEditorFlushPolicy.shouldFlushEditor(GitVaultFlushAction.Push))
    assertFalse(GitEditorFlushPolicy.shouldFlushEditor(GitVaultFlushAction.Discard))
}

@Test
fun vaultRefreshAfterPullNotAfterCommit() {
    assertTrue(GitEditorFlushPolicy.refreshesVaultAfterSuccess(GitVaultFlushAction.Pull))
    assertFalse(GitEditorFlushPolicy.refreshesVaultAfterSuccess(GitVaultFlushAction.Commit))
    assertFalse(GitEditorFlushPolicy.refreshesVaultAfterSuccess(GitVaultFlushAction.Push))
}

@Test
fun fetchAndInitDoNotImplicitlyFlush() {
    assertFalse(GitEditorFlushPolicy.shouldFlushEditor(null))
}

三个用例恰好覆盖了策略决策表的三个关键分支:要 flush 的动作、成功后要刷新 Vault 的动作、不隐式 flush 的动作(null),构成对 GitEditorFlushPolicy 的完整行为契约。

7.2 全量桌面测试

./gradlew :composeApp:desktopTest --offline

在 DIFF-184 落地时全量桌面测试为 342/342 全部通过(该数字为文档记录的当时结果)。此外,随手记侧的 flush 跳过逻辑还有独立的 QuickNoteGitFlushTest(见 366-quicknote-git-flush-skip-clean.md)。


八、总结

GitEditorFlushPolicy + GitVaultFlushAction 是 MooTool Next Compose 版本 Vault Git 能力中一条精密的"数据一致性防线"。它用一张 8 行决策表,解决了"编辑器缓冲区 vs 磁盘工作区"在不同 Git 操作前的同步问题:

  • 提交/推送前强制 flush(Compose 对 Electron 的增强),保证 staged files 与编辑器所见一致;
  • 拉取/继续操作前 flush,对齐 Electron 行为;
  • 丢弃/中止/解决冲突前不 flush,因为这些操作本身在改写工作区;
  • fetch/init/setRemote/打开面板不 flush,不打扰纯查看场景。

配合 JSON 与随手记两侧的"未命名守卫 + 干净跳过 + 静默写盘"实现,以及 GitEngine 的 CLI 封装与加锁串行化,这套机制在保证 Git 操作正确性的同时,把对编辑体验的打扰降到了最低。对希望理解 Vault 数据一致性设计或复刻类似"编辑器 + Git"集成方案的开发者,这份策略与源码就是一份可直接参考的完整范本。

登录后查看全文
MooTool