docx-format-replicator

用途

DOCX Format Replicator 用于从现有 Word 文档（.docx）中提取格式信息，并用这些格式生成内容不同但格式相同的新文档。它适合创建文档模板、在多个文档间保持格式一致，以及复刻复杂的 Word 文档结构。

主要能力

从现有 Word 文档提取格式，生成可复用的格式配置（JSON）。
提取内容包括：样式定义（字体、字号、颜色、对齐）、段落与字符样式、编号方案（如 1、1.1、1.1.1）、表格结构与样式、页眉页脚配置。
根据格式配置与内容数据生成新的 .docx 文件。
支持的内容区块类型：heading（可带编号的标题）、paragraph（文本段落）、table（可配置行列的表格）、page_break（分页符）。

使用方式

该技能通过 Python 脚本执行，分为三步。

第一步：从模板提取格式

python scripts/extract_format.py <template.docx> <output.json>

示例：

python scripts/extract_format.py "HY研制任务书.docx" format_template.json

输出为包含全部格式信息的 JSON 文件（详见 references/format_config_schema.md）。

第二步：准备内容数据

创建一个 JSON 文件，包含新文档的实际内容，结构需符合 references/content_data_schema.md 的定义。内容结构示例：

{
  "metadata": {
    "title": "Document Title",
    "author": "Author Name",
    "version": "1.0",
    "date": "2025-01-15"
  },
  "sections": [
    {
      "type": "heading",
      "content": "Section Title",
      "level": 1,
      "number": "1"
    },
    {
      "type": "paragraph",
      "content": "Paragraph text content."
    },
    {
      "type": "table",
      "rows": 3,
      "cells": [
        ["Header 1", "Header 2"],
        ["Data 1", "Data 2"]
      ]
    }
  ]
}

完整示例见 assets/example_content.json。

第三步：生成新文档

python scripts/generate_document.py <format.json> <content.json> <output.docx>

示例：

python scripts/generate_document.py format_template.json new_content.json output_document.docx

结果：生成一个 .docx 文件，将模板格式应用于新内容。

完整示例流程：用户提出“我有一份研制任务书，需要创建 5 份格式相同但内容不同的文档”时，先提取格式，再为每份新文档创建内容文件，最后逐一生成文档。

适用场景

企业文档模板：从公司模板提取格式，生成格式统一、品牌一致的报告、方案或规格书。
技术文档系列：创建格式相同的多份技术文档（规格书、测试计划、手册）。
研制任务文档：内置示例模板（assets/hy_template_format.json）展示了一份完整的研制任务书格式，包含页眉中的审批/评审表、多级编号（1、1.1、1.1.1）、技术规格表格和结构化章节，可作为类似技术文档的起点。

高级用法

自定义提取：修改 scripts/extract_format.py 以提取默认未覆盖的额外属性，如自定义 XML 元素、高级表格特性（合并单元格、边框）、嵌入对象、自定义属性。
扩展内容类型：在 scripts/generate_document.py 中新增区块类型，如带题注的图片、项目符号或编号列表、脚注与尾注、自定义内容块（扩展指南见 references/content_data_schema.md）。
批量处理：编写包装脚本批量生成多份文档，例如遍历内容文件列表，对每个文件调用 generate_document.py 生成对应输出。

依赖

脚本需要：

Python 3.7+
python-docx 库：pip install python-docx

核心功能无需其他依赖。

资源

scripts/：

extract_format.py - 从 Word 文档提取格式
generate_document.py - 根据格式与内容生成新文档

两个脚本均内置帮助：

python scripts/extract_format.py --help
python scripts/generate_document.py --help

references/：

format_config_schema.md - 格式配置文件的完整 schema
content_data_schema.md - 内容数据文件的完整 schema

assets/：

hy_template_format.json - 从技术研制任务书提取的示例格式
example_content.json - 展示所有区块类型的示例内容数据

限制与注意事项

输出中缺少样式：确保内容数据中的样式 ID 与格式配置中的一致，可检查 format.json 中可用的样式 ID。
表格格式问题：核对内容数据与格式配置中的表格维度（行/列）是否匹配，表格结构见 format_config_schema.md。
字体显示不正确：部分字体可能并非所有系统都可用，需确认所引用的字体已安装。
依赖缺失：安装所需 Python 包 pip install python-docx。

提示

先用示例测试：使用内置的 hy_template_format.json 和 example_content.json 理解工作流程，再提取自己的格式。
从简单开始：先处理基本标题和段落，再添加表格和复杂格式。
校验 JSON：生成文档前用 JSON 校验器检查内容数据文件。
保留格式配置：保存提取出的格式配置，以便在多个项目中复用。
版本控制：将格式配置与内容数据一并纳入版本控制，实现可复现的文档生成。