小锋语音伴侣 V2.3.10 —— 使用说明
（本说明为纯文本，读屏软件可直接朗读）

========================================
版本：V2.3.10
开发者：星夜高飞
开发工具：WorkBuddy（腾讯「小龙虾」）
本软件公益免费，祝大家使用便利，创业成功！
========================================


========================================
有问题，怎么联系我们
========================================

  大爱先锋学员群（QQ 群）
  YY 语音 151991 直播频道
  电话：0539-2232972
  邮箱：277276857@qq.com

  安装或使用中遇到任何问题，任选一种方式联系我们即可。


========================================
目录（读屏可用标题跳转）
========================================

  一、它是什么
  二、安装前必读：系统与权限
  三、怎么安装
  四、怎么用
  五、常见问题（详细解答见同目录 FAQ.txt）
  六、放在哪里
  七、开始菜单怎么用
  八、联网情况说明

  安装位置：用户目录下的 XiaofengVoice
  快捷键速查：见同目录《快捷键说明.txt》


========================================
一、它是什么
========================================

一个让你「用嘴巴操作电脑」的工具。

装上以后，按住键盘上的一个键说话，松开后你说的话会自动变成
文字、填进输入框；同时电脑也会用语音把重要内容念给你听。

语音识别完全在你自己的电脑上完成，不上传任何数据；
语音播报需要联网，详见第八节。

这套工具由 AI 助手「小锋」设计开发，名字也来自它。叫「伴侣」，
是因为它想当的不是一个冷冰冰的工具：你说得不够专业，它帮你把话
说周全；你正忙着，它就安静待着；出了岔子才开口，而且会告诉你
下一步该怎么办。


========================================
二、安装前必读：系统与权限
========================================

【系统要求】
  Windows 10 / Windows 11 —— 完全支持，推荐。
  Windows 8.1            —— 可以用，但微软已停止支持，建议升级。
  Windows 7              —— 不支持。
    原因：本工具自带的运行环境是 Python 3.13，已不再支持 Windows 7，
    强行安装会报各种莫名其妙的错。请换 Windows 10 以上的电脑。
  内存建议 8GB 以上；CPU 建议 4 核 8 线程以上，主频建议 2.5GHz 以上。

【需要管理员权限吗】
  不需要。而且建议你「不要」用管理员身份运行。

  本工具是「用户级安装」：
    运行环境装在你自己的用户目录下
      C:\Users\你的名字\.venv-voice
    程序装在你自己的用户目录下
      C:\Users\你的名字\XiaofengVoice
    开机自启写在你自己的启动文件夹里

  全过程不写系统目录、不改全局注册表，所以不需要管理员。

  【为什么反而不建议用管理员】
  如果你右键选「以管理员身份运行」，安装程序会以为当前用户
  是 Administrator，把东西全装进 C:\Users\Administrator
  下面；等你用自己平时那个账号登录，就什么都找不到了。
  所以：直接双击安装包就行，别右键提权。

【一个例外】
  如果你要让语音去操作某个「以管理员身份运行」的程序，
  Windows 的安全机制（UIPI）会拦住模拟按键，
  那个程序收不到语音发过去的键。
  解决办法是让两边权限一致：都不要提权，或者都提权。


========================================
三、怎么安装
========================================

1. 双击安装包，程序会自行解压并开始安装。

2. 【两种包，看你是哪种】
   完整离线包（安装包里带 wheels、models、runtime 三个目录）：
     全程不联网也能装，推荐。会用自带的 Python 3.13，
     组件和识别模型都从包里取，不受网速影响。
   精简包（没有那三个目录）：
     需要联网，安装时会自动下载组件和约 230 兆的识别模型。

3. 接下来全程语音引导，大约五到十分钟，请不要关闭窗口。

4. 听到「安装完成」后，就可以使用了。

注意：
- 若提示没有 Python，安装程序会自动尝试安装；
  装完请关闭窗口，重新运行一次安装程序。
- 若身边只有解压即用的文件夹版本，进入文件夹双击 install.bat，
  效果相同。


========================================
四、怎么用
========================================

【说话】
按住 F4 键 —— 说话 —— 松开
  按下时会听到一声「嘀」，表示开始录音；
  松开后听到一声「嗒」，表示识别完成并自动发送。

录音过程中按 Esc，这次就不算数。只有在录音时按 Esc 才会取消，
在别的软件里按 Esc（关对话框、退出菜单、读屏操作）都不会有反应。

两种语音指令都不用先点输入框，程序会自动把光标切到 WorkBuddy
的输入框，松手后文字直接落进去，位置不会错。

【指令优化：不会下指令也能用好 AI】
很多人不是不会说话，是不知道该「怎么下指令」——说得太笼统，
AI 只能猜。这个键就是解决这件事的。

  按住 F8 说话
  1. 先请 WorkBuddy 把你的口语改写成一条专业、清晰的指令；
  2. 改写结果放进输入框，同时念一遍给你听；
  3. 听着满意，按回车执行；不满意就重新说一遍。

改写结果只放进输入框，绝不会自动执行；每改写一次要多花一次
AI 调用（也就是一点积分）。随口说一句就够的时候，用 F4 更省。

【八个辅助动作键】
这八个键不录音，只帮你快速定位或查询，按下即生效：

  F1          打开《快捷键说明》，读屏可以直接读，不用再去文件夹里翻。

  Ctrl + F1   窗口综述（强烈推荐，迷路时按它）。
  Ctrl + F2   把「需要你确认」的内容再念一遍。
  Ctrl + F3   打开左下角的个人中心菜单。
  Ctrl + F4   把光标直接放进指令输入框。
  Ctrl + F5   应急恢复读屏朗读。
  Ctrl + F6   切换读屏的「音频闪避」。
  Ctrl + F7   立刻自检自修一遍。

八个键的判定规则与失灵处理，见《快捷键说明.txt》。
所有按键都是局部热键，只在 WorkBuddy 工作台窗口内生效。

【听：结果会自动念给你听】
每次回复，电脑会自动把重点内容念给你听，包括结论和需要你决定的
问题，一轮约一百字。长篇内容只念要点，详细内容留在文字里可手动
查阅。这靠一个「自动播报钩子」实现，不用你做任何操作。
万一哪天不念了：运行 check.bat，或者重新运行一次安装程序。

【和读屏软件配合（重要）】
按住 F4 或 F8 开始说话的瞬间，程序会自动让读屏暂停朗读；松开
按键、说完话之后，再自动让读屏恢复。这样你说的话不会被读屏的
声音盖住，识别更准。
万一松开后读屏没恢复（极少见），按 Ctrl + F5 强制恢复。

【需要你确认时会念给你听】
有些操作（比如删除文件、执行某些命令）电脑会弹出确认框问「是否
允许」。这个框你看不见，所以：

  1. 确认框一出现就立刻念给你听，包括它问的是什么、要执行什么命令；
  2. 念完会把光标移到确认框上，方便你直接按键；
  3. 确认框上的选项通常是：
       1 允许
       2 本次会话内始终允许
       3 拒绝
     按对应的数字键就能选；按回车是「允许」，按 Esc 是「取消」；
  4. 没听清就按 Ctrl + F2，会再念一遍。

【想让它停下来 —— Esc 急停（不花积分）】
觉得这一轮任务跑偏了、或者等太久，直接按 Esc：

  第一次按 Esc   会问你一句：
                「要停止当前任务吗？四秒内再按一次 Esc 确认停止，
                  按其他键取消。」
  第二次按 Esc   真的停下来。
  按其他键 / 等四秒   取消，任务继续跑。

为什么要按两次：Esc 太容易误碰了，一次就停会误伤。
整个过程全在你自己电脑上完成，一句话都不会发给 AI，不花积分。

停下之后会发生三件事：正在念的内容立刻闭嘴、排队等着念的清空、
「忙碌中」的封锁解除——你可以马上说下一句，不用再干等。

注意：如果屏幕上正弹着「是否允许」的确认框，
Esc 会优先让给确认框（那是「拒绝」的意思），不会触发急停。

【任务正在跑的时候】
如果我还在处理上一件事、还没回答你，你这时又说话，会听到一句
提示：「当前任务正在进行，请耐心等待」。这是正常的，等我说完
再开口就行，不会被重复上屏。

【出了问题它会自己修，而且会先告诉你】
后台有个「自愈守护」，每 45 秒巡视一次。发现问题当场处理，
不等你重启电脑：

  工作台升级了     -> 立刻完整自检，把结果念给你听
  语音服务断了     -> 立刻重启，并告诉你已经自动重启好了
  按键失灵了       -> 立刻重启，并告诉你已经自动重启好了
  播报钩子被清掉了 -> 立刻重装，并告诉你已经重新装好

自检共六项：服务 / 热键 / 窗口 / 输入框 / 综述 / 钩子。全过就念
一句「跟新版本兼容，可以继续使用」；有不通的，逐项念出来，告诉
你坏在哪。三条规矩都是为了不给你添乱：

  1) 修了一定说 —— 你看不见，闷不吭声等于没发生
  2) 同一个问题五分钟内只处理一次 —— 不然会反复念同一句
  3) 连续三次修不好就停手，明说「请运行一键体检」—— 绝不没完没了地试

每次开机也会自动比对一次工作台版本，没变就什么都不做，变了就自动
跑一遍自检。想立刻查一次（不用等巡视）：按 Ctrl + F7。
平时想自己看报告：运行 check.bat，最后一段就是兼容性检查。

万一自检说界面改版了（比如定位不到输入框）：
  第一步：重新运行一次安装程序，让它重新认一遍界面。
  第二步：还不行，先按 Ctrl + F4 试试能不能回到输入框；
         再不行就运行 check.bat，把结果反馈给开发人员。

【我没听准会问你】
语音识别不可能百分百准确。遇到人名、数字、文件名这类容易听错的
内容，或者涉及删除、发送这类不可撤销的操作，我一定会先用语音跟
你确认一遍，不会自作主张。


========================================
五、常见问题
========================================

问：按住键没反应？
答：先运行 check.bat，或者按 Ctrl + F7，它会检查并把结果念给你听。
    多数情况是服务没启动，体检会自动帮你启动。

问：说话的时候听到「当前任务正在进行」？
答：说明我上一件事还没干完。等我说完再开口就行，
    这是保护机制，不会让你的指令乱掉。

问：识别出的文字不对？
答：说话时离麦克风近一点，语速放慢一点。
    尽量用短句，一次说一件事。

问：电脑没声音？
答：先检查系统音量和扬声器。如果都没问题，运行 check.bat，
    它会实测离线语音能不能真的出声（不只是看文件在不在）。
    常见原因是微软在线合成需要连 speech.platform.bing.com，
    连不上时程序会自动改走系统离线语音；
    两条路都不通才会静音（日志里会有「TTS 全部失败」）。
    想强制只用离线语音：打开 config.json，把 "tts" 里的
    "engine" 改成 "sapi"，再运行一次 repair.bat。

问：弹出确认框的时候没声音？
答：先按 Ctrl + F2 试试，会把确认框的内容重新念一遍。
    还是没声音就运行 check.bat，检查服务是否正常。

问：想卸载？
答：有两种方式，任选其一，都能干净卸掉：
    1) 开始菜单（最简单）：按 Win 键输入「卸载」回车，
       或输入「语音伴侣」后选「卸载」项；
    2) 安装包文件夹：双击里面的 uninstall.bat。
    菜单里三项的名字与路径，见第六节《开始菜单怎么用》。

问：想改说话的音色、语速？
答：打开 C:\Users\你的用户名\XiaofengVoice\config.json，
    找到 "voice" 一行可以改音色，
    找到 "rate" 一行可以改语速（比如 "+20%" 更快）。
    改完运行一次 repair.bat。


========================================
六、放在哪里
========================================

程序文件：C:\Users\你的用户名\XiaofengVoice
运行环境：C:\Users\你的用户名\.venv-voice
日志文件：XiaofengVoice\logs\ 下面

遇到问题可以把 logs 文件夹打包发给技术人员。


========================================
七、开始菜单怎么用
========================================

装好以后，按一下键盘上的 Windows 键（或 Ctrl+Esc），
直接输入「启动语音伴侣」或「语音伴侣」，就能搜到菜单项。

菜单文件夹的内部名字是 XiaofengVoice（英文，便于系统稳定识别），
里面三项的名字都是中文，读屏可直接朗读：

  1. 启动语音伴侣
     用来启动或叫醒语音服务。平时开机是自动启动的，
     如果某次没起来，用这一项手动启动一次就行。

  2. 软件说明
     用记事本打开本说明（使用说明.txt），
     纯文本，读屏可以直接朗读。

  3. 卸载
     卸载本软件，会先停掉服务、去掉开机自启，
     再问你要不要连程序文件和模型一起删除。

小提示：按 Win 键后输入「卸载」或「软件说明」，也能直接搜到对应项。


========================================
八、联网情况说明
========================================

这一点对隐私很重要，说明如下：

  · 语音识别：完全在本机完成，用的是本地离线模型
    （sherpa-onnx），说的话不会上传到任何服务器，断网也能用；
  · 语音播报：需要联网，使用微软 edge-tts 服务；
  · 除播报所必需的数据外，本软件不会向外发送任何信息。

========================================
