# dsh-visual-plugin

DeepSeek 霓虹像素鲸鱼

本地优先的 DeepSeek Harness 视觉媒体插件。
在本机完成视频校验、转码与场景关键帧提取，结合 DSH 当前视觉模型理解图片和视频，并在右侧面板查看图片历史与播放视频。

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件。视频预处理及插件媒体存储均在运行 DSH 的机器上完成。图片与提取的关键帧通过 DSH 发送给当前配置的模型；模型推理是否在本地运行，取决于你的 DSH 模型配置。 ## 特性 - **原生图片理解** —— 上传图片始终走 DSH 原生附件与模型链路；插件不再配置或调用独立视觉模型。 - **可复制的图片历史** —— 右侧面板在图片缩略图旁记录当前 DSH 模型的最终回答，支持展开历史和一键复制。 - **插件自有视频上传** —— 支持 MP4、M4V、MOV、AVI、MPG/MPEG、MKV 和 WebM；扩展名、文件签名与 FFprobe 结果必须一致。 - **视频场景解析** —— 统一转为 H.264/yuv420p MP4，通过 PySceneDetect 提取关键帧，再将有序、带时间戳的图片交给当前 DSH 视觉模型。 - **右侧面板** —— 在图片/视频视图间切换，直接播放标准化视频，并将选中视频写入会话草稿。 - **视频高级设置** —— 可在插件设置卡中调整上传大小、存储配额、时长、输出尺寸、FPS、CRF 和关键帧数量。 ## 工作原理

dsh web 右侧面板中的图片与视频解析流程

``` 图片 → DSH 原生附件 → 当前视觉模型 → 最终回答 → /vision-bridge/recent → 面板缩略图 + 可复制描述视频 → 容器校验 → H.264/yuv420p 标准化 → PySceneDetect → 带时间戳关键帧 → DSH 原生图片附件 → 当前模型回答 ``` 插件不会改写模型消息，也不会调用私有视觉接口。发送图片或询问视频前，请在 DSH 中选择支持图片输入的模型。 ## 快速开始插件 `0.4.x` 面向 DSH `0.2.0-rc.2`；旧版 DSH `0.1.x` 请继续使用插件 `0.3.2`。升级无需启用版本风险豁免。 ### 1. 安装宿主环境依赖图片功能无需安装以下工具。视频功能需要 FFmpeg/FFprobe `>= 6.1`（同一主版本）、包含 `libx264` 编码器的 FFmpeg，以及 PySceneDetect `>= 0.7.1 < 0.8`。请在运行 `dsh web` 的机器及用户环境中安装依赖。`ffmpeg`、`ffprobe` 和 `scenedetect` 必须加入该进程的 `PATH`，可以从任意目录直接调用。如果 DSH 运行在 Docker、WSL 或远程服务器中，请在对应运行环境内安装依赖。 #### macOS（Homebrew）若尚未安装 [Homebrew](https://brew.sh/)，请先安装并按照其安装后提示将 `brew` 加入 `PATH`。然后安装 [FFmpeg](https://formulae.brew.sh/formula/ffmpeg)（包含 FFprobe）和 [uv](https://docs.astral.sh/uv/getting-started/installation/)： ```sh brew install ffmpeg uv ``` #### Arch Linux（pacman）安装官方仓库中的 [FFmpeg](https://archlinux.org/packages/extra/x86_64/ffmpeg/) 和 [uv](https://archlinux.org/packages/extra/x86_64/uv/)： ```sh sudo pacman -Syu ffmpeg uv ``` #### Windows（PowerShell、WinGet）打开 PowerShell，执行 `winget --version` 确认 [WinGet](https://learn.microsoft.com/windows/package-manager/winget/) 可用。若缺少该命令，请按链接中的说明安装或更新 **应用安装程序（App Installer）**。在 Windows x64 上安装 FFmpeg（包含 FFprobe）和 uv： ```powershell winget install --id Gyan.FFmpeg --exact winget install --id astral-sh.uv --exact ``` 安装后关闭并重新打开 PowerShell，使新的 `PATH` 生效，再继续下面的步骤。如果无法使用 WinGet，可从 [FFmpeg 下载页](https://ffmpeg.org/download.html) 获取 Windows 构建，解压到 `C:\Tools\ffmpeg` 等固定目录，并在 **环境变量** 中将包含 `ffmpeg.exe` 和 `ffprobe.exe` 的目录（通常为 `bin`）添加到当前用户的 `Path`；uv 则按其 [Windows 官方安装说明](https://docs.astral.sh/uv/getting-started/installation/) 安装。 #### 使用 uv 安装 PySceneDetect（三种系统通用）在终端或 PowerShell 中执行： ```sh uv tool install --python 3.12 "scenedetect>=0.7.1,<0.8" uv tool update-shell ``` 该方式将 PySceneDetect 安装为当前用户可直接调用的持久命令，并使用独立环境。uv 会在需要时下载 Python 3.12；标准 `scenedetect` 包包含所需的 OpenCV 依赖。启动 DSH 前无需激活虚拟环境。详见 [uv 工具安装文档](https://docs.astral.sh/uv/guides/tools/) 和 [PySceneDetect 安装说明](https://www.scenedetect.com/download/)。 ### 2. 验证依赖执行 `uv tool update-shell` 后，关闭并重新打开终端。在即将启动 DSH 的同一环境中执行： ```sh ffmpeg -version ffprobe -version ffmpeg -hide_banner -encoders scenedetect version ``` 确认 FFmpeg 和 FFprobe 均为 `>= 6.1` 且主版本一致，编码器列表包含 `libx264`，PySceneDetect 为 `>= 0.7.1 < 0.8`。若提示找不到命令，在 macOS/Arch 中执行 `command -v ffmpeg ffprobe scenedetect`，在 PowerShell 中执行 `Get-Command ffmpeg, ffprobe, scenedetect`，确认命令位置。`uv tool dir --bin` 可查看 PySceneDetect 的命令目录，该目录需要加入 `PATH`。通过服务或容器启动 DSH 时，也应配置相应的 `PATH`，修改后重启 DSH 进程。插件不会自动下载依赖或执行安装脚本。缺少依赖时图片功能仍可用，设置页会列出视频依赖问题。 ### 3. 安装插件 ```sh dsh plugin --profile web add dsh-visual-plugin # 或：github:jyh20030112/dsh-visual-plugin ``` 若使用本地 DeepSeek Harness 源码开发，请改为链接本地插件目录： ```sh cd /absolute/path/to/dsh-visual-plugin npm run bootstrap dsh plugin --profile web add link:/absolute/path/to/dsh-visual-plugin ``` `bootstrap` 要求已安装、构建的 `dsh-v0.2.0-rc.2` Harness 检出，并自动查找同级或祖先目录。其他布局请显式指定： ```sh HARNESS=/absolute/path/to/deepseek-harness npm run bootstrap ``` ### 4. 重启并使用在通过上述依赖验证的环境中**重启** `dsh web`，然后： 1. 打开 **设置 → 插件**，选择 **dsh-visual-plugin** 详情页中的 **视觉媒体** 配置。通过 **侧边栏** 开关控制右侧面板，并按需调整视频解析高级设置。设置保存到当前 profile，立即生效且重启保留；升级会恢复旧设置归档中的有效视频参数，不覆盖已保存的新参数。 DSH rc.2 插件详情页中的视觉媒体配置

2. 在 DSH 中选择支持图片输入的模型；插件不再提供单独的视觉模型配置。 3. 发送图片。当前模型会原生回答，图片面板会记录缩略图和最终回答，方便复制。 4. 点击输入框旁的 **上传视频**。处理完成后在右侧选择 **视频** 播放；点击 **在会话中提问** 只会写入草稿，确认后再发送。 ### 视觉模型图片与视频关键帧均由 DSH 当前选择的视觉模型理解。模型提供方、接口和凭据统一由 DSH 管理，插件不再重复配置。 ## 卸载 ```sh dsh plugin --profile web remove dsh-visual-plugin ``` 重启 `dsh web`。该命令会在 profile 内转发执行 `pnpm remove`，bundle 层列表会自动同步移除该插件。 ## 项目结构 ``` src/ index.ts 原生图片历史、video_describe 工具、设置与 HTTP 路由 config.ts 视频解析高级设置与运行时策略 video/ 上传、容器探测、转码、场景检测、关键帧与 HTTP Range 播放 client/ 图片/视频面板、上传控件、高级设置、文案与样式 cordis.patch.yml bundle 补丁层 ``` ## 构建 ```sh npm run bootstrap && npm run typecheck && npm run build # 需要本地 harness 检出 ``` 预构建 `lib/` 已提交，使用者无需构建。 ## CI/CD `ci.yml` 在每次 push/PR 校验产物与打包内容；`release.yml`（tag `v*`）校验版本、打包、创建 GitHub Release 并发布到 npm。 ## 相关资源 - [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —— 本插件所扩展的宿主框架。 - [PySceneDetect](https://www.scenedetect.com/) —— 用于选择视频关键帧的场景检测工具。 - [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) —— 收录本插件的 DSH 插件精选列表。 ## 友情链接 - [LINUX DO](https://linux.do) ## 致谢 - [HsiangNianian](https://github.com/HsiangNianian/) — 感谢开发过程中的帮助与建议。 - [tingfeng347](https://github.com/tingfeng347) — 感谢构建稳定性修复与本地 harness 开发环境的完善。 - [dsh-auto-continue](https://github.com/HsiangNianian/dsh-auto-continue) — 网络错误等异常导致请求被中断时自动发送「继续」恢复的 DSH 插件（错误分类、自适应退避、浏览器通知），很好用的搭配。 ## 许可证 [MIT](LICENSE)