wx-downloder 0.1.1__tar.gz

wx_downloder-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+*.part
+auth.json
+.env
+.DS_Store
+.playwright-cli/
+*.mp4
+*.log

wx_downloder-0.1.1/LICENSE

@@ -0,0 +1,35 @@
+"Commons Clause" License Condition v1.0
+
+License: MIT License
+Licensor: ltaoo
+Software: wx_channels_download (including binaries and distributions under the names "wx_channels_download.exe", "wx_channel", "wx_video_download", and any substantially similar names)
+
+The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For the purposes of the foregoing, "Sell" means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration, a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any licensee who wishes to Sell the Software must obtain a separate license from the Licensor.
+
+---
+
+MIT License
+
+Copyright (c) 2025 ltaoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wx_downloder-0.1.1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: wx-downloder
+Version: 0.1.1
+Summary: 通过元宝登录解析并下载微信视频号分享链接的 Python CLI
+Project-URL: Homepage, https://github.com/QinGeneral/wx-downloder
+Project-URL: Repository, https://github.com/QinGeneral/wx-downloder
+Project-URL: Issues, https://github.com/QinGeneral/wx-downloder/issues
+License: "Commons Clause" License Condition v1.0
+        
+        License: MIT License
+        Licensor: ltaoo
+        Software: wx_channels_download (including binaries and distributions under the names "wx_channels_download.exe", "wx_channel", "wx_video_download", and any substantially similar names)
+        
+        The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
+        
+        Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+        
+        For the purposes of the foregoing, "Sell" means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration, a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any licensee who wishes to Sell the Software must obtain a separate license from the Licensor.
+        
+        ---
+        
+        MIT License
+        
+        Copyright (c) 2025 ltaoo
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: playwright<2,>=1.51
+Description-Content-Type: text/markdown
+
+# wx-downloder
+
+独立 Python CLI：打开腾讯元宝登录、保存登录凭据、解析微信视频号分享链接并下载 MP4。基于原项目 [wx_channels_download](https://github.com/ltaoo/wx_channels_download) 的元宝分享链接下载流程迁移；运行时无需 Go、微信客户端、代理抓包服务或 Cloudflare Worker。
+
+## 安装
+
+需要 Python 3.10+，以及 Chrome 或 Playwright Chromium。
+
+```bash
+uv tool install wx-downloder
+wx-downloder --help
+```
+
+固定安装本次版本：`uv tool install wx-downloder==0.1.1`。也支持 `python -m pip install wx-downloder`。
+
+如未安装 Chrome，安装 Playwright Chromium：
+
+```bash
+uv tool run --from playwright playwright install chromium
+```
+
+源码开发安装：
+
+```bash
+git clone https://github.com/QinGeneral/wx-downloder.git
+cd wx-downloder
+uv sync
+uv run wx-downloder --help
+```
+
+从旧版 `wx-channels` 更新：先安装新版并确认 `wx-downloder --version` 输出 `0.1.1`，再运行 `uv tool uninstall wx-channels-cli` 移除旧命令。配置目录、`WX_CHANNELS_HOME` 环境变量和登录凭据位置保持兼容，已经登录的用户无需再次扫码。
+
+0.1.1 修复登录成功后浏览器关闭时请求回调反复抛出 `TargetClosedError`：请求监听使用本地缓存的请求头，并在关闭前解除监听。
+
+项目默认使用清华 PyPI 镜像以改善国内安装速度；需要官方源时可执行 `uv sync --default-index https://pypi.org/simple`。
+
+## 登录和下载
+
+```bash
+# 启动独立浏览器窗口，扫码或手机号登录，检测到凭据后自动保存
+wx-downloder login
+
+# 单个链接；未保存登录凭据时会自动打开登录窗口
+wx-downloder download 'https://weixin.qq.com/sph/实际分享ID'
+
+# 多个链接 / JSON 文件 / 内联 JSON
+wx-downloder download 'https://weixin.qq.com/sph/ID1' 'https://weixin.qq.com/sph/ID2'
+wx-downloder download --input examples/links.json
+wx-downloder download links.json
+wx-downloder download '["https://weixin.qq.com/sph/ID1", {"url":"https://weixin.qq.com/sph/ID2"}]'
+cat links.json | wx-downloder download - --no-login --json
+
+# 不传参数：终端交互输入；管道输入则读取标准输入
+wx-downloder download
+```
+
+必须使用微信分享生成的 `https://weixin.qq.com/sph/...` 链接。会自动去除分享参数和重复项。暂不支持公众号文章、直播、图集或微信内部短口令。
+
+JSON 支持字符串数组、带 `url` / `share_url` / `shareUrl` / `sourceUrl` / `link` 字段的对象，以及 `links` / `urls` / `videos` / `items` / `data` 包装的列表。文件支持 UTF-8 和 UTF-8 BOM。示例链接需替换成真实链接。开始下载前验证全部输入，避免错格式时弹出浏览器。
+
+## 目录配置
+
+```bash
+# 成品目录，默认 ~/Downloads/wx-channels
+wx-downloder config set download_dir '/Volumes/Data/微信视频'
+
+# 临时下载缓存目录，默认 ~/.cache/wx-channels（遵循 XDG_CACHE_HOME）
+wx-downloder config set cache_dir '/Volumes/Data/视频缓存'
+
+# 单次覆盖配置；支持缓存和成品在不同磁盘
+wx-downloder download --input links.json --output './videos' --cache-dir './cache'
+
+wx-downloder config set quality h265
+wx-downloder config set timeout 120
+wx-downloder config set retries 2
+wx-downloder config set browser chrome
+wx-downloder config show
+wx-downloder status
+wx-downloder logout
+```
+
+`quality` 默认为 h264；优先所选编码，缺失时尝试通用地址和另一编码。`timeout` 是单次网络读写超时（秒），`retries` 是网络错误、HTTP 429/5xx 的重试次数（0–10）。重试重新解析链接并重新下载，不续传。批量任务中某个视频失败会继续后续项，并返回退出码 1；全部下载或跳过成功返回 0；取消返回 130。
+
+视频先写入缓存目录 `.part` 文件，校验长度和 MP4 文件头后再保存成品。正常结束、失败或 Ctrl+C 时清理本次临时文件。强制终止进程留下的 `.part` 可手动删除。已有文件不会覆盖；匹配下载记录且大小一致的文件自动跳过。成品名称包含视频标题和链接哈希，避免同名冲突；成品目录中的 `.wx-*.json` 保存标题、作者和去重记录，请保留。
+
+## 登录凭据
+
+元宝接口实际使用完整 Cookie，而非单个 token。CLI 在独立浏览器上下文中等待 `hy_user` 和 `hy_token`，保存适用于元宝的 Cookie、浏览器登录状态和相关请求头。保存后关闭本次浏览器，不读取日常浏览器配置文件。
+
+配置默认位于 `~/.config/wx-channels/config.json`，凭据位于同目录的 `auth.json`。可用 `WX_CHANNELS_HOME` 指定其他配置目录。凭据原子写入，文件权限为 `0600`，不打印到终端；下载 CDN 和视频号预览请求不携带元宝 Cookie。`logout` 删除本地凭据，不注销服务器会话。`status` 只反映本地保存情况；服务端凭据过期需重新 `login`。
+
+使用 [Playwright 浏览器登录状态保存机制](https://playwright.dev/python/docs/auth)。元宝和视频号接口并非稳定公开 API，接口或登录方式变化时可能需要更新。真实扫码必须由用户完成；自动测试使用模拟接口，不等同于真实账号端到端验证。
+
+## 开发验证
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv build
+
+# 可选：真实 Chrome 回归测试，模拟登录成功后仍有请求进行的场景
+WX_DOWNLODER_BROWSER_TEST=1 uv run pytest tests/test_browser_login.py -q
+```
+
+原项目许可证为 MIT + Commons Clause，保留在 `LICENSE`；本项目沿用该许可条件。
+
+验收记录：39 项常规自动化测试和 1 项真实 Chrome 登录关闭回归测试通过，Ruff 检查及格式检查通过，wheel/源码包构建通过。使用源项目已有凭据实测下载了一个 8,155,895 字节的视频，ffprobe 确认含 H.264 视频流和 AAC 音频流，时长 73.45 秒。该实测不替代用户首次扫码登录；新项目未预填源项目的凭据。
+
+## 发布流程
+
+发布使用 GitHub Actions 的 `.github/workflows/release.yml`，绑定 PyPI Trusted Publisher：`QinGeneral / wx-downloder / release.yml / pypi`。构建任务检查版本标签、运行测试、构建 wheel 和源码包并验证 CLI；独立发布任务通过 OIDC 上传，只有发布任务拥有 `id-token: write` 权限。
+
+维护者更新版本并提交后，创建与版本一致的 `v<版本>` 标签并推送即可发布。PyPI 版本不可覆盖。PyPI 页面：[wx-downloder](https://pypi.org/project/wx-downloder/)。

wx_downloder-0.1.1/README.md

@@ -0,0 +1,114 @@
+# wx-downloder
+
+独立 Python CLI：打开腾讯元宝登录、保存登录凭据、解析微信视频号分享链接并下载 MP4。基于原项目 [wx_channels_download](https://github.com/ltaoo/wx_channels_download) 的元宝分享链接下载流程迁移；运行时无需 Go、微信客户端、代理抓包服务或 Cloudflare Worker。
+
+## 安装
+
+需要 Python 3.10+，以及 Chrome 或 Playwright Chromium。
+
+```bash
+uv tool install wx-downloder
+wx-downloder --help
+```
+
+固定安装本次版本：`uv tool install wx-downloder==0.1.1`。也支持 `python -m pip install wx-downloder`。
+
+如未安装 Chrome，安装 Playwright Chromium：
+
+```bash
+uv tool run --from playwright playwright install chromium
+```
+
+源码开发安装：
+
+```bash
+git clone https://github.com/QinGeneral/wx-downloder.git
+cd wx-downloder
+uv sync
+uv run wx-downloder --help
+```
+
+从旧版 `wx-channels` 更新：先安装新版并确认 `wx-downloder --version` 输出 `0.1.1`，再运行 `uv tool uninstall wx-channels-cli` 移除旧命令。配置目录、`WX_CHANNELS_HOME` 环境变量和登录凭据位置保持兼容，已经登录的用户无需再次扫码。
+
+0.1.1 修复登录成功后浏览器关闭时请求回调反复抛出 `TargetClosedError`：请求监听使用本地缓存的请求头，并在关闭前解除监听。
+
+项目默认使用清华 PyPI 镜像以改善国内安装速度；需要官方源时可执行 `uv sync --default-index https://pypi.org/simple`。
+
+## 登录和下载
+
+```bash
+# 启动独立浏览器窗口，扫码或手机号登录，检测到凭据后自动保存
+wx-downloder login
+
+# 单个链接；未保存登录凭据时会自动打开登录窗口
+wx-downloder download 'https://weixin.qq.com/sph/实际分享ID'
+
+# 多个链接 / JSON 文件 / 内联 JSON
+wx-downloder download 'https://weixin.qq.com/sph/ID1' 'https://weixin.qq.com/sph/ID2'
+wx-downloder download --input examples/links.json
+wx-downloder download links.json
+wx-downloder download '["https://weixin.qq.com/sph/ID1", {"url":"https://weixin.qq.com/sph/ID2"}]'
+cat links.json | wx-downloder download - --no-login --json
+
+# 不传参数：终端交互输入；管道输入则读取标准输入
+wx-downloder download
+```
+
+必须使用微信分享生成的 `https://weixin.qq.com/sph/...` 链接。会自动去除分享参数和重复项。暂不支持公众号文章、直播、图集或微信内部短口令。
+
+JSON 支持字符串数组、带 `url` / `share_url` / `shareUrl` / `sourceUrl` / `link` 字段的对象，以及 `links` / `urls` / `videos` / `items` / `data` 包装的列表。文件支持 UTF-8 和 UTF-8 BOM。示例链接需替换成真实链接。开始下载前验证全部输入，避免错格式时弹出浏览器。
+
+## 目录配置
+
+```bash
+# 成品目录，默认 ~/Downloads/wx-channels
+wx-downloder config set download_dir '/Volumes/Data/微信视频'
+
+# 临时下载缓存目录，默认 ~/.cache/wx-channels（遵循 XDG_CACHE_HOME）
+wx-downloder config set cache_dir '/Volumes/Data/视频缓存'
+
+# 单次覆盖配置；支持缓存和成品在不同磁盘
+wx-downloder download --input links.json --output './videos' --cache-dir './cache'
+
+wx-downloder config set quality h265
+wx-downloder config set timeout 120
+wx-downloder config set retries 2
+wx-downloder config set browser chrome
+wx-downloder config show
+wx-downloder status
+wx-downloder logout
+```
+
+`quality` 默认为 h264；优先所选编码，缺失时尝试通用地址和另一编码。`timeout` 是单次网络读写超时（秒），`retries` 是网络错误、HTTP 429/5xx 的重试次数（0–10）。重试重新解析链接并重新下载，不续传。批量任务中某个视频失败会继续后续项，并返回退出码 1；全部下载或跳过成功返回 0；取消返回 130。
+
+视频先写入缓存目录 `.part` 文件，校验长度和 MP4 文件头后再保存成品。正常结束、失败或 Ctrl+C 时清理本次临时文件。强制终止进程留下的 `.part` 可手动删除。已有文件不会覆盖；匹配下载记录且大小一致的文件自动跳过。成品名称包含视频标题和链接哈希，避免同名冲突；成品目录中的 `.wx-*.json` 保存标题、作者和去重记录，请保留。
+
+## 登录凭据
+
+元宝接口实际使用完整 Cookie，而非单个 token。CLI 在独立浏览器上下文中等待 `hy_user` 和 `hy_token`，保存适用于元宝的 Cookie、浏览器登录状态和相关请求头。保存后关闭本次浏览器，不读取日常浏览器配置文件。
+
+配置默认位于 `~/.config/wx-channels/config.json`，凭据位于同目录的 `auth.json`。可用 `WX_CHANNELS_HOME` 指定其他配置目录。凭据原子写入，文件权限为 `0600`，不打印到终端；下载 CDN 和视频号预览请求不携带元宝 Cookie。`logout` 删除本地凭据，不注销服务器会话。`status` 只反映本地保存情况；服务端凭据过期需重新 `login`。
+
+使用 [Playwright 浏览器登录状态保存机制](https://playwright.dev/python/docs/auth)。元宝和视频号接口并非稳定公开 API，接口或登录方式变化时可能需要更新。真实扫码必须由用户完成；自动测试使用模拟接口，不等同于真实账号端到端验证。
+
+## 开发验证
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv build
+
+# 可选：真实 Chrome 回归测试，模拟登录成功后仍有请求进行的场景
+WX_DOWNLODER_BROWSER_TEST=1 uv run pytest tests/test_browser_login.py -q
+```
+
+原项目许可证为 MIT + Commons Clause，保留在 `LICENSE`；本项目沿用该许可条件。
+
+验收记录：39 项常规自动化测试和 1 项真实 Chrome 登录关闭回归测试通过，Ruff 检查及格式检查通过，wheel/源码包构建通过。使用源项目已有凭据实测下载了一个 8,155,895 字节的视频，ffprobe 确认含 H.264 视频流和 AAC 音频流，时长 73.45 秒。该实测不替代用户首次扫码登录；新项目未预填源项目的凭据。
+
+## 发布流程
+
+发布使用 GitHub Actions 的 `.github/workflows/release.yml`，绑定 PyPI Trusted Publisher：`QinGeneral / wx-downloder / release.yml / pypi`。构建任务检查版本标签、运行测试、构建 wheel 和源码包并验证 CLI；独立发布任务通过 OIDC 上传，只有发布任务拥有 `id-token: write` 权限。
+
+维护者更新版本并提交后，创建与版本一致的 `v<版本>` 标签并推送即可发布。PyPI 版本不可覆盖。PyPI 页面：[wx-downloder](https://pypi.org/project/wx-downloder/)。

wx_downloder-0.1.1/examples/links.json

@@ -0,0 +1,6 @@
+{
+  "links": [
+    "https://weixin.qq.com/sph/REPLACE_WITH_SHARE_ID",
+    {"url": "https://weixin.qq.com/sph/REPLACE_WITH_ANOTHER_ID", "title": "可选备注，不参与文件名生成"}
+  ]
+}

wx_downloder-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wx-downloder"
+version = "0.1.1"
+description = "通过元宝登录解析并下载微信视频号分享链接的 Python CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+dependencies = ["httpx>=0.28,<1", "playwright>=1.51,<2"]
+
+[project.scripts]
+wx-downloder = "wx_channels_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/QinGeneral/wx-downloder"
+Repository = "https://github.com/QinGeneral/wx-downloder"
+Issues = "https://github.com/QinGeneral/wx-downloder/issues"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff>=0.11"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wx_channels_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/examples", "/README.md", "/LICENSE", "/pyproject.toml", "/uv.lock"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[[tool.uv.index]]
+name = "tuna"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true

wx_downloder-0.1.1/src/wx_channels_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

wx_downloder-0.1.1/src/wx_channels_cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

wx_downloder-0.1.1/src/wx_channels_cli/auth.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import time
+from urllib.parse import urlsplit
+
+from .client import ORIGIN
+from .config import AppError, app_home, read_json, write_json
+
+
+def cookie_header(cookies: list[dict]) -> str:
+    now = time.time()
+    valid = []
+    for cookie in cookies:
+        domain = cookie.get("domain", "").lstrip(".")
+        expiry = cookie.get("expires", -1)
+        if (
+            domain
+            and ("yuanbao.tencent.com" == domain or "yuanbao.tencent.com".endswith("." + domain))
+            and (expiry == -1 or expiry > now)
+            and cookie.get("value")
+            and "/api/weixin/get_parse_result".startswith(cookie.get("path", "/"))
+        ):
+            valid.append(cookie)
+    valid.sort(key=lambda c: len(c.get("path", "/")), reverse=True)
+    return "; ".join(f"{c['name']}={c['value']}" for c in valid)
+
+
+def load_auth() -> dict:
+    auth = read_json(app_home() / "auth.json", {})
+    if not isinstance(auth, dict):
+        raise AppError("登录凭据文件格式错误，请运行 wx-downloder login")
+    cookie = cookie_header(auth.get("cookies", []))
+    names = {part.split("=", 1)[0] for part in cookie.split("; ")}
+    if not cookie or not {"hy_user", "hy_token"}.issubset(names):
+        raise AppError("没有可用的元宝登录凭据，请先运行 wx-downloder login")
+    return auth | {"cookie": cookie}
+
+
+def login(browser_name: str = "auto", timeout: int = 300, emit=print) -> None:
+    from playwright.sync_api import Error as BrowserError
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as pw:
+        browser = None
+        choices = ("chrome", "chromium") if browser_name == "auto" else (browser_name,)
+        for choice in choices:
+            try:
+                browser = pw.chromium.launch(
+                    headless=False, **({"channel": choice} if choice != "chromium" else {})
+                )
+                break
+            except BrowserError:
+                continue
+        if browser is None:
+            raise AppError(
+                "无法启动浏览器。请安装 Chrome，或运行 python -m playwright install chromium"
+            )
+        context = None
+        capture = None
+        try:
+            # Always authenticate afresh: reusing locally unexpired cookies here can
+            # immediately re-save a session that the server has already revoked.
+            context = browser.new_context(locale="zh-CN")
+            page = context.new_page()
+            captured = {}
+
+            def capture(request):
+                if (
+                    urlsplit(request.url).netloc != "yuanbao.tencent.com"
+                    or "/api/" not in request.url
+                ):
+                    return
+                # This property reads the event's cached headers without issuing a
+                # browser RPC. all_headers() can outlive the page during shutdown.
+                for key, value in request.headers.items():
+                    if key in (
+                        "authorization",
+                        "t-userid",
+                        "x-id",
+                        "x-device-id",
+                        "x-hy92",
+                        "x-hy93",
+                    ):
+                        captured[key] = value
+
+            context.on("request", capture)
+            page.goto(ORIGIN, wait_until="domcontentloaded", timeout=60000)
+            emit("已打开元宝，请在浏览器中完成扫码或手机号登录；检测到登录凭据后自动保存。")
+            # Site labels vary; failure to auto-open is harmless, user can click 登录.
+            for label in ("登录", "立即登录", "登录 / 注册", "Log In", "Not logged in"):
+                try:
+                    button = page.get_by_text(label, exact=True).first
+                    if button.is_visible():
+                        button.click(timeout=1500)
+                        break
+                except BrowserError:
+                    pass
+            deadline = time.monotonic() + timeout
+            while time.monotonic() < deadline:
+                if page.is_closed():
+                    raise AppError("浏览器已关闭，未保存新的登录凭据")
+                cookies = context.cookies(ORIGIN + "/api/weixin/get_parse_result")
+                names = {
+                    c["name"].lower(): c["value"]
+                    for c in cookies
+                    if c.get("value") and (c.get("expires", -1) == -1 or c["expires"] > time.time())
+                }
+                # Yuanbao creates anonymous tracking cookies before login; those do not count.
+                if names.get("hy_user") and names.get("hy_token"):
+                    state = context.storage_state()
+                    write_json(
+                        app_home() / "auth.json",
+                        {
+                            "cookies": cookies,
+                            "storage_state": state,
+                            "headers": captured,
+                            "user_agent": page.evaluate("navigator.userAgent"),
+                            "saved_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+                        },
+                    )
+                    emit("元宝登录凭据已保存（仅当前用户可读写）。")
+                    return
+                page.wait_for_timeout(1000)
+            raise AppError("等待登录超时，未检测到 hy_user/hy_token，请重新运行 wx-downloder login")
+        except BrowserError as exc:
+            raise AppError("元宝浏览器登录失败，请检查网络后重试") from exc
+        finally:
+            if context is not None and capture is not None:
+                context.remove_listener("request", capture)
+            browser.close()