# dsh-skin-alphacoders

[English](README.md) | 中文

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sakka6868/dsh-skin/blob/master/LICENSE)
[![npm version](https://img.shields.io/npm/v/dsh-skin-alphacoders)](https://www.npmjs.com/package/dsh-skin-alphacoders)
[![GitHub Release](https://img.shields.io/github/v/release/sakka6868/dsh-skin?label=release)](https://github.com/sakka6868/dsh-skin/releases)
[![Topic: dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-4f46e5)](https://github.com/topics/dsh-plugin)

DSH 皮肤插件：把 [Alphacoders 热门壁纸](https://alphacoders.com/popular-wallpapers) 设为 DeepSeek Harness Web GUI 的背景。符合 DSH 插件包规范的双半（Host + Client）Cordis 插件。

![壁纸效果预览](docs/preview-main.png)

![设置面板](docs/preview-gallery.png)

## 功能

- **壁纸库**：设置面板新增「壁纸」分区，浏览 Alphacoders 热门壁纸（每页 15 张、可翻页、懒加载）。
- **搜索**：按关键词搜索壁纸（走 Alphacoders 官方搜索页，单页最多 30 条）；清除搜索恢复热门列表。
- **本地图片**：点击「上传本地图片」选择 PNG/JPEG/WebP/GIF 文件即可设为壁纸；文件存于 `$DSH_HOME/storages/skin-alphacoders/`，重启后自动恢复；切换或移除壁纸时自动清理旧文件（磁盘上始终只保留一张本地壁纸）。
- **一键应用**：点击缩略图即应用为背景；主表面（对话区、侧边栏）经主题 token 半透明化透出壁纸；**设置面板与浮层（`--dsw-alias-bg-layer-2`）保持不透明**，设置窗口文字清晰可读。
- **浅深双主题壁纸（v2）**：浅色与深色主题各保存一张壁纸，切换明暗时自动跟随。
- **收藏（v2）**：画廊卡片右上角 ☆ 一键收藏，收藏持久化于 `user-data.json`，点击收藏卡即应用。
- **自动更换（v2）**：定时自动换壁纸——`随机`（远程新鲜壁纸）/`顺序`（按收藏顺序轮换）/`仅收藏`（收藏中随机），另有「立即换一张」按钮；间隔 1~168 小时可调。
- **历史记录（v2）**：每张应用过的壁纸自动记录（最多 30 条），一键恢复旧壁纸。
- **显示控制**：四种填充方式（铺满/完整/居中/拉伸）与 0~90% 遮罩强度，保证文字可读。
- **明暗联动**：跟随 DSH 主题（`light`/`dark`/`system`）自动切换遮罩色（浅色白雾、深色黑雾）。
- **持久化**：偏好经 Host 的 settings 命名空间 `ui-skin` 写入 `$DSH_HOME/settings.yaml`，重启后自动恢复；收藏与历史存于 `$DSH_HOME/storages/skin-alphacoders/user-data.json`。
- **性能**：背景默认使用 1920px 变体（`thumb-1920-<id>`），不为背景下载 5K/8K 原图；列表与搜索有内存 TTL 缓存。
- **干净卸载**：移除插件行后 route、调度器、样式全部消失，GUI 恢复默认外观。

## 安装

### 方式一：npm 安装（推荐）

```sh
# 安装到 web profile（含构建产物，无需本地构建）
dsh plugin --profile web add dsh-skin-alphacoders
```

### 方式二：从源码构建安装

```sh
# 1. 构建本包（生成 lib/ 产物）
pnpm install && pnpm build   # 或 npm install && npm run build

# 2. 安装进 web profile（从本包所在目录的上级执行）
dsh plugin --profile web add "file:<本包绝对路径>"
```

两种方式都需在 `$DSH_HOME/profiles/web/cordis.patch.yml` 中登记插件行：

```yaml
# $DSH_HOME/profiles/web/cordis.patch.yml
- insert:
    - id: skin-alphacoders
      name: 'dsh-skin-alphacoders'
      config:
        cacheTtlMs: 3600000      # 可选：列表缓存 TTL（毫秒）
        requestTimeoutMs: 20000  # 可选：抓取超时（毫秒）
```

重启 `dsh web` 生效；设置面板 → 「壁纸」分区即可使用。

> 提示：开发迭代时，可用目录联接把 profile 的 `node_modules/dsh-skin-alphacoders` 指向源码目录（pnpm 的 `file:` 依赖默认硬链接复制，修改源码后需要重建联接或重新 add）。

## 架构

```
┌─ Host 半（node）─────────────────────────────────────────────┐
│  fetch + 解析 alphacoders popular-wallpapers?page=N          │
│  （服务端渲染的 schema.org ImageObject，15 条/页）            │
│  fetch + 解析 search/view?q=<关键词>（单页 ≤30 条）           │
│  内存 TTL 缓存（默认 1 小时）                                 │
│  ctx.settings.register('ui-skin', SkinSettingsSchema)        │
│  user-data.json（收藏 ≤200、历史 ≤30，原子写入）              │
│  自动更换调度器（setTimeout 链，按模式选池）                  │
│  HTTP route（经 ctx.webServer）：                            │
│    GET  /skin-alphacoders/wallpapers?page=N | ?query=Q       │
│    GET  /skin-alphacoders/settings                           │
│    POST /skin-alphacoders/settings   （字段白名单 patch）     │
│    GET  /skin-alphacoders/user-data                          │
│    POST /skin-alphacoders/favorites（+ /favorites/remove）   │
│    POST /skin-alphacoders/theme   （当前主题上报）            │
│    POST /skin-alphacoders/auto-change/now                    │
│    GET  /skin-alphacoders/health                             │
└──────────────────────────────────────────────────────────────┘
        同源 fetch（无 CORS 面）
┌─ Client 半（浏览器）─────────────────────────────────────────┐
│  skin-store：GET/POST settings route 的本地快照 + 订阅        │
│  user-data store：收藏/历史快照                              │
│  双主题镜像：theme/change 时把当前主题槽同步到扁平字段         │
│              （带 fromTheme 标记，不产生历史记录）            │
│  background：body::before 壁纸层 + ::after 遮罩层            │
│              + ctx.theme.overrideTokens 表面半透明           │
│              （签名去重防 theme/change 重入风暴）             │
│  settings.section「壁纸」：画廊 + 收藏 + 历史 + 自动换 + 主题 tab│
└──────────────────────────────────────────────────────────────┘
```

### 为什么不用 settingsScope 传输

api-proxy 的 settings 协议是 Host 白名单（`locale`、`ui-theme` 等），仓库外插件注册的 namespace 只会得到 `settings-not-exposed`。因此本插件在 Host 侧仍用 `SettingsScope.update` 持久化（owner seam 无白名单限制），浏览器侧改为经自己的 HTTP route 读写，持久化文档仍是 `$DSH_HOME/settings.yaml` 的 `ui-skin` 分节。

## 配置

| 字段 | 默认 | 说明 |
|---|---|---|
| `cacheTtlMs` | `3600000` | 壁纸列表页内存缓存时长（毫秒） |
| `requestTimeoutMs` | `20000` | 抓取 alphacoders.com 的超时（毫秒） |

## 版权与合规

- 壁纸版权归原作者与 [Alphacoders](https://alphacoders.com) 所有；本插件仅供个人使用，不批量下载或再分发壁纸。
- 请在网络策略允许访问 `alphacoders.com` 与其图片 CDN（`images*.alphacoders.com`）的环境中使用。

## 验证

`e2e/verify.mjs` 是 Puppeteer（连接本机 Chrome）端到端验证：需先按上述步骤装好插件并启动 `dsh --profile web --port 3090`，再执行：

```sh
node e2e/verify.mjs
```

覆盖（39 项断言）：画廊渲染、收藏往返、双主题独立壁纸、明暗联动、刷新持久化、历史恢复、自动更换（仅收藏模式）、搜索、本地上传与清理、收藏/历史持久化、无页面错误。