document-converter

文档转换器

概述

当你需要转换常见文档和数据格式，并尽可能保留源格式的结构时，请使用此技能。内置 CLI 支持在 Markdown、HTML、CSV、JSON、YAML、TOML、纯文本、Excel 和 PDF 输出之间进行轻量级本地转换。

核心转换使用 Python 标准库：JSON、CSV、HTML 解析、Markdown 启发式处理、通过 tomllib 读取 TOML，以及自定义 TOML/YAML 写入器。PDF 输出使用 pandoc，Excel 读取使用 openpyxl；这两者都是相应转换路径所必需的依赖。如果缺少依赖，工具会给出清晰的安装提示后退出，而不会显示回溯信息。

转换矩阵

源格式	目标格式	命令格式	依赖项	备注
Markdown	HTML	--from markdown --to html	标准库	标题、段落、列表、围栏代码、粗体/斜体/代码、链接。
HTML	Markdown	--from html --to markdown	标准库	常见块级/行内标签；会丢弃复杂的 CSS/布局。
HTML	文本	--from html --to text	标准库	移除标签、解码实体、保留段落/列表换行。
CSV	JSON	--from csv --to json	标准库	标题行会转换为对象键；值保持为字符串。
JSON	CSV	--from json --to csv	标准库	使用点号表示法展平嵌套对象；数组会转换为 JSON 字符串。
CSV	Markdown	--from csv --to markdown	标准库	生成 GitHub 风格的管道符表格。
Markdown	CSV	--from markdown --to csv	标准库	读取第一个管道符表格。
YAML	JSON	--from yaml --to json	标准库回退方案；PyYAML 可选	不使用 PyYAML 时仅支持基本 YAML。
JSON	YAML	--from json --to yaml	标准库	使用 2 个空格缩进的 YAML，不含锚点。
YAML	TOML	--from yaml --to toml	标准库回退方案；PyYAML 可选	单个 YAML 文档；仅支持与 TOML 兼容的值。
TOML	YAML	--from toml --to yaml	标准库	TOML 表会转换为嵌套 YAML 映射。
TOML	JSON	--from toml --to json	Python 3.11+ tomllib	TOML 日期/时间会转换为 JSON 字符串。
JSON	TOML	--from json --to toml	标准库	支持字符串、数字、布尔值、数组和嵌套表。
XLSX	CSV	--from xlsx --to csv	openpyxl	仅读取第一个工作表。
Markdown	PDF	--from markdown --to pdf	pandoc	PDF 仅支持作为输出目标；需要指定 --output。

有关各项转换的限制和数据丢失风险，请参阅 references/conversion-matrix.md。

快速开始

在技能目录中运行，或通过路径调用脚本：

python scripts/convert.py --input notes.md --from markdown --to html --output notes.html

省略 --from 时，会根据输入文件扩展名自动检测格式：

python scripts/convert.py --input notes.md --to html --output notes.html

各受支持转换的示例：

# Markdown ↔ HTML
python scripts/convert.py --input page.md --to html --output page.html
python scripts/convert.py --input page.html --to markdown --output page.md

# HTML → plain text
python scripts/convert.py --input page.html --to text --output page.txt

# CSV ↔ JSON
python scripts/convert.py --input people.csv --to json --output people.json
python scripts/convert.py --input records.json --to csv --output records.csv

# CSV ↔ Markdown table
python scripts/convert.py --input people.csv --to markdown --output people-table.md
python scripts/convert.py --input people-table.md --to csv --output people.csv

# JSON ↔ YAML
python scripts/convert.py --input config.json --to yaml --output config.yaml
python scripts/convert.py --input config.yaml --to json --output config.json

# YAML ↔ TOML
python scripts/convert.py --input config.yaml --to toml --output config.toml
python scripts/convert.py --input config.toml --to yaml --output config.yaml

# JSON ↔ TOML
python scripts/convert.py --input config.json --to toml --output config.toml
python scripts/convert.py --input config.toml --to json --output config.json

# Excel → CSV, first sheet only; requires openpyxl
python scripts/convert.py --input workbook.xlsx --to csv --output sheet.csv

# Markdown → PDF; requires pandoc
python scripts/convert.py --input report.md --to pdf --output report.pdf

对于文本格式，如果省略 --output，转换后的内容会写入标准输出。

边界情况处理

• **嵌套 JSON→CSV 展平：**嵌套对象会使用点号表示法展平，例如，{"user": {"name": "Ada"}} 会变成 user.name 列。列表和非标量嵌套值会序列化为紧凑的 JSON 字符串，因为 CSV 不支持原生嵌套结构。
• **CSV 类型丢失：**CSV 值都是字符串。CSV→JSON→CSV 往返转换无法还原原始数字、布尔值或日期，除非源数据明确编码了这些类型，并且后续流程重新为其指定类型。
• **HTML 实体解码：**HTML→Markdown 和 HTML→文本会解码 &、  和数字实体等内容。空白字符会被规范化；不会保留浏览器中的精确布局。
• **YAML 支持：**如果已安装 PyYAML，则会使用它。否则，简易解析器会处理常见的块样式映射、列表、嵌套字典、字符串、数字、布尔值和 null。回退模式不支持复杂的 YAML 功能：锚点、别名、标签、流样式、合并键和多文档流。
• **YAML 多文档：**转换器会将 YAML 输入视为单个文档。转换前，请将多文档 YAML 拆分为多个文件。
• **TOML 类型限制：**TOML 输出支持基本标量值、标量值数组和嵌套表。混合数组、表数组、带标签的值和任意对象会被拒绝，并显示清晰的提示信息。

依赖项

大多数转换只使用 Python 标准库。以下两种转换需要外部工具：

使用 Pandoc 进行 Markdown→PDF 转换

Markdown→PDF 会调用 pandoc。如果未安装 pandoc，CLI 会输出：

Markdown to PDF requires pandoc. Install pandoc and ensure it is on PATH.

请通过操作系统的软件包管理器或访问 https://pandoc.org/installing.html 安装 pandoc。必须指定 PDF 输出路径，因为 PDF 是二进制文件，无法写入 stdout。

使用 openpyxl 进行 Excel→CSV 转换

读取 Excel 需要 openpyxl：

python -m pip install openpyxl

如果未安装该依赖，CLI 会输出安装提示并以非零状态退出。转换器只读取第一个工作表；如果需要指定名称的工作表、由 Excel 计算的公式、格式或多个 CSV 文件，请使用电子表格工具或编写一个小型自定义脚本。

常见问题

1. **期待 CSV 往返转换无损。**CSV 没有架构、嵌套结构或可靠的类型信息。JSON→CSV 展平适合查看或导入，并不适合作为可逆的归档格式。
2. **以为 HTML 布局会保留。**HTML→Markdown/文本会保留内容结构，而不会保留 CSS、脚本、带跨行或跨列单元格的表格，或浏览器中的精确空白布局。
3. **使用回退模式处理高级 YAML。**锚点、别名、标签、流样式映射/列表、合并键和多文档流需要使用真正的 YAML 解析器；即使使用解析器，写回时也可能丢失锚点的标识关系。
4. **试图将所有 JSON 写入 TOML。**TOML 无法表示所有 JSON 结构。数组中的值必须为标量，且类型要足够一致，以便 TOML 使用方处理；对象会转换为表。
5. **忘记依赖项。**PDF 转换需要 pandoc，Excel 转换需要 openpyxl。依赖自动化流程前，请先安装这两者。
6. **混合 Markdown 文本和表格。**Markdown→CSV 会读取找到的第一个管道符表格，并忽略周围的文本。

此工具不支持的功能

• **不支持 OCR。**扫描版 PDF 和图像需要先通过 OCR 流程处理，再进行文本转换。
• **不支持 PDF 提取。**此处 PDF 仅支持通过 Markdown→PDF 生成。要从 PDF 中提取文本或表格，请使用专用的 PDF/OCR 工具。
• 不支持二进制 Office 文件编辑。.docx、带样式的 .xlsx 生成和邮件合并工作流不在此转换器的支持范围内。请使用 fill-template 填充 Word/Excel 模板。
• **不保留复杂样式布局。**此工具用于便于移植的文本/数据转换，不适用于像素级精准的排版。

验证清单

• 确认矩阵中包含源格式和目标格式。
• 使用 --output 输出到文件；仅当标准输出中的文本可以接受时才省略该选项。
• 批量转换多个文件前，先检查示例输出。
• 对于 JSON→CSV，检查扁平化的列名和列表序列化结果。
• 对于 YAML/TOML，确认不需要高级功能，或这些功能不会被悄然丢弃。
• 对于 PDF/Excel，在依赖自动化之前，确认已安装 pandoc 和 openpyxl。