Video Understanding

Video Understanding v0.2.3

0. 定位

v0.2.0 从“URL 解析器”升级为 Upload-First Agentic Video Understanding。

默认优先级：

理解质量 > 证据完整 > 速度 > 资源节省

入口优先级：

当前聊天已上传视频
> Bilibili URL
> YouTube URL

用户只需：

• 上传视频；或
• 发送一个支持的 URL。

不要求用户：

• 手动切视频；
• 手动抽帧；
• 自己跑 Whisper；
• 自己操作 job_id；
• 自己决定章节范围；
• 长视频手工分段后重复上传。

1. Canonical 与真实性边界

唯一规范主源：

• Repo: 1948666760dty-sys/agent-skills
• Skill: skills/video-understanding/SKILL.md
• Runtime: skills/video-understanding/runtime/
• Runtime contract: skills/video-understanding/references/runtime-contract.md

必须区分：

1. Skill 规则存在；
2. Runtime 代码存在；
3. 当前宿主是否能访问视频附件/URL；
4. 某次 ASR/视觉/回看是否真实成功。

不得因为 Skill 已加载就声称“已经看完视频”。

2. 自动触发

2.0 固定主触发词

用户说 “深度看” 时，只要当前回合或当前视频上下文存在视频附件 / Bilibili / YouTube 输入，视为 Video Understanding 的最高优先级强触发：

深度看
→ Video Understanding
→ mode=deep
→ Quality-First

不得把“深度看”解释成普通图片查看、简短摘要或其他旧任务；若当前存在多个视频，绑定最近明确选中的视频，否则绑定当前回合附件。

2.1 上传视频强触发

当当前对话包含视频附件，且用户表达以下任一语义时自动触发：

• “看一下”
• “总结”
• “这个讲了什么”
• “深度看”
• “分析这个视频”
• “帮我理解”
• “试试看”
• 直接上传视频后继续询问其中内容

若用户只上传视频而无其他明显意图，默认解释为： 请理解并概括这个视频。

宿主已经能直接读取/挂载附件时，不得反过来要求用户提供 URL。

2.2 URL 强触发

Bilibili：

• bilibili.com
• b23.tv
• BV / av / ep / ss

YouTube：

• youtube.com/watch
• youtu.be
• youtube.com/shorts

单独一个支持 URL 默认视为视频理解请求。

2.3 后续问答

同一视频上下文中的：

• “19分钟那个表格”
• “第二种方法”
• “他这里说的靠谱吗”
• “前后有没有矛盾”

继续使用当前 Video Capsule / cache，不重新完整处理。

3. 默认模式

Deep（默认）

mode: deep
priority: quality
transcript: full
scene_detection: adaptive
visual_overview: true
host_vision_ocr: true
chapters: true
video_memory: true
agentic_rewatch: true
evidence_labels: true

Quick（用户显式要求）

触发：

• “快速看”
• “简单总结”
• “只看字幕”
• “不用看画面”

Quick 可以减少视觉覆盖与二次回看，但仍必须如实标记证据来源。

4. 输入路由

A. 当前聊天视频附件（Mobile / Native 优先）

若宿主直接提供可读视频文件：

1. 读取附件；
2. Preflight；
3. 有可信字幕则使用字幕；
4. 否则本地/宿主 ASR；
5. Deep 时执行场景分析和关键帧；
6. 建立 Chapters + Evidence Memory；
7. 全局理解后自动回看重点。

手机端与电脑端在默认质量策略上平等。
不得仅因为附件来自 Android/iOS/移动端，就自动：

• 切 Quick；
• 降低 ASR 完整度；
• 显著减少场景覆盖；
• 跳过二次回看；
• 只做字幕摘要。

若移动端宿主能够持续执行当前任务，允许长视频使用接近或超过视频时长的处理预算。例如：

• 60 分钟视频可允许约 120 分钟甚至更久；
• 复杂、无字幕、重视觉内容允许超过 2× 播放时长。

“允许长时间处理”不等于“后台异步保证”。若当前宿主/会话不支持离开聊天后持续执行，不得承诺关闭 App 后仍会在两小时后自动交付。

若通过 MCP Runtime 处理上传文件：

• 只能使用宿主已 materialize 到受控 upload inbox 的文件；
• Runtime 不允许任意读取电脑文件；
• 默认允许目录是 ~/.video-understanding/inbox；
• 额外目录必须显式配置 VIDEO_UPLOAD_ROOTS。

若宿主没有向 MCP 暴露视频附件字节或受控本地路径，不能虚构“已传给 Runtime”。

B. Bilibili

URL/短链/ID
→ 元数据/分P
→ 人工字幕
→ AI字幕
→ 无字幕本地 ASR
→ Deep 视觉
→ 可选弹幕

C. YouTube

URL/Shorts
→ 元数据
→ 人工字幕
→ 自动字幕
→ 无字幕本地 ASR
→ Deep 视觉

5. Preflight

上传/获取视频后先确认：

• 时长；
• 分辨率；
• FPS；
• 文件大小（若可得）；
• 字幕来源；
• ASR 是否需要；
• 是否可做视觉分析；
• 长视频 tier；
• audio_present；
• audio_decodable；
• speech_transcribed；
• decoded_until_seconds；
• visual_coverage_ratio。

音轨存在、音频能解码、语音已经转写是三个不同状态。
不得再把“没有 Whisper/ASR”表述成“听不到声音”。

Preflight 不需要用户参与。

6. 长视频策略

长视频不是“把更多 token 一次塞进去”，而是分层取证。

6.1 自适应 Tier

参考 Runtime：

这些是 Runtime 默认策略，不是固定 SLA；场景切换仍会额外贡献代表帧。

6.2 长视频处理流程

完整字幕/ASR
↓
结构章节 Chapters
↓
重叠 Evidence Memory
↓
PySceneDetect AdaptiveDetector
↓
自适应全局关键帧
↓
第一遍 Global Pass
↓
发现核心/可疑/低置信度区间
↓
Search Memory / Transcript Window
↓
Dense Agentic Rewatch
↓
最终综合

6.3 上下文保护

30 分钟以上默认不得把完整字幕和所有帧一次性注入模型。

先使用：

• Chapters；
• Evidence Memory；
• 主题/问题检索；
• 时间窗口。

再读取相关：

• transcript；
• overview frames；
• dense rewatch frames。

因此 1～3 小时视频在架构上可以处理，不依赖单次超长上下文。

6.4 超长视频

3 小时仍允许处理，但应：

• 更稀疏全局覆盖；
• 更多依赖章节索引；
• 按问题/主题检索；
• 必要时多轮局部 rewatch。

不得承诺任意长度都能在固定时间完成。

真正上限仍受：

• 宿主上传大小；
• 本地磁盘；
• 下载速度；
• ASR速度；
• GPU/CPU；
• Runtime/会话超时。

7. ASR

优先级：

人工字幕
> 平台自动/AI字幕
> faster-whisper

上传文件若宿主未提供可信字幕，默认 ASR。

如果 ASR 依赖缺失或执行失败：

• 不得让整个视频任务直接失败；
• 保留音频存在/可解码状态；
• 保留视觉结果；
• speech_transcribed=false；
• Completion Guard 通常判为 PARTIAL；
• 明确写“音频正常但未完成语音转写”，而不是“听不到”。

参考 Runtime 使用 faster-whisper >=1.2.1。当前 faster-whisper 仍支持 batched inference、VAD 与本地运行；不得因为 CUDA 尝试失败就声称 GPU ASR 成功。

ASR 高风险：

• 人名；
• 型号；
• 数字；
• 缩写；
• 方言/口音；
• 多人重叠。

关键数字必须尽量结合画面复核。

8. 场景检测与全局视觉

v0.2.0 参考 Runtime 使用 PySceneDetect AdaptiveDetector，而不是 v0.1 的简单直方图阈值。

要求：

• 自动 downscale；
• 快运动场景尽量减少误切；
• scene representative frame；
• baseline frame；
• 长视频控制 overview 总帧预算；
• 不因场景过多而无限保存帧。

若 PySceneDetect 失败： → baseline fallback； → 明确 warning； → 不把 fallback 冒充 scene-aware 成功。

9. Evidence Timeline

每个证据尽量包含：

• timestamp/start/end；
• source；
• confidence；
• evidence type。

证据类型必须分离：

1. speaker/subtitle
2. visual
3. host-vision OCR
4. platform metadata
5. audience/danmaku
6. model inference
7. external verification

作者声称 ≠ 已证实事实。

10. Chapters

Runtime Chapters 默认只是结构导航窗口，不能把未经模型处理的固定时间窗伪装成“语义章节”。

结构章节可以包含：

• start/end；
• transcript segment count；
• preview；
• characters；
• title=null；
• summary=null。

宿主模型完成第一遍理解后，可以生成语义标题/摘要。

11. Video Memory

每个视频构建重叠 transcript Evidence Chunks。

后续问题：

问题
→ search Video Memory
→ 得到候选时间窗口
→ transcript 验证
→ 重要视觉问题 dense rewatch
→ 回答

v0.2.0 参考 Runtime 使用免费本地 lexical/BM25-like 检索，不要求额外 embedding API。

检索结果只能作为候选证据，不能代替最终核验。

12. Agentic Rewatch

Deep 必须允许二次回看。

第一遍发现：

• 数字；
• 表格；
• 实验；
• 代码；
• 价格；
• 前后冲突；
• 字幕不确定；
• 画面信息明显高于口述；
• 用户直接问某个时间点。

则生成 rewatch window，再调用高密度帧。

例如：

{
  "start_seconds": 1120,
  "end_seconds": 1270,
  "reason": "关键实验结果/图表",
  "density": "dense"
}

13. Video Capsule

分析完成后维护轻量 Capsule：

Video ID
Input kind
Duration/Tier
Transcript source
Chapters
Topics
Claims
Important numbers
Important frames
Uncertainties
Rewatch history
Evidence memory

后续问答优先复用 Capsule/cache。

14. Runtime Tools v0.2

参考 MCP Runtime 当前工具：

1. start_video_analysis — B站/YouTube URL
2. start_uploaded_video_analysis — 受控 inbox 中的上传文件
3. wait_video_analysis
4. get_video_manifest
5. get_video_transcript
6. get_video_chapters
7. search_prepared_video
8. inspect_video_window

长任务内部 start/wait 不得交给用户操作。

推荐长视频宿主序列：

start
→ wait
→ manifest
→ chapters
→ transcript/windows
→ overview frames
→ first-pass synthesis
→ search_prepared_video
→ dense rewatch
→ final synthesis

15. 默认输出

中文默认：

1. 30 秒摘要
2. 核心结论
3. 章节/完整时间轴
4. 关键画面
5. 重要数字、参数、专名
6. 作者观点与证据
7. 画面与口述是否一致
8. 矛盾/不确定/待核查
9. 最值得看的时间段
10. 后续可问方向

顶部必须真实标记：

• 输入：上传 / B站 / YouTube
• 时长/Tier
• completion：COMPLETE / PARTIAL / FAILED
• audio_present / audio_decodable / speech_transcribed
• transcript source / transcript coverage
• decoded_until / visual coverage
• OCR = host_vision 或实际本地 OCR
• second-pass 是否真实执行

15.5 Completion Guard

最终输出“看完了 / 分析完成”前必须通过 Completion Guard。

Audio State

必须分别报告：

audio_present
audio_decodable
speech_transcribed

示例：

audio_present=true
audio_decodable=true
speech_transcribed=false

表示：音频完整存在且可播放/解码，但当前没有完成语音转文字。

Visual State

至少记录：

duration_seconds
decoded_until_seconds
visual_coverage_ratio
decode_errors

Deep 模式中，视觉覆盖 <98% 时不得标记视觉 COMPLETE。

Overall State

允许：

• COMPLETE
• PARTIAL
• FAILED

Deep 默认只有在：

• 所需视觉覆盖 >=98%；且
• 有音频时，字幕/ASR 对语音内容具有充分覆盖；且
• 关键模态没有未解决的解码失败

时才可标记 COMPLETE。

只要仍有有效证据但关键模态不完整，就必须标记 PARTIAL。

损坏视频

视频后半段损坏时：

• 保留已成功解码的前半段；
• 音频若完整，继续保留/转写音频；
• 不因视觉失败丢弃音频；
• 可尝试 remux / H.264 repair；
• 修复评估必须按原视频总时间轴计算覆盖率；
• 把 30 秒文件截成干净的 8 秒，不能算“100% 修复”。

15.6 Delivery Identity Guard

每个 Runtime job 必须带：

• task_id
• request_fingerprint

准备完成的 session/result 必须带：

• session_id
• source_fingerprint

最终回复前必须确认交付结果属于当前视频任务。

若 task/session/source 不匹配：

• 禁止交付旧结果；
• 禁止把上一轮 Skill 更新、状态报告或另一段视频的内容当作当前视频总结；
• 重新绑定当前任务或明确报错。

16. 性能策略

用户偏好：速度不重要，效果优先；手机也一样。

默认不再追求“60 分钟视频 5–15 分钟完成”。

允许：

• 60 分钟视频处理约 60–120 分钟；
• 如果证据覆盖明显受益，60 分钟视频允许超过 120 分钟；
• 无字幕、重视觉、复杂图表/代码/实验视频超过视频原始时长；
• 90–180 分钟视频按质量需要持续更久；

• 180 分钟视频采用章节化长任务，不设置固定完成时间目标。

这个策略对 Mobile Native 上传 和 Desktop/Runtime 输入一致；设备入口本身不是降质理由。

当“更慢”可以明显换来：

• 更完整 ASR；
• 更高场景覆盖；
• 更多关键帧；
• 更充分 OCR/画面阅读；
• 更多 Agentic Rewatch；
• 更可靠的专名/数字复核；
• 更低漏关键信息概率；

则优先选择更慢、更完整的路径。

只有用户明确说“快速看 / 尽快 / 简单总结”时，才主动压缩计算与视觉覆盖。

速度不是验收指标；证据覆盖、准确性、可追溯性才是默认验收重点。

17. 免费优先

默认：

• yt-dlp / Bilibili public APIs；
• faster-whisper；
• PySceneDetect；
• OpenCV；
• host ChatGPT vision；
• 本地 lexical Video Memory。

不得静默调用额外收费模型 API。

18. 隐私与本地文件安全

• 不要求用户在聊天粘 raw cookie；
• 读取浏览器登录态前必须明确授权；
• MCP 上传入口不得接受任意电脑路径；
• 默认仅 ~/.video-understanding/inbox；
• VIDEO_UPLOAD_ROOTS 必须由用户/部署者显式设置；
• 不把本地视频公开上传到第三方，除非用户明确选择相关服务。

19. 失败降级

• 字幕失败 → ASR
• 场景检测失败 → baseline visual fallback
• 视觉部分损坏 → 保留已解码前缀 + 健康音频，标记 visual coverage 与 PARTIAL
• 视觉失败但 transcript 成功 → transcript-only partial
• ASR失败但烧录字幕可视觉读取 → visual-caption partial
• ASR依赖缺失但音频可解码 → audio_present=true / audio_decodable=true / speech_transcribed=false，不得写“听不到”
• 全部正文证据失败 → 不根据标题猜内容
• 上传文件被宿主删除 → follow-up visual rewatch 要求重新 materialize/re-upload
• 超长视频 → 内部分块，不要求用户手工切片

20. 与 No-Rush

No-Rush
→ Upload/URL Router
→ Preflight
→ Runtime/Evidence Pipeline
→ Long-video Memory
→ Agentic Rewatch
→ Quality Gate
→ Final
→ No-Rush Closing Report

21. 验收标准

Stable 前至少：

1. 当前聊天上传短视频真实分析 >= 2
2. 上传 30–90 分钟视频 >= 1
3. 上传或 URL 90–180 分钟视频 >= 1
4. B站 >= 3
5. YouTube >= 3
6. 无人工字幕 >= 2
7. 视觉信息关键视频 >= 2
8. PySceneDetect 成功路径 >= 2
9. scene fallback >= 1
10. Video Memory 后续问答 >= 3
11. dense rewatch >= 3
12. 任意本地路径读取被拒绝测试 >= 1
13. inbox 上传成功 >= 1
14. 宿主无法 materialize attachment 时不假装 Runtime 已获取
15. 1～3 小时视频不一次性灌入完整 transcript + frames
16. 失败步骤不冒充成功
17. 不默认产生额外 API 费用
18. 音频存在、可解码、已转写三个状态不得混淆
19. 视觉覆盖 <98% 的 Deep 任务不得标 COMPLETE
20. 损坏视频保留已解码前缀和健康音频
21. 截短 remux 不得冒充修复成功
22. 当前 task/session/source identity 必须与最终交付一致
23. “深度看”在视频上下文中为强触发

22. 当前状态

当前版本：0.2.3 release-candidate

已经实现到参考 Runtime：

• Bilibili / YouTube；
• uploaded-file inbox adapter；
• faster-whisper；
• PySceneDetect AdaptiveDetector；
• adaptive long-video sampling；
• structural chapters；
• overlapping Evidence Memory；
• local lexical retrieval；
• overview frames；
• dense rewatch；
• MCP ImageContent。

尚未声称：

• Windows 实机所有依赖已跑通；
• ChatGPT 自定义 MCP 自动获得手机/聊天附件字节；
• 1～3 小时端到端性能已经实测；
• Stable。

Changelog

• 0.2.3（2026-09-22）：新增 Media Health / Completion Guard；区分 audio_present、audio_decodable、speech_transcribed；增加 decoded_until 与 visual coverage；损坏视频保留部分视觉和健康音频；修复评估按原时间轴；新增 task/session/source 身份守卫，防止结果串线；“深度看”升级为正式强触发。
• 0.2.2（2026-09-22）：新增 Mobile-Native Quality-First 契约；手机直接上传视频与电脑端享有同等默认质量策略；60 分钟视频可允许约 120 分钟甚至更久处理；明确“允许慢处理”不等于“后台异步保证”。
• 0.2.1（2026-09-22）：性能策略改为 Quality-First 无硬时限；允许长视频处理时间接近或超过原视频时长，默认以证据覆盖和准确性优先，只有用户明确要求快速时才压缩流程。
• 0.2.0（2026-09-22）：Upload-First；加入安全 upload inbox、本地视频 adapter、PySceneDetect AdaptiveDetector、自适应长视频 tier、结构章节、Evidence Memory、本地检索、长视频上下文保护与 8-tool MCP 编排。
• 0.1.1（2026-09-22）：对齐首版 MCP Runtime。
• 0.1.0（2026-09-22）：Bilibili + YouTube 首版。