minimax-docx

minimax-docx

透過 CLI 工具或基於 OpenXML SDK (.NET) 的 C# 指令碼，建立、編輯與格式化 DOCX 文件。

設定

首次使用： bash scripts/setup.sh（Windows 上使用 powershell scripts/setup.ps1，加上 --minimal 可跳過選用相依套件）。

工作階段中首次操作： scripts/env_check.sh — 若顯示 NOT READY 則不要繼續。（同一工作階段內的後續操作可跳過。）

快速入門：直接使用 C# 路徑

當任務需要結構性文件操作（自訂樣式、複雜表格、多節版面、頁首/頁尾、目錄、圖片）時，直接撰寫 C# 而非受限於 CLI 限制。使用以下範本：

// 檔案：scripts/dotnet/task.csx（或主控台專案中的新 .cs 檔案）
// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx
#r "nuget: DocumentFormat.OpenXml, 3.2.0"

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;

using var doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
var mainPart = doc.AddMainDocumentPart();
mainPart.Document = new Document(new Body());

// --- 在此撰寫您的邏輯 ---
// 請先閱讀相關的 Samples/*.cs 檔案以取得經過測試的模式。
// 請參閱下方參考資料章節中的 Samples 表格。

在撰寫任何 C# 程式碼之前，請先閱讀相關的 Samples/*.cs 檔案——這些檔案包含可編譯且經過 SDK 版本驗證的模式。下方參考資料章節中的 Samples 表格會將主題對應到檔案。

CLI 簡寫

以下所有 CLI 指令使用 $CLI 作為簡寫：

dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --

流程路由

透過檢查使用者是否有輸入的 .docx 檔案來決定路由：

使用者任務
├─ 無輸入檔案 → 流程 A：建立
│   訊號：「寫」、「建立」、「草擬」、「產生」、「新增」、「製作報告/提案/備忘錄」
│   → 閱讀 references/scenario_a_create.md
│
└─ 有輸入 .docx 檔案
    ├─ 取代/填寫/修改內容 → 流程 B：填寫-編輯
    │   訊號：「填寫」、「取代」、「更新」、「變更文字」、「新增章節」、「編輯」
    │   → 閱讀 references/scenario_b_edit_content.md
    │
    └─ 重新格式化/套用樣式/範本 → 流程 C：格式化-套用
        訊號：「重新格式化」、「套用範本」、「重新設定樣式」、「符合此格式」、「套模板」、「排版」
        ├─ 範本僅為樣式（無內容） → C-1：覆蓋（將樣式套用至來源）
        └─ 範本具有結構（封面/目錄/範例章節） → C-2：基底-取代
            （以範本為基底，將範例內容取代為使用者內容）
        → 閱讀 references/scenario_c_apply_template.md

若請求涵蓋多個流程，請依序執行（例如先建立再格式化-套用）。

前處理

如有需要，將 .doc 轉換為 .docx：scripts/doc_to_docx.sh input.doc output_dir/

編輯前預覽（避免讀取原始 XML）：scripts/docx_preview.sh document.docx

分析結構以進行編輯情境：$CLI analyze --input document.docx

情境 A：建立

請先閱讀 references/scenario_a_create.md、references/typography_guide.md 和 references/design_principles.md。從 Samples/AestheticRecipeSamples.cs 中選取符合文件類型的美學配方——不要自行發明格式設定值。若為中日韓（CJK）文件，也請閱讀 references/cjk_typography.md。

選擇您的路徑：

• 簡單（純文字，最少格式）：使用 CLI — $CLI create --type report --output out.docx --config content.json
• 結構性（自訂樣式、多節、目錄、圖片、複雜表格）：直接撰寫 C#。請先閱讀相關的 Samples/*.cs。

CLI 選項：--type（report|letter|memo|academic）、--title、--author、--page-size（letter|a4|legal|a3）、--margins（standard|narrow|wide）、--header、--footer、--page-numbers、--toc、--content-json。

然後執行驗證流程（如下）。

情境 B：編輯 / 填寫

請先閱讀 references/scenario_b_edit_content.md。預覽 → 分析 → 編輯 → 驗證。

選擇您的路徑：

• 簡單（文字取代、預留位置填寫）：使用 CLI 子指令。
• 結構性（新增/重新組織章節、修改樣式、操作表格、插入圖片）：直接撰寫 C#。閱讀 references/openxml_element_order.md 和相關的 Samples/*.cs。

可用的 CLI 編輯子指令：

• replace-text --find "X" --replace "Y"
• fill-placeholders --data '{"key":"value"}'
• fill-table --data table.json
• insert-section、remove-section、update-header-footer

$CLI edit replace-text --input in.docx --output out.docx --find "OLD" --replace "NEW"
$CLI edit fill-placeholders --input in.docx --output out.docx --data '{"name":"John"}'

然後執行驗證流程。同時執行 diff 以確認變更最小：

$CLI diff --before in.docx --after out.docx

情境 C：套用範本

請先閱讀 references/scenario_c_apply_template.md。預覽並分析來源與範本。

$CLI apply-template --input source.docx --template template.docx --output out.docx

對於複雜的範本操作（多範本合併、各節頁首/頁尾、樣式合併），請直接撰寫 C#——請參閱下方關鍵規則以了解必要模式。

執行驗證流程，然後執行嚴格關卡檢查：

$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd

關卡檢查是嚴格要求。在通過之前請勿交付。若失敗：診斷、修正、重新執行。

同時執行 diff 以確認內容保留：$CLI diff --before source.docx --after out.docx

驗證流程

每次寫入操作後執行。對於情境 C，完整流程是強制性的；對於 A/B 則是建議性的（僅在操作非常簡單時可跳過）。

$CLI merge-runs --input doc.docx                                    # 1. 合併 runs
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd     # 2. XSD 結構
$CLI validate --input doc.docx --business                           # 3. 業務規則

若 XSD 失敗，自動修復並重試：

$CLI fix-order --input doc.docx
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd

若 XSD 仍然失敗，則回退至業務規則加預覽：

$CLI validate --input doc.docx --business
scripts/docx_preview.sh doc.docx
# 驗證：字型污染=0、表格數量正確、繪圖數量正確、sectPr 數量正確

最終預覽：scripts/docx_preview.sh doc.docx

關鍵規則

這些規則可防止檔案損毀——OpenXML 對元素順序有嚴格要求。

元素順序（屬性永遠在前）：

父元素	順序
w:p	pPr → runs
w:r	rPr → t/br/tab
w:tbl	tblPr → tblGrid → tr
w:tr	trPr → tc
w:tc	tcPr → p（至少 1 個 <w:p/>）
w:body	區塊內容 → sectPr（最後一個子元素）

直接格式污染： 從來源文件複製內容時，內聯的 rPr（字型、顏色）和 pPr（框線、陰影、間距）會覆蓋範本樣式。務必移除直接格式——僅保留 pStyle 參考和 t 文字。表格也需清理（包括儲存格內的 pPr/rPr）。

追蹤修訂： <w:del> 使用 <w:delText>，絕不使用 <w:t>。<w:ins> 使用 <w:t>，絕不使用 <w:delText>。

字型大小： w:sz = 點數 × 2（12pt → sz="24"）。邊距/間距以 DXA 為單位（1 英吋 = 1440，1 公分 ≈ 567）。

標題樣式必須有 OutlineLevel： 定義標題樣式（Heading1、ThesisH1 等）時，務必在 StyleParagraphProperties 中包含 new OutlineLevel { Val = N }（H1→0、H2→1、H3→2）。若缺少此設定，Word 會將其視為純樣式文字——目錄和導覽窗格將無法運作。

多範本合併： 當提供多個範本檔案（字型、標題、分節）時，請先閱讀 references/scenario_c_apply_template.md 的「多範本合併」章節。關鍵規則：

• 將所有範本的樣式合併到一個 styles.xml 中。結構（章節/分節符）來自分節範本。
• 每個內容段落必須恰好出現一次——在插入分節符時絕不重複。
• 絕不插入空白/空段落作為填充或章節分隔符。輸出段落數量必須等於輸入數量。使用分節符屬性（w:pPr 內的 w:sectPr）和樣式間距（w:spacing 前/後）來進行視覺分隔。
• 在每個章節標題之前插入奇數頁分節符，而不僅僅是第一個。即使章節有雙欄內容，也必須以奇數頁開始；在標題後使用第二個連續分節符來切換欄位。
• 雙欄章節需要三個分節符：(1) 在前一段落的 pPr 中插入奇數頁分節符，(2) 在章節標題的 pPr 中插入連續分節符並設定 cols=2，(3) 在最後一個正文段落的 pPr 中插入連續分節符並設定 cols=1 以恢復。
• 從分節範本中複製每個章節的 titlePg 設定。摘要和目錄章節通常需要 titlePg=true。

多節頁首/頁尾： 具有 10 個以上章節的範本（例如中文論文）每個章節有不同的頁首/頁尾（羅馬數字與阿拉伯數字頁碼、不同區域的頁首文字）。規則：

• 使用 C-2 基底-取代：將範本複製為輸出基底，然後取代主體內容。這會自動保留所有章節、頁首、頁尾和 titlePg 設定。
• 絕不從頭建立頁首/頁尾——逐位元組複製範本的頁首/頁尾 XML。
• 絕不新增範本頁首 XML 中不存在的格式（框線、對齊、字型大小）。
• 非封面章節必須有頁首/頁尾 XML 檔案（至少包含空白頁首和頁碼頁尾）。
• 請參閱 references/scenario_c_apply_template.md 的「多節頁首/頁尾轉移」章節。

參考資料

按需載入——不要一次全部載入。選取與任務最相關的檔案。

以下 C# 範例和設計參考是專案的知識庫（「百科全書」）。 在撰寫 OpenXML 程式碼時，務必先閱讀相關的範例檔案——其中包含可編譯且經過 SDK 版本驗證的模式，可防止常見錯誤。在進行美學決策時，請閱讀設計原則和配方檔案——它們編碼了來自權威來源（IEEE、ACM、APA、Nature 等）經過測試且和諧的參數集，而非猜測。

情境指南（每個流程先閱讀）

檔案	時機
references/scenario_a_create.md	流程 A：從頭建立
references/scenario_b_edit_content.md	流程 B：編輯現有內容
references/scenario_c_apply_template.md	流程 C：套用範本格式

C# 程式碼範例（可編譯、附有大量註解——撰寫程式碼時請閱讀）

檔案	主題
Samples/DocumentCreationSamples.cs	文件生命週期：建立、開啟、儲存、串流、文件預設值、設定、屬性、頁面設定、多節
Samples/StyleSystemSamples.cs	樣式：Normal/Heading 鏈、字元/表格/清單樣式、DocDefaults、latentStyles、CJK 公文、APA 第 7 版、匯入、解析繼承
Samples/CharacterFormattingSamples.cs	RunProperties：字型、大小、粗體/斜體、所有底線、顏色、醒目提示、刪除線、下標/上標、大小寫、間距、陰影、框線、強調記號
Samples/ParagraphFormattingSamples.cs	ParagraphProperties：對齊、縮排、行距/段落間距、保持/孤行控制、大綱層級、框線、定位點、編號、雙向文字、框架
Samples/TableSamples.cs	表格：框線、格線、儲存格屬性、邊距、列高、標題重複、合併（水平+垂直）、巢狀表格、浮動表格、三線表、斑馬條紋
Samples/HeaderFooterSamples.cs	頁首/頁尾：頁碼、「第 X 頁，共 Y 頁」、首頁/偶數頁/奇數頁、標誌圖片、表格版面、公文「-X-」、各節
Samples/ImageSamples.cs	圖片：內聯、浮動、文字環繞、框線、替代文字、在頁首/表格中、取代、SVG 備援、尺寸計算
Samples/ListAndNumberingSamples.cs	編號：項目符號、多層級十進位、自訂符號、大綱→標題、法律編號、中文一/（一）/1./(1)、重新開始/繼續
Samples/FieldAndTocSamples.cs	功能變數：目錄、SimpleField 與複雜功能變數、DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF、目錄樣式
Samples/FootnoteAndCommentSamples.cs	註腳、章節附註、註解（4 檔案系統）、書籤、超連結（內部+外部）
Samples/TrackChangesSamples.cs	修訂：插入（w:t）、刪除（w:delText!）、格式變更、全部接受/拒絕、移動追蹤
Samples/AestheticRecipeSamples.cs	13 個來自權威來源的美學配方：ModernCorporate、AcademicThesis、ExecutiveBrief、ChineseGovernment（GB/T 9704）、MinimalModern、IEEE Conference、ACM sigconf、APA 第 7 版、MLA 第 9 版、Chicago/Turabian、Springer LNCS、Nature、HBR——每個都包含來自官方樣式指南的準確數值

注意：Samples/ 路徑相對於 scripts/dotnet/MiniMaxAIDocx.Core/。

Markdown 參考資料（當需要規格或設計規則時閱讀）

檔案	時機
references/openxml_element_order.md	XML 元素排序規則（防止損毀）
references/openxml_units.md	單位轉換：DXA、EMU、半點、八分之一點
references/openxml_encyclopedia_part1.md	詳細 C# 百科全書：文件建立、樣式、字元與段落格式
references/openxml_encyclopedia_part2.md	詳細 C# 百科全書：頁面設定、表格、頁首/頁尾、章節、文件屬性
references/openxml_encyclopedia_part3.md	詳細 C# 百科全書：目錄、註腳、功能變數、追蹤修訂、註解、圖片、數學、編號、保護
references/typography_guide.md	字型搭配、大小、間距、頁面版面、表格設計、色彩配置
references/cjk_typography.md	CJK 字型、字號大小、RunFonts 對應、GB/T 9704 公文標準
references/cjk_university_template_guide.md	中文大學論文範本：數值 styleId（1/2/3 與 Heading1）、文件區域結構（封面→摘要→目錄→正文→參考文獻）、字型期望、常見錯誤
references/design_principles.md	美學基礎：6 項設計原則（留白、對比/比例、接近、對齊、重複、層次）——教導 WHY，而不只是 WHAT
references/design_good_bad_examples.md	好與壞比較：10 類排版錯誤，附 OpenXML 數值、ASCII 示意圖和修正方法
references/track_changes_guide.md	修訂標記深入探討
references/troubleshooting.md	症狀導向修正：13 個常見問題，依您所見的現象索引（標題錯誤、圖片遺失、目錄損毀等）——依症狀搜尋，找到修正方法