Cómo añadir funciones personalizadas al plugin de IA de ONLYOFFICE

El plugin de IA de ONLYOFFICE ha introducido una nueva arquitectura orientada al desarrollo. Si deseas ampliar las capacidades del plugin, por ejemplo, para añadir una función específica de IA, ya no necesitas editar un archivo monolítico y enorme.

En su lugar, el plugin ahora incluye un espacio de trabajo dedicado ubicado en la carpeta .dev. Esta guía te mostrará exactamente cómo usar este espacio para añadir una nueva función personalizada.

Usaremos como ejemplo la función Describir imagen para el Editor de documentos.

Flujo de trabajo de desarrollo

El concepto central es sencillo: Trabajas dentro de .dev, y un script genera el código de producción.

• .dev/helpers/: Este es tu entorno de pruebas. Aquí es donde creas nuevos archivos.
• helpers.js: Este es el archivo de producción que el plugin realmente utiliza. No lo edites directamente; se genera automáticamente.

Paso 1: Elige el alcance del editor

Dentro de .dev/helpers/ encontrarás tres carpetas correspondientes a los editores ONLYOFFICE:

• word/ (Editor de documentos)
• cell/ (Editor de hojas de cálculo)
• slide/ (Editor de presentaciones)

Como nuestra función para describir imágenes está diseñada para documentos de texto, trabajaremos en .dev/helpers/word/.

Paso 2: Crea tu propia función

Crea un nuevo archivo llamado describe-image.js dentro de .dev/helpers/word/.

El plugin utiliza una clase específica llamada RegisteredFunction para definir capacidades. Esta estructura le indica a la IA qué hace la función y cómo debe llamarla.

Consejo: Asegúrate de que tu sintaxis sea correcta (cuidado con llaves sin cerrar).

El código:

(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;
})();

Paso 3: Actualiza la versión del plugin

Antes de compilar y probar los cambios, hace falta actualizar la versión del plugin. Esto garantiza que ONLYOFFICE trate la compilación como un nuevo plugin, evita problemas de caché y facilita el seguimiento de los cambios a lo largo del tiempo.

Abre config.json en tu carpeta de plugins.

Aumenta la versión en un nivel de parche, por ejemplo:

"version": "3.0.0" to "3.1.0"

Esto se recomienda tanto para los editores de escritorio como los editores web:

Escritorio: garantiza que la aplicación vuelva a cargar el plugin actualizado.

Web (incluidos los enlaces de tiendas personalizadas): evita que el almacenamiento en caché ignore los cambios en helpers.js.

Paso 4: Compila tus cambios

Este es el paso más importante del nuevo flujo de trabajo. El plugin aún no puede leer tu nuevo archivo directamente. Debes ejecutar el script de ayuda para fusionar tu nuevo archivo con la lógica principal del plugin.

1. Abre tu terminal.
2. Navega al directorio helpers:

cd .dev/helpers

3. Ejecuta el script de compilación en Python.

python3 helpers.py

El script helpers.py analizará las carpetas word/, cell/ y slide/, encontrará tu nuevo describe-image.js y lo fusionará en el archivo principal helpers.js.

Paso 5: Creación del archivo .plugin

• Selecciona todo el contenido del plugin.
• Comprímelo.
• Cambia el nombre del archivo de .zip a .plugin.
• Colócalo en una carpeta llamada deploy dentro de tu plugin.

Paso 6: Reemplaza el plugin en ONLYOFFICE

Desktop Editors

En las versiones recientes de ONLYOFFICE Desktop Editors, el plugin de IA está incluido por defecto. Si estás utilizando una versión anterior en la que el plugin aún no estaba incluido, el proceso de instalación depende de tu situación y sigue dos posibles caminos:

A) Instalación del plugin de IA por primera vez

Si el plugin de IA no aparece en tu directorio local de plugins:

1. Abre ONLYOFFICE Desktop Editors.
2. Ve a Extensiones → Administrador de plugins → Plugins disponibles → Instalar plugin manualmente.
3. Cuando se te pida que selecciones un archivo, elige tu archivo .plugin compilado.

B) Actualización de una copia local existente del plugin de IA

Si el plugin ya está presente en tu sistema:

1. Accede a ~/.local/share/onlyoffice/desktopeditors/sdkjs-plugins
2. Busca la carpeta cuyo nombre coincida con el GUID del plugin de config.json – {9DC93CDB-B576-4F0C-B55E-FCC9C48DD007}
3. Reemplaza la carpeta con tu plugin recién creado.
4. Reinicia la aplicación de escritorio.

Editor web (a través del enlace de la tienda personalizada)

Enlace de la tienda personalizada

Habilita GitHub Pages para tu bifurcación.

Asegúrate de incrementar la versión en config.json para evitar problemas de almacenamiento en caché.

1. Bifurca el repositorio del Marketplace de plugins de ONLYOFFICE. Obtendrás una copia en:
   https://github.com/YOUR-USERNAME/ONLYOFFICE/onlyoffice.github.io
2. Asegúrate de que tu carpeta de plugins incluye una carpeta de implementación que contenga el archivo .plugin.
3. Añade tu carpeta de plugins a: onlyoffice.github.io/sdkjs-plugins/content/ai/
4. Crea tu sitio GitHub Pages desde este repositorio (consulta la documentación de GitHub Pages)
5. Prepara un enlace a tu tienda personalizada añadiendo /store/index.html a la URL de GitHub Pages: https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html
6. Incrementa la versión del plugin en config.json (como se describe en el paso 3) para evitar el almacenamiento en caché.

Actualiza el plugin

Antes de actualizarlo con tu versión personalizada, es posible que tengas que eliminar la versión preinstalada, dependiendo de tu configuración.

• Comprueba si el plugin de IA ya está instalado

Abre el Editor web y ve a Extensiones → Administrador de plugins.

Si el plugin de IA está instalado, elimínalo:

Si no está instalado, pasa al siguiente paso.

Esto garantiza que la versión personalizada se pueda instalar o actualizar sin conflictos.

• Añade tu tienda personalizada

Haz clic en el icono de la tienda en la esquina superior derecha del Administrador de plugins:

Introduce la URL personalizada de tu tienda:

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

Tu tienda personalizada aparecerá ahora en el Administrador de plugins.

• Instala el plugin de IA

Una vez que se cargue tu tienda personalizada, busca Asistente de IA en la lista y haz clic en Instalar.

Paso 7: Prueba tu función

1. Vuelve a cargar el plugin en ONLYOFFICE.
2. Selecciona una imagen en tu documento.
3. Pídele a la IA: «Describe esta imagen» o «Escribe una leyenda para esto».

La IA reconocerá tu nueva función personalizada y ejecutará la lógica que acabas de escribir.