video-downloader

视频下载器 2.0

边界

此技能负责完整的媒体预处理工作流：

video link or local file
→ acquire video and platform caption
→ usable timed platform subtitles, otherwise cloud ASR
→ choose keyframes / full-video / Agent clips
→ preview and confirm each exact cloud payload
→ Doubao image or native-video understanding
→ timestamped plain Markdown

最终交付文件为 multimodal_transcript.md，这是一个普通文本文件。Cangjie Skill 保持不变，只使用文本生成 Skills。不要将下载、ASR、帧、OCR 或视觉模型逻辑移入 Cangjie Skill。

要求

媒体处理所需：

• Python 3.10 或更高版本。
• ffmpeg 和 ffprobe。
• 用于 Bilibili、YouTube 和 Xiaohongshu 的 yt-dlp；某些平台也会将其用作备用方案。

可选：

• 用于云端 ASR 的 SILICONFLOW_API_KEY。
• 用于离线 ASR 的本地 whisper CLI。
• 用于 Doubao 视觉理解的 ARK_API_KEY。
• 用于首次进行 WeChat Channels 交互式授权的 Playwright。

速度默认值与质量权衡

• Bilibili、YouTube 和小红书优先选择恰好 1080p（--download-quality 1080p）。如果没有该画质，则下载可用的最高画质，即使是 4K；这不是分辨率上限。下载名称会包含画质偏好，因此旧的 4K 文件不会被误认为是新下载的 1080p 文件。其他提供方仍使用各自的画质控制选项。
• 微信视频号仍会在每次运行时刷新其链接配置和会过期的播放 URL，但只有通过媒体探测后，才会复用已有目标 MP4。需要刷新平台媒体本身时，请使用 --force-redownload。--force-reprocess 仍表示绕过 ASR/视觉结果缓存，不代表要下载媒体。
• --asr auto 优先使用可用且带时间信息的平台字幕（人工标注字幕优先于自动字幕）。没有字幕时，使用 SiliconFlow。自动字幕和 ASR 都可能出错：对每个视频而言，二者都不一定始终最准确。使用 --no-platform-subtitles 或 --asr siliconflow 可强制重新转录音频。
• 云端 ASR 使用约 60 秒的分块，尽可能在静音处切分，保留全部音频时长，并发请求数最多为四个。这些是音频识别分块，不是 10 分钟的视觉分块上限。
• Agent 场景检测会以 384px / 4fps 与语音处理并行运行，并会缓存。这是一种粗略的筛选辅助，不是 OCR 输入，也不是完整的镜头清单。
• CLI 原生视频并发数默认为四。预处理片段最高使用 720p、12 编码 fps、快速编码和压缩音频。提供方采样默认仍为 0.5fps；小字和快速 MV 剪辑可能仍需要更高采样率或专用关键帧。
• --vision-thinking disabled 可避免 Agent 筛选和原生视频分析产生深度推理延迟。可以显式请求 auto 或 enabled。这不会改变关键帧图像请求。视频请求最多允许 16,384 个输出令牌；不完整的响应属于失败，不能作为已完成的有效结果使用。
• 进度信息会标明每个处理阶段和每个云端分块。timings.json 会记录实际墙钟时间，以及本次运行是否达到 600 秒的目标。各阶段时间可能重叠，切勿直接相加。10 分钟是测试目标，不保证适用于任意视频时长、网络或 API 队列。
• Agent 筛选优先选择不同的技巧和演示内容，而不是重复的广告。如果初始计划未选择某些源视频时间段，会额外发送一次文本模型请求，使用相同的源材料检查遗漏；复核后的计划会被缓存。最终 Markdown 会列出未选择的视觉时间范围。所选时长的覆盖率不代表信息的准确性或完整性。
• 筛选输入会提供原始的 start_ms/end_ms，以减少时间转换错误。开头/结尾回退哨兵不会占用普通候选数量；因此，分块和哨兵可能会产生多于 --vision-max-clips 的执行文件。显式设置的正数总时长预算仍然适用。
• 转录文本线索会序列化为带数字毫秒时间值的 JSON 行。每次初始/复核文本请求遇到格式错误的 JSON 时，可在附加严格格式指导后重试一次；重复失败会停止筛选。此有限的格式重试独立于遗漏复核，不会静默接受被截断的响应。
• 如果已完成的原生视频响应存在无效时间戳/时间基准，系统最多会使用现有云端文件和显式相对边界重新观测一次。文件不会重新上传；时间戳不会被静默截断。第二次无效答案仍视为失败。只有在任务完成且耗时不超过目标时，才会设置 600 秒验收标记。

在 macOS 上：

brew install ffmpeg yt-dlp
python3 -m pip install playwright

Playwright 可以复用已安装的 Google Chrome。如果 Chrome 不可用：

python3 -m playwright install chromium

配置 Doubao Vision

视觉提供方使用 Volcano Ark Responses API 和 Files API：

• Responses 端点：https://ark.cn-beijing.volces.com/api/v3/responses
• Files 端点：https://ark.cn-beijing.volces.com/api/v3/files
• 图像/文本模型：--vision-model，用于关键帧和 Agent 文本选择；默认值为 doubao-seed-evolving。
• 原生视频模型：--vision-video-model，仅用于完整视频和所选片段分析；在 2026-08-30 成功通过非敏感合成视频冒烟测试后，默认值为 doubao-seed-evolving。
• 凭据：环境变量 ARK_API_KEY

这两个 CLI 参数保持独立，尽管目前使用相同的默认值。不要假设图像和原生视频能力在所有账户或未来的模型版本中都可以互换；如果当前账户的模型能力不同，请覆盖 --vision-video-model。

在当前终端中设置密钥：

export ARK_API_KEY="replace-with-your-new-key"

切勿将真实密钥放入 SKILL.md、源代码、提交到 Git 的命令、测试固件、截图或 metadata.json。

此技能使用的最简 API 格式：

curl https://ark.cn-beijing.volces.com/api/v3/responses \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-evolving",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_image", "image_url": "https://example.com/frame.jpg"},
        {"type": "input_text", "text": "请描述画面中的可见事实和屏幕文字。"}
      ]
    }]
  }'

本地关键帧以 Base64 数据 URL 发送。此技能存储标准化观察结果，而非完整的提供方响应。

对于完整视频和 Agent 片段分析，此技能会创建便于上传的 H.264 MP4；如果源文件包含音频，则保留压缩后的 AAC 音轨。它使用 purpose=user_data 上传处理后的文件，等待 Files API 状态变为 active，然后将 input_video + file_id 发送到 Responses API。最后会尽力删除上传文件；如果删除失败，会报告失败，而不会将其视为已成功清理。原生视频分析是 ASR 的补充，并不会取代 ASR，因为对内嵌音频的理解取决于所配置的视频模型。

与此工作流相关的 Files API 官方限制：

• Ark 托管存储接受的单个文件最大为 512 MB。此实现将完整视频代理文件控制在更严格的 480 MB 本地安全上限以内，通过流式多部分传输视频字节，而非将整个文件加载到内存中；如果代理文件过大，则会停止上传。目前不会自动拆分过大的完整视频代理文件。
• 支持扩展名为小写的 MP4、AVI 和 MOV，但容器格式受支持并不意味着系统能够识别其中的所有编码格式变体。
• URL 或 Base64 视频输入有单独的单个视频 50 MB 限制；此技能改用 Files API 路径上传处理后的视频。
• 视频预处理 fps 范围为 0.2 到 5。--vision-video-fps 0.5 表示 Files API 每两秒左右采样一帧作为模型输入；它不是代理文件的编码帧率，也不代表逐帧分析。
• 未显式设置过期时间的上传文件默认保留七天，且可配置为保留 1–30 天。此技能不会设置 expire_at；分析后会尝试立即删除文件，但如果删除失败，文件可能会一直留在托管存储中，直到过期。
• 提供方文档规定单个视频的上限为 80k 视频 token；所配置模型的上下文和输入上限可能更低。官方没有统一的“最长分钟数”数值，因此较长或变化较快的视频可能需要降低预处理 fps，或使用 Agent 选择的片段。

协议参考资料：

• Volcano Ark 视频理解
• Volcano VEADK Responses API 和 Files API
• 官方 Python SDK ResponseInputVideoParam

提供的 API 密钥绝不会写入代码库、上传计划、元数据、日志或 Markdown 输出。如果曾在聊天或文档中粘贴过密钥，请在 Volcano Ark 中轮换密钥，并仅将替换后的密钥保存在 ARK_API_KEY 中。

快速开始

在此技能目录中运行。

使用 ASR 和 Doubao 视觉能力的平台 URL：

python3 scripts/download_video.py "https://www.youtube.com/watch?v=..." \
  --output-dir ./downloads \
  --asr auto \
  --vision auto \
  --vision-mode agent-clips \
  --profile knowledge

当存在可靠的带时间戳 ASR 时，此交互式命令会分别预览并确认两个云端边界：首先是供 Agent 选择使用的带时间戳转录文本、平台字幕和场景索引；然后是精确选定的视频片段。如果没有可靠的带时间戳转录文本，选择将回退到本地场景信号，并且只有上传片段时才需要确认。在自动化场景中，--confirm-cloud-upload 是对本次运行中所有 Doubao 阶段的一次预先授权；它不是两次单独的人工确认。

--vision-plan-only 仅会阻止 Doubao 视觉请求。如果设置了 SILICONFLOW_API_KEY，--asr auto 可能已经将音频发送到 SiliconFlow。如果规划过程本身必须完全在本地运行，请使用 --asr whisper 或 --asr none。

本地视频：

python3 scripts/download_video.py "/absolute/path/demo.mp4" \
  --output-dir ./downloads \
  --local-caption "产品演示" \
  --local-author "作者名" \
  --asr auto \
  --vision doubao \
  --vision-mode keyframes \
  --profile tech

仅下载平台文本和元数据：

python3 scripts/download_video.py "https://v.douyin.com/..." \
  --output-dir ./downloads \
  --metadata-only

跳过任一轨道：

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr none \
  --vision doubao \
  --vision-mode keyframes
python3 scripts/download_video.py "/absolute/path/video.mp4" --vision none
python3 scripts/download_video.py "/absolute/path/video.mp4" --asr none --vision none

选择视觉模式

启用视觉分析时，用户必须选择一种模式。技能不得擅自决定哪些内容会离开本机。

模式	发送内容	优点	局限
keyframes	混合场景／间隔 JPEG 关键帧	Token 用量和成本最低	可能遗漏动态画面和未采样的信息
full-video	压缩后的 720p 视频，分割为最长 10 分钟的片段	覆盖完整源视频	输入更多；压缩可能损失细小文字
agent-clips	带时间戳的文本用于选择，随后发送限定时长的 MP4 片段	推荐的平衡方案	需要两个云端阶段，并且需要可靠的带时间戳 ASR 才能进行真正的 Agent 选择

在交互式终端中，如果省略 --vision-mode，将打开一个包含三个选项的菜单，并推荐 agent-clips。在非交互式运行中，省略此参数将以代码 2 退出。--metadata-only 和 --vision none 不受此限制。

keyframes 和 full-video 会在发送 Doubao 请求前写入并显示 vision_plan.json。agent-clips 会先写入 vision_selection_plan.json；只有完成选择和本地剪辑后，才会写入包含精确片段路径、大小和时长的第二阶段 vision_plan.json。用户回答 y，或自动化通过 --confirm-cloud-upload 对所有 Doubao 阶段进行一次预先授权后，才会发送 Doubao 请求。

使用 --vision-plan-only 准备所有当前可行的本地视觉材料，然后在发送任何 Doubao 请求前停止。在 Agent 模式下，如果需要云端文本选择，此参数会在 vision_selection_plan.json 阶段停止，因此无法提前显示精确的第二阶段片段计划。如果没有可用的带时间戳文本，本地场景回退仍可剪出候选片段，并在停止前写入精确的第二阶段 vision_plan.json。此标记不会禁用更早发起的 SiliconFlow ASR 请求；如需完全在本地运行规划过程，请选择本地 Whisper 或禁用 ASR。

1. 关键帧

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr none \
  --vision doubao \
  --vision-mode keyframes \
  --vision-plan-only

此模式会检测场景变化、添加固定间隔的覆盖采样、合并相近的时间戳、限制最终数量，并且只会在确认后分批发送小批量图像。

2. 完整视频

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr none \
  --vision doubao \
  --vision-mode full-video \
  --vision-video-model doubao-seed-evolving \
  --vision-video-fps 0.5 \
  --vision-plan-only

此技能会准备 H.264/AAC 视频，而不会上传原始文件。时长超过 --vision-max-clip-seconds（默认值为 600）的源视频会直接剪辑为连续片段，存放在 vision/clips/ 下；25 分钟的视频会分为 10 + 10 + 5 分钟。完整视频模式没有总时长或 Agent 候选数量上限。较短的源视频会使用 vision/full-video-proxy.mp4，分辨率最高为 1280×720，编码帧率为 12 fps。两种路径都会使用 --vision-concurrency（CLI 默认值为 4）、逐片段检查点和按源视频顺序合并。计划会列出每个已准备文件及其实际大小／时长；有效的缓存结果会重复使用，而不会再次上传。--vision-video-fps 0.5 控制的是服务提供方的采样，而非编码。较短源视频的代理文件仍受 480 MB 本地上限限制；已准备的片段则受 Files API 大小检查限制。

3. Agent 片段（推荐）

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr auto \
  --asr-language Chinese \
  --vision doubao \
  --vision-mode agent-clips \
  --vision-max-clips 8 \
  --vision-max-clip-seconds 600 \
  --vision-max-total-clip-seconds 0 \
  --vision-concurrency 4 \
  --vision-clip-padding-seconds 2

选择模型会接收完整的带时间戳转录文本、平台字幕、时长和场景时间戳。它应考虑无声演示／B-roll 画面以及开头和结尾的上下文，而不只是语音内容。返回的范围会经过验证、限制在有效范围内、补齐边界并合并。--vision-max-clips 8 限制拆分前的候选区间数量，而非执行分块数量。默认的 --vision-max-total-clip-seconds 0 不设总时长上限：所有选中的时间都会拆分为最长 600 秒的分块，因此，选中的 25 分钟区间会拆成 10 + 10 + 5 分钟，95 分钟的区间则可能拆成 10 个分块。设置明确的正数总预算可能会截断选择结果；未纳入的范围会在警告和最终 Markdown 中报告，包括因此遗漏的结尾。若源视频带有音频，每个处理后的片段都会保留 AAC 音频。

第二个预览会在原生视频分析前列出这些确切的片段。CLI 默认以受限的四路并发分析多个片段；进度显示为 [当前/总数]，结果会恢复为源视频中的顺序，并且每个片段都会单独上传、分析和删除云端文件。账号的速率限制允许时，可使用 --vision-concurrency 1 串行处理，或使用最高为 4 的并发数。--vision-video-fps 控制服务提供方对每个片段进行的帧采样，而非片段编码或逐帧检查。

进度会区分上传／预处理、模型分析、收到的记录数和清理操作。[i/total] 标识片段，而非已完成数量：片段 2 可能先于片段 1 完成。即使模型返回的分段顺序混乱，最终记录也会按原视频时间戳排序。若服务提供方明确标记响应不完整，即使其中包含可解析的 JSON，也会报告为错误。

原生视频提示词要求提供操作／镜头层面的证据，而不是简短摘要：相关按钮、参数、文件名、可见命令，以及 UI 操作前后的状态。不得将语音单独作为可见证据；不得猜测无法辨认的文字。十分钟是可配置的处理时长上限，并非已证实的准确度阈值。对于内容密集的录制视频，如果实际检查发现遗漏细节，请使用更小的 --vision-max-clip-seconds；不要仅凭输出记录数量推断准确度。为并发测试而手动将视频拆成前后两半，是一种手动验证策略，并不能证明 Agent 选择了这些边界。

如果用户请求了 ASR，但 ASR 仍在处理中或已失败，Agent 模式会等待完整的语音轨道，不会选择或上传视觉片段。使用相同设置重新运行，即可复用成功的 ASR 分块并继续处理。这样可避免临时 ASR 错误触发不必要的纯场景云端分析。如果用户明确选择 --asr none，或已完成的转录文本确实没有分段时间戳，该模式仍可回退到场景变化候选项以及开头／结尾哨兵项，并记录 selection_method: scene-fallback；它绝不会假装 Agent 将没有时间戳的文本映射到了视频。

有用的控制项：

--vision auto|doubao|none
--vision-mode keyframes|full-video|agent-clips
--vision-plan-only
--confirm-cloud-upload
--vision-model doubao-seed-evolving
--vision-video-model doubao-seed-evolving
--vision-video-fps 0.5
--vision-frame-interval 10
--vision-max-frames 24
--vision-scene-threshold 0.32
--vision-batch-size 4
--vision-max-clips 8
--vision-max-clip-seconds 600
--vision-max-total-clip-seconds 0
--vision-concurrency 4
--vision-clip-padding-seconds 2
--vision-prompt "额外关注……"
--force-reprocess

如果缺少 ARK_API_KEY，仍会完成可行的本地准备：可以创建关键帧或完整视频代理文件；在适用的情况下，Agent 模式至少可以生成选择计划或基于场景的回退材料。Vision 状态会变为 partial，Markdown 会报告信息缺口，而不会假装云端视觉分析已成功。

配置方案

选择一个：

配置方案	视觉重点
knowledge	框架、幻灯片、图表、示例、教学演示
tech	UI 状态、按钮、参数、代码、错误、前后对比结果
vlog	地点、动作、A/B-roll、情绪、环境、转场
mv	表演、色彩、构图、主题元素、镜头运动、节奏线索
short-video	开场钩子、字幕节奏、反转、CTA、镜头密度

单个视频可以展现可见的制作模式，但无法证明不可见的幕后工作流。所有推断出的工作流说法都应视为假设。对于创作者风格分析，至少使用 3 个视频，最好使用 5–10 个视频，再描述反复出现的方法。

输出约定

完成后的文件夹可以包含：

downloads/<platform>-<id>/
├── video.mp4
├── post_caption.txt
├── metadata.json
├── audio.mp3 or audio.m4a
├── transcript.txt
├── transcript.segments.jsonl
├── frames/
│   └── kf-0001-0000003500.jpg
├── frames.jsonl
├── visual_notes.jsonl
├── vision_plan.json
├── vision_selection_plan.json     # Agent mode
├── clip_selection.json            # Agent mode
├── vision/
│   ├── full-video-proxy.mp4       # Complete-video mode
│   ├── full-video-proxy.manifest.json
│   ├── clips/*.mp4                # Agent mode
│   └── clips/*.manifest.json      # Source/cache identity
└── multimodal_transcript.md

关键文件：

• post_caption.txt：原始平台标题、描述、主题标签或用户提供的本地说明文字。
• transcript.txt：仅包含音频的纯文本转录。
• transcript.segments.jsonl：ASR 后端提供分段信息时的标准化分段时间戳。
• platform_subtitles.json：恢复的平台字幕文本、实际字幕时间、语言，以及人工／自动生成来源信息。
• timings.json：各阶段的墙钟时间、视觉子阶段测量值和 600 秒目标结果。
• frames.jsonl：关键帧时间戳和采样原因。
• visual_notes.jsonl：可见事实、屏幕文字、动作、镜头备注，以及明确区分的推断。
• vision_plan.json：视觉上传的确切文件／数据类型、字节数、媒体时长、模型、限制、同意信息和执行状态。
• vision_selection_plan.json：供 Agent 选择使用的第一阶段转录文本／说明文字／场景索引上传计划。
• clip_selection.json：已验证的片段范围、原因、场景信号、回退状态和本地片段路径。
• *.manifest.json：源文件指纹和编码参数，用于在源文件路径不变但文件已更改时，避免复用过期代理文件／片段。
• multimodal_transcript.md：供下游分析或 Cangjie Skill 使用的最终纯文本交接文件。

对于跨越一段时间的视频观察，Markdown 附带的语音内容会按时间顺序包含所有时间戳重叠的 ASR 分段。单图观察则保留基于时间点的对齐方式。完整音频转录也会单独保留。

ASR

--asr auto 会先使用平台上可用的字幕轨道，然后使用有效的 ASR 检查点，最后在已配置时使用 SiliconFlow。如果缺少凭据或云端 ASR 失败，CLI 不会悄悄启动本地 Whisper。请提供 SILICONFLOW_API_KEY，明确选择 --asr whisper，或选择启用 --allow-local-asr-fallback。即使视觉分析成功，也不得将待处理或失败的语音轨道描述为完整转录。只有在明确允许本地回退时，特定于云端的模型名称才会映射为 Whisper base；已识别的 Whisper 模型名称会保留不变。显式指定 --asr siliconflow 不会切换服务提供方。

这里的“平台 ASR”指已有的字幕/转录结果，而非另一种识别技术：SiliconFlow 和 Whisper 也都是 ASR。默认优先级为：已有的平台转录 → SiliconFlow → 经用户批准的本地 Whisper（最慢）。CLI 和公开的 run_asr 函数都不会默认启用本地回退。

如果没有可用的转录且没有密钥，交互式 CLI 会询问用户选择 (1) 提供 SiliconFlow 密钥（输入时不回显），或 (2) 运行本地 Whisper。非交互式执行会返回 pending、action_required: choose_asr_backend 和两个选项，并以退出码 3 结束；它不会发起视觉请求，也不会进行不必要的场景扫描。**调用方 Agent 必须询问用户并让用户选择，然后继续执行；不得悄悄选择 Whisper、跳过语音处理或声称任务已完成。**如果密钥被拒绝、过期或发生其他云端故障，系统会报告该问题；未经明确授权，不得切换到 Whisper。选择启用 --allow-local-asr-fallback 仍属于明确授权，并非默认行为。

持久化 SiliconFlow 配置

如果 CLI 的环境中已存在非空的 SILICONFLOW_API_KEY，则会保留该密钥。否则会从 ~/.config/kangarooking-skills/video-downloader/env 读取该变量的原始值（文件权限必须为 0600，建议父目录权限为 0700）。这也适用于不会加载 shell 启动文件的桌面进程。Python 加载器不会执行 shell 内容。在所有者的机器上，新启动的 zsh shell 会通过 .zshenv 加载此私有文件；已经运行的 shell 进程可能需要加载该文件或重启。请勿将此私有文件复制到 Skill、Git、日志或测试产物中。仅在交互过程中输入密钥只影响当前运行；持久化存储需要用户提出请求。

指定的模型为 FunAudioLLM/SenseVoiceSmall。截至 2026-09-07， 官方价格页面将其列为免费；免费不代表吞吐量不受限制或延迟有保证。不得悄悄替换为付费/Pro 模型。对于 SiliconFlow，--asr-model base 是映射到此模型的兼容性别名，并非要求运行 Whisper base。

恢复与缓存

正常情况下，重新运行 CLI 时会根据源指纹、请求的后端/模型、语言、提示词和可选时长限制，复用 ASR 文本/时间戳。复用前会校验文本、原始 JSON 和分段产物的校验和。更改源或转录设置、文件缺失或文本损坏都会触发重新处理。--asr none 可显式禁用该轨道；如需复用，请使用相同的 ASR 设置。

Agent 文本选择会按完整的选择提示词和模型缓存，然后根据当前分块设置重新规范化。完整视频和 Agent 原生视频结果会在每个分块成功处理并完成云端清理后，以原子方式创建检查点。缓存键包含预处理文件指纹、时间上下文、配置文件/提示词、模型和采样 fps。失败的分块不会缓存；重新运行时会复用成功的分块，并重试缺失或失败的分块。--force-reprocess 会绕过 ASR、选择和原生视频结果缓存；媒体代理/片段指纹仍可确保安全复用编码结果。目前，关键帧分析会重新处理其图像批次，不受原生视频检查点缓存覆盖。

缓存位置包括 asr-cache/、asr-chunks/、vision/scene-cache/、vision/selection-cache/ 和 vision/analysis-cache/。原生视频检查点包含规范化后的响应文本、提供商用量以及上传/模型耗时，但不包含云端文件 ID 或凭据。缓存标识包含推理设置；ASR 标识还包含分块设置和云端服务可用性，因此新配置的云端 ASR 不会悄然复用旧的本地回退结果。预览计划会说明预处理后的候选载荷；缓存阶段可能不会发出请求，进度消息会对此进行提示。Responses、云端 ASR 分块、检索和删除调用的自动过载/服务器错误重试最多为 3 次；文件创建 POST 和结果不明确的超时不会自动重放。

后端：

--asr auto|siliconflow|whisper|none
--asr-model base
--asr-language Chinese
--asr-prompt "请使用简体中文转写。关键词：……"
--asr-chunk-seconds 60
--asr-concurrency 4

SiliconFlow 默认将 base/auto 设置为 FunAudioLLM/SenseVoiceSmall。Whisper 保留其常规模型名称。SiliconFlow 文档仅保证响应包含文本，不保证包含词级时间戳。因此，并行云端转录会将实际音频窗口范围标记为 timestamp_precision: chunk：60 秒的范围并不代表句子级对齐。渲染器会说明这一限制。平台提示会保留其实际时间戳；不含时间戳的整段文件文本仍可用，但不会伪造对齐信息。静音扫描失败时会回退到等长的连续音频分块。云端分块失败时会保留成功的检查点，但会将整体语音轨道标记为不完整。

官方参考资料：SiliconFlow 转录 API、Ark 推理配置。

微信视频号（实验性）

此技能已集成微信视频号支持，但该功能仍处于 experimental 阶段。模拟测试覆盖和一次公开分享链接端到端验证已于 2026-09-07 通过已保存的 Yuanbao 会话路径完成；这仅证明该测试路径可用，并不代表与所有账号、链接类型或未来的平台变更普遍兼容。该功能有三种路径。

路径 1：兼容的解析器 API

export WX_CHANNELS_API_URL="https://your-parser.example/api/channels/parse_sph"
export WX_CHANNELS_API_TOKEN="replace-if-needed"

python3 scripts/download_video.py "https://weixin.qq.com/sph/..." \
  --output-dir ./downloads \
  --asr none \
  --vision none

你也可以传入 --wechat-api-url。优先使用 WX_CHANNELS_API_TOKEN，而不是 --wechat-api-token，以免令牌出现在 shell 历史记录中。

路径 2：现有 Yuanbao Cookie

export WX_CHANNELS_COOKIE="hy_user=...; hy_token=..."
python3 scripts/download_video.py "https://weixin.qq.com/sph/..." \
  --asr none \
  --vision none

这适用于受控自动化，但环境变量和进程检查可能会暴露 Cookie。日常使用时，建议采用已保存会话路径。

路线 3：首次交互式授权

在真实终端中运行：

python3 scripts/download_video.py "https://weixin.qq.com/sph/..." \
  --wechat-login-timeout 300 \
  --asr none \
  --vision none

如果不存在有效会话，该技能会打开一个隔离的浏览器配置文件。完成一次微信／元宝登录；该技能会验证会话，仅存储 hy_user、hy_token 和 hy_source，然后继续。

默认受保护路径：

~/.config/kangarooking-skills/video-downloader/yuanbao-cookies.json
~/.config/kangarooking-skills/video-downloader/yuanbao-browser-profile/

Cookie 目录权限为 0700；Cookie 文件权限为 0600。该技能不会读取用户常用的 Chrome 配置文件。

实用标志：

--wechat-login
--no-wechat-auto-login
--wechat-login-timeout 300
--wechat-cookie-file /private/path/yuanbao-cookies.json
--wechat-api-url URL
--wechat-api-token TOKEN
--force-redownload

每次运行时，提供方都会刷新元数据和即将过期的播放 URL，但默认会复用确定性输出路径下已有的有效 MP4，以保持 ASR 和视觉缓存稳定。损坏或为空的文件会重新下载。如果直接解析失效，请使用 kg百宝箱 合法保存视频，然后将本地文件传给同一个 CLI。ASR 和视觉处理流程保持不变。

提供方行为

• 抖音：优先使用 H5 路由，然后回退到 yt-dlp。
• Bilibili：使用 yt-dlp 获取元数据和字幕，并尽可能合并为 MP4。
• YouTube：使用 yt-dlp；必要时可能使用本地 Node、远程组件或浏览器 Cookie。
• 小红书：使用 yt-dlp，并在需要时回退到浏览器 Cookie。
• 微信视频号：使用兼容的 API 或元宝授权；目前为实验性功能。
• 本地文件：无需复制；会探测并以只读方式复用源媒体。

失败状态

• done：请求的阶段已完成。
• planned：已创建本地产物和上传计划，但尚未发起 Doubao 请求。
• partial：存在有用的产物，但后端或帧批次不可用。
• failed：该阶段未能生成可用输出。
• skipped：用户已禁用或不适用。

不要仅凭文件是否存在来判断任务已完成。请检查总体 status、asr.status、vision.status 和错误信息。CLI 退出代码：已完成或明确计划／跳过的工作为 0；请求的阶段失败（包括 ASR）为 1；参数／交互无效为 2；请求的处理部分完成／待处理为 3。ASR 错误和片段覆盖率警告会包含在 Markdown 中。原生视频记录必须包含明确、有限、在范围内且长度为正的时间戳，并有观察到的证据；缺失时间戳、空记录和超出范围的区间不会被静默补全，也不会计作有效覆盖。

安全与隐私

• 仅下载用户拥有、获准下载或可依法归档的内容。
• 不得绕过 DRM、付费访问、私人权限或平台访问控制。
• 临时签名视频 URL、原始微信 API 配置文件、Cookie、Bearer 令牌和 API 密钥不会包含在公开产物中。
• 根据所选模式，关键帧、压缩视频代理、带时间戳的转录／字幕／场景时间戳或选定片段，只会在交互确认后，或在非交互运行中预先使用 --confirm-cloud-upload 授权后，才会发送到 Volcano Ark。在交互使用中，Agent 模式的两个 Doubao 阶段会分别预览；自动化标志会预先授权这两个阶段。使用 --vision-plan-only 检查当前可用的视觉处理范围；对于绝不能发送给视觉提供方的材料，请使用 --vision none。
• --vision-plan-only 不会控制 SiliconFlow ASR。如果源音频或转录内容不得离开设备，请使用本地 Whisper 或禁用 ASR。
• 云端文件删除尽力而为。请检查报告的清理错误；删除失败时，不要假定文件已在配置的过期时间前移除。
• 创作者分析可以提取通用方法，但未经许可，不应克隆某人的声音、面容、受版权保护的资产或逐帧创作表达。