技能介绍

问题：Markdown 转 PDF 的排版困境

把 Markdown 文档变成一份排版专业、可直接分发的白皮书 PDF，通常不是一条 pandoc 命令就能搞定的事。默认的 pandoc PDF 输出样式平淡，封面、目录页、章节强调线、代码块配色、页脚页码这些细节都需要手动调。而当你在 CI 或 Agent 流程里自动化这条链路时，字体缺失、模板路径不对、中间产物残留等问题会反复出现。

工作原理

这个技能用 pandoc + typst 的组合解决上述问题。核心是一套 Typst 模板（templates/whitepaper.typ）和一组字体资源：正文用 Source Sans 3 可变字体，代码块和行内代码用 Source Code Pro。

执行流程完全无人值守，技能不会在中途问你"是否继续"或"是否删除文件"，而是一口气跑完以下步骤：

解析参数：从 $ARGUMENTS 提取输入的 Markdown 路径和可选的输出 PDF 路径；输出路径缺省时沿用输入文件名加 .pdf 后缀。
检查依赖：自动检测并安装缺失的 pandoc 和 typst。
定位资源：动态确定插件根目录，把 Typst 模板复制到输出目录。
执行转换：在输出目录中运行 pandoc，模板自行生成目录页（因此不能传 --toc，否则会与模板内置的目录冲突）。
清理产物：PDF 生成后立即删除所有中间文件（.md、.html 等），只保留最终 PDF。
汇报结果：仅返回一行 PDF created: [path]。

文档结构由 Markdown 文件的 YAML frontmatter 驱动：title 是必填项，缺失时技能会询问；subtitle、date、author 为可选，分别出现在封面副标题、封面与页脚、封面作者列表。排版规则包括：H1 用 Black (900) 字重并在其前分页，H2 用 Bold (700) 并配蓝色强调线，正文两端对齐，代码块灰底圆角，引用块蓝色左边框。

适用边界与注意事项

frontmatter 必须放在文件最开头，用 --- 行包裹；如果放在标题或空行之后，模板不会读取它。
值里含冒号时要用引号包裹，比如 title: "AEM: A Guide"。
不要在 frontmatter 里塞 fontsize、papersize 这类 pandoc 变量，应通过 -V key=value 传入；技能内部已处理默认值（A4、10pt、Source Sans 3）。
macOS 和 Linux 环境需要预装 pandoc 和 typst，技能会在缺失时尝试自动安装。
如果 Typst 报字体找不到，检查 TYPST_FONT_PATHS 是否指向插件的 fonts/ 目录。
最需要注意的一点：技能在生成 PDF 后会删除所有源文件。如果你的 Markdown 源稿不在版本控制中，请提前备份，否则生成的 PDF 会是唯一剩下的产物。