主题工坊 MangMax/dsh-themes

dsh-themes

DSH(DeepSeek Harness)运行时的外观与主题插件：内置调色板、明 / 暗 / 跟随系统外观模式、Open VSX 搜索安装、VS Code 主题导入，主题库持久化。

主题引擎（语义角色映射、双种子生成、对比度求解、OKLCH 感知导入映射）的架构灵感来自 t3code

screenshot

兼容性

- 需要 DSH >=0.1.5-rc.1 <0.2.0（通过 peerDependencies 声明，DSH 的插件兼容性门禁据此判定）
- 已在 0.1.7-rc.2（当前最新）与 0.1.5-rc.2 上验证
- Host 半区不再使用 connection.rpc.handle，改为 connection.fetch.register 注册精确 Fetch 路由 /api/dsh-themes：该路由由 DSH 自有的 /api 前置路由转发，自带 trusted-host 检查与浏览器会话鉴权，且不需要消费方注入 webServer。0.1.7 起 connection.rpc.handle 会把路由挂到 connection 插件自身的
fiber 上（owner.effect(() => owner.webServer.register(…))），消费方调用即抛
cannot get property "webServer" without inject
- 因此 不再需要 在 profile 的 cordis.patch.yml 里给 connection 行补
inject: [webRuntime, webServer]（0.1.5 时代的临时绕行补丁，0.1.9 起可删除）

0.2.0：导入修复与提速

这一版解决「导入 Tokyo Night 报 未贡献颜色主题」。根因不是扩展的问题，而是本插件的解析器：

1. VS Code 主题是 JSONC。enkia.tokyo-night 的三个主题文件全部含 // 注释（第 87 行起有整段被注释掉的键），而旧实现用严格 JSON.parse 解析 → 三个文件全部失败 → 宿主返回空主题列表 → 界面误报「未贡献颜色主题」。
现在统一走 jsonc-parser（与 t3code 同一套做法：
parse(text, errors, { allowTrailingComma: true })），注释、尾随逗号、BOM 都能读，
本地扫描 / URL / 粘贴 / VSIX 四条路径一致。
2. 浅色变体被判成深色。Tokyo Night Light 的主题文件里写的是 "type": "dark"（上游笔误），只有扩展清单的 uiTheme: "vs" 说得对。现在按 t3code 的做法用清单 uiTheme 覆盖文件 type，浅色变体终于能出现在明色槽里。
3. 导入提速：
- 按需解压：VSIX 里体积最大的是 readme / changelog / 图标 / .itermcolors，主题相关文件一定是 .json。改用 fflate 的 filter 只解 JSON，不再全量 inflate。
- 压缩载荷：只保留调色板映射真正用到的 44 个 workbench 颜色键，丢掉 tokenColors / semanticTokenColors。实测 Tokyo Night 三个主题的最小化 JSON 载荷 117,679 → 4,412 字节（-96.25%） （对比口径：三个主题文件各自 JSON.stringify 后的字节数之和，即不裁剪时会发给客户端的数据量）。
- 一次批量详情：搜索后的作者/许可证补齐从 N 次 RPC 合并为 1 次 open-vsx-details。
- 搜索缓存 + 短超时：同一关键词 60 秒内直接命中内存；Open VSX 慢请求 10 秒即失败，不再让界面干等 90 秒。
4. 反馈用 Toast：成功/失败提示改用 DSH 原生 Toast （@deepseek-ai/dsh-client-ui-primitives 的 seed word 模块），顶部居中、自带滑入/淡出动画、 z-index: 1100 位于所有面板之上——不再渲染在设置页底部（那里根本看不到）。
5. 搜索有动画：输入 350 ms 去抖自动搜索、回车立即搜索（跳过输入法组字）、输入框内联 spinner、结果区加载态、结果行渐入，并尊重 prefers-reduced-motion。
6. 集成回归测试：node scripts/e2e-import.mjs 用真实的 Tokyo Night VSIX 跑完整链路（52 项断言，含冷缓存下载这条曾经漏掉的路径），node scripts/check-vs-keys.mjs 保证颜色白名单永远覆盖映射器读取的每个键。

功能

- 主题卡片模型：每个主题含明色/暗色两个变体槽，槽内聚合全部明色/暗色变体可选；导入的扩展聚合为一个主题卡片
- 默认主题卡片：DSH 原生外观也是可选主题；删除使用中的导入主题或点击「恢复默认主题」均回退到它
- 变体选择器：多色融合球列表（参照 t3code ThemePreviewCircle），选中放大（固定槽位不跳动）、溢出左右箭头导航、悬停显示变体名
- 外观模式：跟随系统 / 浅色 / 深色，明暗变体随模式自动切换
- 搜索安装（Open VSX）：单请求搜索（60 秒 TTL 缓存、10 秒超时），展示图标 / 作者 / 许可证 / 评分 / 更新时间；作者等详情一次批量补齐；输入去抖 + 内联 spinner + 结果渐入的搜索动画；「导入」一步完成下载、按需解压、解析（JSONC + include 合并）与聚合导入，版本化缓存让重复导入秒开
- VS Code 导入：本地扩展扫描、URL 获取、粘贴 JSON，四条路径统一支持 JSONC（注释 / 尾随逗号 / BOM）；清单 uiTheme 覆盖文件 type，浅色变体不再被误判；OKLCH 感知引擎派生表面，workbench 指定值对比度门控，操作色独立于 accent
- 提示用 Toast：成功 / 失败反馈走 DSH 原生 Toast（顶部居中、自带动画、位于所有面板之上），不再内联在页面底部
- 状态动画色：运行状态点阵（--dsh-state-ongoing → --dsw-static-deepseek-450）跟随主题
- 完整 token 覆盖：DSH 设计平台 95 个颜色 token（表面层级 bg-layer-1~3 / 浮层 / 遮罩、文字层级 primary~caption、交互反馈、按钮、Markdown、状态补充、滚动条、Toast/Tooltip、侧栏与菜单等专用 token）全部随主题覆盖；「修改」编辑器按语义分组可调
- 设置页导航图标：设置面板「主题」菜单图标替换为调色板图标（取自 reicon 图标集，https://github.com/dqev/reicon）
- 中英文界面：设置页文案与提示跟随 DSH 语言设置（设置 → 通用 → Language），切换即时生效；主题库持久化数据保持语言中立，展示时自动本地化
- 持久化：主题库保存到 ~/.dsh/dsh-themes.json，重启后恢复
- 跨平台（Windows / macOS / Linux）：网络与本地文件全部在宿主进程内完成（全局 fetch + node 内置模块 + fflate 内存解压），不依赖 shell 的 curl/mkdir/unzip 等 Unix 命令，Windows（pwsh）下同样可用

开发

源码为 TypeScript 模块，由 VitePlus（vp）打包为 DSH 插件函数体（vite.config.ts 的 pack 块负责构建）。

pnpm install # 安装依赖(vite-plus 已声明为 devDependency,构建不再依赖全局 vp)
pnpm build # vp pack → dist/client/index.cjs 与 dist/host/index.cjs
pnpm verify # ★ 完整门禁 = build + check + test(CI 与发版用这个)

pnpm check # 源码级:颜色白名单覆盖 + 中英文字典对齐(无需构建)
pnpm test # 产物级:产物形状 + 真实 VSIX 端到端(需先 build)

bash scripts/install.sh # 一键:构建 → 组装 npm 包 → 安装到 DSH profile bash scripts/install.sh --pack-only # 只构建并打包,不安装(CI 发版用)
DSH_PLUGIN_PROFILE=desktop bash scripts/install.sh # 安装到其他 profile(默认 web)

scripts/install.sh 优先用 ./node_modules/.bin/vp（CI 里没有全局 vp），版本从 package.json 读取，不再有两处版本号。
注意 vp 的原生插件在部分 Electron 自带 node 下会因签名 Team ID 不匹配而无法加载，本地开发换用系统 / nvm 的 node 即可（例如 PATH=$HOME/.nvm/versions/node/vXX/bin:$PATH vp pack）。
vite 是别名：package.json 里写的是 "vite": "npm:@voidzero-dev/vite-plus-core@<与 vite-plus 同版本>"。
vite-plus 0.3 起会校验这个别名（否则报 Expected @voidzero-dev/vite-plus-core@x, but found vite@y），所以升级 vite-plus 必须把别名一起改成同版本，改完先跑 pnpm verify。
当前：vite-plus 1.0.0-rc.0（内含 vite 8.3.x），要求 Node ^22.19.0 || ^24.11.0 || >=26.0.0。

结构

shared/ # 两侧共用(打进各自产物) jsonc.ts # 宽松 JSONC 解析(jsonc-parser + 允许尾随逗号 + 去 BOM) vs-colors.ts # VS Code 颜色键白名单 + 压缩载荷(宿主 → 客户端的唯一主题形状) client/src/ # 浏览器半区(设置页 UI、调色板引擎) color-utils.ts # RGB/HSL/WCAG 对比度、双种子调色板 oklch.ts # OKLCH 感知引擎(导入派生) chat.ts # t3 chat 调色板(t3.chat 界面取色,颜色保持原样) vs-import.ts # VS Code 主题解析与映射 toast.ts # 基于 DSH 原生 Toast 的提示队列 palette.ts # token 清单、默认外观、内置主题 styles.ts # 设置页样式(含搜索/加载动画) index.ts # 入口:状态/覆盖层/设置页/编辑器/注册 host/src/ # Node 半区(RPC) util.ts # 跨平台网络/文件工具(可配超时与重试) index.ts # 入口:扫描/读取/搜索/详情/安装/持久化 scripts/ install.sh # 一键构建 + 组装 npm 插件包 + 安装 e2e-import.mjs # 端到端导入回归(真实 Tokyo Night VSIX) check-vs-keys.mjs# 颜色白名单覆盖守卫

发版(自动发布 npm)

一条命令搞定:改版本 → commit → tag → push,CI 接着跑门禁、发 npm、生成带 changelog 的 Release。

pnpm release # bumpp(antfu):选版本号 → 更新 package.json → commit → tag vX.Y.Z → push

push tag 后 .github/workflows/release.yml 自动执行:

| 步骤 | 说明 |
| 校验 tag 与 package.json 版本 | 不一致直接失败,避免「tag 是 v0.3.0、发出去还是 0.2.0」 |
| pnpm verify | 完整门禁(构建 + 源码检查 + 产物检查 + 真实 VSIX 端到端) |
| 组装 + npm publish | 带 --provenance 签名;该版本已存在于 npm 时自动跳过(幂等,重跑不会因版本冲突变红) |
| changelogithub 生成 Release | 由 conventional commits / PR 分组生成的变更清单;.tgz 一并附到 Release |

之后 dsh plugin add <Release 里 .tgz 的链接> 就能装到指定版本。

也可以在 GitHub 上手动 Draft a new release 建 tag(旧习惯仍然有效 —— 工作流同时监听 release: published),或手动触发 workflow_dispatch 指定 tag 重跑。

认证只需配一次(二选一,工作流两种情况都支持):

- A. npm 可信发布(OIDC,推荐,无需任何 secret):npmjs.com → 包 dsh-themes → Settings → Trusted Publisher → GitHub Actions,填 MangMax / dsh-themes / release.yml,Environment 留空。之后自动带 provenance 签名。
- B. NPM_TOKEN:仓库 Settings → Secrets and variables → Actions 新建 NPM_TOKEN,值用 Granular Access Token(Read and write + 勾选 Bypass 2FA)。配了就优先用它。

预发布版本(版本号带 -,或 Release 勾了 prerelease)会发到 npm 的 next tag,不会顶掉 latest。

安装

方式一(从 npm registry,已发布后):

dsh plugin --profile web add dsh-themes

方式二(本地一键构建安装,适合开发迭代):

bash scripts/install.sh

两种方式安装后均需重启 dsh web,然后进入 设置 → 主题 使用。

使用

- 外观模式:跟随系统 / 浅色 / 深色;主题库默认未指定时由 DSH 默认主题兜底
- 明暗独立归属:点击变体只设置该侧外观的主题,不切换外观模式;浅色与暗色可来自不同主题;点击卡片名称则明暗两侧同时使用该主题
- 颜色编辑器:主题卡片「修改」进入二级页面——改名、明暗切换、分组 token 色块与 hex 编辑(即时生效)、重置修改
- 内置主题「复制」:复制为自定义副本后再编辑,内置主题不可直接修改
- 从 VS Code 导入:扫描本地扩展(~/.vscode/extensions、~/.vscode-insiders/extensions、~/.cursor/extensions)、URL 获取、粘贴 JSON;导入主题可修改、删除
- 搜索安装(Open VSX):搜索、查看卡片内简介与链接、一键导入(缓存秒开)

卸载

移除插件:

dsh plugin --profile web remove dsh-themes

或删除 profile 依赖后重启 dsh web。卸载后调色板覆盖层自动移除,外观恢复默认。