Markdown → PDF Report

md-pdf-report · Markdown 双产物报告（PDF + MD）

MD 是事实源，PDF 是交付物。 同一份内容，两个产物：

• .md — 可二次编辑、可分发给其他 Agent
• .pdf — 打开即看、可分享给他人

（详见下一节"🚨 必做最后一步"）

核心用户偏好（Jialin）： 调研类内容要同时产出 PDF（方便看/分享）和 MD（方便二次编辑或分发给其他 Agent）。MD 是单一事实源，不要写两份。

---

何时使用

不适用：

• 简历、一页纸、产品白皮书、品牌文档 → 用 kami
• PPT/slides → 用 kami 的 slides 路径
• 简短消息/通知 → 直接发文字
• 不需要 PDF，只要 MD → 直接写 .md，不调用本 skill

---

快速开始

# 0. 首次使用：安装 Python 依赖（macOS 系统 Python 缺这两个模块）
pip3 install --user markdown weasyprint
# 注意：pip3 install 的脚本会装到 ~/Library/Python/3.9/bin（不在 PATH）
# 这是正常的；不影响 python3 -m 形式调用

# 1. 选模板（首次使用）
cp ~/.hermes/skills/md-pdf-report/templates/research-report.md ~/my-report.md
# 或 fact-check.md, scheme.md

# 2. 编辑内容（用任何 MD 编辑器）

# 3. 生成 PDF（用绝对路径调用，最稳）
python3 ~/.hermes/skills/md-pdf-report/md2pdf.py ~/my-report.md
# 等价但更短（前提：依赖已装）：
#   python3 -m md2pdf ~/my-report.md

# 4. 交付（飞书/Telegram）
# 在对话中：MEDIA:/Users/you/my-report.pdf

⚠️ macOS 真实调用姿势：本 skill 的 md2pdf.py 实际位于 skill 根目录（不是 scripts/ 子目录，SKILL.md 旧版本写错了）。系统 Python (/usr/bin/python3) 不预装 markdown 和 weasyprint 两个包，必须先 pip3 install --user。验证命令：python3 -c "import markdown, weasyprint" —— 两者都 OK 才能跑成功。

Python 用法：

from md2pdf import md_to_pdf
md_to_pdf("report.md")                    # 同名 .pdf
md_to_pdf("report.md", "out.pdf")         # 自定义输出
md_to_pdf("report.md", keep_html=True)    # 保留 .html（调试用）

---

工作流

Step 1 — 写 Markdown（事实源）

用标准 GitHub-flavored Markdown 写。支持的语法：

• 标题（#, ##, ###）、列表、表格
• 加粗、斜体、行内代码、代码块
• 链接 [文字](url)
• 引用 >、分隔线 ---

特殊区块（用 `` 实现，已在 CSS 中预定义）：

示例：

**重要：** 这是一段红色 callout 文字。Testing mixed CJK + English.

模板起点：

Step 2 — 转换为 PDF

python3 -m md2pdf /path/to/report.md            # 基本用法
python3 -m md2pdf report.md -o final.pdf         # 自定义输出
python3 -m md2pdf report.md --keep-html          # 保留中间 HTML（调试）

Step 3 — 交付（按平台分两种姿势）

重要：飞书 DM 场景下必须用 send_message 工具，不能只在 assistant 自然回复里写 MEDIA: 路径。 详见下方 Pitfall #6。

姿势 A：跨平台通用 — send_message 工具（推荐，最稳）

# 飞书 DM（用 home channel，gateway 自动路由到当前对话）
send_message(
    action="send",
    target="feishu",
    message="📄 报告标题（简短说明）\n\nMEDIA:/absolute/path/to/report.pdf"
)
# 返回值含 message_id 才算投递成功
# {"success": true, "platform": "feishu", "chat_id": "...", "message_id": "om_xxx"}

其他平台 target 格式：

• Telegram: telegram / telegram:chat_id:thread_id
• Discord: discord:#channel-name / discord:chat_id:thread_id
• 多平台 fan-out: target="all"

姿势 B：只在 assistant 自然回复里嵌 MEDIA: 路径

MEDIA:/absolute/path/to/report.pdf

• ✅ Telegram / Discord 等平台：可能会自动作为附件投递（取决于 gateway 实现）
• ❌ 飞书 DM：不可靠——2026-06-11 和 2026-06-11 两次 session 重蹈覆辙，用户都反馈"必须发到对话框"

⚠️ 经验反例（2026-06-11 + 2026-06-11 两次复现）：首次发布时只给了 /tmp/xxx.pdf 路径或只把 MEDIA: 路径嵌在 assistant 消息里就当作完成，用户立刻反馈"必须发到对话框"。完成定义 = 本地有文件 AND 对话框能看到附件（通过 send_message 工具投递并拿到 message_id 确认），二者缺一不可。

---

关键技术细节

⚠️ Pitfall #1: macOS .ttc 字体不可用

苹果系统 .ttc 字体文件（PingFang.ttc、STHeiti Medium.ttc）用 PostScript outlines， reportlab 和 weasyprint 都无法加载。

解决： 用 .ttf 字体文件：

完整路径、验证脚本、失败模式见 references/macos-cjk-fonts.md

⚠️ Pitfall #2: weasyprint 缺 C 库

brew install pango
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

md2pdf.py 的 bootstrap_macos() 在导入时自动设置。设 MD2PDF_NO_BOOTSTRAP=1 可关闭。

详细步骤、验证方法、Linux 替代见 references/weasyprint-bootstrap.md

⚠️ Pitfall #3: HTML 标签在 reportlab 表格里需要 Paragraph 包裹

如果混用 reportlab 路径（罕见，本 skill 默认 weasyprint）， 在 Table 单元格中不会自动渲染，必须把字符串用 Paragraph() 包一层。

⚠️ Pitfall #4: PDF 文件大小

weasyprint 默认嵌入全字体（2-3MB/页）。研究类报告 < 15 页通常无需优化。 超过 15 页或需要邮件发送时，参考 references/pdf-engine-comparison.md 的优化章节。

⚠️ Pitfall #5: macOS 系统 Python 缺 markdown + weasyprint（首次必踩）

症状：python3 -m md2pdf file.md 直接报 ModuleNotFoundError: No module named 'markdown' 或 No module named 'weasyprint'。

根因：

• macOS 自带 /usr/bin/python3 不带任何第三方包
• pip3 install 默认装到 ~/Library/Python/3.9/site-packages（用户级），不影响系统 Python
• 装完后 markdown_py / weasyprint 脚本在 ~/Library/Python/3.9/bin（不在 PATH）

修复（一次性）：

pip3 install --user markdown weasyprint
python3 -c "import markdown, weasyprint"  # 必须两个都 OK

依赖装好后两种调用方式都 work：

# 方式 1：绝对路径（最稳，永远 work）
python3 ~/.hermes/skills/md-pdf-report/md2pdf.py file.md

# 方式 2：模块形式（依赖已装时才 work）
python3 -m md2pdf file.md

# 方式 3：软链到 PATH 后（同样依赖要先装）
ln -s ~/.hermes/skills/md-pdf-report/md2pdf.py ~/.local/bin/md2pdf
md2pdf file.md

反模式（不要做）：

• ❌ 用 sudo python3 -m pip install 改系统 Python —— 污染 macOS 系统文件
• ❌ 不装依赖就跑任何 md2pdf 调用 —— 必失败
• ❌ 把 ~/Library/Python/3.9/bin 加到 PATH ——会和其他工具的同名脚本冲突

验证清单（必做）：

python3 -c "import markdown; print('markdown', markdown.__version__)"
python3 -c "import weasyprint; print('weasyprint', weasyprint.__version__)"

---

⚠️ Pitfall #6: 飞书 DM 场景下"MEDIA: 路径" ≠ 附件投递（2026-06-11 复现）

症状：PDF 已经在本地生成（ls -lh file.pdf 有 2.4MB），assistant 自然回复里也写了 MEDIA:/Users/.../file.pdf，但用户立刻反馈"把 PDF 发到对话框"——飞书对话框里看不到附件。

根因：

• assistant 消息里的 MEDIA: 前缀在 Telegram / Discord 等平台大概率被 gateway 处理为附件投递
• 但在 飞书 DM 场景，feishu plugin 的消息解析不识别纯文本里的 MEDIA: 路径（不是合法 markdown，也不是 send_message 的 file attachment API）
• 结果：飞书只渲染文本消息，不上传文件 → 用户看不到附件

修复（飞书 DM 场景必做）：

# ❌ 错误姿势：assistant 自然回复里写路径
print("MEDIA:/Users/.../file.pdf")  # 飞书不会上传！

# ✅ 正确姿势：用 send_message 工具
send_message(
    action="send",
    target="feishu",
    message="📄 报告标题\n\nMEDIA:/Users/.../file.pdf"
)
# 返回 message_id 才算成功

判断用哪种姿势：

完成定义（VBC）：

1. ls -lh file.pdf — 本地有文件 ✓
2. pdfinfo file.pdf | grep Pages — 验证渲染 ✓
3. send_message 返回值含 message_id — 对话框收到附件 ✓ 三步全 OK 才能告诉用户"PDF 已交付"

send_message 投递大文件可能 timeout（2026-06-11 复现）：

• 症状：send_message(target="telegram", message="...MEDIA:/path/to/big.pdf") 返回 success: true + message_id，但 warnings: ["Failed to send media ...pdf: Timed out"] —— 消息文本发出去了，附件没上传
• 触发条件：通常是大文件（> 1.5MB，PDF 字体嵌入后常见）+ Telegram。飞书反而更稳
• 修复姿势：
  1. 先验证 send_message 返回的 warnings 字段 —— success: true ≠ 附件成功
  2. 第一次失败后重试一次（多数情况 2-3 次内成功）
  3. 重试前可以考虑复制到 /tmp/ 改用短 ASCII 文件名（避开中文文件名 + 长路径可能引发的 edge case）
  4. 3 次仍失败 → 降级方案：把 PDF 路径 + 关键摘要用纯文本发，告诉用户"附件上传超时，请到本地路径查看"

# 健壮投递模板（按 attachments 是否真的上传决定要不要重试）
result = send_message(action="send", target="telegram", message=f"...\n\nMEDIA:{path}")
warnings = result.get("warnings", [])
if any("media" in w.lower() or "timed out" in w.lower() for w in warnings):
    # 附件失败 → 重试
    result = send_message(action="send", target="telegram", message=f"...\n\nMEDIA:{path}")
# 仍失败 → 降级文本说明

为什么不在 Pitfall #6 主线写：Pitfall #6 解决"压根没投递"的问题（assistant 自然消息 vs send_message 工具），这里的失败是"已经用对了工具但附件本身 timeout"，是不同的失败层次。

---

⚠️ Pitfall #7: weasyprint 不生成可点击 link annotation（必须后处理）

症状（2026-07-29 UNI 费用开关报告复现）：

• 用户要求"每条断言/数据下面附来源链接"
• MD 里的 [文字](https://...) 正常渲染为带下划线的蓝色文字
• 但 PDF 里链接点不开 —— 鼠标悬停不变手型，点击无反应
• macOS Preview / Chrome PDF viewer 都识别不到链接

根因（实测验证）：

• weasyprint.HTML(string=html).write_pdf() 默认不输出 PDF Link annotation
• HTML 里 `` 会被渲染为带样式的可见文字，但 PDF 字节流里 /URI 标记数 = 0
• 实测 5 个场景（baseline / base_url / stylesheets / presentational_hints / 段落多链接）URI 全是 0
• 这是 weasyprint 66.0 的设计行为，不是 bug，也没有"打开开关"的 API

为什么不能靠改 CSS / base_url 修复：

• CSS 加 text-decoration: underline 能让链接视觉上像链接，但 PDF annotation 还是不生成
• 加 base_url 只影响相对路径解析，对绝对 URL 无影响
• presentational_hints=True 不存在该参数

唯一修复方案：pikepdf 后处理

完整流程（已实测通过，51/68 annotation 命中，macOS Preview 可点）：

python3 -m pip install --user pikepdf pdfminer.six

from pikepdf import Pdf, Name, Dictionary, Array
from pdfminer.high_level import extract_pages
from pdfminer.layout import LTTextContainer
import re

LINK_RE = re.compile(r'\[([^\]]+)\]\((https?://[^)]+)\)')
md_links = LINK_RE.findall(md_text)  # 不去重!表格里同一 URL 多行要各算一个

# Step 1: weasyprint 渲染 PDF(写到中间文件,pikepdf 不能覆盖输入)
HTML(string=html).write_pdf('/tmp/tmp.pdf')

# Step 2: pdfminer 抽每页 LTTextContainer + bbox
layouts = list(extract_pages('/tmp/tmp.pdf'))
page_blocks = []
for layout in layouts:
    blocks = [el for el in layout if isinstance(el, LTTextContainer)]
    page_blocks.append(blocks)

# Step 3: 按 link_text 匹配 block,记录 (url, bbox, link_text)
# 关键:不去重 + used_blocks 防止同一 block 被多个链接误占
used_blocks = set()
matched_per_page = [[] for _ in layouts]

for link_text, url in md_links:
    target = link_text.lower().strip()
    fingerprint = target[:25] if len(target) > 25 else target
    found = False
    for p_idx, blocks in enumerate(page_blocks):
        for b_idx, block in enumerate(blocks):
            key = (p_idx, b_idx)
            if key in used_blocks:
                continue
            block_text = block.get_text().lower()
            if target in block_text:
                matched_per_page[p_idx].append((url, block.bbox, link_text))
                used_blocks.add(key)
                found = True
                break
        if found:
            break
    if not found:
        # fingerprint 兜底
        for p_idx, blocks in enumerate(page_blocks):
            for b_idx, block in enumerate(blocks):
                key = (p_idx, b_idx)
                if key in used_blocks:
                    continue
                block_text = block.get_text().lower()
                if fingerprint in block_text:
                    matched_per_page[p_idx].append((url, block.bbox, link_text))
                    used_blocks.add(key)
                    found = True
                    break
            if found:
                break

# Step 4: pikepdf 写入 Link annotation(注意 padding 扩大点击区)
pdf = Pdf.open('/tmp/tmp.pdf')
for i, page in enumerate(pdf.pages):
    annots = page.get('/Annots', Array([]))
    for url, (x0, y0, x1, y1), _ in matched_per_page[i]:
        # 表格 cell bbox 偏小,padding 让点击更容易命中
        width = float(x1 - x0)
        pad_h = 4 if width < 150 else 2
        rect = [float(x0)-pad_h, float(y0)-2, float(x1)+pad_h, float(y1)+2]
        annot = Dictionary(
            Type=Name('/Annot'),
            Subtype=Name('/Link'),
            Rect=Array(rect),
            Border=Array([0, 0, 0]),
            A=Dictionary(Type=Name('/Action'), S=Name('/URI'), URI=url)
        )
        annots.append(annot)
    page['/Annots'] = annots
pdf.save('/tmp/final.pdf')

VBC 验证清单（用户交付前必过）：

1. pdfinfo final.pdf | grep Pages — 页数 OK
2. 统计 annotation 数:应接近 MD 里链接数（不去重 50–70% 命中率，去重 100%）
3. macOS Preview 打开 hover 链接 → 手型 + 点击跳转
4. 表格列里每个 cell 链接都点得开（不是只有第一个）

已知陷阱：

• 表格 cell 链接：LTTextContainer.bbox 是整 cell 的 bbox，不是精确链接文字 bbox。必须给 Rect 加 padding（横向 4pt、纵向 2pt），否则用户点 cell 边缘会落空
• 同 URL 多行出现：不能去重！表格里 CoinGecko 出现 4 次 = 要 4 个独立 annotation，各指各的 cell。set(md_links) 会丢 3 个
• pikepdf 不允许覆盖输入文件：先 weasyprint 写到 /tmp/tmp.pdf，pikepdf 打开后再 save('/tmp/final.pdf')
• 简写引用未匹配是正常的：[Blockworks]（6 字符）+ fingerprint 25 字符兜底，文本完全一致但被前面的 [Blockworks — Uniswap finally turns the fee switch] 先占了 block，命中率为 0。可接受（不影响核心可点性）

完成定义（用户验收）：

• macOS Preview 打开 → 鼠标悬停链接变手型 ✓
• 点击跳转浏览器打开 URL ✓
• 表格里每一行的来源链接都能点（不是只第一个）✓
• 链接文字后不显示完整 URL（CSS 不加 content: attr(href)，保持视觉干净）

参考脚本位置：/tmp/regen.py（验证可用的完整流程，下次直接复用）

---

引擎选择

md2pdf.py 默认使用 weasyprint（最佳平衡点）。三种引擎详细对比、迁移路径见 references/pdf-engine-comparison.md。

简要决策：

---

文件结构

~/.hermes/skills/md-pdf-report/
├── SKILL.md                    # 本文件
├── md2pdf.py                   # 主转换模块（绝对路径调用 / 软链 / 模块形式均可）
├── templates/
│   ├── research-report.md     # 调研报告模板（自己的研究输出）
│   ├── research-digest.md     # 研究消化模板（消化别人研究，必出批判性分析）
│   ├── fact-check.md          # 事实核查模板
│   └── scheme.md              # 方案/计划模板
├── references/
│   ├── macos-cjk-fonts.md     # 中文字体路径与陷阱
│   ├── weasyprint-bootstrap.md # C 库安装与环境变量
│   └── pdf-engine-comparison.md # weasyprint vs reportlab vs pandoc
└── examples/
    ├── Mike_Lynch_FactCheck.md  # 真实案例（7页 PDF）
    └── test_report.md           # 最小测试用例

注意：旧版 SKILL.md 把 md2pdf.py 写在 scripts/ 子目录下，但实际位于 skill 根目录。如果以后发现位置真的变了，先 find ~/.hermes/skills/md-pdf-report -name "md2pdf.py" 确认。

软链到 PATH（可选）：

ln -s ~/.hermes/skills/md-pdf-report/md2pdf.py ~/.local/bin/md2pdf
chmod +x ~/.hermes/skills/md-pdf-report/md2pdf.py
# 然后直接用: md2pdf report.md
# ⚠️ 前提：依赖已装（见 Pitfall #5）

---

自定义 CSS

from md2pdf import md_to_pdf, DEFAULT_CSS

# 追加自定义规则
custom_css = DEFAULT_CSS + """
h1 { color: #B91C1C; }  /* 改标题为红 */
table th { background: #0F172A; }  /* 表头更深 */
"""

md_to_pdf("report.md", css=custom_css)

---

验证清单（生成 PDF 后必做）

• 中文渲染正常（不是方块、不是问号）
• 表格不被截断
• 代码块/引用样式正确
• callout/note/warn 区块显示正确
• 页码/页脚正常
• 链接可点击（导出后 hover 试一下）
• 文件大小 < 5MB

快速验证命令：

pdfinfo report.pdf | grep Pages           # 检查页数
pdftotext report.pdf - | head -50         # 检查中文渲染

---

维护

• macOS 系统升级后字体路径可能变 → find /System/Library/AssetsV2 -name "STXIHEI.ttf" 重新确认
• PDF 突然乱码 → 90% 是字体路径失效，重新 find
• 导出报 cannot load library 'libgobject' → pango 没装好或 DYLD_FALLBACK_LIBRARY_PATH 没设
• weasyprint 版本更新 → 关注 changelog
• 首次跑报 ModuleNotFoundError: No module named 'markdown' 或 'weasyprint' → macOS 系统 Python 缺依赖，pip3 install --user markdown weasyprint（详细见 Pitfall #5）
• python3 -m md2pdf 找不到模块 → md2pdf.py 在 skill 根目录不在 scripts/，改用绝对路径：python3 ~/.hermes/skills/md-pdf-report/md2pdf.py file.md
• 飞书 DM 场景用户看不到 PDF 附件 → assistant 自然消息里的 MEDIA: 路径在飞书 DM 不被处理为附件投递，必须用 send_message 工具（详细见 Pitfall #6）