hanzhaoxuan2991479447-del/deepseek-harness-custom-bg

DeepSeek Harness 自定义背景

面向 DeepSeek Harness Web 的动态 Cordis 自定义背景插件：批量导入、缩略图管理、定时轮换、融入度调节，以及可自由拖动的透明悬浮面板。

Version
Runtime
Cordis
License

DeepSeek Harness 自定义背景插件完整界面

插件把本地图片渲染到 DSH 的 shell.overlay，不替换原有工作区，也不修改聊天内容。控制面板采用透明底、主题边框与发光效果；收起后只保留一个可拖动的 ◈ 圆形按钮。

[!IMPORTANT]
这是第三方社区插件，并非 DeepSeek Harness 官方组件。它依赖 DSH 的动态 Cordis 能力；该工具集通常需要显式启用，不能只把 index.js 当作普通网页脚本执行。

核心功能

| 功能 | 说明 |
| --- | --- |
| 批量上传 | 文件选择器支持一次选择多张图片，也支持把多张图片拖入上传区域 |
| 缩略图管理 | 点击切换当前图片、拖动调整轮换顺序、× 删除单张、一键清空全部 |
| 自动轮换 | 一键开关，支持 2 / 4 / 6 / 8 / 10 / 12 秒六档间隔 |
| 融入度调节 | 5%–100%、步长 5%；控制背景图不透明度，默认 35% |
| 可拖动悬浮 | 展开面板和收起后的圆形按钮均可移动，并限制在可视区域附近 |
| 透明圆圈风格 | 面板与按钮不使用实心底色，以边框、文字和主题强调色发光呈现 |
| 主题自适应 | 文字、边框、强调色和底色优先读取 DSH 主题变量，切换主题后自动跟随 |
| 内存及时释放 | 删除单图、清空列表或卸载组件时撤销浏览器 Blob URL |

界面预览

批量选择与拖拽导入

Windows 文件选择器中的多图片选择

完整控制面板

自定义背景控制面板特写

展开与收起状态

| 浅色背景与收起按钮 | 深色背景与收起按钮 |
| --- | --- |
| 浅色背景与收起按钮 | 深色背景与收起按钮 |

运行条件

| 项目 | 要求 |
| --- | --- |
| DSH 表层 | 必须使用浏览器 Web 表层；纯 Headless / ACP 环境无法显示本插件 |
| 动态 Cordis | 部署必须包含 Host Runner、浏览器 Client Runner，并显式启用模型可见的 @deepseek-ai/dsh-tool-cordis |
| 客户端能力 | 页面需要提供 slots、theme 和 timer；插件会注册 shell.overlay 与 settings.section |
| 浏览器 | 支持 File API、Drag and Drop、URL.createObjectURL 的现代 Chromium 浏览器 |
| Node.js | 插件运行时不需要 Node.js；仅克隆后提取 clientCode 或执行仓库检查时建议使用 Node.js 18+ |

动态 Cordis Package 只存在于当前 DSH 进程内存中。DSH 重启后需要重新定义并运行；页面刷新后若插件没有自动恢复，请重新运行原 Package。

安装

完整步骤、更新、停止、卸载和故障排查见 安装指南。下面是最短流程。

git clone https://github.com/hanzhaoxuan2991479447-del/deepseek-harness-custom-bg.git
cd deepseek-harness-custom-bg

可选：把 cordis_define 所需的纯 clientCode 复制到剪贴板
node -e "process.stdout.write(require('./index.js').clientCode)" | Set-Clipboard

在已经启用动态 Cordis 工具的 DSH 会话中，让 Agent 读取本仓库的 index.js，取出 module.exports.clientCode，然后：

1. 调用 cordis_define，新插件使用 kind: "new" 与 idPrefix: "dsbg"；
2. 将完整 clientCode 原样放入 code.client；
3. 使用返回的 pluginId、packageId 调用 cordis_run，首次运行选择 mode: "run"；
4. 在 DSH 浏览器页面的审批入口允许装载客户端 Package。

clientCode 已经是以 return { ... } 开头的纯 JavaScript 函数体，不要再包一层函数、模板字符串或 TypeScript/JSX。

使用说明

1. 点击上传区选择多图，或直接把图片拖入虚线区域。
2. 点击缩略图立即切换背景；按住缩略图并移动可调整排序。
3. 用 × 删除单图，或点击“清空全部”。
4. 开启“自动更换”后选择轮换间隔。
5. 拖动“融入度”控制背景图不透明度。
6. 拖动面板空白处改变位置；点击“关闭”收成圆形按钮，再点击 ◈ 展开。

默认值

| 设置 | 默认值 | 范围 |
| --- | ---: | --- |
| 融入度 | 35% | 5%–100%，步长 5% |
| 自动轮换 | 关闭 | 开 / 关 |
| 轮换间隔 | 8 秒 | 2 / 4 / 6 / 8 / 10 / 12 秒 |
| 面板状态 | 展开 | 展开 / 收起 |

数据与隐私
- 图片通过浏览器 File API 读取，并以临时 Blob URL 展示；插件自身不会把图片上传到服务器或第三方服务。
- 图片、顺序、融入度和轮换设置只保存在当前页面内存，不写入磁盘，也不使用 localStorage。
- 刷新页面、关闭标签页、停止插件或重启 DSH 后，当前图片与设置不会保留。
- 高分辨率图片和大量图片会增加浏览器内存占用；不使用的图片请及时删除或清空。

主题适配

界面优先使用以下 DSH CSS 变量，并为缺失变量保留浏览器安全回退值：

| 用途 | CSS 变量 |
| --- | --- |
| 主文字、按钮边框、图标 | --dsw-alias-label-primary |
| 次要说明文字 | --dsw-alias-label-secondary |
| 发光、选中态、滑块 | --dsw-alias-brand-primary |
| 普通与弱边框 | --dsw-alias-border-l1、--dsw-alias-border-l2 |
| 页面底色与反色文字 | --dsw-alias-bg-base |

插件不会覆盖 DSH 的全局品牌色，因此强调色会随当前主题变化。截图中的粉色发光来自截图环境当时的主题强调色。

工作原理

index.js 导出 clientCode
↓
cordis_define 登记不可变 Package
↓
cordis_run + 浏览器审批
↓
注册 shell.overlay（背景层 + 控制面板）
└── 注册 settings.section（插件说明入口）

这是纯客户端 Package，不包含 Host 端代码。主体以 React 元素注册到 DSH Slot 系统；自动轮换使用 Cordis timer；样式与 Slot 注册会随插件 dispose 自动撤销。

已知限制

- 当前版本不持久化图片与设置，重载后需要重新选择。
- 只适用于 DSH Web 表层；客户端 Package 的运行需要至少一个已连接且可审批的浏览器页面。
- 图片格式是否可显示取决于浏览器解码能力；建议使用 JPEG、PNG、WebP 或 GIF。
- 背景层使用 background-size: cover，图片边缘可能按窗口比例裁切。
- 本插件使用动态 Cordis 的真实客户端运行时，请只加载你已经审阅和信任的代码。

开发与检查

仓库无构建步骤，也没有运行时依赖。

npm run check          # JavaScript 语法检查
npm run print:client   # 输出可传给 code.client 的函数体

更新已经运行的插件时，调用 cordis_define 的 kind: "existing" 并传入原 pluginId，再用新 packageId 执行 cordis_run 的 mode: "update"。详见 安装指南。

项目结构

deepseek-harness-custom-bg/
├── index.js                 # 动态客户端 Package 源码与 clientCode 导出
├── package.json             # 项目元数据与检查脚本
├── docs/
│   ├── INSTALLATION.md      # 完整安装、更新与故障排查
│   └── images/              # README 演示截图
├── CHANGELOG.md             # 版本记录
├── LICENSE                  # MIT License
└── README.md

许可证

本项目采用 MIT License。提交 Issue 或改进建议请前往本仓库的 Issues 页面。