前言¶

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