asr-tech-stack.md

自进化语音输入（ASR）— 技术栈总览

文档类型：开源设计想法 · 非绑定任何内部产品 · 尚无对应开源仓库
架构主文档：asr-architecture.md
版本：v2.0 · 2026-07

---

1. 分层与技术选型

层	推荐技术	职责
Client UI	Vue 3 / React + TypeScript	麦克风 UI、设置页、session 状态展示
Client 逻辑	纯 TS 模块（可单测）	HotwordAdapter、ReplacementEngine、VoiceSession
音频采集	getUserMedia + AudioWorklet 或 ScriptProcessor	16 kHz mono PCM 分块
流式 ASR	WebSocket（云 Provider 或自托管 FunASR 等）	实时上行 / progressive·sentence 下行
Agent 服务	Node.js ESM + 自研 HTTP	/voice/normalize、/voice/learning
LLM	OpenCode SDK、session.prompt + structured output	整理与自学习分析
本地配置	localStorage / Electron userConfig	Provider、热词、错词规则
本地历史	SQLite（better-sqlite3）或 IndexedDB	三版文本、session、LearningSnapshot
桌面握手	可选 Electron preload	为 WS 注入 Header / 代理（若 Provider 要求）

约束：normalize / learning 走 同步 HTTP，不复用主对话 SSE，避免与 chat 队列互斥。

---

2. 领域模块（逻辑名 → 职责）

client/voice/
├── hotword-adapter.ts      # Provider → 传参
├── replacement-engine.ts   # 下行文本规则替换
├── voice-session.ts        # 一整次 session 状态机
├── voice-agent-client.ts   # normalize HTTP 客户端
├── voice-learning-client.ts
└── types.ts

agent/http/
├── voice-normalize-routes.ts
└── voice-learning-routes.ts

UI 层 composable / hook 组合上述模块；core 禁 直接依赖 DOM 框架（便于 Vitest）。

---

3. ASR Provider 插件位

Provider 类型	协议	HotwordAdapter 输出
URL 热词型	WSS + gRPC 或 binary	query hotWords=词1;词2
词表权重型	WSS JSON	{ "hotwords": [{ "word", "weight" }] }
Whisper 类	HTTP / WS	initial_prompt 拼接
本地 FunASR	ws://127.0.0.1:... 2pass	依 FunASR 文档

新增 Provider = 实现 Adapter 接口 + 设置 UI 一项，不改动三版文本 / 自学习核心。

---

4. 数据与通信

通道	技术	用途
实时 ASR	WebSocket	识别流
normalize	HTTP POST JSON	单次整理
learning	HTTP POST/GET	样本 / status
配置	KV 存储	Provider、规则
历史	SQLite / IDB	三版文本、快照
上下文	内存 session store	normalize 带最近 Q&A

---

5. 测试

类型	工具	覆盖
单元	Vitest	ReplacementEngine、HotwordAdapter、session FSM
集成	mock WS + mock normalize	useVoiceRecognition 主路径
Agent	supertest 或 fetch mock	normalize / learning 路由

---

6. 实验工具链（可选，与主应用解耦）

类别	技术	用途
脚本	Node.js（tsx）、TypeScript	批量探针、manifest 驱动 A/B
音频	ffmpeg-static、ws	转码、重放 PCM
分析	Python（matplotlib、pandas）	字错率曲线
数据集	Common Voice 等公开集	离线对比

本地 FunASR：Python venv + PyTorch + 官方 FunASR 仓库（Windows / Linux 脚本均可）。

---

7. 三阶段技术增量

阶段	增量
I	Client + Agent HTTP + 本地 KV/SQLite 全闭环
II	配置 / 三版文本 / 快照 对象存储；可选服务端 learning
III	第二入口只读接入同一 Provider 与 normalize API

Phase II 可整体暂缓；Phase I 接口预留 cloudSync 字段即可。

---

维护说明：新增 Provider 或存储后端时，同步更新本文与 architecture §7–§9。