RealHacker/dsh-theme-colorizer

dsh-theme-colorizer

Color theme

一个 DeepSeek Harness（DSH）插件，为 DeepSeek Web UI 添加可自定义的颜色主题。用户在设置页面选择一个颜色主题，所选主题的 --dsw-alias- CSS 令牌覆盖将应用在当前激活的浅色/深色基础调色板之上。

功能特性

- 5 种颜色主题：海洋蓝、森林绿、日落橙、皇家紫、单色
- 设置页面集成：在设置面板的“通用”部分会出现一行“颜色主题”
- 偏好持久化：用户的选择保存在浏览器 localStorage 中，页面刷新后依然保留
- 与内置的外观行组合：颜色主题独立于浅色/深色/系统偏好——两者通过主题服务的覆盖堆叠机制组合在一起

工作原理

DSH 插件加载模型

DSH 插件是一个 Cordis 插件模块。它导出一个 apply(ctx) 函数，Cordis 加载器会用一个上下文（ctx）来调用它。插件所做的每一次注册——主题覆盖、插槽注册——都是该上下文上的一个 effect，因此卸载插件时会自动拆除其贡献。

该插件有两半，因为它同时为 DSH Web 应用的 Host（Node.js 服务器）端和 Client（浏览器）端做出贡献：

Host 端（src/index.ts）

Host 这一半是一个可加载但无实际行为的入口：组合中的行必须解析到一个包主入口，而浏览器插件图是从包的 ./client 导出提供的。这里没有 Host 端工作，因为持久化是在客户端进行的：Host API 网关只在一个精选的允许列表（apiproxy 中的 WEB_SETTINGS_NAMESPACES）上暴露设置命名空间，而插件自有的暴露属于待办的 harness 工作——对未列出的命名空间进行写入会被以 settings-not-exposed 拒绝。将偏好保存在 localStorage 中使插件完全自包含（无需修改 harness 源码，无需重新构建 Host）。

加载时机：在服务器启动时，当 Loader 读取组合并挂载此插件入口时。Host 这一半的 apply 会运行并立即返回。

Client 端（src/client/index.ts）

Client 这一半在浏览器中运行。它会：

1. 读取已存储的颜色主题——同步地从 localStorage 中键为 dsh-theme-colorizer:theme 的位置读取（回退到默认值），因此刷新后不存在首帧竞态。

2. 应用令牌覆盖——调用 ctx.theme.overrideTokens('dsh-theme-colorizer', tokens)，将所选主题的 --dsw-alias- CSS 自定义属性叠加在当前激活的基础调色板之上。主题服务按堆叠顺序组合覆盖层；靠后的层按令牌逐个胜出。插件的层由源字符串 'dsh-theme-colorizer' 标识，因此用相同的源再次调用会原子性地替换该层。
3. 持久化选择 — 每次更改时都会将所选 id 写回 localStorage；一个 storage 事件监听器会让其他打开的标签页保持同步。

4. 注册一个设置行 — 注入到 settings.general.item 插槽中，并注册一个 ThemeColorRow React 组件，用于渲染五个颜色主题色板。该组件通过其注入面接收当前选择和一个 setColorTheme 回调。

加载时机：当浏览器的模块加载器构建 window.__DSH_BOOT__ 插件图时。package.json 中的 dsh.client 清单声明这是一个 immediately: false 的 Web 插件，因此它会在正常的插件图初始化期间加载（而不是在第一阶段预取层中）。

设置行渲染

ThemeColorRow 组件渲染在设置面板的“常规”部分内。它使用 DSH 插槽系统：
- ui-settings 包声明了 settings.general.item 插槽类型
- ui-settings-general 包渲染“常规”部分及其条目插槽
- 此插件以 id: 'theme-colorizer' 和 order: 20 注册到该插槽中（将其放置在 order 为 10 的内置“外观”行之后）

主题令牌覆盖流程

用户在设置中选择“Forest Green”
→ ThemeColorRow 调用 setColorTheme('forest-green')
→ 客户端插件将其持久化到 localStorage（dsh-theme-colorizer:theme）
→ 客户端插件调用 ctx.theme.overrideTokens('dsh-theme-colorizer', forestTokens)
→ ThemeRuntime 发布 theme/change 事件
→ ui-layout 的 ThemePresenter 读取新的快照
→  上的 CSS 变量更新
→ 所有组件以新颜色重新渲染
→ 在下次页面加载时，apply() 读取 localStorage 并重新应用主题

安装

快速安装

执行此命令：
dsh plugin --profile web add dist\dsh-theme-colorizer-1.0.1.tgz

先决条件

- 一个可正常工作的 DeepSeek Harness 安装（deepseek-harness 仓库检出）
- DSH Web 应用已构建并正在运行（pnpm run dev:web 或 dsh web）

方法 A（推荐）：使用 dsh plugin add 作为 bundle 安装

该插件被打包为一个可安装的 bundle。两个清单条目使其能够工作：

- package.json 声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } — bundle 层
- 包根目录下的 cordis.patch.yml 将插件行插入到组合中

dsh plugin 通过一条命令将 bundle 安装到 profile 中，就像 web profile 中的内置 dshmarket/dsh-better-sidebar 插件一样。

1. 构建插件（构建配置位于 harness 检出中）：

cd E:\Deepseek\deepseek-harness
pnpm run build:lib:client

这会生成 packages\client\dsh-theme-colorizer\lib\（node 部分 index.js/invariant.js + 浏览器部分 client.js）。

2. 将构建输出同步到工作区副本（可安装产物）：

Copy-Item -Recurse -Force packages\client\dsh-theme-colorizer\lib E:\Deepseek\Workspace\plugins\dsh-theme-colorizer\

3. 打包成 tarball 并安装到 web profile 中：
powershell
cd E:\Deepseek\Workspace\plugins\dsh-theme-colorizer
pnpm pack --pack-destination E:\Deepseek\Workspace\plugins\dist
dsh plugin --profile web add E:\Deepseek\Workspace\plugins\dist\dsh-theme-colorizer-1.0.0.tgz

这会按需初始化 profile、安装该包，并将 dsh-theme-colorizer 追加到 profile 的 dsh.profile.bundles 中。无需启动即可验证：
powershell
dsh --profile web --dump-config   # 显示一个 "# == dsh-theme-colorizer" 层，其中包含 theme-colorizer 行

4. 重启 dsh web。

为什么用 tarball，而不是普通的 add  或 file: 规格？

- 普通的目录 add 使用 pnpm 的 link: —— 一个指向你源码目录的 junction。Node 会解析模块的 realpath，因此插件的 @deepseek-ai/ 导入会从 E:\Deepseek\Workspace\... 开始向上查找，永远到不了内置的 fallback $DSH_HOME/profiles/node_modules（这个修复后的模块 fallback 在运行时提供所有 @deepseek-ai/ 包）。
- file: 规格在 pnpm 中会搞乱 Windows 盘符路径（ENOENT: scandir '\E:\...'）。
- tarball 会把包解压到 profile 自己的 .pnpm store 内，因此其 realpath 保持在 $DSH_HOME/profiles/ 之下，所有运行时导入都会通过 fallback 解析。这就是为什么可安装的 manifest 声明没有运行时依赖：所有 @deepseek-ai/ 导入都是由 fallback 提供的内置包，而 clsx 被内联进了浏览器 bundle。（workspace:^ 范围也会破坏 harness workspace 之外的 pnpm 安装 —— ERR_PNPM_WORKSPACE_PKG_NOT_FOUND。）

以后要更新插件：重新构建、重新同步 lib/、重新打包，然后再次执行 dsh plugin --profile web add （或者先提升版本号）。要移除它：dsh plugin --profile web remove dsh-theme-colorizer。

方法 B：构建集成（手动，用于在 checkout 内进行开发）

仅当直接针对 harness 源码树进行开发时使用此方法。不要与方法 A 组合使用 —— 两者都会把相同的 theme-colorizer 行 id 插入到组合中。

步骤 1：将插件放入 packages 目录

将插件复制到 deepseek-harness 仓库的 packages/client/ 中：
powershell
Copy-Item -Recurse E:\Deepseek\Workspace\plugins\dsh-theme-colorizer packages\client\dsh-theme-colorizer

或者使用 junction 进行实时编辑：
powershell
New-Item -ItemType Junction -Path packages\client\dsh-theme-colorizer -Target E:\Deepseek\Workspace\plugins\dsh-theme-colorizer

步骤 2：将插件注册为 TypeScript 项目

DSH 构建分为两个阶段：tsc -b 编译每个包并输出 lib/types/.js，然后 tsdown 基于这些文件打包每个包。tsc -b 只编译被列为项目引用的包，因此将该包添加到 tsconfig.client.json：
jsonc
{ "path": "./packages/client/dsh-theme-colorizer" },

第 3 步：将插件添加到 web-app 组合中

在 packages/bundle/web-app/cordis.patch.yml 中，将条目添加到 dsh.client 行区域下：

- id: theme-colorizer
name: 'dsh-theme-colorizer'

第 4 步：将该包添加为依赖项

在 packages/bundle/web-app/package.json 中，将 "dsh-theme-colorizer": "workspace:^" 添加到 dependencies 和 devDependencies 中。

第 5 步：安装并构建

cd deepseek-harness
pnpm install
pnpm run build:lib:client

不要使用 pnpm run build --filter dsh-theme-colorizer —— 该包没有独立的 build 脚本，仅靠 tsdown 无法构建它（其入口点是 lib/types/.js 文件，而这些文件只有 tsc -b 阶段才会生成）。pnpm run build:lib:client 会先运行 tsc -b tsconfig.client.json，然后运行 tsdown --env.DSH_BUILD_FACE client；工作区的 tsdown 阶段会通过 packages// glob 自动发现该包。

重启 Web 服务器（两种方法）

如果 Web 服务器已在运行，请重启它，以便 Loader 重新读取组合，并且模块扫描会重新提供插件包：

使用 dsh CLI：
dsh web

或在开发期间：
pnpm run dev:web

验证

1. 在 http://127.0.0.1:3080 打开 Web UI
2. 点击侧边栏中的设置图标（齿轮）
3. 在 General 部分，你应该会看到 "Color Theme" 行，其中有五个彩色色块
4. 点击一个色块 —— UI 颜色应立即更新
5. 该选择在页面重新加载后仍然保留（它存储在 DSH 用户设置文档中）

故障排除

[UNRESOLVED_ENTRY] Cannot resolve entry module lib/types/index.js

这意味着 tsdown 在 TypeScript 生成 lib/types/index.js 之前就运行了 —— 也就是说 tsc -b 没有编译此包。DSH 构建会先编译（tsc -b 生成 lib/types/.js），然后再打包（tsdown 读取这些文件）。两个常见原因：

1. 该包不是项目引用。 将 { "path": "./packages/client/dsh-theme-colorizer" } 添加到 tsconfig.client.json 的 references 数组中（方法 B，第 2 步），然后运行 pnpm run build:lib:client。
2. tsdown 被直接运行了。 运行完整流水线 —— pnpm run build:lib:client —— 而不是单独运行 tsdown / pnpm run bundle。成功构建后，packages/client/dsh-theme-colorizer/lib/types/ 应包含 index.js、invariant.js 和 client/index.js。

cannot get property "theme" without inject

客户端部分访问了 ctx.theme，但插件的 Cordis inject 数组遗漏了 'theme'。Cordis 拒绝分发未注入的已提供服务。该插件声明了 inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope', 'theme'] —— 请将 'theme' 保留在该列表中。

安装时出现 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND
可安装清单不得携带 workspace:^ 范围——这些范围仅在 harness 工作区内解析。该 bundle 的 package.json 有意不声明任何运行时依赖：每个 @deepseek-ai/* 导入都是内置包，在运行时由 $DSH_HOME/profiles/node_modules 回退提供，而 clsx 被内联到浏览器 bundle 中。

使用 file: 规范时出现 ENOENT: scandir '\E:\...'

Windows 上的 pnpm 会破坏 file: 规范中的盘符路径。请改为从打包的 tarball 安装（方法 A，第 3 步）。

选择主题后没有任何变化

- 检查浏览器控制台是否有上述“cannot get property”错误（过期的 bundle：重新构建并重新同步 lib/）。
- 确认设置行出现：组合必须包含 theme-colorizer 行（dsh --profile web --dump-config）。如果你使用方法 A 安装，请不要同时在 packages/bundle/web-app/cordis.patch.yml 中保留 theme-colorizer 行——重复的行 id 会导致加载失败。

文件结构

dsh-theme-colorizer/
package.json              # Bundle + client manifest (dsh.bundle / dsh.client), no runtime deps
cordis.patch.yml          # Bundle patch: inserts the theme-colorizer row
tsconfig.json             # TypeScript config (extends tsconfig.base.client.json, used for the harness build)
tsdown.config.ts          # Build config using the shared clientBundle preset (harness build only)
lib/                      # Built output (copied from the harness build before packing)
index.js                # Host-side entry (bundled)
invariant.js            # Companion entry (bundled)
client.js               # Browser bundle
types/                  # Emitted declarations
src/
index.ts                # Host-side entry: inert apply (persistence is client-side)
invariant.ts            # Companion plugin for invariant checks
theme-color-settings.ts # Shared constants, types, and the localStorage key
css-modules.d.ts        # Type declarations for CSS Module imports
client/
index.ts              # Client-side entry: reads/persists theme, applies overrides, registers row
color-themes.ts       # Theme definitions (token overrides for each color theme)
ThemeColorRow.tsx      # React component for the settings row
ThemeColorRow.module.css # Styles for the settings row
locales.ts            # i18n strings (zh/en)
README.md                 # This file

已知限制与待办工作

- 颜色主题不会影响滚动条或代码高亮颜色——这些由单独的样式表（scrollbar.css、shiki.css）设置样式，它们使用各自的 token 集。未来版本也可以覆盖这些 token。
- 持久化是按浏览器进行的——该选择保存在 localStorage 中，因此不会跨机器或浏览器跟随用户。DSH 设置文档本应是其天然归属，但 Host API 网关尚未暴露插件拥有的设置命名空间（settings-not-exposed 是有意设置的允许列表边界；参见 apiproxy 中的 WEB_SETTINGS_NAMESPACES）。如果 harness 增加了插件拥有的暴露，请将持久化迁移到设置接缝。
- 不支持自定义主题创作——这五个主题是内置的。未来版本可以允许用户定义自定义主题。
- 活动主题未反映在初始 HTML 引导中——在客户端插件树激活之前的首次绘制使用默认主题。内置主题引导（boot-theme.ts）仅处理浅色/深色/系统偏好。未来版本还可以将颜色主题令牌嵌入引导脚本中。