ttstd-infinite-canvas/web/src/components/conversation/IMPLEMENTATION.md

实时对话功能实现（第一阶段 MVP）

项目概述

实现第一阶段（MVP）：本地语音录制 + 浏览器语音识别转写。点击"实时对话"按钮 → 输入行内展开波形录制条 → 停止后自动转写为文字 → 文字填入输入框或直接发送。

第一阶段不接入语音大模型、不依赖后端与 API Key，转写由浏览器内置 Web Speech API 完成，零配置可用。

---

交互流程

1. 点击"实时对话"按钮（VoiceRecordingButton）
2. 输入行内展开 VoiceRecordingInline 录制条（不弹窗），自动开始录音
3. 显示波形动画（AnalyserNode 实时音量）+ 时长
4. 点击停止 → 停止录音并触发浏览器语音识别
5. 识别成功 → 短暂显示"转写完成" → 回调文本，由调用方填入输入框或直接发送
6. 识别失败（无语音 / 权限拒绝 / 网络异常）→ 录制条内提示并支持重试

---

技术架构

用户点击"实时对话"按钮
        │
        ▼
VoiceRecordingButton（输入行内展开录制条，不弹窗）
        │
        ▼
VoiceRecordingInline 内联波形录制条
        ├── useVoiceRecording：MediaRecorder 录制 + AnalyserNode 实时波形
        ├── AudioWaveform：SVG 波形动画 + 时长显示
        └── useSpeechRecognition：Web Speech API 实时转写
                │
                ▼
点击停止 → speech.stop() 返回文本 → onTranscribed(文本) → 填入输入框

前端实现

组件

文件	说明
components/conversation/voice-recording-button.tsx	语音输入按钮：点击后输入行内展开录制条（局部状态，不弹窗）
components/conversation/voice-recording-inline.tsx	内联波形录制条：波形 + 时长 + 停止/取消，停止后自动转写
components/conversation/audio-waveform.tsx	SVG 波形可视化组件
components/conversation/index.ts	组件统一导出

Hook

文件	说明
hooks/use-voice-recording.ts	语音录制逻辑（MediaRecorder + AnalyserNode，波形/时长/停止/取消）
hooks/use-speech-recognition.ts	浏览器语音识别（Web Speech API，start/stop/cancel，返回文本与错误）

接入位置

• 创建页主输入行：web/src/pages/create/index.tsx（CreationComposer 的 creation-chat-controls）
• 画布 Agent 面板：canvas-cloud-agent-panel.tsx（输入行 left 插槽）
• 测试页：web/src/pages/test-voice-recording.tsx（路由 /test-voice-recording）

使用示例

import { VoiceRecordingButton } from "@/components/conversation/voice-recording-button";

<VoiceRecordingButton
  disabled={isBusy}
  onTranscribed={(text) => setPrompt((prev) => (prev.trim() ? `${prev} ${text}` : text))}
/>

浏览器支持

• 语音识别使用 Web Speech API（SpeechRecognition / webkitSpeechRecognition），Chrome / Edge 支持
• 不支持时录制条内提示"当前浏览器不支持语音识别，请使用 Chrome 或 Edge 浏览器"，并可取消
• 识别语言默认 zh-CN，可通过 useSpeechRecognition({ lang }) 调整

已删除内容

以下第二阶段实验代码已全部删除：

前端

• components/conversation/realtime-conversation.tsx、realtime-conversation-button.tsx、voice-recording-overlay.tsx
• hooks/use-websocket.ts、stores/conversation-mode-store.ts
• services/api/stt.ts（后端 Whisper 转写客户端）

后端

• service/stt.go（OpenAI Whisper 转写）、model/stt.go（stt_results 表）
• handler/routes.go 中 RegisterSTTRoutes、main.go 中路由注册
• database/schema.go 中 STTResult 模型注册、repository/repository.go 中 CreateSTTResult

验证情况

• 后端 go build ./...：通过
• 前端 npx tsc --noEmit：无本次新增类型错误（上游遗留 style profile / image.ts 错误除外）
• 浏览器手动测试（真实麦克风 + 语音识别）未运行，需在 Chrome/Edge 下验证

下一步

• 内联波形录制 + 浏览器语音识别自动转写（第一阶段 MVP）
• 移除第二阶段实验代码（WebSocket / WebRTC / Realtime API）
• 语音播放功能（TTS）
• 语音消息发送和显示
• 真正实时对话（WebSocket + WebRTC + Realtime API，后续阶段）