wx_channels_download Documentation

Config Channels Index (`docs/config/channels/index.md`) Copy Section

title: 视频号配置 Copy Chapter

视频号配置

通过 config.yaml 控制视频号及其下载行为。每个配置项的说明如下：

• 启用视频号功能
• 从详情页重定向到首页
• 默认下载原始视频
• 前端下载
• 同时下载封面
• 下载时暂停播放
• 批量下载时检查所有视频

Content Archive Data Model (`docs/content-archive-data-model.md`) Copy Section

网络内容归档数据模型

1. 设计目标 Copy Chapter

本项目是一个通用内容归档工具，需要覆盖视频、音乐、小说、漫画、短内容、长文章、图集、AI 对话等常见网络内容，并支持：

• 同一种内容存在多种可下载表示，例如视频分辨率、音质、字幕格式。
• 内容包含章节、图片、漫画页、课时等嵌套实体。
• 同一个逻辑资产可以被多次下载、重新下载或从不同端点下载。
• 从视频规格、字幕、小说章节、图集图片等对象直接找到实际下载记录。
• 表达合集、系列、回复、引用、转发、翻译等内容间关系。
• 完整保留 AI 对话的消息树、重新生成分支、多模态内容和生成产物。
• 在增加新内容类型时复用现有资产和下载关联结构。

核心原则是将“内容本身”“逻辑归档资产”“实际下载记录”分开存储：

Content（一个网络内容）
├── 类型扩展：ContentVideo / ContentNovel / ContentAlbum / ContentConversation / ...
├── 嵌套实体：章节 / 图片 / 漫画页 / 课程课时 / 对话消息
├── ContentAsset（可归档的逻辑资产）
│   └── DownloadResourceAsset
│       └── DownloadResource（一次实际下载）
│           └── DownloadEndpoint（下载地址或镜像）
└── ContentRelation（系列、回复、引用、转发等关系）

2. 常见内容类型与场景 Copy Chapter

2.1 Type 和 Subtype 的职责 Copy Section

Content.Type 保持稳定和宽泛，平台差异、内容形态差异放入 Content.Subtype：

article  / answer
article  / newsletter
video    / short_video
audio    / audiobook
document / pdf

旧数据中的 answer、music、image_set 等类型会在迁移时归一到稳定大类，同时把原类型保留到 subtype。

2.2 项目当前可直接回归的平台 Copy Section

以下平台在当前代码中已经有实际的内容或下载适配器，适合优先用于端到端测试。测试时应选择自己发布、公开授权或公共领域的内容。

当前代码中的 YouTube、微博和小红书目录主要提供配置或浏览侧入口，不应暂时当作“下载适配器已经完整支持”的验收项。它们仍然很适合作为下一阶段模型覆盖和适配器开发的测试目标。

2.3 用于扩展测试的常见平台 Copy Section

下表用于验证数据模型是否能覆盖主流网络内容。标记为扩展测试的平台通常还需要新增或完善适配器。

2.4 推荐的最小验收样本集 Copy Section

为了尽快验证当前数据模型，可以先准备以下 14 组样本：

1. 一条没有字幕、没有明确分辨率的抖音短视频。
2. 一条音视频分离的哔哩哔哩视频。
3. 一条具有两个以上规格的视频号视频。
4. 一条具有两种语言、每种语言两种格式字幕的测试视频；当前可先使用测试 Fixture，后续可接入 YouTube 公开样本。
5. 一条包含三张以上图片和背景音乐的抖音或视频号图集。
6. 一条包含普通图片和 Live Photo 的自有公众号图片消息。
7. 一篇包含正文、图片、代码块和外部附件的公众号或知乎文章。
8. 一部至少包含两个卷、十个章节的番茄小说。
9. 一部章节页面使用相对 URL 的 69书吧小说。
10. 同一个视频规格连续下载两次，用于验证一个 ContentAsset 对应多个 DownloadResource。
11. 同一资源提供两个 DownloadEndpoint，用于验证端点优先级和失效切换。
12. 手工构造一个播放列表、回复或转发关系，用于验证 ContentRelation 的方向和排序。
13. 导入一段包含“编辑问题”和“重新生成回答”的 ChatGPT 或豆包对话，验证消息树和多个分支没有被展平成重复文本。
14. 导入一段包含图片上传、网页引用、工具调用和生成文件的 AI 对话，验证消息内容块与 DownloadResource 的关联。

2.5 每个平台的通用验收检查 Copy Section

每个样本下载完成后至少检查：

• Content.Id 是否稳定，重复抓取时没有产生第二条内容。
• Content.Type 是否为稳定大类，平台内容形态是否进入 Subtype。
• 每个文件是否拥有唯一且稳定的 (content_id, role, asset_key)。
• 下载 URL 的 token 更新后是否复用原 ContentAsset，只新增或更新下载实例及端点。
• 同一个 ContentAsset 是否允许关联多个 DownloadResource。
• 一个 DownloadResource 是否可以通过 DownloadResourceAsset 关联一个或多个资产。
• 章节、图片等嵌套对象是否能通过 ContentAssetLink 找到 DownloadResource。
• 删除、私密、锁定、登录过期、下载失败时是否保留内容元数据和失败状态。
• 标题包含中文、Emoji、斜杠、换行或超长字符时，逻辑 ID 是否不依赖文件名。
• 重复下载、断点续传、端点切换和派生文件是否不会破坏逻辑资产身份。
• AI 对话重新生成回答后是否保留原分支，当前分支是否可从根消息正确还原。
• AI 对话中的附件、生成图片、Canvas/Artifact 和引用是否关联到正确的消息内容块。

2.6 测试数据使用约束 Copy Section

• 优先使用自己发布的内容、平台官方示例、公共领域内容或明确授权内容。
• 不绕过 DRM、付费墙、访问控制或平台验证码。
• 登录态、Cookie、PO Token 等凭据只放在本地配置中，不写入 Fixture、日志或数据库 Metadata。
• 直播、私密内容和会话数据优先使用自己控制的测试账号。
• 外部平台页面和接口会变化，回归测试应保存脱敏后的原始响应 Fixture，线上冒烟测试与离线解析测试分开执行。

3. Content：内容主体 Copy Chapter

Content 表示一个独立、可识别的网络内容，常用字段包括：

Content
- id                 通常为 platform_id:external_id
- platform_id
- type
- subtype
- external_id
- title
- description
- source_url
- cover_url
- publish_time
- 互动数据
- metadata

内容类型特有字段存入一对一扩展表：

Content 1 ── 0..1 ContentVideo
Content 1 ── 0..1 ContentAudio
Content 1 ── 0..1 ContentArticle
Content 1 ── 0..1 ContentNovel
Content 1 ── 0..1 ContentAlbum
Content 1 ── 0..1 ContentLive
Content 1 ── 0..1 ContentPodcast
Content 1 ── 0..1 ContentDocument
Content 1 ── 0..1 ContentCourse
Content 1 ── 0..1 ContentComic
Content 1 ── 0..1 ContentPost
Content 1 ── 0..1 ContentConversation

内容通用字段不会因为增加一种媒体形态而膨胀，类型扩展表也不负责记录具体的下载过程。

4. ContentAsset：逻辑归档资产 Copy Chapter

ContentAsset 表示一个稳定的、可下载或可生成的逻辑资产：

ContentAsset
- id
- content_id
- kind
- role
- asset_key
- label
- language_code
- mime_type
- size
- sort_order
- metadata

逻辑唯一约束为：

(content_id, role, asset_key)

4.1 Kind：资产的物理形式 Copy Section

video
audio
image
text
document
archive
manifest
data
binary

4.2 Role：资产在内容中的语义 Copy Section

primary
video_variant
audio_variant
subtitle
transcript
lyrics
cover
thumbnail
live_photo
article_body
novel_chapter
novel_book
comic_page
message_attachment
generated_image
generated_file
canvas
artifact
code_output
conversation_export
attachment
source_snapshot

Kind 和 Role 分离后，同一种物理文件可以承担不同语义。例如：

• kind=image, role=cover 表示封面。
• kind=image, role=comic_page 表示漫画页。
• kind=text, role=subtitle 表示字幕文件。
• kind=text, role=novel_chapter 表示小说章节文本。
• kind=archive, role=conversation_export 表示 AI 平台的原始导出包。
• kind=image, role=generated_image 表示 AI 助手生成的图片。

5. 视频规格与多语言字幕 Copy Chapter

5.1 多种视频规格 Copy Section

一个 Content 只对应一个 ContentVideo，不同分辨率或编码保存为多个 ContentVideoVariant：

Content
└── ContentVideo
    ├── ContentVideoVariant 1080p
    ├── ContentVideoVariant 720p
    └── ContentVideoVariant 480p

每个 ContentVideoVariant.AssetId 对应一个 ContentAsset：

kind      = video
role      = video_variant
asset_key = 平台格式 ID、itag、spec 或 default

抖音、视频号等没有明确分辨率信息的视频创建一个默认规格：

asset_key = default
width     = NULL
height    = NULL

未知数据保持为空，不虚构分辨率。

5.2 多语言字幕 Copy Section

字幕分为逻辑轨道和具体文件：

Content
└── ContentTextTrack
    ├── en / official
    │   ├── VTT source
    │   └── SRT source
    ├── zh-Hans / official
    └── ja / auto-generated

ContentTextTrack 保存：

• 语言代码和显示名称。
• 字幕、说明字幕或强制字幕类型。
• 是否默认。
• 是否自动生成。
• 是否为听障字幕。

ContentTextTrackSource 保存具体格式、URL、编码和过期时间。每个 Source 对应一个 ContentAsset，未知语言使用 und。

6. 小说章节和图集图片 Copy Chapter

6.1 小说章节 Copy Section

ContentNovel
├── ContentNovelVolume
└── ContentNovelChapter
    └── ContentAssetLink
        └── ContentAsset
            └── DownloadResource

章节通过稳定的 chapter_key 标识，生成优先级为：

1. 平台章节 ID。
2. 章节 URL。
3. 章节序号，仅作为兼容回退。

同一章节可以有多种表示：

chapter-1:txt
chapter-1:html
chapter-1:epub-fragment

因此可以通过以下链路从章节直接获得实际下载记录：

ContentNovelChapter
  → Assets
  → Asset.DownloadResources

6.2 图集图片 Copy Section

ContentAlbum
└── ContentImage
    └── ContentAssetLink
        ├── 原图 ContentAsset
        └── Live Photo 视频 ContentAsset

图片身份优先使用平台稳定标识：

• 抖音使用图片 URI。
• 视频号优先使用 decode key。
• 公众号图集使用内容内顺序。
• URL 仅作为兼容回退。

这样可以避免 CDN URL 的 token 更新后重复创建图片。

7. DownloadResource：实际下载记录 Copy Chapter

DownloadResource 表示一次具体下载过程或结果：

• 下载文件名和目录。
• 下载状态和已下载字节数。
• 下载速度和实际大小。
• Stream 录制信息。
• 所属下载任务。
• 可用下载端点。

它不再承担逻辑资产身份。逻辑资产与下载实例通过 DownloadResourceAsset 建立多对多关系：

ContentAsset M ── N DownloadResource

DownloadResourceAsset
- resource_id
- asset_id
- relation

支持的关系包括：

source        Resource 下载得到该资产
contains      Resource 包含该资产
derived_from  Resource 由该资产派生

该结构支持：

• 同一个资产被多次下载或重新下载。
• 下载重试产生不同的 Resource。
• 一个 ZIP、合并文件或容器包含多个资产。
• 转码文件与原始资产之间建立关联。
• 不再依赖 content_id + spec 猜测业务关联。

DownloadResource.UniqueID 可以继续用于任务或文件去重，但不再作为资产外键。

8. ContentAssetLink：嵌套实体关联 Copy Chapter

ContentAssetLink 将资产绑定到章节、图片、漫画页、课时等内容内部实体：

ContentAssetLink
- content_id
- subject_type
- subject_key
- asset_id
- relation

目前已经实际接入：

novel_chapter
album_image
conversation_message
conversation_message_part

已经预留：

novel_volume
live_photo
comic_chapter
comic_page
course_lesson
podcast_episode

其中 AI 对话可以把附件关联到整条消息，也可以精确关联到消息中的某个有序内容块。增加漫画页或课程课时时只需要：

1. 给子实体分配稳定的 subject_key。
2. 创建对应的 ContentAsset。
3. 创建 ContentAssetLink。
4. 将下载实例写入 DownloadResourceAsset。

不需要为每种内容重新设计下载关联表。

9. ContentRelation：内容之间的关系 Copy Chapter

ContentRelation 表达顶层内容之间的有向关系：

SourceContent -- relation --> TargetContent

支持：

contains
part_of
episode_of
reply_to
quote_of
repost_of
translation_of
derived_from
related

适用场景包括：

• 播放列表包含多个视频。
• 播客节目包含多期单集。
• 课程包含多个课时。
• Twitter/X Thread 的上下级帖子。
• 微博转发和引用。
• 文章的不同语言版本。
• 直播与直播回放。
• 原视频与剪辑版本。

10. AI 对话平台归档 Copy Chapter

ChatGPT、豆包、Claude、Gemini 等 AI 对话不是简单的线性文本。一个完整对话通常可能包含：

• 用户、助手、System、Developer 和 Tool 等不同角色。
• 编辑问题后产生的分支。
• 同一个问题重新生成的多个回答。
• 对话过程中切换模型。
• 图片、音频、视频和文件输入。
• 网页搜索引用、工具调用及工具结果。
• 生成图片、代码执行结果和可下载文件。
• Canvas、Artifact 或其他可继续编辑的独立产物。

因此不能只使用一张包含 question 和 answer 的线性表。

当前实现范围需要区分为两层：

• 已实现统一数据库模型、幂等保存、详情装配、分支还原，以及消息附件到 DownloadResource 的关联。
• 尚未实现 ChatGPT、豆包等平台原始 JSON、HTML 或 ZIP 的专用解析适配器；接入平台时只需把原始数据转换成下述统一模型。

10.1 与应用自身聊天表的边界 Copy Section

现有 chat_session、chat_member、chat_message 用于应用自身聊天或通用聊天记录导入。外部 AI 对话属于内容归档体系，使用独立表：

Content
├── ContentAsset(role=conversation_export)  原始 JSON、HTML 或 ZIP
└── ContentConversation
    ├── ContentConversationBranch
    └── ContentConversationMessage
        ├── ContentAssetLink                 整条消息的附件
        └── ContentConversationMessagePart
            └── ContentAssetLink             具体内容块或生成产物
                └── ContentAsset
                    └── DownloadResourceAsset
                        └── DownloadResource

这种分离可以避免两类数据在以下方面发生冲突：

• 应用聊天使用自增 Session ID，归档内容使用 platform_id:external_id。
• 应用聊天通常是线性的，AI 对话可能是一棵消息树。
• AI 对话具有模型、工具、引用、Artifact 等特有信息。
• 归档内容需要统一接入 ContentAsset 和 DownloadResource。

10.2 ContentConversation Copy Section

一个外部平台对话对应一个 Content：

Content.Type    = conversation
Content.Subtype = ai_chat
Content.Id      = chatgpt:<conversation_id>
                  doubao:<conversation_id>

ContentConversation 保存会话级字段：

- id
- source_type
- source_format
- format_version
- default_model_provider
- default_model_name
- current_branch_key
- message_count
- branch_count
- is_shared
- metadata

实际数据库表及稳定唯一键如下：

重复导入同一对话时，保存逻辑按照这些稳定键更新已有 Branch、Message 和 Part，不依赖会变化的标题、文件名或临时 URL。

source_type 用来区分获取方式：

official_export  平台官方数据导出
browser_capture  浏览器或客户端捕获
api              平台 API
share_page       公开分享页面
manual_import    手工导入

不同来源的数据完整度并不相同。例如分享页面可能只包含当前分支，官方导出可能包含整个消息树，浏览器捕获则可能包含更完整的附件地址但 URL 有时效性。

原始 JSON、HTML 或 ZIP 不应该只解析后丢弃，应同时作为：

ContentAsset.Role = conversation_export

保存。解析后的表是当前查询投影，原始导出资产用于审计、重放和兼容未来格式变化。

10.3 消息树和对话分支 Copy Section

ContentConversationMessage 是对话树中的稳定节点：

- conversation_id
- message_key
- parent_message_key
- role
- author_name
- model_provider
- model_name
- status
- content_text
- content_hash
- sequence
- sent_at
- edited_at
- metadata

消息角色包括：

unknown
system
developer
user
assistant
tool

message_key 优先使用平台消息 ID，没有平台 ID 时才回退到导入顺序。parent_message_key 保留消息父子关系。

平台消息 ID 在统一模型中使用 external: 形式；没有 ID 时才使用 idx:<sequence>。Branch 和 Part 使用相同原则生成稳定 Key。适配器必须保证同一份平台数据重复导入时生成相同 Key。

例如，重新生成两次回答后的结构可能是：

user-1
└── assistant-1
    └── user-2
        ├── assistant-2a
        └── assistant-2b  ← 当前分支

不能将 assistant-2a 覆盖或删除。两条回答是不同消息节点，分别拥有自己的模型信息、内容块和资产。

ContentConversationBranch 记录一个可选择的消息路径：

- branch_key
- root_message_key
- leaf_message_key
- is_current
- sort_order

共享祖先无需复制。通过 leaf_message_key 沿 parent_message_key 向上遍历即可还原一个完整分支。

查询空 branch_key 时按以下顺序选择分支：

1. ContentConversation.CurrentBranchKey 指向的有效分支。
2. Branch.IsCurrent = 1 的分支。
3. 第一条已保存分支。

还原时会检测父子循环、缺失叶子消息以及无法到达声明根消息的损坏数据。

10.4 消息内容块 Copy Section

一条消息可能同时包含文本、图片和工具结果，因此使用有序的 ContentConversationMessagePart：

- conversation_id
- message_id
- message_key
- part_key
- subject_key
- sort_order
- type
- text
- url
- mime_type
- language_code
- tool_call_id
- tool_name
- metadata

支持的内容块类型包括：

text
markdown
image
audio
video
file
code
tool_call
tool_result
citation
reasoning_summary
structured
link_preview
canvas
artifact
refusal

只保存平台实际展示或导出的思考摘要，不推断或构造模型未提供的隐藏推理过程。

ContentText 是便于搜索和列表展示的文本投影；准确还原消息时应按照 Parts.SortOrder 渲染各内容块。

subject_key 是 Part 的稳定资产关联键，由 message_key 和 part_key 组合生成。由于平台 ID 可能包含分隔符，实现使用带消息 Key 长度前缀的编码，不能由适配器自行拼接普通冒号字符串。

10.5 对话附件和生成产物 Copy Section

消息或内容块本身不存储下载状态。所有上传附件、生成图片和 Artifact 继续使用 ContentAsset：

message_attachment
generated_image
generated_file
canvas
artifact
code_output
conversation_export

关联链路为：

ContentConversationMessagePart
  → ContentAssetLink(subject_type=conversation_message_part)
  → ContentAsset
  → DownloadResourceAsset
  → DownloadResource

如果一个资产属于整条消息而不是某一个 Part，可以使用：

subject_type = conversation_message
subject_key  = message_key

如果资产属于具体内容块，则使用：

subject_type = conversation_message_part
subject_key  = part.subject_key

这可以处理：

• 用户上传一张图片，平台生成缩略图和解析结果。
• 助手生成一张图片，并存在原图和预览图。
• Code Interpreter 生成 CSV、PDF 或 ZIP。
• Canvas/Artifact 同时存在源码、渲染结果和导出文件。
• 同一个附件由于重试或 URL 刷新对应多个 DownloadResource。

一个逻辑资产允许对应多个下载记录，一个下载容器也允许包含多个逻辑资产。因此对话附件同样不应通过 content_id + 文件名 或临时 URL 反向猜测归属。

10.6 平台字段映射 Copy Section

平台适配器应先保留平台原始字段，再映射到统一模型：

适配器不得将 Cookie、Authorization、临时访问 Token 或包含凭据的完整请求头写入 Metadata。Metadata 应优先保存无法归一但重建内容确实需要的业务字段；完整原始响应应保存为受保护的 conversation_export 资产。

10.7 查询 AI 对话 Copy Section

查询内容详情会返回所有分支、消息和内容块：

ContentConversation.Branches
ContentConversation.Messages
ContentConversation.Messages[].Parts
ContentConversation.Messages[].Assets
ContentConversation.Messages[].Parts[].Assets

查询当前分支：

messages, err := content_service.GetContentConversationBranch(content_id, "")

查询指定分支：

messages, err := content_service.GetContentConversationBranch(content_id, branch_key)

返回结果按照根消息到叶子消息排序，并且每个消息内容块已经带有对应的 ContentAsset 和 DownloadResource。

直接查询某个消息内容块的下载资源：

SELECT resource.*
FROM content_conversation_message_part AS part
JOIN content_asset_link AS asset_link
  ON asset_link.content_id = part.conversation_id
 AND asset_link.subject_type = 'conversation_message_part'
 AND asset_link.subject_key = part.subject_key
JOIN download_resource_asset AS resource_asset
  ON resource_asset.asset_id = asset_link.asset_id
JOIN download_resource AS resource
  ON resource.id = resource_asset.resource_id
WHERE part.conversation_id = ?
  AND part.message_key = ?
  AND part.part_key = ?
  AND resource.deleted_at IS NULL;

10.8 AI 对话测试建议 Copy Section

ChatGPT 和豆包至少分别准备以下测试样本：

1. 纯文本单分支对话。
2. 编辑用户问题后产生两个分支的对话。
3. 同一个问题重新生成两次回答的对话。
4. 对话中途切换模型的对话。
5. 上传图片并继续追问的对话。
6. 上传 PDF、表格或压缩包的对话。
7. 包含联网搜索结果和引用来源的对话。
8. 包含工具调用及工具结果的对话。
9. 包含生成图片或生成文件的对话。
10. 包含 Canvas、Artifact 或类似可编辑产物的对话。
11. 仅能通过分享页面访问的对话。
12. 同一对话重复导入，且附件临时 URL 已经变化的对话。

验收时重点检查：

• 重复导入不会重复创建 Content、Message、Part 和 ContentAsset。
• 消息编辑和回答重新生成不会破坏旧分支。
• 当前分支可以从叶子消息完整还原。
• 模型名称记录在具体助手消息上，而不是只记录会话默认模型。
• 多模态内容按照原始顺序还原。
• 附件临时 URL 更新后仍然复用同一个逻辑资产。
• 原始导出文件和解析后的结构化记录能够同时保留。

AI 对话通常包含隐私和账号数据，平台适配器或导入入口应默认将 Content.IsPrivate 设为 1，并避免把对话正文、上传文件内容和凭据写入普通运行日志。

10.9 平台适配器接入流程 Copy Section

ChatGPT、豆包或其他 AI 平台适配器建议按下面的顺序输出数据：

1. 解析平台 Conversation ID，创建 Content(Type=conversation, Subtype=ai_chat)，默认标记为私有。
2. 保存获取方式、平台格式版本和默认模型等会话级信息。
3. 遍历原始消息图，为每个节点生成稳定 message_key 和 parent_message_key。
4. 按原始顺序把文本、多模态输入、工具调用、引用和产物转换成 Message Part。
5. 根据当前叶子节点和其他可选叶子构造 Branch，不丢弃重新生成的旧回答。
6. 将上传附件、生成文件和原始导出声明为 ContentAssetReference，并指定消息或 Part 的 subject_type/subject_key。
7. 交给现有下载任务保存流程：先保存 Content，再保存 Conversation 扩展，最后创建 DownloadResource 和资产关联。

适配器生成稳定键时应调用统一帮助方法：

message_key := model.BuildContentConversationMessageKey(platform_message_id, sequence)
part_key := model.BuildContentConversationMessagePartKey(platform_part_id, sort_order)
subject_key := model.BuildContentConversationMessagePartSubjectKey(message_key, part_key)
asset_key := model.BuildContentConversationAssetKey(subject_key, representation_key)

推荐保留两类数据：

原始层：平台导出的 JSON / HTML / ZIP / 附件
投影层：ContentConversation / Branch / Message / Part

原始层保证将来可以用新版解析器重新建模，投影层用于日常列表、全文搜索、分支展示和附件查询。平台格式发生变化时，优先新增或升级平台解析器，不修改统一表来迁就某个平台的一次性字段。

11. 查询方式 Copy Chapter

11.1 查询内容及其根资产 Copy Section

内容详情查询会预加载：

Content.Assets
└── ContentAsset.DownloadResources

var content model.Content

err := db.
	Preload("Assets").
	Preload("Assets.DownloadResources").
	Where("id = ?", content_id).
	First(&content).Error

11.2 根据视频规格查询下载记录 Copy Section

var variant model.ContentVideoVariant

err := db.
	Preload("Asset.DownloadResources").
	Where("video_id = ? AND variant_key = ?", content_id, variant_key).
	First(&variant).Error

查询结果：

variant.Asset.DownloadResources

11.3 根据字幕源查询下载记录 Copy Section

var source model.ContentTextTrackSource

err := db.
	Preload("Asset.DownloadResources").
	Where("track_id = ? AND source_key = ?", track_id, "vtt").
	First(&source).Error

查询结果：

source.Asset.DownloadResources

11.4 查询小说章节或图集图片的下载记录 Copy Section

通用 SQL：

SELECT resource.*
FROM content_asset_link AS asset_link
JOIN content_asset AS asset
  ON asset.id = asset_link.asset_id
JOIN download_resource_asset AS resource_asset
  ON resource_asset.asset_id = asset.id
JOIN download_resource AS resource
  ON resource.id = resource_asset.resource_id
WHERE asset_link.content_id = ?
  AND asset_link.subject_type = ?
  AND asset_link.subject_key = ?
  AND resource.deleted_at IS NULL;

查询小说章节时：

subject_type = novel_chapter
subject_key  = chapter.chapter_key

查询图集图片时：

subject_type = album_image
subject_key  = image.image_key

内容详情服务已经组装以下查询结果：

chapter.Assets[n].Asset.DownloadResources
image.Assets[n].Asset.DownloadResources

11.5 查询内容关系 Copy Section

查询一个合集或系列包含的内容：

SELECT target.*
FROM content_relation AS relation
JOIN content AS target
  ON target.id = relation.target_content_id
WHERE relation.source_content_id = ?
  AND relation.type = 'contains'
ORDER BY relation.sort_order, target.id;

查询一条短内容引用、回复或转发的原内容：

SELECT target.*, relation.type
FROM content_relation AS relation
JOIN content AS target
  ON target.id = relation.target_content_id
WHERE relation.source_content_id = ?
  AND relation.type IN ('reply_to', 'quote_of', 'repost_of');

12. 当前实现边界 Copy Chapter

已经完整打通：

• 视频多分辨率。
• 没有分辨率信息的短视频。
• 多语言字幕及多种字幕格式。
• 小说卷和章节。
• 小说章节到下载资源的直接关联。
• 图集图片和 Live Photo。
• 图集图片到下载资源的直接关联。
• 内容根资产。
• 旧数据迁移、关联回填和回滚。
• AI 对话、消息父子树和分支。
• AI 消息内容块、附件和生成文件到下载资源的直接关联。
• 当前或指定对话分支的根到叶查询。

AI 对话当前能力边界：

AI 对话表已合并在 000002_content_media_asset 迁移中。ChatGPT、豆包等平台的原始格式解析仍需要各自的导入适配器；在没有脱敏样本时，不应猜测不稳定的私有接口字段。

漫画页、课程课时、播客单集的 subject_type 和通用关联机制已经预留，但对应的章节、页面、课时子表还需要在具体平台接入时继续完善。后续扩展可以复用现有 ContentAsset、ContentAssetLink 和 DownloadResourceAsset，不需要重新设计下载关联结构。

13. 相关代码 Copy Chapter

• internal/database/model/content.go：内容主体、类型扩展、视频、字幕、小说和图集模型。
• internal/database/model/content_media.go：内容类型、通用资产、嵌套实体关联和内容关系。
• internal/database/model/content_conversation.go：AI 对话、分支、消息树和有序内容块。
• internal/database/model/download_task.go：下载资源及资产关联。
• internal/services/download_task.go：内容扩展保存、资产创建和下载资源关联。
• internal/services/content.go：内容详情、章节/图片/AI 消息资产装配，以及 AI 对话分支查询。
• internal/database/migrations/000002_content_media_asset.up.sql：通用内容资产结构、旧数据回填、小说章节扩展及外部 AI 对话归档表迁移。

Linux Certificate Installation (`docs/linux-certificate-installation.md`) Copy Section

Linux Certificate Installation Guide

This document describes the permissions and installation steps required to install a trusted CA certificate on common Linux distributions.

Summary Copy Chapter

Installing a certificate into the system trust store usually requires root or sudo.

The installer must write to system-owned directories such as /usr/local/share/ca-certificates, /etc/pki/ca-trust/source/anchors, or /etc/ca-certificates/trust-source/anchors, then refresh the distribution's generated CA bundle.

Browser-specific stores, Java stores, containers, Flatpak apps, and Snap apps may require additional handling.

Certificate Format Copy Chapter

The certificate should be a CA certificate in PEM format:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Some tools accept DER input, but system CA installation is most reliable when the certificate is written as PEM. Debian-style update-ca-certificates expects local certificates under /usr/local/share/ca-certificates to use a .crt suffix.

Distribution Matrix Copy Chapter

Debian, Ubuntu, Linux Mint Copy Chapter

Install:

sudo install -m 0644 cert.crt /usr/local/share/ca-certificates/<name>.crt
sudo update-ca-certificates

Uninstall:

sudo rm /usr/local/share/ca-certificates/<name>.crt
sudo update-ca-certificates

Alpine Copy Chapter

Install:

sudo install -m 0644 cert.crt /usr/local/share/ca-certificates/<name>.crt
sudo update-ca-certificates

If ca-certificates is not installed:

sudo apk add ca-certificates

Uninstall:

sudo rm /usr/local/share/ca-certificates/<name>.crt
sudo update-ca-certificates

RHEL, CentOS, Rocky Linux, AlmaLinux, Fedora Copy Chapter

Install:

sudo install -m 0644 cert.crt /etc/pki/ca-trust/source/anchors/<name>.crt
sudo update-ca-trust extract

Uninstall:

sudo rm /etc/pki/ca-trust/source/anchors/<name>.crt
sudo update-ca-trust extract

Arch, Manjaro Copy Chapter

Install:

sudo install -m 0644 cert.crt /etc/ca-certificates/trust-source/anchors/<name>.crt
sudo trust extract-compat

Alternative:

sudo trust anchor --store cert.crt
sudo trust extract-compat

Uninstall:

sudo rm /etc/ca-certificates/trust-source/anchors/<name>.crt
sudo trust extract-compat

openSUSE, SLES Copy Chapter

Install:

sudo install -m 0644 cert.pem /usr/share/pki/trust/anchors/<name>.pem
sudo update-ca-certificates

Uninstall:

sudo rm /usr/share/pki/trust/anchors/<name>.pem
sudo update-ca-certificates

NSS Stores for Desktop Browsers Copy Chapter

System trust store installation does not always cover every browser.

NSS databases are used by Firefox and some Chromium builds. User NSS databases usually do not require root, but if the program was elevated with sudo, it must write to the original user's home directory, not root's home directory.

Common NSS paths:

/etc/pki/nssdb
$HOME/.pki/nssdb
$HOME/.mozilla/firefox/<profile>

Install:

certutil -d sql:$HOME/.pki/nssdb -A -n "<name>" -t "CT,C,C" -i cert.crt

Firefox profile example:

certutil -d sql:$HOME/.mozilla/firefox/<profile> -A -n "<name>" -t "CT,C,C" -i cert.crt

Uninstall:

certutil -d sql:$HOME/.pki/nssdb -D -n "<name>"
certutil -d sql:$HOME/.mozilla/firefox/<profile> -D -n "<name>"

If the NSS database does not exist:

mkdir -p "$HOME/.pki/nssdb"
certutil -d sql:$HOME/.pki/nssdb -N --empty-password

Java Trust Store Copy Chapter

Java applications may use their own trust store instead of the system store.

Install:

sudo keytool -importcert \
  -alias "<name>" \
  -file cert.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts"

The common default password is changeit, but it can be different.

Uninstall:

sudo keytool -delete \
  -alias "<name>" \
  -keystore "$JAVA_HOME/lib/security/cacerts"

Containers Copy Chapter

Certificates installed on the host are not automatically trusted inside containers. Install the certificate inside the image or container.

Debian, Ubuntu, Alpine:

COPY cert.crt /usr/local/share/ca-certificates/<name>.crt
RUN update-ca-certificates

RHEL, CentOS, Fedora:

COPY cert.crt /etc/pki/ca-trust/source/anchors/<name>.crt
RUN update-ca-trust extract

The Docker build stage usually runs as root, so these commands can write to system trust directories.

Flatpak and Snap Copy Chapter

Flatpak and Snap applications can be isolated from the host system trust store. Some apps use bundled runtimes or sandbox-specific certificate configuration.

When a system CA install does not affect a sandboxed app, check the app's runtime documentation and whether the certificate must be added inside the sandbox or application-specific store.

Implementation Notes Copy Chapter

For programmatic installation:

• Keep root checks for system trust store installation.
• Use the externally supplied certificate name as the single source of truth.
• Derive only the filesystem-safe certificate file name from that external name.
• Use the original external name as the NSS nickname.
• Do not hardcode certificate names such as SunnyNet or WeChatAppEx_CA.
• In sudo flows, use SUDO_USER or PKEXEC_UID to find the invoking desktop user's home directory.
• If writing a user NSS database while running as root, restore ownership to the original user.
• Treat system trust store refresh failure as a hard error.
• Treat NSS browser store failure as a warning when the target machine may be a server without desktop components.

Package.Json (`docs/package.json`) Copy Section

{
"name": "wx_channels_download-docs",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "vitepress dev",
"build": "vitepress build",
"preview": "vitepress preview",
"prepare": "git config core.hooksPath docs/.husky"
},
"devDependencies": {
"@types/node": "^24.10.1",
"husky": "^9.1.7",
"vitepress": "^1.0.0"
},
"dependencies": {
"@scalar/api-reference": "^1.43.1"
}
}

Releases (`docs/releases.md`) Copy Section

title: Releases Copy Chapter

Releases

最新发布页：https://github.com/ltaoo/wx_channels_download/releases

v251122 Copy Chapter

• 支持通过 config.yaml 配置默认是否下载原始视频
• 新增代理配置项，可指定是否设置系统代理
• 支持自动检测并按需申请管理员权限

示例配置：

download:
  defaultHighest: false

proxy:
  system: true
  port: 2023

如需默认下载原始视频，将压缩包内 config.yaml 的 defaultHighest 改为 true 后重启下载器。

如需配合 Clash 使用，可将 system 改为 false，并在 Clash 配置中添加 Global Extend Script，转发到下载器的代理服务。

v251027 Copy Chapter

• 内置 echo 以替代 SunnyNet，二进制体积缩减到约 8M
• download 命令默认启用多线程
• 在直播详情页增加下载按钮，并在终端打印下载命令（ffmpeg）
• Windows 平台通过设置系统代理注入下载按钮，科学上网可能失效

提示：使用终端下载方式需要安装 ffmpeg。

v250913 Copy Chapter

• 视频号首页视频操作栏增加「下载」按钮
• 增加 uninstall 命令，可卸载根证书
• 增加 decrypt 命令，支持使用指定 key 对已下载视频解密

典型命令：

wx_video_download_xx uninstall
wx_video_download_xx decrypt --filepath <绝对路径> --key <解密key>

v250621 Copy Chapter

• 新增 download 命令，将视频下载到 Downloads 并解密
• 视频号「更多」菜单新增「打印下载命令」按钮
• Windows 平台双击以管理员身份运行，二进制文件增加图标

示例：

./wx_video_download_xx download --url "视频地址" --key 解密key --filename "文件名"

Cli Deploy (`docs/cli/deploy.md`) Copy Section

title: 部署命令 Copy Chapter

deploy

部署 Cloudflare Worker。该命令是父命令，需要指定二级命令。

用法 Copy Chapter

wx_video_download deploy <command>

前置条件 Copy Chapter

• 拥有 Cloudflare 账号，并获取 Account ID 和 API Token。
• API Token 需要有 Workers 相关的读写权限。
• 部署公众号 Worker 时，还需要 D1 相关权限。

二级命令 Copy Chapter

通用配置 Copy Chapter

cloudflare:
  accountId: "your-cloudflare-account-id"
  apiToken: "your-cloudflare-api-token"

deploy bridge Copy Chapter

一次部署用于桥接/转发远程调用的 Durable Objects Bridge Worker 和受密码保护的 Pages 管理页面。

部署完成后的设备注册、调用 Token 创建、API 协议和多语言示例请参阅 Bridge 使用。

wx_video_download deploy bridge

配置 Copy Section

cloudflare:
  accountId: "your-cloudflare-account-id"
  apiToken: "your-cloudflare-api-token"

bridge:
  deploy:
    workerName: "dm-bridge"
    pagesProjectName: "" # 留空时使用 dm-bridge-admin
    token: "bridge-client-token"
    adminToken: "bridge-admin-token"

API Token 需要 Workers Scripts:Edit 和 Pages:Edit 权限。token 与 adminToken 必须使用不同的高强度随机值。

部署命令会依次执行：

1. 上传 Worker，并配置 Durable Objects、BRIDGE_TOKEN 和 BRIDGE_ADMIN_TOKEN；
2. 创建或更新 Pages 项目；
3. 为 Pages 配置 BRIDGE_ADMIN_TOKEN Secret 和指向 Worker 的 BRIDGE Service Binding；
4. 上传管理页面静态资源和高级模式 Worker。

任一步骤失败都会停止后续部署；如果 Pages 阶段失败，命令会明确提示 Worker 已经部署成功，不会回滚 Worker。

deploy mp Copy Chapter

部署公众号 RSS/API 相关的 Cloudflare Worker。

wx_video_download deploy mp

配置 Copy Section

cloudflare:
  accountId: "your-cloudflare-account-id"
  apiToken: "your-cloudflare-api-token"
  workerName: "mp-rss-api"
  d1Name: "mp-rss-db"
  refreshToken: "refresh-token"
  adminToken: "admin-token"

mp:
  remoteServer:
    hostname: "your-remote-server-hostname"

部署内容 Copy Section

• 部署嵌入 internal/workers/mp/index.js 的 Worker。
• 执行嵌入 internal/workers/mp/migrations/ 的 D1 迁移。
• 注入 D1 绑定 DB，以及 ADMIN_TOKEN、REFRESH_TOKEN、REMOTE_SERVER 环境变量。

可用 API Copy Section

deploy sph Copy Chapter

部署视频号视频信息查询页面到 Cloudflare Worker，提供 Web 界面查询视频号视频下载地址。

!!不要提供给外部使用，仅自己使用即可，有被限制使用 yuanbao 的风险!!

wx_video_download deploy sph

配置 Copy Section

在配置文件中添加或修改以下字段：

cloudflare:
  accountId: "your-cloudflare-account-id"
  apiToken: "your-cloudflare-api-token"
  sphWorkerName: "worker-name"
  sphCookie: "元宝 web 端 cookie"
  sphCredential: "页面及 API 的访问凭证"

元宝 Web 端指 https://yuanbao.tencent.com/ 网站，登录后获取 cookie 作为配置即可。
元宝 Web 端 Cookie 有效期约 1 个月，失效后重新登录获取新的 Cookie，并到 Cloudflare Worker 更新 COOKIE 环境变量即可。

!!不要提供给外部使用，仅自己使用即可，有被限制使用 yuanbao 的风险!!

部署内容 Copy Section

• 部署嵌入 internal/workers/sph/worker.js 的 Worker。
• 同时上传嵌入的 internal/workers/sph/index.html 和 build/icon.png。
• Cookie 以 COOKIE 环境变量注入 Worker，用于调用视频号接口时的身份认证。
• 访问凭证以 ACCESS_CREDENTIAL 环境变量注入 Worker；未配置时部署命令会拒绝部署。

访问认证 Copy Section

浏览器访问 Worker 时会显示 HTTP Basic Auth 登录框。用户名固定为 wxchannels，密码填写 cloudflare.sphCredential。登录后，页面对同源 API 的请求会自动携带认证信息。

直接调用 API 时可使用 Bearer Token：

curl -H 'Authorization: Bearer <sphCredential>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://weixin.qq.com/sph/example"}' \
  'https://<worker-name>.<subdomain>.workers.dev/api/fetch_video_profile'

也可使用 Basic Auth：curl -u 'wxchannels:<sphCredential>' ...。

可用 API Copy Section

除 CORS 预检请求外，以上页面、静态资源和 API 均需认证。认证失败返回 401；Worker 未配置 ACCESS_CREDENTIAL 时返回 503。

Cli Mcp (`docs/cli/mcp.md`) Copy Section

title: MCP Server Copy Chapter

MCP Server

项目提供 Streamable HTTP 与 stdio 两种 MCP 接入方式，包含以下语义化 tools：

• get_config：获取应用配置 schema、当前值和解析后的生效值；敏感值不会返回明文。
• update_config：批量修改非只读配置，保存成功后安排应用优雅重启。
• get_restart_status：通过 update_config 返回的确认令牌验证新进程和新配置是否已经生效。
• deploy_sph_worker：读取 Cloudflare 配置，部署或覆盖视频号查询 Worker。
• get_platform_status：获取各平台当前可用状态。
• fetch_content：传入平台内容链接，等待解析完成并返回规范化内容。
• download_content：复用 fetch_content 的 job_id，或直接传入链接，创建并启动下载任务。
• decrypt_wxchannels_video：原地解密由 aria2 等第三方下载器保存的微信视频号视频。
• get_wxchannels_status：检查视频号页面是否已连接。
• search_wxchannels_accounts：搜索视频号账号。
• get_wxchannels_account_videos：获取账号发布的视频列表。
• get_wxchannels_live_replays：获取账号的直播回放。
• get_wxchannels_interacted_videos：获取当前用户赞过或收藏的视频。
• get_wxchannels_followed_accounts：获取当前用户关注的视频号账号。
• get_wxchannels_play_history：获取当前用户的视频号播放记录。
• get_wxchannels_video_profile：通过链接、oid/nid 或 eid 获取视频详情。
• get_wxchannels_video_comments：获取视频评论或根评论的回复。
• get_wxchannels_video_share_url：通过 oid 获取视频分享链接。
• get_download_tasks：分页获取下载任务和状态统计。
• get_download_task_detail：获取下载任务、文件和关联内容详情。
• delete_download_tasks：批量删除下载任务，可通过 delete_files 选择是否同时删除关联的本地文件。
• get_accounts：分页获取数据库中的平台账号。
• get_browse_history：分页获取浏览记录。
• get_logs：分页读取并筛选应用日志。
• get_certificate_status：获取代理根证书的安装及信任状态。

Streamable HTTP（推荐） Copy Chapter

启动下载器后，使用前端「设置 → MCP」页面显示的连接地址；默认地址为：

http://127.0.0.1:2022/mcp

设置页可立即启用或关闭 Streamable HTTP MCP。将 api.hostname 配置为局域网地址时，只应向可信网络开放。

Worker 部署 Copy Chapter

deploy_sph_worker 不接收 Cloudflare Token、Cookie 等敏感参数，而是读取应用配置中的 cloudflare.accountId、cloudflare.apiToken、cloudflare.sphWorkerName、cloudflare.sphCookie 和 cloudflare.sphCredential。它会部署或覆盖同名远端 Worker，调用前必须获得用户确认。get_config 可用时，可先用它检查这些字段的 configured 状态；敏感字段不会返回明文。

微信视频号工具 Copy Chapter

视频号工具通过已打开的视频号页面获取数据。使用前先确认下载器代理工作正常，并已有页面连接到 /ws/channels；可调用 get_wxchannels_status 检查，返回的 available 应为 true。

列表工具返回微信原始分页字段。继续翻页时，把上一页的 data.lastBuffer（账号搜索使用 data.lastBuff）原样传给下一次调用的 next_marker，不要自行解码或改写。

数据查询 Copy Chapter

所有数据查询工具均为只读。get_download_tasks 支持按状态、父任务和根任务筛选；get_accounts 支持账号 ID 和关键词；get_browse_history 支持平台、关联账号和关键词；get_logs 支持日志级别、来源和关键词。列表工具默认分页，并限制单页最大返回量。

stdio Copy Chapter

使用 stdio MCP 前先启动下载器：

wx_video_download server

再在 MCP 客户端中配置：

{
  "mcpServers": {
    "dm": {
      "command": "/absolute/path/to/wx_video_download",
      "args": ["mcp"]
    }
  }
}

默认 API 地址来自项目配置中的 api.protocol、api.hostname 和 api.port。也可显式指定：

{
  "mcpServers": {
    "dm": {
      "command": "/absolute/path/to/wx_video_download",
      "args": ["mcp", "--api-base-url", "http://127.0.0.1:2022"]
    }
  }
}

配置管理 Copy Chapter

修改配置前先调用 get_config 获取合法字段、字段类型和枚举选项。敏感字段只返回是否已配置，不返回明文。update_config 接收 values 对象，例如：

{
  "values": {
    "download.dir": "/data/downloads",
    "download.playDoneAudio": false
  }
}

未知字段、只读字段、类型不匹配或不在 options 中的值会被拒绝。值发生变化后应用会优雅重启，MCP 连接可能短暂中断。修改 api.hostname 或 api.port 后，应使用新地址连接；stdio 客户端需要同步更新 API 地址或重新启动。相同值不会触发重启。

update_config 返回 restart_scheduled: true 时只表示已安排重启。调用方必须保留 restart_token，连接恢复后调用 get_restart_status。只有返回 status: "completed"、restart_completed: true、config_applied: true 时，才表示新进程已经启动并加载了保存后的配置；在此之前不应向用户声称重启完成。

下载行为 Copy Chapter

fetch_content 成功后会返回 job_id，将它原样传给 download_content：

{
  "job_id": "fetch-...",
  "wait_for_completion": true
}

download_content 默认在任务创建并启动后返回；需要等待文件实际下载完成时，传入 wait_for_completion: true。重复任务默认报错，可通过 existing_action 选择 skip、overwrite 或 duplicate。其中 overwrite 会覆盖已有任务和文件。

微信视频号外部下载与解密 Copy Chapter

微信视频号的 fetch_content 结果会额外返回 download_resources。每项包含适合交给 aria2、curl 等第三方下载器使用的信息：

{
  "resource": {
    "name": "视频名称",
    "kind": "video/mp4",
    "extra": "{\"decode_key\":\"123456789\"}"
  },
  "endpoints": [
    {
      "protocol": "https",
      "url": "https://example/video.mp4",
      "enabled": 1
    }
  ],
  "download_url": "https://example/video.mp4",
  "decode_key": "123456789",
  "requires_decryption": true
}

将 download_url 交给外部下载器，例如：

aria2c --out video.mp4 "<download_url>"

外部下载必须已经完成，并且文件必须位于运行下载器服务的同一台机器上。如果 requires_decryption 为 true，把绝对路径与返回的字符串形式 decode_key 传给：

{
  "name": "decrypt_wxchannels_video",
  "arguments": {
    "file_path": "/absolute/path/to/video.mp4",
    "key": "123456789"
  }
}

解密会原地覆盖该文件，不能对同一文件重复调用。如果 requires_decryption 为 false，下载结果已经可以直接使用，不要调用解密工具。

Cli Proxy (`docs/cli/proxy.md`) Copy Section

title: 启动代理服务命令 Copy Chapter

启动代理服务

核心功能，启动一个代理服务，拦截并修改视频号网络请求，达到插入下载按钮的目的

用法 Copy Chapter

wx_video_download --hostname 127.0.0.1 --port 2023 --debug

• --hostname 代理服务器主机名（默认 127.0.0.1）
• --port 代理服务器端口（默认 2023）
• --debug 是否开启调试输出

运行时会打印版本与问题反馈链接，并根据是否设置系统代理给出引导。

Cli Server (`docs/cli/server.md`) Copy Section

title: 服务器模式 Copy Chapter

服务器模式

用于在 linux 服务器上运行，提供 API 服务

用法 Copy Chapter

wx_video_download server

服务以前台方式运行，终端退出后服务也会关闭。

查看服务状态 Copy Section

wx_video_download server status

停止服务 Copy Section

wx_video_download server stop

也可以在运行服务的终端按 Ctrl+C。

重启服务 Copy Section

wx_video_download server restart

Cli Uninstall (`docs/cli/uninstall.md`) Copy Section

title: 卸载根证书命令 Copy Chapter

卸载根证书

下载器首次使用时会自动安装根证书，该命令可以卸载掉安装的根证书

用法 Copy Chapter

wx_video_download uninstall

说明 Copy Chapter

• 卸载后，再次使用下载器，会重新安装证书

Cli Update (`docs/cli/update.md`) Copy Section

title: 更新命令 Copy Chapter

更新

用于检查是否有新版本，并下载更新到最新版本。

用法 Copy Chapter

wx_video_download update

说明 Copy Chapter

• 程序会自动从 GitHub Releases 拉取最新版本信息，并与当前版本进行比较。
• 如果当前已是最新版本，会直接提示并退出。
• 如果发现新版本，会展示版本号、发布时间和发布说明，确认后开始下载更新。
• 下载完成后会自动替换当前程序文件，更新即刻生效。

Cli Version (`docs/cli/version.md`) Copy Section

title: 查看版本 Copy Chapter

查看版本

用于查看当前下载器的版本号

用法 Copy Chapter

wx_video_download version

Config Api (`docs/config/api.md`) Copy Section

title: API 服务 Copy Chapter

API 服务

现在启动后默认会开启 API 服务，下载器默认会通过 API 服务提交下载任务，由 API 服务在后台进行下载。通过 config.yaml 可以配置服务地址。

api:
  protocol: http
  hostname: 127.0.0.1
  port: 2022

• protocol API 服务协议，默认 http
• hostname API 服务监听地址。设为 0.0.0.0 时监听所有 IPv4 接口；本机前端和其他本机客户端仍通过 127.0.0.1 连接
• port API 服务端口

Config Cert (`docs/config/cert.md`) Copy Section

title: 自定义根证书 Copy Chapter

自定义根证书

用于配置自定义证书与私钥。当证书和私钥文件均已配置且可读时，程序会优先使用自定义证书。

配置键 Copy Chapter

示例（config.yaml） Copy Chapter

cert:
  file: "C:/path/to/mycert.pem"
  key: "C:/path/to/mykey.pem"
  name: "MyProxyCA"

生效规则 Copy Chapter

• cert.file 和 cert.key 必须同时配置，并且两个文件都可读，才会使用自定义证书。
• 未配置 cert.name 时使用默认值 Echo。
• 自定义证书不可用时，程序会尝试使用本机已有的 mitmproxy 证书；仍不可用时使用内置 SunnyNet 证书。
• cert.file 和 cert.key 应填写绝对路径。

注意事项 Copy Chapter

• 证书与私钥必须属于同一密钥对。
• cert.name 应与证书的通用名称（CN）一致，否则可能无法正确检测或卸载已安装的证书。
• Windows 安装或卸载证书需要管理员权限，具体操作参考手动安装根证书。

Config Cloudflare (`docs/config/cloudflare.md`) Copy Section

title: Cloudflare 配置 Copy Chapter

Cloudflare 配置

用于配置 Cloudflare Worker 相关的参数，主要用于公众号 RSS 服务。

cloudflare:
  accountId: ""
  apiToken: ""
  refreshToken: ""
  adminToken: ""
  workerName: "official-account-api"
  d1Name: ""

• accountId: Cloudflare 帐号 ID。
• apiToken: Cloudflare Worker 认证 Token。
• refreshToken: 调用 mp-rss 凭证刷新接口所需的 token。
• adminToken: 调用 mp-rss 管理员接口所需的凭证。
• workerName: Cloudflare mp-rss Worker 名称，默认 official-account-api。
• d1Name: Cloudflare mp-rss D1 数据库名称。

Config Debug (`docs/config/debug.md`) Copy Section

title: 调试 Copy Chapter

调试

用于开发和调试的配置项。

错误捕获 Copy Chapter

debug:
  error: true
  echolog: false

是否全局捕获前端错误，出现错误时弹窗展示错误信息。默认 true。

echolog 控制 Echo 代理日志，默认 false。设置为 true 时启用 Echo 日志。

Config Download (`docs/config/download.md`) Copy Section

title: 下载配置 Copy Chapter

下载配置

通过 config.yaml 控制下载行为。

视频号专属的下载行为，请参考视频号配置。

下载时的文件名称 Copy Chapter

download:
  filenameTemplate: "{{filename}}_{{spec}}"

下载时的文件名称，默认「文件名_视频质量」。.mp4 后缀由下载器添加，不支持手动设置后缀

目前支持如下变量

type params = {
  /** 默认文件名，优先取 title，没有则取视频 id，仍没有则使用 当前时间秒数 */
  filename: string,
  /** 视频 id */
  id: string,
  /** 视频标题 */
  title: string,
  /** 视频质量 original | 'xWT111' */
  spec: string,
  /** 视频发布时间（单位秒） */
  created_at: number,
  /** 视频下载时间（单位秒） */
  download_at: number,
  /** up主名称 */
  author: string,
};

如果存在 / 符号，例如 {{author}}/{{filename}}_{{spec}}，这样下载的文件会放在以作者名为目录的目录中，该能力仅在后台下载时生效

下载目录 Copy Chapter

download:
  dir: "%UserDownloads%"

下载文件存放的目录，默认为用户下载目录。可以修改为任意「绝对路径目录」。仅在后台下载时生效

完成音效 Copy Chapter

download:
  playDoneAudio: true

后台下载模式下，下载完成后是否播放完成音效，默认 true。

最大并发任务数 Copy Chapter

download:
  maxRunning: 3

同时运行的下载任务数量上限，默认 3。

Default action when a task exists Copy Chapter

download:
  defaultActionWhenExisting: ""

When creating a download task, an existing task normally returns a conflict so the caller can choose an action. Set this to skip, duplicate, or overwrite to skip the incoming task, create another copy, or overwrite the existing task.

远程服务 Copy Chapter

download:
  remoteServer:
    enabled: false
    protocol: "http"
    hostname: "192.168.1.118"
    port: 2022

是否启用远程服务下载，默认 false

Config Proxy (`docs/config/proxy.md`) Copy Section

title: 代理配置 Copy Chapter

代理配置

通过 config.yaml 控制是否设置系统代理与代理服务端口。

proxy:
  system: true
  hostname: 127.0.0.1
  port: 2023
  tun: false

• system 是否设置系统代理
• hostname 代理主机名
• port 代理端口
• tun 是否启用 TUN 模式

TUN 模式 Copy Chapter

TUN 模式在网络层截获流量，无需修改系统代理即可将目标域名的请求转发到代理服务。适用于不希望改动系统代理，或需要代理非 HTTP 流量的场景。

开启后会创建一个虚拟网卡，将匹配的流量路由到下载器代理进行处理。此时 system 设置将被忽略，不会修改系统代理。

注意：TUN 模式会修改系统路由表，与 VPN 类软件（Clash、Surge 等）同时使用时会产生路由冲突，导致部分网站访问缓慢。建议不要同时开启 TUN 模式和 VPN，或使用 Clash 的 Script 方式（见下方）替代 TUN 模式。

与 Clash 协同 Copy Chapter

当不希望修改系统代理时，可将 system 设为 false，并在 Clash 中加入以下 Global Extend Script，将流量转发到下载器代理服务（端口默认 2023）：

function main(config, profileName) {
  config["proxy-groups"].unshift({
    name: 'ChannelsDownload',
    type: 'fallback',
    proxies: ["channels_download", "DIRECT"],
    interval: 5
  });
  config["proxies"].unshift({
    name: "channels_download",
    type: 'http',
    server: '127.0.0.1',
    port: 2023,
  });
  config.rules.unshift(...[
    "PROCESS-NAME,wx_video_download.exe,DIRECT",
    "PROCESS-NAME,wx_video_download,DIRECT",
    "DOMAIN-SUFFIX,qq.com,ChannelsDownload"
  ]);
  return config;
}

Config Script (`docs/config/script.md`) Copy Section

title: 用户脚本 Copy Chapter

用户脚本

目前有两种方式在视频号页面注入额外的 js 脚本

全局脚本 Copy Chapter

在工作目录 workdir 下，如果存在 global.js，则会将其插入视频号页面。目前可以通过其指定下载时的文件名称。

也可以通过配置指定全局脚本路径；相对路径会按 workdir 解析：

inject:
  globalScript: "global.js"

脚本示例 Copy Section

// global.js
function beforeFilename(filename, params) {
  return filename;
}

Config Workdir (`docs/config/workdir.md`) Copy Section

title: 工作目录 Copy Chapter

工作目录

通过 workdir 可以把数据库和用户脚本集中放在单独目录中，避免在程序所在目录产生运行时文件。

默认配置为：

workdir: ""

默认值为 ""。未配置或留空时，使用下载器可执行文件所在目录。

如需使用单独的工作目录，可以配置为：

workdir: "./workdir"

• 可以使用绝对路径，也可以使用相对路径。
• 相对路径以 config.yaml 所在目录为基准。
• 目录不存在时，程序会在启动时自动创建。

配置后，与数据库和用户脚本相关的主要文件如下：

workdir/
├── data.db
├── global.js
└── hooks.js

• SQLite 数据库默认生成在 workdir/data.db。
• 全局用户脚本放在 workdir/global.js。
• 下载 Hook 脚本放在 workdir/hooks.js。

脚本文件不是必需的；只有需要自定义脚本功能时才需要创建。脚本的具体用法请参考用户脚本、下载任务 Hook和指定下载的文件名。

自定义文件名或路径 Copy Chapter

下面这些路径如果使用相对路径，也会以 workdir 为基准：

workdir: "./runtime"

inject:
  globalScript: "scripts/global.js"

download:
  hooksScript: "scripts/hooks.js"

db:
  filepath: "data-custom.db"

对应文件分别位于 runtime/scripts/global.js、runtime/scripts/hooks.js 和 runtime/data-custom.db。

迁移已有文件 Copy Chapter

设置 workdir 不会自动移动已有的数据库或脚本。如果项目目录中已有 data.db、global.js 或 hooks.js，请在程序停止后将它们移动到新的工作目录，再重新启动程序。数据库旁如果还有 data.db-wal 或 data.db-shm，也需要一起移动。

Faq Button Inject Failed (`docs/faq/button_inject_failed.md`) Copy Section

title: 没有下载按钮 Copy Chapter

没有下载按钮

排查步骤 Copy Chapter

• 确认下载器已启动
• 确认系统代理设置成功
• 若配置不使用系统代理，请使用 Clash 等软件，视频号请求转发到端口 127.0.0.1:2023
• 刷新页面或重新进入视频详情页
• 升级到最新版本后重试。

确认系统代理设置成功 Copy Chapter

如果打开视频号没有下载按钮请先检查系统代理是否如下所示

win 系统 Copy Section

macOS 系统 Copy Section

Faq Network Failed (`docs/faq/network_failed.md`) Copy Section

title: 网络无法访问 Copy Chapter

网络无法访问

常见原因 Copy Chapter

• 启动后设置了系统代理，影响其他代理软件或网络策略。

解决方案 Copy Chapter

取消系统代理即可

和 Clash 一起使用 Copy Chapter

如果使用了类似 Clash、Sing-box 等翻墙软件，可以在 config.yaml 设置 proxy.system=false，通过 Clash 将流量转发到下载器端口。

参考 代理配置

Faq Powershell (`docs/faq/powershell.md`) Copy Section

title: PowerShell Copy Chapter

PowerShell

exec:"powershell.exe":executable file not found in %PATH%。

参考 https://github.com/ltaoo/wx_channels_download/issues/42

Faq Windows Service Timeout (`docs/faq/windows_service_timeout.md`) Copy Section

title: Windows 服务无法访问 Copy Chapter

Windows 服务无法访问

问题描述 Copy Chapter

Windows 电脑可以启动程序，但通过浏览器访问 http://127.0.0.1:2023 或 http://127.0.0.1:2022 时超时无响应。

快速诊断 Copy Chapter

如果你看到 netstat 输出中有 SYN_SENT 状态的连接：

TCP 127.0.0.1:8115 127.0.0.1:2023 SYN_SENT 15616

这个输出的含义：

• 127.0.0.1:8115 - 客户端地址和临时端口（源）
• 127.0.0.1:2023 - 服务端地址和端口（目标）
• SYN_SENT - TCP 连接状态（正在尝试建立连接）
• 15616 - 客户端进程 PID

其中 8115 是操作系统自动分配的临时端口，用于标识这个连接。你可以通过以下命令查看是哪个程序在尝试连接：

tasklist | findstr "15616"

问题诊断：

SYN_SENT 状态说明服务正常运行，但连接被阻止了。客户端发送了 SYN 包，但没有收到服务端的 SYN-ACK 响应。

最可能的原因是：

1. Windows 防火墙阻止（最常见）
2. 安全软件拦截（360、腾讯管家等）
3. 网络驱动异常

立即尝试： 临时关闭 Windows 防火墙和安全软件测试。

排查步骤 Copy Chapter

1. 确认服务已启动 Copy Section

启动程序后，查看控制台输出是否显示：

• API服务启动成功, 地址: 127.0.0.1:2022
• 代理服务启动成功

2. 检查端口占用 Copy Section

打开 PowerShell 或命令提示符，执行：

netstat -ano | findstr "2023"
netstat -ano | findstr "2022"

应该能看到类似输出：

TCP    127.0.0.1:2023         0.0.0.0:0              LISTENING       12345
TCP    127.0.0.1:2022         0.0.0.0:0              LISTENING       12345

如果没有输出，说明服务未正常监听。

3. 测试本地连接 Copy Section

使用 curl 或 PowerShell 测试：

curl http://127.0.0.1:2022/health

或

Invoke-WebRequest -Uri http://127.0.0.1:2022/health

如果返回错误，继续下一步排查。

4. 检查 Windows 防火墙（重点） Copy Section

这是最常见的原因！ 即使是本地回环地址 127.0.0.1，Windows 防火墙也可能阻止连接。

如果 netstat 显示连接状态为 SYN_SENT，说明防火墙正在阻止连接。

解决方案 A：临时关闭防火墙测试

1. 打开"Windows 安全中心"
2. 点击"防火墙和网络保护"
3. 临时关闭"专用网络"和"公用网络"防火墙
4. 重新测试访问

如果关闭防火墙后可以访问，说明确实是防火墙问题。

解决方案 B：添加防火墙规则（推荐）

以管理员身份运行 PowerShell 或命令提示符，执行：

netsh advfirewall firewall add rule name="wx_video_download_api" dir=in action=allow protocol=TCP localport=2022
netsh advfirewall firewall add rule name="wx_video_download_proxy" dir=in action=allow protocol=TCP localport=2023

解决方案 C：允许程序通过防火墙

1. 打开"Windows 安全中心" → "防火墙和网络保护"
2. 点击"允许应用通过防火墙"
3. 点击"更改设置" → "允许其他应用"
4. 浏览并选择 wx_video_download.exe
5. 确保"专用"和"公用"都勾选
6. 点击"添加"

解决方案 D：使用 Windows Defender 防火墙高级设置

1. 按 Win + R，输入 wf.msc，回车
2. 点击左侧"入站规则"
3. 点击右侧"新建规则"
4. 选择"程序" → 下一步
5. 浏览选择 wx_video_download.exe → 下一步
6. 选择"允许连接" → 下一步
7. 全部勾选（域、专用、公用）→ 下一步
8. 输入名称"wx_video_download" → 完成

5. 检查 IPv4/IPv6 配置 Copy Section

某些系统可能存在 IPv4/IPv6 配置问题。尝试使用不同的地址访问：

• http://127.0.0.1:2022 (IPv4)
• http://[::1]:2022 (IPv6)
• http://localhost:2022 (系统解析)

6. 检查代理设置 Copy Section

如果系统设置了其他代理，可能导致访问本地服务时出现问题。

临时禁用系统代理：

1. 打开"设置" → "网络和 Internet" → "代理"
2. 关闭"使用代理服务器"
3. 重新测试

7. 检查安全软件（重点） Copy Section

360、腾讯电脑管家、火绒等安全软件可能拦截本地网络连接。

如果你安装了以下软件，它们可能是问题根源：

• 360 安全卫士 / 360 杀毒
• 腾讯电脑管家
• 火绒安全软件
• 金山毒霸
• 瑞星杀毒
• McAfee、Norton 等国外杀毒软件

解决方案 A：添加到信任列表

以 360 为例：

1. 打开 360 安全卫士
2. 点击"木马防火墙"或"防护中心"
3. 找到"信任与阻止"或"白名单"
4. 添加 wx_video_download.exe 到信任列表

以腾讯电脑管家为例：

1. 打开腾讯电脑管家
2. 点击"病毒查杀" → "信任区"
3. 添加 wx_video_download.exe

解决方案 B：临时关闭测试

临时退出或关闭安全软件，重新测试访问。如果可以访问，说明确实是安全软件问题。

解决方案 C：关闭网络防护功能

某些安全软件有"网络防护"或"流量监控"功能，可能拦截本地连接：

• 360：关闭"网络防护"
• 腾讯管家：关闭"网络防护"
• 火绒：关闭"网络防护"

8. 使用诊断工具 Copy Section

使用 telnet 测试端口连通性：

# 如果没有 telnet，先启用
dism /online /Enable-Feature /FeatureName:TelnetClient

# 测试连接
telnet 127.0.0.1 2022
telnet 127.0.0.1 2023

如果连接成功，会显示空白屏幕（按 Ctrl+] 然后输入 quit 退出）。

常见解决方案 Copy Chapter

方案 1：以管理员身份运行（推荐） Copy Section

右键点击 wx_video_download.exe，选择"以管理员身份运行"。

管理员权限可以避免某些防火墙和安全软件的拦截。

方案 2：添加防火墙规则（推荐） Copy Section

如果确认是防火墙问题，添加规则后就可以正常使用：

# 以管理员身份运行
netsh advfirewall firewall add rule name="wx_video_download_api" dir=in action=allow protocol=TCP localport=2022
netsh advfirewall firewall add rule name="wx_video_download_proxy" dir=in action=allow protocol=TCP localport=2023

方案 3：将程序添加到安全软件白名单 Copy Section

如果使用了 360、腾讯管家等安全软件，将 wx_video_download.exe 添加到信任列表。

方案 4：修改监听地址（不推荐，仅测试用） Copy Section

编辑 config.yaml，尝试修改监听地址：

api:
  hostname: "0.0.0.0"  # 监听所有网络接口
  port: 2022

proxy:
  hostname: "0.0.0.0"
  port: 2023

注意： 这会让服务在所有网络接口上监听，局域网内其他设备也能访问，存在安全风险。仅用于测试排查。

方案 5：更换端口 Copy Section

如果特定端口被限制，尝试更换端口：

api:
  hostname: "127.0.0.1"
  port: 8022  # 更换为其他端口

proxy:
  hostname: "127.0.0.1"
  port: 8023

方案 6：检查 hosts 文件 Copy Section

确认 C:\Windows\System32\drivers\etc\hosts 文件中 127.0.0.1 的配置正确：

127.0.0.1       localhost

方案 7：重置网络栈（高级） Copy Section

如果网络栈出现异常，可以尝试重置。以管理员身份运行：

netsh winsock reset
netsh int ip reset
ipconfig /flushdns

执行后需要重启电脑。

仍然无法解决？ Copy Chapter

如果以上方法都无效，请提供以下信息到 GitHub Issues：

1. Windows 版本（运行 winver 查看）
2. 程序启动时的完整控制台输出
3. netstat -ano | findstr "2022" 和 netstat -ano | findstr "2023" 的输出
4. 是否安装了安全软件或防火墙
5. config.yaml 的配置内容

Feature Api (`docs/feature/api.md`) Copy Section

layout: page title: API Reference Copy Chapter

Feature Bridge (`docs/feature/bridge.md`) Copy Section

title: Bridge 使用 Copy Chapter

Bridge 使用

Bridge 是可以将本机获取视频号数据能力暴露到公网的服务。外部程序只需要提交 method + args 接口请求，Bridge 就会把调用转发给能够执行该方法的在线设备；也可以通过 target_device_id 指定设备。

设备是指可以打开微信视频号的电脑如 Windows、macOS

外部程序 ── HTTPS ── Bridge Worker ── WebSocket ── 设备
             │
             └── 调用 Token 鉴权、任务持久化、设备选择与结果查询

Bridge 提供两种调用方式：/v1/invoke 会等待最多 10 秒并直接返回方法结果，适合快速调用；/v1/call 会立即返回持久任务，适合耗时操作、可靠重试和后台处理。

使用前准备 Copy Chapter

1. 部署 Bridge Copy Section

按照 deploy bridge 部署 Cloudflare Worker 和 Pages 管理页面。本文使用下面的 Worker 地址作为示例：

https://dm-bridge.litao.workers.dev

2. 注册执行设备 Copy Section

需要提供能力的每台设备分别配置并运行 wx_channels_download：

bridge:
  enabled: true
  url: "https://dm-bridge.example.workers.dev"
  deviceId: "my-macbook"
  deviceName: "My MacBook"
  token: "<BRIDGE_TOKEN>"
  httpTimeoutSeconds: 30
  methods: "auto"

• deviceId 是当前 Bridge 内稳定且唯一的设备标识。
• token 是部署时设置的设备 Secret，只用于设备连接，不应提供给外部调用者。
• methods: "auto" 注册当前设备支持的全部方法；也可以使用逗号分隔的方法白名单。
• 视频号方法需要设备上的视频号页面已经连接；仅显示设备在线不代表视频号页面一定可用。

3. 创建调用 Token Copy Section

打开 Pages 管理页面，点击右上角的“调用 Token”进入抽屉，然后创建调用 Token：

• Token 留空时由 Bridge 自动生成，也可以手动指定 16–256 位 Token。
• 用途或使用人可选填。
• 可以设置初始积分以及 1、7、30、90 天或永不过期；之后可由管理员继续充值。
• Token 明文只显示一次，请立即保存。

本文示例通过环境变量读取地址和 Token：

export BRIDGE_URL="https://dm-bridge.litao.workers.dev"
export BRIDGE_CALL_TOKEN="bridge_call_xxx"

::: warning 三类凭证不要混用

• 调用 Token：供外部程序访问 /v1/*，本文所有示例都使用它。
• 设备 Secret：配置项 bridge.token，只供设备连接 Bridge。
• 管理员 Token：配置项 bridge.deploy.adminToken，只供管理页面和管理 API 使用。

:::

API 概览 Copy Chapter

除健康检查外，请求都使用 Bearer 鉴权：

Authorization: Bearer <CALL_TOKEN>

每个调用 Token 都对应独立的发布方身份。一个 Token 不能读取另一个 Token 或设备创建的任务；尝试查询其他发布方的任务时返回 404。

积分与计费 Copy Chapter

Bridge 按请求计费：调用 Token 每成功创建一个 /v1/invoke 或 /v1/call 任务消耗 1 积分，状态查询、任务轮询和 Bridge 状态查询免费。余额不足时调用接口返回 402 Payment Required：

{
  "error": "insufficient credits",
  "required": 1,
  "balance": 0
}

扣费与任务创建在同一个事务内完成，不会因并发请求产生负余额。参数校验失败不扣费；异步调用用同一个非空 idempotency_key 重放时返回原任务且不再次扣费。任务创建后，即使设备执行失败、租约重试或同步调用等待超时也不会退分，因为 Bridge 已经受理并调度了请求。

查询当前 Token 的余额：

curl -sS \
  -H "Authorization: Bearer $BRIDGE_CALL_TOKEN" \
  "$BRIDGE_URL/v1/credits"

{
  "credits": {
    "balance": 998,
    "total_granted": 1000,
    "total_used": 2,
    "default_call_cost": 1
  }
}

调用响应同时包含 X-Bridge-Credit-Balance header；异步创建响应的 credits.charged 和 credits.balance 会给出本次扣费及剩余积分。

::: warning 旧 Token 升级

从没有积分体系的 Bridge 版本升级时，已有调用 Token 会保留但余额初始化为 0。请先在管理页充值，否则新的调用请求会返回 402。

:::

查询 Bridge 状态 Copy Chapter

curl -sS \
  -H "Authorization: Bearer $BRIDGE_CALL_TOKEN" \
  "$BRIDGE_URL/v1"

返回示例：

{
  "devices": [
    {
      "device_id": "my-macbook",
      "device_name": "My MacBook",
      "device_os": "darwin",
      "methods": [
        "wxchannels.contact.feed.list",
        "wxchannels.feed.profile"
      ],
      "status": "online"
    }
  ],
  "methods": [
    "wxchannels.contact.feed.list",
    "wxchannels.feed.profile"
  ],
  "task_counts": []
}

methods 是当前至少有一台在线设备能够执行的方法合集。设备状态可能为 online、busy 或 offline。

同步调用 Copy Chapter

POST /v1/invoke 是日常调用推荐使用的便捷接口。请求只需要提供 method、args，以及可选的 target_device_id；不需要传 idempotency_key，也不需要自行查询任务状态。

下面的请求调用设备上的 FetchChannelsFeedListOfContact：

curl -sS \
  -X POST \
  -H "Authorization: Bearer $BRIDGE_CALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "wxchannels.contact.feed.list",
    "args": {
      "username": "example@finder",
      "next_marker": ""
    }
  }' \
  "$BRIDGE_URL/v1/invoke"

请求字段：

任务在 10 秒内完成时返回 200，响应体就是设备方法返回的 JSON 结果，不包含 task、任务 ID 或其他任务信息。设备执行失败时返回 502；10 秒内没有完成时返回 504：

{
  "error": "invoke timed out after 10 seconds"
}

/v1/invoke 仍会在 Bridge 内创建持久任务。HTTP 超时不会取消已经创建或正在执行的任务，该任务可能在响应超时后继续完成。由于响应不提供任务 ID，而且该接口不使用幂等键，不要直接重试可能产生副作用的调用；这类调用应使用 /v1/call。

创建异步调用 Copy Chapter

下面的请求调用设备上的 FetchChannelsFeedListOfContact：

curl -sS \
  -X POST \
  -H "Authorization: Bearer $BRIDGE_CALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "wxchannels.contact.feed.list",
    "args": {
      "username": "example@finder",
      "next_marker": ""
    },
    "idempotency_key": "feed-list-example-001"
  }' \
  "$BRIDGE_URL/v1/call"

请求字段：

新任务通常返回 201：

{
  "task": {
    "id": "7e793f36-87e0-4ae2-b899-3d57decd95de",
    "method": "wxchannels.contact.feed.list",
    "publisher_device_id": "caller:4ef4d8a0-...",
    "target_device_id": null,
    "idempotency_key": "feed-list-example-001",
    "args": {
      "username": "example@finder",
      "next_marker": ""
    },
    "status": "queued",
    "assigned_device_id": null,
    "attempt_count": 0,
    "result": null,
    "error": null,
    "created_at": 1787200000000,
    "updated_at": 1787200000000,
    "completed_at": null
  }
}

在同一个调用 Token 下重复提交相同的非空 idempotency_key，Bridge 不会创建新任务，而是返回原任务和 "idempotent_replay": true。幂等键不按 method 分组，因此同一 Token 的所有调用都应使用不同的业务键。

指定执行设备 Copy Section

默认建议省略 target_device_id，让调用方只依赖 Bridge 方法，不依赖内部设备。如果业务必须固定到某台设备，可以指定：

{
  "method": "wxchannels.contact.feed.list",
  "target_device_id": "my-macbook",
  "args": {
    "username": "example@finder",
    "next_marker": ""
  }
}

目标设备未登记时返回 404；设备没有注册该方法时返回 409。未指定设备时，如果暂时没有合适的在线设备，任务会保持 queued，等待设备上线或空闲。

查询任务和结果 Copy Chapter

TASK_ID="7e793f36-87e0-4ae2-b899-3d57decd95de"

curl -sS \
  -H "Authorization: Bearer $BRIDGE_CALL_TOKEN" \
  "$BRIDGE_URL/v1/tasks/$TASK_ID"

任务状态：

推荐每 1–5 秒查询一次，遇到 completed 或 failed 后停止。网络错误、429 和 5xx 可以使用指数退避重试；不要高频无间隔轮询。

查询当前 Token 创建的最近任务：

curl -sS \
  -H "Authorization: Bearer $BRIDGE_CALL_TOKEN" \
  "$BRIDGE_URL/v1/tasks?status=completed&limit=20"

limit 的有效范围为 1–200。省略 status 时返回所有状态。

可调用方法 Copy Chapter

实际可用方法以 GET /v1 返回的 methods 为准。

账号搜索继续翻页时，把上一页 data.lastBuff 作为 next_marker；其他视频号列表把上一页 data.lastBuffer 作为 next_marker。游标应原样传递，不要自行解码。

获取公众号消息列表 Copy Section

该方法依赖执行设备上的公众号页面 WebSocket 连接。由于设备端请求最长可等待 20 秒，建议通过异步 /v1/call 调用。

{
  "method": "wxmp.biz.msg.list",
  "args": {
    "username": "公众号用户名",
    "offset": "0"
  }
}

搜索视频号账号 Copy Section

{
  "method": "wxchannels.contact.search",
  "args": {
    "keyword": "视频号名称",
    "next_marker": ""
  }
}

获取单个视频详情 Copy Section

按视频号 URL 获取：

{
  "method": "wxchannels.feed.profile",
  "args": {
    "url": "https://channels.weixin.qq.com/web/pages/feed?..."
  }
}

也可以传 oid + nid，或只传 eid。

在设备上创建下载任务 Copy Section

{
  "method": "download.create",
  "target_device_id": "downloader-linux",
  "args": {
    "url_request": {
      "url": "https://example.com/video.mp4",
      "download_dir": "/downloads",
      "filename": "video.mp4",
      "auto_start": true,
      "config": {}
    }
  }
}

download.create 会在目标设备写入文件系统。外部调用方应明确下载目录和覆盖策略，并优先指定受控的下载设备。

主流语言调用示例 Copy Chapter

下面的示例都通过 /v1/invoke 调用 wxchannels.contact.feed.list，并直接输出方法结果。客户端 HTTP 超时应略大于 Bridge 的 10 秒等待时间。

JavaScript / TypeScript（Node.js 18+） Copy Section

const bridge_url = process.env.BRIDGE_URL?.replace(/\/+$/, "");
const call_token = process.env.BRIDGE_CALL_TOKEN;

if (!bridge_url || !call_token) {
  throw new Error("请设置 BRIDGE_URL 和 BRIDGE_CALL_TOKEN");
}

const response = await fetch(`${bridge_url}/v1/invoke`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${call_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    method: "wxchannels.contact.feed.list",
    args: {
      username: "example@finder",
      next_marker: "",
    },
  }),
  signal: AbortSignal.timeout(15_000),
});

const response_body = await response.text();
if (!response.ok) {
  throw new Error(`Bridge 返回 ${response.status}: ${response_body}`);
}

const result = JSON.parse(response_body);
console.log(result);

Python 3 Copy Section

先安装 Requests：

python3 -m pip install requests

import os
import requests

bridge_url = os.environ["BRIDGE_URL"].rstrip("/")
call_token = os.environ["BRIDGE_CALL_TOKEN"]

response = requests.post(
    f"{bridge_url}/v1/invoke",
    headers={"Authorization": f"Bearer {call_token}"},
    json={
        "method": "wxchannels.contact.feed.list",
        "args": {
            "username": "example@finder",
            "next_marker": "",
        },
    },
    timeout=15,
)
response.raise_for_status()

result = response.json()
print(result)

Go Copy Section

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

type CallRequest struct {
	Method string         `json:"method"`
	Args   map[string]any `json:"args"`
}

func main() {
	bridge_url := strings.TrimRight(os.Getenv("BRIDGE_URL"), "/")
	call_token := os.Getenv("BRIDGE_CALL_TOKEN")
	if bridge_url == "" || call_token == "" {
		log.Fatal("请设置 BRIDGE_URL 和 BRIDGE_CALL_TOKEN")
	}

	request_body, err := json.Marshal(CallRequest{
		Method: "wxchannels.contact.feed.list",
		Args: map[string]any{
			"username":    "example@finder",
			"next_marker": "",
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	http_client := &http.Client{Timeout: 15 * time.Second}
	http_request, err := http.NewRequest(
		http.MethodPost,
		bridge_url+"/v1/invoke",
		bytes.NewReader(request_body),
	)
	if err != nil {
		log.Fatal(err)
	}
	http_request.Header.Set("Authorization", "Bearer "+call_token)
	http_request.Header.Set("Content-Type", "application/json")

	http_response, err := http_client.Do(http_request)
	if err != nil {
		log.Fatal(err)
	}
	defer http_response.Body.Close()

	response_body, err := io.ReadAll(http_response.Body)
	if err != nil {
		log.Fatal(err)
	}
	if http_response.StatusCode < 200 || http_response.StatusCode >= 300 {
		log.Fatalf("Bridge 返回 %s: %s", http_response.Status, response_body)
	}

	fmt.Println(string(response_body))
}

Java 11+ Copy Section

下面的示例只使用 JDK 标准库，并直接输出方法返回的 JSON；实际项目可使用 Jackson、Gson 等库解析结果。

/* Detailed source-code truncated for AI context efficiency. */

PHP 8+ Copy Section

<?php

$bridge_url = rtrim((string) getenv('BRIDGE_URL'), '/');
$call_token = (string) getenv('BRIDGE_CALL_TOKEN');
if ($bridge_url === '' || $call_token === '') {
    throw new RuntimeException('请设置 BRIDGE_URL 和 BRIDGE_CALL_TOKEN');
}
$request_body = json_encode([
    'method' => 'wxchannels.contact.feed.list',
    'args' => [
        'username' => 'example@finder',
        'next_marker' => '',
    ],
], JSON_THROW_ON_ERROR);

$curl_handle = curl_init($bridge_url . '/v1/invoke');
curl_setopt_array($curl_handle, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $call_token,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $request_body,
]);

$response_body = curl_exec($curl_handle);
if ($response_body === false) {
    throw new RuntimeException(curl_error($curl_handle));
}
$status_code = curl_getinfo($curl_handle, CURLINFO_RESPONSE_CODE);
curl_close($curl_handle);

if ($status_code < 200 || $status_code >= 300) {
    throw new RuntimeException("Bridge 返回 {$status_code}: {$response_body}");
}

json_decode($response_body, true, flags: JSON_THROW_ON_ERROR);
echo $response_body . PHP_EOL;

C#（.NET 6+） Copy Section

using System.Net.Http.Headers;
using System.Net.Http.Json;

var bridge_url = (Environment.GetEnvironmentVariable("BRIDGE_URL") ?? "").TrimEnd('/');
var call_token = Environment.GetEnvironmentVariable("BRIDGE_CALL_TOKEN") ?? "";
if (string.IsNullOrWhiteSpace(bridge_url) || string.IsNullOrWhiteSpace(call_token))
{
    throw new InvalidOperationException("请设置 BRIDGE_URL 和 BRIDGE_CALL_TOKEN");
}

using var http_client = new HttpClient { Timeout = TimeSpan.FromSeconds(15) };
http_client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", call_token);

var request_body = new
{
    method = "wxchannels.contact.feed.list",
    args = new
    {
        username = "example@finder",
        next_marker = "",
    },
};

using var http_response = await http_client.PostAsJsonAsync(
    bridge_url + "/v1/invoke",
    request_body
);
var response_body = await http_response.Content.ReadAsStringAsync();
if (!http_response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"Bridge 返回 {(int)http_response.StatusCode}: {response_body}"
    );
}

Console.WriteLine(response_body);

Rust Copy Section

依赖：

[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use reqwest::Client;
use serde_json::{json, Value};
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bridge_url = env::var("BRIDGE_URL")?.trim_end_matches('/').to_owned();
    let call_token = env::var("BRIDGE_CALL_TOKEN")?;
    let http_client = Client::builder()
        .timeout(std::time::Duration::from_secs(15))
        .build()?;

    let result: Value = http_client
        .post(format!("{bridge_url}/v1/invoke"))
        .bearer_auth(call_token)
        .json(&json!({
            "method": "wxchannels.contact.feed.list",
            "args": {
                "username": "example@finder",
                "next_marker": ""
            }
        }))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;

    println!("{result}");
    Ok(())
}

完整轮询示例 Copy Chapter

下面的 JavaScript 示例创建调用并等待最终结果。idempotency_key 应使用业务对象 ID 或请求唯一 ID，而不是每次重试都生成新值。

const bridge_url = process.env.BRIDGE_URL?.replace(/\/+$/, "");
const call_token = process.env.BRIDGE_CALL_TOKEN;
if (!bridge_url || !call_token) {
  throw new Error("请设置 BRIDGE_URL 和 BRIDGE_CALL_TOKEN");
}
const headers = {
  Authorization: `Bearer ${call_token}`,
  "Content-Type": "application/json",
};

async function bridge_request(path, options = {}) {
  const response = await fetch(bridge_url + path, {
    ...options,
    headers: { ...headers, ...(options.headers || {}) },
  });
  const response_body = await response.text();
  if (!response.ok) {
    throw new Error(`Bridge 返回 ${response.status}: ${response_body}`);
  }
  return JSON.parse(response_body);
}

async function wait_for_task(task_id) {
  let delay_milliseconds = 1000;
  while (true) {
    const { task } = await bridge_request(
      `/v1/tasks/${encodeURIComponent(task_id)}`,
    );
    if (task.status === "completed") return task.result;
    if (task.status === "failed") throw new Error(task.error || "Bridge 调用失败");
    await new Promise((resolve) => setTimeout(resolve, delay_milliseconds));
    delay_milliseconds = Math.min(delay_milliseconds * 1.5, 5000);
  }
}

const { task } = await bridge_request("/v1/call", {
  method: "POST",
  body: JSON.stringify({
    method: "wxchannels.contact.feed.list",
    args: { username: "example@finder", next_marker: "" },
    idempotency_key: "complete-example-001",
  }),
});

const result = await wait_for_task(task.id);
console.log(result);

错误处理 Copy Chapter

Bridge 错误响应统一为：

{
  "error": "错误说明"
}

常见 HTTP 状态：

异步任务进入 failed 时，HTTP 查询本身仍返回 200，业务错误位于 task.error。同步调用则直接返回非 2xx 状态和 { "error": "..." }。

可靠性与安全建议 Copy Chapter

• Bridge 使用至少一次投递。设备断线或租约过期时，任务可能重新执行；执行方法应能容忍重复调用。
• 对可能产生副作用的调用始终设置稳定的 idempotency_key。
• /v1/invoke 不使用幂等键。只应自动重试无副作用的方法；其他调用使用 /v1/call 并设置幂等键。
• 不要把调用 Token 放在 URL、浏览器前端代码、日志或 Git 仓库中。
• 为不同人员和系统创建不同 Token，分别设置有效期；不再使用时立即过期或移除。
• 调用 Token 当前可以访问 Bridge 中全部在线方法。需要方法级权限、限流或计费时，应在 Bridge 前增加上层网关。
• 调用 args、结果和任务元数据会在 Bridge 中持久化；不要通过 Bridge 传递不必要的敏感信息。
• 完成和失败任务保留 7 天，调用方应及时保存需要长期使用的结果。

Feature Download Hooks (`docs/feature/download-hooks.md`) Copy Section

title: 下载任务 Hook Copy Chapter

下载任务 Hook

在工作目录的 hooks.js 中可以声明下载任务生命周期 Hook：

function onTaskSuccess(ctx) {
  // 仅在任务成功时调用。
}

function onTaskFailed(ctx) {
  // 仅在任务失败时调用，可通过 ctx.error 获取失败原因。
}

function onTaskFinish(ctx) {
  // 任务成功或失败时都会调用。
}

同一任务的调用顺序如下：

• 成功：onTaskSuccess(ctx)、onTaskFinish(ctx)。
• 失败：onTaskFailed(ctx)、onTaskFinish(ctx)。

这些 Hook 异步执行，不阻塞任务进入终态。某个 Hook 执行失败时会记录警告日志，但不会改变任务状态；onTaskSuccess 或 onTaskFailed 执行失败也不会阻止 onTaskFinish 执行。

ctx 的结构为：

type FinishContext = {
  task: {
    id: number;
    name: string;
    download_dir?: string;
    config: Record<string, unknown>;
  };
  config: Record<string, unknown>;
  metadata: Record<string, unknown>;
  resources: Array<{
    id: number;
    name: string;
    kind: string;
    size: number;
    unique_id: string;
    extra: Record<string, string>;
    endpoints: Array<{
      protocol: string;
      url: string;
    }>;
  }>;
  filePaths: string[];
  downloadDir: string;
  status: "success" | "failed";
  error?: string;
};

失败任务的 filePaths 只包含失败前已完成的资源；没有已完成资源时为空数组。

文件命名 Hook onFilename 的用法参见指定下载的文件名。

Feature Filename (`docs/feature/filename.md`) Copy Section

title: 指定下载的文件名 Copy Chapter

指定下载的文件名

建议通过 hooks.js 配置下载文件的文件名。

通过配置文件（已废弃） Copy Chapter

此方式已废弃，请改用 hooks.js。旧版配置方式可参考下载配置。

通过 hooks.js Copy Chapter

不建议通过全局脚本修改文件名，请在工作目录 workdir 下创建 hooks.js，并定义 onFilename：

function onFilename(meta) {
  return {
    directories: [meta.author],
    name: [meta.title, meta.spec, meta.idx].filter(Boolean).join("_"),
  };
}

directories 是相对于下载目录的子目录列表，name 是不带扩展名的文件名；文件扩展名由下载器自动添加。以上示例会按作者创建子目录，并生成 标题_规格_序号.mp4。

meta.idx 建议保留吧

在下载文件名称中增加视频发布时间 Copy Section

function secondsToYMD(seconds, startTimestamp = 0) {
  const date = new Date((startTimestamp + seconds) * 1000);

  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");

  return `${year}${month}${day}`;
}

function onFilename(meta) {
  const t = secondsToYMD(meta.created_at);
  return {
    directories: [],
    name: [meta.author, meta.title, t, meta.spec, meta.idx].filter(Boolean).join("_"),
  };
}

下载的文件名，就是 作者名称_标题_20260710_规格.mp4

其中 meta 类型为

type Meta = {
  /** 默认文件名，优先取 title，没有则取视频 id，仍没有则使用 当前时间秒数 */
  filename: string,
  /** 视频 id */
  id: string,
  /** 视频标题 */
  title: string,
  /** 视频质量 original | 'xWT111' */
  spec: string,
  /** 视频发布时间（单位秒） */
  created_at: number,
  /** 视频下载时间（单位秒） */
  download_at: number,
  /** up主名称 */
  author: string,
};

Feature Long Video (`docs/feature/long-video.md`) Copy Section

title: 长视频下载 Copy Chapter

长视频下载

251226 及之后的版本默认在后台下载，长视频无需额外配置。像普通视频一样点击「下载」即可，刷新前端页面不会中断下载任务。

退出下载器会中断所有正在进行的下载任务。

Feature Mcp (`docs/feature/mcp.md`) Copy Section

title: MCP Copy Chapter

MCP

MCP（Model Context Protocol）让支持 MCP 的 AI 客户端以工具调用的方式访问下载器。当前实现提供应用配置管理、内容解析与下载、微信视频号查询，以及下载任务、账号、浏览记录、日志和证书状态等本地数据查询能力。

下载器支持两种接入方式：

• Streamable HTTP（推荐）：使用主服务的 /mcp 端点。内置 MCP 直接访问当前进程中的数据库和运行时服务。
• stdio：由 AI 客户端启动 wx_video_download mcp 子进程，再通过已经运行的下载器 API 完成操作。

两种接入方式提供相同的 MCP 工具。需要更完整的 stdio 配置与视频号外部下载说明，可参阅 MCP Server 命令行文档。

文档 Copy Chapter

• 启用
• 命令

常用场景 Copy Section

• 修改下载目录
• 解析链接并下载
• 查询账号内容和浏览记录
• 排查下载失败
• 使用第三方下载器保存视频号视频

Feature Playground (`docs/feature/playground.md`) Copy Section

layout: page title: API Playground sidebar: false pageClass: api-page Copy Chapter

Guide Certificate (`docs/guide/certificate.md`) Copy Section

title: 手动安装根证书 Copy Chapter

手动安装根证书

安装根证书的目的是拦截并修改视频号响应，从而实现插入下载按钮。当自动安装失败时，可以参考该文档手动安装根证书

安装根证书会影响系统的全局信任链，请仅在充分信任的前提下进行。如果担心根证书风险，可以安装自己的根证书。参考 证书配置

下载安装 Copy Section

点击下载 SunnyNet.cer

Windows Copy Chapter

• 下载根证书文件并双击打开
• 按向导选择“本地计算机”，并安装到“受信任的根证书颁发机构”
• 也可通过 MMC 管理单元手动导入

查看是否安装成功

macOS Copy Chapter

• 双击下载的 SunnyNet.cer 打开“钥匙串访问”
• 选择添加到“系统”钥匙串，并设置“始终信任”
  双击 SunnyNet.cer 打开“钥匙串访问”

在左上角选择“系统”钥匙串，将证书添加到系统钥匙串

双击证书，展开“信任”，将“使用此证书时”设为“始终信任”，关闭窗口后输入管理员密码保存

Linux Copy Chapter

下载 SunnyNet.cer 后，根据发行版选择对应命令安装到系统根证书库。

Debian / Ubuntu Copy Section

sudo mkdir -p /usr/local/share/ca-certificates
sudo install -m 0644 ~/Downloads/SunnyNet.cer /usr/local/share/ca-certificates/WeChatAppEx_CA.crt
sudo update-ca-certificates --fresh

Fedora / RHEL / CentOS Copy Section

sudo mkdir -p /etc/pki/ca-trust/source/anchors
sudo install -m 0644 ~/Downloads/SunnyNet.cer /etc/pki/ca-trust/source/anchors/WeChatAppEx_CA.crt
sudo update-ca-trust extract

Arch / Manjaro Copy Section

sudo mkdir -p /etc/ca-certificates/trust-source/anchors
sudo install -m 0644 ~/Downloads/SunnyNet.cer /etc/ca-certificates/trust-source/anchors/WeChatAppEx_CA.crt
sudo trust extract-compat

安装后重启微信和下载器。如果浏览器、Chromium/Electron 应用仍然提示证书不受信任，可以额外写入当前用户的 NSS 证书库：

mkdir -p ~/.pki/nssdb
[ -f ~/.pki/nssdb/cert9.db ] || certutil -d sql:$HOME/.pki/nssdb -N --empty-password
certutil -d sql:$HOME/.pki/nssdb -D -n WeChatAppEx_CA 2>/dev/null || true
certutil -d sql:$HOME/.pki/nssdb -A -n WeChatAppEx_CA -t "CT,C,C" -i ~/Downloads/SunnyNet.cer

certutil 命令由 libnss3-tools（Debian / Ubuntu）或 nss-tools（Fedora / RHEL / CentOS）提供，Arch / Manjaro 可安装 nss。

Guide Docker Webtop (`docs/guide/docker-webtop.md`) Copy Section

Docker image

Docker 镜像包含 WeChat、SunnyNet 系统根证书、Linux wx_video_download 二进制和
自动启动脚本。

默认发布镜像：

ghcr.io/ltaoo/wx_video_download:v260607

使用已发布镜像时，不需要自己准备 WeChatLinux_arm64.deb。deb 只用于本地构建或调试
Docker 镜像。

可以先检查镜像是否可拉取：

docker pull ghcr.io/ltaoo/wx_video_download:v260607

如果提示 denied，说明镜像还没有发布、GHCR 包是私有的，或当前 Docker 没有登录
GHCR。此时需要先发布/公开镜像，或者执行 docker login ghcr.io 后再拉取；否则只能走
“本地构建镜像”路径。

直接启动 Copy Chapter

bash build/run-webtop-container.sh

默认参数等价于下面的手动 Webtop 命令：3000 端口、NET_ADMIN、
seccomp=unconfined、/dev/net/tun、PUID=1000、PGID=1000、
Asia/Shanghai、/config:/config 持久化，并使用固定 hostname
wx-linux。

如果已经存在同名容器，换一个容器名和端口：

NAME=wx_download_test WEB_PORT=3100 bash build/run-webtop-container.sh

打开 http://127.0.0.1:3000 进入桌面。WeChat 会自动启动，
wx_video_download 会在可见终端窗口中前台运行，方便直接观察日志。

手动 docker run 示例 Copy Chapter

docker run -d \
  --name=wx_download \
  --restart=unless-stopped \
  --hostname=wx-linux \
  --security-opt seccomp=unconfined \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e RESOLUTION=1920x1080x24 \
  -p 3000:3000 \
  -v /config:/config \
  ghcr.io/ltaoo/wx_video_download:v260607

多账号多开 Copy Chapter

明确规则：

• 不同 WeChat 账号必须使用不同的宿主机 CONFIG_DIR，例如
  /config/wxaccounts/wxaccount1、/config/wxaccounts/wxaccount2。
• 不同账号同时运行时，也必须使用不同的 NAME 和 WEB_PORT。
• 建议不同账号使用不同但固定的 CONTAINER_HOSTNAME，让每个账号对应一个稳定的
  Linux 环境。
• 同一个 WeChat 账号重建或升级容器时，继续使用同一个 CONFIG_DIR 和
  CONTAINER_HOSTNAME，不要并发启动两份相同账号的数据目录。
• /config 目录里保存 WeChat 用户数据、wx_video_download 配置、系统
  machine-id 和 hostname。删除或更换这些数据会让 WeChat 看到一个新的 Linux
  环境。
• 不要在账号已经登录后，把一个账号的 /config 复制给另一个账号使用。如果需要模板，
  只在未登录 WeChat 之前复制空白初始化目录。

推荐目录结构：

/config/wxaccounts/
  wxaccount1/
  wxaccount2/
  wxaccount3/

启动账号 1：

NAME=wxaccount1 \
WEB_PORT=3001 \
CONFIG_DIR=/config/wxaccounts/wxaccount1 \
CONTAINER_HOSTNAME=wx-linux-account1 \
bash build/run-webtop-container.sh

启动账号 2：

NAME=wxaccount2 \
WEB_PORT=3002 \
CONFIG_DIR=/config/wxaccounts/wxaccount2 \
CONTAINER_HOSTNAME=wx-linux-account2 \
bash build/run-webtop-container.sh

启动账号 3 时继续递增即可：

NAME=wxaccount3 \
WEB_PORT=3003 \
CONFIG_DIR=/config/wxaccounts/wxaccount3 \
CONTAINER_HOSTNAME=wx-linux-account3 \
bash build/run-webtop-container.sh

访问地址：

账号 1: http://127.0.0.1:3001
账号 2: http://127.0.0.1:3002
账号 3: http://127.0.0.1:3003

停止、删除、重建某个账号容器时，只删除容器，不删除 CONFIG_DIR：

docker stop wxaccount1
docker rm wxaccount1

NAME=wxaccount1 \
WEB_PORT=3001 \
CONFIG_DIR=/config/wxaccounts/wxaccount1 \
CONTAINER_HOSTNAME=wx-linux-account1 \
bash build/run-webtop-container.sh

本地构建镜像 Copy Chapter

普通使用不需要本地构建。只有修改 Dockerfile、调试镜像内容，或还没有可用发布镜像时，
才需要自己准备 WeChatLinux_arm64.deb。

构建 arm64 Webtop 镜像：

bash build/build-webtop-image.sh

默认读取 /Users/litao/Downloads/WeChatLinux_arm64.deb。需要指定路径或镜像名时：

WECHAT_DEB=/path/to/WeChatLinux_arm64.deb \
IMAGE=wx_video_download:v260607 \
bash build/build-webtop-image.sh

默认配置来自 internal/config/config.template.yaml，global.js 不存在时会使用空脚本占位。需要打包自定义默认配置或用户脚本时：

CONFIG_FILE=/path/to/config.yaml \
GLOBAL_SCRIPT=/path/to/global.js \
bash build/build-webtop-image.sh

使用本地构建镜像启动：

IMAGE=wx_video_download:v260607 bash build/run-webtop-container.sh

手动启动本地镜像时，把镜像名改成 wx_video_download:v260607 即可：

docker run -d \
  --name=wx_download_local \
  --restart=unless-stopped \
  --hostname=wx-linux \
  --security-opt seccomp=unconfined \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e RESOLUTION=1920x1080x24 \
  -p 3000:3000 \
  -v /config:/config \
  wx_video_download:v260607

持久化文件 Copy Chapter

• /config/wx_video_download/config.yaml
• /config/wx_video_download/app.log
• /config/.wx_identity/machine-id
• /config/.wx_identity/hostname
• /config/logs/wx_video_download.out.log
• /config/logs/wx_video_download_terminal.log
• /config/logs/wechat.log
• /config/Downloads

常用运行参数 Copy Chapter

• IMAGE=ghcr.io/ltaoo/wx_video_download:v260607
• WECHAT_AUTOSTART=false
• WX_VIDEO_AUTOSTART=false
• WX_CHANNELS_DOWNLOAD_CONFIG_FILEPATH=/config/wx_video_download/config.yaml
• CONFIG_DIR=/host/path
• CONTAINER_HOSTNAME=wx-linux
• WEB_PORT=3100

检查运行状态 Copy Chapter

docker exec -it wxaccount1 wx-status
docker exec -it wxaccount1 tail -f /config/logs/wx_video_download.out.log
docker exec -it wxaccount1 tail -f /config/logs/wechat.log

备份某个账号时，先停止容器，再备份对应目录：

docker stop wxaccount1
tar -C /config/wxaccounts -czf wxaccount1-backup.tgz wxaccount1

Guide Docker (`docs/guide/docker.md`) Copy Section

title: 使用 Docker 运行 Copy Chapter

使用 Docker 运行

在 Docker 里的 linux 运行微信并登录，风险自己承担，建议用小号

镜像地址：

ghcr.io/ltaoo/wx_video_download:latest

启动 Copy Chapter

先创建一个目录集中存放微信数据目录，登录状态不丢失。同时视频也是下载到该目录中

mkdir wxchannelsdata

为第一个容器创建数据目录

cd wxchannelsdata
mkdir wx_account1
# 确保当前在 wxchannelsdata 目录中
pwd
~/xxx/wxchannelsdata
ls
wx_account1

然后启动容器

端口3000 如果有冲突，则修改为 -p 8001:3000 ，即左边的端口修改为不会冲突的端口
端口2022、2023 如果有冲突，也按同样方式修改左边的宿主机端口

docker run -d \
  --name=wx_account1 \
  --restart=unless-stopped \
  --hostname=wx-linux \
  --security-opt seccomp=unconfined \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e RESOLUTION=1920x1080x24 \
  -p 3000:3000 \
  -p 2022:2022 \
  -p 2023:2023 \
  -v ./wx_account1:/config \
  ghcr.io/ltaoo/wx_video_download:latest

打开浏览器访问：

http://127.0.0.1:3000

进入桌面后，WeChat 和 wx_video_download 会自动启动。登录 WeChat 后，在容器桌面里打开视频号页面即可使用。下载好的视频默认在下面目录

~/xxx/wxchannelsdata/wx_account1/Downloads

不要启动多个容器运行多个微信帐号，没有经过测试可能封号风险很大

修改配置 Copy Chapter

在挂载的文件夹 wx_account1 中，有 wx_video_download 文件夹，修改其中的 config.yaml，然后，重启容器即可

Guide Macos (`docs/guide/macos.md`) Copy Section

title: macOS 运行 Copy Chapter

macOS 运行

macOS 运行步骤已合并到 下载并运行。

Guide Start (`docs/guide/start.md`) Copy Section

title: 下载 Copy Chapter

下载

下载对应平台的构建包：https://github.com/ltaoo/wx_channels_download/releases

如何选择构建包 Copy Chapter

根据上述环境信息，选择对应的构建包

1. macOS arm64
   选择 darwin_arm64 后缀

2. macOS x86_64
   选择 darwin_x86_64 后缀

3. Windows x86_64
   选择 windows_x86_64 后缀

4. Linux x86_64
   选择 linux_x86_64 后缀

5. Linux arm64
   选择 linux_arm64 后缀

windows 平台有带 safe 标记的文件，表示「没有使用UPX压缩来减小体积」，在某些电脑上，可以避免被识别为病毒

运行下载器 Copy Chapter

Windows Copy Section

在 Windows 平台，解压后双击直接运行 wx_video_download.exe 即可，首次使用会自动安装证书并设置系统代理。

macOS Copy Section

自 251213 之后，会对 wx_video_download 进行签名和公证，以避免 macOS 提示「文件不能打开」。但由于无法对二进制文件「钉证」，双击打开还会触发 Gatekeeper 保护，需要手动确认才能运行。

但是通过命令行运行就完全不会触发任何的校验。

260502 之后证书失效，需要完整按下面步骤执行。

首次打开需要使用 sudo ./wx_video_download 运行一次，后续双击打开即可。

如果有问题，按照下面步骤进行。

赋予执行权限

chmod +x ./wx_video_download

以管理员身份运行

sudo ./wx_video_download

允许来自未知来源的应用

若系统提示「文件不能打开」，在系统设置中允许来自未签名开发者的应用。

再次执行 ./wx_video_download，可能出现下面窗口，选择 Open Anyway。

只有首次打开需要经历上述步骤，之后可直接双击 wx_video_download 运行，无需繁琐步骤。

Linux Copy Section

在 Linux 平台，下载对应的 linux 构建包并解压后，先赋予执行权限：

chmod +x ./wx_video_download

然后修改同目录下的 config.yaml，启用 TUN 模式：

proxy:
  tun: true

TUN 模式需要管理员权限，启动时请使用：

sudo ./wx_video_download

启动成功后，打开微信中的视频号页面即可下载。

Guide Step (`docs/guide/step.md`) Copy Section

title: 步骤 Copy Chapter

使用步骤

当下载器运行成功后，终端内容如下

此时可以打开视频号页面正常下载了

视频号详情页 Copy Chapter

左侧是视频，下面有操作按钮，右侧是推荐，这种页面即「视频号详情页」。默认会在操作按钮一栏插入下载按钮，点击即可下载

当前仅在视频号详情页支持「更多」菜单，可以下载不同规格的视频，可以打印下载命令。可以通过右上角「个人」->「浏览记录」进入该页面

视频号首页 Copy Chapter

即点击微信侧边「视频号」进入的页面，以及某些版本从「文件助手」打开视频号时，会自动跳转至首页。

视频下方的操作栏，同样有下载按钮，点击即可下载视频。

兜底按钮 Copy Chapter

上面的按钮依赖页面上特定的位置，如果视频号有改版，就会出现无法正确插入下载按钮，这种情况下会直接在页面上插入下载按钮

没有下载按钮 Copy Chapter

如果打开视频号没有下载按钮请先检查系统代理是否如下所示

win 系统 Copy Section

macos 系统 Copy Section

Releases 241011 (`docs/releases/241011.md`) Copy Section

title: v241011 Copy Chapter

v241011

主要变化 Copy Chapter

• 应该是视频号又改版了，不能直接在页面下载了。改成点击下载按钮复制视频链接到粘贴板，然后到谷歌或其他浏览器打开下载
• 另外测试了很多视频都可以直接下载，没有加密了。所以如果有加密视频，新版本可能会下载失败

在页面直接下载，理论上还是能实现，实现上要麻烦许多，后面再研究。

Releases 241016 (`docs/releases/241016.md`) Copy Section

title: v241016 Copy Chapter

v241016

主要变化 Copy Chapter

• 前一个版本又下载不了，改回在页面直接下载又正常了

是和微信客户端版本有关吗，对这块不了解。如果 241016 这个版本用不了，可以试试其他版本。

我目前微信客户端版本是 Weixin 3.9.12.17，可以正常下载的。

Releases 241022 (`docs/releases/241022.md`) Copy Section

title: v241022 Copy Chapter

v241022

主要变化 Copy Chapter

• 当视频被删除时没有正确地显示「被删除」而是一直处于加载中状态
• 下载按钮修改成和其他操作按钮相同的样式

Releases 241030 (`docs/releases/241030.md`) Copy Section

title: v241030 Copy Chapter

v241030

主要变化 Copy Chapter

• 当视频号内容是多张图片时，也会出现下载按钮。点击将会下载一个包含了全部图片的压缩包

Releases 241031 (`docs/releases/241031.md`) Copy Section

title: v241031 Copy Chapter

v241031

主要变化 Copy Chapter

• 又遇到之前无法在页面下载的问题，这次改成了下载压缩包，视频在压缩包内的形式

目前是可行的，但无法保证之后仍然可行。

建议使用 WechatVideoSniffer2.0 稳定性更高。

Releases 241101 (`docs/releases/241101.md`) Copy Section

title: v241101 Copy Chapter

v241101

主要变化 Copy Chapter

• 现在无需手动下载证书并安装了
• 修复了下载时提示找不到 lib/jszip.min.js 的问题

Releases 241102 (`docs/releases/241102.md`) Copy Section

title: v241102 Copy Chapter

v241102

主要变化 Copy Chapter

• 在「更多」下拉菜单增加「下载视频」按钮，兼容不同详情页布局不同导致没有下载按钮的问题

Releases 241104 (`docs/releases/241104.md`) Copy Section

title: v241104 Copy Chapter

v241104

主要变化 Copy Chapter

• 支持下载不同质量的视频
• 修复了下载的视频无法拖动进度条的问题
• 修复了长视频内容进度未加载就下载，导致视频无法播放或不完整的问题
• 修复了某些视频误判断为图片导致无法下载的问题
• 修复了直播间一直加载中的问题

关于不同质量的视频，详情见使用说明。

Releases 241106 (`docs/releases/241106.md`) Copy Section

title: v241106 Copy Chapter

v241106

主要变化 Copy Chapter

• 修复了非首次打开的视频，下载下来都无法播放的问题

现在点击页面上「更多推荐」视频，下载下来的视频可以正常打开播放了。

当出现「解密失败，停止下载」的提示，关闭全部视频页面、窗口。重新打开，就可以下载。

Releases 241216 (`docs/releases/241216.md`) Copy Section

title: v241216 Copy Chapter

v241216

主要变化 Copy Chapter

• 支持下载直播回放
• 支持 macOS 系统

在微信 Version 3.8.9 (28564) 测试可用

macOS 下使用说明 Copy Chapter

chmod +x ./wx_video_download_darwin_xxx
sudo ./wx_video_download_darwin_xxx

此时会提示文件不能打开，需要到系统设置中允许，然后重新执行 sudo ./wx_video_download_darwin_xxx。

在安装证书的过程中会申请权限，同意即可。后续打开无需使用 sudo，只需要双击运行

关闭 macOS 终端时请使用 Command + c 的方式，否则可能会出现系统代理未取消，导致网络无法访问的问题

当出现网络无法访问时请检查系统代理并手动取消即可。

Releases 250215 (`docs/releases/250215.md`) Copy Section

title: v250215 Copy Chapter

v250215

主要变化 Copy Chapter

• 在控制台显示下载进度，当获取不到进度时显示已下载的字节数
• 在「更多」菜单中增加封面图片下载
• 自动检测当前网络设备并代理
• 支持命令行参数指定要代理的网络设备和程序使用的端口号

./wx_video_download_xxx --dev=Wi-Fi --port=1080

一般情况下无需手动指定设备与端口号，直接 ./wx_video_download_xxx 即可

Releases 250424 (`docs/releases/250424.md`) Copy Section

title: v250424 Copy Chapter

v250424

主要变化 Copy Chapter

• 修复了下载按钮样式不一致的问题
• 修复了更多按钮点击不显示更多菜单的问题
• 增加了 windows 启动失败时提示是否以管理员身份运行

Releases 250425 (`docs/releases/250425.md`) Copy Section

title: v250425 Copy Chapter

v250425

主要变化 Copy Chapter

• 修复了无法下载视频的问题

Releases 250514 (`docs/releases/250514.md`) Copy Section

title: v250514 Copy Chapter

v250514

主要变化 Copy Chapter

• 修复无法下载图片视频的问题

Releases 250621 (`docs/releases/250621.md`) Copy Section

title: v250621 Copy Chapter

v250621

主要变化 Copy Chapter

• 优化下载时的「进度」展示效果
• 增加 download 命令，可在终端下载视频及解密。超过 1G 的视频建议使用该方式下载

# 使用方式
./wx_video_download_xx download --url "视频地址" --key 解密key --filename "文件名"
# 视频地址、文件名参数需要双引号包裹。解密key不用双引号
# 将会下载视频到 `Downloads` 目录，然后解密

• 视频号「更多」菜单中增加「打印下载命令」按钮
• 修复安装证书时有些错误提示不是中文的问题

Releases 250808 (`docs/releases/250808.md`) Copy Section

title: v250808 Copy Chapter

v250808

主要变化 Copy Chapter

• 修复了微信新版本没有下载按钮的问题

Releases 250913 (`docs/releases/250913.md`) Copy Section

title: v250913 Copy Chapter

v250913

主要变化 Copy Chapter

• 视频号首页增加下载按钮
• 增加 uninstall 命令,可卸载本工具安装的根证书
• 修复打开长视频页面空白的问题

Releases 251027 (`docs/releases/251027.md`) Copy Section

title: v251027 Copy Chapter

v251027

主要变化 Copy Chapter

• 优化了文件大小，现在只有8MB了
• download 命令默认多线程下载
• 直播详情页增加了下载按钮
• 默认下载原始规格的视频

Releases 251122 (`docs/releases/251122.md`) Copy Section

title: v251122 Copy Chapter

v251122

主要变化 Copy Chapter

• 支持通过 config.yaml 配置是否默认下载原始视频：

download:
  defaultHighest: false

• 支持指定是否设置系统代理，并配置端口：

proxy:
  system: true
  port: 2023

• 支持自动检测是否需要管理员权限并按需申请。

Clash 转发示例 Copy Chapter

当关闭系统代理（proxy.system=false）时，可在 Clash 中添加如下脚本，将流量转发到下载器代理服务：

function main(config, profileName) {
    config["proxy-groups"].unshift({
    name: 'ChannelsDownload',
    type: 'fallback',
    proxies: ["channels_download", "DIRECT"],
    interval: 5
  });
  config["proxies"].unshift({
    name: "channels_download",
    type: 'http',
    server: '127.0.0.1',
    port: 2023,
  });
  config.rules.unshift(...[
    "PROCESS-NAME,wx_video_download.exe,DIRECT",
    "PROCESS-NAME,wx_video_download,DIRECT",
    "DOMAIN-SUFFIX,qq.com,ChannelsDownload"
  ]);
  return config;
}

获取 Copy Chapter

• 发布页：https://github.com/ltaoo/wx_channels_download/releases

Releases 251130 (`docs/releases/251130.md`) Copy Section

title: v251130 Copy Chapter

v251130

主要变化 Copy Chapter

• 支持通过 config.yaml 配置下载时的文件名称：

download:
  filenameTemplate: "{{author}}_{{filename}}_{{spec}}_{{download_at}}"

参考 下载配置

• 支持插入 global.js 脚本，对下载时的文件名进行配置

// global.js
function beforeFilename(filename, params) {
	return filename;
}

参考 脚本

Releases 251201 (`docs/releases/251201.md`) Copy Section

title: v251201 Copy Chapter

v251201

主要变化 Copy Chapter

• 增加了本地下载中转服务，开启后下载视频将不会阻塞页面操作。使用参考 配置
• 支持使用本地下载中转服务，将视频转换成 mp3 并下载，参考 mp3下载
• 支持禁止从详情页重定向到首页。使用参考 配置
• 修复了视频号首页切换视频后，没有出现下载按钮的问题（现在仍有问题，出现按钮，但是来回切换后，下载的视频不是当前视频）
• 修复了 download 命令没有指定 key 时，下载的文件名不是传入的文件名的问题
• 修复了 decrypt 命令没有传入正确参数时，终端报错的问题

Releases 251202 (`docs/releases/251202.md`) Copy Section

title: v251202 Copy Chapter

v251202

主要变化 Copy Chapter

• 修复了不能下载封面的问题
• 支持前端转换 mp3 文件，无需本地安装 ffmpeg 了
• 支持配置是否在下载视频时暂停视频播放。参考 配置
• 优化了通过本地中转服务下载时的体验，现在不会打开新 tab 然后再关闭了

Releases 251203 (`docs/releases/251203.md`) Copy Section

title: v251203 Copy Chapter

v251203

主要变化 Copy Chapter

• 修复了双击打开时无法正确找到配置文件的问题
• 修复了不存在配置文件仍尝试读取的问题
• 修复了 Windows 构建包没有 icon 的问题

Releases 251213 (`docs/releases/251213.md`) Copy Section

title: v251213 Copy Chapter

v251213

非常大的一次更新，将原先在视频号脚本内的逻辑全部通过事件分发到外部，由外部处理，从而可以自己实现一些自定义的逻辑

更新内容 Copy Chapter

• 修复首页推荐不展示下载按钮的问题
• 修复终端窗口太窄时无法正确读取到证书的问题
• 将之前「更多」菜单中的功能，移动到下载按钮中。现在首页推荐也有更多菜单了
• 当没有找到操作栏时会在页面注入「悬浮下载按钮」
• 支持自定义菜单功能
• 支持监听「获取视频详情」、「开始下载」、「下载完成」等事件
• 调整了 config.yaml 字段结构
• 对 macOS 端构建包签名、公证

悬浮下载按钮 Copy Chapter

自定义功能 Copy Chapter

目前包括两部分

• 自定义菜单
• 监听事件

其中事件功能，几乎可以实现任意的功能

Releases 251226 (`docs/releases/251226.md`) Copy Section

title: v251226 Copy Chapter

v251226

现在支持批量下载指定帐号的所有视频了，下载能力由 gopeed 提供

更新内容 Copy Chapter

• 修复了在详情页点击侧边视频，会重复插入下载按钮的问题
• 支持在帐号详情页批量下载视频
• 默认在后台下载视频
• 后台下载模式下支持指定下载目录
• 后台下载模式下文件名支持生成目录
• 移除了下载中转服务是否启用的配置

批量下载 Copy Chapter

后台下载 Copy Chapter

之前下载、解密都是在前端，下载长视频经常会中断，而且会阻塞前端页面操作，现在点击「下载」默认是在后台下载了。并且刷新页面不会中断下载，退出下载器后会中断所有下载任务。

重新启动后，需要手动开始暂停的下载任务。

如果不需要后台下载，可以在配置文件中指定在前端下载

• 前端下载

文件名支持生成目录 Copy Section

在配置文件 filenameTemplate，可以使用 {{author}} 来表示视频作者的名称，增加 / 符号，例如 {{author}}/{{filename}}_{{spec}}，这样下载的文件会放在以作者名为目录的目录中。

• 下载时的文件名称

Releases 251231 (`docs/releases/251231.md`) Copy Section

title: v251231 Copy Chapter

v251231

2026 年了，祝大家新年快乐！♪٩(´ω`)و♪

更新内容 Copy Chapter

• 修复了首页推荐页面下载视频时偶尔下载到非当前播放视频的问题
• 修复了下载完成时没有完成音效的问题
• 新增了 API 调用接口

API 调用 Copy Chapter

参考 API

Releases 260110 (`docs/releases/260110.md`) Copy Section

title: v260110 Copy Chapter

v260110

增加了微信公众号 RSS 功能

更新内容 Copy Chapter

• 修复了暂停的任务没有继续开始按钮的问题
• 修复了批量下载会出现重复下载的问题
• 修复了重复启动下载器时，第二个终端无法正常退出的问题
• 直播下载按钮增加 rate 和 质量描述
• 增加了创建视频号下载任务接口
• 视频号视频列表接口现在支持 next_marker 获取下一页
• 视频号详情接口现在支持直接传入视频号页面地址了
• 增加 /play 接口，可以传入视频地址（非视频号页面地址）和 key，即可直接播放
• 优化下载面板样式，增加总下载任务数
• 支持配置下载完成后是否播放音效

公众号RSS Copy Chapter

Releases 260118 (`docs/releases/260118.md`) Copy Section

title: v260118 Copy Chapter

v260118

我经常在不同电脑下载视频，文件就非常零散，所以这次更新可以在 nas 上部署，把视频直接下载到 nas 上就方便多了。

更新内容 Copy Chapter

新功能 Copy Section

• 将原先的 mp 命令改为 server 命令
• 增加 download.remoteServer 配置，开启后请求该服务接口下载视频
• 公众号管理页面现在刷新后仍保留当前筛选项
• 图片类视频也支持在后台下载了
• 批量下载过程中支持中断创建下载任务
• 下载任务列表接口支持分页

问题修复 Copy Section

• 修复了公众号管理页面状态筛选项不生效的问题
• 修复了批量下载时存在图片类视频会中断下载的问题
• 修复了批量下载存在同名视频时实际下载到的视频数和展示的下载任务数不一致的问题

在 nas 上部署下载服务 Copy Chapter

下载 linux 版本的 wx_channels_download，上传到 nas 上，执行如下命令

./wx_channels_download server -d

将以守护进程模式运行

建议修改 config.yaml 中下载目录为 ./downloads 便于管理

然后修改本地的 config.yaml 增加如下配置

download:
  remoteServer:
    enabled: true
    protocol: "http"
    hostname: "192.168.1.118"
    port: 2022

192.168.1.118 是我的 nas 服务内网地址，修改号之后启动下载器，点击下载按钮，就会提交到 nas 上下载了。

同时下载面板上原先的「打开文件」按钮改成了在新窗口打开视频了，同样可以验证视频是否下载成功。

公众号 RSS 服务 Copy Chapter

实际用下来并不稳定，后面会移除掉该功能，改为公众号文章下载功能，预计包含如下功能

• 下载单篇文章
• 下载指定公众号所有文章

Releases 260201 (`docs/releases/260201.md`) Copy Section

title: v260201 Copy Chapter

v260201

修复了一些问题，增加更多的 API 接口

更新内容 Copy Chapter

新功能 Copy Section

• 增加「直播回放列表」接口
• 增加「赞和收藏列表」接口
• 远程服务模式下支持预览图片类视频
• 支持使用自定义根证书 自定义根证书
• 首页推荐现在点击指定帐号下的视频时也会出现下载按钮了

问题修复 Copy Section

• 修复了获取视频号列表时 next_marker 不生效的问题
• 修复了视频描述存在链接时提示「不合法的文件名」问题
• 修复首页推荐没有下载按钮的问题
• 修复了批量下载时将直播当作普通视频下载的问题

Releases 260208 (`docs/releases/260208.md`) Copy Section

title: v260208 Copy Chapter

v260208

更新内容 Copy Chapter

问题修复 Copy Section

• 修复了在 win7 无法安装证书的问题
• 修复了在 linux 无法安装证书的问题
• 修复了下载原始视频，但是文件名后面仍出现 xWT111 后缀的问题

Releases 260302 (`docs/releases/260302.md`) Copy Section

title: v260302 Copy Chapter

v260302

更新内容 Copy Chapter

• 为 Windows 平台增加了 wx_video_download_safe 包
• 在公众号文章页面，增加了「下载」按钮
• 获取视频号详情接口支持 eid 参数，企业微信访问视频号页面时，可以从地址的 query.eid 获取到该参数
• 当下载记录太多时会导致页面卡顿，暂时限制只获取50条下载记录（不影响正常下载功能）
• 现在终端会定时查看代理是否正确，当代理被其他软件覆盖时会在终端提示
• 修复了远程模式下，本地 API 接口无法使用的问题

Releases 260310 (`docs/releases/260310.md`) Copy Section

title: v260310 Copy Chapter

v260310

更新内容 Copy Chapter

• 增加文件传输助手页面，支持自动下载转发到个微「文件传输助手」的视频
• 增加 channels.refreshInterval 配置，用于每隔一段时间自动刷新视频号页面。单位秒，如 3600 表示 10小时
• 内置默认直连服务地址，修复开启下载器后，App Store 等服务无法使用的问题

Releases 260311 (`docs/releases/260311.md`) Copy Section

title: v260311 Copy Chapter

v260311

更新内容 Copy Chapter

问题修复 Copy Section

• 修复企业微信打开的视频号页面无法调用API的问题
• 修复视频号首页偶发下载的视频不是当前视频的问题

Releases 260317 (`docs/releases/260317.md`) Copy Section

title: v260317 Copy Chapter

v260317

更新内容 Copy Chapter

• 适配视频号新样式
• 优化下载列表实现，现在不再卡顿了
• 默认所有服务走直连，指定服务才通过代理，不用额外配置，App Store 等服务就可以正常使用了
• /api/task/list 现在会原样返回 Gopeed 的所有字段了

问题修复 Copy Section

• 修复文件名中的 / 符号没有按预期创建文件夹的问题

Releases 260323 (`docs/releases/260323.md`) Copy Section

title: v260323 Copy Chapter

v260323

问题修复 Copy Chapter

• 修复无法获取直播流链接的问题
• 修复无法通过 eid 调用详情接口的问题
• 修复首页视频切换时没有正确插入下载按钮的问题

Releases 260324 (`docs/releases/260324.md`) Copy Section

title: v260324 Copy Chapter

v260324

更新内容 Copy Chapter

• 公众号文章下载页面，增加「下载记录」菜单项，点击打开下载记录面板
• 支持预览远端服务下载好的公众号文章
• 修复公众号文章可以重复下载的问题
• 修复公众号文章下载时没有展示正确进度的问题

Releases 260502 (`docs/releases/260502.md`) Copy Section

title: v260502 Copy Chapter

v260502

更新内容 Copy Chapter

• 移除 打印下载命令 菜单
• 移除 原始视频 菜单
• 获取视频详情接口的 url 现在支持分享链接了
• 增加获取视频评论接口

Releases 260507 (`docs/releases/260507.md`) Copy Section

title: v260507 Copy Chapter

v260507

更新内容 Copy Chapter

• 增加 原始视频 菜单

Releases 260520 (`docs/releases/260520.md`) Copy Section

title: v260520 Copy Chapter

v260520

更新内容 Copy Chapter

• 当配置 前端下载 时，现在不会渲染自定义下载面板了
• 修复切换到上一个或下一个视频时，没有出现下载按钮的问题

Releases 260524 (`docs/releases/260524.md`) Copy Section

title: v260524 Copy Chapter

v260524

更新内容 Copy Chapter

• 支持 TUN 模式代理，在网络层截获流量，无需修改系统代理

Releases 260531 (`docs/releases/260531.md`) Copy Section

title: v260531 Copy Chapter

v260531

更新内容 Copy Chapter

• 修复 WXU.onFeed 回调在 global.js 不会触发的问题
• 增加 /api/channels/parse_sph 接口支持解析 视频号分享链接
• /api/channels/feed/profile 接口支持解析某些特殊的 视频号分享链接

Releases 260607 (`docs/releases/260607.md`) Copy Section

title: v260607 Copy Chapter

v260607

更新内容 Copy Chapter

• 修复某些视频数据格式不匹配导致报错的问题
• 支持下载包含背景乐的图片类视频
• 支持为 tun模式 指定默认网卡

Releases 260614 (`docs/releases/260614.md`) Copy Section

title: v260614 Copy Chapter

v260614

更新内容 Copy Chapter

• 增加 /api/channels/feed/share_url 接口

Releases 260706 (`docs/releases/260706.md`) Copy Section

title: v260706 Copy Chapter

v260706

更新内容 Copy Chapter

• 增加 /api/channels/follow/list 接口，用于获取「我关注的视频号」列表
• /api/task/create 接口返回将要下载的文件的文件名和绝对路径
• 优化下载按钮菜单样式，更贴合微信原生样式
• 删除下载记录时增加二次确认弹窗，可以选择是否同时删除已下载的文件
• 清空下载记录时增加二次确认弹出，可以选择是否同时删除已下载的文件
• 下载面板增加「查看全部」按钮，点击进入 /download 页面，支持批量删除下载记录、开始/暂停全部、根据状态筛选下载任务等功能
• 支持在 docker 容器中使用

Releases 260714 (`docs/releases/260714.md`) Copy Section

title: v260714 Copy Chapter

v260714

更新内容 Copy Chapter

• 修复下载文件名会出现重复的 .mp4 问题
• 下载重复内容时会出现确认弹窗，支持 覆盖 和 重复下载 两种操作

Releases 260810 (`docs/releases/260810.md`) Copy Section

title: v260810 Copy Chapter

v260810

一次非常大的改版，从3月开始写到8月，将近半年时间。其中也经历了许多次改版，一开始为了更强的自定义能力，实现非常复杂，后面功能全砍了，决定先迭代一部分功能。

这次迭代核心工作是为了后续支持更多平台的下载，所以架构做了很大的调整，同时为了支持更复杂的功能，下载器从 gopeed 切换到自研。

更新内容 Copy Chapter

• 支持保存视频号和公众号的浏览记录，可以通过 http://127.0.0.1:2022/browsehistory 访问浏览记录页面
• 增加了获取「视频号浏览记录」接口 /api/channels/play/history
• 下载面板的下拉菜单增加「刷新」等菜单
• 修复了视频号标题过长导致下载的文件没有文件后缀的问题
• 修复了下载器启动失败时看不到错误提示的问题
• 修复了「视频号解析」接口没有原样返回响应值的问题
• 修复了下载器影响了评论区及部分页面图标大小的问题

Releases 260817 (`docs/releases/260817.md`) Copy Section

title: v260817 Copy Chapter

v260817

更新内容 Copy Chapter

• 优化公众号推送列表面板样式，现在会展示封面，并支持直接下载列表中的推送
• 优化下载管理页面样式，增加侧边菜单
• 支持下载知乎文章
• 增加内容抓取页面，可通过 http://127.0.0.1:2022/scraper 访问，输入链接即可解析并下载内容
• 内容抓取页面会实时显示与视频号的连接状态，直观展示视频号能力是否可用
• 增加内容列表和内容详情页，可直接在详情页播放、查看已下载的视频和图片
• 增加账号管理页面
• 视频号页面的下载按钮增加下载器连接状态标志，可直观看到下载器是否可用
• 视频号页面会定时重连下载服务，重启下载器后无需刷新页面即可自动重连
• 增加 MCP 服务，可通过 Agent 直接下载视频号、公众号和知乎文章
• 前端「设置」页面支持查看下载器实际使用的根证书及其状态
• 部署和使用视频号分享链接解析服务的 Cloudflare Worker 时必须指定凭证信息。请勿向过多人共享，以免元宝账号被封禁（#495）
• 修复某些情况下 macOS 代理无效的问题（#478，感谢 @BozhengLong）
• 修复无法下载原始视频的问题（#489）
• 修复文档站 SunnyNet 根证书无法下载的问题
• 修复公众号图集类文章没有下载按钮的问题

::: warning 数据库版本兼容性

自 v260810 起，部分版本会修改数据库迁移文件，无法在新旧版本间随意切换。例如使用 v260817 后，不能直接切换回 v260810，因为 v260817 增加了更多功能并变更了数据库表结构，切换到旧版本会丢失新功能的数据。

如需切换回旧版本，可以让 AI 根据源码中的 migrations 迁移文件强制将数据库迁移回旧版本，完成后才能正常使用。

:::

Releases 260823 (`docs/releases/260823.md`) Copy Section

title: v260823 Copy Chapter

v260823

更新内容 Copy Chapter

• 未配置元宝 Cookie 时，也支持使用视频号解析分享链接（#508）
• Get 页面支持使用第三方下载器下载视频号视频，目前仅测试过 aria2（#477）
• 重复下载进行中的视频时，现在会正确显示错误提示（#517）
• 支持下载公众号文章中的视频（#518）
• MCP 服务支持更多命令，可获取视频号评论列表、直接创建直播下载任务等
• 前端页面增加版本号显示，发现新版本时支持直接下载更新并重启服务
• 优化前端页面样式和交互，下载任务详情和内容详情改为在抽屉中展示，不再打开新页面
• 移除「原始视频」菜单项（#522）
• 修复 Windows 下文件名过长或包含特殊字符时未正确添加后缀、有时无法正常完成任务的问题（#505）
• 修复无法访问日志页面 http://127.0.0.1:2022/logs 的问题
• 修复视频号详情接口缺少点赞数等字段的问题（#519）
• 修复视频号评论列表接口没有返回数据的问题（#519）
• 修复新版微信页面内嵌在聊天窗口时，无法触发 onFetchFeedProfile 和切换视频事件的问题（#510、#520）

Releases 260830 (`docs/releases/260830.md`) Copy Section

title: v260830 Copy Chapter

v260830

更新内容 Copy Chapter

• 视频号直播下载任务支持边下载边播放
• 优化前端代码和交互体验
• 直播页面支持自定义下载按钮的下拉菜单项（#526）
• 修复下载列表页面「全部开始」功能实际只启动三个下载任务的问题
• 修复首页有时无法获取详情的问题 (#528)
• 修复 API Host 填写 0.0.0.0 时无法正确连接下载服务的问题（#529）
• 修复直播下载中断后无法继续下载的问题（#541）

Config Channels Cover (`docs/config/channels/cover.md`) Copy Section

title: 同时下载封面 Copy Chapter

同时下载封面

channels:
  download:
    cover: false

下载视频或图集时是否同时下载封面，默认 false。该配置仅在后台下载时生效。

Config Channels Default Highest (`docs/config/channels/default-highest.md`) Copy Section

title: 默认下载原始视频 Copy Chapter

默认下载原始视频

channels:
  download:
    defaultHighest: false

点击下载按钮时是否默认下载原始视频，默认 false。设置为 true 后会下载原始画质的视频。

Config Channels Disable Location To Home (`docs/config/channels/disable-location-to-home.md`) Copy Section

title: 从详情页重定向到首页 Copy Chapter

从详情页重定向到首页

从「文件助手」打开视频号时，应该跳转至「视频详情页」，但某些版本会自动重定向到首页。该配置可以用于阻止自动跳转。

channels:
  disableLocationToHome: false

是否禁止从详情页自动跳转至首页，默认 false，会自动跳转。将 disableLocationToHome 设置为 true 后，会禁止自动跳转至首页。

Config Channels Enabled (`docs/config/channels/enabled.md`) Copy Section

title: 启用视频号功能 Copy Chapter

启用视频号功能

channels:
  enabled: true

是否启用视频号功能，默认 true。

Config Channels Force Check All Feeds (`docs/config/channels/force-check-all-feeds.md`) Copy Section

title: 批量下载时检查所有视频 Copy Chapter

批量下载时检查所有视频

channels:
  download:
    forceCheckAllFeeds: false

批量下载作者所有视频时是否强制检查全部视频，默认 false。

Config Channels Frontend (`docs/config/channels/frontend.md`) Copy Section

title: 前端下载 Copy Chapter

前端下载

channels:
  download:
    frontend: false

是否在前端完成下载和解密，默认 false，即创建后台下载任务。设置为 true 后，下载会在视频号页面中完成，无需调用后台下载能力。

前端下载长视频时可能失败，并且「下载目录」配置会失效，文件名也不支持使用 / 创建子目录。

Config Channels Pause When Download (`docs/config/channels/pause-when-download.md`) Copy Section

title: 下载时暂停播放 Copy Chapter

下载时暂停播放

channels:
  download:
    pauseWhenDownload: false

前端下载视频时是否暂停当前视频的播放，默认 false。设置为 true 后，下载完成时会继续播放。

Feature Mcp Commands (`docs/feature/mcp/commands.md`) Copy Section

title: MCP 命令 Copy Chapter

MCP 命令

MCP 中的“命令”以工具（tool）的形式提供。调用时由 AI 客户端传入 JSON 参数。

应用配置 Copy Chapter

get_config 将 internal/config/config.go 注册的应用配置放在 application_fields，将 adapter 提供的配置放在 plugin_fields，并在兼容字段 fields 中返回两者合集。每个字段还带有 source；插件字段额外带有 namespace。

update_config 的键必须来自 get_config。值必须符合字段类型和 options 枚举约束。配置文件使用原子替换方式保存；成功响应中的 restart_scheduled: true 只表示重启已经安排，不能据此宣称重启完成。调用方必须保存 restart_token，在连接恢复后调用 get_restart_status。只有响应同时满足 status: "completed"、restart_completed: true 和 config_applied: true，才能确认新进程已经运行且保存后的配置已经加载。pending 需要继续重试，failed 表示重启请求失败，config_mismatch 表示进程已更换但配置摘要不一致。

重启期间 HTTP、WebSocket 和 MCP 连接可能短暂断开，客户端应重新连接。若修改了 api.hostname 或 api.port，应改用新地址连接；stdio 客户端也需要更新 API 地址或重新启动。提交的值与当前值完全相同时不会写盘或重启。

Worker 部署 Copy Chapter

deploy_sph_worker 读取 cloudflare.accountId、cloudflare.apiToken、cloudflare.sphWorkerName、cloudflare.sphCookie 和 cloudflare.sphCredential，不会通过 MCP 参数传输这些敏感值。调用会覆盖同名远端 Worker，因此必须先获得用户确认。get_config 可用时，可先检查这些字段的 configured 状态。

内容解析与下载 Copy Chapter

::: danger 写文件操作
download_content 会写入下载目录，调用前应先确认下载目标和覆盖策略。existing_action: "overwrite" 会覆盖已有任务及文件。decrypt_wxchannels_video 会原地覆盖指定文件，只能在 fetch_content 返回 requires_decryption: true 时使用。
:::

微信视频号 Copy Chapter

这些工具通过已打开的视频号页面访问微信接口。先调用 get_wxchannels_status，确认返回的 available 为 true。

列表工具会保留微信接口的分页字段。继续翻页时，将上一页 data.lastBuffer 原样传给 next_marker；只有账号搜索使用 data.lastBuff。游标不需要解码或修改。

本地数据 Copy Chapter

本地数据工具均为只读，并支持用筛选参数减少返回量。Streamable HTTP 直接使用当前进程中的数据库与运行时服务；stdio 则通过下载器 API 查询相同数据。

Feature Mcp Enable (`docs/feature/mcp/enable.md`) Copy Section

title: 启用 MCP Copy Chapter

启用 MCP

正常启动下载器后，内置 MCP 默认关闭。打开页面 http://127.0.0.1:2022/ 点击左下角「设置 → MCP」可以查看连接地址并启用或停用服务。

设置页中的开关只在当前进程内生效，不写入配置文件；下载器下次启动时 MCP 会重新默认关闭。

默认地址为：

http://127.0.0.1:2022/mcp

手动开启 MCP 服务后，在 AI 客户端中新增 Streamable HTTP 类型的 MCP Server，并填入这个地址即可

也可以这样对 agent 如 codex 说

bash Copy

添加 MCP 服务，名称为 dm，地址为 http://127.0.0.1:2022/mcp ，类型为 Streamable HTTP

添加好之后就可以通过对话调用下载器的功能了，保持视频号页面打开状态 后，可以这样对 codex 说

使用 dm MCP 服务 查找昵称为 我不叫龙虾 的视频号账号，获取最新的10条视频

还可以这样说

使用 dm MCP 服务 查找昵称为 我不叫龙虾 的视频号账号，下载所有视频，跳过已下载的视频

对 codex 直接说出需求即可，现在还支持

• 下载视频评论列表
• 获取指定视频号账号的直播回放列表
• 获取视频详情
• 删除已下载的视频
• 下载指定链接的视频
• 获取已下载的视频列表

Feature Wxchannels Batch (`docs/feature/wxchannels/batch.md`) Copy Section

title: 下载作者所有视频 Copy Chapter

下载作者所有视频

在作者详情页会插入「批量下载」按钮，点击会获取到该作者的所有视频并创建下载任务，创建好下载任务后，并不会同时下载所有的视频，而是每次执行 3 个任务，直到所有下载任务完成

在下载列表面板可以看到有很多 wait 状态的下载任务，等先创建的任务完成后，会依次下载这些 wait 状态的任务

Feature Wxchannels Custom Menu (`docs/feature/wxchannels/custom-menu.md`) Copy Section

title: 自定义菜单 Copy Chapter

自定义菜单

可以在现有「下载按钮」的悬浮菜单中，增加自己的功能

增加「下载视频和封面」 Copy Chapter

在和 wx_video_download.exe 相同目录下增加一个 global.js 文件，内容如下

/* Detailed source-code truncated for AI context efficiency. */

Feature Wxchannels Event (`docs/feature/wxchannels/event.md`) Copy Section

title: 监听事件 Copy Chapter

监听事件

可以在视频号发生事件时，触发自定义脚本。本下载器的「插入下载按钮」、「在终端打印访问的视频」，都是基于该能力实现的

目前支持的事件有

• onFeed：加载了 feed（首页、详情、直播都会触发）
• onPCFlowLoaded：首页推荐获取到视频列表
• onRecommendFeedsLoaded：获取到推荐列表
• onUserFeedsLoaded：获取到指定用户的部分视频列表
• onGotoNextFeed：首页推荐切换到下一个视频
• onGotoPrevFeed：首页推荐切换到上一个视频
• onFetchFeedProfile：获取到视频详情
• onFetchLiveProfile：获取到直播详情
• beforeDownloadMedia：下载视频之前
• beforeDownloadCover：下载封面之前
• onMediaDownloaded：视频下载完成
• onMP3Downloaded：MP3 下载完成
• onDOMContentLoaded：DOM 完全加载和解析
• onDOMContentBeforeUnLoaded：DOM 加载完成前（页面即将离开，DOM 仍存在）
• onWindowLoaded：所有资源加载完成
• onWindowUnLoaded：页面卸载完成（DOM 即将被销毁）