| name | minimax-docx |
| license | MIT |
| metadata | {"version":"1.0.0","category":"document-processing","author":"Minimax","sources":["ECMA-376 Office Open XML File Formats","GB/T 9704-2012 公文版面布局标准","IEEE / ACM / APA / MLA / Chicago / Turabian 风格指南","Springer LNCS / Nature / HBR 文档模板"]} |
| description | 使用 OpenXML SDK (.NET) 进行专业的 DOCX 文档创建、编辑和格式化。 三种管道：(A) 从零创建新文档，(B) 在已有文档中填充/编辑内容， (C) 应用模板格式化并通过 XSD 验证门控检查。 当用户需要生成、修改或格式化 Word 文档时，必须使用此 skill—— 包括他们说"写一份报告"、"起草建议书"、"制作合同"、 "填写此表单"、"按此模板重新排版"，或任何最终输出为 .docx 文件的任务。 即使用户未明确提及 "docx"，如果任务暗示生成可打印/正式文档，也应使用此 skill。
|
| triggers | ["Word","docx","document","文档","Word文档","报告","合同","公文","排版","套模板"] |
minimax-docx
通过 CLI 工具或基于 OpenXML SDK (.NET) 的直接 C# 脚本创建、编辑和格式化 DOCX 文档。
⚠️ 先判断：是否需要本 Skill
在开始任何操作前，先判断任务复杂度：
执行纪律（必须遵守）
- 只读完成任务所需的最少 reference——读完能执行就立即开始。
- 同一 reference 文件不要重复读取（系统会拦截重复读取）。
- 不要花多轮搜索脚本路径——
scripts/ 路径在 SKILL_DIR 下，用一行命令定位。
- 信息足够后立即执行——不要继续研究文档。
- 若预计轮数紧张，优先输出可交付版本而非继续优化排版。
环境准备
首次使用： bash scripts/setup.sh（Windows 上使用 powershell scripts/setup.ps1，--minimal 跳过可选依赖）。
会话中首次操作： scripts/env_check.sh — 如果返回 NOT READY 则不得继续。（同一会话内的后续操作可跳过此步骤。）
快速入门：直接 C# 路径
当任务需要结构化文档操作（自定义样式、复杂表格、多节布局、页眉/页脚、目录、图片）时，直接编写 C# 而不是纠结于 CLI 限制。使用此脚手架：
#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());
在编写任何 C# 之前，必须先阅读相关的 Samples/*.cs 文件——它们包含可编译、经 SDK 版本验证的模式。下方参考部分的 Samples 表格将主题映射到文件。
CLI 简写
所有以下 CLI 命令使用 $CLI 作为以下命令的简写：
dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --
管道路由
通过检查用户是否有输入 .docx 文件来路由：
用户任务
├─ 无输入文件 → 管道 A：CREATE
│ 信号词："写"、"创建"、"起草"、"生成"、"新建"、"制作一份报告/建议书/备忘录"
│ → 阅读 references/scenario_a_create.md
│
└─ 有输入 .docx
├─ 替换/填充/修改内容 → 管道 B：FILL-EDIT
│ 信号词："填写"、"替换"、"更新"、"更改文本"、"添加章节"、"编辑"
│ → 阅读 references/scenario_b_edit_content.md
│
└─ 重新格式化/应用样式/模板 → 管道 C：FORMAT-APPLY
信号词："重新格式化"、"应用模板"、"重新设计样式"、"匹配此格式"、"套模板"、"排版"
├─ 模板为纯样式（无内容）→ C-1：OVERLAY（将样式应用于源文档）
└─ 模板有结构（封面/目录/示例章节）→ C-2：BASE-REPLACE
（使用模板作为基础，将示例内容替换为用户内容）
→ 阅读 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.jsoninsert-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
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
$CLI validate --input doc.docx --business
如果 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
最终预览：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，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 段前/段后）来实现视觉分隔。
- 在每个章节标题前插入 oddPage 分节符，而不仅仅是第一个。即使章节有双栏内容，也必须以 oddPage 开始；在标题后使用第二个 continuous 分节符来切换栏数。
- 双栏章节需要三个分节符：(1) 前一节段落 pPr 中的 oddPage，(2) 章节标题 pPr 中的 continuous+cols=2，(3) 最后正文段落 pPr 中的 continuous+cols=1 以恢复单栏。
- 为每个节从分节模板复制
titlePg 设置。摘要和目录节通常需要 titlePg=true。
多节页眉/页脚： 具有 10 个以上节的模板（如中文论文）每节有不同的页眉/页脚（罗马 vs 阿拉伯页码、每个区域不同的页眉文本）。规则：
- 使用 C-2 Base-Replace：将模板复制为输出基础，然后替换正文内容。这会自动保留所有节、页眉、页脚和 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 7th、导入、解析继承 |
Samples/CharacterFormattingSamples.cs | RunProperties：字体、字号、粗体/斜体、所有下划线、颜色、高亮、删除线、上标/下标、大写、间距、底纹、边框、着重号 |
Samples/ParagraphFormattingSamples.cs | ParagraphProperties：对齐、缩进、行距/段距、与下段同页/孤行控制、大纲级别、边框、制表位、编号、双向文本、框架 |
Samples/TableSamples.cs | 表格：边框、网格、单元格属性、边距、行高、标题重复、合并（水平+垂直）、嵌套、浮动、三线表、斑马条纹 |
Samples/HeaderFooterSamples.cs | 页眉/页脚：页码、"第 X 页 共 Y 页"、首页/偶数/奇数页、logo 图片、表格布局、公文 "-X-"、每节独立 |
Samples/ImageSamples.cs | 图片：内嵌、浮动、文字环绕、边框、替代文本、页眉/表格中、替换、SVG 回退、尺寸计算 |
Samples/ListAndNumberingSamples.cs | 编号：项目符号、多级十进制、自定义符号、大纲→标题、法律编号、中文 一/（一）/1./(1)、重新开始/继续 |
Samples/FieldAndTocSamples.cs | 域：TOC、SimpleField vs 复杂域、DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF、TOC 样式 |
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# 百科全书：TOC、脚注、域、修订追踪、批注、图片、数学公式、编号、保护 |
references/typography_guide.md | 字体配对、字号、间距、页面布局、表格设计、配色方案 |
references/cjk_typography.md | CJK 字体、字号、RunFonts 映射、GB/T 9704 公文标准 |
references/cjk_university_template_guide.md | 中国大学论文模板：数字 styleIds（1/2/3 vs Heading1）、文档区域结构（封面→摘要→目录→正文→参考文献）、字体预期、常见错误 |
references/design_principles.md | 美学基础：6 项设计原则（留白、对比/比例、邻近、对齐、重复、层级）——教你"为什么"，而不仅仅是"是什么" |
references/design_good_bad_examples.md | 好坏对比：10 类排版错误，含 OpenXML 值、ASCII 模拟图和修复方案 |
references/track_changes_guide.md | 修订标记深入详解 |
references/troubleshooting.md | 按症状驱动修复：13 个常见问题，按你看到的症状索引（标题错误、图片缺失、TOC 损坏等）——按症状搜索，找到修复方案 |
