XenForo 2.3: Что нового в XenForo 2.3.10

На этой неделе мы планируем выпустить версию XenForo 2.3.10 с несколькими значительными дополнениями для разработчиков.

Инструменты управления фразами​

Уже много лет компания использовала внутренний инструмент, помогавший нам следить за использованием фраз при разработке новых функций. Этот инструмент сканирует кодовую базу на предмет строковых значений в шаблонах, которые потенциально требуют перевода в фразы, а также ищет определённые строки в PHP-коде, которые тоже можно преобразовать в фразы.

В версии XenForo 2.3.10 мы наконец доработали этот инструмент и превратили его в команды командной строки.

Фразировщик шаблонов и модификаций шаблонов​

Вот полное руководство по команде. Команда xf-dev:template-modification-phraser практически аналогична ей:

Описание:
  Анализирует и применяет замены фраз в шаблонах

Использование:
  xf-dev:template-phraser [опции]
  xf-dev:phraser-template

Опции:
      --addon=ADDON                  ID аддона для обработки
      --template=TEMPLATE            Шаблон в формате type:title
      --all                          Обработать все фразируемые шаблоны для аддона (по умолчанию, если не указан --template)
      --phrase-prefix=PHRASE-PREFIX  Префикс для генерируемых имён фраз
      --dry-run                      Только анализ и предпросмотр; без применения изменений
      --yes                          Пропустить запросы подтверждения
      --json                         Вывод в формате JSON
      --preview-lines=PREVIEW-LINES  Количество контекстных строк вокруг каждого изменения [по умолчанию: 2]
  -h, --help                         Показать справку для указанной команды
  -q, --quiet                        Не выводить сообщения
  -V, --version                      Показать версию приложения
      --ansi|--no-ansi               Принудительно включить/отключить ANSI-вывод
  -n, --no-interaction               Не задавать интерактивные вопросы
  -v|vv|vvv, --verbose               Повысить детализацию сообщений: 1 — обычный вывод, 2 — более подробный, 3 — отладочный

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



Вы получите список изменений шаблон за шаблоном (если не используете параметр --template), и сможете выбрать все, некоторые или ни одно из предложенных изменений для применения.

Если обнаружится фразируемый текст, который уже существует как фраза, вам предложат использовать именно её, например:



Иногда вам потребуется добавить ограничители при написании текста в шаблоне, чтобы явно определить начало и конец фразируемого текста. Это часто бывает необходимо, когда ваш текст занимает несколько строк или содержит HTML.

Например, если ваш шаблон содержит следующий фрагмент:

Edit note <b>{$note.title}</b>

И вы хотите убедиться, что вся эта строка правильно переведётся в фразу, оберните её следующим образом:

~~Edit note <b>{$note.title}</b>~~

Обратите внимание, что переменная интерполяция работает и в данном примере!

Фразировщик файлов​

Фразировщик файлов действует почти так же. Вот страница справки:

Описание:
  Анализирует и применяет замены фраз в PHP-файлах аддона

Использование:
  xf-dev:file-phraser [опции]
  xf-dev:phraser-file

Опции:
      --addon=ADDON                  ID аддона для обработки
      --file=FILE                    Путь к отдельному файлу относительно корня аддона
      --all                          Обработать все фразируемые файлы для аддона (по умолчанию, если не указан --file)
      --phrase-prefix=PHRASE-PREFIX  Префикс для генерируемых имён фраз
      --dry-run                      Только анализ и предпросмотр; без применения изменений
      --yes                          Пропустить запросы подтверждения
      --json                         Вывод в формате JSON
      --preview-lines=PREVIEW-LINES  Количество контекстных строк вокруг каждого изменения [по умолчанию: 2]
  -h, --help                         Показать справку для указанной команды
  -q, --quiet                        Не выводить сообщения
  -V, --version                      Показать версию приложения
      --ansi|--no-ansi               Принудительно включить/отключить ANSI-вывод
  -n, --no-interaction               Не задавать интерактивные вопросы
  -v|vv|vvv, --verbose               Повысить детализацию сообщений: 1 — обычный вывод, 2 — более подробный, 3 — отладочный

Основное отличие заключается в том, что фразируемый текст в файлах необходимо заключить в двойные тильды ~~ для преобразования в фразу:

Поиск неиспользуемых фраз​

Со временем вы можете накопить фразы в своём дополнении, которые станут ненужными после рефакторинга кода. Для этого случая тоже предусмотрена команда. Вот справка по ней:

Описание:
  Находит и при необходимости удаляет неиспользуемые мастер-фразы для аддона

Использование:
  xf-dev:unused-phrase-finder [опции]

Опции:
      --addon=ADDON     ID аддона для обработки
      --json            Вывод в формате JSON
      --show-unknown    Показать неизвестные использованные названия фраз в текстовом режиме
      --delete=DELETE   Разделённый запятыми список ID или названий фраз для удаления (только неиспользуемые)
      --delete-all      Удалить все текущие неиспользуемые фразы
      --yes             Пропустить запросы подтверждения
  -h, --help            Показать справку для указанной команды
  -q, --quiet           Не выводить сообщения
  -V, --version         Показать версию приложения
      --ansi|--no-ansi  Принудительно включить/отключить ANSI-вывод
  -n, --no-interaction  Не задавать интерактивные вопросы
  -v|vv|vvv, --verbose  Повысить детализацию сообщений: 1 — обычный вывод, 2 — более подробный, 3 — отладочный

Мы давно не запускали её в самой среде XenForo , однако если вы выполните её на собственном дополнении и передадите параметр --delete-all, вы сможете удалить не используемые фразы после подтверждения:

Установка навыков искусственного интеллекта для XenForo​

При работе с любым фреймворком, особенно коммерчески лицензированными, такими как XenForo, взаимодействие с искусственным интеллектом может быть… интересным. Хотя ситуация значительно улучшилась благодаря развитию агентов искусственного интеллекта, вероятность столкнуться с ошибочными представлениями или случайными ошибками всё ещё довольно высока.

Решение проблемы состоит в наличии подробной документации, которая сможет направлять агента искусственного интеллекта и служить точкой отсчёта для объяснения определённых паттернов, лучших практик, доступных команд и общих способов выполнения задач.

Безусловно, вы можете написать всю документацию самостоятельно. Вы можете создать файл CLAUDE.md (или AGENTS.md для всех остальных), который обеспечит чёткое направление действий. Вы также можете разработать собственные «навыки», чтобы помочь агенту выполнять конкретные задачи. Но начиная с XenForo 2.3.10 вам больше не придётся это делать

Мы разработали новую команду xf-dev:install-ai-agents, которая автоматически установит мощный набор инструкций для выбранного вами агента искусственного интеллекта и сохранит их в соответствующих местах. К сожалению, существуют разные соглашения относительно наименования файлов в зависимости от используемого инструмента, и данная команда учитывает это различие.

Description:
  Install AI agent convention files

Usage:
  xf-dev:install-ai-agents [options]

Options:
  -f, --force           Overwrite files if they already exist
      --with-claude     Install default files plus Claude-compatible files
      --only-claude     Install only Claude-compatible files
      --dry-run         Show which files would be written without making changes
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Запуск команды без параметров создаст файлы, совместимые с большинством моделей и агентов, отличных от Claude, например ChatGPT Codex или Open Code. Если вы работаете исключительно с моделью Claude, добавьте параметр --only-claude. Или, если вы переключаетесь между разными инструментами, воспользуйтесь опцией --with-claude.

Все агенты получают примерно одинаковые файлы, различия касаются лишь местоположения сохранения и наименований самих файлов. Например, по умолчанию вы получите файл AGENTS.md вместо файла CLAUDE.md.



Я не буду подробно останавливаться на всём содержимом этих файлов, но структура выглядит примерно так:

CLAUDE.md / AGENTS.md

Это краткий обзор фреймворка, включая расположение ключевых файлов и основные паттерны, о которых агент должен заранее знать. Затем объясняются ряд навыков и их предназначение, подробнее об этом ниже.

xf-shared-policy

Здесь изложены общие правила разработки, касающиеся обеих сторон процесса, включая разработку ядра и дополнений. Объясняются такие вещи, как система вывода результатов разработки, команды xf-make и общие принципы, помогающие агентам оставаться в рамках заданного курса.

xf-core-dev

Эта секция не особо актуальна для большинства пользователей, но представляет собой сборник полезных общепринятых соглашений для основной разработки, используемых командой XenForo.

xf-addon-dev

Здесь объясняется, как узнать правильный идентификатор дополнения, понимание нумерации версий, отказ от ручного редактирования XML-файлов и другие справочные материалы, непосредственно относящиеся к разработке дополнений.

xf-scaffold-make

Этот навык описывает использование команд xf-make более детально и даёт общее представление о рекомендациях касательно генерации артефактов разработки.

xf-template-phrase

Здесь описано, как работают шаблоны и фразы, включая краткую ссылку на семантику языка, применяемую в синтаксисе шаблонов XenForo.

Совокупно эти навыки делают работу с агентами искусственного интеллекта и XenForo гораздо стабильнее и предсказуемее. Однако помните, что результаты могут варьироваться, и иногда даже самый умный агент может ошибаться или сбиваться с пути. Я настоятельно рекомендую внимательно проверять каждую строку кода, написанного агентом, и понимать, что именно происходит!