前言¶

DSH（DeepSeek Harness）的插件化设计让用户能按需扩展能力。当需要处理 B 站视频时，直接把视频丢给视觉模型往往不够用：画面只有时间戳、字幕可能为空、小字难以辨认。bili-vision 让 DSH 的视觉模型直接读取带时间戳的画面、官方字幕或本地转写、画面文字 OCR，把视频变成可分析的证据。

插件定位与核心能力¶

• 插件名：bili-vision
• 维护者：icyaaaww
• 类型：模型推理
• 核心价值：为 DSH 提供带时间戳的画面、字幕/ASR 与 OCR 原生返回，供当前视觉模型分析；可选独立视觉模型分析

核心功能¶

视频证据生成¶

• 带时间戳的画面：默认使用 2 fps 灰度帧计算全局与分块变化，候选帧按时间覆盖全片并保留首尾，最多 60 张候选帧，最终最多 12 帧。默认四宫格（gridSize=4），每格最大宽 480px；局部细看可单图（gridSize=1），最大宽 960px。
• 官方字幕或本地转写：使用 Whisper 模型进行语音识别，默认 small 模型、CPU 运行，可选 base 更快但效果有取舍。语言可设 BILI_VISION_LANG，不设时自动识别。
• 画面文字 OCR：默认对最终选中的画面运行 OCR（RapidOCR/ONNX Runtime），识别结果按图片内容缓存，不产生 OCR API 费用。

两种分析路线¶

• inspect（默认）：在本地整理证据（候选帧、字幕/ASR、OCR），以原生图片附件与文字证据返回，交给当前 DSH 模型分析。不产生独立 API 请求，不要求 DEEPSEEK_API_KEY。
• run：使用独立视觉模型分析，返回答案。需 DEEPSEEK_API_KEY 与配置的 BILI_VISION_MODEL（默认 deepseek-flash），仅 run 路径产生独立 API 调用。

动作与参数¶

policy=auto 为全片覆盖加相关帧；always 完全按时间覆盖；text 跳过视频和全部视觉步骤。

maxVision 取 1～36（默认 12），gridSize 为 1/4/9，start/end 单位秒，maxTextTokens 取 2000～64000。

refresh=true 绕过视觉/OCR/答案缓存；CLI --force-asr 才强制重新转写。

缓存与上下文控制¶

• 元数据、字幕、ASR、候选帧、OCR、拼图分别缓存。刷新会真正重提取图片；下载完成后才发布缓存文件。同视频的并发写入由进程锁串行化。
• 默认文本预算估算为 12000 token。inspect 和 text 的长文本节选兼顾全片覆盖和问题相关性，明确标注省略数量、提供完整文本路径；可指定时间范围继续读，不能把节选当全文。
• 不承诺单图固定 384 token，也不假设两次请求必然命中前缀缓存。run 记录实际 API usage；图像与当前 DSH 对话的实际费用以供应商账单为准。

安装与启用¶

环境要求¶

• Python 3.10+
• ffmpeg 和 ffprobe
• Node 18+（插件入口要求）
• DSH 版本满足 engines.dsh >=0.2.0-rc.2 <0.3.0

标准 DSH bundle 安装¶

在已安装 DSH 的环境执行（示例为 web profile）：

dsh plugin --profile web add 'git+https://github.com/icyaaaww/dsh-bili-vision.git#v0.2.0'

包名是 bili-vision，仓库名是 dsh-bili-vision。该包通过 package.json 的 dsh.bundle.patch 注册 cordis.patch.yml，不需要构建步骤。

标准包管理命令只安装插件包，不会自动安装 Python、Python 依赖或 FFmpeg。安装前后均可准备独立 Python 环境。

在源码目录使用与当前插件版本相同的 requirements.txt：

git clone --branch v0.2.0 --depth 1 https://github.com/icyaaaww/dsh-bili-vision.git
cd dsh-bili-vision
python -m venv "$HOME/.dsh/bili-vision-venv"
& "$HOME/.dsh/bili-vision-venv/Scripts/python.exe" -m pip install -r requirements.txt

Linux/macOS 对应解释器为 ~/.dsh/bili-vision-venv/bin/python。使用自定义 DSH_HOME 时将上述环境建在该目录下，或设置 BILI_VISION_PYTHON 为已有解释器绝对路径。首次 ASR 使用可能需要下载模型。

Windows 源码安装器（替代方式）¶

在解压的 Release 源码包或 Git 克隆目录运行。选择一种安装方式即可；标准包管理安装后不要再用源码安装器覆盖其包目录。

.\install.ps1 -Profile web
# 或桌面 profile
.\install.ps1 -Profile desktop
# 已有完整依赖时
.\install.ps1 -Profile web -SkipDeps

默认把 Python 依赖装进 .dsh/bili-vision-venv，不修改 DSH 自带 Python。设置 BILI_VISION_PYTHON 可以选择已有解释器。安装器保存实际使用的解释器路径，结构化修改 bundles 并保留 package.json 备份。

安装后重启 DSH。默认 inspect 要求当前对话使用支持图片的模型，且宿主加载 attachments 服务；不满足时工具会明确报错。run 通过独立视觉 API 返回文本，不要求当前对话模型支持图片。

卸载¶

标准安装的卸载方式：

dsh plugin --profile web remove bili-vision

桌面版用户请使用桌面插件管理界面或该版本提供的内置命令运行时；npm CLI 不能管理保留的 desktop profile。

源码安装器的卸载方式：

.\install.ps1 -Profile web -Uninstall

上述 -Uninstall 仅用于源码安装器安装的副本。卸载保留视频缓存与独立 Python 环境。

典型用法¶

在 DSH 中直接调用¶

在 DSH 中直接说：

看懂这条视频，说明主线、关键结论和画面中的重要细节：视频链接

工具默认参数相当于：

{"target":"BV1GJ411x7h7","action":"inspect","policy":"auto","maxVision":12,"gridSize":4,"ocr":true}

首次先看全片。图表、小字或某个操作不清楚时，只补看对应区间：

{"target":"BV1GJ411x7h7","action":"inspect","start":65,"end":80,"gridSize":1,"maxVision":6,"ask":"这一步点击了什么，界面有什么变化？"}

只需要口播摘要时调用 bili_summary，或 bili_vision(action=text)。这条路径不下载视频、不抽帧、不额外调用模型。

支持完整 BV 号、B 站视频链接、b23.tv 短链，以及多分 P 链接中的 ?p=2。不同分 P 使用独立缓存。

命令行使用¶

python bv.py inspect BV1GJ411x7h7 --no-ocr
python bv.py plan BV1GJ411x7h7
python bv.py text BV1GJ411x7h7
python bv.py inspect BV1GJ411x7h7 --start 65 --end 80 --grid-size 1 --max-vision 6
python bv.py run BV1GJ411x7h7 --ask "主要内容和关键画面是什么？"

inspect 输出 JSON，图片以本地路径列出；DSH 入口会把它们保存为宿主原生图片附件。CLI 自身不会调用当前 DSH 对话模型。

独立 run 常规只调用一次模型，保留完整预算内文本及所选画面；不再默认先做有损摘要再调用第二次。超过文本预算时，先把全部文本分块生成与问题相关的证据笔记，再合并作答；超过 20 个分块会要求缩小时间范围。长文本笔记和相同问题的最终答案都缓存，干跑与真实答案缓存隔离。

设置 BILI_VISION_DRY_LLM=1 可验证独立请求组装，返回明确的假响应，不代表视频理解效果。

适用场景与注意¶

• 适合需要从 B 站视频中提取结构化证据、让当前 DSH 视觉模型进行推理的用户。
• 不适合逐帧动作判定；2 fps 的候选分析可能漏掉短暂事件。画面上的极小文字应指定时间范围单帧复核。
• ASR/OCR 不是可靠的逐字原文。首轮模型权重下载、CPU 转写和视频下载仍可能较慢。
• 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。
• 稀疏采样可能漏掉短暂事件，若源视频下载分辨率本身不足，可在 CLI 调高 --height 和 --frame-width，其上限仍取决于可访问的视频流。证据返回真实源分辨率；抽帧使用实际媒体时长处理片尾，并显式转换 JPEG 色彩范围。

短结尾¶

bili-vision 把 B 站视频变成带时间戳的证据，让当前 DSH 模型直接分析画面、字幕与文字。适合需要从视频中提取结构化信息的场景。更多细节见插件目录页与 GitHub 仓库。