AntimatterРазработка на Antimatter
Это руководство предназначено для разработчиков. В нём описаны скрипты и боты, использующие API, интеграции на основе вебхуков и команд с косой чертой, приложения (плагины), добавляющие функции на сервер и в веб-приложение, а также сборка Antimatter из исходного кода для участия в его разработке.
Способы расширения Antimatter
Выберите самый простой инструмент, подходящий для задачи. Первые четыре не требуют доступа к самому серверу; приложения работают внутри него.
| Инструмент | Назначение | Подходит для |
|---|---|---|
| REST API | Всё, что делают приложения: сообщения, каналы, пользователи, файлы, параметры. WebSocket отправляет события по мере их возникновения. | Скрипты, синхронизация с другими системами, собственные клиенты. |
| Входящие вебхуки | Секретный URL, который публикует сообщение в канал, когда что-то отправляет ему JSON. | Оповещения, результаты CI, мониторинг, уведомления из других инструментов. |
| Исходящие вебхуки | Antimatter обращается к вашему URL, когда сообщение в публичном канале начинается с триггерного слова, или когда кто-то выбирает ваше действие в меню сообщения, и публикует ваш ответ. | Простые автоматизации, управляемые чатом, отправка сообщений в другие инструменты. |
| Команды с косой чертой | Люди вводят /something; Antimatter обращается к вашему URL и показывает ваш ответ им или в канал. | Поиск информации, действия, запускаемые из чата. |
| Боты | Аккаунты, созданные для программ, с собственными токенами, меткой БОТ, интерактивными сообщениями и диалогами. | Ассистенты, системы уведомлений, всё, что взаимодействует с людьми. |
| Приложения (плагины) | Код, работающий внутри сервера (Go) и в веб-приложении (React): хуки для каждого сообщения, новые меню, панели, типы сообщений, страницы. | Функции: опросы, заметки, календари, интеграции, требующие пользовательского интерфейса. |
В интерфейсе пользователи называют плагины «приложениями». В этом руководстве используется формулировка «приложения (плагины)», когда оба термина уместны, поскольку в коде, API и конфигурации по-прежнему используется слово «plugin».
Совместимость с Mattermost
Antimatter является форком Mattermost. Большинство функций, работающих с сервером Mattermost, также работают с Antimatter.
Что совпадает
- REST API по адресу
/api/v4, его аутентификация, WebSocket и формат ошибок. Сервер сообщает версию12.0.0, поэтому клиенты и приложения, проверяющие версию сервера, видят актуальную версию Mattermost. - Вебхуки и команды с косой чертой, включая их совместимые с Slack данные.
- API и хуки серверных плагинов: Antimatter сохраняет их без изменений. Серверный код компилируется с тем же Go-модулем
github.com/mattermost/mattermost/server/public. Antimatter добавляет только методы для своего ИИ-сервиса (см. ИИ-сервис). - Реестр плагинов веб-приложения: все методы
register…реестра Mattermost присутствуют в обоих веб-интерфейсах Antimatter. - Клиентские библиотеки: Go-клиент
model.Client4и TypeScript-клиент@mattermost/client(см. Клиентские библиотеки). - Пакеты плагинов: файл
.tar.gzс манифестомplugin.json. Устанавливаются плагины, подписанные ключом Mattermost, а также те, что подписаны ключом Antimatter.
Чем отличается
- Два веб-интерфейса. Новый интерфейс Fusion является основным; классический интерфейс Mattermost по-прежнему доступен. Fusion отображает большинство компонентов плагинов, но размещает некоторые из них иначе и не показывает несколько других. Приложение может определить, какой интерфейс запущен. См. Поддержка интерфейса Fusion.
- Дополнительный API. Antimatter добавляет конечные точки для собственных функций: атрибуты сообщества, тайм-ауты, сообщения сверху, запросы сообщений, переопределения каналов и категорий, экспорт каналов, перемещение обсуждений, соединения моделей, действия с сообщениями и новые поля для сообществ. См. Что Antimatter добавляет в API.
- Дополнительные возможности сообщений. Вложения сообщений могут отображать этапы конвейера и небольшую диаграмму; сообщения могут быть встроенными ответами или спойлерами.
- Дополнительные хуки веб-приложения для приложений: пункт меню «+» в композере, вкладки в пикере эмодзи, панель в представлении канала, нижняя часть под каналами в боковой панели, запись на страницах интеграций, представления добавления и управления в пикере эмодзи, а также боковая панель, которая открывается там же, где она была, в новом окне. См. Хуки, которые есть только в Antimatter.
- Лицензии отсутствуют. Все функции доступны без лицензионного ключа. Эндпоинты для лицензий, пробных версий и корпоративных обновлений удалены;
GET /api/v4/license/clientсохранён для клиентов, которые его запрашивают. Некоторые приложения, созданные для платных версий Mattermost, самостоятельно проверяют наличие лицензии и отказываются работать. - Названия. В интерфейсе команды называются сообществами, но в API и коде по-прежнему используется термин
team. Переменные окружения используют префиксAM_, командная утилита называетсяamctl, а исполняемый файл сервера —antimatter.
Где находится код
Весь код открыт и размещён в организации AntimatterChat на GitHub. Все репозитории работают на ветке main.
| Репозиторий | Содержимое |
|---|---|
| antimatter | Сервер (на Go, в каталоге server/), оба веб-интерфейса (webapp/fusion и webapp/channels), клиент на TypeScript и утилита amctl. |
| antimatter-docker | Образы Docker с встроенными приложениями и файлы compose. |
antimatter-plugin-* | По одному репозиторию на каждое встроенное приложение: polls, todo, notes, whiteboard, calendar, mail, gifs, memes, voice-channels, calls, boards (Kanban), playbooks, agents и metrics. |
| gifs-server | Самостоятельно хостингуемый сервис GIF и стикеров, используемый приложением GIFs. |
| desktop-app, mobile-app, push-proxy | Десктопные и мобильные приложения, а также служба, передающая push-уведомления на телефоны. |
| antimatter.chat | Этот сайт и его документация. |
| community | Проблемы и обсуждения по всем компонентам Antimatter. |
Перед началом
- Получите тестовый сервер. Самый быстрый способ — Docker-образ: см. Установка Antimatter. Чтобы работать с самим Antimatter, см. Сборка из исходного кода.
- Узнайте, что разрешает сервер. Некоторые функции интеграции отключены по умолчанию и требуют администратора системы: личные токены доступа, аккаунты ботов, переопределение имени пользователя и значка, а также загрузка приложений. На каждой странице указано, какой параметр для этого нужен.
- Знайте URL вашего сайта. В примерах используется
https://chat.example.com. Замените его на адрес вашего сервера.
В этом руководстве
- REST API: аутентификация, основные ресурсы, постраничная навигация, ошибки, ограничения частоты запросов, WebSocket, клиентские библиотеки и расширения Antimatter.
- Вебхуки: входящие и исходящие вебхуки, полезная нагрузка, вложения и карточки.
- Команды с косой чертой: пользовательские команды, их запросы и ответы, автодополнение.
- Боты и интерактивные сообщения: аккаунты ботов, кнопки, меню и диалоги.
- Создание приложений: структура плагина, серверные хуки, реестр веб-приложений, Fusion, параметры, хранилище, переводы и упаковка.
- Сборка из исходного кода: сервер, веб-интерфейсы, Docker-образ и приложения.
- Вклад в проект: проблемы, pull request'ы, стиль, переводы, безопасность и лицензии.
Вопросы приветствуются в обсуждениях сообщества. Сообщайте об ошибках в проблемах сообщества.