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)的設計依據
• OPC 的封裝觀念可作為 docm/pptm 的研究起點；各格式的 main part、content type、relationship、host binding 與 fixture 必須另案規格化及驗證，不得直接平移 xlsm 契約

Refs #135

Priority

P2

---

Current Status

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

Delivered

• docs/opc-zip-surgery.md：OPC delta、VBA provenance、document-module binding、byte fidelity、macro-alive 與安全／交易邊界。
• docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 已吸收到同一文件與同一交付 PR。

Scope refinement

• 原草稿的「恰好三處」是固定最小 delta；document modules 可能需要條件式 codeName delta。
• 保真單位是未觸碰 entry 的解壓後 payload，不是整個 ZIP archive bytes。
• 實際產品能力與 live Excel tests 仍由 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 承接。

Blocking

• (none)

Commits

• 33cca15 — initial contract
• ca89009 — logic/security boundaries
• a8901e7 — verification gaps
• 9b22acc / 11e6ab0 — descriptor semantics
• 554b8a8 — private staging trust boundary

Verify

• PASS：0 blocking findings
• Report：docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136 (comment)

Platform capability status

• 離線格式層：platform:cross；狀態為 design-only；已驗證的是文件契約本身，feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 尚未交付跨平台 runtime 實作或測試。
• 活 Excel 驗收層：platform:macos；狀態為 design-only；只有 Excel for Mac 歷史觀察，精確 macOS／Excel 版本未記錄，repository 內無 live fixture。
• Windows／Linux 活應用程式層：Excel 自動化；狀態為 not-verified，不得由 OPC 格式知識外推。
• 狀態命名空間：上方 Phase: verified 僅代表 docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136 文件交付通過 IDD verify，不代表 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 runtime 或 live Excel 能力已驗證。

[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,保真測試契約同步擴充。

[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]

Implementation plan

1. 建立 docs/opc-zip-surgery.md，先界定離線 package 手術與活 Excel resave 是兩種不同模式。
2. 精確記錄 .xlsx → .xlsm 的 content type、relationship、binary part 與條件式 document-module 綁定。
3. 將 carrier .bas／vbaProject.bin／binding manifest 的來源與雜湊規則寫成可稽核契約。
4. 寫出 byte-level 保真矩陣與擾動輸入的 macro-alive 驗收流程，納入 docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 的靜默 no-op 反例。
5. 補 hostile OPC、巨集明示授權、原子替換、受保護封裝與 macOS + Excel for Mac 平台限制。
6. 執行 Markdown／連結／關鍵 token 靜態檢查、git diff --check，再進行多面向 IDD verify。

Refs #136
Refs #138

[kiki830621]

📊 For Reviewer / Collaborator

現在：#136 與吸收的 #138 已通過多面向 verify，PR #152 已建立。
Blocking：無。
你該做什麼：review https://github.com/PsychQuant/macdoc/pull/152；確認後 merge，再由人工完成兩張 issue 的 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.