Update code

test2/ARCHITECTURE.md

@@ -0,0 +1,440 @@
+# BigWo 智能语音对话系统 — 系统架构文档
+
+> 版本：1.0 | 更新日期：2026-03-09
+
+---
+
+## 1. 系统概述
+
+BigWo 是一个**企业级智能客服对话系统**，支持**语音通话**和**文字对话**两种交互模式，可无缝切换且保持上下文连续。
+
+### 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| 实时语音对话 | 火山引擎 RTC + S2S 端到端语音大模型，混合编排模式 |
+| 知识库问答 | Function Calling → 方舟私域知识库 → 本地知识库 |
+| 文字对话 | Coze v3 Chat API，支持 SSE 流式输出 |
+| 语音↔文字切换 | 同一 sessionId 贯穿，MySQL 持久化完整历史 |
+| 工具调用 | 知识库检索、天气、订单、时间、计算 |
+
+### 技术栈
+
+- **前端**：React 18 + Vite 5 + TailwindCSS 4 + Lucide Icons
+- **后端**：Node.js + Express 4 (port 3012)
+- **语音**：@volcengine/rtc SDK + S2S 端到端 + 方舟 LLM (API v2024-12-01)
+- **文字**：Coze v3 Chat API（流式 SSE）
+- **知识库**：方舟 Chat Completions API + knowledge_base metadata
+- **数据库**：MySQL 8 (mysql2/promise)
+- **部署**：PM2 (cluster) + Nginx 反向代理 + 宝塔面板
+
+---
+
+## 2. 系统架构图
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      浏览器客户端                         │
+│  ┌────────────┐  ┌───────────┐  ┌──────────────────┐   │
+│  │ VoicePanel │  │ ChatPanel │  │  SettingsPanel   │   │
+│  └─────┬──────┘  └─────┬─────┘  └──────────────────┘   │
+│        │               │                                │
+│  ┌─────▼──────┐  ┌─────▼─────┐  ┌────────────────┐    │
+│  │useVoiceChat│  │  chatApi  │  │   voiceApi     │    │
+│  │  (Hook)    │  │ (HTTP/SSE)│  │  (HTTP 封装)   │    │
+│  └─────┬──────┘  └─────┬─────┘  └────────────────┘    │
+│        │               │                                │
+│  ┌─────▼──────┐        │                                │
+│  │ rtcService │        │                                │
+│  │(WebRTC SDK)│        │                                │
+│  └─────┬──────┘        │                                │
+└────────┼───────────────┼────────────────────────────────┘
+         │ WebRTC        │ HTTPS
+         │ 音频流         │ REST/SSE
+         ▼               ▼
+┌────────────────┐  ┌─────────────────────────────────────┐
+│ 火山引擎 RTC   │  │       Express 后端 (port 3012)       │
+│ 云端服务       │  │                                     │
+│ ┌────────────┐ │  │  routes/voice.js  — 语音全生命周期   │
+│ │S2S 端到端  │ │  │  routes/chat.js   — 文字对话        │
+│ │语音大模型  │ │  │  routes/session.js — 会话管理        │
+│ ├────────────┤ │  │                                     │
+│ │方舟 LLM   │ │  │  services/volcengine.js  — OpenAPI  │
+│ │(工具决策)  │ │  │  services/toolExecutor.js — 工具    │
+│ └─────┬──────┘ │  │  services/cozeChatService.js — Coze │
+│       │FC 回调  │  │  services/arkChatService.js — 方舟  │
+│       │(HTTP)   │  │  config/voiceChatConfig.js — 配置   │
+│       ▼         │  │  db/index.js — MySQL                │
+│  fc_callback ──►│  │                                     │
+│  ◄── Update ────│  └─────────────────────────────────────┘
+└────────────────┘           │
+                             ▼
+                    ┌─────────────────┐     ┌──────────────┐
+                    │   MySQL 8       │     │ 方舟知识库   │
+                    │ sessions 表     │     │ (远程 API)   │
+                    │ messages 表     │     └──────────────┘
+                    └─────────────────┘
+```
+
+---
+
+## 3. 目录结构
+
+```
+test2/
+├── client/                        # 前端（React + Vite）
+│   ├── src/
+│   │   ├── App.jsx                # 主应用，语音/文字模式切换
+│   │   ├── components/
+│   │   │   ├── VoicePanel.jsx     # 语音通话界面
+│   │   │   ├── ChatPanel.jsx      # 文字对话界面（SSE 流式）
+│   │   │   ├── SettingsPanel.jsx  # 语音参数设置面板
+│   │   │   └── SubtitleDisplay.jsx# 实时字幕展示
+│   │   ├── hooks/
+│   │   │   └── useVoiceChat.js    # 语音通话核心 Hook
+│   │   └── services/
+│   │       ├── rtcService.js      # RTC SDK 封装（WebRTC）
+│   │       ├── voiceApi.js        # 语音 HTTP 请求
+│   │       └── chatApi.js         # 文字 HTTP/SSE 请求
+│   └── vite.config.js
+├── server/                        # 后端（Express）
+│   ├── app.js                     # 入口 + FC 回调 raw body 解析
+│   ├── routes/
+│   │   ├── voice.js               # 语音全生命周期 + FC 回调（核心）
+│   │   ├── chat.js                # 文字对话（Coze）
+│   │   └── session.js             # 会话历史 & 模式切换
+│   ├── services/
+│   │   ├── volcengine.js          # 火山引擎 OpenAPI 签名调用
+│   │   ├── toolExecutor.js        # 工具执行器
+│   │   ├── arkChatService.js      # 方舟 LLM（文字场景备选）
+│   │   └── cozeChatService.js     # Coze Chat API（文字主服务）
+│   ├── config/
+│   │   ├── voiceChatConfig.js     # StartVoiceChat 配置构建器
+│   │   └── tools.js               # FC 工具定义（5 个工具）
+│   ├── db/index.js                # MySQL CRUD
+│   ├── lib/token.js               # RTC Token 生成
+│   └── .env                       # 环境变量
+└── ecosystem.config.js            # PM2 部署配置
+```
+
+---
+
+## 4. 语音通话模块
+
+### 4.1 混合编排模式（OutputMode=1）
+
+S2S 端到端模型处理普通闲聊（低延迟 ~300-800ms），方舟 LLM 同时决策是否需要调用工具。两者并行运行。
+
+### 4.2 会话生命周期
+
+```
+POST /prepare  →  创建房间 + 生成 RTC Token + 分配 TaskId
+      ↓
+客户端 joinRoom()  →  用户进入 RTC 房间、开启麦克风
+      ↓
+POST /start  →  构建配置 → StartVoiceChat API → AI Bot 进房
+      ↓
+   实时语音对话（S2S 直接回复 + LLM 工具决策）
+      ↓
+POST /stop  →  StopVoiceChat API → 返回字幕 → 可切换文字模式
+```
+
+### 4.3 语音 API 端点（voice.js）
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/voice/config` | GET | 获取模型、音色列表 |
+| `/api/voice/prepare` | POST | 创建房间、生成 Token |
+| `/api/voice/start` | POST | 启动 AI 语音对话 |
+| `/api/voice/stop` | POST | 停止对话、返回字幕 |
+| `/api/voice/fc_callback` | POST | FC 回调（RTC 服务端→服务端） |
+| `/api/voice/subtitle` | POST | 客户端转发确认字幕 |
+| `/api/voice/room_message` | POST | 客户端转发 RTC 房间消息 |
+
+### 4.4 内存数据映射
+
+voice.js 维护以下 Map 用于会话状态关联：
+
+| Map 名称 | Key | Value | 用途 |
+|----------|-----|-------|------|
+| `activeSessions` | sessionId | 完整会话对象 | 会话生命周期管理 |
+| `roomToBotUserId` | roomId | botUserId | FC 回调→UpdateVoiceChat |
+| `roomToHumanUserId` | roomId | userId | 日志追踪 |
+| `roomToSessionId` | roomId | sessionId | DB 写入关联 |
+| `roomToTaskId` | roomId | taskId | **UpdateVoiceChat 必须用此 TaskId** |
+| `latestUserSpeech` | roomId | {text, timestamp} | FC 参数解析兜底 |
+| `toolCallBuffers` | TaskID | buffer 对象 | FC chunk 收集 |
+
+---
+
+## 5. Function Calling 回调处理（核心）
+
+### 5.1 数据流
+
+```
+RTC 服务 (LLM 触发 tool_call)
+    │ HTTP POST（无 Content-Type，body 为 JSON）
+    ▼
+app.js 手动读取 raw body → JSON.parse → 分配 _seq 序列号
+    │
+    ▼
+voice.js fc_callback 路由
+    │
+    ├─ FormatA: Type="tool_calls" → OpenAI 格式数组，流式 chunk
+    ├─ FormatB: Type="information" → RTC 原生格式
+    └─ FormatC: 会话状态回调 → 记录日志
+    │
+    ▼（FormatA 为主）
+chunk 缓冲收集（toolCallBuffers Map，1s 超时触发）
+    │
+    ▼ 1s 后
+参数解析尝试链：
+    ① JSON.parse(拼接 chunks)
+    ② latestUserSpeech（ASR 用户语音兜底）
+    ③ extractReadableText（从 chunks 提取中文字符）
+    │
+    ▼
+发送 interrupt 打断 S2S 直接回复
+    │  UpdateVoiceChat({ Command: "interrupt", TaskId: sessionTaskId })
+    ▼
+执行工具（toolExecutor.js）
+    │  search_knowledge: 方舟 KB(30s) → 本地 KB
+    ▼
+回传结果
+    │  UpdateVoiceChat({
+    │    Command: "function",
+    │    TaskId: sessionTaskId,    ← 必须是 StartVoiceChat 的 TaskId
+    │    Message: JSON.stringify({ ToolCallID, Content })
+    │  })
+    ▼
+AI 用知识库内容语音回复
+```
+
+### 5.2 关键设计决策
+
+| 问题 | 解决方案 |
+|------|----------|
+| FC 回调无 Content-Type | app.js 在 express.json() 之前手动读取 raw body |
+| Chunk 乱序且不完整 | 1s 定时器收集全部 chunks 后拼接 |
+| JSON.parse 失败 | 用 ASR 用户语音文本作为查询参数（方案B） |
+| S2S 直接回复覆盖 FC 结果 | 先发 interrupt 打断，再发 function 结果 |
+| TaskId 不匹配 | roomToTaskId 存储 StartVoiceChat 的 TaskId |
+| HTTP 响应超时 | 立即返回 200，异步执行工具 |
+
+### 5.3 用户语音文本获取（方案B）
+
+FC 回调的 arguments 经常乱序无法解析，因此需要从其他途径获取用户的原始问题：
+
+```
+客户端 RTC SDK
+    │ onSubtitleMessageReceived / onRoomBinaryMessageReceived
+    ▼
+useVoiceChat.js
+    │ 转发 definite=true 的用户字幕
+    ▼
+POST /api/voice/subtitle    →  latestUserSpeech.set(roomId, text)
+POST /api/voice/room_message →  解析二进制消息中的字幕数据
+```
+
+---
+
+## 6. 文字对话模块
+
+### 6.1 架构
+
+通过 **Coze v3 Chat API** 实现，Coze Bot 内置知识库插件。
+
+```
+用户输入 → POST /api/chat/send-stream
+    ↓
+cozeChatService.chatStream()
+    │ 首次对话注入语音历史作为上下文
+    │ Coze 自动管理 conversation_id
+    ↓
+SSE 流式返回 → 前端逐字展示
+```
+
+### 6.2 文字 API 端点（chat.js）
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/chat/start` | POST | 创建会话，注入语音历史上下文 |
+| `/api/chat/send` | POST | 非流式发送 |
+| `/api/chat/send-stream` | POST | SSE 流式发送 |
+| `/api/chat/history/:id` | GET | 获取会话状态 |
+| `/api/chat/:id` | DELETE | 删除会话 |
+
+---
+
+## 7. 会话管理与模式切换
+
+### 7.1 统一 sessionId
+
+同一个 sessionId 贯穿语音和文字模式，所有消息持久化到 MySQL messages 表。
+
+### 7.2 消息来源标记
+
+| source 值 | 说明 |
+|-----------|------|
+| `voice_asr` | 语音 ASR 识别的用户文本 |
+| `voice_bot` | AI 语音回复字幕 |
+| `voice_tool` | 语音场景工具调用结果 |
+| `chat_user` | 文字对话用户输入 |
+| `chat_bot` | 文字对话 AI 回复 |
+
+### 7.3 模式切换 API（session.js）
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/session/:id/history` | GET | 获取完整历史（支持 llm/full 格式） |
+| `/api/session/:id/switch` | POST | 切换模式，返回上下文历史 |
+
+### 7.4 数据库表
+
+**sessions**：`id(PK)`, `user_id`, `mode(voice/chat)`, `created_at`, `updated_at`
+
+**messages**：`id(AI PK)`, `session_id`, `role(user/assistant/tool/system)`, `content`, `source`, `tool_name`, `created_at`
+
+---
+
+## 8. 客户端组件
+
+### 8.1 组件树
+
+```
+App.jsx                    # 模式切换 + 全局设置
+├── VoicePanel.jsx         # 语音通话 UI（开始/结束/静音/时长）
+│   └── SubtitleDisplay    # 实时字幕（definite/interim 区分）
+├── ChatPanel.jsx          # 文字对话 UI（消息列表 + SSE 流式显示）
+└── SettingsPanel.jsx      # 设置面板（模型/音色/系统角色/VAD）
+```
+
+### 8.2 useVoiceChat Hook
+
+管理语音通话完整生命周期：
+
+- **start(options)**：prepare → joinRoom → startVoiceChat
+- **stop()**：leaveRoom → stopVoiceChat → 返回字幕
+- **toggleMute()**：静音/取消静音
+- **状态**：isActive, isMuted, isConnecting, subtitles, duration, error
+
+### 8.3 rtcService.js
+
+封装 @volcengine/rtc SDK：
+
+- **init(appId)**：创建引擎、注册事件监听
+- **joinRoom()**：入房 + 开始音频采集 + 启用字幕
+- **事件监听**：字幕(onSubtitleMessageReceived)、房间消息(binary/text)、诊断(音量/流)
+- **方案B 消息转发**：所有房间消息 → onRoomMessage 回调 → useVoiceChat → 后端
+
+---
+
+## 9. 环境变量
+
+### 必需
+
+| 变量 | 说明 |
+|------|------|
+| `VOLC_RTC_APP_ID` | RTC 应用 ID |
+| `VOLC_RTC_APP_KEY` | RTC 应用密钥（生成 Token） |
+| `VOLC_ACCESS_KEY_ID` | 火山引擎 AK（API 签名） |
+| `VOLC_SECRET_ACCESS_KEY` | 火山引擎 SK |
+| `VOLC_S2S_APP_ID` | S2S 端到端语音 AppID |
+| `VOLC_S2S_TOKEN` | S2S Token |
+| `VOLC_ARK_ENDPOINT_ID` | 方舟 LLM 推理接入点 ID |
+
+### 可选
+
+| 变量 | 说明 |
+|------|------|
+| `COZE_API_TOKEN` | Coze 智能体 Token（文字对话） |
+| `COZE_BOT_ID` | Coze Bot ID |
+| `VOLC_ARK_KNOWLEDGE_BASE_IDS` | 方舟私域知识库数据集 ID（逗号分隔） |
+| `VOLC_ARK_API_KEY` | 方舟 API Key |
+| `VOLC_WEBSEARCH_API_KEY` | 联网搜索 Key |
+| `FC_SERVER_URL` | FC 回调地址 |
+| `FC_SIGNATURE` | FC 回调签名 |
+| `MYSQL_HOST/PORT/USER/PASSWORD/DATABASE` | MySQL 配置 |
+
+---
+
+## 10. 部署架构
+
+```
+互联网用户
+    │
+    ▼ HTTPS (443)
+┌──────────────┐
+│   Nginx      │  ← 宝塔面板管理
+│  (反向代理)   │
+│  SSL 终止    │
+└──────┬───────┘
+       │ http://localhost:3012
+       ▼
+┌──────────────┐
+│   PM2        │  ← ecosystem.config.js
+│  bigwo-server│
+│  (Node.js)   │
+└──────┬───────┘
+       │
+       ├── MySQL 8 (localhost:3306)
+       ├── 火山引擎 RTC API (rtc.volcengineapi.com)
+       ├── 方舟 LLM API (ark.cn-beijing.volces.com)
+       └── Coze API (api.coze.cn)
+```
+
+### PM2 配置
+
+- 进程名：`bigwo-server`
+- 工作目录：`/www/wwwroot/demo.tensorgrove.com.cn/server`
+- 日志路径：`/var/log/bigwo/server-out.log`、`server-error.log`
+- 内存限制：512M 自动重启
+
+---
+
+## 11. 工具定义（tools.js）
+
+系统定义了 5 个 Function Calling 工具：
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `search_knowledge` | query: string | **核心工具**，强制优先调用 |
+| `query_weather` | city: string | 天气查询（Mock） |
+| `query_order` | order_id: string | 订单查询（Mock） |
+| `get_current_time` | 无 | 当前时间 |
+| `calculate` | expression: string | 数学计算 |
+
+### search_knowledge 查询链
+
+```
+方舟私域知识库 (30s 超时)
+  │ POST https://ark.cn-beijing.volces.com/api/v3/chat/completions
+  │ metadata.knowledge_base: { dataset_ids, top_k: 3, threshold: 0.5 }
+  │
+  │ 失败 ↓
+  ▼
+本地知识库 (即时，关键词匹配)
+  │ 覆盖：退货、退款、配送、保修、会员
+```
+
+---
+
+## 12. 安全与限制
+
+- **API 签名**：所有火山引擎 API 调用使用 AK/SK HMAC 签名
+- **FC 回调签名**：ServerSignature 校验（当前信任模式）
+- **计算工具防注入**：仅允许 `0-9 + - * / ( ) . %` 字符
+- **CORS**：已开启（`cors()` 中间件）
+- **Body 限制**：1MB
+- **会话过期**：文字对话 30 分钟自动清理
+- **环境变量**：敏感信息存于 `.env`，启动时校验
+
+---
+
+## 13. 已知问题与优化方向
+
+1. **FC 响应延迟**：用户提问到 AI 用知识库回答约需 12-15s（LLM 决策 ~8s + KB 查询 ~5s），期间有静默
+2. **Chunk 乱序**：RTC FC 回调的 tool_call arguments 被拆成单字符 chunk 且乱序，只能靠 ASR 文本兜底
+3. **S2S 与 LLM 并行冲突**：S2S 会先给出直接回复，需 interrupt 打断后再发 FC 结果
+4. **Mock 工具**：天气和订单工具目前为 Mock 数据，可接入真实 API
+5. **知识库冷启动**：方舟 KB 首次查询较慢（~10s），后续查询 ~3-5s