客户想要	技能会做	客户能看到
完成本技能覆盖的工作	读取文章、调用 Obsidian 导出或降级本地渲染	PDF 路径、页数、文件大小
缺少 Obsidian / vault	提示降级方案（pandoc / weasyprint）	降级说明与命令
执行完成	验证 PDF 可打开、页数合理	完成回执 + 验证结果

客户如何使用

说明来源：vault 内已归档笔记路径 / X URL / 网页 URL / 本地 Markdown。
可选：指定输出目录（默认与源文件同目录）。
URL 来源先走 soia-pkm-clip-* 归档，再执行 PDF 导出。

依赖与安装

安装本技能：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-transform-obsidian-pdf -y

强依赖：Obsidian（vault 内文章）或 pandoc/weasyprint（vault 外降级）
可选：pdfinfo、pdftoppm（验收用）

私有配置放在 ~/.config/soia-skills/soia-pkm-transform-obsidian-pdf/config.yml，可用 SOIAPKMTRANSFORMOBSIDIANPDFCONFIGFILE 覆盖。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

日志与完成回执

完成：<一句话说明>。

日志摘要：
- source: <路径或 URL>
- provider: obsidian-native | pandoc | weasyprint
- output: <PDF 完整路径>
- pages: <页数>
- size: <文件大小>

验证：
- pdfinfo 确认页数、Creator、Producer
- 必要时渲染首页确认中文正常

问题与下一步：
- <无 / 降级原因 / 建议>

边界

来源是 URL → 先调用 soia-pkm-clip-* 归档为 vault Markdown，再导出 PDF。
来源是本地 Markdown 且不在 vault 内 → 降级：pandoc → weasyprint → 报告失败。
不做内容改写，只做格式转换（preserve 模式）。
输出目录默认与源文件同目录；vault 外文章输出到 outputs/transform/<YYYY>/<stem>/。

工作流

确认来源（vault 内 / URL / 本地文件）。
URL → soia-pkm-clip-* → 得到 vault Markdown 路径。
vault 内文章 → Obsidian URI 打开 → File > 导出 PDF（osascript 自动化，参照 references/provider-soia-local.md）。
确认保存路径，移到目标目录。
验收：pdfinfo 确认页数 > 0、Creator/Producer、文件非空；必要时渲染首页目视中文。vault 内文章的正式 PDF 必须满足 Creator: Chromium 或 Producer: Skia/PDF；wkhtmltopdf、Qt、pandoc 等只算降级产物。
回执。

验收门（摘自 quality-gates.md）

文件存在且非空（> 10KB）
pdfinfo 可读，Pages ≥ 1
Creator: Chromium 或 Producer: Skia/PDF（Obsidian 导出标志）
首页目视：中文正常、无乱码、无全黑页

详见 [PDF-QUALITY-GATES.md](PDF-QUALITY-GATES.md)。 [references/provider-soia-local.md](references/provider-soia-local.md)。

npx skills add soia-team/soia-open-pkm-vault-skills --skill soia-pkm-transform-obsidian-pdf