docx-cli：讓 AI 代理人以高保真度編輯 Word 文件

docx-cli 優化 AI 代理人與 Word 文件的互動

docx-cli 是一款為 AI 代理人（如 Claude 與 Codex）設計的專用 CLI，能在保持完整格式的前提下讀取、編輯與註解 .docx 檔案。與傳統方法直接修改底層 OOXML（Office Open XML）不同——這常導致檔案損毀且耗用大量 token——docx-cli 為代理人提供純文字指令與帶註解的 Markdown 讀取視圖。此方式確保自訂樣式、主題顏色與嵌入物件在編輯過程中得以保留。

效能基準：docx-cli 與預設代理人技能比較

在一次包含六項真實文件任務（如填寫 NDA、標記合約、撰寫期刊）的受控 A/B 測試中，docx-cli 在兩個模型層級上均顯著優於預設代理人技能：

• 成功率：在「弱」Haiku 層級，docx-cli 解決了 4.3/6 個任務，而預設技能僅為 0.7/6。於「強」Sonnet 層級，前者達到完美的 6/6，後者為 4/6。
• Token 效率：docx-cli 將輸入 token 減少約 2.2·2.6·，降低成本並提升速度。
• 延遲：實際執行時間在兩個層級上皆縮短了 1.7·2.0·。
• 可靠性：docx-cli 產出的 100% 檔案在第一次即能於 Microsoft Word 開啟；相較之下，預設技能產生了數個 Word 無法開啟的檔案。

核心技術架構

原位 XML 變更

與其從有損模型重新輸出文件，docx-cli 將抽象語法樹（AST）視為已解析 XML 樹的檢視層。當代理人執行 edit 或 comments add 指令時，CLI 直接變更底層 XML 節點，並將變更序列化回檔案。這確保任何未在 AST 中明確建模的元素（如專有結構擴充或複雜主題顏色）保持原樣且完整。

穩定定位器與位址系統

為避免純文字偏移的脆弱性，docx-cli 使用定位器系統精確定位文件元素：

• 區塊 ID：pN（段落）、tN（表格）與 sN（分節符）依文件順序產生。
• 實體 ID：cN（註解）、imgN（圖片）、linkN（超連結）、fnN（腳註）與 enN（尾註）可透過 list 動詞取得。
• 跨度：字元偏移採 0 起始、起始包含、結束排除的方式（例如 p3:5-20 代表第 3 段的第 5 至第 19 個字元）。

豐富內容處理

docx-cli 實作多項進階功能以處理複雜的 Word 元素：

• 方程式：將 OOXML <m:oMath> 循環轉換為 LaTeX，使用自訂的 MathML–OMML 轉接器。
• 追蹤變更：使用原生 <w:ins> 與 <w:del> 標籤進行紅線標記。CLI 支援三種讀取視圖：--accepted（純文字）、--current（CriticMarkup 搭配腳註）與 --baseline（變更前文字）。
• 圖片：支援從本機路徑、data: URI 或 HTTP(S) URL 插入，並自動進行 HEIC→JPEG 轉碼。
• 樣式：允許編輯 styles.xml 中的樣式定義，實現全域變更（例如「將所有 Heading 1 變為綠色」），而不必逐一修改文件正文中的每個實例。

指令與工作流程參考

讀取與查詢

代理人使用 docx read 取得文件的 Markdown 表示，並附加 HTML 註解（例如 <!-- docx:p pN style="Caption" -->），提供樣式、對齊與間距等結構提示。

變更

變更指令會直接在檔案上作原位修改。主要指令包括：

• docx replace：在保留字元格式的前提下替換模式。
• docx edit：在特定定位器上修改內容，支援純文字、Markdown 或原始 runs。
• docx insert：在定位器前後插入內容。
• docx comments add：將註解附加至特定跨度或片語。

視覺驗證

docx render 允許代理人透過驅動 Microsoft Word（使用 osascript 或 PowerShell COM）或 LibreOffice 產生 PDF，然後使用內建的 PDFium WASM 套件將 PDF 轉為 PNG 或 JPG 圖片，以進行驗證。

安裝與代理人整合

docx-cli 以 Agent Skill 形式發佈，兼容 Claude Code、Codex 與 Pi。可透過 npx skills add kklimuk/docx-cli 安裝，或作為 Linux、macOS、Windows 的獨立二進位檔下載。針對 Claude Code，用戶可使用 /plugin marketplace add kklimuk/docx-cli 指令安裝。