Cree mini-apps para Roomcord

Añada un flujo de trabajo a la sala donde su equipo ya trabaja. Comience con el ejemplo starter, poll o approvals y cree una app para su sala.

Qué es una mini-app

Una mini-app es una pequeña aplicación que vive dentro de una sala de Roomcord. La sala guarda los datos de la app como registros en colecciones. Las funciones de la app se ejecutan en un sandbox en el servidor y son el único código que modifica esos registros. Los miembros de la sala y los agentes de IA instalados en ella llaman a las funciones, y el cliente muestra una pantalla genérica generada a partir de los esquemas de la app.

Antes de empezar

• Node.js y npm en su equipo.
• Una cuenta en el servidor de Roomcord for Enterprise de su empresa.
• El rol de administrador en la sala donde publica la app. Solo los administradores de la sala pueden subir y aprobar apps.

Inicio rápido

Esta guía usa la versión 4.1.0 de @fulldivevr/workcord-cli. La herramienta de línea de comandos se llama workcord. Todos los comandos imprimen JSON en stdout.

1. Instale la CLI.

   npm i -g @fulldivevr/workcord-cli
   

2. Inicie sesión. Recibirá un código por correo y la CLI se lo pedirá. Si su empresa opera su propio servidor, solicite su origen al administrador y añada --base-url <origin> a este comando una vez. El inicio de sesión guarda el servidor.

   workcord auth login --email [email protected] --save
   

3. Busque el id de la sala.

   workcord rooms list
   

4. Cree una carpeta de app a partir de la plantilla.

   workcord app init my-app
   

5. Ejecute las comprobaciones del servidor y las pruebas de la app en su equipo. No necesita un servidor.

   workcord app test my-app
   

6. Guarde la app como borrador pendiente de la sala. El resultado incluye el draftId.

   workcord app push my-app --room <roomId>
   

7. Apruebe el borrador. La app queda instalada en esa sala.

   workcord app drafts --room <roomId>
   workcord app approve <draftId> --room <roomId>
   

8. Llame a una función.

   workcord app call my-app addEntry --room <roomId> --data '{"title":"Dune"}'
   workcord app describe my-app --room <roomId>
   

Antes de subir una actualización, ejecute workcord app validate my-app --room <roomId>. Esto añade las comprobaciones que necesitan la sala: la versión y los registros existentes.

Formato del paquete

Un paquete es una carpeta:

my-app/
  manifest.json      id, version, name, summary, icon, collections, functions
  GUIDE.md           for agents: what the app is for, which function to use when
  functions/
    addEntry.js      one file per function in the manifest
  tests/
    entries.json     one scenario or a list of scenarios

• manifest.json declara las colecciones, cada una con un JSON Schema que debe cumplir cada escritura, y las funciones, cada una con una description, un esquema input y una lista callers.
• callers indica quién puede llamar a una función: members, admins o agents. Los agentes eligen una función por su description.
• GUIDE.md indica a los agentes cómo usar la app.
• tests/ contiene al menos un escenario. Las comprobaciones ejecutan todos los escenarios antes de subir la app y de nuevo antes de aprobarla.

Estructura de una función

Un archivo de función tiene exactamente un export default y ningún otro import o export. Recibe el evento y un contexto:

export default async (event, ctx) => {
  const { title, notes } = event.data;
  return ctx.db.entries.insert({ title, notes, status: 'open' });
};

• event.data es la entrada, después de comprobar el esquema.
• event.caller es el usuario o agente que hizo la llamada. El motor lo establece, por lo que el código de la app nunca realiza la autenticación.
• ctx.db.<collection> ofrece get, query, insert, update y delete. Cada llamada devuelve una promesa.
• throw new AppError(code, message) devuelve ese código y mensaje a quien hizo la llamada.

Cada escritura conserva una versión del registro, y una eliminación conserva su historial.

Límites

Las funciones no tienen red, sistema de archivos, temporizadores ni importaciones. No pueden llamar a otras apps ni leer otras salas. Los agentes hacen ese trabajo.

Quién puede publicar

Solo los administradores de la sala pueden subir y aprobar apps. Los agentes de la sala pueden guardar un borrador, pero un administrador lo aprueba. Una app aprobada se instala solo en esa sala. Cada nueva versión debe tener una version superior a todas las versiones que la sala haya aprobado antes.

Ejemplos y guía completa

El repositorio público fulldiveVR/roomcord-mini-apps contiene tres ejemplos para empezar: starter, poll y approvals.

La guía completa abarca colecciones, consultas, indicaciones de visualización, escenarios de prueba, actualizaciones y códigos de error.