deepseek-harness-background 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HaoyueQin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# DeepSeek Harness Background
+
+[![GitHub stars](https://img.shields.io/github/stars/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/stargazers)
+[![GitHub release](https://img.shields.io/github/v/release/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/releases)
+[![CI](https://img.shields.io/github/actions/workflow/status/HaoyueQin/deepseek-harness-background/ci.yml?style=flat-square&logo=githubactions&logoColor=white)](https://github.com/HaoyueQin/deepseek-harness-background/actions)
+[![GitHub issues](https://img.shields.io/github/issues/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/issues)
+[![GitHub last commit](https://img.shields.io/github/last-commit/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/commits)
+[![Top language](https://img.shields.io/github/languages/top/HaoyueQin/deepseek-harness-background?style=flat-square&logo=typescript)](https://github.com/HaoyueQin/deepseek-harness-background)
+[![Repo size](https://img.shields.io/github/repo-size/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background)
+[![License](https://img.shields.io/github/license/HaoyueQin/deepseek-harness-background?style=flat-square)](LICENSE)
+
+[English](README.md) | [中文](README.zh.md)
+
+A custom **background image plugin** for the DeepSeek Harness Web GUI (`dsh web`): upload a local picture, or paste an image URL, and render it behind the whole app surface with adjustable **opacity**, **readability scrim**, **panel transparency** and **frosted-glass blur** — everything live-previewed inside the settings panel and committed automatically on release.
+
+The look (fixed wallpaper layer + theme-aware scrim + translucent glass panels driven by `--dsw-*` design tokens) is modeled on the community `dsh-wallpaper-engine` implementation.
+
+## Screenshots
+
+|  |  |
+| --- | --- |
+| **Home** | <img src="docs/images/home.jpg" alt="Custom background on the home screen" width="640"> |
+| **Conversation** | <img src="docs/images/conversation.jpg" alt="Custom background behind the conversation" width="640"> |
+| **Settings** | <img src="docs/images/settings.jpg" alt="Background settings row with live preview" width="640"> |
+
+## Features
+
+- **Local upload** — pick a JPG / PNG / WebP / GIF from your computer; the plugin stores it under the harness home and serves it over a same-origin route (admitted only when the declared MIME, detected signature and extension all agree).
+- **Paste a URL** — drop an `http(s)` image link and press Enter.
+- **In-panel live preview** — a preview surface at the top of the row renders the image + scrim + a frosted glass bubble; dragging any slider repaints it instantly.
+- **Stepped sliders** — ratio controls snap in **5% steps**, blur radii in 1/2px steps; dragging only repaints, **release commits** (one write per gesture, no jank).
+- **Five controls** — wallpaper opacity, readability scrim, panel opacity, frosted-glass blur, and wallpaper blur.
+- **Fit modes** — `cover` (fill, crop) or `contain` (whole image).
+- **Theme-aware scrim** — the light theme uses a white veil (lifts the art so dark text keeps contrast); the dark theme automatically switches to a black veil (dims the art so light text keeps contrast).
+- **Frosted glass** — while a background is active, the composer card and message bubbles turn into translucent glass over the wallpaper (specular sheen + `backdrop-filter`), with the blur radius driven by the glass-blur slider. `panelOpacity` at 100% restores the official opaque surfaces.
+- **Persisted in the official settings document** (`$DSH_HOME/settings.yaml`), waits out restarts.
+- **Clean teardown** — disabling, clearing or uninstalling restores the original background exactly; the plugin only ever removes what it wrote.
+
+## Install
+
+The plugin is a standard out-of-tree dsh bundle, published on npm:
+
+```sh
+dsh plugin --profile web add deepseek-harness-background
+```
+
+From a local checkout (development):
+
+```sh
+dsh plugin --profile web add /path/to/deepseek-harness-background
+```
+
+From a source checkout:
+
+```sh
+pnpm dsh plugin --profile web add /path/to/deepseek-harness-background
+```
+
+Or from git:
+
+```sh
+dsh plugin --profile web add github:<you>/deepseek-harness-background#<commit>
+```
+
+Restart to load it:
+
+```sh
+dsh --profile web
+```
+
+## Usage
+
+1. Start the Web UI (`dsh --profile web`) and open it in a browser.
+2. Open **Settings** (bottom-left) → **General** → the **Custom Background** row (in the same area as the Appearance row).
+3. **Upload** an image or **paste a URL** — the background applies immediately and the preview surface above updates in sync.
+4. Tune the controls — sliders snap in steps and **commit on release**:
+
+| Control | Meaning |
+| --- | --- |
+| 不透明度 / Opacity | `0..100%` image opacity (5% steps); lowering it fades the wallpaper toward the surface. |
+| 遮罩 / Scrim | `0..95%` readability veil over the image (5% steps); white in light mode, black in dark mode. |
+| 面板不透明度 / Panel opacity | `0..100%` surface transparency (5% steps); at `100%` the official panels stay opaque (no glass). |
+| 毛玻璃模糊 / Glass blur | `0..40px` `backdrop-filter` blur on the translucent surfaces (1px steps). |
+| 壁纸模糊 / Wallpaper blur | `0..60px` blur of the wallpaper image itself (2px steps). |
+| 填充方式 / Fit | `cover` or `contain`. |
+
+5. **清除背景** removes the background and restores the stock look.
+
+## How it works
+
+- The **settings row** lives in the official General settings section (`settings.general.item` slot), next to the Appearance row. Its chrome uses only `--dsw-alias-*` design tokens (buttons / pills / segmented control / slider track match the official shell); sliders are native `input[type=range]` with 5% / 1–2px steps and release-commit.
+- The plugin's own host routes (`/api/bg-wallpaper/*`: `settings`, `upload`, `image/<id>`) read/write the section and serve uploads with same-origin + size caps + MIME/signature checks + a path-escape fence. A custom route family is used because the api-proxy settings allowlist does not expose third-party namespaces over the settings RPC.
+- The background is drawn as a fixed `z-index:-2` wallpaper layer plus a `z-index:-1` scrim on `body`, toggled by the `data-dsh-bg` attribute; the scrim switches white/black by `data-ds-dark-theme` in the injected stylesheet; the frosted-glass effect overrides the shell's surface design tokens.
+- Uploads live under `$DSH_HOME/deepseek-harness-background/` (content-addressed ids). Switching to a new image or clearing the background deletes the superseded upload file, so the directory never accumulates dead images. Disable / uninstall leaves nothing behind.
+
+## Development
+
+```sh
+pnpm install          # first time; runs prepare (build)
+pnpm run typecheck    # tsc
+pnpm test             # vitest contract tests
+pnpm run build        # tsdown: lib/index.js (host) + lib/client.js (browser bundle)
+```
+
+```
+deepseek-harness-background/          # the plugin repo (package name stays the npm-style id)
+├── package.json          # dsh.bundle.patch + dsh.client.inject declarations
+├── cordis.patch.yml      # inserts the deepseek-harness-background row into the web roster
+├── tsdown.config.ts      # official clientBundle preset
+├── src/
+│   ├── index.ts          # host half: ui-background namespace + API routes
+│   ├── routes.ts         # /api/bg-wallpaper/{settings,upload,image/<id>}
+│   ├── schema.ts         # host-side schemastery schema
+│   ├── settings.ts       # constants/types shared with the client
+│   ├── harness-home.ts   # $DSH_HOME / ~/.dsh resolution
+│   └── client/
+│       ├── index.ts          # painter lifecycle + settings row registration
+│       ├── backdrop.ts       # fixed wallpaper layer + scrim + glass surface + preview vars
+│       ├── background-css.ts # injected stylesheet (layers, glass, light/dark scrim, variables)
+│       ├── SettingsRow.tsx   # the General-settings row (preview surface + stepped sliders)
+│       ├── SettingsRow.module.css # row styles (official tokens)
+│       ├── settings-client.ts# fetch transport (read/write/upload)
+│       └── locales.ts        # zh/en copy
+└── tests/                  # schema, routes, apply (painter), settings-row contracts
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,129 @@
+# DeepSeek Harness Background
+
+[![GitHub stars](https://img.shields.io/github/stars/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/stargazers)
+[![GitHub release](https://img.shields.io/github/v/release/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/releases)
+[![CI](https://img.shields.io/github/actions/workflow/status/HaoyueQin/deepseek-harness-background/ci.yml?style=flat-square&logo=githubactions&logoColor=white)](https://github.com/HaoyueQin/deepseek-harness-background/actions)
+[![GitHub issues](https://img.shields.io/github/issues/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/issues)
+[![GitHub last commit](https://img.shields.io/github/last-commit/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background/commits)
+[![Top language](https://img.shields.io/github/languages/top/HaoyueQin/deepseek-harness-background?style=flat-square&logo=typescript)](https://github.com/HaoyueQin/deepseek-harness-background)
+[![Repo size](https://img.shields.io/github/repo-size/HaoyueQin/deepseek-harness-background?style=flat-square&logo=github)](https://github.com/HaoyueQin/deepseek-harness-background)
+[![License](https://img.shields.io/github/license/HaoyueQin/deepseek-harness-background?style=flat-square)](LICENSE)
+
+[English](README.md) | 中文
+
+一个 **DeepSeek Harness Web GUI**（`dsh web`）的**自定义背景图片插件**：上传一张本地图片，或粘贴一个图片链接，把它绘制在整个应用界面背后，并可调节**不透明度**、**可读性遮罩**、**面板透明**与**毛玻璃模糊** —— 全部在设置面板内实时预览、松手自动保存。
+
+外观（固定壁纸层 + 主题自适应遮罩 + 由 `--dsw-*` 设计 token 驱动的半透明玻璃面板）借鉴了社区 `dsh-wallpaper-engine` 的实现。
+
+## 截图
+
+|  |  |
+| --- | --- |
+| **首页** | <img src="docs/images/home.jpg" alt="首页上的自定义背景" width="640"> |
+| **会话界面** | <img src="docs/images/conversation.jpg" alt="会话背后的自定义背景" width="640"> |
+| **设置界面** | <img src="docs/images/settings.jpg" alt="带实时预览的背景设置行" width="640"> |
+
+## 功能
+
+- **本地上传** —— 从电脑选择 JPG / PNG / WebP / GIF 图片；插件存入 harness home 目录，经同源路由提供（仅当声明的 MIME、探测到的文件签名与扩展名三者一致才被接受）。
+- **粘贴 URL** —— 输入 `http(s)` 图片链接后回车即可。
+- **面板内实时预览** —— 设置行顶部有预览卡：图片 + 遮罩 + 毛玻璃气泡；拖动任意滑块即时重绘，所见即所存。
+- **阻尼滑块** —— 比例类滑块按 **5% 步进**、模糊类按 1/2px 步进吸附；拖动过程只改画面，**松手才保存**（每次手势一次写入，不再抖动）。
+- **五个调节项** —— 壁纸不透明度、可读性遮罩、面板不透明度、毛玻璃模糊、壁纸模糊。
+- **填充方式** —— `cover`（铺满、裁剪）或 `contain`（完整、留白）。
+- **主题自适应遮罩** —— 浅色主题用白色纱帘（把图片提亮保持深色文字对比度），深色主题自动换成黑色纱帘（压暗图片保持浅色文字对比度）。
+- **毛玻璃** —— 启用背景后，输入框卡片与消息气泡变成覆盖在壁纸上的半透明玻璃（顶部白色高光渐变 + `backdrop-filter`），模糊半径由「毛玻璃模糊」滑块驱动；「面板不透明度」调至 100% 即恢复官方不透明表面。
+- **持久化到官方设置文档** —— 存于 `$DSH_HOME/settings.yaml`，跨重启保留。
+- **干净卸载** —— 关闭、清除或卸载后完整恢复原背景；插件只移除自己写过的内容。
+
+## 安装
+
+这是一个标准的 out-of-tree dsh bundle，已发布到 npm：
+
+```sh
+dsh plugin --profile web add deepseek-harness-background
+```
+
+从本地 checkout 安装（开发用）：
+
+```sh
+dsh plugin --profile web add /path/to/deepseek-harness-background
+```
+
+从源代码检出安装：
+
+```sh
+pnpm dsh plugin --profile web add /path/to/deepseek-harness-background
+```
+
+或从 git 安装：
+
+```sh
+dsh plugin --profile web add github:<you>/deepseek-harness-background#<commit>
+```
+
+安装后重启：
+
+```sh
+dsh --profile web
+```
+
+## 使用
+
+1. 启动 Web UI（`dsh --profile web`）并在浏览器打开。
+2. 打开 **设置**（左下角）→ **通用** → 找到 **自定义背景** 一行（与「外观」行同一区域）。
+3. **上传**图片或**粘贴 URL** —— 背景立即生效，面板顶部的预览卡同步显示。
+4. 调整控件，滑块均为阻尼步进、**松手才保存**：
+
+| 控件 | 说明 |
+| --- | --- |
+| 不透明度 | `0..100%` 图片不透明度（5% 步进）；调低让壁纸向表面色淡出。 |
+| 遮罩 | `0..95%` 图片上方的可读性纱帘（5% 步进），浅色主题白色、深色主题黑色。 |
+| 面板不透明度 | `0..100%` 表面透明程度（5% 步进）；为 `100%` 时官方面板保持不透明（无玻璃）。 |
+| 毛玻璃模糊 | `0..40px` 半透明表面上的 `backdrop-filter` 模糊（1px 步进）。 |
+| 壁纸模糊 | `0..60px` 壁纸图片本身的模糊（2px 步进）。 |
+| 填充方式 | `cover`（铺满）或 `contain`（完整）。 |
+
+5. 点 **清除背景** 移除背景，恢复默认外观。
+
+## 原理
+
+- **设置行**位于官方「通用」设置分区的 `settings.general.item` 槽中，紧挨「外观」行。控件样式全部使用 `--dsw-alias-*` 设计 token（按钮 / 胶囊 / 分段控件 / 滑块轨道与官方 chrome 一致），滑块为原生 `input[type=range]` 的 5% / 1–2px 步进 + 松手提交。
+- 插件自有的 host 路由（`/api/bg-wallpaper/*`：`settings`、`upload`、`image/<id>`）负责读写设置与提供上传图片，带同源校验、大小上限、MIME/签名校验与路径穿越防护。使用自定义路由族，是因为 api-proxy 的 settings 白名单不向第三方命名空间开放 settings RPC。
+- 背景以 `body` 上一张固定的 `z-index:-2` 壁纸层 + `z-index:-1` 遮罩绘制，由 `data-dsh-bg` 属性开关；遮罩在注入样式表里按 `data-ds-dark-theme` 切换白/黑纱帘；毛玻璃效果通过覆盖外壳的 surface 设计 token 实现。
+- 上传文件存放在 `$DSH_HOME/deepseek-harness-background/`（内容寻址 id）。切换新图片或清除背景时，被替换的旧上传文件会被自动回收，目录不会堆积死图片。关闭 / 卸载后不留残留。
+
+## 开发
+
+```sh
+pnpm install          # 首次；会运行 prepare（构建）
+pnpm run typecheck    # tsc
+pnpm test             # vitest 契约测试
+pnpm run build        # tsdown：lib/index.js（host）+ lib/client.js（浏览器 bundle）
+```
+
+```
+deepseek-harness-background/          # 插件仓库（包名保留 npm 风格 id）
+├── package.json          # dsh.bundle.patch + dsh.client.inject 声明
+├── cordis.patch.yml      # 向 web 插件名册插入 deepseek-harness-background 一行
+├── tsdown.config.ts      # 官方 clientBundle 预设
+├── src/
+│   ├── index.ts          # host 半部：ui-background 命名空间 + API 路由
+│   ├── routes.ts         # /api/bg-wallpaper/{settings,upload,image/<id>}
+│   ├── schema.ts         # host 侧 schemastery schema
+│   ├── settings.ts       # 两端共享的常量/类型
+│   ├── harness-home.ts   # $DSH_HOME / ~/.dsh 解析
+│   └── client/
+│       ├── index.ts          # painter 生命周期 + 设置行注册
+│       ├── backdrop.ts       # 固定壁纸层 + 遮罩 + 玻璃表面 + 预览变量
+│       ├── background-css.ts # 注入的样式表（层、玻璃、明暗遮罩、变量）
+│       ├── SettingsRow.tsx   # 通用设置中的设置行（预览卡 + 阻尼滑块）
+│       ├── SettingsRow.module.css # 设置行样式（官方 token）
+│       ├── settings-client.ts# fetch 传输层（读/写/上传）
+│       └── locales.ts        # 中/英文案
+└── tests/                  # 契约测试（schema、routes、apply/painter、设置行）
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# deepseek-harness-background bundle patch: inserts its dshClient row into
+# the web plugin roster. The bundle is the official dsh plugin shape — install
+# it with `dsh plugin --profile <name> add <path-or-git-url>` (or `pnpm dsh ...`
+# from a fresh source checkout).
+- insert:
+    - id: deepseek-harness-background
+      name: 'deepseek-harness-background'