# 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`. **В плане показываются формы, отданные модели.** Это единственная часть переноса без гарантии, и её стоит просматривать глазами: форма могла попасть туда по ошибке в словаре. **Блок в промпте перезаписывается целиком.** Скрипт находит свою метку и заменяет всё от неё до конца. Дописывать по частям нельзя: тогда удалённые из словаря записи оставались бы в промпте навсегда. Текст выше метки не трогается — там лежит то, что настроено в приложении помимо нормализации. **Резервные копии перед каждой записью.** Файлов всего два, копии дешёвые, а откат при неудачном переносе нужен немедленно. **Отсутствие доступа — остановка, а не частичная работа.** Если конфигурация недоступна, скрипт завершается до первой записи. Наполовину применённый перенос хуже, чем неприменённый.