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: Ä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 4: 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.