# diagnose — документация Находит в истории распознавания слова, которых нет в корпусе языка, — термины, названия и жаргон, которым место в словаре. Почему устроено именно так — в [[diagnose — дизайн]]. ``` bun diagnose.ts [флаги] ``` Скрипт только читает: историю распознавания, словарь, исключения и разобранные пометки. Ничего не меняет ни в них, ни в настройках приложения. Вывод не ограничивается ничем и обрезать его нечем — флага для этого нет намеренно. Решение по находкам принимает человек, а решать он может только по тому, что видит целиком. ## Оглавление - [[#Флаги]] - [[#Выбор записей]] - [[#Порог частоты]] - [[#Что показывает]] - [[#Разбор находок]] - [[#Переменные окружения]] - [[#Корпус языка]] ## Флаги | Флаг | Значение по умолчанию | Что делает | |---|---|---| | `-n <число>` | `1` | сколько последних записей смотреть; `all` — все | | `--from <дата>` | — | с какой даты | | `--to <дата>` | — | по какую дату | | `-t <число>` | `2` | порог: не реже скольких раз встречается слово | Дата задаётся словом или числом: `сегодня`, `вчера`, `позавчера`, `2026-08-01`. ## Выбор записей Два способа, взаимоисключающие. **По количеству:** ```bash bun diagnose.ts # последняя запись bun diagnose.ts -n 100 # сто последних bun diagnose.ts -n all # вся история ``` **По датам:** ```bash bun diagnose.ts --from вчера # со вчера и до сих пор bun diagnose.ts --from вчера --to вчера # только за вчера bun diagnose.ts --from 2026-08-01 # с первого августа ``` Дата задаёт **сутки целиком**, время указать нельзя. Границы считаются по местному времени, хотя история хранится в UTC, — иначе «вчера» съезжало бы на несколько часов и захватывало соседние сутки. Если задан период, ограничение `-n` не применяется: иначе «за вчера» молча обрезалось бы до одной записи. ## Порог частоты ```bash bun diagnose.ts -n all -t 15 ``` Слова, встретившиеся реже указанного, не показываются. Порог нужен потому, что **три пятых** находок встречаются ровно один раз — это оговорки, обрывки фраз и мусор распознавания. Замерено на всей истории: 4307 находок при пороге 1 против 1670 при пороге 2. Термин, которым пользуешься, повторяется. Сказанное единожды либо мусор, либо всплывёт при следующем запуске — порог ничего не теряет навсегда, он лишь откладывает разбор до второго употребления. Рабочее значение — от 2 до 3 для коротких периодов и от 10 для всей истории. ## Что показывает **Сколько слов заглушено.** В шапке выводится число исключений — слов, признанных обычными вручную. Они в находки не попадают, и видеть их количество нужно, чтобы подавление не было молчаливым. ``` записей: 40 период: 2026-08-08 — 2026-08-09 порог: не реже 2 раз исключений: 6 разобранных пометок: 3 ``` Второе число — сколько пометок уже разобрано и потому не показывается. Ниже может появиться строка о сорванных записях: распознавание ушло в бессмыслицу и модель пометила почти каждое слово. Такие записи целиком пропускаются, разбирать в них нечего. **Отмеченное моделью.** Первая и самая ценная таблица. Языковая модель по правилу в промпте оборачивает в знаки `‡ ‡` места, где слово сидит в фразе криво — не вяжется с соседями, выпадает из смысла. Скрипт их достаёт и показывает с куском фразы вокруг: ``` === ОТМЕЧЕНО МОДЕЛЬЮ КАК НЕОПОЗНАННОЕ — найдено 2 === 3 ищу [2026-08-09] ...Тебе надо ‡ищу‡ создать продукт, создать, если его нету... 2 паф [2026-06-11] ...И там у тебя синтаксис ‡паф‡ указан. Чё за ‡паф‡?... ``` Только эта таблица ловит искажения, **совпавшие с обычным словом языка**: `ищу` вместо `Issue`, `паф` вместо `path`. Такие слова есть в корпусе и в остальные таблицы не попадут никогда. Порог частоты на неё не действует: находка ценна и в единственном экземпляре. Контекст показан сразу, потому что метка указывает точное место — по фразе обычно видно, что имелось в виду. Правило намеренно чувствительное: модели велено метить при сомнении, потому что лишняя строка в выводе дешевле пропущенной ошибки. Поэтому часть пометок окажется пустой — это ожидаемо. Но просто отбросить их нельзя: пометка стоит в тексте истории навсегда и вернётся при следующем запуске. Разобранную пометку надо закрыть командой `dict.ts resolve` с комментарием — тогда она больше не появится. Пометки на словах, которые с тех пор попали в словарь, гасятся сами. **Записи без наших правил.** Сколько записей сделано в режимах, где блока нормализации в промпте не было. Если таких много — правила просто не работали, и разбирать находки рано. **Две таблицы находок**, кириллица и латиница отдельно. Смешивать их нельзя: латиницы в русском языке нет вовсе, и она забила бы весь вывод. ``` === КИРИЛЛИЦА: нет в корпусе — найдено 16 === 16 промпт (промпту 1, промпте 1) 6 Kanban-доской (Kanban-доски 2) 4 промт (промта 1) ``` Первое число — суммарные употребления всех форм. Заголовок строки — самая частая форма, в скобках остальные. Падежные формы одного слова собираются в одну строку. Разные написания — не собираются: `промпт` и `промт` показаны раздельно, потому что второе не форма первого, а искажение. Ради таких находок скрипт и запускают. ## Разбор находок Скрипт только показывает список. Что делать с каждым словом — решает человек, и вариантов три. | Что со словом | Куда оно идёт | Команда | |---|---|---| | транскрибатор пишет его неверно | в словарь | `dict.ts add`, потом `variant` | | пишет верно, просто нет в корпусе | в исключения | `dict.ts except` | | созвучно уже заведённому канону | в `notMatch` этой записи | `dict.ts notmatch` | | разовая оговорка | никуда, само уйдёт под порог | — | | пометка разобрана | в разобранное, с комментарием | `dict.ts resolve` | Вопрос, который разделяет первые два случая, ровно один: **надо ли это слово чинить?** Надо — словарь. Не надо, а показывается — исключения. Занесённое слово при следующем запуске уже не появится: скрипт пропускает всё, что есть в словаре, в `notMatch`, в исключениях и в разобранном. Если по контексту непонятно, что было сказано, — не гадать, а послушать: `bun ../listen/listen.ts "<слово>"`. Скрипт найдёт нужный кусок записи и даст ссылку на него. Пометки — случай особый. Слово из пометки может никуда не попасть: оказаться оговоркой или остаться непонятым. Такую пометку всё равно надо закрыть через `resolve`, иначе она вернётся при следующем запуске, потому что стоит в тексте истории навсегда. После правки словаря изменения нужно перенести в приложение — `apply`. Исключения переносить не надо, они никуда не уезжают. ## Переменные окружения | Переменная | Назначение | |---|---| | `SW_DICT_DIR` | папка со словарём, исключениями и разобранным | Нужна, чтобы прогонять диагностику против тестовой копии. ## Корпус языка Точкой отсчёта служит корпус — файл со словоформами русского языка, 1,5 миллиона строк. Он лежит в `data/` рядом со скриптом и **в репозиторий не входит**: 33 МБ чужих данных в истории заметок ни к чему. Если файла нет, скрипт останавливается с сообщением. Скачивается он из открытого источника одним запросом. Править корпус руками не надо — он заменяется целиком при обновлении, и правки пропадут. Недостающие обычные слова заносятся в исключения.