一致性与明细视图

VMark 的一致性层让递归式推进的写作项目保持诚实：它记录每次 AI 生成实际读取了哪些文档，在这些上游文档随后发生变化时有所察觉，并在你需要时准确展示哪些下游产物可能已经过期。任何内容都不会被自动更新——你始终是主编。

工作原理（30 秒）

• 每一次保存、精灵应用、被接受的 AI 建议、MCP 写入，以及工作流的 save-file 步骤，都会作为一次转换记录进工作区内的纯文本账本（.vmark/——对 git 友好、人类可读的 JSONL；删除派生出的 index.db 不会丢失任何东西）。
• 当 AI 一边读取其他文档一边写入某篇文档时，这些读取会成为依赖边，并固定到读取当时的确切版本。
• 当上游文档越过被固定的版本继续演进时，这条边就变为过期。如果两个版本平行演化（例如在不同的 git 分支上），这条边则是已分叉——只会被如实呈现，绝不靠猜。
• 在 VMark 之外（终端、其他编辑器）编辑过的文件，会在扫描时被对账为观测到的外部编辑——历史保持没有缺口，并如实标记为来源未知。

明细视图

从 窗口 > 一致性明细 打开（或使用命令面板：“一致性明细”）。它严格采用拉取式：只在你打开它或点击刷新时才会刷新——绝不在后台打扰你。

条目按产物（下游文档）分组，并显示上游文档、被固定的版本以及当前状态：

状态	含义
version-stale	上游已经越过该产物生成时所依据的版本
diverged	被固定的版本与当前版本平行并存——两者之间没有承继关系
diverged-multi-head	上游自身存在多个平行的现行版本
waived	你已接受这次分叉，并记录了理由
unpinnable	上游无法解析（例如固定信息无效）

操作

每个条目提供三种诚实的操作——没有一种会改写历史：

• 接受新版——记录该产物与更新后的上游仍然兼容（即一次追认）。该条目随即离开列表；如果上游再次变化，它会回来。
• 修订——打开该产物以便你更新它。保存新版本后，旧的依赖边随之退役。
• 豁免——记录一次有意为之的分叉，且必须填写理由（不可靠的叙述者是存在的）。被豁免的条目仍然可见，带有醒目的标记，并在上游再次变动时重新打开。

当上游存在多个现行版本时，“接受新版”和“豁免”会被禁用——没有唯一的版本可供裁决；请先修订（或先调和这些版本）。

语义检查、设定与上下文

版本过期只说明上游动过了；语义检查则回答这次变动是否真的与派生文档相矛盾。检查严格采用拉取式：在一条过期的边上点击检查，VMark 就会请你配置的 AI 提供商比较被固定的上游版本、当前版本和派生文本。裁定结果以徽章呈现——已验证有效、相互矛盾（必附一段逐字引用的证据），或当模型不确定、超时或回答未达置信门槛时的未验证。未知就如实呈现为未知，绝不隐藏。只要任一文档再次变动——或设定集发生变化——检查即告失效。

正典设定是你明确写下的事实（“埃琳娜是左撇子”）。在文档中选中文本并运行从选中内容提取设定：设定以草稿身份诞生，并带有来源信息（哪个文档、哪个版本）。当它成为正典时，把它提升为已确立——只有已确立的设定才会被送入语义检查。修正或终止一条设定只会追加历史；任何东西都不会被删除。在某个上下文中隐藏一条设定，是可逆的可见性操作，不是终止。

上下文是工作区的具名视图（default 上下文始终存在）。每个上下文决定“当前”意味着什么、哪些设定适用；子上下文以叠加方式继承父上下文的设定。上下文默认处于温室模式——检查裁定只作为提示性的张力呈现。将某个上下文切换为强制执行（一次明确且需确认的操作）后，矛盾会被标记为违反正典。明细视图的上下文选择器决定你正透过哪个上下文观察；检查结果绑定在产生它们的那个上下文与设定快照上，绝不会泄漏到其他上下文。

来源、委托与分支

有三样东西让一致性层在项目真正演进的过程中保持诚实——它们都不会打扰你，全部是纯拉取式。

来源恢复。当你手动编辑一个派生文档时（在 VMark 中或外部编辑器里），这次编辑会理所当然地丢失它记录在案的输入——旧的依赖边不再描述新的文本。明细里的来源未知分组会主动提出恢复它们：按下建议输入，VMark 就会提出该文档最近一次的先前输入集（保留各自的角色），预先勾选且可编辑。确认来源会把这些边重新挂接到当前版本，而不生成新版本，于是该文档自己的下游绝不会看到一次子虚乌有的变更。从未有过输入的文档永远不会被列出——没有什么可恢复的，也没有什么好打扰你的。

智能体委托。默认情况下，只有你能解决过期的边。如果你想让某个 AI 智能体代表你接受新版或豁免（通过“只读加 resolve”的 MCP 界面），请从明细里授予它一份有时限的委托：为智能体命名，选择范围（接受新版和/或豁免），设置一个到期时间（默认 7 天，绝不“永久”）。每一次受委托的解决都会记录在该授予名下，因此审计轨迹始终显示是谁在谁的授权下行事。任何授予都可一键撤销。正典设定与上下文始终仅限人工——智能体永远无法提升一条设定，也无法强制执行某个上下文。

分支上下文。一个上下文可以映射到某个 git 分支。当你检出一个已映射的分支时，明细会显示一个候选标签，提议切换——它绝不会自行切换。如果该分支还没有上下文，标签会提议创建一个以它命名的上下文。当一次真正的（非快进）合并落地时，一条可忽略的横幅会提醒你查看明细；它所呈现的分歧与过期都是明细的常规状态，因此不会有任何新流程运行——你只是被引导去做这次查看。

Frontmatter 身份

文件首次被捕获时，VMark 会在其 frontmatter 中加入一小段身份信息：

vmark:
  id: 018f3c7a-9f2e-7cc1-b302-5e9d4a6b21c7

这个 ID 让文档在重命名和移动之后仍能保留自己的历史。它从不参与内容哈希（加入它不会被视作一次“变更”），frontmatter 里的其他内容也一概不动。如果你复制了一个文件，重复的 ID 会被检测出来并呈现给你处理——绝不自动修复。

与 Git 的互操作

• .vmark/ 账本文件由 git 跟踪，并能在分支之间干净地合并（只追加，merge=union）。
• 检出、切换分支和重置会被识别为导航——绝不制造幽灵版本。
• git revert 以及产生新内容的合并，会被记录为归因于 git 的转换。
• 派生索引（index.db）已被 gitignore，随时可以从纯文本账本重建。

面向 AI 智能体（MCP）

外部智能体可以通过 coherence MCP 工具（status 与 edges 操作）查询你在 VMark 中打开过的工作区的一致性状态。status 是纯读取；edges 会先做一次对账——它可能向该工作区自己的账本追加来源记录，但绝不触碰你的文档。裁决操作（追认 / 豁免）在这个版本中被有意排除在 MCP 之外——决定权留在应用中的人手里。