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"}'

然后运行验证流水线。同时运行差异比较以验证最小更改：

$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

关卡检查是硬性要求。在通过之前不要交付。如果失败：诊断、修复、重新运行。

同时运行差异比较以验证内容保留：$CLI diff --before source.docx --after out.docx

验证流水线

每次写入操作后运行。对于场景 C，完整流水线是强制性的；对于 A/B，是推荐的（仅当操作非常简单时可以跳过）。

$CLI merge-runs --input doc.docx                                    # 1. 合并运行
$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 → 运行
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，1cm ≈ 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 中的连续+分栏=2 分节符，(3) 最后一个正文段落 pPr 中的连续+分栏=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	中国大学学位论文模板：数字样式 ID（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 个常见问题，按所见内容索引（标题错误、图片缺失、目录损坏等）— 按症状搜索，找到修复方法