docx-creator

DOCX 创建器

基于 minimax-skills:minimax-docx 的轻量增量层。不是文档引擎。

请先阅读此处。 OpenXML SDK 的功能由 minimax-docx 提供。本技能不包含任何引擎代码。这里包含的是经过一整场调试才总结出的经验：引擎的 CLI 在何处开始变得不再实用，如何正确使用其 SDK 编写中文正式文档，以及如何验证输出，避免交付一份看起来正常、但在 Word 中却有问题的文件。

分工

层	归属	内容
OpenXML SDK（DocumentFormat.OpenXml）、WordprocessingDocument API、XSD 验证器、样式模板、OpenXML 百科	minimax-skills:minimax-docx	引擎和参考文档。此处绝不重复。
CLI 的表达能力上限，以及何时应改用 C#	本技能	ISSUE-001、ISSUE-002
经验证的中文正式文档 Markdown 转 DOCX 生成器	本技能	scripts/Program.cs
使用 OpenXML 时容易出错的中文正式文档排版规则	本技能	以下硬性规则 + ISSUE-004…007
真实的端到端视觉验证流程	本技能	references/verification_protocol.md

在市场安装路径中查找引擎，通常位于 ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/。

涉及本技能未涵盖的结构时，请直接查阅 minimax-docx，例如图片、修订、批注、目录、多分节布局、模板应用。其 minimax-docx/references/ 文件夹（cjk_typography.md、openxml_element_order.md、 openxml_units.md、troubleshooting.md）以及 Samples/*.cs 是 SDK 用法的权威参考。不要在此重复造轮子。

路由：此文档应选择哪条路径？

情况	路径
中文合同／协议／公文／任何包含甲乙方信息栏、编号条款、签名栏或表格的文档	通过 scripts/Program.cs 使用 C# OpenXML（本技能）
纯文本，只有标题和段落，不含粗体／列表／表格	minimax-docx CLI 的 create --content-json 即可
填写或编辑现有 .docx	minimax-docx 流程 B（edit-content），加上本技能的布局和验证指南
匹配现有 .docx 的格式	minimax-docx 流程 C（apply-template）
现有 Word/WPS → 修复布局／选定内容 → PDF	保留 Word 源文件；遵循 references/word-to-pdf.md 和 references/verification_protocol.md
Markdown → PDF	daymade-docs:pdf-creator

经验法则：CLI 的 --content-json 只支持三种块类型 （heading、paragraph、pagebreak）。粗体、列表、表格、边框、页脚、字体、 对齐方式——这些都无法表达。中文合同需要这些格式。参见 ISSUE-001。

快速开始

生成器读取 Markdown 并写入格式化的 .docx。将其复制到文档旁边，以便构建产物留在技能目录之外：

# 1. Stage the generator beside your markdown
mkdir -p _docxgen && cp <skill-dir>/scripts/Program.cs <skill-dir>/scripts/mmdocx-gen.csproj \
   <skill-dir>/scripts/.gitignore _docxgen/

# 2. Generate (first run restores DocumentFormat.OpenXml + Markdig, ~20s)
dotnet run --project _docxgen -- your-doc.md your-doc.docx

# 3. Structural validation via the engine's XSD validator (note the roll-forward env — ISSUE-003)
DOTNET_ROLL_FORWARD=Major dotnet run \
  --project ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Cli \
  -- validate --input your-doc.docx

# 4. MANDATORY visual verification — never skip, never substitute qlmanage
soffice --headless --convert-to pdf --outdir /tmp/docxcheck your-doc.docx
pdftoppm -png -r 100 /tmp/docxcheck/your-doc.pdf /tmp/docxcheck/page
# then Read every /tmp/docxcheck/page-NN.png

# 5. MANDATORY if Microsoft Word.app is installed — LibreOffice cannot see ISSUE-012
open -a "Microsoft Word" your-doc.docx   # check the title bar for "兼容性模式", check every page

完整的命令详情和故障排查：scripts/README.md。 完整的验证步骤和通过／失败标准：references/verification_protocol.md。

硬性规则（违反这些规则意味着返工）

1. 对齐分层处理——这是最费功夫的部分

不要对整个文档设置两端对齐。分为三层，分别设置对齐方式：

内容	对齐方式	原因
文档标题（H1）	居中	惯例
条款标题（H2+）	左对齐	惯例
信息块和签名块——甲方/乙方/统一社会信用代码/法定代表人/日期，即任何各行之间以 Markdown 软换行或硬换行连接的段落	左对齐	两端对齐会拉伸段落最后一行以外的每一行。多行信息块是一个段落，因此除最后一行外，其他行的字符间距都会被拉得极大。
普通正文	两端对齐（Both）	右边缘整齐

这条规则可以通过机器检查，所以不要凭目测判断：如果 Markdown 段落的内联树中 包含 LineBreakInline，就将该段落设为左对齐；否则设为两端对齐。该逻辑实现在 Main 的块分派 switch 中 case ParagraphBlock p: 分支，换行检测则在 InlineRuns 中。（这里有意不提供行号——文件增长时行号会不断变化；请改查 scripts/README.md 中的函数名索引表。）完整说明：ISSUE-004。

2. 独立列表重新编号；续接列表保留编号

每个独立的 Markdown 列表都必须有自己的 NumId，并带有一个 StartOverrideNumberingValue = 1 的 LevelOverride。在不同条款间复用一个 NumId，条款 3 的列表就会 悄悄从 4 开始。相关实现位于 case ListBlock lb: 分支和 NumberingDefinitionsPart 设置中——这两处都可查阅 scripts/README.md 的索引表。 还要注意两个 SDK 陷阱（类名错误、元素顺序错误）——ISSUE-005、ISSUE-006。 对于现有 Word 列表，要保留有意续接的编号。更改几何属性前，先解析 numId 及其级别； numId=0 表示禁用编号。手动输入的序号是文本，不是自动编号列表。参见 ISSUE-016。

3. 中日韩字体需要设置两个字体槽

一个 run 必须设置 RunFonts { Ascii, HighAnsi, EastAsia }。只设置拉丁文字体槽会让 Word 使用回退字体显示中文字符，文档最终使用哪种字体取决于读者的设备。随附的默认字体： 拉丁文字体为 Times New Roman；正文的东亚字体为宋体，标题为黑体。中文粗体 run 会切换为黑体——宋体没有真正的粗体字重，渲染器合成的粗体会让笔画繁多的字符显得模糊（ISSUE-014）。字号单位为 OpenXML 半磅——正文为 21（10.5pt，常见的中文稿件字号），H1 为 36（18pt），条款标题为 28（14pt）。正文段落还会设置 2 个字符的首行缩进（10.5pt 时为 420 twips——更改时需与正文字号同步）。ISSUE-007。

4. 页面与表格基础设置

A4 页面尺寸为 11906 × 16838 twips，页边距为 1440 twip；页码放在居中的页脚 PAGE 字段中。表格需要设置全部六种边框（top/bottom/left/right/insideH/insideV， 顺序必须符合 ECMA-376 规范——ISSUE-013），还需要 tblGrid（ISSUE-012）——设置的边框较少，打印时单元格会显得没有边框；省略 tblGrid 则文件无法通过严格验证，即使 LibreOffice 不会显示这个问题。相关实现位于 BuildTable 以及 Main 中的 SectionProperties/FooterPart 设置部分——请查阅 scripts/README.md 的索引表。

验证不容忽视

禁止：将 qlmanage 缩略图用作视觉证明。 macOS Quick Look 使用的渲染引擎与 Word 不同，即使文档的信息块被拉开，也会轻易呈现出页面看起来很正常的假象。曾有人根据 qlmanage 的证据宣布文档“验证完美”，但文档在 Word 中打开后却已损坏——这就是本规则的由来。ISSUE-008。

**必须遵循的流程：**生成 → XSD 验证 → soffice --headless --convert-to pdf → pdftoppm -png → 使用 Read 检查每一页图像 → 检查五种故障模式（信息块未被拉开 / 每个列表都从 1 重新开始 / 表格边框存在 / 签名块完整 / 没有分页孤行）→ 如果已安装 Microsoft Word.app，就在其中打开实际文件，检查标题栏是否显示“兼容性模式”，并检查每一页。详情、前提条件以及“哪些情况算故障”列表：references/verification_protocol.md。

LibreOffice 渲染正常，不等于“Word 能正确渲染此文件”。 ISSUE-012 是一个真实且已复现的案例：文件通过了此流程中所有基于 LibreOffice 的检查——信息块整洁、编号正确、表格完整——但在真正的 Word 中打开后，标题栏仍显示“兼容性模式”，且原本从未设置任何编号的段落上出现了多余的项目符号标记。LibreOffice 没有等效的回退路径，在结构上无法发现这一类缺陷。这是 ISSUE-008 的教训（宽松的渲染器会掩盖 Word 的实际表现）在更高一层再次出现；只要可以直接用 Word 检查，就应将仅依赖 LibreOffice 的验证视为不完整。

**覆盖已交付的 .docx 前，**检查是否存在同级文件 ~$<name>.docx——这是 Word 的所有者锁，表示接收者仍打开着旧版本。覆盖操作可以成功，但对方关闭并重新打开文件前，仍会看到过时的文档。请告知对方。ISSUE-011。

自定义

scripts/Program.cs 大约有 260 行直观易懂的 OpenXML 代码。直接编辑它来修改字体、字号、间距、边框或添加新的块类型——这就是预期的工作方式。在添加结构性功能（图像、目录、页眉、修订）之前，请先阅读 minimax-docx 中对应的 Samples/*.cs；这些模式已经过 SDK 版本验证，可以避免反复经历编译错误。

如果向 RunProperties、ParagraphProperties、TableProperties、TableCellProperties 或 TableBorders 添加新属性，该属性必须按照 ECMA-376 中该父级元素的子元素顺序放置，而不能按 C# 中 .Append() 看起来自然的位置来放。 这不是风格偏好——位置不对就会重现 ISSUE-012/ISSUE-013：minimax-docx validate 仍会报告 PASSED，LibreOffice 仍会将文件渲染得很正常，但真正的 Word 打开文件时仍会进入“兼容性模式”，并在文档中散布未经请求的格式设置。当前代码已在每个构造位置（RunProps、Para、BuildTable）附有架构顺序注释——应在原有属性列表中就地扩展，而不是在列表后追加；如果要添加真正的新元素，则应先在 openxml_element_order.md（minimax-docx）中查明其位置，再决定 .Append() 调用的放置位置。每次进行此类更改后，都要重新运行验证协议的第 3a 步（使用真正的 Word，而不只是 LibreOffice）——这是整个流程中唯一能发现此类错误的检查。

参考资料

• references/word-to-pdf.md — 现有 Word 源文件、摘录选择、接受修订、版式修复和 PDF 交付；不进行 Markdown 往返转换。
• references/known_issues.md — 构建此流程时遇到的每个陷阱的症状 / 根本原因 / 修复方法 / 验证方式。开始调试前请先阅读。
• references/verification_protocol.md — 完整的端到端验证流程、前提条件、通过标准以及禁止采用的替代方案。
• scripts/README.md — 生成器的运行方法、支持的 Markdown 内容和环境要求。