@dsh-external/dsh-web-skins

Readme

# 🎨 dsh-external/dsh-skins —— DSH Web 换肤插件

[English](README.en.md) | 中文

> 正经插件去 [dsh-hub](https://github.com/omdsh-dev/dsh-hub)，整活插件去 [toybox](https://github.com/dsh-external/toybox)，**换肤皮肤来 dsh-skins**。
> 一个给 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/dsh) **Web GUI** 换肤的客户端插件仓库：每个皮肤都是官方 `ThemeService` 的第三方主题注册（`--dsw-*` alias token 覆盖，零核心改动），富皮肤在此基础上叠加 AI 生图背景。装得上、换得掉、有验收标准。

> **版权**：本仓库为独立插件项目，版权归作者（mattheliu）所有；仅包含原创插件代码与 DSH 官方 logo 素材（按官方仓库许可使用），不包含官方仓库其余源码内容。当前为私有仓库，供 dsh 内测成员在 dsh-external 组织内使用与协作；正式公开前请勿公开分发。

## 🏠 住户（皮肤目录）

| 皮肤 | 基底 | 类型 | 简介 | 状态 |
|---|---|---|---|---|
| [nord](packages/dsh-web-skins/src/client/skins.ts) | dark | `token` | **Nord**：极夜配色映射到 alias token 层，纯 token 零 CSS 换肤的参考实现 🧊 | ✅ 本地构建通过 |
| [aurora](packages/dsh-web-skins/src/client/skins.ts) | dark | `image` | **极光**：深海军蓝底 + 紫青极光光晕，中央浮一只 DSH 鱼 logo 水印 🌌 | ✅ 本地构建通过 |
| [paper](packages/dsh-web-skins/src/client/skins.ts) | light | `image` | **纸张**：暖纸渐变 + 细颗粒噪点，墨褐色 logo 水印，浅色图片皮肤范例 📜 | ✅ 本地构建通过 |
| [dream](packages/dsh-web-skins/src/client/skins.ts) | dark | `image` | **云梦**：深靛蓝底 + 柔焦粉紫云霭 + 一轮暖月，月夜氛围的图片皮肤 🌙 | ✅ 本地构建通过 |

> 想入住？看 [入住指南](#-入住指南) —— 写皮肤定义 → （可选）生图接入 → `pnpm verify` → README 加一行。

## 🖼️ 皮肤预览

![Nord](docs/images/skin-nord.svg) · ![Aurora](docs/images/skin-aurora.svg) · ![Paper](docs/images/skin-paper.svg) · ![Dream](docs/images/skin-dream.svg)

> 每个皮肤 = 背景图 + token 调色 + focal 焦点，设置页以**图库式瓦片**呈现（背景图当缩略图，参考 [Codex-Dream-Skin](https://github.com/Fei-Away/Codex-Dream-Skin)（MIT）的"一图一情绪"与试穿思路）；完整画廊见 [docs/gallery.md](docs/gallery.md)。

## ✨ 原理（为什么零核心改动）

DSH 官方 `ui-theme` 客户端插件自带主题系统：

- `ThemeService.register({ id, colorScheme, tokens })` 是**官方声明支持的第三方主题表面**（`--dsw-*` token 体系：static 调色板 + alias 语义层 + specific 组件层，暗色挂 `body[data-ds-dark-theme]`）；注册的皮肤由 `ThemePresenter` 把 token 打成 body 内联变量，偏好持久化进 `dsh.theme`。
- 本插件把所有皮肤批量注册进 `ThemeService`，并在设置页**通用（General）区块**注册一行"皮肤"选择器（复用官方 `settings.general.item` slot，与内置"外观"行同模式）。
- 图片皮肤额外维护 `body[data-ds-skin="<id>"]` 属性 + 一个插件自有的 `<style>` 标签（随皮肤切换替换文本、卸载时整体回收），背景图以 **data URL 内联进 bundle**，无需外部托管。

## 📦 安装

本仓库是**私有仓库**：先获得 dsh-external 组织读权限。仓库根已经是官方 Profile Bundle，不需要发布 npm 包；本地开发时再准备一份可用的 [DSH 官方仓库快照](https://github.com/dsh2026/test-mattheliu) 提供私有类型与真实冒烟环境。

<!-- INSTALL -->
```sh
omdsh market install dsh-web-skins --profile web --enable
omdsh activate --profile web
omdsh launch --profile web --
```

市场条目把 id 解析为 `@dsh-external/dsh-web-skins` 与不可变 Git spec `git+https://github.com/dsh-external/dsh-skins.git#78349585a85ab94fd3ad22bfcfa9816058da2d93`；OMDSH 在 candidate generation 中复用官方 `dsh plugin` 并默认禁用安装脚本。直接使用官方 CLI 的调试方式、验证和恢复边界见 [docs/install.md](docs/install.md)。
<!-- /INSTALL -->

装好后到 **设置 → 通用设置 → 皮肤** 就能看到四个皮肤选项，点一下即时换肤（偏好写入 `dsh.theme`，跟随系统时按 OS 深浅自动切换基底）。

各皮肤发布 ref（本仓库每个 commit 都是不可变身份，更新皮肤 = 换 ref）：

<!-- REFS -->
| 插件 | 类型 | 发布 ref |
|---|---|---|
| dsh-web-skins | `web-skin` | `78349585a85ab94fd3ad22bfcfa9816058da2d93` |
<!-- /REFS -->

## 🔨 构建链

皮肤包是完整的客户端插件包（`packages/dsh-web-skins/`），本地 adapter 对齐 **Private DSH snapshot 20260807**（commit `8abbd65a`）的官方 `packages/client/tsdown.client.ts`（node 半 + 浏览器 bundle 双产物）：

```sh
pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm verify
pnpm i18n
pnpm i18n:write
pnpm preview
pnpm run publish
```

- `pnpm install` 需要仓库旁有 `fulltest-wt` 快照（`link:` 依赖提供类型）；`pnpm typecheck` 是 `tsc --noEmit`。
- `pnpm build`：tsdown → `lib/index.js`（宿主半）+ `lib/client.js`（浏览器 bundle）+ `lib/preview-skins.js`（试穿数据模块）；`pnpm test`：vitest（皮肤定义 / store / apply 组合 / DOM 行为）。
- `pnpm verify` 一键全验：typecheck + build + test + 产物冒烟（bundle 在假 loader 下跑 apply）+ **i18n 双语一致性门禁**；`pnpm i18n` 单独跑该门禁。
- 双语对（README 与 docs 的中英文文档）一起改完后，用 `pnpm i18n:write`（即 `--write --all`）重录 hash。
- `pnpm preview`：打开本地试穿预览页（`preview/index.html`，需先 `pnpm build` 且仓库旁有 `fulltest-wt` 快照）。
- `lib/` 是交付物，随源码一起提交（harness 的 `/plugins/<id>/client.js` 直接服务它）；改源码后必须 `pnpm build` 再提交。
- 浏览器 bundle 是 closure-factory 形态（`window.__ModuleLoader__.load({ id, factory })`），外部依赖走 loader 冻结模块表（`cordis` / `react` / `ui-slots` / `ui-primitives` / `runtime/client`），CSS Modules 由 lightningcss 编译成自动注入的 `<style data-plugin>` 标签。
- 浏览器 bundle 携带 sourcemap（`lib/client.js.map`，source 路径 rebase 到仓库形态 `/packages/...` 树、含 sourcesContent），并使用 0807 官方 `ctx.slots.inject()` 声明时序与 scoped CSS 标签选择器语义。

## 🏗️ 入住指南

新皮肤四步入住：

1. **写定义**：在 `packages/dsh-web-skins/src/client/skins.ts` 加一个 `SkinDefinition`（`id` / `colorScheme` / `tokens` 必填，`css` / `accent` 可选），`SKINS` 数组登记；`locales.ts` 补 `skins.name.<id>` 中英文案。
2. **（可选）生图接入**：用 AI 生图（GPT Image / DALL·E 等）产出 1200×800 背景，跑 `node scripts/embed-image.mjs <图> <变量名>` 得到 data URL，写进 `skin-styles.ts`（见 [docs/skin-authoring.md](docs/skin-authoring.md)，内含 DSH logo 水印模板）。
3. **构建 + 自证**：`pnpm verify` 全绿（含产物冒烟）；在真实 `dsh web` 里挂载一次：设置页出现新皮肤瓦片、点击即时生效、切回浅/深色无残留。
4. **登记**：README 住户表加一行。

### 皮肤纪律

- **token-only 优先**：能只用 `--dsw-alias-*` 覆盖实现的皮肤就不写 CSS；写 CSS 必须作用域在 `body[data-ds-skin="<id>"]` 之下，随皮肤切换整体替换/回收。
- **生图自包含**：背景图以 data URL 内联进 bundle，不留外部 URL、不依赖托管服务；图片只做背景氛围，可读性靠 token 层保证（半透明基底 + 不透明内容层）。
- **不重复造轮子**：需要更多设置入口 / 皮肤预览缩略图等能力时，先看官方 slot 体系能否覆盖，别硬编码进本仓库。

## 🗺️ 规划中住户（候选，未开工）

| 皮肤 | 基底 | 梗点 | 状态 |
|---|---|---|---|
| 🏮 赛博竹林 `neon-bamboo` | dark | 霓虹绿竹林剪影 + 赛博朋克风 | 候选 |
| 🍵 墨韵 `ink-wash` | light | 水墨山水背景 + 宣纸质感 | 候选 |
| 🌃 港城夜色 `harbor-night` | dark | 城市天际线夜景长图 | 候选 |

## 🌐 双语一致性门禁（i18n gate）

每对双语文档（`README.md` + `README.en.md`、`docs/install.md` + `docs/install.en.md`、`docs/skin-authoring.md` + `docs/skin-authoring.en.md`）由同名 `*.i18n.yaml` sidecar 记录：

- 两侧各自的内容 blob hash（`sha1("blob <len>\0" + LF 归一化内容)`），作为"最后一次确认一致"的锚点；
- **结构签名对比**：标题层级、代码块（逐字）、表格行列数、列表形状、链接目标必须两侧一致 —— 只有正文允许不同语言；语言切换链接、`#` 锚点与 `exemptLinks`（语言化的文档链接）豁免；
- `pnpm verify` 会跑这个门禁，`pnpm i18n` 单独跑；改任一侧文档必须同步更新另一侧，然后：

```sh
pnpm i18n:write
```

`--write` 要求结构签名先通过（不会给分叉的对"盖章"），只重录 hash、不改内容。翻译质量仍是评审责任，门禁只保证结构与"成对更新"。

## 📚 文档

- [安装手册](docs/install.md) —— 市场事务安装 + 官方 Profile CLI + 恢复边界
- [皮肤制作 / AI 生图接入指南](docs/skin-authoring.md) —— SkinDefinition 字段、token 速查、GPT Image 提示词模板、DSH logo 水印模板
- [皮肤画廊](docs/gallery.md) —— 每个皮肤的预览图与创作思路 + 本地试穿预览页