第三方 Word 文件零 w14:paraId 時 swiftify 無可用產出，且沒有補救路徑（DSL 與 slot 同時失效）

[kiki830621]

Problem

拿一份真實 Microsoft Office Word 產生的 .docx（docProps/app.xml 的 Application = Microsoft Office Word、AppVersion = 14.0000，即 Word 2010）跑 swiftify，得到：

$ macdoc word reverse Assignment.docx --to-mdocx Assignment.mdocx.swift --coverage
word/document.xml                 raw  24932 B   DSL 0.0%
--- Aggregate: 0.0% DSL (0 / 93316 XML bytes across 14 parts) ---

這份文件零表格、25 個段落——按 SKILL.md 的說明應該是 DSL 升級最理想的輸入。實際落 raw，原因是：

w14:paraId 數量: 0
表格 <w:tbl> 數量: 0
段落 <w:p> 數量: 25

w14:paraId 一個都沒有。

byte-equal 重播驗證通過，所以工具本身沒壞。問題是產物的價值：22 行 / 105 KB，全部是 escape 過的單行 XML，不可讀、無 diff 價值，而且因為零 paraId，slot 也用不了（raw channel 的 slot 靠 paraId 定位）。

也就是說，對這一整類文件，swiftify 能給的只有「一份通過驗證但無法閱讀、無法填答、相對於原 .docx 沒有增加任何可回復資訊的封存腳本」。

Type

bug

Expected

需要先裁定一件事：「無 w14:paraId 的第三方 Word 文件」是不是一個要支援的輸入類別？

如果是，缺的是一條補救路徑，例如：

• macdoc word normalize --add-para-ids <in.docx> —— 為缺 paraId 的段落補上，讓文件取得 DSL 升級與 slot 的資格
• 或至少在 --coverage 輸出裡明講「本文件零 paraId，slot 不可用；補救方式是 X」

如果不是，該在 SKILL.md 把「哪些文件用 swiftify 只會得到不可讀封存」講得比現在更前面——目前 SKILL.md 說 raw 的兩個常見原因是「含任一表格」與「段落沒有 paraId（legacy 文件、部分工具產出）」，而**「Word 2010 產物」不會被讀成 legacy**。

Actual

• 無任何補救指令
• --coverage 只報 DSL 0.0%，不說明「因為零 paraId」也不說明「slot 因此不可用」
• 使用者要自己 unzip -p ... | grep w14:paraId 才知道原因

Impact

w14:paraId 缺席不是冷僻邊緣案例——它就是這個 Word 版本的產物長相，而學術界、行政單位至今大量表單與講義出自該版本或其轉檔。對這些文件，SKILL.md 承諾的兩個能力（可讀 DSL、slot 定點填寫）都拿不到，而使用者要跑完整條 reverse 才知道。

與既有 issue 的區別

• #160 講的是 macdoc 自產的 docx 不帶 paraId（狀態顯示已於 v0.7.0 前修好，現在會 stamp）。本 issue 是第三方輸入，macdoc 無法控制其產生端。
• #171（已關）為 raw channel 加了 slot 支援，但那條路徑靠 paraId 定位；零 paraId 的文件仍然拿不到 slot，而這個組合未見於文件。
• #131 是讓真實 Word 文件升級 DSL channel（format alignment）——方向相關，但本 issue 要的是更小的東西：一條讓零-paraId 文件取得 slot 資格的補救路徑，不需要完整 DSL 升級。

環境

• macdoc 0.7.0
• 輸入為 Word AppVersion 14.0000 產物（未附原檔：內含第三方作者與機構 metadata）

[kiki830621]

Errata — 本 issue 的兩個核心宣稱經實測證偽

進 diagnose 時實際跑了 --paragraphs-only（開 issue 時沒試），結果推翻我自己寫的兩點。先更正再談要修什麼。

❌ 錯誤宣稱 1：「產物不可讀」

原文說零-paraId 文件只能得到「22 行 / 105 KB 全是 escape 過的單行 XML」。加上 --paragraphs-only 就不是這樣：

$ macdoc word reverse Assignment.docx --to-mdocx po.mdocx.swift --paragraphs-only
83 行 / 2,875 B

let document = WordDocument {
    Section(id: "main") {
        Paragraph(id: "p1") { "Assignment 02" }
        Paragraph(id: "p2") { "Manipulating the Malthusian Model" }
        Paragraph(id: "p4", style: .a3) { "The Malthusian model is given by ..." }

完全可讀的 DSL。

❌ 錯誤宣稱 2：「slot 用不了」

原文說「因為零 paraId，slot 也用不了」。實測：

$ macdoc word reverse Assignment.docx --to-mdocx slot.mdocx.swift \
    --paragraphs-only --slot title=p2
已寫入: slot.mdocx.swift        # exit 0

產出的腳本：

// slots are function parameters; call-site arguments carry the content.
    title: String
        ...
            title
    title: "Manipulating the Malthusian Model"

macdoc word render 也能把它 render 回有效的 docx。swiftify 的招牌情境「以官方範本定點填寫」在這份零-paraId 文件上是可用的。

✅ 仍然成立的部分

• 這份 docx 是真的 Word 產物（AppVersion 14.0000）卻有 0 個 w14:paraId
• full-fidelity（不帶 --paragraphs-only）路徑確實落 raw、確實 0.0% DSL、確實產出 105 KB 不可讀封存
• 該路徑的 byte-equal 重播驗證確實通過
• ReverseExtractor.swift:333-335 的 guard let paraId ... else { throw Unsupported("paragraph-no-paraId", path) } 確實是 part-level 全有全無的硬門檻

---

修正後的真問題（比原標題窄，但我認為更值得修）

--coverage 對 --paragraphs-only 的產出沒有任何描述力，而 SKILL.md 把 coverage 當成「決定你對產物的期待值」的必經步驟。

實測：對同一份文件加上 --paragraphs-only 再跑 --coverage，report 仍然是 Aggregate: 0.0% DSL——即使該次執行產出的是 83 行可讀 DSL。coverage 量的是 byte-level channel（RawPartChannel.partLevelCoverage），與 --paragraphs-only 的合成路徑無關。

於是照文件走會得到錯誤結論：

1. SKILL.md：「Coverage — 判讀落在哪條 channel（不要跳過這步）… 這一步決定你對產物的期待值。」
2. 使用者跑 coverage，看到 0.0% DSL
3. SKILL.md 的 raw channel 段：「除了 call-site 的 slot 參數值外不能讀、不能手改」、「達不到人類可讀的 Swift」
4. 使用者結論：這份文件沒救 ← 錯的

SKILL.md 的決策步驟從頭到尾沒有提到 --paragraphs-only。 它出現在 macdoc word reverse --help 裡，但不在那條被標「不要跳過」的判讀流程中。

真正的 trade-off（目前沒有出現在任何決策點）

路徑	可讀 DSL	slot	byte-equal
full-fidelity（預設）	✗	需真 paraId	✓
--paragraphs-only	✓	✓（合成 id p1…）	✗

MacDoc+Word.swift:160-174 的註解本來就講清楚了代價（「content-equivalent, not byte-equal」）。缺的是讓使用者在決策點看到這個二選一。

建議（範圍已縮小）

1. --coverage 在偵測到 paragraph-no-paraId 導致降 raw 時，明講根因並指出 --paragraphs-only 這條路與它的代價
2. SKILL.md 的判讀步驟補上這個 trade-off 表
3. （較大、可分開）macdoc word normalize --add-paraids —— 讓文件取得真 paraId 以同時拿到兩者。withStampedParaId（Document.swift:356-370）＋ ParaIdGenerator.next(excluding:) 是現成可重用的零件；archived change 2026-07-18-authoring-canonical-conformance/design.md:55 明確拒絕的是 save-time 自動 backfill（無法區分 authored-new 與 parsed-without-paraId），顯式 opt-in 指令不在該拒絕範圍內（同 design.md:91）

第 3 點是設計決定，不該混進前兩點的文件／訊息修正。

[kiki830621]

Diagnosis

前提已更正：本 diagnosis 建立在上方 errata 之上，不是 issue body 的原始框架。body 宣稱的「產物不可讀」與「slot 用不了」都已實測證偽。

Type

bug（診斷訊息誤導）＋ docs

Root Cause / Analysis

根因不在 paraId 門檻本身，而在 coverage 這個指標被賦予了它承擔不起的決策角色。

三個事實疊起來造成誤判：

1. 門檻是真的、且是 part-level 全有全無。 packages/ooxml-swift/Sources/OOXMLSwift/Transcode/ReverseExtractor.swift:333-335：

   guard let paraId = paraIdValue, !paraId.isEmpty else {
       throw Unsupported("paragraph-no-paraId", path)
   }

   一個段落沒有 paraId → 整個 word/document.xml 降 raw。

2. coverage 量的是 byte-level channel，與 --paragraphs-only 的合成路徑無關。 RawPartChannel.partLevelCoverage（RawPartChannel.swift:71-85）。所以加了 --paragraphs-only、產出 83 行可讀 DSL 之後，report 仍然是 Aggregate: 0.0% DSL。

3. SKILL.md 把 coverage 當成期待值的決定者，而它的 raw channel 段接著說「除了 call-site 的 slot 參數值外不能讀、不能手改」「達不到人類可讀的 Swift」。

於是：看到 0.0% → 照 SKILL.md 讀成「沒救」→ 而實際上 --paragraphs-only 給的正是可讀 DSL 加可用 slot。--paragraphs-only 從頭到尾沒有出現在那條被標「不要跳過」的判讀流程裡。

Impact

使用者照文件走，會對一整類文件（任何零-paraId 的 Word 產物，本例是 AppVersion 14.0000）得到「swiftify 幫不上忙」的錯誤結論，而該類文件正是 swiftify 招牌情境（官方範本定點填寫）的主要對象。

代價不是抽象的：這個誤判已經發生過一次，並被寫成本 issue 的原始 body。

Strategy

• reportCoverage 在偵測到降 raw 的根因是 paragraph-no-paraId 時，於 report 末尾加一行具名提示：根因＋--paragraphs-only 這條路＋它的代價（content-equivalent, not byte-equal）

  • 根因字串已存在：ReverseExtractor 的 .raw(reason:xmlPath:)，rawReasons 已帶到 Reverse.run()

• 只在根因確實是 paragraph-no-paraId 時提示，不對 byte-mismatch / paragraph-attrs / sibling-part 等其他降 raw 原因誤報

• swiftify SKILL.md 的判讀步驟補上 trade-off 表：

  路徑	可讀 DSL	slot	byte-equal
  full-fidelity（預設）	✗	需真 paraId	✓
  --paragraphs-only	✓	✓（合成 id）	✗

• SKILL.md 現行「raw channel 的文件達不到人類可讀的 Swift」一句需修正——它在不帶 --paragraphs-only 的前提下才成立，該把前提寫出來

• 測試：WordReverseCoverageTests.swift 補一例，對零-paraId fixture 斷言 report 含該提示；並補一例對 byte-mismatch 降 raw 的 fixture 斷言不含該提示

Conflict Class

B_resource_serialize —— 與 #177 共享 Sources/MacDocCLI/MacDoc+Word.swift 的 Reverse.run() / reportCoverage。兩張應合成一個 cluster PR：#177 讓 coverage 可以單獨跑，本張讓它跑出來的話是對的——同一個「讓判讀步驟真的能判讀」的目標。

Complexity

Simple

訊息字串＋一個既有變數的條件判斷＋文件。設計決定（下方 Residue）已排除在範圍外。

Risks

風險	緩解
提示訊息對非 paraId 根因誤報	明確條件化在 paragraph-no-paraId，並補反例測試
SKILL.md 改動與 raw-channel-slot-support change 的 SKILL.md 收斂衝突	該 change 已 archive；改動點不同段（它動 raw-channel slot 段，本張動判讀步驟段）

Residue（不在本次範圍）

macdoc word normalize --add-paraids —— 讓零-paraId 文件取得真 paraId，以同時拿到可讀 DSL、slot、與 byte-equal。現成零件齊備：withStampedParaId（packages/ooxml-swift/Sources/OOXMLSwift/Models/Document.swift:356-370）＋ ParaIdGenerator.next(excluding:)。

archived change 2026-07-18-authoring-canonical-conformance/design.md:55 拒絕的是 save-time 自動 backfill（理由：無法區分 authored-new 與 parsed-without-paraId，改一段會重寫全部）——顯式 opt-in 指令不在該拒絕範圍內，同 design.md:91 說 bypass 路徑「Intentionally out of contract」。

這是設計決定不是訊息修正，混進來會讓本張從 Simple 變成 Plan/Spectra。建議另開一張。

Next Step

/issue-driven-dev:idd-implement #177 #176 --pr

[kiki830621]

Implementation Complete

PR #179（與 #177 合成 cluster）。branch idd/cluster-coverage-diagnostics，1 commit 8a782e3。

範圍以上方 errata 為準，不是 issue body 的原始框架。

Checklist

• reportCoverage 接 rawReasons；根因為 paragraph-no-paraId 時於報告末尾說出根因
• 提示同時指出 --paragraphs-only 與它的代價（content-equivalent, not byte-equal）
• 嚴格條件化——其他降 raw 原因（table / byte-mismatch / parse-error / sibling-part）不誤報
• 測試：零-paraId fixture 要出提示；有-paraId fixture 不可出提示（反例）
• [~] swiftify SKILL.md 的 trade-off 表與「達不到人類可讀的 Swift」一句 —— 未做。SKILL.md 住在 plugins/macdoc/skills/swiftify/，屬 plugin 發布物，改它要走 plugin 版本流程；與 CLI 修正的節奏不同。這是本張唯一未兌現的 Strategy 項，留待後續

驗證

反例測試是這張的重點——提示若對所有降 raw 情況都發，會把使用者送上一條幫不上忙的路：

檢查	結果
零-paraId fixture（WordDocument() 直接改 body，繞過 stamping chokepoint）	報告含 paragraph-no-paraId 與 --paragraphs-only ✓
有-paraId fixture（authoring API）	不含提示 ✓
swift test --filter WordReverseCoverageTests	6 passed / 0 failed
完整 swift test	35 tests / 0 failures

Residue（維持不在範圍內）

macdoc word normalize --add-paraids —— 讓文件取得真 paraId 以同時拿到可讀 DSL、slot 與 byte-equal。零件齊備（withStampedParaId + ParaIdGenerator），但那是設計決定不是訊息修正，該另開一張。

[kiki830621]

Closing Summary

Problem

這張 issue 我自己開錯了，修的是更正後的問題。

原始 body 宣稱：零 w14:paraId 的第三方 Word 文件在 swiftify 下「產物不可讀」且「slot 用不了」。進 diagnose 時實跑 --paragraphs-only（開 issue 時沒試），兩個宣稱都被推翻（errata）：同一份檔案產出 83 行可讀 DSL，--slot title=p2 也正常運作並能 render 回有效 docx。

更正後的真問題比原標題窄：--coverage 報的 0.0% DSL 對這類文件是誤導，而 SKILL.md 把那個數字當成期待值的決定者。

Root Cause

三件事疊起來：

1. ReverseExtractor.swift:333-335 的 guard let paraId ... else { throw Unsupported("paragraph-no-paraId", path) } 是 part-level 全有全無——一個段落缺 id，整個 word/document.xml 降 raw。這部分本來就對。
2. RawPartChannel.partLevelCoverage 量的是 byte-level channel，對 --paragraphs-only 的合成路徑零描述力。加了該 flag、產出 83 行可讀 DSL 之後，report 仍是 Aggregate: 0.0% DSL。
3. SKILL.md 的判讀流程從頭到尾沒提過 --paragraphs-only，而其 raw channel 段接著說「不能讀、不能手改」「達不到人類可讀的 Swift」。

於是：看到 0.0% → 照文件讀成「沒救」→ 開出一張前提錯誤的 issue。這個誤判實際發生過一次，就是本張的原始 body。

Solution

reportCoverage 接收 rawReasons；當 word/document.xml 降 raw 的根因是 paragraph-no-paraId 時，於報告末尾說出根因，並指出 --paragraphs-only 這條路與它的代價（content-equivalent，不再 byte-equal）。

嚴格條件化在這一個根因。 其他降 raw 的原因（table / byte-mismatch / parse-error / sibling-part）沒有這條替代路徑，對它們發同一段話會把使用者送上一條幫不上忙的路。

Verification

反例是這張的重點：

檢查	結果
零-paraId fixture（WordDocument() 直接改 body，繞過 stamping chokepoint）	報告含 paragraph-no-paraId 與 --paragraphs-only ✓
有-paraId fixture（authoring API）	不含提示 ✓（守著誤報）
swift test --filter WordReverseCoverageTests	6 passed / 0 failed
完整 swift test	35 tests / 0 failures

Changes

• PR #179（cluster with #177）
• squash 至 main：41237e4

未兌現的 Strategy 項與 Residue

• 未做：swiftify SKILL.md 的 trade-off 表，以及「達不到人類可讀的 Swift」一句的前提補正。SKILL.md 住在 plugins/macdoc/skills/swiftify/，屬 plugin 發布物，改它要走 plugin 版本流程。這是本張唯一未兌現的 Strategy 項——CLI 端已會說出替代路徑，但文件端仍會把讀者導向錯誤結論。
• Residue（未開新案）：macdoc word normalize --add-paraids——讓文件取得真 paraId 以同時拿到可讀 DSL、slot 與 byte-equal。零件齊備（withStampedParaId + ParaIdGenerator）；archived change 2026-07-18-authoring-canonical-conformance/design.md:55 拒絕的是 save-time 自動 backfill，顯式 opt-in 指令不在該拒絕範圍內。那是設計決定，不是訊息修正。