AntimatterРозробка на базі Antimatter
Цей посібник призначений для розробників. Він охоплює скрипти та боти, що використовують API, інтеграції на основі вебхуків і команд зі скісною рискою, додатки (плагіни), які додають функції на сервері та у вебдодатку, а також збирання Antimatter з початкового коду для внесків у проєкт.
Способи розширення Antimatter
Оберіть найпростіший інструмент, який виконає завдання. Перші чотири не потребують доступу до самого сервера; додатки працюють усередині нього.
| Інструмент | Призначення | Підходить для |
|---|---|---|
| REST API | Усе, що роблять додатки: повідомлення, канали, користувачі, файли, налаштування. WebSocket надсилає події в момент їх виникнення. | Скрипти, синхронізацію з іншими системами, власні клієнти. |
| Вхідні вебхуки | Секретний URL, який надсилає повідомлення в канал, коли щось надсилає йому JSON. | Сповіщення, результати CI, моніторинг, сповіщення з інших інструментів. |
| Вихідні вебхуки | Antimatter надсилає запит до вашого URL, коли повідомлення у відкритому каналі починається з тригерного слова, або коли хтось обирає вашу дію в меню повідомлення, і публікує вашу відповідь. | Прості автоматизації, що керуються чатом, для надсилання повідомлення в інший інструмент. |
| Команди зі скісною рискою | Користувачі вводять /something; Antimatter викликає ваш URL і показує вашу відповідь їм або каналу. | Пошуки, дії, що ініціюються з чату. |
| Боти | Акаунти, створені для програм, з власними токенами, міткою БОТ, інтерактивними повідомленнями та діалогами. | Асистенти, сповіщувачі, усе, що спілкується з людьми. |
| Додатки (плагіни) | Код, що працює усередині сервера (Go) та у вебдодатку (React): гачки на кожне повідомлення, нові меню, панелі, типи повідомлень, сторінки. | Функції: опитування, нотатки, календарі, інтеграції, що потребують інтерфейсу користувача. |
У інтерфейсі користувачі називають плагіни «додатками». У цьому посібнику ми пишемо «додатки (плагіни)», коли обидва слова допомагають, оскільки код, API та конфігурація досі використовують слово «плагін».
Сумісність із 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 лише додає методи для своєї AI-служби (див. AI-служба). - Реєстр плагінів веб-додатку: усі методи
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 | Десктопні та мобільні додатки, а також сервіс, що передає сповіщення на смартфони. |
| antimatter.chat | Цей вебсайт та його документація. |
| community | Проблеми та обговорення для всіх частин Antimatter. |
Перед початком
- Отримайте тестовий сервер. Найшвидший спосіб — образ Docker: див. Встановлення Antimatter. Щоб працювати з самим Antimatter, див. Збирання з початкових кодів.
- Перевірте, що дозволяє сервер. Кілька функцій інтеграції вимкнено за замовчуванням і потребують системного адміністратора: особисті токени доступу, акаунти ботів, заміна імен користувачів та іконок, завантаження додатків. На кожній сторінці вказано, яке налаштування потрібне.
- Знайте URL вашого сайту. У прикладах використано
https://chat.example.com. Замініть його на адресу вашого сервера.
У цьому посібнику
- REST API: аутентифікація, основні ресурси, пагінація, помилки, обмеження частоти, WebSocket, клієнтські бібліотеки та доповнення Antimatter.
- Вебхуки: вхідні та вихідні вебхуки, навантаження, вкладення та картки.
- Команди зі скісною рискою: власні команди, їхні запити та відповіді, автозаповнення.
- Боти та інтерактивні повідомлення: акаунти ботів, кнопки, меню та діалоги.
- Написання додатків: структура плагіна, серверні гачки, реєстр вебдодатків, Fusion, налаштування, сховище, переклади та пакування.
- Збирання з початкових кодів: сервер, вебінтерфейси, образ Docker та додатки.
- Внесок: проблеми, pull requests, стиль, переклади, безпека та ліцензії.
Питання вітаються в спільноті. Повідомляйте про вади в списку проблем спільноти.