# Wechat Article To Markdown

> 将微信公众号文章转换为整洁的 Markdown 文件，自动去除广告、赞赏、推广等无关内容，处理代码块格式，支持图片和视频处理。当用户提供微信公众号链接或要求保存微信文章时使用此技能。

- Skill: `hk-hub/wechat-article-to-markdown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hk-hub/wechat-article-to-markdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hk-hub/wechat-article-to-markdown/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: HK-hub (https://skillmd.com/u/hk-hub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hk-hub/wechat-article-to-markdown

---


# 微信公众号文章转 Markdown

## 概述

微信公众号文章网页包含大量无关内容（广告、赞赏、留言区、小程序推广等），直接复制粘贴会产生格式问题。此 Skill 提供一套完整的处理流程，将微信文章转换为干净、规范的 Markdown 文件。

## 触发条件

- 用户提供微信公众号文章链接（`mp.weixin.qq.com`）
- 用户说"保存微信文章"、"另存为 Markdown"
- 用户想要整理微信文章到笔记库

## 完整处理流程

### 第一步：同时获取 HTML 和 Markdown

**必须同时获取两种格式**（并行请求）：

```
# 请求 1：HTML 格式（用于提取图片位置）
mcp__ScraplingServer__stealthy_fetch
  - url: 微信文章链接
  - extraction_type: html
  - main_content_only: true
  - wait: 2000

# 请求 2：Markdown 格式（用于提取文本内容）
mcp__ScraplingServer__stealthy_fetch
  - url: 微信文章链接
  - extraction_type: markdown
  - main_content_only: true
  - wait: 2000
```

### 第二步：提取图片并确定位置

**关键：图片顺序必须按 HTML 中实际出现顺序，而非 imgIndex 数字**

从 HTML 中提取图片信息：

```bash
# 提取所有正文图片（按出现顺序）
cat html_file | tr '>' '\n' | grep -E 'data-src.*mmbiz_(jpg|png)' | grep -v 'mmbiz_svg'
```

**图片类型判断：**

| 类型 | 处理方式 | 说明 |
|------|---------|------|
| `mmbiz_jpg` | **保留** | 文章正文图片 |
| `mmbiz_png` | **保留** | 文章正文图片 |
| `sz_mmbiz_jpg` | **保留** | 文章正文图片 |
| `sz_mmbiz_png` | **保留** | 文章正文图片 |
| `mmbiz_svg` | **丢弃** | 装饰性图标、分隔线 |
| `data:image/svg+xml` | **丢弃** | SVG 占位符 |

**图片位置判断：**

根据 `data-index` 属性或图片在 HTML 中的出现顺序，将图片插入到 Markdown 对应位置：

```
data-index="2" → 第一张正文图片
data-index="3" → 第二张正文图片
...
```

**注意**：`#imgIndex=N` 不等于图片在文章中的实际位置！必须按 HTML 源码中的出现顺序排列。

### 第三步：清理无关内容

**必须移除的内容：**

1. **广告和推广**
   - 文末的广告推广内容
   - "阅读原文" 相关内容
   - 小程序推广
   - 公众号推荐卡片

2. **赞赏相关**
   - "微信扫一扫赞赏作者"
   - 赞赏二维码
   - 赞赏金额选择界面

3. **互动元素**
   - 留言区（"写留言"、"暂无留言"）
   - 分享按钮（Like, Share, Popular, Comment）
   - 关注引导（"扫码关注"、"继续滑动"）
   - 划线功能引导

4. **UI 元素**
   - 无效链接（`javascript:void(0);`）
   - 空图片标签（`![]()`）
   - SVG 占位图片
   - 弹窗和遮罩层内容
   - "预览时标签不可点"
   - 字体调整控件

5. **元数据冗余**
   - 重复的公众号名称和头像
   - 底部 "当前内容可能存在未经审核..." 提示
   - 微信公众平台广告规范指引

### 第四步：规范化 Markdown 格式

**标题处理：**
```markdown
# 文章主标题

## 二级标题

### 三级标题
```

**代码块处理：**
- 检查代码块是否正确使用三反引号
- 添加语言标识符（如 ```java, ```python, ```bash）
- 确保代码缩进正确

**图片格式：**
```markdown
![图片描述](https://mmbiz.qpic.cn/...)
```

**表格处理：**
保留原始表格格式，确保对齐。

### 第五步：添加元信息

在文件开头添加 YAML frontmatter：

```markdown
---
title: 文章标题
author: 作者名称
source: 原始链接
date_saved: 保存日期
tags: [微信公众号, 其他标签]
---
```

### 第六步：保存文件

**文件命名规则：**
- 格式：`YYYY-MM-DD-标题摘要.md`
- 标题摘要：取标题前 30 字符，去除特殊字符
- 示例：`2026-03-18-IM系统消息收发设计.md`

---

## 图片处理详细指南

### 微信图片的特殊性

**重要警告**：微信图片有以下限制：
1. **防盗链**：部分图片直接访问可能返回 403
2. **时效性**：图片链接可能过期（通常 24-48 小时）
3. **无防盗链**：大部分 `mmbiz.qpic.cn` 链接可直接访问

### 图片链接处理

**方案 A - 保留原始链接（推荐，简单）**
```markdown
![图片描述](https://mmbiz.qpic.cn/sz_mmbiz_png/xxx/640?wx_fmt=png)
```
- 优点：简单直接，大多数情况可正常显示
- 缺点：链接可能过期

**方案 B - 下载到本地**
- 如果用户需要离线使用，可下载图片到 `./images/` 目录
- 需要处理防盗链问题

### 常见图片问题

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 图片不显示 | SVG 占位符 | 过滤掉 `data:image/svg+xml` 和 `mmbiz_svg` |
| 图片顺序错乱 | 按 imgIndex 排序 | 按 HTML 中实际出现顺序（data-index） |
| 图片缺失 | 只用了 markdown 提取 | 同时获取 HTML 和 markdown |

---

## 常见问题处理

### 问题 1：图片顺序错乱

**原因**：`imgIndex` 数字不代表文章中的实际位置

**解决方案**：
```
错误做法：按 imgIndex=0,1,2... 排序
正确做法：按 HTML 中 <img> 标签出现的顺序排列
```

### 问题 2：图片缺失

**原因**：只用 markdown 格式提取，部分图片链接丢失

**解决方案**：同时获取 HTML 和 markdown，从 HTML 中提取完整图片列表

### 问题 3：包含无关的 SVG 图片

**原因**：微信使用 SVG 作为占位符和装饰

**解决方案**：过滤掉所有 `mmbiz_svg` 类型和 `data:image/svg+xml` 的图片

### 问题 4：代码块无语言标识

**原因**：微信文章代码块格式不规范

**解决方案**：根据代码内容推断语言，添加标识符

---

## 输出模板

```markdown
---
title: {{文章标题}}
author: {{作者}}
source: {{原始链接}}
date_saved: {{保存日期}}
tags: [微信公众号, {{其他标签}}]
---

# {{文章标题}}

> 作者：{{作者名称}}
> 来源：{{公众号名称}}
> 链接：{{原始链接}}

![封面图片]({{封面图片链接}})

{{正文内容，图片按正确位置插入}}

---

*本文由 [wechat-article-to-markdown] 自动转换*
*保存自微信公众号文章，仅供个人学习使用*
```

---

## 示例工作流

用户输入：
```
保存这篇文章 https://mp.weixin.qq.com/s/xxxxx
```

处理步骤：
1. **并行获取** HTML 和 markdown 两种格式
2. **从 HTML 提取图片**：按出现顺序，过滤 SVG
3. **解析 markdown**：提取标题、正文、代码块
4. **合并内容**：将图片插入到 markdown 正确位置
5. **清理无关内容**：移除广告、赞赏、UI 元素
6. **格式化代码块**：添加语言标识
7. **添加 frontmatter**：元信息
8. **保存文件**：按命名规则保存

---

## 注意事项

1. **版权提醒**：保存的文章仅供个人学习使用，请勿二次传播
2. **图片链接**：大部分可直接访问，少数有防盗链
3. **视频限制**：嵌入的视频记录标题和描述即可
4. **表格处理**：微信表格可能需要手动调整对齐
5. **公式支持**：如有数学公式，转换为 LaTeX 格式

## 相关技能

- `pdf` - 处理 PDF 文件
- `docx` - 处理 Word 文档
- `excalidraw-diagram` - 创建图表