用途与实际影响
这项功能怎样使用
为什么需要它
说话打字最怕文字落进另一个窗口、麦克风被悄悄切换，或点了收起却仍在录音。这个入口将显示、采音、识别和输入落点分开，让本人能随时暂停和取消；它不为追求顺口而自动润色或回车发送。
举个实际例子
“这段邮件我想口述，识别好先放进编辑框，不要发送。”在当前编辑位置启动听写，文字分段输入；窗口焦点变了就停止后续输入，自己检查后再决定发送。
最后我会得到什么
得到当前应用中的文字和面板状态；取消只丢弃尚未提交的片段，不能撤销已经输入的字。
正常时
录音按钮变绿表示正在采音；有效语句识别完成、原焦点仍合适时输入整句文字。本人控制下一段、暂停和最后发送。
发现问题时
焦点变化或管理员窗口拒绝输入时停止自动输入，保留托盘复制入口；Esc取消未输入内容，已输入部分继续留在应用里。
入口不可用或证据不足时
指定麦克风缺席、采音丢帧、模型或GPU资源不可用时显示具体问题，不改用另一麦克风或云端，不把空识别和坏声音送进输入框。
从哪里开始
点好要输入的文本框，用 Win+H 唤起听写小窗。
需要准备什么
- 当前可编辑位置
- 要口述的句子
从开始到拿到结果
- 1
系统核对并处理
小窗收这一句，停顿后由本地单模型识别；输入前再看焦点，焦点变化则停下并保留最近文本供主动复制。
- 2
交付与接续
得到编辑框文字，不自动发送；取消只丢尚未输入片段，已输入内容不会撤销。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
本轮只读任务与入口匹配；来源已验单模型公开音频和有界恢复，个人麦克风体验未重验关键规则与设计选择
开始菜单“中文听写”通知同一个托盘进程，已有实例时不会再开一份。
麦克风按钮只切录音与暂停；×隐藏并暂停、继续完成尾句；托盘退出才真正结束程序。
录音和最近文本只留内存，主动复制才写剪贴板；需要持久文件、逐段审计或恢复历史时使用文件转写路线。
登录预载模型不自动开麦；暂停保留内存模型但释放显存及租约，再次唤起仍须等待实际资源就绪。
单个Qwen3-ASR-1.7B用于听写，不改变文件quick/strict的模型选择，不承诺逐字流式或固定端到端延迟。
模型准备、GPU被合法文件任务占用和指定麦克风断开分别显示；等待保留内存音频，可Esc取消，不能为掩盖争用抢租约或偷偷切换设备。
本模块用到的名词
- VAD（语音活动检测）
- 判断这一段是否含有效语音，保留句内及前后缓冲；无语音或空识别不会输入文字。
- 原生采样率
- 麦克风实际支持的采音频率；同设备不接受16kHz时先按支持值录制，再转换完整语句。
- 单面板的显示选择
- MTT1337 已接入时优先显示，否则回到 PHLC34B 物理主屏；这是同一次听写的唯一控制窗，不是双屏并行录音。
- 最近完整文本
- 只为本次主动复制保留在内存中的识别结果，不是跨退出保存的聊天或录音档案。
专业定义
停顿后把整句文字放进原输入框；面板只显示一份，模型卡住有期限和恢复，换焦点或取消不把迟到文字塞进别处。
解决什么
防止永久停在准备中、模型调用拖住界面、迟到文字进入错误焦点、缺设备误录别的麦克风，以及收起后无意继续录音。
当前怎样实现
- 桌面入口 scripts/dictation.ps1 维护独立托盘进程，不进入文件 Smart API 的 job（任务记录） 队列；dictation.py 组织采音、分句、推理与取消，dictation_audio.py 处理输入设备，dictation_windows.py 维护 Win+H/Esc、焦点检查和文字注入。开始菜单中文听写.lnk经Start-Dictation.vbs隐藏调用Start；已运行时用同会话Start事件通知原窗口执行快捷键同一动作，未运行时由现有任务启动并最多等待30秒，不另建实例。
- configs/dictation.yaml：16 kHz、silence_ms=600、min_speech_ms=240、max_chunk_sec=20；默认指定 DJI Mic Mini，input_device: null 才跟随 Windows 默认输入。hotwords 当前为空，避免不清晰声音触发术语复读；轻量 WebRTC VAD（语音活动检测）保留语句前后缓冲，无有效语音或空识别时不输入。
- dictation_windows.py 当前面板为 200×75 实际像素；优先 MTT1337 VDD，缺席时用 PHLC34B 物理主屏，只保留一份面板并在显示变化时重定位。旧图层素材自身的 160×60 不代表实际窗口大小。
- 麦克风按钮只切录音/暂停，×隐藏并暂停且完成尾句；小箭头或右键显示设备刷新和复制入口。登录只预载内存，不自动开麦；暂停保留内存模型并释放 GPU，真正退出才释放模型。
- 设备菜单随 DPI 缩放，主面板按实际像素固定；选定麦克风下次录音重新枚举，缺设备不改用另一麦克风。本机 preferences.json 保存选择，不修改 Windows 默认设备。若同一设备不接受16kHz，尝试它报告的原生采样率；按实际采样率分句，再用resample_poly把完整语句转成模型要求的16kHz。采音丢帧或采样率未准备好时取消尚未输入内容，不把坏声音当成功。
- 听写直接使用Qwen3-ASR-1.7B，不做双模型等待或LLM润色；模型预载内存，录音推理时通过LocalGpuBroker（本地 GPU 调度器）申请ASR（自动语音识别）租约，暂停将模型放回内存并释放显存。
- 音频和最近文本不保存为历史；outputs/dictation/runtime.log仅记录错误、耗时和字数，preferences.json只保存本机麦克风选择。
- scripts/dictation.ps1的Install安装依赖、创建ChineseASR Dictation登录任务并启动；Status只读状态，Start/Stop控制现有进程，Uninstall移除登录自启但保留项目和模型。
- dictation_worker.py 把原生模型调用放入常驻受监督子进程，匿名管道传内存音频；加载180秒、操作60秒、预热40秒、停车20秒。启动最多恢复一次，未返回的一句确认进程已退出后最多重试一次；预热超时重载但不重复预热，反复失败转为可操作错误。
执行流程
- 1
本人点好输入框，从快捷键或开始菜单唤起同一听写进程。
- 2
重新枚举指定麦克风；设备支持时以16kHz采音，否则使用同设备原生采样率，再把整句转为16kHz。
- 3
在当前选定的一个屏上显示 200×75 面板；采音留内存，VAD（语音活动检测） 判断有效语句，不重复开两套控制窗。
- 4
约600ms停顿、20秒上限或手动暂停后，以单个Qwen模型识别整句。
- 5
输入前再次核对焦点与取消状态；不合适就停下自动输入，保留最近完整文本供主动复制。
- 6
暂停或隐藏后停录并处理允许的尾句，释放显存；退出结束程序并交还快捷键，下一次重新开始。
边界
- 默认指定DJI Mic Mini，input_device=null才跟随Windows默认输入；没有设备时不静默换麦。
- 尚无逐字流式输出，不做自动润色、双模型复核或自动发送。
- ×隐藏并暂停与退出程序不同；Esc不撤销已经送进应用的文字。
- 两个显示器按硬件型号而非DISPLAY编号选择，未接入目标不显示；这不改变显示拓扑。
- 9月9日DJI端点被枚举到不等于已经开麦、验证个人口音或测得按键到上屏延迟。
失败与恢复
- 听写焦点变化或管理员窗口拒绝输入
- 停止自动输入，不把迟到文字送到新焦点；通过托盘主动复制最近文本，再由本人选择粘贴位置。
- 听写按 Esc 或退出
- 取消尚未输入部分并停麦克风，已输入文字保留；退出交还系统 Win+H。
- 指定麦克风未连接
- 提示连接指定设备，不切换到其他麦克风；检查配置或连接后再开始。
- 同一麦克风不接受16kHz
- 尝试该设备报告的原生采样率，再转换整句；采音丢帧或采样率未准备好时取消未输入内容。
- 模型或GPU租约不可用
- 保留明确错误和当前控制入口，不绕过显卡协调器、换模型或上传云端。
- 屏幕接回、断开或分辨率改变
- 按硬件型号重新定位目标小窗，同一次录音与选择继续共享；未接入的目标不显示。
- 真正退出或程序中断
- 结束本次内存会话；沿Start或开始菜单重开，旧录音和文字没有可恢复的文件任务记录。
真实入口
E:\Projects\Tools\ChineseASR\scripts\dictation.ps1听写安装、自启动与停启状态
E:\Projects\Tools\ChineseASR\src\zh_asr\dictation.py采音分句、推理、焦点保护与取消
E:\Projects\Tools\ChineseASR\src\zh_asr\dictation_windows.pyWindows 快捷键、托盘与文字注入
E:\Projects\Tools\ChineseASR\configs\dictation.yaml独立听写模型、指定设备、分句与单面板显示优先级
E:\Projects\Tools\ChineseASR\src\zh_asr\dictation_audio.py设备枚举、采音、原生采样率与重采样
E:\Projects\Tools\ChineseASR\src\zh_asr\dictation_vad.py有效语音检测与缓冲
E:\Projects\Tools\ChineseASR\tests\test_dictation_windows.py输入保护、单面板重定位与控制回归
如何验证
- PUBLIC（公开） main=12eb64e93586b8fce8a4d2b9750c4d097b78ae5a，本次只读远端回读仍同值；新增网页模块不代表新增源码能力。
- 2026-09-09原观察：ChineseASR Dictation已安装且Running，开始菜单中文听写.lnk目标与图标匹配，DJI输入端点可枚举；未打开麦克风。
- 2026-09-09三个听写测试模块45项通过、1.225秒；9月7日71通过/1跳过、9月5日完整376项及公开短音频各保留原日期，不叠加为新全套。
- 个人口音、DJI 麦克风采音、真实快捷键、200×75 实际桌面位置、焦点切换与管理员窗口输入，本轮均未重验；任务 Running 和来源测试不替代使用结果。
与其他模块的关系
桌面听写负责实时采音和应用输入；文件入口与任务模块负责已有录音、持久任务和文件结果。二者复用已有模型适配器与GPU协调，但输入、输出和恢复生命周期分别验收。