前言¶
在 DeepSeek Harness (dsh) Web GUI 中，聊天界面默認沒有頭像顯示。默認情況下，用戶只能看到消息氣泡，缺少視覺標識。對於習慣在會話中快速識別身份的開發者來說，這會增加閱讀負擔。dsh-chat-avatars 插件通過在用戶消息右側、AI 消息左側添加頭像，解決了這一問題。
插件定位¶
dsh-chat-avatars 是一個爲 DeepSeek Harness (dsh) Web GUI 提供頭像功能的插件。由維護者 BlackRasion 開發，當前版本 0.1.3，採用 MIT 許可證。插件通過本地瀏覽器存儲管理頭像與設置，不依賴遠程服務。
核心功能¶
用戶/AI 頭像顯示¶
默認在用戶消息右側、AI 消息左側顯示頭像。支持調整頭像尺寸（24–60px）、選擇圓形或圓角形狀、分別控制兩側頭像的顯示與隱藏。
全局默認 + 工作區覆蓋¶
支持設置全局默認頭像，同時可以爲每個工作區單獨覆蓋頭像。未設置工作區頭像時，會繼承全局默認值。
上傳前交互裁剪¶
上傳頭像時支持交互式裁剪。支持的圖片格式包括 PNG/JPEG/WebP，文件大小限制 2 MB。提供拖拽、縮放和鍵盤操作，預覽效果即爲最終輸出。靜態頭像輸出爲 256×256。
動圖頭像¶
支持 GIF/APNG/動圖 WebP（≤6 MB）。插件在本地解碼動圖，自適應採樣 8–96 幀，並烘焙爲雪碧圖，使用 CSS steps() 播放。開啓 prefers-reduced-motion 時會凍結首幀。
大圖預覽與更換¶
在聊天中單擊頭像，會打開居中大圖預覽。預覽界面中可以直接更換頭像。
拍一拍效果¶
雙擊頭像觸發純本地效果，包括行抖動、氣泡提示和 WebAudio 合成音效。效果不寫會話事件、不聯網、不通知對方。支持配置用戶側/AI 側的拍一拍文案組（最多 8 條），每次隨機選擇且避免連續重複。
數據管理¶
支持導出/導入 JSON 格式的設置與頭像數據。提供清除全部數據功能和清理未使用的工作區頭像功能。多標籤頁會自動同步數據。
安全降級¶
插件會檢測 dsh 版本是否在支持區間（>=0.2.1-rc.2 <0.3.0）以及宿主契約是否匹配。不匹配時會自動暫停並回退到原生界面，不阻斷 GUI 啓動。
安裝與啓用¶
方式 1：GitHub Release tarball（當前推薦）¶
- 打開 Releases 頁面，下載最新
.tgz文件（當前爲dsh-chat-avatars-0.1.3.tgz）。 - 在終端執行安裝命令（把路徑和 profile 換成你的實際值）：
dsh plugin --profile <profile> add /path/to/dsh-chat-avatars-0.1.3.tgz
例如 dsh 的 Web profile 常用 --profile web。
3. 刷新 dsh Web GUI；若未立即生效，重啓 dsh 後再打開。
安裝/啓用會寫入你的 dsh profile，屬於本機配置變更；請確認路徑與來源可信後再執行。
方式 2：npm（發佈準備中）¶
包名 dsh-chat-avatars。npm 發佈完成後可直接：
dsh plugin --profile <profile> add dsh-chat-avatars
當前請先使用上面的 tarball 方式。
使用方法¶
- 打開 設置 → 聊天頭像（Account menu → Settings → Chat avatars）。
- 在 Appearance 中啓用頭像、調整尺寸/形狀/顯示範圍。
- 在 Global defaults 中上傳全局默認頭像；需要時在 Workspace overrides 裏爲單個工作區覆蓋。
- 在聊天中：
- 單擊頭像 → 大圖預覽（可在預覽內更換頭像）；
- 雙擊頭像 → 拍一拍（氣泡 + 音效）；
- 連續雙擊會重新彈出氣泡（視覺冷卻 300ms）；音效 900ms 內只響一次。 - 動圖頭像支持 GIF/APNG/動圖 WebP；上傳後會按裁剪區域逐幀生成。開啓
prefers-reduced-motion時凍結首幀。
拍一拍的文案組（可添加多條，每次隨機）、音效開關與音量在設置頁 Interaction 卡片中配置。
升級與卸載¶
# 升級：下載新的 release tarball 後再次 add 即可；設置與頭像保留
dsh plugin --profile <profile> add /path/to/dsh-chat-avatars-<new>.tgz
# 卸載
dsh plugin --profile <profile> remove dsh-chat-avatars
兼容性與注意事項¶
- 需要 dsh 版本
>=0.2.1-rc.2 <0.3.0。超出範圍時插件會自動暫停並回退到原生界面。 - 零運行時依賴，不需要
npm install；不修改 dsh 源碼，不寫document.body、不寫會話事件、不聯網。 - 動圖播放依賴瀏覽器
ImageDecoder（需要http://127.0.0.1或 https 等安全上下文）；不可用時只拒絕動圖，靜態頭像仍可用。 - 窄屏（<520px）下頭像會按設計隱藏。
- 數據只保存在當前瀏覽器的
localStorage（key：dsh.chat-avatars.v1），不上傳、不聯網、不讀取消息正文。 - 卸載插件不會自動刪除 localStorage；如需徹底清理，請在設置頁使用「清除全部數據」，或在瀏覽器 DevTools 刪除對應 key。
適用場景¶
適合需要在 dsh Web GUI 中爲用戶和 AI 添加頭像標識的開發者。適合希望在工作區級別自定義頭像、使用動圖頭像、或需要本地化拍一拍效果的場景。
總結¶
dsh-chat-avatars 通過在聊天界面添加用戶/AI 頭像、支持全局默認與工作區覆蓋、交互式裁剪、動圖頭像、大圖預覽與拍一拍等功能，提升了 dsh Web GUI 的視覺體驗。插件採用零運行時依賴、純本地數據存儲的設計，數據安全可控。當前版本 0.1.3，支持 dsh 0.2.1-rc.2 至 0.3.0 之間的版本。
- 插件目錄頁：https://www.skillhub.cn/plugins/BlackRasion/dsh-chat-avatars
- GitHub 倉庫：https://github.com/BlackRasion/dsh-chat-avatars
