docs: 平台標示慣例 — docs 與 issues 需明示適用平台(macOS/Windows/Linux/跨平台)與實測範圍

[kiki830621]

Problem

Original text:
「所以macdoc需要事先標示使用的電腦是什麼,是windows, mac, linus之類的」
— Source: 使用者(2026-07-17,連續踩完多個 macOS 特定地雷後)

macdoc 的 docs 與 issues 目前不標示適用平台。但今天沉澱的知識幾乎全是平台特定的,不標示會讓讀者(尤其未來的 AI session)把 macOS 的 workaround 誤套到 Windows、或反之,平白浪費診斷時間。

Type

docs

動機:今天的實例,平台維度其實貫穿每一條

知識	檔案格式層	自動化行為層
OPC zip 手術 / vbaProject.bin 注入(#136)	跨平台(zip/XML 與 OS 無關)	驗證流程用 AppleScript 驅動 Excel = macOS only
codeName 綁定陷阱(#138)	跨平台(OOXML 結構)	「run VB macro 靜默 no-op」是 Mac Excel AppleScript 特性;Windows 走 COM,行為不同
VBE 匯入 .bas 的 legacy codepage 吞引號	—	兩平台都有,但 codepage 來源不同(Mac=系統 locale;Win=ANSI codepage)
SaveAs 被 sandbox 擋 / Grant File Access dialog	—	macOS only(Mac Office App Sandbox;Windows 無此層)
Shapes.AddShape 對未顯示 sheet 拋 1004	—	Mac Excel 實測;Windows 未驗證
AppleScriptTask 回呼橋(#135)	—	macOS only(Windows 對應物是 COM/VSTO)

關鍵洞察:同一篇文件內就需要兩層標示——「檔案格式知識」多半跨平台,「自動化行為知識」幾乎都平台特定。

提案

1. docs 慣例:每篇 docs/*.md 標題下加一行平台聲明,例:
   • > 適用平台:macOS(Excel for Mac 16.x 實測;Windows 未驗證)
   • > 適用平台:跨平台(檔案格式層)/ macOS(自動化驗證流程)
2. issue labels:建 platform:macos / platform:windows / platform:linux / platform:cross,平台特定的 bug/docs issue 掛上
3. 回補既有內容:docs/applescript-swift-parity.md(macOS only)與 feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135/docs: OPC zip 手術論述 — .xlsm 巨集注入、vbaProject.bin 工作流與 byte 級保真驗證 #136/docs: VBA 注入的 document-module 綁定陷阱 — codeName 缺失讓巨集「看似正常、執行全滅」(429/靜默 no-op) #138 規劃的 docs 依上表標示
4. 驗證聲明慣例:標「實測」的平台版本(如 Excel for Mac 16.99/macOS 26)與「未驗證」的平台分開寫——不確定的不聲稱

Impact

• 防止跨平台誤用(最貴的失敗模式:拿 macOS sandbox workaround 去 Windows 上除錯不存在的問題)
• 給 che-excel-mcp(feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server #135)定調:它是 macOS-first 工具(AppleScript 驅動層),離線層(zip 手術)才是跨平台
• AI session 讀 docs 時能立刻判斷知識適用性

Refs #135, #136, #138

Priority

P2