前言¶

DSH（DeepSeek Harness）網頁版有幾處界面元素是寫在宿主構建產物裏的：側邊欄左上角的品牌 Logo、空對話時的歡迎區、對話區域的底色。想在內部部署裏換成自己的標識或背景圖，常規做法是改宿主構建，但宿主一更新就得重做一遍。

dsh-customui-plugin 換了個思路：不改宿主構建，通過插件機制往瀏覽器端注入腳本，在 DOM 層做覆蓋，同時在設置頁裏給這些改動一個正式入口。下面介紹它的功能、原理和安裝步驟。

這是什麼¶

dsh-customui-plugin 是一個 DSH web 平臺插件，倉庫地址爲 https://github.com/nexsjournal/dsh-customui-plugin，許可證爲 MIT。它只做一件事：在 DSH 網頁版的設置頁裏新增一個「個性化」導航項，通過這個頁面自定義三處界面元素——側邊欄左上角 Logo、空對話歡迎區（Logo + 文案）、對話區域背景圖。所有修改即時生效，不需要重啓 DSH。

插件沒有任何構建步驟：lib/index.js（宿主側，註冊設置 + 打白名單補丁）與 lib/client.js（瀏覽器側，設置頁 + 即時應用引擎）都是純 JS，安裝前可以直接讀完源碼。

核心功能¶

每個圖片項都支持兩種來源：

1. 上傳本地圖片。客戶端自動壓縮：位圖縮放到不超過 1920px、轉 JPEG/PNG；SVG 原樣保留。
2. 粘貼 https 圖片鏈接。

其他能力：

• 修改即時生效：純瀏覽器端 DOM 覆蓋 + MutationObserver 監聽，React 重渲染、切換會話、側邊欄摺疊後自動補回，應用邏輯冪等。
• 配置寫入 DSH 設置命名空間 customui，隨 profile 持久化，落在 ~/.dsh/settings.yaml 的 customui 段。
• 支持一鍵「恢復默認」，清掉已存配置。

即時生效的原理¶

插件不改宿主構建，靠兩層機制。

第一層是錨點選擇。客戶端腳本不綁定會隨構建變化的哈希 class 名，而是用三個穩定的設計常量做錨點：

品牌字標   svg[viewBox="0 0 182 24"]
歡迎區小魚 svg[viewBox="0 0 23.16 17.04"]
對話區域   [data-conversation-scroll]

第二層是持續監聽。MutationObserver 盯着 DOM，React 重渲染、切換會話、側邊欄摺疊之後都會把自定義內容補回來；應用邏輯冪等，不會無限循環。配置存在 customui 命名空間裏，命名空間一變更立即重新應用——所以在設置頁裏改，界面馬上變。

背景圖的具體落點：鋪在 [data-conversation-scroll] 容器上，經 ::before 僞元素、z-index:-1、真 CSS opacity 控制。透明度低於 100% 時對話區底色會透出，淺色、深色背景都能融合。

安裝與啓用¶

前提：需要已有一個 DSH web 部署（dsh web 或桌面版）；插件 engines 要求 Node >= 20。

執行安裝腳本：

# 方式一：本倉庫目錄（開發期 link: 軟鏈安裝，改動即時生效）
bash scripts/install.sh

# 方式二：npm / GitHub
bash scripts/install.sh dsh-customui-plugin@1.0.0
bash scripts/install.sh git+https://github.com/<owner>/dsh-customui-plugin.git

兩點說明：

1. npm 示例裏的版本號沿用插件 README 的寫法（@1.0.0），與倉庫 package.json 中的 0.1.0 不一致，安裝時以實際發佈的版本爲準。
2. GitHub 方式裏的 <owner> 是 README 中的佔位符，需替換爲實際倉庫所有者；本插件的倉庫地址見上文。

如果不用腳本，等價的手工步驟是：

dsh plugin --profile web add -w /path/to/dsh-customui-plugin

-w 必需，因爲 profile 是 pnpm workspace 根。

安裝後需要重啓 DSH 一次。原因：插件啓動時會把 customui 命名空間冪等地加入 Web 設置頁的 api-proxy 白名單（dsh-host-apiproxy 的 WEB_SETTINGS_NAMESPACES），所以「個性化」導航項與設置寫入在下一次啓動後纔出現。之後所有配置修改都是熱生效的，不再需要重啓。

另外，桌面版更新（覆蓋安裝）會重置 api-proxy 白名單文件，重啓後插件會再次自動打補丁，不需要手工處理。

典型用法¶

經過上面的步驟，重啓 DSH 後打開設置頁，側邊導航裏會出現「個性化」一項（與通用設置、模型、插件、Agent 預設等並列）。接下來的流程：

1. 進入「個性化」設置頁。
2. 逐項設置左上角 Logo、歡迎區 Logo 與文案、對話背景圖；圖片可上傳本地文件，也可粘貼 https 鏈接。
3. 每一項改動立即反映到界面上，不需要刷新或重啓。

想回到原版界面時，點「恢復默認」即可清掉已存配置。

卸載插件：

dsh plugin --profile web rm dsh-customui-plugin

執行後重啓 DSH，再點一次「恢復默認」，把已經寫入 profile 的配置也清掉。

開發者視角¶

對想研究 DSH 插件寫法的開發者，這個插件的打包方式值得看一下。package.json 裏聲明瞭兩塊：

• dsh.bundle.patch 指向 ./cordis.patch.yml，負責宿主 bundle 樹插入；
• dsh.client.inject 注入 @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-locale、dsh-client-ui-slots、dsh-client-ui-settings 四個客戶端包，platform 爲 web。

peerDependencies 裏的 @deepseek-ai/dsh-settings 與 @deepseek-ai/schemastery 均爲可選。

改完源碼可以做語法檢查：

node --check lib/index.js && node --check lib/client.js

文件結構如下：

├── package.json          # dsh.bundle.patch + dsh.client.inject 聲明
├── cordis.patch.yml      # 宿主 bundle 樹插入
├── dsh.plugin.json       # 插件清單
├── lib/
│   ├── index.js          # 服務端：customui 設置命名空間 + api-proxy 白名單自補丁
│   └── client.js         # 瀏覽器端：個性化設置頁 + 即時 DOM 應用引擎
├── scripts/install.sh
├── LICENSE
└── README.md

適用場景與注意¶

適合的場景：

• 團隊內部部署 DSH，想換成自己的品牌 Logo、歡迎語或統一背景圖；
• 個人想給對話區配一張背景圖、替換默認歡迎語；
• 插件開發者想參考「設置命名空間 + 客戶端注入 + api-proxy 白名單自補丁」這套做法。

已知邊界，使用前先確認：

• 側邊欄摺疊（rail）狀態下只顯示圖標、不渲染字標，此時左上角 Logo 不生效，展開後恢復；
• 歡迎區僅在空對話時顯示，有消息後該區域消失（背景圖不受影響）；
• 若某個版本的 DSH 消息氣泡自帶不透明底色，背景圖會被擋住，可降低透明度或換圖；
• 圖片以 data URL 存進 ~/.dsh/settings.yaml 的 customui 段，上傳時雖已自動壓縮，仍建議用幾十 KB～幾百 KB 的圖。

安全方面需要說明：DSH 插件以當前 dsh 進程的權限運行，安裝任何第三方插件前都應檢查源碼與許可證。就這個插件而言，無構建步驟、lib 下兩個文件均爲純 JS、許可證爲 MIT，審閱成本比較低。

結語¶

dsh-customui-plugin 用插件機制給 DSH 網頁版補上了界面個性化的能力：改動即時生效、隨 profile 持久化、不動宿主構建。對想給內部部署換品牌的團隊，或者想學習 DSH 插件寫法的開發者，都可以先把源碼過一遍。

DSH 的理念是「一切皆插件」，這類個性化插件正是這套機制的正常用法。

• 插件目錄頁：https://www.skillhub.cn/plugins/nexsjournal/dsh-customui-plugin
• GitHub 倉庫：https://github.com/nexsjournal/dsh-customui-plugin

skillhub.cn 是獨立的社區插件目錄，與 DeepSeek、幻方沒有官方從屬關係。