核心用法
Pandoc Skill 是一个封装了开源文档转换工具 Pandoc 的自动化技能，用于在各种文档格式之间进行高质量转换。该技能支持双向转换 Markdown、HTML、PDF、DOCX、EPUB、LaTeX、ODT、RST、Org、MediaWiki、JIRA、CSV、Jupyter Notebook 等 50 余种格式。
基础转换流程：通过 scripts/convert.sh 助手脚本实现自动化检测，自动识别输入/输出格式（基于文件扩展名），智能选择 PDF 引擎，并传递参数至底层 Pandoc 命令。转换过程遵循"读取源格式 → 解析为内部 AST → 写入目标格式"的三阶段模型。
关键控制点：
- PDF 引擎选择：
xelatex（Unicode/字体最优）、lualatex（复杂排版）、tectonic（自包含 TeX）、pdflatex（ASCII 文档最快）、或 HTML/CSS 引擎（weasyprint、wkhtmltopdf、prince） - 样式控制：CSS 用于 HTML 类输出，LaTeX 变量/模板用于 PDF，参考文档用于 DOCX/ODT
- 增强功能：目录生成（
--toc）、元数据注入（-M）、媒体提取（--extract-media）、Lua 过滤器、多文件合并
显著优点
1. 格式覆盖全面：支持学术出版、技术文档、电子书、办公文档等全场景格式需求
2. 转换质量高：基于 AST 的中间表示确保语义保留，非简单的文本替换
3. 样式深度可控：从快速转换到企业级品牌定制均有对应方案
4. 工程化封装：convert.sh 脚本自动处理引擎检测、错误提示、参数校验，降低使用门槛
5. 多引擎 PDF 生成：针对不同场景提供 6 种 PDF 引擎选项，平衡质量、速度与资源占用
潜在缺点与局限性
1. 外部依赖复杂：必须预装 Pandoc，PDF 生成还需额外安装 TeX 发行版或特定引擎，完整环境配置较重
2. CSS-LaTeX 割裂：PDF 输出若使用 LaTeX 引擎则忽略 CSS，样式需用两套技术栈维护
3. 复杂排版边界：极度复杂的页面布局、交互式 HTML 特性可能无法完美转换
4. 字体渲染差异：跨平台字体可用性差异可能导致 PDF 字符缺失（需显式指定支持字体）
适合人群
- 技术写作者：Markdown 源文件输出多格式分发版本
- 学术研究者：LaTeX/Pandoc 工作流生成 PDF 论文与 HTML 预印本
- 出版与文档工程师：批量文档格式标准化、电子书生成（EPUB）
- 企业 IT：文档自动化流水线，品牌模板化 DOCX/PDF 输出
常规风险
- 依赖缺失导致转换失败：未安装对应 PDF 引擎时生成 PDF 将报错
- 样式预期落差：用户对"美观"的期望与实际模板效果不一致
- 路径与资源引用：相对路径图片/CSS 在转换后可能失效，需使用
--self-contained或绝对路径 - 敏感信息泄露：模板或参考文档可能携带元数据，用于外部文件时需注意清理
该技能本身为 Pandoc 的调用封装，不引入额外网络请求或远程代码执行风险，安全性主要取决于底层 Pandoc 及 PDF 引擎的安装来源与版本。