Escriure aplicacions (plugins)

Les aplicacions afegeixen funcions a Antimatter des de dins: una part de servidor en Go que s'acobla al servidor, i una part d'aplicació web en React que afegeix menús, panells, tipus de missatges i pàgines. Aquesta pàgina mostra com s'estructura una aplicació, utilitzant l'aplicació Enquestes integrada com a exemple, i què canvia a la interfície Fusion d'Antimatter.

Com funciona una aplicació

• La part de servidor és un programa en Go. El servidor l'executa com a procés independent i hi comunica mitjançant RPC: crida els hooks de l'aplicació (s'apunta a publicar un missatge, s'ha executat una comanda...) i l'aplicació crida l'API de plugins del servidor (crear una publicació, llegir un usuari, emmagatzemar dades...). També pot servir rutes HTTP sota /plugins/<app id>/.
• La part d'aplicació web és un paquet JavaScript que es carrega al navegador amb l'aplicació web. Registra components i callbacks de React al registre: un botó en un menú, un panell, una manera de dibuixar un tipus de missatge.
• Cada part és opcional. Una aplicació s'instal·la com a paquet .tar.gz, i els administradors del sistema l'activen, la desactiven i la configuren.

Antimatter executa aplicacions escrites per a Mattermost, i a l'inrevs, sempre que l'aplicació només utilitzi hooks que tinguin tots dos. Vegeu Hooks que només té Antimatter.

L'estructura del paquet

No hi ha cap plantilla inicial separada: comenceu amb una petita aplicació integrada com antimatter-plugin-polls o antimatter-plugin-todo, i canvieu-ne l'ID i el codi. Enquestes s'estructura així:

antimatter-plugin-polls/
├── plugin.json            the manifest
├── Makefile               build, test, bundle, deploy
├── build/                 the manifest and pluginctl helper tools (Go), setup.mk
├── assets/icon.svg        files shipped with the bundle
├── go.mod
├── server/
│   ├── main.go            plugin.ClientMain(&Plugin{})
│   ├── plugin.go          the Plugin type, OnActivate, ServeHTTP
│   ├── manifest.go        generated from plugin.json
│   ├── api.go, command.go, hooks.go, store.go …
│   └── dist/              compiled binaries, one per platform
└── webapp/
    ├── package.json, webpack.config.js, tsconfig.json
    ├── i18n/              en.json and one file per language
    ├── src/index.tsx      registers the app with the web app
    ├── src/manifest.ts    generated from plugin.json
    ├── src/translations.ts
    └── dist/main.js       the bundle

Opcional: una carpeta public/, servida tal qual a /plugins/<app id>/public/.

plugin.json

{
  "id": "com.example.weather",
  "name": "Weather",
  "description": "Forecasts in the chat.",
  "homepage_url": "https://github.com/example/weather",
  "support_url": "https://github.com/example/weather/issues",
  "icon_path": "assets/icon.svg",
  "version": "1.0.0",
  "min_server_version": "12.0.0",
  "server": {
    "executables": {
      "linux-amd64": "server/dist/plugin-linux-amd64",
      "linux-arm64": "server/dist/plugin-linux-arm64",
      "darwin-amd64": "server/dist/plugin-darwin-amd64",
      "darwin-arm64": "server/dist/plugin-darwin-arm64",
      "windows-amd64": "server/dist/plugin-windows-amd64.exe"
    }
  },
  "webapp": {"bundle_path": "webapp/dist/main.js"},
  "settings_schema": {"settings": []}
}

• id: únic i permanent; sol ser un nom de domini invers. Nomena les rutes, la configuració emmagatzemada i els esdeveniments WebSocket.
• version: versió semàntica. Les aplicacions integrades l'ometen de plugin.json; la seva eina de construcció la pren de l'etiqueta git v* més recent.
• min_server_version: Antimatter informa 12.0.0.
• settings_schema: la pàgina de configuració de l'aplicació al Consola del sistema (vegeu Configuració).

make apply copia el manifest a server/manifest.go i webapp/src/manifest.ts; make manifest-check el valida.

La part del servidor

La part del servidor importa el mateix mòdul Go que les aplicacions de Mattermost, github.com/mattermost/mattermost/server/public, des del proxy de mòduls Go. El seu main només inicia l'aplicació:

package main

import "github.com/mattermost/mattermost/server/public/plugin"

func main() {
	plugin.ClientMain(&Plugin{})
}

El tipus Plugin incorpora plugin.MattermostPlugin, que li proporciona p.API, i implementa els ganxos que necessita:

type Plugin struct {
	plugin.MattermostPlugin
	router *mux.Router
}

func (p *Plugin) OnActivate() error {
	p.router = p.newRouter()
	return p.API.RegisterCommand(&model.Command{
		Trigger:          "weather",
		AutoComplete:     true,
		AutoCompleteDesc: "Show the forecast",
		AutoCompleteHint: "[city]",
	})
}

func (p *Plugin) ExecuteCommand(c *plugin.Context, args *model.CommandArgs) (*model.CommandResponse, *model.AppError) {
	city := strings.TrimSpace(strings.TrimPrefix(args.Command, "/weather"))
	return &model.CommandResponse{
		ResponseType: model.CommandResponseTypeEphemeral,
		Text:         "Forecast for " + city + ": sunny",
	}, nil
}

func (p *Plugin) ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) {
	p.router.ServeHTTP(w, r)
}

Ganxos comuns

La llista completa, amb les signatures exactes, es troba a server/public/plugin/hooks.go; l'API és a server/public/plugin/api.go. El paquet pluginapi (server/public/pluginapi) envolta l'API amb ajudants més amigables.

Crides a l'API útils

• CreatePost, UpdatePost, SendEphemeralPost: publica com a bot de l'aplicació o com a usuari.
• EnsureBotUser(&model.Bot{Username, DisplayName}): crea el bot de l'aplicació una sola vegada i obté el seu ID.
• PublishWebSocketEvent("poll_updated", payload, &model.WebsocketBroadcast{ChannelId: id}): envia un esdeveniment a l'aplicació web. Arriba com custom_<app id>_poll_updated.
• OpenInteractiveDialog: obre un diàleg.
• LogInfo, LogError i altres: escriu al registre del servidor, etiquetat amb l'ID de l'aplicació.
• GetUser, GetChannel, HasPermissionToChannel: comprova qui pot fer què abans d'actuar en nom d'un usuari.

Una aplicació s'executa en cada servidor d'un clúster. Mantén l'estat a l'emmagatzematge de claus i valors o a la base de dades, no només a la memòria.

El servei d'IA

El servidor d'Antimatter crida models d'IA per a les aplicacions, a través de les connexions de models configurades per un administrador (vegeu IA a la guia d'administració). Una aplicació mai no guarda la clau d'un proveïdor: nomena la persona per la qual actua i on, i el servidor comprova que aquesta persona pot utilitzar la connexió allà, aplica els seus límits i pressupostos, compta els tokens en nom de la persona i de l'aplicació, i audita la crida sense el seu contingut.

El ConnectionID de cada sol·licitud tria la connexió, i Model un dels seus models (buit per al model predeterminat de la connexió). Operation és una etiqueta curta per als registres d'ús i d'auditoria, mai el contingut. La seva versió mínima de servidor és 11.11.

Aquests mètodes i el paquet ai (server/public/ai) existeixen només a la còpia del mòdul d'Antimatter, no a la versió publicada per Mattermost. Per utilitzar-los, compila contra server/public d'Antimatter amb una línia replace al teu go.mod, per exemple replace github.com/mattermost/mattermost/server/public => ../antimatter/server/public. Una aplicació d'aquest tipus només funciona a Antimatter.

Donar eines als agents

Una aplicació ofereix les seves pròpies eines als agents amb RegisterAITools([]*model.AIToolDefinition): el nom, el títol, la descripció, l'esquema JSON d'entrada i el tipus de cada eina (read, write o external_write), que determina si la política d'un agent pot executar-la per si sola (vegeu Eines a la guia d'administració). Els permisos es comproven en un argument de canal o comunitat de la crida, o al servidor, segons el que necessiti l'eina. Quan un agent utilitza l'eina, el servidor crida el ganxo ExecuteAITool(c, *model.AIToolExecution) *model.AIToolResult amb la persona verificada que ho ha sol·licitat a UserId: actua només amb els seus permisos, mai amb els de l'agent. Les eines s'anomenen <app id>.<name>; versió mínima del servidor 11.11; aquests mètodes i el ganxo només existeixen a server/public d'Antimatter, com el servei d'IA anterior. Una aplicació amb ID antimatter, o que comenci per mcp., no pot registrar eines.

Emmagatzemar dades

Cada aplicació té el seu propi emmagatzematge de claus i valors a la base de dades del servidor:

• KVSet(key, value), KVGet(key), KVDelete(key): els valors són bytes, normalment JSON. Les claus tenen com a màxim 150 caràcters.
• KVSetWithExpiry(key, value, seconds): el valor desapareix després d'aquest temps.
• KVCompareAndSet(key, old, new) i KVSetWithOptions amb Atomic: actualitzacions segures quan diverses sol·licituds o servidors escriuen la mateixa clau. Enquesta desa cada vot d'aquesta manera i torna a intentar-ho en cas de conflicte.
• KVList(page, perPage): les claus, pàgina per pàgina.

La part de l'aplicació web

El paquet registra una classe amb window.registerPlugin. El seu initialize rep el registre i l'emmagatzematge de Redux:

import manifest from './manifest';

class Plugin {
    initialize(registry, store) {
        registry.registerTranslations((locale) => translationsFor(locale));
        registry.registerPostTypeComponent('custom_poll', PollPost);
        registry.registerWebSocketEventHandler(`custom_${manifest.id}_poll_updated`, (msg) => {
            store.dispatch(pollUpdated(JSON.parse(msg.data.poll)));
        });
        registry.registerReconnectHandler(() => store.dispatch(reloadPolls()));
    }
}

window.registerPlugin(manifest.id, new Plugin());

• Biblioteques compartides. L'aplicació web proporciona React, ReactDOM, Redux, React Redux i React Intl: llista-les com a externals de webpack (React, ReactDOM, Redux, ReactRedux, ReactIntl) en lloc d'empaquetar còpies pròpies. Consulta webpack.config.js d'Enquesta.
• Crèdit a la part del servidor. Fes una sol·licitud a ${window.basename}/plugins/<app id>/… amb les opcions de Client4.getOptions() (de mattermost-redux/client): porten les capçaleres que el servidor necessita per acceptar una sol·licitud del navegador.
• El teu propi estat. registerReducer afegeix un reductor, emmagatzemat sota state['plugins-<app id>'].
• Tipus. Els mètodes addicionals del registre d'Antimatter no estan als tipus publicats de Mattermost: Enquesta declara el registre que utilitza a webapp/src/types/host.ts.

Els mètodes del registre i els seus paràmetres estan documentats al codi, a webapp/fusion/src/plugins/registry.ts (Fusion) i webapp/channels/src/plugins/registry.ts (clàssic).

Donar suport a la interfície Fusion

Antimatter té dues interfícies web: Fusion, la predeterminada, i la clàssica. Ambdues carreguen els mateixos paquets d'aplicacions i tenen el mateix registre, però Fusion dibuixa moltes coses per si mateixa i col·loca els components de les aplicacions a la seva manera. Prova la teva aplicació en ambdues.

Detectar la interfície

Abans que qualsevol aplicació es carregui, ambdues interfícies estableixen window.antimatterWebUI a 'fusion' o 'classic', i el mateix valor a l'element arrel de la pàgina com a data-am-web-ui. A Mattermost, cap dels dos s'estableix.

export function isFusionUI(): boolean {
    return window.antimatterWebUI === 'fusion' || document.documentElement.dataset.amWebUi === 'fusion';
}

Les aplicacions integrades l'utilitzen per dibuixar de manera diferent. Les enquestes dibuixen les seves targetes amb l'estil de Fusion, i a Fusion l'enquesta s'escriu al compositor (un mode de compositor) en lloc d'un diàleg. Les trucades i els canals de veu ometen la barra lateral i els components de notificació emergent que Fusion substitueix per la seva pròpia interfície de trucada. L'aplicació de xat d'IA posa les seves accions d'IA al menú del missatge, com un grup sota Més accions, en lloc de la barra d'eines en passar el ratolí. Les classes CSS pròpies de Fusion (amb el prefix am-) i la seva capa de diàlegs (l'element am-layer) són el que aquestes aplicacions utilitzen per adaptar-se a la interfície; no són una API documentada ni estable.

On Fusion mostra els components dels plugins

El que Fusion no mostra ni executa

• registerPostDropdownMenuComponent (un component al menú del missatge) i registerPostCardTypeComponent (la targeta d'un missatge al panell de la dreta) no es mostren a les vistes principals de Fusion. registerProductSwitcherMenuItem no fa res a Fusion, que no té menú de producte (registra un avís). Utilitzeu registerPostDropdownMenuAction en lloc del primer.
• registerMessageWillBeUpdatedHook no s'executa quan un missatge s'edita a Fusion. Comprova les edicions al servidor amb el hook MessageWillBeUpdated en lloc d'això.
• registerActionAfterChannelCreation només s'executa des del diàleg de creació de canal clàssic, que Fusion obre des de Més opcions… al seu diàleg Crea un canal.
• Els components de la barra d'aplicacions es mostren independentment del seu supportedProductIds.
• Les rutes de registerNeedsTeamRoute i registerCustomRoute mantenen el marc de pàgina clàssic, com els productes.

Hooks que només té Antimatter

Aquests mètodes de registre no existeixen a Mattermost. Comprova que un mètode existeix abans de cridar-lo, perquè l'aplicació també funcioni allà:

if (typeof registry.registerComposerMenuItem === 'function') {
    registry.registerComposerMenuItem({
        text: 'Create a poll',
        icon: <i className='icon icon-chart-bar'/>,
        fusionIcon: 'poll',
        action: ({channelId, rootId}) => openPollCreation(channelId, rootId),
    });
} else {
    registry.registerChannelHeaderButtonAction(icon, (channel) => openPollCreation(channel.id), 'Create a poll', 'Create a poll');
}

Afegeix i gestiona vistes al selector d'emoji

A Fusion, la pestanya del selector d'emoji rep una propietat pickerKit: els components que la pestanya Emoji utilitza per a les seves pròpies vistes d'addició i gestió, de manera que les vistes d'una pestanya tinguin l'aparença i es mantinguin dins del selector. Les aplicacions GIF i Memes l'utilitzen per afegir i gestionar GIF, adhesius i plantilles de memes. Conté version (1), els hooks usePickerView i useOnEscape, i els components PickerViewButtons (els botons + i de gestió al costat de la caixa de cerca), PickerViewFrame (una vista amb la seva fletxa enrere), PickerNotice, PickerField, PickerSearch, PickerDropZone i PickerManageList. La tecla Escape torna d'una vista a la graella de la pestanya. Assegureu-vos que la propietat hi és: altres amfitrions l'ometen, i en aquest cas la pestanya manté els seus propis diàlegs. Els tipus es troben a webapp/fusion/src/types/store/plugins.ts (EmojiPickerTabProps) i els components a webapp/fusion/src/fusion/popovers/picker_views.tsx.

Modes de compositor

A Fusion, registerComposerMode({id, label, fusionIcon, placeholder, sendLabel, component, shouldRender}) afegeix una altra manera d'escriure un missatge al redactor, com fa Polls per a una enquesta. El mode s'ofereix al menú + del redactor amb el seu label. Un cop seleccionat, el redactor manté la seva caixa de text (amb el placeholder del mode: la pregunta de l'enquesta), mostra el teu component a sota i una barra amb el nom del mode i un botó Cancel·la; Envia utilitza el sendLabel i executa el teu enviament en lloc de publicar el text.

• El component rep channelId, rootId (el fil, en una caixa de resposta), message (el text del redactor), setSubmit i onCancel (torna a un missatge normal, mantenint el text).
• Passa a setSubmit una funció que es crida amb el text del redactor i es resol a res (o una cadena buida) un cop enviat: el redactor s'esbuirra i torna a un missatge normal. Resol a una cadena per mostrar-la com un error al lloc.
• placeholder i sendLabel són cadenes o funcions de l'intl de react-intl. shouldRender(state, {channelId, rootId}) decideix si un redactor ofereix el mode.
• Per obrir el mode des d'un altre lloc, com ara una comanda amb barra sense arguments: window.dispatchEvent(new CustomEvent('am-composer-mode', {detail: {id, channelId, rootId}})).

Només Fusion té modes de redactor: comprova que el registre tingui la funció i, si no, mantingues el teu propi diàleg. El mètode retorna l'id del mode, i el mode desapareix quan es desinstal·la l'aplicació.

El panell en una finestra nova

Fusion passa al component registerRightHandSidebarComponent dues propietats més, de manera que Obre en una finestra nova obre el panell on era, en lloc de fer-ho a la pàgina inicial de l'aplicació:

• setPanelState(state): crideu-lo quan el panell canviï de lloc, amb una cadena curta que la vostra aplicació defineixi, com ara 'note/<id>' o 'board/<id>/card/<id>', o null a la seva pàgina d'inici. Aquesta informació s'incorpora a la direcció de la finestra, per tant, no hi introduïu mai cap secret. Un estat més llarg de 512 caràcters, o amb caràcters de control, es descarta.
• initialPanelState: a la finestra nova, l'estat que tenia el panell, o undefined. Tracteu-lo com a entrada no fiable: recupereu de nou l'element com a la persona iniciada sessió, i mostreu la pàgina d'inici de l'aplicació o una vista de no trobat si no pot obrir-lo.

L'estat s'oblida quan el panell es tanca o el panell d'una altra aplicació pren el seu lloc. Per obrir la finestra d'un panell per compte propi, popoutRhsPlugin (també a window.WebappUtils.popouts) pren l'estat com a cinquè argument opcional. Notes, Pissarra, Tasques pendents, Kanban i Guies d'actuació utilitzen això.

fusionIcon nomena un icona del conjunt d'icones de Fusion (per exemple poll, sticker, calendar o image; vegeu webapp/fusion/src/fusion/components/icon). Fusion la mostra en lloc de icon, de manera que l'element coincideix amb els altres.

Configuració

settings_schema a plugin.json descriu la pàgina de l'aplicació a Consola del sistema › Connectors:

"settings_schema": {
  "header": "Forecasts come from the weather service below.",
  "settings": [
    {"key": "ServiceURL", "display_name": "Service URL", "type": "text", "default": "https://api.example.com"},
    {"key": "Units", "display_name": "Units", "type": "dropdown", "default": "metric",
     "options": [{"display_name": "Celsius", "value": "metric"}, {"display_name": "Fahrenheit", "value": "imperial"}]},
    {"key": "EnableAlerts", "display_name": "Severe weather alerts", "type": "bool", "default": false,
     "help_text": "Post alerts in the channels that follow a city."}
  ]
}

Tipus de configuració: bool, text, longtext, number, dropdown, radio, generated (un secret aleatori), username i custom (dibuixat per un component que la part de l'aplicació web registra amb registerAdminConsoleCustomSetting). Les configuracions es poden agrupar en sections.

La part del servidor les llegeix en una estructura de dades (struct) els camps de la qual coincideixen amb les claus:

type configuration struct {
	ServiceURL   string
	Units        string
	EnableAlerts bool
}

func (p *Plugin) OnConfigurationChange() error {
	var cfg configuration
	if err := p.API.LoadPluginConfiguration(&cfg); err != nil {
		return err
	}
	p.setConfiguration(&cfg)
	return nil
}

Els administradors també poden establir-les a la configuració, sota PluginSettings.Plugins.<app id>, amb claus en minúscules (vegeu la guia d'administració).

Traduccions

Antimatter està traduït a 37 idiomes, i les aplicacions integrades també. La part de l'aplicació web ho fa d'aquesta manera:

1. Escriviu cada cadena amb React Intl, amb un ID i el seu text en anglès: <FormattedMessage id='polls.create' defaultMessage='Create a poll'/> o defineMessages. Prefixeu els ID amb el nom de la vostra aplicació.
2. Extraieu les cadenes en anglès a webapp/i18n/en.json (les aplicacions integrades utilitzen formatjs extract).
3. Afegiu un fitxer per idioma al costat, amb els mateixos ID: fr.json, de.json, pt-BR.json, zh-CN.json…
4. Passa-les a l'aplicació web, que demana l'idioma de l'usuari:

   import fr from '../i18n/fr.json';
   import ptBR from '../i18n/pt-BR.json';
   
   const catalogs = {fr, 'pt-BR': ptBR};
   
   export function translationsFor(locale) {
       return catalogs[locale] || catalogs[locale.split('-')[0]] || {};
   }
   
   registry.registerTranslations(translationsFor);

Si falta una cadena, s'utilitza el defaultMessage en anglès. Per a les cadenes que envia la part del servidor (respostes de comandes, missatges de bots), el paquet pluginapi/i18n carrega els fitxers de traducció inclosos al paquet (per exemple assets/i18n) i proporciona un localitzador en l'idioma de cada usuari.

Compila, instal·la i depura

Necessites Go i Node.js (la versió indicada al .nvmrc de l'aplicació). A la carpeta de l'aplicació:

make deploy i les altres comandes del servidor utilitzen un socket de mode local si n'hi ha un (/var/tmp/antimatter_local.socket, o AM_LOCALSOCKETPATH): executa-les a la màquina del servidor amb el mode local activat. En cas contrari, s'hi autenticen al servidor indicat per MM_SERVICESETTINGS_SITEURL amb AM_ADMIN_TOKEN, o amb AM_ADMIN_USERNAME i AM_ADMIN_PASSWORD. Les eines de compilació encara no llegeixen un nom AM_ per a l'URL del lloc.

Instal·la un paquet manualment

• Un administrador del sistema permet les pujades amb AM_PLUGINSETTINGS_ENABLEUPLOADS=true (desactivat per defecte; no hi ha un interruptor a la Consola del sistema).
• Després, Consola del sistema › Connectors › Gestió de plugins › Carrega un plugin, o amctl plugin add weather.tar.gz seguit de amctl plugin enable com.example.weather.
• Si el servidor té activada l'opció Requerix la signatura del complement, només accepta paquets signats amb una clau de confiança; consulta Instal·lació d'altres aplicacions.