一致性与明细视图

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

工作原理（30 秒）

• 来源追踪需手动开启。 请先打开设置 → 文件与图片 → 保存 → 保存时写入标识块。在此之前，任何写入——保存、精灵应用、被接受的 AI 建议、MCP 写入、恢复早期版本，或从文件浏览器新建文件——都不会给你的文件写入标识块，也不会创建 .vmark/。
• 启用后，每一次保存、精灵应用、被接受的 AI 建议、MCP 写入、恢复早期版本，以及工作流的 save-file 步骤，都会作为一次转换记录进工作区内的纯文本账本（.vmark/——对 git 友好、人类可读的 JSONL；删除派生出的 index.db 不会丢失任何东西）。
• 已有账本的工作区（你之前创建的 .vmark/，或协作者提交的 .vmark/）即使关闭此设置，也会继续记录对其所跟踪文档的写入。以下文档算作已跟踪：账本此前记录过的文档，或文件本身已带有 vmark: 标识块的文档——即你移动、复制进来或检出的已跟踪文件；账本自身的扫描纳入的也正是这些。它不会写入任何标识块：没有标识块的文档会被略过，因此输入不完整的写入会记录为 inferred 而非 exact。
• 当 AI 一边读取其他文档一边写入某篇文档时，这些读取会成为依赖边，并固定到读取当时的确切版本。应用内经过插桩的路径记录的是 exact 输入；MCP 写入则如实记录为 inferred——即会话中观测到的读取集合。
• 当上游文档越过被固定的版本继续演进时，这条边就变为过期。如果两个版本平行演化（例如在不同的 git 分支上），这条边则是已分叉——只会被如实呈现，绝不靠猜。
• 在 VMark 之外（终端、其他编辑器）编辑过的文件，会在扫描时被对账为观测到的外部编辑——历史保持没有缺口，并如实标记为来源未知。

明细视图

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

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

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

操作

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

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

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

让不需要的提醒安静下来

明细视图每一行上的两个控件可以收窄一致性层向你询问的范围。二者都仅限人工操作——没有任何 MCP 工具能设置它们。

标记为已完成（文档生命周期）。当某个下游文档已经完成——一个已发布的章节、一份已交付的报告——在它的任意一行上选择标记为已完成。这会让指向该文档的所有依赖安静下来，包括当前未列出的依赖，因此它会请你确认。这些边会移到面板底部折叠起来的不再询问这些分组中，并标注为已完成的文档：仍被跟踪，需要时仍然可见，只是不再打扰你。重新开启只需一次点击、无需确认即可恢复它们，因为重新开启只会把打扰加回来。生命周期记录在账本中，而不是 frontmatter 中，因此把文档标记为已完成不会为它生成新版本。

章节锚点。未锚定的边问的是“上游文件变了吗？”。锚定到章节把问题收窄为“我所依赖的那一节变了吗？”：从上游文档中选择一个标题，这条边就会被固定到该标题路径。只要锚定的章节没有改动，上游其他位置的编辑会让这条边留在被抑制的分组中，标注为所依赖的章节未改动；章节内部的编辑则会让它浮现出来，标注为锚定的章节已改动。如果该标题消失，这条边会被标记为锚点已丢失，而不是悄悄退回整个文件的行为。更改锚点会重新固定它，整个文件则会清除锚点。锚点本身是可修订的独立账本条目，因此在之后的版本中也会跟随这条边。

一致性日志与提醒判定

一致性日志（明细面板中的一个展开区）是账本保存的逐边历史：每一次检查、追认和豁免，每条边被解决过多少次（已解决 3 次），以及有多少条边被解决过不止一次——这就是反复波动，也是嘈杂依赖图真正的负担。模型给出的置信度低于阈值的语义检查，会连同保留下来的裁定与置信度一起显示（模型答复 …（置信度 …），低于阈值），因此“没有信号”与“有回答，但不够自信”始终可以区分。日志从整个账本读取，因此只在你展开它时加载，并在每次展开时重新加载。

这值得提醒吗？每个浮现出来的行都提供值得提醒吗？，有三个答案——值得、不值得、不确定——并且有意不设默认值。你的回答会作为独立的账本条目记录下来，并在日志中汇总（已判定：值得 … · 噪音 … · 不确定 … · 未判定 …）。这正是一致性层据以调校的过期相关性指标：被你判定为噪音的提醒，就是设置章节锚点或标记为已完成的候选对象。

语义检查、设定与上下文

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

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

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

来源、委托与分支

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

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

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

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

Frontmatter 身份

开启保存时写入标识块后，文件首次被捕获时，VMark 会在其 frontmatter 中加入一小段身份信息：

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

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

如果你希望 VMark 从不改动你的文件，请保持保存时写入标识块关闭——这是默认设置。关闭时，无论文件以何种方式写入，VMark 都不会向任何文件加入这段信息——包括 AI 或 MCP 编辑仅读取过的文件。

与 Git 的互操作

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

面向 AI 智能体（MCP）

外部智能体可以通过 coherence MCP 工具（status、edges、claims 与 contexts 操作）查询你在 VMark 中打开过的工作区的一致性状态。status 是纯读取；edges 会先做一次对账——它可能向该工作区自己的账本追加来源记录，但绝不触碰你的文档。该工具声明了 readOnlyHint: true，因此客户端可以自动批准它。

裁决（追认 / 豁免）位于一个独立的工具 coherence_resolve 中，并默认留在人的手里：只有在你向某个特定智能体授予有时限的委托之后，它才能调用该工具，并且每一次裁决都会记录在该授予名下以供审计。把它排除在 coherence 之外，正是为了让读取工具可以被自动批准，而不会让智能体悄悄获得写入你账本的能力。

正典设定与上下文完全无法通过 MCP 修改。