2026-06-13 10:08:12 +08:00
34 changed files with 4779 additions and 0 deletions
--- a/.gitea/workflow/backend-ci.yml
+++ b/.gitea/workflow/backend-ci.yml
@@ -0,0 +1,34 @@
+name: Backend CI
+
+on:
+  push:
+    branches: [main]
+    paths: [backend/**]
+  pull_request:
+    branches: [main]
+    paths: [backend/**]
+
+jobs:
+  ci:
+    runs-on: aliyun
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Build
+        run: go build ./cmd/server
+
+      - name: Test
+        run: go test ./...
--- a/.gitea/workflow/frontend-ci.yml
+++ b/.gitea/workflow/frontend-ci.yml
@@ -0,0 +1,33 @@
+name: Frontend CI
+
+on:
+  push:
+    branches: [main]
+    paths: [frontend/**]
+  pull_request:
+    branches: [main]
+    paths: [frontend/**]
+
+jobs:
+  ci:
+    runs-on: aliyun
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check & Build
+        run: npm run build
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,22 @@
+# ---- 前端 ----
+frontend/node_modules/
+frontend/dist/
+
+# ---- 后端 ----
+backend/bin/
+
+# ---- 环境变量 ----
+.env
+.env.local
+.env.*.local
+
+# ---- OS ----
+.DS_Store
+Thumbs.db
+
+# ---- IDE ----
+.idea/
+.vscode/
+
+# ---- Obsidian ----
+.obsidian/
--- a/backend/cmd/server/main.go
+++ b/backend/cmd/server/main.go
@@ -0,0 +1,40 @@
+package main
+
+import (
+	"log"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/hhs/camtalk/internal/ws"
+)
+
+var startTime = time.Now()
+
+func main() {
+	r := gin.Default()
+
+	// REST API
+	api := r.Group("/api")
+	{
+		api.GET("/health", healthHandler)
+	}
+
+	// WebSocket
+	r.GET("/ws", ws.ServeWS)
+
+	log.Println("CamTalk gateway starting on :8080")
+	if err := r.Run(":8080"); err != nil {
+		log.Fatalf("failed to start server: %v", err)
+	}
+}
+
+// healthHandler 健康检查。
+func healthHandler(c *gin.Context) {
+	c.JSON(200, gin.H{
+		"status":         "ok",
+		"version":        "0.1.0",
+		"uptime":         time.Since(startTime).String(),
+		"active_sessions": 0, // TODO: 接入 Session Manager
+	})
+}
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -0,0 +1,38 @@
+module github.com/hhs/camtalk
+
+go 1.23
+
+require (
+	github.com/gin-gonic/gin v1.10.0
+	github.com/google/uuid v1.6.0
+	github.com/gorilla/websocket v1.5.3
+)
+
+require (
+	github.com/bytedance/sonic v1.11.6 // indirect
+	github.com/bytedance/sonic/loader v0.1.1 // indirect
+	github.com/cloudwego/base64x v0.1.4 // indirect
+	github.com/cloudwego/iasm v0.2.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
+	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.20.0 // indirect
+	github.com/goccy/go-json v0.10.2 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.2.12 // indirect
+	golang.org/x/arch v0.8.0 // indirect
+	golang.org/x/crypto v0.23.0 // indirect
+	golang.org/x/net v0.25.0 // indirect
+	golang.org/x/sys v0.20.0 // indirect
+	golang.org/x/text v0.15.0 // indirect
+	google.golang.org/protobuf v1.34.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
--- a/backend/go.sum
+++ b/backend/go.sum
@@ -0,0 +1,93 @@
+github.com/bytedance/sonic v1.11.6 h1:oUp34TzMlL+OY1OUWxHqsdkgC/Zfc85zGqw9siXjrc0=
+github.com/bytedance/sonic v1.11.6/go.mod h1:LysEHSvpvDySVdC2f87zGWf6CIKJcAvqab1ZaiQtds4=
+github.com/bytedance/sonic/loader v0.1.1 h1:c+e5Pt1k/cy5wMveRDyk2X4B9hF4g7an8N3zCYjJFNM=
+github.com/bytedance/sonic/loader v0.1.1/go.mod h1:ncP89zfokxS5LZrJxl5z0UJcsk4M4yY2JpfqGeCtNLU=
+github.com/cloudwego/base64x v0.1.4 h1:jwCgWpFanWmN8xoIUHa2rtzmkd5J2plF/dnLS6Xd/0Y=
+github.com/cloudwego/base64x v0.1.4/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
+github.com/cloudwego/iasm v0.2.0 h1:1KNIy1I1H9hNNFEEH3DVnI4UujN+1zjpuk6gwHLTssg=
+github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
+github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
+github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
+github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
+github.com/gin-gonic/gin v1.10.0 h1:nTuyha1TYqgedzytsKYqna+DfLos46nTv2ygFy86HFU=
+github.com/gin-gonic/gin v1.10.0/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBExVwjEviJTixqxL8=
+github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
+github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
+github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
+github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
+github.com/klauspost/cpuid/v2 v2.2.7 h1:ZWSB3igEs+d0qvnxR/ZBzXVmxkgt8DdzP6m9pfuVLDM=
+github.com/klauspost/cpuid/v2 v2.2.7/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=
+github.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
+github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
+github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
+golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
+golang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=
+golang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=
+golang.org/x/crypto v0.23.0 h1:dIJU/v2J8Mdglj/8rJ6UUOM3Zc9zLZxVZwwxMooUSAI=
+golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
+golang.org/x/net v0.25.0 h1:d/OCCoBEUq33pjydKrGQhw7IlUPI2Oylr+8qLx49kac=
+golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
+golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
+golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
+golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
+google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
+rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=
--- a/backend/internal/models/models.go
+++ b/backend/internal/models/models.go
@@ -0,0 +1,108 @@
+package models
+
+import "time"
+
+// Session 会话。
+type Session struct {
+	ID        string        `json:"session_id"`
+	CreatedAt time.Time     `json:"created_at"`
+	Config    SessionConfig `json:"config"`
+}
+
+// SessionConfig 会话配置。
+type SessionConfig struct {
+	TTSEnabled  bool   `json:"tts_enabled"`
+	DetailLevel string `json:"detail_level"` // "low" | "high"
+	Language    string `json:"language"`
+}
+
+// DefaultConfig 默认会话配置。
+func DefaultConfig() SessionConfig {
+	return SessionConfig{TTSEnabled: true, DetailLevel: "low", Language: "zh-CN"}
+}
+
+// Message 对话消息。
+type Message struct {
+	Role    string `json:"role"` // "user" | "assistant"
+	Content string `json:"content"`
+}
+
+// --- WebSocket 消息 ---
+
+// WsQuery 客户端 query 消息。
+type WsQuery struct {
+	Type      string `json:"type"`
+	RequestID string `json:"request_id"`
+	Image     string `json:"image"`     // base64
+	Audio     string `json:"audio"`     // base64
+	MimeType  string `json:"mime_type"` // 默认 "audio/pcm"
+}
+
+// WsConfig 客户端 config 消息。
+type WsConfig struct {
+	Type    string `json:"type"`
+	Payload struct {
+		TTSEnabled  *bool   `json:"tts_enabled,omitempty"`
+		DetailLevel *string `json:"detail_level,omitempty"`
+		Language    *string `json:"language,omitempty"`
+	} `json:"payload"`
+}
+
+// WsConnected 服务端 connected 消息。
+type WsConnected struct {
+	Type          string `json:"type"`
+	SessionID     string `json:"session_id"`
+	ServerVersion string `json:"server_version"`
+}
+
+// WsSTTResult 服务端 stt_result 消息。
+type WsSTTResult struct {
+	Type      string `json:"type"`
+	RequestID string `json:"request_id"`
+	Text      string `json:"text"`
+	IsFinal   bool   `json:"is_final"`
+}
+
+// WsLLMChunk 服务端 llm_chunk 消息。
+type WsLLMChunk struct {
+	Type      string `json:"type"`
+	RequestID string `json:"request_id"`
+	Delta     string `json:"delta"`
+	Role      string `json:"role"`
+}
+
+// WsLLMDone 服务端 llm_done 消息。
+type WsLLMDone struct {
+	Type       string `json:"type"`
+	RequestID  string `json:"request_id"`
+	FullText   string `json:"full_text"`
+	TokensUsed struct {
+		Prompt     int `json:"prompt"`
+		Completion int `json:"completion"`
+		Total      int `json:"total"`
+	} `json:"tokens_used"`
+	Model     string `json:"model"`
+	LatencyMs int64  `json:"latency_ms"`
+}
+
+// WsTTSAudio 服务端 tts_audio 消息。
+type WsTTSAudio struct {
+	Type      string `json:"type"`
+	RequestID string `json:"request_id"`
+	Audio     string `json:"audio"`     // base64
+	MimeType  string `json:"mime_type"` // "audio/mp3" 或 "audio/pcm"
+	IsLast    bool   `json:"is_last"`
+}
+
+// WsError 服务端 error 消息。
+type WsError struct {
+	Type      string `json:"type"`
+	RequestID string `json:"request_id,omitempty"`
+	Code      string `json:"code"`
+	Message   string `json:"message"`
+}
+
+// WsPong 服务端 pong 消息。
+type WsPong struct {
+	Type string `json:"type"`
+}
--- a/backend/internal/ws/handler.go
+++ b/backend/internal/ws/handler.go
@@ -0,0 +1,149 @@
+package ws
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/gorilla/websocket"
+
+	"github.com/hhs/camtalk/internal/models"
+)
+
+var upgrader = websocket.Upgrader{
+	CheckOrigin: func(r *http.Request) bool { return true }, // 开发阶段允许所有来源
+}
+
+// Client 代表一个 WebSocket 客户端连接。
+type Client struct {
+	conn      *websocket.Conn
+	sessionID string
+	mu        sync.Mutex
+}
+
+func (c *Client) sendJSON(v any) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.conn.WriteJSON(v)
+}
+
+// ServeWS 处理 WebSocket 升级请求。
+func ServeWS(c *gin.Context) {
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		log.Printf("websocket upgrade failed: %v", err)
+		return
+	}
+	defer conn.Close()
+
+	sessionID := uuid.New().String()
+	client := &Client{conn: conn, sessionID: sessionID}
+
+	// 发送 connected 消息
+	_ = client.sendJSON(models.WsConnected{
+		Type:          "connected",
+		SessionID:     sessionID,
+		ServerVersion: "0.1.0",
+	})
+	log.Printf("client connected: session=%s", sessionID)
+
+	// 心跳检测
+	lastPong := time.Now()
+	conn.SetPongHandler(func(string) error {
+		lastPong = time.Now()
+		return nil
+	})
+
+	// 启动心跳检查 goroutine
+	done := make(chan struct{})
+	go func() {
+		ticker := time.NewTicker(30 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				if time.Since(lastPong) > 60*time.Second {
+					log.Printf("heartbeat timeout: session=%s", sessionID)
+					conn.Close()
+					return
+				}
+			case <-done:
+				return
+			}
+		}
+	}()
+
+	// 消息读取循环
+	for {
+		_, message, err := conn.ReadMessage()
+		if err != nil {
+			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+				log.Printf("ws read error: %v", err)
+			}
+			break
+		}
+
+		// 解析消息类型
+		var envelope struct {
+			Type string `json:"type"`
+		}
+		if err := json.Unmarshal(message, &envelope); err != nil {
+			_ = client.sendJSON(models.WsError{
+				Type:    "error",
+				Code:    "INVALID_MESSAGE",
+				Message: "invalid JSON",
+			})
+			continue
+		}
+
+		switch envelope.Type {
+		case "ping":
+			_ = client.sendJSON(models.WsPong{Type: "pong"})
+
+		case "query":
+			var msg models.WsQuery
+			if err := json.Unmarshal(message, &msg); err != nil {
+				_ = client.sendJSON(models.WsError{
+					Type:      "error",
+					Code:      "INVALID_MESSAGE",
+					Message:   "invalid query message",
+					RequestID: msg.RequestID,
+				})
+				continue
+			}
+			log.Printf("query received: session=%s request=%s", sessionID, msg.RequestID)
+			// TODO: 调用 AI 编排流程（STT → LLM → TTS）
+
+		case "config":
+			var msg models.WsConfig
+			if err := json.Unmarshal(message, &msg); err != nil {
+				_ = client.sendJSON(models.WsError{
+					Type:    "error",
+					Code:    "INVALID_MESSAGE",
+					Message: "invalid config message",
+				})
+				continue
+			}
+			log.Printf("config update: session=%s", sessionID)
+			// TODO: 更新会话配置
+
+		case "interrupt":
+			log.Printf("interrupt received: session=%s", sessionID)
+			// TODO: 中断当前 AI 响应
+
+		default:
+			_ = client.sendJSON(models.WsError{
+				Type:    "error",
+				Code:    "INVALID_MESSAGE",
+				Message: "unknown message type: " + envelope.Type,
+			})
+		}
+	}
+
+	close(done)
+	log.Printf("client disconnected: session=%s", sessionID)
+}
--- 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": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "uuid": "^14.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.3",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "@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()],
+})