word-document-processor

DOCX 建立、編輯與分析

概述

使用者可能要求你建立、編輯或分析 .docx 檔案的內容。.docx 檔案本質上是一個 ZIP 壓縮檔，包含 XML 檔案及其他資源，你可以讀取或編輯這些內容。針對不同任務，你有不同的工具與工作流程可用。

工作流程決策樹

讀取/分析內容

請使用下方「文字擷取」或「原始 XML 存取」章節

建立新文件

請使用「建立新 Word 文件」工作流程

編輯現有文件

• 你自己的文件 + 簡單修改
  使用「基本 OOXML 編輯」工作流程

• 他人的文件
  使用**「修訂標記工作流程」**（建議預設）

• 法律、學術、商業或政府文件
  使用**「修訂標記工作流程」**（必要）

讀取與分析內容

文字擷取

如果你只需要讀取文件的文字內容，應使用 pandoc 將文件轉換為 markdown。Pandoc 提供絕佳的結構保留支援，並能顯示追蹤修訂：

# 將文件轉換為 markdown，保留追蹤修訂
pandoc --track-changes=all path-to-file.docx -o output.md
# 選項：--track-changes=accept/reject/all

原始 XML 存取

你需要原始 XML 存取來處理：註解、複雜格式、文件結構、嵌入媒體及中繼資料。對於這些功能，你需要解壓縮文件並讀取其原始 XML 內容。

解壓縮檔案

python ooxml/scripts/unpack.py <office_file> <output_directory>

關鍵檔案結構

• word/document.xml - 主要文件內容
• word/comments.xml - document.xml 中引用的註解
• word/media/ - 嵌入的圖片與媒體檔案
• 追蹤修訂使用 <w:ins>（插入）與 <w:del>（刪除）標籤

建立新 Word 文件

從頭建立新 Word 文件時，請使用 docx-js，它允許你使用 JavaScript/TypeScript 建立 Word 文件。

工作流程

1. 必須 - 完整讀取檔案：從頭到尾完整讀取 docx-js.md（約 500 行）。讀取此檔案時絕對不要設定任何範圍限制。 在開始建立文件前，請完整讀取檔案內容以了解詳細語法、關鍵格式規則及最佳實務。
2. 使用 Document、Paragraph、TextRun 元件建立 JavaScript/TypeScript 檔案（你可以假設所有相依套件已安裝，若未安裝，請參考下方相依套件章節）
3. 使用 Packer.toBuffer() 匯出為 .docx

編輯現有 Word 文件

編輯現有 Word 文件時，請使用 Document 函式庫（一個用於 OOXML 操作的 Python 函式庫）。該函式庫會自動處理基礎設施設定，並提供文件操作方法。對於複雜情境，你可以透過函式庫直接存取底層 DOM。

工作流程

1. 必須 - 完整讀取檔案：從頭到尾完整讀取 ooxml.md（約 600 行）。讀取此檔案時絕對不要設定任何範圍限制。 完整讀取檔案內容以了解 Document 函式庫 API 及直接編輯文件檔案的 XML 模式。
2. 解壓縮文件：python ooxml/scripts/unpack.py <office_file> <output_directory>
3. 使用 Document 函式庫建立並執行 Python 腳本（請參閱 ooxml.md 中的「Document 函式庫」章節）
4. 打包最終文件：python ooxml/scripts/pack.py <input_directory> <office_file>

Document 函式庫提供高階方法處理常見操作，以及直接 DOM 存取處理複雜情境。

文件審閱的修訂標記工作流程

此工作流程允許你在以 OOXML 實作修訂前，先使用 markdown 規劃完整的追蹤修訂。關鍵：要實現完整的追蹤修訂，你必須系統性地實作所有修改。

批次策略：將相關修改分組為 3-10 個變更的批次。這使得除錯易於管理，同時保持效率。在進行下一批次前，先測試每個批次。

原則：最小、精確的編輯
在實作追蹤修訂時，只標記實際變更的文字。重複未變更的文字會使編輯難以審閱，且顯得不專業。將取代拆分為：[未變更文字] + [刪除] + [插入] + [未變更文字]。透過從原始內容中提取 <w:r> 元素並重複使用，保留未變更文字的原始 RSID。

範例 - 將句子中的「30 天」改為「60 天」：

# 錯誤 - 取代整個句子
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# 正確 - 只標記變更的部分，保留未變更文字的原始 <w:r>
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

追蹤修訂工作流程

1. 取得 markdown 表示：將文件轉換為 markdown，保留追蹤修訂：

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. 識別並分組修改：審閱文件，識別所有需要的修改，並將其組織為邏輯批次：

   定位方法（用於在 XML 中尋找修改）：

   • 章節/標題編號（例如「第 3.2 節」、「第四條」）
   • 段落識別碼（如有編號）
   • 使用唯一周圍文字的 Grep 模式
   • 文件結構（例如「第一段」、「簽名欄」）
   • 不要使用 markdown 行號 - 它們無法對應到 XML 結構

   批次組織（每批分組 3-10 個相關修改）：

   • 按章節：「批次 1：第 2 節修正」、「批次 2：第 5 節更新」
   • 按類型：「批次 1：日期修正」、「批次 2：當事人名稱變更」
   • 按複雜度：從簡單的文字取代開始，再處理複雜的結構變更
   • 按順序：「批次 1：第 1-3 頁」、「批次 2：第 4-6 頁」

3. 讀取文件並解壓縮：

   • 必須 - 完整讀取檔案：從頭到尾完整讀取 ooxml.md（約 600 行）。讀取此檔案時絕對不要設定任何範圍限制。 特別注意「Document 函式庫」與「追蹤修訂模式」章節。
   • 解壓縮文件：python ooxml/scripts/unpack.py <file.docx> <dir>
   • 記下建議的 RSID：解壓縮腳本會建議一個用於追蹤修訂的 RSID。複製此 RSID 以在步驟 4b 中使用。

4. 分批實作修改：將修改按邏輯分組（按章節、類型或鄰近性），並在單一腳本中一起實作。這種方法：

   • 使除錯更容易（較小的批次 = 更容易隔離錯誤）
   • 允許逐步進展
   • 保持效率（批次大小 3-10 個修改效果良好）

   建議的批次分組：

   • 按文件章節（例如「第 3 節修改」、「定義」、「終止條款」）
   • 按修改類型（例如「日期變更」、「當事人名稱更新」、「法律用語取代」）
   • 按鄰近性（例如「第 1-3 頁的修改」、「文件前半部的修改」）

   對於每批相關修改：

   a. 將文字對應到 XML：在 word/document.xml 中 Grep 文字，以確認文字如何跨 <w:r> 元素拆分。

   b. 建立並執行腳本：使用 get_node 尋找節點，實作修改，然後 doc.save()。請參閱 ooxml.md 中的「Document 函式庫」章節以了解模式。

   注意：在撰寫腳本前，務必立即 Grep word/document.xml 以取得當前行號並確認文字內容。每次腳本執行後行號會改變。

5. 打包文件：所有批次完成後，將解壓縮的目錄轉換回 .docx：

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. 最終驗證：對完整文件進行全面檢查：

   • 將最終文件轉換為 markdown：

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • 確認所有修改已正確套用：

     grep "original phrase" verification.md  # 應找不到
     grep "replacement phrase" verification.md  # 應找到
     

   • 檢查是否引入了非預期的修改

將文件轉換為圖片

若要視覺化分析 Word 文件，請透過兩步驟流程將其轉換為圖片：

1. 將 DOCX 轉換為 PDF：

   soffice --headless --convert-to pdf document.docx
   

2. 將 PDF 頁面轉換為 JPEG 圖片：

   pdftoppm -jpeg -r 150 document.pdf page
   

   這會建立如 page-1.jpg、page-2.jpg 等檔案。

選項：

• -r 150：設定解析度為 150 DPI（可調整以平衡品質/大小）
• -jpeg：輸出 JPEG 格式（若偏好 PNG 可使用 -png）
• -f N：要轉換的第一頁（例如 -f 2 從第 2 頁開始）
• -l N：要轉換的最後一頁（例如 -l 5 在第 5 頁停止）
• page：輸出檔案的前綴

指定範圍的範例：

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # 僅轉換第 2-5 頁

程式碼風格指南

重要：在產生 DOCX 操作的程式碼時：

• 撰寫簡潔的程式碼
• 避免冗長的變數名稱與多餘的操作
• 避免不必要的 print 陳述式

相依套件

必要的相依套件（若未安裝請安裝）：

• pandoc：sudo apt-get install pandoc（用於文字擷取）
• docx：npm install -g docx（用於建立新文件）
• LibreOffice：sudo apt-get install libreoffice（用於 PDF 轉換）
• Poppler：sudo apt-get install poppler-utils（用於 pdftoppm 將 PDF 轉換為圖片）
• defusedxml：pip install defusedxml（用於安全的 XML 解析）