# Speech Wingman

**你专心说，它帮你留意那些想改掉的表达习惯。**

Speech Wingman 是一个在 Mac 本机运行的语音提醒助手。用日常语言写下规则，点一下悬浮麦克风，正常说话；命中规则时，它引用原话，给你一个简短提醒。适合会议、演讲和面试练习。

**自定义规则 · 英语、中文、日语、韩语与粤语 · 完全离线运行**

[多语言实测演示](#多语言一段会话交替说) · [安装与使用](guide.md) · [测试结果](validation.md) · [English](../README.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [廣東話](README.zh-HK.md)

*开源开发预览版 · Apple Silicon · macOS 14+ · 目前需要本地构建，尚无即装即用安装包。首次下载依赖与模型需要联网，构建后的应用离线运行。*

## 写一条规则，看看它怎样提醒

一个真实使用案例：练习用更中性的方式评价别人。

1. **写规则：** “if i say bad thing about Tom, alert me in English”（说汤姆的坏话时，用英文提醒）。
2. **说话：** “Yeah, Tom is a very mean person. In my opinion.”
3. **看提醒：** 应用引用这句发言，建议改用更有建设性或中性的表达。

![真实使用：评价汤姆的发言触发英文提醒](assets/desktop-english-full.png)

*截图来自早期 0.2.1 界面的真实使用。识别与提醒可能出错或延迟，这个案例不代表准确率保证。*

**想支持这个完全离线的语音助手？欢迎点击仓库顶部的 ⭐ Star。** 新版通知请选 **Watch → Custom → Releases**。

[构建并试用](../README.md#getting-started) · [先触发你的第一条提醒](../README.md#your-first-reminder)

## 多语言，一段会话交替说

**Multilingual（英语、中文、日语、韩语，甚至粤语）。** 同一段会话可以交替使用这些语言，识别保持自动模式。界面和生成提醒统一使用所选语言，默认英语；转录及引用保留原文。

这次用一条规则实测：**“只要发言提到香蕉，不论哪种语言，都提醒。”** 一条连续音频依次说五种语言，再按自然停顿交替混说，全程没有切换识别语言，提醒保持英文。

![当前应用实测：同一会话依次识别英语、普通话、日语、韩语和粤语](assets/multilingual-five-languages.gif)

### 同一会话交替混说

![同一会话再次交替使用五种语言，无需修改识别设置](assets/multilingual-mixed.gif)

[观看带声音的完整视频](assets/multilingual-continuous.mp4) · [真实转录与判断记录](assets/multilingual-report.json) · [复现步骤](../Tests/MultilingualDemo/README.md)

*演示将虚构的 macOS 合成语音按正常速度送入正式的语音识别、判断、会话控制和界面代码，只用音频回放替代麦克风输入。转录和提醒都由模型实际产生，没有预填结果；视频含原始合成语音，GIF 无声。这是开发演示，不是真人麦克风准确率测试。*

**自然停顿有帮助。** 把多种语言快速挤在一个未停顿的片段中，仍可能漏字或识别错误；[间隔仅 250 毫秒的压力测试](assets/multilingual-rapid-stress.json)保留了这一失败情况，不把多语言支持写成任意混说都零误差。

当前通过 **20 组核心测试**。此前独立模型回归为 **63/73**，两者不是同一个准确率指标；完整结果和已知失败见[验证说明](validation.md)。约 11 分 26 秒的历史长语音测试仍保留在 [Ultimate Test Case](../Samples/UltimateTestCase/README.md)。

## 规则可以很实用，也可以很有脑洞

本地小语言模型按语义判断，不局限于固定提醒类别。你可以尝试：

1. **承诺守门员：** 明确保证会完成，却没有说明截止时间或交付范围时提醒；条件承诺和信息完整的承诺不提醒。
2. **术语检查员：** 面向非技术听众，使用了未解释的技术缩写时提醒；当前片段已经解释过的词不提醒。
3. **宇宙猫船长警报：** 认真提议让猫驾驶宇宙飞船时提醒；否定、引用和虚构故事不提醒。

**每行一条规则，任意一条命中即可提醒。** 例如：

```text
说到 banana 就提醒。
说汤姆的坏话就提醒，赞扬他不提醒。
透露数字密码时提醒。
```

每条规则独立检查，例外条件写在同一行；首次命中后给出一条提醒。编辑框总计最多 4,000 字，规则共用敏感度和静音设置。默认不再限制为十分钟三条。[英文界面演示](examples.md)使用虚构内容，并非这些例子的模型准确性证明。

## 适用场景与特点

可用于会议、演讲、面试和销售沟通练习，例如提醒自己补充承诺的截止时间与交付范围，或检查是否使用了需要解释的术语。这些是可尝试的规则，不是保证准确的预设能力。

- **运行完全离线：** 模型随本机构建的应用打包，不需要账号、API key 或云端服务。首次下载源码、依赖和模型需要联网。
- **五种语言自动识别：** 不需要手动切换录音语言。界面和生成提醒默认英文，支持中文、日语和韩语，可在 **Settings → Interface and alert language → 中文** 切换并保存。
- **自然语言规则：** 每行写一条独立规则和它的例外条件。自定义规则和转录保留原文；新生成的提醒按所选语言输出，内置规则有四语版本。
- **桌面悬浮按钮：** 可拖动、跨桌面显示，点一下开始监听，再点一下停止收音并保留会话；下方紧凑文字区显示最近发言和实时转写，自动跟随最新一行；可在设置中隐藏。
- **可控的会话：** 手动开始、暂停/继续、停止并清空、静音一小时，或主动导出 JSON。应用不默认保存录音或转录。

## 系统要求与安装

需要 **Apple Silicon Mac、macOS 14+、Swift 6+、Apple 开发工具、Python 3.9+ 和兼容 ARM64 的 CMake**。建议 16 GB 统一内存、至少 10 GB 可用磁盘空间。当前验证环境为 Apple M4 / 16 GB / macOS 27，较老系统及更低内存配置尚未全面验证。

本仓库发布源码和固定版本的下载清单，不包含模型权重或公证安装包。按[构建指南](guide.md#getting-started)中的命令克隆仓库、运行 `bootstrap-dev.sh`、下载模型，再执行 `build-app.sh`。生成的应用约 2.78 GB，使用本机 ad hoc 签名，未做 Developer ID 公证。

打开应用后，点击菜单栏麦克风图标，在设置中填写提醒条件，保存后点击 **Start listening / 开始监听**，并允许麦克风访问。麦克风拾取到的其他人声也会参与判断，应用不区分说话人。悬浮按钮下方会显示最近几句和正在识别的文字，文字区保持固定高度，并自动滚动到最新一行；暂停后保留已定稿文字，清空会话后恢复小尺寸。悬浮按钮停止收音会保留会话；“停止并清空”和退出应用会丢弃会话，如需持久保留，请主动导出。更新时运行 `git pull --ff-only` 和 `bash Scripts/build-app.sh`；若旧版仍在运行，新版会暂存为 `build/Speech Wingman.next.app`，不会自动关闭当前会话。导出并退出旧版后，再运行一次构建脚本，随后打开 `build/Speech Wingman.app`。

## 工作方式与边界

处理链路为 **Silero VAD → SenseVoiceSmall 转录 → Qwen3 4B 文本判断**。当前预览约每秒更新，约 650 ms 静音后定稿；语义判断处理定稿片段。连续长发言会按约 12–15 秒窗口处理，继续说话也可能延后提醒，因此不承诺逐字即时判断。

每行一条独立规则，任意一条命中即可提醒；提醒与按钮统一使用语言设置；转录和引用保留原文。默认不再限制为十分钟三条。相邻定稿片段会短暂合并成当前发言，给停顿后的解释留出时间，不引入更早的聊天历史。新发言不再取消正在进行的判断；最多排队四句，超量或过期会跳过，并在导出中标记原因。长停顿后的补充解释仍可能被分开。桌面悬浮按钮可点击开始／停止收音、拖动位置，并可在设置中隐藏。专有名词、口音、多人重叠、复杂规则和快速多语言切换都可能出现错误。小规模合成语音回放中，基础组 8/8、补充组 5/6 符合预期；仍存在“中文中出现英文词就提醒”的漏报，不能把这一结果当作真实场景准确率。

应用源码采用 MIT；模型和依赖适用各自许可证，尤其 SenseVoiceSmall 使用 FunASR 模型协议。详细依赖许可、架构和测试方法见[第三方许可](../THIRD_PARTY_NOTICES.md)、[架构](architecture.md)和[测试记录](validation.md)。旧版截图与当前多语言回放各自标明来源；当前回放使用虚构合成语音和真实模型输出。

## 更新记录

0.4.0 带来悬浮转录、连续发言处理和敏感度校准。查看[完整中文版本说明](release-notes-0.4.0.md#中文更新说明)与[更新日志](../CHANGELOG.md)。