DeepSeek Harness 插件：自定義用戶名與頭像

前言¶

DeepSeek Harness（DSH）的左下角賬號區域顯示的是 DeepSeek 平臺賬號，只讀；未登錄時顯示通用的“更多”按鈕。這個位置無法反映你想要展示的內容。

dsh-user-profile 填補了這個空白：在本地存儲一個名字和頭像，疊加在同一控制上。賬號菜單（設置/反饋/登出）繼續正常工作，只有頭像和名字發生變化。

插件定位¶

插件名：dsh-user-profile
維護者：xbbkok
功能：在 DSH 中自定義本地顯示的名字與頭像，顯示在側邊欄賬號芯片中
分類：未在 README 中明確標註，僅用於本地顯示

核心能力¶

用戶名：最多 32 個字符，支持任意字符集；留空則使用平臺默認
頭像：支持 PNG/JPG/WebP，居中裁剪並縮放到 192×192，以 base64 形式存儲
實時預覽：在設置頁編輯時可以看到結果，保存後側邊欄立即更新
可逆重置：清除後恢復平臺身份
本地化：遵循 DSH 的語言設置（中文/英文）
本地存儲：不上傳或同步，數據位於 ~/.dsh/plugins-data/dsh-user-profile/profile.json

安裝與啓用¶

官方推薦通過 bundle 安裝：

dsh plugin --profile web add github:xbbkok/dsh-user-profile

在桌面應用上，使用 desktop 替代 web，然後重啓 DSH。

若從本地檢出安裝，需要在對應配置文件中添加 insert 條目，且路徑必須以 file:// 開頭：

- insert:
    - id: dsh-user-profile
      name: 'file:///C:/path/to/dsh-user-profile/lib/index.js'

桌面與 Web 的配置路徑：

構建類型	路徑
Desktop	`%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml`
Web	`%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`

典型用法¶

點擊側邊欄賬號芯片，打開 Settings（快捷鍵 Ctrl+Alt+,）。
在設置列表中找到 Profile。
設置名字，選擇圖片，點擊 Save。
需要恢復平臺身份時，點擊 Reset。

存儲位置與格式¶

%USERPROFILE%\.dsh\plugins-data\dsh-user-profile\profile.json

示例內容：

{
  "version": 1,
  "name": "Ada",
  "avatar": "data:image/png;base64,…",
  "updatedAt": "2026-10-20T02:14:44.183Z"
}

同一目錄下的 heartbeat.txt 會在每次插件掛載時被重寫，可用於檢查插件是否加載成功。

頭像以 192×192 的 base64 PNG 形式存儲（通常 10–40 KB），由瀏覽器裁剪壓縮，原始文件不會寫入磁盤。

API¶

插件在 DSH Web 服務器上註冊兩個端點（與 GUI 同源）：

方法	路徑	說明
GET	`/user-profile`	返回 `{ ok, profile, storagePath }`
POST	`/user-profile`	Body `{ name?, avatar? }`；未填字段保持原值；`avatar: null` 可清除頭像

驗證規則：
- 名字限制 32 個碼點，並移除控制字符
- 頭像僅接受 PNG/JPEG/WebP 的 data: URL，並有字節上限
- 寫入請求的 Origin 必須匹配本地主機，否則返回 403，防止跨站篡改

工作原理¶

插件採用“一包兩半”的架構，類似其他 DSH UI 插件：

lib/index.js（Host / Node）：管理 /user-profile 路由，負責驗證、原子寫入（臨時文件 + 重命名）、心跳。無第三方運行時依賴。
lib/client.js（瀏覽器）：通過 ctx.slots.register({ name: 'settings.section', id: 'profile', order: -30 }) 註冊設置頁，然後覆蓋賬號觸發器 button[data-signed-out] 上的頭像與名字。

設計選擇：
- 不 fork 其他包的組件。賬號按鈕屬於 dsh-client-ui-settings-account，直接修改容易在更新時失效。插件通過 DOM 裝飾實現：記錄每個原生子元素的 display，隱藏它們，插入自定義頭像與標籤；清除時恢復所有內容。使用 MutationObserver 在 React 重新渲染後重新應用，寫入操作冪等，防止觀察者遞歸觸發。
- 失敗在插件內部處理。缺失 Web 服務器、目錄不可寫或路由註冊失敗只會產生警告，不會破壞插件樹。
- 語言跟隨應用。通過 ctx.locale.register('user-profile', { zh, en }) 註冊字典，頁面讀取 ctx.locale.bind()，使用 DSH 自身語言設置。
- 無構建步驟。lib/*.js 爲可讀的 ESM，直接被客戶端模塊系統使用，無需打包或 postinstall。

兼容性¶

DSH 0.2.x（@deepseek-ai/dsh >= 0.1.2-rc.1），桌面與 Web 構建
使用 settings.section 插槽與賬號觸發器的 data-signed-out 屬性，自 0.1.x 起穩定
僅修改顯示內容，登錄、計費與模型調用不受影響

已知限制¶

修改的是顯示的資料，而非 DeepSeek 平臺賬號本身
資料存儲在單機，不跨設備同步
若 DSH 未來重命名 button[data-signed-out]，側邊欄覆蓋會靜默失效（設置頁仍然可用）
側邊欄覆蓋是對其他包組件的 DOM 裝飾，不是官方插槽

開發與測試¶

npm install   # 僅用於在無 GUI 環境運行瀏覽器端的 jsdom
npm test

測試覆蓋 19 項：Host 驗證、原子持久化、HTTP 處理（GET/POST/JSON 格式/過長名字/SVG 僞裝/跨站寫入/錯誤方法）、Bundle 加載、帶本地化標籤的插槽註冊、芯片覆蓋與完整恢復、摺疊側邊欄、觀察者穩定。

修改 lib/client.js 可在頁面中熱交換；修改 lib/index.js 需重啓 DSH 以重新導入。

卸載¶

從對應配置文件中移除 dsh-user-profile 行（或從 dsh.profile.bundles 中移除）。
刪除 %USERPROFILE%\.dsh\plugins-data\dsh-user-profile\ 目錄。
刷新 DSH。

許可證¶

生態背景¶

DSH 的理念是“一切皆插件”，社區目錄獨立於 DeepSeek 與幻方，不構成官方應用商店。該插件爲社區維護，使用前建議檢查源碼與許可證。