AVIS DSH Plugin — 视频语义层

给视频建一份「AI 能直接读懂的目录」，之后无限次本地查询、零 token。

一次本地分析（对象检测 + 场景描述 + ASR 转写 + 向量标注），之后任何支持 MCP 的 agent（DeepSeek Harness / Claude / Codex 等）都能用自然语言在亚秒级定位到「精确到秒」的片段，不再需要反复解码视频。

这是一个 DeepSeek Harness（DSH）社区插件（dsh-plugin）。它本质是一份 MCP 桥接配置 + 一个本地 Python 语义层：dsh-mcp-client 拉起本地 server，把视频检索能力注册成 5 个 mcp__avis__* 工具。

核心价值

• 一次编码，无限复用：索引建一次（约 1.5× 实时），之后查询亚秒级、零 token
• 对象级时间轴：每个出现过的对象都有向量标注 + 时间窗（主角有 VLM 描述，配角/龙套只留向量）
• 三层融合检索：对象（视觉向量）+ 场景（BLIP 描述）+ 语音（ASR）同进统一时间轴
• 自动分诊：auto 模式先探测语音密度/对象密度，纯语音视频走 asr_only（秒级），有对象的走 avis_full

前置依赖

依赖	说明
macOS + Apple Silicon（MPS）	当前只在 M4 Mac 验证过；mlx-lm 是 Apple 专用本地 VLM 后端
Python 3.10+
ffmpeg / ffprobe	brew install ffmpeg
磁盘 ~16GB（全量 7 模型）或 75MB（纯语音 asr_only 起步）	模型缓存

快速开始（作为 DSH 插件）

# 1. 克隆
git clone https://github.com/<你的账号>/avis-dsh-plugin.git
cd avis-dsh-plugin

# 2. 一键安装环境（venv + 依赖 + 7 个模型 + 生成 avis.cordis.yml）
bash setup_env.sh --mirror        # 国内网络走 hf-mirror；直连 HF 则去掉 --mirror

# 3. 冒烟自检（三节全绿即就绪）
bash smoke_test.sh

# 4. 接进 DeepSeek Harness（一次性）
dsh web --patch "$PWD/avis.cordis.yml"

第 2 步会自动把 avis.cordis.yml.example 里的 __AVIS_ROOT__ 占位符替换成你的本机绝对路径，生成 avis.cordis.yml（已 gitignore，不进仓库）。

接好后，DSH 会注册 5 个工具，会话里直接说「找 xx 视频里讲口红的片段」即可：

工具	作用
mcp__avis__encode_video	给视频建索引（长任务）
mcp__avis__search_index	文字/图片检索，返回精确到秒的片段 + 证据
mcp__avis__understand_video	用本地 VLM 深度理解某段视频
mcp__avis__plan_clips	剪辑规划，输出带证据的 t0/t1 清单
mcp__avis__index_info	索引统计

持久化（不想每次带 --patch）：把 avis.cordis.yml 的 insert 块合并进 $DSH_HOME/cordis.patch.yml（本机所有 profile 生效）或 $DSH_HOME/profiles/<name>/cordis.patch.yml（仅某 profile）。

快速开始（作为 CLI 直接命令行用）

setup_env.sh 装好环境后，可直接用 bin/avis（零摩擦封装，自动下载缺失模型、自动命名索引、自动注册）：

# 建索引（自动 -o、自动下载缺失模型、自动注册）
bin/avis index 视频.mp4

# 查询（毫秒级、零 token）
bin/avis search "口红"

# 按名字检索 / 列出所有索引
bin/avis search "口红" -i idx_某视频
bin/avis list

# 手动下载模型（--mirror 走镜像 / --asr-only 只要 75MB / --full 全量）
bin/avis setup

想直接用 avis 命令（不带 bin/）：ln -s "$PWD/bin/avis" /usr/local/bin/avis，或 pip install -e .（在正常 Python 上会生成 avis 控制台脚本）。

底层五命令：build（建索引）/ query（查询）/ plan（剪辑规划）/ info（统计）/ cut（按 plan 切片段），avis 是它们之上的封装。完整参数见 skill/SKILL.md（给 agent 用的 skill 封装，含异步约定、踩坑、典型工作流）。

目录结构

avis-dsh-plugin/
├── avis.cordis.yml.example  DSH MCP 插件配置模板（setup_env.sh 生成 .yml）
├── setup_env.sh             一键安装（venv + 依赖 + 模型 + 生成 cordis.yml）
├── smoke_test.sh            冒烟自检
├── requirements.txt         Python 依赖
├── src/semantic_layer/      语义层核心（build/query/plan/info/cut + MCP server）
├── src/avis/                早期 avis 原型实现（演进参考）
├── patches/                 路径修复补丁
├── skill/                   给 Hermes/DSH agent 用的 skill 封装
├── ROADMAP.md               技术路线（4 阶段）
└── PHASE3.md                Cordis 桥接说明

模型清单（约 16GB 全量）

GroundingDINO（检测）· CLIP ViT-B-32（视觉向量）· BLIP（场景描述）· MiniLM（文本向量）· faster-whisper tiny / large-v3（ASR）· Qwen2-VL-2B-4bit（本地 VLM，Apple Silicon）

实际磁盘：基础 5 个模型（tiny ASR）约 12GB，加 large-v3 + VLM 全量约 16GB。纯语音检索（--mode asr_only）只需 faster-whisper-tiny（75MB）。

已知限制

• 检测约 1.7s/帧，长视频（>10min）建议先缩范围再检测
• 同类别多对象靠 IoU 跟踪，快速运动/遮挡会断轨（下一步 ByteTrack+ReID）
• 增量索引（查询未命中时按新提示词补检测）待实现
• 仅 Apple Silicon 验证过；Linux 需替换 mlx-lm 为 CUDA 后端

License

MIT