yingpanwang/dsh_web_client_theme_switcher

DSH Theme Switcher（主题切换插件）

DeepSeek Harness (DSH) 的主题切换插件：注册自定义主题、一键切换、自定义主题编辑器、按钮位置自定义、图片背景壁纸。

提供两种形态，同一份功能：

| 形态 | 文件 | 特点 |
| --- | --- | --- |
| 静态 bundle（推荐） | lib/ + cordis.patch.yml | 装一次永久生效；重启不丢；出现在「设置 → 插件」清单；供他人分发 |
| 动态插件 | src/client.js | 会话内即时注入；零安装；重启后需重新注入 |

✨ 功能

- 主题切换：跟随系统 / 浅色 / 深色 / 暗夜 dsh-midnight / 森绿 dsh-forest / 日光 dsh-solarized
- 自定义主题：面板内「＋ 新建自定义主题」：命名、选色板（浅/深）、选起点、9 个核心颜色取色器；保存即注册并应用；可删除
- 按钮位置：侧边栏底部 / 会话标题栏 / 输入行 / 悬浮可拖动（面板内可复位）
- 图片背景：上传本地图片或粘贴 URL；暗化滑块（0–80%）；内置测试渐变；预览与加载失败提示
- 纯 Client 端实现：theme.register / overrideTokens / slots 槽位注入 / 自持样式标签

📦 安装方式一：静态 bundle（永久安装，推荐）

把插件装进 DSH 的 web profile（浏览器端组合由 bundle 组成）。任何 DSH 部署都适用。

1. 获取包（三选一）

a) 已发布到 npm
npm i dsh_web_client_theme_switcher

b) 从 GitHub 安装（先推送仓库）
npm i github:/dsh_web_client_theme_switcher

c) 本地目录（开发时）
npm i file:/path/to/dsh_web_client_theme_switcher

2. 加入 web profile 的 bundle 列表

编辑 $DSH_HOME/profiles/web/package.json（Windows 示例：C:\Users\\.dsh\profiles\web\package.json）：

{
"dependencies": {
"dsh_web_client_theme_switcher": "^1.0.0"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh_web_client_theme_switcher"
]
}
}
}

3. 安装依赖并重启 web

cd $DSH_HOME/profiles/web
pnpm install        # 或 npm install
dsh --profile web   # 重启后插件常驻生效

重启后：
- 插件自动加载，无需任何会话操作
- 出现在 设置 → 插件 → 全部 的插件清单中（id: ui-theme-switcher）
- 侧边栏底部出现「主题」按钮

说明：bundle 是 DSH 官方扩展机制（web 组合 = dsh-base + dsh-web-app 等 bundle 的补丁叠加 + 用户 cordis.patch.yml）。本包通过 package.json 的 dsh.bundle.patch 声明组合补丁、dsh.client 声明浏览器半区，lib/client.js 为 __ModuleLoader__ 模块格式。

⚡ 安装方式二：动态插件（会话内快速注入）

适合临时试用：让任意 DSH 会话的 Agent 读取 src/client.js，调用 cordis_define（code.client = 文件内容，plugin.kind: "new"，idPrefix: "theme"），再 cordis_run 并授权。重启后需重新注入。

🧩 架构

┌─────────────────────────────────────────────────────────┐
│ 浏览器半区 apply(ctx)                                    │
│  ├─ theme.register(...)        注册 3 套自定义主题        │
│  ├─ theme.overrideTokens(...)  壁纸模式：bg-base 透明化   │
│  ├─ insertStyle(...)           body 壁纸层 + 暗化遮罩     │
│  └─ slots.register(...)        UI 入口（5 个槽位）        │
│      ├─ sidebar.footer.action        侧边栏底部按钮        │
│      ├─ conversation.session.header.utilities 标题栏按钮   │
│      ├─ conversation.input.left      输入行按钮           │
│      ├─ shell.overlay                悬浮按钮 + 主题面板   │
│      └─ tool.view.cordis             运行卡片取色器       │
└─────────────────────────────────────────────────────────┘

关键技术点

- 主题系统：theme 服务提供 getTheme() / setTheme(id) / register(def) / overrideTokens(source, tokens)。注册的主题需提供 { id, colorScheme: 'light'|'dark', tokens: Record }；override 层需要 { light, dark } 双值。
- 壁纸实现：主题 token 只接受颜色，图片走 CSS 路径——注入 body{background-image:url(...) !important}（带黑色渐变暗化遮罩）。应用外壳 .frame 会用不透明 --dsw-alias-bg-base 铺满视口盖住 body，因此壁纸开启时通过 overrideTokens 把 --dsw-alias-bg-base 覆盖为透明、--dsw-specific-sidebar-fill 覆盖为半透明，让壁纸透出全部区域；关闭/卸载时自动还原。
- 共享状态：多槽位组件通过闭包小 store（Set 订阅 + 递增计数强制刷新）同步面板开关、位置、自定义主题与壁纸状态。setState 传相同值会 bail out，订阅回调必须包 force(n => n + 1)。
- 生命周期：theme.register / overrideTokens / 样式标签 disposer 全部交由 ctx.effect 或闭包管理，插件停止/更新时自动清理。

📁 文件结构

├── README.md            # 本文档
├── package.json         # bundle 包声明（dsh.bundle.patch / dsh.client / exports）
├── cordis.patch.yml     # web 组合补丁：插入 ui-theme-switcher 行
├── lib/
│   ├── index.js         # Host（node）半区：空插件，供组合行挂载
│   └── client.js        # 浏览器半区：__ModuleLoader__ 模块（静态版）
└── src/
└── client.js        # 动态插件版源码（cordis_define 用）

📜 版本历史

| 版本 | 内容 |
| --- | --- |
| pkg-1 | 初始：3 套自定义主题 + 运行卡片取色器 |
| pkg-2 | 侧边栏底部常驻按钮 + 浮层面板 |
| pkg-3 | 按钮位置选择（侧边栏/标题栏/输入行/悬浮拖动） |
| pkg-4 | 修复悬浮拖动不实时更新（setState bail out） |
| pkg-5 | 自定义主题编辑器（新建/删除） |
| pkg-6 | 图片背景（上传/URL + 暗化滑块） |
| pkg-7 | 壁纸诊断：自动应用、内置测试渐变、状态行 |
| pkg-8 | 修复壁纸被应用外壳遮挡（overrideTokens 透明化） |
| 1.0.0 | 静态 bundle 化（lib/ + cordis.patch.yml），可永久安装 |