---
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", "转成PDF", "PDF报告".
  CRITICAL: NEVER write ad-hoc reportlab/fpdf/canvas code to generate PDFs. ALWAYS call export_pdf.py via this skill.
  This skill provides Chinese font support (wqy-microhei). Without it, Chinese text renders as black squares.
  SUPPORTS AI analysis injection: Agent writes analysis text, passes via --analysis flag, skill inserts it as a dedicated chapter.
  Do NOT use for: reading PDFs, merging PDFs, OCR, PDF form filling (use pdf skill instead).
version: "1.2"
---

# PDF 导出技能（含 AI 智能分析）

将 HTML 报告导出为支持中文的 PDF 文件，并在报告末尾自动插入 Agent 生成的 AI 智能分析章节。

## 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)
- ALWAYS include `--analysis` parameter with AI-generated analysis when exporting data reports
- The `--analysis` value MUST be written in Chinese, supports Markdown: `##` for subheadings, `-` for bullet points

## 触发范围

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

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

---

## 执行流程

### Step 1 — 生成 AI 分析内容

FIRST, send the user this message:
> 【正在生成 AI 智能分析】正在根据报告数据生成分析内容...

THEN: 根据已有的 HTML 报告数据（从上下文或 HTML 文件中提取关键数据），自行撰写 AI 分析文字。

**分析内容应包含（根据数据类型选择适用项）：**
- `## 数据概况`：用 1~2 句话总结核心指标（最大值、最小值、平均值、总量等）
- `## 趋势分析`：描述数据的变化趋势（上升/下降/波动/平稳）
- `## 异常识别`：指出明显偏高或偏低的数据点及可能原因
- `## 优化建议`：基于数据给出 2~3 条可操作的具体建议

**分析格式示例：**
```
## 数据概况
本报告统计了园区 2 月份共 28 天的每日用电量，总用电量为 12,450 kWh，日均 444.6 kWh。

## 趋势分析
整体用电量呈先升后降趋势，2 月 10~15 日为用电高峰期，峰值达 680 kWh/天。

## 异常识别
- 2 月 14 日：用电量 680 kWh，较日均高出 53%，疑为设备满负荷运行所致
- 2 月 22 日：用电量 180 kWh，较日均低 60%，疑为节假日停产

## 优化建议
- 建议在用电高峰期（10~15 日）错峰生产，降低峰时电费
- 对 2 月 14 日异常用电进行排查，确认是否存在设备故障或浪费
- 建议安装智能电表，实现分时段精细化用电管理
```

Output: 将分析文字保存为变量 `ANALYSIS_TEXT`，传入 Step 2 的 `--analysis` 参数。

---

### Step 2 — 导出 PDF

FIRST, send the user this message:
> 【正在导出 PDF 报告】正在生成含 AI 分析的 PDF 文件，请稍候...

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

**参数说明：**

| 参数 | 说明 | 示例 |
|---|---|---|
| `--input` | 输入 HTML 文件的绝对路径 | `/workspace/skill/sql-report-generator/output/report_xxx.html` |
| `--output` | 输出 PDF 路径，**必须保存到** `/workspace/Document/PersonalDocuments/` | `/workspace/Document/PersonalDocuments/电力能耗趋势报告_1234567890.pdf` |
| `--title` | PDF 标题（显示在文档首页），使用中文报告名称 | `"电力能耗趋势报告"` |
| `--analysis` | Step 1 生成的 AI 分析文字，用引号包裹，内部换行用 `\n` 表示 | `"## 数据概况\n总用电量 12,450 kWh..."` |

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

- `output_path`：生成的 PDF 文件路径，用于 Final Reply 中的地址标签
- `chinese_font`：若为 `false` 说明字体文件缺失，需检查 `/workspace/skills/pdf-exporter/fonts/wqy-microhei.ttc`
- `has_analysis`：若为 `false` 说明 `--analysis` 参数为空，AI 分析章节未插入
- 若 `status` 为 `error`，读取 `message` 字段排查原因

---

## Final Reply Format

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

**Part 1 — 摘要**：2~3 句话说明 PDF 已生成，包含文件大小，并说明已保存至个人知识库，简要提及 AI 分析的核心结论。

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

**Part 3 — 建议标签（最后一行，格式固定）**：
```
#####%下载 PDF 报告%￥点击上方链接下载完整 PDF 报告（含 AI 智能分析）￥ %继续深入分析%￥基于当前数据进行更深度的挖掘￥ %导出其他格式%￥将报告导出为 Excel 或图片格式￥#####
```

---

## Bundled Resources

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

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

---

## Error Handling

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

---

## Notes

- `--analysis` 参数支持多行 Markdown 文字：`##` 开头为绿色小标题，`-` 开头为列表项，普通文字为正文段落
- AI 分析章节使用绿色（`#0d6e4f`）主题色，与数据报告的蓝色（`#1677FF`）主题色区分，视觉上清晰分离
- 分析末尾自动添加"以上分析由 AI 自动生成，仅供参考"免责声明及生成时间
- 字体文件路径固定为 `/workspace/skills/pdf-exporter/fonts/wqy-microhei.ttc`，脚本自动查找，无需手动指定
- PDF 输出文件名建议使用中文报告名称 + 时间戳，如 `电力能耗趋势报告_1234567890.pdf`
- 脚本会自动从 HTML 中提取标题（h1~h4）、段落、表格；图表（Canvas/ECharts/SVG）无法转换，将被忽略
- 所有导出的 PDF 统一保存至 `/workspace/Document/PersonalDocuments/`，方便用户在个人知识库中检索