# 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 "Проверка" ```