前言¶

DeepSeek Harness（DSH）的 Web 与 Desktop 表面共用同一套对话 UI，默认背景是静态色块。若希望长时间盯屏时有一点动态视觉，常见做法是换系统壁纸或在外部窗口垫一层视频，但那样与聊天区域脱节，也无法随主题一起调节对比度。

dsh-video-bg 是社区插件，在 DSH 自带的 loopback Web 服务上挂载本地视频流，并在浏览器侧把壳层设计令牌改成半透明，让背景视频透出来，同时尽量保持气泡与输入框可读。视频字节不离开本机，也不依赖外部服务。

这是什么¶

• 名称：dsh-video-bg（npm 包名同名）
• 维护者：zhang-guangjie
• 分类：趣味换装（社区目录 SkillHub 条目）
• 版本：0.4.0（package.json）
• 许可证：MIT

插件在 dsh web 与 DSH Desktop（渲染同一 Web 应用）上均可使用：全视口固定 <video> 置于 z-index: -1，由宿主进程经 HTTP 流式提供文件，浏览器通过 Range 请求 seek，无需把数百 MB 文件上传进页面。

核心功能¶

背景视频与本地托管¶

宿主半部（lib/index.js）注入 webServer，注册：

• GET/HEAD /video-bg/media：流式输出配置的视频，支持单段 Range（206/416），缓存键含文件大小与修改时间（?v=<size>-<mtime>），文件变更后会重新拉取。
• GET /video-bg/status：JSON 状态（ok、rev、size、mime、有效路径与默认项等）。

客户端请求与文档同源（相对路径 video-bg/media）；Desktop 下文档来自 dsh-app://app/，其余路径转发到同一 loopback 宿主。

半透明 UI¶

通过重映射 DSH 设计令牌（如 --dsw-alias-bg-base、--dsw-specific-sidebar-fill、--dsw-specific-input-major 等）为半透明色，明暗主题均覆盖；使用令牌的面板会自动变透，聊天气泡与 composer 保持接近不透明的填充。

浮动控制面板¶

右上角控件支持：

选项写入 localStorage（键 dsh.videoBg.v3）；窗口隐藏时视频会暂停。文件缺失或不可读时显示警告徽标，并在控制台输出诊断信息。

环境与依赖¶

• DeepSeek Harness 0.2.x（engines.dsh 与已安装运行时校验后才加载 bundle）。
• Node 20+（宿主侧仅使用 node:fs、node:path、node:url）。
• 视频须能被宿主进程读取；识别扩展名包括 MP4、WebM、MOV、MKV、AVI、OGG、TS，其余按 video/mp4 提供。

安装与启用¶

包为普通 DSH bundle，任选下列方式之一（安装后会自动写入 dsh.profile.bundles，勿手写重复行）：

# 从 GitHub 安装（纯 JavaScript，无构建步骤，无需 allowBuilds）
dsh plugin --profile desktop add github:zhang-guangjie/dsh-video-bg
dsh plugin --profile web add github:zhang-guangjie/dsh-video-bg

# 本地开发目录（绝对路径）
dsh plugin --profile desktop add link:/absolute/path/to/dsh-video-bg

# npm（发布后）
dsh plugin --profile desktop add dsh-video-bg

也可在 GUI 的插件管理器（Plugins → install / browse）中安装。

Desktop 说明：若 profile 为随装随用，新 bundle 会热重组；若为仅启动时加载的 profile，需完全退出并重启 DSH Desktop 一次。Web 侧安装后刷新页面即可。

配置视频路径与默认值¶

解析顺序：

1. 插件行配置 videoPath；
2. 环境变量 DSH_VIDEO_BG_PATH；
3. 包内默认 media/background.mp4。

在 profile 的 patch 层（$DSH_HOME/profiles/<profile>/cordis.patch.yml）中设置，行 id 为 ui-video-bg：

- id: ui-video-bg
  config:
    videoPath: 'D:\my-video.mp4'   # 本地路径；~ 会展开
    fit: cover                     # cover | contain
    opacity: 55                    # 初始视频不透明度 0-100
    veil: 25                       # 初始遮罩 0-100

• videoPath、fit 由宿主读取；opacity、veil 仅在浏览器尚无滑块存档时作为默认值，之后以控制面板为准。
• 启用 HMR 时修改配置可热重载插件。
• 也可在启动 DSH 前设置环境变量 DSH_VIDEO_BG_PATH。

典型用法¶

1. 按上一节安装并（可选）在 cordis.patch.yml 指向你的 MP4/WebM 等文件。
2. 打开 dsh web 或 DSH Desktop，确认右上角出现浮动控制。
3. 用不透明度与遮罩调节可读性；需要看全画面时选 contain，需要铺满窗口时选 cover。
4. 若出现警告徽标，在浏览器访问 GET /video-bg/status 查看 error（如 missing / unreadable），并核对 videoPath。

适用场景与注意¶

适合：希望在同一聊天界面内做动态背景、且视频只存本机、不想走第三方壁纸服务的 DSH 0.2.x 用户。

隐私：视频仅由宿主在既有 loopback Web 服务上提供；插件不发起外连、不上传、不读凭证或 cookie。状态接口会暴露本地视频路径（与控制面板 tooltip 一致），videoPath 应视为与 profile 其他配置同级的可信配置。

权限与安全：插件以当前 DSH 宿主进程权限读盘并提供 HTTP 路由。安装前建议在 GitHub 仓库 查看源码与 MIT 许可证，确认路径与运行环境符合你的策略。

兼容性：若其他皮肤或插件把表面硬编码为不透明色，可能盖住令牌半透明效果，需禁用冲突项。大文件首帧可能稍慢，属 Range 从磁盘拉取的正常现象。

排错速查：

结尾¶

dsh-video-bg 把本地循环视频、半透明壳层与可调遮罩收进 DSH 插件模型：宿主负责 Range 流式读盘，客户端负责挂载与控制，数据不出本机。社区目录与 DeepSeek / 幻方无官方从属关系，属 DSH「一切皆插件」生态中的趣味换装类扩展。

• 目录页：https://www.skillhub.cn/plugins/zhang-guangjie/dsh-video-bg
• 源码与文档：https://github.com/zhang-guangjie/dsh-video-bg