公众号文章转 PDF

把一个微信公众号链接变成一份能直接阅读和归档的 PDF。三步：抓取 → 排版 → （可选）入 ima。

何时使用

用户丢来一个 mp.weixin.qq.com/s/... 链接，要求转 PDF、导出、存档
用户要求把某篇公众号文章保存到 ima 知识库
需要把长文（万字级）做成带目录层级、代码块、提示框的中文 PDF

环境准备（首次运行）

PDF 用 PyMuPDF 离线生成，不依赖浏览器（Chrome/Edge 无头模式在本机常被已打开的浏览器实例占住而失败，别走这条路）。

# 创建隔离虚拟环境（只用一次，之后直接复用）
"C:/Users/liebe/.workbuddy/binaries/python/versions/3.13.12/python.exe" -m venv "C:/Users/liebe/.workbuddy/binaries/python/envs/default"
"C:/Users/liebe/.workbuddy/binaries/python/envs/default/Scripts/pip.exe" install pymupdf
# 仅在需要上传到 ima 时安装
"C:/Users/liebe/.workbuddy/binaries/python/envs/default/Scripts/pip.exe" install cos-python-sdk-v5

Python 可执行文件统一用：C:/Users/liebe/.workbuddy/binaries/python/envs/default/Scripts/python.exe

工作流

Step 1 · 抓取原文

用 WebFetch 拉取链接，prompt 明确要求不要总结、直接输出原文：

请完整提取这篇文章的：标题、作者/公众号名称、发布时间、正文全部内容
（保留段落结构和小标题）。不要总结，直接输出原文。

WebFetch 会转 HTML → Markdown，通常够用。若正文被截断或丢失（常见于超长图文），改用浏览器技能或让用户提供复制文本。

抓完后先确认拿到了：标题、作者/公众号、发布时间、正文全文。内容不全就不要往下走。

Step 2 · 写成结构化中间文件 `content.txt`

这是质量的关键一步。把抓取的内容按标记语法落到 content.txt（UTF-8），每行一条记录：

@@H1 文章主标题
@@META 原作者：X ｜ 公众号：Y ｜ 发布时间：Z
@@SEC SECTION 01
@@H2 一级章节标题
@@H3 1.1 二级小节
@@P 正文段落，支持 <b>加粗</b>
@@LABEL 小标签文字
@@PRE 等宽模板块第一行
@@NOTE 黄色提示框内容
@@LI 列表项（连续多行自动合并成一个 ul）
@@END 结束标记

完整语法与注意事项见 references/content-markup.md——写文件前先读它。

要点速记：

代码块/模板用 @@PRE，连续多行每行都加 @@PRE 前缀；块内空行写 @@PRE（裸空行）
<b>…</b> 是唯一保留的 HTML，会被渲染成粗体；正文里的其他 < > 会被自动转义
不要自作聪明精简原文，用户要的是完整归档

Step 3 · 渲染 PDF

cd <工作目录>
"C:/Users/liebe/.workbuddy/binaries/python/envs/default/Scripts/python.exe" \
  "C:/Users/liebe/.workbuddy/skills/wechat-article-to-pdf/scripts/build_pdf.py" \
  content.txt "输出文件名.pdf" --header "页眉文字"

--header 建议用文章短标题（如 Seedance 2.5 提示词指南），会印在每页左下角，右下角是页码。

脚本会自动：A4 页面 + 52pt 页边距、自动分页、嵌入中文字体（PyMuPDF 内置 china-s，无需外部字体文件）、压缩输出。

Windows 下若输出 PDF 已存在且被占用，先 rm -f 再生成，否则会报权限错误。

Step 4 · 校验内容完整性（必做）

不要只看文件生成成功就交差。用关键词抽查，确认没有内容被吞掉：

"C:/Users/liebe/.workbuddy/binaries/python/envs/default/Scripts/python.exe" -c "
import pymupdf
d = pymupdf.open('输出文件名.pdf')
full = '\n'.join(p.get_text() for p in d)
nospace = ''.join(full.split())
print('pages:', d.page_count, '| chars:', len(full))
for k in ['关键词1','关键词2','最后一节的标题']:
    ok = (k in full) or (k.replace(' ', '') in nospace)
    print(('OK  ' if ok else 'MISS'), k)
"

比对时保留空格版本。PDF 提取文本会在部分字符间插入空格，'CASE A' 直接匹配会假阴性——所以要么用原始文本比对，要么关键词也去掉空格再比。

抽查清单：文章标题、每个章节标题、正文里几个独特的专有名词/模板片段、最后一个章节的收尾内容。

已知坑：@@PRE 多行块解析时，如果块内空行后面紧跟的不是 @@ 起首的行，就属于块内分隔而非块结束——build_pdf.py 已正确处理，别改回"见空行即断块"的写法，那会只保留模板首行。

Step 5 · 存入 ima 知识库（可选，用户要求时才做）

完整流程（含 create_media → COS 上传 → add_knowledge 三步的字段说明）见 references/ima-workflow.md——执行前先读它。

摘要：

mcp__ima-mcp__get_addable_knowledge_base_list 列出可入库的知识库，跟用户确认目标（或选唯一/默认那个）
mcp__ima-mcp__create_media 换取上传凭据（返回 media_id + COS 临时密钥）
scripts/upload_cos.py 把 PDF 传到 COS
mcp__ima-mcp__add_knowledge 提交入库

Step 6 · 交付

清理临时文件（_stage*.pdf、预览 png、调试脚本）
写一份简短的 overview 说明产物位置与页数
用 present_files 把 PDF 呈现给用户

排版样式一览

| 标记 | 渲染效果 | |---|---| | @@H1 / @@META | 大标题 + 灰色元信息，下方 1.5pt 分割线 | | @@SEC | 黑底白字全宽分节带（如 SECTION 01） | | @@H2 / @@H3 | 章节标题（H3 带蓝色左侧竖线） | | @@LABEL | 蓝底蓝字小标签 | | @@PRE | 灰底蓝左边框的等宽模板块 | | @@NOTE | 黄底橙边框提示框 | | @@LI | 圆点列表 | | @@END | 居中灰色 END OF GUIDE 收尾 |

想换配色改 scripts/build_pdf.py 里的 CSS 常量即可。

故障排查

| 现象 | 原因 / 解法 | |---|---| | Chrome headless 打印无输出、exit code 非零 | 浏览器已被现有会话占用。改走 PyMuPDF（本 skill 的默认路线） | | PDF 里中文是空白或方块 | CSS 里字体必须是 "china-s"，不要用 simsun/msyh 等系统字体名 | | PermissionError 写 PDF | 目标 PDF 正被 PDF 阅读器打开，先关闭或 rm -f 后重跑 | | 模板块只剩第一行 | @@PRE 块解析被截断，见 Step 4 的已知坑 | | 生成的 PDF 缺内容 | 回到 Step 2 检查 content.txt 是否本身就缺失，别在 PDF 环节找原因 | | OSError: [safe-delete] 操作失败 | 所在环境拦截了 Path.unlink()。build_pdf.py 已把中间文件放进系统临时目录规避，不要在脚本里加回主动删除逻辑 | | 校验时关键词明明有却报 MISS | PDF 提取文本插了空格，见 Step 4 的比对说明 |