中文 · English · 日本語 · 한국어 · Español · Français · Deutsch · Русский

🎮 两种玩法，一条插件都给你

两种玩法分层独立、互不干扰：预设主题决定「意境与底色」，自定义一层是纯叠加（overrideTokens），随开随关、一键还原。

📸 实机截图

真机效果，非概念图。水墨主题应用于 DSH 界面，东方意境与现代工具的融合。

🎨 预览 — 墨韵系列

玩法一 · 开箱即用的意境。 5 套水墨主题，由各主题的真实 token + 意境背景生成——所见即所得。点开可放大查看。

远山孤松 · 远山淡影，苍松独立	烟雨江南 · 水乡烟雨，灯影朦胧	竹影清风 · 翠竹摇曳，清风徐来
梅傲霜雪 · 梅花傲雪，枝干虬曲	山水留白 · 留白写意，远山孤亭

📋 主题一览

🧱 强大自定义空间（玩法二）

预设主题之外，墨韵还给你一套完整的自定义体系——想要独一无二的水墨意境，从这里开始。

一切都叠加在预设之上，随开随关、一键还原到 DSH 内置外观——大胆去试，不会弄坏什么。

⚡ 一句话安装

复制下面这句话给你的 DSH，它自己会装好一切：

请帮我安装 dsh-web-theme 墨韵水墨主题插件（https://github.com/luckzhangfengbo/dsh-web-theme 或 npm 的 dsh-web-theme），装完告诉我如何重启 DSH Web。

不想麻烦 Agent？命令行一条：

dsh plugin --profile web add dsh-web-theme && dsh web

🚀 现已发布到 npm！ 装好 DSH 后，一条命令即可安装，无需 clone。

致敬 https://github.com/luckzhangfengbo/dsh-dream-skin 。 借鉴其插件架构与设计理念，但专注于中国水墨画风格与东方美学。

🏆 为什么值得用（vs 同类）

换个赛道看：同类插件把换肤做成二次元题材的「贴图墙」；我们把换肤做成水墨意境与东方美学的精细化表达—— 追求的不是「更花」，而是「更雅、更远、更耐看」，像一幅反复推敲的水墨画。意境是我们的护城河。

✨ 功能一览

🧩 它是什么形式的插件

它是 DeepSeek Harness 的标准「双面插件」（dsh-plugin）——加载和用法与官方 ui-theme 完全一致。

DeepSeek Harness 的口号是「一切皆插件」：模型、工具、沙箱、会话、UI，乃至 Agent Loop 本身都是插件。 dsh-web-theme 的本质就是把「水墨换肤」做成一个和官方 UI 包同构的 npm 包：

            ┌────────────── dsh-web-theme（标准 dsh-plugin / 双面插件）──────────────┐
            │  dsh.bundle   → cordis.patch.yml 插入 dsh-web-theme 入口   (host 半边)     │
            │  dsh.client   → client/client.js（浏览器 bundle）          (浏览器半边)     │
            └─────────────────────────────────────────────────────────────────────────┘

• 安装命令 = 官方唯一安装命令：dsh plugin --profile web add dsh-web-theme
• 调用的是官方扩展点：ctx.theme（注册主题）、ctx.theme.overrideTokens（叠加层）、 ctx.slots（把 UI 挂进独立的 设置 → 主题 分节）。
• manifest 契约与官方一致：dsh.bundle + dsh.client + exports["./client"]。

也就是说：你装的不是一个旁门左道的脚本，而是 DSH 官方插件体系里的标准主题插件。

⚡ 快速开始（3 步）

# 1. 安装
dsh plugin --profile web add dsh-web-theme
# 2. 重启
dsh web
# 3. 打开 设置 → 主题 → 挑一套水墨意境 → 完。

装的是 npm 已完成发布的正式包，无需 clone。若 dsh plugin add 报 workspace 相关错误，补一个 -w 即可。

📦 安装

四种方式任选其一，装完重启 DSH Web 即生效（当前会话会中断，但 DSH 会话有磁盘持久化，重启后可以恢复）。

方式一：npm 正式包（推荐，最简单）

dsh plugin --profile web add dsh-web-theme

方式二：从 GitHub 安装

dsh plugin --profile web add 'github:luckzhangfengbo/dsh-web-theme'

方式三：克隆后从本地路径安装（开发迭代）

git clone https://github.com/luckzhangfengbo/dsh-web-theme.git
cd dsh-web-theme
dsh plugin --profile web add .

dsh plugin 会把相对路径锚定到你运行命令的目录，装的是指向克隆目录的 link 依赖：改完源码保存，重启 DSH 即生效，无需重新安装。

重启并验证：

dsh web
dsh --profile web --dump-config | grep -A2 dsh-web-theme   # 应出现 dsh-web-theme loader 条目

打开 设置 → 主题，即可看到「预设主题」「自定义图片」「模糊 / 透明度」与「粒子特效」等选项。

-w 标志在裸 add 时必需：每个 profile 自带 pnpm-workspace.yaml，pnpm 会把它当作 workspace 根，裸加报错 ERR_PNPM_ADDING_TO_ROOT。若已加过 -w，后续用现有 workspace 即无需重复。

🔄 更新 / 卸载

更新到最新版（装的是 npm 正式包时）：

dsh plugin --profile web update dsh-web-theme
dsh web   # 重启生效

卸载：

dsh plugin --profile web remove dsh-web-theme
dsh web   # 重启后恢复官方外观

🧩 兼容性

升级 DSH 到新版本时，请同步更新 package.json 里的 peerDependencies。

⚙️ 工作原理

DSH 的主题系统是 token 化的：web 外壳内置 --dsw-* 设计令牌，ThemeRuntime 允许第三方插件注册主题去 覆盖别名层（--dsw-alias-*）。本插件是标准的「双面」插件：

                ┌─────────────────────────────────────────────┐
                │            dsh-web-theme (双面插件)          │
                ├────────────────────────────┬────────────────┤
    Host 半边   │  src/index.ts               │  浏览器半边      │
                │  cordis.patch.yml 插入      │  client/client.js │
                │  dsh-web-theme loader 入口  │  __ModuleLoader__│
                └────────────────────────────┴────────────────┘
                             │                         │
                        profile 树加载              /plugins/dsh-web-theme/client.js
                                                          │
        ┌────────────────────────────────┬────────────────┐
        │                                │                │
   ctx.theme.register(5套主题)      ctx.theme.overrideTokens(壁纸半透明)   ctx.slots.inject('settings.section' + 'settings.moyun.item')

• Host 半边（src/index.ts）：dsh.bundle patch 层，插入 dsh-web-theme loader 入口；同时注册主题图片 API 路由（/api/dsh-web-theme/themes/*.png）供浏览器端预览图加载。
• 浏览器半边（client/client.js）：
  1. ctx.theme.register(...) 注册 5 套水墨主题的 tokens；
  2. 恢复上次保存的主题并 ctx.theme.setTheme(...) 应用；
  3. 壁纸渲染为 z-index:-1 固定背景层，叠加 ctx.theme.overrideTokens(...) 让主画布与侧边栏半透明；
  4. 监听 theme/change，切主题 / 深浅色时自动重新着色壁纸；
  5. 墨点粒子动画层，密度可调；
  6. 注册独立的 设置 → 主题 分节（settings.section），功能行挂在 settings.moyun.item 插槽下。

每套主题携带自己的 colorScheme（dark），驱动 body[data-ds-dark-theme]；别名 token 覆盖作为 <body> 内联自定义属性由 ui-layout 的 ThemePresenter 应用。

💼 持久化说明

• 主题选择存于 localStorage（键前缀 dsh-web-theme:），只在当前浏览器生效。
• 自定义壁纸存储于 IndexedDB（dsh-web-theme-db / images 仓库），支持大图持久化。
• 设置（模糊、透明度、粒子密度等）通过 DSH Host settings API 同步，跨浏览器标签页共享。
• 为何不用单一存储？壁纸图片可能数 MB，IndexedDB 更适合大图存储；偏好设置用 localStorage 读写更快。

🛠️ 开发 / 扩展

客户端 bundle 直接以 __ModuleLoader__ 格式编写（即 tsdown 为官方 ui-* 包输出的形态），免构建。 client/client.js 只能 require 模块表实体：平台种子词（react、react/jsx-runtime、…）与已注册客户端 bundle（@deepseek-ai/dsh-client-runtime/client、…）。

• 新增一套内置主题：在 client/themes.js 的 THEMES 数组加一个对象（id + name + description + tokens）， 它即自动出现在设置里；记得在全部 8 种语言词典（client/i18n.js）补对应文案。
• 放你自己的壁纸：把图片丢进 themes/ 目录（注意只在你有权限的前提下分发），再在 DSH 的「自定义图片」里导入即可。
• 编译 TypeScript：npm run build 编译宿主端代码到 dist/。
• 开发模式：npm run dev 监听 TypeScript 变更自动编译，另开一个终端 dsh web 启动服务。

📌 Roadmap

• 首版：5 套水墨主题 + 自定义壁纸（模糊 / 透明度）+ 本地持久化
• 墨点粒子特效（密度可调）
• 8 种语言国际化
• DSH 原生设置面板集成（dsh-settings 注册）
• 更多水墨主题（四季系列、山水长卷等）
• 在线主题 Studio（浏览器内调色 + 实时预览）
• 首帧无闪烁（FOUC）改进
• 社区主题投稿与分享

🤝 贡献

欢迎提交 Issue 与 PR！请先阅读 贡献指南。

⭐ 支持这个项目

喜欢的话，给仓库点个 Star ⭐、在 npm 上点个 👍，或把它转发给你的 DSH 朋友——这会让更多人发现它， 也能激励持续维护。

🔒 安全

发现安全问题？请勿直接开公开 Issue。

📄 开源协议

MIT

🙏 致谢

• 架构与 API 参考：DeepSeek Harness 官方 https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-theme 客户端包。
• 设计理念与插件架构参考：https://github.com/luckzhangfengbo/dsh-dream-skin 。
• 主题意境灵感：中国传统水墨画（宋画、元画意境）。

📈 成长曲线

发布后每天自动更新（GitHub Actions）。下载量来自 npm 公共 API。

📊 发布后此处将展示下载量曲线图