对于 .doc（旧格式），首先使用 libreoffice --headless --convert-to docx 进行转换。

第二部分：执行

文件结构

docx/
├── SKILL.md                      ← 此文件（入口点 + 参考）
├── references/
│   └── EditingGuide.md           → 完整的 Python 编辑教程（评论、修订跟踪、5 文件同步）
├── scripts/
│   ├── docx                      → 统一入口（唯一需要调用的脚本）
│   ├── fix_element_order.py      → 自动修复 XML 元素顺序
│   ├── validate_docx.py          → 业务规则验证
│   ├── generate_backgrounds.py       → 莫兰迪风格背景
│   ├── generate_inkwash_backgrounds.py → 水墨风格背景
│   └── generate_chart.py         → matplotlib（仅用于热图/3D/雷达图；简单图表必须使用原生）
├── assets/
│   └── templates/
│       ├── KimiDocx.csproj       → 项目文件模板（用于创建新文档）
│       ├── Program.cs            → 程序入口模板
│       ├── Example.cs            → 完整示例（封面+目录+图表+封底）
│       ├── CJKExample.cs         → CJK 内容模式（引号转义、字体）
│       └── xml/                  → 评论基础设施的 XML 模板
└── validator/                    → OpenXML 验证器（预编译二进制文件，AI 不修改）

创建新文档：使用 C# SDK 配合 ./scripts/docx build → 查看 Example.cs 了解模式，CJKExample.cs 了解 CJK 内容 编辑现有文档：使用 Python + lxml → 查看 references/EditingGuide.md 获取完整教程

⚠️ 切勿混合使用这些方法。 C# SDK 用于创建，Python 用于编辑。切勿使用 python-docx/docx-js。

环境设置

首次使用时，在 SKILL 目录中执行：

cd /app/.kimi/skills/kimi-docx/
./scripts/docx init

固定路径约定（不可更改）：

脚本命令 (./scripts/docx <cmd>)：

脚本自动处理：

• 检测 dotnet/python3（必需），pandoc/playwright/matplotlib（可选）
• 已安装 → 直接使用；未安装 → 自动安装；损坏 → 修复
• 初始化工作目录，复制模板文件

构建流程

必须使用./scripts/docx build，不要单独执行 dotnet build && dotnet run（会跳过验证）。

Program.cs 输出路径约定（关键）

Program.cs 必须从命令行参数获取输出路径，否则构建脚本无法找到生成的文件：

// 正确 - 从命令行参数获取输出路径
string outputFile = args.Length > 0 ? args[0] : "/mnt/okcomputer/output/output.docx";

// 错误 - 硬编码路径导致构建失败
string outputFile = "my_document.docx";  // 脚本找不到文件！

验证是必需的：失败时，文件会被保留但会显示警告。检查错误信息以修复问题。

独立验证

cd /app/.kimi/skills/kimi-docx/
./scripts/docx validate /mnt/okcomputer/output/report.docx

内容验证（必需）

pandoc 是唯一真相来源。 OpenXML 验证器检查结构；pandoc 显示实际内容。

交付前，使用 pandoc 验证：

• pandoc output.docx -t plain — 检查文本完整性
• 对于修订/评论：添加 --track-changes=all 以验证标记位置

⚠️ 关键：comments.xml 存在 ≠ 评论可见。计数不匹配 = doc_tree 未保存。参见 references/EditingGuide.md §5.3。

第三部分：质量标准

交付标准

通用样式和中等审美 = 中等交付。

交付具有工作室品质的 Word 文档，深入思考内容、功能和样式。用户通常不会明确要求高级功能（封面、目录、背景、封底、脚注、图表）— 深刻理解需求并主动扩展。

语言一致性

文档语言 = 用户对话语言（包括文件名、正文、标题、页眉、目录提示、图表标签以及所有其他文本）。

页眉和页脚 - 默认必需

大多数文档必须包含页眉和页脚。具体样式（对齐方式、格式、内容）应与文档的整体设计相匹配。

• 页眉：通常是文档标题、公司名称或章节名称
• 页脚：通常是页码（格式灵活："X / Y"、"第 X 页"、"— X —" 等）
• 封面/封底：使用 TitlePage 设置隐藏首页的页眉/页脚

专业元素（关键）

创建超出用户期望的文档，主动添加专业元素，不要等待用户要求。交付标准：2024 年顶级设计师的视觉质量。

封面与视觉：

• 正式文档（提案、报告、财务、投标、合同）/ 创意文档（邀请函、贺卡）必须有封面和封底
• 封面必须有设计师品质的背景图片
• 正文页面可选择包含背景以增强视觉吸引力

结构：

• 长文档（3 个以上章节）添加目录，必须在目录后添加刷新提示

数据呈现：

• 比较数据或显示趋势时，使用图表而非纯文本列表
• 表格使用浅灰色表头或三线样式，避免 Word 默认的蓝色

链接与引用：

• URL 必须是可点击的超链接
• 多个图/表添加编号和交叉引用（"见图 1"、"如表 2 所示"）
• 学术/法律/数据分析引用场景实现正确的文内点击跳转引用及相应的脚注/尾注

目录刷新提示

Word 目录是域代码，生成时页码可能不准确。必须在目录后添加灰色提示文本，告知用户手动刷新：

Table of Contents
─────────────────
Chapter 1 Overview .......................... 1
Chapter 2 Methods ........................... 3
...

(提示：首次打开时，右键点击目录并选择"更新域"以显示正确的页码)

提示文本要求：

• 视觉上不显眼 — 灰色、较小字体，不应与实际目录条目竞争
• 语言：与用户对话语言一致

仅当用户明确要求时

图表选择策略（关键）

默认使用原生 Word 图表，可编辑、文件小、专业。

原生图表是首选（可编辑、文件更小），但对于数据分析场景，matplotlib 是可接受的。

插入图片/图表

任何 PNG（matplotlib 图表、背景、照片）必须使用 AddInlineImage() 插入：

AddInlineImage(body, mainPart, "/path/to/image.png", "Description", docPrId++);

关键：

• 图表标签/标题必须与文档语言匹配（例如，中文文档使用中文标签）
• 构建输出显示 X images — 如果为 0，则图片未插入

内容约束

字数/页数要求

禁止：用过多的项目符号列表填充字数。保持信息密度。

大纲遵循

• 用户提供大纲：严格遵守，不增、不减、不重排
• 未提供大纲：使用标准结构
  • 学术：引言 → 文献综述 → 方法 → 结果 → 讨论 → 结论
  • 商业：执行摘要 → 分析 → 建议
  • 技术：概述 → 原理 → 用法 → 示例 → 常见问题

场景完整性

比用户多想一步，完成场景所需的元素。以下示例并非详尽 — 将此原则应用于所有文档类型：

• 试卷 → 姓名/班级/ID 填写区域、每题分值（考虑总分）、评分区
• 合同 → 双方签字盖章区域、日期、合同编号、附件列表
• 会议纪要 → 出席者、缺席者、带负责人的行动项、下次会议时间

设计理念

配色方案

低饱和度色调，避免 Word 默认蓝色和 matplotlib 默认高饱和度。

根据文档场景灵活选择配色方案：

同一文档内配色方案必须一致。

布局

留白（边距、段落间距）、清晰的层次结构（H1 > H2 > 正文）、适当的填充（文本不应触及边框）。

分页控制

Word 使用流式布局，而非固定页面。使用以下属性控制分页：

// 示例：H1 始终从新页开始，并与下段同页
new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new PageBreakBefore(),
    new KeepNext(),
    new KeepLines()
)

表格分页：

// 允许行跨页断开（避免大块空白区域）
new TableRowProperties(
    new CantSplit { Val = false }  // false = 可以拆分
)

// 每页重复表头行
new TableRowProperties(
    new TableHeader()
)

第四部分：技术参考

选择你的路径：

4.1 SDK 基础

模式合规性（记住这些）

OpenXML 有严格的元素顺序要求。顺序错误 = Word 无法打开文件。

必需样式

// Normal 样式必须存在 - 所有 Heading 样式都使用 basedOn="Normal"
styles.Append(new Style(
    new StyleName { Val = "Normal" },
    new StyleParagraphProperties(
        new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
    ),
    new StyleRunProperties(
        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
        new FontSize { Val = "22" },
        new FontSizeComplexScript { Val = "22" }
    )
) { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });

元素顺序规则

大多数排序问题由 fix_element_order.py 自动修复。需要记住的关键规则：

表格必须有 tblGrid

// 正确 - 表格必须定义网格
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableGrid(           // 必需！
    new GridColumn { Width = "4680" },
    new GridColumn { Width = "4680" }
));
table.Append(new TableRow(...));

// 错误 - 缺少 tblGrid，Word 无法打开
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableRow(...));  // 直接添加行

表格列宽一致性

表格扭曲的主要原因：tblGrid 中的 gridCol 宽度与单元格的 tcW 宽度不匹配。

// 正确 - gridCol 和 tcW 完全匹配
table.Append(new TableGrid(
    new GridColumn { Width = "3600" },  // 第一列
    new GridColumn { Width = "5400" }   // 第二列
));

var row = new TableRow(
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "3600", Type = TableWidthUnitValues.Dxa }  // 匹配 gridCol！
        ),
        new Paragraph(new Run(new Text("Content")))
    ),
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "5400", Type = TableWidthUnitValues.Dxa }  // 匹配 gridCol！
        ),
        new Paragraph(new Run(new Text("Content")))
    )
);

值限制

• paraId 必须 < 0x80000000（用于评论段落 ID）

创建 vs 编辑

创建新文档：使用 Example.cs 模式配合 SDK。

编辑现有文档：查看 references/EditingGuide.md 获取完整的 Python 工作流程。

Example.cs

阅读整个文件以理解整体结构，而不仅仅是单个函数。该文件演示了各部分如何连接（封面 → 目录 → 正文 → 封底）。

Example 中的 "Project Proposal"、"[Company Name]" 等是仅作示例的内容，配色方案仅供参考。

⚠️ 切勿复制示例的配色方案。 根据你的文档场景重新设计视觉风格，就像顶级设计师那样。

函数索引（阅读源代码了解实现细节）：

CJKExample.cs

CJK 文档必须只阅读CJKExample.cs — 阅读 Example.cs 会导致错误（缺少字体配置、引号转义）。它处理：

• 引号转义（"" → \u201c \u201d）
• CJK 字体配置（SimHei、Microsoft YaHei）
• CJK 文本的段落缩进

结构与 Example.cs 相同 — 无需阅读两者。

4.2 内容元素

域代码

PAGE/NUMPAGES/DATE/TOC — 结构：FieldChar(Begin) → FieldCode(" PAGE ") → FieldChar(Separate) → Text → FieldChar(End)。结果被缓存；WPS 不支持 UpdateFieldsOnOpen。

书签和交叉引用

书签标记位置（BookmarkStart/BookmarkEnd 具有匹配的 ID）；交叉引用通过 REF 域链接（" REF bookmarkName \\h "）。

陷阱：删除带书签的文本会删除书签 → "错误！未找到引用源"。

4.3 视觉设计

背景图片设计

封面/封底必须有背景。背景图片应有中心留白，使用低饱和度颜色。背景图片必须不包含任何文本；文本应在 Word 中实现，以便用户可编辑。

设计流程

1. 阅读示例：阅读 scripts/generate_backgrounds.py 了解 HTML/CSS 技术（径向渐变、透明度、定位）
2. 选择方向：根据文档场景从下表中选择一种风格方向
3. 创建原创：从头开始编写新的 HTML/CSS — 示例展示了一种风格，你的应该不同

⚠️ 复制示例 = 所有文档看起来都一样 = 平庸的交付。 每个文档都应具有与其内容和目的相匹配的独特视觉标识。

风格参考

技术：Playwright 生成 794×1123px (device_scale_factor=2)，作为浮动锚点插入，BehindDoc=true。参见 Example.cs:CreateFloatingBackground()。

信头（商业文档）

对于正式商业信函，考虑在页眉区域添加信头。常见模式：

• 首页完整信头（徽标 + 公司名称 + 联系信息），后续页面简化或隐藏
• 在 SectionProperties 中使用 TitlePage 以启用不同的首页页眉
• 根据具体业务背景灵活设计 — 无固定规则

双栏布局

使用带有 Columns 的 sectPr。影响整个章节直到下一个 sectPr。

4.4 特殊内容

数学公式（OMML）

核心模式：<m:e> 是通用的内容容器。几乎所有元素都将内容包装在 <m:e> 中。

文本：始终是 <m:r><m:t>text</m:t></m:r>，绝不能是裸文本。

根元素：<m:oMath>（内联）或 <m:oMathPara>（显示）。不要将 <m:oMath> 嵌套在另一个里面。

结构示例：

陷阱：矩阵使用 <m:e> 表示单元格，而不是 <m:mc>（后者用于列属性）。

C# 字符串中的弯引号

C# 将 " " 视为字符串分隔符 → CS1003。最简单的修复方法：在字符串字面量中使用转义直引号 \"。如果需要弯引号，使用 XML 实体编码：“ ”（双引号）或 ‘ ’（单引号）。

中文引号处理 — 查看 CJKExample.cs 获取完整模式：

// ❌ 错误 - 中文引号导致编译失败
new Text("请点击"确定"按钮")  // CS1003!

// ✓ 正确 - 使用 Unicode 转义
new Text("请点击\u201c确定\u201d按钮")

⚠️ 切勿使用逐字字符串@"" — \u 转义在逐字字符串中不起作用：

// ❌ 错误 - @"" 逐字字符串，\u 未转义，输出字面量 "\u201c"
string text = @"她说\u201c你好\u201d";  // 输出：她说\u201c你好\u201d

// ✓ 正确 - 常规字符串，\u 已转义
string text = "她说\u201c你好\u201d";   // 输出：她说"你好"

// ✓ 对于长文本，使用 + 连接
string para = "第一段内容，" +
              "她说\u201c这是引用\u201d，" +
              "继续写第二段。";

单位

缇 = 1/20 磅（11906 = A4 宽度）。字体大小为半磅（24 = 12pt）。EMU = 914400/英寸。

4.5 页面布局

图片尺寸

wp:extent 和 a:ext 的 Cx/Cy 必须匹配。对于按比例缩放：读取 PNG 头（字节 16-23）获取尺寸，计算 cy = cx * 高度 / 宽度。

分页控制

向标题/图表段落添加 KeepNext，以防止标题孤立或图表与标题分离。

分节符

pPr 内的 sectPr = 章节的最后一段。避免 PageBreak + Continuous（空白页）。使用 NextPage。

目录（TOC）

WPS 不支持 UpdateFieldsOnOpen → 必须使用域代码结构预填充目录条目：FieldChar(Begin) → FieldCode(" TOC ...") → FieldChar(Separate) → 占位符条目（超链接文本 + 页码） → FieldChar(End)。Separate 和 End 之间的占位符条目允许 Word 立即显示目录；用户刷新以获取准确的页码。切勿使用静态文本段落模拟目录 — 必须使用域代码结构，否则无法刷新。参见 Example.cs:AddTocSection()。

参数：\o "1-3"（标题级别），\h（超链接），\z（在网页中隐藏页码），\u（大纲级别）。

标题必须使用内置的 Heading1/Heading2 样式（自定义样式不被识别）。

对齐和排版

CJK 正文：两端对齐 + 2 字符缩进。英文：左对齐。表格数字：右对齐。标题：无缩进。

4.6 页面元素

页眉和页脚

// 1. 创建页眉部分
var headerPart = mainPart.AddNewPart<HeaderPart>();
var headerId = mainPart.GetIdOfPart(headerPart);

headerPart.Header = new Header(
    new Paragraph(
        new ParagraphProperties(
            new ParagraphStyleId { Val = "Header" },
            new Justification { Val = JustificationValues.Center }
        ),
        new Run(new Text("Document Title"))
    )
);

// 2. 创建页脚部分（带页码）
var footerPart = mainPart.AddNewPart<FooterPart>();
var footerId = mainPart.GetIdOfPart(footerPart);

var footerPara = new Paragraph(
    new ParagraphProperties(
        new Justification { Val = JustificationValues.Center }
    )
);
// PAGE 域：Begin → FieldCode → Separate → Text → End
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" PAGE ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));  // 占位符，打开时更新
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPara.Append(new Run(new Text(" / ") { Space = SpaceProcessingModeValues.Preserve }));
// NUMPAGES 域（相同结构）
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" NUMPAGES ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPart.Footer = new Footer(footerPara);

// 3. 在 SectionProperties 中引用
new SectionProperties(
    new HeaderReference { Type = HeaderFooterValues.Default, Id = headerId },
    new FooterReference { Type = HeaderFooterValues.Default, Id = footerId },
    new PageSize { Width = 11906, Height = 16838 },
    new PageMargin { Top = 1440, Right = 1440, Bottom = 1440, Left = 1440, Header = 720, Footer = 720 }
)

页眉/页脚类型：

首页不同（用于封面）：在 sectPr 中添加 TitlePage()。

奇偶页不同：在 settings.xml 中添加 <w:evenAndOddHeaders/>。

脚注和尾注

分隔符陷阱：FootnotesPart/EndnotesPart 必须在任何用户注释之前包含 Id=-1（Separator）和 Id=0（ContinuationSeparator）。缺少这些 → Word 无法渲染。

<!-- 在 footnotes.xml / endnotes.xml 中，用户注释之前必需 -->
<w:footnote w:type="separator" w:id="-1">
  <w:p><w:r><w:separator/></w:r></w:p>
</w:footnote>
<w:footnote w:type="continuationSeparator" w:id="0">
  <w:p><w:r><w:continuationSeparator/></w:r></w:p>
</w:footnote>
<!-- 用户注释从 id="1" 开始 -->

列表

需要带有 AbstractNum + NumberingInstance 的 NumberingDefinitionsPart。通过段落中的 NumberingProperties 应用。

多级：创建具有多个 Level 的 AbstractNum。格式：Decimal、UpperLetter、LowerRoman、Bullet、ChineseCounting。

超链接

必须使用<w:hyperlink> 元素，而非纯文本。 首先需要建立关系：

var relId = mainPart.AddHyperlinkRelationship(new Uri("https://example.com"), true).Id;
paragraph.Append(new Hyperlink(new Run(
    new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
    new Text("Click here")
)) { Id = relId })

图表和可视化

Word 图表：使用 NumberLiteral（无 Excel），DataPoint 用于颜色。参见 Example。

matplotlib：dpi=300，axes.unicode_minus=False。字体/标签必须与文档语言匹配。

4.7 编辑操作（Python API）

使用 docx_lib.editing 进行评论和修订跟踪：

from scripts.docx_lib.editing import (
    DocxContext,
    add_comment, reply_comment, resolve_comment, delete_comment,
    insert_paragraph, insert_text, propose_deletion,
    reject_insertion, restore_deletion, enable_track_changes
)

with DocxContext("input.docx", "output.docx") as ctx:
    # add_comment(ctx, para_text, comment, highlight=None)
    # - para_text: 用于定位段落的文本
    # - comment: 评论内容
    # - highlight: 要高亮的文本（省略则高亮整个段落）
    add_comment(ctx, "M-SVI index", "Please define", highlight="M-SVI")
    insert_text(ctx, "The method", after="method", new_text=" and materials")

完整指南：references/EditingGuide.md

4.8 XML