微信视频号视频归档（含创作者署名）

这个技能做什么

把一条 https://weixin.qq.com/sph/xxxx 分享链，归档成本地 MP4 + 一份署名元数据，让文件始终带着原作者信息，便于日后溯源与规范引用。

链路：本机元宝登录会话 → 元宝解析接口获取播放页信息 → 视频号官方 feed 接口取视频流地址 → 带 MP4 头校验下载 → 写出 .info.json 署名文件。

支持批量：一次传多个链接，浏览器只启动一次，逐条处理、逐条报错，某条失败不影响其他条。

适用场景与合规边界

适用：把自己创作的、或已取得作者授权的视频号内容保存到本地，用于个人学习、研究、教学与资料存档。

不适用（明确拒绝）：

• 保存他人作品后用于二次发布、公开传播、商业用途或流量搬运。
• 保存私密、已删除、付费或受访问控制的内容。
• 任何以规避平台访问控制为目的的批量抓取。

判断原则：如果用户未说明用途，按"个人存档"处理，并在汇报时提示署名文件包含原作者信息与权利声明。如用户明确表示要用于转载或商用，应先提醒其取得作者授权。

署名与溯源（本技能的设计要点）

微信视频号的作者标识（头像、昵称）是微信客户端播放器上的浮层，并不烧录在视频文件里——CDN 上的源流本身就不含画面水印。因此本技能不提供"去水印"能力，也不涉及任何水印处理；相反，它把创作者信息结构化保留下来：

1. 文件名带作者：<视频描述> - <作者昵称>.mp4
2. 同目录署名文件：<视频文件名>.info.json，含
   - author 作者昵称、author_avatar 作者头像地址、author_verified 是否认证账号
   - published_at 发布时间、tags 话题标签、title 原始描述
   - source_share_url 原始分享链接（可回溯到原视频）
   - notice 版权归属与使用限制声明

这样即使视频文件被移动或转发，原作者信息也不会丢失。

硬性规则

• 只接受 https://weixin.qq.com/sph/ 开头的官方分享链，其他链接一律拒绝。
• 绝不向用户索要 Cookie、token、generalToken、exportId 或请求头；绝不让用户从别的浏览器复制 Cookie。
• 绝不在最终回复里回显媒体直链、Cookie、请求头。
• 绝不读取用户日常 Edge/Chrome 的个人资料——浏览器配置目录是技能专属的（%LOCALAPPDATA%\wx-channels-download\profiles\<browser>）。
• 绝不移除、篡改或伪造任何来源标识；署名文件必须原样写出。
• 只处理用户有权访问的内容。不绕过私密、已删除、付费或受访问控制的内容。

依赖

• Python 3.10+（setup 脚本会自建独立 venv，不污染系统环境）
• 已安装 Edge 或 Chrome（复用现有浏览器，不下载 Playwright 自带 Chromium）
• Playwright（首次运行自动安装到技能专属目录）
• 一个腾讯元宝账号用于扫码登录（仅首次需要，会话持久保存）

标准工作流

按顺序执行，每一步都跑完再看结果。

第 0 步：先看有没有跑过大检查（省时间）

powershell -ExecutionPolicy Bypass -File scripts/run.ps1 doctor

返回里关注三个字段：
- available_browsers：本机装了哪些浏览器
- selected_browser：当前已保存的选择（null 表示还没选过）
- logged_in：true 表示元宝会话仍然有效，可以直接跳到最后一步

第 1 步：选择浏览器（仅在 selected_browser 为 null 时问一次）

只问一次：「视频号归档使用 Edge 还是 Chrome？」

用户已经说明过就直接用，不要重复问。然后保存选择：

powershell -ExecutionPolicy Bypass -File scripts/run.ps1 doctor --browser edge

把 edge 换成 chrome。选择会持久保存，以后不用再问。

> 若 available_browsers 只有一个，直接用那一个，不必问。
> 若浏览器缺失，引导用户装 Edge（https://www.microsoft.com/edge/download ）或 Chrome（https://www.google.com/chrome/ ），装完重跑 doctor。

第 2 步：登录（仅当 logged_in 不是 true）

powershell -ExecutionPolicy Bypass -File scripts/run.ps1 login --timeout 600

会弹出一个可见的浏览器窗口。告诉用户：

> 请在刚弹出的浏览器窗口里完成腾讯元宝登录（微信扫码或 QQ 登录），登录后不用关窗口。

命令会阻塞直到检测到登录（或超时）。关闭窗口不会退出登录，本地配置会复用。

第 3 步：归档

单条：

powershell -ExecutionPolicy Bypass -File scripts/run.ps1 download "https://weixin.qq.com/sph/xxxx" --output-dir "<绝对目录>"

批量（推荐，多条一起只开一次浏览器）：

powershell -ExecutionPolicy Bypass -File scripts/run.ps1 download "https://weixin.qq.com/sph/AAA" "https://weixin.qq.com/sph/BBB" --output-dir "<绝对目录>"

• 未指定 --output-dir 时默认存到用户下载文件夹。
• 需要 H.265 时加 --codec h265，默认 h264。
• 只想看元信息、不下载：把 download 换成 resolve。

第 4 步：汇报

只汇报这些：文件路径、字节数、标题、作者、是否认证、发布时间、署名文件路径、浏览器、SHA-256，以及批量时的成功/失败条数。

不要汇报媒体直链、Cookie、token、请求头。

结果文件

脚本 stdout 是纯 JSON，进度信息走 stderr。归档成功时每条包含 file_path（视频）与 attribution_file（署名文件）。批量结构：

{
  "ok": true,
  "command": "download",
  "total": 2, "succeeded": 2, "failed": 0,
  "output_dir": "C:\\...\\Downloads",
  "results": [
    {
      "ok": true,
      "title": "...", "author": "制冷百科", "author_verified": true,
      "published_at": "2026-04-24T17:00:00+08:00", "tags": ["冷库", "制冷"],
      "file_path": "C:\\...\\标题 - 制冷百科.mp4",
      "attribution_file": "C:\\...\\标题 - 制冷百科.mp4.info.json",
      "bytes": 3294077, "sha256": "..."
    }
  ]
}

单条归档时，顶层会额外展开该条的字段，读起来更省事。

⚠️ Windows 上取不到命令输出时（重要）

某些 WorkBuddy / CodeBuddy Windows 环境下，执行 PowerShell 的通道不回传 stdout（命令其实执行成功了，但你看不到输出）。这时不要反复重试，改用「日志落盘 + 读日志」：

$log = "<工作区>\logs\wx-download.log"
powershell -ExecutionPolicy Bypass -File scripts/run.ps1 download "<url>" --output-dir "<dir>" *> $log

然后读取 $log。注意：

• PowerShell Out-File / *> 默认写 UTF-16LE，读的时候要转码，例如在 bash 里
  iconv -f UTF-16LE -t UTF-8 "$log"。
• scripts/run.ps1 本身已经会把每次运行追加写到
  %LOCALAPPDATA%\wx-channels-download\last-run.log，直接读这个文件也行。

另一个环境差异：某些 Bash 沙箱会丢弃子进程（python/curl）的文件写入（命令报成功但文件不落盘）。因此凡是需要 Python 写文件的操作（装依赖、归档视频），请走 PowerShell 通道，不要走 Bash。

命令速查

通用参数：--log-file <路径> 额外把 JSON 结果追加到指定文件。

会话与故障

• 可见的 resolve / download 遇到 HTTP 401 会自动自愈：只清除本技能专属配置里的元宝登录态 → 打开登录页等你登录 → 自动重试原链接一次。
• 出现 SESSION_EXPIRED 时去弹窗里登录即可，不要在后台另起一个命令，否则会互相抢浏览器。
• 需要手动重置会话时才用 login --force，它同样只动技能专属配置。
• 保持浏览器可见。--headless 只在同一台机器上成功跑过一次可见归档之后再用；无头模式无法交互式恢复会话。
• 遇到任何非零退出或 error JSON，读 references/troubleshooting.md 按 error.code 定位。

主要错误码

来源与致谢

本技能的解析思路参考了社区中公开讨论的「视频号分享链解析」通用做法（经由官方播放页 token 换取视频号官方 feed 接口的视频流地址）。代码为独立重写实现，并在此基础上增加了批量处理、逐条错误隔离、创作者署名元数据与跨平台脚本。

发布前请确认：如本技能包含来自其他作者的代码、文档或实现思路，请在此处如实署名并确认其许可证允许再分发。

隐私与安全说明

• 只使用技能专属浏览器配置目录，不读取用户日常浏览器的 Cookie、书签、历史或个人资料。
• 不复制用户凭据到技能目录之外，不回显任何 token、Cookie 或请求头。
• 不注册开机自启项、计划任务、系统服务或常驻后台进程；浏览器仅在命令运行期间打开。
• 不连接任何第三方服务器，全部请求只发往 yuanbao.tencent.com 与 channels.weixin.qq.com。