wechat-article-parser 0.0.15__tar.gz → 0.0.17__tar.gz

wechat_article_parser-0.0.17/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: wechat-article-parser
+Version: 0.0.17
+Summary: WeChat MP article parser - extract metadata and content from WeChat public account articles
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: markdownify>=0.13
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wechat-article-parser
+
+微信公众号文章解析器。传入文章链接，提取公众号信息、文章元数据和 Markdown 正文，支持同步与异步调用。
+
+## 功能
+
+- 支持微信文章短链接和长链接。
+- 支持标准图文、转载式文章、纯文本、视频与音频分享、图片轮播及全屏布局短文本。
+- 提取标题、作者公众号、摘要、封面、发布时间、付费标记等信息，返回结构化数据。
+- 将正文转换为 Markdown，提取正文图片链接，支持 SVG 内嵌图片和文字。
+- 将投票、公众号推荐、小程序、红包封面等组件转换为可读文字或查看提示。
+- 支持请求超时、自定义 User-Agent、代理和按需返回原始 HTML。
+
+## 安装
+
+需要 **Python 3.10+**。
+
+```bash
+python -m pip install wechat-article-parser
+```
+
+`httpx`、`beautifulsoup4` 和 `markdownify` 会随包自动安装。
+
+## 快速开始
+
+将以下示例中的 URL 替换为实际文章链接。
+
+### 同步调用
+
+```python
+from wechat_article_parser import parse
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+
+if result.is_valid:
+    print(result.article_title)
+    print(result.mp_name)
+    print(result.article_markdown)
+    print(result.images)
+else:
+    print("部分关键字段未能解析，请检查返回结果")
+```
+
+### 异步调用
+
+```python
+import asyncio
+
+from wechat_article_parser import parse_async
+
+
+async def main():
+    result = await parse_async("https://mp.weixin.qq.com/s/xxxxx")
+    if result.is_valid:
+        print(result.article_title)
+        print(result.article_markdown)
+    else:
+        print("部分关键字段未能解析，请检查返回结果")
+
+
+asyncio.run(main())
+```
+
+### 请求选项
+
+两个接口均支持以下关键字参数：
+
+```python
+from wechat_article_parser import parse
+
+result = parse(
+    "https://mp.weixin.qq.com/s/xxxxx",
+    timeout=30,                    # 默认 15 秒
+    user_agent="MyBot/1.0",         # 默认使用内置 User-Agent
+    proxy="http://127.0.0.1:7890",  # 可选，显式指定代理
+    include_raw_html=True,          # 默认 False
+)
+print(result.raw_html)
+```
+
+## 返回结果
+
+两个接口均返回 `ArticleResult` 数据类，常用字段如下：
+
+| 字段 | 说明 |
+|---|---|
+| `article_title` / `article_description` | 文章标题 / 摘要 |
+| `article_markdown` | Markdown 正文 |
+| `article_publish_time` | 发布时间，Unix 时间戳 |
+| `article_cover_image` / `images` | 封面链接 / 最终保留的正文图片链接列表 |
+| `mp_name` / `mp_user_name` | 公众号名称 / 用户名 |
+| `article_display_type` | `article`、`video`、`audio`、`image`、`text` 或 `unknown` |
+| `article_url_type` | 输入链接类型：`short`、`long` 或 `unknown` |
+| `article_is_paid` | 是否检测到付费标记 |
+| `is_valid` | 关键字段是否完整的计算属性 |
+
+完整字段、枚举、长链接识别条件及 JSON 序列化示例见 [API 参考](docs/api.md)。
+
+## 使用边界与错误处理
+
+- 基于页面 HTML 和已知脚本数据提取，不执行 JavaScript，不还原交互与视觉布局。图片返回链接，不下载媒体文件。
+- 明确识别的 SVG 快速逐帧动画仅保留首帧；轮播及无法确认的帧序列保留可提取图片。具体规则见[正文转换规则](docs/content-rules.md)。
+- 视频、音频分享可以没有文字附言。付费预览及部分卡片可能只返回文字提示；`is_valid=True` 不代表已获取付费全文、媒体文件或小程序内部内容。
+- 页面结构变化或内容不可访问时，可能返回不完整结果。调用方应检查 `is_valid`；长链接的 `article_id` 为空属于正常情况。
+- **自 2026-11-02 起，微信短链接文章页不再提供文章签名 `sn`，返回的 `article_sn` 为空字符串，不影响 `is_valid` 判断。**
+- 检测到微信人机验证时抛出 `WeChatVerifyError`；HTTP 状态异常和网络错误通过 `httpx` 异常向外传播。接口不自动重试，处理示例见 [API 参考](docs/api.md#异常与不完整结果)。
+
+## 文档
+
+- [API 参考](docs/api.md)：参数、全部返回字段、枚举、有效性判断和异常处理。
+- [正文转换规则](docs/content-rules.md)：图片与动画、微信组件、页面模板与回退规则。
+- [开发指南](docs/development.md)：本地安装、项目结构、离线测试和真实链接调试。
+- [版本记录](https://github.com/huanjuedadehen/wechat-article-parser/releases)：各版本的发布说明。
+
+## 参与贡献
+
+欢迎通过 [Issues](https://github.com/huanjuedadehen/wechat-article-parser/issues) 报告问题，或提交 Pull Request。
+请附上可复现的文章链接、版本信息和预期结果；修改解析行为时补充离线回归用例。
+开发环境和测试方法见[开发指南](docs/development.md)。
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE)。

wechat_article_parser-0.0.17/README.md

@@ -0,0 +1,123 @@
+# wechat-article-parser
+
+微信公众号文章解析器。传入文章链接，提取公众号信息、文章元数据和 Markdown 正文，支持同步与异步调用。
+
+## 功能
+
+- 支持微信文章短链接和长链接。
+- 支持标准图文、转载式文章、纯文本、视频与音频分享、图片轮播及全屏布局短文本。
+- 提取标题、作者公众号、摘要、封面、发布时间、付费标记等信息，返回结构化数据。
+- 将正文转换为 Markdown，提取正文图片链接，支持 SVG 内嵌图片和文字。
+- 将投票、公众号推荐、小程序、红包封面等组件转换为可读文字或查看提示。
+- 支持请求超时、自定义 User-Agent、代理和按需返回原始 HTML。
+
+## 安装
+
+需要 **Python 3.10+**。
+
+```bash
+python -m pip install wechat-article-parser
+```
+
+`httpx`、`beautifulsoup4` 和 `markdownify` 会随包自动安装。
+
+## 快速开始
+
+将以下示例中的 URL 替换为实际文章链接。
+
+### 同步调用
+
+```python
+from wechat_article_parser import parse
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+
+if result.is_valid:
+    print(result.article_title)
+    print(result.mp_name)
+    print(result.article_markdown)
+    print(result.images)
+else:
+    print("部分关键字段未能解析，请检查返回结果")
+```
+
+### 异步调用
+
+```python
+import asyncio
+
+from wechat_article_parser import parse_async
+
+
+async def main():
+    result = await parse_async("https://mp.weixin.qq.com/s/xxxxx")
+    if result.is_valid:
+        print(result.article_title)
+        print(result.article_markdown)
+    else:
+        print("部分关键字段未能解析，请检查返回结果")
+
+
+asyncio.run(main())
+```
+
+### 请求选项
+
+两个接口均支持以下关键字参数：
+
+```python
+from wechat_article_parser import parse
+
+result = parse(
+    "https://mp.weixin.qq.com/s/xxxxx",
+    timeout=30,                    # 默认 15 秒
+    user_agent="MyBot/1.0",         # 默认使用内置 User-Agent
+    proxy="http://127.0.0.1:7890",  # 可选，显式指定代理
+    include_raw_html=True,          # 默认 False
+)
+print(result.raw_html)
+```
+
+## 返回结果
+
+两个接口均返回 `ArticleResult` 数据类，常用字段如下：
+
+| 字段 | 说明 |
+|---|---|
+| `article_title` / `article_description` | 文章标题 / 摘要 |
+| `article_markdown` | Markdown 正文 |
+| `article_publish_time` | 发布时间，Unix 时间戳 |
+| `article_cover_image` / `images` | 封面链接 / 最终保留的正文图片链接列表 |
+| `mp_name` / `mp_user_name` | 公众号名称 / 用户名 |
+| `article_display_type` | `article`、`video`、`audio`、`image`、`text` 或 `unknown` |
+| `article_url_type` | 输入链接类型：`short`、`long` 或 `unknown` |
+| `article_is_paid` | 是否检测到付费标记 |
+| `is_valid` | 关键字段是否完整的计算属性 |
+
+完整字段、枚举、长链接识别条件及 JSON 序列化示例见 [API 参考](docs/api.md)。
+
+## 使用边界与错误处理
+
+- 基于页面 HTML 和已知脚本数据提取，不执行 JavaScript，不还原交互与视觉布局。图片返回链接，不下载媒体文件。
+- 明确识别的 SVG 快速逐帧动画仅保留首帧；轮播及无法确认的帧序列保留可提取图片。具体规则见[正文转换规则](docs/content-rules.md)。
+- 视频、音频分享可以没有文字附言。付费预览及部分卡片可能只返回文字提示；`is_valid=True` 不代表已获取付费全文、媒体文件或小程序内部内容。
+- 页面结构变化或内容不可访问时，可能返回不完整结果。调用方应检查 `is_valid`；长链接的 `article_id` 为空属于正常情况。
+- **自 2026-11-02 起，微信短链接文章页不再提供文章签名 `sn`，返回的 `article_sn` 为空字符串，不影响 `is_valid` 判断。**
+- 检测到微信人机验证时抛出 `WeChatVerifyError`；HTTP 状态异常和网络错误通过 `httpx` 异常向外传播。接口不自动重试，处理示例见 [API 参考](docs/api.md#异常与不完整结果)。
+
+## 文档
+
+- [API 参考](docs/api.md)：参数、全部返回字段、枚举、有效性判断和异常处理。
+- [正文转换规则](docs/content-rules.md)：图片与动画、微信组件、页面模板与回退规则。
+- [开发指南](docs/development.md)：本地安装、项目结构、离线测试和真实链接调试。
+- [版本记录](https://github.com/huanjuedadehen/wechat-article-parser/releases)：各版本的发布说明。
+
+## 参与贡献
+
+欢迎通过 [Issues](https://github.com/huanjuedadehen/wechat-article-parser/issues) 报告问题，或提交 Pull Request。
+请附上可复现的文章链接、版本信息和预期结果；修改解析行为时补充离线回归用例。
+开发环境和测试方法见[开发指南](docs/development.md)。
+
+## 许可证
+
+本项目使用 [MIT License](LICENSE)。

wechat_article_parser-0.0.17/docs/api.md

@@ -0,0 +1,226 @@
+# API 参考
+
+[返回 README](../README.md) · [正文转换规则](content-rules.md)
+
+## 解析接口
+
+以下接口和类型均可从 `wechat_article_parser` 顶层导入。
+
+```python
+from wechat_article_parser import ArticleResult
+
+
+def parse(
+    url: str,
+    *,
+    timeout: int = 15,
+    user_agent: str | None = None,
+    proxy: str | None = None,
+    include_raw_html: bool = False,
+) -> ArticleResult: ...
+
+async def parse_async(
+    url: str,
+    *,
+    timeout: int = 15,
+    user_agent: str | None = None,
+    proxy: str | None = None,
+    include_raw_html: bool = False,
+) -> ArticleResult: ...
+```
+
+两个接口使用相同的解析逻辑，均返回 `ArticleResult`；异步接口需要 `await`。
+每次调用创建一个 HTTP 客户端，请求时跟随重定向，结束后关闭客户端。
+
+| 参数 | 说明 |
+|---|---|
+| `url` | 微信公众号文章链接，支持短链接和长链接 |
+| `timeout` | 传给 HTTP 客户端的超时时间，单位秒，默认 `15` |
+| `user_agent` | 自定义 User-Agent，默认使用内置浏览器标识 |
+| `proxy` | 显式指定代理地址，例如 `http://127.0.0.1:7890`；默认 `None` |
+| `include_raw_html` | 默认 `False`；为 `True` 时填充 `result.raw_html` |
+
+`url` 之后的参数必须以关键字传入。`proxy=None` 时不显式设置代理；HTTP 客户端仍使用默认环境配置。
+
+```python
+from wechat_article_parser import parse
+
+result = parse(
+    "https://mp.weixin.qq.com/s/xxxxx",  # 替换为实际文章链接
+    timeout=30,
+    user_agent="MyBot/1.0",
+    proxy="http://127.0.0.1:7890",
+    include_raw_html=True,
+)
+```
+
+## 链接识别
+
+同步和异步接口均支持短链接 `/s/<22位文章ID>`（ID 由英文字母、数字、`_` 或 `-` 组成）和长链接 `/s?__biz=...&mid=...&idx=...&sn=...&chksm=...`。
+根据原始输入 URL 识别链接类型：协议须为 HTTP/HTTPS，域名须为 `mp.weixin.qq.com`，且不能包含 URL 用户名或密码。
+长链接路径须为 `/s`，且 `__biz`、`mid`、`idx`、`sn`、`chksm` 五个查询参数必须都存在且有值，
+空字符串或纯空白不算有效值；重复参数中的每个值也须非空白。额外查询参数和片段不影响识别。
+未满足识别条件时，`article_url_type` 为 `unknown`，仍尝试解析页面，不额外抛出链接校验异常。
+
+长链接返回的 `article_id` 为空，其他字段继续从页面提取。
+只有识别为 `long` 时，`is_valid` 才允许缺少 `article_id`。
+
+`ArticleURLType` 的成员为 `SHORT = "short"`、`LONG = "long"`、`UNKNOWN = "unknown"`。
+支持枚举比较、字符串比较和 JSON 序列化。链接类型按原始输入判断，不按重定向后的地址判断。
+
+## 返回结果
+
+`parse` 和 `parse_async` 均返回 `ArticleResult` 数据类，包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `mp_id_b64` | `str` | 公众号 ID（Base64 编码原始值） |
+| `mp_id` | `int` | 公众号 ID（解码后的整数） |
+| `mp_name` | `str` | 公众号名称 |
+| `mp_alias` | `str` | 公众号别名 |
+| `mp_user_name` | `str` | 公众号用户名（如 `aifaner383402` 或 `gh_9a1919baf888`），未获取到时为空字符串 |
+| `mp_image` | `str` | 公众号头像链接 |
+| `mp_description` | `str` | 公众号简介 |
+| `mp_account_type` | `AccountType` | 账号类型：`AccountType.SUBSCRIPTION`（订阅号）/ `AccountType.SERVICE`（服务号）/ `AccountType.UNKNOWN`（未识别） |
+| `article_id` | `str` | 短链接中的文章 ID；长链接为空字符串 |
+| `article_url_type` | `ArticleURLType` | 输入链接类型：`short`、`long` 或 `unknown`（默认）；可从包顶层导入枚举，支持字符串比较和 JSON 序列化 |
+| `article_msg_id` | `int` | 文章所在的群发消息 ID |
+| `article_idx` | `int` | 群发图文中的位置（从 1 开始） |
+| `article_sn` | `str` | 文章签名（防伪校验）；页面未提供时为空字符串，不影响 `is_valid` |
+| `article_title` | `str` | 文章标题 |
+| `article_cover_image` | `str` | 文章封面图链接 |
+| `article_description` | `str` | 文章摘要 |
+| `article_markdown` | `str` | 文章正文的 Markdown 内容；视频或音频分享没有文字附言时可为空 |
+| `article_publish_time` | `int` | 发布时间（Unix 时间戳） |
+| `article_is_paid` | `bool` | 是否检测到当前文章的付费标记，默认 `False`；不表示是否已获取付费全文 |
+| `article_display_type` | `ArticleDisplayType` | 文章展示类型：`article`、`video`、`audio`、`image`、`text` 或 `unknown` |
+| `article_item_show_type` | `int \| None` | 微信页面中的原始展示类型：`0` 图文、`5` 视频、`7` 音频、`8` 图片轮播、`10` 文字；其他已提取的数值原样保留，缺失或无法解析时为 `None` |
+| `raw_html` | `str` | 原始 HTML 网页源代码（仅在 `include_raw_html=True` 时填充，否则为空字符串） |
+| `images` | `list[str]` | 最终保留的正文图片链接，按顺序去重；不包含被省略的动画帧、小程序封面和头像、红包封面预览图 |
+| `is_valid` | `bool` | 关键字段是否全部解析成功（属性） |
+
+`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_msg_id`、`article_idx`、`article_title`、`article_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type in ("video", "audio")`。
+`article_sn` 为非必需字段，页面未提供签名时仍可返回有效结果；这不改变输入长链接的参数要求，详见[链接识别](#链接识别)。
+此外，`article_url_type == "long"` 时允许 `article_id` 为空；短链接和未识别链接仍要求 `article_id` 非空。
+视频和音频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频或音频文件。
+
+付费受限页面返回提示且关键元数据完整时，`is_valid` 也为 `True`，这不表示已获取付费正文。
+
+未提取到的字符串默认为 `""`，整数默认为 `0`，图片列表默认为空列表；
+展示类型、链接类型和账号类型默认为各自的 `UNKNOWN`。
+`article_is_paid` 默认为 `False`，`article_item_show_type` 默认为 `None`。
+
+## JSON 序列化
+
+```python
+import json
+from dataclasses import asdict
+
+from wechat_article_parser import parse
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+data = asdict(result)
+data["is_valid"] = result.is_valid
+print(json.dumps(data, ensure_ascii=False, indent=2))
+```
+
+`is_valid` 是计算属性，**不包含在 `asdict(result)` 中**，需要时自行加入。
+三个枚举均继承自 `str`，JSON 中直接输出字符串值。
+
+## 判断是否为付费文章
+
+```python
+from wechat_article_parser import parse
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+print(result.article_is_paid)  # True：识别为付费文章
+```
+
+未检测到付费标记时返回 `False`；有可见预览或可访问正文的付费文章仍返回 `True`。
+该字段包含在 `dataclasses.asdict(result)` 中，JSON 序列化为布尔值。
+标记来源及预览处理方式见[正文转换规则](content-rules.md#微信组件与占位提示)。
+
+## 判断文章展示类型
+
+`ArticleDisplayType` 是字符串枚举，既支持枚举比较，也支持语义字符串比较：
+
+| 枚举 | 字符串值 | 含义 |
+|---|---|---|
+| `ArticleDisplayType.ARTICLE` | `article` | 图文，包括转载式 |
+| `ArticleDisplayType.VIDEO` | `video` | 视频分享 |
+| `ArticleDisplayType.AUDIO` | `audio` | 音频分享 |
+| `ArticleDisplayType.IMAGE` | `image` | 图片轮播 |
+| `ArticleDisplayType.TEXT` | `text` | 文字消息 |
+| `ArticleDisplayType.UNKNOWN` | `unknown` | 页面类型缺失或未支持 |
+
+```python
+from wechat_article_parser import parse, ArticleDisplayType
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+if result.article_display_type == ArticleDisplayType.VIDEO:
+    print("这是视频分享")
+
+if result.article_display_type == "video":
+    print("视频分享可以没有文字正文")
+
+print(result.article_display_type)  # 例如 video
+print(result.article_item_show_type)  # 例如 5
+```
+
+`article_display_type` 是返回结果中的数据字段，包含在 `dataclasses.asdict(result)` 中，JSON 序列化时输出语义字符串。
+`article_item_show_type` 返回微信页面中 `item_show_type` 的原始数值，也包含在 `dataclasses.asdict(result)` 中；JSON 序列化时输出数字或 `null`。
+
+## 判断账号类型
+
+`AccountType` 继承自 `str` 枚举，既支持枚举比较，也支持与中文字符串直接比较：
+
+```python
+from wechat_article_parser import parse, AccountType
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+
+# 推荐：枚举比较（有类型提示与 IDE 补全）
+if result.mp_account_type == AccountType.SERVICE:
+    print("这是服务号")
+
+# 也支持：字符串字面量比较
+if result.mp_account_type == "服务号":
+    print("这是服务号")
+
+# 打印直接输出中文值
+print(f"账号类型: {result.mp_account_type}")  # 账号类型: 订阅号
+```
+
+`AccountType.UNKNOWN` 的字符串值为空字符串 `""`。
+
+## 异常与不完整结果
+
+| 情况 | 行为 |
+|---|---|
+| 检测到微信验证码或人机验证页面 | 抛出 `WeChatVerifyError` |
+| HTTP 状态异常 | `response.raise_for_status()` 抛出的 `httpx.HTTPStatusError` 直接向外传播 |
+| 请求超时、连接失败等网络问题 | `httpx.RequestError` 及其子类直接向外传播，例如 `httpx.TimeoutException` |
+| 页面可获取，但关键内容未提取完整 | 返回 `ArticleResult`，由调用方检查 `is_valid` |
+
+```python
+import httpx
+
+from wechat_article_parser import WeChatVerifyError, parse
+
+try:
+    result = parse("https://mp.weixin.qq.com/s/xxxxx")
+except WeChatVerifyError:
+    print("微信要求人机验证，请稍后重试")
+except httpx.HTTPStatusError as exc:
+    print(f"HTTP 请求失败：{exc.response.status_code}")
+except httpx.RequestError as exc:
+    print(f"网络请求失败：{exc}")
+else:
+    if result.is_valid:
+        print(result.article_markdown)
+    else:
+        print("部分关键字段未能解析，请检查返回结果")
+```
+
+接口不自动重试。封面、摘要等非必填字段为空不影响有效性；
+`is_valid` 不用于判断付费全文、视频文件或组件内部内容是否已获取。

wechat_article_parser-0.0.17/docs/content-rules.md

@@ -0,0 +1,95 @@
+# 正文转换规则
+
+[返回 README](../README.md) · [API 参考](api.md) · [开发指南](development.md)
+
+本文说明 Markdown 和图片列表的保留规则，以及页面模板的识别方式。
+解析器从页面 HTML 和已知脚本数据结构提取内容，不执行 JavaScript，也不渲染页面截图。
+
+## 文字与排版
+
+- 保留可提取的正文文字、段落、图片和普通正文链接，转换为 Markdown；不还原原网页的样式和交互布局。
+- 富文本中的代码保留缩进与换行，代码中的不换行空格转为普通空格；表格中的管道符进行转义。
+- 展开无格式作用的 `span`，合并重复嵌套的加粗、斜体和删除线，避免编辑器生成的冗余标签导致递归超限。
+- 纯文本和分享附言保留换行。纯文本、全屏布局分支的标题超过 50 字符时，优先取不超过 50 字符的首句，否则截取前 30 字符。
+
+## 图片与 SVG
+
+| 内容 | 输出规则 |
+|---|---|
+| 静态正文图片 | 保留图片链接 |
+| 轮播图片 | 保留各页图片 |
+| SVG 缩放动画中的图片 | 保留图片，去掉缩放效果 |
+| 明确识别的 SVG 快速逐帧序列 | 仅保留首帧 |
+| 无法确认的帧序列、CSS / JavaScript 动画 | 保留可提取的图片，不执行动画 |
+| SVG 延迟显示、点击展开的内容 | 直接输出可提取的文字和图片 |
+| SVG 跳转链接 | 去掉链接，保留其中的文字或图片 |
+| SVG 遮罩、空热区、动画控制和无来源空图片 | 不生成正文 |
+
+富文本图片支持 `src`、`data-src`；SVG 图片支持 `background`、`background-image` 中的
+HTTP(S) 地址（有引号或无引号）、`foreignObject` 内的图片，以及 `<image href="…">` / `<image xlink:href="…">`。
+微信 CDN 图片地址会进行规格标准化，提取结果不保证与原始 URL 完全相同。
+这里只返回链接，不下载图片文件，也不对 GIF 等图片文件解码、截取首帧。
+
+`images` 收集最终保留的正文图片并按顺序去重；除已识别的帧序列缩减外，富文本 Markdown 保留原文重复图片。
+小程序封面、头像和红包封面预览图按下文规则排除。
+
+SVG `<text>` / `<tspan>` 和 `foreignObject` 中的 HTML 正文按原顺序保留。
+定义、裁剪、遮罩、辅助标题/说明及路径等几何元素不作为正文输出。
+这些规则按标签和结构处理，**不会根据画面语义判断一张图片是否为纯装饰**，也不把 SVG 矢量图形栅格化为图片。
+
+### 快速逐帧序列的识别条件
+
+当前仅对可确认的结构缩减图片，规则包括：
+
+- 图片尺寸相同，按横向或纵向等距排列；循环的 `discrete` 平移动画按对应坐标依次切换。
+- 合并连续重复坐标后至少有 3 个位置，总时长除以位置数大于 0 且不超过 0.2 秒。
+- 支持动画序列末尾分号、重复坐标停留，以及通过最近 SVG 的 `viewBox` 或明确尺寸解析的百分比宽高。
+- 背景 SVG 未设置自身位置和尺寸时，可读取直接外层 `foreignObject` 的几何信息。
+- 帧间距大于图片尺寸时，须确认视口能容纳当前帧且不会展示相邻帧；未播放的尾图仅在视口恰好容纳一帧时省略。
+- 存在不支持的额外变换、关键时间点或无法确认的几何结构时，不缩减帧序列。
+
+## 微信组件与占位提示
+
+以下规则用于富文本正文中的相应组件。组件文字按其正文位置输出；
+仅有组件提示且关键元数据完整时，`is_valid` 也可能为 `True`。
+
+| 内容 | Markdown 输出 | 范围说明 |
+|---|---|---|
+| 仅有视频号视频卡片或微信视频 iframe | 这是一篇纯视频内容。 | 不提取视频文件 |
+| 仅有付费预览占位 | 这是一篇付费内容，正文需付费后查看。 | 保留公开元数据；可见预览正文正常提取 |
+| 仅有商品广告卡片（`mp-common-cpsad`） | 这是一篇商品推荐内容。 | 已有文字和图片仍正常提取，不表示获取了商品详情 |
+| 公众号推荐卡片（`mp-common-profile`） | `**公众号名称**：简介` | 缺少名称或简介时，仅输出已有字段 |
+| 小程序卡片（`mp-common-miniprogram`） | 加粗标题、`小程序：名称`、请在微信中打开小程序查看内容。 | 缺少标题或名称时省略对应段落；不保留封面、头像和内部路径链接 |
+| 红包封面（`mp-common-redpacket`） | 红包封面，请在微信中查看。 | 不展示名称、预览图或领取链接，不判断是否仍可领取 |
+| 投票（`mp-common-vote`） | 加粗题目及选项列表 | 支持多题和多个组件；不输出票数，不推断单选或多选 |
+
+投票数据缺失或异常时，保留组件已有文字；没有文字则输出“投票内容，请在微信中查看。”。
+解析结果不代表完整投票内容或实时结果。
+
+`article_is_paid` 独立于正文内容：有可见预览或可访问正文的付费文章仍会标记为 `True`。
+识别来源为页面全局或 `window.cgiDataNew` 直接属性中的 `is_pay_subscribe`，以及正文中的 `mp-pay-preview-filter`。
+
+## 页面模板与回退
+
+解析优先读取全局 `item_show_type`：`0` 图文、`5` 视频、`7` 音频、`8` 图片轮播、`10` 文字。
+音频与视频共用文字附言提取逻辑。展示类型的原始值和语义值分别写入
+`article_item_show_type` 和 `article_display_type`。
+
+字段缺失、未知或优先分支未提取到正文时，依次尝试：
+
+| 顺序 | 模板 | HTML 特征 |
+|---|---|---|
+| 1 | 标准富文本 | `div.rich_media_content` |
+| 2 | 转载式 | `div.original_page` |
+| 3 | 纯文本 | `p#js_text_desc` |
+| 4 | 视频分享 | `div#js_common_share_desc_wrap` |
+| 5 | 图片轮播 | `div.share_media_swiper_content` |
+| 6 | 全屏布局 | `div#js_fullscreen_layout_padding` |
+
+每个分支使用独立候选结果，只有提取到正文才采用；失败分支不影响后续分支的标题、图片和元数据。
+展示类型由 `item_show_type` 映射，不根据回退模板重新推断，因此未知类型也可能提取到正文。
+视频、音频无附言时仍可通过最终元数据提取返回有效结果。
+
+全屏文字只读取 `cgiDataNew.text_page_info` 的直接属性：优先使用 `content_noencode`，为空或没有可见正文时尝试 `content`。
+外层或嵌套卡片中的同名字段不作为正文。图片和文字可位于不同脚本中，转义引号和换行会解码。
+图文通过全屏脚本回退提取正文时，也会读取富文本元数据。

wechat_article_parser-0.0.17/docs/development.md

@@ -0,0 +1,100 @@
+# 开发指南
+
+[返回 README](../README.md) · [正文转换规则](content-rules.md)
+
+## 本地安装
+
+需要 Python 3.10 或更高版本。建议使用虚拟环境：
+
+```bash
+git clone https://github.com/huanjuedadehen/wechat-article-parser.git
+cd wechat-article-parser
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+Windows PowerShell 下使用 `.venv\Scripts\Activate.ps1` 激活虚拟环境。
+构建系统为 hatchling，版本号、依赖及 pytest 配置集中在 `pyproject.toml`。
+
+## 项目结构
+
+```text
+src/wechat_article_parser/
+├── __init__.py  # 公开接口和类型导出
+├── models.py    # ArticleResult、枚举和异常
+└── parser.py    # HTTP 抓取、页面提取与 Markdown 转换
+tests/          # 离线回归用例与真实链接集成测试
+docs/           # API、转换规则和开发说明
+```
+
+`parse()` 和 `parse_async()` 共用 `_parse_html()`。
+修改模板或组件行为前，可先阅读[正文转换规则](content-rules.md)；公开字段约定见 [API 参考](api.md)。
+
+## 离线回归测试
+
+日常修改优先运行离线测试，不请求微信：
+
+```bash
+python -m pytest tests --ignore=tests/test_parser.py -q
+```
+
+功能用例分布在 `tests/test_*_content.py`、`test_markdown.py`、`test_type_routing.py`、
+`test_models.py`、`test_user_name.py` 等文件中。异步测试使用 `@pytest.mark.asyncio`，
+项目已配置 `asyncio_mode = "auto"`。
+
+## 真实链接集成测试
+
+以下命令会访问微信，请按需要运行：
+
+```bash
+# 全部测试：包含离线回归与真实链接请求
+python -m pytest tests -v
+
+# 仅运行真实链接测试
+python -m pytest tests/test_parser.py -v -s
+
+# 仅运行同步测试
+python -m pytest tests/test_parser.py -v -s -k "test_parse_sync"
+
+# 仅运行异步测试
+python -m pytest tests/test_parser.py -v -s -k "test_parse_async"
+```
+
+频繁请求可能触发验证码或 IP 限流。参数化同步/异步测试遇到 `WeChatVerifyError` 时会跳过，
+**跳过不代表解析通过**。其他网络错误仍会导致测试失败。
+
+## 调试单个链接
+
+将示例 URL 替换为实际文章链接：
+
+```bash
+# 打印所有字段
+python -m pytest tests/test_parser.py::test_fetch_all -s --url "https://mp.weixin.qq.com/s/xxxxx"
+
+# 打印 Markdown
+python -m pytest tests/test_parser.py::test_fetch_markdown -s --url "https://mp.weixin.qq.com/s/xxxxx"
+
+# 打印原始 HTML
+python -m pytest tests/test_parser.py::test_fetch_raw_html -s --url "https://mp.weixin.qq.com/s/xxxxx"
+
+# 通过代理请求
+python -m pytest tests/test_parser.py::test_fetch_all -s \
+  --url "https://mp.weixin.qq.com/s/xxxxx" \
+  --proxy "http://127.0.0.1:7890"
+```
+
+`--url` 只供三个 `test_fetch_*` 调试入口使用，不替换参数化集成测试中的链接列表。
+未传 `--url` 时，这三个入口会跳过；遇到验证码时则直接抛出异常。
+`--proxy` 供真实链接测试使用。
+
+`test_fetch_all` 和 `test_fetch_markdown` 只打印结果，不断言解析有效；
+`test_fetch_raw_html` 只检查原始 HTML 非空。验证修复时应同时检查关键字段、`is_valid` 和实际正文内容。
+
+## 提交问题与贡献代码
+
+- 通过 [Issues](https://github.com/huanjuedadehen/wechat-article-parser/issues) 报告问题，提供包版本、Python 版本、可复现的文章链接、预期结果和实际结果或异常。
+- 分享 HTML、日志或代理配置前，移除凭据及不适合公开的信息。
+- 修改解析行为时添加对应的离线 HTML 或脚本样例，断言正文、图片或元数据的预期结果，再按需要验证真实链接。
+- 保持同步和异步接口行为一致；修改公开接口或转换规则时同步更新文档。
+- 注释与文档使用中文。提交 PR 前运行离线回归测试，并在 PR 中说明改动目的与验证方式。