Digital Human SDK

嵌入第三方 Web 页面中的数字人客户端，当前用于验证 MVP 接入链路。

本地运行

本工程需要先切换到 Node 20：

nvm use 20

然后启动 Vite：

npm run dev

默认开发地址：

http://localhost:5173

安装

npm install @yujiezou/digital-human-sdk

国内用户建议设置镜像：

npm config set registry https://registry.npmmirror.com/

使用

Vue 3 / Vite 项目

import { init } from '@yujiezou/digital-human-sdk'
import '@yujiezou/digital-human-sdk/styles'

const dh = init({
  apiBaseUrl: 'http://localhost:8080',
  avatarCode: 'boy',
  position: 'right-bottom',
  width: 280,
  voice: true
})

Vue 2 / Webpack 项目

Vue 3 已打包在 SDK 内部，不会和宿主项目的 Vue 2 冲突。安装后在组件中直接使用：

<template>
  <div class="page">
    <!-- 数字人挂载容器，设置 position: relative 确保绝对定位正确 -->
    <div ref="dhContainer" style="position: relative; min-height: 200px;"></div>
  </div>
</template>

<script>
import { init } from '@yujiezou/digital-human-sdk'
import '@yujiezou/digital-human-sdk/dist/digital-human-sdk.css'

export default {
  data() {
    return {
      dh: null
    }
  },
  mounted() {
    this.dh = init({
      apiBaseUrl: 'http://10.17.6.249:18081',
      avatarCode: 'zouyj',
      container: this.$refs.dhContainer
    })
  },
  beforeDestroy() {
    this.dh?.destroy()
  }
}
</script>

注意：Vue CLI 4 Webpack 4 不支持 exports 快捷路径，样式需用完整文件路径 dist/digital-human-sdk.css 引入。

纯 HTML

<script src="./node_modules/@yujiezou/digital-human-sdk/dist/digital-human-sdk.umd.js"></script>
<link rel="stylesheet" href="./node_modules/@yujiezou/digital-human-sdk/dist/digital-human-sdk.css">

<script>
  const dh = DigitalHuman.init({
    apiBaseUrl: 'http://localhost:8080',
    avatarCode: 'boy'
  })
</script>

外部页面接入测试

项目根目录下的 test/ 是本地第三方 Web 测试工程，用于模拟和 SDK 项目无关的外部页面。

建议启动顺序：

cd sdk
nvm use 20
npm run dev

另开终端：

cd test
nvm use 20
npm run dev

在 test/ 或任意本地 Web 页面中临时引入 SDK：

<script type="module">
  import { init } from 'http://localhost:5173/src/sdk.ts'

  const digitalHuman = init({
    appKey: 'demo-app',
    apiBaseUrl: 'http://localhost:8080',
    avatarCode: 'boy',
    position: 'right-bottom',
    width: 280,
    chatMode: 'knowledge',
    voice: true
  })

  window.digitalHuman = digitalHuman
</script>

控制台可测试：

digitalHuman.say('这是一条外部页面主动发送的消息')
digitalHuman.playAction('thinking')
digitalHuman.startVoiceInput()
digitalHuman.destroy()

未传入 asrAdapter、ttsAdapter、chatAdapter 时，SDK 会默认通过 apiBaseUrl + avatarCode 调用后台 openapi 链路：

GET  /openapi/digital/avatar/{avatarCode}/manifest
GET  /openapi/digital/avatar/{avatarCode}/runtime-config
POST /openapi/digital/avatar/{avatarCode}/asr
POST /openapi/digital/avatar/{avatarCode}/chat
POST /openapi/digital/avatar/{avatarCode}/tts

SDK 使用后台 manifest 中的对话动作编排切换 idle、listening、 thinking、talking 阶段。ASR、TTS 和问答服务由后端根据数字人绑定关系代理调用，第三方页面不需要暴露 providerId 或第三方服务密钥。

点击“语音对话”后，SDK 会读取 runtime-config.wakeword 并进入“等待唤醒”状态。待唤醒期间数字人保持 idle 动作，不会直接播放收听动画；检测到绑定唤醒词后，会先播报“在呢，有什么能帮您”，再进入 ASR 收听。SDK 以“已绑定唤醒词且存在 wsUrl”作为尝试连接条件，serviceStatus 只作为后台状态提示；如果 WebSocket 无法连接，SDK 会提示配置或服务异常，不会绕过唤醒词直接收听。

语音 ASR 文本会先经过 SDK 内置控制命令判断。当前支持“退下”类指令，例如“退下”“退下吧”“你退下”“可以退下了”。命中后 SDK 不再调用问答接口，而是播报“好的，我退下啦”，播报期间不启动打断或继续收音，播报结束后回到等待唤醒状态。

点击数字人后会弹出操作菜单。点击“设置”可打开设置弹窗，运行时调整数字人宽高、问答模式和背景模式；切换到“状态”标签页可查看 TTS、ASR、唤醒词、知识库、问数、智能模式和动作编排的当前配置状态：

| 模式 | 值 | 说明 | | --- | --- | --- | | 知识库问答 | knowledge | 默认模式，调用当前数字人绑定的知识库问答 | | 问数模式 | thinking | 调用后端问数运行时 | | 智能模式 | smart | 由后端先判断问题走问数还是知识库问答 |

也可以在初始化时通过 chatMode 指定默认模式。用户在设置弹窗中修改的宽高、问答模式和背景模式会按 appKey + avatarCode/avatarId 保存到 localStorage，刷新页面后自动恢复。背景模式开启后，SDK 会在数字人背后显示白色卡片，用于蓝色或复杂大屏背景下提升数字人的可见性。

如果未提供 apiBaseUrl + avatarCode，也未提供对应 adapter，SDK 会退回本地 mock 回复。mock fallback 只适合本地演示，不代表真实接入完成。

更完整的 Vue、React、Next.js、普通 HTML 接入方案见：

../docs/sdk-integration.md

当前 MVP 能力

• 右下角悬浮数字人。
• 点击数字人展开操作菜单，支持聊天、语音对话、设置和动作测试。
• 输入文本后默认调用后台 /chat，无后台配置时才返回本地 mock 回复。
• 支持在设置弹窗中调整数字人大小和问答模式。
• 支持通过后台 manifest 播放数字人动作资源。
• 支持 idle、listening、thinking、talking 对话阶段动作编排。
• 支持通过 init() 动态挂载到第三方页面。