Le dépôt officiel de DeepSeek Harness affiche actuellement 15,8 k forks et 152,7 k étoiles, mais ces chiffres ne garantissent pas la stabilité de l’API. (dépôt officiel DeepSeek Harness) Pour cette semaine, la bonne décision est donc simple : choisissez d’abord le scénario d’extension, puis construisez le plugin minimal qui prouve une seule capacité. Ne commencez pas par un ensemble complet d’outils, une interface et plusieurs fournisseurs de modèles.

Dernière mise à jour : 18 août 2026. Informations vérifiées sur le README, l’architecture, le guide de développement et le package.json du dépôt officiel DeepSeek Harness à cette date.

Cet article s’adresse à vous si vous devez transformer un script interne en outil utilisable par DeepSeek Harness, connecter un point d’accès de modèle personnalisé ou fournir à une petite équipe un environnement de développement reproductible. Il convient également aux responsables qui doivent définir une procédure d’acceptation avant de laisser un plugin entrer dans un profil partagé.

01

Le périmètre du plugin dépend de l’extension recherchée

DeepSeek Harness est présenté comme un projet open source en developer preview, avec une architecture où plusieurs parties importantes peuvent être fournies par un plugin. Les documents officiels décrivent notamment une organisation autour de Cordis, de bundles, de profils et de composants remplaçables. (documentation d’architecture officielle)

Cette flexibilité crée aussi le premier piège : vous pouvez facilement placer trop de responsabilités dans un seul paquet.

Plugin d’outil

Choisissez ce format lorsque votre besoin se résume à une action clairement nommée :

  • interroger une base interne ;
  • convertir un fichier audio ou vidéo ;
  • appeler une API métier ;
  • lancer une opération avec un outil de design automatisé ;
  • exécuter une commande avec des permissions contrôlées.

L’outil doit posséder une entrée identifiable, un schéma d’entrée, un résultat structuré et une erreur exploitable. Si votre script nécessite son propre modèle, sa propre interface et une orchestration de plusieurs étapes, il ne s’agit probablement plus d’un simple plugin d’outil.

Signal de réussite : le plugin se charge, l’outil apparaît dans le registre et une entrée invalide retourne une erreur indiquant le champ fautif.

Retour arrière : retirez uniquement la ligne de configuration ou le paquet de l’environnement d’essai. Le profil doit pouvoir démarrer sans ce plugin.

Plugin de fournisseur de modèle

Ce scénario concerne la connexion à un endpoint compatible avec votre organisation, un relais interne ou un modèle qui possède un format de requête particulier. Sa responsabilité est différente de celle d’un outil : il expose une capacité de génération, gère les paramètres du fournisseur et respecte le contrat attendu par la boucle d’agent.

Ne mélangez pas ce code avec les outils métier. Vous devez pouvoir changer de fournisseur sans réécrire la logique qui manipule des fichiers, interroge vos systèmes ou contrôle une tâche audio.

Signal de réussite : un profil de test sélectionne le fournisseur, affiche le modèle disponible et exécute une requête minimale.

Retour arrière : repassez sur le fournisseur déjà présent dans le profil de référence, sans supprimer les plugins d’outils.

Extension d’interface

Une fonction visible dans le Web UI, comme une vue de session, un panneau de diagnostic ou un flux de validation pour une production vidéo, traverse une frontière différente. Le guide de développement officiel distingue les agrégats Host et Client, avec des configurations TypeScript séparées. (guide officiel de développement)

Le point important n’est pas de reproduire toute l’implémentation interne. C’est de décider où vit chaque responsabilité :

  • accès aux secrets et aux services côté Host ;
  • rendu, état visuel et ressources navigateur côté Client ;
  • contrat distant documenté entre les deux ;
  • vérification du résultat après génération des artefacts.

Signal de réussite : le paquet se compile dans la bonne face, le service distant répond avec son contrat prévu et le navigateur charge les ressources sans contourner les permissions.

Retour arrière : désactivez le panneau dans un profil dédié et conservez l’interface standard pour vérifier que le problème ne vient pas d’un service Host partagé.

Composition de workflow

Un workflow ne doit pas automatiquement devenir un « super-plugin ». Si vous combinez un outil de recherche, un fournisseur de modèle, une validation humaine et une exportation vidéo, la maintenance sera plus sûre si chaque capacité reste installable et désinstallable séparément.

Utilisez ensuite un profil pour composer ces éléments. L’architecture officielle décrit un profil comme une composition nommée de bundles, de plugins externes et de couches cordis.patch.yml. (référence officielle sur les profils et les plugins)

Signal de réussite : le profil d’essai reproduit la chaîne complète, tandis que chaque plugin peut encore être testé seul.

Retour arrière : revenez à un profil minimal et retirez la dernière couche ajoutée. Vous devez identifier le composant fautif sans restaurer tout le dépôt.

02

Première étape : bâtir le plus petit plugin vérifiable

Pour un premier dsh-plugin, partez d’un seul contrat. Le nom du paquet, les champs du manifeste et le point d’entrée exacts doivent être vérifiés dans la documentation et dans le code de la branche master au moment du développement. Le dépôt recommande d’ajouter le sujet dsh-plugin à un dépôt de plugin pour améliorer sa découvrabilité, mais ce sujet ne constitue pas à lui seul une garantie de compatibilité. (indications officielles pour les contributeurs)

Votre structure de travail doit au minimum séparer :

  1. le manifeste du paquet, qui indique comment DeepSeek Harness identifie et charge l’extension ;
  2. le point d’entrée, qui enregistre la capacité dans le contexte Cordis ;
  3. les types de configuration, avec les valeurs obligatoires et facultatives ;
  4. la logique métier, qui ne doit pas dépendre d’un état global invisible ;
  5. les tests, séparant le chargement, la validation et l’exécution ;
  6. la documentation de profil, expliquant où l’extension doit être activée.

Ne copiez pas tout le répertoire d’un paquet interne en espérant obtenir un plugin public. Cette méthode importe souvent des dépendances non documentées, des chemins propres au monorepo ou des hypothèses de compilation qui ne tiennent pas dans un paquet isolé.

Avec TypeScript, imposez un contrat d’entrée strict. Une requête sans identifiant, avec un chemin ambigu ou une option incompatible doit échouer avant l’appel externe. Le message doit fournir le nom de l’opération, le champ concerné et l’action corrective. Une simple exception générique ne suffit pas pour diagnostiquer un plugin chargé dans un profil distant.

Attention : DeepSeek Harness est encore en developer preview et le README annonce explicitement des changements pouvant casser la compatibilité. Toute documentation interne doit donc mentionner le commit ou la version vérifiée, et non seulement le nom du projet.

03

Deuxième étape : isoler les secrets et les paramètres variables

Les identifiants ne doivent jamais être écrits dans le code du plugin ni dans un fichier de profil partagé. Le guide de développement indique que les démonstrations et les tests réels peuvent lire DEEPSEEK_API_KEY depuis l’environnement ou depuis un fichier .env ignoré par Git. Il documente également DEEPSEEK_BASE_URL comme variable facultative pour un endpoint personnalisé. (variables d’environnement documentées officiellement)

La séparation recommandée est la suivante :

  • code versionné : noms de variables, valeurs par défaut non sensibles, validation et documentation ;
  • environnement local : clé API et endpoint de développement ;
  • profil d’équipe : sélection du fournisseur, modèle autorisé et politique de permissions ;
  • système de livraison : injection des secrets au dernier moment, jamais dans l’archive du plugin.

Un plugin de fournisseur doit aussi distinguer trois éléments souvent mélangés :

  • l’URL du service ;
  • la méthode d’authentification ;
  • le catalogue de modèles acceptés.

Cette distinction facilite le remplacement d’un endpoint interne et permet d’écrire un test sans clé réelle. Pour un fournisseur non disponible pendant les tests, utilisez un faux transport ou un adaptateur local ; ne désactivez pas la validation simplement pour faire passer le démarrage.

04

Troisième étape : respecter la frontière Host et Client

Les projets qui ajoutent une interface Web doivent traiter la construction comme une chaîne ordonnée. Le guide officiel décrit un build qui passe par le typage Host, la génération des artefacts Host, le typage Client, les artefacts navigateur, puis la construction Web. Les commandes documentées sont :

pnpm run typecheck
pnpm run build

Le guide détaille également l’ordre interne utilisé par le build complet, notamment les agrégats tsconfig.host.json et tsconfig.client.json.

Pour votre extension, vérifiez séparément :

  • que le service Host est déclaré dans le bon agrégat ;
  • que le composant Client n’importe pas un module serveur ;
  • que les types distants sont générés avant leur consommation côté navigateur ;
  • que les erreurs réseau sont visibles dans l’interface ;
  • que le retrait du plugin ne laisse pas une route ou une ressource orpheline.

Cela s’applique aussi aux cas créatifs. Un panneau qui envoie une séquence vidéo à un service d’analyse, une vue de planche pour un outil de design ou un retour audio temps réel ne doit pas exposer directement les identifiants au navigateur.

05

Quatrième étape : composer les profils sans modifier une configuration globale

Un profil sert à décrire une combinaison de plugins. L’architecture précise que les bundles sont appliqués dans un ordre, puis complétés par les patches du profil, ceux du répertoire utilisateur et éventuellement une surcharge passée avec --patch.

Pour une équipe, créez au moins trois compositions conceptuelles :

  • expérimentation : plugin en cours, journaux détaillés, permissions limitées ;
  • test : fournisseur simulé ou endpoint contrôlé, données synthétiques, aucune action destructive ;
  • tâche continue : uniquement les plugins validés, avec politique d’approbation stricte.

Après chaque modification, inspectez la configuration réellement chargée. La commande officielle suivante permet d’afficher l’arbre d’un profil Web :

dsh --profile web --dump-config

Ne supposez pas qu’un paquet installé est actif. Il peut être présent dans l’environnement tout en restant absent de la composition du profil. Inversement, une couche de patch peut remplacer toute la configuration d’une ligne existante, ce qui explique certains comportements différents entre deux machines.

La bonne pratique consiste à versionner la composition du profil avec le plugin, puis à conserver les secrets et les valeurs propres à chaque développeur hors du dépôt. Vous évitez ainsi qu’une personne modifie la configuration globale et rende les tests d’une autre personne non reproductibles.

06

Cinquième étape : vérifier l’environnement avant d’accuser le plugin

Le guide de développement officiel demande actuellement Node.js 22.19 ou une version 24 et indique que l’intégration continue couvre aussi Node.js 26. Le dépôt épingle pnpm@11.7.0 dans son package.json et recommande Corepack pour utiliser cette version. (versions et commandes du guide officiel)

Une séquence de base, vérifiée dans le guide, est :

corepack enable
pnpm install
pnpm run typecheck
pnpm run build

Pour un dépôt source complet, le README indique également le flux git clone, pnpm install, pnpm run build, puis pnpm dsh web. (procédure officielle de démarrage)

Avant de tester votre extension, notez :

  • la version de Node.js ;
  • la version de pnpm ;
  • le commit DeepSeek Harness ;
  • le système d’exploitation ;
  • le profil utilisé ;
  • la présence ou non d’une clé API ;
  • la date de la dernière vérification.

Ce relevé est plus utile qu’un simple « fonctionne chez moi ». Dans une preview active, une modification du contrat TypeScript ou d’un bundle peut ressembler à une erreur de logique alors qu’elle provient du socle.

07

Les conditions de décision pour choisir votre architecture

Utilisez les règles suivantes avant d’ouvrir un nouveau dépôt :

  • Si votre besoin expose une seule action avec une entrée et une sortie nettes, choisissez un plugin d’outil ; sinon, revenez à un adaptateur plus petit avant d’ajouter une orchestration.
  • Si votre besoin change l’endpoint, l’authentification ou le catalogue de modèles, choisissez un plugin de fournisseur ; ne le combinez pas avec des outils métier.
  • Si votre besoin possède un écran, un état navigateur ou une API distante, séparez Host et Client ; sinon, restez côté Host.
  • Si votre besoin coordonne plusieurs capacités indépendantes, composez-les dans un profil ; ne copiez pas leurs sources dans un paquet unique.
  • Si vous ne pouvez pas retirer votre extension sans casser le profil de référence, elle est trop couplée pour une première livraison.
  • Si l’API utilisée n’est pas confirmée par la documentation ou la branche vérifiée, marquez-la comme dépendance expérimentale et prévoyez une couche d’adaptation.
08

La réception du plugin doit être testée comme un produit

La publication ne se limite pas à produire un paquet. Vous devez prouver que l’extension est chargeable, identifiable, contrôlable et réversible.

Vérification du typage

Lancez pnpm run typecheck sur un environnement propre. Le dépôt utilise des projets TypeScript séparés pour Host et Client ; une extension ne doit pas être inscrite simultanément dans les deux agrégats sans raison documentée.

Démarrage minimal

Chargez le profil sans exécuter de tâche complexe. Vérifiez que l’application démarre, que les journaux identifient le plugin et qu’une erreur de configuration ne bloque pas toute la composition.

Découverte de la capacité

Pour un outil, confirmez qu’il apparaît avec le nom prévu. Pour un fournisseur, vérifiez la sélection du modèle. Pour une interface, vérifiez le chargement du composant et la réponse du service distant.

Permissions

Testez chaque permission avec un cas autorisé et un cas refusé. Un plugin capable de lire un répertoire, d’appeler un endpoint ou d’écrire un fichier doit afficher une erreur claire lorsque l’accès n’est pas accordé.

Installation propre

Installez le paquet dans un profil qui ne contient aucun artefact de développement. Cette étape révèle les imports locaux, les chemins relatifs fragiles et les fichiers générés absents du paquet.

Retrait et retour arrière

Désactivez l’extension, restaurez le profil minimal et relancez DeepSeek Harness. Le système doit revenir à un état utilisable sans intervention manuelle dans plusieurs fichiers de configuration.

Traçabilité

Archivez le commit testé, le contenu du manifeste, la version des dépendances et la date de révision. Dans un projet dont l’API n’est pas figée, cette fiche de validation doit accompagner chaque version publiée.

09

Comparer le poste actuel avec un environnement Mac conservé

Un poste local déjà utilisé peut convenir pour un plugin ponctuel. Il présente toutefois quatre limites fréquentes : dépendances installées au fil du temps, versions Node.js différentes entre collègues, accès distant peu fiable et absence de procédure propre pour conserver un profil entre deux phases de test. Pour une extension Web, les interruptions de session compliquent aussi la validation Host/Client et les essais audio ou vidéo.

Un environnement Mac réservé au développement apporte surtout de la continuité, pas une garantie magique de compatibilité. Vous devez encore figer les versions, documenter le commit et exécuter les tests de retrait. La différence est que l’environnement reste disponible lorsque le plugin doit être repris, démontré à un client ou testé par plusieurs personnes à des horaires différents.

Situation de développement Solution actuelle Environnement Mac avec VpsMesh
Prototype isolé, peu de reprises Poste local suffisant Location souvent inutile
Tests réguliers sur plusieurs profils Versions et fichiers locaux difficiles à harmoniser Mac distant conservé avec profils séparés
Interface Web, audio ou vidéo Risque de session interrompue et de dépendances divergentes Accès distant persistant, à condition de documenter le poste
Petite équipe avec validations croisées Partage manuel du dépôt et de la configuration Environnement commun ou postes dédiés, avec droits distincts
Charge longue et stable Achat d’un poste peut être plus rationnel Location à évaluer selon la fréquence réelle
Besoin d’interfaces physiques spécifiques Le poste local reste préférable Vérifier les limites d’un accès distant avant de louer

Si vous développez seulement un outil interne une fois par trimestre, la location n’est probablement pas le meilleur choix. Si vous construisez plusieurs plugins, répétez les tests de compatibilité et devez reprendre rapidement une session distante, consultez les options de location de Mac pour le développement et comparez-les avec votre coût réel de remise en état.

Pour un usage continu, vous pouvez aussi examiner les environnements Mac distants disponibles. L’objectif n’est pas de remplacer vos contrôles logiciels, mais de disposer d’un poste accessible lorsque le projet doit être reconstruit ou présenté. Si votre équipe travaille surtout sur une zone géographique donnée, vérifiez également la configuration Mac dédiée au développement.

La décision finale doit suivre trois mesures internes : durée de construction, fréquence des tests et nombre de contributeurs. Si ces trois facteurs restent faibles, gardez un poste local propre. S’ils augmentent, un Mac distant conservé peut réduire les écarts entre sessions, éviter les installations improvisées et rendre les validations de plugins plus faciles à reprendre.