露娜主题 shinku-xuan/dsh-luna-theme

dsh-luna-theme

为 DSH 桌面端和 Web 客户端提供 Luna-Chat 风格的浅色与深色主题，并随包提供露娜余额挂件、朝日桌宠和游戏主界面开屏。

- 安装与组件开关
- 主题外观
- 对话背景
- 露娜余额挂件
- 朝日桌宠
- 开屏动画
- 项目结构与开发
- 素材与许可
- 更新日志

安装与组件开关

这是 DSH bundle：安装到目标配置档后，重启应用加载主题与组件。插件包版本为 0.15.0；功能变更见更新日志。

| 行 id | 功能 | 包入口 |
| dsh-luna-theme | 配色、材质、背景动画和内存徽标 | dsh-luna-theme |
| luna-balance-widget | 露娜余额挂件 | dsh-luna-theme/widget |
| luna-pet | 朝日桌宠与聊天 | dsh-luna-theme/pet |
| luna-opening | 启动页皮肤、镜头拉远开屏与语音 | dsh-luna-theme/opening |

三个组件可单独停用。在配置档的 cordis.patch.yml 中按行 id 设置 disabled: true，例如：

- id: luna-opening
disabled: true

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

主题外观

浅色模式使用樱花粉、白色玻璃面板和蓝紫色次要按钮；深色模式使用紫色玻璃面板和金色强调。设置面板、菜单、输入框读数、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 提供给客户端。安装后无需访问制作素材时的本机目录。

背景设置

在 DSH「设置 → 背景」中调整以下选项，点击「保存」后才会一次写入当前配置文档并应用到对话背景，刷新后保留，并同步到连接同一 Host 的客户端。编辑控件、按回车、离开输入框和点击「恢复默认」都只修改草稿，不改变正在播放的背景。关闭面板或离开背景分区会丢弃未保存的草稿；已点击保存的请求继续等待 Host 确认。轮换间隔使用数字输入框，保存时拒绝空值、小数和小于 12 秒的值。保存被拒绝或无法确认结果时保留草稿，可再次点击保存。

| 配置字段 | 功能 | 默认值 |
| animated | 启用角色动画，关闭后显示静态图 | true |
| mask | 明暗主题遮罩强度，0–100% | 56 |
| blur | 背景模糊半径，0–24px | 2 |
| transparency | 背景透明度，0% 完全显示、100% 完全透明 | 0 |
| backgroundMode | rotate 按编号轮换，fixed 固定背景 | rotate |
| rotationSeconds | 每张背景的显示时间，整数秒，最少 12 秒 | 30 |
| backgroundId | 固定模式下选用的资源 id | luna-1 |
| transitionMilliseconds | 背景交叉淡化时间，可通过配置修改，0–5000ms | 1000 |

轮换顺序为 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 1，与单个视频的循环时长独立；关闭动态背景后改为轮换对应 PNG。播放方式菜单使用 DSH 的菜单样式；选择固定背景后显示一排静态缩略图，不显示名称，支持鼠标、触摸和键盘选择。选择与恢复默认都要点击保存后才生效。后台页面暂停视频和轮换计时，返回后继续剩余时间；系统启用“减少动态效果”时使用静态图并直接切换。模糊、遮罩和透明度只作用于对话背景，不改变设置面板的图片与控件。

切换时保留前一张画面，等新图片或视频就绪后，在默认一秒内让前一张降低透明度、后一张增加透明度。淡化结束后释放旧视频与场景；快速再次选择时收尾上一段淡化，最多同时保留两个场景。视频播放失败使用对应 PNG，图片加载失败保留已有场景，并在设置页提供重试。停用插件会释放媒体、淡化动画、轮换定时器和监听；只读配置下禁用调整。

背景资源接口

resources/backgrounds.json 是资源目录，定义稳定的 id、数字顺序 order、中英文名称、poster、可选 video、循环时长 duration 与内容版本 revision。资源使用 assets/backgrounds/<id>.png 与 <id>.mp4；Host 在加载时检查缺失资源、重复编号和路径，提供支持 Range 与 HEAD 的 /dsh-luna/backgrounds/<id>.* 路由。URL 包含 revision，替换成片时更新版本以刷新缓存。新增背景时添加目录条目及资源，并运行 npm run build 更新 lib/client.js 内的背景模块与目录快照；只有 PNG 的条目可省略 video 和 duration。
播放顺序按 order 的数字值排序，与 JSON 插入位置无关。src/client/background/ 中的 playback.js 负责轮换时钟，editor.js 负责草稿与原子保存，renderer.js 负责媒体、淡化和清理，index.js 注册设置页面。偏好与资源类型位于 src/shared/background-types.d.ts。外部编辑器可通过主插件 ConfigForm 修改 backgroundMode、rotationSeconds 与 backgroundId。目录中的 aliases 将已保存的旧 id luna-v08 解析到 luna-1，无需保留旧媒体。客户端使用 lib/client.js 中的模块与目录快照，不另行请求这些源文件。

露娜余额挂件

头像为透明背景、银白长发、红色胶囊眼的极简露娜形象，保留独立白色余额框并水平镜像显示。气泡以较大字号显示金额和计费时段，正常状态和刷新过程中都不显示提示文字。点击人物刷新余额，拖拽可移动并吸附到屏幕左右边缘。

鼠标靠近挂件和按钮区域时，切换、收起、放大与缩小按钮显示；移开后隐藏。键盘聚焦时显示操作，触屏上保持显示。点击「切换」在「可用余额」和「本日已用金额」之间切换；打开页面时默认显示余额。点击收起按钮后挂件移到屏幕外，靠近边缘可找到展开按钮，再次点击恢复位置和尺寸。操作与状态支持中英文。

余额优先用 DSH 配置的 DEEPSEEK_API_KEY 查询官方余额接口；没有这个密钥时改用已登录的 DeepSeek 账号，把充值钱包与赠送钱包的金额相加后显示，因此只登录账号、从未申请密钥的读者也能看到余额。密钥必须是 DeepSeek 官方 API 密钥，其他服务商的密钥不能查询此接口。余额查询含重试与账号回退共限时 20 秒，密钥拒绝和超时显示对应提示；密钥与账号令牌都不会发给页面。尺寸读取与金额查询同时开始，尺寸请求失败不影响金额。页面资源路径跟随 DSH 的文档 base，支持反向代理的子路径部署。尺寸保存在当前 profile 的 luna-widget-size.json，读取时兼容包内和 profile 根的旧 .dshw-size.json；新修改只写入 profile，替换安装包后继续保留。诊断日志 luna-theme-ping.log 同样保存在 profile。收起状态仅在当前页面保留。

本日金额需要登录 DeepSeek 账号，按北京时间当天零点至次日零点读取平台用量账单，汇总账号所有 API Key 和模型的金额，包含 DSH 之外的消费；未登录时显示登录提示。仅配置 API 密钥仍可查看余额，但不能查询平台账单。若 API 密钥属于其他账号，余额与本日金额对应各自的数据来源。金额优先显示人民币，否则显示美元，两种币种不相加。当前选中的金额每分钟更新，也可点击人物手动刷新；跨天清除昨日金额，刷新失败保留当天最后的读数并提示重试。平台账单可能延迟更新。

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

朝日桌宠

朝日在窗口底部活动，支持拖拽、抛掷、落地反弹、点击反应、打盹以及任务状态联动。十二种动作采用 Live2D 模型经实际 Cubism Core 渲染的透明动画，以 30fps 分段图集播放。页面只解码当前及下一段，最多保留三张解码图集；切换资源时保留上一幅画面，减少动态效果模式显示当前动作的首帧，后台暂停动作时间。停用主题会停止桌宠定时器、请求和监听，并释放动画缓存。

| 动作 | 使用场景 |
| 站立 idle | 空闲 |
| 挥手 wave | 问候、唤醒 |
| 思考 thinking | 模型思考、聊天等待回复 |
| 工作 working | 任务处理中、工具结果返回 |
| 等待 waiting | 等待用户确认或回复 |
| 开心 happy | 任务完成 |
| 难过 sad | 任务失败 |
| 惊讶 surprise | 点击反应 |
| 打盹 sleep | 空闲睡眠 |
| 拖拽 drag | 鼠标提起 |
| 行走 walk-a | 漫游、回家 |
| 下落 fall | 松开、抛掷、反弹 |

所有动作统一使用细白色外描边，厚度随桌宠尺寸缩放。显示时先收敛素材自带的浅色边缘，再补上统一白边；黑色轮廓、五官和衣服内部线条保留。原有静态姿态及加载失败后的回退画面也使用相同描边，原图和动画图集不改写。

地面平移只在实际显示行走动作时推进；挥手、惊讶、任务状态和其他非行走动作期间暂停，行走画面加载完成后才能继续。拖拽跟随鼠标，下落继续使用重力和反弹。

行走使用左右两套原地步态，步态按实际移动距离选帧；屏幕位移由插件处理，保持角色正面，不再切成侧身或镜像角色。下落姿态和抛掷轨迹分别播放，原有重力、反弹和边缘限制继续生效。其他动作保留各自的眨眼、手部和发裙运动。

新资源位于 assets/pet-live2d/，共 2592 帧、217 张分段图集，包含行走的左右方向。客户端播放离线渲染结果，无需加载 Cubism SDK。分段图集加载失败后分别等待 0.5 秒、1 秒重试；连续失败三次后，每隔 30 秒重试仍需要的图集。当前分段尚未就绪时暂停动作时间并保留上一幅画面，连续失败三次才临时使用原有静态姿态或八帧图集，图集恢复后自动继续新动画。下一段预加载失败不影响已经就绪的当前分段；后台取消未完成的图集请求，回到前台后重新加载。profile 根或包内 pet-art/ 中与配套素材不同的自定义姿态仍优先使用；与配套素材逐字节相同的旧副本继续使用新动画。

右键菜单提供对话、切换模型、清空上下文、调整尺寸、回到角落、原地不动和睡一会儿。回家时加快位移，步态节奏保持正常；原地不动只暂停自主漫游，拖拽、抛掷和回家仍可使用。位置、尺寸、打盹与移动偏好保存在浏览器 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 可跳过，语音期间同样有效。浏览器阻止自动播放时，全黑画面显示「播放语音」；图片或音频失败时提供重试，也可点击空白画面跳过。播放与重试按钮不会同时触发跳过。系统启用减少动态效果时直接显示完成构图，停留与渐黑缩短，仍等待语音结束。

开屏期间应用内容不可交互；退出或卸载会停止语音、撤回遮罩并恢复原有焦点和交互状态。开屏只读取挂载时的主题，不修改模式偏好。

项目结构与开发

源码按 Host 和 Client 分开，再按背景、余额挂件、桌宠、开屏归类。包的公开入口仍为 dsh-luna-theme、/client、/widget、/pet、/opening、/backgrounds 和 /background-types；安装配置和资源 URL 不受内部文件位置影响。

src/
host/ Node 路由、凭据读取和服务接入 client/ index.js 主题配色、样式和组件脚本挂载 background/ 背景设置、草稿、轮换、渲染和样式 widget/ 余额挂件页面脚本 pet/ 桌宠页面脚本与动画播放器 opening/ 开屏脚本、样式和首屏皮肤 shared/ 背景资源与偏好的类型定义 resources/backgrounds.json 背景资源目录与默认值 assets/ 随包运行的图片、视频、音频和图集 persona/ 桌宠人格提示词 scripts/ 客户端构建脚本 tests/ 入口、资源路由与客户端加载回归 lib/client.js DSH 加载的最终客户端文件

安装 package.json 声明的运行与开发依赖后，在插件目录执行：

npm run build
npm run build:check
npm test

build 从 src/client/index.js 收集本地模块、样式、目录和设置图片，生成 DSH 支持的 lazy CommonJS 客户端；React 与 DSH 控件使用应用提供的模块。build:check 只检查成品是否与源码一致，不改写文件；修改源码、背景目录或设置图片后重新构建。Host 直接运行 ESM 源文件，余额挂件与桌宠的经典页面脚本分别由对应 Host 组件提供，开屏代码也由原来的资源 URL 提供。

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

开源目录保留源码、回归测试、构建脚本、最终客户端文件、文档和运行素材。开发副本中的制作工具、原始图层、预览、历史交接资料及运行状态独立保留，不同步到开源目录，也不进入 package.json 的发布清单。

素材与许可

代码采用 MIT License。余额挂件代码派生自 MeteorNOX 的 DeepSeek-Balance-Whale-Widget，许可和改动声明见 THIRD-PARTY-NOTICES.md。

《近月少女的礼仪》相关插画、角色、Logo、语音及其派生图像的权利归 Navel；代码的 MIT 许可不覆盖这些素材。本插件用于个人非商业界面装饰，素材声明和移除说明见上述文件。