openJiuwen agent-core 微信公众号文章解析器(WeChatArticleParser)完整指南:从 URL 抓取、正文提取到 RAG 索引接入
openJiuwen agent-core 微信公众号文章解析器(WeChatArticleParser)完整指南:从 URL 抓取、正文提取到 RAG 索引接入
微信公众号文章(mp.weixin.qq.com/s/...)是知识库(Knowledge Base, KB)构建中常见的高价值文本源。openJiuwen agent-core 在检索索引(retrieval/indexing)处理器链中内置了专用的 WeChatArticleParser,可自动抓取微信文章页面并用 BeautifulSoup 解析出正文,产出标准化的 Document 对象,供切分、向量化与检索使用。读完本文,你将掌握该解析器的完整 API、底层抓取与正文提取原理、与 AutoParser/AutoLinkParser 的自动路由集成方式,以及如何在实际项目中独立或自动化地使用它。
一、模块定位:检索索引处理器链中的微信文章解析器
在 openJiuwen agent-core 的检索索引流程中,文档解析(parser)负责把各种来源(本地文件、URL、微信文章)统一转换成 Document 对象,是索引管线的第一步。WeChatArticleParser 属于 openjiuwen.core.retrieval.indexing.processor.parser 包,专门处理微信公众号文章 URL。
整个 parser 家族在 parser/README.md 中有完整清单,微信文章解析在其中承担两个职责:
- 类实现:
WeChatArticleParser—— 面向对象的解析器,可通过parse()方法或配合自动路由解析器使用; - 便捷函数:
parse_wechat_article_url—— 无实例化的函数式入口,直接传入 URL 即可完成「抓取 + 解析」全过程。
从源码继承关系看,WeChatArticleParser(WebPageParser),而 WebPageParser(HTMLFileParser),HTMLFileParser(TxtMdParser),TxtMdParser 向上追溯至抽象基类 Parser(见 base.py)。因此微信解析器天然复用 HTML 解析、标题提取、文本清洗等底层能力,而仅针对微信文章页做差异化定制。
二、核心 API:类定义与参数说明
2.1 构造器
WeChatArticleParser(
timeout: float = 30.0,
user_agent: str = DEFAULT_USER_AGENT,
verify: bool | str | ssl.SSLContext = True,
**kwargs,
)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
timeout |
float | 30.0 |
HTTP 请求超时时间(秒)。构造时设置,后续调用 parse() 时可用关键字参数覆盖 |
user_agent |
str | 内置浏览器 UA | 请求携带的 User-Agent 请求头。默认值为 Chrome 120 的完整 UA 字符串 |
verify |
bool | str | ssl.SSLContext | True |
httpx 客户端的 SSL 校验配置,语义与 httpx.AsyncClient 完全一致:True 使用系统默认 CA;False 关闭校验(如企业代理做 TLS 解密时);也可传 CA bundle 文件路径或自定义 ssl.SSLContext |
**kwargs |
Any | — | 透传给基类的可变参数 |
默认 UA 定义在 html_file_parser.py:
DEFAULT_USER_AGENT = (
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
"(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
)
DEFAULT_TIMEOUT = 30.0
构造逻辑继承自 WebPageParser.__init__(见 web_page_parser.py),三个参数被保存为实例属性,供后续 parse() 调用默认使用。
2.2 异步解析方法 parse
async parse(doc: str, doc_id: str = "", **kwargs: Any) -> List[Document]
doc(str):微信文章 URL,形如https://mp.weixin.qq.com/s/...;doc_id(str,可选):文档 ID;为空时默认使用 URL 或自动生成的 UUID,默认"";**kwargs:可在调用时覆盖构造器设置,支持timeout、user_agent、verify以及client(一个可复用的httpx.AsyncClient实例);- 返回值:
List[Document],通常为单个Document,包含正文text与元数据(source_url、title、source_type="wechat_article")。
parse() 的实现继承自 WebPageParser(web_page_parser.py):先从 kwargs 中读取覆盖值(未提供则回落到构造器属性),再调用类方法 parse_url(),doc_id 为空时以 doc 作为 ID:
async def parse(self, doc: str, doc_id: str = "", **kwargs) -> List[Document]:
timeout = kwargs.get("timeout", self.timeout)
user_agent = kwargs.get("user_agent", self.user_agent)
verify = kwargs.get("verify", self.verify)
client = kwargs.get("client")
return await self.parse_url(
doc,
doc_id=doc_id or doc,
timeout=timeout,
user_agent=user_agent,
verify=verify,
client=client,
)
2.3 支持判定 supports
supports(doc: str) -> bool
判断输入是否为微信文章 URL。实现直接复用 web_page_parser.py 中的 URL 判定函数 _is_wechat_article_url,其正则在 web_page_parser.py:
WECHAT_MP_URL_PATTERN = re.compile(
r"^https?://(?:mp\.weixin\.qq\.com|.*?\.weixin\.qq\.com)/s\b.*",
re.IGNORECASE,
)
def _is_wechat_article_url(url: str) -> bool:
return bool(url and WECHAT_MP_URL_PATTERN.match(url.strip()))
即:以 http:// 或 https:// 开头、主机为 mp.weixin.qq.com(或任意 *.weixin.qq.com 子域)且路径以 /s 开头(/s 后必须是单词边界,如 /s/xxxx)的 URL 才会被识别为微信文章链接。单元测试也验证了这一点(test_wechat_article_parser.py):
assert parser.supports("https://mp.weixin.qq.com/s/abc123") is True
assert parser.supports("http://mp.weixin.qq.com/s/xyz") is True
assert parser.supports("https://example.com/page") is False
assert parser.supports("") is False
三、便捷函数:parse_wechat_article_url
async parse_wechat_article_url(
url: str,
doc_id: str = "",
*,
timeout: float = 30.0,
user_agent: str = DEFAULT_USER_AGENT,
verify: bool | str | ssl.SSLContext = True,
client: Optional[httpx.AsyncClient] = None,
) -> List[Document]
url(str):微信文章 URL,必填;doc_id(str,可选):文档 ID,为空时默认用 URL 或生成的 UUID,默认"";timeout(float,可选):仅当未传入client时生效的请求超时,默认30.0;user_agent(str,可选):请求 UA,默认内置 UA;verify(bool | str | ssl.SSLContext,可选):仅作用于内部自建的 httpx 客户端;当传入了client时该参数被忽略,默认True;client(Optional[httpx.AsyncClient],可选):可复用的异步 httpx 客户端;若未提供,内部会临时创建(携带verify/timeout/ UA 配置)并在请求完成后自动关闭,默认None;- 返回值:解析得到的
Document列表(通常为单个)。
该函数是类方法 parse_url 的别名,源码里一行定义(wechat_article_parser.py):
parse_wechat_article_url = WeChatArticleParser.parse_url
因此它拥有与 parse_url 完全相同的语义:URL 校验 → 下载 HTML → 解析正文 → 写元数据 → 返回文档列表。
四、抓取与解析的底层实现原理
4.1 三步流水线:校验 → 下载 → 提取
parse_url 的完整链路(web_page_parser.py)分为三步:
- URL 校验
_validate_url:微信解析器覆写了基类校验(wechat_article_parser.py),只接受微信文章 URL,否则抛出RETRIEVAL_INDEXING_FETCH_ERROR错误,错误信息为Not a WeChat article URL: ...。注意与泛用WebPageParser的差异:后者恰恰拒绝微信 URL,并提示改用WeChatArticleParser(web_page_parser.py),两套解析器通过 URL 模式互补分工。 - HTML 下载
_download_html:优先使用调用方传入的client;否则以async with httpx.AsyncClient(verify=..., timeout=httpx.Timeout(timeout), headers={"User-Agent": user_agent})自建客户端,请求完成后自动关闭(web_page_parser.py)。所有httpx.HTTPStatusError(如 404/403,会报告状态码)、httpx.RequestError及其他异常都会被包装为带RETRIEVAL_INDEXING_FETCH_ERROR状态码的build_error抛给调用方(web_page_parser.py)。 - 解析提取
_parse_html:这是WeChatArticleParser的定制核心,见下文。
4.2 微信正文提取的差异化实现
微信文章页正文固定放在 id="js_content" 的 div 中,这是与泛用网页解析器最关键的差异。WeChatArticleParser 覆写了 _parse_html(wechat_article_parser.py),流程如下:
- 用
_parse_html(html)构建BeautifulSoup对象:优先尝试lxml解析器,未安装时回退到标准库html.parser(html_file_parser.py); - 用
_extract_title(soup)提取标题:优先读取<meta property="og:title">的content,缺失时回退到<title>标签文本(html_file_parser.py); - 用
_extract_js_content(soup)定位正文节点:soup.find("div", id="js_content")(wechat_article_parser.py); - 若找不到
js_content节点,抛出RETRIEVAL_INDEXING_FETCH_ERROR(提示Could not find article content (js_content) in page); - 用
_get_text_from_soup(content_node)提取正文文本:先移除script/style标签,再以换行符分隔获取文本,压缩行内多余空格、规范化连续空行(html_file_parser.py); - 若文本为空,抛出错误
Article content is empty after parsing。
最终产出一个 Document:
Document(
id_=doc_id,
text=text,
metadata={
"title": title or "(无标题)",
"source_type": "wechat_article",
},
)
随后 parse_url 会再补写 source_url 元数据并打印日志(web_page_parser.py)。因此最终文档携带四类信息:title、source_type="wechat_article"、source_url(原始 URL)以及正文 text。单元测试对这套元数据行为做了完整断言(test_wechat_article_parser.py)。
4.3 错误处理约定
所有失败场景统一收敛为 RETRIEVAL_INDEXING_FETCH_ERROR 状态码,覆盖:非微信 URL、HTTP 状态错误(携带实际状态码)、网络请求失败、找不到 js_content、正文为空等。异常统一通过 openjiuwen.core.common.exception.errors.build_error 构造,调用方可用 except BaseError 统一捕获(测试即以此断言非微信 URL 抛出 BaseError,见 test_wechat_article_parser.py)。
五、实战接入:独立调用与自动路由
5.1 方式一:直接函数调用
适合在脚本或管线中一次性解析单个 URL:
import asyncio
from openjiuwen.core.retrieval.indexing.processor.parser import (
parse_wechat_article_url,
)
async def main():
url = "https://mp.weixin.qq.com/s/abcdef123456"
docs = await parse_wechat_article_url(url, doc_id="wechat_001")
for doc in docs:
print(doc.id_, doc.metadata.get("title"))
print(doc.metadata.get("source_type")) # "wechat_article"
print(doc.metadata.get("source_url")) # 原始 URL
print(doc.text)
asyncio.run(main())
5.2 方式二:解析器实例调用
适合需要复用实例配置(如关闭 SSL 校验、自定义 UA)的场景:
from openjiuwen.core.retrieval.indexing.processor.parser import WeChatArticleParser
parser = WeChatArticleParser(timeout=60.0, verify=False) # 企业代理场景可关闭校验
if parser.supports(url):
docs = await parser.parse(url, doc_id="doc_2")
parse() 的 kwargs 可单次覆盖构造配置,例如 await parser.parse(url, timeout=120.0, user_agent="MyAgent/1.0")。
5.3 方式三:AutoLinkParser / AutoParser 自动路由
若要混合解析「微信链接 + 普通网页链接 + 本地文件」,无需手动判断 URL 类型,交给自动路由解析器即可。AutoLinkParser 的默认路由表把微信文章 URL 排在最前(auto_link_parser.py):
return [
(WECHAT_MP_URL_PATTERN, WeChatArticleParser()),
(HTTP_URL_PATTERN, WebPageParser()),
]
即:命中 WECHAT_MP_URL_PATTERN 的 URL 自动交给 WeChatArticleParser,其余 http(s) URL 交给泛用 WebPageParser,首个匹配的路由胜出。AutoParser 则在其上再封装一层:URL 交给 AutoLinkParser,本地路径交给 AutoFileParser(按扩展名路由),实现「传入一个 path 或 URL,自动选择解析器」的统一入口(auto_parser.py)。所有解析器均从 openjiuwen.core.retrieval.indexing.processor.parser 包导出,见 parser/init.py。
from openjiuwen.core.retrieval.indexing.processor.parser import AutoParser
parser = AutoParser() # 一个入口混合解析
wechat_docs = await parser.parse("https://mp.weixin.qq.com/s/xxx") # → WeChatArticleParser
web_docs = await parser.parse("https://example.com/blog/post") # → WebPageParser
解析出的 Document 对象是后续索引管线的标准输入,可继续交给切分(TextChunk)、向量化与入库环节(Document/TextChunk 数据模型定义见 document.py)。
六、适用前提与注意事项
- URL 形态限制:
supports()与parse()只接受mp.weixin.qq.com或*.weixin.qq.com且路径以/s开头的链接。微信分享卡片短链、weixin.qq.com非/s页面不会被识别,会直接报Not a WeChat article URL。 - 网络与反爬现实约束:微信公众号页面可能要求 UA 或存在访问限制,默认 UA 模拟 Chrome 120 浏览器;若抓取失败可尝试调整
user_agent、加大timeout。若处于企业代理等 TLS 解密环境,可设置verify=False。 - 正文完整性:
js_content为文章正文容器,解析器不处理页内图片(text仅包含文本);图片、视频等富媒体内容不会进入Document.text。 - 连接复用:批量解析大量文章时,可复用同一个
httpx.AsyncClient并传给parse()/parse_wechat_article_url()的client参数,避免为每篇文章新建连接;不传时每次调用会自建并关闭客户端。 - 运行环境:依赖
httpx与beautifulsoup4;使用lxml可获得更快解析速度(缺失时自动回退到html.parser)。
七、参考文档与源码速查
- API 参考:本模块即 wechat_article_parser.md,中英双语版本见 中文 API 文档
- parser 家族总览:parser/README.md
- 核心实现:wechat_article_parser.py、web_page_parser.py、html_file_parser.py
- 自动路由:auto_link_parser.py、auto_parser.py
- 单元测试:test_wechat_article_parser.py