wispr-flow-dictionary

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wispr Flow dictionary

Wispr Flow 词典

Wispr Flow is a macOS dictation app. It has no CLI, and its remote MCP server covers meetings, not dictation history or the dictionary. It keeps both in a local SQLite database, and

scripts/wispr.py

is the interface to it. Go through the script for every read and write, so the database internals stay in one place.

Run

status

first. When it reports a

CHANGED

schema, stop and inspect the changed tables before any write. Take every count you report from

count

Wispr Flow 是一款 macOS 听写应用。它没有 CLI，且其远程 MCP server 仅涵盖会议场景，不支持听写历史或词典。它将两者都保存在本地 SQLite 数据库中，而

scripts/wispr.py

是访问它们的接口。所有读写都应通过该脚本进行，让数据库内部细节集中在一处。

先运行

status

。如果它报告 schema 为

CHANGED

，停止操作，并在任何写入之前检查发生变化的表。你报告的每个计数都应取自

count

。

Commands

命令

bash

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

Command	What it does
`status`	Checks the database. A `CHANGED` schema means an app update changed the database tables the script reads and writes.
`history`	Dictations in a window ( `--since 30m` , `3h` , `2d` , `1h30m` , or `--from` / `--to` ). `--diff` shows only the words formatting swapped; `--fields raw,formatted` shows both texts; `--out FILE` writes to a file.
`terms`	Name-like and command-like words in a window, with counts, whether the dictionary has them, and hits since it got them.
`snippets`	Links, emails and sentences dictated in full again and again, and whether a snippet already expands to them.
`count TERM...`	Dictations containing each term, whole word, any case, with hits since its dictionary entry was added. `--field formatted` counts only what was pasted.
`dict list` / `add` / `remove` / `undo` / `backup`	The dictionary. Every write backs up first; `add` prints a batch id that `undo` reverts. `--restart` quits Wispr Flow before the write and relaunches it after, which is how the app loads a change. `add --snippet` makes a trigger phrase that expands to `--replace` .

Backups go to

~/.local/state/wispr-flow/backups/

; the newest 30 are kept. Change that with

--backup-dir

and

--keep-backups

or the

WISPR_FLOW_*

variables. Put the two options before the command, since the script rejects them after it.

Entries the app learned from the user's edits have

source: user_edits

, and

observedSource

holds what it had heard.

bash

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

命令	作用
`status`	检查数据库。schema 为 `CHANGED` 表示应用更新修改了脚本读写所用的数据库表。
`history`	指定时间窗口内的听写（ `--since 30m` 、 `3h` 、 `2d` 、 `1h30m` ，或 `--from` / `--to` ）。 `--diff` 仅显示被 formatter 替换过的词； `--fields raw,formatted` 同时显示两种文本； `--out FILE` 将结果写入文件。
`terms`	窗口内类似名称和命令的词，以及它们的计数、词典中是否已有这些词，以及自词典收录后命中的次数。
`snippets`	反复完整听写的链接、邮箱和句子，以及是否已有 snippet 可展开为这些内容。
`count TERM...`	包含各 term 的听写，按完整词匹配且不区分大小写，并显示自其词典条目添加以来的命中次数。 `--field formatted` 只统计实际粘贴的文本。
`dict list` / `add` / `remove` / `undo` / `backup`	管理词典。每次写入前都会先备份； `add` 会打印可供 `undo` 撤销的 batch id。 `--restart` 会在写入前退出 Wispr Flow，并在写入后重新启动，应用通过这种方式加载更改。 `add --snippet` 会创建一个可展开为 `--replace` 的触发短语。

备份保存在

~/.local/state/wispr-flow/backups/

；默认保留最新 30 份。可通过

--backup-dir

和

--keep-backups

或

WISPR_FLOW_*

变量进行修改。由于脚本拒绝在命令之后传入这些选项，因此要将这两个选项放在命令之前。

应用从用户编辑中学习到的条目带有

source: user_edits

，而

observedSource

保存应用此前听到的形式。

The dictionary

词典

A word (phrase, no replacement) teaches Wispr the term. Fix with a word first, for a mishearing as much as a misspelling: add
```
Herdr
```
, not
```
Herder
```
→
```
Herdr
```
.
A rule (phrase plus replacement) rewrites a phrase every time it is heard. Propose one only when the mistake keeps coming after its word was added, or when the intended word is an ordinary one a word entry can't teach, such as
```
work tree
```
→
```
worktree
```
. The user decides.
To see whether a mistake came back, count the wrong form in pasted text from the day its word was added:
```
count <wrong form> --field formatted --from <date>
```
, with the date from
```
In dictionary since
```
in the intended word's
```
count
```
row. The since-added columns of
```
count
```
and
```
terms
```
count the entry's own phrase, so they show the word in use, not its mishearings.
A rule's phrase matches whole words, so a plural needs its own rule (
```
cloud sessions
```
).
Matching ignores case. Add each entry once, spelled exactly as it should appear: brand casing for names (
```
GitHub
```
,
```
WebMCP
```
), lowercase for commands (
```
npx
```
,
```
to-pr
```
). A second entry in another case does nothing.
A rule is safe only when its phrase is not something the user also means literally.
```
city
```
→
```
Citi
```
breaks the word city; add
```
Citi
```
as a word instead.
A snippet is a short trigger phrase that expands to longer text, such as
```
my email address
```
→ the address. Propose one only for text the user dictates in full again and again.

word（短语，不带替换内容）用于教会 Wispr 该术语。无论是误听还是拼写错误，都应优先使用 word 修复：添加
```
Herdr
```
，而不是添加
```
Herder
```
→
```
Herdr
```
。
rule（短语加替换内容）会在每次听到该短语时重写它。仅在添加对应 word 后错误仍反复出现，或目标词是普通词汇、word 条目无法教会它时，才提出 rule，例如
```
work tree
```
→
```
worktree
```
。最终由用户决定。
要判断错误是否再次出现，请从目标 word 添加当天起，在粘贴文本中统计错误形式：
```
count <wrong form> --field formatted --from <date>
```
，日期取自目标 word 的
```
count
```
行中的
```
In dictionary since
```
。
```
count
```
和
```
terms
```
中“自添加以来”的列会统计条目自身的短语，因此显示的是 word 的使用情况，而不是其误听形式。
rule 的短语按完整词匹配，因此复数形式需要单独的 rule（
```
cloud sessions
```
）。
匹配不区分大小写。每个条目只添加一次，拼写应与最终显示完全一致：名称采用品牌大小写（
```
GitHub
```
、
```
WebMCP
```
），命令采用小写（
```
npx
```
、
```
to-pr
```
）。以其他大小写再添加一个条目不会产生任何效果。
只有当 rule 的短语不是用户也会按字面表达的含义时，它才是安全的。
```
city
```
→
```
Citi
```
会破坏单词 city；应改为将
```
Citi
```
添加为 word。
snippet 是一种可展开为较长文本的简短触发短语，例如
```
my email address
```
→ 地址。仅针对用户反复完整听写的文本提出 snippet。

Fixing a mistake the user just reported

修复用户刚报告的错误

When the user says a word came out wrong ("I said skill, it wrote SQL"), fix it in the same turn:

```
count
```
both forms with no window, which covers the full history, to see whether the wrong form is also a word the user means. SQL was: several dictations meant it.
Choose the fix:
- If the intended word is missing: add it as a word with
```
--restart
```
  .
- If the word is there and the wrong form still turns up since it was added: propose a rule instead.
- If the wrong form is also a word the user means: propose no rule, and tell the user why a rule would do harm.
Tell the user what was added, and that the next review will show whether it held.

当用户表示某个词被写错时（"我说的是 skill，它写成了 SQL"），应在同一轮中完成修复：

不设置窗口，对两种形式运行
```
count
```
，以覆盖完整历史，从而判断错误形式是否也是用户实际想表达的 word。SQL 的统计结果是：有多条听写确实指 SQL。
选择修复方式：
- **如果目标词不存在：**使用
```
--restart
```
  将其作为 word 添加。
- **如果该 word 已存在，但添加后错误形式仍再次出现：**改为提出 rule。
- **如果错误形式也是用户实际想表达的 word：**不要提出 rule，并告诉用户为什么 rule 会造成伤害。
告诉用户添加了什么，并说明下次检查将显示该修复是否持续有效。

Finding transcription mistakes

查找转写错误

Look for the words speech recognition gets wrong most, and more so with a non-native accent: names of people, companies, products, tools, and CLI commands.

Read the dictionary, the
```
terms
```
table and the
```
--diff
```
history for the window, the last 24 hours by default. Then read every dictation in the window, raw and formatted:
```
terms
```
and
```
--diff
```
miss mishearings that came out as ordinary words the formatter left unchanged ("verb tree", "two PR").
- When the user names a window: use that window instead.
- When the window is longer than a few hours: write
```
history --fields raw,formatted
```
  with
```
--out
```
  to a file in a temporary directory outside any repository and read that file in pages, since it costs about 30k tokens per day of dictation and the dictations are private.
Find candidates: words that are wrong in context, such as a real word where a name belongs ("Herder session", "cloud code"), a name spelled several ways, or a command turned into a word ("Sila" for CLI). Check the raw text too; formatting sometimes hides a mishearing and sometimes fixes it.
Confirm the intended word from the surrounding text and the user's projects: the one open now, and any other the dictation was about, which the
```
app
```
column shows. Grep them for the name.
- Where the intended word can't be established: list it under Unclear and ask.
Count every misheard form and every intended form over the same window, and repeated snippets over the last 30 days.

Report, in exactly this shape:

markdown

### 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?

Leave out anything already in the dictionary.

When an entry is still being misheard after it was added: it moves to Rules to add ("
```
CLI
```
is a word since 09-28, heard as Sila twice since").
When a section is empty: drop it.

Write only after the user approves the list. Put the approved entries in a JSON file:

json

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

Dry-run it with

dict add --file <file> --dry-run

, tell the user Wispr Flow will close for a few seconds, write it with

dict add --file <file> --restart

, and give the user the batch id.

The app syncs the dictionary to the user's account. Entries written this way have survived a restart; whether a sync ever drops them is not known, so say so when reporting a write.

重点寻找语音识别最常听错的词；在非母语口音下尤其如此，包括人名、公司、产品、工具和 CLI 命令。

读取指定窗口的词典、
```
terms
```
表和
```
--diff
```
历史记录，默认窗口为最近 24 小时。然后读取窗口内每条听写的 raw 和 formatted 文本：
```
terms
```
和
```
--diff
```
会漏掉那些被听成普通词、而 formatter 未作改动的误听（"verb tree"、"two PR"）。
- **当用户指定时间窗口时：**改用该窗口。
- **当窗口超过几小时时：**运行
```
history --fields raw,formatted
```
  ，使用
```
--out
```
  将文件写入 repository 之外的临时目录，并分页读取该文件，因为每一天的听写约耗费 30k tokens，且听写内容属于隐私数据。
**寻找候选项：**寻找在上下文中不正确的词，例如本应是名称却成了真实普通词（"Herder session"、"cloud code"），同一人名有多种拼写，或命令被写成普通词（用 "Sila" 表示 CLI）。也要检查 raw 文本；formatter 有时会掩盖误听，有时又会把误听修正。
**确认目标词：**根据上下文和用户项目判断：当前打开的项目，以及听写所涉及的其他项目；
```
app
```
列会显示这些信息。在这些项目中 grep 该名称以进行确认。
- **无法确定目标词时：**将其列在 Unclear 下并询问用户。
统计同一窗口内每个误听形式和每个目标形式的次数，以及最近 30 天内重复出现的 snippet。

报告，严格使用以下格式：

markdown

### 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
```
自 09-28 起已是一个 word，但此后仍两次被听成
```
Sila
```
”）。
**如果某个部分为空，则删除该部分。

写入前必须获得用户对清单的批准。将获批条目放入 JSON 文件：

json

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

先使用

dict add --file <file> --dry-run

进行 dry-run，告诉用户 Wispr Flow 会关闭几秒钟，再使用

dict add --file <file> --restart

写入，并向用户提供 batch id。

应用会将词典同步到用户账户。以这种方式写入的条目已能在重启后保留；至于同步过程是否会丢失它们尚不清楚，因此写入后报告时应说明这一点。

Scripts

脚本

scripts/wispr.py: the one interface to Wispr Flow's database.

scripts/wispr.py：访问 Wispr Flow 数据库的唯一接口。