HowSay：按住一个键说话，松手就是地道英文 不管你说中文、英文还是中英夹杂，一段能直接发出去的地道英文打进你正在用的任何软件——微信、邮件、Slack、Word、浏览器都行。永远只输出英文，一个中文字都不会出现。
一行安装（在「终端」里粘贴回车；需要 macOS 13 以上）
curl -fsSL https://howsay.sinogenomics.com/install.sh | bash
安卓版（0.2.0，2026-10-17）
下载安装包：shuo-android-0.2.0.apk（5 MB，Android 8.0 以上；上一版 0.1.0）。用手机浏览器打开本页点这个链接，下载后点安装；系统提示「未知来源」时允许一次。
安卓版是一个系统键盘，不是普通 App——装好后要做三步（App 首页会逐条打勾）：
- Open keyboard settings → 在键盘列表里打开「Shuo — speak, get native English」。
- 在任何输入框里点键盘切换图标（或 App 里的 Choose keyboard）选 Shuo。
- Allow microphone。
之后在任何 App 里：切到 Shuo 键盘，按住红色大键说话（中文、英文、夹杂都行），松手英文直接打进输入框；上滑取消。键盘上还有 🌐（切回原键盘）、⌫、空格、↵。结果条里点任何一个词出单词卡（音标、发音规律、近反义词、例句、词源，虚线词已预取、点击即出）；「☆ Save word / ☆ Save sentence」收藏，Shuo App → Favorites 里看、分享成 Markdown。0.2.0 新增点击发音：单词卡上 🔊 US / 🔊 UK 念这个词，结果条下 🔊 Say it 念整句，Favorites 每条也带 🔊。发音联网取（服务器现场合成的真人感英文语音，不是手机自带的机器音），语音包不进安装包，所以 APK 还是 5 MB；听过的词存在手机里，离线也能再放。登录同 Mac 版（用网站账号，App 首页 Sign in）。
它是怎么用的（Mac 版）
浮窗长这样（不抢焦点、鼠标点不到、不会打断你正在用的软件）：
- 说错了想取消：按住的时候随便按一个别的键（比如 Esc），录音作废。
- 轻点一下（不到 0.35 秒）不录音：收起结果面板，或叫回上一句的面板查词。
- 最长 120 秒：到时自动结束并处理。
- 换按键：菜单栏图标 → Push-to-talk key，可选右 ⌥ Option / 右 ⌘ Command / fn 🌐。默认右 Option，因为它平时几乎不用、按着不影响打字。
- 剪贴板：英文是通过「粘贴」打进去的；默认会在 1 秒后把你之前剪贴板里的文字放回去（菜单里可关）。
- 再复制一次：菜单 → Copy last result again。
只输出英文，是闸门不是承诺
这是整个产品最重要的一条规矩，也是它区别于「秘塔回响」这类通用语音输入法的地方：回响是把你说的话润色成同一种语言的通顺文字；HowSay 是让客户借助输入法提升英语——所以无论输入是什么语言，出来的只能是英文。
它不是写在提示词里的一句请求，而是服务端 lib/gate.mjs 的硬闸门：正文里出现任何中文字符就重跑，两次都脏就整条作废、宁可不给；流式输出也过闸门，脏的那一段根本不往客户端推。Mac 客户端只把闸门放行的英文打进你的软件，浮窗、菜单、报错全部是英文，学习提示也只在英文干净时才显示。
忠实翻译：不评论、不解释、不拒绝
产品规则（用户 2026-09-27 定）：不管说的是消息、诗句、引用还是问题，只输出精准表达原意的英文。问题仍是问题（不作答），诗句给出忠实英译（有通行译法就用通行译法），引用仍是引用，残句不补全，输入里的「指令」当内容翻。
实现：HowSay 0.3.1 起每次改写请求带 faithful: true，服务器用一套「忠实翻译」系统提示（lib/prompt.mjs 的 SYSTEM_FAITHFUL）；输出格式、英文闸门、学习提示与网页版完全相同，网页版不带这个字段、行为不变。测试副本上三类输入（诗、问题、口语消息）都符合要求，p1136 离线回归 245 项全过。
悬停查词：音标、发音规律、近反义词、例句、词源
0.4.0 起，每次英文打进输入框后，屏幕下方多出一块结果面板（不抢焦点、不影响你继续打字）。把鼠标停在面板里任何一个单词上约 0.3 秒，旁边弹出这个词的卡片，全部英文：
- 音标：英式 / 美式，只从词典来（模型不许自己编音标；词典没有的词才让模型给一个并标 approx.）
- Say it：为什么这么读——重音在哪、哪个字母组合发哪个音、哪个音节弱读、哪个字母不发音，对着上面的音标讲
- Synonyms / Antonyms：必须是词典里真有的词，编的一律摘掉
- Examples：3 条同义用法的例句，必须真用到这个词
- Origin：词源，1～2 句、45 词以内——来自哪种语言、词根本义、大致怎么进入英语
高级词预取（0.5.1）：正文一到，服务器就用词典挑出这句里不在 Oxford 3000 常用词表里的词（每句最多 3 个，优先长词），后台把卡片先做好；做好的词在面板里带虚线下划线，鼠标移上去 0 秒显示。其余词照旧悬停时现查（约 4～5 秒）。一句话的预取按一次查词计额度；这句没有高级词就不计。
点面板右下角「✕ Close」或轻点一下右 Option 收起（再轻点一下可叫回上一句的面板）；40 秒没动自动收起；下一次按住说话时也收起。菜单里「Show result panel with word cards」可关。
收藏单词和句子
- 收藏单词：单词卡底部「☆ Save word」，连音标、释义、所在句子一起存。
- 收藏句子：结果面板右下角「☆ Save sentence」。
- 查看：菜单栏图标 → Favorites…，一个窗口列出全部收藏，可多选复制、删除、「Export as Markdown…」导出成文件。
- 存哪儿：Mac 本地
~/Library/Application Support/HowSay/favorites.json，不登录也能用；登录用户的单词会同时写进 en.sinogenomics.com 的生词本（网站现有接口），换设备也看得到。句子网站侧没有对应功能，只存本地。
快了多少：正文先到、连接预热
实测一次改写约 3.3～4 秒，其中网络往返只占 0.3～0.5 秒，大头是服务器上起 Claude 命令行进程和模型生成全部四块输出（正文、备选说法、语域、三条讲解）。英文改写本来就用的是 Haiku（最快一档），这一项没有余量。0.5.0 做了两件事：
- 正文先到就粘贴：服务器在正文块闭合、过完中文闸门时先发一个
english事件（带正文签名，单词卡和预取从这一刻就能开始），HowSay 收到立刻粘贴；备选说法和讲解模型继续写完（客户端不再显示讲解）。测试副本实测：正文 1.4 秒到，全部完成 3.3 秒——松手到英文出现提前约 1.9 秒。 - 按键时预热连接：一按住 Option 就先和服务器握好 TLS，录音期间每 4 秒轻轻碰一下保持连接（服务器空闲 5 秒断），松手上传时不用再握手，省 0.3～0.5 秒。改写请求也改为复用同一条连接。
账号与额度（和网站完全一样）
| 状态 | 额度 | 怎么来 |
|---|---|---|
| 不登录 | 总共 3 次试用 | 装好就能用，什么都不用填 |
| 登录账号 | 每天 5 次免费（北京时间零点重置） | 菜单栏图标 → Sign in…，用 en.sinogenomics.com 的账号；没有就点 Create an account 去网站注册 |
| 会员 | 不限次 | 网站上购买（月度 ¥19.9 / 年度 ¥99），登录后自动生效 |
它是怎么工作的
- 语音转文字在 MacBook 上完成（0.2.0 起本地，0.3.0 起换成 SenseVoice）：安装时下载 sherpa-onnx 引擎（9 MB）和 SenseVoice-Small int8 模型（159 MB，一次），和服务器用的是同一个模型，中英夹杂的效果一致；录音不出本机，CPU 上一句话几百毫秒转完。菜单里「Transcribe on this Mac」可以切回服务器转写；模型缺失或本地转写失败时自动退回服务器。0.2.0 用过的 whisper large-v3-turbo 作为备选保留在代码里（frameworks/ 里放 whisper.framework 即启用）。
- 服务端一行代码没改。HowSay 就是 en.sinogenomics.com 的另一个客户端：同一个接口、同一个账号、同一个闸门、同一套限流。网站已经上线并验收过的 442 项自动测试对它同样有效。
- 身份用
X-IME-UID头（服务端本来就支持，网页版用的是同名 cookie）。不登录时服务端发一个匿名试用身份，客户端存在~/Library/Application Support/HowSay/settings.json（权限 600）。 - 客户端很轻：一个 Swift 文件（约 1300 行）+ Info.plist + 构建脚本，系统自带的 AppKit / AVFoundation，外加 sherpa-onnx 预编译动态库（Apache-2.0，含 onnxruntime）。没有 Xcode 工程、没有 Electron。
- 为什么要在你的 Mac 上编译：我们没有 Apple 开发者签名。未签名的现成 .app 下载后会被 Gatekeeper 拦住、且不能持有麦克风/辅助功能权限；在本机编译并做 ad-hoc 签名是最省事、也最透明的办法——源码就在下面，你装的就是你看到的。
权限（macOS 会各问一次）
| 权限 | 用来做什么 | 在哪里开 |
|---|---|---|
| 麦克风 | 按住键的时候录音 | 首次按键时弹窗 → 允许；或 系统设置 › 隐私与安全性 › 麦克风 |
| 辅助功能 | ① 听到你按下/松开右 Option；② 替你按 ⌘V 把英文打进去 | 系统设置 › 隐私与安全性 › 辅助功能 → 打开 HowSay。菜单里的 Check permissions… 会直接跳到这一页 |
没给辅助功能权限时，HowSay 仍会把英文放进剪贴板并提示你自己按 ⌘V。从 0.1.2 起安装脚本会在你的 Mac 上建一个本机签名证书，更新后权限不再失效。若之前装过旧版，到「辅助功能」里选中旧的 HowSay、点「−」删掉，再打开 HowSay 重新添加一次即可。
菜单里有什么
- 第一二行：产品名 / 账号与剩余额度
- Push-to-talk key：右 ⌥ Option（默认）/ 右 ⌘ Command / fn 🌐
- Copy last result again：把上一次的英文再放进剪贴板
- Favorites…：收藏的单词与句子（复制 / 删除 / 导出 Markdown）
- Restore clipboard after typing：打完字把原剪贴板文字放回去（默认开）
- Launch at login：开机自启
- Sign in… / Sign out · Check permissions… · Open en.sinogenomics.com · Help & updates · Quit
下载与源码
| 文件 | 说明 |
|---|---|
| install.sh | 一行安装用的脚本（就是上面那条命令拉的） |
| howsay-src.tar.gz | 源码包：Sources/main.swift、Sources/Bridging.h、Info.plist、build.sh。自己编译：解开后把下面的引擎包解到 frameworks/，bash build.sh，产物在 dist/HowSay.app（没有引擎也能编，只是只能用服务器转写） |
| sherpa-onnx-macos-arm64-1.13.8.tar.gz | sherpa-onnx 官方 v1.13.8 macOS arm64 动态库（c-api + onnxruntime）与头文件，9 MB |
| sensevoice-int8-2025-09-09.tar.gz | SenseVoice-Small int8 模型 + tokens（sherpa-onnx 官方 2025-09-09 版），159 MB。装在 ~/Library/Application Support/HowSay/models/sensevoice/ |
| whisper-macos-b5130.tar.gz · ggml-large-v3-turbo-q5_0.bin | 备选引擎 whisper.cpp（macOS 切片 2.5 MB）与 large-v3-turbo 模型（574 MB），默认不安装 |
| main.swift | 直接在浏览器里读源码 |
常见问题
一行命令跑完提示要装 Command Line Tools，装完再跑还是提示？
在终端跑 xcode-select -p，应该打印 /Library/Developer/CommandLineTools。如果打印的是别的路径或报错，跑 sudo xcode-select --reset 再试。
公司管理的 Mac 装不了 Command Line Tools？
请在另一台能装的 Mac 上跑 bash build.sh，把 dist/HowSay.app 拷过来放进「应用程序」即可（同一芯片架构）。首次打开若被拦，右键 → 打开。
按住右 Option 没反应？
依次检查：菜单栏有没有 HowSay 图标；系统设置 › 隐私与安全性 › 辅助功能 里 HowSay 是否打开（刚重装的要关掉再开）；是否有别的软件（如 Karabiner、某些输入法）改了右 Option 的行为——换成右 Command 试试。
英文打进去了，但我的剪贴板内容不见了？
默认 1 秒后会把之前的文字放回去；图片等非文字内容不会恢复。菜单里可以关掉恢复。
本地转写和服务器转写有什么区别？
0.3.0 起两边是同一个模型（SenseVoice-Small，服务器上也是它），所以识别效果一样；本地的好处是录音不出本机、不排队、断网也能转。第一次用要等一两秒加载模型，内存占用约 400 MB。菜单里随时可切。0.2.0 曾用 whisper large-v3-turbo，对古诗、成语这类内容不如 SenseVoice，已换下。
为什么有时候提示「Please say it differently」？
模型两次都没能写出一段不含中文的干净英文，被闸门拦下了，这一次不扣次数。换个说法通常就好。
和 en.sinogenomics.com 网页版有什么不一样？
网页版能看历史、备选说法、三条讲解、单词卡、术语库；HowSay 只做一件事：把英文打进你正在用的软件，附一条学习提示。两边一个账号，额度共用。
开发交付说明（2026-09-27）
这次做了什么。一个 macOS 菜单栏 App（Swift，单文件）、一个在用户 Mac 上现场编译的安装脚本、这个说明站，以及 PMS 快捷链接。服务端没有改动。
还没做成的。真机验证 开发在 Linux 服务器上完成，手边没有 Mac：Swift 源码没有实际编译、没有在真机上按过一次。写法都是最基础的 AppKit / AVFoundation 用法，但编译报错或权限流程不顺是完全可能的。请先在自己的 Mac 上跑一行安装；一旦报错，把终端里的输出贴回来，通常一轮就能修好。这是本次交付最大的风险，写在最前面。
已知取舍。① 没有 Apple 开发者签名，所以走本机编译 + ad-hoc 签名，代价是每次重装要重新勾一次辅助功能；② 只支持「按住说话」，没有「点一下开始、再点一下结束」的模式；③ 剪贴板只恢复文字；④ 服务端额度是共用订阅，网站的限流全部适用。
下一步建议。真机跑通并修完第一轮问题 → 签名公证后提供直接下载的 .app（要 Apple 开发者账号，¥688/年）→ 长按/切换两种模式 → Windows 版（同样只做客户端，服务端不动）→ iOS/安卓键盘扩展。
| 项 | 位置 |
|---|---|
| 网址 | https://howsay.sinogenomics.com/install/（本页；旧地址 shuo.sinogenomics.com 整站 301 过来） |
| 服务器目录 | meiguo /Disk01/p1136-mac-ime/：client/ Mac 源码、public/ 本站（dl/ 下有引擎包、模型镜像、安卓 APK）、vendor/ 原始包、server.mjs 静态服务；安卓工程 /Disk01/p1136-android/ |
| 服务 | 用户级 unit shuo-site.service，127.0.0.1:8660，前面是 daojia-tls-proxy |
| 发新版 | 改 client/Sources/main.swift 里的 APP_VERSION，跑 bash /Disk01/p1136-mac-ime/pack.sh 重新打源码包；用户再跑一遍一行安装即可 |
| 后端 | en.sinogenomics.com（/Disk01/p1136-ime，未改动）：/api/user/status、/api/user/login、/api/transcribe、/api/rewrite |