md-to-docx

name	md-to-docx
description	将 Markdown 文件转换为格式化的 Word 文档。当用户想要将 .md 转换为 .docx、从 Markdown 创建 Word 文档或提及文档转换时调用此技能。

Markdown 转 Word 文档转换器

本技能将 Markdown 文件转换为专业格式的 Word 文档（.docx）。

何时调用

在以下情况下调用此技能：

• 用户想要将 Markdown 文件转换为 Word 文档
• 用户要求从 Markdown 内容创建 Word 文档
• 用户提及 .md 到 .docx 的转换
• 用户需要格式化的文档输出

处理流程

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   输入 MD 文件   │ ──▶ │  版本号管理处理  │ ──▶ │  格式规范化处理  │ ──▶ │   解析 MD 元素   │ ──▶ │  生成 Word 文档  │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
                                                      │
                                            ┌─────────┴─────────┐
                                            ▼                   ▼
                                      ┌───────────┐       ┌───────────┐
                                      │ 保存规范化 │       │ 应用模板   │
                                      │ 后的文件   │       │ 样式       │
                                      └───────────┘       └───────────┘

功能特性

1. 自动版本管理

技能自动管理输出文件的版本号：

场景	输入文件	输出文件
文件名无版本号	document.md	document_V1.docx、document_V1_normalized.md
文件名含版本号	document_V3.md	document_V4.docx、document_V4_normalized.md
目录中已有 V1	document.md	document_V2.docx、document_V2_normalized.md

版本规则：

• 如果输入文件名包含版本号（如 _V3），则从该版本号递增
• 如果文件名无版本号，则扫描目录中已有版本并递增
• 版本格式：_V{n}，其中 n 为整数（V1、V2、V3...）
• .docx 和 _normalized.md 文件使用相同的版本号

2. Markdown 格式规范化

转换前，技能会自动规范化 Markdown 格式问题：

问题类型	示例	修复
未闭合的代码块	```python 无闭合	自动添加闭合```
标题后无空格	###标题	→### 标题
标题中的中文数字	## 一、核心原理	→## 1. 核心原理
标题中的中文数字	### (一)技术细节	→### (1) 技术细节
无序列表无空格	-项目	→- 项目
有序列表无空格	1.项目	→1. 项目
分隔线变体	-- 或 ----	→---
不匹配的粗体标记	**只有开头	移除无效标记
不匹配的斜体标记	*只有开头	移除无效标记
缺少表格分隔行	表格无`	---
表格列数不一致	行的列数不同	自动填充/截断
多个连续空行	3+ 个连续空行	压缩为 1 个
标题前缺少空行	文本直接在标题前	添加空行
有序列表间距	列表项之间的空行	保留（不移除）
段落首行空格	带首行空格的文本	移除首行空格
段落间空行	段落之间的单个空行	移除（清理）

中文数字转换： 技能自动将标题中的中文数字序列转换为阿拉伯数字：

• 支持：一、二、三、四、五、六、七、八、九、十（至二十）
• 模式 1：一、 → 1.（中文标点）
• 模式 2：(一) → (1)（括号形式）
• 适用于所有标题级别（# ~ ######）

有序列表间距： 有序列表项之间的空行会被智能保留以保持文档可读性：

• 如果两个编号列表项之间存在空行，该空行将被保留
• 这允许列表项内容有更好的视觉分隔
• 示例：1. 项目 1 →（空行）→ 2. 项目 2 将保留间距

空行管理： 技能根据上下文智能管理空行：

• 移除：普通段落之间的空行（清理以获得更好的格式）
• 保留：特殊元素周围的空行（标题、列表、代码块、表格、分隔线）
• 保留：缩进内容周围的空行（列表项详情、嵌套项）
• 压缩：多个连续空行减少为单个

段落首行空白： 普通段落的首行空白会自动移除以防止 Word 中出现双重缩进：

• Word 文档自动为段落应用首行缩进
• Markdown 中的首行空格会造成视觉不一致
• 列表项缩进被保留（无序列表和有序列表）
• 代码块和引用块保留其格式

3. 支持的 Markdown 元素

元素	语法	支持程度
标题	# ~ ######	完全支持
段落	纯文本	完全支持
粗体	**文本**	完全支持
斜体	*文本*	完全支持
粗体+斜体	***文本***	完全支持
无序列表	- 项目 / * 项目	完全支持
有序列表	1. 项目	完全支持
表格	`	列
代码块	```代码```	完全支持
行内代码	`代码`	完全支持
链接	[文本](url)	完全支持
图片		完全支持
引用块	> 引用	完全支持
分隔线	---	完全支持
删除线	~~文本~~	完全支持
换行	<br> 或 \\	完全支持

4. 文档格式规范

字体规范

元素类型	中文字体	英文字体	字号	说明
正文	宋体	Times New Roman	12pt（小四）	标准正文字号
一级标题	宋体	Times New Roman	22pt（二号）	大标题
二级标题	宋体	Times New Roman	16pt（三号）	章节标题
三级标题	宋体	Times New Roman	15pt（小三）	小节标题
四级标题	宋体	Times New Roman	14pt（四号）	条目标题
五级标题	宋体	Times New Roman	14pt（四号）	子条目标题
代码块	Consolas	Consolas	9pt（小五）	略小于正文
行内代码	Consolas	Consolas	12pt（小四）	与正文同字号

段落规范

属性	设置值	说明
首行缩进	0.74cm	约两个汉字宽度
行间距	1.5 倍	提升阅读舒适度
段前间距	0pt	保持紧凑排版
段后间距	0pt	保持紧凑排版

标题规范

标题级别	Markdown 语法	字号	样式特点
文档标题	# 标题	22pt（二号）	加粗、居中、可生成封面页
一级标题	## 标题	22pt（二号）	加粗、段前自动分页
二级标题	### 标题	16pt（三号）	加粗、不分页
三级标题	#### 标题	15pt（小三）	加粗、不分页
四级标题	##### 标题	14pt（四号）	加粗、不分页
五级标题	###### 标题	14pt（四号）	加粗、不分页

表格规范

属性	设置值	说明
表格样式	Table Grid	带边框的标准表格
对齐方式	居中	表格整体居中显示
列宽	自动计算	根据内容智能分配
表头背景	#D9D9D9	浅灰色背景突出表头
表头对齐	居中	表头文字居中对齐
单元格对齐	左对齐	数据内容左对齐

代码块规范

属性	设置值	说明
字体	Consolas	等宽字体，代码清晰
字号	9pt	略小于正文
背景色	#F5F5F5	浅灰色背景区分代码
左缩进	0.5cm	突出代码块层次
语言标签	斜体显示	如[python]

行内代码规范

属性	设置值	说明
字体	Consolas	等宽字体
字号	同正文	保持行高一致
背景色	#F0F0F0	浅灰背景突出显示

引用块规范

属性	设置值	说明
左边框	#6366F1	紫色竖线标识
边框宽度	1.5pt	清晰可见
左右缩进	1cm	突出引用内容
字体样式	斜体	区分引用文字

列表规范

属性	设置值	说明
左缩进	0.74cm × 层级	支持多级嵌套缩进
行间距	1.5 倍	与正文保持一致
无序列表符号	•	实心圆点
有序列表格式	1. 2. 3.	数字加点

分隔线规范

属性	设置值	说明
样式	底部边框	段落下方的横线
颜色	#CCCCCC	浅灰色
段前段后间距	6pt	保持适当间隔

封面页规范

元素	设置值	说明
标题字号	22pt	与一级标题一致
标题样式	加粗、居中	突出文档标题
版本信息	12pt、居中	格式：版本：V1
日期信息	12pt、居中	格式：编制日期：2024年01月01日
前置空行	3 行	标题上方留白
后置空行	14 行	标题与版本信息间距

分页控制

规则	说明
一级标题前分页	每个一级标题自动另起一页
其他标题不分页	二级及以下标题保持连续
封面页后分页	封面页结束后自动分页

使用方法

基本转换

将此 Markdown 文件转换为 Word：
[提供 .md 文件路径或内容]

使用自定义模板

使用此模板将 Markdown 转换为 Word：
Markdown：[路径或内容]
模板：[.docx 模板路径]

带封面页

转换为带封面页的 Word：
[Markdown 内容]
标题：[文档标题]
版本：[版本号]
日期：[日期]

参数说明

参数	类型	必填	描述
markdown_content	字符串	是	Markdown 文本或文件路径
output_path	字符串	否	输出 .docx 文件路径
template_path	字符串	否	自定义 .docx 模板路径
version	字符串	否	封面页版本号（未提供则自动生成）
date	字符串	否	封面页日期
normalize	布尔值	否	启用格式规范化（默认：true）
save_normalized	布尔值	否	保存规范化后的 MD 文件（默认：true）
use_versioning	布尔值	否	启用自动版本编号（默认：true）

实现原理

技能使用 Python 脚本，逻辑如下：

步骤 0：版本管理（version_manager.py）

# 自动确定输出文件的版本号
version_info = get_versioned_output_paths(input_path, output_dir)
# 返回：{ 'version': 1, 'docx_path': 'document_V1.docx', 'normalized_md_path': 'document_V1_normalized.md' }

步骤 1：格式规范化（markdown_normalizer.py）

# 自动修复常见的 Markdown 格式问题
normalizer = MarkdownNormalizer()
normalized_content = normalizer.normalize(content)
# 保存到：original_filename_normalized.md

步骤 2：解析 Markdown（md_to_docx.py）

# 将规范化的 Markdown 转换为结构化元素
parser = MarkdownParser()
elements = parser.parse(normalized_content)

步骤 3：生成 Word 文档

# 创建带格式的 Word 文档
generator = DocxGenerator(template_path)
generator.create_document(output_path)
generator.generate(elements, version, date)
generator.save(output_path)

输出文件

转换后，生成以下文件：

文件	描述
document_V{n}.docx	带版本号的最终 Word 文档
document_V{n}_normalized.md	带版本号的规范化 Markdown

版本号示例：

• 首次转换：document_V1.docx、document_V1_normalized.md
• 第二次转换：document_V2.docx、document_V2_normalized.md
• 带版本输入：document_V3.md → document_V4.docx

模板支持

使用自定义模板

如果提供了模板：

• 继承页面设置（边距、纸张大小）
• 继承样式定义（标题 1-6、正文）
• 添加新内容前清除模板内容

内置样式（无模板）

本 Skill 可独立运行，无需外部模板文件。

如果未提供模板或模板文件不存在：

• 自动创建空白文档
• 使用默认页面设置（A4，2.54cm 边距）
• 以编程方式创建样式
• 应用一致的格式

这意味着本 Skill 可以在任何安装了 Python 和 python-docx 的环境中独立运行，无需依赖外部模板文件。

示例

示例 1：格式规范化

输入（含问题）：

# 测试文档
## 一、表格测试
| 列1|列2|列3
|数据1|数据2|数据3
###标题无空格
-项目1无空格

规范化输出：

# 测试文档

## 一、表格测试

|列1|列2|列3|
|---|---|---|
|数据1|数据2|数据3|

### 标题无空格

- 项目1无空格

示例 2：简单转换

输入：

# 项目文档

## 概述
这是项目概述。

## 功能特性
- 功能 1
- 功能 2

输出：格式化的 Word 文档，具有正确的标题层级和项目符号列表。

示例 3：带表格

输入：

## API 端点

| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | /api/users | 获取所有用户 |
| POST | /api/users | 创建用户 |

输出：带格式化表格的 Word 文档，表头行为灰色背景。

示例 4：带代码块

输入：

## 安装

```bash
npm install package-name

输出：带等宽字体代码块的 Word 文档。

## 错误处理

- **无效 Markdown**：记录警告，继续部分解析
- **模板缺失**：回退到内置样式
- **文件未找到**：返回清晰的错误消息
- **权限错误**：建议替代输出路径
- **格式问题**：在规范化阶段自动修复

## 依赖

- Python 3.x
- python-docx 库

## 模块文件

| 文件 | 描述 |
|------|------|
| `md_to_docx.py` | 主转换脚本 |
| `markdown_normalizer.py` | Markdown 格式规范化 |
| `version_manager.py` | 自动版本编号 |
| `create_template.py` | 模板生成脚本（可选） |
| `template.docx` | 默认 Word 模板（可选） |

**说明：**
- `template.docx` 是可选的模板文件，如果存在则使用，不存在则自动创建空白文档
- `create_template.py` 可用于重新生成符合格式规范的模板文件
- 本 Skill 可完全独立运行，无需外部依赖