feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server

[kiki830621]

Problem

Original text:
「我覺得這些經驗可以用來發展che-excel-mcp,你覺得呢」
— Source: 使用者(2026-07-17,一個顧問案 Excel 交付工具鏈收尾後)

macdoc 的 mcp/ 家族已有 che-word-mcp / che-pptx-mcp / che-pdf-mcp,Excel 是 Office 文件家族的最後一個缺口。最近一輪實戰(用 openpyxl + LibreOffice + AppleScript + VBA 打通「產生 xlsx/xlsm → 注入巨集 → 真 Excel 驗證」全鏈)踩出了一批 generic 的 Excel 自動化知識,值得沉澱成 MCP server,讓之後任何 session 不必重踩。

Type

feature

實戰經驗清單(全部可轉化為 MCP 功能或內建 workaround)

1. xlsx 產物相容性

• openpyxl 3.x 寫 inline strings(無 xl/sharedStrings.xml),部分 Excel 版本直接拒開
• Workaround:LibreOffice headless round-trip(soffice --headless --convert-to xlsx)正規化結構
• → MCP 產表工具應內建正規化(或原生寫 sharedStrings)

2. .xlsm 巨集注入(零 GUI)

• openpyxl 無法建立 VBA 專案;可用 OPC zip 手術把現成 vbaProject.bin 縫進 xlsx:
  [Content_Types].xml workbook 型別改 macroEnabled + 加 bin Default + rels 加 vbaProject relationship
• 保真可測:除 3 處預期改動外,逐 zip 條目 byte-identical
• → inject_vba(xlsx, bin) → xlsm 工具

3. VBA .bas 匯入的編碼陷阱

• VBE 用 legacy codepage 解 .bas;UTF-8 中文字串的尾 byte(如「率」的 0x87)會與後面的 " 配成 double-byte 字、吞掉閉引號 → 編譯錯誤
• 解法:.bas 全 ASCII;中文 sheet 名用 ChrW(&H....) 組字
• → MCP 產 .bas / 驗 .bas 時 lint 這個

4. 真 Excel AppleScript 驅動的地雷(Mac)

• run VB macro 對不存在的巨集 silent no-op(exit 0,無錯誤)— 必須先驗巨集清單
• VBA 編譯錯誤讓 VBE 進 break mode,之後所有 run VB macro 靜默吞掉
• 巨集 MsgBox 會擋 AppleEvent 回傳;自動化要能偵測/關閉 dialog
• save workbook as 到 File Provider 路徑(Dropbox 等)回 -50;寫 ~/Documents 觸發 sandbox「授與檔案存取權」dialog;正解是 VBA 自己 SaveAs(Excel 進程內,無 sandbox 限制)
• 舊 API make new button 建的 form control 會讓 save-as-xlsm 序列化失敗(「移除或修復部分功能」錯誤)
• GUI scripting(keystroke/click)會搶焦點,使用者同時在用機器時有誤擊風險 — 讀值/按鈕盡量走 AX API(不 activate)

5. 驗證方法論

• 工作簿內建「比較」活公式頁(整表 SUMPRODUCT 逐格比對)= 交付檔自帶驗證器
• AppleScript 靜默讀 range value(不搶焦點)做 round-trip 驗證
• 雙實作交叉驗證:Python 引擎 vs Excel/VBA 對同一組測試向量必須逐格一致

提議的 tool surface(草案)

Tool	功能
open_workbook / close_workbook	開關檔(處理巨集安全提示)
list_sheets / read_range / write_range	讀寫(AX 級,不搶焦點)
read_formula / set_formula	公式層存取
recalculate	強制重算
list_macros / run_macro	巨集(先驗存在,偵測 break mode / MsgBox)
save_as	由 VBA 進程內執行,繞 sandbox
build_xlsx / inject_vba	離線產表 + 巨集注入(不需開 Excel)
normalize_xlsx	LibreOffice 正規化
compare_ranges	兩表逐格 diff(容差參數)

架構同 che-ical/mail/notes 家族:Swift + AppleScript/ScriptingBridge 驅動真 Excel;離線部分(zip 手術、xlsx 產生)純 Swift。sign + notarize pipeline(che-mcps-notary)現成。

Impact

• Office MCP 家族補齊(word/pptx/pdf/excel)
• 精算/財務類顧問案的 Excel 交付自動化(產表 → 巨集 → 驗證)變成可重用能力
• 上面每一條地雷都是踩過一次就該封裝的知識;不沉澱下次照踩

Priority

P2

---

Platform Capability Status

• 離線格式層：platform:cross；狀態為 design-only；OPC／xlsx 契約可不依賴作業系統，但 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 尚未交付產品實作與可重現測試。
• 活 Excel 自動化層：platform:macos；狀態為 design-only；AppleScript／Apple Events 是 macOS 專屬設計，目前只有歷史觀察，當時的 macOS 與 Excel 精確版本未記錄。
• Windows／Linux 活應用程式層：Excel 自動化；狀態為 not-supported，COM／VSTO 或其他橋接須另案設計，不由離線格式契約外推。
• 證據規則：以 docs/platform-support.md 為準；issue 的工作流 Phase 不等於平台能力已驗證。

---

Implementation Readiness

Phase: blocked on product authority and fixtures
Last updated: 2026-08-13 by idd-all

Gates

• Dedicated repository ownership／visibility／release decision 尚未授權。
• 可信 VBA carrier asset、digest 與 module/procedure inventory 尚未提供。
• 可重現的 macOS／Excel live integration fixture 與版本尚未指定。

Safe progress completed

• docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136／docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 OPC、binding、macro-alive 與交易契約已通過 verify，PR Document OPC ZIP surgery and VBA binding contracts #152 待審。
• docs: 平台標示慣例 — docs 與 issues 需明示適用平台(macOS/Windows/Linux/跨平台)與實測範圍 #139 platform capability status 已同步，PR docs: define platform support declarations #153 待審。
• 未建立外部 repository、未上傳 VBA binary、未宣稱 runtime 已支援。

Blocking

• 需要 owner 提供 repository／資產／live fixture 三項 authority；其餘無法在不擴張權限下完成。

[kiki830621]

設計補充:AppleScript alignment(雙向橋)

Original text:
「而且有趣的是可以跟apple scripts alignment,這是目前沒有想到的做法」
— Source: 使用者(2026-07-17,follow-up)

這個 alignment 有三層,其中第三層是 macdoc 家族目前完全沒有的維度:

1. 驅動方向:AppleScript → Excel(已實戰驗證)

MCP tool 內部以 AppleScript/ScriptingBridge 驅動活的 Excel(開簿、讀寫 range、run VB macro、偵測 dialog)。macdoc 既有三個 MCP(word/pptx/pdf)都是離線檔案轉換;Excel 是家族第一個需要「app 在跑」的成員——這個模式 che-ical-mcp / che-apple-mail-mcp 已驗證,搬過來即可。

2. 語意對齊:tool surface 對齊 Excel 的 AppleScript dictionary

tool 命名與參數語意直接對齊官方 scripting dictionary(worksheet / range / value / formula / run VB macro),而不是自創抽象 — 行為可預測、文件可互查,也把 dictionary 沒暴露的部分(如 VBE 操作)明確標為「需走其他路徑」。

3. 回呼方向:VBA → AppleScript(AppleScriptTask)— 新做法

Mac Office sandbox 提供官方橋:放在 ~/Library/Application Scripts/com.microsoft.Excel/ 的 .scpt 可被 VBA 以 AppleScriptTask("script.scpt", "handler", "arg") 呼叫,以完整使用者權限執行(繞開 VBA 自身的 sandbox 限制)。這開啟一個沒想過的架構:

• MCP 安裝時把 helper .scpt 部署進該目錄
• MCP 注入的 VBA 巨集透過 AppleScriptTask 回呼系統能力:寫任意路徑(取代 Grant-File-Access dialog 地獄)、發通知、觸發外部驗證、甚至回報執行狀態給 MCP
• 等於 MCP ⇄ AppleScript ⇄ Excel/VBA 三方閉環:MCP 產巨集 → 巨集在 Excel 內算 → 算完經 AppleScriptTask 把結果/狀態送回系統側 → MCP 讀取,全程零 GUI scripting、零搶焦點

實戰註腳:本輪 SaveAs 的 sandbox 迷宮(File Provider 路徑 -50、~/Documents 要授權 dialog)如果當時有第 3 層,巨集直接 AppleScriptTask 存檔即可,整段 GUI 纏鬥都不會發生。

[kiki830621]

Rule 已落地:docs/applescript-swift-parity.md — 每個 AppleScript 能力都必須有型別化 Swift 函數對應;tool handler 永不直呼 osascript。含五條精確化(capability 粒度、唯一入口可 lint、錯誤路徑型別化、AppleScriptTask 資產的對應物、integration test 義務)與 che-excel-mcp 草案簽名。

[kiki830621]

Implementation readiness audit

現況證據

• 既有 che-word-mcp／che-pdf-mcp／che-pptx-mcp 都是獨立 repository，再由 macdoc 以 git submodule 引入；目前沒有 PsychQuant/che-excel-mcp repository，也沒有可引用的 submodule commit。
• docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136／docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 的契約已完成，但第一版 inject_vba 必須使用受信任 carrier asset、binary digest、module/procedure inventory 與 target binding；目前 repository 沒有這組可驗證資產。
• 活 Excel 層目前只有歷史觀察，沒有記錄精確 macOS／Excel 版本的公開 fixture 或可重現 integration environment。平台狀態仍是 design-only。
• 評估 macdoc 是否需要 xlsx 支援（sibling concern from #143） #144 已確認 macdoc CLI 不新增一般 xlsx conversion route；feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135 是獨立 MCP 產品，不應把它偷渡進 root convert router。

Implementation gates

1. Repository ownership：由 owner 決定新 server 的 repository 名稱、visibility 與發布方式；macdoc 只在上游有 authoritative commit 後加入 submodule／plugin wiring。
2. Trusted VBA asset：提供或在受控流程產生第一份可審核的 .bas source、vbaProject.bin、digest 與完整 inventory；不得由任意使用者活頁簿抽取後直接重用。
3. Live Excel acceptance：指定可重現的 macOS／Excel 版本與 opt-in fixture，並以 workbook-qualified macro、execution witness 與獨立 oracle 驗收。

建議切片

• Slice A：獨立 repo scaffold、typed bridge 與只讀 workbook tools。
• Slice B：依 docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136/docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 實作離線 inject_vba，只接受 distinct new destination 與可信 asset。
• Slice C：live Excel read/write/recalculate/macro-alive tools，以明示同意與真 App gate 驗收。
• Slice D：macdoc submodule／plugin marketplace 接線。

本輪不會自行建立或公開新 repository，也不會產生／上傳未經 owner 審核的 VBA binary。這不是宣告 #135 完成；issue 保持 OPEN，等待上述 authority／fixture gates 後再實作。

Refs #135 #136 #138 #139

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

The design groundwork is complete, but implementation cannot safely start because three product-authority inputs remain absent:

1. repository name/visibility/release ownership for the new MCP server,
2. a trusted VBA carrier (.bas, vbaProject.bin, digest, module/procedure inventory),
3. an opt-in live Excel fixture with exact macOS/Excel versions.

These are not code-discovery questions. Creating a public/private repository, publishing a binary asset, or selecting a user's live workbook without explicit authority would exceed the requested workflow and create irreversible external state.

Impact

• Safe completed scope: docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136/docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 offline OPC/binding contracts and docs: 平台標示慣例 — docs 與 issues 需明示適用平台(macOS/Windows/Linux/跨平台)與實測範圍 #139 platform declarations.
• Blocked scope: standalone server repository, VBA asset pipeline, live Excel read/write/macro acceptance, macdoc submodule/plugin wiring.

Strategy

• Owner chooses repository name, visibility, and release policy.
• Owner provides or authorizes creation of a reviewable trusted VBA carrier and inventory.
• Owner designates the live Excel fixture and exact supported macOS/Excel versions.
• After those gates, create a cross-repo umbrella/children and execute the existing A→D slices (scaffold/read-only bridge; offline injection; live tools; macdoc wiring).

Conflict Class

D_diagnose_first

The physical implementation resources do not yet exist or are not authorized; conflict class cannot safely become A/B/C until repository and fixture decisions are made.

Complexity

Spectra

Layer 2：new public MCP tool/server contracts. Layer 3：cross-repo architecture, binary provenance, live-application security, release and platform-support decisions.

Risks

• Choosing visibility/release defaults without owner authority creates the wrong external product surface.
• Reusing an arbitrary workbook's VBA binary can leak third-party code/data and invalidate provenance.
• Live Excel automation without opt-in fixture/version can interrupt the user's application session or produce unverifiable claims.

Residue

The product goal is clear, but its ownership and trusted-fixture horizon cannot be operationalized from repository evidence alone.

Vagueness Pre-check

• V1: 3 — product slices are defined; the authoritative repository/asset choices are missing.
• V4: 5 — live acceptance cannot be reproduced until fixture and platform versions are named.
• Triggered: yes (max=5)
• User choice: unattended default proceed anyway; implementation remains authority-blocked rather than guessing.
• Effect: keep D_diagnose_first and surface human action.

Layer V Deferred Record

• Reason: unattended-auto-Step-3.4-layerV-deferred

• V1: 3 — repository/asset authority absent

• V4: 5 — reproducible live fixture/version absent

• Catch-up: /idd-clarify #135 after the owner supplies the three decisions.

• Hard-gate: triggered — one product concept spans server repo, assets, bridge, tools, tests, release, and root wiring; Spectra already takes precedence.

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• (none newly filed) docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136/docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138/docs: 平台標示慣例 — docs 與 issues 需明示適用平台(macOS/Windows/Linux/跨平台)與實測範圍 #139 already carry the adjacent design work.