mux9056-bot/dsh-theme

🎨 dsh-theme

DeepSeek Harness 主题插件 · 30 款即插即用主题 · DSH 原生集成

一个面向 DeepSeek Harness Web 界面的主题包：既是零依赖的 DSH 客户端插件（注册进「设置 → 通用」，与内置「外观」选择器并列），也附带 30 个独立 CSS 文件 可任意方式接入。

每个主题都完整映射 DSH 官方设计令牌（--dsw-alias- 语义层、--dsw-specific- 组件层、--shiki- 代码高亮），并同时提供浅色 / 深色两套变体——深色变体会跟随 DSH 内置的 data-ds-dark-theme 自动切换，无需额外设置。

| | |
|---|---|
| 插件类型 | DSH web 客户端插件（platform: web、immediately: true、inject: ["slots"]、零依赖） |
| 主题数量 | 30（每个含 light + dark 双变体，共 60 套配色） |
| 集成方式 | 设置 → 通用 →「主题包」（settings.general.item 槽位，React 组件经平台 seed 渲染） |
| 程序化接入 | window.dshTheme / ctx.provide("dshTheme")（Agent 可直接调用） |
| 持久化 | localStorage（dsh-theme:theme / dsh-theme:mode，旧 dsh-theme-pack: key 自动迁移） |

🤖 你是 AI Agent / 想快速接入？直接看 docs/AGENT.md（Agent 快速接入指南）。

30 款主题目录

| # | id | 中文名 | English | 特点 | 描述 |
|---|----|--------|---------|------|------|
| 1 | ocean | 海洋 | Ocean | 浅色·冷·蓝 | 清凉的蓝，安静而深邃 |
| 2 | midnight | 午夜 | Midnight | 深色·冷·蓝 | 深夜藏蓝，缀以电光蓝 |
| 3 | aurora | 极光 | Aurora | 深色·紫·青 | 紫罗兰与青碧交融的夜空 |
| 4 | lava | 熔岩 | Lava | 深色·暖·橙 | 炭黑岩层，燃烧的橙红余烬 |
| 5 | forest | 森林 | Forest | 浅色·绿 | 松绿与柔软的苔藓 |
| 6 | sakura | 樱花 | Sakura | 浅色·粉 | 淡粉的春日，落樱如雨 |
| 7 | sunset | 日落 | Sunset | 浅色·暖·橙 | 暖桃色渐入黄昏 |
| 8 | graphite | 石墨 | Graphite | 中性·极简 | 柔和的暖灰，护眼耐看 |
| 9 | ink | 墨黑 | Ink | 深色·中性·极简 | 纯粹的黑与白，至简 |
| 10 | paper | 纸张 | Paper | 浅色·暖·米 | 暖奶油色，像一本翻旧了的笔记本 |
| 11 | amber | 琥珀 | Amber | 浅色·暖·金 | 蜂蜜般的金色，温暖透亮 |
| 12 | mint | 薄荷 | Mint | 浅色·绿·青 | 清新的青绿，脆爽清凉 |
| 13 | violet | 紫罗兰 | Violet | 浅色·紫 | 柔和的紫，带着一丝庄重 |
| 14 | cyber | 赛博 | Cyber | 深色·霓虹·蓝 | 近黑底上的霓虹青，赛博电路板 |
| 15 | retro | 复古 | Retro | 浅色·暖·复古 | 旧照片般的米褐与陶土红 |
| 16 | terminal | 终端 | Terminal | 深色·绿·CRT | CRT 黑底上的磷光绿（含 shiki 语法色） |
| 17 | dune | 沙丘 | Dune | 浅色·暖·沙 | 暖阳下的金色沙丘 |
| 18 | glacier | 冰川 | Glacier | 浅色·冷·蓝 | 清澈锐利的冰蓝 |
| 19 | nebula | 星云 | Nebula | 深色·靛·紫 | 靛蓝星云，缀满星光 |
| 20 | coral | 珊瑚 | Coral | 浅色·暖·橙 | 礁石珊瑚，明快而活泼 |
| 21 | steel | 钢铁 | Steel | 深色·冷·蓝灰 | 冷冽的蓝灰，工业般的沉静 |
| 22 | autumn | 秋日 | Autumn | 浅色·暖·金 | 丰收午后，满地金黄 |
| 23 | matcha | 抹茶 | Matcha | 浅色·绿·暖 | 苔绿间透着茶香 |
| 24 | knight | 骑士 | Knight | 深色·金·中性 | 暗色铠甲，缀以古金 |
| 25 | pastel | 粉彩 | Pastel | 浅色·柔和·紫 | 糖果般的柔彩，轻柔俏皮 |
| 26 | lavender | 薰衣草 | Lavender | 浅色·紫·冷 | 晨光里的薰衣草田 |
| 27 | charcoal | 煤灰 | Charcoal | 中性·极简·灰 | 诚实的灰，不打扰你的专注 |
| 28 | rose | 玫瑰 | Rose | 深色·粉·酒红 | 深酒红的天鹅绒，缀着浅绯花瓣 |
| 29 | wave | 碧波 | Wave | 浅色·青·冷 | 青碧的水波，清澈灵动 |
| 30 | mono | 极简 | Mono | 中性·极简·单色 | 严格单色，极致专注 |

打开 preview.html（构建产物，双击即可，无需服务器）可浏览全部 30 款主题的实时预览。

目录结构

dsh-theme/
├── package.json            # DSH 插件清单：dsh.client { inject:["slots"], platform:"web", immediately:true }
├── README.md
├── docs/
│   └── AGENT.md            # ★ Agent 快速接入指南（安装/API/自定义主题/排障）
├── preview.html            # 构建生成：30 主题自包含预览页（file:// 直接打开）
├── src/
│   ├── themes.json         # ★ 30 个主题的唯一数据源（16 个语义插槽 × light/dark）
│   └── client.template.js  # 客户端插件模板（__THEME_DATA__ 由构建内联；设置页 React 行）
├── scripts/
│   ├── build.mjs           # 构建：生成 themes/.css、manifest、client.js、preview.html（含令牌校验）
│   ├── screenshot.mjs      # 开发工具：对运行中的 DSH 界面截图验证主题
│   ├── plugintest.mjs      # 开发工具：模拟 DSH loader 对插件做集成测试
│   └── pixelcheck.mjs      # 开发工具：PNG 像素校验（截图非空 + 主色命中）
├── themes/                 # 构建生成：每主题一个独立 CSS（可直接用）
│   ├── ocean.css
│   ├── ...
│   ├── index.css           # 全部 30 个主题合一的样式
│   └── manifest.json       # 机器可读目录（含色板 swatch）
├── lib/
│   ├── index.js            # ★ 服务端入口（no-op cordis 插件，loader 挂载必需）
│   ├── client.js           # ★ 构建生成：自包含 DSH 客户端插件（内联全部主题）
│   └── themes.data.json    # 运行时数据
└── shots/                  # 开发工具产出的效果截图

快速安装（三选一）

方式 0：一键安装脚本（推荐给普通用户 / Agent）

克隆仓库后直接运行（自动完成构建 + dsh plugin add + loader 条目写入，幂等、带备份）：

git clone https://github.com/mux9056-bot/dsh-theme ~/dsh-theme
cd ~/dsh-theme
node scripts/install.mjs          # 可选：--profile  装到其他 profile；--no-build 跳过构建

脚本跑完只需重启 dsh web 并刷新页面。详细说明见 docs/AGENT.md。

通过 Agent 安装（3 分钟）

如果你用 DeepSeek Harness 或其他 AI Agent，把下面这段指令直接复制发给你的 Agent，
它会照着 docs/AGENT.md 自动完成安装、重启与验证：

📋 给 Agent 的安装指令（可直接复制）

请帮我把 dsh-theme 主题插件安装到 DSH web 界面（仓库：https://github.com/mux9056-bot/dsh-theme ）：
1. clone 仓库到持久路径（如 ~/dsh-theme，不要用 /tmp）；若无 lib/client.js 先执行 npm run build
2. 安装进 web profile：COREPACK_ENABLE_PROJECT_SPEC=0 dsh plugin --profile web add ~/dsh-theme
（若报 corepack 权限错就用这个前缀重试）
3. 必须在 $DSH_HOME/profiles/web/cordis.patch.yml 追加 loader 条目：
- insert: [{ id: theme, name: 'dsh-theme' }] —— 客户端插件没有自动发现，漏掉就不生效
4. 重启 dsh web（注意：agent 通常运行在 dsh web 进程内，需用 detach 方式重启并留出收尾时间；或让用户手动重启）
5. 验证：curl -s http://127.0.0.1:3080/ | grep '"id":"dsh-theme"' 命中；
并打开「设置 → 通用」确认出现「主题包 · 30 款」色卡行
6. 完成后告诉我，我刷新页面即可使用

Agent 会自行处理所有已知坑（corepack 权限、loader 条目、重启时机、manifest 验证）；
遇到异常可直接让它查阅 docs/AGENT.md 的排障清单。手动安装见下节。

快速接入（DSH 原生方案）

⚠️ 重要：DSH 的客户端插件（dsh.client 清单）没有自动发现机制。光把包装进 profile 的
node_modules 还不够 —— 必须同时满足三个条件插件才会出现在 boot manifest 里：
① 依赖装入 profile；② 在 profile 补丁层注册 loader 条目；③ 重启 dsh web。
并且包的 exports 必须提供 . 主入口（lib/index.js），因为 loader 会 import() 整个包。

方式 A：作为 DSH 客户端插件（推荐）

lib/client.js 遵循 DSH 官方客户端插件打包契约（与 @deepseek-ai/dsh-client-ui-theme 同款）：

// package.json —— 本项目的 dsh.client 清单
"dsh": { "client": { "inject": ["slots"], "platform": "web", "immediately": true } },
"exports": {
".":        { "default": "./lib/index.js" },   // 服务端入口（loader import 必需）
"./client": { "default": "./lib/client.js" }   // 浏览器 bundle
}

第 1 步：构建并安装依赖（本地目录即可，无需发布 npm）：

npm run build                                  # 生成 lib/client.js 等构建产物
dsh plugin --profile web add /absolute/path/to/dsh-theme

若遇到 corepack 报 EPERM ... package.json（它会试图往项目外层写 packageManager 字段），
加环境变量重试：COREPACK_ENABLE_PROJECT_SPEC=0 dsh plugin --profile web add 。

第 2 步：在 profile 补丁层注册 loader 条目（$DSH_HOME/profiles/web/cordis.patch.yml）：

- insert:
- id: theme
name: 'dsh-theme'

第 3 步：重启 web profile 并刷新页面

dsh web        # 重启（或在你原来的终端里 Ctrl+C 后重跑）

刷新后：左下角侧边栏 → ⚙ 设置 → 通用 → 找到「主题包 · 30 款」分区即可换肤。
（也可在浏览器控制台用 window.dshTheme API，见下文。）

方式 B：纯 CSS（零依赖，任何部署都适用）

每款主题是一个自包含的 CSS 文件，选择器基于 body 上的属性：

/ themes/ocean.css 的生效选择器 /
body[data-dsh-theme="ocean"] { / 浅色令牌 / }
body[data-dsh-theme="ocean"][data-ds-dark-theme] { / 深色令牌 / }

使用只需两步：

// 1. 引入主题 CSS（任一方式：、注入 、构建时合并）
// 2. 给 body 打上属性
document.body.setAttribute("data-dsh-theme", "ocean");

- 想一次性引入全部：用 themes/index.css，然后只需切换 data-dsh-theme 属性值（ocean / midnight / …）。
- 深色变体由 DSH 自己的 body[data-ds-dark-theme] 控制（设置 → 外观 → 深色/浅色/跟随系统），无需额外处理。
- 也可以直接粘贴到浏览器 DevTools 的 Console 里即时预览：
fetch('/themes/aurora.css').then(r=>r.text()).then(css=>{
const s=document.createElement('style'); s.textContent=css;
document.head.appendChild(s); document.body.setAttribute('data-dsh-theme','aurora');
})

方式 C：完整源码集成

若你在 deepseek-harness 完整源码中开发，可将 src/client.template.js 作为客户端插件包
（仿照 packages/client/ui-theme 布局），npm run build 后产出 lib/client.js 即符合
packages/client/ 的构建产物格式（__ModuleLoader__.load + exports.inject/apply）。

插件功能

| 功能 | 说明 |
|---|---|
| 🎨 设置页集成 | 「设置 → 通用」新增「主题包」分区（settings.general.item 槽位，order: 20，在内置「外观」行之下） |
| 色卡网格 | 30 张主题色卡（渐变迷你预览 + 强调色圆点 + 色块 chips + 名称），选中态高亮边框 + 加粗名称 |
| 浅/深/自动 | 行内三态切换；「自动」跟随 DSH 内置外观设置 |
| 恢复默认 | 行尾「恢复默认」按钮，移除 data-dsh-theme 并清空主题 CSS |
| 持久化 | 选择写入 localStorage（dsh-theme:theme / dsh-theme:mode），刷新/重启后自动恢复 |
| 程序化 API | window.dshTheme（Agent / 控制台可直接调用，见下） |
| 服务注入 | ctx.provide("dshTheme", api)，其他插件可 inject: ["dshTheme"] 使用 |

window.dshTheme.list()                       // [{id,name,nameZh,desc,descZh,tags}, ...] 共 30 项
window.dshTheme.get()                        // {id,name,nameZh} 或 null
window.dshTheme.set("aurora")                // 切换主题（无效 id 抛错）
window.dshTheme.cycle()                      // 轮换到下一个主题
window.dshTheme.reset()                      // 恢复 DSH 默认外观
window.dshTheme.setMode("light"|"dark"|"system")
window.dshTheme.getMode()

主题机制：语义插槽 → DSH 设计令牌

每个主题在 src/themes.json 中只定义 16 个语义插槽 × 2 种模式，构建时自动展开为 94 个
DSH 真实令牌（全部经过与 DSH 实际 CSS 的差集校验，无拼写错误）：

| 插槽 | 作用 | 主要映射到的令牌（节选） |
|---|---|---|
| bg | 应用底色 | --dsw-alias-bg-base |
| surface | 抬升表面（卡片/输入） | --dsw-alias-bg-layer-1/2、--dsw-specific-menu |
| surfaceAlt | 次级表面（悬停/标签） | --dsw-alias-bg-layer-3、--dsw-specific-selector |
| text / text2 / text3 | 主/次/三级文字 | --dsw-alias-label-primary/secondary/tertiary/caption |
| border | 边框 | --dsw-alias-border-l1~l4（自动派生透明度梯度） |
| accent / accentHover / accentText | 品牌色 | --dsw-alias-brand-primary、--dsw-alias-button-primary-fill/-hover、--dsw-alias-state-business-primary |
| code / codeBanner | 代码块 | --dsw-alias-markdown-code-block/-banner |
| sidebar | 侧边栏 | --dsw-specific-sidebar-fill |
| warn / error / success | 状态色 | --dsw-alias-state-warn-/error-/success- |
| （派生） | 交互态、滚动条、toast、渐变 | --dsw-alias-interactive-bg-、--dsw-alias-scrollbar-、--dsw-linear-gradient-think 等 |

代码高亮：默认使用 DSH 内置 shiki 配色（浅/深各一套，自动适配）；个别主题可覆写
（如 terminal 的磷光绿语法色），在 src/themes.json 中加 shiki.light/dark 字段即可。

自定义 / 新增主题

1. 在 src/themes.json 的 themes 数组里追加一个对象（id 唯一、小写字母/数字/连字符）：
{
"id": "mytheme",
"name": "My Theme", "nameZh": "我的主题",
"desc": "…", "descZh": "…",
"tags": ["light", "blue"],
"light": { "bg": "#f5f8fc", "surface": "#ffffff", "surfaceAlt": "#e9f0f8", "text": "#12283f",
"text2": "#4a637c", "text3": "#7c93a8", "border": "rgba(18,40,63,0.10)",
"accent": "#1d6fb8", "accentText": "#ffffff", "accentHover": "#175a94",
"code": "#eaf2fa", "codeBanner": "#e1ecf6", "sidebar": "#eaf2f9",
"warn": "#b45309", "error": "#dc2626", "success": "#15803d" },
"dark": { / 同结构，深色插槽 / }
}

2. npm run build —— 自动产出该主题的 themes/.css、更新 manifest、重打 lib/client.js，
并执行令牌名校验（每个变量名都必须存在于 DSH 真实令牌集，防止拼错）。

开发与验证

npm run build              # 全量构建 + 令牌校验
npm run verify             # 仅校验（令牌名 ∈ 内置 DSH 令牌集、花括号配平）
npm run verify:live        # ★ 校验时对比「运行中的 DSH」真实 CSS（DSH 升级后用它复检令牌漂移）
node scripts/plugintest.mjs    # 对运行中的 DSH (http://127.0.0.1:3080) 做插件集成测试
node scripts/screenshot.mjs ocean light shots/ocean-light.png   # 截图验证某主题
node scripts/pixelcheck.mjs shots/ocean-light.png eef5fb        # 像素级校验主色

verify:live 会抓取运行中 DSH 的样式资源并提取全部 --dsw- / --shiki-* 令牌，把 30 个主题
以及设置行的 UI 令牌一并与真实令牌集比对 —— 这是 DSH 升级后最可靠的适配自检。
（DSH_LIVE_URL 环境变量可指定别的实例地址。）

集成测试会模拟 DSH loader 的真实加载路径：__ModuleLoader__.load 注册 → __DSH_MODULES__.materialize(id)
→ apply(ctx)，并断言：30 个色块、主题切换后 computed style 命中插槽色、深浅色切换、轮换/重置、
刷新后持久化恢复。

开源 / 发布

- npm 发布：包名 dsh-theme 在 npm 上未被占用，可 npm publish；用户随后只需
dsh plugin --profile web add dsh-theme + loader 条目 + 重启（见上）。
- ⚠️ 旧包 dsh-theme-pack@1.0.0（已存在于 npm）是早期版本：缺少服务端入口（exports["."] /
lib/index.js），装进 DSH 会报 ERR_PACKAGE_PATH_NOT_EXPORTED，不要用它；请用本仓库的新包名。
- 发布前检查清单：npm run verify:live 通过 → npm run build → npm pack 确认产物包含
lib/、themes/、scripts/、docs/。

已知限制与说明

- 设置页集成：主题入口在「设置 → 通用 → 主题包」，与内置「外观」选择器并列；没有页面级浮动控件
（DSH 理念：插件应注册进宿主 UI 槽位，而不是独立悬浮组件）。
- 模式切换：行内「浅色/深色」会直接设置 body[data-ds-dark-theme]（persist 到 localStorage），
此时 DSH 内置「外观」设置页的显示可能与实际不一致；点「自动」即可恢复跟随内置设置。
- loader 条目是硬性要求：DSH 的 client-modules 只扫描 loader entries（补丁层里的行），
不会自动发现 node_modules 里的 dsh.client 包；漏掉 cordis.patch.yml 的 insert 会导致插件不进
启动清单。参见 docs/AGENT.md 的排障章节。
- 服务端入口必需：loader 会 import() 插件包，因此 exports["."] 与 lib/index.js 缺一不可；
漏掉会报 ERR_PACKAGE_PATH_NOT_EXPORTED 或 ERR_MODULE_NOT_FOUND。
- 样式隔离：设置行样式与当前主题 CSS 分属两个  元素，任何主题切换/清空都不会破坏行样式；
深色模式下色卡预览条跟随 body[data-ds-dark-theme] 切换为对应深色 swatch。
- 主题标识：主题通过 body[data-dsh-theme=""] 生效，与 DSH 内置外观（浅/深）正交，二者可自由组合。
- 兼容性：令牌名取自 DSH 0.1.0-rc.6 的 Web 产物；DSH 升级后请用 npm run verify:live 复检。
- 依赖平台 seed：设置行用 react + slots 服务（DSH 平台 seed，inject: ["slots"]），
需要 DSH 版本提供这两个 seed（0.1.0-rc.6 起包含）；缺失时插件优雅降级（仅保留 window.dshTheme API）。

License

Apache License 2.0