需要生成/修改/格式化 Word DOCX 时，用…

当最终输出为 .docx 或需要正式可打印文档（报告、合同、公文、表单、套模板排版）时，按创建、填充编辑、套模板三条流水线处理。

适用场景

解决思路

1. 首次使用运行 `bash scripts/setup.sh`；Windows 用 `powershell scripts/setup.ps1`；可加 `--minimal` 跳过可选依赖。
2. 会话中首次操作运行 `scripts/env_check.sh`，如果输出 `NOT READY` 则不要继续；同一会话后续操作可跳过。
3. 当任务需要结构化文档操作（自定义样式、复杂表格、多节布局、页眉/页脚、目录、图片）时，直接写 C#，不要受 CLI 限制。
4. 使用脚手架：`scripts/dotnet/task.csx`（或 Console 项目中的新 .cs），通过 `dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx` 运行。
5. 在 C# 中引入 `#r "nuget: DocumentFormat.OpenXml, 3.2.0"` 及所需 using。
6. 写任何 C# 前先阅读相关的 `Samples/*.cs` 文件；它们包含可编译且 SDK 版本验证过的模式，References 中的 Samples 表把主题映射到文件。
7. 所有 CLI 命令用 `$CLI` 简写替代 `dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --`。
8. 按输入文件路由：无输入 .docx 走 Pipeline A: CREATE，信号词 `write`、`create`、`draft`、`generate`、`new`、`make a report/proposal/memo`，读取 `references/scenario_a_create.md`。
9. 有输入 .docx 且要替换/填充/修改内容走 Pipeline B: FILL-EDIT，信号词 `fill in`、`replace`、`update`、`change text`、`add section`、`edit`，读取 `references/scenario_b_edit_content.md`。
10. 有输入 .docx 且要重新格式化/应用样式/模板走 Pipeline C: FORMAT-APPLY，信号词 `reformat`、`apply template`、`restyle`、`match this format`、`套模板`、`排版`；纯样式模板走 C-1: OVERLAY（应用样式到源文件），有结构模板（封面/目录/示例章节）走 C-2: BASE-REPLACE（以模板为基础，替换示例内容为用户内容）；读取 `references/scenario_c_apply_template.md`。
11. 如果请求跨多个流水线，按顺序运行（例如先 Create 再 Format-Apply）。
12. 需要时把 `.doc` 转成 `.docx`：`scripts/doc_to_docx.sh input.doc output_dir/`。
13. 编辑前预览以避免读原始 XML：`scripts/docx_preview.sh document.docx`。
14. 为编辑场景分析结构：`$CLI analyze --input document.docx`。
15. Scenario A 创建时，先读取 `references/scenario_a_create.md`、`references/typography_guide.md`、`references/design_principles.md`。
16. 从 `Samples/AestheticRecipeSamples.cs` 中选择与文档类型匹配的审美配方，不要自行发明格式值。
17. 如果是 CJK 文档，还要读取 `references/cjk_typography.md`。
18. Scenario A 选择路径：简单（纯文本、最少格式）用 CLI `$CLI create --type report --output out.docx --config content.json`；结构化（自定义样式、多节、目录、图片、复杂表格）直接写 C#，先读相关 `Samples/*.cs`。
19. Scenario A 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`。
20. Scenario A 完成后运行验证流水线。
21. Scenario B 编辑/填充时，先读取 `references/scenario_b_edit_content.md`；按预览 → 分析 → 编辑 → 验证顺序操作。
22. Scenario B 选择路径：简单（文本替换、占位符填充）用 CLI 子命令；结构化（添加/重组章节、修改样式、操作表格、插入图片）直接写 C#，先读 `references/openxml_element_order.md` 和相关 `Samples/*.cs`。
23. Scenario B 可用 CLI 编辑子命令：`replace-text --find "X" --replace "Y"`、`fill-placeholders --data '{"key":"value"}'`、`fill-table --data table.json`、`insert-section`、`remove-section`、`update-header-footer`。
24. Scenario B 示例：`$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"}'`。
25. Scenario B 编辑后运行验证流水线，并运行 diff 验证最小变更：`$CLI diff --before in.docx --after out.docx`。
26. Scenario C 应用模板时，先读取 `references/scenario_c_apply_template.md`；预览并分析源文件和模板。
27. Scenario C 运行 `$CLI apply-template --input source.docx --template template.docx --output out.docx`。
28. 复杂模板操作（多模板合并、按节页眉/页脚、样式合并）直接写 C#；参见 Critical Rules 中的必需模式。
29. Scenario C 运行验证流水线，然后运行硬性 gate-check：`$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd`；gate-check 是硬性要求，未通过前不要交付；如果失败则诊断、修复、重新运行。
30. Scenario C 同时运行 diff 验证内容保留：`$CLI diff --before source.docx --after out.docx`。
31. 每次写操作后运行验证流水线；Scenario C 的完整流水线是强制的，A/B 是推荐的（仅当操作非常简单时可跳过）：先 `$CLI merge-runs --input doc.docx` 合并 run，再 `$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd` 检查 XSD 结构，再 `$CLI validate --input doc.docx --business` 检查业务规则。
32. 如果 XSD 失败，自动修复并重试：`$CLI fix-order --input doc.docx`，然后 `$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd`。
33. 如果 XSD 仍然失败，回退到业务规则加预览：`$CLI validate --input doc.docx --business`，`scripts/docx_preview.sh doc.docx`；验证字体污染=0、表格数正确、绘图数正确、sectPr 数正确。
34. 最终预览：`scripts/docx_preview.sh doc.docx`。
35. 元素顺序规则（防止文件损坏，属性总是在前）：`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`（最后一个子元素）。
36. 避免直接格式污染：从源文档复制内容时，内联 `rPr`（字体、颜色）和 `pPr`（边框、底纹、间距）会覆盖模板样式；始终删除直接格式，只保留 `pStyle` 引用和 `t` 文本；表格也要清理（包括单元格内的 `pPr/rPr`）。
37. 修订跟踪：`<w:del>` 使用 `<w:delText>`，绝不用 `<w:t>`；`<w:ins>` 使用 `<w:t>`，绝不用 `<w:delText>`。
38. 字号：`w:sz` = 磅值 × 2（12pt → `sz="24"`）；边距/间距使用 DXA（1 英寸 = 1440，1cm ≈ 567）。
39. 标题样式必须有 OutlineLevel：定义标题样式（Heading1、ThesisH1 等）时，始终在 `StyleParagraphProperties` 中包含 `new OutlineLevel { Val = N }`（H1→0，H2→1，H3→2）；否则 Word 会将其视为普通样式文本，目录和导航窗格无法工作。
40. 多模板合并：当给定多个模板文件（字体、标题、分节符）时，先阅读 `references/scenario_c_apply_template.md` 的 `Multi-Template Merge` 部分；将所有模板的样式合并到一个 styles.xml，结构（节/分节符）来自分节符模板。
41. 多模板合并时，每个内容段落必须正好出现一次——插入分节符时绝不重复。
42. 多模板合并时，绝不插入空/空白段落作为填充或分节分隔符；输出段落数必须等于输入；使用节属性（`w:pPr` 内的 `w:sectPr`）和样式间距（`w:spacing` before/after）实现视觉分隔。
43. 多模板合并时，在每个章节标题前插入 oddPage 分节符，而不仅是第一个；即使某章节有双栏内容，也必须以 oddPage 开始，在标题后使用第二个连续分节符切换栏。
44. 双栏章节需要三个分节符：(1) 前一 paras 的 pPr 中 oddPage，(2) 章节标题的 pPr 中 continuous+cols=2，(3) 最后一个正文段落的 pPr 中 continuous+cols=1 以还原。
45. 多模板合并时，对每个节从分节符模板复制 `titlePg` 设置；摘要和目录节通常需要 `titlePg=true`。
46. 多节页眉/页脚：有 10+ 节的模板（例如中文学位论文）每节有不同页眉/页脚（罗马 vs 阿拉伯页码，不同区域不同页眉文本）；使用 C-2 Base-Replace：复制模板作为输出基础，然后替换正文内容，这会自动保留所有节、页眉、页脚和 titlePg 设置。
47. 多节页眉/页脚时，绝不从头重建页眉/页脚——逐字节复制模板页眉/页脚 XML。
48. 多节页眉/页脚时，绝不添加模板页眉 XML 中不存在的格式（边框、对齐、字号）。
49. 多节页眉/页脚时，非封面节必须有页眉/页脚 XML 文件（至少空页眉 + 页码页脚）。
50. 多节页眉/页脚更多细节参见 `references/scenario_c_apply_template.md` 的 `Multi-Section Header/Footer Transfer` 部分。
51. 参考文件按需加载，不要一次性全加载；选择与任务最相关的文件。
52. C# 示例和设计参考是项目知识库（“百科全书”）：写 OpenXML 代码时始终先读相关示例文件，它们包含可编译、SDK 版本验证过的模式，可防止常见错误；做审美决策时阅读设计原则和配方文件，它们编码了来自权威来源（IEEE、ACM、APA、Nature 等）的经过测试的和谐参数集，而不是猜测。
53. 场景指南先读：`references/scenario_a_create.md` 对应 Pipeline A 从零创建；`references/scenario_b_edit_content.md` 对应 Pipeline B 编辑现有内容；`references/scenario_c_apply_template.md` 对应 Pipeline C 应用模板格式。
54. C# 代码示例（可编译、大量注释，写代码时读）：`Samples/DocumentCreationSamples.cs` 文档生命周期：创建、打开、保存、流、文档默认值、设置、属性、页面设置、多节；`Samples/StyleSystemSamples.cs` 样式：Normal/Heading 链、字符/表格/列表样式、DocDefaults、latentStyles、CJK 公文、APA 7th、导入、解析继承；`Samples/CharacterFormattingSamples.cs` RunProperties：字体、字号、粗体/斜体、所有下划线、颜色、高亮、删除线、上下标、大写、间距、底纹、边框、着重号；`Samples/ParagraphFormattingSamples.cs` ParagraphProperties：对齐、缩进、行/段间距、keep/widow、大纲级别、边框、制表位、编号、双向、框架；`Samples/TableSamples.cs` 表格：边框、网格、单元格属性、边距、行高、表头重复、合并（水平+垂直）、嵌套、浮动、三线表、斑马纹；`Samples/HeaderFooterSamples.cs` 页眉/页脚：页码、`第 X 页，共 Y 页`、首页/偶数/奇数页、logo 图片、表格布局、公文 `-X-`、按节；`Samples/ImageSamples.cs` 图片：内联、浮动、文字环绕、边框、替代文本、页眉/表格中的图片、替换、SVG 回退、尺寸计算；`Samples/ListAndNumberingSamples.cs` 编号：项目符号、多级十进制、自定义符号、大纲→标题、法律、中文 一/（一）/1./(1)、重新开始/继续；`Samples/FieldAndTocSamples.cs` 域：目录、SimpleField vs 复杂域、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/`。
55. 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` 中文学位论文模板：数字 styleIds（1/2/3 vs Heading1）、文档区域结构（封面→摘要→目录→正文→参考文献）、字体期望、常见错误；`references/design_principles.md` 审美基础：6 项设计原则（留白、对比/缩放、亲密性、对齐、重复、层次）——教 WHY，不只是 WHAT；`references/design_good_bad_examples.md` 好 vs 坏对比：10 类排版错误及 OpenXML 值、ASCII 示意图和修复；`references/track_changes_guide.md` 修订标记深入；`references/troubleshooting.md` 症状驱动修复：13 个常见问题按你看到的现象索引（标题错误、图片缺失、目录损坏等）——按症状搜索，找到修复。

适用边界 · 注意事项

• 最终输出不是 .docx 或不需要 Word 正式可打印文档时，不适用（例如只需要 Markdown、HTML、PDF 或其他非 DOCX 格式）。
• 没有 .NET/OpenXML SDK 环境且无法运行 `scripts/setup.sh` 或 `scripts/setup.ps1` 时，不适用。
• 只需要极简文本修改且不关心 Word 排版、样式、模板或验证时，可不用此技能。