语音输入法（dudu）

变更记录

目录

一、产品概述与 MVP 需求

一款付费语音输入法，核心卖点：大模型识别准确度 + 流式实时上屏 + 极简交互。

二、关键技术决策

三、总体架构

┌─────────────┐   ┌─────────────┐   ┌──────────────────┐
│ 桌面端 Tauri │   │ iOS/Android │   │                  │
│ Mac/Windows │   │  键盘扩展    │   │   微信开放平台    │
└──────┬──────┘   └──────┬──────┘   │ (OAuth/支付回调)  │
       │  WSS 音频流      │          └────────┬─────────┘
       ▼                 ▼                   │
┌──────────────────────────────────────────────────────┐
│                  Go 后端（单体起步）                    │
│  ┌─────────┐ ┌───────────┐ ┌─────────┐ ┌──────────┐  │
│  │  auth   │ │asr-gateway│ │ billing │ │  quota   │  │
│  │ 微信登录 │ │ WS 流式中继│ │ 微信支付 │ │ 用量/配额 │  │
│  └─────────┘ └─────┬─────┘ └─────────┘ └──────────┘  │
└────────────────────┼─────────────────────────────────┘
                     │ WSS（同区域部署，内网级延迟）
                     ▼
          ┌─────────────────────┐     ┌──────────────┐
          │ 阿里云百炼 Gummy     │     │ PostgreSQL   │
          │ （流式大模型 ASR）   │     │ + Redis      │
          └─────────────────────┘     └──────────────┘

四、后端设计（Go）

4.1 技术栈与部署

• gin（HTTP API）+ gorilla/websocket（流式网关）
• PostgreSQL（用户/订单/时长账本）+ Redis（配额计数、登录轮询状态）
• wechatpay-go 官方 SDK
• 部署：阿里云（与百炼同区域）、Docker、单体应用起步

4.2 模块划分

server/
  cmd/server/main.go
  internal/
    auth/        微信 OAuth（扫码 + App 登录）、JWT 签发与中间件
    asr/         Provider 接口 + gummy / volcano 两个实现
    gateway/     WS /v1/asr/stream 处理器（核心）
    billing/     微信支付下单、回调验签、订单状态机
    quota/       用量计量（Redis INCR + 异步落库）、试用/余额校验
    user/        用户、设备 CRUD、时长包查询
    store/       gorm models + migrations
  pkg/protocol/  客户端协议常量与消息结构（5 端对齐的唯一真相源）

4.3 ASR Provider 抽象（可切换的关键）

type Provider interface {
    // 建立一次流式识别会话
    StartSession(ctx context.Context, cfg SessionConfig) (Session, error)
}
type Session interface {
    SendAudio(pcm []byte) error   // 推 100ms 音频帧
    Results() <-chan Result       // {Text, IsFinal, BeginTime, EndTime}
    Close() error
}

MVP 实现 gummy provider（DashScope WebSocket API，原生流式、自带标点和 ITN、中英混说）。

4.4 客户端 ↔ 后端流式协议（WSS /v1/asr/stream）

鉴权：连接时带 Authorization: Bearer <JWT>。连接为长连接 + ping/pong 心跳，客户端启动时即预连接，按下快捷键时零握手开销。

4.5 微信登录

用 unionid 关联同一用户的多端身份（桌面扫码与手机 App 登录是两个不同 openid）。

4.6 微信支付与计费

• 桌面端：Native 支付（后端下单返回 code_url → 客户端展示二维码）
• 移动端：APP 支付（主 App 拉起微信收银台）
• 回调 POST /v1/pay/notify：验签 → 订单状态机（pending → paid）→ 时长入账
• 计费模型（v0.2）：时长包不过期（100 分钟 ¥9 / 500 分钟 ¥39 / 2000 分钟 ¥129）+ 每天免费试用 3 分钟；用量按识别音频秒数计、先扣试用再扣余额，用尽时网关下发 QUOTA_EXCEEDED。详见后端与数据架构 v1.0 第五章

4.7 核心数据表

users、wechat_identities、duration_packs、orders、balance_ledger（时长账本）、trial_usage（每日试用）、asr_sessions、devices

五、存储选型说明

一句话总结：PostgreSQL 管"钱和账"（强一致、持久），Redis 管"快和临时"（计数器、带过期时间的状态）。

PostgreSQL — 持久化业务数据（不能丢的数据）

特点：写入频率低、绝对不能丢，且需要事务（"回调到账 → 订单置为已支付 → 时长入账"必须原子完成）。

Redis — 高频、短生命周期的热数据

1. 实时配额计数：识别过程中每隔几秒累计用量并校验是否超额。每帧都查 PostgreSQL 既扛不住也拖慢链路，故用 Redis INCR 实时计数，后台异步批量落库到 balance_ledger / asr_sessions；
2. 扫码登录轮询状态：桌面端展示二维码后轮询"扫了没"，state 只活 2 分钟，天然适合带 TTL 的 key；
3. JWT 黑名单 / 会话踢出：退出登录、账号踢出立即生效。

六、桌面端设计（Tauri 2 + Rust）

6.1 核心交互流程（push-to-talk）

按下快捷键 → 浮层弹出（光标附近）→ 采集音频流式上传
→ partial 结果实时显示在浮层 → 松开快捷键
→ final 注入焦点输入框 → 浮层消失

6.2 Rust 侧模块

6.3 前端 UI（Web 技术）

• 设置窗口：快捷键自定义、麦克风选择、登录状态、购买时长（Native 支付二维码）
• 浮层窗口：识别文本 + 波形动画
• 常驻系统托盘，开机自启

七、移动端设计（系统输入法扩展）

7.1 iOS / iPadOS（同一套代码）

• 主 App（SwiftUI）：微信登录、购买时长（微信 APP 支付）、输入法启用引导；
• Keyboard Extension（UIInputViewController）：键盘上一个大麦克风按钮，按住说话 → 浮动文本区实时显示 partial → 松开后 final 经 textDocumentProxy.insertText 上屏；
• 需开启完全访问权限（联网必需）；token 通过 App Group 与主 App 共享。

7.2 Android

• 主 App（Kotlin + Compose）：登录、支付、启用引导；
• IME Service（InputMethodService）：自绘键盘 + 按住说话，RECORD_AUDIO 权限即可在 IME 内录音（无 iOS 式限制），currentInputConnection.commitText 上屏，成熟可控。

实施顺序：先 Android 后 iOS（风险低、验证快）。两端不引入跨端框架，Swift / Kotlin 各自原生实现协议（对齐 server/pkg/protocol）。

八、各终端简要设计（界面与交互）

8.1 桌面端（Mac / Windows）

界面清单：① 识别浮层② 系统托盘菜单③ 设置窗口④ 登录/购买窗口

① 识别浮层（核心界面，两态）

按下快捷键瞬间弹出在光标附近，不抢焦点；松开快捷键注入文字后淡出。

② 系统托盘菜单 + ③ 设置窗口

④ 登录 / 购买窗口

• 登录：窗口内展示微信二维码（后端 /v1/auth/qr），手机扫码授权后自动登录并关闭；
• 购买：选套餐（月/年）→ 展示微信 Native 支付二维码 → 支付完成自动刷新订阅状态；
• 首次启动流程：欢迎页 → 授予权限（macOS 辅助功能 + 麦克风）→ 微信登录 → 试一试（引导用户在示例输入框里按快捷键说一句话）。

8.2 移动端键盘扩展（iOS / Android 布局一致）

界面清单：① 键盘面板（核心）② 候选/partial 文本条③ 未登录/超额提示态

MVP 键盘策略：以语音为主键盘——大麦克风按键 + 一行常用功能（切回系统键盘、退格、回车、标点），不做完整 26 键（降低开发量，用户在语音和系统键盘间一键切换）。

键盘交互细节

• 按住说话，松开上屏；上滑取消本次输入（微信语音的肌肉记忆）；
• 流式上屏策略：final 句子即时 insertText 上屏，partial 显示在键盘自带的文本条里（不直接写入宿主输入框，避免修正抖动）；
• 未登录态：麦克风按键置灰，点击提示"打开 dudu App 登录"（deep link 跳主 App）；
• 超额态：按键变橙色提示"今日免费额度已用完，升级会员"。

8.3 移动端主 App（iOS / Android）

界面清单：① 启用引导页② 登录页③ 套餐购买页④ 我的（用量/订阅管理）

8.4 iPad 适配要点

• 与 iPhone 同一个 Keyboard Extension target，键盘布局按 size class 自适应（横屏时麦克风键加宽、功能键拉开间距）；
• 支持悬浮键盘（floating keyboard）形态下的紧凑布局；
• 主 App 用 SwiftUI 自适应布局，无需单独开发。

九、延迟优化清单（贯穿各端）

1. 客户端 WS 启动即预连接 + 心跳保活，按键时零握手；
2. 100ms 帧直推，客户端不做缓冲聚合；
3. 后端与 ASR 同区域部署，中继 goroutine 零拷贝转发；
4. 浮层/键盘 UI 在按键瞬间先进入"聆听中"态，不等首个结果；
5. 埋点指标：按键 → 首个 partial（目标 P95 < 500ms）、松开 → final 注入（目标 < 300ms）。

十、仓库结构（monorepo）

dudu/
  server/      Go 后端
  desktop/     Tauri 2（Mac + Windows）
  android/     Kotlin：主 App + IME Service
  ios/         Swift：主 App + Keyboard Extension
  docs/        协议文档、架构决策记录

十一、里程碑

十二、风险与验证

主要风险

验证方式

• 后端：go test ./...；测试脚本推送 wav 文件模拟音频流，断言收到 partial/final 序列；微信支付用沙箱/模拟回调测试订单状态机；
• 桌面端：本地起 server 真实说话验证全链路；在备忘录/浏览器/IDE 等不同应用验证注入兼容性；记录 P95 首字延迟；
• 移动端：Android 真机在微信/备忘录中切换到本输入法验证上屏；iOS TestFlight 验证完全访问权限流程；
• 计费：构造超额场景验证 QUOTA_EXCEEDED 下发与客户端提示。