dsh-duobaxian

Readme

# dsh-duobaxian · 多巴仙

**DeepSeek Harness Web UI 主题插件：八仙 × 多巴胺亮色。**

为 dsh 社区用户解决"现有主题偏二次元/暗色、缺活泼有品牌感"的问题——通过名字 + 八仙形象 + 多巴胺亮色全套品牌化（口号「仙气多巴胺，界面好心情」），8 位仙家 8 套皮肤，点击即换。

```
dsh web (3080)
   │  webServer.tapIndex() 注入 <style data-plugin="duobaxian"> + 切换器
   ▼
多巴仙主题 (theme.css)
   └── 覆盖 --dsw-alias-* 设计令牌 + --dsw-static-* 静态令牌 + 8 仙变体
```

## 特性

- **纯 CSS 换肤**：只覆盖 dsh 官方设计令牌，不动布局与功能代码
- **8 仙变体**：吕洞宾·青绿 / 钟离权·明黄 / 何仙姑·樱粉 / 铁拐李·橙红 / 韩湘子·紫罗兰 / 曹国舅·鎏金 / 蓝采和·天蓝 / 张果老·草绿
- **界面切换器**：右下角 🎨 按钮，点击即换仙家，localStorage 记忆选择
- **明暗双模式**：跟随 dsh 主题自适应
- **对比度保障**：按钮/文字 WCAG AA ≥ 4.5:1 自动校验
- **幂等注入**：重复注入不叠加；`enabled: false` 可关闭而不卸载

## 前置条件

一个可运行的 DeepSeek Harness `web` profile（提供 `webServer` 服务）。

## 安装

### 方式 A：tarball

```bash
npm pack                                  # 生成 dsh-duobaxian-0.1.0.tgz
dsh plugin --profile <profile> add ./dsh-duobaxian-0.1.0.tgz
```

### 方式 B：本地目录

```bash
dsh plugin --profile <profile> add <本目录绝对路径>
```

验证配置层生效：

```bash
dsh --profile <profile> --dump-config
```

然后**重启 dsh web**，打开 `http://127.0.0.1:3080` 即可看到多巴仙主题与右下角切换器。

## 配置项

在 profile 的 `cordis.patch.yml` 覆盖：

```yaml
- id: duobaxian-theme
  name: dsh-duobaxian
  config:
    enabled: true        # false 关闭主题而不卸载
    variant: lv          # 默认仙家：lv/zlq/hxg/tgl/hxz/cgj/lch/zgl
    showSwitcher: true   # false 隐藏右下角切换器
```

> 注意：patch 覆盖是整行替换 config，覆盖时需重述所有键。

## 架构

```
dsh-duobaxian/
├── package.json        # dsh.bundle 声明
├── cordis.patch.yml    # 插入插件行
├── index.js            # 插件入口：webServer.tapIndex 注入主题 + 切换器
├── theme.css           # 多巴仙主题：令牌覆盖 + 8 仙变体 + 明暗双模式
├── test/
│   ├── load.mjs        # 插件契约测试（导出结构/注入幂等/变体完备性/无敏感信息）
│   └── contrast.mjs    # 8 仙 × 明暗对比度校验（WCAG AA ≥ 4.5:1）
├── docs/               # 设计规划 + 使用手册（白话版）
└── README.md / LICENSE
```

## 工作原理

1. 插件 `inject: ['webServer']`，依赖 dsh 内置 web 服务器服务。
2. `apply` 读取 `theme.css`，通过 `ctx.webServer.tapIndex()` 在 `</head>` 前注入 `<style data-plugin="duobaxian">`。
3. 样式在 `body`（亮色）与 `body[data-ds-dark-theme]`（暗色）作用域内覆盖 `--dsw-alias-*` / `--dsw-static-*` 令牌。
4. 切换器脚本注入 `</body>` 前：点击仙家 → 设置 `body[data-baxian="xxx"]` → 对应变体变量即时生效。
5. 插件卸载时 disposer 自动移除注入，样式随之消失（幂等、可清理）。

## 开发与测试

```bash
npm install
npm test                # 契约测试 8 项 + 对比度校验 3 项
npm pack                # 打包
```

## License

MIT