一致性與明細檢視

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 修改。