feat: 文件修改可信層 — 將三層方法論升格為所有修改的認證式交易閘門

[kiki830621]

Problem

Original text:
「轉成十年後仍可能需要的「文件修改可信層」 我要確保的就是所有文件改變都能完全無損也不會壞掉，也跟人看到的一樣，人跟AI能完全有相同理解」

「不用比較吧，工具就是要確認跟人類一樣，我都有方法論了」
— Source: 使用者直接輸入（本對話）

macdoc 不應把長期價值建立在「AI 還不會完整修改 Word」上，而應成為任何人類或 AI 修改 Word 文件時都能依賴的文件修改可信層。專案已具備 Word 模仿三層方法論：Layer 1 位元組保留、Layer 2 合法 typed operation 序列化、Layer 3 真實 Word 渲染效果驗證；缺口是這些 gate 尚未統一成每一次正式修改都不能繞過的執行契約。

本 issue 要把既有方法論從研究、量測與測試流程升格為 runtime certification contract：修改先在隔離候選上執行，只有在預期改變被證明、非預期改變不存在、文件可安全開啟，且人類透過 Word 實際看到的效果符合 AI 的可驗證主張時，才准以原子方式寫回正式文件。

Type

feature

Priority

P1（本週處理）

Expected

1. 所有修改走同一認證入口：每個 mutator、Edit、MCP tool 與未來 AI 操作都必須宣告目標 ElementID、OOXML part、預期內容差異及預期渲染效果；不得另有繞過認證的正式寫回路徑。
2. 隔離式候選修改：先在來源文件的隔離副本套用操作，正式文件在全部 gate 通過前保持位元組不變。
3. Layer 1 — 無損與完整性證明：
   • 未列入意圖範圍的 parts／nodes 必須維持原始位元組或既定 canonical identity。
   • DOCX ZIP、Content Types、relationships、引用目標及 XML 安全檢查全部通過。
   • 修改後文件可由 ooxml-swift 重新讀取，並可由真實 Microsoft Word 開啟。
4. Layer 2 — 合法表示證明：
   • 被修改目標必須能由 typed operation 完整表達。
   • typed ops 從受控基線重放後必須通過 trial-rebuild gate。
   • 目標若只能留在 raw channel、存在 form gap，或 serializer 無法忠實拼寫 Word canonical form，修改必須拒絕；不得用「語意等價」作豁免。
5. Layer 3 — 人類可見效果證明：
   • 每個被改動的格式欄位必須對應 render-effect registry 中通過 probe 的 verified 主張。
   • AI 預測的方向、幅度與可觀測效果必須由真實 Word render oracle 驗證。
   • 未修改頁面／區域不得出現超過門檻的視覺漂移；字形、字型替代、圖片、表格、欄位、註解等尚未覆蓋的效果必須以 effect gap 明確拒絕或標示未認證，不能假裝已理解。
6. 人與 AI 相同理解的操作型定義：AI 對文件結構、內容與排版效果所做的每個主張，都必須映射到人類實際使用的 Word 可觀測結果，並有可重跑的 gate 證據；主觀「看起來差不多」不算通過。
7. No probe, no claim：任一 gate 缺席、skip、unverified、證據過期或環境不符時，不得產生「已認證」結果。系統回傳結構化 form gap、effect gap、preservation violation 或 oracle-unavailable 原因。
8. 原子提交：只有認證成功才能取代正式文件；任何失敗都保留原檔，候選副本與證明報告可供診斷。
9. 認證證書：每次成功修改產生機器可讀且人可讀的證書，至少記錄來源雜湊、操作意圖、允許差異範圍、實際差異、三層 gate 結果、Word／字型／渲染環境版本及證據時間。
10. 任意文件、保守修改：系統可以接收含未知 OOXML 的真實 DOCX；未知但未修改的內容由 raw byte-equal floor 保留。若修改會觸及尚未理解或無法驗證的內容，必須拒絕，而不是破壞或近似處理。

Actual

• docs/word-imitation-methodology.md 已定義三層階梯與「主張必須綁 gate」「no probe, no claim」。
• docx-render-semantics 與 docx-visual-diff-testing 已有真實 Word gated probes、幾何量測及視覺差異基礎，但目前是測試／registry 機制，不是每次正式修改的統一 runtime gate。
• EditError.preserveViolation 已存在於規格，但 WordDocument.apply 的非目標 preservation check 仍標為 Phase 2c follow-up；現行 apply pipeline 仍信任 reducer 的 per-op semantics。
• render-effect registry 只證明目前已量測的部分效果，尚不能支撐「所有文件、所有改變、人與 AI 完全相同理解」的全域主張。
• MCP mutators、Edit algebra、overlay writer、visual oracle 與 certification evidence 尚未由單一 transaction orchestrator 串成不可繞過的提交路徑。

Impact

• 將 macdoc 的定位從「AI 可以操作 Word 的工具」提升為「任何 AI 或人類自動化都可依賴的文件修改可信層」。
• 防止長期最嚴重的失敗類型：文件表面可開啟但內容、格式、關聯或人類看到的結果已被非預期改動。
• 讓「支援」「理解」「無損」從產品宣稱變成可重跑、可稽核、可拒絕的證明。
• 這是跨 ooxml-swift、WordDSLSwift、docx workflow、che-word-mcp 與真實 Word oracle 的 umbrella feature，後續應以 Spectra 拆出清楚階段與驗收 gate。

Related

• Refs Tracking: word-aligned-state-sync round-trip 驗證線（XmlNode tree + .mdocx Swift 腳本） #127 — word-aligned-state-sync round-trip 驗證線
• Refs feat: format alignment engine — 從既有 docx 逆向 template schema 並單指令重建（word reverse 深化） #130 — format alignment engine
• Refs Word-canonical forms 對齊 — 讓真實 Word 文件升級 DSL channel（format-alignment step 2） #131 — Word-canonical forms 對齊
• docs/word-imitation-methodology.md
• docs/render-effect-registry.md
• openspec/specs/ooxml-edit-algebra-runtime/spec.md
• openspec/specs/docx-render-semantics/spec.md
• openspec/specs/docx-visual-diff-testing/spec.md

---

Current Status

Dashboard: For Reviewer / Collaborator

Phase: diagnosed
Last updated: 2026-07-17 by idd-diagnose

Key Decisions

• 採用分層認證協調器；OOXML 核心維持 deterministic 且不依賴 GUI。
• 認證只涵蓋證書明列的 scope、observable、evidence 與環境；未知項 fail closed。
• Complexity 判定為 Spectra；下一階段由使用者選定 spectra-discuss。

Scope Changes

• (none)

Blocking

• (none)

Commits

• (none)

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

#137 的方法論不是多餘的；真正的缺口是「三層證據已各自存在，但沒有被組成所有修改都必經、失敗即不得提交的認證交易」。目前狀態如下：

1. Layer 1 的保真原語存在，但防線尚未兌現。 WordDocument.apply(_:) 的公開說明宣稱會在防禦性檢查失敗時拋出 EditError.preserveViolation（packages/ooxml-swift/Sources/OOXMLSwift/EditAlgebra/WordDocument+Apply.swift:17-28），錯誤型別也已存在；然而目前實作只依 operation 找到目標 part、materialize 後直接提交 operationLog 與 xmlTrees，沒有比較未宣告目標 part／subtree 的 canonical identity。既有 spec 也把這項檢查標成 phased follow-up。也就是說，底層目前能「正確套用已知 operation」，但還不能證明「沒有額外改到別處」。
2. 工作流已有驗證器，但它是選配且未進入交易路徑。 Manifest.verify 是 optional；Verifier 能檢查 XML 可解析、計數與指定 part 的 raw-byte equality（packages/docx-workflow-swift/Sources/DocxWorkflowLib/Verifier.swift:25-59），但 Executor.apply 沒有呼叫它，而是在修改完成後直接把 bytes 寫到最終 outputURL（Executor.swift:23-70）。目前只有測試直接呼叫 Verifier。因此驗證不是 universal gate，失敗也無法阻止最終路徑先被覆寫。
3. Layer 3 的 Word oracle 仍是測試設施，不是可重用的執行期能力。 VisualDiffHarness、RenderProbeHarness 位於 OOXMLSwiftTests，依 RUN_WORD_INTEGRATION=1 啟用，環境不具備時會 skip；它們尚無法被 DocxWorkflowLib 或 MCP 儲存流程當成 fail-closed gate。docs/render-effect-registry.md 目前也只為有限欄位建立可觀察、可重現的效果證據，不能據此宣稱任意 OOXML 屬性都已與人類理解一致。
4. 高階修改入口仍可繞過驗證。 mcp/che-word-mcp/Sources/CheWordMCP/Server.swift 的 save、autosave、checkpoint 路徑直接呼叫 DocxWriter.write；這些路徑有耐久性與備份保護，但沒有意圖範圍、三層 gate 或認證證書。CLI／library 也可直接使用 writer。現在沒有一個共同邊界能保證「任何對外宣稱為可信的修改」都經過相同檢查。
5. 缺少可稽核的共同語言。 現有 operation log 描述「做了什麼」，但尚未同時攜帶「允許改哪裡、預期人類會看到什麼、用了哪個 Word／字型／render 環境驗證、哪些主張因 registry 不支援而拒絕」。因此 AI 與人目前可以共享操作描述，還不能共享一份可驗證的理解契約。

Issue 無附件；本次分析以 issue body、現行 specs、程式碼與測試為依據。

Impact

• 影響的核心模組：packages/ooxml-swift 的 Edit／Operation scope 與 preservation check；packages/docx-workflow-swift 的 Manifest、Executor、Verifier、候選輸出與 commit 流程；mcp/che-word-mcp 的 save／finalize／autosave 整合。
• 影響的驗證設施：VisualDiffHarness、RenderEffectProbeTests、render-effect registry，以及真實 Word fixture corpus。
• 影響的規格：至少包含 ooxml-edit-algebra-runtime、docx-workflow-cli、docx-render-semantics、docx-visual-diff-testing、format-alignment-pipeline、ooxml-atomic-save、ooxml-roundtrip-fidelity。
• 影響的使用者流程：AI／CLI／MCP 修改文件後的儲存、另存、autosave、finalize；任何顯示「成功」或「與 Word／人類一致」的結果。

Strategy

推薦採用分層認證協調器，置於 workflow／tool 邊界；低階 OOXML 核心維持 deterministic、無 GUI 依賴。不要把 live Word 直接塞進 WordDocument.apply，也不要只在 MCP 外層補一個特例。

• 凍結認證契約與術語。 定義 MutationIntent（操作、允許變更範圍、預期可觀察效果）、CertificationPolicy、每層 GateResult、CertificationCertificate 與明確的 uncertified 狀態。把「人與 AI 相同理解」收斂成可稽核條件：雙方讀的是同一份 intent、observable、evidence 與限制。
• 補齊 Layer 1 的不可旁路保真檢查。 每個 edit／operation 必須可推導或宣告 target parts／ElementIDs；套用後比較所有非目標 part 的 raw bytes，並對目標 part 的非目標區域做 canonical identity／結構完整性檢查。真正接上 preserveViolation，另驗證 OPC relationships、content types、必要 parts 與重新開啟能力。
• 建立隔離候選與兩階段提交。 一律先在同一檔案系統建立 candidate，所有 gate 只讀 baseline＋candidate；任何 gate 失敗都保留原檔不動。全部通過後才以原子 replace 提交，並防止 verify 與 commit 之間 baseline 被外部修改（hash／file identity 的 TOCTOU 檢查）。
• 把 Layer 2 變成正式 gate。 對宣告可型別化的 parts／slots 執行 parse → typed/trial rebuild → byte／canonical identity 比對；不在支援矩陣內的結構採 conservative raw preservation，不得以近似重建冒充完整理解。
• 把 Layer 3 抽成執行期 oracle protocol。 將 Word→PDF、page diff、geometry probe 從 test-only harness 抽成可注入 adapter；認證模式缺 Word、權限、字型或 registry evidence 時必須回傳「無法認證」，不能像測試一樣 skip 後仍宣稱成功。oracle 實作保留 macOS／Word 邊界，核心 library 只依 protocol。
• 產生 content-addressed 證書。 記錄 baseline／candidate／final hash、intent、允許變更範圍、每層證據、未支援項、Word 版本、OS、字型與 registry 版本。證書只能證明其明列的 scope／observable，不能外推成整份文件的無條件語意等價。
• 逐步收斂所有公開修改入口。 先讓 DocxWorkflowLib 提供唯一的 certified transaction API，再把 MCP save_document／finalize_document 與 CLI 串入；既有直接 writer 保留為明確標示的 low-level／uncertified API，逐步 deprecate 高階呼叫端的繞過路徑。autosave／checkpoint 要明定是復原快照還是可對外交付的 certified output，兩者不可混稱。
• 建立失敗導向測試矩陣。 包含非目標 part 單 byte 漂移、relationship／content-type 破壞、typed rebuild 不等價、Word 無法啟動、字型缺漏、render 漂移、candidate crash、commit 前 baseline 被改、未知 OOXML extension、巨集／簽章／嵌入物件等保守處理案例；並以真實文件 corpus 驗證通過證書可重現。

方案取捨：

• 只在 MCP 加 gate：較快，但 library／CLI／直接 writer 仍可繞過，無法達成 universal contract。
• 把 Word oracle 放進 OOXMLSwift.apply：表面最嚴格，但會讓 deterministic core 綁定 GUI、TCC、Word 版本與 macOS，測試與重用性都會惡化。
• 分層認證協調器（推薦）：底層負責可證明的結構保真，高層負責候選、oracle、政策、證書與原子提交；各入口共享同一條認證路徑，同時誠實保留能力邊界。

Conflict Class

C_shared_module_coord

實作會同時修改主 repo 的 packages/ooxml-swift／packages/docx-workflow-swift，並協調共享 submodule mcp/che-word-mcp 的 save/finalize 邊界與 submodule pointer；不能把這些變更當成互不相干的平行編輯。

Complexity

Spectra

• Layer 2：會新增供 future callers 使用的公開 Swift transaction／certificate／oracle protocol，並改變 MCP／CLI 對「修改成功」與「認證成功」的工具契約。
• Layer 3：會修改多份既有 normative specs，且「純 OOXML 核心 vs. workflow 認證協調器 vs. Word oracle adapter」是具有長期維護影響的架構決策。
• Hard-gate: triggered — 同一認證概念預估散佈於 WordDocument+Apply.swift、Manifest.swift、Executor.swift、Verifier.swift、視覺／render harness、MCP Server.swift 與至少六份 specs；WordDocument.apply、DocxWriter、Verifier 都是被多個呼叫端共用的抽象。

→ 建議 pre-implementation staging：superpowers:brainstorming（非必要）；正式下一步仍依 Spectra routing 由使用者選擇 discuss 或 propose。

Risks

• 過度宣稱：未區分「未改區域 byte-exact」與「預期改動在人類視覺／語意上正確」，會讓證書看似比實際證據更強。
• oracle 不穩定：Word 版本、OS、字型、印表機／版面設定、TCC 權限都可能影響 render；環境必須進入證書，失敗必須 fail closed。
• 效能與互動成本：每次修改都開 Word／輸出 PDF 會很慢；需以 policy／effect registry 決定何時要求哪種證據，但不可讓效能捷徑變成靜默略過。
• TOCTOU 與耐久性：驗證後到 replace 前原檔可能被 Word 或其他程序改動；候選與提交需綁 hash／identity，並保留目前的備份與復原能力。
• 相容性：未知 extension、數位簽章、巨集、嵌入物件與受保護文件可能無法完整理解；正確行為應是原樣保留或拒絕認證，不是近似重建。
• 導入範圍過大：若一次強制所有低階 writer 都必須有 live Word，會破壞既有 caller。應先建立 certified／uncertified 的明確邊界，再逐入口遷移並量測。

Residue

「人與 AI 能完全有相同理解」是本 issue 必須保留的產品方向，但不能被有限測試直接證明成無條件事實。可 operationalize 的版本是：人與 AI共享同一份結構化 intent、observable、證據、環境與未知項，且系統只在該明列範圍內核發證書；超出 registry 或 oracle 能力的部分必須標示未知或拒絕認證。這個 residue 不應刪掉，而應作為持續擴充 registry／oracle 的 horizon。

Vagueness Pre-check

• V1: 1 — 「要做什麼」已由 10 項 Expected 明確拆成共用認證入口、隔離候選、三層 gate、原子提交與證書，沒有多個互斥的功能詮釋。
• V4: 2 — 完成條件已明列 fail-closed、no probe no claim、未修改範圍不得漂移及證書欄位；視覺門檻與支援矩陣的數值仍需在 Spectra 階段凍結，但不妨礙 routing。
• Triggered: no — both axes ≤ 3

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

(none surfaced)

Recommended Agent: claude-opus-4.7

Confidence: 0.5
Data source: static_heuristic（cold start，無歷史樣本）
Reasoning: 靜態評分為 Codex 2、Claude family 10。#137 雖有明確驗收條件，但同時涉及公開 API、跨 repo／submodule 協調、設計取捨、相容性與變更紀錄，因此偏向需要全域範圍掌握的 agent。

Compare:

Agent	N	Status
codex-xhigh	0	insufficient_data
claude-opus-4.7	0	insufficient_data
claude-sonnet-4.6	0	insufficient_data
claude-haiku-4.5	0	insufficient_data

[kiki830621]

📊 For Reviewer / Collaborator

現在：已確認三層能力分散存在，但尚未形成所有正式修改都不可略過的認證交易；diagnosis 已獲確認，下一站為 Spectra 討論。
Blocking：無
你該做什麼：啟動 spectra-discuss，先收斂 certified／uncertified 邊界、Word oracle 強制程度與分階段導入順序。

last-updated by idd-diagnose at diagnosed transition, 2026-07-17