# PNG 导出模式规范

本文档是 PNG 导出模式的规范，生成 SVG 文件后转换为高保真 PNG，然后插入 Markdown 图片引用。

## 模式特性

- 生成独立的 SVG 文件
- 自动转换为高保真 PNG（600 DPI）
- 插入 Markdown 图片引用
- 跨平台兼容性最佳

---

## 依赖 {#依赖}

PNG 转换功能需要安装以下依赖：

### 系统依赖

| 依赖 | 安装方式 |
|------|----------|
| Node.js (v18+) | macOS: `brew install node`<br>Linux: `sudo apt-get install nodejs npm` |

### Node.js 包

| 包名 | 用途 | 安装命令 |
|------|------|----------|
| `puppeteer` | 高保真 SVG 转 PNG 渲染 | `npm install puppeteer` |

**注意**：如果只使用 SVG 直接嵌入模式（dynamic-svg/static-svg），无需安装这些依赖。

---

## 一、文件保存位置

### 强制规则

- **所有 SVG 文件必须保存到源文章所在目录**（与 article.md 文件同目录）
- 禁止保存到子目录，所有配图与源文件保持同一层级
- PNG 文件自动转换，强制生成到 SVG 源文件所在目录

### 目录结构示例

```text
articles/
├── 文章标题.md          # 源文章
├── AI治理-01.svg        # 配图 1
├── AI治理-01.png        # 自动转换的 PNG
├── AI治理-02.svg        # 配图 2
├── AI治理-02.png        # 自动转换的 PNG
├── AI治理-03.svg        # 配图 3
└── AI治理-03.png        # 自动转换的 PNG
```

---

## 二、文件命名规范

### 严格限制

所有文件名必须控制在 **15 个字符以内**（含扩展名），确保 Obsidian 正常引用。

### 命名格式

- **格式**：`短名-序号.svg`（总长度 ≤ 15 字符）
- **短名要求**：文章核心名称，≤ 8 个中文字符
- **序号格式**：2 位数字，从 01 开始
- **扩展名**：.svg（4 字符）

### 命名示例

| 文件名 | 状态 | 说明 |
|--------|------|------|
| `AI治理-01.svg` | ✅ | 8 字符 |
| `法律科技-02.svg` | ✅ | 8 字符 |
| `数据合规-03.svg` | ✅ | 8 字符 |
| `智能合约-04.svg` | ✅ | 8 字符 |
| `人工智能治理-01-核心概念.svg` | ❌ | 超长，禁用 |

### 命名策略

1. 提取核心关键词：从文章标题中提取 2-4 个字的核心概念
2. 确保唯一性：同一目录下避免重复短名
3. 保持语义：短名应能让人联想到文章内容
4. 使用中文：优先使用中文短名，便于理解

---

## 三、PNG 转换

### 使用 skill 脚本

使用 `scripts/svg2png.js` 进行转换：

```bash
node scripts/svg2png.js input.svg output.png 600
```

### 转换参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| input.svg | 输入 SVG 文件路径 | 必填 |
| output.png | 输出 PNG 文件名（可选） | 与 SVG 同名 |
| 600 | DPI 值（72-2400） | 600 |

### 转换特性

- 高保真渲染：支持 emoji、中文、CSS
- 自动尺寸：根据 viewBox 自动计算
- 统一位置：PNG 总是生成到 SVG 源文件所在目录

---

## 四、Markdown 图片插入

### 插入格式

```markdown
<!-- 配图：[简短描述] -->
![](AI治理-01.png)
```

### 插入位置规则

- 段落级插入：每个重要段落开头插入对应配图
- 概念级插入：关键概念解释处插入专门配图
- 间隔原则：每 2-3 个段落插入一张配图
- 使用标准 Markdown 语法
- 图片路径使用相对引用

---

## 五、输出示例

### Markdown 文件结构

```markdown
# 文章标题

## 第一部分

段落内容...

<!-- 配图：核心概念可视化 -->
![](AI治理-01.png)

继续论述...

## 第二部分

另一段核心概念...

<!-- 配图：第二概念可视化 -->
![](AI治理-02.png)

...更多内容
```

---

## 六、成功标准

- 配图密度显著提升（8-15 张），有效增强文章视觉吸引力
- 文件命名符合规范（≤ 15 字符）
- SVG 和 PNG 文件位于源文章同一目录
- PNG 高保真渲染（600 DPI），emoji 和字体正常显示
- 跨平台兼容性良好，适合所有平台发布

---

## 七、与其他技能的协作

### 与 piclist-upload 技能配合

当用户需要将生成的本地 PNG 图片上传到云图床时，可以进一步使用 **piclist-upload** 技能：

**使用场景**：
- 需要跨设备访问文章（云端图片链接）
- 需要在多个平台发布同一篇文章
- 需要减轻本地存储负担

**使用提示**：

PNG 模式生成配图后，如果用户满意并需要上传到云图床，可以调用 piclist-upload skill：

```
/piclist-upload @article.md
```

或者直接告诉 AI："把这篇文章的图片上传到图床"。

piclist-upload skill 会：
1. 读取 Markdown 文件中的本地图片引用
2. 将 PNG 文件上传到配置的图床
3. 将本地路径替换为云端 URL
4. （可选）删除本地图片文件

**注意**：生成 PNG 图片后不会自动上传，给用户留出"抽卡"和调整的空间。只有用户明确需要上传时，才调用 piclist-upload skill。