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 文件。
工作流程
- 務必完整閱讀整個檔案：從頭到尾完整閱讀
docx-js.md（約 500 行）。閱讀此檔案時切勿設定任何範圍限制。 在進行文件建立之前，請完整閱讀檔案內容，以取得詳細的語法、關鍵格式規則與最佳實務。 - 建立一個 JavaScript/TypeScript 檔案，使用 Document、Paragraph、TextRun 等元件（你可以假設所有相依套件皆已安裝，如果沒有，請參考下方的相依套件章節）。
- 使用
Packer.toBuffer()匯出為 .docx。
編輯現有 Word 文件
編輯現有 Word 文件時，請使用 Document Library（一個專為 OOXML 操作設計的 Python 函式庫）。該函式庫會自動處理基礎架構設定，並提供文件操作方法。對於複雜的情境，你可以透過該函式庫直接存取底層的 DOM。
工作流程
- 務必完整閱讀整個檔案：從頭到尾完整閱讀
ooxml.md（約 600 行）。閱讀此檔案時切勿設定任何範圍限制。 請完整閱讀檔案內容，以了解 Document Library API 以及直接編輯文件檔案的 XML 模式。 - 解開文件：
python ooxml/scripts/unpack.py <office_file> <output_directory> - 建立並執行一個使用 Document Library 的 Python 腳本（請參閱 ooxml.md 中的「Document Library」章節）。
- 打包最終文件：
python ooxml/scripts/pack.py <input_directory> <office_file>
Document Library 同時提供高階方法用於常見操作，以及直接的 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>'
追蹤修訂工作流程
-
取得 Markdown 表示：將文件轉換為 Markdown，並保留追蹤修訂：
pandoc --track-changes=all path-to-file.docx -o current.md -
識別並分組變更：審閱文件並識別所有需要的變更，將其組織成邏輯批次：
定位方法（用於在 XML 中找到變更位置）：
- 章節/標題編號（例如「第 3.2 節」、「第 IV 條」）
- 段落識別碼（如果有序號）
- 使用唯一周圍文字的 Grep 模式
- 文件結構（例如「第一個段落」、「簽名欄位」）
- 切勿使用 Markdown 行號——它們無法對應到 XML 結構
批次組織（每批分組 3-10 個相關變更）：
- 按章節：「批次 1：第 2 節修正」、「批次 2：第 5 節更新」
- 按類型：「批次 1：日期修正」、「批次 2：當事人姓名變更」
- 按複雜度：先從簡單的文字取代開始，再處理複雜的結構變更
- 按順序：「批次 1：第 1-3 頁」、「批次 2：第 4-6 頁」
-
閱讀文件並解開：
- 務必完整閱讀整個檔案：從頭到尾完整閱讀
ooxml.md（約 600 行）。閱讀此檔案時切勿設定任何範圍限制。 特別注意「Document Library」與「追蹤修訂模式」章節。 - 解開文件：
python ooxml/scripts/unpack.py <file.docx> <dir> - 注意建議的 RSID：解開腳本會建議一個用於追蹤修訂的 RSID。請複製此 RSID 供步驟 4b 使用。
- 務必完整閱讀整個檔案：從頭到尾完整閱讀
-
批次實作變更：將變更按邏輯分組（按章節、按類型或按鄰近性），並在單一腳本中一起實作。這種方法：
- 讓除錯更容易（較小的批次 = 更容易隔離錯誤）
- 允許逐步進展
- 維持效率（批次大小在 3-10 個變更之間效果最佳）
建議的批次分組：
- 按文件章節（例如「第 3 節變更」、「定義」、「終止條款」）
- 按變更類型（例如「日期變更」、「當事人姓名更新」、「法律用語取代」）
- 按鄰近性（例如「第 1-3 頁的變更」、「文件前半部的變更」）
對於每一批相關的變更：
a. 將文字對應到 XML：在
word/document.xml中使用 Grep 搜尋文字，以驗證文字如何跨<w:r>元素分割。b. 建立並執行腳本：使用
get_node來尋找節點，實作變更，然後doc.save()。請參閱 ooxml.md 中的「Document Library」章節以了解模式。注意：在撰寫腳本之前，務必立即對
word/document.xml執行 Grep，以取得當前行號並驗證文字內容。每次腳本執行後，行號都會改變。 -
打包文件：所有批次完成後，將解開的目錄轉換回 .docx：
python ooxml/scripts/pack.py unpacked reviewed-document.docx -
最終驗證：對完整文件進行全面檢查：
- 將最終文件轉換為 Markdown：
pandoc --track-changes=all reviewed-document.docx -o verification.md - 驗證所有變更都已正確套用：
grep "原始片語" verification.md # 應找不到 grep "替代片語" verification.md # 應找得到 - 檢查是否引入了非預期的變更
- 將最終文件轉換為 Markdown：
將文件轉換為圖片
若要視覺化分析 Word 文件，請透過兩個步驟將其轉換為圖片：
-
將 DOCX 轉換為 PDF：
soffice --headless --convert-to pdf document.docx -
將 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 解析）