docx

Word (.docx) 文件處理

處理 .docx 檔案的三件事：讀取抽取、建立、轉換 PDF。所有腳本用 uv run 執行，依賴以 PEP 723 inline metadata 宣告（python-docx），uv 會自動 建立隔離環境；uv 不存在時改用 pip install python-docx 後 python3 執行。

何時使用

• 收到 .docx 附件，需要讀出內容或表格來彙總、分析。
• 要把彙總結果、報告產出成一份 Word 文件回傳給使用者。
• 需要把 Word 轉成 PDF 交付。

腳本

腳本位於本技能的 scripts/ 目錄（相對於此 SKILL.md）。兩種執行路徑，依你有沒有 Bash 工具擇一：

• 有 Bash / shell 工具 → 直接跑 uv run scripts/<script>.py ...（見下方各節）。

• 沒有 Bash / shell 工具（API 模式後端，如 Grok / DeepSeek / MiniMax） → 不要只回文字， 改用 office_script MCP 工具在伺服器端跑同一支腳本：

  • skill：docx
  • script：create / extract / to_pdf（不含路徑，.py 可省略）
  • args：字串陣列，等同 uv run 後面那串參數；任何路徑須落在你的 agent 目錄或其 attachments/。

  例（把報告做成 Word）：

  {"skill": "docx", "script": "create",
   "args": ["report.md", "--out", "/你的agent目錄/attachments/report.docx"]}
  

  工具以 uv run（uv 不存在時退回 python3）在你的 agent 目錄內執行並回傳腳本 stdout； 產出檔案後務必依下方 📎DELIVER 協定交付。

1. 讀取抽取 — extract.py

uv run scripts/extract.py <input.docx> --format json   # 依文件順序的 blocks
uv run scripts/extract.py <input.docx> --format md      # markdown 純文字

json 輸出 {"blocks": [{"type":"heading"|"paragraph"|"bullet"|"table", ...}]}， 依 document body 的實際順序（標題／段落／清單／表格交錯，不重新分組）；md 把同一組 blocks 轉成可直接閱讀的 markdown。此 JSON 即 create.py 的輸入格式， 故 extract → create 可往返。

2. 建立 — create.py

從 markdown 或 JSON 來源檔建立 .docx（來源型別依副檔名判定，.json → JSON， 其餘 → markdown）：

uv run scripts/create.py report.md --out /abs/path/report.docx
uv run scripts/create.py spec.json --out /abs/path/report.docx

markdown 支援 #/##/### 標題、清單 - 、以及 | 分隔的表格。

3. 轉 PDF — to_pdf.py

用 LibreOffice headless 轉換：

uv run scripts/to_pdf.py <input.docx> --outdir <dir>

未安裝 LibreOffice（soffice）時，腳本會明確回報「LibreOffice 未安裝，僅轉換 功能不可用；讀取與建立功能不受影響」並以非零碼結束 — 不是靜默失敗。

交付檔案給使用者（📎DELIVER 協定）

產出檔案後，在回覆的最後另起一行加上標記，gateway 會自動把該檔案傳回使用者：

📎DELIVER:/絕對路徑/report.docx

規則：

• 路徑必須是絕對路徑，且位於你的 agent 工作目錄（或其 attachments/）下。
• 一行一個檔案，可多行。
• 標記行不會顯示給使用者；請同時用一般文字說明你做了什麼。
• API 模式同樣適用：用 office_script 產出 .docx 後，一樣在最後一行輸出 📎DELIVER:<絕對路徑>——只回文字不算完成。