ammosu DOCX 建立、編輯和分析
概述
使用者可能會要求您建立、編輯或分析 .docx 檔案的內容。.docx 檔案本質上是一個包含 XML 檔案和其他資源的 ZIP 壓縮檔，您可以讀取或編輯這些內容。針對不同的任務，您有不同的工具和工作流程可供使用。
工作流程決策樹
讀取/分析內容
使用下方的「文字擷取」或「原始 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 行）。絕對不要在讀取此檔案時設定任何範圍限制。 在進行文件建立之前，請先閱讀完整檔案內容，了解詳細語法、重要格式規則和最佳實踐。 - 使用 Document、Paragraph、TextRun 元件建立 JavaScript/TypeScript 檔案（您可以假設所有相依套件都已安裝，但如果沒有，請參考下方的相依套件章節）
- 使用 Packer.toBuffer() 匯出為 .docx 檔案
編輯現有 Word 文件
編輯現有 Word 文件時，請使用 Document 函式庫（一個用於 OOXML 操作的 Python 函式庫）。此函式庫會自動處理基礎架構設定，並提供文件操作方法。對於複雜情境，您可以透過函式庫直接存取底層 DOM。
工作流程
- 必要 - 讀取完整檔案：完整從頭到尾讀取
ooxml.md（約 600 行）。絕對不要在讀取此檔案時設定任何範圍限制。 閱讀完整檔案內容以了解 Document 函式庫 API 和直接編輯文件檔案的 XML 模式。 - 解壓縮文件：
python ooxml/scripts/unpack.py <office_file> <output_directory> - 使用 Document 函式庫建立並執行 Python 腳本（請參考 ooxml.md 中的「Document Library」章節）
- 打包最終文件：
python ooxml/scripts/pack.py <input_directory> <office_file>
Document 函式庫提供常見操作的高階方法，以及複雜情境的直接 DOM 存取。
文件審閱的紅線修訂工作流程
此工作流程允許您在 OOXML 中實作之前，使用 markdown 規劃全面的追蹤修訂。重要：對於完整的追蹤修訂，您必須系統性地實作所有變更。
批次處理策略：將相關變更分組為 3-10 個變更的批次。這樣可以讓除錯變得易於管理，同時維持效率。在移至下一批次之前，先測試每個批次。
原則：最小化、精確的編輯
實作追蹤修訂時，只標記實際變更的文字。重複未變更的文字會讓編輯更難審閱，且顯得不專業。將替換分解為：[未變更文字] + [刪除] + [插入] + [未變更文字]。透過從原始元素中擷取 <w:r> 元素並重新使用，來保留原始執行的 RSID（對於未變更的文字）。
範例 - 將句子中的「30 days」改為「60 days」：
# 不良 - 替換整個句子
'<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 節」、「第四條」）
- 段落識別碼（如有編號）
- 使用獨特周圍文字的 Grep 模式
- 文件結構（例如：「第一段」、「簽名區塊」）
- 不要使用 markdown 行號 - 它們無法對應到 XML 結構
批次組織（每批次分組 3-10 個相關變更）：
- 按章節：「批次 1：第 2 節修訂」、「批次 2：第 5 節更新」
- 按類型：「批次 1：日期更正」、「批次 2：當事人名稱變更」
- 按複雜度：從簡單的文字替換開始，然後處理複雜的結構變更
- 循序：「批次 1：第 1-3 頁」、「批次 2：第 4-6 頁」
讀取文件並解壓縮：
- 必要 - 讀取完整檔案：完整從頭到尾讀取
ooxml.md（約 600 行）。絕對不要在讀取此檔案時設定任何範圍限制。 特別注意「Document Library」和「Tracked Change Patterns」章節。 - 解壓縮文件：
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」 章節以了解模式。注意：在撰寫腳本之前，務必立即 grep
word/document.xml以取得當前行號並驗證文字內容。行號會在每次腳本執行後變更。打包文件：完成所有批次後，將解壓縮的目錄轉換回 .docx：
python ooxml/scripts/pack.py unpacked reviewed-document.docx最終驗證：對完整文件進行全面檢查：
- 將最終文件轉換為 markdown：
pandoc --track-changes=all reviewed-document.docx -o verification.md - 驗證所有變更都已正確套用：
grep "original phrase" verification.md # 應該找不到 grep "replacement phrase" 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 解析）