Construire une extension
Une extension Ormuz est un contrat public composé de contributions déclarées. Commencez par les responsabilités métier et les échanges nécessaires, puis exposez uniquement les primitives qui servent un cas d’usage durable.
La surface d’une extension
| Surface | Rôle |
|---|---|
| Manifest | Décrit l’identité, le type, la cardinalité, l’activation, les capacités et les contributions de l’extension. |
| Configuration | Déclare les valeurs qu’un marchand doit fournir et les secrets qui lui appartiennent. |
| Channels | Déclare les échanges API ou événementiels pris en charge dans chaque direction. |
| Objets externes | Expose des représentations typées du système partenaire sans les confondre avec des objets plateforme. |
| Nodes | Expose des opérations explicites destinées à être composées dans un processus. |
| Agent tools | Expose des capacités agent-facing conçues indépendamment du catalogue de nodes. |
| Événements | Expose les occurrences externes utilisables comme déclencheurs ou contexte de processus. |
| Actions de parcours utilisateur | Fournit une UI participant-facing ou une redirection provider chargée uniquement lorsque l’action devient courante. |
| Process templates | Distribue séparément une composition de processus réutilisable qui déclare les extensions et configurations dont elle dépend. |
Une extension n’a pas à remplir toutes ces surfaces. Chaque contribution supplémentaire augmente son contrat de maintenance, sa documentation et sa surface de revue. Les process templates sont des artefacts marketplace associés à des extensions par leurs prérequis ; ils ne sont pas des contributions embarquées dans spec.contributes.
Ordre de conception recommandé
Définir le rôle de l’extension
Identifiez le système ou service relié à Ormuz, les faits qu’il possède et les résultats métier attendus.
Déclarer le manifeste
Choisissez le type, la cardinalité, l’activation, les mécanismes d’intégration et les contributions réellement supportées.
Choisir les channels
Déterminez qui initie chaque échange et qui possède le contrat : API sortante, API entrante, événement entrant ou événement sortant.
Modéliser les données
Séparez objets externes, objets plateforme, drafts et mappings avant de définir des mutations.
Ajouter les contributions nécessaires
Introduisez uniquement les nodes, Tools, événements ou actions de parcours utilisateur qui justifient un contrat maintenu et dont les responsabilités peuvent être explicitement vérifiées.
Frontières à préserver
- Le manifeste décrit des capacités ; il ne doit pas transporter de secret.
- Un objet externe n’est pas automatiquement un objet plateforme.
- Un mapping ne crée pas une nouvelle autorité métier.
- Un node n’accorde pas de permission simplement parce qu’il existe dans le catalogue.
- Un Tool n’est pas dérivé automatiquement d’un node ou d’un endpoint API.