Перейти к содержанию

Разработка с помощью ИИ

Портирование плагина или темы с Grav 1.7 на Grav 2.0 — в основном механическая работа: объявить флаг совместимости, открыть функциональность в виде эндпоинтов API, если у вас есть фичи админки, перенести схемы и языковые файлы для работы с Admin 2.0 и адаптироваться к обновлениям версий Symfony, Twig и PHP.

Механическая работа — как раз то, что хорошо даётся ИИ-агентам. Команда Grav выпускает набор Claude Code Skills — опубликованный на github.com/getgrav/grav-skills — в котором зашиты шаблоны, соглашения и подводные камни разработки плагинов Grav 2.0. С установленными навыками ИИ-агент вроде Claude Code получает знания о проекте, необходимые, чтобы правильно выполнить эту работу с первого раза.

Хотя эта страница находится в разделе миграции, навыки предназначены не только для портирования. Они так же полезны для:

  • Портирования существующего плагина Grav 1.7 для совместимости с 2.0 (флаги совместимости, устаревшие возможности PHP 8.3+, удаление привязок к классической админке)
  • Создания нового плагина Grav 2.0 с нуля, интегрированного с API и/или Admin Next
  • Добавления интеграции с Admin Next в плагин, у которого раньше был интерфейс классической админки (настраиваемые поля форм, страницы админки, навигация в боковой панели, панели, пункты меню)

Навыки также содержат ссылки на плагины Grav Premium (Yeti Search Pro, SEO Magic, AI Pro, AI Translate, Quick Links), чтобы у агента были реальные примеры для генерации кода.

На этой странице описано, что охватывает каждый навык, когда его вызывать и чего примерно ждать от агента.

Примечание

Эти навыки рассчитаны на Claude Code — официального терминального агента Anthropic для программирования. Те же шаблоны работают и с другими агентами, но файлы навыков в текущем виде используют формат Skills Claude Code.

Что такое навык?

Навык Claude Code — это markdown-файл, который ИИ-агент загружает по требованию, когда условия его срабатывания совпадают с вашей задачей. Каждый навык содержит:

  • Когда использовать: условия срабатывания, чтобы агент подхватывал его автоматически
  • Что делать: пошаговые процедуры, соглашения и шаблоны для конкретной области
  • Справочный материал: пути к файлам, имена событий и классов, структуры схем и другие факты, которые агенту трудно обнаружить с нуля

Навыки хранятся в вашей домашней папке или рядом с проектом, к которому относятся. Когда агент обнаруживает совпадение с триггером, содержимое навыка подключается к его рабочему контексту до конца задачи.

Доступные навыки для разработки плагинов Grav 2.0

grav-api-integration

Добавление эндпоинтов REST API в плагин Grav 2.0 через собственный плагин Grav API.

Когда использовать:

  • При работе в user/plugins/<plugin>/ с кодом, который открывает функциональность плагина как HTTP-эндпоинты
  • Когда пользователь упоминает Grav API, AbstractApiController, ApiResponse или onApiRegisterRoutes

Что охватывает:

  • Настройку контроллера с наследованием от AbstractApiController
  • Регистрацию маршрутов через onApiRegisterRoutes
  • Проверку разрешений и модель аутентификации
  • Помощники ответов, исключения, конверты ошибок
  • Шаблоны тестирования через curl

Используйте более полный навык grav-api-admin-next-integration, если вашему плагину также нужен собственный интерфейс Admin Next.

grav-api-admin-next-integration

Полная история интеграции с Admin Next для плагина Grav 2.0: эндпоинты API плюс собственный интерфейс админки.

Когда использовать:

  • При переносе плагина с классической админкой на Admin Next
  • При добавлении любого интерфейса Admin Next в плагин (боковая панель, меню, поля, страницы, виджеты, панели, отчёты)
  • При работе в user/plugins/<plugin>/admin-next/ или с обработчиками событий с префиксом onApi*

Что охватывает:

  • Все обработчики событий onApi* и их роли
  • Эндпоинты API (onApiRegisterRoutes)
  • Элементы боковой панели, кнопки меню/панели инструментов, плавающие виджеты
  • Страницы плагина (режимы схемы и компонента)
  • Настраиваемые типы полей
  • Настраиваемые отчёты
  • Изменения схем
  • Разрешения, языки и передачу конфигурации в веб-компоненты

grav-translations

Строки перевода в плагине Grav 2.0: languages/<lang>.yaml, languages.yaml и строки label/help/title в схемах.

Когда использовать:

  • При редактировании языковых YAML в плагине
  • При добавлении полей схемы со свойствами label:, help:, title:, text: или description:
  • При отладке отсутствующих или автоматически «очеловеченных» меток в Admin 2.0 (например, метка отображается как "Xss Security" вместо "XSS Security for Content")
  • При переносе языкового файла плагина Grav 1.7 для поддержки Admin 2.0
  • При аудите плагина или ядра на пробелы в переводах

Что охватывает:

  • Цепочку поиска ICU или плоских ключей как на клиенте Admin 2.0, так и на сервере плагина API
  • Канонические пространства имён ключей (общий словарь PLUGIN_ADMIN.* против приватного PLUGIN_<MYPLUGIN>.*)
  • Структуру языкового YAML для двух версий (Grav 1.7 + 2.0)
  • Рендеринг HTML в тексте справки
  • Фильтр отключённых плагинов, который не пускает устаревшие строки в Admin 2.0
  • Скрипт i18n-blueprint-audit.mjs для поиска пробелов

Установка навыков

Навыки распространяются как маркетплейс плагинов Claude Code. Внутри Claude Code выполните:

/plugin marketplace add getgrav/grav-skills

Это регистрирует репозиторий как маркетплейс навыков. Три навыка ниже сразу станут доступны, и Claude будет загружать их автоматически при совпадении триггеров (например, когда вы открываете файл в user/plugins/<plugin>/ или просите помочь с интеграцией API или Admin Next). Вы также можете вызвать навык явно по имени, например: «используй навык grav-api-admin-next-integration».

Чтобы позже удалить маркетплейс:

/plugin marketplace remove getgrav/grav-skills

Требования: код, который создают эти навыки, рассчитан на PHP 8.3+ и Grav 2.0 (или 2.0 RC в период релиз-кандидатов). Навыки повсюду предполагают современный стек.

Типичный процесс портирования

После установки Claude Code и регистрации маркетплейса grav-skills портирование существующего плагина выглядит примерно так:

  1. Откройте рабочую папку плагина в терминале.
  2. Запустите Claude Code: claude.
  3. Попросите агента примерно так:

    «Этот плагин сейчас поддерживает только Grav 1.7. Порти его для поддержки Grav 2.0: добавь флаг совместимости, перенеси интерфейс админки на Admin Next, открой его CRUD-операции как эндпоинты API и обнови языковые файлы для ICU.»

  4. Агент автоматически загрузит grav-api-admin-next-integration и grav-translations в зависимости от задачи. Он изучит существующий код плагина, предложит план и затем реализует его шаг за шагом.
  5. Проверяйте каждый diff по мере появления. Запустите плагин на установке Grav 2.0 (идеально подходит подготовленная установка из мастера миграции) и дорабатывайте всё, что работает неправильно.
  6. Когда всё заработает, добавьте '2.0' в флаг compatibility: в blueprints.yaml, повысьте версию и выпускайте.

Совет

Проверяйте diff. Вывод агента обычно правильный, но он не безошибочен. Цель — пропустить шаблонную работу, а не инженерные решения.

Где найти навыки

Официальные файлы навыков находятся на github.com/getgrav/grav-skills. Рекомендуемый способ установки — команда /plugin marketplace add getgrav/grav-skills, показанная выше; README в этом репозитории также описывает ручную установку и правила участия.

Подробности о самом формате Skills, включая то, как написать собственный навык, см. в документации Anthropic по Skills.

С вопросами о разработке для Grav 2.0 или о самих навыках быстрее всего обратиться к команде и сообществу в Discord Grav.

Чем эти навыки не являются

Эти навыки не заменяют справочную документацию по API, совместимости плагинов и переводам админки. Они подсказывают агенту, какие шаблоны применять и каких ошибок избегать; справочная документация — источник истины о том, какими эти шаблоны должны быть. Если вы выполняете портирование вручную, работайте по справочной документации. Если передаёте работу агенту, установите навыки, чтобы у агента был тот же контекст.