# apply — дизайн
Почему перенос устроен именно так. Как пользоваться — в
[[apply — документация]].
## Оглавление
- [[#Назначение и границы]]
- [[#Разложение словаря по трём механизмам]]
- [[#Список слов: канон и все формы]]
- [[#Замены: только безопасные формы]]
- [[#Промпт: каноны и все формы]]
- [[#Пометка неопознанного]]
- [[#Критерий — неуместность, а не незнакомость]]
- [[#Порог чувствительности]]
- [[#Почему двойной кинжал]]
- [[#Запрет на перевод]]
- [[#Требование к механизму замен]]
- [[#Как это проверено]]
- [[#Почему грубая замена по подстроке недопустима]]
- [[#Что из этого следует для словаря]]
- [[#Доступ к папке Documents]]
- [[#Full Disk Access диалогом не запрашивается]]
- [[#Диалог показывают только приложению]]
- [[#Исполняемый файл обязан быть настоящим Mach-O]]
- [[#Запускать только через `open -a`]]
- [[#Разрешение спрашивается один раз]]
- [[#Побочные следствия]]
- [[#Решения по поведению]]
## Назначение и границы
Скрипт **только переносит**. Он не редактирует словарь и не решает, что в него
класть: это работа `dict`.
Разделение то же, что и раньше: правка локального файла безопасна, а запись
в конфигурацию приложения — нет. Смешивать в одной команде не стоит, иначе
любая мелкая правка словаря становится операцией с риском.
Скрипт также **не создаёт режим**. Он обновляет уже существующий, потому что
при создании пришлось бы выбирать модели, язык и прочие настройки — а это
решения, которые принимает человек, а не перенос.
## Разложение словаря по трём механизмам
Смысл всей затеи: одна запись в словаре превращается в три разные настройки,
и человек не должен держать это соответствие в голове.
### Список слов: канон и все формы
В подсказку распознаванию идут и канон, и все его формы.
Может показаться, что подсказывать искажённые формы бессмысленно — но список
влияет на то, что модель **услышит**, а услышать она может любую из них.
Канона в списке недостаточно: он не помогает, когда произносится другой
вариант названия.
### Замены: только безопасные формы
Замены детерминированы: строка совпала — подстановка произошла. Это
единственный механизм с гарантией, и потому основной.
Но подстановка слепа, поэтому в неё идут только формы, помеченные в словаре
как безопасные. Решение принимается при ведении словаря, а не здесь: скрипт
переноса ничего не оценивает.
### Промпт: каноны и все формы
В промпт идут **все** формы, независимо от флага — в том числе те, что уже
попали в замены.
Дублирование здесь намеренное. Слои не делят работу между собой, а
**страхуют друг друга**:
```
замена -> берёт точное совпадение, гарантированно
модель -> берёт всё остальное, включая падежные формы
```
Замена пословная: форму «докер» она починит, а «докере», «докером»,
«докера» не увидит — это другие слова. Такие формы доезжают до модели как
есть, и если бы их не было в промпте, чинить их было бы нечем.
Раздел «не путать» собирается из `notMatch`: это защита от обратной ошибки,
когда модель исправляет то, что исправлять не следовало.
> [!warning] Не «оптимизировать» отсюда формы
> Убрать из промпта то, что уже есть в заменах, кажется разумным — промпт
> короче, дублирования нет. Но тогда перестанут чиниться все падежные формы,
> а в языке со склонением это большинство употреблений.
## Пометка неопознанного
Последнее правило промпта просит модель обернуть в знаки `‡ ‡` место, где
слово сидит в фразе криво: не вяжется с соседями, выпадает из смысла, читается
как чужое.
Правило закрывает дыру в диагностике. Она сравнивает текст с корпусом языка
и потому слепа к искажениям, **совпавшим с обычным словом**: `ищу` вместо
`Issue`, `паф` вместо `path`, `оси` вместо `ОС`. Все три есть в корпусе,
находкой не станут никогда, и сколько ни запускай диагностику — не всплывут.
Модель на таком месте спотыкается: «надо ищу создать продукт» невозможно
грамматически. Просим её оставить след — и получаем сигнал там, где своих
средств у нас нет.
> [!info] Откуда взялась идея
> Замечено на живом случае: модель **сама** написала `ИЩУ` прописными, хотя
> распознавание выдало строчные. Канона она не нашла, но неуместность
> почувствовала и выделила единственным доступным ей способом.
>
> Регистр как сигнал не годится — настоящие аббревиатуры дают ложные
> срабатывания. Поэтому спонтанное поведение заменено явной пометкой.
Правило намеренно не просит исправлять: подбор замены здесь означал бы
догадку, а догадка противоречит правилу 4. Пометка — это указание места,
решение по нему принимает человек.
### Критерий — неуместность, а не незнакомость
Самая опасная ошибка в формулировке этого правила — попросить отмечать
«подозрительное» без уточнения. Тогда модель разметит все термины подряд:
`кварк`, `глюон`, `MCP`, `Kanban` ей незнакомы ровно так же, как искажения.
А это весь наш словарь, то есть вывод превратится в шум.
Поэтому в правиле прямо сказано, что незнакомость поводом не является. Редкое
название, вписанное в фразу складно, — нормальный текст. Помечается только
то, что стоит **не на своём месте**.
Граница проходит не по словарю модели, а по связности фразы, и в этом всё дело:
о связности модель судить умеет, а о том, какие названия бывают в нашей
предметной области, — нет.
### Порог чувствительности
Первая формулировка заканчивалась словами «сомневаешься — не помечай».
Заменено на обратное: **сомневаешься — пометь**.
Цены ошибок несимметричны. Лишняя пометка стоит одной строки в выводе
диагностики, которую человек отбросит за секунду. Пропущенная ошибка означает,
что искажение продолжает попадать в тексты, и заметить его больше нечем —
именно этот класс не ловится ни корпусом, ни частотой.
Порог осознанно смещён в сторону чувствительности; насколько сильно — покажет
замер: доля пометок, которые пошли в дело.
### Почему двойной кинжал
Знак обязан не встречаться в тексте случайно и ничего не значить там, куда
текст попадёт потом. Большинство очевидных вариантов отпадает:
| Знак | Почему нет |
|---|---|
| `?` `!` `«»` | часть пунктуации, спутается с обычной речью |
| `[[ ]]` | вики-ссылка в редакторе заметок |
| `{{ }}` | шаблонный синтаксис, плагины подставят своё |
| `%% %%` | комментарий, текст станет невидимым |
| `<? ?>` | похоже на разметку, может быть скрыто |
| `== ==` | выделение маркером |
| ПРОПИСНЫЕ | аббревиатуры дают ложные срабатывания |
`‡` не участвует в грамматике ни одного языка и в редакторах ничего не значит.
Пометка ограничена одной строкой: перевод строки её обрывает. Так потерянный
закрывающий знак испортит одно место, а не съест половину текста.
## Запрет на перевод
Правило сопоставления по звучанию отдельно оговаривает: **русский перевод
канона каноном не является**.
> [!warning] Случай из практики
> Канон `Issue` заставил модель переписать обычное слово «случай» в `Issue` —
> трижды в одной записи. Замены отработали чисто, распознавание тоже: слово
> подменила языковая модель.
>
> ```
> сырой текст: Слово «Случай». Что означает под словом «случай»?
> итог модели: Слово «Issue». Что означает под словом «Issue»?
> ```
>
> Созвучия здесь нет вовсе. Модель сопоставила по смыслу: «случай» — русский
> перевод слова issue.
Опасность общая, а не про одну запись. Любой канон, который является обычным
английским словом с ходовым русским переводом, тянет её за собой: `Issue`
и случай, `path` и путь, `Discovery` и открытие.
Поэтому запрет стоит в самом правиле 1, а не разбирается через `notMatch`.
Перечислить все возможные переводы заранее нельзя — их не угадать, а промах
обнаружится только по испорченному тексту.
`notMatch` тут работает вторым слоем: он закрывает конкретную подмену, которая
уже случилась, и не заменяет общего запрета.
## Требование к механизму замен
Замена должна сопоставлять **слова целиком, а не подстроки**. Это не деталь
реализации superwhisper, а требование: при переходе на другой транскрибатор
или при собственной реализации механизм обязан вести себя так же, иначе
словарь начнёт портить текст.
### Как это проверено
Измерено на истории распознавания. В настройках было правило `гит -> git`.
Слова, содержащие «гит» как часть, **не были затронуты**:
```
гитхаб -> гитхаб (не тронуто)
гитте -> гитте (не тронуто)
гитар -> гитар (не тронуто)
гитфлоу -> гитфлоу (не тронуто)
```
При этом на отдельном слове правило срабатывает: четыре раза за три месяца,
все промахи приходятся на время до его добавления.
Вывод: сопоставление пословное. Официальная документация это подтверждает
формулировкой «замены сопоставляют слова без учёта регистра».
### Почему грубая замена по подстроке недопустима
В языке со склонением подстрочная замена ломает текст:
```
пословно «в обсидиане» -> «в обсидиане» не тронуто, чинит модель
по подстроке «в обсидиане» -> «в Obsidianе» сломано
```
Во втором случае к латинскому названию приклеивается русское окончание.
Такой текст хуже исходного: исходный хотя бы читаем.
### Что из этого следует для словаря
Флаг `safeToReplace` **не должен** учитывать склоняемость. Склонённые формы
просто не попадут под замену и достанутся языковой модели — это штатное
поведение, а не потеря.
Флаг нужен только там, где форма совпадает с настоящим словом языка: замена
сработает и в обычном предложении, где это слово употреблено по прямому
назначению.
> [!warning] При собственной реализации
> Границы слова должны учитывать кириллицу. Регулярное выражение вида `\b`
> в некоторых языках программирования работает только с латиницей, и тогда
> «обсидиане» ошибочно совпадёт с «обсидиан».
## Доступ к папке Documents
Конфигурация superwhisper лежит в `~/Documents`, а эта папка защищена
механизмом macOS TCC. Обычный скрипт туда не пустят, причём **молча** —
без диалога и без внятной ошибки, просто отказ в доступе.
Всё описанное ниже добывалось опытом, поэтому зафиксировано подробно.
### Full Disk Access диалогом не запрашивается
Здесь легко пойти не туда. Два разрешения ведут себя по-разному:
| Разрешение | Запрашивается диалогом |
|---|---|
| Full Disk Access | **нет**, только вручную в системных настройках |
| Доступ к папке Documents | **да** |
Программного способа попросить Full Disk Access не существует вовсе. А вот
доступ к Documents запросить можно — но не любому процессу.
### Диалог показывают только приложению
Запрос засчитывается «ответственному процессу», и им должно быть полноценное
приложение: с идентификатором бандла, с подписью и с ключом
`NSDocumentsFolderUsageDescription` в `Info.plist`. Текст из этого ключа
пользователь увидит в самом диалоге.
Скрипту, запущенному из терминала, диалог не покажут. Поэтому скрипт собирает
минимальное `.app`, подписывает его ad-hoc и запускает — а уже приложение
вызывает этот же файл с флагом `--write`.
Разрешение достаётся именно этому приложению, а не терминалу целиком: доступ
получает один понятный инструмент, а не всё, что запущено в консоли. Отозвать
можно там же, где выдано — в разделе Files and Folders системных настроек.
### Исполняемый файл обязан быть настоящим Mach-O
Если сделать исполняемым файлом бандла shell-скрипт, доступ к файлам запросит
**интерпретатор** — системный бинарник. Система не отнесёт запрос к приложению
и откажет молча, не показав диалога.
Проверено: со скриптом внутри бандла отказ приходит без диалога, с
скомпилированным бинарником диалог появляется. Поэтому ядро собирается через
`bun build --compile`.
Смысл правила простой: разрешение привязывается к тому коду, который
обращается к диску. Скрипт таким кодом не является.
### Запускать только через `open -a`
Прямой вызов бинарника из терминала наследует атрибуцию терминала и получает
отказ — несмотря на то, что это тот же самый подписанный файл.
Проверено: тот же бинарник, запущенный напрямую, возвращает `EPERM`;
запущенный через `open -a`, работает.
### Разрешение спрашивается один раз
Дальше оно действует постоянно. Диалог появится снова только в двух случаях:
при явном сбросе или **при изменении исходника ядра**.
Второе неочевидно. Приложение подписано ad-hoc, а при такой подписи
идентичность приложения — это хеш его кода. Пересборка даёт новый хеш, система
считает бандл другим приложением, и старое разрешение к нему не относится.
Поэтому бандл пересобирается только когда исходник ядра стал новее
собранного бинарника. Пересборка на каждом запуске приводила бы к диалогу
при каждом применении.
> [!warning] Не сбрасывать разрешение без нужды
> Первая версия скрипта сбрасывала решение системы перед каждым запуском —
> это осталось от отладки, когда приложение застряло в записанном отказе.
> В результате система спрашивала заново каждый раз, потому что ей велели
> забыть предыдущий ответ.
### Побочные следствия
**Логи вместо вывода.** У приложения, запущенного через `open`, нет терминала.
Поэтому ядро складывает вывод в файл, а скрипт его читает и показывает.
**Артефакты вне хранилища заметок.** Собранное приложение весит около 60 МБ.
Оно лежит в папке сборки, закрытой `.gitignore`, иначе попадёт в синхронизацию
и в историю репозитория.
## Решения по поведению
**По умолчанию — план, а не применение.** Команда без аргументов ничего
не меняет. Запись требует явного слова `apply`.
**В плане показываются формы, отданные модели.** Это единственная часть
переноса без гарантии, и её стоит просматривать глазами: форма могла попасть
туда по ошибке в словаре.
**Блок в промпте перезаписывается целиком.** Скрипт находит свою метку
и заменяет всё от неё до конца. Дописывать по частям нельзя: тогда удалённые
из словаря записи оставались бы в промпте навсегда.
Текст выше метки не трогается — там лежит то, что настроено в приложении
помимо нормализации.
**Резервные копии перед каждой записью.** Файлов всего два, копии дешёвые,
а откат при неудачном переносе нужен немедленно.
**Отсутствие доступа — остановка, а не частичная работа.** Если конфигурация
недоступна, скрипт завершается до первой записи. Наполовину применённый
перенос хуже, чем неприменённый.