wechat-article-camofox

name	wechat-article-camofox
description	使用本机部署的 camofox-browser 稳定抓取微信公众号文章链接内容，优先读取浏览器 accessibility snapshot，并对公众号页噪音做专用清洗，输出 Markdown 或 JSON。
version	1.1.1
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["wechat","mp.weixin.qq.com","camofox","browser","extraction","markdown","json"],"related_skills":["ocr-and-documents","hermes-agent"]}}

WeChat Article Extraction via Camofox

当你要稳定获取 微信公众号文章链接（mp.weixin.qq.com/s/...）的正文内容时，使用这个 skill，喵。

它依赖 camofox-browser 作为浏览器采集层，读取页面 accessibility snapshot，再做公众号页面专用清洗，得到更干净的正文输出。

当前版本已经升级成 方案 B：自动安装型：首次运行会先检查本机 camofox-browser 是否可用；如果还没装，会尝试自动 clone 仓库并执行 npm install，然后再拉起服务。也就是说，用户不必再手动预装 CamouFox，只需要本机已有 git 和 Node.js 18+ / npm，喵。

适用场景

• 抓取微信公众号文章正文
• 输出 Markdown 或 JSON
• 普通静态抓取噪音过多，或浏览器兜底更稳时
• 后续想把公众号抓取能力接到 Hermes 或自己的脚本链路里

这版 skill 提供什么

• scripts/run.py：统一入口（推荐公开仓库用户直接使用）
• scripts/fetch_wechat_article.py：主提取脚本
• scripts/publish_wechat_article_to_feishu.py：抓取并发布到飞书原生文档（含正文图片）
• templates/article_urls.example.txt：示例输入
• 若装进 Hermes 本机环境，可继续提供命令入口：wechat-article-fetch
• 若装进 Hermes 本机环境，可继续提供命令入口：wechat-article-to-feishu
• 若本机已存在 camofox-browser-start / status / stop 管理脚本，会优先复用这些入口；若没有，Python 脚本也能直接完成自动安装与拉起
• 首次运行或服务未就绪时，脚本会在 stderr 打印阶段性进度：检查健康状态、安装依赖、clone 仓库、执行 npm install、启动服务、等待健康检查通过
• 依赖的 camofox-browser 服务管理脚本（若本机已配置）：
  • camofox-browser-start
  • camofox-browser-status
  • camofox-browser-stop

这次实测后又补了两条关键经验：

• 写飞书原生文档并做回读校验 是这条 workflow 的基本要求，不是可选项
• 图片要按原文顺序插回正文，而不是统一堆到文末

前提条件

1. 本机已安装 git
2. 本机已安装 Node.js 18+ 与 npm
3. 目标链接为可公开访问的公众号文章页

可选预检查：

node --version
npm --version
git --version

camofox-browser 本身不再要求手动预装。首次运行 wechat-article-fetch / wechat-article-to-feishu 时，脚本会自动检查；若缺失，会自动 clone https://github.com/jo-inc/camofox-browser.git 并执行 npm install，然后再尝试拉起本地服务。

最常用用法

0）抓取并直接发布到飞书原生文档

python3 scripts/run.py publish-feishu "https://mp.weixin.qq.com/s/xxxxxxxxxxxxxxxx"

这个 workflow 会执行：

• 抓取公众号文章
• 清洗正文与标题
• 自动提取正文图片并按原文顺序写进飞书原生文档正文
• 回读飞书文档做校验

如果你的任务目标里包含“放到飞书文档里”，这是优先入口。

1）抓取为 Markdown

python3 scripts/run.py fetch "https://mp.weixin.qq.com/s/xxxxxxxxxxxxxxxx"

如果本机还没有 camofox-browser，它会先自动安装；如果服务未启动，它会自动拉起服务，再继续抓取。首次运行过程中会在 stderr 持续打印阶段性进度，例如：检查健康状态、clone 仓库、执行 npm install、启动服务、等待健康检查通过。

2）输出 JSON

python3 scripts/run.py fetch "https://mp.weixin.qq.com/s/xxxxxxxxxxxxxxxx" --format json

3）保存到文件

python3 scripts/run.py fetch "https://mp.weixin.qq.com/s/xxxxxxxxxxxxxxxx" --save /tmp/article.md

4）附带图片列表

python3 scripts/run.py fetch "https://mp.weixin.qq.com/s/xxxxxxxxxxxxxxxx" --format json --include-images

Python 脚本直接调用

python3 scripts/fetch_wechat_article.py \
  "https://mp.weixin.qq.com/s/xxxxxxxxxxxxxxxx" \
  --format markdown

输出说明

Markdown

默认输出：

• 标题
• 作者 / 发布时间（若能识别）
• 正文清洗结果

JSON

输出字段：

• url
• title
• author
• published_at
• content_markdown
• images（可选）
• source（固定为 camofox_snapshot）

提取策略

1. 先检查本机 camofox-browser 是否健康
2. 若未安装，则自动 clone camofox-browser 仓库并执行 npm install
3. 若服务未运行，则自动拉起本地服务
4. 新建隔离 tab 打开目标公众号链接
5. 读取 snapshot（必要时翻页 offset）
6. 解析标题 / 作者 / 时间 / 正文
7. 过滤公众号常见噪音：
   • 视频控件
   • 点赞 / 留言 / 关注 / 分享区
   • 扫码提示
   • 页脚互动区
   • 小程序 / 二维码 / 继续访问等提示
8. 关闭临时 tab

已知边界

• 这是“公众号正文提取器”，不是通用网页抽取器
• 个别文章若页面结构特殊，清洗规则可能需要补充
• 当前已支持把正文图片按页面 snapshot 顺序插回正文，并在发布飞书文档时渲染成原生图片块
• 当前也已修复一批常见的块级恢复问题：嵌套 listitem 的多余圆点、list item 内联 code 被拆行、blockquote 段落丢失、以及列表和后续正文之间的错误折行
• 解析 snapshot 时，遇到 - list: / - listitem: / - paragraph: / - blockquote: 这类容器节点，应该按子树聚合成同一个块；不要把子节点里的 - text:、- code:、- strong: 当成独立段落逐行吐出，否则很容易产生假圆点、额外折行和断裂的 inline code
• 序列化 Markdown 时，列表块结束后如果下一块不是列表，必须主动补空行；否则飞书/Markdown 渲染会把后续正文错误吞进上一个 list item
• 但“逐块原样恢复”仍是近似重建，不保证与手机端公众号富文本 100% 像素级一致；复杂卡片、特殊组件、极细碎图文混排仍可能需要继续补规则
• 自动安装模式仍依赖本机已有 git 与 Node.js 18+ / npm；如果这些底层依赖缺失，脚本会停止并给出明确提示
• 当前实测下，若飞书授权缺少 space:document:delete，则无法真正删除旧文档；稳妥替代方案是用 docs +update --mode overwrite 将旧文档覆盖为“已废弃，请看新版”提示

何时优先使用这个 skill

当用户提到：

• 微信公众号文章
• 公众号链接抓取
• mp.weixin.qq.com
• 提取公众号正文
• 微信文章转 Markdown / JSON

一句话总结

这套 skill 用 camofox-browser 解决“稳稳打开页面”的问题，再用公众号专用清洗解决“拿到干净正文”的问题。