docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op)

[kiki830621]

Problem

Original text:
「幫我放進macdoc」
— Source: 使用者(2026-07-17,VBA 注入 no-op 之謎破案後)

zip 注入 vbaProject.bin 到 openpyxl 產的 xlsx 時,document-module 綁定缺失會讓 VBA 專案「看似正常、執行全滅」——巨集清單看得到、run VB macro 回成功,但沒有任何巨集真的執行。這個 gotcha 在網路上的 xlsm 注入教程幾乎沒人提,實戰花了一整個下午才破案,必須沉澱。

Type

docs

根因

vbaProject.bin 的 PROJECT stream(明文,MBCS 編碼)宣告 document modules:

Document=ThisWorkbook/&H00000000
Document=<carrier 的 sheet codeName>/&H00000000

綁定鍵在宿主端 XML:

bin 宣告	宿主綁定鍵	缺失時的後果
Document=ThisWorkbook	xl/workbook.xml 的 <workbookPr codeName="ThisWorkbook"/>	致命:ThisWorkbook 物件無法解析 → 任何巨集一觸碰它就拋 429「ActiveX 元件無法產生物件」
Document=<sheet>	各 xl/worksheets/sheetN.xml 的 <sheetPr codeName="..."/>	次要:配對未定義(懸空 module 通常無害)

openpyxl / LibreOffice 產的檔都不寫 codeName → 注入的 VBA 天生殘廢。

三個惡性疊加(為什麼難診斷)

1. 429 被巨集自己的 On Error handler 吃掉 → 錯誤 MsgBox 一閃而過或被忽略,表面「執行完成」
2. Mac Excel AppleScript run VB macro 對解析失敗靜默回 exit 0(對不存在的巨集名也一樣!);詭異的是帶 module 限定名(Module.Sub)反而能觸發真執行並暴露錯誤
3. 輸出恰好等於預期值時,no-op 與成功不可區分——靜態預填值本來就正確,巨集沒跑也「全對」

修法(注入器一併縫,純檔案層)

# xl/workbook.xml
<workbookPr/> → <workbookPr codeName="ThisWorkbook"/>
# xl/worksheets/sheetN.xml(每張)
<sheetPr .../> → <sheetPr codeName="工作表N" .../>

注意 <sheetPr> 可能帶既有屬性或不存在——regex 要處理三種形態,且絕不能產生重複的 sheetPr 元素(schema 違規 → Excel 靜默拒開,又是一個無聲失敗)。

驗收方法論(本案最大教訓)

驗收必須要求可觀察的狀態改變,不能只驗「結果正確」:

改輸入(利率 1.75% → 3%)→ 跑巨集 → 輸出必須改變(且與獨立實作的理論值一致)
→ 改回 → 輸出必須復原

實測修復後:42,112 格中恰好 310 格如 Python 引擎理論預測地改變——雙實作逐格吻合才算驗證完成。「跑了沒報錯 + 結果正確」在這個 bug class 面前毫無鑑別力。

Expected

• 這份知識進 macdoc docs(可併入 docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136 規劃的 docs/opc-zip-surgery.md 作為核心章節,或獨立成篇)
• che-excel-mcp(feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135)的 inject_vba 工具把 codeName 縫合做成內建步驟 + 把「狀態改變驗收」做成 verify_macro_alive 類工具

Impact

• 沒有這頁,任何人(包括未來的 AI session)做 xlsm 注入都會掉進同一個「看似成功實為全滅」的洞,且平均要數小時才爬得出來
• xlsm 的失敗模式可作為 docm/pptm 的研究假說；各格式的 host model、relationship、content type 與真實 fixture 必須另案驗證，不能由本案直接宣稱適用

Refs #135, #136

Priority

P2

---

Current Status

Phase: verified
Last updated: 2026-08-13 by idd-verify

Delivered

• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 已成為 docs/opc-zip-surgery.md 的 document-module binding 與 macro-alive 核心章節。
• 文件明確區分 carrier inventory 與本次 target binding，並要求 workbook／project／module-qualified invocation、execution witness 與獨立 oracle。

Evidence qualification

• 42,112／310 是歷史實戰證據；fixture、oracle 與命令尚未進 repo，因此沒有冒充可重現測試。
• 實際 inject_vba 與 verify_macro_alive 仍由 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 實作。

Blocking

• (none)

Commits

• authoritative：554b8a895d6d1faeaec3c66688c10263dd39649a

Verify

• PASS：0 blocking findings
• Report：docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 (comment)

Platform capability status

• 離線格式層：platform:cross；狀態為 design-only；已驗證的是 xlsm 文件契約，實際 inject_vba 仍由 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 承接。
• 活 Excel 驗收層：platform:macos；狀態為 design-only；42,112／310 是不可在 repository 重現的歷史證據，當時的 macOS／Excel 精確版本未記錄。
• Windows／Linux 活應用程式層：Excel 自動化；狀態為 not-verified，Mac Excel AppleScript 的 silent no-op 不得外推。
• 狀態命名空間：上方 Phase: verified 僅代表 docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 文件交付通過 IDD verify，不代表 runtime 或 live Excel 能力已驗證。

[kiki830621]

Diagnosis

Evidence

• repo 目前只有 docs/applescript-swift-parity.md 記錄活 Excel bridge 的型別化入口，沒有 OPC／VBA 注入設計文件。
• docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136 的基礎「三處差異」只描述 content type、workbook relationship 與 xl/vbaProject.bin；後續實戰已證明，從一般 .xlsx 注入帶 document modules 的 carrier 時，還必須依 manifest 補齊 workbookPr/@codeName 與工作表 sheetPr/@codeName。
• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 是這個缺口的完整失敗模式：巨集可列出、AppleScript 可回成功，但 ThisWorkbook 無法解析，錯誤又可能被 VBA handler 吃掉，形成靜默 no-op。
• 因此「永遠恰好三處」與「整個 ZIP 檔 byte-identical」都太強；正確契約應區分固定 package delta、依 carrier／宿主決定的綁定 delta，以及未觸碰 entry 的 payload byte equality。

Scope

• 新增 docs/opc-zip-surgery.md，同時完成 docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136 與 docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 的文件要求。
• 文件涵蓋：OPC delta、vbaProject.bin provenance、document-module 綁定、byte-level 驗收、狀態改變驗收、惡意輸入／巨集授權／原子儲存／平台邊界。
• 不在本 PR 實作 inject_vba、不新增 converter route，也不執行或封裝未受信任巨集；實作仍由 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 承接。

Acceptance contract

1. 固定三項 package delta 與條件式 codeName delta 分開列示，不再誤稱所有輸入都只改三處。
2. 明確定義 allowed touched parts、未觸碰 entry payload byte equality、XML reverse-patch equality、VBA asset hash equality。
3. vbaProject.bin 必須有來源、雜湊、對應 .bas 版本與 module binding manifest；注入與執行是分離的明示操作。
4. 驗收必須擾動輸入、執行 module-qualified macro、觀察輸出改變並與獨立 oracle 對照，再復原輸入；「沒報錯」或「結果本來就對」不算通過。
5. hostile OPC、受保護／簽章封裝、stale save 與真 Excel 平台限制皆 fail-loud。

Sister disposition

• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 直接吸收到同一文件與 PR，不另建重複文章。
• feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 保留為產品實作；docs: 平台標示慣例 — docs 與 issues 需明示適用平台(macOS/Windows/Linux/跨平台)與實測範圍 #139 保留為 repo-wide 平台標示規範。本文件只套用並引用其邊界。

[kiki830621]

📊 For Reviewer / Collaborator

現在：#138 已由 #136 文件完整吸收並通過 verify；共同 PR 為 #152。
Blocking：無。
你該做什麼：review https://github.com/PsychQuant/macdoc/pull/152；merge 後再由人工完成 closing summary。

last-updated by idd-all at PR transition, 2026-08-13

[kiki830621]

Implementation complete

Commit: 33cca152fd2afbbb3bbbe98d6c27c3548a8373fc

新增 docs/opc-zip-surgery.md（247 行），內容包括：

• 固定三項 .xlsx → .xlsm package delta，以及依 carrier manifest 決定的 codeName 綁定 delta；
• vbaProject.bin 的文字來源、Excel carrier、digest 與 binding manifest 供應鏈；
• entry 集合、未觸碰 payload byte equality、XML reverse-patch 與 binary hash 驗收；
• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 的 document-module 429／靜默 no-op 失敗鏈，以及擾動輸入後必須觀察狀態改變的 macro-alive 測試；
• hostile OPC、巨集明示授權、same-filesystem staging、generation check、atomic replace、受保護封裝與 macOS + Excel for Mac 平台限制；
• feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 inject_vba 的 typed implementation handoff checklist。

靜態驗證：

• git diff --check origin/main..HEAD：PASS
• required content type／relationship／binding／atomic-save tokens：PASS
• auto-close phrase scan：PASS
• worktree：clean

這是 docs-only 變更，沒有執行 Swift runtime tests。下一步進行多面向 IDD verify；issue 保持 open。

Refs #136
Refs #138

[kiki830621]

Verify: #136 + #138

Engine

Manual fan-out：Requirements、Logic/Evidence、Security/Privacy/Data Integrity；修正完成後再序列化 Devil’s Advocate。Codex gpt-5.6-sol xhigh 跨模型通道另行嘗試兩次。

Aggregate

PASS — 0 blocking findings。非阻擋後續均已放進 #135 implementation handoff 或 reviewer note，不改變本次文件交付 verdict。

Codex HTTP 通道第一次回服務錯誤，第二次在 600 秒上限逾時，均未產出內容；故列為 INFO process gap，不把空白輸出計為 PASS。其餘四個 lens 都有非空、可稽核報告。

要求覆蓋率

• docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136 Expected／草稿大綱／後續 acceptance：FULLY
• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 Expected／根因／修法／狀態改變 acceptance：FULLY
• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 已吸收到同一份 docs/opc-zip-surgery.md，避免兩份設計漂移

Findings（合併後）

Round	Severity	Finding	Disposition
R1	P1	目的世代、relationship confinement、raw XML／VBA 隱私；OPC path／content type、inventory／target binding、macro invocation 時序	Closed in ca89009
R2	P1	codeName equality／uniqueness、procedure attestation、destination check→rename TOCTOU、macro formula false-positive	Closed in a8901e7
R3–R4	P1	ancestor symlink 與 descriptor-anchored commit 的實際 Darwin 語意	Closed in 11e6ab0
DA	P1	已驗證 staging leaf 可在 rename 前被普通檔取代	Closed in 554b8a8
Final	—	Requirements、Logic/DA、Security/Privacy/Data Integrity	PASS
Final	INFO	Codex HTTP 通道沒有產出	Disclosed; not counted as PASS

Final evidence

• Frozen SHA：554b8a895d6d1faeaec3c66688c10263dd39649a
• Base：origin/main（f3efc3fa8ca1831a4900e55d6f0578e3fbd1a9b5）
• Diff：只新增 docs/opc-zip-surgery.md，340 行
• git diff --check origin/main..HEAD：PASS
• worktree：clean
• privacy scan：key／token／private key／credential URL、email、本機使用者絕對路徑、未授權 mention 全部 0
• docs-only：未執行 Swift runtime tests

Acceptance highlights

• 固定 package delta 與條件式 document-module binding 分開建模；來源只接受 canonical Excel .xlsx profile，其他 layout fail-loud。
• Carrier module inventory 與本次 target binding 分離並驗完整雙射；v1 只支援 workbook／worksheet hosts。
• 未觸碰 entry 比較解壓後 payload bytes；XML 用交易內 typed ledger 做 reverse-patch exact equality。
• Macro-alive 使用首次開啟前 entrypoint attestation、隔離 session、manual calculation、禁止 refresh、workbook/project/module-qualified invocation 與每輪 execution witness。
• 輸出只允許 distinct new destination；私有 staging trust boundary、descriptor-anchored atomic no-replace、提交前後 inode／digest 驗證皆已明訂。
• hostile OPC／XML、external relationship no-dereference、VBA provenance／consent、受保護封裝與 raw-data retention 邊界完整。

Verdict

verify-gated PASS。可進入 PR review；本流程不自動 merge，也不自動關閉 issue。#135 仍負責實際 inject_vba、binding patcher 與 live Excel tests，不能把本文件誤報為已交付產品能力。

Refs #136
Refs #138

[kiki830621]

PR opened

• PR: Document OPC ZIP surgery and VBA binding contracts #152
• Verified commit: 554b8a895d6d1faeaec3c66688c10263dd39649a
• Verified tags: idd-136-verified、idd-138-verified
• Multi-lens verdict: PASS（0 blocking）

Issues 136 and 138 remain open. After review and merge, use the IDD closing workflow for each issue.