openJiuwen agent-core 微信公众号文章解析器(WeChatArticleParser)完整指南:从 URL 抓取、正文提取到 RAG 索引接入

原创2026-10-08 23:17:551,717 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 编排多智能体工作流自动化RAGEmbeddingRerank向量数据库MCP 服务提示工程可观测性后端

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)分为三步:

  1. 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 模式互补分工。
  2. 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)。
  3. 解析提取 _parse_html:这是 WeChatArticleParser 的定制核心,见下文。

4.2 微信正文提取的差异化实现

微信文章页正文固定放在 id="js_content" 的 div 中,这是与泛用网页解析器最关键的差异。WeChatArticleParser 覆写了 _parse_html(wechat_article_parser.py),流程如下:

  1. 用 _parse_html(html) 构建 BeautifulSoup 对象:优先尝试 lxml 解析器,未安装时回退到标准库 html.parser(html_file_parser.py);
  2. 用 _extract_title(soup) 提取标题:优先读取 <meta property="og:title"> 的 content,缺失时回退到 <title> 标签文本(html_file_parser.py);
  3. 用 _extract_js_content(soup) 定位正文节点:soup.find("div", id="js_content")(wechat_article_parser.py);
  4. 若找不到 js_content 节点,抛出 RETRIEVAL_INDEXING_FETCH_ERROR(提示 Could not find article content (js_content) in page);
  5. 用 _get_text_from_soup(content_node) 提取正文文本:先移除 script/style 标签,再以换行符分隔获取文本,压缩行内多余空格、规范化连续空行(html_file_parser.py);
  6. 若文本为空,抛出错误 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)。

七、参考文档与源码速查

登录后查看全文
agent-core