video-to-article 技能

目标

把一个视频整理成可发布的图文文章，适合公众号、CSDN、总结报告或普通 Markdown 文档。

适用场景

• 用户给出一个本地视频，希望提炼内容并生成文章
• 用户给出一个视频 URL，希望先下载，再继续做转写和写作
• 用户需要按视频时间轴匹配配图，而不是依赖图像理解模型

关键原则

1. 优先使用本技能目录下的脚本，不要自行重造相同流程。
2. 在 Windows 上默认使用 python，不要写死成 python3。
3. 下载视频时优先调用 scripts/video_downloader.py。
4. 转写音频时优先调用 scripts/video_to_text.py。
5. 图片与字幕的匹配必须基于时间轴，不要调用图像理解类 skill 来“猜”画面内容。
6. 如果用户已经明确要直接生成结果，不要为了补齐信息反复追问。只在必要时问 1 到 2 个问题，否则用合理默认值继续。

前置检查

在执行流程前，先确认以下事实：

• 当前环境里是否存在 python
• 如果要下载在线视频，是否允许联网
• 如果要做首次转写，是否允许下载 Whisper 模型
• 输入是本地视频文件，还是在线 URL

标准流程

1. 明确目标

优先确认以下信息；如果用户已经说清楚，不要重复问：

• 输出类型：公众号、博客、总结、普通 Markdown
• 是否需要配图
• 文章风格：客观总结、教程、评论、种草、复盘等

2. 判断输入类型

情况 A：用户提供在线视频 URL

先下载视频，再走后续流程。

使用命令：

python scripts/video_downloader.py "<视频URL>" "1080p" "<输出目录>"

说明：

• 第一个参数是视频 URL，必填
• 第二个参数是目标分辨率，可选，如 1080p、720p
• 第三个参数是输出目录，可选；不填则由脚本使用临时目录
• 该脚本已经兼容 Windows 上只有 python、没有 python3 的情况
• 脚本内部会自动调用 yt-dlp，必要时自动合并音视频流，并清理文件名

如果下载失败，优先排查：

• 网络访问是否被沙箱、系统防火墙或代理策略拦截
• 目标站点是否对当前网络环境有限制
• yt-dlp 依赖是否可导入

情况 B：用户提供本地视频路径

直接进入转写流程，不需要下载。

3. 语音转文本

使用命令：

python scripts/video_to_text.py --input "<视频文件路径>" --language zh

可选参数：

• --output-dir "<目录>"
• --output-path "<基础输出路径>"
• --model-size base|small|medium|large-v3
• --language auto|zh|en
• --device cpu|cuda

说明：

• 首次运行会下载 Whisper 模型到 scripts/models
• 如果没有网络，且本地没有对应模型，脚本会失败
• 在 Windows 上建议用 python
• 该脚本会输出 .srt 和 .txt

4. 截取关键帧

使用本目录里的相关说明和脚本进行抽帧。对讲解类、财经类、静态画面较多的视频，不要轻易启用“跳过相似帧”，否则会漏图。

5. 基于时间轴匹配图文

做法：

1. 读取 .srt
2. 读取抽帧结果，例如 frames/result.json
3. 按时间区间把截图路径插入到对应字幕段附近
4. 生成中间稿，再继续写作

禁止做法：

• 不要让模型通过“看图”来判断字幕该配哪张图
• 不要把时间轴匹配替换成纯语义猜测

6. 写作

写作时遵循以下规则：

• 优先遵循用户指定风格
• 如果用户没有给风格，参考 assets 目录下模板
• 只使用时间轴上匹配得到的图片
• 图片数量由视频长度与内容密度决定，不要机械平均分配

推荐命令模板

下载视频

python scripts/video_downloader.py "https://www.bilibili.com/video/BVxxxx" "720p" ".\\downloads"

转写视频

python scripts/video_to_text.py --input ".\\downloads\\demo.mp4" --output-dir ".\\transcripts"

常见坑

1. python3 不存在

在很多 Windows 环境里只有 python，没有 python3。本技能内的调用说明统一使用 python。

2. 下载脚本报 “找不到指定的文件”

通常是旧版写法把 yt-dlp 子进程写成了 python3 -m yt_dlp。当前脚本已经改成复用当前解释器。

3. 下载或转写时报 WinError 10013

这通常不是脚本语法错误，而是网络访问权限被拦截。常见来源：

• 沙箱限制
• 本机防火墙
• 安全软件
• 代理或公司网络策略

4. 转写脚本第一次运行失败

常见原因是 Whisper 模型还没下载成功。需要允许联网，或者提前把模型缓存到 scripts/models。

5. 控制台出现 Hugging Face symlink 警告

这不是致命错误，只是提示 Windows 没开启开发者模式，缓存会更占磁盘。

对其他模型的执行指令

如果你是后续接手该技能的模型，请按下面顺序工作：

1. 先判断输入是 URL 还是本地文件。
2. 需要下载时，调用 python scripts/video_downloader.py ...。
3. 需要转写时，调用 python scripts/video_to_text.py ...。
4. 如果失败，先判断是网络/权限问题，还是代码/依赖问题，不要直接归因为“脚本坏了”。
5. 需要给用户解释失败原因时，优先说清楚是：
• 解释器问题
• 依赖问题
• 网络权限问题
• 模型下载问题
6. 不要在 Windows 指南里继续写 python3。
7. 不要用图像理解代替时间轴匹配。

依赖

• Python 3.11 或 3.12
• yt-dlp
• ffmpeg
• faster-whisper
• av
• opencc-python-reimplemented

输出

最终文章通常输出为与视频同目录或指定目录下的 Markdown 文件，例如：

• <视频名>_article.md

更新记录

• 2026-03-20：初版工作流
• 2026-03-21：加入视频 URL 下载
• 2026-03-21：明确图文按时间轴匹配
• 2026-04-21：修正文档中的 python3 误导，补充 Windows 兼容说明、模型下载说明与常见故障排查