Voice-Typing 插件需求文档 (PRD)

1. 项目概述

Voice-Typing 是一款为 MicYou 桌面端（Windows）设计的 Native 插件。本插件的核心目标是订阅 MicYou 生态中 WDIS (WhatdidIsay) 插件的全局语音转录广播，并将识别到的文本自动、无感地输入到当前系统的焦点输入框中。

与传统的语音控制工具不同，本插件不干涉或控制底层 WDIS 识别引擎的启停状态。WDIS 始终在后台运行并持续广播转录结果，本插件通过本地状态机、快捷键交互与时间戳过滤机制，决定“哪些语音片段应当被转化为键盘输入”，从而提供更灵活、低延迟的系统级语音打字体验。

---

2. 核心功能需求

2.1 WDIS 转录监听与解析

• 订阅广播：插件需接入 MicYou 宿主内部的 Message Bus，订阅 WDIS 的转录广播频道。
• 协议解析：能够正确解析 WDIS 的二进制广播协议，精准提取消息中的核心载荷，包括：识别开始时间戳（start_ms）、识别结束时间戳（end_ms）以及 UTF-8 编码的转录文本。

2.2 系统级文本注入 (Auto-Typing)

• 焦点感知：插件需具备系统级焦点感知能力，能够识别当前处于激活状态的窗口及输入控件。
• 文本模拟输入：将过滤后允许的转录文本，以系统级模拟键盘事件的方式注入到当前焦点输入框中。
• 字符集支持：必须完美支持 Unicode/UTF-8 字符集，确保多语言、特殊符号及 Emoji 的正确输入。
• 剪贴板保护：注入过程不得污染或覆盖用户的系统剪贴板内容。
• 智能排版（可选）：支持根据上下文自动追加空格或处理标点符号的粘连问题。

2.3 状态音效反馈

• 本地状态提示：由于插件不控制 WDIS 引擎，提示音的触发应绑定于本插件输入状态的切换。
• 开始提示音：当用户通过快捷键激活“允许输入”状态时，播放预设的“开始”提示音。
• 结束提示音：当用户通过快捷键解除“允许输入”状态时，播放预设的“结束”提示音。
• 音频通道：需调用 MicYou 宿主提供的音频播放 API 进行异步播放，确保不阻塞主线程或消息处理逻辑。

2.4 悬浮 UI 与光标跟随

• 轻量级悬浮窗：提供一个无边框、置顶的悬浮 UI 面板，用于展示当前的输入状态（如：待机、录音中/允许输入中、处理中）。
• 光标自动定位：
  • 插件需实时获取当前焦点窗口中的输入光标（Caret）坐标。
  • 悬浮 UI 需自动吸附至输入光标附近（如光标正下方或侧边），确保用户在打字时视线无需大幅度移动。
  • 边界避让：当光标位于屏幕边缘时，UI 需具备智能避让逻辑，防止悬浮窗溢出屏幕可视区域。
  • 降级策略：若某些应用程序（如终端或特定游戏）无法暴露光标坐标，UI 需自动降级为跟随鼠标指针坐标。

---

3. 快捷键与输入控制逻辑（核心）

本插件不向 WDIS 发送任何启停指令。WDIS 持续广播，插件通过拦截快捷键，并结合 WDIS 消息中的时间戳，在本地决定当前接收到的文本是否执行注入。插件需在设置中提供以下两种控制方案供用户选择：

方案 A：长按模式 (Push-to-Talk)

• 交互方式：用户按住快捷键期间，允许文本输入；松开快捷键，停止文本输入。
• 时间戳过滤逻辑：
  1. 插件在后台记录快捷键的 按下时间 (Press_Time) 和 松开时间 (Release_Time)。
  2. 当收到 WDIS 广播时，比对消息中的 start_ms 和 end_ms。
  3. 注入条件：只有当 WDIS 消息的时间段（start_ms 到 end_ms）与用户按住快捷键的时间段（Press_Time 到 Release_Time）存在交集，或 start_ms 落在按键按住区间内时，该段文本才被允许注入。
  4. 容差机制：考虑到语音识别和网络/总线广播的微小延迟，需支持配置“时间容差（Grace Period）”，允许在松开快捷键后的短暂时间（如 500ms）内接收到的尾巴文本继续注入，防止句子被截断。

方案 B：按键切换模式 (Toggle)

• 交互方式：用户短按快捷键，开启“全局允许输入”状态；再次短按，关闭该状态。
• 时间戳过滤逻辑：
  1. 插件维护一个本地的布尔状态（Is_Active）。
  2. 每次短按快捷键，Is_Active 状态翻转，并触发相应的状态音效和 UI 状态变更。
  3. 注入条件：当 Is_Active == true 时，接收到的所有 WDIS 广播文本均直接注入；当 Is_Active == false 时，丢弃所有接收到的广播文本。

---

4. 插件清单 (Manifest) 需求

插件需向 MicYou 宿主提供标准化的 plugin.json 清单文件，声明以下元数据与权限：

• 基础信息：
  • ID: opss.Voice-Typing
  • Name: Voice-Typing
  • Runtime: native (cdylib)
  • Platforms: ["windows"]
• 能力声明 (Capabilities)：
  • message.receive：用于订阅 WDIS 广播。
  • audio.play：用于播放开始/结束状态提示音。
  • config.read / config.write：用于持久化用户的快捷键偏好、控制模式及 UI 设置。
  • event.emit：用于向前端 GUI 抛出状态变更事件（如快捷键冲突、配置更新）。

---

5. 配置项需求 (Settings)

插件需通过宿主的配置系统暴露以下可调参数，并支持热更新：

配置项	类型	默认值	说明
control_mode	Enum	push_to_talk	控制模式：push_to_talk (长按) 或 toggle (切换)
hotkey	String	Alt+Space	全局快捷键组合映射
grace_period_ms	Integer	500	长按模式下的时间容差（毫秒），防止尾音截断
auto_spacing	Boolean	true	是否在连续注入的英文单词或特定中文语境间自动补全空格
ui_follow_cursor	Boolean	true	是否启用悬浮 UI 光标跟随功能
sound_enabled	Boolean	true	是否启用状态切换提示音
sound_volume	Float	0.8	提示音音量大小 (0.0 - 1.0)

---

6. 资产与目录结构需求

插件仓库需遵循 MicYou 标准的 Native 插件目录规范，并包含必要的资产文件：

• 根目录：包含 plugin.json 与 README.md。
• 资产目录 (assets/)：
  • start.wav：短促、清脆的激活提示音。
  • end.wav：低沉或平缓的解除提示音。
• 构建产物：编译输出的动态链接库（如 .dll），文件名需与 Manifest 中声明的 entry 保持一致。

---

7. 非功能性需求

• 实时安全性：消息处理与文本注入逻辑不得阻塞 MicYou 宿主的消息总线或音频/DSP 线程。所有系统级 UI 渲染和键盘注入操作需在独立的后台线程或异步任务中执行。
• 权限优雅降级：若因 Windows 权限限制（如以管理员身份运行的目标窗口）导致文本注入失败，插件需捕获异常，通过 UI 提示用户，而不得导致插件崩溃或宿主卡死。
• 低资源占用：作为常驻后台插件，在“非激活”状态下，内存占用与 CPU 轮询开销应降至最低。