Wie man dem ONLYOFFICE KI-Plugin benutzerdefinierte Funktionen hinzufügt

Das ONLYOFFICE KI-Plugin bietet eine neue, entwicklerfreundliche Architektur. Um die Funktionen des Plugins zu erweitern, beispielsweise um eine bestimmte KI-Funktion hinzuzufügen, müssen Sie keine umfangreiche, monolithische Datei mehr bearbeiten.

Stattdessen verfügt das Plugin nun über einen eigenen Arbeitsbereich im Ordner .dev. Diese Anleitung zeigt Ihnen, wie Sie diesen Arbeitsbereich nutzen, um eine neue benutzerdefinierte Funktion hinzuzufügen.

Als Beispiel entwickeln wir die Funktion Describe image (“Bild beschreiben”) für den Dokumenteneditor.

Der Entwicklungsablauf

Das Grundkonzept ist einfach: Sie arbeiten im .dev-Verzeichnis, und ein Skript erstellt den Produktionscode.

• .dev/helpers/: Dies ist Ihre Testumgebung. Hier erstellen Sie neue Dateien.
• helpers.js: Dies ist die Produktionsdatei, die das Plugin tatsächlich verwendet. Bearbeiten Sie diese Datei nicht direkt. Sie wird automatisch generiert.

Schritt 1: Editorbereich wählen

Im Verzeichnis .dev/helpers/ finden Sie drei Ordner, die den ONLYOFFICE-Editoren entsprechen:

• word/ (Dokumenteneditor)
• cell/ (Tabellenkalkulationseditor)
• slide/ (Präsentationseditor)

Da unsere Funktion zum Beschreiben von Bildern für Textdokumente gedacht ist, arbeiten wir im Ordner .dev/helpers/word/.

Schritt 2: Eigene Funktion erstellen

Erstellen Sie eine neue Datei namens describe-image.js im Verzeichnis .dev/helpers/word/.

Das Plugin verwendet eine spezielle Klasse namens RegisteredFunction, um die Fähigkeiten der Funktion zu definieren. Diese Struktur teilt der KI mit, was die Funktion bewirkt und wie sie aufgerufen wird.

Tipp: Achten Sie auf eine korrekte Syntax (vermeiden Sie fehlende schließende Klammern).

Der Code:

(function () {
  let func = new RegisteredFunction({
    name: "describeImage",
    description:
      "Allows users to select an image and generate a meaningful title, description, caption, or alt text for it using AI.",
    // Define parameters so the AI knows what to ask for
    parameters: {
      type: "object",
      properties: {
        prompt: {
          type: "string",
          description:
            "instruction for the AI (e.g., 'Add a short title for this chart.')",
        },
      },
      required: ["prompt"],
    },
    // Provide examples to train the AI on usage
    examples: [
      {
        prompt: "Add a short title for this chart.",
        arguments: { prompt: "Add a short title for this chart." },
      },
      {
        prompt: "Write me a 1–2 sentence description of this photo.",
        arguments: {
          prompt: "Write me a 1–2 sentence description of this photo.",
        },
      },
      {
        prompt: "Generate a descriptive caption for this organizational chart.",
        arguments: {
          prompt:
            "Generate a descriptive caption for this organizational chart.",
        },
      },
      {
        prompt: "Provide accessibility-friendly alt text for this infographic.",
        arguments: {
          prompt:
            "Provide accessibility-friendly alt text for this infographic.",
        },
      },
    ],
  });

   // The actual logic executed inside the editor
  func.call = async function (params) {
    let prompt = params.prompt;

    async function insertMessage(message) {
      Asc.scope._message = String(message || "");
      // 3. Insert the result into the document
      await Asc.Editor.callCommand(function () {
        const msg = Asc.scope._message || "";
        const doc = Api.GetDocument();
        const selected =
          (doc.GetSelectedDrawings && doc.GetSelectedDrawings()) || [];
        if (selected.length > 0) {
          for (let i = 0; i < selected.length; i++) {
            const drawing = selected[i];
            const para = Api.CreateParagraph();
            para.AddText(msg);
            drawing.InsertParagraph(para, "after", true);
          }
        } else {
          const para = Api.CreateParagraph();
          para.AddText(msg);
          let range = doc.GetCurrentParagraph();
          range.InsertParagraph(para, "after", true);
        }
        Asc.scope._message = "";
      }, true);
    }

    try {
    // 1. Get the selected image
      let imageData = await new Promise((resolve) => {
        window.Asc.plugin.executeMethod(
          "GetImageDataFromSelection",
          [],
          function (result) {
            resolve(result);
          }
        );
      });

      if (!imageData || !imageData.src) {
        await insertMessage("Please select a valid image first.");
        return;
      }

      const whiteRectangleBase64 =
        "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
      if (imageData.src === whiteRectangleBase64) {
        await insertMessage("Please select a valid image first.");
        return;
      }

      let argPrompt = prompt + " (for the selected image)";
      // 2. Send image + prompt to the AI engine
      let requestEngine = AI.Request.create(AI.ActionType.Chat);
      if (!requestEngine) {
        await insertMessage("AI request engine not available.");
        return;
      }

      const allowVision = /(vision|gemini|gpt-4o|gpt-4v|gpt-4-vision)/i;
      if (!allowVision.test(requestEngine.modelUI.name)) {
        await insertMessage(
          "⚠ This model may not support images. Please choose a vision-capable model (e.g. GPT-4V, Gemini, etc.)."
        );
        return;
      }

      await Asc.Editor.callMethod("StartAction", [
        "Block",
        "AI (" + requestEngine.modelUI.name + ")",
      ]);
      await Asc.Editor.callMethod("StartAction", ["GroupActions"]);

      let messages = [
        {
          role: "user",
          content: [
            { type: "text", text: argPrompt },
            {
              type: "image_url",
              image_url: { url: imageData.src, detail: "high" },
            },
          ],
        },
      ];

      let resultText = "";
      await requestEngine.chatRequest(messages, false, async function (data) {
        if (data) {
          resultText += data;
        }
      });

      await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
      await Asc.Editor.callMethod("EndAction", [
        "Block",
        "AI (" + requestEngine.modelUI.name + ")",
      ]);

      Asc.scope.text = resultText || "";

      if (!Asc.scope.text.trim()) {
        await insertMessage(
          "⚠ AI request failed (maybe the model cannot handle images)."
        );
        return;
      }
      await insertMessage(Asc.scope.text);
    } catch (e) {
      try {
        await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
        await Asc.Editor.callMethod("EndAction", [
          "Block",
          "AI (describeImage)",
        ]);
      } catch (ee) {
        /* ignore */
      }
      console.error("describeImage error:", e);
      await insertMessage(
        "An unexpected error occurred while describing the image."
      );
    }
  };

  return func;
})();

Schritt 3: Plugin-Version aktualisieren

Vor dem Kompilieren und Testen Ihrer Änderungen empfiehlt es sich, die Plugin-Version zu erhöhen. Dadurch wird sichergestellt, dass ONLYOFFICE Ihren Build als neues Plugin behandelt, Caching-Probleme werden vermieden und Änderungen können im Laufe der Zeit nachverfolgt werden.

Öffnen Sie die Datei config.json in Ihrem Plugin-Ordner.

Erhöhen Sie die Version um eine Patch-Stufe, zum Beispiel:

<code class="language-javascript">"version": "3.0.0" to "3.1.0"</code>

Dies wird sowohl für Desktop- als auch für Web-Editoren empfohlen.

Desktop: Stellt sicher, dass die Anwendung das aktualisierte Plugin neu lädt.

Web (einschließlich benutzerdefinierter Store-Links): Verhindert, dass das Caching Ihre Änderungen in helpers.js ignoriert.

Schritt 4: Änderungen kompilieren

Dies ist der wichtigste Schritt im neuen Workflow. Das Plugin kann Ihre neue Datei noch nicht direkt lesen. Sie müssen das Hilfsskript ausführen, um Ihre neue Datei in die Hauptlogik des Plugins zu integrieren.

1. Öffnen Sie Ihr Terminal.

2. Navigieren Sie zum Verzeichnis „helpers“.

cd .dev/helpers

3. Führen Sie das Python-Build-Skript aus.

python3 helpers.py

Das Skript „helpers.py“ durchsucht die Ordner word/, cell/ und slide/, findet Ihre neue Datei „describe-image.js“ und fügt sie in die Hauptdatei „helpers.js“ ein.

Schritt 5: Erstellen der .plugin-Datei

• Markieren Sie den gesamten Plugin-Inhalt.
• Komprimieren Sie ihn in eine ZIP-Datei.
• Benennen Sie das Archiv von .zip in .plugin um.
• Legen Sie es in einen Ordner namens „deploy“ innerhalb Ihres Plugin-Verzeichnisses.

Schritt 6: Plugin in ONLYOFFICE ersetzen

Desktop Editors

In neueren Versionen von ONLYOFFICE Desktop Editors ist das KI-Plugin standardmäßig enthalten. Wenn Sie eine ältere Version verwenden, in der das Plugin noch nicht enthalten war, hängt die Installation von Ihrer Situation ab und kann auf zwei Arten erfolgen:

A) Erstinstallation des KI-Plugins

Falls das KI-Plugin in Ihrem lokalen Plugin-Verzeichnis fehlt:

1. Öffnen Sie ONLYOFFICE Desktop Editors.
2. Gehen Sie zu Plugins → Plugin-Manager → Verfügbare Plugins → Plugin manuell installieren.
3. Wählen Sie bei der Aufforderung zur Dateiauswahl Ihre kompilierte .plugin-Datei aus.

B) Aktualisieren einer vorhandenen lokalen Kopie des KI-Plugins

Falls das Plugin bereits auf Ihrem System vorhanden ist:

1. Gehen Sie zu ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins
2. Suchen Sie den Ordner, dessen Name mit der Plugin-GUID aus der Datei config.json übereinstimmt – {9DC93CDB-B576-4F0C-B55E-FCC9C48DD007}
3. Ersetzen Sie den Ordner durch Ihr neu erstelltes Plugin.
4. Starten Sie die Desktop-Anwendung neu.

Web-Editor (über benutzerdefinierten Store-Link)

Benutzerdefinierter Store-Link

Aktivieren Sie GitHub Pages für Ihren Fork.

Erhöhen Sie die Versionsnummer in der config.json, um Caching-Probleme zu vermeiden.

1. Forken Sie das ONLYOFFICE Plugin Marketplace-Repository. Sie erhalten eine Kopie unter:
   https://github.com/YOUR-USERNAME/ONLYOFFICE/onlyoffice.github.io
2. Stellen Sie sicher, dass Ihr Plugin-Ordner einen Deploy-Ordner mit der .plugin-Datei enthält.
3. Fügen Sie Ihren Plugin-Ordner hier hinzu:
   onlyoffice.github.io/sdkjs-plugins/content/ai/
4. Erstellen Sie Ihre GitHub Pages-Website aus diesem Repository (GitHub Pages-Dokumentation).
5. Verknüpfen Sie Ihren benutzerdefinierten Shop mit /store/index.html, indem Sie die URL Ihrer GitHub Pages-Website wie folgt anhängen:
   https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html
6. Erhöhen Sie die Plugin-Version in der Datei config.json (wie in Schritt 3 beschrieben), um das Caching zu umgehen.

Plugin aktualisieren

Bevor Sie Ihre benutzerdefinierte Version installieren, müssen Sie je nach Ihrer Konfiguration möglicherweise die vorinstallierte Version entfernen.

• Prüfen Sie, ob das KI-Plugin bereits installiert ist.

Öffnen Sie den Web-Editor und gehen Sie zu Plugins → Plugin-Manager.

Falls das KI-Plugin installiert ist, entfernen Sie es.

Falls es nicht installiert ist, fahren Sie mit dem nächsten Schritt fort.

Dadurch wird sichergestellt, dass die benutzerdefinierte Version ohne Konflikte installiert oder aktualisiert werden kann.

• Fügen Sie Ihren benutzerdefinierten Store hinzu

Klicken Sie dazu auf das Store-Symbol oben rechts im Plugin-Manager.

Geben Sie Ihre benutzerdefinierte URL ein:

https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html

Ihr benutzerdefinierter Store wird nun im Plugin-Manager angezeigt.

• Installieren Sie das KI-Plugin

Sobald Ihr benutzerdefinierter Store geladen ist, suchen Sie in der Liste nach „KI-Assistent“ und klicken Sie auf „Installieren“.

Schritt 7: Funktion testen

1. Laden Sie das Plugin in ONLYOFFICE neu.
2. Wählen Sie ein Bild in Ihrem Dokument aus.
3. Fragen Sie die KI: „Beschreiben Sie dieses Bild“ oder „Schreiben Sie eine Bildunterschrift“.

Die KI erkennt nun Ihre neue benutzerdefinierte Funktion und führt die von Ihnen erstellte Logik aus.