docx-generator

DOCX Generator 是一个用于以编程方式创建和操作 Word DOCX 文件的技能，适合需要自动化文档生成或批量处理 DOCX 的场景。

用途

该技能主要用于以下情况：

• 根据数据或规格以编程方式创建 Word 文档
• 用动态内容填充品牌模板，同时保留企业样式
• 从现有 DOCX 文件中提取文本、表格和结构以供分析
• 查找并替换 {{TITLE}} 或 ${author} 等占位符文本
• 自动化文档生成工作流（报告、合同、信函）

不适用的情况：用户希望打开或查看文档（应使用原生 Word 或查看器）；需要与数据源进行复杂邮件合并（应使用原生 Word 邮件合并）；处理旧版 .doc 格式（仅支持 DOCX）；需要输出 PDF（应使用 pdf-generator 技能）。

主要能力

该技能提供两种操作模式：

模板模式：修改现有的品牌模板。先分析模板以查找占位符，然后用实际内容替换 {{PLACEHOLDERS}}。分析脚本会输出段落、表格、图片数量以及占位符位置（段落、页眉、页脚、表格单元格等）。替换时可通过 includeHeaders 和 includeFooters 控制是否处理页眉页脚。

从零模式：使用 JSON 规格文件从无到有创建文档。规格支持标题、创建者、默认字体和字号、节（sections），每节可包含页眉、页脚和内容。内容元素支持段落、标题（1-6 级）、文本运行（runs，可混合格式）、表格、分页符、超链接等。

支持的格式选项包括：段落对齐（左、居中、右、两端对齐）、项目符号、编号列表、间距、缩进、分页前分页；文本运行支持粗体、斜体、下划线、删除线、字号、字体、颜色（十六进制）、高亮、上标、下标；表格支持行、宽度百分比、边框、单元格背景色和垂直对齐；超链接支持链接文本、URL、粗体和斜体。

使用方式

使用前需安装 Deno（https://deno.land/）。模板模式需要输入 DOCX 文件，从零模式需要 JSON 规格文件。

模板模式步骤：

1. 分析模板：deno run --allow-read scripts/analyze-template.ts corporate-template.docx > inventory.json
2. 创建替换规格 replacements.json，包含 textReplacements 数组（tag 和 value）、includeHeaders、includeFooters
3. 生成输出：deno run --allow-read --allow-write scripts/generate-from-template.ts corporate-template.docx replacements.json output.docx

从零模式步骤：

1. 创建 spec.json，包含 title、creator、styles、sections 等
2. 生成文档：deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.docx

脚本权限：analyze-template.ts 需要 --allow-read；generate-from-template.ts 和 generate-scratch.ts 需要 --allow-read --allow-write。

适用场景

• 合同生成：从品牌模板生成合同，替换客户数据
• 带表格的报告：生成包含表格和格式的数据报告
• 带页眉页脚的信函：创建带有信头的正式信函
• 文档内容提取：分析现有 DOCX 以获取文本、表格和占位符清单

限制

• 仅支持 DOCX，不支持旧版 .doc 格式
• 不支持修订记录（track changes）
• 不支持文档批注
• 不支持 VBA 宏
• 对复杂编号方案支持有限
• Word 可能将文本拆分到多个 XML 元素中，脚本处理常见情况

常见问题

• 占位符未被替换：运行 analyze-template.ts 验证确切标签文本；标签可能跨 XML 运行拆分，脚本会自动合并；确保 includeHeaders 和 includeFooters 为 true。
• 替换后格式丢失：文本替换会保留原始占位符的格式，确保占位符格式与期望的最终文本一致。
• 图片未显示：使用相对于 spec.json 文件位置的路径；验证图片文件存在且可读；支持 PNG、JPEG、GIF 格式。
• 表格单元格内容错误：每个单元格的 content 必须是段落规格数组；使用 shading 设置背景色，verticalAlign 设置对齐。

相关技能

• pptx-generator：创建 PowerPoint 演示文稿
• xlsx-generator：创建 Excel 电子表格
• pdf-generator：创建 PDF 文档