refactor(arch): harden runtime ownership and cleanup

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: LessUp

.trellis/tasks/05-21-adapter/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/05-21-adapter/implement.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/05-21-adapter/prd.md

@@ -0,0 +1,38 @@
+# PRD: 架构优化 — 消除透传层、集中Adapter定义、消除模块级状态
+
+## 背景
+
+通过架构分析发现以下摩擦点：
+
+1. **纯透传层** — `DigitalHumanViewer.tsx` 仅重新导出，无价值
+2. **Adapter分散** — 服务层 adapter 定义分散，难以看到完整依赖图
+3. **模块级状态** — `dialogueOrchestrator` 和 `visionService` 的模块级状态导致测试泄漏
+
+## 目标
+
+1. 删除 `DigitalHumanViewer.tsx` 透传层
+2. 集中所有 adapter 定义到 `src/core/adapters.ts`
+3. 消除模块级状态，改为类实例或 store 管理
+
+## 范围
+
+### In Scope
+
+- 删除透传文件并更新导入
+- 创建集中式 adapter 定义文件
+- 重构 dialogueOrchestrator 为类实例
+- 重构 visionService 为类实例
+
+### Out of Scope
+
+- ASRStateAdapter 拆分（工作量过大，单独任务）
+- 聊天流架构文档（低优先级）
+
+## 验收标准
+
+- [ ] 所有导入 DigitalHumanViewer 的地方已更新
+- [ ] 所有 adapter 定义集中在 `src/core/adapters.ts`
+- [ ] dialogueOrchestrator 无模块级状态
+- [ ] visionService 无模块级状态
+- [ ] 现有测试通过
+- [ ] 类型检查通过

.trellis/tasks/05-21-adapter/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "adapter",
+  "name": "adapter",
+  "title": "架构优化：消除透传层、集中Adapter定义、消除模块级状态",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "shane",
+  "assignee": "shane",
+  "createdAt": "2026-05-21",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}

changelog/2026-05-21-architecture-optimization.zh-CN.md

@@ -0,0 +1,67 @@
+# 架构优化：消除透传层、集中Adapter定义、消除模块级状态
+
+## 变更类型
+
+- refactor: 架构优化
+
+## 变更内容
+
+### 1. 删除透传层
+
+- 删除 `src/components/DigitalHumanViewer.tsx`（仅重新导出，无价值）
+- 更新所有导入路径直接使用 `@/components/viewer`
+
+### 2. 集中 Adapter 定义
+
+- 新建 `src/core/adapters.ts`，集中所有服务层与状态层的适配器接口和工厂函数
+- 更新 `createServices.ts` 使用集中式 adapters
+- 更新 `audioService.ts` 从 adapters.ts 导入接口
+- 更新 `DigitalHumanEngine.ts` 从 adapters.ts 导入接口
+
+### 3. 消除模块级状态
+
+- 重构 `dialogueOrchestrator.ts` 为 `DialogueOrchestrator` 类
+- 模块级状态改为类实例状态，避免测试间泄漏
+- 保留向后兼容的函数导出（标记为 deprecated）
+
+### 4. 收紧运行时所有权与清理
+
+- `ServicesProvider` 统一负责共享 `engine` / `tts` / `asr` 的释放
+- `useAdvancedDigitalHumanController` 不再在页面卸载时误销毁应用级单例服务
+- `useChatStream` 在卸载和会话切换时主动中止未完成的对话轮次，避免悬挂流式回调
+
+### 5. 修复状态透传与适配器安全性
+
+- `AdvancedDigitalHumanPage` 改为从 store 读取真实 `isMuted`，修复聊天流始终未静音的问题
+- `src/core/adapters.ts` 改为静态 ESM 导入，移除浏览器侧运行时 `require()` 调用
+- 新增回归测试覆盖 Provider 清理、控制器生命周期、聊天流卸载清理、静音状态透传
+
+## 影响范围
+
+- `src/components/DigitalHumanViewer.tsx`（已删除）
+- `src/pages/AdvancedDigitalHumanPage.tsx`
+- `src/pages/DigitalHumanPage.tsx`
+- `src/__tests__/digitalHuman.test.tsx`
+- `src/core/adapters.ts`（新增）
+- `src/core/createServices.ts`
+- `src/core/audio/audioService.ts`
+- `src/core/avatar/DigitalHumanEngine.ts`
+- `src/core/dialogue/dialogueOrchestrator.ts`
+- `src/core/ServicesProvider.tsx`
+- `src/hooks/useAdvancedDigitalHumanController.ts`
+- `src/hooks/useChatStream.ts`
+- `src/__tests__/AdvancedDigitalHumanPage.test.tsx`（新增）
+- `src/__tests__/ServicesProvider.test.tsx`（新增）
+- `src/__tests__/useAdvancedDigitalHumanController.test.tsx`
+- `src/__tests__/useChatStream.test.tsx`
+
+## 验证
+
+- ✅ TypeScript 类型检查通过
+- ✅ ESLint 检查通过
+- ✅ 168 个测试全部通过
+
+## 参考
+
+- 架构分析发现的问题：透传层、Adapter分散、模块级状态泄漏
+- 解决方案：删除透传、集中定义、类实例化

src/__tests__/AdvancedDigitalHumanPage.test.tsx

@@ -0,0 +1,85 @@
+import { render } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import AdvancedDigitalHumanPage from '@/pages/AdvancedDigitalHumanPage';
+import { useDigitalHumanStore } from '@/store/digitalHumanStore';
+
+const useChatStreamMock = vi.fn();
+
+vi.mock('@/components/viewer', () => ({
+  DigitalHumanViewer: () => <div data-testid="viewer" />,
+}));
+
+vi.mock('@/components/TopHUD', () => ({
+  default: () => <div data-testid="top-hud" />,
+}));
+
+vi.mock('@/components/SettingsDrawer', () => ({
+  default: () => <div data-testid="settings-drawer" />,
+}));
+
+vi.mock('@/components/ChatDock', () => ({
+  default: () => <div data-testid="chat-dock" />,
+}));
+
+vi.mock('@/hooks/useConnectionHealth', () => ({
+  useConnectionHealth: () => ({
+    reconnect: vi.fn(),
+  }),
+}));
+
+vi.mock('@/hooks/useAdvancedDigitalHumanController', () => ({
+  useAdvancedDigitalHumanController: () => ({
+    activeTab: 'basic',
+    autoRotate: false,
+    closeSettings: vi.fn(),
+    handleBehaviorChange: vi.fn(),
+    handleEmotionChange: vi.fn(),
+    handleExpressionChange: vi.fn(),
+    handleHeadMotion: vi.fn(),
+    handleModelLoad: vi.fn(),
+    handleNewSession: vi.fn(),
+    handlePlayPause: vi.fn(),
+    handleReset: vi.fn(),
+    handleToggleRecording: vi.fn(),
+    handleVoiceCommand: vi.fn(),
+    setActiveTab: vi.fn(),
+    showSettings: false,
+    toggleMute: vi.fn(),
+    toggleSettings: vi.fn(),
+    toggleAutoRotate: vi.fn(),
+    setConnectionStatus: vi.fn(),
+    setError: vi.fn(),
+    clearError: vi.fn(),
+    sessionId: 'session_test',
+  }),
+}));
+
+vi.mock('@/hooks/useChatStream', () => ({
+  useChatStream: (...args: unknown[]) => useChatStreamMock(...args),
+}));
+
+describe('AdvancedDigitalHumanPage', () => {
+  beforeEach(() => {
+    useChatStreamMock.mockReset();
+    useChatStreamMock.mockReturnValue({
+      chatInput: '',
+      setChatInput: vi.fn(),
+      isChatLoading: false,
+      handleChatSend: vi.fn(),
+    });
+
+    useDigitalHumanStore.setState({
+      isMuted: true,
+    });
+  });
+
+  it('passes the muted state from the store into useChatStream', () => {
+    render(<AdvancedDigitalHumanPage />);
+
+    expect(useChatStreamMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        isMuted: true,
+      }),
+    );
+  });
+});

src/__tests__/ServicesProvider.test.tsx

@@ -0,0 +1,47 @@
+import { render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const createServicesMock = vi.fn();
+const disposeMock = vi.fn();
+const resetMock = vi.fn();
+
+vi.mock('@/core/createServices', () => ({
+  createServices: () => createServicesMock(),
+}));
+
+describe('ServicesProvider', () => {
+  afterEach(() => {
+    createServicesMock.mockReset();
+    disposeMock.mockReset();
+    resetMock.mockReset();
+  });
+
+  it('disposes provider-owned services on unmount', async () => {
+    createServicesMock.mockReturnValue({
+      engine: {
+        dispose: disposeMock,
+      },
+      tts: {
+        dispose: disposeMock,
+      },
+      asr: {
+        dispose: disposeMock,
+      },
+      dialogue: {
+        reset: resetMock,
+      },
+    });
+
+    const { ServicesProvider } = await import('@/core/ServicesProvider');
+    const { unmount } = render(
+      <ServicesProvider>
+        <div>child</div>
+      </ServicesProvider>,
+    );
+
+    unmount();
+
+    expect(resetMock).toHaveBeenCalledTimes(1);
+    expect(disposeMock).toHaveBeenCalledTimes(3);
+  });
+});

src/__tests__/digitalHuman.test.tsx

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/react';
-import DigitalHumanViewer from '../components/DigitalHumanViewer';
+import { DigitalHumanViewer } from '../components/viewer';
 import ControlPanel from '../components/ControlPanel';
 import { useDigitalHumanStore } from '../store/digitalHumanStore';
 import { useChatSessionStore } from '../store/chatSessionStore';

src/__tests__/useAdvancedDigitalHumanController.test.tsx

@@ -242,11 +242,11 @@ describe('useAdvancedDigitalHumanController', () => {
     expect(useSystemStore.getState().error).toBeNull();
   });
 
-  it('disposes the avatar engine on unmount', () => {
+  it('does not dispose the avatar engine on unmount', () => {
     const { unmount } = renderHook(() => useAdvancedDigitalHumanController());
 
     unmount();
 
-    expect(mocks.digitalHumanDisposeMock).toHaveBeenCalledTimes(1);
+    expect(mocks.digitalHumanDisposeMock).not.toHaveBeenCalled();
   });
 });

src/__tests__/useChatStream.test.tsx

@@ -6,6 +6,7 @@ import { useChatSessionStore } from '../store/chatSessionStore';
 import { useSystemStore } from '../store/systemStore';
 
 const runDialogueTurnStreamMock = vi.fn();
+const abortPendingTurnMock = vi.fn();
 
 vi.mock('@/core/services', () => ({
   useTTS: () => ({ speak: vi.fn() }),
@@ -14,11 +15,13 @@ vi.mock('@/core/services', () => ({
 
 vi.mock('../core/dialogue/dialogueOrchestrator', () => ({
   runDialogueTurnStream: (...args: unknown[]) => runDialogueTurnStreamMock(...args),
+  abortPendingTurn: () => abortPendingTurnMock(),
 }));
 
 describe('useChatStream', () => {
   beforeEach(() => {
     runDialogueTurnStreamMock.mockReset();
+    abortPendingTurnMock.mockReset();
     useDigitalHumanStore.setState({
       currentBehavior: 'idle',
     });
@@ -109,4 +112,20 @@ describe('useChatStream', () => {
     expect(useSystemStore.getState().chatPerformance.firstTokenMs).toBeNull();
     expect(useSystemStore.getState().chatPerformance.responseCompleteMs).not.toBeNull();
   });
+
+  it('aborts the pending dialogue turn on unmount', () => {
+    const { unmount } = renderHook(() =>
+      useChatStream({
+        sessionId: 'session_test',
+        isMuted: false,
+        onConnectionChange: vi.fn(),
+        onClearError: vi.fn(),
+        onError: vi.fn(),
+      }),
+    );
+
+    unmount();
+
+    expect(abortPendingTurnMock).toHaveBeenCalledTimes(1);
+  });
 });