Word转Markdown转换助手

转换流程

当用户需要将Word文档转换为Markdown格式时，按以下步骤操作：

1. 确认输入文件：获取用户提供的Word文档路径，或询问文档位置
2. 确定输出位置：默认在原文件同目录生成同名.md文件，图片保存在<文件名>_images/目录
3. 执行转换：调用转换脚本完成转换
4. 验证结果：检查生成的.md文件和提取的图片，向用户说明输出位置

使用转换脚本

必须使用bundled的转换脚本，而不是自己编写。脚本路径相对于此SKILL.md文件。

基本命令：

node scripts/convert.js <输入.docx文件路径>

完整命令格式：

node scripts/convert.js <输入.docx文件路径> --output <输出.md路径> --images <图片保存目录>

参数说明

• <输入文件>: .docx文件的完整路径（必需）
• --output 或 -o: 输出的.md文件路径（可选）
  • 默认：与输入文件同目录，同名但扩展名为.md
  • 使用-输出到stdout（用于管道操作）
• --images 或 -i: 图片保存目录（可选）
  • 默认：<输入文件名>_images/目录

使用示例

# 最简单用法（使用所有默认值）
node scripts/convert.js document.docx

# 指定输出文件和图片目录
node scripts/convert.js document.docx --output result.md --images ./images

# 输出到stdout（不保存文件）
node scripts/convert.js document.docx --output -

# 处理带空格的路径（Windows）
node scripts/convert.js "C:\Users\Documents\my report.docx"

转换说明

支持的Word元素

转换脚本可以正确处理：

• 标题：H1-H6所有级别
• 段落：普通段落和换行
• 文本格式：粗体、斜体、删除线、下划线（转为斜体）
• 列表：有序列表和无序列表（包括嵌套）
• 表格：使用GitHub Flavored Markdown表格格式
• 图片：自动提取并保存为本地文件
• 链接：保留超链接

图片处理细节

• 所有嵌入图片会被提取并保存到指定目录
• Markdown中的图片引用使用相对路径（./图片目录/文件名）
• 图片文件名格式：image-<时间戳>-<序号>.<扩展名>
• 支持的图片格式：PNG, JPG, GIF, BMP等
• 如果图片提取失败，会在警告中说明，但不会中断整体转换

限制和注意事项

以下Word特性无法保留或转换：

• 复杂的样式：自定义字体、颜色、高亮、页眉页脚
• 页面布局：分栏、页边距、页面方向
• 嵌入对象：Excel表格、图表、嵌入视频、音频
• 特殊功能：批注、修订记录、域代码、目录
• 高级表格：合并单元格（会尝试转换但可能不完美）

转换后操作

转换完成后，按以下方式向用户报告结果：

1. 成功情况：

   • 明确告知输出.md文件的完整路径
   • 如果提取了图片，说明图片数量和目录位置
   • 如果有警告信息（如某些格式无法转换），向用户解释
   • 询问用户是否需要查看转换结果或进一步调整

2. 失败情况：

   • 说明具体的错误原因（文件不存在、权限问题、格式不支持等）
   • 提供可能的解决方案
   • 询问用户是否需要重试或更改参数

示例输出说明

成功时：

✓ Word文档已转换为Markdown
  输入文件: C:\Users\Documents\report.docx
  输出文件: C:\Users\Documents\report.md
  提取图片: 3张，保存在 C:\Users\Documents\report_images\

有警告时：

✓ 转换完成，但有2个警告：
  1. 某些自定义样式无法保留
  2. 一张图片提取失败

常见使用场景

场景1：用户提供了文件路径

用户说："把 D:\files\meeting-notes.docx 转成markdown"

操作：

cd C:\Users\linfe\.claude\skills\word-to-markdown
node scripts/convert.js "D:\files\meeting-notes.docx"

场景2：用户只说了文件名

用户说："转换一下我的 report.docx"

操作：先询问完整路径或查找常见位置（Downloads、Documents），然后执行转换。

场景3：批量转换（多个文件）

用户说："把这个文件夹里的所有Word文档都转成markdown"

操作：遍历目录，对每个.docx文件分别调用转换脚本。

错误处理

常见错误及解决方案

错误：文件不存在

• 检查路径是否正确
• 确认文件扩展名是.docx（不是.doc）
• 使用引号处理包含空格的路径

错误：权限不足

• 确认文件没有被其他程序打开（如Word）
• 检查目录写入权限
• 尝试在其他位置保存输出文件

错误：不支持的格式

• 确认是.docx格式（Word 2007+）
• 旧的.doc格式需要先在Word中转换为.docx

错误：依赖未安装

• 执行 npm install 安装依赖
• 确认Node.js版本 >= 14

技术说明

此skill使用以下技术栈：

• mammoth.js: 解析.docx文件结构，转换为HTML
• turndown: 将HTML转换为干净的Markdown
• turndown-plugin-gfm: 支持GitHub Flavored Markdown扩展语法

转换质量说明：

• 适合标准文档转换（技术文档、报告、笔记）
• 简单格式文档转换效果最佳
• 复杂排版可能需要人工调整
• 转换速度：约1-2秒/MB