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>
2026-06-12 17:46:25 +08:00
parent 10f676f3b4
commit b5c0d40609
26 changed files with 4236 additions and 0 deletions
--- a/frontend/.gitignore
+++ b/frontend/.gitignore
@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -0,0 +1,28 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      globals: globals.browser,
+    },
+    rules: {
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+    },
+  },
+])
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@ricky0123/vad-web": "^0.0.30",
+    "onnxruntime-web": "^1.26.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/uuid": "^10.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.3.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.59.2",
+    "vite": "^8.0.12"
+  }
+}
--- a/frontend/public/favicon.svg
+++ b/frontend/public/favicon.svg
--- a/frontend/public/icons.svg
+++ b/frontend/public/icons.svg
@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg">
+  <symbol id="bluesky-icon" viewBox="0 0 16 17">
+    <g clip-path="url(#bluesky-clip)"><path fill="#08060d" d="M7.75 7.735c-.693-1.348-2.58-3.86-4.334-5.097-1.68-1.187-2.32-.981-2.74-.79C.188 2.065.1 2.812.1 3.251s.241 3.602.398 4.13c.52 1.744 2.367 2.333 4.07 2.145-2.495.37-4.71 1.278-1.805 4.512 3.196 3.309 4.38-.71 4.987-2.746.608 2.036 1.307 5.91 4.93 2.746 2.72-2.746.747-4.143-1.747-4.512 1.702.189 3.55-.4 4.07-2.145.156-.528.397-3.691.397-4.13s-.088-1.186-.575-1.406c-.42-.19-1.06-.395-2.741.79-1.755 1.24-3.64 3.752-4.334 5.099"/></g>
+    <defs><clipPath id="bluesky-clip"><path fill="#fff" d="M.1.85h15.3v15.3H.1z"/></clipPath></defs>
+  </symbol>
+  <symbol id="discord-icon" viewBox="0 0 20 19">
+    <path fill="#08060d" d="M16.224 3.768a14.5 14.5 0 0 0-3.67-1.153c-.158.286-.343.67-.47.976a13.5 13.5 0 0 0-4.067 0c-.128-.306-.317-.69-.476-.976A14.4 14.4 0 0 0 3.868 3.77C1.546 7.28.916 10.703 1.231 14.077a14.7 14.7 0 0 0 4.5 2.306q.545-.748.965-1.587a9.5 9.5 0 0 1-1.518-.74q.191-.14.372-.293c2.927 1.369 6.107 1.369 8.999 0q.183.152.372.294-.723.437-1.52.74.418.838.963 1.588a14.6 14.6 0 0 0 4.504-2.308c.37-3.911-.63-7.302-2.644-10.309m-9.13 8.234c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.894 0 1.614.82 1.599 1.82.001 1-.705 1.82-1.6 1.82m5.91 0c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.893 0 1.614.82 1.599 1.82 0 1-.706 1.82-1.6 1.82"/>
+  </symbol>
+  <symbol id="documentation-icon" viewBox="0 0 21 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="m15.5 13.333 1.533 1.322c.645.555.967.833.967 1.178s-.322.623-.967 1.179L15.5 18.333m-3.333-5-1.534 1.322c-.644.555-.966.833-.966 1.178s.322.623.966 1.179l1.534 1.321"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M17.167 10.836v-4.32c0-1.41 0-2.117-.224-2.68-.359-.906-1.118-1.621-2.08-1.96-.599-.21-1.349-.21-2.848-.21-2.623 0-3.935 0-4.983.369-1.684.591-3.013 1.842-3.641 3.428C3 6.449 3 7.684 3 10.154v2.122c0 2.558 0 3.838.706 4.726q.306.383.713.671c.76.536 1.79.64 3.581.66"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M3 10a2.78 2.78 0 0 1 2.778-2.778c.555 0 1.209.097 1.748-.047.48-.129.854-.503.982-.982.145-.54.048-1.194.048-1.749a2.78 2.78 0 0 1 2.777-2.777"/>
+  </symbol>
+  <symbol id="github-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M9.356 1.85C5.05 1.85 1.57 5.356 1.57 9.694a7.84 7.84 0 0 0 5.324 7.44c.387.079.528-.168.528-.376 0-.182-.013-.805-.013-1.454-2.165.467-2.616-.935-2.616-.935-.349-.91-.864-1.143-.864-1.143-.71-.48.051-.48.051-.48.787.051 1.2.805 1.2.805.695 1.194 1.817.857 2.268.649.064-.507.27-.857.49-1.052-1.728-.182-3.545-.857-3.545-3.87 0-.857.31-1.558.8-2.104-.078-.195-.349-1 .077-2.078 0 0 .657-.208 2.14.805a7.5 7.5 0 0 1 1.946-.26c.657 0 1.328.092 1.946.26 1.483-1.013 2.14-.805 2.14-.805.426 1.078.155 1.883.078 2.078.502.546.799 1.247.799 2.104 0 3.013-1.818 3.675-3.558 3.87.284.247.528.714.528 1.454 0 1.052-.012 1.896-.012 2.156 0 .208.142.455.528.377a7.84 7.84 0 0 0 5.324-7.441c.013-4.338-3.48-7.844-7.773-7.844" clip-rule="evenodd"/>
+  </symbol>
+  <symbol id="social-icon" viewBox="0 0 20 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M12.5 6.667a4.167 4.167 0 1 0-8.334 0 4.167 4.167 0 0 0 8.334 0"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M2.5 16.667a5.833 5.833 0 0 1 8.75-5.053m3.837.474.513 1.035c.07.144.257.282.414.309l.93.155c.596.1.736.536.307.965l-.723.73a.64.64 0 0 0-.152.531l.207.903c.164.715-.213.991-.84.618l-.872-.52a.63.63 0 0 0-.577 0l-.872.52c-.624.373-1.003.094-.84-.618l.207-.903a.64.64 0 0 0-.152-.532l-.723-.729c-.426-.43-.289-.864.306-.964l.93-.156a.64.64 0 0 0 .412-.31l.513-1.034c.28-.562.735-.562 1.012 0"/>
+  </symbol>
+  <symbol id="x-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M1.893 1.98c.052.072 1.245 1.769 2.653 3.77l2.892 4.114c.183.261.333.48.333.486s-.068.089-.152.183l-.522.593-.765.867-3.597 4.087c-.375.426-.734.834-.798.905a1 1 0 0 0-.118.148c0 .01.236.017.664.017h.663l.729-.83c.4-.457.796-.906.879-.999a692 692 0 0 0 1.794-2.038c.034-.037.301-.34.594-.675l.551-.624.345-.392a7 7 0 0 1 .34-.374c.006 0 .93 1.306 2.052 2.903l2.084 2.965.045.063h2.275c1.87 0 2.273-.003 2.266-.021-.008-.02-1.098-1.572-3.894-5.547-2.013-2.862-2.28-3.246-2.273-3.266.008-.019.282-.332 2.085-2.38l2-2.274 1.567-1.782c.022-.028-.016-.03-.65-.03h-.674l-.3.342a871 871 0 0 1-1.782 2.025c-.067.075-.405.458-.75.852a100 100 0 0 1-.803.91c-.148.172-.299.344-.99 1.127-.304.343-.32.358-.345.327-.015-.019-.904-1.282-1.976-2.808L6.365 1.85H1.8zm1.782.91 8.078 11.294c.772 1.08 1.413 1.973 1.425 1.984.016.017.241.02 1.05.017l1.03-.004-2.694-3.766L7.796 5.75 5.722 2.852l-1.039-.004-1.039-.004z" clip-rule="evenodd"/>
+  </symbol>
+</svg>
--- a/frontend/src/App.css
+++ b/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;
+}
--- a/frontend/src/App.tsx
+++ b/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;
--- a/frontend/src/components/CameraManager/index.tsx
+++ b/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 };
+}
--- a/frontend/src/components/ChatPanel/index.tsx
+++ b/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>
+  );
+}
--- a/frontend/src/components/EdgeProcessor/index.tsx
+++ b/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 };
+}
--- a/frontend/src/components/MicManager/index.tsx
+++ b/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 };
+}
--- a/frontend/src/components/VideoPreview/index.tsx
+++ b/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>
+    );
+  }
+);
--- a/frontend/src/components/WebSocketManager/index.tsx
+++ b/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),
+  };
+}
--- a/frontend/src/hooks/useVisionSession.ts
+++ b/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,
+  };
+}
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -0,0 +1,7 @@
+/* 全局重置 — 详细样式在 App.css 中定义 */
+
+#root {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
--- a/frontend/src/lib/audio.ts
+++ b/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;
+}
--- a/frontend/src/lib/websocket.ts
+++ b/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();
--- a/frontend/src/main.tsx
+++ b/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>,
+)
--- a/frontend/src/types/index.ts
+++ b/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";
--- a/frontend/tsconfig.app.json
+++ b/frontend/tsconfig.app.json
@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+    "strict": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
--- a/frontend/tsconfig.node.json
+++ b/frontend/tsconfig.node.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "module": "esnext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})