---
name: wechat-article-formatter
description: 将Markdown文章转换为美化的HTML格式，适配微信公众号发布。应用专业CSS样式、代码高亮、优化排版。当用户说"美化这篇文章"、"转换为HTML"、"优化公众号格式"、"生成公众号HTML"时使用。
allowed-tools: Read, Write, Bash
---

# 微信公众号文章格式化工具（Claude 执行指南）

**目标**: 将 Markdown 文章转换为适配微信公众号的精美 HTML，实现一键发布。

**核心价值**: 效率提升 15 倍（30分钟 → 2分钟），格式一致专业。

**全新升级**: 使用 AI 科技主题，专为 AI 领域内容设计，支持丰富的视觉组件和自定义语法。

---

## 主题说明

本工具使用 **AI 科技主题**（ai-tech-theme），专为 AI 领域内容设计：

- 渐进式紫蓝绿配色（保留原紫色，扩展至青、绿等辅助色）
- 丰富的视觉组件（信息卡片、徽章、表格、代码块等）
- AI 领域专用组件（模型对比、Prompt 示例、API 调用、性能指标）
- Atom One Dark 代码高亮
- 响应式设计，移动端友好

---

## 新增组件使用

### 信息卡片

使用 `:::` 语法创建不同类型的信息框：

```markdown
::: info
这是一条信息提示
:::

::: success
操作成功！模型训练完成。
:::

::: warning
注意：此操作会消耗大量 tokens
:::

::: danger
错误：API key 无效
:::

::: tech
技术提示：使用 --temperature 参数控制输出随机性
:::
```

### 徽章标签

使用 `[!TEXT]` 语法添加徽章：

```markdown
GPT-4 [!NEW] 支持多模态输入 [!AI]

Claude Opus [!推荐] 具有最强推理能力
```

支持的徽章类型：
- `[!NEW]` - 渐变紫蓝徽章（新功能）
- `[!AI]` - 青色徽章（AI 相关）
- `[!推荐]` - 紫色徽章（推荐内容）
- `[!成功]` - 绿色徽章（成功状态）
- `[!警告]` - 黄色徽章（警告提示）

---

## ⚡ 执行流程（严格遵守）

### 步骤1：获取输入文件

**场景判断**：

| 场景 | 如何处理 |
|------|---------|
| 用户提供文件路径 | 直接使用该路径 |
| 用户粘贴 Markdown 内容 | 先使用 Write 工具保存为 .md 文件 |
| 刚使用过 wechat-tech-writer | 自动查找最新生成的 .md 文件（见集成指导） |
| 用户只说"美化文章" | 询问用户：文件路径或粘贴内容 |

**自动检测最新文章**（与 wechat-tech-writer 集成）：
```bash
# 查找当前目录最新的 .md 文件
latest_md=$(ls -t *.md 2>/dev/null | head -1)
if [ -n "$latest_md" ]; then
    echo "检测到最新文章：$latest_md"
fi
```

---

### 步骤2：执行转换

**标准转换命令**：
```bash
cd /root/.claude/skills/wechat-article-formatter

python3 scripts/markdown_to_html.py \
  --input "{文件路径}" \
  --output "{输出路径}" \
  --preview
```

**参数说明**：
- `--input`：Markdown 文件路径（必需）
- `--output`：HTML 输出路径（可选，默认同名 .html）
- `--theme`：主题选择（现在只有 ai-tech，可省略）
- `--preview`：转换后自动在浏览器打开预览（推荐）

**示例**：
```bash
# 最常用：转换并预览
python3 scripts/markdown_to_html.py \
  --input "Claude_Sonnet_4介绍.md" \
  --preview
```

**重要提醒**：
- 微信公众号有独立的标题输入框，HTML 中已自动移除 H1 标题
- 转换后的 HTML 包含注释：`<!-- ⚠️ 标题请在微信公众号编辑器中单独填写 -->`

---

### 步骤3：质量检查

**转换完成后，必须检查**：

使用 Read 工具读取生成的 HTML 文件（前 50 行），检查：

| 检查项 | 如何验证 | 常见问题 |
|-------|---------|---------|
| 标题样式 | 查看 `<h2>`, `<h3>` 标签的 style 属性 | 样式丢失 → 重新转换 |
| 代码高亮 | 查看 `<pre><code>` 是否有语法高亮样式 | 无高亮 → 检查 Markdown 是否指定语言 |
| 信息卡片 | 查看是否包含 `class="alert alert-info"` 等 | 未转换 → 检查 ::: 语法格式 |
| 徽章 | 查看是否包含 `class="badge badge-new"` 等 | 未转换 → 检查 [!] 语法格式 |
| 图片路径 | 查看 `<img src="">` 的路径 | 本地路径 → 提醒用户需上传到微信 |
| 表格格式 | 查看 `<table>` 是否有内联样式 | 格式混乱 → 简化表格列数 |

**快速检查命令**：
```bash
# 查看 HTML 文件前 50 行
head -50 output.html

# 检查是否包含信息卡片
grep -o 'class="alert alert-[^"]*"' output.html

# 检查是否包含徽章
grep -o 'class="badge [^"]*"' output.html
```

---

### 步骤4：预览和反馈

**询问用户**：
```
✅ 转换成功！已生成：{输出文件路径}

预览效果：
- 已在浏览器打开预览
- 或访问：file://{绝对路径}

请检查效果，满意吗？
- 满意 → 进入步骤5（发布指导）
- 需要调整 → 可以修改 Markdown 后重新转换
```

**如果用户不满意**：

| 问题 | 解决方案 |
|------|---------|
| "信息框没显示" | 检查是否使用了正确的 ::: 语法 |
| "徽章没显示" | 检查是否使用了正确的 [!] 语法 |
| "代码块没高亮" | 检查 Markdown 代码块是否指定语言（\`\`\`python） |
| "图片显示不正常" | 提醒：本地图片需上传到微信编辑器 |
| "表格太宽" | 建议简化表格（≤4列）或接受横向滚动 |

---

### 步骤5：发布指导

**输出给用户的完整指导**：

```
📋 发布到微信公众号步骤：

1. 打开微信公众号编辑器
2. ✅ 在标题栏填写文章标题：{从 Markdown 提取的标题}
3. 打开生成的 HTML 文件：{文件路径}
4. 在浏览器中按 Ctrl+A（全选）→ Ctrl+C（复制）
5. 粘贴到编辑器正文区（Ctrl+V）
6. 处理图片：
   - 删除无法显示的本地图片引用
   - 重新上传图片到微信编辑器
7. 最后检查：标题层级、段落间距、代码块、信息卡片、徽章
8. 使用微信编辑器的"预览"功能在手机查看
9. 确认无误后发布

⚠️ 注意事项：
- 样式已内联，可直接粘贴
- 本地图片需重新上传
- 粘贴后微信编辑器可能微调部分样式（正常）
- 信息卡片和徽章的颜色背景会保留
```

---

## 🔄 与 wechat-tech-writer 集成

### 场景：刚用 wechat-tech-writer 生成文章

**识别标志**：
- 用户刚说过"写一篇关于XXX的文章"
- 当前目录有新生成的 .md 文件

**自动化流程**：
```bash
# 1. 查找最新文章
latest_article=$(ls -t *.md 2>/dev/null | head -1)

# 2. 确认是否是目标文章
echo "检测到最新文章：$latest_article"
echo "是否要转换这篇文章？(y/n)"

# 3. 自动转换（AI 科技主题）
python3 scripts/markdown_to_html.py \
  --input "$latest_article" \
  --preview
```

**无缝衔接话术**：
```
检测到你刚用 wechat-tech-writer 生成了文章：{文件名}
现在为你美化格式，使用 AI 科技主题...
```

---

## ❌ 错误处理表

| 错误信息 | 原因 | Claude 应该做什么 |
|---------|------|-----------------|
| `FileNotFoundError: Input file not found` | 文件路径错误 | 询问用户正确的文件路径 |
| `Unknown theme: xxx` | 主题名错误 | 提示现在只有 ai-tech 主题 |
| `Theme CSS file not found` | 主题文件缺失 | 检查文件是否存在，重新安装 |
| 转换成功但代码无高亮 | Markdown 未指定语言 | 提醒用户修改代码块（\`\`\`python） |
| 信息框未转换 | ::: 语法格式错误 | 检查是否有正确的开始和结束标记 |
| 徽章未转换 | [!] 语法格式错误 | 检查是否使用了支持的徽章类型 |
| 图片无法显示 | 本地路径或外链失效 | 提醒用户在微信编辑器重新上传 |
| 表格格式混乱 | 表格过宽 | 建议简化表格或转为图片 |

---

## 📚 快速参考

### 最常用命令

**标准转换**（最常用）：
```bash
python3 scripts/markdown_to_html.py --input article.md --preview
```

**指定输出路径**：
```bash
python3 scripts/markdown_to_html.py --input article.md --output output.html --preview
```

### 常见问题快速解答

**Q: 粘贴到微信后样式丢失？**
A: 使用"粘贴"而非"粘贴并匹配样式"，或清空编辑器后重新粘贴。

**Q: 代码块没有高亮？**
A: 确保 Markdown 中指定了语言：\`\`\`python（不是 \`\`\`）

**Q: 信息卡片没有显示？**
A: 检查 ::: 语法格式，确保有开始和结束标记，且类型正确（info/success/warning/danger/tech）

**Q: 徽章没有显示？**
A: 检查 [!] 语法格式，确保使用了支持的徽章类型（NEW/AI/推荐/成功/警告）

**Q: 如何自定义颜色？**
A: 修改 `templates/ai-tech-theme.css` 中的 CSS 变量（:root 部分）

---

## ✅ 执行检查清单（每次执行完毕后确认）

- [ ] 已获取输入文件（路径或内容）
- [ ] 已执行转换命令
- [ ] 已检查生成的 HTML 文件（标题、代码、信息卡片、徽章、图片）
- [ ] 已询问用户预览效果是否满意
- [ ] 已提供完整的发布指导
- [ ] 已处理可能出现的错误

---

**记住**：这个 skill 的核心是**自动化 + 专业化**，让用户 2 分钟完成原本 30 分钟的工作！