docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證

[kiki830621]

Problem

Original text:
「這值得放到macdoc」
— Source: 使用者(2026-07-17,聽完 .xlsm zip 注入原理解說後)

#135 經驗清單第 2 條(「.xlsm 巨集注入(零 GUI)」)只有摘要;完整的原理與驗證方法論散在對話裡,應沉澱成 macdoc docs 設計論述(同 docs/applescript-swift-parity.md 體例),並成為 che-excel-mcp inject_vba / build_xlsx 工具的設計依據。

Type

docs

要沉澱的內容(草稿大綱)

1. OPC 結構觀:.xlsx/.xlsm 是 zip,巨集只是一個成員

xlsx(zip)                          xlsm(zip)
├── [Content_Types].xml   ──改──►  workbook 型別改 macroEnabled + 宣告 bin Default
├── xl/_rels/workbook.xml.rels ─►  加一條指向 vbaProject.bin 的 relationship
├── xl/…(其他全部不動)
                          ──加──►  xl/vbaProject.bin(巨集本體)

xlsm − xlsx = 恰好三處:兩個 XML 宣告 + 一個二進位成員。注入器 = 逐 zip 成員 byte 複製 + 這三處手術。

2. vbaProject.bin 的來源工作流(不可無中生有)

• bin 是專有編譯容器(OLE + compressed source + p-code),無可靠開源生成器
• 工作流:.bas(source of truth,pure ASCII per applescript-swift-parity 的編碼教訓)→ 真 Excel 匯入空白活頁簿 → 存 xlsm → 抽 xl/vbaProject.bin → 進 repo assets
• VBA 邏輯變更 = 重走一次抽取;bin 是 build artifact,bas 是 source

3. Byte 級保真驗證模式(注入器的測試契約)

• 條目集合 = 原集合 + {xl/vbaProject.bin}(不多不少)
• 除兩個預期 XML 外,每個成員與來源 byte-identical
• 兩個被改的 XML:把預期改動還原後必須與原文完全相等(多改一個字元測試就掛)
• 注入的 bin 與 asset 逐 byte 相同

這種保證 Excel 自己的「另存」給不了(它重寫整個檔案結構)——是 zip 手術路線獨有的紅利。

4. 邊界聲明

• 不是繞過安全機制:產物是結構標準的 .xlsm,Excel 開檔照常跑巨集安全檢查
• 手術繞開的是 Excel GUI 存檔流程的坑(File Provider 路徑 -50、sandbox 授權 dialog、老式 form control 序列化失敗)

Expected

docs/opc-zip-surgery.md(暫名)進 macdoc docs;#135 的 inject_vba 工具設計引用它。

Impact

• che-excel-mcp 離線層(build_xlsx / inject_vba / normalize_xlsx)的設計依據
• 同樣手術適用家族其他成員(docx/pptx 也是 OPC;巨集注入模式可平移 .docm/.pptm)

Refs #135

Priority

P2

[kiki830621]

實戰新發現:document-module 綁定是 zip 注入的隱形殺手(必須進論述)

注入 `vbaProject.bin` 後巨集清單看得到、執行卻靜默失敗的根因:bin 的 `PROJECT` stream 記錄 document module(`Document=ThisWorkbook` + carrier 的 sheet),而綁定鍵在宿主端:

• `xl/workbook.xml` 的 `` ← 缺這個 = ThisWorkbook 物件無法解析 → runtime error 429「ActiveX 元件無法產生物件」
• 各 `xl/worksheets/sheetN.xml` 的 ``(次要)

三個惡性疊加讓它極難診斷:

1. 429 被巨集的 `On Error` handler 吃掉 → 表面「執行成功」實為 no-op
2. Mac Excel 的 `run VB macro`(AppleScript)對解析失敗靜默回 exit 0(對不存在的巨集名也是)— 帶 module 限定名(`Module.Sub`)反而能觸發真執行
3. 驗收若只看「結果正確」(輸出本來就是預期值)完全無法區分 no-op — 驗收必須要求可觀察的狀態改變(改輸入 → 輸出必須變)

修法(注入器一併縫,各一行 XML 屬性):`workbookPr` 加 `codeName="ThisWorkbook"`、各 sheet 的 `sheetPr` 加 codeName。修復後實測:注入版巨集完整 round-trip(改參數 → 42,112 格中 310 格如理論預測地 FAIL → 復原 → 全 PASS),且進程內 `ThisWorkbook.Save` 對 File Provider(Dropbox)路徑也隨綁定修復而恢復。

同時驗證:注入前後除 4 類預期改動(content-types / rels / workbook.xml / sheets 的 codeName)外仍逐條目 byte-identical,保真測試契約同步擴充。