DSH Theme Switcher（主题切换插件）

August 14, 2026 · View on GitHub

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<string,string> }；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），可永久安装