# dict — дизайн
Почему скрипт и словарь устроены именно так. Как этим пользоваться —
в [[dict — документация]].
## Оглавление
- [[#Назначение и границы]]
- [[#Куда попадает содержимое словаря]]
- [[#Решения по устройству записи]]
- [[#Одна запись — один смысл]]
- [[#Канон задаёт алфавит]]
- [[#Все формы в одном поле]]
- [[#safeToReplace — единственный флаг]]
- [[#notMatch — предупреждение модели и память между запусками]]
- [[#Исключения]]
- [[#Почему отдельный файл, а не поле словаря]]
- [[#Почему простой список, а не JSON]]
- [[#Почему не дописывать корпус]]
- [[#Разобранное — четвёртый список]]
- [[#Где лежат файлы и почему там]]
- [[#Решения по поведению скрипта]]
- [[#Что рассматривалось и отброшено]]
## Назначение и границы
Скрипт **только ведёт словарь**. Он не трогает настройки транскрибатора,
ничего не измеряет и ничего не применяет.
Разделение намеренное: словарь хранит решения, а перенос этих решений
в настройки — отдельная задача с другими рисками. Скрипт, который правит
локальный JSON, безопасен; скрипт, который закрывает приложение и переписывает
его конфигурацию, — нет. Смешивать их в одном месте не стоит.
Отсюда же независимость от superwhisper: в формате нет ни одного поля,
завязанного на конкретное приложение. При смене транскрибатора словарь
остаётся, меняется только то, что его читает.
## Куда попадает содержимое словаря
```
canonical -> список канонов в промпте
-> словарь распознавания
variants, safeToReplace true -> замены, срабатывают гарантированно
variants, safeToReplace false -> промпт и примеры, решает модель
notMatch -> раздел «не путать» в промпте
-> игнорируется при анализе истории
```
Словарь ничего не делает сам: он только хранит решения. Переносом в настройки
приложения занимаются отдельные скрипты.
## Решения по устройству записи
### Одна запись — один смысл
Запись описывает **вещь**, а не написание. Все способы назвать одну и ту же
вещь — полное название, аббревиатура, произношение, ошибочные написания —
живут в одной записи.
Альтернатива была: отдельная запись на каждую форму. Отброшена, потому что
тогда связь между формами нигде не выражена, и при переименовании пришлось бы
искать все разрозненные записи руками.
### Канон задаёт алфавит
Отдельного поля «на каком языке писать» нет. Его роль выполняет сам канон:
написан латиницей — значит вывод латиницей, написан кириллицей — кириллицей.
Изначально в схеме были два поля — `latin` и `cyrillic` — плюс флаг
приоритета. От них отказались, когда стало ясно, что приоритет и есть выбор
канона: держать одно и то же решение в двух местах незачем.
### Все формы в одном поле
Раньше формы делились на три группы: другие названия, произношение, искажения
транскрибатора. Сейчас все они лежат в `variants`.
Причина: **поведение у них одинаковое**. Во всех трёх случаях это строка,
которую надо привести к канону. Смысловая разница между «законным синонимом»
и «ошибкой распознавания» ни на что не влияет, а три поля вместо одного —
это втрое больше работы при ведении словаря.
### safeToReplace — единственный флаг
Он решает **каким механизмом** чинить форму, и это единственное реальное
различие между формами.
```
true -> подстановка строки: срабатывает всегда, гарантия
false -> языковая модель: решение по смыслу, гарантии нет
```
Флаг нужен ровно для одного случая: **форма совпадает с настоящим словом
языка**, которое употребляется и в обычной речи. Подстановка сработает и там,
испортив нормальное предложение.
Склонение причиной не является — почему, разобрано в
[[apply — дизайн#Требование к механизму замен]]. Изначально мы считали иначе
и помечали склоняемые формы небезопасными; измерение это опровергло.
Значение по умолчанию — `true`, то есть подстановка. Выбрано так намеренно:
детерминированный механизм надёжнее, и отступать от него следует осознанно,
явным флагом.
### notMatch — предупреждение модели и память между запусками
У поля две работы, и главная из них — первая.
**Предупреждение языковой модели.** Канон лежит в промпте, и модель, встретив
созвучное слово, вполне может переписать его в канон. `notMatch` собирается
в отдельный раздел промпта «не путать»: `Unity: не путать с юниты`. Это защита
от обратной ошибки — когда исправляется то, что исправлять не следовало.
**Память между запусками.** Сопоставление по звучанию иногда роднит совершенно
разные слова — особенно короткие. Разобравшись с ложной находкой один раз,
результат надо где-то сохранить, иначе она всплывёт при следующем разборе
истории.
Из первой роли следует граница поля: сюда идёт только то, что **созвучно
конкретному канону**. Обычное слово, которому не с чем путаться, в промпте
не нужно — ему место в исключениях.
И вторая граница, из той же роли: заносить надо **по факту подмены**, а
не по сходству. Обе работы поля обходятся дорого, если заполнять его впрок:
раздел «не путать» читается моделью при каждой диктовке, а заглушённое слово
перестаёт появляться в диагностике — и настоящая находка по нему уже
не всплывёт.
Поле хранится в самой записи, а не общим списком: ложное созвучие всегда
относится к конкретной записи, и в общем списке было бы непонятно, к чему оно.
## Исключения
Второй файл, который ведёт этот скрипт: обычные слова, которых нет в корпусе
языка.
Нужен он потому, что корпус описывает язык не целиком. Новояз, свежие
заимствования и англоязычные слова, которые распознаются верно, в нём
отсутствуют — и всплывают в диагностике при каждом запуске. Разбирать их
заново каждый раз бессмысленно: решение уже принято, его надо записать.
### Почему отдельный файл, а не поле словаря
Похожее поле в словаре уже есть — `notMatch`, — но оно решает другую задачу.
```
notMatch слово созвучно КОНКРЕТНОМУ канону
-> едет в промпт разделом «не путать»
исключения слову не с чем путаться, оно просто обычное
-> никуда не едет, гасит находку в диагностике
```
Сложить обычные слова в `notMatch` значит приписать каждое к какому-то канону,
которого у него нет, и вдобавок засорить промпт предупреждениями о том, что
никогда не спутается. Промпт читает языковая модель при каждой диктовке —
лишние строки там не бесплатны.
Отдельный файл ещё и подчёркивает границу: словарь уезжает в настройки
транскрибатора, исключения не уезжают никуда.
### Почему простой список, а не JSON
У исключения ровно одно свойство — само слово. Ни флагов, ни вариантов,
ни связей.
JSON на таких данных добавляет кавычки, запятые и обёртку, ничего не давая
взамен: файл правится руками, читается глазами и живёт под контролем версий,
а построчный список даёт там самые чистые различия.
### Почему не дописывать корпус
Соблазн есть: раз слова в корпусе не хватает — дописать его, и дело с концом.
Так делать нельзя. Корпус скачан целиком и заменяется целиком: обновится
источник — правки пропадут. Свои решения обязаны лежать отдельно от чужих
данных, иначе они не переживут первого же обновления.
## Разобранное — четвёртый список
Хранит решения по пометкам модели: текст пометки, кусок фразы, комментарий
и дату.
Причина та же, что у исключений, но источник другой. Исключение гасит слово,
которого нет в корпусе. Разобранное гасит **пометку**, которая стоит в тексте
истории и оттуда никуда не денется.
**Почему не в исключения.** Пометка не обязана быть словом: `даю чем я` —
цепочка из трёх. И смысл другой: исключение утверждает «это обычное слово»,
а разобранное — «мы это видели и решили вот так». Слить их значило бы потерять
различие между «слово нормальное» и «место разобрано».
**Почему JSON, а не построчный список.** У записи четыре поля против одного
у исключения. Простой список тут не выражает нужного.
**Почему комментарий обязателен, а контекст нет.** Комментарий — единственное,
что делает список полезным через месяц: без него это свалка молча заглушённого.
Контекст восстановим из базы, хоть и с трудом, поэтому он не обязателен —
но сохраняется, потому что в момент разбора уже есть под рукой.
## Где лежат файлы и почему там
Словарь, исключения и разобранное живут в `~/.config/superwhisper-extender/`,
а не в хранилище заметок рядом со скриптами.
**Причина — состав данных.** В словаре имена проектов, рабочий жаргон
и оговорки; в разобранном — куски живой речи. Хранилище заметок публичное,
и всему этому там не место. Скрипты — общее знание, словарь — личное.
**Папка под своим git.** Решений в словаре накопилось много, часть добыта
измерениями, и второй копии у них нет: снесённая папка означает потерю
всего. Репозиторий на месте дешевле любых бэкапов и не тащит личные данные
в чужую историю.
Собранный плеер в историю не идёт: артефакт на 200 КБ, который пересобирается
сам.
**Коммиты руками.** Автоматического коммита при каждой правке нет: словарь
меняется пачками во время разбора, и осмысленное сообщение к пачке пишет
человек, а не скрипт.
## Решения по поведению скрипта
**Формы уникальны во всём словаре.** Одна и та же форма не может принадлежать
двум записям — попытка привязать её ко второй останавливается с указанием,
за кем форма уже закреплена. Иначе результат зависел бы от порядка обработки.
**Регистр не учитывается при поиске, но сохраняется при записи.** Искать
термин, помня его точное написание, неудобно; хранить его в изменённом
виде — неправильно.
**Записи сортируются по канону при каждой записи файла.** Словарь читают
глазами и держат под контролем версий: постоянный порядок делает изменения
в нём обозримыми.
**Версия формата проверяется при чтении.** Если файл окажется новее, чем
понимает скрипт, тот остановится, а не испортит данные молча.
**Ошибки останавливают работу.** Удаление несуществующей формы, повторное
добавление канона, форма, занятая другой записью — всё это завершается
сообщением, а не тихим бездействием. Молчаливое «ничего не произошло» —
худший исход для команды, которая должна что-то изменить.
**Путь к словарю подменяется переменной окружения.** Нужно, чтобы прогонять
команды на копии, не трогая рабочий файл. Исключения лежат в той же папке
и подменяются вместе со словарём.
**Исключения заносятся пачкой.** Команда принимает сколько угодно слов за раз:
разбор находок диагностики даёт их именно пачкой, и добавлять по одному было бы
неудобно. Уже занесённые молча пропускаются — но если новых не оказалось
ни одного, команда останавливается с сообщением.
**Ключ массива называется `entries`, а не `terms`.** В словаре лежат не только
термины: туда же попадают названия продуктов, аббревиатуры и фразы. Переименовано
в версии формата 2; файлы версии 1 читаются по-прежнему — чтение поднимает
записи из старого ключа, запись всегда идёт в новый.
## Что рассматривалось и отброшено
**Флаг «добавлять ли в словарь распознавания».** Отброшен по решению
владельца словаря: туда идут все записи без исключения.
**Поле с измеренной точностью распознавания.** Хранило долю случаев, когда
транскрибатор записал слово верно. Отброшено после того, как перестало
на что-либо влиять: цифру всегда можно пересчитать отдельно, а в словаре она
устаревала бы.
**Отдельное поле произношения.** Идея была дать модели опору для узнавания
форм, которых нет в списке. Отброшено: практическая разница не измерена,
а лишнее поле — это реальные затраты на ведение словаря.
**Флаг «схлопывать ли синонимы».** Отброшен: синонимы схлопываются всегда,
выбор оказался не нужен.
**Поле темы.** Задумывалось на вырост: когда записей станет много, промпт
разрастётся, и можно будет собирать отдельные режимы под разные задачи —
в каждом только свои записи. Отброшено: поле ни на что не влияло, а заполнять
его требовалось при каждом добавлении. Если такая разбивка понадобится,
проще вернуть поле тогда, чем годами вести его вхолостую.