Videodevour

VideoDevour 视频转图文报告

Goal

调用 VideoDevour 项目（本仓库），把视频端到端处理为中文图文报告 （ASR 转写 → 大纲 → 视频切分 → 关键帧 → 图文报告），不依赖 Web 界面。 产出三层内容：图文大纲 / 精简报告（结论先行）/ 详细报告（完整原文+笔记对照）； 可按需改写成量子速读 / 公众号文章 / 小红书笔记，并导出 PDF。 项目同时把每次任务的产物沉淀为本地文档库，可跨任务检索复用（见第 11 节）。

必要输入

• 视频来源：B站/YouTube/抖音/X 链接、微信视频号分享链接（weixin.qq.com/sph/...，可直接粘贴含链接的分享文案）、或本地视频文件路径（MP4 等）
• 可选：学习阶段（自由学习[默认]/小学/初中/高中/大学/硕士/博士/深入研究/垂直领域研究）

使用前检查（首次使用时执行一次）

1. 项目根目录按以下顺序解析（脚本已内置，无需手动指定）： --home 参数 → VIDEO_DEVOUR_HOME 环境变量 → 脚本所在仓库 → 默认安装路径。
2. 确认项目虚拟环境已就绪（不存在则执行 cd <项目目录> && uv sync，用 Python 3.12）； 脚本会自动切换到 .venv 运行。
3. ASR/LLM/VLM 配置读取项目根目录 settings.json；LLM/VLM 需要 key。 ASR 默认走在线（云端识别，零模型下载）；仅当用户要用本地离线 ASR 时，才需下载 约 2GB 模型：设置页切到「离线」会显示自检结果与安装命令，或执行 bash scripts/install_offline_asr.sh。缺 key 时提示用户在 WebUI 控制台（/settings）填写。
4. 导出 PDF 依赖 reportlab（已写入 requirements.txt / requirements-lite.txt）， 执行过 uv sync 即可用。

Workflow

以下 <skill目录> 指本 SKILL.md 所在目录（.agents/skills/videodevour）。

1. 搜索视频（用户只给了关键词时）

# B站（默认）
python3 <skill目录>/scripts/devour.py search "关键词" --platform bilibili --max 5
# YouTube
python3 <skill目录>/scripts/devour.py search "关键词" --platform youtube --max 5
# 抖音（需要登录 Cookie，见第 4 节）
python3 <skill目录>/scripts/devour.py search "关键词" --platform douyin --max 5

输出 JSON 列表（标题/时长/UP主/链接），交给用户选择或选最匹配的一条。

• 抖音搜索需要登录态 Cookie（匿名会返回「请先登录」）。未配置时脚本会明确提示； 抖音另有 a_bogus 浏览器签名校验，若接口触发人机校验，脚本会给出「改用浏览器搜索后 粘贴链接」的引导，而非静默返回空结果。
• 微信视频号不支持搜索，只能粘贴分享链接（见第 3 节）。

2. 查看链接信息（可选，用户想先预览时）

python3 <skill目录>/scripts/devour.py info "https://www.bilibili.com/video/BV..."

输出标题/UP主/时长/封面 JSON。注意：多P合集的 BV 链接，info 返回的时长是合集总时长， 而 process 只下载并处理当前分P（通常几分钟），不会被合集时长吓退。

3. 微信视频号（weixin.qq.com/sph/... 分享链接）

# 首次使用先检查元宝 Cookie（视频号解析依赖腾讯元宝接口登录态）
python3 <skill目录>/scripts/devour.py wechat --check
# 下载视频号视频到项目 uploads/（仅下载，返回 JSON：file_path/title/uploader）
python3 <skill目录>/scripts/devour.py wechat "https://weixin.qq.com/sph/..."
# 也可直接粘贴含链接的分享文案；下载后接 process 本地文件即得图文报告

• Cookie 未配置/失效时 --check 会明确返回并给出配置指引；配置方法见 README 「微信视频号 Cookie 配置」一节（WebUI 设置页或 settings.json / 环境变量均可）
• process 命令同样直接支持视频号链接（自动先下载再处理），wechat 用于只要视频文件的场景
• 直播回放、已过期分享链接无法解析；解析失败会返回中文引导

4. 抖音（douyin.com/video/{id}、v.douyin.com 短链）

# 检查抖音登录 Cookie 是否已配置
python3 <skill目录>/scripts/devour.py douyin --check
# 下载抖音视频到项目 uploads/（仅下载，返回 JSON：file_path/title/uploader）
python3 <skill目录>/scripts/devour.py douyin "https://www.douyin.com/video/7624464836100967732"
# 短链与分享文案均可（自动跟随重定向、提取链接）
python3 <skill目录>/scripts/devour.py douyin "https://v.douyin.com/xxxxxx/"

• 下载需要登录态 Cookie：在设置页「抖音 cookies」填写，或点「一键读取浏览器 Cookie」 自动获取（需浏览器已登录抖音）；也可写入 settings.json 的 douyin_cookies。 Cookie 缺失或失效时，脚本返回明确的配置指引。
• 抖音下载走 App 接口直连（aweme.snssdk.com）：web 端接口自 2026 起受 Argus 浏览器签名校验拦截，仅带登录 Cookie 也会返回 403 Blocked by ArgusSecurityPlugin， yt-dlp 会把它误报成「Fresh cookies are needed」。看到该提示时不要反复重配 Cookie， 先确认下载是否已走 App 接口成功；仅当 App 接口也失败时才需要重新读取登录态。
• 支持三种链接形态：douyin.com/video/{id} 视频页、douyin.com/note/{id} 图文、 含 ?modal_id={id} 的搜索页链接、v.douyin.com 短链（脚本自动归一化）。
• 下载默认取 720p H.264（抖音的 bytevc1/H.265 直链会 403，脚本已固定选 H.264 档， 优先不超过 720p 的最高可用画质）。该档通常是带抖音水印的 download_addr； 需要干净画面（如关键帧配图）时设 VIDEO_DEVOUR_DOUYIN_CLEAN=1，改为优先无水印源 （分辨率可能更低）。
• process 命令同样直接支持抖音链接（自动先下载再处理）；douyin 用于只要视频文件的场景。

4b. X（Twitter）链接（x.com / twitter.com 推文）

# 下载 X 推文视频到项目 uploads/（仅下载）
python3 <skill目录>/scripts/devour.py process "https://x.com/{user}/status/{id}"
# 或只下载不处理：info 查看 / process 处理，均支持 X 链接

• 下载需要登录态 Cookie：X 对未登录访问限制较严。在设置页「X cookies」填写，或点 「一键读取浏览器 Cookie」/「应用内登录读取」自动获取（需含 auth_token）；也可写入 settings.json 的 x_cookies。未登录时 yt-dlp 常返回「No video could be found」。
• 支持 x.com / twitter.com、/{user}/status/{id}、/i/status/{id}、/i/web/status/{id}、 mobile.twitter.com、带 ?s= 追踪参数等形态（脚本自动归一化）。
• X 不支持关键词搜索（需要登录 GraphQL），只能粘贴推文链接。
• process 命令同样直接支持 X 链接（自动先下载再处理）。

5. 字幕速记（B站/YouTube，秒级纯文本笔记）

不下载视频、不走 ASR：直接读取平台已有字幕（B站 AI 字幕轨 / YouTube 手动或自动字幕）， LLM 整理为纯文本要点笔记。适合"只要文字内容、要快"的场景。

python3 <skill目录>/scripts/devour.py notes "https://www.bilibili.com/video/BV..." --level 高中

输出 JSON：notes 为 Markdown 笔记全文（含 ```mermaid 概念关系图）、 file（.txt 纯文本）/ md_file（.md 含关系图）落盘路径。注意：视频没有字幕轨时 报错并建议改走 process 完整流程；YouTube 无 cookies 或被 bot 检查拦截时提示配置 「YouTube cookies」（设置控制台，可一键读取浏览器 Cookie）。

6. 一键处理（核心流程）

python3 <skill目录>/scripts/devour.py process "https://www.bilibili.com/video/BV..." --level 高中
# 或抖音 / 视频号 / 本地文件：
python3 <skill目录>/scripts/devour.py process "https://www.douyin.com/video/..." --level 高中
python3 <skill目录>/scripts/devour.py process /path/to/video.mp4 --level 初中

• 命令是同步阻塞的，bash 超时请设为 600000ms（10分钟）以上；10 分钟内的视频一般 2-5 分钟完成 （90 分钟以上的长视频，详细报告分段生成需 10 分钟以上，请把超时再放大）
• 下载缓存：同一视频之前下载过会直接复用本地文件（<数据根>/downloads/，映射表 index.json 记录来源 URL/平台/标题/命中次数），不重复下载；换链接形式（短链/搜索页链接） 也能命中同一缓存（按「平台+视频ID」为键）。
• 处理前会自动把视频压到 720p / 10fps / H.264 再转写与抽帧（省时省存储）；压缩结果大于原文件时保留原文件
• 输出为逐阶段进度日志，成功结束时打印 JSON 结果，关键字段：
  • report：精简报告（结论先行，快速阅读）
  • detailed_report：详细报告（完整视频原文 + 整理笔记对照，原文不截断）
  • outline：图文大纲（章节 + 关键帧）
  • keyframes：关键帧图片路径数组
  • media_profile：压缩前后体积与分辨率（确认存储收益时看这个）
  • styles：已生成的衍生文体（未生成时不出现，见第 8 节）
• ASR 模式跟随 settings.json（默认在线 DashScope/StepFun；离线=本地 MPS/CUDA/CPU， 需先装模型），LLM/VLM 固定走云端
• 关键帧策略：按大纲章节均匀采样固定帧数（默认每章 10 帧，VIDEO_DEVOUR_FRAMES_PER_CHAPTER 可调），再由 VLM 评分挑选每章最佳一张——不随视频长短暴增候选帧
• 思维导图/知识图谱/学习卡片默认不生成（为不需要的用户节省时间）。用户明确需要时， 加 --extras "mindmap,graph,card"（可任选其一或多个，逗号分隔）在报告完成后一次生成； 也可事后用 mindmap / graph 子命令单独生成。不要在用户未要求时主动生成

7. 生成思维导图与知识图谱（仅用户需要时）

基于任务报告生成两种知识可视化（LLM 生成、浏览器渲染的交互页面）：

# 思维导图：三层分支结构（markmap 渲染，可缩放/折叠）
python3 <skill目录>/scripts/devour.py mindmap --latest --open
# 知识图谱：概念关系力导向网络（节点按类别着色、关系标注）
python3 <skill目录>/scripts/devour.py graph --latest --open
# 也可用 --dir 指定任务输出目录、--level 指定学习阶段

输出 JSON {"html": "<输出目录>/mindmap.html", ...}，将 html 路径呈现给用户（浏览器打开即用）。 若在 process 时已用 --extras 生成过，直接使用输出 JSON 中 extras 里的路径，无需重复生成。