#Développement de plugins pour les employés IA

Dans NocoBase, un plugin peut mettre ses capacités métier à la disposition des employés IA. Trois points d’extension couvrent différents niveaux :

• Tool (outil) — exécute une opération précise, comme interroger des données, appeler une API ou modifier un enregistrement
• Skill (compétence) — indique au modèle quand utiliser les Tools et quelles étapes suivre pour accomplir une tâche
• Employé IA intégré (Built-in AI Employee) — assemble un profil, un prompt système, des Skills et des Tools pour fournir un employé prêt à l’emploi

En règle générale, il n’est pas nécessaire d’appeler manuellement les API d’enregistrement. Placez les fichiers dans le répertoire conventionnel src/ai du plugin : NocoBase les analyse et les enregistre automatiquement au chargement du plugin. Un enregistrement supplémentaire dans src/client-v2/plugin.tsx n’est nécessaire que lorsqu’un Tool requiert une carte personnalisée, une fenêtre modale ou une logique exécutée dans le navigateur.

Avant de commencer, vérifiez que l’application a installé et activé @nocobase/plugin-ai. Le code du plugin peut utiliser les types et les fonctions de définition fournis par @nocobase/ai et @nocobase/actions.

#Index rapide

#Choisir d’abord le niveau à étendre

Les Tools, les Skills et les employés IA intégrés ne sont pas trois fonctions indépendantes. Ils se combinent progressivement, du niveau le plus bas au niveau le plus haut. Un plugin n’a pas forcément besoin d’implémenter les trois niveaux.

Tool：让 AI 能执行一个具体动作
  ↓
Skill：让 AI 按固定方法完成一类任务
  ↓
内置 AI 员工：把这些能力装配成一个固定角色和使用入口

Choisissez le point de départ selon votre besoin :

• Si l’IA doit uniquement interroger des données, appeler une API ou modifier un enregistrement, un Tool suffit
• Si vous devez définir l’ordre d’appel des Tools, les étapes de confirmation et le format de sortie, ajoutez un Skill pour ces Tools
• Si le plugin doit fournir directement un rôle fixe après son activation, créez également un employé IA intégré et liez-lui les Skills et les Tools correspondants

Lorsque les trois niveaux sont utilisés, une tâche suit cet ordre :

1. L’utilisateur confie une tâche à l’employé IA
2. L’employé IA détermine le Skill à utiliser à partir du prompt système
3. Le Skill indique au modèle quels Tools appeler et dans quel ordre
4. Le Tool exécute une requête, une écriture ou un appel externe, puis renvoie le résultat
5. L’employé IA prépare la réponse finale à partir du résultat du Tool

La carte frontend d’un Tool ne constitue pas un quatrième niveau. Elle complète uniquement l’interface d’un ToolCall lorsque le Tool doit demander à l’utilisateur de confirmer, de sélectionner une option ou de modifier des paramètres.

#Placer les ressources IA dans src/ai

NocoBase détecte les ressources IA d’un plugin selon des conventions de répertoire. Dans un plugin standard, placez les Tools, les Skills et les employés IA intégrés sous src/ai ; il n’est pas nécessaire de les enregistrer un par un dans la méthode load() de src/server/plugin.ts.

Un répertoire complet peut être organisé ainsi :

src/ai/
├── tools/
│   └── searchDocs.ts
├── skills/
│   └── document-search/
│       ├── SKILLS.md
│       └── tools/
│           └── readDocument.ts
└── ai-employees/
    ├── translator.ts
    └── developer/
        ├── index.ts
        ├── prompt.md
        ├── skills/
        └── tools/

Chaque emplacement correspond à un mode d’enregistrement :

Lors du chargement du plugin, NocoBase effectue les opérations suivantes avant d’exécuter la méthode load() du plugin :

1. Analyser et enregistrer les Tools
2. Analyser les fichiers SKILLS.md, puis lier les Tools de chaque répertoire au Skill correspondant
3. Charger les employés IA intégrés et fusionner leur prompt.md, leurs Skills et leurs Tools

src/client-v2 ne fait pas partie de ces répertoires analysés automatiquement. Un enregistrement supplémentaire dans src/client-v2/plugin.tsx est nécessaire uniquement lorsqu’un Tool requiert une carte frontend, une fenêtre modale ou une logique exécutée dans le navigateur.

#Référence rapide des points d’extension et des répertoires

Commencez par implémenter un Tool. Ajoutez un Skill si vous avez besoin d’un processus fixe, puis créez un employé IA intégré si vous souhaitez fournir un rôle fixe. N’ajoutez une carte frontend que lorsqu’un Tool requiert une interaction dans le navigateur.

#Liens connexes

• Écrire votre premier plugin — créez et exécutez un plugin NocoBase à partir de zéro
• Présentation des employés IA — découvrez les points d’accès aux employés IA
• Guide d’ingénierie des prompts — rédigez des prompts système et des contraintes de tâche