bug: insert_image_from_path append 模式不寫 <w:drawing> — 圖片靜默遺失，三個驗證管道都測不到

[kiki830621]

Problem

insert_image_from_path 在 append 模式（不帶任何 anchor）只建立 relationship 與 word/media/ 二進位檔，不把 <w:drawing> 寫進 body。save_document 照當下的 body 序列化，於是那張圖在輸出檔裡根本不存在——但關係與媒體檔都在，所以檔案帶著一份永遠不會顯示的酬載。

被積壓的 append 圖片會在之後某個會重建 body 的操作（帶 anchor 的插入、insert_equation…）發生時一起 materialize。也就是說：一張 append 的圖能不能存活，取決於你之後碰巧做了什麼。

最自然的用法——「把圖附在最後然後存檔」——必然遺失最後那張。

最小重現（che-word-mcp 4.0.7）

base.docx = macdoc convert 產的 3 段落文件（drawing=0）

#	操作序列	存檔後 <w:drawing>	rels image	判讀
1	insert_image ×2（append）→ save	0	2	兩張全遺失
2	接著 insert_paragraph（append）→ save	0	2	文字有寫入，圖仍遺失
3	再 save 到新路徑	0	2	與存檔路徑無關
4	insert_image（帶 after_text）→ save	3	3	積壓的 2 張一起 materialize
5	insert_image（append）+ insert_equation（append）→ save	4	4	insert_equation 也會 flush
6	insert_image（append）→ 立刻 save	4	5	最後一張遺失，rels/media 與 body 不一致

第 6 列是本 issue 的核心：rels=5 / media=5 但 body=4。

Type

bug

Expected

insert_image_from_path 回報成功後，save_document 寫出的檔案裡該圖片應有對應的 <w:drawing>；rels / media / body drawing 三者數量一致。

Actual

append 模式插入的圖片在 body 缺席，除非之後恰好有其他操作重建 body。輸出檔的 rels 與 media 數量大於 body 的 <w:drawing> 數量。

Impact

這個失敗是靜默的，而且三個看起來像驗證的管道都偵測不到：

1. insert_image_from_path 的回傳值 —— 回報 Inserted image 'x.png' with id 'rIdN'，成功
2. list_images —— 回報全部圖片都在（它列的是 relationship／media，不是 body 引用）
3. save_document —— 回報成功

唯一抓得到的方法是打開輸出檔數 document.xml 的 <w:drawing>。

實際踩到的情境：用 MCP 組一份要交出去的 Word 文件，插 7 張圖，全部回報成功，list_images 回報 7 張。轉成 PDF 目視才發現其中 4 張根本沒出現。若沒有目視那一步，交出去的就是一份少了 4 張圖的檔案。

建議

• 修正 append 路徑，讓 <w:drawing> 在插入當下就進 body（與 anchored 路徑一致）
• 若短期難修，至少讓 save_document 在序列化後比對 rels／media／body drawing 三者數量，不一致就 報錯而非回報成功
• list_images 應區分「有 relationship」與「body 有引用」，或直接以 body drawing 為準

環境

• che-word-mcp 4.0.7
• macOS 27.0

---

Current Status

Phase: planning
Last updated: 2026-09-01 by idd-implement (Stage 1)

Key Decisions

• Root cause：ooxml-swift appendParagraph op 快路徑的 payload 投影無 drawing 詞彙（RunPayload OpLog/Operation.swift:366），磁碟開啟文件的 append 圖片段落 <w:drawing> 被靜默丟棄；typed view 保有 → 後續 typed-dirty 操作才 materialize
• Complexity = Plan（硬閘：shared abstraction appendParagraph；risk-sensitive data-loss + 跨 repo 釋出鏈）；Conflict Class = C_shared_module_coord
• Fix 方向：白名單「payload 可表示」才走快路徑，否則 fallback typed-dirty；defense-in-depth save 計數一致性檢查

Scope Changes

• list_images 語意旁支 → PsychQuant/che-word-mcp（sister issue，見 diagnosis comment）

Blocking

• 等待 Fix append-mode insertImage silently dropping <w:drawing> on save ooxml-swift#128 review/merge（Stage 1 fix PR）——merge 後接 3.6.0 tag → Stage 2/3

Commits

• ooxml-swift branch fix/175-append-image-payload-loss（PR spec 整合：operation taxonomy 收斂到 ooxml-operation-log 單一 home，命名與官方 OOXML（ECMA-376）對齊 #128）

[kiki830621]

Diagnosis

Type

bug（data-loss family——與 #142 tblPr 清空、#109 同族：「投影/重建時丟掉表示不了的內容」）

Root Cause

**appendParagraph 的 op-emission 快路徑把段落投影成 payload，而 payload 的詞彙表沒有 drawing——<w:drawing> 在投影中被靜默丟棄。**證據鏈（ooxml-swift，行號對 v3.5.0 abf8a52；che-word-mcp 4.0.7 pin v3.4.0 同構）：

1. che-word-mcp handler：append 模式（無 anchor）分派到 doc.insertImage(at: nil)（Server.swift:8408-8556）
2. Document.insertImage(path:at:nil) 建 Run.withDrawing(drawing) 段落後呼叫 appendParagraph(para)（Document.swift:1565-1605）
3. appendParagraph（Document.swift:372）在 xmlTrees["word/document.xml"] != nil（任何從磁碟開啟的文件）時走 tree-backed op 快路徑：把段落投影成 ParagraphPayload + RunPayload 再 appendAndMaterialize(ops)
4. RunPayload（OpLog/Operation.swift:366-386）只有 text/bold/italic/color/fonts/size/underline/vertAlign——沒有 drawing 欄位。含 Drawing 的 run 投影成空文字 run，<w:drawing> 從未到達 XML tree
5. typed view（body.children.append(.paragraph(stamped))）保有 drawing；rels/media/[Content_Types] 各自 markTypedDirty 照寫 → rels=N+1 / media=N+1 / body=N（重現表第 6 列的簽名）
6. 之後任何呼叫 markTypedDirty("word/document.xml") 的操作（anchored insert、insert_equation…）把 document.xml 的序列化切回 typed body → 積壓圖片一起 materialize（重現表第 4-5 列）；純文字 append 存活（第 2 列）因為 text 在 payload 詞彙內

歷史脈絡：這條快路徑由 #96 引入；#104 已修過同一分支的姊妹 bug（resync 覆蓋鄰居），其註解明言「An append knows exactly what it changed」——投影 lossiness 是同分支殘留的下一個缺口。

Impact

• 影響檔案：packages/ooxml-swift/Sources/OOXMLSwift/Models/Document.swift（appendParagraph 快路徑）；釋出鏈 ooxml-swift → che-word-mcp（4.0.8）→ macdoc submodule/pin
• 影響面：任何磁碟開啟文件 + append 含 payload 表示不了內容的段落——drawings 已證實；同構風險及於 RunPayload 詞彙外的一切 run 內容
• 使用者流程：MCP 組文件插圖交付——最自然的「插圖→存檔」必然遺失，且三個回報管道全部說成功

Strategy

• RED（ooxml-swift）：磁碟開啟 fixture → insertImage(at: nil) → save → assert document.xml 含 <w:drawing> 且 rels/media/body 三計數一致（現行必紅）
• Fix A（正解，最小而完整）：appendParagraph 快路徑加「payload 可表示性」檢查——run 含 drawing（或任何 RunPayload 詞彙外內容）→ fallback 到 typed-dirty 路徑（body.children.append + markTypedDirty），不發 lossy ops。快路徑對可表示段落照走
• Defense-in-depth（issue 建議 2）：save 序列化後比對 rels/media/body drawing 計數，不一致 → 報錯而非成功（落點 ooxml-swift save 或 che-word-mcp save_document，implement 時定）
• 釋出鏈：ooxml-swift patch release → che-word-mcp bump + 重現矩陣 6 列轉 regression tests → macdoc pin
• （選項 B 記錄不做：擴充 op 詞彙納 drawing——op-schema 大改，留給未來需要 op-log 完整重放 drawing 時）

Conflict Class

C_shared_module_coord — 共享 submodule/套件鏈（ooxml-swift ← che-word-mcp ← macdoc），appendParagraph 為 25+ 消費者共用抽象。

Complexity

Plan

硬閘命中：動到 shared abstraction（appendParagraph 跨 repo ≥2 消費者引用）；Layer P 亦中（risk-sensitive data-loss 路徑 + 跨 repo 釋出順序依賴）。

Risks

• Fallback 判準若列舉不全（漏某種 payload 外內容）→ 同 bug 換內容重演——判準應為「白名單可表示才走快路徑」，不是「黑名單 drawing 才 fallback」
• typed-dirty fallback 會令整個 document.xml 改走 typed 序列化——對 raw-channel 文件的 byte 影響需 regression 覆蓋（Word-canonical forms 對齊 — 讓真實 Word 文件升級 DSL channel（format-alignment step 2） #131 詞彙已 typed 化，預期可控）
• che-word-mcp 4.0.7 已出貨——修復前使用者無 workaround 提示（暫時 workaround：append 後任意帶 anchor 操作可 flush，但不可依賴）

Residue

使用者已交付的「少 4 張圖」文件無法由本修復回溯補救——只能修未來。「為何三個驗證管道都看不到 body」的設計反思超出本 bug scope，由 defense-in-depth 項部分回應。

Vagueness Pre-check

• V1: 1 — 6 列重現矩陣 + 精確操作序列，要修什麼無歧義
• V4: 1 — Expected 明定三計數一致的驗收
• Triggered: no

Hard-gate: triggered — shared abstraction appendParagraph（ooxml-swift，跨 word-builder/che-word-mcp/macdoc 消費）→ 強制 Plan（見 Complexity）。

Sister Concerns Filed (mid-diagnose)

• list_images 只列 relationship 層，看不見 body 引用——孤兒圖片被誤報為存在（sister concern from macdoc#175） che-word-mcp#199 — list_images relationship vs body 引用語意（驗證管道側旁支，root-cause 修復不涵蓋）
• 未另立：「RunPayload 詞彙外內容的同構風險」——屬 Fix A 白名單判準的 in-scope 範圍；「save 計數一致性」——已列 Strategy defense-in-depth 項

[kiki830621]

Implementation Plan (Plan tier)

修復 locus 在 ooxml-swift（packages/ooxml-swift，own repo）；本 issue（macdoc）追蹤端到端，釋出鏈三段。

Files & Changes

Stage 1 — ooxml-swift（fix 本體）

• Sources/OOXMLSwift/Models/Document.swift — appendParagraph（:372）快路徑前加白名單可表示性判準 isOpPayloadRepresentable(paragraph)：段落所有 runs 皆為「純文字 + RunPayload 既有屬性（bold/italic/color/fonts/size/underline/vertAlign）」且無 drawing／其他非文字內容 → 才走 op-emission；否則 fallback body.children.append(stamped) + markTypedDirty("word/document.xml")（既有慢路徑，行為已正確）
• 同檔 insertImage(base64:) / insertImage(path:)（:1525/:1565）— 不改（呼叫 appendParagraph 自動獲得 fallback）；加註解指向判準
• Sources/OOXMLSwift/Models/Document.swift（或新檔）— defense-in-depth API imageConsistencyReport()：回報 rels image 數 / media 數 / body <w:drawing> 數三元組，供上層 save 前驗證
• Tests/OOXMLSwiftTests/Issue175AppendImageTests.swift（新）— RED→GREEN + no-regress（見 Test Plan）

Stage 2 — che-word-mcp（enforcement + regression）

• Package.swift pin bump 至含 fix 的 ooxml-swift release
• Server.swift saveDocument — 序列化後呼叫 imageConsistencyReport()，三計數不一致 → 回報錯誤（不再靜默成功；issue 建議 2）
• Tests/ — 把 issue 重現矩陣第 1、2、6 列轉 regression tests（append×2→save、append+text→save、append→立即 save）
• 版本 4.0.8，簽章公證釋出（make release-signed pipeline）

Stage 3 — macdoc（收尾）

• mcp/che-word-mcp submodule pin bump + marketplace binary_version 同步（common-release-flow）

Family-wide scope（shared-abstraction 硬閘產出）

Document.appendParagraph 全部已知 call sites，逐一裁定：

Call site	內容形狀	受影響
Document.insertImage(base64:)	drawing run	✅ 修復目標
Document.insertImage(path:)	drawing run	✅ 修復目標
che-word-mcp insert_paragraph（Server.swift:7211，append 模式）	文字（可含格式屬性）	白名單內，走 op path 不變——測試鎖行為
OpLog 機構（OperationReducer/JSONL）	op 的消費端非生產端	不改

判準寫成白名單（正面枚舉可表示），不是黑名單 drawing——RunPayload 詞彙未來若擴充，判準同步收斂於單一函式。

Sequencing & Dependencies

Stage 1 → 2 → 3 嚴格順序（release chain）。Stage 1 內：RED 測試先行 → 白名單 fallback → GREEN → consistency API → FormatAlignmentAcceptanceTests 全綠確認 raw-channel 無退化 → tag release（3.6.0，additive API）。

Decision Points

1. 白名單 vs 黑名單：白名單（diagnosis Risks 定調——黑名單漏枚舉會讓同 bug 換內容重演）
2. consistency check 落點：兩層——ooxml-swift 出 API（可測、可重用）、che-word-mcp save_document enforce（tool 面回報）。單放 MCP 會讓 CLI 路徑裸奔；單放 library 內硬錯會破壞既有合法中間態（rels 先行本就是 insert 流程暫態）
3. ooxml-swift 版本：3.6.0（新增 public API）；不動 op schema（選項 B 明文不做）
4. fallback 的序列化影響：typed-dirty 令整個 document.xml 走 typed 序列化——僅發生在「本來就要新增 drawing」的存檔，可接受；raw-channel 文件的 append-image 場景以 acceptance tests 驗 Stage B 恆綠

Risks & Mitigations

Risk	Mitigation
白名單誤窄（可表示卻 fallback）	後果只是損 op-log 粒度、行為仍正確；用「純文字段落仍走 op path」的斷言鎖住不退化
白名單誤寬（漏枚舉非文字內容）	判準以 Run model 欄位正面枚舉實作 + code comment 要求新欄位同步；Run 增欄位時編譯器可見（若用 exhaustive 檢查形式）
raw-channel byte 退化	FormatAlignmentAcceptanceTests 全跑 + Stage B byte-equal 恆綠為 gate
3-repo 釋出鏈中斷	每 stage 獨立 verify；che-word-mcp 走既有 signed release pipeline；marketplace sync per common-release-flow
save-check 誤傷合法暫態	check 只在 save_document 序列化後跑（非 insert 當下）；錯誤訊息附三計數與孤兒 rIds

Test Plan

ooxml-swift（Issue175AppendImageTests）

1. RED：磁碟載入 fixture → insertImage(at:nil) → save → document.xml 含 <w:drawing> 且三計數一致（現行紅：body 少 1）
2. 連插兩張 → save（矩陣列 1）；插圖+插文字段 → save（列 2）；插圖→立即 save（列 6）
3. No-regress：純文字 appendParagraph 仍走 op path（斷言 oplog 有 appendParagraph op）；anchored insertImage(after_text) 行為不變
4. FormatAlignmentAcceptanceTests 全綠（raw floor）

che-word-mcp
5. save_document 對「人工製造的孤兒 rels」fixture 回報錯誤（defense-in-depth 生效）
6. 矩陣列 1/2/6 的 MCP 層 regression（工具序列重現）

Out-of-scope（明文不做）

• list_images 語意區分 —— sister issue list_images 只列 relationship 層，看不見 body 引用——孤兒圖片被誤報為存在（sister concern from macdoc#175） che-word-mcp#199
• op 詞彙擴充 drawing（重放完整性）—— 記錄於 diagnosis Decision B，待真需求
• bug: insert_image_from_path append 模式不寫 <w:drawing> — 圖片靜默遺失，三個驗證管道都測不到 #175 報告中已交付文件的回溯補救（殘留損害已發生）
• headers/footers 路徑的同構檢查（無證據顯示同 bug；不擴 scope）

Tangential Observations (filed mid-plan)

• Package.resolved 的 mlx-swift pin 本機反覆漂移（0.31.6→0.31.4）——連續阻擋 git 操作 #182 — Package.resolved mlx-swift pin 本機漂移（本批次四度阻擋 git 操作）
• 已關 issue 的 stale worktrees（idd-136/139/144/148）直接 GC 清除（一次性 housekeeping，不立案）
• （無其他 orphan：#199 sister 已於 diagnose 立案）

[kiki830621]

Implementation Progress — Stage 1 complete（ooxml-swift fix 本體）

PR: PsychQuant/ooxml-swift#128（branch fix/175-append-image-payload-loss，待 review/merge）

Plan Stage 1 四項全落地：

• isOpPayloadRepresentable 正面白名單 gate 快路徑（Paragraph 11 內容欄位 + 7 未投影 pPr + Run 6 內容欄位 + 9 未投影 rPr 全枚舉）；不可表示 → fallback 既有 typed-dirty 慢路徑
• insertImage(base64:/path:) 經 appendParagraph 自動獲得 fallback（未改）
• PackageInspector.imageConsistencyReport(of:) defense-in-depth API（孤兒 image rel 偵測，掃全 word/*.xml 引用避免 header 圖誤報）
• Issue175AppendImageTests 7/7：矩陣列 1/2/6 RED→GREEN、純文字 op-path no-regress（oplog 斷言）、anchored 路徑 no-regress、inspector 正反例

驗證：full suite passed（0 failures）；FormatAlignmentAcceptanceTests 綠（raw-channel Stage B floor 不受影響）。

RED 過程的一個誠實記錄：矩陣列 1 的初版測試用同一來源 PNG 插兩次，暴露出「同名 media 檔互相覆蓋」的另一個現象（rels=2/media=1）——與 #175 無關，測試改用兩個不同來源檔隔離；該現象未立案（單一觀察，尚無實害證據）。

待辦（release chain）：

• Stage 2：ooxml-swift#128 merge → tag 3.6.0 → che-word-mcp pin bump + save_document enforce + 矩陣 regression → 4.0.8 signed release
• Stage 3：macdoc submodule pin + marketplace sync → /idd-verify #175