Bibliothèque Navin : compétences, plugins, MCP, canaux et règles par projet

English version: ../../en/guides/navin-library.md

Ce que contient la bibliothèque

La plateforme livre la bibliothèque du paquet Navin dans catalog/navin : 276 compétences, 17 plugins, 28 commandes, 14 agents, 31 préréglages de serveurs MCP, 10 canaux de messagerie (Discord, e-mail, Matrix, Mattermost, Microsoft Teams, Signal, Slack, Telegram, WebSocket, WhatsApp) et 6 sources de règles de projet. catalog/navin/index.json donne l'empreinte sha256 de chaque élément. La copie se met à jour avec python tools/navin_library/sync.py ; python tools/navin_library/sync.py --check signale une copie qui ne correspond plus à la source.

GET /v1/navin-library donne la version et les compteurs, GET /v1/navin-library/{kind} liste un type (skills, plugins, commands, agents, mcp-presets, channels) et GET /v1/navin-library/{kind}/{name} donne le contenu d'un élément.

Publication dans Harbor

Chaque compétence, plugin, commande et agent de catalog/navin se publie aussi dans le Harbor du Navin Trusted Hub, dans les projets skills, plugins, commands et agents : un bundle OCI par élément, registry.navinspire.ai/<projet>/<nom>:<version du paquet Navin>, dont l'unique couche est l'archive tar reproductible de l'élément, avec sa licence (annotation org.opencontainers.image.licenses). Le catalogue du Hub déclare les mêmes dépôts dans hub/catalog/library.yaml, généré par python hub/tools/generate_library.py (contrôlé en CI avec --check).

1. python tools/navin_library/library_hub_release.py plan construit les bundles dans dist/navin-library/<version> et écrit le plan release/navin-library/hub-release.json (empreinte sha256 de chaque bundle).
2. python tools/navin_library/library_hub_release.py check --strict vérifie que le plan correspond à la bibliothèque et que le Hub connaît chaque élément avec sa licence.
3. python tools/navin_library/library_hub_release.py publish, avec HUB_API, HUB_TOKEN, REGISTRY_USER et REGISTRY_PASSWORD dans l'environnement, pousse chaque bundle dans le projet staging, contrôle son empreinte, puis l'enregistre en quarantaine avec hub/pipeline/publish.sh --register-only. Une reprise saute les éléments déjà enregistrés. Les releases restent en quarantaine jusqu'à leur promotion par la porte de publication du Hub.
4. python tools/navin_library/library_hub_release.py verify --location quarantine (ou published) relit chaque bundle et compare ses octets au plan.

Une étiquette Harbor est immuable : un élément déjà enregistré qui change demande une nouvelle version du paquet Navin.

Activer dans un projet

Tout se fait par projet du tenant : un autre projet ne voit ni ses activations, ni ses serveurs MCP, ni ses canaux, ni ses règles. POST /v1/projects/{project_id}/navin-library/activations active une compétence, un plugin, une commande ou un agent. Une compétence activée est enregistrée dans le registre des compétences avec la signature de la bibliothèque et le Skill Loader la sert comme une compétence signée. Un plugin active ses compétences, commandes et agents, et les retire avec lui (DELETE /v1/projects/{project_id}/navin-library/activations/{activation_id}).

from enterprise_ai import EnterpriseAI

client = EnterpriseAI("<control-plane-url>", api_key="eai_...")
client.navin_library.activate("alpha", "plugin", "hookify")
print(client.navin_library.project("alpha")["counts"])

Serveurs MCP depuis un préréglage

POST /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install crée un serveur MCP du projet. Les champs secrets ne se donnent que par référence openbao:// ou env://. Un préréglage HTTP passe par la passerelle MCP ; un préréglage stdio (commande locale comme npx ou uvx) se lance depuis la page MCP du Navin Manager, par tenant et par projet, qui teste la connexion et scelle les secrets, puis s'enregistre ici par l'URL de son point d'accès HTTP.

client.navin_library.install_mcp_preset("alpha", "browserbase", url="https://mcp.browserbase.com/mcp",
                                        credential_refs={"browserbase_api_key": "openbao://mcp/browserbase"})
client.mcp.list_servers(project="alpha")

Canaux réutilisables

POST /v1/projects/{project_id}/navin-library/channels/{name}/install crée un canal du projet depuis le contrat d'un canal Navin : chaque champ est vérifié (type, choix, champs obligatoires) et les secrets restent des références. Le pont de canaux du SDK Python relaie les messages de l'adaptateur Navin vers POST /v1/channels/{name}/inbound et renvoie la réponse de l'agent.

import asyncio

from enterprise_ai.channels.bridge import ChannelBridge
from enterprise_ai.runtime.bus import BusMessage, MessageBus

client.navin_library.install_channel("alpha", "telegram", settings={"allowFrom": ["42"]},
                                     secret_refs={"token": "env://TELEGRAM_TOKEN"}, agent_ref="agent:support")
bridge = ChannelBridge(client, "telegram-alpha")
bus = MessageBus()
asyncio.run(bridge.handle(BusMessage(content="Bonjour", session_id="chat-1", sender="42"), bus))

Avec le paquet Navin installé, bridge.load_adapter(bus) instancie l'adaptateur Navin du canal (Telegram, Discord, Slack...) sur le même bus et bridge.run(bus) relaie chaque message.

Règles de projet

POST /v1/projects/{project_id}/rules/import lit les fichiers de règles d'un dépôt : .navin/rules/*.md, .cursor/rules/*.mdc (alwaysApply, description, globs), .cursorrules, .clinerules, .windsurfrules et .github/copilot-instructions.md. PUT /v1/projects/{project_id}/rules/{name} écrit une règle, GET /v1/projects/{project_id}/rules/prompt rend la section de prompt reçue par chaque exécution du projet : règles permanentes incluses, règles conditionnelles listées avec leurs globs.

client.navin_library.import_rules("alpha", "./mon-depot")
print(client.navin_library.rules_prompt("alpha")["prompt"])

Procédures

L'écran est Studio développeur > Bibliothèque Navin (portal/src/screens/navin-library.tsx), avec les onglets Catalogue, Activé dans le projet, MCP, Instances MCP, Canaux et Règles. Activer et installer demandent le rôle administrateur du tenant, développeur ou responsable d'application ; les autres rôles voient la bibliothèque en lecture seule.

1. Choisir le projet. Chaque activation, serveur MCP, canal et règle appartient à un projet : rien ne passe à un autre projet du tenant.

   Écran : Bibliothèque Navin, champ Projet.

   Résultat attendu : les compteurs de la bibliothèque et du projet s'affichent.

   En cas d'échec : « Aucun projet pour l'instant » signale un tenant sans projet ; créez-en un dans Administration > Projets et environnements. 404 project_not_found signale un projet inconnu de votre tenant.

2. Activer une compétence, un plugin, une commande ou un agent. L'activation enregistre l'élément pour le projet ; une compétence activée est servie par le Skill Loader comme toute compétence signée.

   Écran : Catalogue, choisissez le type, ouvrez l'élément, Activer dans le projet. API : POST /v1/projects/{project_id}/navin-library/activations.

   Résultat attendu : « Activé : n élément(s) » ; l'élément figure dans Activé dans le projet, un plugin avec ce qu'il apporte.

   En cas d'échec : 422 navin_library_kind_not_activable signale un type qui s'installe au lieu de s'activer (préréglages MCP et canaux) ; 409 navin_skill_name_taken signale une compétence du même nom, hors bibliothèque, déjà présente ; 404 navin_library_item_not_found signale un élément inconnu.

3. Installer un serveur MCP depuis un préréglage. Le formulaire n'accepte que des références pour les champs secrets : la plateforme ne conserve aucun secret.

   Écran : MCP, choisissez le préréglage, Installer, remplissez les champs (champs secrets en références openbao:// ou env://), Installer. API : POST /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install.

   Résultat attendu : « Serveur MCP installé » ; le serveur figure parmi les serveurs MCP du projet.

   En cas d'échec : 409 mcp_preset_needs_endpoint signale un préréglage stdio sans le point d'accès HTTP qui l'expose ; 422 mcp_preset_secret_ref_required signale un secret donné en valeur ; 422 mcp_preset_field_missing liste les champs manquants ; 409 mcp_preset_not_installable signale un préréglage non installable.

4. Installer un canal. Le formulaire est généré depuis le contrat d'installation du canal Navin.

   Écran : Canaux, choisissez le canal, remplissez le formulaire, installez. API : POST /v1/projects/{project_id}/navin-library/channels/{name}/install.

   Résultat attendu : « Canal installé » ; le canal figure parmi les canaux du projet.

   En cas d'échec : 422 channel_field_invalid (type ou choix faux), 422 channel_field_missing (exigence non remplie), 422 channel_secret_ref_required (secret donné en valeur).

5. Importer ou écrire les règles du projet. Les règles sont les consignes que reçoit chaque exécution du projet.

   Écran : Règles, Importer depuis un dépôt (fichiers ou dossier, chemins relatifs à la racine du dépôt), puis Importer ; ou Nouvelle règle, puis Enregistrer la règle. Aperçu du prompt montre la section reçue par les exécutions.

   Résultat attendu : « Importé : n règle(s) », avec les fichiers ignorés et leur raison (pas un fichier de règles, vide, trop volumineux).

   En cas d'échec : 422 rule_empty, 413 rule_too_large, 422 rule_name_invalid, 422 rule_scope_required (règle conditionnelle sans globs ni description).

6. Retirer une activation. Retirer un plugin retire les compétences, commandes et agents qu'il a apportés.

   Écran : Activé dans le projet, Retirer, puis Confirmer. API : DELETE /v1/projects/{project_id}/navin-library/activations/{activation_id}.

   Résultat attendu : « Retiré : n élément(s) ».

   En cas d'échec : 404 navin_library_activation_not_found.

Dépannage

Statut	Code	Cause	Correction
503	navin_library_unavailable	la bibliothèque livrée ne peut pas être lue	lancez python tools/navin_library/sync.py --check et restaurez catalog/navin
404	navin_library_kind_unknown	type hors skills, plugins, commands, agents, mcp-presets, channels	utilisez l'un des types listés
404	project_not_found	projet inconnu de votre tenant	vérifiez l'identifiant du projet
409	navin_skill_name_taken	une compétence de ce nom, hors bibliothèque, existe déjà	retirez ou renommez la compétence existante
409	mcp_preset_needs_endpoint	préréglage stdio sans point d'accès HTTP	lancez-le depuis la page MCP du Navin Manager, puis donnez son URL
422	mcp_preset_secret_ref_required	secret donné en valeur	donnez une référence openbao:// ou env://
422	channel_field_missing	exigence du canal non remplie	remplissez une alternative de chaque exigence
404	rule_not_found	nom de règle inconnu	listez les règles avec GET /v1/projects/{project_id}/rules

Étapes suivantes

• Guide de développement MCP
• Guide de développement de skill
• Guide de développement de plugin
• Décision d'architecture : docs/architecture/ADRs/ADR-0164-bibliotheque-navin-par-projet.md