Claude Style Pdf

---
name: claude-style-pdf
description: Claude 暖纸风格 PDF 生成器（Markdown → 暖纸风 HTML → Chromium 无头打印 → PDF）。与 claude-style-ppt 同一套设计语言（温润米色底、赭红强调、思源宋体+Source Serif Pro、真 SVG 装饰）。适合知识分享/学习笔记、报告、文章随笔、白皮书、方案、操作指南。
---

# Claude 风格 PDF 工作流

把一句话主题、一份大纲、或一篇文档，转成视觉上忠实于 Claude.ai 调性的**暖纸风 PDF**。
作者写 **Markdown**，CSS 主题负责好看；Python 把它渲染成 PDF。

## 第一性原则：三条试金石（与 PPT skill 同源）

1. **纸感**：背景温润米色 `#F4EEE1`，强调赭红 `#A6645A`，正文暖墨黑 `#2C2826`。**绝不出现冷色**（蓝/绿/紫/冷灰）。
2. **节奏**：全衬线（中文思源宋体、西文 Source Serif Pro），行高 1.6，正文测距 ~32 字，字号梯度收窄。让人"读"而非"扫"。
3. **克制**：无阴影、无渐变、圆角≤4px、边框≤0.5pt。装饰只允许引用竖条/波浪线/章节编号/年轮四种；赭红是稀缺高光，每页 `==变色==` 最多 2-3 处，优先用波浪线/加粗。

设计 token 固化在 `scripts/theme.py`（与 PPT 的 `tokens.py` 同色），改色/改字号只动这一处。

## 工作流（状态机）

### 0. SCENE — 场景采访（用户未说明用途时先问）

> 这份文档用于什么场景？(知识分享/学习笔记 · 报告 · 文章随笔 · 白皮书 · 方案提案 · 操作指南，或直接描述)

场景决定：是否要封面/目录、密度（`density`）、是否自动章节编号（`numbered`）、用哪些块。

### 1. INTAKE — 识别输入

| 输入 | 处理 |
|---|---|
| 一两句话主题 | 你生成大纲与全部正文 |
| 大纲 | 你按大纲填正文 |
| 长文档 | 切章节、提炼，保留原意 |

### 2. PLAN — 列章节结构

用 `#`/`##`/`###` 规划层级。每个一级章节是一个 `#`。长文每 1-2 个大章节前可放一个**章节分隔整页**（`::: divider`）。

### 3. WRITE — 写 Markdown

写到工作目录的一个 `.md`，结构见下方「作者契约」。

### 4. BUILD — 渲染

```bash
python scripts/build_pdf.py <输入.md> --output "<桌面或指定>.pdf" -v
```
不要 AI 配图占位时加 `--no-images`。

### 5. DELIVER — 交付

读 stdout 摘要 JSON（页 md、是否目录、内嵌图/占位图数），用自然语言告知用户：生成到哪、是否含占位图（需补真实配图）。

## 作者契约：Markdown + frontmatter + 块指令

### frontmatter（YAML，文件顶部）

```yaml
---
title: 文档标题           # 必填（封面/页眉用）
subtitle: 副标题          # 可选
author: 作者              # 可选
date: 2026-05-31          # 可选
doc_type: notes           # 语义标记：notes/report/article/whitepaper/guide
language: zh-CN
density: medium           # low | medium | high → 整体字号微调
cover: true               # 是否生成封面页（带年轮角饰）
toc: true                 # 是否生成目录页
numbered: false           # 正文 H1/H2 是否自动章节编号；用 divider 承载编号时设 false 避免重号
accent: "#A6645A"          # 可选，覆盖强调色
---
```

### 正文（标准 Markdown）

`#`/`##`/`###` 标题、段落、`-`/`1.` 列表、`> 引用`、表格、` ```代码``` `、`![alt](图)`。

**三层强调（与 PPT 同语义，由轻到重，优先用轻的）**：
- `~~文字~~` = 墨色文字 + 赭红波浪下划线（最克制、最 Claude，首选）
- `**文字**` = 加粗，不改色
- `==文字==` = 赭红加粗（最重，即"标红"，每页 ≤2-3 处）

代码块/行内代码内的标记不会被改写。

### 块指令（容器，`:::` 包裹）

```markdown
::: callout idea
批注框。首词选图标变体：idea(灯泡)/note(书)/warn(天平)。内部是 Markdown。
:::

::: pullquote
居中金句，上下细线。
:::

::: figure caption="图1：流程示意"
![alt 文本/英文生图 prompt](图片路径)
:::

::: divider num="01" title="控制循环" subtitle="harness 的骨架"
:::
```

## 元素目录（都按暖纸调性渲染）

封面（大衬线标题 + 赭红短线 + 年轮 SVG 角饰）· 自动目录（衬线 + 引导点）· 标题 H1–H3（可选自动编号）· 正文（衬线、两端对齐）· 引用块（赭红左竖条）· 金句 pullquote · callout 批注框（暖卡片底 + 图标）· 图 + 图注 · 表格（仅横细线、赭红表头）· 章节分隔整页（呼应 PPT divider）· 代码块（暖灰底等宽）· 页脚页码。

装饰（波浪线/年轮/9 个线性图标 focus/time/growth/star/idea/book/balance/connect/person）全部输出**真 SVG**。

## 渲染引擎与已知限制

- 引擎：**Playwright / Chromium 无头打印**（全保真 CSS + 真 SVG，Windows 无需 GTK；无头无弹窗）。首次需 `playwright install chromium`。
- **满铺米色**靠根元素 `html` 背景传播到整张纸（含页边），每页都铺。
- **目录无页码**：Chromium 打印不支持 `@page` 边距盒计数器，故目录只列条目（可点击跳转），不显示页码。需要目录页码可改用 WeasyPrint（Windows 需装 GTK）。
- **页码**：用 Playwright 页脚，所有页（含封面）统一显示。
- **AI 配图**：默认占位（暖色虚线框显示 alt/prompt）；本地存在的图自动内嵌为 data URI。接 AI 生图可后续接 `claude-style-ppt` 的 `gen_image`。
- **章节编号 vs 分隔页**：两者都用会重号；用 `::: divider` 承载编号时把 `numbered` 设 false。

## 依赖

`pip install markdown jinja2 pyyaml playwright && playwright install chromium`
最佳调性需系统装思源宋体(Source Han Serif SC) + Source Serif Pro/4；缺失会回退。