前言¶

在 DSH 上做智能體應用時，一般做法是把對話放在網頁聊天框裏。如果需求是「一個看得見的 AI 形象」，通常得自己搭前端、自己接模型接口，工程量不小。dsh-avatar 把這個事做成了插件：在 DSH 界面上常駐渲染一個 VRM 數字人，由大模型通過工具驅動表情和動作，並提供模型與動作素材管理頁。它只負責形象表現，不提供人格、記憶、字幕或語音功能。

插件由 sunqing975 維護，倉庫爲 sunqing975/dsh-avatar。下面介紹它的定位、安裝方式、素材管理和常見排查點。

這個插件解決什麼問題¶

DSH 的理念是把能力拆成插件。dsh-avatar 把「AI 數字人」這層單獨收進插件裏，宿主不用關心 VRM 渲染、動作隊列或上傳存儲。它做了三件事：把形象掛到界面右下角並支持拖動；把表情和動作調用暴露成工具（set_expression、play_motion），讓模型在對話中觸發；把模型和動作文件放在用戶數據目錄管理，導入後即刻生效。

它明確不做的事：不建人格設定，不做長期記憶，不生成字幕，不合成語音。如果需要這些，得另裝插件或自己實現。

核心能力¶

常駐浮層：數字人默認顯示在界面右下角，通過全局 shell.overlay 在各頁面與會話中保持可見。按住浮層可拖動，拖拽位置按人物實際顯示範圍限制，窗口縮放後重新計算邊界。

工具驅動：模型調用 set_expression 改變表情，可選表情來自當前模型的 blend shapes，5 秒後自動復位；調用 play_motion 播放動作，可選動作來自當前動作清單，一次性動作結束後回到待機。工具表情優先於待機素材中的同名表情通道。

循環待機：優先播放 idle_stand，其次使用 idle；素材缺失時使用程序化上半身待機。待機素材優先加載，其餘動作在後臺加載。

素材管理：從左側菜單「數字人」打開中央管理頁，可以導入 VRM 模型與 VRMA 動作、切換模型、刪除用戶導入的素材。內置資產不可刪除，導入的模型自動成爲當前模型。管理頁變更後浮層自動重載，工具參數同步更新，無需重啓，浮層拖拽位置保持不變。

前置條件：管理頁需要宿主提供 sidebar.panellist 和 main 插槽。左側菜單收窄時入口顯示爲圖標；若取消固定，可從「更多」菜單打開。

安裝與啓用¶

在已安裝 DSH 的環境中，選擇要使用的 profile 安裝：

dsh plugin --profile <你的profile名> add github:sunqing975/dsh-avatar

例如使用 web profile：

dsh plugin --profile web add github:sunqing975/dsh-avatar

裝完後重啓對應宿主，左側菜單會出現「數字人」入口。

首次安裝時，若 DSH 的供應鏈安全策略攔截 Git 源包的 prepare 構建腳本，會報錯 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED。確認來源後，把報錯提示的完整條目加入 ~/.dsh/profiles/<profile>/pnpm-workspace.yaml 的 allowBuilds，例如：

allowBuilds:
  dsh-avatar@https://codeload.github.com/sunqing975/dsh-avatar/tar.gz/<commit>: true

條目必須以實際報錯提示爲準，保存後重新執行相同的安裝命令，再重啓宿主。

本地開發安裝：先安裝依賴並構建，再鏈接到目標 profile：

dsh plugin --profile web add link:/path/to/dsh-avatar
dsh web --no-open

未全局安裝 DSH 時，可把 dsh 替換爲 npx @deepseek-ai/dsh。宿主正在運行則重啓後加載構建產物。

模型與動作素材¶

內置模型是 assets/models/nuomi.vrm。內置動作放在 assets/animations/，包括 idle_stand、idle、bow、elbow_punch、Praying、sitting_laughing 和 Body Block；待機素材的來源與許可見 assets/animations/ATTRIBUTION.md。

自定義素材推薦通過「數字人」管理頁導入。本地開發時也可以向 assets/animations/ 放入 .vrma 文件，重啓插件後加入動作清單。

兩個限制要留意：表情與動作的實際效果取決於模型提供的表情、骨骼和素材兼容性，並非導入即可用；上傳端點只檢查 GLB 魔數與文件大小（模型 128 MB、動作 64 MB），不保證所有素材均可播放。

用戶資產保存在數據目錄：

<dshHome>/dsh-avatar/
  models/        # 用戶導入的 VRM
  animations/    # 用戶導入的 VRMA
  state.json     # 當前模型名

<dshHome> 默認是 ~/.dsh，可用 DSH_HOME 覆蓋；測試或開發可用 DSH_AVATAR_DATA_DIR 指定獨立目錄。同名資產以用戶文件優先，刪除用戶文件後恢復使用內置資產。升級插件不會覆蓋導入的資產。

插件如何與宿主協作¶

Host 側註冊了一組 HTTP 端點，客戶端輪詢指令並渲染：

工具執行後寫入 Host 的 PoseHub，客戶端每 400 ms 輪詢 /dsh-avatar/pose，按序號轉發到內部事件總線。首次讀取只建立水位線，避免重放歷史動作。工具參數隨資產變化重新註冊；同一畫布用 AvatarController.reload() 重載資源，保留渲染器與浮層位置。待機默認鎖定胯部位移軌道，工具表情在動畫更新後重新應用，以減少位移漂移與表情通道覆蓋。

工程結構上，src/index.ts 是 Host 插件（HTTP 端點與工具熱更新），src/tools.ts 定義兩個工具，src/pose.ts 是指令隊列，src/assets-registry.ts 管資產合併、當前模型持久化與導入刪除，src/model-info.ts 解析 GLB blend shapes，src/config.ts 是配置 schema。客戶端部分在 src/client/，渲染用 three.js 與 @pixiv/three-vrm，動畫用 @pixiv/three-vrm-animation。

驗證與排查¶

開發命令：

npm install
npm run build          # esbuild 構建 host(lib/index.js) + client(lib/client.js)
npm run typecheck      # 雙 tsconfig 類型檢查
npm run verify:bridge  # 驗證工具指令橋、資產熱更新與客戶端註冊等行爲

verify:bridge 依賴構建產物：加載 lib/index.js 註冊路由與工具，啓動 HTTP 服務，並在最小 window 環境執行 lib/client.js。修改代碼後先構建再驗證。該腳本不替代瀏覽器中的 WebGL 渲染檢查。

若工具返回成功但數字人不響應，按下面順序查：

1. 打開 /dsh-avatar/pose，如果 404，多半是 Host 沒加載新版插件。
2. 在瀏覽器控制台看 window.__dshAvatarLog：baseline seq=N 表示已建立水位線，pose seq=N ... 表示已接收指令，controller:idle:... 與 controller:motions:loaded=n/N:ms=... 表示素材加載狀態。
3. 素材加載失敗時，先確認模型和動作兼容性，再檢查上傳日誌。

浮層、指令橋與管理頁分別註冊，故障相互隔離。管理頁通過 ctx.slots.inject 等待宿主插槽：在 sidebar.panellist 註冊入口，在 keyed slot main 以相同 id dsh-avatar 註冊中央正文。

後續計劃見 TODO.md，維護記錄見 AGENT.md。

適用場景與注意¶

適合需要給 DSH 應用加一個可視化形象、且形象表現要能被模型在對話中觸發的場合，例如演示界面、可視化助手。不適合需要人格、記憶、字幕、語音的場景，需要另外組合插件。

插件以當前 DSH 進程權限運行，上傳接口會落盤到用戶數據目錄。安裝前建議先檢查倉庫源碼與許可證（MIT），確認供應鏈安全策略（allowBuilds）配置符合自身環境。

小結¶

dsh-avatar 做了一件窄而具體的事：把 VRM 數字人的畫面、工具驅動和素材管理裝進 DSH 插件，不碰人格與語音。需要自己搭前端纔能有的可視化形象，現在可以裝插件後直接用。

目錄頁：https://www.skillhub.cn/plugins/sunqing975/dsh-avatar
GitHub：https://github.com/sunqing975/dsh-avatar