Add-On-Authoring-Guide

Add-On-Authoring-Guide

Dieses Guide erklärt, wie Sie ein Vorlagen-Add-On-Pack für den satware(r) AI OnlyOffice MCP Server erstellen, verpacken und versenden.

Schnellstart

Ein Kunden-Image erweitert das Basis-Image und führt das Add-On zur Build-Zeit zusammen:

FROM satware/onlyoffice-mcp:1.3.0-base AS base
COPY ./my-addon/ /tmp/addon/
RUN node dist/scripts/bake-addon.js /tmp/addon

Ihr Add-On-Verzeichnis benötigt ein addon.json-Manifest und optionale templates/, assets/ und fonts/ Unterverzeichnisse.

Manifest-Referenz

Die addon.json-Datei befindet sich im Wurzelverzeichnis Ihres Add-On-Verzeichnisses:

{
  "$schema": "./addon.schema.json",
  "id": "worms",
  "version": "1.0.0",
  "minBaseVersion": "1.3.0",
  "label": "Stadt Worms Template Pack",
  "description": "Corporate templates for Stadt Worms municipal administration",
  "priority": 10,
  "suppressedIds": ["beschlussvorlage"],
  "languages": ["de"]
}

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Kleinbuchstaben-ASCII-Slug. Eindeutig über alle geladenen Add-Ons.
version	string	Ja	Semver-Version dieses Add-On-Packs.
minBaseVersion	string	Ja	Mindest-Basis-Image-Version (X.Y.Z).
label	string	Ja	Mensch-lesbarer Anzeigename.
description	string	Nein	Längere Beschreibung.
priority	number	Nein	Merge-Reihenfolge (Standard: 10). Höhere gewinnt bei ID-Kollision.
suppressedIds	string[]	Nein	Basis-Vorlagen-IDs zum Ausblenden.
languages	string[]	Nein	BCP-47-Sprachcodes (z.B. ["de"]).

Schema-Validierung

Die addon.schema.json-Datei dient nur der IDE-Validierung. Die Laufzeit-Validierung ist strukturell (keine Ajv-Abhängigkeit) - passend zum TemplateLoader-Muster.

Verzeichnislayout

my-addon/
  addon.json
  templates/
    registry.json
    my_template/
      v1.0/
        template.docbuilder
        schema.json
  assets/
    my_category/
      logo.base64
  fonts/
    montserrat-regular.ttf

Unterdrückung

suppressedIds verbirgt Basis-Vorlagen, die Ihr Add-On ersetzt:

• Soft-Deaktivierung: Dateien bleiben auf der Festplatte, nur aus der API ausgeblendet
• Absolut: nach Override angewendet (selbst Add-On-bereitgestellte IDs werden entfernt)
• Idempotent: unbekannte IDs erzeugen eine Warnung, keinen Fehler

Override nach ID

Eine Add-On-Vorlage mit derselben ID gewinnt gegen die Basis. Auflösung: höhere priority gewinnt; bei Gleichstand gewinnt Add-On gegen Basis.

Schriftarten-Verpackung

• Formate: TTF, OTF, WOFF
• Installationspfad: /usr/share/fonts/truetype/addons/
• Lizenzierung: Sie sind verantwortlich für die Einhaltung der Schriftarten-Lizenz

Versionierung

• minBaseVersion muss einfaches X.Y.Z sein (keine Pre-Release-Suffixe)
• Vergleich verwendet Semver-Regeln
• Nichtübereinstimmung = Add-On abgelehnt; Server fährt nur mit Basis fort
• Basis-Image-Tags sind unveränderlich - niemals retaggen

Tests

Verwenden Sie das vorgelagerte tests/fixtures/synthetic-addon/ als Referenz-Fixture. Testen Sie den Merge lokal:

node dist/scripts/bake-addon.js ./my-addon --templates-dir ./templates --output /tmp/baked
cat /tmp/baked/registry.json | jq '.templates | keys'

Migration von Spec 003

1. addon.json-Manifest erstellen
2. minBaseVersion auf Ihre aktuelle Basis-Version setzen
3. Vorlagen nach templates/, Assets nach assets/, Schriftarten nach fonts/ verschieben
4. suppressedIds für ersetzte Basis-Vorlagen hinzufügen
5. Lokal mit bake-addon testen
6. Dockerfile auf FROM base + COPY + RUN bake-addon umstellen