pandoc-convert — pandoc 转换器

Pandoc 转换 使用 Pandoc 转换文档，同时保持转换的可预测性、验证性和易于排除故障。对于用户面向的工作，优先使用捆绑的包装器，因为它们添加了依赖项检查、更安全的默认值、进度输出、重试和报告。

快速决策 当用户提供一个输入文件或要求一个输出时，使用 scripts/convert.sh。 当用户提供一个目录、多个文件、一个 glob 或说“批量 / batch”时，使用 scripts/batch_convert.py。 当用户询问文档是否准备好转换或转换需要引用、模板、CSS、资源或 PDF 输出时，使用 scripts/validate.sh。 仅当用户明确要求安装 Pandoc 或修复缺失的 Pandoc 依赖项时，使用 scripts/install_pandoc.sh。

如果目标是 PDF，请提及 Pandoc 需要一个 PDF 引擎。对于中文文档，优先使用 --pdf-engine xelatex（如果可用）。

安装策略 在转换过程中不要默默地安装 Pandoc。如果 Pandoc 缺失，报告验证错误并询问用户是否需要安装帮助。除非用户明确请求安装，否则先以 dry-run 模式运行安装器： bash ${CLAUDE_SKILL_DIR}/scripts/install_pandoc.sh 仅在获得用户明确批准后运行安装： bash ${CLAUDE_SKILL_DIR}/scripts/install_pandoc.sh --yes 安装器检测现有的 pandoc、Homebrew、Conda、apt-get、dnf 或 pacman，然后打印或运行推荐的命令。它不安装 PDF 引擎（如 xelatex）；单独处理 PDF 引擎设置。

单文件工作流 确认输入文件存在并推断所需的输出格式。如果输出路径缺失，建议在输入文件旁边使用默认路径，例如 README.md → README.docx。 从技能目录运行包装器： bash ${CLAUDE_SKILL_DIR}/scripts/convert.sh input.md -o output.docx bash ${CLAUDE_SKILL_DIR}/scripts/convert.sh input.md -o output.pdf --pdf-engine xelatex --toc bash ${CLAUDE_SKILL_DIR}/scripts/convert.sh input.md -o output.pdf --citeproc --bibliography refs.bib --csl style.csl 报告生成的文件路径。如果命令失败，显示可操作的错误并推荐最小的修复。

批量工作流 使用 Python 批量包装器进行重试、容错、进度和报告： python3 ${CLAUDE_SKILL_DIR}/scripts/batch_convert.py docs --output-dir out --to docx python3 ${CLAUDE_SKILL_DIR}/scripts/batch_convert.py docs --output-dir out --to pdf --pdf-engine xelatex --retries 2 python3 ${CLAUDE_SKILL_DIR}/scripts/batch_convert.py docs --output-dir out --to html --continue-on-error --report out/report.md --json-report out/report.json 批量行为： 保留相对路径：docs/a/b.md 变为 out/a/b.pdf。 跳过隐藏目录、.git、node_modules、dist、build、target 和输出目录。 显示进度，如 [3/28] 转换 docs/a.md -> out/a.pdf。 使用 --retries N 和 --retry-delay SEC 重试失败的文件。 默认情况下在失败后继续，除非传递 --fail-fast。 总结成功、失败和跳过的计数，并可以写入 Markdown/JSON 报告。 如果任何文件失败，请不要说整个批次成功。 列出失败的文件、报告路径和重试命令。

常用选项 需要选项 输入格式覆盖 --from markdown、--from gfm、--from docx 输出格式覆盖 --to html、--to docx、--to pdf、--to epub 独立文档 --standalone 或 -s 目录 --toc --toc-depth 3 编号部分 --number-sections 引用 --citeproc --bibliography refs.bib --csl style.csl DOCX 样式 --reference-doc reference.docx HTML/LaTeX 模板 --template template.html 或 --template template.tex HTML/EPUB CSS --css style.css PDF 引擎 --pdf-engine xelatex 图像/资源 --resource-path .:assets:images 提取 DOCX 媒体 --extract-media media 格式说明 加载 references/formats.md 时，格式支持或扩展映射很重要。 加载 references/workflows.md 以获取步骤式转换配方。 加载 references/troubleshooting.md 时，转换失败。

最佳实践 优先使用 Markdown 加 YAML 前置内容作为源真实性；将 DOCX/PDF/EPUB 视为生成输出。 在长时间转换之前验证引用、模板和资源路径。 对于批量转换，从小样本开始，然后转换大目录。 对于 PDF，选择引擎时输出质量很重要。 对于 Word 样式，使用 Pandoc 生成的 reference.docx 作为自定义样式的基础。

常见错误 运行 Markdown→PDF 而没有安装 PDF 引擎。 使用 pdflatex 进行中文文本；使用 xelatex 代替。 将 DOCX→Markdown 转换而没有 --extract-media，这会丢失嵌入的图像。 忘记 --resource-path 时，Markdown 引用 sibling 目录中的图像。 声称批次成功，而实际上只有部分文件转换。