dsh-chat-background 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# 更新日志
+
+本项目遵循 [SemVer](https://semver.org/lang/zh-CN/)；版本号与 `package.json`、`client.js` banner 保持一致。
+
+## [1.1.0] - 2026-11-04
+
+阅读体验版本：对话内容按轮次分区显示，设置页控件在不同屏幕/缩放下保持稳定。
+
+### 新增
+
+- **按轮次绘制的对话遮罩**：每一轮对话（用户消息 + 对应回复）单独一张遮罩卡，卡片宽度 = 阅读列宽 + 两侧各 24px 留白，随阅读列拖拽手柄自动变化；轮次之间露出壁纸，不再整列铺一层遮罩。
+- **舒适轮次间距**：把 DSH 的轮次布局间距从原生 12px 调到 28px（写回宿主的 `--dsh-chat-flow-gap`），配合卡片上边 6px 出血，卡片间保留约 14px 壁纸缝，用户消息气泡完整包在遮罩内。
+
+### 变更
+
+- **主窗口遮罩层**现在控制“每轮对话卡片”的透明度，而不是整块主窗口；0 为无遮罩，100 为不透明卡片。
+- **设置页控件模块化**：所有设置行改为两列 grid，右侧控件组保持自身宽度并右对齐；轮换设置使用固定的 caption/输入/数值槽位；下拉框、按钮、颜色块固定尺寸，不再随语言、字体缩放或 DPI 漂移。
+- **滑块**改用尺寸变量推导 thumb 偏移，替代手调像素值；窄屏（≤640px）控件堆叠到说明下方。
+
+### 修复
+
+- 切换窗口后主窗口/右侧栏偶发变白：通过稳定的槽位标记清除 app 画在布局 frame、主窗口列和右侧栏上的不透明底色，并在标题栏标记变化、窗口重新获得焦点或恢复可见时重新测量。
+- 设置页滑块圆点在部分缩放/DPI 下浮到轨道上方、控件互相挤压错位。
+- 对话遮罩层被宿主的 flow 间距下推 6px，导致用户消息气泡顶部露在遮罩外。
+- npm 安装说明与实际发布状态不一致。
+
+### 安装与兼容
+
+- DSH 桌面端 `>=0.2.1-rc.3`；Node `^22.19.0 || >=24.0.0`。
+- 支持从 GitHub、npm 或手动安装到 profile，详见 [README](README.md#安装)。
+
+## [1.0.0] - 2026-11-02
+
+首个公开版本。
+
+### 功能
+
+- **背景图**：从 `~/.dsh/backgrounds/` 选择图片铺满 DSH 界面；支持 png / apng / jpg / jpeg / webp / gif / avif / bmp / svg，GIF、动画 WebP、APNG 按帧播放。
+- **独立遮罩**：左侧栏、主窗口、右侧栏三个区域可分别设置 0–100 的遮罩不透明度，浅色/深色主题自动适配。
+- **背景轮换**：固定/轮换两种显示方式；间隔 5–300 秒；切换特效支持淡入淡出、渐变过渡、无，时长 0–3 秒。
+- **轮换分组**：勾选背景库中的图片组成轮换集合；行内缩略图、5 行滚动列表、拖动排序，勾选不改变顺序。
+- **右侧栏全屏**：全屏预览时保留左侧栏，只把主窗口与原右栏变为右栏内容；统一遮罩、立即切换，无闪烁。
+- **背景条**：输入栏下方一条与输入栏等宽、包住用量数据的背景条，可自定义颜色。
+- **任务进度条**：有任务清单时按完成度显示，执行中按步数估算，空闲时隐藏。
+- **Token 总用量**：左下角显示所有会话（含已归档）的累计 token 用量，可调字号。
+- **图片滚轮缩放**：聊天图片灯箱与右侧栏图片预览支持滚轮缩放，双击灯箱还原；不作用于设置页图片。
+
+### 安装与兼容
+
+- DSH 桌面端 `>=0.2.1-rc.3`；Node `^22.19.0 || >=24.0.0`。
+- 支持从 GitHub、npm 或手动安装到 profile，详见 [README](README.md#安装)。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LittleLemonJam
+
+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.en.md

@@ -0,0 +1,130 @@
+# dsh-chat-background
+
+> A visual background plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) desktop:
+> wallpaper, independent scrims for the three columns, background rotation with groups, a bar under the composer,
+> a task progress bar and an all-session token total — all configured in **Settings → Page settings**.
+
+[![CI](https://github.com/LittleLemonJam/dsh-chat-background/actions/workflows/ci.yml/badge.svg)](https://github.com/LittleLemonJam/dsh-chat-background/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![Main UI: wallpaper, composer strip, progress bar and token line](assets/screenshots/main-ui.png)
+
+## What it does
+
+Pick a few pictures, put them in the background folder (default `~/.dsh/backgrounds/`, created automatically if
+missing), and the chat window gets a wallpaper. Keep one image fixed or rotate through a group of favourites; tune the
+left sidebar, main window and right sidebar scrims separately so text stays readable. The plugin also adds a bar under
+the input, a task progress bar and a total token usage line.
+
+## Features
+
+| Feature         | Description                                                                                                                                                          |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Chat background | Picks an image from the background folder and paints it across the app. png / apng / jpg / jpeg / webp / gif / avif / bmp / svg; GIF, animated WebP and APNG animate |
+| Rotation        | Keep one image fixed or rotate automatically every 5–300 seconds                                                                                                     |
+| Transition      | Fade, fade-through or none; duration 0–3 seconds                                                                                                                     |
+| Rotation group  | Rotate only checked images; thumbnails, a five-row scrollable list and drag reordering that never changes on selection                                               |
+| Column scrims   | Independent 0–100 opacity for the left sidebar, main window and right sidebar                                                                                        |
+| Composer bar    | A bar as wide as the input wrapping the usage row, with a configurable colour                                                                                        |
+| Task progress   | Todo completion when available, a step estimate while running, hidden when idle                                                                                      |
+| Total tokens    | All-session (archived included) token usage above the account row, adjustable font size                                                                              |
+| Image zoom      | Wheel zoom in the chat image lightbox and right-sidebar preview; double-click resets the lightbox                                                                    |
+
+![Settings → Page settings](assets/screenshots/settings-page.png)
+
+## Install
+
+Requirement: DSH desktop **≥ 0.2.1-rc.3**. Node ≥ 22.19 is only needed to build and test from source.
+
+### From GitHub (recommended)
+
+```bash
+dsh plugin --profile desktop add github:LittleLemonJam/dsh-chat-background
+```
+
+Fully quit and reopen DSH afterwards — the host half loads at boot; refreshing the page is not enough.
+Check **Plugins → Installed** to confirm `dsh-chat-background` is enabled.
+
+### From npm
+
+```bash
+dsh plugin --profile desktop add dsh-chat-background
+```
+
+The npm package tracks the GitHub release (currently `1.1.0`); either channel works.
+
+### Manual install
+
+1. Copy `package.json`, `index.js`, `host/`, `client.js`, `cordis.patch.yml`, `locale/` and `icon.svg` into
+   `~/.dsh/profiles/desktop/node_modules/dsh-chat-background/`;
+2. Add `"dsh-chat-background": "file:./node_modules/dsh-chat-background"` to the profile's `dependencies` and
+   `dsh-chat-background` to `dsh.profile.bundles`;
+3. Add the following to the profile's `cordis.patch.yml`:
+
+   ```yaml
+   - insert:
+       - id: chat-background
+         name: 'dsh-chat-background'
+   ```
+
+4. Restart DSH.
+
+### Where pictures go
+
+Pictures live in `~/.dsh/backgrounds/` (`C:\Users\<you>\.dsh\backgrounds\` on Windows; set `DSH_BACKGROUNDS_DIR` to use
+another folder). **You do not need to create the folder first** — opening the settings page or pressing **Open folder**
+creates it automatically. Drop images in, then press **Rescan** under **Settings → Page settings → Background**.
+
+## Usage
+
+- **Fixed / rotation**: choose the display mode under the image picker. Rotation uses the checked images in the
+  rotation group; if nothing is checked, the whole library is used.
+- **Progress**: exact when the agent keeps a todo list; otherwise estimated from this turn's steps (capped at 92%);
+  hidden while idle.
+- **Tokens**: totals across all sessions (archived included), cached for 10 seconds and refreshed once a minute.
+- **Themes and scrims**: light/dark themes adapt automatically. A 100% scrim is fully opaque; 0% shows the wallpaper.
+- **Right-sidebar full screen**: the left sidebar stays visible while the main window and the original right sidebar
+  become the right sidebar content; exiting restores the layout.
+
+## Compatibility
+
+| Item             | Value                                |
+| ---------------- | ------------------------------------ |
+| Verified DSH     | `0.2.1-rc.3` (Electron 44 / Node 24) |
+| DSH requirement  | `>=0.2.1-rc.3`                       |
+| Node requirement | `^22.19.0 \|\| >=24.0.0`             |
+| Platforms        | Windows / macOS / Linux desktop      |
+
+When the GUI is opened through a non-loopback address (reverse proxy or remote access), the image and token routes are
+rejected by the request fence by default; set `DSH_CHAT_BACKGROUND_ALLOWED_HOSTS=<your-host>` for a trusted proxy.
+
+## Security and privacy
+
+- Reads only the background folder and local session projections; no internet requests and no credentials;
+- HTTP routes are loopback-only with Host / Origin / Fetch metadata checks;
+- SVG is served with a sandbox CSP, so opening it directly cannot run scripts;
+- File names, image size, directory scan count and session file size are all bounded.
+
+See [SECURITY.md](SECURITY.md) for details.
+
+## Development
+
+```bash
+npm install
+npm run build        # src/ → client.js (commit the bundle)
+npm run check        # manifest, locale, build freshness, encoding/i18n checks
+npm run test:unit    # unit tests
+npm run test:e2e     # isolated end-to-end suite (requires a local DSH install)
+npm run verify       # format:check + build + check + test:unit
+```
+
+See the [development guide](docs/DEVELOPMENT.md), [architecture](docs/ARCHITECTURE.md) and
+[testing guide](docs/TESTING.md).
+
+## Publishing
+
+See the [publishing guide](docs/PUBLISHING.md) for GitHub, npm and plugin-market steps.
+
+## License
+
+[MIT](LICENSE) © 2026 LittleLemonJam

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# dsh-chat-background
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）桌面端换一张好看的背景：
+> 聊天背景图、三栏独立遮罩、背景轮换与分组、输入栏背景条、任务进度条、Token 总用量，全部在「设置 → 页面设置」里调整。
+
+[![CI](https://github.com/LittleLemonJam/dsh-chat-background/actions/workflows/ci.yml/badge.svg)](https://github.com/LittleLemonJam/dsh-chat-background/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![主界面：背景图、输入栏背景条、进度条与 Token 行](assets/screenshots/main-ui.png)
+
+## 简介
+
+这是一个本地运行的 DSH 插件。选几张喜欢的图片放进背景文件夹（默认 `~/.dsh/backgrounds/`，不存在会自动创建），
+就能让聊天界面拥有自己的壁纸：可以固定一张，也可以按间隔自动轮换；左侧栏、主窗口、右侧栏的遮罩深浅可以分别调，界面文字仍然清楚可读。
+另外还附带输入栏背景条、任务进度条和全会话 Token 用量等小工具。
+
+## 功能
+
+| 功能         | 说明                                                                                                                    |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| 聊天背景     | 从背景文件夹选图铺满界面；支持 png / apng / jpg / jpeg / webp / gif / avif / bmp / svg，GIF、动画 WebP、APNG 会播放动画 |
+| 背景轮换     | 固定一张或自动轮换；轮换间隔 5–300 秒                                                                                   |
+| 切换特效     | 淡入淡出、渐变过渡、无；时长 0–3 秒                                                                                     |
+| 轮换分组     | 只轮换勾选的图片；缩略图、5 行滚动列表、拖动排序，勾选不改变顺序                                                        |
+| 三栏遮罩     | 左侧栏 / 主窗口 / 右侧栏分别设置 0–100 遮罩不透明度                                                                     |
+| 背景条       | 输入栏下方一条等宽背景条，包住用量数据，可自定义颜色                                                                    |
+| 任务进度条   | 有任务清单时显示完成度，执行中按步数估算，空闲时隐藏                                                                    |
+| Token 总用量 | 左下角显示所有会话（含已归档）的累计 token 用量，可调字号                                                               |
+| 图片滚轮缩放 | 聊天图片灯箱、右侧栏图片预览可滚轮缩放；灯箱双击还原                                                                    |
+
+![设置 → 页面设置](assets/screenshots/settings-page.png)
+
+## 安装
+
+前置：DSH 桌面端 **≥ 0.2.1-rc.3**。Node ≥ 22.19 只用于从源码构建和测试，普通安装不需要。
+
+### 从 GitHub 安装（推荐）
+
+```bash
+dsh plugin --profile desktop add github:LittleLemonJam/dsh-chat-background
+```
+
+安装后**完全退出并重新打开** DSH 桌面端（宿主半在启动时加载，只刷新页面不够）。
+可以在 **插件 → 已安装** 里确认 `dsh-chat-background` 处于启用状态。
+
+### 从 npm 安装
+
+```bash
+dsh plugin --profile desktop add dsh-chat-background
+```
+
+npm 包与 GitHub 发布同步（当前 `1.1.0`），两条安装方式任选其一即可。
+
+### 手动安装
+
+1. 把仓库（或 `npm pack` 解压后）的 `package.json`、`index.js`、`host/`、`client.js`、`cordis.patch.yml`、
+   `locale/`、`icon.svg` 放进 `~/.dsh/profiles/desktop/node_modules/dsh-chat-background/`；
+2. 在 profile 的 `package.json` 的 `dependencies` 加入
+   `"dsh-chat-background": "file:./node_modules/dsh-chat-background"`，并把 `dsh-chat-background` 加入
+   `dsh.profile.bundles`；
+3. 在 profile 的 `cordis.patch.yml` 追加：
+
+   ```yaml
+   - insert:
+       - id: chat-background
+         name: 'dsh-chat-background'
+   ```
+
+4. 重启 DSH。
+
+### 背景图放在哪里
+
+图片固定放在 `~/.dsh/backgrounds/`（Windows 为 `C:\Users\<用户名>\.dsh\backgrounds\`；也可以用环境变量
+`DSH_BACKGROUNDS_DIR` 指向其他目录）。**目录不存在不用手动创建**：第一次打开设置页或点「打开文件夹」时插件会自动建好。
+把图片放进去后，在 **设置 → 页面设置 → 背景** 点「重新扫描」即可看到。
+
+## 使用
+
+- **固定/轮换**：在「背景显示方式」里选择；轮换时只使用「轮换分组」里勾选的图片，全部不勾选则使用整个背景库。
+- **进度条**：agent 有任务清单时按「已完成 / 总数」显示；没有清单但正在执行时按本轮步数估算，最高 92%；空闲时隐藏。
+- **Token 总用量**：汇总所有会话（含已归档）的 token 用量，每 10 秒缓存、每分钟刷新；数据只在本机读取。
+- **主题与遮罩**：浅色/深色自动适配；遮罩调到 100 时该区域完全不透明，调到 0 时完全显示背景。
+- **右侧栏全屏**：全屏预览时左侧栏保持可见，主窗口与原右栏变为右栏内容；退出后恢复原布局。
+
+## 兼容性
+
+| 项            | 值                                    |
+| ------------- | ------------------------------------- |
+| 已验证 DSH    | `0.2.1-rc.3`（Electron 44 / Node 24） |
+| DSH 版本要求  | `>=0.2.1-rc.3`                        |
+| Node 版本要求 | `^22.19.0 \|\| >=24.0.0`              |
+| 支持平台      | Windows / macOS / Linux 桌面端        |
+
+通过**非回环地址**（反向代理或远程访问）打开 GUI 时，图片与 Token 路由默认会被请求栅栏拒绝；请设置
+`DSH_CHAT_BACKGROUND_ALLOWED_HOSTS=<你的主机名>`（仅限可信代理）后再使用。
+
+## 安全与隐私
+
+- 只读取背景文件夹和本机会话投影，不访问互联网、不读取凭据；
+- 所有 HTTP 路由只监听本机回环地址，并校验 Host / Origin / Fetch 元数据；
+- SVG 以沙箱 CSP 提供，顶层打开也不会执行脚本；
+- 文件名、图片大小、目录扫描数量和会话文件大小都有上限。
+
+细节见 [SECURITY.md](SECURITY.md)。
+
+## 开发
+
+```bash
+npm install
+npm run build        # src/ → client.js（提交构建产物）
+npm run check        # 清单、locale、构建产物、编码/i18n 检查
+npm run test:unit    # 单元测试
+npm run test:e2e     # 隔离实例的端到端测试（需要本机 DSH）
+npm run verify       # format:check + build + check + test:unit
+```
+
+仓库结构、热更新规则与调试方法见 [开发指南](docs/DEVELOPMENT.md)；
+实现与不变量见 [架构说明](docs/ARCHITECTURE.md)；测试说明见 [测试指南](docs/TESTING.md)。
+
+## 发布
+
+发布流程、GitHub / npm / 插件市场提交说明见 [发布指南](docs/PUBLISHING.md)。
+
+## 许可证
+
+[MIT](LICENSE) © 2026 LittleLemonJam