dsh-video-understand

Readme

# dsh-video-understand

[![npm version](https://img.shields.io/npm/v/dsh-video-understand)](https://www.npmjs.com/package/dsh-video-understand)
[![GitHub stars](https://img.shields.io/github/stars/ilps2/dsh-video-understand)](https://github.com/ilps2/dsh-video-understand)

低成本视频理解插件：给 dsh agent 注册 `video_understand` 工具——B站链接 / BV 号 / 本地视频 → AVIS 信息层（ASR 转写 + 场景结构 + 运动对象轨迹 + YOLO 语义）→ 摘要+问答。引擎自包含，无需外部依赖。

## 安装

```bash
# npm 安装
npm install dsh-video-understand

# 或 dsh plugin add dsh-video-understand
```

**装完即用**：首次调用 `video_understand` 时自动创建插件本地隔离环境（`.venv`）并安装核心依赖（优先 `uv`，回退 `venv`+pip 清华镜像）——无需手动执行任何命令，不污染系统 Python。

**引擎已内含**，无需额外克隆外部仓库。

### 环境自检

```bash
npx dsh-video-understand doctor        # 逐项检测 + 给出修复命令
npx dsh-video-understand doctor --fix  # 一键自动修复（建环境 + 装依赖）
```

前置条件仅两个：`ffmpeg`（macOS `brew install ffmpeg` / Ubuntu `sudo apt install ffmpeg`）和一个 LLM API key（见下表）。语义层依赖（torch/CLIP/YOLO，约 2GB）为可选，仅建完整语义层时再装：`pip install -r engine/requirements-layer.txt`。

## ⚠️ 数据流披露

| 级别 | 数据流向 | 说明 |
|---|---|---|
| **L0**（默认） | **完全本地** | ASR + 场景分类 + 运动检测，不上传任何数据 |
| **L1** | MiMo API | 视频帧发送至 MiMo 服务器进行 VLM 分析 |
| **L2** | MiMo API | 视频帧发送至 MiMo 服务器进行 VLM 分析 |

- L0 级别（默认）仅使用本地 ASR + 场景分类 + 运动检测，不涉及云服务
- L1/L2 级别会将视频帧（JPEG 编码）发送至 MiMo API 进行视觉理解
- 帧数据仅用于单次 VLM 推理，不会被存储或用于训练

## 环境变量

| 变量 | 必需 | 说明 |
|---|---|---|
| `LLM_API_KEY` | ✅* | LLM API 密钥（默认 MiMo：`sk-xxxxx`） |
| `LLM_API_URL` | ❌ | API endpoint（默认 `https://api.xiaomimimo.com/v1/chat/completions`） |
| `LLM_MODEL` | ❌ | 模型名（默认 `mimo-v2.5`） |
| `VIDEO_UNDERSTAND_PYTHON` | ❌ | Python 解释器路径（自动检测有依赖的 Python） |
| `BILI_DOWNLOAD_SCRIPT` | ❌ | bilibili-downloader 脚本路径（下载 B站视频用） |

> \* 未设置 `LLM_API_KEY` 时，自动从 `~/.dsh/.credentials.yaml` 读取（优先 `XIAOMI_API_KEY`，兼容 `DEEPSEEK_API_KEY`）。一个 key 搞定。

## 工具

`video_understand(target, questions?, noDownload?, level?, window?)`

| 参数 | 类型 | 说明 |
|---|---|---|
| target | string | B站 URL / BV 号 / 本地视频绝对路径 |
| questions | string[] | 可选，自定义问题（默认 3 问） |
| noDownload | boolean | 本地文件置 true |
| level | string | `l0`(默认) / `l1`(+3-5帧VLM视觉摘要) / `l2`(+时间窗密集帧证据) |
| window | string | L2 时间窗，如 `10-30` 或秒数（auto=轨迹最活跃30s） |
| budgetCny | number | 单次问题预算上限（元），视觉成本估算超预算自动降级（拦截 L2 用 L0/L1 回答） |

返回 JSON：`video / duration_s / token_compression_pct / cost_cny / answers[]`。

## 结构

```
dsh-video-understand/
├── package.json
├── cordis.patch.yml
├── dsh/
│   └── index.js          # host 端：注册 video_understand 工具
├── engine/               # 自包含引擎（无需外部依赖）
│   ├── understand_video.py
│   ├── avis.py
│   ├── visual_level.py
│   ├── frame_prep.py
│   └── livestream-highlight/
│       └── asr.py
└── skills/
    └── video-understand/SKILL.md
```

## 分级实测（2026-08）

| 层级 | 内容 | 数据流向 | 成本（估算*） |
|---|---|---|---|
| L0 信息层 | ASR+场景+轨迹+YOLO → 摘要/问答 | 本地 | 仅 LLM 文本成本 |
| L1 视觉级 | 3-5 帧 VLM → 颜色/姿态/衣着 | MiMo API | +数帧 VLM 成本 |
| L2 证据级 | 时间窗密集帧 → 时间线 | MiMo API | 按窗长 |

> \* 成本按 `engine/understand_video.py` 的价格常量估算（可配置输入），实际随厂商定价变化，非测量承诺。详见 [docs/blog-视频理解性价比实验](docs/blog-视频理解性价比实验-2026-08-20.md)（方法 + 实测）。

实测：电影解说 L1 补出「白色立领衬衫/神情凝重/暗色调诊室」（L0 完全给不出）；舞蹈 L2 逐帧「头部转 15-20°→45°、口型开口→闭合→微笑」。

## 设计背景

本插件的核心目标是**低成本视频理解**：用信息层代替逐帧像素喂 LLM，单视频 LLM 调用仅需几千 token（具体成本取决于所选模型定价，见上）。

- **LLM 选型**：最初选用 DeepSeek v4 Flash 因其性价比最优；近期调价后已迁移至 MiMo，持续追踪成本效益比
- **视觉级（L1/L2）**：DeepSeek 暂不支持多模态输入，故 L1/L2 使用 MiMo API 进行视觉分析（此前曾使用 DashScope 作为过渡方案）。未来若 DeepSeek 支持多模态或出现更优的本地推理方案，可进一步优化成本

## 原理

引擎把视频压缩成**信息层**（ASR 转写 + 场景结构 + 运动对象轨迹 + YOLO 语义，约 1k token）再喂 LLM；同一视频重复理解时信息层缓存复用（内容哈希，二次提问跳过 ASR）。成本与 token 对比的具体测量见 [docs/blog-视频理解性价比实验](docs/blog-视频理解性价比实验-2026-08-20.md)。

## License

MIT