一致性與明細檢視

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 開放 — 決定權留在應用程式中的人手上。