# 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 читаются по-прежнему — чтение поднимает записи из старого ключа, запись всегда идёт в новый. ## Что рассматривалось и отброшено **Флаг «добавлять ли в словарь распознавания».** Отброшен по решению владельца словаря: туда идут все записи без исключения. **Поле с измеренной точностью распознавания.** Хранило долю случаев, когда транскрибатор записал слово верно. Отброшено после того, как перестало на что-либо влиять: цифру всегда можно пересчитать отдельно, а в словаре она устаревала бы. **Отдельное поле произношения.** Идея была дать модели опору для узнавания форм, которых нет в списке. Отброшено: практическая разница не измерена, а лишнее поле — это реальные затраты на ведение словаря. **Флаг «схлопывать ли синонимы».** Отброшен: синонимы схлопываются всегда, выбор оказался не нужен. **Поле темы.** Задумывалось на вырост: когда записей станет много, промпт разрастётся, и можно будет собирать отдельные режимы под разные задачи — в каждом только свои записи. Отброшено: поле ни на что не влияло, а заполнять его требовалось при каждом добавлении. Если такая разбивка понадобится, проще вернуть поле тогда, чем годами вести его вхолостую.