first commit

wechat_official_acc_article_downloader/README.md

@@ -0,0 +1,89 @@
+# 网页文章离线下载
+
+使用 uv 管理 Python 环境和依赖（Python 3.10 或更新版本）。将 `download_article.py` 与 `requirements.txt` 放在同一个目录，并确保已安装 uv。
+
+## 安装与运行
+
+在这两个文件所在目录打开终端，执行：
+
+```sh
+uv run --no-project --python 3.12 --with-requirements requirements.txt python download_article.py 'https://mp.weixin.qq.com/s/Jcu2J5YlaMdxbAUgLMd56A'
+```
+
+uv 会自动准备 Python 3.12 和所需依赖，无需手动创建或激活虚拟环境。后续运行相同命令即可复用缓存。依赖继续通过 `requirements.txt` 管理，无需创建 `pyproject.toml`。
+
+默认在**运行命令时的当前目录**创建文章目录，也可以用 `-o /你的/保存目录` 指定父目录。
+
+```text
+当前目录/
+└── 文章标题/
+    ├── 文章标题.md
+    ├── image001.png
+    └── image002.jpg
+```
+
+图片后缀按实际文件内容判断；同一地址的图片只下载一次。正文中的图片引用使用相对路径，离线阅读时请保留整个目录。支持微信的延迟加载图片和行内 CSS 背景图，保留常见的标题、段落、列表、链接、表格等 Markdown 格式；公众号的复杂视觉排版不会原样复刻。
+
+Markdown 开头不添加原文链接和作者/公众号信息，文章末尾统一追加 `来源：公众号作者，如有侵权，请联系删除。`。无法获取公众号作者时使用“未知作者”。接口返回的 `source_url` 仍保留，方便调用方追踪来源。
+
+文件名中系统不允许的字符会替换为 `_`，过长标题会截短。已有同名目录时创建 `文章标题 (2)/文章标题 (2).md`，不会覆盖已有内容。
+
+## 其他任务通过命令行调用
+
+```sh
+uv run --no-project --python 3.12 --with-requirements requirements.txt python download_article.py 'https://mp.weixin.qq.com/s/Jcu2J5YlaMdxbAUgLMd56A' --json
+```
+
+也可以从标准输入读取单个 JSON 请求：
+
+```sh
+printf '%s' '{"url":"https://mp.weixin.qq.com/s/Jcu2J5YlaMdxbAUgLMd56A","output_root":".","timeout":30,"allow_missing_images":false}' | uv run --no-project --python 3.12 --with-requirements requirements.txt python download_article.py --stdin-json
+```
+
+每次进程处理一个网址。JSON 模式下，标准输出只有一个 JSON 对象，路径均为绝对路径。调用方应解析 JSON，不要依赖错误消息的具体文字。
+
+成功返回退出码 `0`：
+
+```json
+{
+  "ok": true,
+  "title": "文章标题",
+  "source_url": "https://example.com/article",
+  "directory": "/完整路径/文章标题",
+  "markdown": "/完整路径/文章标题/文章标题.md",
+  "images": ["/完整路径/文章标题/image001.png"],
+  "warnings": []
+}
+```
+
+失败返回退出码 `1`：
+
+```json
+{"ok": false, "error": "错误说明", "error_type": "ArticleDownloadError"}
+```
+
+命令行参数格式错误由 argparse 返回退出码 `2`，说明写入标准错误。`--stdin-json` 使用 JSON 中的参数，不使用其他命令行下载选项。
+
+## 其他 Python 任务直接调用
+
+将脚本放入调用方的 Python 模块搜索路径，并在调用方的 uv 环境中安装本脚本 `requirements.txt` 所列依赖后：
+
+```python
+from download_article import save_article
+
+result = save_article(
+    url="https://mp.weixin.qq.com/s/Jcu2J5YlaMdxbAUgLMd56A",
+    output_root=".",
+    timeout=30,
+    allow_missing_images=False,
+)
+saved_directory = result.directory  # 已保存文件所在目录（绝对路径字符串）
+print(saved_directory)
+# 完整结果可调用 result.to_dict()
+```
+
+函数失败时抛出异常，调用方可自行捕获。默认任何图片失败都会终止保存并清理半成品。若只希望尽量保存正文，可传 `allow_missing_images=True` 或命令行添加 `--allow-missing-images`，失败图片会替换为文字提示，详情写入 `warnings`。
+
+微信可能返回验证、登录或失效页面，脚本会报告未找到正文，不会绕过访问限制。普通网页使用 article/main/body 提取，不适用于必须执行 JavaScript 才出现正文的页面。原文中的外链仍需联网，文章文字及成功下载的图片可离线查看。
+
+如果接口对外提供服务，请由调用方限制网址及重定向目的地，只允许可信站点；此脚本本身允许访问运行机器能连接的 HTTP 地址。