minimax-docx

minimax-docx

通过 CLI 工具或基于 OpenXML SDK (.NET) 的直接 C# 脚本创建、编辑和格式化 DOCX 文档。

⚠️ 先判断：是否需要本 Skill

在开始任何操作前，先判断任务复杂度：

• 简单文档生成（报告、总结、方案、请假条等纯文本段落）→ 直接用 write_word 工具，不要继续读本 Skill。 write_word 已内置美观样式（标题颜色/字号、正文行距/字体/颜色）和支持多种预设风格。 用户说"美观""好看"时，读 styles/catalog.md 选 2-4 个风格，用 ask_user_choice 弹卡片让用户选。 第一个选项固定是 default（默认商务）。用户选完传 style 参数给 write_word 即可。

• 需要以下任一才继续本 Skill：

  • 页眉/页脚、目录、图片插入
  • 复杂表格、多节布局
  • 编辑已有 docx 文件（保留格式/批注/修订）
  • 应用模板格式化 + XSD 验证门控

执行纪律（必须遵守）

1. 只读完成任务所需的最少 reference——读完能执行就立即开始。
2. 同一 reference 文件不要重复读取（系统会拦截重复读取）。
3. 不要花多轮搜索脚本路径——scripts/ 路径在 SKILL_DIR 下，用一行命令定位。
4. 信息足够后立即执行——不要继续研究文档。
5. 若预计轮数紧张，优先输出可交付版本而非继续优化排版。

环境准备

首次使用： bash scripts/setup.sh（Windows 上使用 powershell scripts/setup.ps1，--minimal 跳过可选依赖）。

会话中首次操作： scripts/env_check.sh — 如果返回 NOT READY 则不得继续。（同一会话内的后续操作可跳过此步骤。）

快速入门：直接 C# 路径

当任务需要结构化文档操作（自定义样式、复杂表格、多节布局、页眉/页脚、目录、图片）时，直接编写 C# 而不是纠结于 CLI 限制。使用此脚手架：

// 文件：scripts/dotnet/task.csx（或 Console 项目中的新 .cs 文件）
// 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());

// --- 在此处编写你的逻辑 ---
// 首先阅读相关的 Samples/*.cs 文件以获取已验证的模式。
// 参见下方参考部分中的 Samples/ 表格。

在编写任何 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.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 段前/段后）来实现视觉分隔。
• 在每个章节标题前插入 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 等）的经过测试的和谐参数集，而非猜测。

场景指南（每个管道首先阅读）

C# 代码示例（可编译、注释详尽 — 编写代码时阅读）

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

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