Qiaomu WX Video 是一个技能包（Skill），使AI Agent（如Claude Code、Codex等）能够根据用户提供的 weixin.qq.com/sph 分享链接，自动下载微信视频号的普通视频或生成的直播回放。它遵循“先在线解析、必要时本地捕获”的流程，并内置了代理冲突诊断、哈希校验和文件验证机制。

1. 前置条件

在使用此技能前，请确保您的环境满足以下要求：

  • AI Agent环境：已安装并配置好 Claude Code、Codex 或其他支持Skills的AI编程助手。
  • 操作系统：目前仅实测支持 macOS (Apple Silicon)。Windows/Linux 适配尚未经过完整测试。
  • 微信桌面版：对于需要本地捕获的直播回放，需要在macOS上已安装并登录微信桌面版。
  • Python 3：系统需安装Python 3，技能脚本依赖它。
  • 用户授权：首次使用本地捕获功能时，需要用户明确授权根证书和系统代理变更。

2. 安装步骤

2.1 通过技能市场安装（推荐，发布后可用）

如果技能已发布到官方技能市场，可以使用以下命令一键安装：

1
npx skills add joeseesun/qiaomu-wx-video

2.2 本地开发安装（手动）

  1. 克隆或下载此仓库到您的本地机器。

  2. 复制到Agent技能目录：

    1
    2
    # 将技能包复制到 Claude Code 的技能目录（示例）
    cp -R qiaomu-wx-video ~/.agents/skills/qiaomu-wx-video

    您的AI Agent的技能目录可能不同（如 ~/.claude/skills/），请根据您的Agent配置调整路径。

  3. 验证安装（可选）：

    1
    2
    3
    4
    5
    # 验证技能包结构
    python3 ~/.agents/skills/qiaomu-wx-video/scripts/validate_skill.py ~/.agents/skills/qiaomu-wx-video

    # 触发评估测试
    python3 ~/.agents/skills/qiaomu-wx-video/scripts/trigger_eval.py ~/.agents/skills/qiaomu-wx-video

3. 使用方式

安装完成后，您可以在与AI Agent的对话中，通过自然语言指令来使用此技能。

3.1 基本指令示例

  • 下载普通视频：

    “下载这个视频号 https://weixin.qq.com/sph/xxxx”

  • 下载直播回放：

    “把这个视频号直播回放保存下来：<分享链接>”

  • 指定视频版本（默认会尝试保存H.264和H.265两个版本）：

    “只要这个视频号的高清兼容版（H.264），不要省空间版（H.265）。”

  • 强制使用本地下载路径：

    “不用在线解析，直接在本地下载这个视频号链接”

3.2 技能工作流程

当您发出指令后，Agent会按以下步骤执行：

  1. 链接校验：规范化并验证您提供的 weixin.qq.com/sph 链接。
  2. 尝试在线解析（首选）：在征得您同意后，优先使用上游的公开在线解析服务，避免安装证书和修改代理。此方式对普通分享视频成功率较高。
  3. 按需本地捕获：如果在线解析失败（常见于直播回放），技能会：
    • 检查并提示可能的代理冲突（如Shadowrocket、Clash、Surge等）。
    • 经您明确授权后，自动下载并校验所需的本地后端工具（SHA-256哈希校验）。
    • 请求根证书和系统代理权限（仅首次需要）。
    • 通过您已登录的微信桌面版捕获媒体信息并下载视频。
  4. 文件验证与输出：下载完成后，验证文件完整性，并自动恢复系统代理到启动前的状态。
  5. 输出结果：向您报告下载路径、文件大小、编码格式等信息。

4. 输出与配置

4.1 默认输出策略

  • 如果解析结果同时提供 H.264 和 H.265 编码，技能会默认下载两个文件：
    • *_H264_高清兼容版.mp4：码率通常更高，兼容性更好。
    • *_H265_省空间版.mp4：文件更小，适合归档。
  • 如果只有一路可用，或您明确指定，则只下载一个版本。

4.2 环境变量配置（可选）

您可以通过设置环境变量来定制行为：

变量名 是否必需 说明
QIAOMU_WX_VIDEO_HOME 否 指定后端工具和状态存储目录；默认使用用户级数据目录。
QIAOMU_WX_VIDEO_OUTPUT 否 指定视频下载目录；不设置则由Agent或环境决定。
QIAOMU_WX_VIDEO_BACKEND 否 指向现有的 wx_video_download 后端，可跳过自动下载。

5. 重要注意事项与风险

  • 在线解析依赖第三方服务：此步骤会将分享链接发送给上游的第三方服务，必须先获得您的明确同意。
  • 本地捕获会解密HTTPS流量：为了获取直播回放，技能需要临时作为中间人解密本机的HTTPS流量。这需要您信任根证书并授权系统代理变更。请仅在您信任的设备上使用此功能。
  • 不影响其他代理软件：技能会尝试保存并恢复您原有的代理设置（如Clash、Surge），但不会自动关闭它们。
  • 权限与合规：请确保您有权下载和保存目标内容。技能本身不会上传您的Cookie或抓包数据。

6. 故障排查（Troubleshooting）

症状 常见原因 建议处理方式
断开代理后微信无法联网 系统代理残留指向已停止的 127.0.0.1 端口 重启本地后端工具，或手动在系统网络设置中恢复HTTP/HTTPS代理。
分享链接可打开，但解析不到视频 内容为直播回放，或在线解析不支持 技能会自动切换到本地捕获路径。请确保微信桌面版已登录。
下载器启动，但微信页面无下载按钮 微信页面未经过本地代理，或页面未刷新 确认端口监听和代理已生效，然后刷新微信页面并再次播放视频。
关闭工具后无法联网 上游退出时未恢复系统代理 使用技能保存的代理快照手动恢复，或重启网络服务。
哈希校验不匹配 下载的后端文件损坏或来源不可信 删除该下载文件，停止执行，并检查上游Release页面。

7. 卸载

删除技能包不会自动移除已下载的视频、后端工具或根证书。

  1. 在卸载前，请先确认系统代理已恢复正常。
  2. 然后按照 references/security.md 中的说明，逐项清理（删除技能目录、后端文件、根证书等）。

8. 总结

Qiaomu WX Video 是一个专门为AI Agent设计的、用于下载微信视频号内容的技能包。

核心使用路径：

  1. 安装：通过 npx skills add 或手动复制到Agent技能目录。
  2. 使用：在对话中用自然语言向Agent发出下载指令（提供 weixin.qq.com/sph 链接）。
  3. 授权：根据提示，同意在线解析或授权本地捕获所需的临时系统权限。
  4. 获取结果：视频将下载到指定目录，Agent会报告完成状态。

最关键的是理解其两种工作模式：优先使用无需安装的在线解析，在失败时（特别是回放）才启动需要用户授权的本地捕获流程。建议在首次使用前，确保您已阅读并理解其安全风险和授权流程。

项目地址：https://github.com/joeseesun/qiaomu-wx-video