feat(avatar): 引入统一人物表现协议并重构相关模块

shijiashuai · shijiashuai · commit 4b37421e6b2b · 2026-03-13T14:03:14.000+08:00
新增 avatarPresentation.ts 作为统一表现协议层，集中定义表现状态与校验规则
重构 digitalHumanStore 复用协议类型，修正 setBehavior 不再意外覆盖动画
调整 DigitalHumanEngine 将表现入口收口至统一命令提交逻辑
更新 dialogueOrchestrator 与 audioService 优先通过引擎驱动表现状态
更新相关测试桩以覆盖新协议字段与完整行为集合
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh repo:*)",
+      "Bash(gh api:*)",
+      "Bash(python -c \"import json,re; p='/home/shane/.claude/projects/-home-shane-lessup-meta-human/c37b280f-e7b8-4089-954f-88436d3bd09a/tool-results/b0cdlho3r.txt'; data=json.load\\(open\\(p\\)\\); pats=re.compile\\(r'\\(live2d|vrm|avatar|character|portrait|model\\)',re.I\\); matches=[x['path'] for x in data['tree'] if pats.search\\(x['path']\\)]; print\\('\\\\n'.join\\(matches[:300]\\)\\)\")",
+      "Bash(python -c \"import json,re; p='/home/shane/.claude/projects/-home-shane-lessup-meta-human/c37b280f-e7b8-4089-954f-88436d3bd09a/tool-results/b0cdlho3r.txt'; data=json.load\\(open\\(p\\)\\); pats=re.compile\\(r'\\(frontend|web|app|components|widgets|store|state\\)',re.I\\); matches=[x['path'] for x in data['tree'] if pats.search\\(x['path']\\)]; print\\('\\\\n'.join\\(matches[:300]\\)\\)\")"
+    ]
+  }
+}
diff --git a/changelog/2026-03-13_avatar-presentation-protocol.md b/changelog/2026-03-13_avatar-presentation-protocol.md
@@ -0,0 +1,25 @@
+# Avatar Presentation Protocol 重构
+
+日期：2026-03-13
+
+## 变更内容
+
+- 新增 `src/core/avatar/avatarPresentation.ts` 作为统一人物表现协议层，集中定义 `AvatarPresentation`、`AvatarCommand`、表现状态、校验集合、行为/姿态/动作映射与动画时长。
+- 调整 `src/store/digitalHumanStore.ts`，改为复用统一协议类型与选择器，并修正 `setBehavior()` 不再意外覆盖当前动画。
+- 重构 `src/core/avatar/DigitalHumanEngine.ts`，将 emotion / expression / behavior / animation 的兼容入口收口到统一命令提交逻辑，保留既有 API，同时新增 `applyCommand()` 作为协议入口。
+- 调整 `src/core/dialogue/dialogueOrchestrator.ts` 与 `src/core/audio/audioService.ts`，优先通过 `digitalHumanEngine` 驱动说话、倾听、思考与预设动作，减少对 store 底层字段的直接竞争写入。
+- 更新相关测试桩与属性测试，覆盖新的协议依赖字段与更完整的行为集合。
+
+## 背景
+
+原有人物系统中，`emotion`、`expression`、`behavior`、`animation` 的语义边界重叠，页面、对话、语音和引擎都可能直接写 store，导致状态所有权分散、Cyber/VRM 难以共享统一输入模型。本次重构先引入稳定的中间表现协议，为后续 Stage Driver 分层和渲染适配打基础。
+
+## 验证
+
+- 使用 `./node_modules/.bin/tsc --noEmit` 通过类型检查。
+- 使用 `./node_modules/.bin/vitest run src/__tests__/store.test.ts src/__tests__/engine.test.ts src/__tests__/properties/engine.property.test.ts src/__tests__/properties/orchestrator.property.test.ts src/__tests__/properties/tts.property.test.ts src/__tests__/properties/asr.property.test.ts --silent`，共 82 项测试全部通过。
+- 使用 `./node_modules/.bin/vite build` 构建通过；仍有既存的 chunk size warning，但不阻塞产物生成。
+
+## 备注
+
+- 当前 `npm run build` / `npm run test:run` 在本环境下会因 `spawn pwsh ENOENT` 失败，因此本次改用本地二进制直接执行 `vite`、`tsc`、`vitest` 完成验证。
diff --git a/src/__tests__/properties/asr.property.test.ts b/src/__tests__/properties/asr.property.test.ts
@@ -14,11 +14,24 @@ vi.mock('../../store/digitalHumanStore', () => ({
         getState: vi.fn(() => ({
             setRecording: vi.fn(),
             setBehavior: vi.fn(),
+            setAnimation: vi.fn(),
+            setEmotion: vi.fn(),
+            setExpression: vi.fn(),
+            setPlaying: vi.fn(),
+            setExpressionIntensity: vi.fn(),
             addError: vi.fn(),
             setLoading: vi.fn(),
             addChatMessage: vi.fn(),
             sessionId: 'test-session',
             isMuted: false,
+            avatarType: 'cyber',
+            currentAnimation: 'idle',
+            currentBehavior: 'idle',
+            currentEmotion: 'neutral',
+            currentExpression: 'neutral',
+            expressionIntensity: 0.8,
+            isRecording: false,
+            isSpeaking: false,
         })),
     },
 }));
@@ -113,11 +126,24 @@ describe('ASR Service Properties', () => {
         (useDigitalHumanStore.getState as any).mockReturnValue({
             setRecording: vi.fn((val: boolean) => setRecordingCalls.push(val)),
             setBehavior: vi.fn(),
+            setAnimation: vi.fn(),
+            setEmotion: vi.fn(),
+            setExpression: vi.fn(),
+            setPlaying: vi.fn(),
+            setExpressionIntensity: vi.fn(),
             addError: vi.fn(),
             setLoading: vi.fn(),
             addChatMessage: vi.fn(),
             sessionId: 'test-session',
             isMuted: false,
+            avatarType: 'cyber',
+            currentAnimation: 'idle',
+            currentBehavior: 'idle',
+            currentEmotion: 'neutral',
+            currentExpression: 'neutral',
+            expressionIntensity: 0.8,
+            isRecording: false,
+            isSpeaking: false,
         });
 
         await fc.assert(
diff --git a/src/__tests__/properties/engine.property.test.ts b/src/__tests__/properties/engine.property.test.ts
@@ -240,7 +240,8 @@ describe('Digital Human Engine Properties', () => {
 
         const validBehaviors = [
             'idle', 'greeting', 'listening', 'thinking', 'speaking', 'excited',
-            'wave', 'greet', 'think', 'nod', 'shakeHead', 'dance', 'speak', 'waveHand', 'raiseHand'
+            'wave', 'greet', 'think', 'nod', 'shakeHead', 'dance', 'speak', 'waveHand', 'raiseHand',
+            'bow', 'clap', 'thumbsUp', 'headTilt', 'shrug', 'lookAround', 'cheer', 'sleep', 'crossArms', 'point'
         ];
 
         await fc.assert(
diff --git a/src/__tests__/properties/orchestrator.property.test.ts b/src/__tests__/properties/orchestrator.property.test.ts
@@ -22,8 +22,14 @@ vi.mock('../../store/digitalHumanStore', () => ({
             setEmotion: vi.fn((val: string) => {
                 stateChanges.push({ type: 'emotion', value: val, timestamp: Date.now() });
             }),
+            setAnimation: vi.fn(),
             currentEmotion: 'neutral',
             currentBehavior: 'idle',
+            currentAnimation: 'idle',
+            currentExpression: 'neutral',
+            expressionIntensity: 0.8,
+            avatarType: 'cyber',
+            isRecording: false,
             isSpeaking: false,
             isLoading: false,
         })),
@@ -40,6 +46,9 @@ vi.mock('../../core/avatar/DigitalHumanEngine', () => ({
         playAnimation: vi.fn((val: string) => {
             stateChanges.push({ type: 'engine-animation', value: val, timestamp: Date.now() });
         }),
+        setBehavior: vi.fn((val: string) => {
+            stateChanges.push({ type: 'engine-behavior', value: val, timestamp: Date.now() });
+        }),
     },
 }));
 
diff --git a/src/__tests__/properties/tts.property.test.ts b/src/__tests__/properties/tts.property.test.ts
@@ -14,7 +14,20 @@ vi.mock('../../store/digitalHumanStore', () => ({
         getState: vi.fn(() => ({
             setSpeaking: vi.fn(),
             setBehavior: vi.fn(),
+            setAnimation: vi.fn(),
+            setEmotion: vi.fn(),
+            setExpression: vi.fn(),
+            setPlaying: vi.fn(),
+            setExpressionIntensity: vi.fn(),
             addError: vi.fn(),
+            avatarType: 'cyber',
+            currentAnimation: 'idle',
+            currentBehavior: 'idle',
+            currentEmotion: 'neutral',
+            currentExpression: 'neutral',
+            expressionIntensity: 0.8,
+            isRecording: false,
+            isSpeaking: false,
         })),
     },
 }));
@@ -133,7 +146,20 @@ describe('TTS Service Properties', () => {
         (useDigitalHumanStore.getState as any).mockReturnValue({
             setSpeaking: mockSetSpeaking,
             setBehavior: vi.fn(),
+            setAnimation: vi.fn(),
+            setEmotion: vi.fn(),
+            setExpression: vi.fn(),
+            setPlaying: vi.fn(),
+            setExpressionIntensity: vi.fn(),
             addError: vi.fn(),
+            avatarType: 'cyber',
+            currentAnimation: 'idle',
+            currentBehavior: 'idle',
+            currentEmotion: 'neutral',
+            currentExpression: 'neutral',
+            expressionIntensity: 0.8,
+            isRecording: false,
+            isSpeaking: false,
         });
 
         await fc.assert(
diff --git a/src/__tests__/store.test.ts b/src/__tests__/store.test.ts
@@ -87,6 +87,13 @@ describe('digitalHumanStore — 行为', () => {
     expect(useDigitalHumanStore.getState().currentBehavior).toBe('greeting');
   });
 
+  it('setBehavior 不强制覆盖当前动画', () => {
+    const store = useDigitalHumanStore.getState();
+    store.setAnimation('wave');
+    store.setBehavior('greeting');
+    expect(useDigitalHumanStore.getState().currentAnimation).toBe('wave');
+  });
+
   it('setAnimation 更新动画', () => {
     useDigitalHumanStore.getState().setAnimation('wave');
     expect(useDigitalHumanStore.getState().currentAnimation).toBe('wave');
diff --git a/src/core/audio/audioService.ts b/src/core/audio/audioService.ts
@@ -1,4 +1,5 @@
 import { useDigitalHumanStore } from '../../store/digitalHumanStore';
+import { digitalHumanEngine } from '../avatar/DigitalHumanEngine';
 import { sendUserInput } from '../dialogue/dialogueService';
 import { handleDialogueResponse } from '../dialogue/dialogueOrchestrator';
 
@@ -108,7 +109,7 @@ export class TTSService {
     this.synth.cancel();
     this.isProcessingQueue = false;
     useDigitalHumanStore.getState().setSpeaking(false);
-    useDigitalHumanStore.getState().setBehavior('idle');
+    digitalHumanEngine.setBehavior('idle');
   }
 
   // 语音合成 - 支持队列
@@ -177,22 +178,22 @@ export class TTSService {
 
       utterance.onstart = () => {
         useDigitalHumanStore.getState().setSpeaking(true);
-        useDigitalHumanStore.getState().setBehavior('speaking');
+        digitalHumanEngine.setBehavior('speaking');
       };
 
       utterance.onend = () => {
         // 只有队列为空时才重置状态
         if (this.speechQueue.length === 0) {
           useDigitalHumanStore.getState().setSpeaking(false);
-          useDigitalHumanStore.getState().setBehavior('idle');
+          digitalHumanEngine.setBehavior('idle');
         }
         resolve();
       };
 
       utterance.onerror = (event) => {
         console.error('语音合成错误:', event);
         useDigitalHumanStore.getState().setSpeaking(false);
-        useDigitalHumanStore.getState().setBehavior('idle');
+        digitalHumanEngine.setBehavior('idle');
         useDigitalHumanStore.getState().addError(`语音合成失败: ${event.error}`);
         reject(new Error(event.error));
       };
@@ -355,7 +356,7 @@ export class ASRService {
 
     this.recognition.onstart = () => {
       this.isRunning = true;
-      useDigitalHumanStore.getState().setBehavior('listening');
+      digitalHumanEngine.setBehavior('listening');
       this.callbacks.onStart?.();
     };
 
@@ -450,7 +451,7 @@ export class ASRService {
     this.clearTimeout();
     this.isRunning = false;
     useDigitalHumanStore.getState().setRecording(false);
-    useDigitalHumanStore.getState().setBehavior('idle');
+    digitalHumanEngine.setBehavior('idle');
   }
 
   async start(options?: ASRStartOptions): Promise<boolean> {
@@ -523,7 +524,7 @@ export class ASRService {
     this.mode = 'command';
     this.isRunning = false;
     useDigitalHumanStore.getState().setRecording(false);
-    useDigitalHumanStore.getState().setBehavior('idle');
+    digitalHumanEngine.setBehavior('idle');
   }
 
   abort(): void {
@@ -604,7 +605,7 @@ export class ASRService {
     const store = useDigitalHumanStore.getState();
 
     store.setLoading(true);
-    store.setBehavior('thinking');
+    digitalHumanEngine.setBehavior('thinking');
     store.addChatMessage('user', text);
 
     try {
@@ -621,7 +622,7 @@ export class ASRService {
     } catch (error: unknown) {
       console.error('对话服务错误:', error);
       store.addError('对话服务暂时不可用，请稍后重试');
-      store.setBehavior('idle');
+      digitalHumanEngine.setBehavior('idle');
 
       // 本地降级回复
       const fallbackReply = '抱歉，我暂时无法处理您的请求，请稍后再试。';
@@ -636,75 +637,63 @@ export class ASRService {
 
   // 预设动作：打招呼
   performGreeting(): void {
-    const store = useDigitalHumanStore.getState();
-    store.setEmotion('happy');
-    store.setExpression('smile');
-    store.setBehavior('greeting');
-    store.setAnimation('wave');
+    digitalHumanEngine.setEmotion('happy');
+    digitalHumanEngine.setExpression('smile');
+    digitalHumanEngine.playAnimation('wave');
 
     this.tts.speak('您好！很高兴见到您！有什么可以帮助您的吗？');
 
     setTimeout(() => {
-      store.setEmotion('neutral');
-      store.setExpression('neutral');
-      store.setBehavior('idle');
-      store.setAnimation('idle');
+      digitalHumanEngine.setEmotion('neutral');
+      digitalHumanEngine.setExpression('neutral');
+      digitalHumanEngine.setBehavior('idle');
     }, 4000);
   }
 
   // 预设动作：跳舞
   performDance(): void {
-    const store = useDigitalHumanStore.getState();
-    store.setAnimation('dance');
-    store.setBehavior('excited');
-    store.setEmotion('happy');
+    digitalHumanEngine.setEmotion('happy');
+    digitalHumanEngine.playAnimation('dance');
 
     this.tts.speak('让我为您跳一支舞！');
 
     setTimeout(() => {
-      store.setAnimation('idle');
-      store.setBehavior('idle');
-      store.setEmotion('neutral');
+      digitalHumanEngine.setEmotion('neutral');
+      digitalHumanEngine.setBehavior('idle');
     }, 6000);
   }
 
   // 预设动作：点头
   performNod(): void {
-    const store = useDigitalHumanStore.getState();
-    store.setAnimation('nod');
-    store.setBehavior('listening');
+    digitalHumanEngine.playAnimation('nod');
 
     this.tts.speak('好的，我明白了。');
 
     setTimeout(() => {
-      store.setAnimation('idle');
-      store.setBehavior('idle');
+      digitalHumanEngine.setBehavior('idle');
     }, 2000);
   }
 
   // 预设动作：摇头
   performShakeHead(): void {
-    const store = useDigitalHumanStore.getState();
-    store.setAnimation('shakeHead');
+    digitalHumanEngine.playAnimation('shakeHead');
 
     this.tts.speak('不太确定呢。');
 
     setTimeout(() => {
-      store.setAnimation('idle');
+      digitalHumanEngine.setBehavior('idle');
     }, 2000);
   }
 
   // 预设动作：思考
   performThinking(): void {
-    const store = useDigitalHumanStore.getState();
-    store.setBehavior('thinking');
-    store.setAnimation('think');
+    digitalHumanEngine.setBehavior('thinking');
+    digitalHumanEngine.playAnimation('think');
 
     this.tts.speak('让我想想...');
 
     setTimeout(() => {
-      store.setBehavior('idle');
-      store.setAnimation('idle');
+      digitalHumanEngine.setBehavior('idle');
     }, 3000);
   }
 }
diff --git a/src/core/avatar/DigitalHumanEngine.ts b/src/core/avatar/DigitalHumanEngine.ts
diff --git a/src/core/avatar/avatarPresentation.ts b/src/core/avatar/avatarPresentation.ts
diff --git a/src/core/dialogue/dialogueOrchestrator.ts b/src/core/dialogue/dialogueOrchestrator.ts
diff --git a/src/store/digitalHumanStore.ts b/src/store/digitalHumanStore.ts
