wispr-flow-dictionary

Wispr Flow 词典

Wispr Flow 是一款 macOS 听写应用。它没有 CLI，其远程 MCP 服务涵盖会议，而不包括听写历史或词典。两者都存储在本地 SQLite 数据库中，scripts/wispr.py 是访问接口。所有读写都通过该脚本进行，以便将数据库内部细节集中在一处。

先运行 status。如果报告的架构状态为 CHANGED，请停止操作并检查发生变化的表，然后再进行任何写入。报告的所有计数都从 count 获取。

命令

python3 <skill-dir>/scripts/wispr.py <command> --help

命令	功能
status	检查数据库。架构状态为 CHANGED 表示应用更新更改了脚本读写的数据库表。
history	指定时间范围内的听写记录（--since 30m、3h、2d、1h30m 或 --from/--to）。--diff 仅显示格式调整过的词语；--fields raw,formatted 显示两种文本；--out FILE 将内容写入文件。
terms	指定时间范围内类似名称和命令的词语，包括计数、词典中是否已有这些词语，以及收录后出现的次数。
snippets	一再完整听写的链接、电子邮件和句子，以及是否已有片段可展开为这些内容。
count TERM...	统计包含各个词条的听写记录数；按完整单词匹配，不区分大小写，并显示词条添加后出现的次数。--field formatted 只统计粘贴的内容。
dict list / add / remove / undo / backup	词典。每次写入前都会备份；add 会打印一个批次 ID，可用 undo 撤销。--restart 会在写入前退出 Wispr Flow，并在写入后重新启动，这是应用加载更改的方式。add --snippet 会创建一个可展开为 --replace 内容的触发短语。

• 备份位置： ~/.local/state/wispr-flow/backups/，保留最新的 30 个备份。
• 选项覆盖： 使用 --backup-dir 和 --keep-backups，或 WISPR_FLOW_* 变量。请将这两个选项放在命令之前，因为脚本会拒绝放在命令之后的选项。

应用从用户的编辑中学到的词条带有 source: user_edits，而 observedSource 保存的是应用原先听到的内容。

词典

• 单词是不带替换内容的短语，用于教会 Wispr 识别词条。如果听写有误，先添加正确的词；无论是误听还是拼写错误都一样：添加 Herdr，而不是 Herder → Herdr。
• 规则是带有替换内容的短语，每次听到该短语时都会改写它。只有在添加对应单词后错误仍反复出现，或者目标词是单词词条无法教会应用识别的常见词时，才提出规则，例如 work tree → worktree。由用户决定。
• 要检查错误是否再次出现，请从添加对应单词当天起，在粘贴的文本中统计错误形式：count <wrong form> --field formatted --from <date>，其中日期取自目标单词 count 行里的 In dictionary since。count 和 terms 中表示添加后次数的列统计的是词条本身的短语，因此显示的是该词的使用情况，而不是误听情况。
• 规则的短语按完整单词匹配，因此复数形式需要单独的规则（cloud sessions）。
• 匹配时不区分大小写。每个词条只添加一次，并按其应显示的拼写添加：名称使用品牌大小写（GitHub、WebMCP），命令使用小写（npx、to-pr）。再添加一个大小写不同的词条没有作用。
• 只有当用户不会也把规则短语按字面意思使用时，该规则才安全。city → Citi 会破坏单词 city；应将 Citi 作为单词添加。
• 片段是可展开为较长文本的简短触发短语，例如 my email address → 电子邮件地址。只有对于用户一再完整听写的文本，才提出片段。

修正用户刚刚报告的错误

当用户说某个词识别错了（“我说的是 skill，它写成了 SQL”）时，在同一轮中修正：

1. 不设时间窗口，用两种形式执行 count，以覆盖完整历史记录，查看错误形式是否也是用户想说的词，例如对从事数据库工作的用户来说，SQL 就是一个有效词。
2. 选择修正方式：
   • 如果缺少用户想说的词： 使用 --restart 将其添加为词条。
   • 如果该词已存在，但自添加后错误形式仍会出现： 改为建议添加规则。
   • 如果错误形式也是用户想说的词： 不建议添加规则，并告诉用户规则会造成什么问题。
3. 告诉用户添加了什么，并说明下一次复查会确认是否生效。

查找转录错误

重点查找语音识别最容易识错的词：人名、公司名、产品名、工具名和 CLI 命令。

1. 阅读词典、terms 表，以及该时间窗口内的 --diff 历史记录；默认窗口为最近 24 小时。然后阅读窗口内每条听写的原始文本和格式化文本：terms 和 --diff 会漏掉那些被识别成普通词、且格式化器未作更改的误听词（“verb tree”“two PR”）。

   • 用户指定时间窗口时： 使用该窗口。
   • 时间窗口超过几小时时： 使用 history --fields raw,formatted 并通过 --out 将结果写入仓库外临时目录中的文件，然后分批读取该文件，因为每天的听写约消耗 30k 个 token，而且听写内容属于隐私。

2. 查找候选项： 在上下文中不正确的词，例如本应是名称的位置出现了普通词（“Herder session”“cloud code”）、同一个名称出现多种拼法，或命令被识别成普通词，例如 CLI 被识别为 “Sila”。也要检查原始文本；格式化有时会掩盖误听，有时则会修正误听。

3. 根据上下文和用户的项目确认用户想说的词：当前打开的项目，以及听写内容涉及的其他项目（app 列会显示这些项目）。在项目中用 grep 查找该名称。

   • 无法确认用户想说的词时： 将其列在 Unclear 下并询问用户。

4. 在同一时间窗口内统计每个误听形式和用户想说的形式，并统计过去 30 天内重复出现的片段。

5. 按以下格式报告：

   ### Words to add
   | Word | Wispr wrote | Dictations | Example |
   
   ### Rules to add
   | Wispr writes | You meant | Dictations | Since its word was added | Example |
   
   ### Snippets to add
   | Trigger | Expands to | Dictations |
   
   ### Not fixable with the dictionary
   - <mishearing>: <why a rule would do harm, or what would fix it instead>
   
   ### Unclear
   - "<what Wispr wrote>": <the context>. What did you say?
   

   不要列出词典中已有的词条。

   • 添加后仍被误听的词条： 将其移至 Rules to add（“CLI 是一个词，但自添加后被听成 Sila 两次”）。
   • 某个部分为空时： 删除该部分。

6. 只有在用户批准列表后才写入。将批准的词条放入 JSON 文件：

   [{"phrase": "Figma"}, {"phrase": "work tree", "replacement": "worktree"}, {"phrase": "my site", "replacement": "https://example.com", "snippet": true}]
   

   使用 dict add --file <file> --dry-run 执行试运行，告诉用户 Wispr Flow 将关闭几秒钟，再使用 dict add --file <file> --restart 写入，并告知用户批次 ID。

应用会将词典同步到用户的帐户。以此方式写入的词条在重启后仍会保留。已知缺口： 尚不确定同步是否会删除这些词条，因此报告写入结果时要说明这一点。

脚本

• scripts/wispr.py：与 Wispr Flow 数据库交互的唯一接口。