前言¶

DSH 的界面默认是一套通用外壳。做智能体应用的人通常有自己的视觉偏好，但改配色、改背景、加桌面装饰，往往要改应用源码，或者把主题逻辑散落在多个自定义组件里维护。个人换肤类的需求，社区里一般也有零散方案，不过多数只覆盖单一元素，且桌面端和 Web 端行为不一致。

dsh-luna-theme 是一个定位明确的换肤插件：为 DSH 桌面端和 Web 客户端提供 Luna-Chat 风格的浅色与深色主题，并把对话背景、余额挂件、桌宠和开屏动画打包成同一个 bundle，随主题一起加载、一起停用。插件由 shinku-xuan 维护，在社区目录归类为「趣味换装」，目前 GitHub 4 stars、1 fork。当前包版本 0.15.0，代码采用 MIT License。

下面介绍它包含哪些组件、哪些是既定行为、以及接入前需要注意的地方。

这是什么¶

一句话：这是 DSH 的 bundle 插件，安装到目标 profile 后，重启应用即可加载主题和四个随包组件。

它解决的是「个人界面装饰」这一类问题，而不是业务流程问题。作者的取舍也很清楚：主题只读取挂载时的状态，不修改模式偏好；桌宠聊天不写入 DSH Session，主题也不注册模型工具。换句话说，它不会干扰你已有的 Host 配置和 Session 数据。

核心功能¶

主题外观¶

浅色模式使用樱花粉、白色玻璃面板和蓝紫色次要按钮；深色模式使用紫色玻璃面板和金色强调。设置面板、菜单、输入框读数、Markdown 内容与对话轮次导航都跟随配色；模式切换带柔和渐变，窗口的最小化、最大化、关闭按钮直接跟随当前模式。

自带底色的区域有单独处理：Markdown 代码块、终端卡片、JSON 与检索结果，在两种模式下都按底色取前景色，包括括号、花括号、$变量、标点这些未着色的字面量，它们与高亮片段共用同一前景，不会与底色同色或消失。

输入框下方还有一个内存徽标，显示电脑内存使用率，点击后可查看系统总量、已用量和 DSH 进程占用。Windows 按当前可执行文件名汇总进程；其他平台或读取失败时只显示 Host 进程。同名的其他进程可能被计入 Windows 的汇总，这是已知行为。

对话背景¶

随包提供十组编号素材，每组包含 PNG 静态图和约 11.82 秒的 MP4 动画，视频采用 H.264 编码，客户端只播成片，不需要加载 Cubism SDK。主画面按完整构图居中显示，比例不一致的边缘用同图柔化填充，不再做模糊向外扩图。

图片和视频存放在 assets/backgrounds/，文件名从 luna-1.png、luna-1.mp4 到 luna-10.png、luna-10.mp4，运行时由 Host 提供给客户端，安装后不需要访问制作素材时的本机目录。

背景行为有两个值得注意的设计。

第一，设置面板里的修改默认只改草稿。点击「保存」才会一次写入当前配置文档并应用，刷新后保留，并同步到连接同一 Host 的客户端；编辑控件、按回车、离开输入框、点击「恢复默认」都只改草稿，不改变正在播放的背景。关闭面板或离开背景分区会丢弃未保存的草稿。

第二，轮换与淡入淡出是分开计时的。轮换顺序固定为 1 → 2 → … → 10 → 1，与单个视频循环时长独立；切换时保留前一张画面，等新素材就绪后在默认 1000 毫秒内交叉淡化，淡化结束后释放旧视频与场景，最多同时保留两个场景。视频播放失败时使用对应的 PNG。

配置字段与默认值：

资源目录 resources/backgrounds.json 定义了稳定的 id、数字顺序 order、中英文名称、poster、可选 video、循环时长 duration 和内容版本 revision；Host 提供支持 Range 与 HEAD 的 /dsh-luna/backgrounds/<id>.* 路由，URL 带 revision 以便替换成片时刷新缓存。目录中的 aliases 把已保存的旧 id luna-v08 解析到 luna-1，不需要保留旧媒体。新增背景时添加目录条目及资源，并运行 npm run build 更新 lib/client.js 内的背景模块与目录快照。

露娜余额挂件¶

头像是透明背景、银白长发、红色胶囊眼的极简形象，配独立白色余额框并水平镜像显示。气泡以较大字号显示金额和计费时段。点击人物刷新余额，拖拽可移动并吸附到屏幕左右边缘；鼠标靠近时显示切换、收起、放大、缩小按钮，键盘聚焦时也会显示操作，触屏上保持显示。

余额获取有两条路径：优先用 DSH 配置的 DEEPSEEK_API_KEY 查询官方余额接口；没有该密钥时改用当前已登录的 DeepSeek 账号，把充值钱包与赠送钱包的金额相加后显示。密钥必须是 DeepSeek 官方 API 密钥，其他服务商的密钥不能查询此接口。余额查询含重试与账号回退，共限时 20 秒；密钥与账号令牌都不会发给页面。

「本日已用金额」需要登录 DeepSeek 账号，按北京时间当天零点至次日零点读取平台用量账单，汇总账号所有 API Key 和模型的金额，包含 DSH 之外的消费。仅配置 API 密钥仍可查看余额，但不能查询平台账单。金额优先显示人民币，否则显示美元，两种币种不相加；当前选中的金额每分钟更新，也可点击人物手动刷新。

气泡内部下方常驻计费时段显示：「空闲时段」绿色、「高峰时段」红色，与金额查询是否成功无关。高峰按北京时间工作日 09:00–12:00、14:00–18:00 判断，端点 12:00 和 18:00 起为空闲；周末（含调休上班）和中国公众假期全天空闲。插件随附 2026 年节假日数据，新年度需更新日历；未收录年份的工作日高峰窗口显示「时段待确认」。

尺寸保存在当前 profile 的 luna-widget-size.json，读取时兼容包内和 profile 根的旧 .dshw-size.json；新修改只写入 profile，替换安装包后继续保留。诊断日志 luna-theme-ping.log 同样保存在 profile。收起状态仅在当前页面保留。

朝日桌宠¶

朝日在窗口底部活动，支持拖拽、抛掷、落地反弹、点击反应、打盹以及任务状态联动。十二种动作（idle、wave、thinking、working、waiting、happy、sad、surprise、sleep、drag、walk-a、fall）采用 Live2D 模型经实际 Cubism Core 渲染的透明动画，以 30fps 分段图集播放。页面只解码当前及下一段，最多保留三张解码图集；切换资源时保留上一幅画面；减少动态效果模式下显示当前动作首帧；后台暂停动作时间。

资源位于 assets/pet-live2d/，共 2592 帧、217 张分段图集，包含行走的左右方向。客户端播放离线渲染结果，不需要加载 Cubism SDK。分段图集加载失败后分别等待 0.5 秒、1 秒重试；连续失败三次后，每隔 30 秒重试仍需要的图集。连续失败三次才临时使用原有静态姿态或八帧图集，图集恢复后自动继续新动画。

行走使用左右两套原地步态，步态按实际移动距离选帧；屏幕位移由插件处理，保持角色正面，不再切换侧身或镜像角色。地面平移只在实际显示行走动作时推进，挥手、惊讶、任务状态和其他非行走动作期间暂停。右键菜单提供对话、切换模型、清空上下文、调整尺寸、回到角落、原地不动和睡一会儿；位置、尺寸、打盹与移动偏好保存在浏览器 localStorage。

桌宠聊天使用 DSH 已配置的模型，会消耗对应模型额度，回复以流式文字显示。聊天路由使用应用的请求鉴权，鉴权服务缺席时拒绝请求；人格提示词随包提供于 persona/asahi-chat.md。这组聊天不写入 DSH Session，主题也不注册模型工具。

开屏动画¶

应用加载后，视点从中央近景逐渐拉远，外侧角色从画面外进入并保持前后遮挡，镜头就位后三层原版 Logo 依次展开。浅色模式使用 Back_1.png，深色模式使用 Back_2.png。默认入场与停留共 7.6 秒，随后用 1.4 秒渐黑；完全黑屏并绘制后才播放 lun_sp06.wav，等待语音实际播放结束再退出开屏，正常播放总时长约 11.6 秒，另加素材读取时间。

点击画面或按 Esc 可跳过，语音期间同样有效。浏览器阻止自动播放时，全黑画面显示「播放语音」；图片或音频失败时提供重试，也可点击空白画面跳过。系统启用减少动态效果时直接显示完成构图，停留与渐黑缩短，仍等待语音结束。开屏期间应用内容不可交互；退出或卸载会停止语音、撤回遮罩并恢复原有焦点和交互状态。

安装与启用¶

插件以 DSH bundle 形式分发，README 给出的安装方式是：安装到目标 profile，重启应用后加载主题与组件；没有给出命令行安装命令。社区目录页提供安装入口，方法是访问插件目录页后按页面提示安装到目标 profile。由于这里涉及以当前 dsh 进程权限运行的插件，安装前建议先阅读源码并确认目录页给出的安装方式。

装好之后，profile 的 cordis.patch.yml 中四个行 id 对应不同功能：

三个组件可以单独停用，按行 id 设置 disabled: true：

- id: luna-opening
  disabled: true

调整 Host 组件配置后需重启应用。停用主题主行会同时撤回主题样式、背景动画和它加载的组件页面脚本。开屏随主题提供，不需要另装开屏插件。

典型用法¶

只看余额，不装桌宠和开屏¶

在 profile 的 cordis.patch.yml 里保留主题主行和余额挂件，停用其余两项：

- id: luna-balance-widget
  disabled: false
- id: luna-pet
  disabled: true
- id: luna-opening
  disabled: true

重启后只加载配色与余额挂件，桌宠和开屏不会占用资源。余额部分在没有 DEEPSEEK_API_KEY 时会自动降级到已登录账号，只登录过账号、从未申请密钥的场景也能看到余额。

固定一张背景并放慢轮换¶

在 DSH「设置 → 背景」中把 backgroundMode 改为 fixed，backgroundId 指定为 luna-3，rotationSeconds 设为 60。点击「保存」后才写入配置文档并应用；离开输入框或点击「恢复默认」只改草稿，不改变播放中的背景。轮换间隔不接受空值、小数和小于 12 秒的值。

调整背景与主题的观感¶

想压低背景存在感时，把 blur 调到 0–24px 之间一档、transparency 提到 30 以上、mask 降到 56 以下即可，保存后生效。这些只作用于对话背景，不改变设置面板的图片与控件。

用外部编辑器配置背景¶

backgroundMode、rotationSeconds 与 backgroundId 可通过主插件 ConfigForm 修改；偏好与资源类型定义在 src/shared/background-types.d.ts。

开发与构建¶

源码按 Host 和 Client 分开，再按背景、余额挂件、桌宠、开屏归类，公开入口为 dsh-luna-theme、/client、/widget、/pet、/opening、/backgrounds 和 /background-types。安装 package.json 声明的运行与开发依赖后，在插件目录执行：

npm run build
npm run build:check
npm test

build 从 src/client/index.js 收集本地模块、样式、目录和设置图片，生成 DSH 支持的 lazy CommonJS 客户端；build:check 只检查成品是否与源码一致，不改写文件。Host 直接运行 ESM 源文件。修改源码、背景目录或设置图片后需要重新构建。

tests/ 保存入口、资源路由与持久化的回归测试，只用于开发验证，不在 package.json 的发布清单中，用户安装包不包含测试文件。

适用场景与注意¶

适合想要把 DSH 界面换成个人化外观、同时希望桌面端和 Web 端保持一致的开发者，或者需要长时间运行桌面端、希望看到余额与模型用量消耗的使用者。它是纯界面装饰类插件，不提供业务流程能力。

需要注意几点。

插件以当前 dsh 进程权限运行，Host 侧会读取凭据（余额查询需要 DEEPSEEK_API_KEY 或已登录账号的令牌）、提供 /dsh-luna/backgrounds/<id>.* 路由，并加载客户端脚本。安装前应检查源码与许可证，确认目录页给出的安装方式与预期一致。

桌宠聊天会消耗 DSH 已配置模型的额度；本轮聊天记录在关闭窗口或清空上下文时清除，不写入 DSH Session。

素材方面，代码采用 MIT License。余额挂件代码派生自 MeteorNOX 的 DeepSeek-Balance-Whale-Widget，许可与改动声明见 THIRD-PARTY-NOTICES.md。插画、角色、Logo、语音等素材权利归 Navel，MIT 许可不覆盖这些素材，插件用于个人非商业界面装饰。

音效与动画对浏览器自动播放策略敏感：被阻止时全黑画面显示「播放语音」，素材加载失败时提供重试或跳转。

结尾¶

dsh-luna-theme 把换肤、背景、余额挂件、桌宠和开屏打包成一个 bundle，用行 id 开关控制加载范围，行为边界也写得很细：草稿与已保存配置分离、轮换与循环计时独立、停用主题时释放定时器与媒体、聊天不写入 Session。对想改造 DSH 外观的开发者来说，它比零散的自定义组件更好维护；唯一需要留意的是素材版权范围和以进程权限运行带来的必要性审查。

插件目录页：https://www.skillhub.cn/plugins/shinku-xuan/dsh-luna-theme

GitHub：https://github.com/shinku-xuan/dsh-luna-theme