Referencia de la API de plugins
Esta página explica el contrato de desarrollo actual. El Explorador de capacidades muestra el catálogo activo, los nombres exactos de los métodos, sus firmas y las declaraciones de origen. Una aplicación publicada o la plantilla pública pueden exponer versiones anteriores; ajusta los rangos de requires a un host probado.
Paquete y manifiesto
Un plugin contiene manifest.json y un módulo ES autocontenido, normalmente main.js. Mantén el código fuente y los recursos necesarios dentro del paquete para su revisión.
| Campo | Significado |
|---|---|
id, name, version | Espacio de nombres estable, nombre visible y versión del paquete. El ID coincide con el nombre de la carpeta. |
schemaVersion | Entero positivo para el esquema de datos privado del plugin; es independiente de la versión del paquete. |
requires | IDs de capacidades y rangos semver, agrupados en domains, contributions, services y schemas. |
permissions | Autoridad semántica, como library:read o service:llm. |
settingsAccess | Concesiones independientes de discover, read y write para rutas exactas o grupos de secciones explícitos. |
networkAccess | Orígenes HTTP(S) permitidos para Network 2.x; es obligatorio junto con service:network. |
minAppVersion | Límite inferior opcional de la versión de la aplicación, además de los requisitos de capacidades. |
main | Módulo de entrada relativo; por defecto es main.js. |
settings, schedules, themes, fonts | Declaraciones interpretadas por el host. |
services | Exportaciones de servicios de módulos versionadas y tipadas para llamadas entre plugins. |
No existe ningún campo del manifiesto que conceda acceso arbitrario al sistema de archivos, SQL, DOM o IPC nativo.
Contexto y ámbito de los objetos
El host llama a activate(ctx) con ctx.domains, ctx.contributions y ctx.services, además del manifiesto, el idioma, la versión de la aplicación, la fase del ciclo de vida, las versiones de las capacidades y la concesión inmutable del libro.
ctx.grants.book es all, current o un book especificado. El host lo selecciona mediante consentimiento. La lectura, la memoria, las conversaciones, los comandos y los recursos conservan ese ámbito entre llamadas y callbacks. Un cambio de libro actual puede invalidar lecturas, identificadores, propuestas y observaciones pendientes.
El permiso de escritura de un dominio incluye la lectura. Las concesiones de Settings siguen siendo independientes según la operación. Los espacios de nombres o métodos protegidos por permisos pueden estar ausentes; aun así, las comprobaciones del host se ejecutan en cada llamada. Usa ctx.services.session.operationAvailability(...) para las consultas de preflight admitidas y gestiona el fallo de ejecución incluso después de un resultado positivo.
Dominios
| Dominio | Trabajo disponible | Límites |
|---|---|---|
library | Libros y colecciones, índices, búsqueda de ubicaciones exactas, rangos, referencias e imágenes, importaciones, tareas de texto, metadatos, fusiones de duplicados y eliminación. | Versiones de origen, ámbito del libro, lecturas acotadas, tareas propias del actor y comprobantes independientes de limpieza de archivos. |
reading | Instantáneas de sesión, navegación, selección, controles de reproducción y modo, progreso, tiempo de lectura e información de uso. | Protecciones de la sesión actual, estado asentado frente a pendiente, disponibilidad del proveedor y cancelación. |
annotations | Páginas, inspección y observaciones; crear destacados o notas; lotes condicionales de edición/eliminación. | Usa la revisión observada antes de la decisión del usuario. Los rangos capturados también requieren acceso a Library. |
conversations | Transcripciones autorizadas, resúmenes almacenados, estado de ejecución y de solicitudes de turnos; controles de hilos y turnos propuestos. | La aprobación del host inicia un turno propuesto. Las operaciones sobre hilos globales requieren acceso a todos los libros. Los plugins no sustituyen el runtime de chat. |
settings | Descubrimiento del catálogo, instantáneas resueltas, opciones, metadatos de modelos, observación, actualizaciones y reinicios de lectura. | Rutas exactas, política del objetivo y autoridad adicional para trabajar con proveedores externos. |
memory | Búsqueda y páginas, inspección, corrección/olvido, perfiles, entidades, clasificación, grafos y tareas, archivos de contexto. | Concesiones de libros y revisiones condicionales. Las operaciones de identidad/perfil globales requieren acceso a todos los libros; la generación también necesita autoridad sobre el modelo. |
Texto de origen y navegación
Usa library.queries.books.searchLocations para coincidencias navegables en el origen y readRange para obtener texto de origen acotado. Conserva la versión de origen y la ubicación devueltas. Las coincidencias derivadas de searchText son vistas previas, no anclas de navegación intercambiables. La preparación explícita de texto devuelve un trabajo cuyo progreso y resultado deben observarse.
Escrituras condicionales
Inspecciona el objeto actual y conserva su revisión antes de mostrar una edición. Envía la mutación condicional contra esa revisión. En caso de conflicto, vuelve a leer y deja que el usuario decida; sustituir silenciosamente la revisión esperada sobrescribiría otro cambio.
annotations.commands.applyChanges, las mutaciones de Memory, los commits de documentos privados y las vistas previas de transacciones tienen cada uno su propio contrato tipado. Los comandos ordinarios no se pueden deshacer automáticamente ni son transacciones distribuidas.
Observaciones y reacciones
Usa observaciones autorizadas para el estado actual y suscripciones confirmadas para los eventos. Un número de secuencia puede ordenar las entregas sin ser un cursor de base de datos ni una revisión de escritura condicional. Las observaciones fallidas deben poder distinguirse de los resultados vacíos.
Usa ctx.withEvent(delivery) para el trabajo de seguimiento automático y IDs de reglas estables en las suscripciones causales cuando sea necesario. Conserva el contexto vinculado durante las llamadas asíncronas. El host rechaza los ciclos causales y las entregas caducadas; las acciones de usuario independientes usan el contexto original.
Contribuciones
| Contribución | Lo que proporciona el plugin |
|---|---|
selectionActions, headerActions, contextActions, commands, uriHandlers | Acciones en superficies tipadas del host, comandos de la paleta y gestión de URI con espacios de nombres. |
settingsOptions | Opciones dinámicas para un ajuste declarado del plugin. |
voiceProviders, contentProviders, readerModes | Síntesis de audio, contenido de libros virtuales y modos de segmentación incluidos en el lector. |
agentTools, agentContextProviders, agentRetrievalProviders | Herramientas, contexto acotado por turno y fuentes propias del plugin que se pueden buscar. |
memoryCandidateProviders | Memorias candidatas para la validación y aceptación del host. |
themes, fonts | Opciones de apariencia declaradas en el manifiesto. |
syncTransports | Almacenamiento de sobres de sincronización cifrados opacos y objetos meta. |
Las acciones pueden actualizar su propio estado visible/habilitado/marcado cuando sea compatible. Los registros y los objetos descartables pertenecen a una activación. Devolver una vista no concede al callback autoridad adicional sobre los dominios.
Las memorias candidatas y los comandos directos de Memory son rutas distintas: las candidatas pasan por la aceptación del host, mientras que los comandos directos requieren la concesión de Memory y la revisión adecuadas. Ninguna de las dos permite inyectar reglas del sistema ni sustituir al agente principal.
Servicios del host
| Servicio | Úsalo para | Límite principal |
|---|---|---|
storage | KV privado, colecciones de documentos, commits condicionales, páginas, observaciones y políticas de uso. | Espacio de nombres y cuotas del plugin; los cursores obsoletos requieren una nueva línea base. |
resources | Archivos/directorios elegidos por el usuario, identificadores sellados de bytes, exportaciones, imágenes y recursos binarios privados. | No hay rutas ambientales. Los identificadores tienen propietarios, límites y ciclos de vida. |
secrets | Ranuras privadas de credenciales cifradas del plugin. | No hay acceso a los secretos de otro plugin. |
network | HTTP con ámbito de origen, solicitudes almacenadas en búfer y streaming acotados. | Se comprueba cada redirección; no se repiten automáticamente escrituras arbitrarias. |
llm | Inferencia de texto o estructurada, streaming, recursos de imagen, comprobantes de solicitudes y presupuestos. | Configuración del usuario, reglas de privacidad, cancelación y límites del host/proveedor. |
clipboard | Escribir texto o una imagen sellada. | Permiso explícito y tipo de recurso compatible. |
ui | Vistas, toast, flujos nativos de guardado/apertura, navegación por el espacio de trabajo y comandos, paneles del lector y ventanas. | Concesiones de dominio específicas del método y presentación propiedad del host. |
session | Metadatos del entorno no sensibles y disponibilidad de operaciones. | No hay suscripción a la antigua sesión de lectura; usa el dominio Reading. |
schedules | Handlers recurrentes declarados y solicitudes diferidas propias. | El trabajo se ejecuta mientras la aplicación está abierta; la hora no es exacta. |
jobs | Planes duraderos compatibles, checkpoints, observación y control. | Operaciones tipadas del host, no ejecución arbitraria de JavaScript. |
changes | Cursores de cambios persistentes con ámbito. | Indicaciones de recarga, no un registro de eventos sin procesar ni valores históricos. |
transactions | Vista previa, commit, consulta de comprobantes y vista previa de deshacer condicional. | Operaciones locales compatibles y concesiones originales; los resultados desconocidos requieren consultar el comprobante. |
plugins | Inspeccionar registros, observar cambios, descubrir e invocar servicios de plugins tipados. | Intersección de autoridad entre quien llama y quien recibe, ámbito, versiones y ejecución aislada del servicio. |
maintenance | Exportaciones de diagnóstico revisadas y flujos de estado, copia de seguridad, prueba de conexión y actualización gestionados por el host. | El host conserva las credenciales, los diálogos de archivos y las confirmaciones consecuentes. |
sync | Estado de sincronización autorizado, cola pendiente y flujos de cuenta o sincronización gestionados por el host. | No hay claves de cifrado ni credenciales de cuenta sin procesar. |
diagnostics, logging | Exportaciones de diagnóstico revisadas y eventos de desarrollador estructurados y acotados. | No hay contenido arbitrario, secretos ni informes automáticos mediante la API de logs. |
Red e inferencia
Network 2.x necesita tanto un permiso semántico como orígenes explícitos:
{
"requires": { "services": { "network": "^2.2.0" } },
"permissions": ["service:network"],
"networkAccess": { "origins": ["https://api.example.com"] }
}Sustituye el origen de ejemplo por el endpoint que realmente uses. Los orígenes incluyen esquema, host y puerto; no son rutas URL ni comodines de subdominio. Las redirecciones deben seguir estando autorizadas. Los llamadores de streaming cierran los streams propios cuando terminan. El reintento seguro opcional se limita a solicitudes de lectura compatibles antes de entregar una respuesta; la cancelación no revierte un efecto secundario remoto.
Para la inferencia, usa readingContext para el contexto del libro, de modo que el host pueda aplicar las reglas de privacidad y ámbito. Usa IDs de recursos sellados para las imágenes compatibles. Los metadatos de la solicitud y los presupuestos de salida ayudan a controlar el trabajo; no son un estado de facturación ni una garantía de cumplimiento del proveedor.
Trabajo en segundo plano y transacciones
Usa un schedule para organizar la invocación de un handler, una solicitud diferida propia para trabajo posterior mientras la aplicación se ejecuta y un job duradero solo cuando su plan tipado admita la operación. La recuperación tras un reinicio puede requerir atención en lugar de repetir a ciegas un resultado externo incierto.
Las transacciones combinan operaciones compatibles de Settings, documentos privados y dominios bajo las concesiones originales. La vista previa congela el trabajo propuesto; el commit consume esa vista previa. Después de una respuesta desconocida, consulta el comprobante antes de reintentar. Deshacer está condicionado a que el estado siga coincidiendo con el resultado anterior.
Servicios entre plugins
Declara en el manifiesto del proveedor el ID del servicio, la versión, el ámbito, los permisos necesarios y los esquemas de entrada/salida, y exporta su handler en el objeto services del módulo. Descúbrelo y llámalo mediante el servicio Plugins. El host ejecuta un nuevo realm de servicio aislado con autoridad intersectada; no activa el runtime de UI normal del proveedor para la llamada. Las llamadas originadas por el agente conservan su requisito de aprobación.
Vistas, ajustes, temas y fuentes
Los plugins devuelven datos de vista declarativos. El host renderiza listas, formularios, Markdown, detalles y diseños de bloques compatibles. Usa resultados de vista tipados y actualizaciones de vista en vivo; mantén diferenciados los estados de carga, conflicto, vacío y error. El código del plugin no dispone de React, DOM, iframe ni CSS arbitrario.
Los campos de Settings los renderiza el host. Los campos secretos escriben en ranuras de secretos cifradas y no se convierten en valores de formulario ordinarios ni en ajustes visibles para el modelo. Proporcionar un tema o una fuente requiere ui:themes; seleccionar uno usa la concesión de escritura de Settings correspondiente.
Ciclo de vida y compatibilidad
- Activando: lecturas y registros compatibles; las contribuciones en preparación todavía no son visibles.
- Migrando: solo almacenamiento privado, antes de confirmar un esquema modificado.
- Activo: los handlers promovidos pueden usar las capacidades concedidas.
El host comprueba el estado y promueve un candidato cuando la activación y cualquier migración terminan correctamente. Un fallo restaura el paquete y los datos anteriores. La descarga libera registros, callbacks y recursos propios; los datos duraderos siguen su contrato de retención independiente. En el desarrollo actual, la desinstalación elimina las colecciones de documentos privados y los recursos binarios, y conserva el estado definido de KV/secret/schema para la reinstalación.
Declara cada capacidad y esquema utilizados de forma independiente. Un número de versión demuestra compatibilidad del contrato, pero no que todos los sistemas operativos, proveedores o casos de fallo hayan superado la aceptación de extremo a extremo. Verifica el flujo real de escritorio que distribuyes.