g-ai-robot3

g-ai-robot3

内部数字人对话组件，基于 Vue 3，封装了文本问答、语音交互、数字人视频播放和工作流回调能力。

包说明

• 这是内部业务 npm 包，默认会随包发布内部接口地址、默认 bot_id、默认代理前缀和默认 WS 地址。
• 这些默认值已经集中到 packages/internal-defaults.ts 统一管理。
• 组件仍然保留原有覆盖能力。业务方可以通过 props 覆盖 apiPrefix、REST 地址、WS 地址和数字人接口地址。

安装

npm install g-ai-robot3

本包要求宿主项目使用 Vue 3。

快速开始

<script setup lang="ts">
import GAiRobot3 from "g-ai-robot3";
import "g-ai-robot3/style.css";
</script>

<template>
  <GAiRobot3
    :cozeInfo="{ bot_id: '7429224296222097443' }"
    apiPrefix="/api21216"
  />
</template>

Vite 项目额外配置

本组件包含图片等静态资源，Vite 项目需要引入配套插件以确保资源路径正确：

// vite.config.ts
import gAiRobot from "g-ai-robot3/vite-plugin";

export default defineConfig({
  plugins: [
    vue(),
    gAiRobot(), // 确保图片等静态资源路径正确
  ],
});

该插件会将 g-ai-robot3 排除出 Vite 依赖预构建，同时保留其子依赖的预构建，避免 CJS/ESM 兼容问题。

全局默认配置

组件插件支持通过 install 参数设置全局默认值，实例 props 优先级更高：

import { createApp } from "vue";
import GAiRobot3 from "g-ai-robot3";

createApp(App).use(GAiRobot3, {
  defaults: {
    showDigitalHuman: false,
    useAudio: false,
    dialogStyle: { right: "24px", bottom: "24px", left: "auto" },
  },
});

仓库内示例

• 当前仓库直接使用 examples/App.vue 作为示例页面。
• 页面入口在 index.html 和 examples/main.ts。
• 本地联调时在仓库根目录运行 npm run dev 即可。

Vite 代理示例

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      "/api21216": {
        target: "https://model.keepsoft.net:39002",
        changeOrigin: true,
        secure: false,
        rewrite: (path) => path.replace(/^\/api21216/, ""),
      },
    },
  },
});

常用 Props

必填参数（Required）

参数	说明	类型	默认值	注意事项
cozeInfo	智能体配置	object	{ bot_id: "..." }	bot_id 必须替换为实际的智能体 id
apiPrefix	API 基础路径	string	"/api21216"	必须配置为你的代理前缀（如 /api21216），可通过本地代理或环境变量覆盖

基础配置

参数	说明	类型	默认值
isDebug	是否开启调试模式（打印语音输出）	boolean	false
dialogBoxTheme	对话框主题	string	"light"
suspensionStyle	对话框高度	CSSProperties	{ maxHeight: "33vh" }
showMsgBubble	是否显示消息气泡	boolean	true
isExhibitionPro	是否为数字展厅项目	boolean	false
isShowDialogIcon	是否显示对话框图标	boolean	false
stream	是否启用流式传输（已废弃）	string	"True"
title	对话框标题	string	"GR水利大模型"
greet	欢迎语（文本对话框）	string	"您好,我是GR水利大模型智能小助手..."
welcomeMessage	欢迎消息（气泡对话框）	string	"您好,我是GR水利大模型智能小助手..."
waitTxt	等待提示文本	string	"贵仁科技AI正在生成回答"
systemName	系统标识	string	"g-ai-robot3"
placementBottom	对话框底部距离	number	100
placementLeft	对话框左侧距离	number	450
showFollowUpQuestions	是否显示关联问题	boolean	true
useAudio	是否启用语音识别、音频播放和数字人语音	boolean	true
showDigitalHuman	是否显示数字人；关闭后仅保留对话框	boolean	true
dialogClass	对话框根节点自定义 class	string | string[] | Record<string, boolean>	-
dialogStyle	对话框根节点自定义样式，覆盖默认定位	CSSProperties	-
space	监听间隔（ms）（已废弃）	number	3000
mode	交互模式（默认 video，其他已废弃）	string	"video"
modelType	模型类型（local 或 online）	string	"online"
showModelTypeToggle	显示模型类型切换开关	boolean	false
driverMode	AI 结果驱动模式	string	"workflow"
data	agent 模式下随消息透传给后端的动态上下文	Record<string, any>	{}

API 配置

参数	说明	类型	默认值
apiPrefix	API 基础路径（可自定义跨域）	string	"/api21216"
createConversationUrl	创建会话接口	string	${apiPrefix}/chatGlm/createConversation
wakeupAudio	音频打标接口	string	${apiPrefix}/asr/saveWakeUpAudio
interrupt	中断请求接口	string	${apiPrefix}/chatGlm/cancelChat
qaServer	问答服务接口	string	${apiPrefix}/chatGlm/searchTextNew
offer	数字人形象接口	string	${apiPrefix}/metahuman/offer
humanaudio	数字人音频接口	string	${apiPrefix}/metahuman/humanaudio
stop_audio	停止音频接口	string	${apiPrefix}/metahuman/stop_audio
textDriven	文本驱动接口	string	${apiPrefix}/intelligentVoice/tts
audioWs	语音 WebSocket 服务	string	wss://model.keepsoft.net:39002/funasrWs
voiceprintWs	声纹识别 WebSocket 服务	string	wss://model.keepsoft.net:39002/speakerWs
instructWs	指令 WebSocket 服务（已废弃）	string	wss://model.keepsoft.net:39002/commandWs

数字人配置

参数	说明	类型	默认值	注意事项
videoStyle	视频样式	CSSProperties	{ width: "180px", opacity: "0", pointerEvents: "none" }	建议 width 与 canvasWidth 一致
digitalStyle	数字人样式	CSSProperties	{ width: "180px", height: "180px" }	与 canvasWidth / canvasHeight 保持一致
canvasStyle	画布样式	CSSProperties	{ width: "180px", height: "180px" }	与 canvasWidth / canvasHeight 保持一致
bubbleStyle	气泡样式	CSSProperties	{ width: "30%", height: "30%" }	-
canvasWidth	画布宽度	number	180	建议与 videoStyle.width、digitalStyle.width 一致
canvasHeight	画布高度	number	180	建议与 digitalStyle.height 一致
canvasCartoonWidth	卡通形象宽度	number	200	-
canvasCartoonHeight	卡通形象高度	number	320	-

消息气泡配置

参数	说明	类型	默认值
showMsgNumber	显示消息数量	number	5
bubbleTheme	气泡主题	string	"dark"
useCustomDialog	是否使用自定义对话框	boolean	false
BubbleWidth	气泡容器样式	CSSProperties	{ width: "220px", bottom: "85%" }
BubbleBottom	气泡底部距离	number	85
initialQuestion	外部传入的首条问题（仅展示不请求接口）	string	-
streamChunks	外部传入的单条流式消息块	StreamChunk[]	[]
conversations	外部传入的多轮对话展示数据	ConversationInput[]	[]

对话框外部控制

通过组件 ref 可由宿主按钮直接控制对话框：

<script setup lang="ts">
import { ref } from "vue";
import GAiRobot3 from "g-ai-robot3";

const robotRef = ref<InstanceType<typeof GAiRobot3>>();
</script>

<template>
  <button @click="robotRef?.showDialog()">打开对话框</button>
  <button @click="robotRef?.hideDialog()">关闭对话框</button>
  <GAiRobot3
    ref="robotRef"
    :show-digital-human="false"
    :use-audio="false"
    :dialog-style="{ right: '24px', bottom: '24px', left: 'auto' }"
  />
</template>

showDialog() 是幂等操作，重复调用不会清空当前对话；toggleDialog() 可用于单个切换按钮。dialogStyle 支持直接传入 left/right/top/bottom/position/transform 等 CSS 定位属性，dialogClass 可用于覆盖尺寸和视觉样式。

类型导出

本包会导出常用类型，内部项目可以直接引用：

import type { ConversationInput, IndexProps, StreamChunk } from "g-ai-robot3";

工作流事件示例

const eventFun = [
  {
    keywords: ["scene1_fuyangWeather"],
    trigger: "before",
    fun: (params: Record<string, any>) => {
      console.log("scene1_fuyangWeather", params);
    },
  },
  {
    keywords: ["scene2"],
    trigger: "after",
    fun: (params: Record<string, any>) => {
      console.log("scene2", params);
    },
  },
];

Agent 输出驱动模式

driverMode 默认为 workflow，老项目不需要改动。切换到 agent 后：

• 忽略 eventFun
• 不做关键词匹配
• 每次 AI 返回 data 时直接触发 agent-response
• 由业务层自行决定如何处理返回 JSON
• 发送请求时 searchText 会升级为 JSON.stringify({ msg, data }) 后的字符串；msg 为用户输入或补问组装文本，data 为外部传入的最新 data prop

<script setup lang="ts">
import { ref } from "vue";

const agentContext = ref({
  anything: "from parent",
});

const handleAgentResponse = (params: any) => {
  console.log("agent response", params);
};
</script>

<template>
  <GAiRobot3
    mode="video"
    driverMode="agent"
    :data="agentContext"
    @agent-response="handleAgentResponse"
  />
</template>

业务侧可以直接拿到类似下面的结构：

function handleAgentResponse(params: any) {
  // {
  //   reply,
  //   targetState,
  //   commands
  // }
  applyAgentResponse(params);
}

workflow 模式继续保持旧请求结构，不启用 { msg, data } 和补问组装，老项目不需要调整后端接口。

注意事项

• 这是浏览器组件，不适用于 SSR 直接渲染。
• 如果需要覆盖默认内部地址，优先通过 props 覆盖，不要直接改 dist 产物。
• stream、space、instructWs 等旧字段仍保留兼容，但不建议新增使用。
• 视频和动图资源体积较大，当前库产物会偏重，内部接入时建议通过缓存策略降低重复下载成本。

许可证

本项目遵循仓库内的 LICENSE。