# diagnose — дизайн Почему диагностика устроена именно так. Как пользоваться — в [[diagnose — документация]]. ## Оглавление - [[#Назначение и границы]] - [[#Почему нужен корпус языка]] - [[#Что пробовали до него]] - [[#Почему не собрать корпус из своей речи]] - [[#Исключения — заплатка к корпусу]] - [[#Пометки модели]] - [[#Разобранное — память по пометкам]] - [[#Заведённое гасится вместе с падежами]] - [[#Какой текст анализируется]] - [[#Как определяется находка]] - [[#Решения по разбору слов]] - [[#Составные слова через дефис]] - [[#Склейка падежных форм]] - [[#Кириллица и латиница порознь]] - [[#Чего диагностика не найдёт]] - [[#Решения по поведению]] ## Назначение и границы Скрипт **только находит**. Он не правит словарь и не трогает настройки приложения — решение по каждой находке принимает человек. Так же, как `dict` только ведёт словарь, а `apply` только переносит: у каждого шага свой риск, и смешивать их в одной команде не стоит. ## Почему нужен корпус языка Задача звучит просто: отделить обычную речь от терминов. Но у «клавиши» и «hotfix» **одинаковая статистика** — по 15 употреблений в схожем числе записей. Никакая формула их не различит, потому что различие не в цифрах. «Клавиши» — обычное слово, «hotfix» — нет. Это знание **о языке**, и взять его из истории распознавания неоткуда. Поэтому нужен внешний корпус словоформ. Всё остальное — арифметика поверх него. ### Что пробовали до него Три подхода проверены на реальном корпусе и отброшены. **Мера «часто и редко одновременно».** Классическая формула: частота умножается на редкость. Наверху оказались `что`, `есть`, `это` — частота перевешивает. Обычные слова встречаются стократно чаще терминов, и бонус за редкость этого не компенсирует. **Чистая редкость.** Наверх всплыло то, что встретилось один раз: оговорки и мусор распознавания. Их почти половина от всех уникальных слов. **Сортировка по возрастанию частоты.** Идея была в том, что термины произносятся реже обычной речи. На практике вперемешку пошли `процитируешь`, `оберни`, `клавиши` — редкие, но совершенно обычные слова. А главный проблемный термин оказался бы в самом низу: `Claude Code` произносится сотни раз. Вывод из всех трёх: редкость в собственной речи и специфичность — разные вещи. ### Почему не собрать корпус из своей речи Такой корпус описывает не язык, а привычки говорящего на момент сбора. Прочитал книгу, сменил тему работы — и он устарел, а слова из новой области посыплются в находки как «необычные». Внешний корпус этим не страдает: язык меняется медленнее. ## Исключения — заплатка к корпусу Корпус описывает язык не целиком. Новояз, свежие заимствования и англоязычные слова, которые распознаются верно, в нём отсутствуют — и всплывают как находки при каждом запуске, хотя чинить в них нечего. Поэтому у диагностики есть второй источник: список исключений, который ведёт `dict`. Слово оттуда находкой не становится. **Почему не дописать корпус.** Он скачан целиком и заменяется целиком: при обновлении источника правки пропадут. Свои решения обязаны лежать отдельно от чужих данных. **Почему не в `notMatch` словаря.** Оно едет в промпт разделом «не путать» и потому предназначено для слов, созвучных конкретному канону. У обычного слова канона нет, и предупреждать модель не о чем — а промпт она читает при каждой диктовке. **Почему число исключений выводится в шапке.** Подавление не должно быть молчаливым: список из трёх находок читается по-разному, когда за ним стоит ноль заглушённых слов и когда двести. Наполняется список вручную, по одному решению человека на слово, — как и всё остальное в этом решении. Скрипт сам туда ничего не пишет. ## Заведённое гасится вместе с падежами Слово считается заведённым не только при точном совпадении, но и когда оно — **словоформа** чего-то из словаря или исключений. Без этого каждый падеж приходилось заносить отдельно: `оркестратор` не гасил `оркестратора`, `транскрибацию` не гасило `транскрибации`. Список исключений рос бесконечно, а каждый разбор начинался с одних и тех же слов в другом падеже. Признак словоформы взят тот же, что при склейке находок в таблице, — см. [[#Склейка падежных форм]]: общее начало не меньше 80 % длины, расхождение не больше трёх букв. ``` оркестратор / оркестратора 92 % -> гасится транскрибацию / транскрибации 85 % -> гасится постобработчик / постобработки 79 % -> НЕ гасится, разные слова промпт / промт 67 % -> НЕ гасится, это искажение ``` Последние две строки показывают, что порог работает в обе стороны. Обработчик и обработка — действительно разные вещи, и то, что они не слились, правильно. **Чем платим.** Настоящее искажение, похожее на падежную форму, спрячется: при заведённом `фреймворк` искажение `фреймворг` даёт 89 % и будет сочтено формой. Цена принята сознательно. Порог 80 % выбирался ради `промпт`/`промт` и такие подмены разводит, а то, что проскочит, — одноразовые сбои распознавания, которые при разборе всё равно закрываются как «игнорируем». **Проверяются только однословные записи длиной от четырёх букв.** У коротких слов общее начало набирается случайно, а на фразах вроде `super whisper` понятие словоформы бессмысленно. ## Какой текст анализируется Берётся **итоговый текст** — тот, что увидел пользователь: результат работы языковой модели, а если её в режиме нет, то результат после замен. Это принципиально. Смотреть можно было бы и на сырой вывод распознавания, но тогда в находки попадало бы всё, что уже успешно чинится заменами и промптом, и список состоял бы из решённых задач. Значит находка по определению — то, что **до пользователя доехало неисправленным**. ## Как определяется находка ``` слово есть в словаре -> пропустить, уже заведено слово — форма заведённого -> пропустить, падеж уже разобран слово есть в исключениях -> пропустить, признано обычным вручную слово есть в корпусе -> пропустить, обычная речь иначе -> находка ``` Находки сортируются по частоте: чем чаще слово произносится, тем важнее его завести. Разовые оговорки сами опускаются вниз и отсекаются порогом. Проверка по нашему словарю включает и `notMatch` — то, что однажды признано ложной находкой, больше не всплывает. ## Решения по разбору слов ### Составные слова через дефис Слово считается обычным, если **все** его части есть в корпусе. Без этого правила `какие-то`, `какую-то`, `по-умному`, `что-нибудь` попадали в находки: как единые формы их в списке нет, хотя обе половины — обычные русские слова. На коротком периоде это была самая крупная группа шума. При этом `Kanban-доской` и `shell-команды` остаются находками: одна из частей языку неизвестна. Части короче трёх букв не проверяются — иначе `то`, `либо`, `нибудь` ломали бы разбор. ### Склейка падежных форм Формы одного слова показываются одной строкой с суммарным счётчиком. Признак словоизменения: общее начало занимает **не меньше 80 %** длины слова, а расхождение — не больше трёх букв. ``` оркестратор / оркестратора общее начало 92% -> одна строка Kanban-доской / Kanban-доски общее начало 85% -> одна строка промпт / промт общее начало 67% -> РАЗНЫЕ строки ``` Последний случай объясняет высокий порог. `промт` — не падежная форма, а искажение. Слить его с `промпт` значит спрятать находку, ради которой скрипт и запускается. По той же причине не сводятся разные написания одного названия: `Джарвиса` и `Jarvis`, `Superwhisper` и `Supervisper`. Они расходятся не хвостом, и видеть их нужно порознь. ### Кириллица и латиница порознь Двумя таблицами, потому что латиницы в русском языке нет вовсе — любое английское слово окажется «необычным» и забьёт общий список, вытеснив кириллические находки. Слово с буквами обоих алфавитов считается кириллическим и попадает в первую таблицу: `Kanban-доской`, `shell-команды`, `JSON-файлов`. Так и правильно — это русские конструкции с иноязычным корнем, и разбираться с ними надо вместе с остальной кириллицей. ## Пометки модели Единственный источник, который не опирается на корпус. Языковая модель по правилу в промпте оборачивает в знаки `‡ ‡` места, где слово сидит в фразе криво — не вяжется с соседями, выпадает из смысла. Скрипт достаёт помеченное и показывает первой таблицей, с куском фразы вокруг. Нужно это потому, что сравнение с корпусом слепо к целому классу ошибок: искажение, совпавшее с настоящим словом языка. `ищу` вместо `Issue`, `паф` вместо `path` — оба есть в корпусе, и никакая арифметика поверх него их не покажет. Подробнее про правило — в [[apply — дизайн#Пометка неопознанного]]. **Порог частоты на эту таблицу не действует.** Обычная находка при частоте 1 — скорее всего мусор. Помеченная — наоборот: модель споткнулась осознанно, и такой сигнал ценен даже в единственном экземпляре. Отсекать его по частоте значило бы выбрасывать самое полезное. **Непонятную пометку слушают, а не отгадывают.** Для этого есть отдельный скрипт — [[listen — документация]]: он даёт ссылку на нужный кусок записи по таймингам из неё. Контекст в выводе помогает не всегда, а домысел в словаре стоит дорого. **Контекст показывается сразу,** в отличие от обычных находок. Метка указывает точное место, и по фразе обычно видно, что имелось в виду: «надо ‡ищу‡ создать продукт» читается как `Issue` без гадания. У обычной находки такого места нет — слово могло встретиться в сотне разных фраз. **Пометка обрывается переводом строки.** Потерянный моделью закрывающий знак испортит одно место, а не проглотит половину текста. ## Разобранное — память по пометкам Пометка стоит в тексте истории и оттуда не исчезнет. Значит разобранная однажды, при следующем запуске она появится снова — и так вечно. Обычные находки этой болезнью не страдают: слово уходит в словарь или в исключения, и оба списка его глушат. У пометки такого дома нет. Она может оказаться оговоркой (`даю чем я`), обрывком (`виде`) или так и остаться непонятой — а закрыть её всё равно надо. Отсюда четвёртый список: текст пометки, кусок фразы, решение и дата. **Комментарий обязателен.** Через месяц пометка `виде` сама по себе не скажет ничего; нужен ответ на вопрос «что мы с этим сделали и почему». Список без комментариев быстро превратился бы в свалку молча заглушённого. **Контекст сохраняется вместе с решением.** Он есть в момент разбора и стоит дёшево, а восстановить его потом — значит идти в базу истории руками. **Пометки на словах из словаря гасятся сами,** без записи в разобранное. Такая пометка почти всегда стоит в записи, сделанной ДО того, как слово попало в словарь: модель тогда канона не имела и споткнулась законно. Держать это в списке разобранного значило бы дублировать словарь. **Сорванные записи пропускаются целиком.** Распознавание иногда уходит в бессмыслицу — обычно на тишине, — и модель добросовестно помечает почти каждое слово. Одна такая запись дала **39 пометок из 45 слов**: четверть всего списка за четыре дня. Разбирать там нечего, а по правилу каждую пометку надо закрыть вручную — то есть сорок бессмысленных вопросов человеку. Признак: помечено больше четверти слов при четырёх пометках и более. Порог с запасом: у настоящих записей доля пометок — единицы процентов, ближайшая к границе давала 14 %. Число пропущенных записей выводится в шапке: подавление не должно быть молчаливым. **Фраза гасится, если заведено каждое слово в ней.** Пометка не обязана быть словом: `кварка имплемент`, `integrate кварк integrate`. Как строка такой фразы в словаре нет, и она висела в выводе даже после того, как все её слова были заведены по отдельности. Проверка идёт по словам, короче трёх букв — пропускаются: предлоги и союзы иначе рушили бы её, а смысла в них нет. Разбирать в такой фразе действительно нечего: каждое слово уже разобрано. ## Чего диагностика не найдёт **Термины, совпадающие с обычными словами.** Для языка `докер` — портовый рабочий, `обсидиан` — вулканическое стекло, `кварк` и `глюон` — частицы, `опус` — музыкальное произведение. Все они есть в корпусе, и находкой не станут. Отчасти эту дыру закрывают пометки модели — но только когда она спотыкается. Термин, стоящий в предложении складно, не заметит никто. **Прижившиеся заимствования.** Список знает `баг`, `релиз`, `хостинг`, `контент`, `кейс`. Проверено: из двенадцати айтишных слов девять он не знает (`бэкенд`, `деплой`, `коммит`, `репозиторий`, `фича`, `промпт` и другие), но три пропускает. **Слово, которое всегда искажается одинаково.** Если правильная форма не встречается ни разу, сравнивать не с чем — но такое слово всё равно попадёт в находки, если языку неизвестно. Пропуски не критичны: эти слова обычно уже заведены вручную, а новые заметны при чтении текста. ## Решения по поведению **Ограничить вывод нечем.** Флага для этого нет вовсе — не «по умолчанию выводится всё», а «обрезать невозможно». Сначала такой флаг был, с полным выводом по умолчанию. Убран после того, как обрезка случилась на практике: показанная человеку половина списка превращает его согласие в согласие вслепую. Раз обрезать нельзя никогда, флаг только создаёт соблазн. Длинный вывод — повод сузить период, а не спрятать находки. **Порог частоты по умолчанию — два.** Три пятых находок встречаются ровно один раз: на всей истории порог 1 даёт 4307 находок, порог 2 — уже 1670. Отсеянное — оговорки, обрывки и мусор распознавания вроде «витлений» или `Pungaline`. Единица не выбрана потому, что термин, которым пользуются, повторяется. А если однократное слово всё же окажется нужным, оно всплывёт при следующем запуске: порог не теряет находку навсегда, он откладывает её разбор до второго употребления. **Период отменяет ограничение по количеству.** Иначе запрос «за вчера» молча обрезался бы до одной записи — значение по умолчанию у счётчика. **Границы суток по местному времени.** История хранится в UTC. Без пересчёта «вчера» съезжало бы на несколько часов и захватывало соседние сутки. **Отдельная строка про записи без наших правил.** Если диктовка шла в режиме, где блока нормализации нет, разбирать находки бессмысленно — сначала надо переключить режим. Такое уже случалось, и без этой строки было незаметно. **Корпус вне репозитория.** 33 МБ чужих данных в истории заметок ни к чему; отсутствие файла — явная ошибка, а не тихая работа вхолостую. **База читается через временную копию, только на чтение.** Приложение может работать и писать в неё в этот момент; диагностика не должна ни мешать ему, ни блокировать файл. **Сравнение без учёта регистра, показ — как в тексте.** Искать слово, помня его точное написание, неудобно. Но в выводе оно должно выглядеть так, как встретилось: `Kanban-доской`, а не `kanban-доской`. **Слова короче трёх букв пропускаются.** Предлоги, союзы и обрывки распознавания дают сплошной шум, а полезных терминов такой длины почти нет. **Фразы из списка шума разбиваются на слова.** Иначе выдуманные распознаванием титры попадали бы в находки по частям: сама фраза заведена целиком, а её слова языку неизвестны. **Папка словаря подменяется переменной `SW_DICT_DIR`.** Нужно, чтобы прогонять диагностику против тестовой копии, не трогая рабочую. Исключения читаются из той же папки и подменяются вместе со словарём.