前言¶
在 DeepSeek Harness（DSH）里跑智能体时，纯文本模型无法直接「看见」用户上传的图片；即便切换到支持视觉的模型，对话流里的图像描述也往往散落在消息历史中，不便回看和复制。视频场景更麻烦：需要转码、抽帧、再交给模型逐段理解，单靠 DSH 原生界面通常不够顺手。
dsh-visual-plugin 是社区维护者 jyh20030112 为 DSH Web 端开发的视觉媒体插件。它不单独配置或调用私有视觉端点，而是走 DSH 原生的附件与模型路径，并在右侧 Web UI 面板里集中展示图像缩略图、可复制的模型回答，以及经过规范化处理的视频与关键帧分析结果。
这是什么¶
dsh-visual-plugin（npm 包名 dsh-visual-plugin，当前版本 0.3.0）是 DeepSeek Harness 的 Web 平台插件，采用 MIT 许可证，运行时零额外 npm 依赖。插件在 SkillHub 社区目录中归类为「联网工具」。
一句话定位：让 DSH 当前选中的图像能力模型原生理解用户图片，并对视频做场景感知的关键帧抽取与分析，结果统一呈现在右侧面板。
核心功能¶
原生图像理解¶
用户上传的图片走 DSH 原生附件通道，由当前选中的、具备图像能力的模型直接作答。插件不重写模型消息，也不调用独立的视觉 API；模型提供商、端点与凭证均由 DSH 统一管理。
可复制的图像历史¶
右侧面板为每张图片记录缩略图与当前模型的最终回答，支持展开历史记录和一键复制，方便把描述粘贴到别处使用。
视频上传与校验¶
插件自行处理视频上传，仅在接受扩展名、文件签名与 FFprobe 探测结果一致时放行，支持格式包括 MP4、M4V、MOV、AVI、MPG/MPEG、MKV、WebM。
场景感知的视频分析¶
视频经规范化转为 H.264/yuv420p MP4，再用 PySceneDetect 提取有序、带时间戳的关键帧，作为 DSH 原生图像附件发送给当前视觉模型逐帧理解。
右侧面板与高级设置¶
面板可在图像/视频视图间切换，直接播放规范化后的视频，并通过「Ask in chat」将选中视频暂存到聊天草稿（不会自动提交）。在 Settings → Plugins → Plugin configuration 的 Visual Media 卡片中，可控制侧边栏显隐，并调整上传大小、存储配额、时长、输出尺寸、FPS、CRF、关键帧数量等视频处理参数。
工作原理¶
image → DSH native attachment → current image-capable model → final answer
→ /vision-bridge/recent → panel thumbnail + copyable description
video → container validation → H.264/yuv420p normalization → PySceneDetect
→ timestamped keyframes → DSH native image attachments → current model answers
使用前须在 DSH 中先选中支持图像的模型；插件本身不提供单独的视觉模型配置项。
安装与启用¶
视频依赖（可选）¶
图像功能不依赖下列工具；视频功能需要宿主机预先安装 FFmpeg/FFprobe（>= 6.1，同一主版本，且含 libx264）和 PySceneDetect（>= 0.7.1 < 0.8）。插件不会自动下载或安装它们，缺失时设置卡片会报告具体依赖问题。
ffmpeg -version
ffprobe -version
python -m pip install 'scenedetect[opencv]>=0.7.1,<0.8'
scenedetect version
安装插件¶
dsh plugin --profile web add dsh-visual-plugin
也可指定 GitHub 源：
dsh plugin --profile web add github:jyh20030112/dsh-visual-plugin
安装后重启 dsh web。
卸载¶
dsh plugin --profile web remove dsh-visual-plugin
重启 dsh web 后生效。
典型用法¶
经过上面的安装步骤，按以下顺序操作：
- 打开 Settings → Plugins → Plugin configuration，展开 Visual Media 卡片。用 Sidebar 控制右侧面板显隐，按需调整高级视频参数。
- 在 DSH 模型选择器里选中具备图像能力的模型。
- 发送一张图片。模型原生作答后，右侧面板会显示缩略图与可复制的最终回答。
- 在输入框旁点击 Upload video 上传视频。处理完成后，在右侧面板切换到 Videos 视图播放；点击 Ask in chat 可将视频上下文写入聊天草稿，由你手动发送。
本地开发该插件源码时，可先执行 npm run bootstrap，再以 link 方式安装：
cd /absolute/path/to/dsh-visual-plugin
npm run bootstrap
dsh plugin --profile web add link:/absolute/path/to/dsh-visual-plugin
bootstrap 会自动查找同级或上级目录中的 Harness 源码；目录布局不同时可显式指定：
HARNESS=/absolute/path/to/deepseek-harness npm run bootstrap
适用场景与注意¶
适合谁
- 已在 DSH Web 端使用支持视觉的模型，希望集中管理图像描述历史的使用者。
- 需要把本地视频规范化、抽关键帧后交给当前 DSH 视觉模型分析的场景。
- 希望在右侧面板直接预览视频、再把分析请求写入聊天草稿的工作流。
使用注意
- 图像与关键帧理解完全依赖 DSH 当前选中的模型；切换模型前请确认其具备图像能力。
- 未安装 FFmpeg 或 PySceneDetect 时，图像功能仍可用，视频相关能力会受限并在设置页提示。
- 插件以当前
dsh进程的权限在宿主机上运行，视频转码与文件读写发生在本地。安装前应阅读 源码 与 MIT 许可证，确认符合你的安全与合规要求。 - SkillHub 社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；插件列表由社区维护，安装前自行甄别。
结语¶
dsh-visual-plugin 把 DSH 原生的图像理解能力与场景感知的视频关键帧分析接到统一的 Web 右侧面板，减少在对话历史里翻找描述、手动处理视频的步骤。若你已在 DSH Web 端配置好视觉模型，可按本文命令安装试用。
