在编写任何 C# 代码之前，请先阅读相关的 Samples/*.cs 文件 — 它们包含可编译、经过 SDK 版本验证的模式。下方“参考资料”部分的 Samples 表格将主题映射到文件。

CLI 简写

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

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

流程路由

通过检查以下条件进行路由：用户是否有输入的 .docx 文件？

用户任务
├─ 无输入文件 → 流程 A：创建
│   信号："write", "create", "draft", "generate", "new", "make a report/proposal/memo"
│   → 阅读 references/scenario_a_create.md
│
└─ 有输入 .docx 文件
    ├─ 替换/填充/修改内容 → 流程 B：填充-编辑
    │   信号："fill in", "replace", "update", "change text", "add section", "edit"
    │   → 阅读 references/scenario_b_edit_content.md
    │
    └─ 重新格式化/应用样式/模板 → 流程 C：格式化-应用
        信号："reformat", "apply template", "restyle", "match this format", "套模板", "排版"
        ├─ 模板是纯样式（无内容） → 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"}'

然后运行验证流程。同时运行 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                                    # 1. 合并 runs
$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 对元素顺序有严格要求。

元素顺序（属性始终在前）：

直接格式污染： 从源文档复制内容时，内联的 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 的 before/after）进行视觉分隔。
• 在每个章节标题前插入 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 中的“多节页眉/页脚转移”部分。

参考资料

按需加载 — 不要一次性加载所有内容。为任务选择最相关的文件。

下面的 C# 示例和设计参考资料是项目的知识库（“百科全书”）。 编写 OpenXML 代码时，始终首先阅读相关的示例文件 — 它包含可编译、经过 SDK 版本验证的模式，可防止常见错误。进行美学决策时，阅读设计原则和配方文件 — 它们编码了来自权威来源（IEEE、ACM、APA、Nature 等）的经过测试、和谐的参数集，而不是猜测。

场景指南（每个流程首先阅读）

C# 代码示例（可编译，有详细注释 — 编写代码时阅读）

注意：Samples/ 路径相对于 scripts/dotnet/MiniMaxAIDocx.Core/。

Markdown 参考资料（需要规范或设计规则时阅读）

每周安装次数

126

仓库

minimax-ai/skills

GitHub 星标

3.5K

首次出现

3 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

codex123

cursor122

opencode122

cline121

gemini-cli121

kimi-cli121