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

========================================
版本：V2.3.27
开发者：星夜高飞
开发工具：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          打开《快捷键说明》，读屏可以直接读，不用再去文件夹里翻。

  F2          窗口综述（强烈推荐，迷路时按它；V2.3.26 从 Ctrl+F1 迁来）。
  Ctrl + F2   把「需要你确认」的内容再念一遍。
  Ctrl + F3   打开左下角的个人中心菜单。
  Ctrl + F4   把光标直接放进指令输入框。
  Ctrl + F5   应急恢复读屏朗读。
  Ctrl + F6   切换读屏的「音频闪避」。
  Ctrl + F7   立刻自检自修一遍。
  Ctrl + F8   切换播报模式（结果模式 / 全部模式；与 Ctrl+F1 同一个功能）。
  Ctrl + F1   同上——切换播报模式（V2.3.26 起，两个键按哪个都行）。
  Ctrl + Shift + F8   问一句「现在用的是哪种音色」（V2.3.27 与 Ctrl+F8 对换：
                      顺手键留给常用的播报模式，问音色放到带 Shift 的键上）。

  录屏五键另见下方「四点五、录屏」：
  Ctrl + F9 开始/停止、Ctrl + F10 暂停/继续、
  Ctrl + F11 循环切换录制模式、Ctrl + Shift + F11 循环切换三档画质、
  Ctrl + F12 打开录屏文件夹。

判定规则与失灵处理，见《快捷键说明.txt》。
除 Ctrl+F1、Ctrl+F8、Ctrl+Shift+F8 与录屏五键（Ctrl+F9~F12 及
Ctrl+Shift+F11）是全局热键外，其余按键只在 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，把结果反馈给开发人员。

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


========================================
四点五、录屏（V2.3.24 新增，V2.3.25 四种模式，V2.3.26 加三档画质）
========================================

【能录什么：四种模式，按 Ctrl + F11 循环换】
  1. 仅画面            只录屏幕，一点声音都不录
  2. 画面加系统声音    录屏幕 + 电脑里正在播放的声音
  3. 画面加麦克风      录屏幕 + 你的麦克风
  4. 画面加系统声音加麦克风   三样全录（出厂默认）
  做教程、演示操作、给别人看你遇到的报错，都用它。
  画面 + 声音存成一个标准的 MP4 文件，微信、QQ、手机、剪辑软件都能直接打开。
  「仅画面」这一档出来的文件里干脆没有音轨，不是录坏了，是本来就没要声音。

  怎么换：按 Ctrl + F11，每按一次换一档，会念「已切到……，下次录制就按这一档」。
  · 没在录制时换：下一次录制就按新档位走，不必重启。
  · 正在录制时换：只记下新档位，并念「本次录制保持不变，下次录制生效」。
    已经开录的音轨不会热插拔——硬换会造成音画不同步，所以我宁可等下一次。
  · 想直接用某一档而不循环：用记事本把 config.json 里的
    "recording" -> "mode" 改成 screen / screen+system / screen+mic /
    screen+system+mic 之一，改完下一次录制生效。
  · 想知道现在是哪一档：运行「一键体检」（check.bat），第 10 项会念出来。

【清晰还是小文件：三档画质，按 Ctrl + Shift + F11 循环换（V2.3.26 新增）】
  1. 高清：最高 1080p、每秒 30 帧——每分钟约 60 兆；
  2. 标准：720p、每秒 15 帧——每分钟约 30 兆（出厂默认）；
  3. 流畅：480p、每秒 10 帧——每分钟约 15 兆。
  每按一次换一档，会念「已切到……」；与录制模式互不影响，换法规则相同：
  没在录制时下一次录制生效，正在录制时只记档位、下次生效。
  想直接用某一档：把 config.json 里 "recording" -> "quality_level" 改成
  high / standard / low 之一。

【怎么开始、怎么停】
  按 Ctrl + F9：第一次按是开始，再按一次是停止。
  按下之后会念「正在启动录屏」，接着是三声短音、一声长音——
  听到那声长音，录像才真正开始。倒数那几秒不会录进视频里。
  开录时会念出画面的抓屏方式与声音来源，例如
  「系统声音来自 扬声器 xxx、麦克风是 xxx」——外置声卡的用户听一眼
  就知道抓的是不是正在用的那块。万一画面抓不到（个别双显卡机器、
  或开了 HDR 的机器），程序会自动换「桌面复制」方式重试；实在不行
  会如实播报并取消，绝不存出黑屏文件（这时关掉 HDR 再录即可）。
  想中途歇一下：按 Ctrl + F10 暂停，再按一次继续。暂停的那段时间不算进视频。
  想停止：再按一次 Ctrl + F9。录完会念录了多久、文件多大、存到哪儿了。
  找文件不用记路径：按 Ctrl + F12 直接打开录屏文件夹，读屏可以读文件列表。

  这五个键是**全局热键**：在任何软件前面都能按，不用先把工作台切到前台。
  录制中连按、快按也不会打乱画面：按键只发一道命令，抓屏和编码在独立进程里。

【存在哪儿】
  默认存在「视频」文件夹里的「小锋录屏」文件夹，文件名是
  「录屏_日期_时间」，例如 录屏_20261021_120000.mp4。同一秒录两次
  也不会互相覆盖，会自动加 _2、_3。
  想换地方：用记事本打开程序目录里的 config.json，找到 "recording"
  一节，改 "save_dir" 那一行（支持 %USERPROFILE% 这种写法）。
  改完不用重启，下一次录制就生效。目录建不了、没权限或空间不足时，
  我会自动退到「视频\小锋录屏」或桌面，并在开始录制时告诉你存哪儿了。

【录多大、占多少电脑】
  画质由三档画质键决定（默认「标准」：720p、15 帧、每分钟约 30 兆）。
  本机是 2 核处理器，实测标准档约占四分之一个核；嫌大就切「流畅」，
  想清晰就切「高清」，但高帧率在弱机上画面和声音都可能卡。
  录屏跑在独立的进程里：就算录屏出了问题，说话、热键、读屏一概不受影响。

【声音的事，都照实说】
  · 只有你要了那一路声音、却没拿到时，才算异常，才会念出来：
    要了麦克风没打开，念「麦克风没打开（原因），这次只录系统声音」；
    要了系统声音没拿到，念「没拿到系统声音，这次只录麦克风」。
  · 你没要的那一路，绝不会被念成故障。选了「仅画面」就只念
    「按当前设置，这次只录画面，不录声音」——这是你选的，不是坏了。
  · 电脑本来就没在出声，录到的系统声音就是安静的，这不算故障。
  · 开始录之后 6 秒内一点声音都没有，会提醒一句「到现在没听到任何声音」，
    只提醒一次，不啰嗦。
  · 极少数精简版系统缺 AAC 编码器：画面照录，声音另存一个同名的 .wav，
    结束时会明确告诉你。
  · 录制期间读屏语音和我的播报都会被录进系统声音里——做教程时这通常
    正是想要的；不想要就切到「仅画面」或「画面加麦克风」，
    也可以按 Ctrl + F6 把读屏闪避开。

【几个保护】
  · 开始前检查磁盘：剩余空间少于 500 兆（config.json 里 min_free_mb 可改）
    就不开始，免得录到一半写满。
  · 录制中屏幕分辨率变了、或系统休眠过，会自动停止并保存已录的部分，
    并说明原因——不会留下一堆错位的画面。
  · 文件先写成「xxx.part.mp4」，正常收尾才改成正式名字。万一断电、
    被强杀，你看到的是带 part 的文件，那表示它可能不完整。
  · 录制期间自动暂停「抢焦点」，免得录教程时窗口焦点乱跳；录完自动恢复。
  · 有时杀毒软件会扫一遍新生成的视频，停止后要多等几秒才有结果播报，
    等待超过 4 秒我会说一句「正在收尾」，不是死机。

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

问：按住键没反应？
答：先运行 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），说的话不会上传到任何服务器，断网也能用；
  · 语音播报：**会自动挑最好的一档**。联网正常时用微软的在线
    神经语音（音质最好）；网络受限、连不上时自动改用你正在用的
    读屏语音；两者都不行，用系统自带语音（慧慧）。所以断网也能
    听到播报，只是音色会退一档。
    想确认当前用的是哪一档，按 Ctrl + F8 问一句即可；
    换档时程序也会主动说一句，只说不重复。
  · 除播报所必需的数据外，本软件不会向外发送任何信息。

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