ReadAware

Crear un plugin

Empieza con la plantilla pública de TypeScript, declara el conjunto mínimo de capacidades y prueba el paquete compilado en la aplicación de escritorio de ReadAware. El host se encarga del ciclo de vida, los permisos, la presentación y la reversión; tu plugin se encarga de su comportamiento y sus datos privados.

Requisitos previos

  • La aplicación de escritorio de ReadAware, con acceso a Ajustes → Plugins.
  • Bun para los scripts del repositorio.
  • Un clon o fork del repositorio readaware-plugins.

Crear el paquete

  1. Copia template/ en plugins/<your-plugin-id>/.
  2. Mantén idénticos el nombre de la carpeta, el id del manifest y el espacio de nombres del runtime.
  3. Edita manifest.json y src/main.ts.
  4. Elimina las contribuciones de la plantilla que no uses y quita sus permisos.
  5. Compila el main.js autocontenido que carga ReadAware.
bash
bun run build
bun run typecheck
bun test
bun run validate

Diseña el manifest antes de implementar

Revisa el manifest en este orden:

  1. Identidad — ID estable, nombre, versión del paquete, autor y versión mínima de la aplicación.
  2. Datos — entero positivo schemaVersion y ruta de migración.
  3. Compatibilidad — un rango semver en requires para cada API y esquema utilizado.
  4. Autoridad — permissions semánticos y concesiones exactas de settingsAccess.
  5. Declaraciones — ajustes, tareas programadas, temas, fuentes y módulo de entrada.

Usa el navegador de capacidades y la vista previa de permisos antes de instalar. Los requisitos son afirmaciones de compatibilidad, no autoridad del usuario; las capacidades sin permisos también deben figurar en requires cuando tu plugin depende de su contrato.

Elegir la capacidad adecuada

  1. Usa un Dominio para el estado o comportamiento que pertenece a ReadAware.
  2. Usa una Contribución para proporcionar una opción, acción o proveedor.
  3. Usa un Servicio para una operación acotada del host.
  4. Usa el almacenamiento del plugin únicamente para datos propios del plugin.
  5. Solicita una nueva capacidad tipada del host cuando ninguna forma existente encaje.

No dupliques libros, progreso, anotaciones, Ajustes ni memoria en el almacenamiento del plugin. El estado paralelo evita las invariantes del producto, los eventos confirmados, la reconstrucción de proyecciones, la semántica de sincronización y el contexto del agente.

Mantener la activación declarativa

Durante activate(ctx), inspecciona el entorno y registra acciones, comandos, proveedores, suscripciones y tareas programadas. No realices escrituras de negocio ni trabajo externo. El host prepara cada registro hasta que terminan las RPC de activación y el Worker responde a un ping de salud.

Inicia el trabajo del runtime desde un manejador registrado después de la promoción. Si un manejador devuelve una promesa, deja que el host presente los estados de carga y error. Conserva referencias a recursos externos solo cuando tu deactivate() opcional deba cerrarlos; los registros y las suscripciones del host se eliminan automáticamente.

Versionar los datos privados explícitamente

schemaVersion versiona el KV y las colecciones de documentos del plugin; es independiente de la versión del paquete. Cámbialo únicamente cuando cambie la forma de los datos privados. Exporta migrate(storageCtx, change) para cada actualización y degradación compatibles después de confirmar un esquema.

  • Las migraciones solo reciben almacenamiento: no dominios, Ajustes, secretos, red, UI, LLM ni contribuciones.
  • Haz que cada transición sea determinista e idempotente.
  • Prueba un fallo después de escrituras parciales; el host debe restaurar exactamente el KV, los documentos, los archivos y los metadatos del esquema.
  • No uses una comprobación de la versión del paquete como sustituto del esquema de datos.

Instalar la carpeta de trabajo

  1. Ejecuta la compilación y las comprobaciones.
  2. Abre ReadAware → Ajustes → Plugins → Instalar plugin.
  3. Selecciona la carpeta del plugin compilado e inspecciona el resumen del consentimiento.
  4. Prueba la funcionalidad real en la aplicación de escritorio.
  5. Vuelve a compilar y reinstala para probar una actualización.

Un navegador convencional no puede verificar la instalación del plugin, la IPC del Worker, la persistencia de SQLite, el acceso directo a libros, la integración con el lector ni la reversión. Prueba la aplicación Tauri distribuida.

Probar el ciclo de vida, no solo el camino feliz

  • Instalación nueva, activación, desactivación y reactivación sin reiniciar.
  • Actualización y degradación correctas con datos reales.
  • Tiempo de espera agotado durante la activación, rechazo del manejador, fallo de migración y reversión exacta.
  • Limpieza al desinstalar: ninguna acción, escucha, tarea programada, proveedor o Worker superviviente.
  • Eliminación y ampliación de permisos durante una actualización.
  • Etiquetas largas, estados vacíos, navegación con teclado y todos los temas del host.

Conocer los límites actuales

Las tareas programadas se ejecutan mientras ReadAware está abierto, al menos con la cadencia declarada, y se ponen al día al iniciar cuando están atrasadas. No son trabajos duraderos: no se ejecutan mientras la aplicación está cerrada, no tienen una cola persistente, un contrato de reintento con backoff ni garantía de reanudación tras un fallo.

La UI solo está disponible en los puntos de contribución tipados existentes. Una ubicación que falte requiere una contribución y un consumidor propiedad del host; no se añadirá HTML arbitrario ni una API genérica de invocación nativa como atajo.

Siguiente

Mantén la referencia de la API junto a tu editor y después lee Publicación antes de preparar un pull request para el registro.