wechat-article-to-markdown 是由开发者 jackwener 开源的一款高效、专业的网页信息抓取与格式转换工具。该项目专注于解决在处理微信公众号文章、进行知识库归档或二次排版时的痛点，用户仅需通过一行简单的命令行指令，即可将排版复杂的微信网页无损提取，并彻底转换为干净、标准的 Markdown 纯文本格式文件。
在核心技术设计上，该工具内置了基于 Camoufox 的反检测网页抓取引擎，能够非常稳定地穿透微信页面的反爬虫拦截机制。不仅如此，它在处理文本内容时进行了深度的场景优化：能够精准捕捉文章的主标题、发布账号名称、发布时间及原始来源链接等元数据；针对技术类文章，专门解析微信独有的 code-snippet 代码块，从而保留准确的编程语言高亮标识。
最核心的优势在于，它完美解决了微信严格的图片防盗链问题，在抓取文章正文的同时，会自动将文中引用的外部网络图片全量并发下载到本地文件夹，并智能替换 Markdown 文档内的图片关联路径，让用户真正实现百分之百的纯离线阅读。此外，该项目还原生配备了 SKILL.md，可作为 Claude Code 等 AI 智能体的本地技能插件，为大型语言模型提供优质的长文本输入语料。
Function List
- Camoufox 反检测抓取引擎：内置高级浏览器伪装技术，智能绕过微信公众号的网页反爬机制，保障抓取过程的稳定连贯。
- 智能化元数据提取功能：在正文前自动提取并附加页面的核心元数据（如文章主标题、公众号名称、发布时间、对应原始URL），方便后续信息追溯。
- 富文本无损转化为纯文本：将含有复杂 HTML 结构与富媒体样式的微信网页彻底清洗，转换为轻量级、标准化且极易二次开发的 Markdown 格式。
- 防盗链图片本地化下载与替换：抓取时会自动将文章中的所有网络图片并发下载到专属的
images/子文件夹中，并自动修改 Markdown 里的图片相对路径，彻底避免防盗链导致的图片失效问题。 - 代码块语法高亮标识适配：针对程序员和技术作者群体，深度解析微信特殊的
code-snippet代码块，生成带有准确编程语言标识（Language fences）的代码区域。 - AI Agent 原生环境技能集成：项目代码库默认配备自动化执行协议
SKILL.md，支持通过 CLI 工具一键集成到 Claude Code 等本地大模型智能体中，让 AI 具备直接读取和总结微信文章的能力。
Using Help
Welcome wechat-article-to-markdown。这是一款功能强大且专注于微信公众号内容解析与提取的自动化工具。为了让无论是有编程基础的极客开发者，还是对命令行不太熟悉的普通办公用户，都能顺畅地部署和使用本程序，以下为您提供一份全面、详尽的实战操作指南。从基础的环境准备到各种安装方式，再到核心命令的运行和 AI 智能体集成，我们进行了保姆级的步骤拆解。
一、 核心环境准备
在正式安装之前，因为该工具基于 Python 开发，并引用了 Camoufox 抓取引擎，您需要确认本地计算机已安装以下环境：
- 安装 Python 解释器：强烈建议安装 Python 3.8 或以上较新版本。您可以访问 Python 官方网站，根据您的操作系统（Windows、macOS 或 Linux）下载稳定版本。
- 部署先进的包管理工具
uv：我们极其推荐使用最新一代的 Python 依赖管理工具uv，它能为您提供闪电般的安装速度与完全隔离的虚拟运行环境（macOS 平台用户可以通过终端输入brew install uv极速安装）。如果不使用uv，您也可以选择社区普及度很高的pipx工具来进行全局部署。
二、 程序安装流程全解析
为了适配不同人群的使用习惯，本项目官方提供了三种灵活的安装途径：
方案 A：使用 uv 工具全局安装（官方强烈推荐，速度极快）
uv tool 能够为您自动创建纯净沙盒环境，有效避免不同 Python 项目之间的依赖版本冲突问题。
- 请打开您电脑中的命令行终端（Windows 用户启动 PowerShell，macOS 用户启动 Terminal）。
- 在光标处输入并执行以下自动安装命令：
uv tool install wechat-article-to-markdown - 等待几秒钟，安装程序完成后，工具的核心命令就会注册到您电脑的全局环境变量中，您可以随时随地调用它。
方案 B：使用 pipx 工具全局安装
如果您本地已经习惯使用了 pipx 生态系统，该方式同样极为安全可靠：
- 在终端直接输入以下指令：
pipx install wechat-article-to-markdown
方案 C：通过克隆源码进行本地部署（适合想要二次开发的极客）
若您期望审查工具底层抓取逻辑或直接贡献代码：
- 确保电脑已安装 Git 环境。
- 拉取 GitHub 官方代码仓库：
git clone git@github.com:jackwener/wechat-article-to-markdown.git - 进入项目目录并使用
uv同步所需依赖文件：cd wechat-article-to-markdown uv sync
三、 功能实战：核心命令操作与输出文件解析
在安装工作一切就绪后，把微信文章“据为己有”就只剩下一条命令的距离。
1. 执行网页抓取指令
无论您处于系统的哪个本地目录，只需要调用主程序名并加上你要保存的微信文章的官方网页链接。为了防止终端对网址里特殊符号的错误识别，建议将目标 URL 用英文字符的双引号括起来。
基础执行命令：
wechat-article-to-markdown "https://mp.weixin.qq.com/s/文章的专属随机码"
(提示：如果您是通过方案C源码克隆的形式部署的，请在项目根目录使用命令 uv run wechat-article-to-markdown "您的URL" 甚至兼容性的 uv run main.py "您的URL" 来启动抓取。)
2. 解析强大的自动化输出文件结构
按下回车后，工具会在后台默默启动浏览器内核执行反检测策略，解析 HTML，并在当前终端所在的路径自动生成一个非常具有结构条理的 output 文件夹。其内部解剖结构如下：
output/
└── <自动提取识别的文章实际标题>/
├── <自动提取识别的文章实际标题>.md
└── images/
├── img_001.png
├── img_002.png
└── ...
- 智能化的分类归档：工具会自动提取公众号文章的原有标题作为主文件夹名称。这在您批量抓取多篇文章时，能够保持整个目录的整洁、不杂乱。
- 详尽的主 Markdown 文档：该
.md文件是提取并转换的精华所在，它完美保留了文本的阅读体验，顶部记录了文章的元数据（发文时间、作者信息等）。如果是技术博文，文章内原本难看的微信代码块也会被转换成标准且带有指定语言标识的高亮代码。 - 完美的本地化图片防盗链对策（images文件夹）：由于微信具有极度严苛的静态资源防盗链访问策略，直接复制内容到本地必然导致“图片无法显示”。该工具最强大的地方就是替您将网页所引用的全部插图提前下载，保存在独立的
images文件夹里，并在刚才的.md主文件中将所有的在线图片链接自动重写为了本地相对路径（例如）。这样一套文件夹打包，真正做到了百分百无死角离线断网查看。
四、 进阶发烧友专区：集成为 AI Agent 技能插件（Skill）
在这个 AI 崛起的时代，本工具原生设计为能让 AI “长出眼睛”的实用技能插件。它附带了一份标准化的 SKILL.md 配置声明文件，以方便诸如 Claude Code 这样的智能助手在执行任务时自动唤起它进行网页内容抓取。
一键集成法（基于 Skills CLI）
如果您的电脑安装了 Node.js，即可通过命令行自动化完成技能绑定：
npx skills add jackwener/wechat-article-to-markdown
(附加参数说明：可以加上 -g 参数进行全局安装共享，也可以加上 -a claude-code 参数精准指向您的 AI 代理，若在自动化脚本中运行可以添加 -y 实现静默非交互模式。)
手动配置文件集成法
不想使用第三方 CLI 工具的用户可按以下三步手动部署给 Claude Code：
- 手动为技能创建一个系统存放目录：
mkdir -p ~/.claude/skills/wechat-article-to-markdown - 从官方云端抓取最新的配置引导文件存放进去：
curl -o ~/.claude/skills/wechat-article-to-markdown/SKILL.md \ https://raw.githubusercontent.com/jackwener/wechat-article-to-markdown/main/SKILL.md - 设置完毕后，记得重启您的 Claude Code。再次向您的 AI 输入类似 “请帮我总结一下这篇微信长文的中心思想 https://…” ，您会惊奇地发现 AI 将自动使用此工具完美下载并深度阅读长文内容，极大地扩展了大型语言模型的上下文检索能力。(注：旧版的 OpenClaw / ClawHub 安装途径官方已声明废弃，请统一按照本指南操作。)
application scenario
- 个人离线知识库搭建与重要笔记永久归档
面对互联网上具有时效性或面临被创作者删除风险的优质微信公众号深度报道与技术干货，知识管理工作者可以利用本工具将其一键转化为离线 Markdown 文件，连同防盗链图片素材库一并沉淀导入至 Obsidian、Notion 或 Logseq 中，实现不受平台限制的永久个人数字资产归档。 - AI 大语言模型上下文语料自动抓取与投喂
由于大多数先进的大型语言模型（如 ChatGPT、Claude）原生不具备穿透微信反爬直接读取文章URL的能力。借助集成了该工具技能插件（Skill）的 AI Agent 工作流，模型能够直接将复杂的富文本化繁为简变成结构化的纯文本并进行消化，从而能够完美完成长篇微信文章的提取摘要、信息二次挖掘和结构化重写任务。 - 技术开发者自动获取文章进行跨平台内容分发
习惯于通过微信公众号进行初次发布的技术创作者，如需将自己的历史优质内容迁移并同步部署至个人的 GitHub Pages、基于 Hugo/Hexo 构建的独立博客时。该工具能够完美解析原本杂乱繁复的微信 HTML 源码，自动将插图本地化下载，最关键的是能无损保留代码块的语法高亮标识，免去了极其痛苦的手动复制和繁复的重新排版成本。
QA
- 这个工具可以穿透抓取需要扫码验证或强制登录的微信公众号文章吗？
常规的公开微信公众号长图文链接（即他人可以点击直接在微信外部浏览器中阅读的文章），此工具依赖底层的 Camoufox 反检测抓取引擎便能顺畅模拟合法环境进行静默抓取，完全不需要您个人进行任何二维码扫描或授权登录；但该工具无法获取非公开、已被删除或属于付费解锁内容的私密文章。 - 把抓取完毕生成的 Markdown 笔记文件发送给同事，他们打开还能看到图片吗？
完全可以，但前提是您必须将工具产出的整个包含images子文件夹的父级文件夹打包压缩后发送。因为为了对抗微信的“图片防盗链失效”机制，我们已将所有配图物理下载到了本地images中，文档采用的是本地相对路径读取。只要不破坏该树形目录结构，跨设备、跨电脑均能完美加载并展示原文内含的所有图像资源。 - 我该如何更新并保持我的工具处于最新的抓取兼容版本？
微信平台可能会不定期调整页面代码结构。如果工具出现不兼容现象，请尝试获取最新版本：如果您之前采用的是官方最推荐的uv命令安装，只需在终端敲入uv tool upgrade wechat-article-to-markdown即可完成智能覆盖；如果您是使用pipx部署的，那么请运行对应指令pipx upgrade wechat-article-to-markdown完成一键升级。 - 项目介绍里提到的“集成 AI Agent 技能插件（SKILL）”有什么实际的用途？
传统的爬虫工具只能依赖人类去键盘敲入命令行；而集成了“SKILL”后，这款工具就能化身为支持 MCP 协议或 AI 框架（如 Claude Code）手中的一件“武器”。当你在终端让 AI 去执行关于“微信文章阅读分析”的自然语言命令时，AI 便能自动调用系统里的wechat-article-to-markdown自行获取网页的源代码并自我分析。这是打造自动化智能阅读助手的底层基石。
