diff --git a/docs/fr/concepts/qa-e2e-automation.md b/docs/fr/concepts/qa-e2e-automation.md index 8a073b499..0b68172df 100644 --- a/docs/fr/concepts/qa-e2e-automation.md +++ b/docs/fr/concepts/qa-e2e-automation.md @@ -1,23 +1,23 @@ --- read_when: - - Extension de qa-lab ou qa-channel + - Extension de qa-lab ou de qa-channel - Ajout de scénarios QA adossés au dépôt - Création d’une automatisation QA plus réaliste autour du tableau de bord Gateway summary: Forme de l’automatisation QA privée pour qa-lab, qa-channel, les scénarios initialisés et les rapports de protocole -title: Automatisation E2E de la QA +title: Automatisation QA E2E x-i18n: - generated_at: "2026-04-16T21:51:24Z" + generated_at: "2026-04-17T06:57:31Z" model: gpt-5.4 provider: openai - source_hash: 7deefda1c90a0d2e21e2155ffd8b585fb999e7416bdbaf0ff57eb33ccc063afc + source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# Automatisation E2E de la QA +# Automatisation QA E2E -La pile QA privée est conçue pour tester OpenClaw d’une manière plus réaliste, -façonnée par les canaux, qu’un simple test unitaire ne peut le faire. +La pile QA privée a pour but d’exercer OpenClaw d’une manière plus réaliste, +structurée comme un canal, qu’un simple test unitaire ne peut le faire. Éléments actuels : @@ -25,26 +25,26 @@ façonnée par les canaux, qu’un simple test unitaire ne peut le faire. les réactions, les modifications et les suppressions. - `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription, injecter des messages entrants et exporter un rapport Markdown. -- `qa/` : ressources de départ adossées au dépôt pour la tâche de lancement et les +- `qa/` : ressources initiales adossées au dépôt pour la tâche de démarrage et les scénarios QA de référence. Le flux opérateur QA actuel est un site QA à deux volets : -- Gauche : tableau de bord Gateway (Control UI) avec l’agent. -- Droite : QA Lab, affichant une transcription de type Slack et le plan du scénario. +- Gauche : tableau de bord Gateway (UI de contrôle) avec l’agent. +- Droite : QA Lab, affichant la transcription de type Slack et le plan du scénario. -Lancez-le avec : +Exécutez-le avec : ```bash pnpm qa:lab:up ``` Cela construit le site QA, démarre la voie Gateway adossée à Docker et expose la -page QA Lab où un opérateur ou une boucle d’automatisation peut confier à l’agent une -mission QA, observer le comportement réel du canal et consigner ce qui a -fonctionné, échoué ou est resté bloqué. +page QA Lab où un opérateur ou une boucle d’automatisation peut confier à l’agent une mission QA, +observer le comportement réel du canal et consigner ce qui a fonctionné, échoué ou +est resté bloqué. -Pour des itérations plus rapides sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois, +Pour itérer plus rapidement sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois, démarrez la pile avec un bundle QA Lab monté par liaison : ```bash @@ -54,81 +54,81 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` maintient les services Docker sur une image préconstruite et monte par liaison +`qa:lab:up:fast` conserve les services Docker sur une image préconstruite et monte par liaison `extensions/qa-lab/web/dist` dans le conteneur `qa-lab`. `qa:lab:watch` reconstruit ce bundle à chaque modification, et le navigateur se recharge automatiquement lorsque le hachage des ressources QA Lab change. -Pour une voie de validation Matrix avec transport réel, exécutez : +Pour une voie de smoke test Matrix sur transport réel, exécutez : ```bash pnpm openclaw qa matrix ``` Cette voie provisionne un homeserver Tuwunel jetable dans Docker, enregistre -des utilisateurs temporaires pour le pilote, le SUT et l’observateur, crée une salle privée, -puis exécute le véritable plugin Matrix dans un enfant Gateway QA. La voie de transport en direct conserve -la configuration enfant limitée au transport testé, de sorte que Matrix s’exécute sans +des utilisateurs temporaires pilote, SUT et observateur, crée une salle privée, puis exécute +le vrai Plugin Matrix dans un enfant Gateway QA. La voie sur transport réel conserve +la configuration enfant limitée au transport testé, afin que Matrix s’exécute sans `qa-channel` dans la configuration enfant. Elle écrit les artefacts de rapport structurés ainsi qu’un journal combiné stdout/stderr dans le répertoire de sortie Matrix QA sélectionné. Pour -capturer également la sortie de construction/lancement externe de `scripts/run-node.mjs`, définissez +capturer également la sortie externe de build/lancement de `scripts/run-node.mjs`, définissez `OPENCLAW_RUN_NODE_OUTPUT_LOG=` vers un fichier journal local au dépôt. -Pour une voie de validation Telegram avec transport réel, exécutez : +Pour une voie de smoke test Telegram sur transport réel, exécutez : ```bash pnpm openclaw qa telegram ``` -Cette voie cible un groupe Telegram privé réel au lieu de provisionner un +Cette voie cible un vrai groupe Telegram privé au lieu de provisionner un serveur jetable. Elle nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, ainsi que deux bots distincts dans le même groupe privé. Le bot SUT doit avoir un nom d’utilisateur Telegram, et l’observation -bot-à-bot fonctionne mieux lorsque les deux bots ont le mode de communication bot-à-bot +bot à bot fonctionne mieux lorsque les deux bots ont le mode de communication Bot-to-Bot activé dans `@BotFather`. -Les voies de transport en direct partagent désormais un contrat plus petit au lieu que chacune -invente sa propre forme de liste de scénarios. +Les voies sur transport réel partagent désormais un contrat plus réduit au lieu que chacune +invente sa propre structure de liste de scénarios. -`qa-channel` reste la suite large de comportements synthétiques du produit et ne fait pas partie -de la matrice de couverture des transports en direct. +`qa-channel` reste la suite large de comportements produit synthétiques et ne fait pas partie +de la matrice de couverture des transports réels. -| Voie | Canary | Filtrage des mentions | Blocage par liste d’autorisation | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans un fil | Isolation des fils | Observation des réactions | Commande d’aide | -| -------- | ------ | --------------------- | -------------------------------- | --------------------------- | ------------------------- | ----------------- | ------------------ | ------------------------- | --------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Voie | Canary | Gating par mention | Blocage par allowlist | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans le fil | Isolation du fil | Observation des réactions | Commande d’aide | +| -------- | ------ | ------------------ | --------------------- | --------------------------- | ------------------------- | ----------------- | ---------------- | ------------------------- | --------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Cela conserve `qa-channel` comme la suite large de comportements du produit, tandis que Matrix, -Telegram et les futurs transports en direct partagent une checklist explicite de contrat de transport. +Cela permet à `qa-channel` de rester la suite large de comportements produit, tandis que Matrix, +Telegram et les futurs transports réels partagent une checklist explicite unique du contrat de transport. -Pour une voie sur VM Linux jetable sans intégrer Docker dans le parcours QA, exécutez : +Pour une voie de VM Linux jetable sans intégrer Docker dans le chemin QA, exécutez : ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Cela démarre un invité Multipass neuf, installe les dépendances, construit OpenClaw +Cela démarre un nouvel invité Multipass, installe les dépendances, construit OpenClaw dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le résumé dans `.artifacts/qa-e2e/...` sur l’hôte. -Elle réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte. -Les exécutions sur l’hôte et sur Multipass exécutent par défaut plusieurs scénarios sélectionnés en parallèle +Cela réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte. +Les exécutions de suite sur l’hôte et dans Multipass exécutent par défaut plusieurs scénarios sélectionnés en parallèle avec des workers Gateway isolés, jusqu’à 64 workers ou au nombre de scénarios sélectionnés. Utilisez `--concurrency ` pour ajuster le nombre de workers, ou `--concurrency 1` pour une exécution en série. -Les exécutions en direct transmettent les entrées d’authentification QA prises en charge qui sont pratiques pour -l’invité : les clés de fournisseur basées sur l’environnement, le chemin de configuration du fournisseur QA live, et -`CODEX_HOME` lorsqu’il est présent. Gardez `--output-dir` sous la racine du dépôt afin que l’invité +Les exécutions live transmettent les entrées d’auth QA prises en charge qui sont pratiques pour +l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA live, et +`CODEX_HOME` lorsqu’il est présent. Conservez `--output-dir` sous la racine du dépôt afin que l’invité puisse écrire en retour via l’espace de travail monté. -## Ressources de départ adossées au dépôt +## Ressources initiales adossées au dépôt -Les ressources de départ se trouvent dans `qa/` : +Les ressources initiales se trouvent dans `qa/` : - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Elles sont volontairement conservées dans git afin que le plan QA soit visible à la fois pour les humains et pour +Elles sont volontairement dans git afin que le plan QA soit visible à la fois pour les humains et pour l’agent. `qa-lab` doit rester un exécuteur Markdown générique. Chaque fichier Markdown de scénario est @@ -136,41 +136,57 @@ la source de vérité pour une exécution de test et doit définir : - les métadonnées du scénario - les références de documentation et de code -- les exigences de plugin facultatives -- le correctif de configuration Gateway facultatif +- les exigences facultatives en matière de Plugin +- le correctif facultatif de configuration Gateway - le `qa-flow` exécutable La surface d’exécution réutilisable qui sous-tend `qa-flow` peut rester générique -et transversale. Par exemple, les scénarios Markdown peuvent combiner des -helpers côté transport avec des helpers côté navigateur qui pilotent la Control UI intégrée via la -surface Gateway `browser.request` sans ajouter d’exécuteur spécialisé. +et transverse. Par exemple, des scénarios Markdown peuvent combiner des helpers côté transport +avec des helpers côté navigateur qui pilotent l’UI de contrôle intégrée via le +point d’intégration Gateway `browser.request` sans ajouter d’exécuteur spécialisé. La liste de référence doit rester suffisamment large pour couvrir : -- les conversations en MP et en canal +- les MP et les conversations en canal - le comportement des fils - le cycle de vie des actions sur les messages - les rappels Cron - le rappel de mémoire - le changement de modèle -- le transfert à un sous-agent +- le transfert vers un sous-agent - la lecture du dépôt et de la documentation - une petite tâche de build comme Lobster Invaders +## Voies avec fournisseur simulé + +`qa suite` dispose de deux voies locales avec fournisseur simulé : + +- `mock-openai` est le mock OpenClaw sensible aux scénarios. Il reste la + voie simulée déterministe par défaut pour la QA adossée au dépôt et les gates de parité. +- `aimock` démarre un serveur fournisseur adossé à AIMock pour une couverture expérimentale + de protocole, de fixtures, d’enregistrement/relecture et de chaos. Il est additionnel et ne + remplace pas le répartiteur de scénarios `mock-openai`. + +L’implémentation des voies fournisseur se trouve sous `extensions/qa-lab/src/providers/`. +Chaque fournisseur possède ses valeurs par défaut, le démarrage de serveur local, la configuration +du modèle Gateway, les besoins de préparation du profil d’auth, et les indicateurs de capacités live/simulées. +Le code partagé de suite et Gateway doit passer par le registre des fournisseurs plutôt que de +se brancher selon les noms de fournisseurs. + ## Adaptateurs de transport -`qa-lab` possède une interface de transport générique pour les scénarios QA Markdown. -`qa-channel` est le premier adaptateur sur cette interface, mais l’objectif de conception est plus large : -les futurs canaux réels ou synthétiques devraient s’intégrer au même exécuteur de suite +`qa-lab` possède un point d’intégration de transport générique pour les scénarios QA Markdown. +`qa-channel` est le premier adaptateur sur ce point d’intégration, mais l’objectif de conception est plus large : +les futurs canaux réels ou synthétiques doivent pouvoir se brancher sur le même exécuteur de suite au lieu d’ajouter un exécuteur QA spécifique au transport. Au niveau de l’architecture, la séparation est la suivante : -- `qa-lab` gère l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et le reporting. -- l’adaptateur de transport gère la configuration Gateway, l’état de préparation, l’observation des entrées et sorties, les actions de transport et l’état de transport normalisé. -- les fichiers de scénarios Markdown sous `qa/scenarios/` définissent l’exécution du test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute. +- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et les rapports. +- l’adaptateur de transport possède la configuration Gateway, l’état prêt, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé. +- les fichiers de scénarios Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute. -Les consignes d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans +Les directives d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans [Testing](/fr/help/testing#adding-a-channel-to-qa). ## Rapports @@ -181,10 +197,10 @@ Le rapport doit répondre aux questions suivantes : - Ce qui a fonctionné - Ce qui a échoué - Ce qui est resté bloqué -- Quels scénarios de suivi valent la peine d’être ajoutés +- Quels scénarios de suivi méritent d’être ajoutés -Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs -références de modèles en direct et écrivez un rapport Markdown évalué : +Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles live +et écrivez un rapport Markdown évalué : ```bash pnpm openclaw qa character-eval \ @@ -203,36 +219,36 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -La commande exécute des processus enfants Gateway QA locaux, pas Docker. Les scénarios d’évaluation de caractère -doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur ordinaires -comme la discussion, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le -modèle candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande préserve chaque -transcription complète, enregistre des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec -un raisonnement `xhigh` de classer les exécutions selon leur naturel, leur ambiance et leur humour. -Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : l’invite du juge reçoit toujours -chaque transcription et le statut d’exécution, mais les références candidates sont remplacées par des -étiquettes neutres telles que `candidate-01` ; le rapport réassocie les classements aux références réelles après +La commande exécute des processus enfants Gateway QA locaux, pas Docker. Les +scénarios d’évaluation de caractère doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur +ordinaires tels que la conversation, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle +candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande conserve chaque +transcription complète, enregistre les statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec +un raisonnement `xhigh` de classer les exécutions selon le naturel, l’ambiance et l’humour. +Utilisez `--blind-judge-models` lors de la comparaison entre fournisseurs : l’invite du juge reçoit toujours +chaque transcription et l’état d’exécution, mais les références candidates sont remplacées par des +étiquettes neutres telles que `candidate-01` ; le rapport réassocie les classements aux vraies références après l’analyse. -Les exécutions candidates utilisent par défaut le niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui +Les exécutions candidates utilisent par défaut un niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui le prennent en charge. Remplacez un candidat spécifique en ligne avec -`--model provider/model,thinking=`. `--thinking ` définit toujours un -repli global, et l’ancienne forme `--model-thinking ` est +`--model provider/model,thinking=`. `--thinking ` définit toujours une +valeur de repli globale, et l’ancienne forme `--model-thinking ` est conservée pour compatibilité. -Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé lorsque -le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un -candidat ou juge unique nécessite un remplacement. Passez `--fast` uniquement si vous souhaitez -forcer le mode rapide pour chaque modèle candidat. Les durées des candidats et des juges sont -enregistrées dans le rapport pour l’analyse comparative, mais les invites des juges indiquent explicitement -de ne pas classer en fonction de la vitesse. +Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé là +où le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un +candidat ou juge particulier a besoin d’un remplacement. Passez `--fast` uniquement lorsque vous souhaitez +forcer le mode rapide pour tous les modèles candidats. Les durées des candidats et des juges sont +enregistrées dans le rapport pour l’analyse de benchmark, mais les invites des juges indiquent explicitement +de ne pas classer selon la vitesse. Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une concurrence de 16. Réduisez -`--concurrency` ou `--judge-concurrency` lorsque les limites des fournisseurs ou la pression locale sur Gateway -rendent une exécution trop bruyante. -Lorsqu’aucun `--model` candidat n’est transmis, l’évaluation de caractère utilise par défaut +`--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression sur le Gateway local +rendent une exécution trop bruitée. +Lorsqu’aucun `--model` candidat n’est fourni, l’évaluation de caractère utilise par défaut `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, -`moonshot/kimi-k2.5` et -`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est transmis. -Lorsqu’aucun `--judge-model` n’est transmis, les juges utilisent par défaut +`moonshot/kimi-k2.5`, et +`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est fourni. +Lorsqu’aucun `--judge-model` n’est fourni, les juges utilisent par défaut `openai/gpt-5.4,thinking=xhigh,fast` et `anthropic/claude-opus-4-6,thinking=high`. diff --git a/docs/fr/help/testing.md b/docs/fr/help/testing.md index 8249211d8..cb618a95a 100644 --- a/docs/fr/help/testing.md +++ b/docs/fr/help/testing.md @@ -1,24 +1,24 @@ --- read_when: - - Exécuter les tests en local ou dans CI - - Ajouter des tests de régression pour les bugs de modèle/fournisseur - - Déboguer le comportement de Gateway et de l’agent -summary: 'Kit de test : suites unitaires/e2e/live, exécuteurs Docker, et ce que couvre chaque test' -title: Testირება + - Exécution des tests localement ou en CI + - Ajout de tests de régression pour les bugs de modèle/fournisseur + - Débogage du comportement de Gateway + agent +summary: 'Kit de test : suites unitaires/e2e/live, exécuteurs Docker et ce que couvre chaque test' +title: Tests x-i18n: - generated_at: "2026-04-16T21:51:25Z" + generated_at: "2026-04-17T06:57:43Z" model: gpt-5.4 provider: openai - source_hash: af2bc0e9b5e08ca3119806d355b517290f6078fda430109e7a0b153586215e34 + source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 source_path: help/testing.md workflow: 15 --- # Tests -OpenClaw propose trois suites Vitest (unitaire/intégration, e2e, live) et un petit ensemble d’exécuteurs Docker. +OpenClaw comporte trois suites Vitest (unitaire/intégration, e2e, live) ainsi qu’un petit ensemble d’exécuteurs Docker. -Cette documentation est un guide « comment nous testons » : +Ce document est un guide « comment nous testons » : - Ce que couvre chaque suite (et ce qu’elle ne couvre délibérément _pas_) - Quelles commandes exécuter pour les workflows courants (local, avant push, débogage) @@ -29,76 +29,80 @@ Cette documentation est un guide « comment nous testons » : La plupart du temps : -- Porte complète (attendue avant push) : `pnpm build && pnpm check && pnpm test` -- Exécution locale plus rapide de la suite complète sur une machine bien dimensionnée : `pnpm test:max` -- Boucle de surveillance Vitest directe : `pnpm test:watch` -- Le ciblage direct de fichier route maintenant aussi les chemins d’extension/de canal : `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Préférez d’abord les exécutions ciblées quand vous itérez sur un seul échec. +- Barrière complète (attendue avant un push) : `pnpm build && pnpm check && pnpm test` +- Exécution locale plus rapide de la suite complète sur une machine confortable : `pnpm test:max` +- Boucle watch Vitest directe : `pnpm test:watch` +- Le ciblage direct de fichier route désormais aussi les chemins d’extension/canal : `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Préférez d’abord les exécutions ciblées lorsque vous itérez sur un seul échec. - Site QA adossé à Docker : `pnpm qa:lab:up` - Voie QA adossée à une VM Linux : `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quand vous modifiez des tests ou voulez plus de confiance : +Quand vous modifiez des tests ou souhaitez plus de confiance : -- Porte de couverture : `pnpm test:coverage` +- Barrière de couverture : `pnpm test:coverage` - Suite E2E : `pnpm test:e2e` Quand vous déboguez de vrais fournisseurs/modèles (nécessite de vrais identifiants) : -- Suite live (modèles + sondes d’outils/images Gateway) : `pnpm test:live` -- Cibler silencieusement un seul fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (modèles + sondes Gateway outil/image) : `pnpm test:live` +- Cibler silencieusement un fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Astuce : quand vous n’avez besoin que d’un seul cas en échec, préférez restreindre les tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous. +Astuce : lorsque vous n’avez besoin que d’un seul cas en échec, préférez restreindre les tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous. ## Exécuteurs spécifiques à la QA -Ces commandes se trouvent à côté des suites de test principales quand vous avez besoin du réalisme de qa-lab : +Ces commandes se trouvent à côté des suites de test principales lorsque vous avez besoin du réalisme de qa-lab : - `pnpm openclaw qa suite` - - Exécute directement sur l’hôte des scénarios QA adossés au dépôt. + - Exécute directement sur l’hôte les scénarios QA adossés au dépôt. - Exécute par défaut plusieurs scénarios sélectionnés en parallèle avec des workers Gateway isolés, jusqu’à 64 workers ou au nombre de scénarios sélectionnés. Utilisez `--concurrency ` pour ajuster le nombre de workers, ou `--concurrency 1` pour l’ancienne voie sérielle. + - Prend en charge les modes fournisseur `live-frontier`, `mock-openai` et `aimock`. + `aimock` démarre un serveur fournisseur local adossé à AIMock pour une couverture expérimentale de fixtures et de moqueries de protocole, sans remplacer la voie `mock-openai` orientée scénario. - `pnpm openclaw qa suite --runner multipass` - Exécute la même suite QA dans une VM Linux Multipass jetable. - Conserve le même comportement de sélection de scénarios que `qa suite` sur l’hôte. - - Réutilise les mêmes drapeaux de sélection de fournisseur/modèle que `qa suite`. - - Les exécutions live transmettent les entrées d’authentification QA prises en charge qui sont pratiques pour l’invité : - clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA, et `CODEX_HOME` si présent. - - Les répertoires de sortie doivent rester sous la racine du dépôt pour que l’invité puisse réécrire via l’espace de travail monté. - - Écrit le rapport QA normal + le résumé ainsi que les logs Multipass sous + - Réutilise les mêmes drapeaux de sélection fournisseur/modèle que `qa suite`. + - Les exécutions live transmettent les entrées d’authentification QA prises en charge et pratiques pour l’invité : + clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA et `CODEX_HOME` lorsqu’il est présent. + - Les répertoires de sortie doivent rester sous la racine du dépôt afin que l’invité puisse y réécrire via l’espace de travail monté. + - Écrit le rapport + résumé QA habituels ainsi que les journaux Multipass dans `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Démarre le site QA adossé à Docker pour le travail QA de type opérateur. + - Démarre le site QA adossé à Docker pour un travail QA de type opérateur. +- `pnpm openclaw qa aimock` + - Démarre uniquement le serveur fournisseur AIMock local pour des tests de fumée directs du protocole. - `pnpm openclaw qa matrix` - Exécute la voie QA live Matrix contre un homeserver Tuwunel jetable adossé à Docker. - - Cet hôte QA est pour le dépôt/le développement uniquement aujourd’hui. Les installations OpenClaw packagées n’incluent pas `qa-lab`, elles n’exposent donc pas `openclaw qa`. - - Les extractions du dépôt chargent directement l’exécuteur intégré ; aucune étape d’installation de plugin séparée n’est nécessaire. - - Approvisionne trois utilisateurs Matrix temporaires (`driver`, `sut`, `observer`) ainsi qu’une salle privée, puis démarre un processus enfant de Gateway QA avec le vrai plugin Matrix comme transport SUT. - - Utilise par défaut l’image Tuwunel stable épinglée `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Remplacez-la avec `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quand vous devez tester une autre image. + - Cet hôte QA est aujourd’hui réservé au dépôt/au développement. Les installations OpenClaw packagées n’embarquent pas `qa-lab`, elles n’exposent donc pas `openclaw qa`. + - Les clones du dépôt chargent directement l’exécuteur groupé ; aucune étape d’installation de Plugin séparée n’est nécessaire. + - Provisionne trois utilisateurs Matrix temporaires (`driver`, `sut`, `observer`) plus une salle privée, puis démarre un processus enfant QA Gateway avec le vrai Plugin Matrix comme transport du SUT. + - Utilise par défaut l’image Tuwunel stable épinglée `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Remplacez-la avec `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` lorsque vous devez tester une autre image. - Matrix n’expose pas de drapeaux partagés de source d’identifiants, car la voie provisionne localement des utilisateurs jetables. - - Écrit un rapport QA Matrix, un résumé, un artefact observed-events, et un log de sortie combiné stdout/stderr sous `.artifacts/qa-e2e/...`. + - Écrit un rapport QA Matrix, un résumé, un artefact des événements observés et un journal combiné stdout/stderr dans `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Exécute la voie QA live Telegram contre un groupe privé réel en utilisant les jetons de bot du driver et du SUT depuis l’environnement. - - Nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’identifiant du groupe doit être l’identifiant numérique du chat Telegram. - - Prend en charge `--credential-source convex` pour des identifiants partagés mutualisés. Utilisez le mode env par défaut, ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` pour utiliser des baux mutualisés. - - Nécessite deux bots distincts dans le même groupe privé, avec le bot SUT exposant un nom d’utilisateur Telegram. + - Exécute la voie QA live Telegram contre un vrai groupe privé à l’aide des jetons de bot driver et SUT issus de l’environnement. + - Nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’identifiant du groupe doit être l’identifiant numérique du chat Telegram. + - Prend en charge `--credential-source convex` pour des identifiants mutualisés partagés. Utilisez le mode environnement par défaut, ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` pour opter pour des baux mutualisés. + - Nécessite deux bots distincts dans le même groupe privé, le bot SUT devant exposer un nom d’utilisateur Telegram. - Pour une observation stable entre bots, activez le mode de communication bot-à-bot dans `@BotFather` pour les deux bots et assurez-vous que le bot driver peut observer le trafic des bots du groupe. - - Écrit un rapport QA Telegram, un résumé et un artefact observed-messages sous `.artifacts/qa-e2e/...`. + - Écrit un rapport QA Telegram, un résumé et un artefact des messages observés dans `.artifacts/qa-e2e/...`. -Les voies de transport live partagent un contrat standard pour éviter que les nouveaux transports ne divergent : +Les voies de transport live partagent un contrat standard unique afin que les nouveaux transports ne divergent pas : `qa-channel` reste la suite QA synthétique large et ne fait pas partie de la matrice de couverture des transports live. -| Voie | Canary | Filtrage des mentions | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi de fil | Isolation du fil | Observation des réactions | Commande d’aide | -| -------- | ------ | --------------------- | -------------------------------- | ------------------------- | ------------------------- | ------------ | ---------------- | ------------------------- | --------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Voie | Canary | Filtrage des mentions | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi de fil | Isolation des fils | Observation des réactions | Commande d’aide | +| -------- | ------ | --------------------- | -------------------------------- | ------------------------- | ------------------------- | ------------ | ------------------ | ------------------------- | --------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Identifiants Telegram partagés via Convex (v1) -Quand `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) est activé pour -`openclaw qa telegram`, QA lab acquiert un bail exclusif depuis un pool adossé à Convex, envoie un Heartbeat pour -ce bail pendant l’exécution de la voie, puis libère le bail à l’arrêt. +Lorsque `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) est activé pour +`openclaw qa telegram`, QA lab acquiert un bail exclusif depuis un pool adossé à Convex, envoie un Heartbeat +de ce bail pendant l’exécution de la voie, puis libère le bail à l’arrêt. -Squelette de projet Convex de référence : +Structure de projet Convex de référence : - `qa/convex-credential-broker/` @@ -108,9 +112,9 @@ Variables d’environnement requises : - Un secret pour le rôle sélectionné : - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` pour `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` pour `ci` -- Sélection du rôle des identifiants : +- Sélection du rôle d’identifiant : - CLI : `--credential-role maintainer|ci` - - Valeur par défaut de l’environnement : `OPENCLAW_QA_CREDENTIAL_ROLE` (par défaut : `maintainer`) + - Valeur par défaut via l’environnement : `OPENCLAW_QA_CREDENTIAL_ROLE` (par défaut `maintainer`) Variables d’environnement facultatives : @@ -119,15 +123,15 @@ Variables d’environnement facultatives : - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (par défaut `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (par défaut `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (par défaut `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (identifiant de traçage facultatif) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` autorise les URL Convex `http://` de loopback pour le développement strictement local. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (identifiant de traçabilité facultatif) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` autorise les URL Convex `http://` en loopback pour le développement strictement local. `OPENCLAW_QA_CONVEX_SITE_URL` doit utiliser `https://` en fonctionnement normal. -Les commandes d’administration mainteneur (ajout/suppression/liste du pool) nécessitent +Les commandes d’administration de maintenance (ajout/suppression/liste du pool) nécessitent spécifiquement `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Aides CLI pour les mainteneurs : +Assistants CLI pour les mainteneurs : ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -142,41 +146,41 @@ Contrat de point de terminaison par défaut (`OPENCLAW_QA_CONVEX_SITE_URL` + `/q - `POST /acquire` - Requête : `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Succès : `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Épuisé / réessayable : `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Épuisé/réessayable : `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Requête : `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Succès : `{ status: "ok" }` (ou `2xx` vide) - `POST /release` - Requête : `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Succès : `{ status: "ok" }` (ou `2xx` vide) -- `POST /admin/add` (secret mainteneur uniquement) +- `POST /admin/add` (secret maintainer uniquement) - Requête : `{ kind, actorId, payload, note?, status? }` - Succès : `{ status: "ok", credential }` -- `POST /admin/remove` (secret mainteneur uniquement) +- `POST /admin/remove` (secret maintainer uniquement) - Requête : `{ credentialId, actorId }` - Succès : `{ status: "ok", changed, credential }` - Garde de bail actif : `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (secret mainteneur uniquement) +- `POST /admin/list` (secret maintainer uniquement) - Requête : `{ kind?, status?, includePayload?, limit? }` - Succès : `{ status: "ok", credentials, count }` -Structure de payload pour le type Telegram : +Forme de charge utile pour le type Telegram : - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` doit être une chaîne représentant un identifiant numérique de chat Telegram. -- `admin/add` valide cette structure pour `kind: "telegram"` et rejette les payloads mal formés. +- `groupId` doit être une chaîne correspondant à un identifiant numérique de chat Telegram. +- `admin/add` valide cette forme pour `kind: "telegram"` et rejette les charges utiles mal formées. ### Ajouter un canal à la QA -Ajouter un canal au système QA Markdown nécessite exactement deux choses : +L’ajout d’un canal au système QA Markdown nécessite exactement deux éléments : 1. Un adaptateur de transport pour le canal. -2. Un pack de scénarios qui exerce le contrat du canal. +2. Un paquet de scénarios qui exerce le contrat du canal. -N’ajoutez pas une nouvelle racine de commande QA de premier niveau quand l’hôte partagé `qa-lab` peut -gérer le flux. +N’ajoutez pas une nouvelle racine de commande QA de premier niveau lorsque l’hôte partagé `qa-lab` peut +prendre en charge le flux. -`qa-lab` gère les mécanismes d’hôte partagés : +`qa-lab` possède les mécanismes hôtes partagés : - la racine de commande `openclaw qa` - le démarrage et l’arrêt de la suite @@ -186,7 +190,7 @@ gérer le flux. - l’exécution des scénarios - les alias de compatibilité pour les anciens scénarios `qa-channel` -Les plugins d’exécuteur gèrent le contrat de transport : +Les Plugins d’exécuteur possèdent le contrat de transport : - comment `openclaw qa ` est monté sous la racine partagée `qa` - comment Gateway est configuré pour ce transport @@ -195,28 +199,28 @@ Les plugins d’exécuteur gèrent le contrat de transport : - comment les messages sortants sont observés - comment les transcriptions et l’état de transport normalisé sont exposés - comment les actions adossées au transport sont exécutées -- comment la réinitialisation ou le nettoyage spécifiques au transport sont gérés +- comment la réinitialisation ou le nettoyage spécifique au transport est géré Le seuil minimal d’adoption pour un nouveau canal est : 1. Conserver `qa-lab` comme propriétaire de la racine partagée `qa`. -2. Implémenter l’exécuteur de transport sur l’interface d’hôte partagée `qa-lab`. -3. Conserver les mécanismes spécifiques au transport dans le plugin d’exécuteur ou le harnais du canal. -4. Monter l’exécuteur sous `openclaw qa ` au lieu d’enregistrer une racine de commande concurrente. - Les plugins d’exécuteur doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. +2. Implémenter l’exécuteur de transport sur la jonction hôte partagée `qa-lab`. +3. Conserver les mécanismes spécifiques au transport dans le Plugin d’exécuteur ou le harnais du Plugin. +4. Monter l’exécuteur comme `openclaw qa ` au lieu d’enregistrer une racine de commande concurrente. + Les Plugins d’exécuteur doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. Gardez `runtime-api.ts` léger ; l’exécution paresseuse de la CLI et de l’exécuteur doit rester derrière des points d’entrée séparés. -5. Rédiger ou adapter les scénarios Markdown sous `qa/scenarios/`. -6. Utiliser les aides de scénario génériques pour les nouveaux scénarios. -7. Conserver les alias de compatibilité existants en fonctionnement, sauf si le dépôt effectue une migration intentionnelle. +5. Rédiger ou adapter des scénarios Markdown sous `qa/scenarios/`. +6. Utiliser les assistants de scénario génériques pour les nouveaux scénarios. +7. Conserver les alias de compatibilité existants, sauf si le dépôt effectue une migration intentionnelle. La règle de décision est stricte : - Si un comportement peut être exprimé une seule fois dans `qa-lab`, placez-le dans `qa-lab`. -- Si un comportement dépend d’un transport de canal, conservez-le dans ce plugin d’exécuteur ou ce harnais de plugin. -- Si un scénario nécessite une nouvelle capacité que plusieurs canaux peuvent utiliser, ajoutez une aide générique plutôt qu’une branche spécifique à un canal dans `suite.ts`. +- Si un comportement dépend d’un seul transport de canal, conservez-le dans ce Plugin d’exécuteur ou ce harnais de Plugin. +- Si un scénario nécessite une nouvelle capacité utilisable par plus d’un canal, ajoutez un assistant générique au lieu d’une branche spécifique au canal dans `suite.ts`. - Si un comportement n’a de sens que pour un seul transport, gardez le scénario spécifique à ce transport et rendez cela explicite dans le contrat du scénario. -Les noms d’aides génériques préférés pour les nouveaux scénarios sont : +Les noms d’assistants génériques préférés pour les nouveaux scénarios sont : - `waitForTransportReady` - `waitForChannelReady` @@ -239,160 +243,160 @@ Des alias de compatibilité restent disponibles pour les scénarios existants, n - `formatConversationTranscript` - `resetBus` -Les nouveaux travaux sur les canaux doivent utiliser les noms d’aide génériques. +Les nouveaux travaux sur les canaux doivent utiliser les noms d’assistants génériques. Les alias de compatibilité existent pour éviter une migration brutale, pas comme modèle pour la rédaction de nouveaux scénarios. ## Suites de test (ce qui s’exécute où) -Considérez les suites comme un « réalisme croissant » (et une fragilité/un coût croissants) : +Considérez les suites comme un « réalisme croissant » (et une instabilité/un coût croissants) : ### Unitaire / intégration (par défaut) - Commande : `pnpm test` -- Configuration : dix exécutions de fragments séquentielles (`vitest.full-*.config.ts`) sur les projets Vitest ciblés existants +- Config : dix exécutions de fragments séquentielles (`vitest.full-*.config.ts`) sur les projets Vitest ciblés existants - Fichiers : inventaires core/unit sous `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, et les tests node `ui` autorisés couverts par `vitest.unit.config.ts` - Portée : - Tests unitaires purs - - Tests d’intégration en processus (auth Gateway, routage, outillage, parsing, configuration) + - Tests d’intégration en processus (auth Gateway, routage, outillage, analyse, config) - Régressions déterministes pour des bugs connus - Attentes : - - S’exécute dans CI + - S’exécute en CI - Aucune vraie clé requise - Doit être rapide et stable - Note sur les projets : - - `pnpm test` sans ciblage exécute maintenant onze petites configurations fragmentées (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) au lieu d’un seul énorme processus projet-racine natif. Cela réduit le pic de RSS sur les machines chargées et évite que le travail auto-reply/extension n’affame les suites non liées. - - `pnpm test --watch` utilise toujours le graphe de projets racine natif `vitest.config.ts`, car une boucle de surveillance multi-fragments n’est pas pratique. - - `pnpm test`, `pnpm test:watch`, et `pnpm test:perf:imports` font passer en priorité les cibles explicites de fichier/répertoire par des voies ciblées, donc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite de payer le coût de démarrage complet du projet racine. - - `pnpm test:changed` étend les chemins git modifiés vers ces mêmes voies ciblées quand le diff ne touche que des fichiers source/test routables ; les modifications de config/setup reviennent toujours à une relance large du projet racine. - - Les tests unitaires légers à l’import depuis agents, commands, plugins, aides auto-reply, `plugin-sdk`, et zones utilitaires pures similaires passent par la voie `unit-fast`, qui ignore `test/setup-openclaw-runtime.ts` ; les fichiers stateful/lourds à l’exécution restent sur les voies existantes. - - Certains fichiers source utilitaires `plugin-sdk` et `commands` sélectionnés font aussi correspondre les exécutions en mode changed à des tests frères explicites dans ces voies légères, afin que les modifications d’aides évitent de relancer toute la suite lourde pour ce répertoire. - - `auto-reply` a maintenant trois compartiments dédiés : aides core de premier niveau, tests d’intégration `reply.*` de premier niveau, et le sous-arbre `src/auto-reply/reply/**`. Cela garde le travail de harnais de réponse le plus lourd à l’écart des tests bon marché de statut/bloc/token. + - `pnpm test` non ciblé exécute désormais onze petites configs fragmentées (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) au lieu d’un seul énorme processus racine natif. Cela réduit le pic de RSS sur les machines chargées et évite que le travail `auto-reply`/extension n’affame des suites sans rapport. + - `pnpm test --watch` utilise toujours le graphe de projets natif racine `vitest.config.ts`, car une boucle watch multi-fragments n’est pas pratique. + - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` font d’abord passer les cibles explicites de fichier/répertoire par des voies ciblées, afin que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite le coût de démarrage complet du projet racine. + - `pnpm test:changed` développe les chemins git modifiés dans ces mêmes voies ciblées lorsque le diff ne touche que des fichiers source/test routables ; les modifications de config/setup reviennent toujours à une relance large du projet racine. + - Les tests unitaires légers en imports provenant des agents, commandes, plugins, assistants `auto-reply`, `plugin-sdk` et zones utilitaires pures similaires passent par la voie `unit-fast`, qui ignore `test/setup-openclaw-runtime.ts` ; les fichiers à état/lourds à l’exécution restent sur les voies existantes. + - Certains fichiers source assistants `plugin-sdk` et `commands` font aussi correspondre les exécutions en mode changed à des tests frères explicites dans ces voies légères, afin que les modifications d’assistants évitent de relancer toute la suite lourde pour ce répertoire. + - `auto-reply` possède maintenant trois compartiments dédiés : assistants core de premier niveau, tests d’intégration `reply.*` de premier niveau, et le sous-arbre `src/auto-reply/reply/**`. Cela garde le travail le plus lourd du harnais de réponse hors des tests bon marché de statut/fragment/token. - Note sur l’exécuteur embarqué : - - Quand vous modifiez les entrées de découverte des outils de message ou le contexte d’exécution de Compaction, + - Lorsque vous modifiez les entrées de découverte des message-tools ou le contexte d’exécution de Compaction, conservez les deux niveaux de couverture. - - Ajoutez des régressions d’aides ciblées pour les frontières pures de routage/normalisation. - - Gardez également saines les suites d’intégration de l’exécuteur embarqué : + - Ajoutez des régressions d’assistants ciblées pour les frontières pures de routage/normalisation. + - Gardez aussi les suites d’intégration de l’exécuteur embarqué en bon état : `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, et `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ces suites vérifient que les identifiants ciblés et le comportement de Compaction passent toujours - par les vrais chemins `run.ts` / `compact.ts` ; des tests d’aides seuls ne sont pas + - Ces suites vérifient que les identifiants ciblés et le comportement de Compaction continuent bien de circuler + dans les vrais chemins `run.ts` / `compact.ts` ; des tests d’assistants seuls ne constituent pas un substitut suffisant à ces chemins d’intégration. - Note sur le pool : - - La configuration Vitest de base utilise désormais `threads` par défaut. - - La configuration Vitest partagée fixe aussi `isolate: false` et utilise l’exécuteur non isolé sur les projets racine, e2e et live. - - La voie UI racine conserve sa configuration `jsdom` et son optimiseur, mais s’exécute désormais aussi sur l’exécuteur partagé non isolé. - - Chaque fragment `pnpm test` hérite des mêmes valeurs par défaut `threads` + `isolate: false` depuis la configuration Vitest partagée. - - Le lanceur partagé `scripts/run-vitest.mjs` ajoute maintenant aussi `--no-maglev` par défaut pour les processus enfant Node de Vitest afin de réduire l’agitation de compilation V8 pendant les grosses exécutions locales. Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si vous devez comparer avec le comportement V8 standard. + - La config Vitest de base utilise désormais `threads` par défaut. + - La config Vitest partagée fixe aussi `isolate: false` et utilise l’exécuteur non isolé sur les projets racine, e2e et live. + - La voie UI racine conserve son setup `jsdom` et son optimiseur, mais s’exécute maintenant elle aussi sur l’exécuteur partagé non isolé. + - Chaque fragment `pnpm test` hérite des mêmes valeurs par défaut `threads` + `isolate: false` depuis la config Vitest partagée. + - Le lanceur partagé `scripts/run-vitest.mjs` ajoute aussi désormais `--no-maglev` par défaut pour les processus Node enfants de Vitest afin de réduire l’agitation de compilation V8 lors des grosses exécutions locales. Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si vous devez comparer avec le comportement V8 standard. - Note sur l’itération locale rapide : - `pnpm test:changed` passe par des voies ciblées lorsque les chemins modifiés correspondent proprement à une suite plus petite. - `pnpm test:max` et `pnpm test:changed:max` conservent le même comportement de routage, simplement avec une limite de workers plus élevée. - - L’auto-dimensionnement local des workers est maintenant volontairement conservateur et réduit aussi la charge quand la moyenne de charge de l’hôte est déjà élevée, afin que plusieurs exécutions Vitest concurrentes fassent moins de dégâts par défaut. - - La configuration Vitest de base marque les fichiers de projet/configuration comme `forceRerunTriggers` afin que les relances en mode changed restent correctes quand le câblage des tests change. - - La configuration garde `OPENCLAW_VITEST_FS_MODULE_CACHE` activé sur les hôtes pris en charge ; définissez `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si vous voulez un emplacement de cache explicite pour du profilage direct. -- Note de débogage des performances : - - `pnpm test:perf:imports` active les rapports de durée d’import Vitest ainsi qu’une sortie détaillée des imports. - - `pnpm test:perf:imports:changed` applique cette même vue de profilage aux fichiers modifiés depuis `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compare `test:changed` routé avec le chemin natif projet-racine pour ce diff validé et affiche le temps mur ainsi que le RSS max macOS. -- `pnpm test:perf:changed:bench -- --worktree` mesure l’arbre de travail courant en faisant passer la liste des fichiers modifiés par `scripts/test-projects.mjs` et la configuration Vitest racine. - - `pnpm test:perf:profile:main` écrit un profil CPU du thread principal pour les coûts de démarrage et de transformation Vitest/Vite. + - L’auto-dimensionnement local des workers est désormais volontairement conservateur et ralentit aussi lorsque la charge moyenne de l’hôte est déjà élevée, afin que plusieurs exécutions Vitest concurrentes causent moins de dégâts par défaut. + - La config Vitest de base marque les fichiers projets/config comme `forceRerunTriggers` afin que les relances en mode changed restent correctes lorsque le câblage des tests change. + - La config conserve `OPENCLAW_VITEST_FS_MODULE_CACHE` activé sur les hôtes pris en charge ; définissez `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si vous voulez un emplacement de cache explicite pour du profilage direct. +- Note sur le débogage des performances : + - `pnpm test:perf:imports` active le rapport de durée d’import Vitest ainsi qu’une sortie détaillée des imports. + - `pnpm test:perf:imports:changed` limite cette même vue de profilage aux fichiers modifiés depuis `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compare `test:changed` routé au chemin natif du projet racine pour ce diff validé et affiche le temps mur ainsi que le RSS max macOS. +- `pnpm test:perf:changed:bench -- --worktree` mesure l’arbre de travail sale actuel en faisant passer la liste des fichiers modifiés par `scripts/test-projects.mjs` et la config Vitest racine. + - `pnpm test:perf:profile:main` écrit un profil CPU du thread principal pour les coûts de démarrage et de transformation de Vitest/Vite. - `pnpm test:perf:profile:runner` écrit des profils CPU+tas de l’exécuteur pour la suite unitaire avec le parallélisme de fichiers désactivé. -### E2E (smoke Gateway) +### E2E (test de fumée Gateway) - Commande : `pnpm test:e2e` -- Configuration : `vitest.e2e.config.ts` +- Config : `vitest.e2e.config.ts` - Fichiers : `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Valeurs d’exécution par défaut : - - Utilise `threads` de Vitest avec `isolate: false`, comme le reste du dépôt. + - Utilise Vitest `threads` avec `isolate: false`, comme le reste du dépôt. - Utilise des workers adaptatifs (CI : jusqu’à 2, local : 1 par défaut). - - S’exécute en mode silencieux par défaut pour réduire le coût des E/S console. + - S’exécute en mode silencieux par défaut afin de réduire le coût des E/S console. - Remplacements utiles : - `OPENCLAW_E2E_WORKERS=` pour forcer le nombre de workers (plafonné à 16). - - `OPENCLAW_E2E_VERBOSE=1` pour réactiver la sortie console détaillée. + - `OPENCLAW_E2E_VERBOSE=1` pour réactiver une sortie console verbeuse. - Portée : - Comportement end-to-end Gateway multi-instance - Surfaces WebSocket/HTTP, appairage de nœuds et réseau plus lourd - Attentes : - - S’exécute dans CI (lorsqu’activé dans le pipeline) + - S’exécute en CI (quand activé dans le pipeline) - Aucune vraie clé requise - Plus de pièces mobiles que les tests unitaires (peut être plus lent) -### E2E : smoke du backend OpenShell +### E2E : test de fumée du backend OpenShell - Commande : `pnpm test:e2e:openshell` - Fichier : `test/openshell-sandbox.e2e.test.ts` - Portée : - - Démarre un Gateway OpenShell isolé sur l’hôte via Docker - - Crée un sandbox à partir d’un Dockerfile local temporaire - - Exerce le backend OpenShell d’OpenClaw via de vrais `sandbox ssh-config` + exécution SSH - - Vérifie le comportement du système de fichiers canonique distant via le pont fs du sandbox + - Démarre via Docker une Gateway OpenShell isolée sur l’hôte + - Crée un bac à sable à partir d’un Dockerfile local temporaire + - Exerce le backend OpenShell d’OpenClaw via un vrai `sandbox ssh-config` + exécution SSH + - Vérifie le comportement du système de fichiers canonique distant via le pont fs du bac à sable - Attentes : - - Opt-in uniquement ; ne fait pas partie de l’exécution par défaut `pnpm test:e2e` - - Nécessite une CLI `openshell` locale ainsi qu’un démon Docker fonctionnel - - Utilise `HOME` / `XDG_CONFIG_HOME` isolés, puis détruit le Gateway de test et le sandbox + - Uniquement sur activation volontaire ; ne fait pas partie de l’exécution par défaut `pnpm test:e2e` + - Nécessite une CLI `openshell` locale ainsi qu’un démon Docker opérationnel + - Utilise un `HOME` / `XDG_CONFIG_HOME` isolé, puis détruit la Gateway de test et le bac à sable - Remplacements utiles : - `OPENCLAW_E2E_OPENSHELL=1` pour activer le test lors de l’exécution manuelle de la suite e2e plus large - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` pour pointer vers un binaire CLI non standard ou un script wrapper + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` pour pointer vers un binaire CLI non par défaut ou un script wrapper ### Live (vrais fournisseurs + vrais modèles) - Commande : `pnpm test:live` -- Configuration : `vitest.live.config.ts` +- Config : `vitest.live.config.ts` - Fichiers : `src/**/*.live.test.ts` - Par défaut : **activé** par `pnpm test:live` (définit `OPENCLAW_LIVE_TEST=1`) - Portée : - - « Est-ce que ce fournisseur/modèle fonctionne vraiment _aujourd’hui_ avec de vrais identifiants ? » - - Détecter les changements de format de fournisseur, les particularités d’appel d’outils, les problèmes d’authentification et le comportement de limite de débit + - « Ce fournisseur/modèle fonctionne-t-il réellement _aujourd’hui_ avec de vrais identifiants ? » + - Détecter les changements de format fournisseur, les particularités d’appel d’outils, les problèmes d’authentification et le comportement de limitation de débit - Attentes : - - Pas stable pour CI par conception (vrais réseaux, vraies politiques de fournisseur, quotas, pannes) + - Pas stable en CI par conception (vrais réseaux, vraies politiques fournisseur, quotas, indisponibilités) - Coûte de l’argent / consomme des limites de débit - Préférez exécuter des sous-ensembles restreints plutôt que « tout » - Les exécutions live chargent `~/.profile` pour récupérer les clés API manquantes. -- Par défaut, les exécutions live isolent toujours `HOME` et copient les éléments de configuration/authentification dans un home de test temporaire afin que les fixtures unitaires ne puissent pas modifier votre vrai `~/.openclaw`. -- Définissez `OPENCLAW_LIVE_USE_REAL_HOME=1` uniquement lorsque vous avez intentionnellement besoin que les tests live utilisent votre vrai répertoire home. -- `pnpm test:live` utilise maintenant par défaut un mode plus discret : il conserve la sortie de progression `[live] ...`, mais masque l’avis supplémentaire `~/.profile` et coupe les logs de bootstrap Gateway / le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez récupérer les logs complets de démarrage. -- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` avec un format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou un remplacement par live via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient sur les réponses de limitation de débit. +- Par défaut, les exécutions live isolent toujours `HOME` et copient le matériel de config/auth vers un répertoire personnel de test temporaire afin que les fixtures unitaires ne puissent pas modifier votre vrai `~/.openclaw`. +- Définissez `OPENCLAW_LIVE_USE_REAL_HOME=1` uniquement lorsque vous voulez intentionnellement que les tests live utilisent votre vrai répertoire personnel. +- `pnpm test:live` utilise désormais par défaut un mode plus silencieux : il conserve la sortie de progression `[live] ...`, mais masque l’avis supplémentaire `~/.profile` et coupe les journaux de bootstrap Gateway/le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez récupérer les journaux de démarrage complets. +- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` au format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou un remplacement par live via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient sur les réponses de limitation de débit. - Sortie de progression/Heartbeat : - - Les suites live émettent maintenant des lignes de progression vers stderr afin que les longs appels fournisseur soient visiblement actifs même lorsque la capture console Vitest est silencieuse. - - `vitest.live.config.ts` désactive l’interception console de Vitest afin que les lignes de progression fournisseur/Gateway soient diffusées immédiatement pendant les exécutions live. - - Ajustez les Heartbeat de modèle direct avec `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajustez les Heartbeat Gateway/sonde avec `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Les suites live émettent désormais des lignes de progression sur stderr afin que les longs appels fournisseur restent visiblement actifs même lorsque la capture console de Vitest est silencieuse. + - `vitest.live.config.ts` désactive l’interception de console par Vitest afin que les lignes de progression fournisseur/Gateway soient diffusées immédiatement pendant les exécutions live. + - Ajustez les Heartbeat des modèles directs avec `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Ajustez les Heartbeat Gateway/sondes avec `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Quelle suite dois-je exécuter ? Utilisez ce tableau de décision : -- Modification de logique/tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié) -- Modification du réseau Gateway / du protocole WS / de l’appairage : ajoutez `pnpm test:e2e` -- Débogage de « mon bot est en panne » / d’échecs spécifiques au fournisseur / d’appels d’outils : exécutez un `pnpm test:live` restreint +- Modifier de la logique/des tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié) +- Toucher au réseau Gateway / au protocole WS / à l’appairage : ajoutez `pnpm test:e2e` +- Déboguer « mon bot est hors service » / des échecs spécifiques à un fournisseur / l’appel d’outils : exécutez un `pnpm test:live` restreint ## Live : balayage des capacités du nœud Android - Test : `src/gateway/android-node.capabilities.live.test.ts` - Script : `pnpm android:test:integration` -- Objectif : invoquer **chaque commande actuellement annoncée** par un nœud Android connecté et vérifier le comportement du contrat de commande. +- Objectif : invoquer **chaque commande actuellement annoncée** par un nœud Android connecté et vérifier le comportement contractuel de la commande. - Portée : - - Configuration préalable/manuelle (la suite n’installe pas, n’exécute pas et n’appaire pas l’application). - - Validation Gateway `node.invoke` commande par commande pour le nœud Android sélectionné. + - Préconfiguration/manuelle (la suite n’installe pas, n’exécute pas et n’appaire pas l’application). + - Validation `node.invoke` Gateway commande par commande pour le nœud Android sélectionné. - Préconfiguration requise : - - Application Android déjà connectée et appairée à Gateway. + - Application Android déjà connectée + appairée à la Gateway. - Application maintenue au premier plan. - - Permissions/consentement de capture accordés pour les capacités que vous attendez de voir réussir. -- Remplacements de cible facultatifs : + - Permissions/consentement de capture accordés pour les capacités que vous attendez comme réussies. +- Remplacements facultatifs de cible : - `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Détails complets de configuration Android : [Application Android](/fr/platforms/android) +- Détails complets de la configuration Android : [Application Android](/fr/platforms/android) -## Live : smoke des modèles (clés de profil) +## Live : test de fumée des modèles (clés de profil) -Les tests live sont divisés en deux couches afin d’isoler les échecs : +Les tests live sont divisés en deux couches afin que nous puissions isoler les échecs : - « Modèle direct » nous indique si le fournisseur/modèle peut répondre tout court avec la clé donnée. -- « Smoke Gateway » nous indique si le pipeline complet Gateway+agent fonctionne pour ce modèle (sessions, historique, outils, politique sandbox, etc.). +- « Test de fumée Gateway » nous indique si le pipeline complet Gateway+agent fonctionne pour ce modèle (sessions, historique, outils, politique de bac à sable, etc.). -### Couche 1 : complétion de modèle directe (sans Gateway) +### Couche 1 : complétion directe du modèle (sans Gateway) - Test : `src/agents/models.profiles.live.test.ts` - Objectif : @@ -401,55 +405,55 @@ Les tests live sont divisés en deux couches afin d’isoler les échecs : - Exécuter une petite complétion par modèle (et des régressions ciblées si nécessaire) - Comment l’activer : - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement) -- Définissez `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias de modern) pour exécuter réellement cette suite ; sinon elle est ignorée afin de garder `pnpm test:live` centré sur le smoke Gateway +- Définissez `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias de modern) pour réellement exécuter cette suite ; sinon elle est ignorée afin de garder `pnpm test:live` centré sur le test de fumée Gateway - Comment sélectionner les modèles : - `OPENCLAW_LIVE_MODELS=modern` pour exécuter la liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` est un alias de la liste d’autorisation moderne - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (liste d’autorisation séparée par des virgules) - - Les balayages modern/all utilisent par défaut une limite sélectionnée à fort signal ; définissez `OPENCLAW_LIVE_MAX_MODELS=0` pour un balayage modern exhaustif ou une valeur positive pour une limite plus petite. + - Les balayages modern/all utilisent par défaut un plafond curaté à fort signal ; définissez `OPENCLAW_LIVE_MAX_MODELS=0` pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus petit. - Comment sélectionner les fournisseurs : - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (liste d’autorisation séparée par des virgules) - D’où viennent les clés : - - Par défaut : magasin de profils et replis environnementaux + - Par défaut : magasin de profils et solutions de repli via l’environnement - Définissez `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour imposer **uniquement le magasin de profils** - Pourquoi cela existe : - - Sépare « l’API fournisseur est cassée / la clé est invalide » de « le pipeline d’agent Gateway est cassé » - - Contient de petites régressions isolées (exemple : rejouage du raisonnement OpenAI Responses/Codex Responses + flux d’appels d’outils) + - Sépare « l’API du fournisseur est cassée / la clé est invalide » de « le pipeline d’agent Gateway est cassé » + - Contient de petites régressions isolées (exemple : rejeu de raisonnement OpenAI Responses/Codex Responses + flux d’appel d’outils) -### Couche 2 : smoke Gateway + agent de développement (ce que fait réellement "@openclaw") +### Couche 2 : test de fumée Gateway + agent de développement (ce que fait réellement « @openclaw ») - Test : `src/gateway/gateway-models.profiles.live.test.ts` - Objectif : - - Démarrer un Gateway en processus - - Créer/modifier une session `agent:dev:*` (remplacement de modèle par exécution) + - Démarrer une Gateway en processus + - Créer/modifier une session `agent:dev:*` (remplacement de modèle à chaque exécution) - Itérer sur les modèles avec clés et vérifier : - - réponse « pertinente » (sans outils) - - le fonctionnement d’une vraie invocation d’outil (sonde de lecture) - - des sondes d’outils supplémentaires facultatives (sonde exec+lecture) - - que les chemins de régression OpenAI (appel d’outil seul → suivi) continuent de fonctionner -- Détails des sondes (pour pouvoir expliquer rapidement les échecs) : + - réponse « significative » (sans outils) + - un vrai appel d’outil fonctionne (sonde de lecture) + - sondes d’outils supplémentaires facultatives (sonde exec+read) + - les chemins de régression OpenAI (tool-call-only → suivi) continuent de fonctionner +- Détails des sondes (afin d’expliquer rapidement les échecs) : - sonde `read` : le test écrit un fichier nonce dans l’espace de travail et demande à l’agent de le `read` puis de renvoyer le nonce. - - sonde `exec+read` : le test demande à l’agent d’écrire un nonce dans un fichier temporaire via `exec`, puis de le relire via `read`. + - sonde `exec+read` : le test demande à l’agent d’écrire via `exec` un nonce dans un fichier temporaire, puis de le relire via `read`. - sonde d’image : le test joint un PNG généré (chat + code aléatoire) et attend du modèle qu’il renvoie `cat `. - Référence d’implémentation : `src/gateway/gateway-models.profiles.live.test.ts` et `src/gateway/live-image-probe.ts`. - Comment l’activer : - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement) - Comment sélectionner les modèles : - Par défaut : liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` est un alias de la liste d’autorisation moderne + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` est un alias pour la liste d’autorisation moderne - Ou définissez `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou une liste séparée par des virgules) pour restreindre - - Les balayages Gateway modern/all utilisent par défaut une limite sélectionnée à fort signal ; définissez `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` pour un balayage moderne exhaustif ou une valeur positive pour une limite plus petite. + - Les balayages Gateway modern/all utilisent par défaut un plafond curaté à fort signal ; définissez `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus petit. - Comment sélectionner les fournisseurs (éviter « tout OpenRouter ») : - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (liste d’autorisation séparée par des virgules) -- Les sondes d’outil + d’image sont toujours activées dans ce test live : +- Les sondes outil + image sont toujours activées dans ce test live : - sonde `read` + sonde `exec+read` (stress des outils) - - la sonde d’image s’exécute quand le modèle annonce la prise en charge de l’entrée image + - la sonde d’image s’exécute lorsque le modèle annonce la prise en charge de l’entrée image - Flux (vue d’ensemble) : - Le test génère un petit PNG avec « CAT » + un code aléatoire (`src/gateway/live-image-probe.ts`) - L’envoie via `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway parse les pièces jointes dans `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Gateway analyse les pièces jointes en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - L’agent embarqué transmet au modèle un message utilisateur multimodal - - Vérification : la réponse contient `cat` + le code (tolérance OCR : de petites erreurs sont autorisées) + - Vérification : la réponse contient `cat` + le code (tolérance OCR : petites erreurs autorisées) Astuce : pour voir ce que vous pouvez tester sur votre machine (et les identifiants exacts `provider/model`), exécutez : @@ -458,26 +462,26 @@ openclaw models list openclaw models list --json ``` -## Live : smoke du backend CLI (Claude, Codex, Gemini, ou autres CLI locales) +## Live : test de fumée du backend CLI (Claude, Codex, Gemini ou autres CLI locales) - Test : `src/gateway/gateway-cli-backend.live.test.ts` -- Objectif : valider le pipeline Gateway + agent à l’aide d’un backend CLI local, sans toucher à votre configuration par défaut. -- Les valeurs par défaut de smoke spécifiques au backend se trouvent dans la définition `cli-backend.ts` de l’extension propriétaire. +- Objectif : valider le pipeline Gateway + agent à l’aide d’un backend CLI local, sans toucher à votre config par défaut. +- Les valeurs par défaut des tests de fumée spécifiques au backend se trouvent dans la définition `cli-backend.ts` de l’extension propriétaire. - Activer : - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Valeurs par défaut : - Fournisseur/modèle par défaut : `claude-cli/claude-sonnet-4-6` - - Le comportement commande/arguments/image provient des métadonnées du plugin backend CLI propriétaire. + - Le comportement de commande/arguments/image provient des métadonnées du Plugin backend CLI propriétaire. - Remplacements facultatifs : - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` pour envoyer une vraie pièce jointe image (les chemins sont injectés dans le prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` pour transmettre les chemins de fichier image comme arguments CLI au lieu de l’injection dans le prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) pour contrôler comment les arguments image sont transmis lorsque `IMAGE_ARG` est défini. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` pour envoyer un deuxième tour et valider le flux de reprise. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` pour désactiver la sonde par défaut de continuité de même session Claude Sonnet -> Opus (définissez `1` pour la forcer lorsque le modèle sélectionné prend en charge une cible de bascule). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` pour envoyer une vraie pièce jointe image (les chemins sont injectés dans l’invite). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` pour transmettre les chemins de fichiers image comme arguments CLI au lieu de l’injection dans l’invite. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) pour contrôler la manière dont les arguments image sont transmis lorsque `IMAGE_ARG` est défini. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` pour envoyer un second tour et valider le flux de reprise. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` pour désactiver la sonde de continuité par défaut sur la même session Claude Sonnet -> Opus (définissez `1` pour la forcer lorsque le modèle sélectionné prend en charge une cible de bascule). Exemple : @@ -493,7 +497,7 @@ Recette Docker : pnpm test:docker:live-cli-backend ``` -Recettes Docker à fournisseur unique : +Recettes Docker mono-fournisseur : ```bash pnpm test:docker:live-cli-backend:claude @@ -505,27 +509,27 @@ pnpm test:docker:live-cli-backend:gemini Notes : - L’exécuteur Docker se trouve dans `scripts/test-live-cli-backend-docker.sh`. -- Il exécute le smoke live du backend CLI dans l’image Docker du dépôt en tant qu’utilisateur `node` non root. -- Il résout les métadonnées de smoke CLI depuis l’extension propriétaire, puis installe le paquet CLI Linux correspondant (`@anthropic-ai/claude-code`, `@openai/codex`, ou `@google/gemini-cli`) dans un préfixe inscriptible en cache à `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (par défaut : `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` nécessite une authentification OAuth portable à l’abonnement Claude Code via soit `~/.claude/.credentials.json` avec `claudeAiOauth.subscriptionType`, soit `CLAUDE_CODE_OAUTH_TOKEN` depuis `claude setup-token`. Il prouve d’abord `claude -p` direct dans Docker, puis exécute deux tours Gateway backend CLI sans conserver les variables d’environnement de clé API Anthropic. Cette voie d’abonnement désactive par défaut l’outil Claude MCP et les sondes d’image, car Claude route actuellement l’usage d’applications tierces via une facturation d’usage supplémentaire plutôt que via les limites normales du plan d’abonnement. -- Le smoke live du backend CLI exerce maintenant le même flux end-to-end pour Claude, Codex et Gemini : tour texte, tour de classification d’image, puis appel d’outil MCP `cron` vérifié via la CLI Gateway. -- Le smoke par défaut de Claude modifie aussi la session de Sonnet vers Opus et vérifie que la session reprise se souvient toujours d’une note antérieure. +- Il exécute le test de fumée live du backend CLI dans l’image Docker du dépôt en tant qu’utilisateur `node` non root. +- Il résout les métadonnées du test de fumée CLI à partir de l’extension propriétaire, puis installe le paquet CLI Linux correspondant (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) dans un préfixe inscriptible mis en cache à `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (par défaut : `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` nécessite une authentification OAuth portable Claude Code subscription via soit `~/.claude/.credentials.json` avec `claudeAiOauth.subscriptionType`, soit `CLAUDE_CODE_OAUTH_TOKEN` issu de `claude setup-token`. Il prouve d’abord un `claude -p` direct dans Docker, puis exécute deux tours Gateway backend CLI sans conserver les variables d’environnement de clé API Anthropic. Cette voie subscription désactive par défaut la sonde Claude MCP/tool et les sondes d’image, car Claude achemine actuellement l’usage d’applications tierces via une facturation d’usage supplémentaire plutôt que via les limites normales du plan d’abonnement. +- Le test de fumée live du backend CLI exerce maintenant le même flux end-to-end pour Claude, Codex et Gemini : tour texte, tour de classification d’image, puis appel d’outil MCP `cron` vérifié via la CLI Gateway. +- Le test de fumée par défaut de Claude modifie aussi la session de Sonnet vers Opus et vérifie que la session reprise se souvient toujours d’une note antérieure. -## Live : smoke de liaison ACP (`/acp spawn ... --bind here`) +## Live : test de fumée de liaison ACP (`/acp spawn ... --bind here`) - Test : `src/gateway/gateway-acp-bind.live.test.ts` - Objectif : valider le vrai flux de liaison de conversation ACP avec un agent ACP live : - envoyer `/acp spawn --bind here` - lier sur place une conversation synthétique de canal de messages - envoyer un suivi normal sur cette même conversation - - vérifier que le suivi arrive dans la transcription de session ACP liée + - vérifier que le suivi aboutit dans la transcription de session ACP liée - Activer : - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Valeurs par défaut : - Agents ACP dans Docker : `claude,codex,gemini` - Agent ACP pour `pnpm test:live ...` direct : `claude` - - Canal synthétique : contexte de conversation de type message privé Slack + - Canal synthétique : contexte de conversation de type message direct Slack - Backend ACP : `acpx` - Remplacements : - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -534,8 +538,8 @@ Notes : - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Notes : - - Cette voie utilise la surface Gateway `chat.send` avec des champs `originating-route` synthétiques réservés à l’administrateur afin que les tests puissent attacher un contexte de canal de messages sans prétendre effectuer une livraison externe. - - Quand `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` n’est pas défini, le test utilise le registre d’agents intégré du plugin `acpx` embarqué pour l’agent de harnais ACP sélectionné. + - Cette voie utilise la surface `chat.send` de Gateway avec des champs de route d’origine synthétiques réservés à l’admin afin que les tests puissent joindre un contexte de canal de messages sans prétendre à une livraison externe. + - Lorsque `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` n’est pas défini, le test utilise le registre d’agents intégré du Plugin `acpx` embarqué pour l’agent de harnais ACP sélectionné. Exemple : @@ -551,7 +555,7 @@ Recette Docker : pnpm test:docker:live-acp-bind ``` -Recettes Docker à agent unique : +Recettes Docker mono-agent : ```bash pnpm test:docker:live-acp-bind:claude @@ -562,19 +566,19 @@ pnpm test:docker:live-acp-bind:gemini Notes Docker : - L’exécuteur Docker se trouve dans `scripts/test-live-acp-bind-docker.sh`. -- Par défaut, il exécute le smoke de liaison ACP contre tous les agents CLI live pris en charge en séquence : `claude`, `codex`, puis `gemini`. -- Utilisez `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` pour restreindre la matrice. -- Il charge `~/.profile`, prépare le matériel d’authentification CLI correspondant dans le conteneur, installe `acpx` dans un préfixe npm inscriptible, puis installe la CLI live demandée (`@anthropic-ai/claude-code`, `@openai/codex`, ou `@google/gemini-cli`) si elle est absente. -- Dans Docker, l’exécuteur définit `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` afin que acpx conserve les variables d’environnement fournisseur du profil chargé disponibles pour la CLI harnais enfant. +- Par défaut, il exécute en séquence le test de fumée de liaison ACP contre tous les agents CLI live pris en charge : `claude`, `codex`, puis `gemini`. +- Utilisez `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` pour restreindre la matrice. +- Il charge `~/.profile`, prépare dans le conteneur le matériel d’authentification CLI correspondant, installe `acpx` dans un préfixe npm inscriptible, puis installe la CLI live demandée (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) si elle est absente. +- Dans Docker, l’exécuteur définit `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` afin que acpx conserve pour la CLI de harnais enfant les variables d’environnement du fournisseur issues du profil chargé. -## Live : smoke du harnais app-server Codex +## Live : test de fumée du harnais Codex app-server -- Objectif : valider le harnais Codex appartenant au plugin via la méthode - Gateway `agent` normale : - - charger le plugin `codex` intégré +- Objectif : valider le harnais Codex possédé par le Plugin via la méthode + `agent` normale de Gateway : + - charger le Plugin `codex` groupé - sélectionner `OPENCLAW_AGENT_RUNTIME=codex` - - envoyer un premier tour d’agent Gateway vers `codex/gpt-5.4` - - envoyer un deuxième tour à la même session OpenClaw et vérifier que le fil + - envoyer un premier tour agent Gateway à `codex/gpt-5.4` + - envoyer un second tour à la même session OpenClaw et vérifier que le fil app-server peut reprendre - exécuter `/codex status` et `/codex models` via le même chemin de commande Gateway @@ -582,11 +586,11 @@ Notes Docker : - Activer : `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modèle par défaut : `codex/gpt-5.4` - Sonde d’image facultative : `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sonde MCP/outil facultative : `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Le smoke définit `OPENCLAW_AGENT_HARNESS_FALLBACK=none` afin qu’un harnais Codex - cassé ne puisse pas réussir en retombant silencieusement sur PI. -- Authentification : `OPENAI_API_KEY` depuis le shell/profil, plus éventuelle copie de - `~/.codex/auth.json` et `~/.codex/config.toml` +- Sonde MCP/tool facultative : `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Le test de fumée définit `OPENCLAW_AGENT_HARNESS_FALLBACK=none` afin qu’un harnais Codex + défectueux ne puisse pas réussir en basculant silencieusement vers PI. +- Authentification : `OPENAI_API_KEY` depuis le shell/profil, plus éventuellement + `~/.codex/auth.json` et `~/.codex/config.toml` copiés Recette locale : @@ -609,21 +613,22 @@ pnpm test:docker:live-codex-harness Notes Docker : - L’exécuteur Docker se trouve dans `scripts/test-live-codex-harness-docker.sh`. -- Il charge le `~/.profile` monté, transmet `OPENAI_API_KEY`, copie les fichiers d’authentification CLI Codex lorsqu’ils sont présents, installe `@openai/codex` dans un préfixe npm monté inscriptible, prépare l’arbre source, puis n’exécute que le test live du harnais Codex. -- Docker active par défaut les sondes d’image et MCP/outil. Définissez +- Il charge le `~/.profile` monté, transmet `OPENAI_API_KEY`, copie les fichiers d’authentification de la CLI Codex lorsqu’ils sont présents, installe `@openai/codex` dans un préfixe npm monté inscriptible, prépare l’arborescence source, puis exécute uniquement le test live du harnais Codex. +- Docker active par défaut les sondes d’image ainsi que les sondes MCP/tool. Définissez `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` lorsque vous avez besoin d’une exécution de débogage plus restreinte. -- Docker exporte aussi `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, conformément à la - configuration du test live afin que le repli `openai-codex/*` ou PI ne puisse pas masquer une régression du harnais Codex. +- Docker exporte aussi `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, conformément à la config du test + live afin qu’un fallback `openai-codex/*` ou PI ne puisse pas masquer une régression + du harnais Codex. ### Recettes live recommandées -Les listes d’autorisation restreintes et explicites sont les plus rapides et les moins fragiles : +Les listes d’autorisation étroites et explicites sont les plus rapides et les moins instables : - Modèle unique, direct (sans Gateway) : - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modèle unique, smoke Gateway : +- Modèle unique, test de fumée Gateway : - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Appel d’outils sur plusieurs fournisseurs : @@ -636,19 +641,19 @@ Les listes d’autorisation restreintes et explicites sont les plus rapides et l Notes : - `google/...` utilise l’API Gemini (clé API). -- `google-antigravity/...` utilise le pont OAuth Antigravity (point de terminaison d’agent de style Cloud Code Assist). -- `google-gemini-cli/...` utilise la CLI Gemini locale sur votre machine (authentification séparée + particularités d’outillage). +- `google-antigravity/...` utilise le pont OAuth Antigravity (point de terminaison d’agent de type Cloud Code Assist). +- `google-gemini-cli/...` utilise la CLI Gemini locale sur votre machine (authentification distincte + particularités d’outillage). - API Gemini vs CLI Gemini : - - API : OpenClaw appelle l’API Gemini hébergée par Google via HTTP (clé API / authentification de profil) ; c’est ce que la plupart des utilisateurs veulent dire par « Gemini ». - - CLI : OpenClaw exécute un binaire `gemini` local ; il a sa propre authentification et peut se comporter différemment (streaming/prise en charge des outils/décalage de version). + - API : OpenClaw appelle l’API Gemini hébergée par Google via HTTP (clé API / authentification de profil) ; c’est ce que la plupart des utilisateurs entendent par « Gemini ». + - CLI : OpenClaw exécute un binaire local `gemini` ; il possède sa propre authentification et peut se comporter différemment (streaming/prise en charge des outils/décalage de version). ## Live : matrice de modèles (ce que nous couvrons) -Il n’existe pas de « liste de modèles CI » fixe (le live est opt-in), mais voici les modèles **recommandés** à couvrir régulièrement sur une machine de développement disposant de clés. +Il n’existe pas de « liste de modèles CI » fixe (live est activé sur demande), mais voici les modèles **recommandés** à couvrir régulièrement sur une machine de développement disposant des clés. -### Ensemble de smoke moderne (appel d’outils + image) +### Ensemble de fumée moderne (appel d’outils + image) -C’est l’exécution « modèles courants » que nous nous attendons à maintenir opérationnelle : +Il s’agit de l’exécution des « modèles courants » que nous attendons de garder fonctionnelle : - OpenAI (hors Codex) : `openai/gpt-5.4` (facultatif : `openai/gpt-5.4-mini`) - OpenAI Codex : `openai-codex/gpt-5.4` @@ -658,7 +663,7 @@ C’est l’exécution « modèles courants » que nous nous attendons à main - Z.AI (GLM) : `zai/glm-4.7` - MiniMax : `minimax/MiniMax-M2.7` -Exécutez le smoke Gateway avec outils + image : +Exécutez le test de fumée Gateway avec outils + image : `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Référence de base : appel d’outils (Read + Exec facultatif) @@ -671,81 +676,81 @@ Choisissez au moins un modèle par famille de fournisseurs : - Z.AI (GLM) : `zai/glm-4.7` - MiniMax : `minimax/MiniMax-M2.7` -Couverture facultative supplémentaire (souhaitable) : +Couverture additionnelle facultative (agréable à avoir) : -- xAI : `xai/grok-4` (ou la dernière version disponible) +- xAI : `xai/grok-4` (ou le plus récent disponible) - Mistral : `mistral/`… (choisissez un modèle compatible « tools » que vous avez activé) - Cerebras : `cerebras/`… (si vous y avez accès) - LM Studio : `lmstudio/`… (local ; l’appel d’outils dépend du mode API) ### Vision : envoi d’image (pièce jointe → message multimodal) -Incluez au moins un modèle compatible image dans `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes Claude/Gemini/OpenAI compatibles vision, etc.) afin d’exercer la sonde d’image. +Incluez au moins un modèle compatible image dans `OPENCLAW_LIVE_GATEWAY_MODELS` (variants Claude/Gemini/OpenAI compatibles vision, etc.) afin d’exercer la sonde d’image. ### Agrégateurs / passerelles alternatives -Si vous avez les clés activées, nous prenons aussi en charge des tests via : +Si vous avez activé les clés, nous prenons aussi en charge les tests via : - OpenRouter : `openrouter/...` (des centaines de modèles ; utilisez `openclaw models scan` pour trouver des candidats compatibles outil+image) - OpenCode : `opencode/...` pour Zen et `opencode-go/...` pour Go (authentification via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Autres fournisseurs que vous pouvez inclure dans la matrice live (si vous avez les identifiants/la configuration) : +Autres fournisseurs que vous pouvez inclure dans la matrice live (si vous avez les identifiants/la config) : - Intégrés : `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Via `models.providers` (points de terminaison personnalisés) : `minimax` (cloud/API), ainsi que tout proxy compatible OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) +- Via `models.providers` (points de terminaison personnalisés) : `minimax` (cloud/API), plus tout proxy compatible OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) Astuce : n’essayez pas de coder en dur « tous les modèles » dans la documentation. La liste faisant autorité est celle que `discoverModels(...)` renvoie sur votre machine + les clés disponibles. -## Identifiants (ne jamais commit) +## Identifiants (ne jamais valider) -Les tests live découvrent les identifiants de la même manière que la CLI. Implications pratiques : +Les tests live découvrent les identifiants de la même façon que la CLI. Implications pratiques : - Si la CLI fonctionne, les tests live devraient trouver les mêmes clés. -- Si un test live indique « aucun identifiant », déboguez-le de la même manière que `openclaw models list` / la sélection de modèle. +- Si un test live indique « pas d’identifiants », déboguez-le comme vous débogueriez `openclaw models list` / la sélection de modèle. - Profils d’authentification par agent : `~/.openclaw/agents//agent/auth-profiles.json` (c’est ce que signifient les « clés de profil » dans les tests live) -- Configuration : `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) -- Répertoire d’état hérité : `~/.openclaw/credentials/` (copié dans le home live préparé quand il est présent, mais pas dans le magasin principal de clés de profil) -- Les exécutions live locales copient par défaut la configuration active, les fichiers `auth-profiles.json` par agent, le répertoire hérité `credentials/` et les répertoires d’authentification CLI externes pris en charge dans un home de test temporaire ; les homes live préparés ignorent `workspace/` et `sandboxes/`, et les remplacements de chemin `agents.*.workspace` / `agentDir` sont supprimés afin que les sondes restent hors de votre véritable espace de travail hôte. +- Config : `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) +- Répertoire d’état hérité : `~/.openclaw/credentials/` (copié dans le répertoire personnel live préparé lorsqu’il est présent, mais pas dans le magasin principal de clés de profil) +- Les exécutions live locales copient par défaut la config active, les fichiers `auth-profiles.json` par agent, l’ancien répertoire `credentials/` et les répertoires d’authentification CLI externes pris en charge dans un répertoire personnel de test temporaire ; les répertoires personnels live préparés ignorent `workspace/` et `sandboxes/`, et les remplacements de chemin `agents.*.workspace` / `agentDir` sont supprimés afin que les sondes restent en dehors de votre véritable espace de travail hôte. Si vous voulez vous appuyer sur des clés d’environnement (par exemple exportées dans votre `~/.profile`), exécutez les tests locaux après `source ~/.profile`, ou utilisez les exécuteurs Docker ci-dessous (ils peuvent monter `~/.profile` dans le conteneur). -## Deepgram live (transcription audio) +## Live Deepgram (transcription audio) - Test : `src/media-understanding/providers/deepgram/audio.live.test.ts` - Activer : `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live BytePlus coding plan - Test : `src/agents/byteplus.live.test.ts` - Activer : `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Remplacement facultatif du modèle : `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live média de workflow ComfyUI - Test : `extensions/comfy/comfy.live.test.ts` - Activer : `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Portée : - - Exerce les chemins image, vidéo et `music_generate` du paquet comfy intégré - - Ignore chaque capacité sauf si `models.providers.comfy.` est configuré - - Utile après avoir modifié l’envoi de workflow comfy, le polling, les téléchargements ou l’enregistrement du plugin + - Exerce les chemins groupés comfy image, vidéo et `music_generate` + - Ignore chaque capacité à moins que `models.providers.comfy.` ne soit configuré + - Utile après modification de la soumission de workflow comfy, du polling, des téléchargements ou de l’enregistrement du Plugin -## Génération d’image live +## Live génération d’image - Test : `src/image-generation/runtime.live.test.ts` - Commande : `pnpm test:live src/image-generation/runtime.live.test.ts` - Harnais : `pnpm test:live:media image` - Portée : - - Énumère chaque plugin fournisseur de génération d’image enregistré - - Charge les variables d’environnement fournisseur manquantes depuis votre shell de connexion (`~/.profile`) avant les sondes - - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que d’anciennes clés de test dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell - - Ignore les fournisseurs sans authentification/profil/modèle exploitable - - Exécute les variantes standard de génération d’image via la capacité runtime partagée : + - Énumère chaque Plugin fournisseur de génération d’image enregistré + - Charge les variables d’environnement fournisseur manquantes depuis votre shell de connexion (`~/.profile`) avant la sonde + - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que des clés de test périmées dans `auth-profiles.json` ne masquent pas de vrais identifiants du shell + - Ignore les fournisseurs sans auth/profil/modèle exploitable + - Exécute les variantes standard de génération d’image via la capacité d’exécution partagée : - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Fournisseurs intégrés actuellement couverts : +- Fournisseurs groupés actuellement couverts : - `openai` - `google` - Restriction facultative : @@ -753,74 +758,74 @@ Si vous voulez vous appuyer sur des clés d’environnement (par exemple export - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Comportement d’authentification facultatif : - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification via le magasin de profils et ignorer les remplacements provenant uniquement de l’environnement + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement basés sur l’environnement -## Génération de musique live +## Live génération de musique - Test : `extensions/music-generation-providers.live.test.ts` - Activer : `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harnais : `pnpm test:live:media music` - Portée : - - Exerce le chemin partagé des fournisseurs intégrés de génération de musique + - Exerce le chemin groupé partagé des fournisseurs de génération de musique - Couvre actuellement Google et MiniMax - - Charge les variables d’environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant les sondes - - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que d’anciennes clés de test dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell - - Ignore les fournisseurs sans authentification/profil/modèle exploitable - - Exécute les deux modes runtime déclarés lorsqu’ils sont disponibles : - - `generate` avec entrée de type prompt uniquement + - Charge les variables d’environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant la sonde + - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que des clés de test périmées dans `auth-profiles.json` ne masquent pas de vrais identifiants du shell + - Ignore les fournisseurs sans auth/profil/modèle exploitable + - Exécute les deux modes d’exécution déclarés lorsqu’ils sont disponibles : + - `generate` avec entrée uniquement textuelle - `edit` lorsque le fournisseur déclare `capabilities.edit.enabled` - Couverture actuelle de la voie partagée : - `google` : `generate`, `edit` - `minimax` : `generate` - - `comfy` : fichier live Comfy séparé, pas ce balayage partagé + - `comfy` : fichier live Comfy distinct, pas ce balayage partagé - Restriction facultative : - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Comportement d’authentification facultatif : - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification via le magasin de profils et ignorer les remplacements provenant uniquement de l’environnement + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement basés sur l’environnement -## Génération de vidéo live +## Live génération de vidéo - Test : `extensions/video-generation-providers.live.test.ts` - Activer : `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harnais : `pnpm test:live:media video` - Portée : - - Exerce le chemin partagé des fournisseurs intégrés de génération de vidéo - - Utilise par défaut le chemin de smoke sûr pour les versions : fournisseurs hors FAL, une requête texte-vers-vidéo par fournisseur, prompt lobster d’une seconde, et une limite d’opération par fournisseur depuis `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` par défaut) + - Exerce le chemin groupé partagé des fournisseurs de génération de vidéo + - Utilise par défaut le chemin de fumée sûr pour une release : fournisseurs hors FAL, une requête texte-vers-vidéo par fournisseur, une invite lobster d’une seconde, et une limite d’opération par fournisseur issue de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` par défaut) - Ignore FAL par défaut car la latence de file d’attente côté fournisseur peut dominer le temps de release ; passez `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` pour l’exécuter explicitement - - Charge les variables d’environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant les sondes - - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que d’anciennes clés de test dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell - - Ignore les fournisseurs sans authentification/profil/modèle exploitable + - Charge les variables d’environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant la sonde + - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que des clés de test périmées dans `auth-profiles.json` ne masquent pas de vrais identifiants du shell + - Ignore les fournisseurs sans auth/profil/modèle exploitable - Exécute uniquement `generate` par défaut - - Définissez `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` pour exécuter aussi les modes de transformation déclarés quand ils sont disponibles : - - `imageToVideo` lorsque le fournisseur déclare `capabilities.imageToVideo.enabled` et que le fournisseur/modèle sélectionné accepte une entrée image locale adossée à un tampon dans le balayage partagé - - `videoToVideo` lorsque le fournisseur déclare `capabilities.videoToVideo.enabled` et que le fournisseur/modèle sélectionné accepte une entrée vidéo locale adossée à un tampon dans le balayage partagé + - Définissez `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` pour exécuter aussi les modes de transformation déclarés lorsqu’ils sont disponibles : + - `imageToVideo` lorsque le fournisseur déclare `capabilities.imageToVideo.enabled` et que le fournisseur/modèle sélectionné accepte dans le balayage partagé une entrée image locale adossée à un buffer + - `videoToVideo` lorsque le fournisseur déclare `capabilities.videoToVideo.enabled` et que le fournisseur/modèle sélectionné accepte dans le balayage partagé une entrée vidéo locale adossée à un buffer - Fournisseurs `imageToVideo` actuellement déclarés mais ignorés dans le balayage partagé : - - `vydra` car le `veo3` intégré est uniquement texte et le `kling` intégré exige une URL d’image distante - - Couverture spécifique au fournisseur Vydra : + - `vydra` car le `veo3` groupé est texte uniquement et le `kling` groupé nécessite une URL d’image distante + - Couverture Vydra spécifique au fournisseur : - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - ce fichier exécute `veo3` en texte-vers-vidéo ainsi qu’une voie `kling` qui utilise par défaut une fixture d’URL d’image distante - - Couverture live `videoToVideo` actuelle : + - ce fichier exécute `veo3` texte-vers-vidéo ainsi qu’une voie `kling` qui utilise par défaut une fixture d’URL d’image distante + - Couverture live actuelle `videoToVideo` : - `runway` uniquement lorsque le modèle sélectionné est `runway/gen4_aleph` - Fournisseurs `videoToVideo` actuellement déclarés mais ignorés dans le balayage partagé : - `alibaba`, `qwen`, `xai` car ces chemins nécessitent actuellement des URL de référence distantes `http(s)` / MP4 - - `google` car la voie partagée Gemini/Veo actuelle utilise une entrée locale adossée à un tampon, et ce chemin n’est pas accepté dans le balayage partagé - - `openai` car la voie partagée actuelle ne garantit pas l’accès spécifique à l’organisation pour la retouche/remix vidéo + - `google` car la voie Gemini/Veo partagée actuelle utilise une entrée locale adossée à un buffer et ce chemin n’est pas accepté dans le balayage partagé + - `openai` car la voie partagée actuelle ne garantit pas l’accès spécifique à l’organisation pour le video inpaint/remix - Restriction facultative : - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` pour inclure chaque fournisseur dans le balayage par défaut, y compris FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` pour réduire la limite d’opération de chaque fournisseur lors d’un smoke agressif + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` pour réduire la limite d’opération de chaque fournisseur lors d’une exécution de fumée agressive - Comportement d’authentification facultatif : - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification via le magasin de profils et ignorer les remplacements provenant uniquement de l’environnement + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement basés sur l’environnement -## Harnais media live +## Harnais live média - Commande : `pnpm test:live:media` -- But : - - Exécute les suites live partagées d’image, de musique et de vidéo via un point d’entrée natif du dépôt +- Objectif : + - Exécute les suites live partagées image, musique et vidéo via un point d’entrée unique natif du dépôt - Charge automatiquement les variables d’environnement fournisseur manquantes depuis `~/.profile` - - Restreint automatiquement chaque suite aux fournisseurs qui disposent actuellement d’une authentification exploitable par défaut + - Restreint automatiquement par défaut chaque suite aux fournisseurs disposant actuellement d’une authentification exploitable - Réutilise `scripts/test-live.mjs`, afin que le comportement Heartbeat et le mode silencieux restent cohérents - Exemples : - `pnpm test:live:media` @@ -828,78 +833,78 @@ Si vous voulez vous appuyer sur des clés d’environnement (par exemple export - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Exécuteurs Docker (vérifications facultatives « ça fonctionne sous Linux ») +## Exécuteurs Docker (vérifications facultatives « fonctionne sous Linux ») -Ces exécuteurs Docker se divisent en deux catégories : +Ces exécuteurs Docker se répartissent en deux catégories : -- Exécuteurs live de modèles : `test:docker:live-models` et `test:docker:live-gateway` n’exécutent que leur fichier live à clés de profil correspondant dans l’image Docker du dépôt (`src/agents/models.profiles.live.test.ts` et `src/gateway/gateway-models.profiles.live.test.ts`), en montant votre répertoire de configuration local et votre espace de travail (et en chargeant `~/.profile` s’il est monté). Les points d’entrée locaux correspondants sont `test:live:models-profiles` et `test:live:gateway-profiles`. -- Les exécuteurs live Docker utilisent par défaut une limite de smoke plus petite afin qu’un balayage Docker complet reste pratique : +- Exécuteurs live de modèles : `test:docker:live-models` et `test:docker:live-gateway` n’exécutent que leur fichier live à clés de profil correspondant dans l’image Docker du dépôt (`src/agents/models.profiles.live.test.ts` et `src/gateway/gateway-models.profiles.live.test.ts`), en montant votre répertoire de config local et votre espace de travail (et en chargeant `~/.profile` s’il est monté). Les points d’entrée locaux correspondants sont `test:live:models-profiles` et `test:live:gateway-profiles`. +- Les exécuteurs Docker live utilisent par défaut un plafond de fumée plus petit afin qu’un balayage Docker complet reste pratique : `test:docker:live-models` utilise par défaut `OPENCLAW_LIVE_MAX_MODELS=12`, et `test:docker:live-gateway` utilise par défaut `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, et - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Remplacez ces variables d’environnement quand vous - voulez explicitement un balayage exhaustif plus large. -- `test:docker:all` construit une fois l’image Docker live via `test:docker:live-build`, puis la réutilise pour les deux voies live Docker. -- Exécuteurs smoke de conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, et `test:docker:plugins` démarrent un ou plusieurs vrais conteneurs et vérifient des chemins d’intégration de plus haut niveau. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Remplacez ces variables d’environnement lorsque vous + voulez explicitement lancer le balayage exhaustif plus large. +- `test:docker:all` construit l’image Docker live une fois via `test:docker:live-build`, puis la réutilise pour les deux voies Docker live. +- Exécuteurs de fumée en conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` et `test:docker:plugins` démarrent un ou plusieurs vrais conteneurs et vérifient des chemins d’intégration de plus haut niveau. -Les exécuteurs Docker live de modèles montent aussi uniquement les répertoires d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le home du conteneur avant l’exécution afin que l’OAuth des CLI externes puisse rafraîchir les jetons sans modifier le magasin d’authentification de l’hôte : +Les exécuteurs Docker live de modèles montent également en bind uniquement les répertoires d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le répertoire personnel du conteneur avant l’exécution afin que l’OAuth des CLI externes puisse rafraîchir les jetons sans modifier le magasin d’authentification de l’hôte : - Modèles directs : `pnpm test:docker:live-models` (script : `scripts/test-live-models-docker.sh`) -- Smoke de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh`) -- Smoke du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`) -- Smoke du harnais app-server Codex : `pnpm test:docker:live-codex-harness` (script : `scripts/test-live-codex-harness-docker.sh`) +- Test de fumée de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh`) +- Test de fumée du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`) +- Test de fumée du harnais Codex app-server : `pnpm test:docker:live-codex-harness` (script : `scripts/test-live-codex-harness-docker.sh`) - Gateway + agent de développement : `pnpm test:docker:live-gateway` (script : `scripts/test-live-gateway-models-docker.sh`) -- Smoke live Open WebUI : `pnpm test:docker:openwebui` (script : `scripts/e2e/openwebui-docker.sh`) -- Assistant d’onboarding (TTY, échafaudage complet) : `pnpm test:docker:onboard` (script : `scripts/e2e/onboard-docker.sh`) -- Réseau Gateway (deux conteneurs, authentification WS + santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`) -- Pont de canal MCP (Gateway amorcé + pont stdio + smoke brut de trame de notification Claude) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke d’installation + alias `/plugin` + sémantique de redémarrage du bundle Claude) : `pnpm test:docker:plugins` (script : `scripts/e2e/plugins-docker.sh`) +- Test de fumée live Open WebUI : `pnpm test:docker:openwebui` (script : `scripts/e2e/openwebui-docker.sh`) +- Assistant d’onboarding (TTY, scaffolding complet) : `pnpm test:docker:onboard` (script : `scripts/e2e/onboard-docker.sh`) +- Réseau Gateway (deux conteneurs, authentification WS + état de santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`) +- Pont de canal MCP (Gateway prérempli + pont stdio + test de fumée brut de trame de notification Claude) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (fumée d’installation + alias `/plugin` + sémantique de redémarrage du bundle Claude) : `pnpm test:docker:plugins` (script : `scripts/e2e/plugins-docker.sh`) -Les exécuteurs Docker live de modèles montent aussi l’extraction courante en lecture seule et -la préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela garde l’image d’exécution -légère tout en exécutant Vitest sur votre source/configuration locale exacte. -L’étape de préparation ignore les gros caches locaux et sorties de build d’application comme -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, et les répertoires locaux `.build` ou -de sortie Gradle afin que les exécutions live Docker ne passent pas des minutes à copier +Les exécuteurs Docker live de modèles montent aussi en bind le checkout courant en lecture seule et +le préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela garde l’image d’exécution +légère tout en exécutant Vitest sur votre source/config locale exacte. +L’étape de préparation ignore les gros caches strictement locaux et les sorties de build d’applications telles que +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, ainsi que les répertoires `.build` locaux aux applications ou +les répertoires de sortie Gradle, afin que les exécutions Docker live ne passent pas des minutes à copier des artefacts spécifiques à la machine. Ils définissent aussi `OPENCLAW_SKIP_CHANNELS=1` afin que les sondes live Gateway ne démarrent pas -de vrais workers de canal Telegram/Discord/etc. dans le conteneur. +de vrais workers de canaux Telegram/Discord/etc. dans le conteneur. `test:docker:live-models` exécute toujours `pnpm test:live`, donc transmettez aussi `OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture live Gateway de cette voie Docker. -`test:docker:openwebui` est un smoke de compatibilité de plus haut niveau : il démarre un +`test:docker:openwebui` est un test de fumée de compatibilité de plus haut niveau : il démarre un conteneur Gateway OpenClaw avec les points de terminaison HTTP compatibles OpenAI activés, -démarre un conteneur Open WebUI épinglé contre ce Gateway, se connecte via +démarre un conteneur Open WebUI épinglé contre cette Gateway, se connecte via Open WebUI, vérifie que `/api/models` expose `openclaw/default`, puis envoie une vraie requête de chat via le proxy `/api/chat/completions` d’Open WebUI. -La première exécution peut être sensiblement plus lente car Docker peut devoir extraire l’image -Open WebUI et Open WebUI peut devoir terminer sa propre initialisation à froid. +La première exécution peut être sensiblement plus lente car Docker peut devoir récupérer l’image +Open WebUI et Open WebUI peut devoir terminer son propre démarrage à froid. Cette voie attend une clé de modèle live exploitable, et `OPENCLAW_PROFILE_FILE` -(`~/.profile` par défaut) est le principal moyen de la fournir dans les exécutions Docker. +(`~/.profile` par défaut) est le moyen principal de la fournir dans les exécutions Dockerisées. Les exécutions réussies affichent une petite charge utile JSON comme `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` est volontairement déterministe et n’a pas besoin d’un vrai compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway -amorcé, démarre un second conteneur qui lance `openclaw mcp serve`, puis -vérifie la découverte de conversation routée, la lecture des transcriptions, les métadonnées de pièce jointe, -le comportement de la file d’attente d’événements live, le routage d’envoi sortant, et les notifications de canal + -permissions de style Claude via le vrai pont MCP stdio. La vérification de notification -inspecte directement les trames MCP stdio brutes afin que le smoke valide ce que le -pont émet réellement, et pas seulement ce qu’un SDK client particulier choisit d’exposer. +prérempli, lance un second conteneur qui exécute `openclaw mcp serve`, puis +vérifie la découverte de conversations routées, les lectures de transcription, les métadonnées de pièces jointes, +le comportement de la file d’événements live, le routage des envois sortants, ainsi que les notifications +de canal + permissions de type Claude via le vrai pont MCP stdio. La vérification de notification +inspecte directement les trames MCP stdio brutes afin que le test de fumée valide ce que +le pont émet réellement, et pas seulement ce qu’un SDK client particulier choisit d’exposer. -Smoke manuel ACP de fil en langage naturel (hors CI) : +Test manuel ACP de fil en langage naturel (hors CI) : - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Conservez ce script pour les workflows de régression/débogage. Il pourrait être de nouveau nécessaire pour la validation du routage des fils ACP, donc ne le supprimez pas. +- Conservez ce script pour les workflows de régression/débogage. Il pourra être de nouveau nécessaire pour la validation du routage de fils ACP, donc ne le supprimez pas. Variables d’environnement utiles : - `OPENCLAW_CONFIG_DIR=...` (par défaut : `~/.openclaw`) monté sur `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (par défaut : `~/.openclaw/workspace`) monté sur `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (par défaut : `~/.profile`) monté sur `/home/node/.profile` et chargé avant l’exécution des tests -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` pour vérifier uniquement les variables d’environnement chargées depuis `OPENCLAW_PROFILE_FILE`, en utilisant des répertoires config/workspace temporaires et sans montage d’authentification CLI externe -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté sur `/home/node/.npm-global` pour les installations CLI en cache dans Docker +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` pour vérifier uniquement les variables d’environnement chargées depuis `OPENCLAW_PROFILE_FILE`, avec des répertoires temporaires de config/espace de travail et sans montage d’authentification CLI externe +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté sur `/home/node/.npm-global` pour les installations CLI mises en cache dans Docker - Les répertoires/fichiers d’authentification CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés vers `/home/node/...` avant le démarrage des tests - Répertoires par défaut : `.minimax` - Fichiers par défaut : `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` @@ -907,50 +912,50 @@ Variables d’environnement utiles : - Remplacement manuel avec `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, ou une liste séparée par des virgules comme `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` pour restreindre l’exécution - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` pour filtrer les fournisseurs dans le conteneur -- `OPENCLAW_SKIP_DOCKER_BUILD=1` pour réutiliser une image `openclaw:local-live` existante lors de relances qui ne nécessitent pas de reconstruction +- `OPENCLAW_SKIP_DOCKER_BUILD=1` pour réutiliser une image `openclaw:local-live` existante lors de relances ne nécessitant pas de reconstruction - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour garantir que les identifiants proviennent du magasin de profils (et non de l’environnement) -- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par Gateway pour le smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer le prompt de vérification de nonce utilisé par le smoke Open WebUI -- `OPENWEBUI_IMAGE=...` pour remplacer le tag d’image Open WebUI épinglé +- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par la Gateway pour le test de fumée Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer l’invite de vérification par nonce utilisée par le test de fumée Open WebUI +- `OPENWEBUI_IMAGE=...` pour remplacer la balise d’image Open WebUI épinglée -## Vérification de la documentation +## Vérification de cohérence de la documentation Exécutez les vérifications de documentation après des modifications de doc : `pnpm check:docs`. -Exécutez la validation complète des ancres Mintlify quand vous avez aussi besoin de vérifier les titres dans la page : `pnpm docs:check-links:anchors`. +Exécutez la validation complète des ancres Mintlify lorsque vous avez aussi besoin de vérifier les titres dans la page : `pnpm docs:check-links:anchors`. ## Régression hors ligne (compatible CI) -Ce sont des régressions de « vrai pipeline » sans vrais fournisseurs : +Il s’agit de régressions en « pipeline réel » sans vrais fournisseurs : - Appel d’outils Gateway (OpenAI simulé, vraie boucle Gateway + agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistant Gateway (WS `wizard.start`/`wizard.next`, écriture de config + authentification imposée) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config") +- Assistant Gateway (WS `wizard.start`/`wizard.next`, écriture de config + auth imposée) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config") -## Évaluations de fiabilité d’agent (Skills) +## Évaluations de fiabilité de l’agent (Skills) -Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité d’agent » : +Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité de l’agent » : - Appel d’outils simulé via la vraie boucle Gateway + agent (`src/gateway/gateway.test.ts`). - Flux d’assistant end-to-end qui valident le câblage de session et les effets de configuration (`src/gateway/gateway.test.ts`). Ce qui manque encore pour les Skills (voir [Skills](/fr/tools/skills)) : -- **Prise de décision :** lorsque des Skills sont listées dans le prompt, l’agent choisit-il la bonne Skill (ou évite-t-il celles qui sont non pertinentes) ? -- **Conformité :** l’agent lit-il `SKILL.md` avant utilisation et suit-il les étapes/arguments requis ? -- **Contrats de workflow :** scénarios multi-tours qui vérifient l’ordre des outils, la conservation de l’historique de session, et les frontières du sandbox. +- **Prise de décision :** lorsque les Skills sont listées dans l’invite, l’agent choisit-il la bonne Skill (ou évite-t-il les Skills non pertinentes) ? +- **Conformité :** l’agent lit-il `SKILL.md` avant usage et suit-il les étapes/arguments requis ? +- **Contrats de workflow :** scénarios multi-tours qui vérifient l’ordre des outils, le report de l’historique de session et les limites du bac à sable. Les futures évaluations doivent d’abord rester déterministes : -- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + leur ordre, les lectures de fichiers de Skills, et le câblage de session. -- Une petite suite de scénarios ciblés sur les Skills (utiliser vs éviter, filtrage, injection de prompt). -- Des évaluations live facultatives (opt-in, filtrées par variables d’environnement) uniquement après la mise en place de la suite compatible CI. +- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + leur ordre, les lectures de fichiers de Skill et le câblage de session. +- Une petite suite de scénarios centrés sur les Skills (utiliser vs éviter, contrôles, injection d’invite). +- Des évaluations live facultatives (sur activation, protégées par variables d’environnement) uniquement après la mise en place de la suite compatible CI. -## Tests de contrat (forme des plugins et des canaux) +## Tests de contrat (forme des Plugins et des canaux) -Les tests de contrat vérifient que chaque plugin et canal enregistré respecte son -contrat d’interface. Ils parcourent tous les plugins découverts et exécutent une suite de +Les tests de contrat vérifient que chaque Plugin et canal enregistré respecte son +contrat d’interface. Ils itèrent sur tous les Plugins découverts et exécutent une suite de vérifications de forme et de comportement. La voie unitaire par défaut `pnpm test` -ignore volontairement ces fichiers partagés de seam et de smoke ; exécutez explicitement -les commandes de contrat quand vous touchez les surfaces partagées de canal ou de fournisseur. +ignore volontairement ces fichiers partagés de joints et de fumée ; exécutez les commandes de contrat explicitement +lorsque vous modifiez des surfaces partagées de canal ou de fournisseur. ### Commandes @@ -962,53 +967,53 @@ les commandes de contrat quand vous touchez les surfaces partagées de canal ou Situés dans `src/channels/plugins/contracts/*.contract.test.ts` : -- **plugin** - Forme de base du plugin (id, nom, capacités) +- **plugin** - Forme de base du Plugin (id, nom, capacités) - **setup** - Contrat de l’assistant de configuration - **session-binding** - Comportement de liaison de session -- **outbound-payload** - Structure de la charge utile du message +- **outbound-payload** - Structure de charge utile des messages - **inbound** - Gestion des messages entrants - **actions** - Gestionnaires d’actions de canal - **threading** - Gestion des identifiants de fil -- **directory** - API d’annuaire/de roster +- **directory** - API d’annuaire/de liste - **group-policy** - Application de la politique de groupe ### Contrats d’état des fournisseurs Situés dans `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondes d’état du canal -- **registry** - Forme du registre de plugins +- **status** - Sondes d’état des canaux +- **registry** - Forme du registre de Plugins ### Contrats de fournisseurs Situés dans `src/plugins/contracts/*.contract.test.ts` : -- **auth** - Contrat du flux d’authentification -- **auth-choice** - Choix/sélection d’authentification +- **auth** - Contrat de flux d’authentification +- **auth-choice** - Choix/sélection de l’authentification - **catalog** - API du catalogue de modèles -- **discovery** - Découverte de plugins -- **loader** - Chargement de plugin -- **runtime** - Runtime du fournisseur -- **shape** - Forme/interface du plugin +- **discovery** - Découverte des Plugins +- **loader** - Chargement des Plugins +- **runtime** - Exécution du fournisseur +- **shape** - Forme/interface du Plugin - **wizard** - Assistant de configuration ### Quand les exécuter -- Après une modification des exports ou sous-chemins de `plugin-sdk` -- Après l’ajout ou la modification d’un plugin de canal ou de fournisseur -- Après un refactoring de l’enregistrement ou de la découverte de plugins +- Après modification des exportations ou sous-chemins de `plugin-sdk` +- Après ajout ou modification d’un Plugin de canal ou de fournisseur +- Après refactorisation de l’enregistrement ou de la découverte des Plugins -Les tests de contrat s’exécutent dans CI et ne nécessitent pas de vraies clés API. +Les tests de contrat s’exécutent en CI et ne nécessitent pas de vraies clés API. -## Ajouter des régressions (guide) +## Ajouter des régressions (recommandations) -Quand vous corrigez un problème de fournisseur/modèle découvert en live : +Lorsque vous corrigez un problème de fournisseur/modèle découvert en live : -- Ajoutez si possible une régression compatible CI (fournisseur simulé/mocké, ou capture exacte de la transformation de forme de requête) -- Si c’est intrinsèquement live-only (limitations de débit, politiques d’authentification), gardez le test live restreint et opt-in via des variables d’environnement +- Ajoutez si possible une régression compatible CI (fournisseur simulé/substitué, ou capture de la transformation exacte de forme de requête) +- Si le problème est intrinsèquement limité au live (limitations de débit, politiques d’authentification), gardez le test live étroit et activé sur demande via des variables d’environnement - Préférez cibler la plus petite couche qui détecte le bug : - bug de conversion/rejeu de requête fournisseur → test de modèles directs - - bug de pipeline Gateway session/historique/outils → smoke live Gateway ou test mock Gateway compatible CI -- Garde-fou de traversée SecretRef : - - `src/secrets/exec-secret-ref-id-parity.test.ts` dérive une cible échantillonnée par classe SecretRef à partir des métadonnées de registre (`listSecretTargetRegistryEntries()`), puis vérifie que les identifiants exec de segment de traversée sont rejetés. - - Si vous ajoutez une nouvelle famille cible SecretRef `includeInPlan` dans `src/secrets/target-registry-data.ts`, mettez à jour `classifyTargetClass` dans ce test. Le test échoue volontairement sur les identifiants de cible non classés afin qu’aucune nouvelle classe ne puisse être ignorée silencieusement. + - bug du pipeline Gateway session/historique/outils → test de fumée live Gateway ou test simulé Gateway compatible CI +- Garde-fou de parcours SecretRef : + - `src/secrets/exec-secret-ref-id-parity.test.ts` dérive une cible échantillonnée par classe SecretRef depuis les métadonnées du registre (`listSecretTargetRegistryEntries()`), puis vérifie que les identifiants exec de segment de parcours sont rejetés. + - Si vous ajoutez une nouvelle famille de cibles SecretRef `includeInPlan` dans `src/secrets/target-registry-data.ts`, mettez à jour `classifyTargetClass` dans ce test. Le test échoue volontairement sur les identifiants de cible non classés afin que de nouvelles classes ne puissent pas être ignorées silencieusement. diff --git a/docs/fr/plugins/sdk-migration.md b/docs/fr/plugins/sdk-migration.md index 71c1bd611..f00e7874e 100644 --- a/docs/fr/plugins/sdk-migration.md +++ b/docs/fr/plugins/sdk-migration.md @@ -1,130 +1,122 @@ --- read_when: - - Vous voyez l'avertissement OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - - Vous voyez l'avertissement OPENCLAW_EXTENSION_API_DEPRECATED - - Vous mettez à jour un plugin vers l'architecture de plugin moderne - - Vous maintenez un plugin OpenClaw externe + - Vous voyez l’avertissement `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` + - Vous voyez l’avertissement `OPENCLAW_EXTENSION_API_DEPRECATED` + - Vous mettez à jour un Plugin vers l’architecture de Plugin moderne + - Vous maintenez un Plugin OpenClaw externe sidebarTitle: Migrate to SDK -summary: Migrez depuis la couche héritée de rétrocompatibilité vers le Plugin SDK moderne +summary: Migrez de la couche de compatibilité descendante héritée vers le Plugin SDK moderne title: Migration du Plugin SDK x-i18n: - generated_at: "2026-04-09T01:29:23Z" + generated_at: "2026-04-17T06:57:32Z" model: gpt-5.4 provider: openai - source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 + source_hash: f0283f949eec358a12a0709db846cde2a1509f28e5c60db6e563cb8a540b979d source_path: plugins/sdk-migration.md workflow: 15 --- # Migration du Plugin SDK -OpenClaw est passé d'une large couche de rétrocompatibilité à une architecture de plugin -moderne avec des imports ciblés et documentés. Si votre plugin a été créé avant -la nouvelle architecture, ce guide vous aidera à migrer. +OpenClaw est passé d’une large couche de compatibilité descendante à une architecture de Plugin moderne avec des imports ciblés et documentés. Si votre Plugin a été conçu avant la nouvelle architecture, ce guide vous aide à le migrer. ## Ce qui change -L'ancien système de plugins fournissait deux surfaces très ouvertes qui permettaient aux plugins d'importer -tout ce dont ils avaient besoin depuis un seul point d'entrée : +L’ancien système de Plugin fournissait deux surfaces très ouvertes qui permettaient aux Plugins d’importer tout ce dont ils avaient besoin depuis un seul point d’entrée : -- **`openclaw/plugin-sdk/compat`** — un import unique qui réexportait des dizaines de - helpers. Il a été introduit pour maintenir le fonctionnement des anciens plugins basés sur des hooks pendant que la - nouvelle architecture de plugin était en cours de construction. -- **`openclaw/extension-api`** — un pont qui donnait aux plugins un accès direct à - des helpers côté hôte comme l'exécuteur d'agent embarqué. +- **`openclaw/plugin-sdk/compat`** — un import unique qui réexportait des dizaines de helpers. Il a été introduit pour permettre aux anciens Plugins basés sur des hooks de continuer à fonctionner pendant la construction de la nouvelle architecture de Plugin. +- **`openclaw/extension-api`** — un pont qui donnait aux Plugins un accès direct à des helpers côté hôte, comme l’exécuteur d’agent embarqué. -Ces deux surfaces sont maintenant **obsolètes**. Elles fonctionnent toujours à l'exécution, mais les nouveaux -plugins ne doivent pas les utiliser, et les plugins existants doivent migrer avant que la prochaine -version majeure ne les supprime. +Ces deux surfaces sont désormais **dépréciées**. Elles fonctionnent toujours à l’exécution, mais les nouveaux Plugins ne doivent pas les utiliser, et les Plugins existants doivent migrer avant que la prochaine version majeure ne les supprime. - La couche de rétrocompatibilité sera supprimée dans une future version majeure. - Les plugins qui importent encore depuis ces surfaces ne fonctionneront plus lorsque cela arrivera. + La couche de compatibilité descendante sera supprimée dans une future version majeure. + Les Plugins qui importent encore depuis ces surfaces cesseront de fonctionner à ce moment-là. ## Pourquoi cela a changé -L'ancienne approche causait des problèmes : +L’ancienne approche causait des problèmes : -- **Démarrage lent** — importer un helper chargeait des dizaines de modules sans rapport -- **Dépendances circulaires** — les réexportations larges facilitaient la création de cycles d'import -- **Surface d'API floue** — il n'y avait aucun moyen de distinguer quels exports étaient stables et lesquels étaient internes +- **Démarrage lent** — l’import d’un helper chargeait des dizaines de modules sans lien +- **Dépendances circulaires** — de larges réexportations facilitaient la création de cycles d’import +- **Surface d’API peu claire** — il n’y avait aucun moyen de savoir quelles exportations étaient stables ou internes -Le Plugin SDK moderne corrige cela : chaque chemin d'import (`openclaw/plugin-sdk/\`) -est un petit module autonome avec une finalité claire et un contrat documenté. +Le Plugin SDK moderne corrige cela : chaque chemin d’import (`openclaw/plugin-sdk/\`) +est un petit module autonome avec un objectif clair et un contrat documenté. -Les interfaces de commodité provider héritées pour les canaux intégrés ont également disparu. Les imports +Les couches de commodité héritées pour les providers des canaux groupés ont également disparu. Les imports tels que `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -les interfaces helpers de marque de canal, ainsi que -`openclaw/plugin-sdk/telegram-core` étaient des raccourcis privés du mono-repo, pas -des contrats de plugin stables. Utilisez plutôt des sous-chemins SDK génériques et étroits. À l'intérieur de l' -espace de travail du plugin intégré, conservez les helpers détenus par le provider dans l' -`api.ts` ou `runtime-api.ts` de ce plugin. +les couches de helpers associées à une marque de canal, et +`openclaw/plugin-sdk/telegram-core` étaient des raccourcis privés du mono-repo, et non +des contrats de Plugin stables. Utilisez à la place des sous-chemins génériques étroits du SDK. Dans l’espace de travail +des Plugins groupés, conservez les helpers appartenant au provider dans le +`api.ts` ou le `runtime-api.ts` propre à ce Plugin. -Exemples actuels de providers intégrés : +Exemples actuels de providers groupés : -- Anthropic conserve les helpers de flux spécifiques à Claude dans sa propre interface `api.ts` / +- Anthropic conserve les helpers de flux spécifiques à Claude dans sa propre couche `api.ts` / `contract-api.ts` -- OpenAI conserve les builders de provider, les helpers de modèle par défaut et les builders de provider temps réel - dans son propre `api.ts` -- OpenRouter conserve le builder de provider ainsi que les helpers d'onboarding/configuration dans son propre +- OpenAI conserve les builders de provider, les helpers de modèle par défaut et les builders de provider + temps réel dans son propre `api.ts` +- OpenRouter conserve le builder de provider et les helpers d’onboarding/configuration dans son propre `api.ts` ## Comment migrer - - Les plugins de canal capables d'approbation exposent désormais le comportement d'approbation natif via - `approvalCapability.nativeRuntime` ainsi que le registre partagé de contexte d'exécution. + + Les Plugins de canal capables de gérer les approbations exposent désormais le comportement d’approbation natif via + `approvalCapability.nativeRuntime` ainsi que le registre partagé de contexte d’exécution. - Changements clés : + Principaux changements : - Remplacez `approvalCapability.handler.loadRuntime(...)` par `approvalCapability.nativeRuntime` - - Déplacez l'authentification/la livraison spécifiques aux approbations hors du câblage hérité `plugin.auth` / + - Déplacez l’authentification/la distribution spécifiques aux approbations hors de l’ancien câblage `plugin.auth` / `plugin.approvals` vers `approvalCapability` - - `ChannelPlugin.approvals` a été supprimé du contrat public du plugin de canal ; + - `ChannelPlugin.approvals` a été supprimé du contrat public du Plugin de canal ; déplacez les champs delivery/native/render vers `approvalCapability` - - `plugin.auth` reste réservé aux flux de connexion/déconnexion du canal ; les hooks d'authentification - d'approbation qui s'y trouvent ne sont plus lus par le cœur - - Enregistrez les objets d'exécution détenus par le canal tels que clients, jetons ou applications Bolt - via `openclaw/plugin-sdk/channel-runtime-context` - - N'envoyez pas d'avis de reroutage détenus par le plugin depuis des gestionnaires d'approbation natifs ; - le cœur gère désormais les avis « routé ailleurs » à partir des résultats de livraison réels - - Lors du passage de `channelRuntime` à `createChannelManager(...)`, fournissez une - vraie surface `createPluginRuntime().channel`. Les stubs partiels sont rejetés. + - `plugin.auth` reste utilisé uniquement pour les flux de connexion/déconnexion des canaux ; les hooks + d’authentification des approbations qui s’y trouvent ne sont plus lus par le core + - Enregistrez les objets d’exécution appartenant au canal, comme les clients, jetons ou applications + Bolt, via `openclaw/plugin-sdk/channel-runtime-context` + - N’envoyez pas d’avis de réacheminement appartenant au Plugin depuis les gestionnaires d’approbation natifs ; + le core gère désormais les avis « acheminé ailleurs » à partir des résultats réels de distribution + - Lors du passage de `channelRuntime` à `createChannelManager(...)`, fournissez une vraie + surface `createPluginRuntime().channel`. Les stubs partiels sont rejetés. Voir `/plugins/sdk-channel-plugins` pour la disposition actuelle de la - capacité d'approbation. + capacité d’approbation. - Si votre plugin utilise `openclaw/plugin-sdk/windows-spawn`, les wrappers Windows - `.cmd`/`.bat` non résolus échouent désormais de manière fermée sauf si vous passez explicitement + Si votre Plugin utilise `openclaw/plugin-sdk/windows-spawn`, les wrappers Windows + `.cmd`/`.bat` non résolus échouent désormais de manière stricte, sauf si vous transmettez explicitement `allowShellFallback: true`. ```typescript - // Avant + // Before const program = applyWindowsSpawnProgramPolicy({ candidate }); - // Après + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // Définissez ceci uniquement pour les appelants de compatibilité de confiance qui - // acceptent intentionnellement le repli via le shell. + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - Si votre appelant ne repose pas intentionnellement sur un repli shell, ne définissez pas - `allowShellFallback` et gérez plutôt l'erreur levée. + Si votre appelant ne dépend pas intentionnellement du repli via shell, ne définissez pas + `allowShellFallback` et gérez plutôt l’erreur levée. - - Recherchez dans votre plugin les imports depuis l'une ou l'autre des surfaces obsolètes : + + Recherchez dans votre Plugin les imports provenant de l’une ou l’autre surface dépréciée : ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -134,35 +126,35 @@ Exemples actuels de providers intégrés : - Chaque export de l'ancienne surface correspond à un chemin d'import moderne spécifique : + Chaque export de l’ancienne surface correspond à un chemin d’import moderne spécifique : ```typescript - // Avant (couche de rétrocompatibilité obsolète) + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Après (imports modernes ciblés) + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Pour les helpers côté hôte, utilisez le runtime de plugin injecté au lieu d'importer + Pour les helpers côté hôte, utilisez le runtime de Plugin injecté au lieu d’importer directement : ```typescript - // Avant (pont extension-api obsolète) + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Après (runtime injecté) + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Le même modèle s'applique aux autres helpers de pont hérités : + Le même modèle s’applique aux autres helpers hérités du pont : | Ancien import | Équivalent moderne | | --- | --- | @@ -172,7 +164,7 @@ Exemples actuels de providers intégrés : | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | helpers de magasin de session | `api.runtime.agent.session.*` | + | helpers du stockage de session | `api.runtime.agent.session.*` | @@ -184,227 +176,227 @@ Exemples actuels de providers intégrés : -## Référence des chemins d'import +## Référence des chemins d’import - - | Chemin d'import | Finalité | Exports clés | + + | Chemin d’import | Objectif | Exportations clés | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Helper canonique de point d'entrée de plugin | `definePluginEntry` | - | `plugin-sdk/core` | Réexportation parapluie héritée pour les définitions/builders d'entrée de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Export du schéma de configuration racine | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper de point d'entrée de provider unique | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Définitions et builders ciblés de point d'entrée de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Helpers partagés pour l'assistant de configuration | Prompts de liste d'autorisation, builders d'état de configuration | - | `plugin-sdk/setup-runtime` | Helpers d'exécution au moment de la configuration | Adaptateurs de patch de configuration sûrs à importer, helpers de notes de recherche, `promptResolvedAllowFrom`, `splitSetupEntries`, proxys de configuration déléguée | - | `plugin-sdk/setup-adapter-runtime` | Helpers d'adaptateur de configuration | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helpers d'outillage de configuration | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers multi-comptes | Helpers de liste/configuration/contrôle d'action de compte | - | `plugin-sdk/account-id` | Helpers d'ID de compte | `DEFAULT_ACCOUNT_ID`, normalisation d'ID de compte | + | `plugin-sdk/plugin-entry` | Helper d’entrée de Plugin canonique | `definePluginEntry` | + | `plugin-sdk/core` | Réexportation parapluie héritée pour les définitions/builders d’entrée de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Exportation du schéma de configuration racine | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Helper d’entrée à provider unique | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Définitions et builders d’entrée de canal ciblés | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Helpers partagés de l’assistant de configuration | Prompts de liste d’autorisation, builders d’état de configuration | + | `plugin-sdk/setup-runtime` | Helpers d’exécution au moment de la configuration | Adaptateurs de patch de configuration sûrs à l’import, helpers de notes de recherche, `promptResolvedAllowFrom`, `splitSetupEntries`, proxys de configuration déléguée | + | `plugin-sdk/setup-adapter-runtime` | Helpers d’adaptateur de configuration | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Helpers d’outillage de configuration | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Helpers multi-comptes | Helpers de liste/configuration/action gate de compte | + | `plugin-sdk/account-id` | Helpers d’identifiant de compte | `DEFAULT_ACCOUNT_ID`, normalisation de l’identifiant de compte | | `plugin-sdk/account-resolution` | Helpers de recherche de compte | Helpers de recherche de compte + repli par défaut | - | `plugin-sdk/account-helpers` | Helpers de compte étroits | Helpers de liste de compte/action de compte | - | `plugin-sdk/channel-setup` | Adaptateurs d'assistant de configuration | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ainsi que `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Primitives de pairage DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Câblage de préfixe de réponse + frappe | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Fabriques d'adaptateurs de configuration | `createHybridChannelConfigAdapter` | + | `plugin-sdk/account-helpers` | Helpers de compte ciblés | Helpers de liste de comptes/action de compte | + | `plugin-sdk/channel-setup` | Adaptateurs d’assistant de configuration | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | Primitives d’appairage DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Câblage du préfixe de réponse + saisie | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | Fabriques d’adaptateurs de configuration | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Builders de schéma de configuration | Types de schéma de configuration de canal | - | `plugin-sdk/telegram-command-config` | Helpers de configuration de commande Telegram | Normalisation de nom de commande, réduction de description, validation des doublons/conflits | + | `plugin-sdk/telegram-command-config` | Helpers de configuration des commandes Telegram | Normalisation des noms de commandes, réduction des descriptions, validation des doublons/conflits | | `plugin-sdk/channel-policy` | Résolution de politique groupe/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Suivi d'état de compte | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers d'enveloppe entrante | Helpers partagés de route + construction d'enveloppe | - | `plugin-sdk/inbound-reply-dispatch` | Helpers de réponse entrante | Helpers partagés d'enregistrement et de distribution | - | `plugin-sdk/messaging-targets` | Analyse des cibles de messagerie | Helpers d'analyse/correspondance de cible | - | `plugin-sdk/outbound-media` | Helpers de média sortant | Chargement partagé de média sortant | - | `plugin-sdk/outbound-runtime` | Helpers d'exécution sortante | Helpers de délégation d'identité/d'envoi sortants | - | `plugin-sdk/thread-bindings-runtime` | Helpers de liaison de thread | Helpers de cycle de vie de liaison de thread et d'adaptateur | - | `plugin-sdk/agent-media-payload` | Helpers hérités de charge utile média | Builder de charge utile média d'agent pour des dispositions de champs héritées | - | `plugin-sdk/channel-runtime` | Shim de compatibilité obsolète | Utilitaires d'exécution de canal hérités uniquement | - | `plugin-sdk/channel-send-result` | Types de résultat d'envoi | Types de résultat de réponse | - | `plugin-sdk/runtime-store` | Stockage persistant de plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Helpers d'exécution étendus | Helpers d'exécution/journalisation/sauvegarde/installation de plugin | - | `plugin-sdk/runtime-env` | Helpers d'environnement d'exécution étroits | Helpers de logger/environnement d'exécution, délai, retry et backoff | - | `plugin-sdk/plugin-runtime` | Helpers partagés d'exécution de plugin | Helpers de commandes/hooks/http/interactifs de plugin | - | `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers partagés de pipeline de hooks webhook/internes | - | `plugin-sdk/lazy-runtime` | Helpers d'exécution différée | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpers de processus | Helpers partagés d'exécution de commande | - | `plugin-sdk/cli-runtime` | Helpers d'exécution CLI | Formatage de commandes, attentes, helpers de version | - | `plugin-sdk/gateway-runtime` | Helpers de passerelle | Client de passerelle et helpers de patch d'état de canal | + | `plugin-sdk/channel-lifecycle` | Suivi de l’état du compte | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Helpers d’enveloppe entrante | Helpers partagés de route + construction d’enveloppe | + | `plugin-sdk/inbound-reply-dispatch` | Helpers de réponse entrante | Helpers partagés d’enregistrement et de répartition | + | `plugin-sdk/messaging-targets` | Analyse des cibles de messagerie | Helpers d’analyse/correspondance de cibles | + | `plugin-sdk/outbound-media` | Helpers de médias sortants | Chargement partagé des médias sortants | + | `plugin-sdk/outbound-runtime` | Helpers d’exécution sortante | Helpers de délégation d’identité/d’envoi sortants | + | `plugin-sdk/thread-bindings-runtime` | Helpers de liaison de fil | Helpers de cycle de vie et d’adaptateur de liaison de fil | + | `plugin-sdk/agent-media-payload` | Helpers hérités de payload média | Builder de payload média d’agent pour les dispositions de champs héritées | + | `plugin-sdk/channel-runtime` | Shim de compatibilité déprécié | Utilitaires hérités d’exécution de canal uniquement | + | `plugin-sdk/channel-send-result` | Types de résultat d’envoi | Types de résultat de réponse | + | `plugin-sdk/runtime-store` | Stockage persistant de Plugin | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Helpers d’exécution étendus | Helpers d’exécution/journalisation/sauvegarde/installation de Plugin | + | `plugin-sdk/runtime-env` | Helpers ciblés d’environnement d’exécution | Logger/runtime env, helpers de délai d’expiration, de retry et de backoff | + | `plugin-sdk/plugin-runtime` | Helpers partagés d’exécution de Plugin | Helpers de commandes/hooks/http/interactifs de Plugin | + | `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers partagés de pipeline de Webhook/hook interne | + | `plugin-sdk/lazy-runtime` | Helpers d’exécution paresseuse | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helpers de processus | Helpers partagés d’exécution | + | `plugin-sdk/cli-runtime` | Helpers d’exécution CLI | Formatage des commandes, attentes, helpers de version | + | `plugin-sdk/gateway-runtime` | Helpers Gateway | Client Gateway et helpers de patch d’état de canal | | `plugin-sdk/config-runtime` | Helpers de configuration | Helpers de chargement/écriture de configuration | - | `plugin-sdk/telegram-command-config` | Helpers de commande Telegram | Helpers de validation de commande Telegram stables en repli lorsque la surface de contrat Telegram intégrée n'est pas disponible | - | `plugin-sdk/approval-runtime` | Helpers de prompt d'approbation | Charge utile d'approbation exec/plugin, helpers de capacité/profil d'approbation, helpers natifs de routage/runtime d'approbation | - | `plugin-sdk/approval-auth-runtime` | Helpers d'authentification d'approbation | Résolution d'approbateur, authentification d'action dans le même chat | - | `plugin-sdk/approval-client-runtime` | Helpers client d'approbation | Helpers natifs de profil/filtre d'approbation exec | - | `plugin-sdk/approval-delivery-runtime` | Helpers de livraison d'approbation | Adaptateurs natifs de capacité/livraison d'approbation | - | `plugin-sdk/approval-gateway-runtime` | Helpers de passerelle d'approbation | Helper partagé de résolution de passerelle d'approbation | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers d'adaptateur d'approbation | Helpers légers de chargement d'adaptateur d'approbation natif pour points d'entrée de canal à chaud | - | `plugin-sdk/approval-handler-runtime` | Helpers de gestionnaire d'approbation | Helpers d'exécution plus larges pour gestionnaire d'approbation ; préférez les interfaces plus étroites d'adaptateur/passerelle lorsqu'elles suffisent | - | `plugin-sdk/approval-native-runtime` | Helpers de cible d'approbation | Helpers natifs de liaison cible/compte d'approbation | - | `plugin-sdk/approval-reply-runtime` | Helpers de réponse d'approbation | Helpers de charge utile de réponse d'approbation exec/plugin | - | `plugin-sdk/channel-runtime-context` | Helpers de contexte d'exécution de canal | Helpers génériques d'enregistrement/obtention/surveillance de contexte d'exécution de canal | - | `plugin-sdk/security-runtime` | Helpers de sécurité | Helpers partagés de confiance, contrôle DM, contenu externe et collecte de secrets | - | `plugin-sdk/ssrf-policy` | Helpers de politique SSRF | Helpers de liste d'autorisation d'hôte et de politique de réseau privé | - | `plugin-sdk/ssrf-runtime` | Helpers d'exécution SSRF | Helpers de pinned-dispatcher, fetch protégé et politique SSRF | + | `plugin-sdk/telegram-command-config` | Helpers de commandes Telegram | Helpers de validation de commandes Telegram stables en repli lorsque la surface de contrat Telegram groupée n’est pas disponible | + | `plugin-sdk/approval-runtime` | Helpers de prompt d’approbation | Helpers de payload d’approbation exec/Plugin, de capacité/profil d’approbation, de routage/exécution d’approbation native | + | `plugin-sdk/approval-auth-runtime` | Helpers d’authentification d’approbation | Résolution de l’approbateur, autorisation d’action dans le même chat | + | `plugin-sdk/approval-client-runtime` | Helpers de client d’approbation | Helpers de profil/filtre d’approbation exec native | + | `plugin-sdk/approval-delivery-runtime` | Helpers de distribution d’approbation | Adaptateurs de capacité/distribution d’approbation native | + | `plugin-sdk/approval-gateway-runtime` | Helpers Gateway d’approbation | Helper partagé de résolution de Gateway d’approbation | + | `plugin-sdk/approval-handler-adapter-runtime` | Helpers d’adaptateur d’approbation | Helpers légers de chargement d’adaptateur d’approbation native pour les points d’entrée de canal à chaud | + | `plugin-sdk/approval-handler-runtime` | Helpers de gestionnaire d’approbation | Helpers plus étendus d’exécution de gestionnaire d’approbation ; préférez les couches adaptateur/Gateway plus ciblées lorsqu’elles suffisent | + | `plugin-sdk/approval-native-runtime` | Helpers de cible d’approbation | Helpers natifs de cible d’approbation/liaison de compte | + | `plugin-sdk/approval-reply-runtime` | Helpers de réponse d’approbation | Helpers de payload de réponse d’approbation exec/Plugin | + | `plugin-sdk/channel-runtime-context` | Helpers de contexte d’exécution de canal | Helpers génériques d’enregistrement/lecture/surveillance du contexte d’exécution de canal | + | `plugin-sdk/security-runtime` | Helpers de sécurité | Helpers partagés de confiance, de filtrage DM, de contenu externe et de collecte de secrets | + | `plugin-sdk/ssrf-policy` | Helpers de politique SSRF | Helpers de liste d’autorisation d’hôte et de politique réseau privé | + | `plugin-sdk/ssrf-runtime` | Helpers d’exécution SSRF | Répartiteur épinglé, fetch protégé, helpers de politique SSRF | | `plugin-sdk/collection-runtime` | Helpers de cache borné | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helpers de contrôle diagnostic | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helpers de formatage d'erreur | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de graphe d'erreur | - | `plugin-sdk/fetch-runtime` | Helpers fetch/proxy encapsulés | `resolveFetch`, helpers de proxy | - | `plugin-sdk/host-runtime` | Helpers de normalisation d'hôte | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/diagnostic-runtime` | Helpers de filtrage diagnostique | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Helpers de formatage des erreurs | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de graphe d’erreurs | + | `plugin-sdk/fetch-runtime` | Helpers de fetch/proxy encapsulés | `resolveFetch`, helpers de proxy | + | `plugin-sdk/host-runtime` | Helpers de normalisation d’hôte | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | Helpers de retry | `RetryConfig`, `retryAsync`, exécuteurs de politique | - | `plugin-sdk/allow-from` | Formatage de liste d'autorisation | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Mappage d'entrée de liste d'autorisation | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Contrôle de commande et helpers de surface de commande | `resolveControlCommandGate`, helpers d'autorisation d'expéditeur, helpers de registre de commandes | - | `plugin-sdk/command-status` | Rendu d'état/d'aide des commandes | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Analyse d'entrée de secret | Helpers d'entrée de secret | - | `plugin-sdk/webhook-ingress` | Helpers de requête webhook | Utilitaires de cible webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de protection du corps webhook | Helpers de lecture/limite de corps de requête | - | `plugin-sdk/reply-runtime` | Runtime de réponse partagé | Distribution entrante, heartbeat, planificateur de réponse, découpage | - | `plugin-sdk/reply-dispatch-runtime` | Helpers étroits de distribution de réponse | Helpers de finalisation + distribution provider | - | `plugin-sdk/reply-history` | Helpers d'historique de réponse | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/allow-from` | Formatage de liste d’autorisation | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mappage d’entrée de liste d’autorisation | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Filtrage des commandes et helpers de surface de commande | `resolveControlCommandGate`, helpers d’autorisation de l’expéditeur, helpers de registre de commandes | + | `plugin-sdk/command-status` | Moteurs de rendu d’état/aide des commandes | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Analyse des entrées secrètes | Helpers d’entrée secrète | + | `plugin-sdk/webhook-ingress` | Helpers de requête Webhook | Utilitaires de cible Webhook | + | `plugin-sdk/webhook-request-guards` | Helpers de garde du corps de requête Webhook | Helpers de lecture/limitation du corps de requête | + | `plugin-sdk/reply-runtime` | Exécution partagée des réponses | Répartition entrante, Heartbeat, planificateur de réponse, découpage | + | `plugin-sdk/reply-dispatch-runtime` | Helpers ciblés de répartition des réponses | Helpers de finalisation + répartition provider | + | `plugin-sdk/reply-history` | Helpers d’historique des réponses | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | Planification de référence de réponse | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers de découpage de réponse | Helpers de découpage texte/markdown | - | `plugin-sdk/session-store-runtime` | Helpers de magasin de session | Helpers de chemin de magasin + updated-at | - | `plugin-sdk/state-paths` | Helpers de chemins d'état | Helpers de répertoires d'état et OAuth | + | `plugin-sdk/reply-chunking` | Helpers de découpage des réponses | Helpers de découpage texte/Markdown | + | `plugin-sdk/session-store-runtime` | Helpers de stockage de session | Helpers de chemin de stockage + `updated-at` | + | `plugin-sdk/state-paths` | Helpers de chemins d’état | Helpers de répertoire d’état et OAuth | | `plugin-sdk/routing` | Helpers de routage/clé de session | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalisation de clé de session | - | `plugin-sdk/status-helpers` | Helpers d'état de canal | Builders de résumé d'état de canal/compte, valeurs par défaut d'état runtime, helpers de métadonnées de problème | + | `plugin-sdk/status-helpers` | Helpers d’état de canal | Builders de résumé d’état de canal/compte, valeurs par défaut d’état d’exécution, helpers de métadonnées d’incident | | `plugin-sdk/target-resolver-runtime` | Helpers de résolution de cible | Helpers partagés de résolution de cible | - | `plugin-sdk/string-normalization-runtime` | Helpers de normalisation de chaîne | Helpers de normalisation slug/chaîne | - | `plugin-sdk/request-url` | Helpers d'URL de requête | Extraction d'URL chaîne depuis des entrées de type requête | - | `plugin-sdk/run-command` | Helpers de commande temporisée | Exécuteur de commande temporisée avec stdout/stderr normalisés | - | `plugin-sdk/param-readers` | Lecteurs de paramètres | Lecteurs communs de paramètres d'outil/CLI | - | `plugin-sdk/tool-payload` | Extraction de charge utile d'outil | Extraction de charges utiles normalisées depuis des objets de résultat d'outil | - | `plugin-sdk/tool-send` | Extraction d'envoi d'outil | Extraction des champs de cible d'envoi canoniques depuis les arguments d'outil | - | `plugin-sdk/temp-path` | Helpers de chemins temporaires | Helpers partagés de chemin de téléchargement temporaire | - | `plugin-sdk/logging-core` | Helpers de journalisation | Logger de sous-système et helpers de masquage | - | `plugin-sdk/markdown-table-runtime` | Helpers de tableau Markdown | Helpers de mode tableau Markdown | - | `plugin-sdk/reply-payload` | Types de réponse de message | Types de charge utile de réponse | - | `plugin-sdk/provider-setup` | Helpers de configuration sélectionnés pour providers locaux/autohébergés | Helpers de découverte/configuration de provider autohébergé | - | `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de provider autohébergé compatible OpenAI | Les mêmes helpers de découverte/configuration de provider autohébergé | - | `plugin-sdk/provider-auth-runtime` | Helpers d'authentification runtime de provider | Helpers de résolution runtime de clé API | - | `plugin-sdk/provider-auth-api-key` | Helpers de configuration de clé API provider | Helpers d'onboarding/écriture de profil de clé API | - | `plugin-sdk/provider-auth-result` | Helpers de résultat d'authentification provider | Builder standard de résultat d'authentification OAuth | - | `plugin-sdk/provider-auth-login` | Helpers de connexion interactive provider | Helpers partagés de connexion interactive | - | `plugin-sdk/provider-env-vars` | Helpers de variables d'environnement provider | Helpers de recherche de variables d'environnement d'authentification provider | - | `plugin-sdk/provider-model-shared` | Helpers partagés de modèle/relecture provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders partagés de politique de relecture, helpers de point d'accès provider et helpers de normalisation d'ID de modèle | - | `plugin-sdk/provider-catalog-shared` | Helpers partagés de catalogue provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Patches d'onboarding provider | Helpers de configuration d'onboarding | - | `plugin-sdk/provider-http` | Helpers HTTP provider | Helpers génériques HTTP/capacités de point d'accès provider | - | `plugin-sdk/provider-web-fetch` | Helpers web-fetch provider | Helpers d'enregistrement/cache de provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpers de configuration de recherche web provider | Helpers étroits de configuration/identifiants de recherche web pour les providers qui n'ont pas besoin de câblage d'activation de plugin | - | `plugin-sdk/provider-web-search-contract` | Helpers de contrat de recherche web provider | Helpers étroits de contrat de configuration/identifiants de recherche web tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et setters/getters d'identifiants à portée limitée | - | `plugin-sdk/provider-web-search` | Helpers de recherche web provider | Helpers d'enregistrement/cache/runtime de provider de recherche web | - | `plugin-sdk/provider-tools` | Helpers de compatibilité provider outil/schéma | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helpers d'usage provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`, et autres helpers d'usage provider | - | `plugin-sdk/provider-stream` | Helpers d'encapsulation de flux provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types d'encapsulation de flux, et helpers partagés d'encapsulation Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | File async ordonnée | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Helpers média partagés | Helpers de récupération/transformation/stockage de média ainsi que builders de charge utile média | - | `plugin-sdk/media-generation-runtime` | Helpers partagés de génération média | Helpers partagés de basculement, sélection de candidat, et messages de modèle manquant pour la génération d'image/vidéo/musique | - | `plugin-sdk/media-understanding` | Helpers de compréhension média | Types de provider de compréhension média ainsi que exports de helpers image/audio côté provider | - | `plugin-sdk/text-runtime` | Helpers texte partagés | Suppression de texte visible par l'assistant, helpers de rendu/découpage/tableau markdown, helpers de masquage, helpers de balises de directive, utilitaires de texte sûr, et helpers associés de texte/journalisation | + | `plugin-sdk/string-normalization-runtime` | Helpers de normalisation de chaîne | Helpers de normalisation de slug/chaîne | + | `plugin-sdk/request-url` | Helpers d’URL de requête | Extraire des URL sous forme de chaîne à partir d’entrées de type requête | + | `plugin-sdk/run-command` | Helpers de commande chronométrée | Exécuteur de commande chronométrée avec stdout/stderr normalisés | + | `plugin-sdk/param-readers` | Lecteurs de paramètres | Lecteurs courants de paramètres d’outil/CLI | + | `plugin-sdk/tool-payload` | Extraction de payload d’outil | Extraire des payloads normalisés à partir d’objets de résultat d’outil | + | `plugin-sdk/tool-send` | Extraction d’envoi d’outil | Extraire les champs canoniques de cible d’envoi à partir des arguments d’outil | + | `plugin-sdk/temp-path` | Helpers de chemin temporaire | Helpers partagés de chemin de téléchargement temporaire | + | `plugin-sdk/logging-core` | Helpers de journalisation | Logger de sous-système et helpers de rédaction | + | `plugin-sdk/markdown-table-runtime` | Helpers de tableau Markdown | Helpers de mode de tableau Markdown | + | `plugin-sdk/reply-payload` | Types de réponse de message | Types de payload de réponse | + | `plugin-sdk/provider-setup` | Helpers de configuration local/self-hosted de provider organisés | Helpers de découverte/configuration de provider auto-hébergé | + | `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de provider auto-hébergé compatible OpenAI | Les mêmes helpers de découverte/configuration de provider auto-hébergé | + | `plugin-sdk/provider-auth-runtime` | Helpers d’authentification d’exécution du provider | Helpers de résolution de clé API à l’exécution | + | `plugin-sdk/provider-auth-api-key` | Helpers de configuration de clé API du provider | Helpers d’onboarding/écriture de profil de clé API | + | `plugin-sdk/provider-auth-result` | Helpers de résultat d’authentification du provider | Builder standard de résultat d’authentification OAuth | + | `plugin-sdk/provider-auth-login` | Helpers de connexion interactive du provider | Helpers partagés de connexion interactive | + | `plugin-sdk/provider-env-vars` | Helpers de variables d’environnement du provider | Helpers de recherche de variables d’environnement d’authentification du provider | + | `plugin-sdk/provider-model-shared` | Helpers partagés de modèle/relecture du provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders partagés de politique de relecture, helpers de point de terminaison du provider et helpers de normalisation d’identifiant de modèle | + | `plugin-sdk/provider-catalog-shared` | Helpers partagés du catalogue de providers | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Correctifs d’onboarding des providers | Helpers de configuration d’onboarding | + | `plugin-sdk/provider-http` | Helpers HTTP des providers | Helpers génériques HTTP/capacités de point de terminaison des providers | + | `plugin-sdk/provider-web-fetch` | Helpers de web-fetch des providers | Helpers d’enregistrement/de cache des providers de web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helpers de configuration de recherche web des providers | Helpers ciblés de configuration/d’identifiants de recherche web pour les providers qui n’ont pas besoin de câblage d’activation de Plugin | + | `plugin-sdk/provider-web-search-contract` | Helpers de contrat de recherche web des providers | Helpers ciblés de contrat de configuration/d’identifiants de recherche web tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` et setters/getters d’identifiants à portée limitée | + | `plugin-sdk/provider-web-search` | Helpers de recherche web des providers | Helpers d’enregistrement/de cache/d’exécution des providers de recherche web | + | `plugin-sdk/provider-tools` | Helpers de compatibilité outil/schéma des providers | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Helpers d’usage des providers | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` et autres helpers d’usage des providers | + | `plugin-sdk/provider-stream` | Helpers d’encapsulation de flux des providers | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types d’encapsulation de flux, et helpers partagés d’encapsulation Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | File asynchrone ordonnée | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Helpers média partagés | Helpers de récupération/transformation/stockage de média ainsi que builders de payload média | + | `plugin-sdk/media-generation-runtime` | Helpers partagés de génération de média | Helpers partagés de basculement, sélection de candidats et messages de modèle manquant pour la génération d’image/vidéo/musique | + | `plugin-sdk/media-understanding` | Helpers de compréhension des médias | Types de providers de compréhension des médias ainsi qu’exports de helpers image/audio destinés aux providers | + | `plugin-sdk/text-runtime` | Helpers texte partagés | Suppression du texte visible par l’assistant, helpers de rendu/découpage/tableau Markdown, helpers de rédaction, helpers de balises de directive, utilitaires de texte sûr et helpers associés de texte/journalisation | | `plugin-sdk/text-chunking` | Helpers de découpage de texte | Helper de découpage de texte sortant | - | `plugin-sdk/speech` | Helpers de parole | Types de provider speech ainsi que helpers côté provider de directive, registre et validation | - | `plugin-sdk/speech-core` | Cœur speech partagé | Types de provider speech, registre, directives, normalisation | - | `plugin-sdk/realtime-transcription` | Helpers de transcription temps réel | Helpers de types provider et de registre | - | `plugin-sdk/realtime-voice` | Helpers de voix temps réel | Helpers de types provider et de registre | - | `plugin-sdk/image-generation-core` | Cœur partagé de génération d'image | Helpers de types, basculement, authentification et registre pour génération d'image | - | `plugin-sdk/music-generation` | Helpers de génération musicale | Types de provider/requête/résultat pour génération musicale | - | `plugin-sdk/music-generation-core` | Cœur partagé de génération musicale | Types de génération musicale, helpers de basculement, recherche de provider et analyse de référence de modèle | - | `plugin-sdk/video-generation` | Helpers de génération vidéo | Types de provider/requête/résultat pour génération vidéo | - | `plugin-sdk/video-generation-core` | Cœur partagé de génération vidéo | Types de génération vidéo, helpers de basculement, recherche de provider et analyse de référence de modèle | - | `plugin-sdk/interactive-runtime` | Helpers de réponse interactive | Normalisation/réduction de charge utile de réponse interactive | - | `plugin-sdk/channel-config-primitives` | Primitives de configuration de canal | Primitives étroites de schéma de configuration de canal | - | `plugin-sdk/channel-config-writes` | Helpers d'écriture de configuration de canal | Helpers d'autorisation d'écriture de configuration de canal | - | `plugin-sdk/channel-plugin-common` | Prélude de canal partagé | Exports partagés de prélude de plugin de canal | - | `plugin-sdk/channel-status` | Helpers d'état de canal | Helpers partagés d'instantané/résumé d'état de canal | - | `plugin-sdk/allowlist-config-edit` | Helpers de configuration de liste d'autorisation | Helpers de lecture/édition de configuration de liste d'autorisation | - | `plugin-sdk/group-access` | Helpers d'accès de groupe | Helpers partagés de décision d'accès de groupe | - | `plugin-sdk/direct-dm` | Helpers de DM direct | Helpers partagés d'authentification/protection de DM direct | - | `plugin-sdk/extension-shared` | Helpers d'extension partagés | Primitives helpers de canal passif/état et proxy ambiant | - | `plugin-sdk/webhook-targets` | Helpers de cibles webhook | Registre de cibles webhook et helpers d'installation de route | - | `plugin-sdk/webhook-path` | Helpers de chemin webhook | Helpers de normalisation de chemin webhook | + | `plugin-sdk/speech` | Helpers Speech | Types de providers Speech ainsi qu’helpers de directive, de registre et de validation destinés aux providers | + | `plugin-sdk/speech-core` | Noyau Speech partagé | Types de providers Speech, registre, directives, normalisation | + | `plugin-sdk/realtime-transcription` | Helpers de transcription en temps réel | Types de providers et helpers de registre | + | `plugin-sdk/realtime-voice` | Helpers de voix en temps réel | Types de providers et helpers de registre | + | `plugin-sdk/image-generation-core` | Noyau partagé de génération d’images | Types, helpers de basculement, d’authentification et de registre pour la génération d’images | + | `plugin-sdk/music-generation` | Helpers de génération de musique | Types de provider/requête/résultat pour la génération de musique | + | `plugin-sdk/music-generation-core` | Noyau partagé de génération de musique | Types de génération de musique, helpers de basculement, recherche de provider et analyse de model-ref | + | `plugin-sdk/video-generation` | Helpers de génération de vidéo | Types de provider/requête/résultat pour la génération de vidéo | + | `plugin-sdk/video-generation-core` | Noyau partagé de génération de vidéo | Types de génération de vidéo, helpers de basculement, recherche de provider et analyse de model-ref | + | `plugin-sdk/interactive-runtime` | Helpers de réponse interactive | Normalisation/réduction du payload de réponse interactive | + | `plugin-sdk/channel-config-primitives` | Primitives de configuration de canal | Primitives ciblées de schéma de configuration de canal | + | `plugin-sdk/channel-config-writes` | Helpers d’écriture de configuration de canal | Helpers d’autorisation d’écriture de configuration de canal | + | `plugin-sdk/channel-plugin-common` | Prélude de canal partagé | Exports partagés du prélude de Plugin de canal | + | `plugin-sdk/channel-status` | Helpers d’état de canal | Helpers partagés d’instantané/de résumé de l’état du canal | + | `plugin-sdk/allowlist-config-edit` | Helpers de configuration de liste d’autorisation | Helpers d’édition/de lecture de configuration de liste d’autorisation | + | `plugin-sdk/group-access` | Helpers d’accès de groupe | Helpers partagés de décision d’accès de groupe | + | `plugin-sdk/direct-dm` | Helpers de DM direct | Helpers partagés d’authentification/de garde pour DM direct | + | `plugin-sdk/extension-shared` | Helpers d’extension partagés | Primitives de helper pour canal passif/état et proxy ambiant | + | `plugin-sdk/webhook-targets` | Helpers de cible Webhook | Helpers de registre de cible Webhook et d’installation de route | + | `plugin-sdk/webhook-path` | Helpers de chemin Webhook | Helpers de normalisation de chemin Webhook | | `plugin-sdk/web-media` | Helpers média web partagés | Helpers de chargement de média distant/local | - | `plugin-sdk/zod` | Réexportation Zod | `zod` réexporté pour les consommateurs du Plugin SDK | - | `plugin-sdk/memory-core` | Helpers memory-core intégrés | Surface helper de gestionnaire/configuration/fichier/CLI mémoire | - | `plugin-sdk/memory-core-engine-runtime` | Façade runtime du moteur mémoire | Façade runtime d'indexation/recherche mémoire | - | `plugin-sdk/memory-core-host-engine-foundation` | Moteur foundation hôte mémoire | Exports du moteur foundation hôte mémoire | - | `plugin-sdk/memory-core-host-engine-embeddings` | Moteur d'embeddings hôte mémoire | Exports du moteur d'embeddings hôte mémoire | - | `plugin-sdk/memory-core-host-engine-qmd` | Moteur QMD hôte mémoire | Exports du moteur QMD hôte mémoire | - | `plugin-sdk/memory-core-host-engine-storage` | Moteur de stockage hôte mémoire | Exports du moteur de stockage hôte mémoire | - | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux hôte mémoire | Helpers multimodaux hôte mémoire | - | `plugin-sdk/memory-core-host-query` | Helpers de requête hôte mémoire | Helpers de requête hôte mémoire | - | `plugin-sdk/memory-core-host-secret` | Helpers de secret hôte mémoire | Helpers de secret hôte mémoire | - | `plugin-sdk/memory-core-host-events` | Helpers de journal d'événements hôte mémoire | Helpers de journal d'événements hôte mémoire | - | `plugin-sdk/memory-core-host-status` | Helpers d'état hôte mémoire | Helpers d'état hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI hôte mémoire | Helpers runtime CLI hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-core` | Runtime cœur hôte mémoire | Helpers runtime cœur hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers fichier/runtime hôte mémoire | Helpers fichier/runtime hôte mémoire | - | `plugin-sdk/memory-host-core` | Alias runtime cœur hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers runtime cœur hôte mémoire | - | `plugin-sdk/memory-host-events` | Alias journal d'événements hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d'événements hôte mémoire | - | `plugin-sdk/memory-host-files` | Alias fichier/runtime hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers fichier/runtime hôte mémoire | - | `plugin-sdk/memory-host-markdown` | Helpers markdown géré | Helpers partagés de markdown géré pour les plugins adjacents à la mémoire | - | `plugin-sdk/memory-host-search` | Façade de recherche de mémoire active | Façade runtime différée du gestionnaire de recherche de mémoire active | - | `plugin-sdk/memory-host-status` | Alias d'état hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers d'état hôte mémoire | - | `plugin-sdk/memory-lancedb` | Helpers memory-lancedb intégrés | Surface helper memory-lancedb | - | `plugin-sdk/testing` | Utilitaires de test | Helpers et mocks de test | + | `plugin-sdk/zod` | Réexportation de Zod | `zod` réexporté pour les consommateurs du Plugin SDK | + | `plugin-sdk/memory-core` | Helpers groupés memory-core | Surface de helpers pour le gestionnaire/configuration/fichier/CLI de la mémoire | + | `plugin-sdk/memory-core-engine-runtime` | Façade d’exécution du moteur mémoire | Façade d’exécution d’indexation/recherche mémoire | + | `plugin-sdk/memory-core-host-engine-foundation` | Moteur de fondation hôte de la mémoire | Exports du moteur de fondation hôte de la mémoire | + | `plugin-sdk/memory-core-host-engine-embeddings` | Moteur d’embeddings hôte de la mémoire | Contrats d’embeddings mémoire, accès au registre, provider local et helpers génériques de lot/distant ; les providers distants concrets résident dans leurs Plugins propriétaires | + | `plugin-sdk/memory-core-host-engine-qmd` | Moteur QMD hôte de la mémoire | Exports du moteur QMD hôte de la mémoire | + | `plugin-sdk/memory-core-host-engine-storage` | Moteur de stockage hôte de la mémoire | Exports du moteur de stockage hôte de la mémoire | + | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux hôte de la mémoire | Helpers multimodaux hôte de la mémoire | + | `plugin-sdk/memory-core-host-query` | Helpers de requête hôte de la mémoire | Helpers de requête hôte de la mémoire | + | `plugin-sdk/memory-core-host-secret` | Helpers de secret hôte de la mémoire | Helpers de secret hôte de la mémoire | + | `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements hôte de la mémoire | Helpers de journal d’événements hôte de la mémoire | + | `plugin-sdk/memory-core-host-status` | Helpers d’état hôte de la mémoire | Helpers d’état hôte de la mémoire | + | `plugin-sdk/memory-core-host-runtime-cli` | Exécution CLI hôte de la mémoire | Helpers d’exécution CLI hôte de la mémoire | + | `plugin-sdk/memory-core-host-runtime-core` | Exécution core hôte de la mémoire | Helpers d’exécution core hôte de la mémoire | + | `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/d’exécution hôte de la mémoire | Helpers de fichier/d’exécution hôte de la mémoire | + | `plugin-sdk/memory-host-core` | Alias d’exécution core hôte de la mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers d’exécution core hôte de la mémoire | + | `plugin-sdk/memory-host-events` | Alias de journal d’événements hôte de la mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements hôte de la mémoire | + | `plugin-sdk/memory-host-files` | Alias de fichier/d’exécution hôte de la mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/d’exécution hôte de la mémoire | + | `plugin-sdk/memory-host-markdown` | Helpers de Markdown géré | Helpers partagés de Markdown géré pour les Plugins adjacents à la mémoire | + | `plugin-sdk/memory-host-search` | Façade de recherche Active Memory | Façade d’exécution paresseuse du gestionnaire de recherche Active Memory | + | `plugin-sdk/memory-host-status` | Alias d’état hôte de la mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers d’état hôte de la mémoire | + | `plugin-sdk/memory-lancedb` | Helpers groupés memory-lancedb | Surface de helpers memory-lancedb | + | `plugin-sdk/testing` | Utilitaires de test | Helpers de test et mocks | -Ce tableau est volontairement le sous-ensemble courant de migration, et non la surface complète du SDK. -La liste complète des plus de 200 points d'entrée se trouve dans +Ce tableau correspond intentionnellement au sous-ensemble commun de migration, et non à la surface complète +du SDK. La liste complète des plus de 200 points d’entrée se trouve dans `scripts/lib/plugin-sdk-entrypoints.json`. -Cette liste inclut encore certaines interfaces helpers de plugins intégrés telles que +Cette liste inclut encore certaines couches de helpers de Plugins groupés telles que `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` et `plugin-sdk/matrix*`. Elles restent exportées pour -la maintenance et la compatibilité des plugins intégrés, mais elles sont intentionnellement -omises du tableau de migration courant et ne sont pas la cible recommandée pour -du nouveau code de plugin. +`plugin-sdk/zalo-setup`, et `plugin-sdk/matrix*`. Elles restent exportées pour la +maintenance et la compatibilité des Plugins groupés, mais elles sont volontairement +omises du tableau de migration commun et ne constituent pas la cible recommandée pour +le nouveau code de Plugin. -La même règle s'applique aux autres familles de helpers intégrés telles que : +La même règle s’applique aux autres familles de helpers groupés telles que : - helpers de prise en charge du navigateur : `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix : `plugin-sdk/matrix*` - LINE : `plugin-sdk/line*` - IRC : `plugin-sdk/irc*` -- surfaces de helper/plugin intégrées comme `plugin-sdk/googlechat`, +- surfaces de helper/Plugin groupées comme `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, - `plugin-sdk/thread-ownership` et `plugin-sdk/voice-call` + `plugin-sdk/thread-ownership`, et `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` expose actuellement la surface étroite de helper de jeton +`plugin-sdk/github-copilot-token` expose actuellement la surface ciblée de helper de jeton `DEFAULT_COPILOT_API_BASE_URL`, -`deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken`. +`deriveCopilotApiBaseUrlFromToken`, et `resolveCopilotApiToken`. -Utilisez l'import le plus étroit correspondant au besoin. Si vous ne trouvez pas un export, -consultez la source dans `src/plugin-sdk/` ou demandez sur Discord. +Utilisez l’import le plus ciblé qui correspond à la tâche. Si vous ne trouvez pas une exportation, +consultez la source dans `src/plugin-sdk/` ou demandez dans Discord. ## Calendrier de suppression | Quand | Ce qui se passe | | ---------------------- | ----------------------------------------------------------------------- | -| **Maintenant** | Les surfaces obsolètes émettent des avertissements à l'exécution | -| **Prochaine version majeure** | Les surfaces obsolètes seront supprimées ; les plugins qui les utilisent encore échoueront | +| **Maintenant** | Les surfaces dépréciées émettent des avertissements à l’exécution | +| **Prochaine version majeure** | Les surfaces dépréciées seront supprimées ; les Plugins qui les utilisent encore échoueront | -Tous les plugins du cœur ont déjà été migrés. Les plugins externes doivent migrer +Tous les Plugins du core ont déjà été migrés. Les Plugins externes doivent migrer avant la prochaine version majeure. ## Supprimer temporairement les avertissements -Définissez ces variables d'environnement pendant que vous travaillez à la migration : +Définissez ces variables d’environnement pendant que vous travaillez à la migration : ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Il s'agit d'une échappatoire temporaire, pas d'une solution permanente. +Il s’agit d’une échappatoire temporaire, et non d’une solution permanente. ## Liens associés -- [Premiers pas](/fr/plugins/building-plugins) — créez votre premier plugin -- [Vue d'ensemble du SDK](/fr/plugins/sdk-overview) — référence complète des imports par sous-chemin -- [Plugins de canal](/fr/plugins/sdk-channel-plugins) — création de plugins de canal -- [Plugins de provider](/fr/plugins/sdk-provider-plugins) — création de plugins de provider -- [Internes des plugins](/fr/plugins/architecture) — analyse détaillée de l'architecture -- [Manifeste de plugin](/fr/plugins/manifest) — référence du schéma de manifeste +- [Bien démarrer](/fr/plugins/building-plugins) — créez votre premier Plugin +- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence complète des imports par sous-chemin +- [Plugins de canal](/fr/plugins/sdk-channel-plugins) — créer des Plugins de canal +- [Plugins de provider](/fr/plugins/sdk-provider-plugins) — créer des Plugins de provider +- [Internes des Plugins](/fr/plugins/architecture) — analyse approfondie de l’architecture +- [Manifest de Plugin](/fr/plugins/manifest) — référence du schéma du manifest diff --git a/docs/fr/plugins/sdk-overview.md b/docs/fr/plugins/sdk-overview.md index ce566ac64..0be0f93bb 100644 --- a/docs/fr/plugins/sdk-overview.md +++ b/docs/fr/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - Vous devez savoir depuis quel sous-chemin du SDK importer - - Vous voulez une référence pour toutes les méthodes d'enregistrement sur OpenClawPluginApi - - Vous recherchez un export spécifique du SDK + - Vous voulez une référence pour toutes les méthodes d’enregistrement sur `OpenClawPluginApi` + - Vous recherchez une exportation SDK spécifique sidebarTitle: SDK Overview -summary: Import map, référence de l'API d'enregistrement et architecture du SDK -title: Vue d'ensemble du SDK de plugin +summary: Map d’importation, référence de l’API d’enregistrement et architecture du SDK +title: Vue d’ensemble du SDK Plugin x-i18n: - generated_at: "2026-04-11T02:46:28Z" + generated_at: "2026-04-17T06:57:33Z" model: gpt-5.4 provider: openai - source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c + source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a source_path: plugins/sdk-overview.md workflow: 15 --- -# Vue d'ensemble du SDK de plugin +# Vue d’ensemble du SDK Plugin -Le SDK de plugin est le contrat typé entre les plugins et le cœur. Cette page est la +Le SDK Plugin est le contrat typé entre les plugins et le cœur. Cette page est la référence pour **quoi importer** et **ce que vous pouvez enregistrer**. **Vous cherchez un guide pratique ?** - - Premier plugin ? Commencez par [Getting Started](/fr/plugins/building-plugins) - - Plugin de channel ? Voir [Channel Plugins](/fr/plugins/sdk-channel-plugins) - - Plugin de provider ? Voir [Provider Plugins](/fr/plugins/sdk-provider-plugins) + - Premier plugin ? Commencez par [Premiers pas](/fr/plugins/building-plugins) + - Plugin de canal ? Voir [Plugins de canal](/fr/plugins/sdk-channel-plugins) + - Plugin de fournisseur ? Voir [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) -## Convention d'import +## Convention d’importation Importez toujours depuis un sous-chemin spécifique : @@ -36,331 +36,333 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Chaque sous-chemin est un petit module autonome. Cela permet de conserver un démarrage rapide et -d'éviter les problèmes de dépendances circulaires. Pour les helpers d'entrée/build spécifiques aux channels, -préférez `openclaw/plugin-sdk/channel-core` ; gardez `openclaw/plugin-sdk/core` pour -la surface ombrelle plus large et les helpers partagés tels que +Chaque sous-chemin est un module petit et autonome. Cela permet de garder un +démarrage rapide et d’éviter les problèmes de dépendances circulaires. Pour les +helpers d’entrée/de build spécifiques aux canaux, préférez +`openclaw/plugin-sdk/channel-core` ; gardez `openclaw/plugin-sdk/core` pour +la surface parapluie plus large et les helpers partagés tels que `buildChannelConfigSchema`. -N'ajoutez pas et ne dépendez pas de surfaces de commodité nommées d'après des providers telles que +N’ajoutez pas et ne dépendez pas de surfaces de commodité nommées d’après des fournisseurs comme `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ou -de surfaces helper associées à une marque de channel. Les plugins intégrés doivent composer des sous-chemins -SDK génériques dans leurs propres barils `api.ts` ou `runtime-api.ts`, et le cœur -doit soit utiliser ces barils locaux au plugin, soit ajouter un contrat SDK générique étroit -lorsque le besoin est réellement inter-channel. +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de +surfaces helper associées à une marque de canal. Les plugins intégrés doivent +composer des sous-chemins SDK génériques dans leurs propres barrels `api.ts` ou `runtime-api.ts`, et le cœur +doit soit utiliser ces barrels locaux au plugin, soit ajouter un contrat SDK +générique étroit lorsque le besoin est réellement transversal aux canaux. -La map d'exports générée contient encore un petit ensemble de -surfaces helper de plugins intégrés telles que `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +La map d’exportation générée contient encore un petit ensemble de surfaces helper +pour les plugins intégrés, comme `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` et `plugin-sdk/matrix*`. Ces -sous-chemins n'existent que pour la maintenance et la compatibilité des plugins intégrés ; ils sont -volontairement omis du tableau courant ci-dessous et ne constituent pas le -chemin d'import recommandé pour les nouveaux plugins tiers. +sous-chemins n’existent que pour la maintenance et la compatibilité des plugins intégrés ; +ils sont volontairement omis du tableau courant ci-dessous et ne constituent pas +le chemin d’importation recommandé pour les nouveaux plugins tiers. ## Référence des sous-chemins -Les sous-chemins les plus couramment utilisés, regroupés par objectif. La liste complète générée de -plus de 200 sous-chemins se trouve dans `scripts/lib/plugin-sdk-entrypoints.json`. +Les sous-chemins les plus couramment utilisés, regroupés par usage. La liste +complète générée de plus de 200 sous-chemins se trouve dans +`scripts/lib/plugin-sdk-entrypoints.json`. -Les sous-chemins helper réservés aux plugins intégrés apparaissent toujours dans cette liste générée. -Traitez-les comme des surfaces de détail d'implémentation/de compatibilité, sauf si une page de documentation +Les sous-chemins helper réservés aux plugins intégrés figurent toujours dans cette +liste générée. Traitez-les comme des surfaces de détail d’implémentation/de compatibilité, sauf si une page de documentation en promeut explicitement une comme publique. ### Entrée de plugin -| Sous-chemin | Exports clés | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Sous-chemin | Exportations clés | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - - | Sous-chemin | Exports clés | + + | Sous-chemin | Exportations clés | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Export du schéma Zod racine de `openclaw.json` (`OpenClawSchema`) | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Helpers partagés d'assistant de configuration, invites de liste d'autorisation, constructeurs d'état de configuration | + | `plugin-sdk/config-schema` | Exportation du schéma Zod racine `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ainsi que `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | Helpers partagés d’assistant de configuration, invites d’allowlist, constructeurs d’état de configuration | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers de configuration/action-gate multi-comptes, helpers de fallback de compte par défaut | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalisation d'identifiant de compte | - | `plugin-sdk/account-resolution` | Recherche de compte + helpers de fallback par défaut | + | `plugin-sdk/account-core` | Helpers de config/mécanisme de contrôle d’action multi-compte, helpers de repli pour compte par défaut | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalisation d’identifiant de compte | + | `plugin-sdk/account-resolution` | Helpers de recherche de compte + repli par défaut | | `plugin-sdk/account-helpers` | Helpers étroits de liste de comptes/action sur compte | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Types de schéma de configuration de channel | - | `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation de commandes personnalisées Telegram avec fallback de contrat intégré | + | `plugin-sdk/channel-config-schema` | Types de schéma de config de canal | + | `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation de commandes personnalisées Telegram avec repli sur contrat intégré | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers partagés de route entrante + construction d'enveloppe | - | `plugin-sdk/inbound-reply-dispatch` | Helpers partagés d'enregistrement et de répartition entrante | - | `plugin-sdk/messaging-targets` | Helpers d'analyse/correspondance des cibles | - | `plugin-sdk/outbound-media` | Helpers partagés de chargement des médias sortants | - | `plugin-sdk/outbound-runtime` | Helpers de délégué d'identité/envoi sortants | - | `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie et d'adaptateur pour les liaisons de fil | - | `plugin-sdk/agent-media-payload` | Constructeur historique de charge utile média d'agent | - | `plugin-sdk/conversation-runtime` | Helpers de conversation/liaison de fil, appairage et liaison configurée | - | `plugin-sdk/runtime-config-snapshot` | Helper d'instantané de configuration d'exécution | - | `plugin-sdk/runtime-group-policy` | Helpers de résolution de politique de groupe à l'exécution | - | `plugin-sdk/channel-status` | Helpers partagés d'instantané/résumé d'état de channel | - | `plugin-sdk/channel-config-primitives` | Primitives étroites de schéma de configuration de channel | - | `plugin-sdk/channel-config-writes` | Helpers d'autorisation d'écriture de configuration de channel | - | `plugin-sdk/channel-plugin-common` | Exports de prélude partagés pour plugin de channel | - | `plugin-sdk/allowlist-config-edit` | Helpers de lecture/modification de configuration de liste d'autorisation | - | `plugin-sdk/group-access` | Helpers partagés de décision d'accès de groupe | - | `plugin-sdk/direct-dm` | Helpers partagés d'authentification/garde de DM direct | - | `plugin-sdk/interactive-runtime` | Helpers de normalisation/réduction de charges utiles de réponse interactive | - | `plugin-sdk/channel-inbound` | Helpers d'anti-rebond entrant, de correspondance de mentions, d'aide de politique de mention et d'enveloppe | + | `plugin-sdk/inbound-envelope` | Helpers partagés de route entrante + construction d’enveloppe | + | `plugin-sdk/inbound-reply-dispatch` | Helpers partagés d’enregistrement et de répartition entrante | + | `plugin-sdk/messaging-targets` | Helpers d’analyse/de correspondance de cibles | + | `plugin-sdk/outbound-media` | Helpers partagés de chargement de médias sortants | + | `plugin-sdk/outbound-runtime` | Helpers de délégation d’envoi/d’identité sortante | + | `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie et d’adaptateur pour liaisons de fils | + | `plugin-sdk/agent-media-payload` | Constructeur historique de charge utile média d’agent | + | `plugin-sdk/conversation-runtime` | Helpers de liaison conversation/fil, appairage et liaison configurée | + | `plugin-sdk/runtime-config-snapshot` | Helper d’instantané de config d’exécution | + | `plugin-sdk/runtime-group-policy` | Helpers de résolution de politique de groupe à l’exécution | + | `plugin-sdk/channel-status` | Helpers partagés d’instantané/résumé de statut de canal | + | `plugin-sdk/channel-config-primitives` | Primitives étroites de schéma de config de canal | + | `plugin-sdk/channel-config-writes` | Helpers d’autorisation d’écriture de config de canal | + | `plugin-sdk/channel-plugin-common` | Exportations de prélude partagées pour plugin de canal | + | `plugin-sdk/allowlist-config-edit` | Helpers de lecture/modification de config d’allowlist | + | `plugin-sdk/group-access` | Helpers partagés de décision d’accès de groupe | + | `plugin-sdk/direct-dm` | Helpers partagés d’authentification/de garde pour messages directs | + | `plugin-sdk/interactive-runtime` | Helpers de normalisation/réduction de charge utile de réponse interactive | + | `plugin-sdk/channel-inbound` | Helpers d’anti-rebond entrant, de correspondance de mention, de politique de mention et d’enveloppe | | `plugin-sdk/channel-send-result` | Types de résultat de réponse | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Helpers d'analyse/correspondance des cibles | - | `plugin-sdk/channel-contract` | Types de contrat de channel | - | `plugin-sdk/channel-feedback` | Câblage des retours/réactions | - | `plugin-sdk/channel-secret-runtime` | Helpers étroits de contrat de secret tels que `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, et types de cible de secret | + | `plugin-sdk/channel-targets` | Helpers d’analyse/de correspondance de cibles | + | `plugin-sdk/channel-contract` | Types de contrat de canal | + | `plugin-sdk/channel-feedback` | Câblage de feedback/réaction | + | `plugin-sdk/channel-secret-runtime` | Helpers étroits de contrat de secret comme `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, ainsi que les types de cible de secret | - - | Sous-chemin | Exports clés | + + | Sous-chemin | Exportations clés | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helpers sélectionnés de configuration de provider local/autohébergé | - | `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de provider autohébergé compatible OpenAI | + | `plugin-sdk/provider-setup` | Helpers de configuration organisés pour fournisseurs locaux/autohébergés | + | `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de fournisseur autohébergé compatible OpenAI | | `plugin-sdk/cli-backend` | Valeurs par défaut du backend CLI + constantes watchdog | - | `plugin-sdk/provider-auth-runtime` | Helpers d'exécution de résolution de clé API pour les plugins de provider | - | `plugin-sdk/provider-auth-api-key` | Helpers d'onboarding/écriture de profil de clé API tels que `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Constructeur standard de résultat d'authentification OAuth | - | `plugin-sdk/provider-auth-login` | Helpers interactifs partagés de connexion pour les plugins de provider | - | `plugin-sdk/provider-env-vars` | Helpers de recherche de variables d'environnement d'authentification provider | + | `plugin-sdk/provider-auth-runtime` | Helpers d’exécution de résolution de clé API pour plugins de fournisseur | + | `plugin-sdk/provider-auth-api-key` | Helpers d’intégration/écriture de profil de clé API comme `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Constructeur standard de résultat d’authentification OAuth | + | `plugin-sdk/provider-auth-login` | Helpers partagés de connexion interactive pour plugins de fournisseur | + | `plugin-sdk/provider-env-vars` | Helpers de recherche de variables d’environnement d’authentification de fournisseur | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de replay, helpers de point de terminaison provider et helpers de normalisation d'identifiant de modèle tels que `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de relecture, helpers de point de terminaison de fournisseur, et helpers de normalisation d’identifiant de modèle tels que `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helpers génériques de capacités HTTP/point de terminaison provider | - | `plugin-sdk/provider-web-fetch-contract` | Helpers étroits de contrat de configuration/sélection web-fetch tels que `enablePluginInConfig` et `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helpers d'enregistrement/cache de provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpers étroits de configuration/identifiants web-search pour les providers qui n'ont pas besoin de câblage d'activation de plugin | - | `plugin-sdk/provider-web-search-contract` | Helpers étroits de contrat de configuration/identifiants web-search tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et setters/getters d'identifiants limités par portée | - | `plugin-sdk/provider-web-search` | Helpers d'enregistrement/cache/exécution de provider web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage + diagnostics de schéma Gemini, et helpers de compatibilité xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Helpers génériques de capacité HTTP/point de terminaison de fournisseur | + | `plugin-sdk/provider-web-fetch-contract` | Helpers étroits de contrat de config/sélection web-fetch comme `enablePluginInConfig` et `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Helpers d’enregistrement/cache de fournisseur web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helpers étroits de config/identifiants web-search pour les fournisseurs qui n’ont pas besoin du câblage d’activation du plugin | + | `plugin-sdk/provider-web-search-contract` | Helpers étroits de contrat de config/identifiants web-search comme `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et les setters/getters d’identifiants à portée limitée | + | `plugin-sdk/provider-web-search` | Helpers d’exécution/cache/enregistrement de fournisseur web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI comme `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` et similaires | | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types de wrapper de flux, et helpers partagés de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helpers de patch de configuration d'onboarding | + | `plugin-sdk/provider-onboard` | Helpers de correctif de config d’intégration | | `plugin-sdk/global-singleton` | Helpers de singleton/map/cache locaux au processus | - - | Sous-chemin | Exports clés | + + | Sous-chemin | Exportations clés | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registre de commandes, helpers d'autorisation d'expéditeur | - | `plugin-sdk/command-status` | Constructeurs de messages de commande/d'aide tels que `buildCommandsMessagePaginated` et `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Helpers de résolution d'approbateur et d'authentification d'action dans le même chat | - | `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d'approbation native d'exécution | - | `plugin-sdk/approval-delivery-runtime` | Adaptateurs de capacité/livraison d'approbation native | - | `plugin-sdk/approval-gateway-runtime` | Helper partagé de résolution de gateway d'approbation | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d'adaptateur d'approbation native pour les points d'entrée de channel à chaud | - | `plugin-sdk/approval-handler-runtime` | Helpers d'exécution plus larges du gestionnaire d'approbation ; préférez les surfaces adaptateur/gateway plus étroites lorsqu'elles suffisent | - | `plugin-sdk/approval-native-runtime` | Helpers de cible d'approbation native + liaison de compte | - | `plugin-sdk/approval-reply-runtime` | Helpers de charge utile de réponse d'approbation d'exécution/plugin | - | `plugin-sdk/command-auth-native` | Helpers d'authentification de commande native + helpers de cible de session native | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registre de commandes, helpers d’autorisation d’expéditeur | + | `plugin-sdk/command-status` | Constructeurs de messages de commande/d’aide tels que `buildCommandsMessagePaginated` et `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helpers de résolution d’approbateur et d’authentification d’action dans la même discussion | + | `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d’approbation d’exécution native | + | `plugin-sdk/approval-delivery-runtime` | Adaptateurs natifs de capacité/livraison d’approbation | + | `plugin-sdk/approval-gateway-runtime` | Helper partagé de résolution de Gateway d’approbation | + | `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d’adaptateur d’approbation native pour les points d’entrée de canal critiques | + | `plugin-sdk/approval-handler-runtime` | Helpers plus larges du runtime de gestionnaire d’approbation ; préférez les surfaces adaptateur/Gateway plus étroites lorsqu’elles suffisent | + | `plugin-sdk/approval-native-runtime` | Helpers natifs de cible d’approbation + liaison de compte | + | `plugin-sdk/approval-reply-runtime` | Helpers de charge utile de réponse d’approbation exec/plugin | + | `plugin-sdk/command-auth-native` | Helpers natifs d’authentification de commande + helpers natifs de cible de session | | `plugin-sdk/command-detection` | Helpers partagés de détection de commande | - | `plugin-sdk/command-surface` | Normalisation du corps de commande et helpers de surface de commande | + | `plugin-sdk/command-surface` | Helpers de normalisation de corps de commande et de surface de commande | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helpers étroits de collecte de contrat de secret pour les surfaces de secret de channel/plugin | - | `plugin-sdk/secret-ref-runtime` | Helpers étroits `coerceSecretRef` et de typage SecretRef pour l'analyse de contrat de secret/configuration | - | `plugin-sdk/security-runtime` | Helpers partagés de confiance, filtrage DM, contenu externe et collecte de secrets | - | `plugin-sdk/ssrf-policy` | Helpers de liste d'autorisation d'hôte et de politique SSRF réseau privé | - | `plugin-sdk/ssrf-runtime` | Helpers de dispatcher épinglé, fetch protégé par SSRF et politique SSRF | - | `plugin-sdk/secret-input` | Helpers d'analyse d'entrée secrète | - | `plugin-sdk/webhook-ingress` | Helpers de requête/cible webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de taille de corps de requête/délai d'expiration | + | `plugin-sdk/channel-secret-runtime` | Helpers étroits de collecte de contrat de secret pour les surfaces de secret de canal/plugin | + | `plugin-sdk/secret-ref-runtime` | Helpers étroits `coerceSecretRef` et de typage SecretRef pour l’analyse de contrat de secret/config | + | `plugin-sdk/security-runtime` | Helpers partagés de confiance, contrôle DM, contenu externe et collecte de secrets | + | `plugin-sdk/ssrf-policy` | Helpers de politique SSRF d’allowlist d’hôtes et de réseau privé | + | `plugin-sdk/ssrf-runtime` | Helpers de répartiteur épinglé, fetch protégé par SSRF et politique SSRF | + | `plugin-sdk/secret-input` | Helpers d’analyse d’entrée de secret | + | `plugin-sdk/webhook-ingress` | Helpers de requête/cible Webhook | + | `plugin-sdk/webhook-request-guards` | Helpers de taille du corps de requête/délai d’attente | - - | Sous-chemin | Exports clés | + + | Sous-chemin | Exportations clés | | --- | --- | - | `plugin-sdk/runtime` | Helpers larges d'exécution/journalisation/sauvegarde/installation de plugin | - | `plugin-sdk/runtime-env` | Helpers étroits d'environnement d'exécution, logger, délai d'expiration, retry et backoff | - | `plugin-sdk/channel-runtime-context` | Helpers génériques d'enregistrement et de recherche de contexte d'exécution de channel | + | `plugin-sdk/runtime` | Helpers larges de runtime/journalisation/sauvegarde/installation de plugin | + | `plugin-sdk/runtime-env` | Helpers étroits d’environnement de runtime, logger, délai d’attente, retry et backoff | + | `plugin-sdk/channel-runtime-context` | Helpers génériques d’enregistrement et de recherche du contexte d’exécution de canal | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | Helpers partagés de commande/hook/http/interaction de plugin | - | `plugin-sdk/hook-runtime` | Helpers partagés de pipeline de webhook/hook interne | - | `plugin-sdk/lazy-runtime` | Helpers d'import/binding d'exécution paresseux tels que `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpers d'exécution de processus | - | `plugin-sdk/cli-runtime` | Helpers CLI de formatage, d'attente et de version | - | `plugin-sdk/gateway-runtime` | Helpers de client gateway et de patch d'état de channel | - | `plugin-sdk/config-runtime` | Helpers de chargement/écriture de configuration | - | `plugin-sdk/telegram-command-config` | Normalisation du nom/de la description des commandes Telegram et vérifications de doublons/conflits, même lorsque la surface de contrat Telegram intégrée n'est pas disponible | - | `plugin-sdk/approval-runtime` | Helpers d'approbation d'exécution/plugin, constructeurs de capacité d'approbation, helpers d'authentification/profil, helpers de routage/exécution natifs | - | `plugin-sdk/reply-runtime` | Helpers partagés d'exécution entrante/réponse, fragmentation, répartition, heartbeat, planificateur de réponse | + | `plugin-sdk/hook-runtime` | Helpers partagés de pipeline de Webhook/hook interne | + | `plugin-sdk/lazy-runtime` | Helpers d’importation/de liaison de runtime paresseux tels que `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helpers d’exécution de processus | + | `plugin-sdk/cli-runtime` | Helpers de formatage, d’attente et de version pour CLI | + | `plugin-sdk/gateway-runtime` | Helpers de client Gateway et de correctif de statut de canal | + | `plugin-sdk/config-runtime` | Helpers de chargement/écriture de config | + | `plugin-sdk/telegram-command-config` | Normalisation du nom/de la description de commande Telegram et vérifications de doublon/conflit, même lorsque la surface de contrat Telegram intégrée n’est pas disponible | + | `plugin-sdk/approval-runtime` | Helpers d’approbation exec/plugin, constructeurs de capacité d’approbation, helpers d’authentification/profil, helpers natifs de routage/runtime | + | `plugin-sdk/reply-runtime` | Helpers partagés du runtime entrant/de réponse, segmentation, répartition, Heartbeat, planificateur de réponse | | `plugin-sdk/reply-dispatch-runtime` | Helpers étroits de répartition/finalisation de réponse | - | `plugin-sdk/reply-history` | Helpers partagés d'historique de réponse sur fenêtre courte tels que `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-history` | Helpers partagés d’historique de réponse sur fenêtre courte tels que `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers étroits de fragmentation texte/Markdown | - | `plugin-sdk/session-store-runtime` | Helpers de chemin de magasin de session + date de mise à jour | - | `plugin-sdk/state-paths` | Helpers de chemin de répertoire d'état/OAuth | - | `plugin-sdk/routing` | Helpers de route/clé de session/liaison de compte tels que `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helpers partagés de résumé d'état de channel/compte, valeurs par défaut d'état d'exécution et helpers de métadonnées de problème | + | `plugin-sdk/reply-chunking` | Helpers étroits de segmentation de texte/Markdown | + | `plugin-sdk/session-store-runtime` | Helpers de chemin du magasin de session + date de mise à jour | + | `plugin-sdk/state-paths` | Helpers de chemin de répertoire pour état/OAuth | + | `plugin-sdk/routing` | Helpers de routage/clé de session/liaison de compte tels que `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helpers partagés de résumé de statut de canal/compte, valeurs par défaut de l’état d’exécution et helpers de métadonnées de problème | | `plugin-sdk/target-resolver-runtime` | Helpers partagés de résolution de cible | | `plugin-sdk/string-normalization-runtime` | Helpers de normalisation de slug/chaîne | - | `plugin-sdk/request-url` | Extraire des URL chaîne depuis des entrées de type fetch/request | + | `plugin-sdk/request-url` | Extraire des URL de chaîne à partir d’entrées de type fetch/request | | `plugin-sdk/run-command` | Exécuteur de commande temporisé avec résultats stdout/stderr normalisés | - | `plugin-sdk/param-readers` | Lecteurs de paramètres communs d'outil/CLI | - | `plugin-sdk/tool-payload` | Extraire des charges utiles normalisées depuis des objets de résultat d'outil | - | `plugin-sdk/tool-send` | Extraire des champs cibles d'envoi canoniques depuis des arguments d'outil | + | `plugin-sdk/param-readers` | Lecteurs courants de paramètres d’outil/CLI | + | `plugin-sdk/tool-payload` | Extraire des charges utiles normalisées à partir d’objets résultat d’outil | + | `plugin-sdk/tool-send` | Extraire les champs de cible d’envoi canoniques à partir des arguments d’outil | | `plugin-sdk/temp-path` | Helpers partagés de chemin de téléchargement temporaire | - | `plugin-sdk/logging-core` | Logger de sous-système et helpers de masquage | - | `plugin-sdk/markdown-table-runtime` | Helpers de mode tableau Markdown | - | `plugin-sdk/json-store` | Petits helpers de lecture/écriture d'état JSON | + | `plugin-sdk/logging-core` | Helpers de logger de sous-système et de masquage | + | `plugin-sdk/markdown-table-runtime` | Helpers de mode de tableau Markdown | + | `plugin-sdk/json-store` | Petits helpers de lecture/écriture d’état JSON | | `plugin-sdk/file-lock` | Helpers de verrouillage de fichier réentrant | - | `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication adossé au disque | - | `plugin-sdk/acp-runtime` | Helpers ACP d'exécution/session et de répartition de réponse | - | `plugin-sdk/agent-config-primitives` | Primitives étroites de schéma de configuration d'exécution d'agent | - | `plugin-sdk/boolean-param` | Lecteur permissif de paramètre booléen | + | `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication sauvegardé sur disque | + | `plugin-sdk/acp-runtime` | Helpers ACP de runtime/session et de répartition de réponse | + | `plugin-sdk/agent-config-primitives` | Primitives étroites de schéma de config du runtime d’agent | + | `plugin-sdk/boolean-param` | Lecteur souple de paramètre booléen | | `plugin-sdk/dangerous-name-runtime` | Helpers de résolution de correspondance de nom dangereux | - | `plugin-sdk/device-bootstrap` | Helpers d'initialisation d'appareil et de jeton d'appairage | - | `plugin-sdk/extension-shared` | Primitives helper partagées de channel passif, d'état et de proxy ambiant | - | `plugin-sdk/models-provider-runtime` | Helpers de réponse de commande `/models`/provider | - | `plugin-sdk/skill-commands-runtime` | Helpers de listage des commandes de Skills | - | `plugin-sdk/native-command-registry` | Helpers de registre/build/sérialisation de commandes natives | - | `plugin-sdk/agent-harness` | Surface expérimentale de plugin de confiance pour les harnais d'agent bas niveau : types de harnais, helpers de pilotage/abandon d'exécution active, helpers de pont d'outils OpenClaw et utilitaires de résultat de tentative | - | `plugin-sdk/provider-zai-endpoint` | Helpers de détection de point de terminaison Z.AI | - | `plugin-sdk/infra-runtime` | Helpers d'événement système/heartbeat | + | `plugin-sdk/device-bootstrap` | Helpers d’initialisation d’appareil et de jeton d’appairage | + | `plugin-sdk/extension-shared` | Primitives helper partagées pour canal passif, statut et proxy ambiant | + | `plugin-sdk/models-provider-runtime` | Helpers de réponse de fournisseur/commande `/models` | + | `plugin-sdk/skill-commands-runtime` | Helpers de liste de commandes Skills | + | `plugin-sdk/native-command-registry` | Helpers natifs de registre/construction/sérialisation de commande | + | `plugin-sdk/agent-harness` | Surface expérimentale de plugin approuvé pour des harnais d’agent bas niveau : types de harnais, helpers de pilotage/abandon d’exécution active, helpers de pont d’outil OpenClaw et utilitaires de résultat de tentative | + | `plugin-sdk/provider-zai-endpoint` | Helpers de détection de point de terminaison Z.A.I | + | `plugin-sdk/infra-runtime` | Helpers d’événement système/Heartbeat | | `plugin-sdk/collection-runtime` | Petits helpers de cache borné | - | `plugin-sdk/diagnostic-runtime` | Helpers d'indicateur et d'événement de diagnostic | - | `plugin-sdk/error-runtime` | Graphe d'erreurs, formatage, helpers partagés de classification d'erreurs, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helpers de fetch encapsulé, proxy et recherche épinglée | - | `plugin-sdk/host-runtime` | Helpers de normalisation de nom d'hôte et d'hôte SCP | - | `plugin-sdk/retry-runtime` | Helpers de configuration et d'exécuteur de retry | - | `plugin-sdk/agent-runtime` | Helpers de répertoire/identité/espace de travail d'agent | - | `plugin-sdk/directory-runtime` | Requête/déduplication de répertoire adossée à la configuration | + | `plugin-sdk/diagnostic-runtime` | Helpers de drapeau et d’événement de diagnostic | + | `plugin-sdk/error-runtime` | Helpers de graphe d’erreur, formatage, classification d’erreur partagée, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Helpers de fetch enveloppé, proxy et recherche épinglée | + | `plugin-sdk/host-runtime` | Helpers de normalisation de nom d’hôte et d’hôte SCP | + | `plugin-sdk/retry-runtime` | Helpers de config de retry et d’exécuteur de retry | + | `plugin-sdk/agent-runtime` | Helpers de répertoire/identité/espace de travail d’agent | + | `plugin-sdk/directory-runtime` | Requête/déduplication de répertoire basée sur la config | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Sous-chemin | Exports clés | + + | Sous-chemin | Exportations clés | | --- | --- | - | `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias plus constructeurs de charges utiles média | - | `plugin-sdk/media-generation-runtime` | Helpers partagés de fallback de génération de médias, sélection de candidats et messagerie de modèle manquant | - | `plugin-sdk/media-understanding` | Types de provider de compréhension des médias plus exports helper orientés provider pour image/audio | - | `plugin-sdk/text-runtime` | Helpers partagés de texte/Markdown/journalisation tels que suppression du texte visible par l'assistant, helpers de rendu/fragmentation/tableau Markdown, helpers de masquage, helpers de balises de directive et utilitaires de texte sûr | - | `plugin-sdk/text-chunking` | Helper de fragmentation de texte sortant | - | `plugin-sdk/speech` | Types de provider de parole plus helpers orientés provider de directive, registre et validation | - | `plugin-sdk/speech-core` | Helpers partagés de types de provider de parole, registre, directive et normalisation | - | `plugin-sdk/realtime-transcription` | Types de provider de transcription en temps réel et helpers de registre | - | `plugin-sdk/realtime-voice` | Types de provider de voix en temps réel et helpers de registre | - | `plugin-sdk/image-generation` | Types de provider de génération d'image | - | `plugin-sdk/image-generation-core` | Helpers partagés de types de génération d'image, fallback, authentification et registre | - | `plugin-sdk/music-generation` | Types de provider/requête/résultat de génération musicale | - | `plugin-sdk/music-generation-core` | Types partagés de génération musicale, helpers de fallback, recherche de provider et analyse de référence de modèle | - | `plugin-sdk/video-generation` | Types de provider/requête/résultat de génération vidéo | - | `plugin-sdk/video-generation-core` | Types partagés de génération vidéo, helpers de fallback, recherche de provider et analyse de référence de modèle | - | `plugin-sdk/webhook-targets` | Registre de cibles webhook et helpers d'installation de route | - | `plugin-sdk/webhook-path` | Helpers de normalisation de chemin webhook | + | `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias ainsi que constructeurs de charge utile média | + | `plugin-sdk/media-generation-runtime` | Helpers partagés de basculement en cas d’échec pour la génération de médias, sélection de candidats et messagerie de modèle manquant | + | `plugin-sdk/media-understanding` | Types de fournisseur de compréhension des médias ainsi qu’exportations helper orientées fournisseur pour image/audio | + | `plugin-sdk/text-runtime` | Helpers partagés de texte/Markdown/journalisation tels que suppression du texte visible par l’assistant, helpers de rendu/segmentation/tableau Markdown, helpers de masquage, helpers de balise de directive et utilitaires de texte sûr | + | `plugin-sdk/text-chunking` | Helper de segmentation de texte sortant | + | `plugin-sdk/speech` | Types de fournisseur Speech ainsi qu’helpers orientés fournisseur pour directives, registre et validation | + | `plugin-sdk/speech-core` | Helpers partagés de types, registre, directive et normalisation pour fournisseur Speech | + | `plugin-sdk/realtime-transcription` | Types de fournisseur de transcription en temps réel et helpers de registre | + | `plugin-sdk/realtime-voice` | Types de fournisseur de voix en temps réel et helpers de registre | + | `plugin-sdk/image-generation` | Types de fournisseur de génération d’image | + | `plugin-sdk/image-generation-core` | Helpers partagés de types, basculement en cas d’échec, authentification et registre pour la génération d’image | + | `plugin-sdk/music-generation` | Types de fournisseur/de requête/de résultat pour la génération musicale | + | `plugin-sdk/music-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de référence de modèle pour la génération musicale | + | `plugin-sdk/video-generation` | Types de fournisseur/de requête/de résultat pour la génération vidéo | + | `plugin-sdk/video-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de référence de modèle pour la génération vidéo | + | `plugin-sdk/webhook-targets` | Helpers de registre de cible Webhook et d’installation de route | + | `plugin-sdk/webhook-path` | Helpers de normalisation de chemin Webhook | | `plugin-sdk/web-media` | Helpers partagés de chargement de médias distants/locaux | - | `plugin-sdk/zod` | `zod` réexporté pour les consommateurs du SDK de plugin | + | `plugin-sdk/zod` | `zod` réexporté pour les consommateurs du SDK Plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Sous-chemin | Exports clés | + + | Sous-chemin | Exportations clés | | --- | --- | - | `plugin-sdk/memory-core` | Surface helper memory-core intégrée pour les helpers de gestionnaire/configuration/fichier/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Façade d'exécution d'indexation/recherche de mémoire | - | `plugin-sdk/memory-core-host-engine-foundation` | Exports du moteur de fondation de l'hôte mémoire | - | `plugin-sdk/memory-core-host-engine-embeddings` | Exports du moteur d'embeddings de l'hôte mémoire | - | `plugin-sdk/memory-core-host-engine-qmd` | Exports du moteur QMD de l'hôte mémoire | - | `plugin-sdk/memory-core-host-engine-storage` | Exports du moteur de stockage de l'hôte mémoire | - | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux de l'hôte mémoire | - | `plugin-sdk/memory-core-host-query` | Helpers de requête de l'hôte mémoire | - | `plugin-sdk/memory-core-host-secret` | Helpers de secret de l'hôte mémoire | - | `plugin-sdk/memory-core-host-events` | Helpers de journal d'événements de l'hôte mémoire | - | `plugin-sdk/memory-core-host-status` | Helpers d'état de l'hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-cli` | Helpers d'exécution CLI de l'hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-core` | Helpers d'exécution cœur de l'hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/exécution de l'hôte mémoire | - | `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers d'exécution cœur de l'hôte mémoire | - | `plugin-sdk/memory-host-events` | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d'événements de l'hôte mémoire | - | `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/exécution de l'hôte mémoire | - | `plugin-sdk/memory-host-markdown` | Helpers partagés de Markdown géré pour les plugins proches de la mémoire | - | `plugin-sdk/memory-host-search` | Façade d'exécution de mémoire active pour l'accès au gestionnaire de recherche | - | `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les helpers d'état de l'hôte mémoire | - | `plugin-sdk/memory-lancedb` | Surface helper memory-lancedb intégrée | + | `plugin-sdk/memory-core` | Surface helper `memory-core` intégrée pour les helpers de gestionnaire/config/fichier/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Façade de runtime pour l’indexation/la recherche mémoire | + | `plugin-sdk/memory-core-host-engine-foundation` | Exportations du moteur de fondation hôte mémoire | + | `plugin-sdk/memory-core-host-engine-embeddings` | Contrats d’embedding hôte mémoire, accès au registre, fournisseur local et helpers génériques de lot/distant | + | `plugin-sdk/memory-core-host-engine-qmd` | Exportations du moteur QMD hôte mémoire | + | `plugin-sdk/memory-core-host-engine-storage` | Exportations du moteur de stockage hôte mémoire | + | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux hôte mémoire | + | `plugin-sdk/memory-core-host-query` | Helpers de requête hôte mémoire | + | `plugin-sdk/memory-core-host-secret` | Helpers de secret hôte mémoire | + | `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements hôte mémoire | + | `plugin-sdk/memory-core-host-status` | Helpers de statut hôte mémoire | + | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime CLI hôte mémoire | + | `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime central hôte mémoire | + | `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/runtime hôte mémoire | + | `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers de runtime central hôte mémoire | + | `plugin-sdk/memory-host-events` | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements hôte mémoire | + | `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/runtime hôte mémoire | + | `plugin-sdk/memory-host-markdown` | Helpers partagés de Markdown géré pour les plugins adjacents à la mémoire | + | `plugin-sdk/memory-host-search` | Façade de runtime Active Memory pour l’accès au gestionnaire de recherche | + | `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les helpers de statut hôte mémoire | + | `plugin-sdk/memory-lancedb` | Surface helper `memory-lancedb` intégrée | | Famille | Sous-chemins actuels | Utilisation prévue | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de prise en charge du plugin browser intégré (`browser-support` reste le baril de compatibilité) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/d'exécution Matrix intégrée | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/d'exécution LINE intégrée | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de support pour le plugin Browser intégré (`browser-support` reste le barrel de compatibilité) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/runtime Matrix intégrée | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/runtime LINE intégrée | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface helper IRC intégrée | - | Helpers spécifiques au channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Surfaces de compatibilité/helper de channel intégrées | - | Helpers spécifiques à auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Surfaces helper de fonctionnalité/plugin intégrées ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` | + | Helpers spécifiques à un canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Surfaces de compatibilité/helper de canaux intégrés | + | Helpers spécifiques à l’authentification/au plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Surfaces helper de fonctionnalités/plugins intégrés ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` | -## API d'enregistrement +## API d’enregistrement Le callback `register(api)` reçoit un objet `OpenClawPluginApi` avec ces méthodes : ### Enregistrement de capacités -| Méthode | Ce qu'elle enregistre | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Inférence de texte (LLM) | -| `api.registerAgentHarness(...)` | Exécuteur d'agent bas niveau expérimental | -| `api.registerCliBackend(...)` | Backend CLI d'inférence locale | -| `api.registerChannel(...)` | Channel de messagerie | -| `api.registerSpeechProvider(...)` | Synthèse texte-vers-parole / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Transcription temps réel en streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sessions vocales temps réel duplex | -| `api.registerMediaUnderstandingProvider(...)` | Analyse d'image/audio/vidéo | -| `api.registerImageGenerationProvider(...)` | Génération d'image | -| `api.registerMusicGenerationProvider(...)` | Génération musicale | -| `api.registerVideoGenerationProvider(...)` | Génération vidéo | -| `api.registerWebFetchProvider(...)` | Fournisseur de récupération / scraping web | -| `api.registerWebSearchProvider(...)` | Recherche web | +| Méthode | Ce qu’elle enregistre | +| ----------------------------------------------- | -------------------------------------- | +| `api.registerProvider(...)` | Inférence de texte (LLM) | +| `api.registerAgentHarness(...)` | Exécuteur d’agent bas niveau expérimental | +| `api.registerCliBackend(...)` | Backend local d’inférence CLI | +| `api.registerChannel(...)` | Canal de messagerie | +| `api.registerSpeechProvider(...)` | Synthèse texte-parole / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Transcription en temps réel en streaming | +| `api.registerRealtimeVoiceProvider(...)` | Sessions vocales duplex en temps réel | +| `api.registerMediaUnderstandingProvider(...)` | Analyse d’image/audio/vidéo | +| `api.registerImageGenerationProvider(...)` | Génération d’image | +| `api.registerMusicGenerationProvider(...)` | Génération musicale | +| `api.registerVideoGenerationProvider(...)` | Génération vidéo | +| `api.registerWebFetchProvider(...)` | Fournisseur de récupération / scraping web | +| `api.registerWebSearchProvider(...)` | Recherche web | ### Outils et commandes -| Méthode | Ce qu'elle enregistre | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Outil d'agent (obligatoire ou `{ optional: true }`) | -| `api.registerCommand(def)` | Commande personnalisée (contourne le LLM) | +| Méthode | Ce qu’elle enregistre | +| ----------------------------- | ------------------------------------------- | +| `api.registerTool(tool, opts?)` | Outil d’agent (obligatoire ou `{ optional: true }`) | +| `api.registerCommand(def)` | Commande personnalisée (contourne le LLM) | ### Infrastructure -| Méthode | Ce qu'elle enregistre | -| ---------------------------------------------- | ------------------------------------ | -| `api.registerHook(events, handler, opts?)` | Hook d'événement | -| `api.registerHttpRoute(params)` | Point de terminaison HTTP de Gateway | -| `api.registerGatewayMethod(name, handler)` | Méthode RPC de Gateway | -| `api.registerCli(registrar, opts?)` | Sous-commande CLI | -| `api.registerService(service)` | Service d'arrière-plan | +| Méthode | Ce qu’elle enregistre | +| --------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook d’événement | +| `api.registerHttpRoute(params)` | Point de terminaison HTTP Gateway | +| `api.registerGatewayMethod(name, handler)` | Méthode RPC Gateway | +| `api.registerCli(registrar, opts?)` | Sous-commande CLI | +| `api.registerService(service)` | Service en arrière-plan | | `api.registerInteractiveHandler(registration)` | Gestionnaire interactif | -| `api.registerMemoryPromptSupplement(builder)` | Section additive d'invite proche de la mémoire | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additif de recherche/lecture mémoire | +| `api.registerMemoryPromptSupplement(builder)` | Section additive de prompt adjacente à la mémoire | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additif de recherche/lecture mémoire | -Les espaces de noms d'administration du cœur réservés (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) restent toujours `operator.admin`, même si un plugin essaie d'assigner une -portée de méthode gateway plus étroite. Préférez des préfixes spécifiques au plugin pour +Les espaces de noms d’administration du cœur réservés (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) restent toujours `operator.admin`, même si un plugin essaie d’assigner une +portée de méthode Gateway plus étroite. Préférez des préfixes spécifiques au plugin pour les méthodes appartenant au plugin. -### Métadonnées d'enregistrement CLI +### Métadonnées d’enregistrement CLI -`api.registerCli(registrar, opts?)` accepte deux types de métadonnées de niveau supérieur : +`api.registerCli(registrar, opts?)` accepte deux types de métadonnées de premier niveau : -- `commands` : racines de commandes explicites appartenant au registrar -- `descriptors` : descripteurs de commande à l'analyse utilisés pour l'aide de la CLI racine, - le routage et l'enregistrement paresseux de la CLI du plugin +- `commands` : racines de commande explicites appartenant au registrar +- `descriptors` : descripteurs de commande au moment de l’analyse utilisés pour l’aide de la CLI racine, + le routage et l’enregistrement paresseux de la CLI du plugin -Si vous voulez qu'une commande de plugin reste chargée paresseusement dans le chemin CLI racine normal, -fournissez des `descriptors` qui couvrent chaque racine de commande de niveau supérieur exposée par ce +Si vous voulez qu’une commande de plugin reste chargée paresseusement dans le chemin CLI racine normal, +fournissez des `descriptors` qui couvrent chaque racine de commande de premier niveau exposée par ce registrar. ```typescript @@ -373,7 +375,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Gérer les comptes Matrix, la vérification, les appareils et l'état du profil", + description: "Gérer les comptes Matrix, la vérification, les appareils et l’état du profil", hasSubcommands: true, }, ], @@ -381,134 +383,135 @@ api.registerCli( ); ``` -Utilisez `commands` seul uniquement lorsque vous n'avez pas besoin d'un enregistrement CLI racine paresseux. -Ce chemin de compatibilité eager reste pris en charge, mais il n'installe pas de -placeholders soutenus par des descripteurs pour le chargement paresseux au moment de l'analyse. +Utilisez `commands` seul uniquement lorsque vous n’avez pas besoin d’un enregistrement CLI racine paresseux. +Ce chemin de compatibilité eager reste pris en charge, mais il n’installe pas +d’emplacements réservés adossés à des descripteurs pour le chargement paresseux au moment de l’analyse. -### Enregistrement de backend CLI +### Enregistrement du backend CLI -`api.registerCliBackend(...)` permet à un plugin de posséder la configuration par défaut d'un backend CLI -d'IA local tel que `codex-cli`. +`api.registerCliBackend(...)` permet à un plugin de posséder la config par défaut d’un backend CLI +d’IA local tel que `codex-cli`. -- Le `id` du backend devient le préfixe provider dans des références de modèle comme `codex-cli/gpt-5`. -- La `config` du backend utilise la même structure que `agents.defaults.cliBackends.`. -- La configuration utilisateur garde la priorité. OpenClaw fusionne `agents.defaults.cliBackends.` au-dessus de la - valeur par défaut du plugin avant d'exécuter la CLI. -- Utilisez `normalizeConfig` lorsqu'un backend a besoin de réécritures de compatibilité après fusion - (par exemple normaliser d'anciennes formes de drapeaux). +- L’`id` du backend devient le préfixe de fournisseur dans des références de modèle comme `codex-cli/gpt-5`. +- La `config` du backend utilise la même forme que `agents.defaults.cliBackends.`. +- La config utilisateur garde la priorité. OpenClaw fusionne `agents.defaults.cliBackends.` sur la + valeur par défaut du plugin avant d’exécuter la CLI. +- Utilisez `normalizeConfig` lorsqu’un backend a besoin de réécritures de compatibilité après fusion + (par exemple pour normaliser d’anciennes formes de drapeaux). ### Emplacements exclusifs -| Méthode | Ce qu'elle enregistre | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Moteur de contexte (un seul actif à la fois). Le callback `assemble()` reçoit `availableTools` et `citationsMode` afin que le moteur puisse adapter les ajouts à l'invite. | -| `api.registerMemoryCapability(capability)` | Capacité mémoire unifiée | -| `api.registerMemoryPromptSection(builder)` | Constructeur de section d'invite mémoire | +| Méthode | Ce qu’elle enregistre | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Moteur de contexte (un seul actif à la fois). Le callback `assemble()` reçoit `availableTools` et `citationsMode` afin que le moteur puisse adapter les ajouts au prompt. | +| `api.registerMemoryCapability(capability)` | Capacité mémoire unifiée | +| `api.registerMemoryPromptSection(builder)` | Constructeur de section de prompt mémoire | | `api.registerMemoryFlushPlan(resolver)` | Résolveur de plan de vidage mémoire | -| `api.registerMemoryRuntime(runtime)` | Adaptateur d'exécution mémoire | +| `api.registerMemoryRuntime(runtime)` | Adaptateur de runtime mémoire | -### Adaptateurs d'embeddings mémoire +### Adaptateurs d’embedding mémoire -| Méthode | Ce qu'elle enregistre | -| ---------------------------------------------- | --------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptateur d'embeddings mémoire pour le plugin actif | +| Méthode | Ce qu’elle enregistre | +| --------------------------------------------- | -------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptateur d’embedding mémoire pour le plugin actif | -- `registerMemoryCapability` est l'API exclusive préférée pour les plugins mémoire. +- `registerMemoryCapability` est l’API de plugin mémoire exclusive préférée. - `registerMemoryCapability` peut aussi exposer `publicArtifacts.listArtifacts(...)` - afin que les plugins compagnons puissent consommer les artefacts mémoire exportés via - `openclaw/plugin-sdk/memory-host-core` au lieu d'accéder à la disposition privée d'un + afin que des plugins compagnons puissent consommer les artefacts mémoire exportés via + `openclaw/plugin-sdk/memory-host-core` au lieu d’atteindre la disposition privée d’un plugin mémoire spécifique. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` et - `registerMemoryRuntime` sont des API exclusives de plugin mémoire compatibles avec l'historique. -- `registerMemoryEmbeddingProvider` permet au plugin mémoire actif d'enregistrer un - ou plusieurs identifiants d'adaptateur d'embeddings (par exemple `openai`, `gemini`, ou un identifiant défini par un plugin personnalisé). -- La configuration utilisateur telle que `agents.defaults.memorySearch.provider` et + `registerMemoryRuntime` sont des API exclusives de plugin mémoire compatibles avec les versions historiques. +- `registerMemoryEmbeddingProvider` permet au plugin mémoire actif d’enregistrer un + ou plusieurs identifiants d’adaptateur d’embedding (par exemple `openai`, `gemini` ou un identifiant + personnalisé défini par le plugin). +- La config utilisateur comme `agents.defaults.memorySearch.provider` et `agents.defaults.memorySearch.fallback` se résout par rapport à ces identifiants - d'adaptateur enregistrés. + d’adaptateur enregistrés. ### Événements et cycle de vie -| Méthode | Ce qu'elle fait | -| -------------------------------------------- | ------------------------------ | -| `api.on(hookName, handler, opts?)` | Hook de cycle de vie typé | +| Méthode | Ce qu’elle fait | +| ------------------------------------------- | ----------------------------- | +| `api.on(hookName, handler, opts?)` | Hook de cycle de vie typé | | `api.onConversationBindingResolved(handler)` | Callback de liaison de conversation | ### Sémantique de décision des hooks -- `before_tool_call` : renvoyer `{ block: true }` est terminal. Dès qu'un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. -- `before_tool_call` : renvoyer `{ block: false }` est traité comme aucune décision (comme si `block` était omis), pas comme une surcharge. -- `before_install` : renvoyer `{ block: true }` est terminal. Dès qu'un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. -- `before_install` : renvoyer `{ block: false }` est traité comme aucune décision (comme si `block` était omis), pas comme une surcharge. -- `reply_dispatch` : renvoyer `{ handled: true, ... }` est terminal. Dès qu'un gestionnaire revendique la répartition, les gestionnaires de priorité inférieure et le chemin de répartition de modèle par défaut sont ignorés. -- `message_sending` : renvoyer `{ cancel: true }` est terminal. Dès qu'un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. -- `message_sending` : renvoyer `{ cancel: false }` est traité comme aucune décision (comme si `cancel` était omis), pas comme une surcharge. +- `before_tool_call` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. +- `before_tool_call` : retourner `{ block: false }` est traité comme aucune décision (comme si `block` était omis), et non comme une surcharge. +- `before_install` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. +- `before_install` : retourner `{ block: false }` est traité comme aucune décision (comme si `block` était omis), et non comme une surcharge. +- `reply_dispatch` : retourner `{ handled: true, ... }` est terminal. Dès qu’un gestionnaire revendique la répartition, les gestionnaires de priorité inférieure et le chemin par défaut de répartition du modèle sont ignorés. +- `message_sending` : retourner `{ cancel: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. +- `message_sending` : retourner `{ cancel: false }` est traité comme aucune décision (comme si `cancel` était omis), et non comme une surcharge. -### Champs de l'objet API +### Champs de l’objet API -| Champ | Type | Description | -| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------ | -| `api.id` | `string` | Identifiant du plugin | -| `api.name` | `string` | Nom d'affichage | -| `api.version` | `string?` | Version du plugin (facultatif) | -| `api.description` | `string?` | Description du plugin (facultatif) | -| `api.source` | `string` | Chemin source du plugin | -| `api.rootDir` | `string?` | Répertoire racine du plugin (facultatif) | -| `api.config` | `OpenClawConfig` | Instantané de configuration actuel (instantané d'exécution actif en mémoire lorsqu'il est disponible) | -| `api.pluginConfig` | `Record` | Configuration spécifique au plugin depuis `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helpers d'exécution](/fr/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger limité par portée (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Mode de chargement actuel ; `"setup-runtime"` est la fenêtre légère de démarrage/configuration avant l'entrée complète | -| `api.resolvePath(input)` | `(string) => string` | Résoudre un chemin relatif à la racine du plugin | +| Champ | Type | Description | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Identifiant du plugin | +| `api.name` | `string` | Nom d’affichage | +| `api.version` | `string?` | Version du plugin (facultatif) | +| `api.description` | `string?` | Description du plugin (facultatif) | +| `api.source` | `string` | Chemin source du plugin | +| `api.rootDir` | `string?` | Répertoire racine du plugin (facultatif) | +| `api.config` | `OpenClawConfig` | Instantané de config actuel (instantané actif en mémoire à l’exécution lorsqu’il est disponible) | +| `api.pluginConfig` | `Record` | Config spécifique au plugin depuis `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/fr/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger à portée limitée (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Mode de chargement actuel ; `"setup-runtime"` est la fenêtre légère de démarrage/configuration avant le chargement complet | +| `api.resolvePath(input)` | `(string) => string` | Résoudre un chemin relatif à la racine du plugin | ## Convention de module interne -Dans votre plugin, utilisez des fichiers barils locaux pour les imports internes : +Dans votre plugin, utilisez des fichiers barrel locaux pour les importations internes : ``` my-plugin/ - api.ts # Exports publics pour les consommateurs externes - runtime-api.ts # Exports d'exécution internes uniquement - index.ts # Point d'entrée du plugin - setup-entry.ts # Entrée légère réservée à la configuration (facultative) + api.ts # Exportations publiques pour les consommateurs externes + runtime-api.ts # Exportations de runtime réservées à l’interne + index.ts # Point d’entrée du plugin + setup-entry.ts # Entrée légère réservée à la configuration (facultatif) ``` - N'importez jamais votre propre plugin via `openclaw/plugin-sdk/` - depuis le code de production. Faites passer les imports internes via `./api.ts` ou - `./runtime-api.ts`. Le chemin SDK est uniquement le contrat externe. + N’importez jamais votre propre plugin via `openclaw/plugin-sdk/` + depuis le code de production. Faites passer les importations internes par `./api.ts` ou + `./runtime-api.ts`. Le chemin du SDK est uniquement le contrat externe. -Les surfaces publiques de plugin intégré chargées via façade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` et autres fichiers d'entrée publics similaires) préfèrent désormais l'instantané -de configuration d'exécution actif lorsque OpenClaw est déjà en cours d'exécution. Si aucun instantané d'exécution -n'existe encore, elles se replient sur le fichier de configuration résolu sur le disque. +Les surfaces publiques des plugins intégrés chargées via façade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` et fichiers d’entrée publics similaires) préfèrent désormais +l’instantané actif de config d’exécution lorsque OpenClaw est déjà en cours d’exécution. Si aucun instantané +d’exécution n’existe encore, elles reviennent au fichier de config résolu sur le disque. -Les plugins de provider peuvent aussi exposer un baril de contrat local au plugin et étroit lorsqu'un -helper est intentionnellement spécifique au provider et n'a pas encore sa place dans un -sous-chemin SDK générique. Exemple intégré actuel : le provider Anthropic conserve ses helpers de flux Claude -dans sa propre surface publique `api.ts` / `contract-api.ts` au lieu de promouvoir la logique -d'en-tête bêta Anthropic et `service_tier` dans un contrat générique -`plugin-sdk/*`. +Les plugins de fournisseur peuvent aussi exposer un barrel de contrat local au plugin et étroit lorsqu’un +helper est intentionnellement spécifique à un fournisseur et n’a pas encore sa place dans un sous-chemin SDK +générique. Exemple intégré actuel : le fournisseur Anthropic conserve ses helpers de flux Claude +dans sa propre surface publique `api.ts` / `contract-api.ts` au lieu de +promouvoir la logique d’en-tête bêta Anthropic et `service_tier` dans un contrat +générique `plugin-sdk/*`. Autres exemples intégrés actuels : -- `@openclaw/openai-provider` : `api.ts` exporte des constructeurs de provider, - des helpers de modèle par défaut et des constructeurs de provider temps réel -- `@openclaw/openrouter-provider` : `api.ts` exporte le constructeur de provider ainsi que - des helpers d'onboarding/configuration +- `@openclaw/openai-provider` : `api.ts` exporte des constructeurs de fournisseur, + des helpers de modèle par défaut et des constructeurs de fournisseur temps réel +- `@openclaw/openrouter-provider` : `api.ts` exporte le constructeur de fournisseur ainsi que + des helpers d’intégration/de config - Le code de production d'extension doit aussi éviter les imports `openclaw/plugin-sdk/`. + Le code de production des extensions doit également éviter les importations `openclaw/plugin-sdk/`. Si un helper est réellement partagé, promouvez-le vers un sous-chemin SDK neutre - tel que `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, ou une autre - surface orientée capacité au lieu de coupler deux plugins ensemble. + tel que `openclaw/plugin-sdk/speech`, `.../provider-model-shared` ou une autre + surface orientée capacité au lieu de coupler deux plugins entre eux. -## Voir aussi +## Liens connexes -- [Points d'entrée](/fr/plugins/sdk-entrypoints) — options `definePluginEntry` et `defineChannelPluginEntry` -- [Helpers d'exécution](/fr/plugins/sdk-runtime) — référence complète de l'espace de noms `api.runtime` -- [Configuration et config](/fr/plugins/sdk-setup) — packaging, manifestes, schémas de configuration +- [Points d’entrée](/fr/plugins/sdk-entrypoints) — options de `definePluginEntry` et `defineChannelPluginEntry` +- [Helpers de runtime](/fr/plugins/sdk-runtime) — référence complète de l’espace de noms `api.runtime` +- [Configuration et config](/fr/plugins/sdk-setup) — empaquetage, manifestes, schémas de config - [Tests](/fr/plugins/sdk-testing) — utilitaires de test et règles de lint -- [Migration du SDK](/fr/plugins/sdk-migration) — migration depuis les surfaces obsolètes -- [Internes des plugins](/fr/plugins/architecture) — architecture approfondie et modèle de capacité +- [Migration du SDK](/fr/plugins/sdk-migration) — migration depuis des surfaces obsolètes +- [Internes des plugins](/fr/plugins/architecture) — architecture détaillée et modèle de capacités diff --git a/docs/fr/tools/thinking.md b/docs/fr/tools/thinking.md index 0022ea8f4..803a2d601 100644 --- a/docs/fr/tools/thinking.md +++ b/docs/fr/tools/thinking.md @@ -1,13 +1,13 @@ --- read_when: - - Ajuster l'analyse ou les valeurs par défaut des directives de réflexion, du mode rapide ou du mode verbeux -summary: Syntaxe des directives pour `/think`, `/fast`, `/verbose`, `/trace` et la visibilité du raisonnement + - Ajustement de l’analyse des directives ou des valeurs par défaut pour le niveau de réflexion, le mode rapide ou le mode verbeux +summary: Syntaxe des directives pour /think, /fast, /verbose, /trace et la visibilité du raisonnement title: Niveaux de réflexion x-i18n: - generated_at: "2026-04-12T23:33:32Z" + generated_at: "2026-04-17T06:57:28Z" model: gpt-5.4 provider: openai - source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68 + source_hash: 1cb44a7bf75546e5a8c3204e12f3297221449b881161d173dea4983da3921649 source_path: tools/thinking.md workflow: 15 --- @@ -16,103 +16,106 @@ x-i18n: ## Ce que cela fait -- Directive inline dans tout corps entrant : `/t `, `/think:`, ou `/thinking `. +- Directive en ligne dans tout corps de message entrant : `/t `, `/think:` ou `/thinking `. - Niveaux (alias) : `off | minimal | low | medium | high | xhigh | adaptive` - minimal → « réfléchir » - low → « réfléchir sérieusement » - medium → « réfléchir davantage » - high → « ultrathink » (budget maximal) - - xhigh → « ultrathink+ » (modèles GPT-5.2 + Codex uniquement) - - adaptive → budget de raisonnement adaptatif géré par le fournisseur (pris en charge pour la famille de modèles Anthropic Claude 4.6) - - `x-high`, `x_high`, `extra-high`, `extra high`, et `extra_high` sont mappés vers `xhigh`. - - `highest`, `max` sont mappés vers `high`. -- Notes sur les fournisseurs : - - Les modèles Anthropic Claude 4.6 utilisent `adaptive` par défaut lorsqu'aucun niveau de réflexion explicite n'est défini. - - MiniMax (`minimax/*`) sur le chemin de streaming compatible Anthropic utilise par défaut `thinking: { type: "disabled" }` sauf si vous définissez explicitement thinking dans les paramètres du modèle ou de la requête. Cela évite les deltas `reasoning_content` divulgués par le format de flux Anthropic non natif de MiniMax. - - Z.AI (`zai/*`) ne prend en charge qu'un thinking binaire (`on`/`off`). Tout niveau autre que `off` est traité comme `on` (mappé vers `low`). - - Moonshot (`moonshot/*`) mappe `/think off` vers `thinking: { type: "disabled" }` et tout niveau autre que `off` vers `thinking: { type: "enabled" }`. Lorsque thinking est activé, Moonshot n'accepte que `tool_choice` `auto|none` ; OpenClaw normalise les valeurs incompatibles vers `auto`. + - xhigh → « ultrathink+ » (GPT-5.2 + modèles Codex et effort Anthropic Claude Opus 4.7) + - adaptive → réflexion adaptative gérée par le fournisseur (prise en charge pour Anthropic Claude 4.6 et Opus 4.7) + - `x-high`, `x_high`, `extra-high`, `extra high` et `extra_high` correspondent à `xhigh`. + - `highest`, `max` correspondent à `high`. +- Remarques sur les fournisseurs : + - Les modèles Anthropic Claude 4.6 utilisent `adaptive` par défaut lorsqu’aucun niveau de réflexion explicite n’est défini. + - Anthropic Claude Opus 4.7 n’utilise pas la réflexion adaptative par défaut. Sa valeur d’effort par défaut de l’API reste gérée par le fournisseur, sauf si vous définissez explicitement un niveau de réflexion. + - Anthropic Claude Opus 4.7 mappe `/think xhigh` vers une réflexion adaptative plus `output_config.effort: "xhigh"`, car `/think` est une directive de réflexion et `xhigh` est le paramètre d’effort d’Opus 4.7. + - MiniMax (`minimax/*`) sur le chemin de streaming compatible Anthropic utilise par défaut `thinking: { type: "disabled" }`, sauf si vous définissez explicitement la réflexion dans les paramètres du modèle ou de la requête. Cela évite les deltas `reasoning_content` divulgués par le format de flux Anthropic non natif de MiniMax. + - Z.AI (`zai/*`) prend uniquement en charge une réflexion binaire (`on`/`off`). Tout niveau autre que `off` est traité comme `on` (mappé vers `low`). + - Moonshot (`moonshot/*`) mappe `/think off` vers `thinking: { type: "disabled" }` et tout niveau autre que `off` vers `thinking: { type: "enabled" }`. Lorsque la réflexion est activée, Moonshot n’accepte que `tool_choice` `auto|none` ; OpenClaw normalise les valeurs incompatibles en `auto`. ## Ordre de résolution -1. Directive inline sur le message (s'applique uniquement à ce message). -2. Remplacement de session (défini en envoyant un message contenant uniquement une directive). -3. Valeur par défaut par agent (`agents.list[].thinkingDefault` dans la configuration). -4. Valeur par défaut globale (`agents.defaults.thinkingDefault` dans la configuration). -5. Repli : `adaptive` pour les modèles Anthropic Claude 4.6, `low` pour les autres modèles compatibles avec le raisonnement, `off` sinon. +1. Directive en ligne sur le message (s’applique uniquement à ce message). +2. Surcharge de session (définie en envoyant un message contenant uniquement une directive). +3. Valeur par défaut par agent (`agents.list[].thinkingDefault` dans la config). +4. Valeur par défaut globale (`agents.defaults.thinkingDefault` dans la config). +5. Repli : `adaptive` pour les modèles Anthropic Claude 4.6, `off` pour Anthropic Claude Opus 4.7 sauf configuration explicite, `low` pour les autres modèles prenant en charge la réflexion, `off` sinon. ## Définir une valeur par défaut de session - Envoyez un message qui contient **uniquement** la directive (espaces autorisés), par exemple `/think:medium` ou `/t high`. -- Cela reste appliqué à la session actuelle (par expéditeur par défaut) ; effacé par `/think:off` ou une réinitialisation après inactivité de session. -- Une réponse de confirmation est envoyée (`Thinking level set to high.` / `Thinking disabled.`). Si le niveau est invalide (par exemple `/thinking big`), la commande est rejetée avec une indication et l'état de la session reste inchangé. +- Cela reste actif pour la session en cours (par expéditeur par défaut) ; effacé par `/think:off` ou par la réinitialisation après inactivité de la session. +- Une réponse de confirmation est envoyée (`Thinking level set to high.` / `Thinking disabled.`). Si le niveau est invalide (par exemple `/thinking big`), la commande est rejetée avec une indication et l’état de la session reste inchangé. - Envoyez `/think` (ou `/think:`) sans argument pour voir le niveau de réflexion actuel. ## Application par agent -- **Pi embarqué** : le niveau résolu est transmis au runtime d'agent Pi en processus. +- **Pi intégré** : le niveau résolu est transmis au runtime de l’agent Pi en cours de processus. ## Mode rapide (/fast) - Niveaux : `on|off`. -- Un message contenant uniquement la directive active/désactive un remplacement de session du mode rapide et répond `Fast mode enabled.` / `Fast mode disabled.`. -- Envoyez `/fast` (ou `/fast status`) sans mode pour voir l'état effectif actuel du mode rapide. +- Un message contenant uniquement une directive active ou désactive une surcharge de session du mode rapide et répond `Fast mode enabled.` / `Fast mode disabled.`. +- Envoyez `/fast` (ou `/fast status`) sans mode pour voir l’état effectif actuel du mode rapide. - OpenClaw résout le mode rapide dans cet ordre : - 1. `/fast on|off` inline/contenant uniquement la directive - 2. Remplacement de session + 1. `/fast on|off` en ligne / sous forme de directive seule + 2. Surcharge de session 3. Valeur par défaut par agent (`agents.list[].fastModeDefault`) - 4. Configuration par modèle : `agents.defaults.models["/"].params.fastMode` + 4. Config par modèle : `agents.defaults.models["/"].params.fastMode` 5. Repli : `off` - Pour `openai/*`, le mode rapide correspond au traitement prioritaire OpenAI en envoyant `service_tier=priority` sur les requêtes Responses prises en charge. -- Pour `openai-codex/*`, le mode rapide envoie le même indicateur `service_tier=priority` sur Codex Responses. OpenClaw conserve un seul basculement `/fast` partagé entre les deux chemins d'authentification. -- Pour les requêtes directes publiques `anthropic/*`, y compris le trafic authentifié par OAuth envoyé à `api.anthropic.com`, le mode rapide correspond aux niveaux de service Anthropic : `/fast on` définit `service_tier=auto`, `/fast off` définit `service_tier=standard_only`. +- Pour `openai-codex/*`, le mode rapide envoie le même indicateur `service_tier=priority` sur les réponses Codex. OpenClaw conserve un seul basculement `/fast` partagé entre les deux chemins d’authentification. +- Pour les requêtes directes publiques `anthropic/*`, y compris le trafic authentifié par OAuth envoyé vers `api.anthropic.com`, le mode rapide correspond aux niveaux de service Anthropic : `/fast on` définit `service_tier=auto`, `/fast off` définit `service_tier=standard_only`. - Pour `minimax/*` sur le chemin compatible Anthropic, `/fast on` (ou `params.fastMode: true`) réécrit `MiniMax-M2.7` en `MiniMax-M2.7-highspeed`. -- Les paramètres explicites de modèle Anthropic `serviceTier` / `service_tier` remplacent la valeur par défaut du mode rapide lorsque les deux sont définis. OpenClaw continue à ignorer l'injection du niveau de service Anthropic pour les URL de base proxy non Anthropic. +- Les paramètres explicites du modèle Anthropic `serviceTier` / `service_tier` remplacent la valeur par défaut du mode rapide lorsque les deux sont définis. OpenClaw continue toutefois à ignorer l’injection du niveau de service Anthropic pour les URL de base proxy non Anthropic. ## Directives verbeuses (/verbose ou /v) - Niveaux : `on` (minimal) | `full` | `off` (par défaut). -- Un message contenant uniquement la directive active le mode verbeux de session et répond `Verbose logging enabled.` / `Verbose logging disabled.` ; les niveaux invalides renvoient une indication sans modifier l'état. -- `/verbose off` stocke un remplacement explicite de session ; effacez-le via l'interface Sessions en choisissant `inherit`. -- La directive inline n'affecte que ce message ; les valeurs par défaut de session/globales s'appliquent sinon. -- Envoyez `/verbose` (ou `/verbose:`) sans argument pour voir le niveau verbeux actuel. -- Lorsque le mode verbeux est activé, les agents qui émettent des résultats d'outils structurés (Pi, autres agents JSON) renvoient chaque appel d'outil dans son propre message contenant uniquement des métadonnées, préfixé par ` : ` lorsque disponible (chemin/commande). Ces résumés d'outils sont envoyés dès le démarrage de chaque outil (bulles séparées), et non comme deltas de streaming. -- Les résumés d'échec d'outil restent visibles en mode normal, mais les suffixes détaillés d'erreur brute sont masqués sauf si verbose vaut `on` ou `full`. -- Lorsque verbose vaut `full`, les sorties d'outils sont également transmises après leur achèvement (bulle séparée, tronquée à une longueur sûre). Si vous basculez `/verbose on|full|off` pendant qu'une exécution est en cours, les bulles d'outils suivantes respectent le nouveau réglage. +- Un message contenant uniquement une directive active la verbosité de session et répond `Verbose logging enabled.` / `Verbose logging disabled.` ; les niveaux invalides renvoient une indication sans modifier l’état. +- `/verbose off` enregistre une surcharge explicite de session ; effacez-la via l’interface Sessions en choisissant `inherit`. +- La directive en ligne n’affecte que ce message ; sinon, les valeurs par défaut de session/globales s’appliquent. +- Envoyez `/verbose` (ou `/verbose:`) sans argument pour voir le niveau de verbosité actuel. +- Lorsque le mode verbeux est activé, les agents qui émettent des résultats d’outils structurés (Pi, autres agents JSON) renvoient chaque appel d’outil comme son propre message de métadonnées uniquement, préfixé par ` : ` lorsque disponible (chemin/commande). Ces résumés d’outils sont envoyés dès le démarrage de chaque outil (bulles séparées), et non comme deltas de streaming. +- Les résumés d’échec des outils restent visibles en mode normal, mais les suffixes détaillant les erreurs brutes sont masqués sauf si verbose vaut `on` ou `full`. +- Lorsque verbose vaut `full`, les sorties des outils sont également transmises après leur fin (bulle séparée, tronquée à une longueur sûre). Si vous basculez `/verbose on|full|off` pendant qu’une exécution est en cours, les bulles d’outils suivantes respecteront le nouveau paramètre. -## Directives de trace du Plugin (/trace) +## Directives de trace de Plugin (/trace) - Niveaux : `on` | `off` (par défaut). -- Un message contenant uniquement la directive active la sortie de trace du Plugin pour la session et répond `Plugin trace enabled.` / `Plugin trace disabled.`. -- La directive inline n'affecte que ce message ; les valeurs par défaut de session/globales s'appliquent sinon. +- Un message contenant uniquement une directive active la sortie de trace des plugins pour la session et répond `Plugin trace enabled.` / `Plugin trace disabled.`. +- La directive en ligne n’affecte que ce message ; sinon, les valeurs par défaut de session/globales s’appliquent. - Envoyez `/trace` (ou `/trace:`) sans argument pour voir le niveau de trace actuel. -- `/trace` est plus étroit que `/verbose` : il n'expose que les lignes de trace/de débogage appartenant au Plugin, comme les résumés de débogage Active Memory. -- Les lignes de trace peuvent apparaître dans `/status` et comme message de diagnostic de suivi après la réponse normale de l'assistant. +- `/trace` est plus ciblé que `/verbose` : il n’expose que les lignes de trace/debug appartenant aux plugins, comme les résumés de débogage Active Memory. +- Les lignes de trace peuvent apparaître dans `/status` et sous forme de message de diagnostic de suivi après la réponse normale de l’assistant. ## Visibilité du raisonnement (/reasoning) - Niveaux : `on|off|stream`. -- Un message contenant uniquement la directive active/désactive l'affichage des blocs de réflexion dans les réponses. -- Lorsqu'il est activé, le raisonnement est envoyé comme **message séparé** préfixé par `Reasoning:`. -- `stream` (Telegram uniquement) : diffuse le raisonnement dans la bulle de brouillon Telegram pendant la génération de la réponse, puis envoie la réponse finale sans le raisonnement. +- Un message contenant uniquement une directive active ou désactive l’affichage des blocs de réflexion dans les réponses. +- Lorsqu’elle est activée, la réflexion est envoyée comme **message séparé** préfixé par `Reasoning:`. +- `stream` (Telegram uniquement) : diffuse la réflexion dans la bulle de brouillon Telegram pendant la génération de la réponse, puis envoie la réponse finale sans la réflexion. - Alias : `/reason`. -- Envoyez `/reasoning` (ou `/reasoning:`) sans argument pour voir le niveau de raisonnement actuel. -- Ordre de résolution : directive inline, puis remplacement de session, puis valeur par défaut par agent (`agents.list[].reasoningDefault`), puis repli (`off`). +- Envoyez `/reasoning` (ou `/reasoning:`) sans argument pour voir le niveau actuel de raisonnement. +- Ordre de résolution : directive en ligne, puis surcharge de session, puis valeur par défaut par agent (`agents.list[].reasoningDefault`), puis repli (`off`). -## Voir aussi +## Lié -- La documentation du mode élevé se trouve dans [Elevated mode](/fr/tools/elevated). +- La documentation du mode élevé se trouve dans [Mode élevé](/fr/tools/elevated). ## Heartbeats -- Le corps de la sonde Heartbeat est l'invite Heartbeat configurée (par défaut : `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Les directives inline dans un message Heartbeat s'appliquent comme d'habitude (mais évitez de modifier les valeurs par défaut de session à partir des Heartbeats). -- L'envoi Heartbeat transmet par défaut uniquement la charge utile finale. Pour envoyer aussi le message séparé `Reasoning:` (lorsqu'il est disponible), définissez `agents.defaults.heartbeat.includeReasoning: true` ou, par agent, `agents.list[].heartbeat.includeReasoning: true`. +- Le corps de la sonde Heartbeat est le prompt Heartbeat configuré (par défaut : `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Les directives en ligne dans un message Heartbeat s’appliquent normalement (mais évitez de modifier les valeurs par défaut de session à partir des Heartbeats). +- La livraison Heartbeat envoie par défaut uniquement la charge utile finale. Pour envoyer aussi le message séparé `Reasoning:` (lorsqu’il est disponible), définissez `agents.defaults.heartbeat.includeReasoning: true` ou, par agent, `agents.list[].heartbeat.includeReasoning: true`. ## Interface de chat web -- Le sélecteur de réflexion du chat web reflète le niveau stocké de la session depuis le magasin de sessions/configuration entrante au chargement de la page. -- Choisir un autre niveau écrit immédiatement le remplacement de session via `sessions.patch` ; il n'attend pas l'envoi suivant et ce n'est pas un remplacement ponctuel `thinkingOnce`. -- La première option est toujours `Default ()`, où la valeur par défaut résolue provient du modèle actif de la session : `adaptive` pour Claude 4.6 sur Anthropic/Bedrock, `low` pour les autres modèles compatibles avec le raisonnement, `off` sinon. -- Le sélecteur reste conscient du fournisseur : +- Le sélecteur de réflexion du chat web reflète le niveau stocké de la session à partir du magasin de session entrant/de la config au chargement de la page. +- Choisir un autre niveau écrit immédiatement la surcharge de session via `sessions.patch` ; cela n’attend pas le prochain envoi et ce n’est pas une surcharge ponctuelle `thinkingOnce`. +- La première option est toujours `Default ()`, où la valeur par défaut résolue provient du modèle actif de la session : `adaptive` pour Claude 4.6 sur Anthropic, `off` pour Anthropic Claude Opus 4.7 sauf configuration, `low` pour les autres modèles prenant en charge la réflexion, `off` sinon. +- Le sélecteur reste adapté au fournisseur : - la plupart des fournisseurs affichent `off | minimal | low | medium | high | adaptive` + - Anthropic Claude Opus 4.7 affiche `off | minimal | low | medium | high | xhigh | adaptive` - Z.AI affiche le binaire `off | on` -- `/think:` fonctionne toujours et met à jour le même niveau de session stocké, de sorte que les directives de chat et le sélecteur restent synchronisés. +- `/think:` fonctionne toujours et met à jour le même niveau de session stocké, afin que les directives du chat et le sélecteur restent synchronisés.