# dict — документация
Управление словарём: создание, изменение и удаление записей.
Почему скрипт устроен именно так — в [[dict — дизайн]].
```
bun dict.ts <команда> [аргументы] [флаги]
```
Скрипт ведёт три файла:
| Файл | Что в нём |
|---|---|
| `~/.config/superwhisper-extender/dictionary.json` | словарь |
| `~/.config/superwhisper-extender/exceptions.txt` | исключения |
| `~/.config/superwhisper-extender/resolved.json` | разобранные пометки |
Папка с этими файлами — **отдельный git-репозиторий**. Правки словаря стоит
коммитить: в нём накапливаются решения, часть которых добыта измерениями,
и второй копии у них нет.
```bash
cd ~/.config/superwhisper-extender
git add -A && git commit -m "что изменилось"
```
Запуск без команды выводит справку.
## Оглавление
- [[#Формат словаря]]
- [[#canonical]]
- [[#variants]]
- [[#safeToReplace]]
- [[#notMatch]]
- [[#noise]]
- [[#Полный пример файла]]
- [[#Команды]]
- [[#Флаги]]
- [[#list]]
- [[#show]]
- [[#add]]
- [[#variant]]
- [[#unvariant]]
- [[#notmatch]]
- [[#rename]]
- [[#remove]]
- [[#noise и unnoise]]
- [[#Разобранные пометки]]
- [[#Исключения]]
- [[#exceptions]]
- [[#except]]
- [[#unexcept]]
- [[#Переменные окружения]]
## Формат словаря
Одна запись — **один смысл**, а не одно написание. Все способы назвать одну
и ту же вещь собраны в одной записи и приводятся к общей форме.
### canonical
Как запись должна выглядеть в готовом тексте. Единственная форма, к которой
приводится всё остальное.
Именно это поле задаёт, какой алфавит побеждает. Написан канон латиницей —
значит слово всегда будет латиницей, даже если произнесён по-русски.
Написан кириллицей — наоборот.
### variants
Всё, что должно превращаться в канон. Сюда попадают три разных по природе
вещи, но ведут себя они одинаково:
| Что | Пример |
|---|---|
| другое законное название | полное имя вместо аббревиатуры |
| как ты это произносишь | произношение, записанное кириллицей |
| как это коверкает транскрибатор | ошибочные написания |
Разделять их отдельными полями смысла нет: во всех случаях это строка,
которую надо заменить на канон.
### safeToReplace
Единственный флаг в словаре, и он решает главное — **каким механизмом**
чинить эту форму.
```
true -> подстановка строки, срабатывает всегда, гарантия
false -> только языковая модель, решение по смыслу
```
Ставить `false` нужно в одном случае: **форма совпадает с настоящим словом
языка**, которое употребляется и в обычной речи. Замена сработает и там,
испортив нормальное предложение.
Пример: искажение «код-код». Слово «код» произносится постоянно в прямом
смысле, поэтому заменять его вслепую нельзя — тут решает языковая модель,
по смыслу фразы.
> [!info] Склонение — не причина для `false`
> Замена сопоставляет **слова целиком**, а не части слов. Склонённую форму
> она просто не увидит: правило «обсидиан» не сработает на «обсидиане».
>
> То есть замена не портит склонение, а не берётся за него: именительный
> падеж чинит, остальные оставляет языковой модели. Это штатное поведение,
> а не потеря.
>
> Проверено измерением — см. [[apply — дизайн#Требование к механизму замен]].
### notMatch
Слова, которые звучат похоже на запись, но ею не являются.
Главное назначение — **предупредить языковую модель**. Канон лежит в промпте,
и модель, встретив созвучное слово, может переписать его в канон. Из этого поля
собирается отдельный раздел промпта:
```
НЕ ПУТАТЬ:
Unity: не путать с юниты
Claude Code: не путать с Code
```
Побочно это ещё и память между запусками: помеченное слово перестаёт
всплывать при разборе истории. Разобрался один раз, записал, больше не мешает.
Сюда идёт только то, что созвучно **конкретному канону**. Обычное слово,
которому не с чем путаться, в промпте не нужно.
> [!warning] Заносить по факту, а не по созвучию
> Основание — **состоявшаяся подмена**: в истории видно, что слово превратилось
> в канон, которым оно не является. Одного сходства мало.
>
> Заполненный впрок `notMatch` удлиняет промпт, который модель читает при
> каждой диктовке, и вдобавок глушит слово в диагностике — настоящая находка
> по нему уже не всплывёт.
### noise
Фразы, которые распознавание **выдумывает** — обычно на тишине и в паузах.
Модели семейства Whisper обучались в том числе на субтитрах и в тишине
выдают титры переводчиков.
Это не искажение чего-либо: заменять их не на что, они просто удаляются.
Поэтому лежат отдельным списком, а не записями с пустым каноном.
## Полный пример файла
```json
{
"version": 2,
"entries": [
{
"canonical": "Claude Code",
"variants": [
{ "form": "клод код", "safeToReplace": false },
{ "form": "клауди код", "safeToReplace": true },
{ "form": "клаудиокод", "safeToReplace": true },
{ "form": "CloudyCode", "safeToReplace": true },
{ "form": "Cloud Decode", "safeToReplace": true },
{ "form": "Cloud Code", "safeToReplace": true },
{ "form": "код-код", "safeToReplace": false }
],
"notMatch": ["Code"]
},
{
"canonical": "MCP",
"variants": [
{ "form": "Model Context Protocol", "safeToReplace": true },
{ "form": "эмсипи", "safeToReplace": true },
{ "form": "Mcp", "safeToReplace": true }
],
"notMatch": []
},
{
"canonical": "Docker",
"variants": [
{ "form": "докер", "safeToReplace": false }
],
"notMatch": []
}
],
"noise": [
"Субтитры создавал DimaTorzok"
]
}
```
Обрати внимание на две записи с `false`.
У `Claude Code` форма `код-код` не заменяется: «код» — обычное русское слово,
подстановка сломала бы нормальные фразы.
У `Docker` форма `докер` заменяется: это не слово из обычной речи,
а искажение названия. На склонённых формах вроде «докере» правило просто
не сработает, и их подхватит языковая модель.
## Команды
| Команда | Аргументы | Что делает |
|---|---|---|
| `list` | — | показывает все записи |
| `show` | `<канон>` | показывает одну запись целиком |
| `add` | `<канон>` | создаёт запись |
| `variant` | `<канон> <форма>` | добавляет форму к записи |
| `unvariant` | `<канон> <форма>` | убирает форму |
| `notmatch` | `<канон> <слово>` | помечает созвучие ложным |
| `rename` | `<канон> <новый канон>` | переименовывает канон |
| `remove` | `<канон>` | удаляет запись со всеми формами |
| `noise` | `<фраза>` | добавляет фразу в список удаляемых |
| `unnoise` | `<фраза>` | убирает фразу из списка удаляемых |
| `exceptions` | — | показывает исключения |
| `except` | `<слово>...` | заносит слова в исключения |
| `unexcept` | `<слово>...` | убирает слова из исключений |
| `resolved` | — | показывает разобранные пометки |
| `resolve` | `<пометка> <решение>` | закрывает пометку с комментарием |
| `unresolve` | `<пометка>` | возвращает пометку в вывод |
## Флаги
| Флаг | Для команд | Смысл |
|---|---|---|
| `--unsafe` | `variant` | форму чинит языковая модель, а не подстановка строки |
| `--context` | `resolve` | кусок фразы вокруг пометки, для памяти |
## list
Сводка по всем записям.
```bash
bun dict.ts list
```
```
записей: 2
канон форм замен
Claude Code 2 1
Docker 1 0
```
Столбец «замен» меньше столбца «форм», когда часть форм добавлена с флагом
`--unsafe`: такие подстановкой не заменяются.
## show
Показывает запись целиком, как она лежит в файле.
```bash
bun dict.ts show "Claude Code"
```
```json
{
"canonical": "Claude Code",
"variants": [
{ "form": "CloudyCode", "safeToReplace": true },
{ "form": "код-код", "safeToReplace": false }
],
"notMatch": ["Code"]
}
```
## add
Создаёт запись. Аргумент — канон, то есть форма, которая должна оказаться
в готовом тексте.
```bash
bun dict.ts add "Claude Code"
bun dict.ts add "кварк"
```
**Канон задаёт алфавит.** Написан латиницей — слово всегда будет латиницей,
даже когда произнесено по-русски. Написан кириллицей — наоборот.
Повторное добавление того же канона останавливается с ошибкой.
## variant
Добавляет форму, которая должна превращаться в канон.
```bash
bun dict.ts variant "Claude Code" "CloudyCode"
bun dict.ts variant "Claude Code" "код-код" --unsafe
```
В формы идёт всё, что должно приводиться к канону: другие названия,
произношение, ошибки транскрибатора.
Одна форма не может принадлежать двум записям — попытка останавливается
с указанием, за кем форма уже закреплена.
Флаг `--unsafe` выставляет полю `safeToReplace` значение `false` — когда это
нужно, разобрано выше, в [[#safeToReplace]].
## unvariant
Убирает форму из записи.
```bash
bun dict.ts unvariant "Docker" "докер"
```
Если такой формы нет — останавливается с ошибкой, а не молча ничего не делает.
## notmatch
Помечает слово как созвучное, но записью не являющееся.
```bash
bun dict.ts notmatch "Claude Code" "Code"
```
Нужно, потому что сопоставление по звучанию иногда роднит разные слова.
Без пометки одна и та же ложная находка всплывает при каждом разборе истории.
## rename
Меняет канон, сохраняя формы и настройки записи.
```bash
bun dict.ts rename "Claude code" "Claude Code"
```
Если запись с новым именем уже есть — останавливается, чтобы не слить две
записи в одну незаметно.
## remove
Удаляет запись целиком.
```bash
bun dict.ts remove "Docker"
```
В ответе указывается, сколько форм удалено вместе с записью — чтобы случайное
удаление большой записи было заметно.
## noise и unnoise
Управление списком выдуманных фраз.
```bash
bun dict.ts noise "Субтитры создавал DimaTorzok"
bun dict.ts unnoise "Субтитры создавал DimaTorzok"
```
Такие фразы заменяются на пустоту. Механизм тот же, что у обычных замен,
поэтому они попадают в тот же список настроек приложения.
## Исключения
Обычные слова, которых нет в корпусе языка: новояз, свежие заимствования,
английские слова, которые транскрибатор и так пишет верно.
Такое слово чинить не надо — оно и так правильное. Но диагностика показывает
его как находку, потому что корпус его не знает. Занесённое в исключения слово
больше не всплывает.
**В настройки транскрибатора исключения не уезжают.** Ни в список слов,
ни в замены, ни в промпт. Они влияют только на то, что показывает `diagnose`.
> [!info] Чем исключение отличается от записи словаря
> Вопрос ровно один: **правильно ли транскрибатор пишет это слово?**
>
> Пишет неверно — запись в словарь, с вариантами.
> Пишет верно, а диагностика ругается — исключение.
**Падежи заносить не надо.** Достаточно одной формы: диагностика гасит
и остальные, если они отличаются только хвостом. `оркестратор` закрывает
`оркестратора` и `оркестратору`, но не `постобработчик` при заведённой
`постобработке` — это разные слова. Подробнее — в
[[diagnose — дизайн#Заведённое гасится вместе с падежами]].
Живут они простым списком строк, по слову в строке, — файл правится и руками:
```
edit
read
задеплоить
коммитить
хлеб
```
### exceptions
```bash
bun dict.ts exceptions
```
Показывает весь список с числом слов.
### except
```bash
bun dict.ts except read edit хлеб
```
Слов можно указать сколько угодно за раз — разбор находок обычно даёт их
пачкой. Уже занесённые пропускаются; если все указанные слова уже в списке,
команда останавливается с сообщением.
Список хранится отсортированным и без повторов — его читают глазами и держат
под контролем версий.
### unexcept
```bash
bun dict.ts unexcept хлеб
```
Убирает слова обратно. В ответе — сколько убрано. Если ни одного из указанных
слов в списке нет, команда останавливается с ошибкой, а не молчит.
## Разобранные пометки
Языковая модель помечает знаками `‡ ‡` места, где слово сидит в фразе криво.
Диагностика их показывает, а этот список хранит принятые по ним решения.
Нужен он потому, что пометка стоит в тексте истории **навсегда**. Разобрал
один раз — при следующем запуске увидишь снова, и так до бесконечности.
У обычной находки такой беды нет: она уходит в словарь или в исключения,
и оба списка её глушат. Пометке же деваться некуда — она может оказаться
оговоркой или остаться непонятой, но закрыть её всё равно надо.
```bash
bun dict.ts resolve "даю чем я" "оговорка, речь свернулась — не термин"
bun dict.ts resolve "виде" "не понял, вернуться если повторится" \
--context "Существующий ‡виде‡ проекта телом"
```
Комментарий обязателен. Через месяц пометка `виде` сама по себе не скажет
ничего — нужен ответ на вопрос, что с ней сделали и почему. Без этого список
превратится в свалку молча заглушённого.
Контекст необязателен, но полезен: он есть в момент разбора и стоит дёшево,
а восстанавливать его потом — идти в базу истории руками.
```bash
bun dict.ts resolved # показать всё
bun dict.ts unresolve "виде" # вернуть в вывод
```
Пометки на словах, которые с тех пор попали в словарь, гасятся сами —
заносить их сюда не нужно.
## Переменные окружения
| Переменная | Назначение |
|---|---|
| `SW_DICT_DIR` | папка со словарём и исключениями вместо стандартной |
Нужна, чтобы прогонять команды на копии, не трогая рабочие файлы:
```bash
SW_DICT_DIR=/tmp/проба bun dict.ts add "Проверка"
```