前言¶

在 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