# 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 МБ чужих данных в истории заметок ни к чему.
Если файла нет, скрипт останавливается с сообщением. Скачивается он
из открытого источника одним запросом.
Править корпус руками не надо — он заменяется целиком при обновлении, и правки
пропадут. Недостающие обычные слова заносятся в исключения.