dsh-vidlens

VidLens for DeepSeek Harness

中文 · English

把 vidlens 从一个 stdio MCP 外壳变成 DSH 原生插件：18 个 vidlens_* 工具、图片直接进对话、按工具设超时、外加三个零下载的缓存工具。

工程本体（Python）没有改一行逻辑：插件通过一个常驻桥进程调用 vl_mcp.py 里已经测过的工具函数，所以 MCP 外壳和插件的行为不会漂移。

• 工程仓库（Python + MCP 服务器）：https://github.com/cctv2333/vidlens
• 本仓库（DSH 插件）：https://github.com/cctv2333/dsh-vidlens
• 插件要求：vidlens >= 1.4.0（video_soundscape 起）、Node ≥ 20、DSH >=0.2.1-rc.2 <0.3.0

用户: 这个视频讲了什么？ <url>
  → vidlens_meta      0 下载：值不值得看
  → vidlens_plan      0 下载：切章节，挑 2–3 段
  → vidlens_window    只下这一窗的音频（或直接读缓存/字幕）
  → vidlens_sheet     只下这 20 秒，拼图带时间码，图直接附在结果里
  → vidlens_brief     平台字幕优先；无字幕才下音频做本地 ASR
  → vidlens_soundscape 台词之外的声音（吃饭/敲击/水声），带概率

相对 MCP 外壳的增强

能力	MCP 外壳	本插件
工具名	mcp__vidlens__video_meta	vidlens_meta（短、可读）
超时	客户端一个全局 60s	每个工具自带预算（vidlens_brief 15 分钟，vidlens_scan 15 分钟）
图片	取决于客户端是否支持 MCP image content	走宿主 attachments.saveImage，成为持久图片附件，同轮就能看
缓存意识	无	vidlens_library（零网络列缓存）、vidlens_seek（零网络查原话）
批量筛选	无	vidlens_compare（最多 8 个链接，0 媒体下载）
行为约束	只在 MCP instructions 里	独立的 system-prompt 小节：先 meta→plan→抽样，绝不下整片
取消	断开连接	exec.signal 取消时重启桥进程，不留下卡死的下载
整片下载	video_full(confirm=true) 存在	故意不提供：需要画面就用 sheet/frames/scan
本地视频	与 Python 核同步（1.6.0 起）	所有 url 参数都接受本地路径：D:\a.mp4、file:///D:/a.mp4、~/a.mov

安装

前置：先有一份 vidlens。 二选一：

pipx install "vidlens-mcp[all]"          # 推荐：无 checkout，命令叫 vidlens / vidlens-mcp
# 或
git clone https://github.com/cctv2333/vidlens && cd vidlens && install.cmd

然后装本插件（三选一）：

# A. 本地目录（开发；换成你自己 clone 的位置）
plugin_manager action=install_bundle target=<你的路径>\dsh-vidlens

# B. GitHub 直装（本包无 build/prepare 脚本，不需要 allowBuilds 权限）
#    注意：这条会真的 git clone 本仓库，会被 GitHub 记一次 clone
dsh plugin --profile desktop add github:cctv2333/dsh-vidlens#<sha>

# C. npm（registry，不经过 GitHub）
dsh plugin --profile desktop add dsh-vidlens

插件会自动找 Python 工程：config.projectDir → $VIDLENS_PROJECT → <本包>/../vidlens → 当前目录 （只认真实存在的目录，不含任何人的本机路径）； 找不到时按 $VIDLENS_PYTHON / .venv / python 依次尝试。PyPI 安装的形态下， 把 projectDir 指到 pipx 的 venv 或直接设 VIDLENS_PROJECT 都行（模块名不变）。

安装后这个 bundle 会插入一行 Host 插件：

- insert:
    - id: dsh-vidlens
      name: 'dsh-vidlens'
      config: {}

想改成别的工程位置（例如换机器）就在 config 里写：

- insert:
    - id: dsh-vidlens
      name: 'dsh-vidlens'
      config:
        projectDir: D:\path\to\vidlens
        pythonPath: D:\path\to\vidlens\.venv\Scripts\python.exe
        warm: true

字段都可省略：projectDir 默认依次取 config.projectDir → $VIDLENS_PROJECT → <本包>/../vidlens → 当前目录；pythonPath 默认取 $VIDLENS_PYTHON → 工程的 .venv → python。

工具（21 个）

基础四件（0 下载）

工具	用途
vidlens_meta(url)	标题/UP主/时长/播放/平台字幕/平台标注音乐 + 注入风险扫描
vidlens_plan(url, window=300)	按切点/长静音分章节 + 建议顺序
vidlens_subs(url, lang=zh)	平台字幕（人工优先，其次自动/AI）
vidlens_library(limit=20, query='')	新增：本地缓存清单，避免重复下载

读内容

工具	下载量	用途
vidlens_watch(url, minutes=5, cursor="next")	每段该窗音频（或缓存）	新增：一段一段看（默认 5 分钟、约 0.5k 字），返回该段要点 + 「已看 X / 共 Y（%）」，并要求先汇报、再问用户要不要继续
vidlens_window(url, start, end)	0（有缓存/字幕）或该窗音频	某时间窗的台词与停顿
vidlens_brief(url, ..., level="digest")	平台字幕 0；无字幕才下音频	摘要（默认约 1.5k 字：章节 + 5 句关键台词 + 全文路径）；level="full" 才给 6–9k 字完整报告（结构/停顿/低置信词/广告段落/风险）
vidlens_seek(query, url='')	0（新增）	在缓存转写里按关键词查原话 → 时间码
vidlens_audio(url, start, end)	该段音频	SenseVoice 语种/情感/事件 + 节拍与能量
vidlens_soundscape(url, start, end)	该段音频	新增：AudioSet 527 类声音事件（吃饭/敲击/水声/碰撞…）+ 概率 + 时间码

看画面（图片直接进对话）

工具	下载量	用途
vidlens_sheet(url, start, end, cols, rows)	该段（20s≈0.9MB）	带绝对时间码的拼图
vidlens_frames(url, at=[...])	该段	最多 6 张精确帧（读小字用）
vidlens_scan(url, n=24)	最低画质整片（7min≈14-21MB，用完即删）	全片抽样拼图（无音频视频）
vidlens_ocr(url, start, end, n=12)	该段最低画质	把画面上的字读成文本（本地 OCR，离线）；无人声、无字幕的视频靠它，输出带时间码

vidlens_ocr 的引擎是可选依赖（RapidOCR，Apache-2.0，PP-OCRv6 模型随包分发，装完离线）。 第一次调用不会偷偷下载：它先告诉你「约 80MB、会装到哪个目录、怎么换目录」， 再调一次并传 install: true 才开始下，结果里会写清装到哪。

变量	作用	默认
VIDLENS_OCR_TARGET	装到指定目录（自动加入 import 路径，不写系统目录）	本解释器 site-packages（Windows 上通常就是 C 盘）
VIDLENS_OCR_AUTO_INSTALL	ask 先问 / auto 自动装 / off 只给命令	ask

# 想放 D 盘 + 以后自动装（桥进程会读这两个环境变量）：
set VIDLENS_OCR_TARGET=D:\your\ocr
set VIDLENS_OCR_AUTO_INSTALL=auto

没装也不会坏：vidlens_ocr 返回安装说明，其他工具不受影响。

上下文预算（为什么默认给摘要）

一次「看视频」如果按老路子走，实测是这么多字符：

调用	字符	说明
meta + plan	~730	便宜
window × 3（各 1 分钟）	~2,800	~0.9k/分钟
soundscape（60 秒）	~1,500	12 窗 × 8 标签
brief（旧版全量）	~9,000	6–9k 字 ≈ 4–6k tokens
合计	~14,200	还没算图片

关键不在单次有多大，而在于这些字符之后每一轮都在上下文里。一个 64k 窗口， 两三个视频 + 正常对话就会顶到上限，于是出现「看完视频就超上下文」。

所以默认改成三档，按需升级：

1. vidlens_brief → 摘要（约 0.7–1.5k 字：标题/时长/语音覆盖/章节/5 句均匀取样的关键台词/全文路径）；
2. vidlens_window → 只读某一段（约 0.8k 字/分钟），读细节用它，别用 brief 代；
3. vidlens_brief(level="full") → 完整报告（6–9k 字），只在用户明确要全文时用一次。

全文始终写在 out/<id>/brief.md，不会丢；摘要里直接给路径和下一次该调什么。 vidlens_window 另有 80 行上限，超了会明说「还有 N 行，缩小范围」而不是无限倾倒。

判断 / 长视频 / 自检

工具	用途
vidlens_comments(url, limit=40)	评论区互动比、正负面、争议度、高赞评论 + 评论配图
vidlens_compare(urls=[...])	新增：批量元数据对比（0 媒体下载，最多 8 个）
vidlens_job_start(url, ..., full=False)	长视频后台任务，立即返回 job_id
vidlens_job(job_id, wait_seconds=20)	轮询阶段/百分比，完成返回报告
vidlens_models(action=list)	本地模型目录 + 本机真实路径；action=download, name=..., confirm=true 才真下（ced-mini 10MB / whisper 75–484MB）
vidlens_doctor()	自检 python/ffmpeg/yt-dlp/依赖/模型/磁盘/网络

架构

DSH Host (index.js)
  ├─ 21 × ctx.tools.register(...)        原生工具 + 每工具 timeoutMs
  ├─ ctx.systemPrompt.section('vidlens') 取样协议（meta→plan→抽样）
  └─ Bridge (常驻)  ──stdin/stdout JSONL──▶  python -u bridge/vidlens_bridge.py
                                                │
                                                ├─ import vl_mcp   （复用工具函数）
                                                ├─ import vidlens_web / _extra / _sanitize
                                                └─ out/<id>/        （缓存，进程重启不丢）

为什么不是直接把 MCP 服务器挂上来：MCP 客户端只有一个全局工具超时，长视频 ASR 会被误杀；图片是否进模型取决于客户端实现；也拿不到「缓存清单 / 关键词定位」这类只在本地才有答案的能力。桥进程把「已验证的 Python 逻辑」和「宿主的原生能力」接在一起，两边都不用重写。

协议（每行一个 JSON）

// 启动
{"op":"ready","ok":true,"pid":1234,"project":"D:\\\\projects\\\\vidlens","python":"3.12.10","tools":["meta",...]}
// 请求 → 响应
{"id":7,"tool":"sheet","args":{"url":"...","start":"0","end":"20"}}
{"id":7,"ok":true,"text":"...","images":[{"path":"...jpg","mediaType":"image/jpeg","name":"sheet_0_20000.jpg"}]}
{"id":8,"ok":false,"error":"ValueError: ...","trace":"..."}

sys.stdout 在导入任何库之前就被指向 stderr，所以依赖里的杂散 print 不可能污染协议；桥只把帧写进保存下来的真实 stdout。

多进程安全：DSH 会话、MCP 服务器、插件桥是不同进程，进程内 threading.Lock 互相看不见。 工程侧用 vidlens_web.CrossProcessLock（进程内 RLock + out/.media.lock 文件锁，msvcrt/flock） 把「一个下载口」扩展到整台机器；超时可用 VIDLENS_LOCK_TIMEOUT（默认 900s）调整。 实测两个进程同时调 video_sheet：第二个的 acq 时间落在第一个 end 之后（串行，不互相踩）。

验证

离线（不联网、不下媒体）

node tools/selftest.mjs
# 130/130 checks passed（工具表 + 桥握手 + library/models/seek + 本地路径声明 + 强制杀进程后自愈）

带真实链路（约 1MB 媒体）

node tools/selftest.mjs --live
# 130/130 再加 live 3 项（真实链路，约 1MB 媒体）

安装后在 DSH 里的实测（本机 2026-10-25，全部走原生工具通道）

调用	结果
vidlens_library(limit=6)	9 个缓存视频，标题/时长/段数/来源/占用/时间齐全（out/ 里的 bili/、comment_pics/ 等非视频目录已自动排除）
vidlens_doctor()	11/11：python 3.12.10、ffmpeg 7.1、yt-dlp 2026.10.21、4 个依赖、whisper 461MB、磁盘 332GB、B站 API 200
vidlens_meta(BV1PinG6fEPX)	真实标题/UP主/139514 播放；正确报出「字幕需要登录」
vidlens_plan(window=120)	3 章节，0 下载
vidlens_window(02:10–02:25)	asr(cached)，0 下载直接读缓存
vidlens_seek("宪法")	3 条原文 + 时间码（00:20.460、02:17.720…），0 网络
vidlens_sheet(60–72s, 3×2)	下载 12 秒，产出 1440×540 拼图，图片作为持久附件进入对话（时间码 00:00:59.995 … 00:01:09.594）
vidlens_frames([63, 68])	2 张 960×540 帧，同一条结果里两张图都在
vidlens_compare(2 个链接)	一张 markdown 表，0 媒体下载
vidlens_job_start → vidlens_job	起任务拿到 job_id=6652ac4e，轮询后返回完整 brief（asr(cached)，含低置信词/停顿/广告段）
vidlens_meta(错误 URL)	可读错误：ERROR: meta failed rc=1: ... HTTP Error 404，工具不崩

拼图实测（时间码烧在每格左上角）：

发布（维护者）

• CI：.github/workflows/ci.yml —— 会 checkout 两个仓库（本插件 + cctv2333/vidlens 作为兄弟目录）， 装 Python 核心后跑离线自检；另外两个 job 校验 manifest 可发布、tarball 含 bridge/ 与 LICENSE。
• 发版：打 tag 即发布 npm。

git tag v1.2.0 && git push origin v1.2.0

release.yml 会 npm pack、npm publish --access public，走 Trusted Publishing（OIDC）—— CI 里没有任何长期 token。npm 的 publisher 只能在包存在后配置，所以首次发布要在本地做一次 （npm stage publish → npm stage approve，全程不需要把 token 交给 CI，见 RELEASING.md），之后打 tag 即可。

注意：PowerShell 5.1 不支持 &&，用 ; 或分行。

实现笔记

• output.schema 不能用 {type:'json'}：宿主对工具输出 schema 做严格校验，只接受 object/array/string/number/integer/boolean/null。第一版用了 {type:'json'}，安装直接 application: failed（JsonSchemaError: unsupported JSON schema）。现在写成显式的 object schema（text + images[]）。
• 被杀掉的旧进程不能污染新进程：超时/取消会 kill() 工作进程并在同一 tick 重建。旧 进程的 exit 事件是异步到的，必须先判 this.child !== child 再清理，否则它会把新 进程上排队的请求全部 reject（这个 bug 是自检里的「强制杀进程后自愈」用例抓到的）。
• 本插件不导出 Config：Config.listConfigs 里这一行显示 status: absent（没有配置 schema），但 config: 里的 projectDir / pythonPath / warm 仍会原样传给 apply()。 不导出 schema 是刻意的：schema 需要 schemastery，而插件的解析链未必能找到宿主那份 @deepseek-ai/schemastery；宁可少一个设置表单，也不要一个「载入期 import 失败 → 18 个工具整体消失」的失败模式。
• 图标：icon.svg 是原创矢量图（2042 字节，well-formed XML，256×256，边缘圆角 + 时间码刻度 + 镜头环 + 播放三角）。结构校验通过；Plugin Manager 里的实际渲染效果 没有在浏览器里验证（无头浏览器对 file: / data: 导航超时），这一项留待用户目视确认。

路线图

产品级路线图（已做 / 未做 / 验收标准 / 不做清单）在工程仓库： vidlens/ROADMAP.md。

插件专属待办，按工作量从小到大：

1. Config schema（现在 status: absent，只能手改 YAML）
2. /vl <url> 斜杠命令
3. present 交付物卡片（brief.md / 拼图）
4. 右侧栏 Web 面板（缓存列表 + brief 预览 + 时间轴）
5. 设置页（模型路径 / 代理 / cookie）

边界与已知限制

• job 状态在进程内存：vidlens_job_start 起的任务，桥进程重启（超时/取消/宿主重启）后会消失；已下的缓存不丢，重跑即可。
• 取消 = 杀桥进程：Python 侧没有协作取消，所以被取消/超时的调用会重启工作进程（缓存在磁盘上，代价很小）。
• 需要 cookie 的站点（抖音、B 站 AI 字幕）默认不碰：按报错提示设 VIDLENS_COOKIES_FROM_BROWSER=edge 或 VIDLENS_COOKIES=path\cookies.txt。
• 不下整片：video_full 故意没有移植。整片画面需求用 vidlens_scan（最低画质、用完即删）。
• PyPI 形态也能接：工程装成 wheel 后没有 vidlens.py 旁边的 checkout 标记，插件的 目录嗅探找不到它；把 config.projectDir 指到 pipx 的 venv 目录（或任意含 vidlens.py 的目录），或设 VIDLENS_PROJECT 即可。安装形态下 out/ 会落在 %LOCALAPPDATA%\vidlens\out。
• Windows 优先：工程默认路径与 .venv\Scripts\python.exe 是 Windows 习惯；Linux/macOS 用 projectDir + pythonPath 显式指定即可（跨进程锁在 POSIX 用 flock）。
• 工程本体仍无 LICENSE，公开分发前需项目所有者选定；本包 license 标为 UNLICENSED。