hanzora

Hanzora 数字人 SDK，提供 Vue / React 组件接入与底层 RuntimeEngine 能力。

稳定性承诺

当前处于 0.x 预发布阶段，minor 版本之间可能包含破坏性变更。生产环境请在 package.json 中锁定具体 patch 版本（例如 "hanzora": "0.1.9"），不要使用 ^0.1.x。

1.0.0 起严格遵循 SemVer 2.0。每次发布的变更详情见 CHANGELOG.md。

包入口

| 入口 | 场景 | | --- | --- | | hanzora/vue | Vue 3 项目接入（推荐） | | hanzora/react | React 18+ 项目接入（推荐） | | hanzora | 底层能力接入（自定义渲染器 / 生命周期编排） |

安装

从 npm 安装：

pnpm add hanzora

离线包安装（先在 packages 目录执行 pnpm pack:local 生成 tgz）：

pnpm pack:local
pnpm add ./hanzora-<version>.tgz

配置方式

标准配置（推荐）

{
  baseUrl: string
  token: string
  avatarId?: string
  userId?: string
  chatBaseUrl?: string
  asrWsUrl?: string
  visible?: boolean
}

| 字段 | 必填 | 说明 | | --- | --- | --- | | baseUrl | 是 | 后端地址，可传 '' 走同源 | | token | 是 | 鉴权 token | | avatarId | 否 | Avatar 资源 ID，不传使用默认值 | | userId | 否 | 不传时 SDK 会生成并持久化匿名 userId | | chatBaseUrl | 否 | 对话服务地址，不传继承 baseUrl | | asrWsUrl | 否 | ASR WebSocket 地址 | | visible | 否 | 初始显隐，默认 true |

组件入口的语音延迟策略由 SDK 内部选择：组件模式默认使用更适合实时交互的时序，底层 classic / full config 保持安全默认，避免把 final 提交延迟、播报后静音等待和复听 guard 这类实现细节推给接入方。

服务端驱动配置（进阶）

{
  baseUrl: string
  agentId: string
  userId?: string
  visible?: boolean
  runtimeConfigPath?: string // 默认 /api/hanzora/runtime-config
}

Vue 3 接入

<script setup lang="ts">
import { ref } from 'vue'
import { Hanzora, type HanzoraHandle } from 'hanzora/vue'

const hanzoraRef = ref<HanzoraHandle | null>(null)

const config = {
  baseUrl: 'https://your-avatar-service',
  token: 'your-token',
  userId: 'user-001',
  chatBaseUrl: 'https://your-chat-service',
  asrWsUrl: 'wss://your-asr-service/ws/asr',
}

async function onAction(
  action: { action: string; payload?: Record<string, unknown> },
  done: (result: { success: boolean; message?: string; data?: unknown }) => void,
) {
  const { action: type, payload = {} } = action

  switch (type) {
    case 'avatar.hide':
      hanzoraRef.value?.hide()
      done({ success: true })
      break
    case 'avatar.show':
      hanzoraRef.value?.show()
      done({ success: true })
      break
    default:
      done({ success: false, message: `未处理的 action: ${type}` })
  }
}
</script>

<template>
  <Hanzora ref="hanzoraRef" :config="config" debug @action="onAction" />
</template>

说明：debug 面板当前仅 Vue 组件支持。

React 接入

import { useRef } from 'react'
import { Hanzora, type HanzoraHandle } from 'hanzora/react'

export function AvatarPanel() {
  const ref = useRef<HanzoraHandle>(null)

  return (
    <>
      <Hanzora
        ref={ref}
        config={{
          baseUrl: 'https://your-avatar-service',
          token: 'your-token',
          userId: 'user-001',
          chatBaseUrl: 'https://your-chat-service',
          asrWsUrl: 'wss://your-asr-service/ws/asr',
        }}
        onAction={async (action, done) => {
          const { action: type } = action as {
            action: string
            payload?: Record<string, unknown>
          }

          switch (type) {
            case 'avatar.hide':
              ref.current?.hide()
              done({ success: true })
              break
            default:
              done({ success: false, message: `未处理的 action: ${type}` })
          }
        }}
      />
    </>
  )
}

组件通用能力

| 能力 | Vue | React | | --- | --- | --- | | 状态回调 | @stateChange | onStateChange | | action 回调 | @action | onAction | | 错误回调 | @error | onError | | 原始消息回调 | @message | onMessage | | 重连通知 | @reconnect | onReconnect | | 文本提交通知 | @textSubmit | onTextSubmit | | 调试面板 | debug | 不支持 |

实例方法：

• start(options?) / stop()
• sendText(text) / interrupt()
• startMic() / stopMic()
• registerAction(type, handler)
• patchAsr({ wakeWord })
• getState() / getDiagnostics()
• show() / hide() / setVisible(v) / getVisible()

说明：旧的 setLiveTranscript() / clearLiveTranscript() 占位方法已移除；组件转写展示改为完全由运行时消息驱动。

默认行为

• 组件挂载后默认自动启动。
• 启动门控默认开启（requireUserGesture = true），用于满足浏览器音频策略。
• 初始显隐通过 visible 字段控制（默认 true）。
• userId 不传时，SDK 会自动生成并持久化匿名 ID。
• show / hide 只影响 UI 显隐，不会中断已建立会话。
• Vue / React 组件固定渲染为 body overlay；组件所在挂载节点只作为生命周期锚点，不承诺在该 DOM 容器内内嵌渲染。

如果你需要真正的 container mount，请改用 hanzora 根入口的低层 API，例如：

import { createHanzoraRuntime, defineHanzoraConfig } from 'hanzora'

const container = document.getElementById('avatar-slot')
if (!container) throw new Error('avatar-slot not found')

const runtime = createHanzoraRuntime({
  config: defineHanzoraConfig({
    baseUrl: 'https://your-avatar-service',
    token: 'your-token',
  }),
  mountTarget: 'container',
  presentation: () => ({}),
  callbacks: {},
})

await runtime.mount(container)

常见排查

1. 页面无声音或无法自动播报：检查是否已完成用户手势触发（点击启动门控）。
2. agentId 模式初始化失败：检查 runtime-config 接口是否可达。
3. 语音识别不生效：检查 asrWsUrl（标准配置）或服务端 runtime-config 返回的 ASR 配置（服务端驱动配置）。
4. action 未落地：确认 onAction/@action 中已调用 done(...)。

文档

• docs/sdk-integration-guide.md —— 接入端到端流程
• docs/map-control-actions.md —— 地图集成 action 命名约定
• docs/voice-interaction-cohesion.md —— 语音交互模块边界
• docs/browser-kws-architecture.md —— 浏览器端 KWS 架构