haperone_local-image-compress/README.ru.md

Local Image Compress

Сжимает PNG и JPEG файлы в desktop-хранилище локально через встроенные WebAssembly-кодеки. Облако не используется, внешние бинарники и node_modules для обычной установки не нужны.

English version

Установка

1. Установите Local Image Compress через Obsidian Community Plugins или скопируйте release-файлы в Vault/.obsidian/plugins/local-image-compress.
2. Включите плагин в Settings -> Community plugins.
3. Запускайте сжатие изображений.

Release самодостаточный. Устанавливать pngquant, mozjpeg, Homebrew, Scoop или зависимости в папку плагина не нужно.

Модель сборки и релиза

Исходники находятся в src-ts. Корневой main.js генерируется и игнорируется Git, поэтому в репозитории остаётся читаемый TypeScript, а не compiled output. npm run build создаёт production-minified локальный bundle; npm run test:release собирает его дважды, проверяет детерминированные байты, inline WASM и точный allowlist релиза.

GitHub release artifact содержит только install-файлы Obsidian: manifest.json, main.js и styles.css. versions.json остаётся в репозитории как compatibility metadata, но не загружается как release asset. Минификация не является обфускацией: полный читаемый исходный код остаётся в репозитории. Теги имеют точный numeric SemVer без префикса v. См. RELEASE_POLICY.md.

Возможности

• Локальное сжатие: PNG через libimagequant-wasm и PNG WASM decode; JPEG через mozjpeg-wasm.
• Команды:
  • Сжать все изображения в текущей заметке
  • Сжать все изображения в папке
  • Сжать все изображения во всём vault
  • Переместить сжатые файлы на места оригиналов
• Автоматизация:
  • Автосжатие новых файлов при добавлении
  • Фоновое сжатие при неактивности пользователя и превышении порога
• UI и удобства:
  • Контекстное меню для файлов/папок
  • Индикатор экономии места и tooltip с деталями
  • Статус-бар с индикатором процесса
• Безопасность и надёжность:
  • Кэш обработанных файлов с бэкапами кэша
  • Резервные копии перед перемещением сжатых файлов

Команды

• Сжать все изображения в заметке: Обрабатывает изображения, упомянутые или используемые в активной заметке.
• Сжать все изображения в папке: Даёт выбрать папку и сжимает все поддерживаемые изображения внутри, кроме папки вывода.
• Сжать все изображения в vault: Полный проход по хранилищу, исключая папку вывода.
• Переместить сжатые файлы: Переносит результаты сжатия туда, где лежали оригиналы. Перед перемещением создаётся резервная копия оригиналов и сжатых версий.

Поддерживаемые форматы

• PNG (imagequant WASM pipeline)
• JPEG/JPG (mozjpeg WASM pipeline)

WebP, GIF, BMP, HEIC/HEIF и AVIF в этом релизе намеренно пропускаются: для них не встроен encoder pipeline.

Настройки

Параметр	Описание	Тип/диапазон	По умолчанию
Качество PNG (мин-макс)	Диапазон качества для lossy PNG quantization	1-100 (например 65-80)	65-80
Качество JPEG	Качество сжатия JPEG	1-95	85
Разрешённые корни	Относительные пути, где разрешено сжатие. Пусто = везде	список строк	пусто
Выходная папка	Папка для сохранения сжатых файлов	строка	Compressed
Автосжатие новых файлов	Сжимать новые изображения при добавлении	boolean	false
Автоматическое фоновое сжатие	Сжимать в фоне при неактивности	boolean	true
Порог фонового сжатия	Количество несжатых изображений для автозапуска	10-1000	50
Порог неактивности	Минуты без действий пользователя перед запуском фонового сжатия	1-60 минут	2
Срок хранения кэша	Сколько месяцев хранить устаревшие записи кэша после последнего доступа	1-60 месяцев	12
Автоочистка призраков при старте	Удалять записи кэша на удалённые файлы при запуске	boolean	false
Автохранение бэкапов	Автоматически удалять старые бэкапы перед переносом	boolean	false
Хранить бэкапы, дней	Удалять бэкапы переноса старше N дней, если автохранение включено	1-365	30
Автоперемещение сжатых файлов	При запуске переносить сжатые файлы обратно к оригиналам, если готово достаточно файлов	boolean	false
Порог автоперемещения	Количество готовых к переносу сжатых файлов для автозапуска	1-1000	50

Страница настроек также показывает статус WASM-модулей, экономию места, управление кэшем, очистку призрачных записей и управление бэкапами.

Как это работает

1. Сжатые файлы сохраняются в папку Compressed с повторением структуры путей.
2. Кэш фиксирует факт обработки файлов и исходный размер, чтобы не сжимать повторно и корректно считать экономию.
3. Команда «Переместить сжатые файлы» переносит файлы из Compressed на места оригиналов, если оригинал найден в разрешённых корнях. Перед перемещением создаётся бэкап.

Минимальные размеры для сжатия: очень маленькие файлы обычно пропускаются (<5KB для PNG и <10KB для JPEG).

Внутренние лимиты безопасности фиксированы: файлы больше 100 МБ пропускаются до чтения, изображения выше 100 млн пикселей пропускаются после проверки заголовка, одно задание сжатия может выполняться до 120 секунд, а инициализация воркеров — до 60 секунд.

Кэш и бэкапы

• Кэш: Vault/.obsidian/plugins/local-image-compress/tinyLocal-cache.json.
• Бэкапы кэша: автоматически создаются при важных изменениях в Vault/.local-image-compress/backups/cache/; хранится не более 50 файлов.
• Бэкапы перед переносом: сохраняются в Vault/.local-image-compress/backups/originals/. Включают оригиналы и сжатые файлы по относительным путям vault.
• Существующие папки бэкапов из старых версий автоматически переносятся при запуске. Основной файл кэша остается в директории плагина.

Автоматизация

• «Автоматическое фоновое сжатие» при включении показывает ползунок порога.
• «Хранить бэкапы, дней» при включении показывает ползунок срока хранения.
• «Автоперемещение сжатых файлов» при включении показывает порог по количеству файлов. При запуске плагина, если в Compressed файлов не меньше порога, запускается перемещение.

Совместимость

• isDesktopOnly: true.
• Требуется Obsidian 1.4.0+.
• Нативные бинарники компрессоров не нужны на Windows, macOS и Linux.
• Поддержка mobile пока не заявляется: управление кэшем, перемещение и бэкапы всё ещё используют desktop Node filesystem API.
• Во время сжатия и перемещения совместимый плагин obsidian-paste-image-rename временно отключается, если он включён, чтобы избежать конфликтов имён и перемещения. Защита восстанавливает плагины, которые отключила сама, и не присваивает себе восстановление, если состояние плагина изменилось извне во время операции.

Взаимодействие с Paste Image Rename

Плагин временно отключает сторонний плагин obsidian-paste-image-rename на время сжатия или перемещения файлов. Настройки для отключения этой защиты нет, потому что сопоставление сжатого вывода с оригиналом зависит от того, что свежие файлы не будут переименованы другим плагином.

Зачем это нужно:

• Paste Image Rename вешает обработчик vault.on("create"), который срабатывает на каждое изображение, добавленное в хранилище в пределах ~1 секунды с момента создания. Он всегда обрабатывает файлы с именем, начинающимся на Pasted image , и все остальные изображения, если включена его опция «Handle all attachments».
• Когда наш плагин пишет сжатые копии в папку вывода, эти свежие файлы запускают тот обработчик. При активной Markdown-вкладке Paste Image Rename переименовывает только что записанный вывод (это ломает сопоставление «сжатый → оригинал», на которое опирается перемещение) или показывает модалку переименования на каждый файл. Без активной Markdown-вкладки он показывает уведомление Error: No active file found на каждый созданный файл — при пакетном прогоне это засыпает интерфейс ошибками.
• В Obsidian нет публичного API, чтобы один плагин попросил другой приостановиться, поэтому временное отключение этого одного плагина — единственный надёжный способ.

Как это сделано безопасно:

• Затрагивается только один известный id obsidian-paste-image-rename и только пока идёт операция сжатия или перемещения.
• Плагин всегда восстанавливается потом, с повторами. Защита отслеживает, она ли его отключила, и не присваивает себе восстановление, если состояние плагина изменилось извне во время операции.
• Включение/отключение этого плагина использует внутренний API Obsidian app.plugins, так как публичного аналога нет; вызовы feature-detected и мягко обрабатывают ошибки.

Приватность и внешнее поведение

• Сеть: плагин не выполняет runtime-сетевые запросы. PNG/JPEG-кодеки встроены в main.js; изображения не загружаются.
• Телеметрия и реклама: нет аналитики, телеметрии, crash reporting, tracking, динамической рекламы или механизма самообновления.
• Аккаунты и платежи: аккаунт, подписка, лицензионный ключ и оплата не нужны. Funding-ссылка в manifest необязательна и самим плагином не запрашивается.
• Файлы vault: плагин читает поддерживаемые изображения, выбранные командами, автоматизацией или allowed roots. Сжатые результаты пишутся в настроенную vault-relative папку; оригиналы заменяются только через документированный move/auto-move flow после создания бэкапов.
• Локальное состояние: кэш хранится в папке плагина. Бэкапы кэша и перемещения хранятся в Vault/.local-image-compress/backups/.
• Внешние файлы: управляемые данные остаются внутри текущего vault. Команды «Открыть папку» только просят ОС показать документированные папки бэкапов и ничего не передают.
• Другие плагины: obsidian-paste-image-rename может временно отключаться во время сжатия/перемещения, как описано выше, а затем восстанавливается с проверкой ownership.

Советы

• Разумный диапазон качества: PNG 65-80, JPEG 75-90.
• Настройте «Разрешённые корни», если хотите сжимать только определённые папки, например files/ или images/.
• Используйте фоновое сжатие, если в хранилище много несжатых изображений.

Частые вопросы

Плагин пишет, что WebAssembly-модули не инициализировались. Перезагрузите плагин. Если ошибка повторяется, приложите версию Obsidian, платформу и ошибку из консоли к bug report.

Где оказываются сжатые файлы? По умолчанию в Compressed. Для замены оригиналов используйте команду «Переместить сжатые файлы».

Как считается экономия? Экономия точная, когда в кэше есть исходный и выходной размеры. Для несжатых PNG/JPEG плагин использует консервативную оценку с ограниченными коэффициентами; текущие размеры сжатых файлов при необходимости читаются с диска.

Что такое призрачные записи? Записи кэша, которые указывают на удалённые или отсутствующие файлы. Их можно очистить в настройках.

Диагностика

• Убедитесь, что файлы достаточно большие: слишком маленькие изображения пропускаются.
• Проверьте «Разрешённые корни»: файлы вне этих путей не обрабатываются.
• Если перенос не происходит, убедитесь, что у сжатого файла есть соответствующий оригинал в разрешённом корне.
• Смотрите уведомления приложения и консоль разработчика для логов Local Image Compress.

Метаданные

• ID: local-image-compress
• Имя: Local Image Compress
• Версия: 1.0.1
• Минимальная версия приложения: 1.4.0
• Desktop-only: да
• Репозиторий: https://github.com/haperone/local-image-compress

Лицензия

• Дистрибутив плагина: GPL-3.0-or-later (см. LICENSE).
• Плагин включает WebAssembly-код imagequant/libimagequant под GPL v3, поэтому распространяемый плагин лицензирован как GPL-3.0-or-later.
• Сторонние кодеки: см. THIRD_PARTY_NOTICES.md и точные отслеживаемые тексты в licenses/.