Структура плагина

Плагин — каталог с корневым plugin.json. Манифест объявляет файлы для загрузки и возможности, которые появятся в GrigDesk.

Файлы пакета

У простой панели структура может быть такой:

first-plugin/
├── plugin.json
├── assets/icon.png
├── ui/
│   ├── panel.js
│   ├── panel.css
│   └── locales/
│       ├── ru.json
│       └── en.json
└── docs/README.md

Серверный файл добавляют при необходимости и явно объявляют в entrypoints.server. Наличие server.js рядом с манифестом само по себе его не подключает.

Манифест v1

Это полный манифест учебного плагина:

{
  "id": "first-plugin",
  "api": 1,
  "name": "Счётчик проверок",
  "version": "1.0.0",
  "description": "Учебная панель со счётчиком проверенных пунктов",
  "icon": "assets/icon.png",
  "category": "dev",
  "entrypoints": {
    "web": {
      "dir": "ui",
      "entry": "panel.js",
      "css": ["panel.css"],
      "locales": { "ru": "locales/ru.json", "en": "locales/en.json" }
    }
  },
  "contributes": {
    "panels": [{ "title": "Счётчик проверок", "group": "tools", "order": 50 }]
  },
  "install": { "npm": [] }
}

Поле	Назначение
id	Уникальное имя пакета: строчные латинские буквы, цифры, _ и -; первый символ — буква или цифра, всего до 41 символа. Не должно совпадать с системным ID.
api	Поколение контракта. Сейчас только 1; это не версия плагина или пакета типов.
name, description	Имя и описание. Непустое описание обязательно, до 4096 символов.
version	Стабильная версия пакета для установки из Git, совпадающая с тегом без v.
icon	Путь к PNG, JPEG или WebP до 256 КиБ. Один файл используется в навигации и карточках.
entrypoints	Серверный вход и/или модуль интерфейса. Объект обязателен, но может быть пустым.
contributes	Панель, поддерживаемые слоты, настройки и другие декларации. Объект обязателен, но может быть пустым.
install.npm	Каталоги подготовки production-зависимостей. В примере зависимостей нет.

Необязательный engines.grigdesk задаёт минимум приложения только в форме ">=X.Y.Z". category выбирает группу каталога: work, dev, knowledge или other. gallery.screenshots может содержать до шести PNG/JPEG/WebP по 4 МиБ. SVG для иконки и галереи не принимается.

Пути относительны пакету. dir модуля задаётся от корня, а entry, css и locales — от dir. Нельзя использовать абсолютные пути, URL, выход через .., скрытые компоненты пути, node_modules и символические ссылки.

Перенос прежнего пакета

Старые верхнеуровневые web, webModule, nav, settings, placements и minGrigDeskVersion не адаптируются автоматически. Вместо них нужны entrypoints, contributes и, для минимума приложения, engines.grigdesk. Пакеты прежнего формата, включая api: 2, остаются видны с причиной несовместимости, но их код не исполняется.

Панель внутри GrigDesk

entrypoints.web указывает на готовый ESM-модуль .js или .mjs с компонентом Vue в default-экспорте. contributes.panels объявляет не более одной панели: group выбирает rail, tools или dock, order — порядок. Адрес /ext/<id> формирует GrigDesk.

Группа определяет место пункта навигации. Способ открытия зависит от текущего экрана и ширины окна: от 900 px панель доступна в доке рядом с текущей работой, а в узком окне открывается страницей. Переход между доком и страницей сохраняет экземпляр панели и её ввод.

Vue импортируется из vue, общие контролы и диалоги — из @grigdesk/ui. Их предоставляет окно приложения. Свои копии Vue, отдельный Vue app, хосты диалогов и EventSource не нужны. CSS выпускается отдельно; свои селекторы ограничивайте корнем панели.

Вход панели	Для чего нужен
context.api	Общий клиент get/post/put/patch/del с сессией, только пути /api/….
context.locale, context.t	Реактивный язык и перевод по словарям плагина.
context.settings	Доступные только для чтения эффективные значения настроек.
context.signal	Отмена при отзыве доступа к экземпляру.
context.events, context.alerts	Свои события через общий SSE и уведомления от имени плагина.
context.askAgent, context.panel	Новый чат с неотправленным черновиком и управление своей панелью.
active, compact, presentation	Видимость и способ показа панели.

Модуль загружается по первому спросу панели или объявленного слота. Необязательный start(context) может вернуть функцию очистки. При скрытии панель сохраняет ввод; при выключении плагина доступ отзывается. Освобождайте таймеры и подписки, учитывайте signal. После восстановления связи context может замениться без повторного setup: в действиях читайте актуальный prop.

Встраивание в существующий экран

Кроме своей панели плагин может объявить блок в поддерживаемом слоте ядра. Например, этот фрагмент манифеста добавляет данные исполнителя во всплывающее окно верхней панели, под полосами лимитов:

{
  "contributes": {
    "slots": [
      {
        "slot": "provider.popover.after-bars",
        "kind": "provider-usage",
        "default": true
      }
    ]
  }
}

Это дополнение к полному манифесту. Для слота также нужен объявленный entrypoints.server, который предоставляет данные JSON для provider-usage. Их отображает штатный интерфейс GrigDesk; произвольный Vue-компонент через этот слот не подключается. Размещение блока можно выключить в настройках, сохранив включённость остальных возможностей плагина.

Слот и contributes.panels можно использовать вместе. Для открытой панели доступны также свои уведомления через context.alerts, события через context.events и создание чата с неотправленным черновиком через context.askAgent.

Сервер и данные

entrypoints.server указывает на свой .js, .mjs или .ts с default-экспортом плагина Fastify. Его обработчики находятся под /api/ext/<id>/. В options.core доступны сервисы ядра; наличие нужных методов проверяет автор. Для действий только из пользовательского интерфейса проверяют request.authKind === 'session'.

Долговечные данные сохраняйте в options.dataDir, если он предоставлен. По умолчанию это state/plugins/<id>/ в папке данных GrigDesk, отдельно от установленного кода plugins/<id>/. Обновление кода не заменяет эту папку. Сервер должен освобождать свои ресурсы при закрытии; для длительных работ предусмотрен lifecycle.prepareReplace, который закрывает новый допуск и дожидается завершения работы перед заменой пакета.

Остальные декларации

contributes.settings описывает поля общей страницы настроек.

contributes.commands и contributes.themes пока сохраняют декларации id/title; исполнения команд и переключения тем они не добавляют.

Документация автора начинается с docs/README.md. Для включённого совместимого пользовательского плагина GrigDesk передаёт агенту путь к оглавлению; агент читает его, когда просьба относится к плагину. Остальные документы связывайте относительными ссылками. Без оглавления сам плагин продолжает работать.

Далее: создать первый плагин.