---
name: pdf-exporter
description: >
  MANDATORY: Use this skill for ANY PDF export or generation task.
  Triggers: "导出PDF", "下载PDF", "保存为PDF", "生成PDF", "PDF版本", "export pdf", "save as pdf".
  CRITICAL: NEVER write ad-hoc reportlab/fpdf code to generate PDFs. ALWAYS call export_pdf.py.
  This skill provides Chinese font support (wqy-microhei). Without it, Chinese text renders as black squares.
  Do NOT use for: reading PDFs, merging PDFs, OCR, PDF form filling (use pdf skill instead).
version: "1.1"
---

# PDF 导出技能（pdf-exporter）

## CRITICAL RULES

- MUST call `export_pdf.py` for ALL PDF export requests; **NEVER write ad-hoc reportlab/fpdf/canvas code**
- MUST use the bundled `wqy-microhei.ttc` font; **NEVER use Helvetica or other ASCII-only fonts** — they render Chinese as black squares
- NEVER fabricate a PDF file path; ALWAYS use the actual `output_path` returned by the script
- Output PDF MUST be saved to `/workspace/Document/PersonalDocuments/` (personal knowledge base)
- The script handles font registration automatically; no manual font setup needed

## 触发范围

**激活场景（MUST activate）：**
- 用户说"导出 PDF"、"下载 PDF"、"保存为 PDF"、"生成 PDF"、"PDF 版本"
- 用户要求将某个 HTML 报告文件转换为 PDF
- 用户说"把报告发给我"且当前有 HTML 报告文件
- 任何需要生成 `.pdf` 文件的场景

**排除场景（Do NOT activate）：**
- 读取、解析、提取 PDF 内容 → 使用 `pdf` skill
- 合并、拆分、旋转 PDF → 使用 `pdf` skill
- PDF 表单填写 → 使用 `pdf` skill

---

## 执行流程

### Step 1 — 导出 PDF

FIRST, send the user this message:
> 【正在导出 PDF】正在将报告转换为 PDF 格式，支持中文显示，请稍候...

THEN run:
```bash
python3 /workspace/skills/pdf-exporter/scripts/export_pdf.py \
  --input  <html_file_path> \
  --output /workspace/Document/PersonalDocuments/<报告名称_时间戳>.pdf \
  --title  "<报告标题>"
```

**参数说明：**

| 参数 | 说明 | 示例 |
|---|---|---|
| `--input` | 输入 HTML 文件的绝对路径 | `/workspace/skill/sql-report-generator/output/report_xxx.html` |
| `--output` | 输出 PDF 路径，**必须保存到** `/workspace/Document/PersonalDocuments/` | `/workspace/Document/PersonalDocuments/电力能耗趋势报告_1234567890.pdf` |
| `--title` | PDF 标题（显示在文档首页），使用中文报告名称 | `"电力能耗趋势报告"` |

**Output（脚本输出 JSON）：**
```json
{
  "status": "success",
  "message": "PDF 导出成功",
  "output_path": "/workspace/Document/PersonalDocuments/电力能耗趋势报告_1234567890.pdf",
  "file_size_kb": 128.5,
  "chinese_font": true,
  "sections_count": 12
}
```

- `output_path`：生成的 PDF 文件路径，用于后续引用
- `chinese_font`：若为 `false` 说明字体文件缺失，需检查 `/workspace/skills/pdf-exporter/fonts/wqy-microhei.ttc`
- 若 `status` 为 `error`，读取 `message` 字段排查原因

---

## Final Reply Format

成功导出后，回复格式如下：

**Part 1 — 摘要**：一句话说明 PDF 已生成，包含文件大小，并说明已保存至个人知识库。

**Part 2 — 文件地址标签**：
```
@@@@@/Document/PersonalDocuments/<文件名>.pdf@@@@@
```
例如：`@@@@@/Document/PersonalDocuments/电力能耗趋势报告_1234567890.pdf@@@@@`

**Part 3 — 建议标签（最后一行，格式固定）**：
```
#####%下载 PDF%￥点击上方链接下载 PDF 文件￥ %查看原始报告%￥返回查看 HTML 版本报告￥#####
```

---

## Bundled Resources

```
skills/pdf-exporter/
├── SKILL.md                    # 本文件
├── scripts/
│   └── export_pdf.py           # PDF 导出脚本（支持中文、表格、标题层级）
└── fonts/
    └── wqy-microhei.ttc        # 文泉驿微米黑中文字体（5MB，支持简繁中文+日韩）
```

**依赖**：reportlab（已安装于 `/workspace/.local/lib/python3.11/site-packages`）

---

## Error Handling

| 错误信息 | 原因 | 处理方式 |
|---|---|---|
| `reportlab 未安装` | reportlab 未安装到 `/workspace/.local` | 参考安装文档重新安装 reportlab |
| `中文字体文件不存在` | `fonts/wqy-microhei.ttc` 缺失 | 检查字体文件是否在正确路径 |
| `读取 HTML 文件失败` | HTML 文件路径错误或不存在 | 确认 `--input` 路径正确 |
| `PDF 生成失败` | reportlab 内部错误 | 查看 stderr 输出获取详细错误 |

---

## Notes

- 字体文件路径固定为 `/workspace/skills/pdf-exporter/fonts/wqy-microhei.ttc`，脚本会自动查找，无需手动指定
- PDF 输出文件名建议使用中文报告名称 + 时间戳，如 `电力能耗趋势报告_1234567890.pdf`
- 脚本会自动从 HTML 中提取标题（h1~h4）、段落、表格，图表（Canvas/SVG）无法转换为 PDF 图形，将被忽略
- 所有导出的 PDF 统一保存至 `/workspace/Document/PersonalDocuments/`，方便用户在个人知识库中检索
