Lexicon

You said:        "tell Ashlr.AI to deploy the Kubernetes auth service"
STT heard:       "tell Ashler to deploy the Cooper Nettie's off service"
Agent received:  "tell Ashlr.AI to deploy the Kubernetes auth service"

这就是在线演示，它在浏览器中使用本仓库的真实匹配器处理你的文本，无需安装任何内容。（其中的 Dictate 按钮使用浏览器自带的语音识别器；在 Chrome 中，音频会发送给 Google。）

测量结果

方法、完整表格和所有失败案例见 docs/BENCHMARK.md。可通过 npm run bench 复现（克隆后无需额外设置），或运行 npm run bench:audio && npm run bench:compare（需要 macOS 和 whisper.cpp）。

与其他方案对比。 将 330 段合成（文本转语音）音频交给 whisper.cpp small.en 处理，使用三个音色。每一行使用相同的音频、识别器和包含 70 个词条的词典；唯一变化的是专有名词的修正方式。

词语修正方式	找回的专有名词	被错误修改的通顺文本
不作处理，使用原始 whisper.cpp 输出	45.9%	不适用，不作处理
精确字符串替换，即 macOS“文本替换”方案	62.0%	72 段中 0 段
同上，另为每个词条添加大小写规则	71.3%	72 段中 0 段
whisper.cpp 自带的 --prompt 提示词列表	76.0%	不适用，不作处理
Lexicon	91.0%	72 段中 0 段

每一行都使用同一份精选的 70 词词典（bench/lexicon.yaml）。通顺文本这一列的结果既取决于匹配器，也取决于词典中的词条，因此，用其他方式编制的词典会得出不同的测量结果。

精确替换只能找回已有书面拼写的词，无法做到更多。它无法识别 Versal、Superbase、CloudFloor 或 pedantic，因为手动编写的表中不可能包含你尚未听到过的错误形式。音位和模糊匹配层正是为弥补这一缺口而设，它们单独找回了 279 个词条位置中的 31 个，即提升 11 个百分点。相比启用大小写匹配的方案多出的 9 个百分点，则来自别名层对识别器拆分名称方式的容错，因为该方案已经能匹配大小写。--prompt 是补充手段，而非竞争方案：与词典结合使用时，准确率可达 95.7%。 关于该表，有两点需要如实说明。原始 whisper.cpp 不可能错误地改写正文，因为它不执行任何处理；这只是缺少该功能，并非优势。--prompt 则不同：它会影响识别器本身，因此它造成的任何变化，在开始评分前就已经体现在转录文本中；而该指标统计的是后处理阶段改动的句子。该单元格的数据未测量，并非为零。要判断它的影响方向，就得比较使用提示词和不使用提示词时的转录文本差异，而这个测试框架并未这样做。

前后对比。

语料	原始语音转文字中识别出的专有名词	使用词库后	被错误改动的通顺正文
TTS 音频，whisper.cpp base.en（330 个片段）	41.9%	82.8%	72 个中有 0 个
TTS 音频，使用提示词提示的 whisper.cpp small.en	76.0%	95.7%	72 个中有 0 个
合成的语音转文字错误（402 个句子，70 个术语）	5.1%	96.8%	95 个中有 0 个

该测试框架中的延迟约为每个句子 0.3 ms。TTS 音频行使用 macOS 文本转语音朗读，再输入 whisper.cpp，因此比手机麦克风录音更干净。espanso 和 whisper.cpp 的另一项同虚拟机对比（安装、延迟、内存）见 docs/BENCHMARKS.md。

合成数据中的 5.1% 并不表示语音转文字通常能正确识别 5% 的专有名词。该语料中的每个句子都是专门编写来包含误听的，因此 5.1% 仅指少数碰巧仍被正确识别的情况。真实的「前」数据是 TTS 音频中的 41.9%。

最后一列只统计普通正文。每个语料还包含一些专门设计来触发匹配器的句子（例如 Ollama 相关术语旁出现单独的「llama」、近音词、代码片段），并标记为 expected-hard；计入这些句子后，合成语料中的误报率为 15.3%（124 个中有 19 个），音频语料中为 16.7%（90 个中有 15 个）。这两个数据，以及所有失败案例，均见 docs/BENCHMARK.md。

留出数据检查（单独的内部测试，使用未见过的声音）。 上述表格使用了针对测试术语编写的词库。为了测试更难的情况，我们只从其他句子和声音中学习别名，然后在从未用于学习的声音和句子上评分（63 个片段）。三个开源文本转语音声音合成的语音输入 whisper.cpp；只有恢复所有目标术语的片段才计为正确。

识别器	原始结果	词库，仅含规范术语	词库，加上从其他片段中学到的别名
whisper.cpp base.en	63 个中有 16 个	63 个中有 38 个	63 个中有 44 个
whisper.cpp small.en	63 个中有 25 个	63 个中有 39 个	63 个中有 42 个

该轮测试中，词库改动的通顺正文：60 个中有 0 个。

Whisper 提示词注意事项。 在同样的 378 个片段上，仅使用 whisper 的 --prompt 提示词列表，就将 base.en 的正确片段数从 97 提升到 228，将 small.en 的正确片段数从 141 提升到 320；因此，提示词是很强的基线，词库在此基础上的增益较小（使用词库后，base.en 为 271，small.en 为 339）。提示词还使 base.en 生成了 55 份退化转录文本（空文本或循环文本），而不使用提示词时为 5 份，因此提示词对小型模型并非没有代价。这里的音频全部为合成音频，并非麦克风录音；测试框架也尚未发布，因此在发布前请将这些数据视为内部数据。

安装

软件包为 @ashlr/lexicon；命令为 lexicon。

curl -fsSL https://ashlrai.github.io/lexicon/install.sh | sh   # CLI + the setup wizard
brew install ashlrai/tap/lexicon                               # or Homebrew (macOS, Linux)
npm i -g @ashlr/lexicon                                        # or npm (Node 20+)

然后打开 Claude Code，说一句包含你公司名称的话。完成。关于在全新 Linux 虚拟机上安装的计时演示，以及给 Agent 的说明，请参阅 docs/FIRST-RUN.md。

npm 目前提供的是 @ashlr/lexicon 0.5.4，而此源代码树的版本是 0.5.6（可通过 npm view @ashlr/lexicon version 查看）。自 0.5.4 以来的更改（例如下方的 lexicon export 格式建议）尚未包含在已发布的 npm 软件包中。

安装脚本在有终端可供提问时会替你运行 lexicon setup；如果没有终端（CI、Dockerfile）、在 sudo 下运行，或设置了 LEXICON_NO_SETUP=1，则只进行安装，并提示你自行运行 lexicon setup，这与通过 Homebrew 或 npm 安装后的情况相同。每个步骤都是可选的，也可以安全地重复运行；lexicon setup --dry-run 不会写入任何内容，只会说明不加该参数运行同一命令时会发生什么：它将执行哪些步骤、哪些步骤会暂停并询问，以及按 Enter 键会对每个问题给出什么回答。

使用 Homebrew 时，务必使用完整的 tap 名称 ashlrai/tap/lexicon。直接运行 brew install lexicon 会安装 dns-lexicon，这是 homebrew-core 中一个无关的 DNS 工具。

`lexicon setup` 的功能，分为七个编号步骤

1. 将你的姓名和公司名称，以及 STT 会产生的拼写错误录入词库。
2. 以清单形式提供入门词包供你选择。
3. 从当前仓库中提取代码里已有的名称。
4. 在检测到的所有 Agent 客户端中注册 MCP 服务和钩子。
5. 将本地 API 安装为登录服务。
6. 导出到你的听写应用。
7. 用刚刚录入的词条组成一句话进行听写，并向你展示纠正结果。

完整演示（包含实际终端输出）请参阅 docs/QUICKSTART.md。

或者跳过向导，手动添加一个词条。第一个参数是规范拼写，其余参数是 STT 实际会产生的内容：

lexicon add Ashlr.AI Ashler Ashlar "Ashler AI" --phonetic ASH-ler
lexicon normalize "tell Ashler to ship it"
# tell Ashlr.AI to ship it

使用十分钟后，教它识别你实际会说出的名称。lexicon import --guided 会询问你的专有名词存放在哪里（联系人、日历、GitHub），展示每个候选词及其来源，并且只写入你批准的词条。你勾选前不会读取任何内容，而且完全不会访问邮件和聊天记录。

Claude Code 插件，如果你不想安装 CLI。无需安装 Node，也无需构建：

claude plugin marketplace add ashlrai/lexicon
claude plugin install lexicon@ashlrai

lexicon doctor 会检查安装情况。此工具不会收集遥测数据。词汇和应用状态都保存在本地文件中；普通钩子、纠正、MCP、本地 API 和扩展路径都不会将转录内容发送到远程服务。显式的网络操作包括：lexicon voice 首次使用时下载 whisper 模型；lexicon pack 从 --registry URL 下载社区词包并验证校验和；以及选择在 lexicon import --guided 中使用 GitHub 来源。该来源通过你现有的 gh 配置和登录状态调用 GitHub API（通常是 api.github.com），获取个人资料、组织成员身份、成员登录名和仓库名称元数据；不会请求新的 OAuth 权限范围。检查前会先选择来源，写入前会先审核候选项。安装脚本、npm 和 Homebrew 会下载软件包本身。详见 SECURITY.md。

GitHub 引导式导入器随 0.5.5 一同发布（PR #25）；npm latest 目前为 0.5.4。

MCP 配置

lexicon install <client> --apply 会替你完成这些操作。手动配置方法如下：

# Claude Code
claude mcp add lexicon -- npx -y -p @ashlr/lexicon lexicon-mcp
# Codex
codex mcp add lexicon -- npx -y -p @ashlr/lexicon lexicon-mcp

Cursor（~/.cursor/mcp.json）：

{ "mcpServers": { "lexicon": { "command": "npx", "args": ["-y", "-p", "@ashlr/lexicon", "lexicon-mcp"] } } }

服务读取的环境变量（LEXICON_PATH、LEXICON_HARVEST_ROOTS、LEXICON_REGISTRIES 等）列在 docs/MCP.md 中。

为什么

普通英语语音转文字的准确率约为 95%，遇到虚构名称时准确率会低得多。在上面的基准测试中，原始 whisper.cpp base.en 正确转写了 279 个口述专有名词中的 117 个。“Ashlr.AI”会变成“Ashler”，“Kubernetes”会变成“Cooper Nettie's”，“SaaS”会变成“sauce”，“auth”会变成“off”。这些恰恰是 Agent 必须识别正确的词。

听写应用（Wispr Flow、Superwhisper、Aqua）各自维护自己的词典，彼此之间无法共享。Agent（Claude Code /voice、ChatGPT 语音、Codex、本地 Whisper）使用各自的识别器，完全没有用户词汇表。这是两者之间可移植的一层：无论文本经过何处，纠正都发生在语音转文字之后、模型处理之前。

这不是一款听写应用。它位于你使用的任何听写工具与交谈的任何 Agent 之间。此方案背后的研究（包括终止标准）见 docs/RESEARCH.md。

你将获得

• 二十一个 MCP 工具、两个资源和两个提示词，适用于 Claude Code、Codex、Cursor、Windsurf、Gemini CLI、VS Code 和 Claude Desktop。你的 Agent 可以自行完成设置：setup_lexicon、lexicon_doctor、install_client、trust_project、import_dictionary、import_vocabulary 和 suggest_terms，让“设置我的词库”无需使用终端即可完成。会修改你设备的工具会先预览：setup_lexicon 和 install_client 会返回计划，在 Agent 传入 apply: true 前不会写入任何内容；uninstall_client（对应 lexicon uninstall）在传入 apply: true 前只会执行试运行；trust_project 会在固定文件前直接征求你的同意（Agent 无法代为回答的 MCP 询问提示）；import_dictionary 接受 dryRun；import_vocabulary 只读取明确选定的来源，随后要求提供已保存的预览令牌和获批的候选 ID，并传入 apply: true。
• Claude Code 插件：MCP 服务、SessionStart 和 UserPromptSubmit 钩子、一个 lexicon 技能以及一个 /lexicon 命令。可直接从此仓库的市场安装，无需构建。
• 包含 27 个命令的 CLI，从 lexicon add 到 lexicon voice。
• 176 个入门词条，分为四个词包（开发者、AI、商业、语音工具），每个词包只需一条命令即可安装；还可通过注册表索引获取社区词包（lexicon pack search cardiology --registry <index>）：安装时固定校验和，每次安装和更新都会在写入前预览。
• 十六种导出格式（Wispr Flow、Superwhisper、macOS Text Replacement、espanso、Whisper 和 OpenAI 提示词、Deepgram、AssemblyAI、Speechmatics、Azure、Google、CLAUDE.md、markdown、text、CSV、JSON），以及 八种导入器（包括其写入的 CLAUDE.md 表格），可用于导入你已经训练好的词典。 不指定格式运行 lexicon export 会列出所有格式。格式拼写错误时会以状态码 1 退出并提供建议；例如，运行 lexicon export wisprr 会打印 Did you mean wispr? Run: lexicon export wispr（0.5.6 源码）。
• 仓库采集、引导式词汇导入（lexicon import --guided：你的联系人、日历和 GitHub；每个来源都需选择加入，每个候选词在写入前都需获批）、纠错学习（“不是 Ashler，而是 Ashlr.AI”；提示词钩子发现的纠正也会排入全局词库旁的 pending-aliases.yaml 以供审核；只有运行 lexicon pending accept <id> 后，队列中的内容才会影响匹配；lexicon pending reject <id> 会移除某一项；LEXICON_QUEUE_CORRECTIONS=0 可关闭队列）、使用统计、从语音历史中挖掘的建议，以及项目词库的信任门控。
• 纯粹的库。 normalize() 是纯函数：输入文本和词库，输出纠正后的文本及替换列表。

适用范围

平台	方式	文档
Claude Code	插件，或 MCP 服务加两个钩子，在模型读取提示词前进行修正	CLIENTS.md
Codex、Cursor、Windsurf、Gemini CLI、VS Code、Claude Desktop	lexicon install <client> --apply 注册 MCP 服务；lexicon uninstall <client> 仅移除它写入的内容（先运行 --dry-run）	CLIENTS.md
任意 MCP 客户端	stdio 服务，包含二十一个工具	MCP.md
ChatGPT、Claude.ai、Grok、Gemini、Perplexity、Poe、Copilot	浏览器扩展：按下发送时重写输入框内容	EXTENSION.md
任意 macOS 应用、任意听写工具	LexiconBar 菜单栏应用：通过辅助功能重写焦点字段中的听写文本，并提供撤销气泡	MACOS-APP.md
Shortcuts、Raycast、脚本、自有应用	lexicon serve：在 127.0.0.1:41733 上提供受 bearer token 保护的回环 HTTP API	LOCAL-API.md
不使用听写应用的听写	lexicon voice：ffmpeg 录音，whisper.cpp 使用你的规范词条作为提示词提示进行转录，词库负责修正	VOICE.md
任意文本字段、任意操作系统	使用热键运行 lexicon daemon --once --paste	DAEMON.md
Wispr Flow、Superwhisper、macOS Text Replacement、espanso、Deepgram、Azure、Google	导出到它们各自的词典和偏置参数中	EXPORTS.md
自有 STT 流水线	npm i @ashlr/lexicon，在转录和模型之间调用 normalize()	LIBRARY.md
上述任意平台，在 Windows 或 Linux 上	了解各操作系统中哪些平台已在 CI 中测试、哪些可用但从未在真实硬件上运行，以及哪些完全不可用	PLATFORMS.md

工作原理

在词元窗口上分三层匹配：先匹配完全相同的别名，然后进行 double-metaphone 语音匹配，最后在置信度阈值以上进行 Damerau-Levenshtein 模糊匹配。完全匹配优先占用对应文本范围；匹配之间不会重叠。约 3400 个常见英语单词的停用列表、每个词条各自的 never 列表，以及（默认启用 skipCode 时）代码片段、URL、电子邮件、路径和粘连标识符，都会排除在匹配范围之外。这就是基准测试中没有改动任何无误句子的原因。每次替换都会报告其 reason 和 confidence。

如果你没有自己的词库，normalize 会使用内置示例（Ashlr.AI、Kubernetes、PostgreSQL、Pydantic、SaaS），并说明这一点。它不包含 Hetzner，因此在你添加该词条之前，head sner 会保持不变。

lexicon normalize --diff "ask ashler to deploy kuber netties with post gressql"
# stderr:  lexicon: no terms yet, so this is the built-in example (Ashlr.AI, Kubernetes, PostgreSQL, Pydantic, SaaS).
#          lexicon: run `lexicon setup` to build your own; nothing was written.
#          "ashler" -> "Ashlr.AI" (alias, 1.00)
#          "kuber netties" -> "Kubernetes" (phonetic, 0.88)
#          "post gressql" -> "PostgreSQL" (phonetic, 0.88)
# stdout:  ask Ashlr.AI to deploy Kubernetes with PostgreSQL

完整规则（包括所有保护条件）见 docs/MATCHING.md。

使用 doctor --fix 修复

lexicon doctor --fix 会预览 lexicon doctor 报告的问题的修复方案，但不会写入任何内容（退出码为 0）。lexicon doctor --fix --apply 会执行修复，并先备份每个文件。单独使用 lexicon doctor --apply（不带 --fix）会被拒绝，退出码为 1。添加 --json 可输出一个 { mode, plan, outcome } 对象。该功能已包含在源码（main）中，但尚未发布；npm 包（0.5.4）不包含该功能。

$ lexicon doctor --fix
doctor --fix (dry run, nothing written):
  would fix  move aside the trust registry (trust.json), which is not valid JSON (...)
Run `lexicon doctor --fix --apply` to make these changes (each file is backed up first).
$ lexicon doctor --fix --apply
doctor --fix --apply:
  fixed   move aside the trust registry (trust.json), which is not valid JSON (...)
          backup: ~/.config/lexicon/trust.json.bak-<UTC stamp>

修复内容：如果全局词库缺失，则会创建一个空词库（与 lexicon init 的行为相同）；如果 trust.json、hits.json、待处理修正队列或索引缓存无法使用，则会将其复制为 <file>.bak-<UTC stamp>，然后删除原文件。需要手动处理的内容（列为 manual，绝不会更改）：无法解析的词库（其中保存着你的词条；请使用 lexicon edit 修复）、serve.json（其中保存着配对令牌）、作为目录或符号链接的状态路径，以及 Claude 钩子和 MCP 注册（lexicon install claude --apply）。详情见：docs/doctor-fix.md。如需一次性修复所有 Ashlr 工具，请参阅 Ashlr Stack 指南中的修复所有内容。

文档

完整索引位于 docs/，按任务分组：开始使用、与客户端搭配使用、了解其工作原理、参与贡献、内部机制。大多数人需要查看的三个页面：

页面	内容
QUICKSTART.md	五分钟内从零开始，在 Claude Code 中修正内容，并说明每个设置步骤会写入什么
CLIENTS.md	安装到 Claude Code（插件、钩子、无头模式）和其他所有 Agent 客户端
FAQ.md	安装前大家常问的问题

正在编写一个为他人安装此工具的 Agent？docs/AGENTS.md 是写给你的。要修改代码？请从 CONTRIBUTING.md 和 docs/ARCHITECTURE.md 开始。

根目录中还有：SECURITY.md、CODE_OF_CONDUCT.md、CHANGELOG.md。

下载

每个 GitHub 版本都附带适用于 Chrome/Edge/Brave 和 Firefox 的浏览器扩展、适用于 macOS 的 LexiconBar.app.zip、用于离线安装的 npm 压缩包以及 SHA256SUMS。Homebrew formula 位于 ashlrai/homebrew-tap。发布 0.5.6 后，运行 npm i -g github:ashlrai/lexicon#v0.5.6 即可直接从 GitHub 安装该标签，并在安装时进行构建。

路线图和非目标

非目标：这不是听写应用，没有托管账户，也没有同步服务。它就是一个文件。

• 为扩展上架 Chrome 网上应用店和 Firefox AMO。目前需从版本压缩包安装。
• 经过公证的 macOS 应用。LexiconBar 采用临时签名，因此首次启动时需要右键点击并选择“打开”。
• 提供相同按住说话和修复剪贴板操作的 Linux 托盘应用。Windows 版本已构建完成：请参见 docs/WINDOWS-APP.md。
• 非英语语音音系。Double metaphone 针对英语优化；其他语言中的姓名会回退到模糊匹配。
• 真实麦克风基准测试。音频语料是由 macOS 文本转语音读出并输入 whisper.cpp 的文本，而非录制的语音。

Ashlr 生态系统的一部分

Lexicon 是 Ashlr（一家前沿部署工程公司）推出的开源工具之一。每款工具都可独立安装和运行：

• Phantom（phm）：Agent 工作台。源代码：ashlrai/phantom。
• Phantom Secrets（phantom）：使用 phm_ 占位符，避免 Agent 上下文中出现真实 API 密钥。源代码：ashlrai/phantom-secrets。
• Locus（locus）：将每个 Agent 会话固定到一个账户。
• Ashlr MD：一款带有 MCP 服务的 Markdown 应用。
• Ashlr Stack（stack）：配置服务，并将其密钥存储在 Phantom Secrets 中。
• ashlr-plugin（ashlr-plugin）：面向 Claude Code 和 Codex 的令牌效率工具。

Phantom：INTEGRATION.md 从 Lexicon 的角度概述了 Phantom 将要集成的契约（lexicon 文件、信任门控、normalize 入口）。它不会改动 Phantom 核心。

后量子准备情况：docs/PQ-READINESS.md 记录了 Lexicon 当前使用加密技术的情况（用于完整性校验的 SHA-256 和 SHA-512 哈希；已发布的源代码中不包含加密、密钥交换或签名），以及迁移会涉及哪些部分。文档并未声称 Lexicon 可抵御量子攻击。

参与贡献

适合新手的议题都已标记并明确范围：新增入门包、导出器、导入器或采集器来源。CONTRIBUTING.md 包含环境设置、测试布局以及各项任务的操作步骤。

发现它识别错的姓名？提交误听词条议题。

License

MIT. Copyright 2026 AshlrAI, Inc.