Справочник Plugin API
На этой странице объясняется текущий контракт разработки. Обозреватель возможностей содержит актуальный каталог, точные имена методов, сигнатуры и объявления исходного кода. Опубликованное приложение или публичный шаблон могут предоставлять более старые версии; сопоставляйте диапазоны requires с проверенным хостом.
Пакет и манифест
Плагин содержит manifest.json и автономный ES-модуль, обычно main.js. Храните исходный код и необходимые ресурсы вместе с пакетом для проверки.
| Поле | Значение |
|---|---|
id, name, version | Стабильное пространство имён, отображаемое имя и версия пакета. Идентификатор совпадает с именем папки. |
schemaVersion | Положительное целое число для схемы приватных данных плагина; не зависит от версии пакета. |
requires | Идентификаторы возможностей и семантические диапазоны версий, сгруппированные в domains, contributions, services и schemas. |
permissions | Семантические полномочия, например library:read или service:llm. |
settingsAccess | Отдельные разрешения discover, read и write для точных путей или явных групп разделов. |
networkAccess | Разрешённые HTTP(S) источники для Network 2.x; требуется вместе с service:network. |
minAppVersion | Необязательный минимальный уровень версии приложения, дополнительно к требованиям возможностей. |
main | Относительный модуль входа; по умолчанию main.js. |
settings, schedules, themes, fonts | Объявления, интерпретируемые хостом. |
services | Версионированные, типизированные экспорты модульных сервисов для вызовов между плагинами. |
Нет поля манифеста, которое предоставляет произвольный доступ к файловой системе, SQL, DOM или нативному IPC.
Контекст и область действия объектов
Хост вызывает activate(ctx) с ctx.domains, ctx.contributions и ctx.services, а также манифест, локаль, версию приложения, фазу жизненного цикла, версии возможностей и неизменяемый грант на книгу.
ctx.grants.book — это all, current или указанная book. Хост выбирает его через согласие. Чтение, память, разговоры, команды и ресурсы сохраняют эту область действия при вызовах и обратных вызовах. Изменение текущей книги может сделать недействительными незавершённые чтения, дескрипторы, предложения и наблюдения.
Право на запись в домене включает чтение. Разрешения настроек остаются отдельными по операции. Пространства имён или методы, ограниченные разрешениями, могут отсутствовать; проверки на стороне хоста всё равно выполняются при каждом вызове. Используйте ctx.services.session.operationAvailability(...) для поддерживаемых предварительных запросов и обрабатывайте сбой выполнения даже после положительного результата.
Домены
| Домен | Доступная работа | Границы |
|---|---|---|
library | Книги и коллекции, оглавления, точный поиск местоположений, диапазоны, ссылки и изображения, импорт, текстовые задачи, метаданные, слияние дубликатов и удаление. | Исходные версии, область действия книги, ограниченные чтения, задачи, принадлежащие актору, и отдельные квитанции очистки файлов. |
reading | Снимки сеанса, навигация, выделение, управление воспроизведением и режимами, прогресс, время чтения и аналитика. | Защита текущего сеанса, установленное и ожидающее состояния, доступность провайдера и отмена. |
annotations | Страницы, проверка и наблюдения; создание выделений или заметок; условные пакетные правки/удаления. | Используйте ревизию, наблюдаемую до решения пользователя. Захваченные диапазоны также требуют доступа к Library. |
conversations | Авторизованные стенограммы, сохранённые сводки, состояние выполнения и запросов на поворот; управление потоками и предложенные повороты. | Одобрение хоста запускает предложенный поворот. Глобальные операции с потоками требуют доступа ко всем книгам. Плагины не заменяют чат-рантайм. |
settings | Обнаружение каталога, разрешённые снимки, параметры, метаданные моделей, наблюдение, обновления и сбросы чтения. | Точные пути, целевая политика и дополнительные полномочия для работы с внешними провайдерами. |
memory | Поиск и страницы, проверка, исправление/забывание, профили, сущности, классификация, графы и задачи, контекстные архивы. | Гранты на книги и условные ревизии. Глобальные операции с идентичностью/профилями требуют доступа ко всем книгам; генерация также требует полномочий модели. |
Исходный текст и навигация
Используйте library.queries.books.searchLocations для навигационных совпадений в исходном тексте и readRange для ограниченного исходного текста. Сохраняйте возвращённую исходную версию и местоположение. Производные совпадения searchText являются предпросмотрами, а не взаимозаменяемыми навигационными якорями. Явная подготовка текста возвращает задачу, за прогрессом и результатом которой необходимо наблюдать.
Условные записи
Проверьте текущий объект и сохраните его ревизию перед показом правки. Отправьте условную мутацию с этой ревизией. При конфликте перечитайте и дайте пользователю решить; молчаливая замена ожидаемой ревизии перезапишет другое изменение.
annotations.commands.applyChanges, мутации памяти, коммиты приватных документов и предпросмотры транзакций имеют свои собственные типизированные контракты. Обычные команды не автоматически отменяемы и не являются распределёнными транзакциями.
Наблюдения и реакции
Используйте авторизованные наблюдения для текущего состояния и зафиксированные подписки для событий. Порядковый номер может упорядочивать доставки, не будучи курсором базы данных или ревизией для условной записи. Неудачные наблюдения должны оставаться отличимыми от пустых результатов.
Используйте ctx.withEvent(delivery) для автоматической последующей работы и стабильных идентификаторов правил на причинно-следственных подписках, где это требуется. Сохраняйте связанный контекст при асинхронных вызовах. Хост отклоняет причинно-следственные циклы и истёкшие доставки; независимые действия пользователя используют исходный контекст.
Вклады
| Вклад | Что поставляет плагин |
|---|---|
selectionActions, headerActions, contextActions, commands, uriHandlers | Действия на типизированных поверхностях хоста, команды палитры и обработка URI в пространствах имён. |
settingsOptions | Динамические параметры для объявленной настройки плагина. |
voiceProviders, contentProviders, readerModes | Синтез аудио, контент виртуальных книг и встроенные режимы сегментации чтения. |
agentTools, agentContextProviders, agentRetrievalProviders | Инструменты, ограниченный контекст на поворот и доступные источники, принадлежащие плагину. |
memoryCandidateProviders | Кандидаты памяти для проверки и принятия хостом. |
themes, fonts | Объявленные в манифесте варианты внешнего вида. |
syncTransports | Хранение непрозрачных зашифрованных конвертов синхронизации и метаобъектов. |
Действия могут обновлять своё собственное состояние видимости/активности/отметки, где это поддерживается. Регистрации и одноразовые ресурсы принадлежат одной активации. Возврат представления не предоставляет обратному вызову дополнительные полномочия домена.
Кандидаты памяти и прямые команды Memory — это отдельные пути: кандидаты проходят через принятие хостом, тогда как прямые команды требуют соответствующего гранта Memory и ревизии. Ни один из них не позволяет внедрять системные правила или заменять основного агента.
Сервисы хоста
| Сервис | Используйте для | Ключевое ограничение |
|---|---|---|
storage | Приватное KV, коллекции документов, условные коммиты, страницы, наблюдения и политики использования. | Пространство имён плагина и квоты; устаревшие курсоры требуют новой базовой линии. |
resources | Выбранные пользователем файлы/каталоги, запечатанные байтовые дескрипторы, экспорты, изображения и приватные бинарные ресурсы. | Нет неявных путей. Дескрипторы имеют владельцев, лимиты и сроки жизни. |
secrets | Приватные зашифрованные слоты учётных данных плагина. | Нет доступа к секретам другого плагина. |
network | HTTP с ограничением по источнику, ограниченные буферизованные запросы и потоковая передача. | Каждое перенаправление проверяется; нет автоматического повтора произвольных записей. |
llm | Текстовая или структурированная инференция, потоковая передача, ресурсы изображений, квитанции запросов и бюджеты. | Конфигурация пользователя, правила конфиденциальности, отмена и лимиты хоста/провайдера. |
clipboard | Запись текста или запечатанного изображения. | Явное разрешение и поддерживаемый тип ресурса. |
ui | Представления, тосты, нативные потоки сохранения/открытия, навигация по рабочему пространству и командам, панели читателя и окна. | Специфические для метода гранты домена и собственная презентация хоста. |
session | Нечувствительные метаданные среды и доступность операций. | Нет старой подписки на сеанс чтения; используйте домен Reading. |
schedules | Объявленные повторяющиеся обработчики и собственные отложенные запросы. | Работа выполняется, пока приложение открыто; время не точное. |
jobs | Поддерживаемые устойчивые планы, контрольные точки, наблюдение и контроль. | Типизированные операции хоста, а не произвольное выполнение JavaScript. |
changes | Ограниченные устойчивые курсоры изменений. | Подсказки перезагрузки, а не необработанный журнал событий или исторические значения. |
transactions | Предпросмотр, коммит, поиск квитанций и условный предпросмотр отмены. | Поддерживаемые локальные операции и исходные гранты; неизвестные результаты требуют поиска квитанций. |
plugins | Проверка регистраций, наблюдение за изменениями, обнаружение и вызов типизированных сервисов плагинов. | Пересечение полномочий вызывающего/вызываемого, область действия, версии и изолированное выполнение сервиса. |
maintenance | Статус и резервное копирование хоста, проверка соединения и потоки обновлений. | Хост хранит учётные данные, диалоги файлов и подтверждение последствий. |
sync | Авторизованный статус синхронизации, отставание и управляемые хостом потоки учётной записи или синхронизации. | Нет ключей шифрования или необработанных учётных данных. |
diagnostics, logging | Проверенные диагностические экспорты и ограниченные структурированные события разработчика. | Нет произвольного контента, секретов или автоматической отправки через API логирования. |
Сеть и инференция
Network 2.x требует и семантического разрешения, и явных источников:
{
"requires": { "services": { "network": "^2.2.0" } },
"permissions": ["service:network"],
"networkAccess": { "origins": ["https://api.example.com"] }
}Замените пример источника на конечную точку, которую вы фактически используете. Источники включают схему, хост и порт; это не пути URL или поддоменные шаблоны. Перенаправления должны оставаться авторизованными. Потоковые вызывающие закрывают собственные потоки после завершения. Необязательный безопасный повтор ограничен поддерживаемыми запросами чтения до доставки ответа; отмена не откатывает удалённый побочный эффект.
Для инференции используйте readingContext для контекста книги, чтобы хост мог применять правила конфиденциальности и области действия. Используйте запечатанные идентификаторы ресурсов для поддерживаемых изображений. Метаданные запроса и бюджеты вывода помогают контролировать работу; это не платёжный документ и не гарантия соответствия провайдера.
Фоновая работа и транзакции
Используйте расписание для организации вызова обработчика, собственный отложенный запрос для более поздней работы, пока приложение работает, и устойчивое задание только тогда, когда его типизированный план поддерживает операцию. Восстановление после перезапуска может потребовать внимания, а не слепого повторения неопределённого внешнего результата.
Транзакции объединяют поддерживаемые настройки, приватные документы и операции домена под исходными грантами. Предпросмотр замораживает предлагаемую работу; коммит потребляет этот предпросмотр. После неизвестного ответа проверьте квитанцию перед повтором. Отмена условна — состояние должно всё ещё соответствовать предыдущему результату.
Сервисы между плагинами
Объявите идентификатор сервиса, версию, область действия, требуемые разрешения и схемы ввода/вывода в манифесте провайдера и экспортируйте его обработчик в объекте services модуля. Обнаруживайте и вызывайте его через сервис Plugins. Хост запускает свежую изолированную область сервиса с пересечёнными полномочиями; он не активирует обычный UI-рантайм провайдера для вызова. Вызовы, инициированные агентом, сохраняют требование одобрения.
Представления, настройки, темы и шрифты
Плагины возвращают декларативные данные представлений. Хост рендерит списки, формы, markdown, детали и поддерживаемые блочные макеты. Используйте типизированные результаты представлений и живые обновления; держите состояния загрузки, конфликта, пустоты и ошибки различимыми. Нет React, DOM, iframe или произвольного CSS для кода плагина.
Поля настроек рендерятся хостом. Поля секретов записываются в зашифрованные слоты секретов и не становятся обычными значениями формы или видимыми для модели настройками. Предоставление темы или шрифта требует ui:themes; выбор использует соответствующее разрешение записи в Settings.
Жизненный цикл и совместимость
- Активация: поддерживаемые чтения и регистрации; поэтапные вклады ещё не видны.
- Миграция: только приватное хранилище, до фиксации изменённой схемы.
- Активен: продвигаемые обработчики могут использовать предоставленные возможности.
Хост проводит проверку работоспособности и продвигает кандидата после успешной активации и миграции. Сбой восстанавливает предыдущий пакет и данные. Выгрузка освобождает регистрации, обратные вызовы и собственные ресурсы; устойчивые данные следуют отдельному контракту хранения. В текущей разработке удаление удаляет коллекции приватных документов и бинарные ресурсы, сохраняя определённое состояние KV/секретов/схемы для повторной установки.
Объявляйте каждую используемую возможность и схему независимо. Номер версии доказывает совместимость контракта, а не то, что каждая операционная система, провайдер или случай сбоя прошли сквозное приёмочное тестирование. Проверьте фактический рабочий процесс настольного приложения, который вы публикуете.