Guide de développement de plugin

English version: ../../en/guides/plugin-development.md

Ce guide montre comment construire, valider, signer, publier, installer, mettre à niveau et retirer un plugin. Il s'adresse aux développeurs qui ont le rôle developer ou tenant_admin ; installer dans un environnement demande tenant_admin et une approbation.

Concept

Un manifeste de kind Plugin (contracts/v1/plugin-manifest.schema.json) a deux formats :

Format	Ce que c'est	Où il va
pack	Un pack Marketplace complet : agents, skills, prompts, serveurs MCP, connecteurs, politiques, évaluations, tests et documentation en anglais et en français.	Publié dans la Marketplace avec enterprise-ai plugin publish, installé par POST /v1/marketplace/installations après un preflight et une approbation. POST /v1/plugins le refuse avec 422 pack_requires_marketplace.
oci_plugin (par défaut)	Une image OCI signée avec des capacités déclarées, exécutée dans un bac à sable.	Enregistré par POST /v1/plugins, installé par POST /v1/plugins/{name}/install.

Un plugin passe par les statuts registered, installing, installed, failed, uninstalled et blocked.

Champs du manifeste

Champ	Type	Obligatoire	Description
apiVersion, kind, metadata		oui	enterprise-ai.io/v1, Plugin, name, version (semver), owner.
spec.description	chaîne	oui	Ce qu'apporte le plugin.
spec.capabilities	tableau	oui	Chaque élément : type (tool, connector, channel, model_adapter, evaluator, ui_extension, policy) et name.
spec.format	énumération	non	oci_plugin ou pack.
spec.artifact	objet	oci_plugin	oci_ref, digest (sha256:<64 hex>), media_type.
spec.signature	objet	oci_plugin	digest, cosign_bundle, signer, issued_at.
spec.sandbox	objet	oci_plugin	runtime (gvisor, kata, wasm, none), network (deny_all, egress_allowlist, cluster_only), egress_allowlist, read_only_rootfs, limits.
spec.permissions, spec.min_platform_version		non	Permissions et version minimale de la plateforme d'un plugin OCI.
spec.license, spec.licenseDeclaration	chaîne, objet	pack	Identifiant SPDX ; une licence autre que MIT ou Apache-2.0 demande une déclaration (spdx, reason).
spec.compatibility	objet	pack	Plages platform et sdk comme >=1.0.0 <2.0.0.
spec.requestedPermissions	tableau	pack	scope, reason, sensitive, classification ; l'administrateur en accorde une partie.
spec.dataProtection	objet	pack	classification_max, pii, residency.
spec.approvals	objet	pack	install.quorum (1 à 10) et rôles.
spec.docs	objet	pack	Chemins de la documentation en et fr.
spec.evaluations, spec.tests	tableau	pack	Suites d'évaluation (promptfoo, ragas, ...) et suites de tests (unit, integration, authz, security, opa).
spec.dependencies	tableau	non	name, plage version, optional.
spec.configSchema	objet	non	JSON Schema de la configuration d'installation.
spec.domain, spec.namespace, spec.category, spec.publisher, spec.displayName, spec.security, spec.layout, spec.signedArtifact, spec.testFlags		non	Métadonnées de catalogue et de sécurité d'un pack.

Cycle de vie

enterprise-ai plugin couvre create, validate, build, sign, publish et install d'un pack de la Marketplace ; le manifeste suit contracts/v1/plugin-manifest.schema.json. Le détail des packs est dans le guide de développement de packs.

enterprise-ai plugin create ./crm-pack --domain sales-crm --name crm-pack
enterprise-ai plugin validate ./crm-pack
enterprise-ai plugin build ./crm-pack --out dist
enterprise-ai plugin sign ./crm-pack --out dist --key cosign.key --signer acme
enterprise-ai plugin publish ./crm-pack --out dist --key cosign.key

build, sign et publish prennent le dossier du pack : l'archive est reconstruite, de façon reproductible, dans le dossier --out (par défaut dist dans le pack).

Étapes

1. Créer le pack. Le modèle généré est exécutable et passe tous les contrôles. Dans le portail, le manifeste d'un plugin OCI s'écrit dans Studio développeur > Atelier de plugins.

   enterprise-ai plugin create ./crm-pack --domain sales-crm --name crm-pack

   --domain : l'un de banking, cybersecurity, document-intelligence, finance, hr, it, legal, marketing, procurement, risk-compliance, sales-crm, support.

   Résultat attendu : les fichiers créés sont listés.

   En cas d'échec : le code de sortie 1 signifie que le dossier existe ; ajoutez --force.

2. Modifier le manifeste. Remplissez plugin.yaml : permissions demandées avec une raison chacune, protection des données, approbations, compatibilité. Voyez le guide de développement de packs pour chaque dossier.

   Résultat attendu : chaque droit utilisé par un agent, une skill ou un outil du pack est demandé.

   En cas d'échec : l'étape suivante liste les permissions manquantes ou dangereuses.

3. Valider. Les mêmes contrôles sont refaits par le Control Plane à la publication et à l'installation.

   enterprise-ai plugin validate ./crm-pack

   Résultat attendu : le pack est déclaré valide avec son nom et sa version.

   En cas d'échec : le code de sortie 1 liste chaque erreur de structure et de manifeste.

4. Construire et signer. build écrit l'archive reproductible, son empreinte SHA-256 et un SBOM SPDX. sign signe l'empreinte de l'archive et celle de chaque SKILL.md, et écrit le descripteur <name>-<version>.pack.json à côté de l'archive.

   enterprise-ai plugin build ./crm-pack --out dist
   enterprise-ai plugin sign ./crm-pack --out dist --key cosign.key --signer acme

   acme : le nom d'éditeur enregistré dans la Marketplace.

   Résultat attendu : l'empreinte, le signataire et le nombre de skills signées sont affichés.

   En cas d'échec : code de sortie 2 avec « --key and --signer are required ».

5. Publier. publish lance les tests du pack, les évaluations et l'analyse, s'arrête sur un contrôle en échec, pousse au besoin vers un registre OCI avec --oci, puis appelle POST /v1/marketplace/packages.

   enterprise-ai plugin publish ./crm-pack --out dist --key cosign.key --oci <harbor-host>/packs/crm-pack

   Résultat attendu : la version du paquet est renvoyée par la Marketplace.

   En cas d'échec : le code de sortie 1 nomme le contrôle en échec ; une archive non signée est refusée avant tout appel.

6. Installer. plugin install envoie POST /v1/marketplace/installations : le preflight s'exécute, puis une approbation marketplace.install est ouverte (quorum 2 quand une permission sensible est accordée ou en prod). Une fois approuvée, POST /v1/marketplace/installations/{installation_id}/apply crée les objets et lance un test de fumée.

   enterprise-ai plugin install crm-pack --version 1.0.0 --env staging --grant crm.records.read

   Résultat attendu : l'identifiant de l'approbation et le quorum sont affichés.

   En cas d'échec : 403 permission_unsafe, 422 config_invalid, 422 permission_not_requested, 409 package_suspended ou 422 preflight_failed.

7. Enregistrer et installer un plugin OCI. POST /v1/plugins vérifie la signature de l'image et l'enregistre ; POST /v1/plugins/{name}/install produit le déploiement en bac à sable et sa politique réseau. Dans le portail : Studio développeur > Atelier de plugins > Test > Lire le statut (GET /v1/plugins/{name}/status).

   Résultat attendu : statut installed, verified: true et la runtime_class du bac à sable.

   En cas d'échec : 403 plugin_unsigned, 403 plugin_blocked, 422 invalid_manifest.

8. Mettre à niveau ou revenir en arrière. Augmentez metadata.version, publiez, puis POST /v1/marketplace/installations/{installation_id}/upgrade ; POST /v1/marketplace/installations/{installation_id}/rollback rétablit la version précédente. Un plugin OCI se met à jour par POST /v1/plugins tant qu'il n'est pas installé.

   Résultat attendu : l'installation exécute la nouvelle version après son approbation et son test de fumée.

   En cas d'échec : 409 installation_state, 409 rollback_unavailable, 422 smoke_failed (la version courante reste), 409 plugin_installed pour un plugin OCI encore installé.

9. Suspendre ou retirer. POST /v1/marketplace/installations/{installation_id}/status suspend ou reprend une installation ; POST /v1/marketplace/installations/{installation_id}/uninstall retire chaque objet qu'elle a créé. Un plugin OCI se retire par POST /v1/plugins/{name}/uninstall.

   Résultat attendu : statut suspended ou uninstalled.

   En cas d'échec : 409 installation_state ou 409 plugin_not_installed.

Installation

POST /v1/plugins enregistre un plugin, POST /v1/plugins/{name}/install l'installe ; côté Marketplace, POST /v1/marketplace/preflight vérifie capacités et configuration avant POST /v1/marketplace/installations. Voir le guide Marketplace.

client.plugins.install("sap-connector-pack")

Dépannage

Symptôme	Cause	Correction
422 pack_requires_marketplace	Un manifeste format: pack a été envoyé à POST /v1/plugins.	Publiez-le avec enterprise-ai plugin publish et installez-le depuis la Marketplace.
422 invalid_manifest	Empreinte OCI différente de artifact.digest, egress_allowlist absent ou limites du bac à sable invalides.	Corrigez le champ nommé dans details.
403 plugin_unsigned	La signature de l'image n'est pas vérifiée à l'installation.	Signez l'image et enregistrez-la de nouveau.
403 plugin_blocked	Le plugin est blocked.	Demandez la raison à un security_officer ; publiez une version corrigée.
409 plugin_installed	Mise à jour d'un plugin OCI installé.	Désinstallez-le d'abord.
409 plugin_not_installed	Désinstallation d'un plugin qui n'est pas installé.	Lisez GET /v1/plugins/{name}/status.
422 preflight_failed	Un contrôle du preflight a échoué.	Lancez POST /v1/marketplace/preflight et lisez chaque contrôle.
403 permission_unsafe	Le pack demande un droit dangereux.	Retirez ce droit de requestedPermissions.
422 smoke_failed	Le test de fumée a échoué après l'application.	L'installation a été annulée ; corrigez le pack et publiez une nouvelle version.
409 marketplace_version_exists	La version est déjà publiée.	Augmentez metadata.version.

Étapes suivantes

• Guide de développement de packs et guide Marketplace.
• Guide de développement MCP et guide de développement de connecteur.
• Référence de la CLI.