feat: 初始化前端项目，搭建 React + TypeScript + Vite 工程结构

- 创建 Vite + React 18 + TypeScript 项目（严格模式）
- 安装 @ricky0123/vad-web、onnxruntime-web、uuid 依赖
- 定义全部 WebSocket 消息类型和数据模型（对齐接口文档）
- 实现 WebSocket 连接管理（心跳保活、指数退避重连）
- 实现音频编码工具（PCM↔Base64、DataURL 转换）
- 创建组件骨架：CameraManager、MicManager、EdgeProcessor、WebSocketManager、ChatPanel、VideoPreview
- 实现核心 useVisionSession Hook 骨架
- 配置 ESLint（_前缀变量忽略规则）

Co-Authored-By: Claude <noreply@anthropic.com>

frontend/src/App.css

@@ -0,0 +1,241 @@
+/* ============================================================
+   CamTalk — 主应用样式
+   ============================================================ */
+
+:root {
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-bg: #0f172a;
+  --color-surface: #1e293b;
+  --color-text: #f1f5f9;
+  --color-text-muted: #94a3b8;
+  --color-border: #334155;
+  --color-success: #22c55e;
+  --color-warning: #f59e0b;
+  --color-error: #ef4444;
+  --radius: 8px;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: var(--color-bg);
+  color: var(--color-text);
+  min-height: 100vh;
+}
+
+.app {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 0 16px;
+}
+
+/* ---- Header ---- */
+
+.app-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.app-header h1 {
+  font-size: 1.5rem;
+  font-weight: 700;
+}
+
+.status {
+  font-size: 0.85rem;
+  padding: 4px 12px;
+  border-radius: 12px;
+  background: var(--color-surface);
+}
+
+.status--connected {
+  color: var(--color-success);
+  border: 1px solid var(--color-success);
+}
+
+.status--connecting {
+  color: var(--color-warning);
+  border: 1px solid var(--color-warning);
+}
+
+.status--disconnected {
+  color: var(--color-text-muted);
+  border: 1px solid var(--color-border);
+}
+
+/* ---- Main ---- */
+
+.app-main {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 16px 0;
+  overflow: hidden;
+}
+
+.video-section {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.vad-indicator {
+  position: absolute;
+  bottom: 12px;
+  left: 12px;
+  background: rgba(0, 0, 0, 0.7);
+  color: var(--color-success);
+  padding: 6px 12px;
+  border-radius: var(--radius);
+  font-size: 0.85rem;
+  animation: pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+
+.chat-section {
+  flex: 1;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+/* ---- Video Preview ---- */
+
+.video-preview {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 4 / 3;
+  background: var(--color-surface);
+  border-radius: var(--radius);
+  overflow: hidden;
+}
+
+.video-preview__video {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.video-preview__placeholder {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--color-text-muted);
+}
+
+/* ---- Chat Panel ---- */
+
+.chat-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.chat-panel--empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 48px 0;
+  color: var(--color-text-muted);
+}
+
+.chat-message {
+  padding: 12px 16px;
+  border-radius: var(--radius);
+  background: var(--color-surface);
+}
+
+.chat-message--user {
+  border-left: 3px solid var(--color-primary);
+}
+
+.chat-message--assistant {
+  border-left: 3px solid var(--color-success);
+}
+
+.chat-message--streaming {
+  opacity: 0.8;
+}
+
+.chat-message__role {
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  color: var(--color-text-muted);
+  margin-bottom: 4px;
+}
+
+.chat-message__content {
+  font-size: 0.95rem;
+  line-height: 1.5;
+  white-space: pre-wrap;
+}
+
+/* ---- Footer ---- */
+
+.app-footer {
+  display: flex;
+  gap: 12px;
+  justify-content: center;
+  padding: 16px 0;
+  border-top: 1px solid var(--color-border);
+}
+
+/* ---- Buttons ---- */
+
+.btn {
+  padding: 10px 24px;
+  border: none;
+  border-radius: var(--radius);
+  font-size: 0.95rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background 0.2s;
+}
+
+.btn--primary {
+  background: var(--color-primary);
+  color: white;
+}
+
+.btn--primary:hover {
+  background: var(--color-primary-hover);
+}
+
+.btn--secondary {
+  background: var(--color-surface);
+  color: var(--color-text);
+  border: 1px solid var(--color-border);
+}
+
+.btn--secondary:hover {
+  background: var(--color-border);
+}
+
+.btn--warning {
+  background: var(--color-warning);
+  color: #000;
+}
+
+.btn--warning:hover {
+  opacity: 0.9;
+}

frontend/src/App.tsx

@@ -0,0 +1,72 @@
+// ============================================================
+// CamTalk — 主应用组件
+// ============================================================
+
+import { useVisionSession } from "./hooks/useVisionSession";
+import { VideoPreview } from "./components/VideoPreview";
+import { ChatPanel } from "./components/ChatPanel";
+import "./App.css";
+
+function App() {
+  const {
+    messages,
+    currentReply,
+    isProcessing,
+    isSpeaking,
+    connectionStatus,
+    videoRef,
+    stream,
+    startSession,
+    stopSession,
+    interrupt,
+  } = useVisionSession();
+
+  return (
+    <div className="app">
+      <header className="app-header">
+        <h1>CamTalk</h1>
+        <span className={`status status--${connectionStatus}`}>
+          {connectionStatus === "connected" ? "已连接" : connectionStatus === "connecting" ? "连接中..." : "未连接"}
+        </span>
+      </header>
+
+      <main className="app-main">
+        <div className="video-section">
+          <VideoPreview ref={videoRef} isStreaming={!!stream} />
+          {isSpeaking && <div className="vad-indicator">🎤 正在聆听...</div>}
+        </div>
+
+        <div className="chat-section">
+          <ChatPanel messages={messages} />
+          {currentReply && (
+            <div className="chat-message chat-message--assistant chat-message--streaming">
+              <div className="chat-message__role">AI</div>
+              <div className="chat-message__content">{currentReply}</div>
+            </div>
+          )}
+        </div>
+      </main>
+
+      <footer className="app-footer">
+        {connectionStatus !== "connected" ? (
+          <button className="btn btn--primary" onClick={startSession}>
+            开始对话
+          </button>
+        ) : (
+          <>
+            <button className="btn btn--secondary" onClick={stopSession}>
+              结束对话
+            </button>
+            {isProcessing && (
+              <button className="btn btn--warning" onClick={interrupt}>
+                打断
+              </button>
+            )}
+          </>
+        )}
+      </footer>
+    </div>
+  );
+}
+
+export default App;

frontend/src/components/CameraManager/index.tsx

@@ -0,0 +1,59 @@
+// ============================================================
+// CameraManager — 摄像头流采集
+// 职责：获取用户摄像头 MediaStream，提供给 VideoPreview 和 EdgeProcessor
+// ============================================================
+
+import { useCallback, useRef, useState } from "react";
+
+export interface CameraManagerHandle {
+  /** 获取当前视频轨道 */
+  stream: MediaStream | null;
+  /** 捕获当前帧为 JPEG DataURL */
+  captureFrame: () => string | null;
+}
+
+export function useCamera() {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const startCamera = useCallback(async () => {
+    try {
+      const mediaStream = await navigator.mediaDevices.getUserMedia({
+        video: { facingMode: "environment", width: 640, height: 480 },
+        audio: false,
+      });
+      setStream(mediaStream);
+      if (videoRef.current) {
+        videoRef.current.srcObject = mediaStream;
+      }
+      setError(null);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "无法访问摄像头";
+      setError(message);
+      console.error("[Camera] 获取摄像头失败:", err);
+    }
+  }, []);
+
+  const stopCamera = useCallback(() => {
+    stream?.getTracks().forEach((track) => track.stop());
+    setStream(null);
+  }, [stream]);
+
+  /** 从 video 元素捕获当前帧为 JPEG DataURL */
+  const captureFrame = useCallback((): string | null => {
+    const video = videoRef.current;
+    if (!video || video.readyState < 2) return null;
+
+    const canvas = document.createElement("canvas");
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return null;
+
+    ctx.drawImage(video, 0, 0);
+    return canvas.toDataURL("image/jpeg", 0.7);
+  }, []);
+
+  return { videoRef, stream, error, startCamera, stopCamera, captureFrame };
+}

frontend/src/components/ChatPanel/index.tsx

@@ -0,0 +1,33 @@
+// ============================================================
+// ChatPanel — 消息展示面板
+// 职责：渲染对话消息列表（用户提问 + AI 回复）
+// ============================================================
+
+import type { ChatMessage } from "../../types";
+
+interface ChatPanelProps {
+  messages: ChatMessage[];
+}
+
+export function ChatPanel({ messages }: ChatPanelProps) {
+  if (messages.length === 0) {
+    return (
+      <div className="chat-panel chat-panel--empty">
+        <p>开始对话：对着摄像头说话即可</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="chat-panel">
+      {messages.map((msg, index) => (
+        <div key={index} className={`chat-message chat-message--${msg.role}`}>
+          <div className="chat-message__role">
+            {msg.role === "user" ? "你" : "AI"}
+          </div>
+          <div className="chat-message__content">{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  );
+}

frontend/src/components/EdgeProcessor/index.tsx

@@ -0,0 +1,58 @@
+// ============================================================
+// EdgeProcessor — 边缘预处理（VAD + 关键帧检测）
+// 职责：浏览器端语音活动检测、关键帧筛选
+// 技术：@ricky0123/vad-web（VAD）、ONNX Runtime Web（关键帧检测）
+// ============================================================
+
+import { useCallback, useState } from "react";
+
+export interface VADOptions {
+  /** 语音结束回调，携带录音 Float32Array */
+  onSpeechEnd?: (audio: Float32Array) => void;
+  /** 语音开始回调 */
+  onSpeechStart?: () => void;
+}
+
+export function useVAD(_options?: VADOptions) {
+  const [isSpeaking] = useState(false);
+  // TODO: 初始化 @ricky0123/vad-web，加载后设为 true
+  const isReady = false;
+
+  // TODO: 实现 VAD 初始化
+  // 1. 加载 @ricky0123/vad-web
+  // 2. 配置 VAD 参数（阈值、最小语音时长等）
+  // 3. 连接麦克风 stream
+  // 4. 在 onSpeechEnd 时收集音频并回调 _options.onSpeechEnd
+
+  const start = useCallback(() => {
+    // TODO: 启动 VAD 监听
+  }, []);
+
+  const stop = useCallback(() => {
+    // TODO: 停止 VAD 监听
+  }, []);
+
+  return { isSpeaking, isReady, start, stop };
+}
+
+// ---- 关键帧检测（ONNX Runtime Web）----
+
+export function useKeyframeDetection() {
+  // TODO: 加载 ONNX 模型后设为 true
+  const isReady = false;
+
+  // TODO: 实现关键帧检测
+  // 1. 加载 ONNX 模型
+  // 2. 对比当前帧与上一帧的像素差异
+  // 3. 超过阈值则判定为关键帧
+
+  const isKeyframe = useCallback(
+    (_currentFrame: ImageData, _previousFrame: ImageData): boolean => {
+      // TODO: 实现像素差异对比
+      return true; // 暂时所有帧都视为关键帧
+    },
+    [],
+  );
+
+  return { isReady, isKeyframe };
+}

frontend/src/components/MicManager/index.tsx

@@ -0,0 +1,51 @@
+// ============================================================
+// MicManager — 麦克风音频采集
+// 职责：获取麦克风 MediaStream，供 VAD 和音频录制使用
+// ============================================================
+
+import { useCallback, useRef, useState } from "react";
+
+export function useMicrophone() {
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const audioContextRef = useRef<AudioContext | null>(null);
+
+  const startMic = useCallback(async () => {
+    try {
+      const mediaStream = await navigator.mediaDevices.getUserMedia({
+        audio: {
+          sampleRate: 16000,
+          channelCount: 1,
+          echoCancellation: true,
+          noiseSuppression: true,
+        },
+        video: false,
+      });
+      setStream(mediaStream);
+      setError(null);
+      return mediaStream;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "无法访问麦克风";
+      setError(message);
+      console.error("[Mic] 获取麦克风失败:", err);
+      return null;
+    }
+  }, []);
+
+  const stopMic = useCallback(() => {
+    stream?.getTracks().forEach((track) => track.stop());
+    setStream(null);
+    audioContextRef.current?.close();
+    audioContextRef.current = null;
+  }, [stream]);
+
+  /** 获取或创建 AudioContext */
+  const getAudioContext = useCallback((): AudioContext => {
+    if (!audioContextRef.current) {
+      audioContextRef.current = new AudioContext({ sampleRate: 16000 });
+    }
+    return audioContextRef.current;
+  }, []);
+
+  return { stream, error, startMic, stopMic, getAudioContext };
+}

frontend/src/components/VideoPreview/index.tsx

@@ -0,0 +1,31 @@
+// ============================================================
+// VideoPreview — 摄像头画面预览
+// 职责：显示实时摄像头画面
+// ============================================================
+
+import { forwardRef } from "react";
+
+interface VideoPreviewProps {
+  isStreaming: boolean;
+}
+
+export const VideoPreview = forwardRef<HTMLVideoElement, VideoPreviewProps>(
+  function VideoPreview({ isStreaming }, ref) {
+    return (
+      <div className="video-preview">
+        <video
+          ref={ref}
+          autoPlay
+          playsInline
+          muted
+          className="video-preview__video"
+        />
+        {!isStreaming && (
+          <div className="video-preview__placeholder">
+            摄像头未开启
+          </div>
+        )}
+      </div>
+    );
+  }
+);

frontend/src/components/WebSocketManager/index.tsx

@@ -0,0 +1,32 @@
+// ============================================================
+// WebSocketManager — WebSocket 连接生命周期管理
+// 职责：管理连接状态、消息分发
+// ============================================================
+
+import { useEffect, useState } from "react";
+import { wsClient } from "../../lib/websocket";
+import type { ConnectionStatus } from "../../lib/websocket";
+import type { ServerMessage } from "../../types";
+
+export function useWebSocketManager() {
+  const [status, setStatus] = useState<ConnectionStatus>(wsClient.status);
+  const [lastMessage, setLastMessage] = useState<ServerMessage | null>(null);
+
+  useEffect(() => {
+    const unsubStatus = wsClient.onStatusChange(setStatus);
+    const unsubMessage = wsClient.onMessage(setLastMessage);
+
+    return () => {
+      unsubStatus();
+      unsubMessage();
+    };
+  }, []);
+
+  return {
+    status,
+    lastMessage,
+    connect: () => wsClient.connect(),
+    disconnect: () => wsClient.disconnect(),
+    send: wsClient.send.bind(wsClient),
+  };
+}

frontend/src/hooks/useVisionSession.ts

@@ -0,0 +1,134 @@
+// ============================================================
+// useVisionSession — 核心视觉对话会话 Hook
+// 职责：封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态）
+// 来源：docs/02-系统架构.md 核心 Hook 设计
+// ============================================================
+
+import { useCallback, useEffect, useState } from "react";
+import { v4 as uuidv4 } from "uuid";
+import { wsClient } from "../lib/websocket";
+import { encodeAudioToBase64, dataUrlToBase64 } from "../lib/audio";
+import { useCamera } from "../components/CameraManager";
+import { useVAD } from "../components/EdgeProcessor";
+import { useWebSocketManager } from "../components/WebSocketManager";
+import type { ChatMessage, ServerMessage, LLMDoneMessage } from "../types";
+
+export function useVisionSession() {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [currentReply, setCurrentReply] = useState<string>("");
+  const [isProcessing, setIsProcessing] = useState(false);
+
+  const { videoRef, captureFrame, startCamera, stopCamera, stream } = useCamera();
+  const { status, connect, disconnect, send } = useWebSocketManager();
+
+  // VAD：语音结束时自动发送 query
+  const { isSpeaking, start: startVAD, stop: stopVAD } = useVAD({
+    onSpeechEnd: useCallback(
+      (audio: Float32Array) => {
+        const frame = captureFrame();
+        if (!frame) {
+          console.warn("[Session] 无法捕获图像帧");
+          return;
+        }
+
+        const requestId = uuidv4();
+        send({
+          type: "query",
+          request_id: requestId,
+          image: dataUrlToBase64(frame),
+          audio: encodeAudioToBase64(audio),
+        });
+
+        // 添加用户消息（STT 结果到达后会更新文本）
+        setMessages((prev) => [
+          ...prev,
+          { role: "user", content: "（语音识别中...）", timestamp: Date.now() },
+        ]);
+        setIsProcessing(true);
+      },
+      [captureFrame, send]
+    ),
+  });
+
+  // 处理服务端消息
+  useEffect(() => {
+    const unsub = wsClient.onMessage((msg: ServerMessage) => {
+      switch (msg.type) {
+        case "stt_result":
+          if (msg.is_final) {
+            setMessages((prev) => {
+              const updated = [...prev];
+              const lastUserIdx = updated.findLastIndex((m) => m.role === "user");
+              if (lastUserIdx >= 0) {
+                updated[lastUserIdx] = { ...updated[lastUserIdx], content: msg.text };
+              }
+              return updated;
+            });
+          }
+          break;
+
+        case "llm_chunk":
+          setCurrentReply((prev) => prev + msg.delta);
+          break;
+
+        case "llm_done":
+          setMessages((prev) => [
+            ...prev,
+            {
+              role: "assistant",
+              content: (msg as LLMDoneMessage).full_text,
+              timestamp: Date.now(),
+              tokensUsed: (msg as LLMDoneMessage).tokens_used?.total,
+            },
+          ]);
+          setCurrentReply("");
+          setIsProcessing(false);
+          break;
+
+        case "tts_audio":
+          // TODO: 音频流播放
+          break;
+
+        case "error":
+          console.error("[Session] 服务端错误:", msg.code, msg.message);
+          setIsProcessing(false);
+          break;
+      }
+    });
+
+    return unsub;
+  }, []);
+
+  /** 启动会话 */
+  const startSession = useCallback(async () => {
+    await startCamera();
+    connect();
+    startVAD();
+  }, [startCamera, connect, startVAD]);
+
+  /** 结束会话 */
+  const stopSession = useCallback(() => {
+    stopVAD();
+    stopCamera();
+    disconnect();
+  }, [stopVAD, stopCamera, disconnect]);
+
+  /** 打断当前回复 */
+  const interrupt = useCallback(() => {
+    send({ type: "interrupt" });
+    setIsProcessing(false);
+  }, [send]);
+
+  return {
+    messages,
+    currentReply,
+    isProcessing,
+    isSpeaking,
+    connectionStatus: status,
+    videoRef,
+    stream,
+    startSession,
+    stopSession,
+    interrupt,
+  };
+}

frontend/src/index.css

@@ -0,0 +1,7 @@
+/* 全局重置 — 详细样式在 App.css 中定义 */
+
+#root {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}

frontend/src/lib/audio.ts

@@ -0,0 +1,50 @@
+// ============================================================
+// 音频编码工具
+// 职责：将浏览器采集的音频数据编码为 Base64 PCM 格式
+// ============================================================
+
+/**
+ * 将 Float32Array 音频样本编码为 Base64 PCM 16kHz 字符串
+ * 用于 WebSocket query 消息的 audio 字段
+ */
+export function encodeAudioToBase64(samples: Float32Array): string {
+  // Float32 -> Int16 PCM
+  const buffer = new ArrayBuffer(samples.length * 2);
+  const view = new DataView(buffer);
+
+  for (let i = 0; i < samples.length; i++) {
+    const s = Math.max(-1, Math.min(1, samples[i]));
+    view.setInt16(i * 2, s < 0 ? s * 0x8000 : s * 0x7fff, true);
+  }
+
+  // ArrayBuffer -> Base64
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * 将 Base64 音频数据解码为可用于播放的 Blob URL
+ * 用于 TTS 音频播放
+ */
+export function decodeBase64Audio(base64: string, mimeType: string): string {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  const blob = new Blob([bytes], { type: mimeType });
+  return URL.createObjectURL(blob);
+}
+
+/**
+ * 将 JPEG DataURL 转换为纯 Base64（去掉 data:image/jpeg;base64, 前缀）
+ * 用于 WebSocket query 消息的 image 字段
+ */
+export function dataUrlToBase64(dataUrl: string): string {
+  const commaIndex = dataUrl.indexOf(",");
+  return commaIndex >= 0 ? dataUrl.substring(commaIndex + 1) : dataUrl;
+}

frontend/src/lib/websocket.ts

@@ -0,0 +1,149 @@
+// ============================================================
+// WebSocket 连接管理
+// 职责：心跳保活、指数退避重连、类型安全的消息收发
+// 来源：docs/03-接口文档.md §六 连接管理
+// ============================================================
+
+import type { ClientMessage, ServerMessage, WsMessage } from "../types";
+
+const WS_URL = "ws://localhost:8080/ws";
+const PING_INTERVAL = 30_000;   // 30 秒心跳
+const MAX_RECONNECT_DELAY = 30_000; // 最大重连延迟 30 秒
+
+type MessageHandler = (msg: ServerMessage) => void;
+type StatusHandler = (status: ConnectionStatus) => void;
+
+export type ConnectionStatus = "connecting" | "connected" | "disconnected";
+
+export class CamTalkWebSocket {
+  private ws: WebSocket | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private shouldReconnect = true;
+
+  private messageHandlers = new Set<MessageHandler>();
+  private statusHandlers = new Set<StatusHandler>();
+  private _status: ConnectionStatus = "disconnected";
+
+  get status(): ConnectionStatus {
+    return this._status;
+  }
+
+  /** 注册消息回调 */
+  onMessage(handler: MessageHandler): () => void {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+
+  /** 注册连接状态回调 */
+  onStatusChange(handler: StatusHandler): () => void {
+    this.statusHandlers.add(handler);
+    return () => this.statusHandlers.delete(handler);
+  }
+
+  /** 建立连接 */
+  connect(): void {
+    if (this.ws?.readyState === WebSocket.OPEN) return;
+
+    this.shouldReconnect = true;
+    this.setStatus("connecting");
+
+    const ws = new WebSocket(WS_URL);
+
+    ws.onopen = () => {
+      this.reconnectAttempt = 0;
+      this.setStatus("connected");
+      this.startPing();
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data) as WsMessage;
+        // 忽略 pong，心跳由服务端自动回复
+        if (msg.type === "pong") return;
+        this.messageHandlers.forEach((h) => h(msg as ServerMessage));
+      } catch {
+        console.error("[WS] 无法解析消息:", event.data);
+      }
+    };
+
+    ws.onclose = () => {
+      this.stopPing();
+      this.setStatus("disconnected");
+      if (this.shouldReconnect) {
+        this.scheduleReconnect();
+      }
+    };
+
+    ws.onerror = (err) => {
+      console.error("[WS] 连接错误:", err);
+      ws.close();
+    };
+
+    this.ws = ws;
+  }
+
+  /** 断开连接，不再自动重连 */
+  disconnect(): void {
+    this.shouldReconnect = false;
+    this.clearTimers();
+    this.ws?.close();
+    this.ws = null;
+    this.setStatus("disconnected");
+  }
+
+  /** 发送客户端消息 */
+  send(msg: ClientMessage): void {
+    if (this.ws?.readyState !== WebSocket.OPEN) {
+      console.warn("[WS] 连接未就绪，消息丢弃:", msg.type);
+      return;
+    }
+    this.ws.send(JSON.stringify(msg));
+  }
+
+  /** 发送 ping 心跳 */
+  private startPing(): void {
+    this.stopPing();
+    this.pingTimer = setInterval(() => {
+      this.send({ type: "ping" });
+    }, PING_INTERVAL);
+  }
+
+  private stopPing(): void {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+
+  /** 指数退避 + 抖动重连 */
+  private scheduleReconnect(): void {
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempt), MAX_RECONNECT_DELAY);
+    const jitter = Math.random() * 1000;
+    const totalDelay = delay + jitter;
+
+    console.log(`[WS] ${totalDelay.toFixed(0)}ms 后重连 (attempt ${this.reconnectAttempt})`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectAttempt++;
+      this.connect();
+    }, totalDelay);
+  }
+
+  private setStatus(status: ConnectionStatus): void {
+    this._status = status;
+    this.statusHandlers.forEach((h) => h(status));
+  }
+
+  private clearTimers(): void {
+    this.stopPing();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}
+
+/** 创建单例实例 */
+export const wsClient = new CamTalkWebSocket();

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

frontend/src/types/index.ts

@@ -0,0 +1,148 @@
+// ============================================================
+// CamTalk 前端类型定义
+// 来源：docs/03-接口文档.md
+// ============================================================
+
+// ---- 会话模型 ----
+
+export interface SessionConfig {
+  ttsEnabled: boolean;
+  detailLevel: "low" | "high";
+  language: string;
+}
+
+export interface Session {
+  sessionId: string;
+  createdAt: string;
+  config: SessionConfig;
+}
+
+// ---- 聊天消息 ----
+
+export interface ChatMessage {
+  role: "user" | "assistant";
+  content: string;
+  imageUrl?: string;
+  timestamp: number;
+  tokensUsed?: number;
+}
+
+// ---- WebSocket 通用信封 ----
+
+export interface WsMessage {
+  type: string;
+  request_id?: string;
+  timestamp?: number;
+  [key: string]: unknown;
+}
+
+// ---- 客户端 → 服务端消息 ----
+
+export interface QueryMessage {
+  type: "query";
+  request_id: string;
+  image: string;       // Base64 JPEG（不含 data: 前缀）
+  audio: string;       // Base64 PCM 16kHz
+  mime_type?: string;  // 默认 "audio/pcm"
+}
+
+export interface ConfigMessage {
+  type: "config";
+  payload: {
+    tts_enabled?: boolean;
+    detail_level?: "low" | "high";
+    language?: string;
+  };
+}
+
+export interface InterruptMessage {
+  type: "interrupt";
+  request_id?: string;
+}
+
+export interface PingMessage {
+  type: "ping";
+}
+
+export type ClientMessage =
+  | QueryMessage
+  | ConfigMessage
+  | InterruptMessage
+  | PingMessage;
+
+// ---- 服务端 → 客户端消息 ----
+
+export interface ConnectedMessage {
+  type: "connected";
+  session_id: string;
+  server_version: string;
+}
+
+export interface STTResultMessage {
+  type: "stt_result";
+  request_id: string;
+  text: string;
+  is_final: boolean;
+}
+
+export interface LLMChunkMessage {
+  type: "llm_chunk";
+  request_id: string;
+  delta: string;
+  role: "assistant";
+}
+
+export interface LLMDoneMessage {
+  type: "llm_done";
+  request_id: string;
+  full_text: string;
+  tokens_used: {
+    prompt: number;
+    completion: number;
+    total: number;
+  };
+  model: string;
+  latency_ms: number;
+}
+
+export interface TTSAudioMessage {
+  type: "tts_audio";
+  request_id: string;
+  audio: string;       // Base64 音频片段
+  mime_type: string;   // "audio/mp3" 或 "audio/pcm"
+  is_last: boolean;
+}
+
+export interface ErrorMessage {
+  type: "error";
+  request_id?: string;
+  code: string;
+  message: string;
+}
+
+export interface PongMessage {
+  type: "pong";
+}
+
+export type ServerMessage =
+  | ConnectedMessage
+  | STTResultMessage
+  | LLMChunkMessage
+  | LLMDoneMessage
+  | TTSAudioMessage
+  | ErrorMessage
+  | PongMessage;
+
+// ---- 错误码 ----
+
+export type ErrorCode =
+  | "INVALID_MESSAGE"
+  | "SESSION_NOT_FOUND"
+  | "RATE_LIMITED"
+  | "IMAGE_TOO_LARGE"
+  | "AUDIO_TOO_SHORT"
+  | "LLM_TIMEOUT"
+  | "LLM_ERROR"
+  | "STT_ERROR"
+  | "TTS_ERROR"
+  | "INTERNAL_ERROR";