数字人「小慧」项目文档

外观

前端项目结构 ​

适用项目：bigscreen（大塔智慧管廊可视化大屏，Vue3 + Vite6）

本节只聚焦与数字人「小慧」相关的文件，列出清单并着重标注「哪些需要引入 / 哪些必须配置」。

一、bigscreen 数字人相关目录树 ​

text
bigscreen/
├── package.json              # ⚠️ 须含 @epicgames-ps/lib-pixelstreamingfrontend-ue5.4
├── .env.*                    # ⚠️ 须配 VITE_AI_APP_HOST / VITE_APP_AVATAR_URL / VITE_APP_UE_SIGNALLING_URL
├── vite.config.js            # ⚠️ /dhman-api 代理 → VITE_AI_APP_HOST
├── src/
│   ├── api/
│   │   ├── ai/               # 智能交互 / 专家问答 流式接口
│   │   ├── construct/ device/ emergency/ gallery/ hazard/
│   │   ├── inspection/ pipeLine/ roam/ system/ login.js
│   ├── components/
│   │   └── vis-assistant/     # 数字人对话核心
│   │       ├── VisAssistant.vue        # UI 装配层（面板 / 数字人 / 气泡 / 停止播报）
│   │       ├── useAssistantCore.js     # 会话组装层（组合根，约 410 行）
│   │       ├── core/                   # 会话各职责模块（拆分自 useAssistantCore.js，见第三节）
│   │       │   ├── state.js            # 响应式状态 + 开关持久化
│   │       │   ├── session.js          # 跨模块共享的可变会话状态（S）
│   │       │   ├── duplex.js           # 双工节流投喂的共享状态与常量（DS）
│   │       │   ├── messages.js         # 消息列表与「AI 回答中」状态
│   │       │   ├── speech.js           # TTS 播放编排（整段序列 / 增量队列 / 取消）
│   │       │   ├── aiChatStream.js     # 智能交互 SSE + 边收边播 + 双工投喂
│   │       │   ├── expertChat.js       # 专家问答 SSE 事件解析
│   │       │   ├── clientTools.js      # clientTools 执行 + 流式消息固化
│   │       │   ├── demoTour.js         # 系统导览（分段播报 / 打字机 / 预取 / 预投喂）
│   │       │   ├── connection.js       # WebSocket / 心跳重连 / 配对 / 移动端指令
│   │       │   └── config.js ttsText.js thinkFilter.js sseParse.js utils.js
│   │       ├── data/demoQA.js # 内置演示脚本
│   │       ├── utils/
│   │       │   ├── ueSound.js  # ⚠️ UE 音频驱动核心
│   │       │   ├── uePcm.js    # ⚠️ PCM 重采样
│   │       │   ├── audio.js    # TTS / 播放
│   │       │   └── sse.js      # SSE 解析
│   │       ├── components/ styles/
│   │       └── Avatar/Core/    # 数字人形象：UE 自集成（当前）；GLB/iframe 已废弃仅兜底
│   ├── composables/
│   │   └── mobile/            # ⚠️ 配对 / 遥控 composable
│   └── views/
│       ├── mobile/            # ⚠️ 手机 H5 遥控器
│       └── home/index.vue     # ⚠️ 注入 clientTools、挂载 VisAssistant

各模块的详细功能、协议与踩坑，见「大屏模块 / 移动端模块 / UE 模块 / 接口概览 / 亮点功能」。

二、数字人相关文件清单 ​

文件 / 目录作用必须引入 / 必须配置
package.json前端依赖清单⚠️ 必须引入 @epicgames-ps/lib-pixelstreamingfrontend-ue5.4（当前 ^1.1.6）。包名里的 UE 版本须与推流端 UE 版本一致（-ue5.4）。数字人语音/Markdown 相关还依赖：
fuse.js
marked
dompurify
qrcode
.env.development / .env.production / .env.staging / .env.test环境变量⚠️ 必须配置：VITE_AI_APP_HOST（AI 服务地址，WebSocket 与 /dhman-api 代理据此拼接）、VITE_APP_AVATAR_URL（数字人地址）、启用 UE 时 VITE_APP_UE_SIGNALLING_URL（信令地址，如 ws://host:91）；另需 VITE_APP_AI_API（默认 /dhman-api）、VITE_APP_BASE_API（/dev-api，/ai/... 走此）
vite.config.jsVite 构建与 dev 代理⚠️ 必须保证 /dhman-api 代理目标为 http://${VITE_AI_APP_HOST}（与 .env 一致）；dev 端口 3482；生产/预发 base 为 /bigscreen/
src/api/ai各业务模块接口封装⚠️ 数字人核心接口在 src/api/ai/（智能交互 /ai/chat/stream、专家问答 /ai/orchestrate/chat/stream）；NLU / TTS / ASR / 配对等统一走 VITE_APP_AI_API（/dhman-api）前缀，注意不要改前缀
src/components/vis-assistant/数字人对话核心组件⚠️ 重点文件：VisAssistant.vue（UI 装配层）、useAssistantCore.js（会话组装层：注入依赖、拼装 core/ 各模块，见第三节）、core/（会话各职责模块：状态 / 消息 / 语音播报 / 流式会话 / 系统导览 / 连接配对）；utils/ueSound.js + utils/uePcm.js（UE 音频驱动核心，引入 UE 库后由 UePixelStreaming.vue 调用）、utils/audio.js（TTS/播放）、utils/sse.js（SSE 解析）；data/demoQA.js（内置演示脚本）；components/、styles/
src/composables/
mobile/
useSuggestedQuestions.js
处理AI数字人遥控器.md		组合式函数⚠️ composables/mobile/ 提供配对/遥控相关 composable（usePairing 等），遥控器逻辑依赖它
src/views/mobile/
MobileEntry.vue
RemotePanel.vue
ScanPair.vue
ChatInputBar.vue
MobileMessageItem.vue
mobile.css
AI数字人遥控器.md		手机 H5 遥控器⚠️ 须与 .env 中 VITE_MOBILE_URL（默认 {origin}{pathname}#/mobile）一致；ScanPair.vue 依赖 VITE_AI_APP_HOST 拼接 WebSocket
src/views/home/index.vue大屏首页⚠️ 必须在此注入 clientTools（合并 demoFuncs.js 的 funcList），并挂载 VisAssistant；数字人导览动作（switchGallery / look*Dialog 等）已收敛到 src/assistant/ 能力注册表（如 system.switchModule），demoBus 仅承载系统级广播（demo-interrupt）与地图事件（open-pipe-list / hideWindows）

三、会话核心 core/（useAssistantCore.js 的拆分） ​

原 useAssistantCore.js 单文件约 3100 行，已按职责拆分为「组装层 + core/ 模块」：

  • useAssistantCore.js（约 410 行）：只做组装 —— 解构入参、创建共享状态、按依赖顺序创建各模块、注入依赖、对外暴露 UI 需要的 API（state / sendMessage / setMode / generatePairingCode / stopBroadcast / stopGenerate / speakDemoSegments 等，对外接口未变）。
  • core/*.js：每个文件一个职责，模块头注释说明用途与依赖。
文件职责
core/config.js端点与常量（/ai/chat/stream、/ai/orchestrate/chat/stream、WS 心跳/重连/配对常量）、localStorage 初始值读取、专家问答请求体构造
core/state.js响应式状态定义 + 「音色 / 语音播报 / 实时合成」开关的持久化 watch（「流式播报」已固定开启、界面上不再提供开关，故不再持久化）
core/session.js跨模块共享的可变会话状态（S）：aiChatSessionId、stopGenerating、broadcastAborted、activeRequestAbort、段间预准备缓存等
core/duplex.js双工节流投喂的共享状态与常量（DS）：待投喂队列、泵定时器、已投喂预估时长、轮次号；DUPLEX_LEAD_SECONDS / DUPLEX_STALL_MS
core/messages.js消息列表与「AI 回答中」状态：addMessage / clearMessages / resetAnsweringState 等
core/speech.jsTTS 播放编排：playTTSSequence / speakText / speakLocalAudio、增量队列 enqueueAudio / runAudioQueue、取消与打断 cancelTTS / stopBroadcast
core/aiChatStream.js智能交互 SSE：事件过滤、30s 空闲看门狗、切句与边收边播、双工节流投喂、收尾冲洗与整段兜底
core/expertChat.js专家问答 SSE：handleSSEStream + Dify 事件解析（message / retrieval_status / search / message_end）
core/clientTools.jsclientTools 执行、工具结果回传（当前调用点注释）、引用卡片 Markdown、流式消息固化 finalizeStreamingMessage
core/demoTour.js系统导览：内置问答库匹配与多段播报、打字机、段内预取 / 段间预投喂、段结束动作、resetPreparedDuplex
core/connection.jsWebSocket 连接与心跳重连、wsSend、服务端消息分发、移动端指令 handleMobileCommand、配对码生成 / 踢出、导览回复逐段回推
core/ttsText.jsTTS 文本处理：cleanTextForTTS / splitTextForTTS / resolveStreamingCut / isExceptionAnswer
core/thinkFilter.js<think>…</think> 流式思考过程过滤
core/sseParse.jsparseLooseObject（宽松对象字符串解析）、deepFind（RuoYi 多层包装深查找）
core/utils.jssleep 等通用小工具

3.1 约定（改代码前先看） ​

  1. 跨模块可变状态只有两处：createSession()（S）与 createDuplexState()（DS）——原本是闭包 let，跨模块无法共享；其余状态都留在各自模块内（如 speech.js 的 TTS 令牌与增量队列、connection.js 的 WS 实例与心跳定时器）。
  2. 模块间调用走显式依赖注入：工厂函数接收同名依赖参数（如 enqueueAudio / addSystemMessage / playTTSSequence），模块内部调用点与拆分前一致；需要后建模块时用箭头包装延迟解析，避免初始化顺序问题。
  3. 新功能落点：纯文本/解析工具 → ttsText.js / sseParse.js；播报相关 → speech.js；智能交互流 → aiChatStream.js；导览 → demoTour.js；连接/配对/移动端 → connection.js。
  4. 对外 API 不变：VisAssistant.vue 只通过 useAssistantCore(config) 返回值访问，拆分未改动任何对外字段。

数字人「小慧」项目文档

管廊可视化大屏 · 数字人团队