# WeChat Article Archive
## 微信公众号文章本地归档 Skill
[](#项目状态)
[](#核心思路)
[](#工具组合)
[](#工具组合)
[](#输出结构)
[](#许可证)
> 使用 WorkBuddy + Playwright MCP，将用户自己有权访问的微信公众号已发布文章，逐篇归档为可检索、可迁移的本地 HTML 文件，并保留图片、发布时间、原始 URL、清单和执行日志。
**项目类型：** WorkBuddy Skill / 浏览器自动化工作流 / 本地归档方案
**适用范围：** 个人备份、研究和知识归档
**核心原则：** 浏览器可见性优先、本地存储优先、可审计、可断点续传
> [!IMPORTANT]
> 本项目不是微信接口绕过工具，也不是面向公众的大规模抓取服务。它只归档用户自己有权访问、并且能够在其登录浏览器中正常打开的文章。
## 目录
- [项目状态](#项目状态)
- [实操验证](#实操验证)
- [背景与问题定义](#背景与问题定义)
- [核心思路](#核心思路)
- [工具组合](#工具组合)
- [快速开始](#快速开始)
- [标准工作流](#标准工作流)
- [输出结构](#输出结构)
- [清单与断点续传](#清单与断点续传)
- [安全与合规](#安全与合规)
- [局限性](#局限性)
- [参考资料](#参考资料)
- [许可证](#许可证)
- [English Summary](#english-summary)
## 项目状态
**Experimental / 可用但依赖页面环境。**
本流程已经在真实微信公众号后台完成过全量归档验证，但它依赖：
- WorkBuddy 当前版本的 MCP 能力；
- 已信任的 Playwright MCP；
- 用户本人完成的浏览器登录和二次验证；
- 微信公众号后台和文章页面当前仍可访问；
- 页面结构、资源加载策略和反自动化策略未发生破坏性变化。
项目不承诺兼容微信未来的页面改版，也不承诺远程视频或外链资源永久可用。
## 实操验证
这套流程已经通过真实 WorkBuddy + Playwright MCP 浏览器链路完成过一次完整归档验证。截图展示了任务结束时的汇总结果：
- 后台发表记录：181 条；
- 页面总数：19 页；
- 发现唯一文章链接：184 篇；
- 成功保存：184 篇；
- 失败：0 篇；
- 未处理：0 篇；
- 输出格式：HTML；
- 日期范围：2016-05-01 至 2026-08-09。
<p align="center"><sub>实操验证：WorkBuddy + Playwright MCP 完成微信公众号文章全量本地归档后的结果汇总。</sub></p>
> [!NOTE]
> 该截图用于证明流程曾经真实跑通，不代表微信页面结构、登录状态或上游策略在未来保持不变。公开分享时，建议同时保留自己的 `manifest.csv` 和 `download-log.md` 作为可审计的执行记录。
## 背景与问题定义
参考项目：[`wechat-article-exporter`](https://github.com/wechat-article/wechat-article-exporter)
该项目在 [Issue #200](https://github.com/wechat-article/wechat-article-exporter/issues/200) 中说明，其依赖的微信上游核心接口已被关闭，原有的“一键同步公众号历史文章”链路不再可用；仓库转为只读归档，已经同步到用户本地的数据仍然可以继续导出。
这里需要区分两种能力：
| 能力 | 说明 |
| --- | --- |
| 历史文章列表同步 | 依赖微信上游接口，可能随平台策略变化而失效 |
| 浏览器可见文章归档 | 让真实浏览器打开页面，再保存渲染后的内容和资源 |
Playwright MCP 不会修复或绕过已经关闭的接口。它提供的是一条更接近真实用户操作、依赖用户登录态、便于审计和断点续传的本地归档路线。
## 核心思路
将任务拆成“浏览器可见性”和“本地归档”两层：
```text
用户手动登录 / 验证
↓
Playwright MCP 控制浏览器
↓
读取公众号后台「发表记录」
↓
收集文章原始 URL
↓
逐篇打开、滚动、等待资源加载
↓
保存浏览器渲染后的 HTML
↓
下载图片并改写为本地相对路径
↓
更新 manifest.csv + download-log.md
↓
执行完整性校验
```
这种设计的价值在于：即使远程导出器或历史列表接口停止工作，只要用户仍能在自己的浏览器中打开文章，就可以尝试将可见内容沉淀为本地资产。
## 工具组合
### WorkBuddy
负责：
- 任务理解和流程编排；
- 调用已信任的浏览器能力；
- 读取和写入本地文件；
- 维护 CSV 清单和执行日志；
- 执行断点续传和最终校验。
### Playwright MCP
准确名称是 **Playwright MCP**，不是 Playground。官方 npm 包为 `@playwright/mcp`。
WorkBuddy 用户级 MCP 配置示例：
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
}
}
}
```
通常保存到：
```text
~/.workbuddy/mcp.json
```
保存后需要在 WorkBuddy 的 MCP/连接器管理界面点击 **Trust / 信任**。不同版本的入口可能不同，以当前客户端界面为准。
### 本地文件能力
负责：
- 创建年份目录；
- 保存 HTML 和图片；
- 改写相对路径；
- 更新 `manifest.csv`；
- 追加 `download-log.md`；
- 校验成功路径和资源文件。
### 可选：临时本地 HTTP 服务
当浏览器需要读取本地 `manifest.csv` 来选择下一批待处理文章时，可以在归档目录启动只读 HTTP 服务：
```bash
python3 -m http.server 8877 --directory ./raw
```
使用完成后必须：
1. 停止本地服务；
2. 删除临时的 `manifest-view.html`；
3. 确认没有把服务暴露到公网。
## 快速开始
### 1. 准备 Skill
将本仓库作为 WorkBuddy 用户级 Skill 安装，或将 `SKILL.md` 放入项目级 `.workbuddy/skills/` 目录。
推荐结构：
```text
wechat-playwright-archive/
├── README.md
└── SKILL.md
```
### 2. 配置并信任 Playwright MCP
将上面的配置加入 `~/.workbuddy/mcp.json`，保存后在 WorkBuddy 中信任 `playwright`。
### 3. 准备归档目录
```text
sources/wechat/raw/
├── manifest.csv
├── download-log.md
└── <year>/
```
不要把以下内容提交到 GitHub：
- 登录 Cookie；
- 密码和验证码；
- 二维码截图；
- MCP 会话状态；
- 个人浏览器配置；
- 未获授权的文章内容和图片资源。
### 4. 启动任务
可以向 WorkBuddy 发送类似指令：
> 使用已信任的 Playwright MCP，进入我有权访问的微信公众号后台，盘点全部已发表文章。先验证最早 3 篇，确认 HTML、图片、发布时间和原始 URL 均能保存后，再继续批量归档。按原始 URL 去重，失败单篇最多重试 2 次，并维护 `manifest.csv` 和 `download-log.md`。不要修改公众号后台内容。
### 5. 人工完成登录验证
遇到以下步骤时必须由用户本人完成：
- 扫码登录；
- 密码二次验证；
- 短信验证；
- CAPTCHA；
- 双因素认证。
完成后再让 WorkBuddy 继续。
## 标准工作流
### Step 1：检查已有清单
先读取：
```text
raw/manifest.csv
raw/download-log.md
raw/<year>/...
```
以 **原始 URL** 作为唯一去重键。标题只能用于展示和文件名，不能作为唯一身份。
### Step 2：盘点发表记录
进入公众号后台：
```text
内容管理 → 发表记录
```
记录：
- 页面默认排序；
- 后台显示的总记录数；
- 总页数；
- 每页文章数量；
- 多图文记录拆出的文章链接数。
如果页面默认是“最新到最早”，先完整收集全部链接，再按需要反转处理顺序。
### Step 3：验证最早 3 篇
每篇样本执行：
1. 打开原始文章 URL；
2. 等待 `#js_content` 出现；
3. 滚动到页面底部；
4. 等待图片完成加载或优雅超时；
5. 在 `<body>` 开头插入备份元数据；
6. 获取完整浏览器渲染 HTML；
7. 通过 Playwright 下载事件保存到 MCP 允许目录；
8. 复制到 `raw/<year>/`；
9. 下载正文图片到同名 `_files` 目录；
10. 将 `data-src` 和 `src` 改写为相对路径；
11. 检查正文、标题、日期、原始 URL 和图片文件。
> [!TIP]
> 三篇样本没有全部通过时，停止批量执行并报告原因。不要让一个未经验证的流程直接跑完整历史记录。
### Step 4：批量归档
对每篇文章：
- 判断原始 URL 是否已成功；
- 已成功则跳过；
- 否则打开文章页并保存 HTML；
- 根据文章页的 `#publish_time` 确认日期；
- 下载并本地化图片；
- 成功后立即更新 manifest；
- 失败时最多再试 2 次；
- 最终失败写入 manifest 和日志后继续。
### Step 5：最终校验
至少检查：
- `manifest.csv` 是否一篇 URL 一行；
- 成功路径是否全部存在；
- HTML/PDF 数量；
- `_files` 目录数量；
- HTML 引用的本地图片是否存在；
- 发布时间是否为 `YYYY-MM-DD`；
- 最早和最新文章日期；
- 临时 `manifest-view.html` 是否删除；
- 临时 HTTP 服务是否停止；
- Playwright 浏览器会话是否关闭。
## 输出结构
```text
raw/
├── manifest.csv
├── download-log.md
├── 2016/
│ ├── 2016-05-01__0001__文章标题.html
│ └── 2016-05-01__0001__文章标题_files/
│ ├── image-0001.jpg
│ └── image-0002.png
├── 2025/
│ └── ...
└── 2026/
└── ...
```
文件名格式：
```text
YYYY-MM-DD__NNNN__标题.html
```
建议将以下字符替换为 `_`：
```text
/ \ : * ? " < > |
```
同时清理控制字符、连续空格和末尾的点/空格，并限制标题长度。不要修改文章正文内容。
## 清单与断点续传
### `manifest.csv`
最低字段：
```csv
序号,标题,发布时间,原始 URL,保存路径,保存格式,状态,失败原因
```
示例：
```csv
1,文章标题,2026-01-01,https://mp.weixin.qq.com/s/example,2026/2026-01-01__0001__文章标题.html,HTML,成功,
```
推荐每成功保存一篇就写入一行，避免长任务中断后丢失进度。
### 重试规则
每篇文章采用：
```text
首次尝试 + 最多 2 次重试
```
恢复任务时：
- `状态=成功` 且原始 URL 已存在：跳过；
- `状态=失败`：重新尝试；
- `状态=待处理`：继续处理；
- 不要仅按标题或发布时间判断重复。
## 图片本地化
正文图片通常可能出现在以下属性中：
- `data-src`；
- `src`；
- `srcset`。
提取可访问的图片 URL，保存到同名 `_files` 目录，再把 HTML 引用改为相对路径。
图片下载失败时：
- 不阻塞整个批次；
- 记录失败 URL；
- 保留原始远程 URL 或相应的失败说明；
- 在最终日志中说明资源不完整。
## 安全与合规
### 必须遵守
- 只处理用户自己有权访问的公众号；
- 不代填密码、验证码、短信码或 2FA；
- 不上传 Cookie、登录态或文章内容到第三方；
- 不修改、删除、发布、定时发布或移动公众号后台内容；
- 将临时浏览器状态、认证文件和个人归档数据加入 `.gitignore`；
- 文章内容仅用于有权进行的个人备份、研究和归档。
### 不要误解
该流程：
- 不绕过微信验证；
- 不恢复已关闭的历史文章接口；
- 不保证未来微信页面结构和反自动化策略不变；
- 不保证远程视频、音频或外链资源永久可用。
## 局限性
- 公众号后台页面、登录态和文章页可能随微信升级变化；
- 纯图片、视频、脚本型文章的可见正文文字可能很少；
- 视频通常只能保存页面中的引用信息，除非用户另行授权并实现下载；
- 外链资源可能过期或需要额外权限；
- 文章列表盘点和文章正文保存是两条不同链路，任一链路受限都可能导致部分任务无法完成；
- 本流程适合本地归档，不应作为面向公众的大规模抓取服务。
## 参考资料
- [Playwright MCP](https://github.com/microsoft/playwright-mcp)
- [WorkBuddy MCP 文档](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide)
- [wechat-article-exporter](https://github.com/wechat-article/wechat-article-exporter)
- [停止维护说明 Issue #200](https://github.com/wechat-article/wechat-article-exporter/issues/200)
## 许可证
本 README 和配套 Skill 的许可证应由仓库维护者明确选择。若仓库尚未添加 `LICENSE` 文件，GitHub 默认不会授予他人复制、修改或再发布的明确许可。
文章内容、图片和第三方资源的版权归相应权利人所有；本项目只描述归档流程，不授予任何内容使用权。
## English Summary
This repository documents a local-first workflow for archiving a user's own WeChat Official Account articles.
It uses WorkBuddy as the orchestration layer and Playwright MCP as the authenticated browser-control layer. The workflow inventories the account's published history, opens each accessible article in a real browser, saves rendered HTML, downloads referenced images into a sibling `_files` directory, rewrites image references to relative paths, and maintains `manifest.csv` plus `download-log.md` for resumable execution and verification.
This is not an API bypass and does not restore any discontinued WeChat history-list endpoint. It archives content that the user can legitimately access in their own browser session.