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 的限制。使用此脚手架：

// File: scripts/dotnet/task.csx  (or a new .cs in a Console project)
// 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());

// --- Your logic here ---
// Read the relevant Samples/*.cs file FIRST for tested patterns.
// See Samples/ table in References section below.

编写任何 C# 之前，请先阅读相关的 Samples/*.cs 文件 — 其中包含可编译且已验证 SDK 版本的用法模式。下方“参考资料”部分中的 Samples 表格列出了主题与文件的对应关系。

CLI 简写

以下所有 CLI 命令均使用 $CLI 作为以下内容的简写：

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

工作流路由

通过检查用户是否提供了输入 .docx 文件来进行路由：

User task
├─ No input file → Pipeline A: CREATE
│   signals: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
│   → Read references/scenario_a_create.md
│
└─ Has input .docx
    ├─ Replace/fill/modify content → Pipeline B: FILL-EDIT
    │   signals: "fill in", "replace", "update", "change text", "add section", "edit"
    │   → Read references/scenario_b_edit_content.md
    │
    └─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY
        signals: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
        ├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)
        └─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE
            (use template as base, replace example content with user content)
        → Read references/scenario_c_apply_template.md

如果请求涉及多个工作流，请按顺序运行（例如，Create 后接 Format-Apply）。

预处理

如有需要，将 .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. consolidate runs
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd     # 2. XSD structure
$CLI validate --input doc.docx --business                           # 3. business rules

如果 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
# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct

最终预览：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 中的“Multi-Template Merge”部分。关键规则：

• 将所有模板中的样式合并到一个 styles.xml 中。结构（分节/分节符）来自分节符模板。
• 每个内容段落必须且只能出现一次——插入分节符时绝不能重复段落。
• 绝不能插入空段落作为填充或分节符分隔。输出段落数必须与输入相同。使用分节符属性（w:pPr 中的 w:sectPr）和样式间距（w:spacing 的前后间距）实现视觉分隔。
• 在每个章节标题之前插入 oddPage 分节符，而不只是第一个章节。即使章节内容为双栏，也必须以 oddPage 开始；在标题之后使用第二个 continuous 分节符切换分栏。
• 双栏章节需要三个分节符：(1) 前一段 pPr 中的 oddPage，(2) 章节标题 pPr 中的 continuous+cols=2，(3) 最后一段正文 pPr 中的 continuous+cols=1，以恢复单栏。
• 从分节符模板中复制每个分节的 titlePg 设置。摘要和目录部分通常需要 titlePg=true。

多分节页眉/页脚： 包含 10 个以上分节的模板（例如中文论文）会为不同分节设置不同的页眉/页脚（罗马数字与阿拉伯数字页码、不同区域的页眉文本）。规则：

• 使用 C-2 基础模板替换：以模板作为输出底稿，然后替换正文内容。这样会自动保留所有分节、页眉、页脚和 titlePg 设置。
• 绝不要从头重建页眉/页脚——逐字节复制模板的页眉/页脚 XML。
• 绝不要添加模板页眉 XML 中不存在的格式（边框、对齐方式、字号）。
• 非封面分节必须有页眉/页脚 XML 文件（至少包含空页眉和页码页脚）。
• 请参阅 references/scenario_c_apply_template.md 中的“Multi-Section Header/Footer Transfer”部分。

参考资料

按需加载——不要一次性全部加载。选择与任务最相关的文件。

以下 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 7th、导入、解析继承
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 7th、MLA 9th、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 项设计原则（留白、对比/比例、邻近、对齐、重复、层级）——讲解原因，而不仅是做法
references/design_good_bad_examples.md	正反对比：10 类排版错误，附 OpenXML 值、ASCII 示意图和修正方法
references/track_changes_guide.md	修订标记深入指南
references/troubleshooting.md	按症状查找修复方法：按可见问题索引的 13 个常见问题（标题错误、图片缺失、目录损坏等）——根据症状搜索并找到修复方法