dsh-plugin-dev

Standard de développement de plugins DSH

Cette compétence est le standard unique pour développer des plugins DeepSeek Harness (DSH) : elle consolide les règles éparpillées dans la documentation officielle de DSH — tutoriels, manuels de référence et répertoires de génération — en un workflow exécutable, des règles strictes et une checklist exploitable. Tout dans DSH est un plugin — adaptateurs de modèle, registres d'outils, logs de session, boucle agent — donc suivre cette compétence équivaut à étendre DSH selon sa propre architecture.

Portée

• Développement de plugins DSH dans un dépôt ou sous forme de fichiers : écriture de paquets de plugin, enregistrement de lignes cordis.yml, patch overlay, développement d'outils, intégration de modèles, empaquetage et installation.
• Le développement de paquets workspace dans le monorepo DSH (packages//) relève également de cette compétence (references/workspace-package.md).
• Cette compétence ne couvre pas : les plugins dynamiques en session (flux cordis_define/cordis_run) ni l'édition de combinaisons agent preset — ces deux catégories sont couvertes par des compétences spécialisées ou des outils officiels de chaque déploiement.

Règles strictes (à respecter dans tous les scénarios)

1. Les interfaces sont basées sur les références générées. Les noms de service, méthodes publiques, signatures d'événements et clés ctx sont basés sur les pages de sous-système et interfaces TypeScript générées automatiquement par le dépôt ; ne déduisez pas l'API complète à partir de noms de service, d'exemples ou d'anciens codes, et ne maintenez pas une autre liste statique.
2. Toutes les contributions sont des effets de bord. Tout enregistrement via ctx (écouteurs d'événements, outils, adaptateurs, ctx.effect) est automatiquement annulé lors du déchargement du plugin ; ne créez pas d'effets de bord au niveau du processus ou de la page dans la portée du module ; pour les abonnements tiers qui ne retournent pas de disposer, identifiez activement le mécanisme de nettoyage.
3. Les écouteurs waterfall doivent appeler next(). Ne pas appeler next() signifie intentionnellement court-circuiter les écouteurs aval (pour interception/passage), ce n'est pas optionnel.
4. Les échecs doivent être bruyants. Une exception dans apply termine le processus ; une validation de configuration échouée doit produire une erreur explicite ; le schéma doit exprimer des contraintes complètes, n'engloutissez pas silencieusement les erreurs à l'exécution.
5. Les dépendances obligatoires sont déclarées avec inject, les dépendances optionnelles utilisent ctx.get() avec vérification null. N'utilisez pas inject pour éviter une vérification undefined ; n'accédez pas non plus directement à ctx.xxx non déclaré — un service non déclaré évalué par le résolveur de service peut donner undefined.
6. La configuration est toujours via Schemastery. Exportez l'interface Config et le Schema du même nom, les valeurs par défaut sont écrites dans le schéma ; n'exportez pas d'objet simple comme Config ; tout paramètre susceptible de changer selon le déploiement doit être dans la configuration.
7. L'exécution d'un outil retourne une valeur JSON standard, pas un bloc de contenu. Le texte destiné aux humains est placé dans output.render ; les stratégies/accroches de déploiement ne doivent pas être intégrées dans l'outil lui-même.
8. Ce qui est visible par le modèle est déjà enregistré. Toute nouvelle entrée visible par le modèle doit reposer sur un mécanisme reconstructible dans les logs de session (nouvel événement persistant ou via agent.inject()), avec une assertion d'invariant à l'exécution.
9. Les panneaux de paramètres npm privilégient ctx.connection.rpc. Les panneaux de paramètres semi-navigateur qui appellent des méthodes du processus principal privilégient Connection RPC (ctx.connection.rpc.handle + ctx.connection.rpc.call), l'exemple est dans references/connection-rpc.md. Interdiction d'utiliser nu @Remote, de rédiger manuellement un manifeste typert, ou d'utiliser createRequire pour accrocher le code source de harness. Les chemins complets issus du générateur Typert et exportés via ./typert + ./remote dans package.json, consommés par ctx.remote.$mount(), restent valides.

Workflows standard

Scénario A : Créer un nouveau plugin

1. Déterminez ce que le plugin apporte (service ? outil ? écouteur ?), utilisez le tableau « Emplacement du nouveau comportement » dans references/seams.md pour choisir le mécanisme.
2. Créez src/.ts, exportez name, inject (optionnel), apply(ctx, config?). Écrivez d'abord sous forme de fonction ; passez à une classe Service lorsque vous devez fournir un service externe.
3. Boucle de développement local (checkout des sources) :

mkdir -p scratch-plugin/src

# scratch-plugin/cordis.yml —— patch overlay ; le chemin du plugin doit être absolu
- insert:
    - id: hello
      name: '/chemin/absolu/vers/deepseek-harness/scratch-plugin/src/mon-plugin.ts'

pnpm dsh web --patch ./scratch-plugin/cordis.yml   # ouvre http://127.0.0.1:3080

4. Vérifiez le chargement et le déchargement : apparition dans les logs de démarrage, nettoyage effectif des ressources à l'arrêt (references/plugin-anatomy.md).

Scénario B : Ajouter un outil à un modèle

1. inject: ['tools'], définissez avec defineTool (name/description/parameters/output/execute).
2. Implémentez selon les conventions d'exécution de references/tools.md : schéma DSL pour déclarer les paramètres et la sortie, execute retourne une valeur standard, respecte exec.signal, presentationMeta/cartes UI optionnelles.
3. Pour les stratégies, accrochez les événements tools/* (pre-execute/guard/execute/post-execute/result), n'écrivez pas la stratégie en dur dans l'outil (exemple de contrôle d'accès dans references/plugin-forms.md).
4. Redémarrez et faites effectivement appeler par le modèle pour validation.

Scénario C : Capacité remplaçable (plusieurs fournisseurs)

1. Selon references/three-roles.md, découpez en trois paquets Definition / Provider / Consumer (fusionnez les rôles selon les besoins, ne séparez pas par précaution).
2. Definition possède les types Request/Result et le Service abstrait ; Provider implémente ; Consumer expose comme outil ou consommateur de service.
3. Dans cordis.yml, listez uniquement les lignes Provider et Consumer ; changez de fournisseur en changeant une seule ligne.

Scénario D : Intégrer un nouveau fournisseur de modèle

1. Héritez de LlmAdapter, implémentez stream(), émettez des fragments selon le protocole StreamChunk ; gérez les erreurs avec LlmError (code stable) (ou terminez dans le flux avec finish { kind: 'error' | 'aborted' }) ; fusionnez attributionHeaders() pour chaque requête HTTP et transmettez signal.
2. ctx.llm.registerAdapter([''], adapter) ; optionnellement surchargez resolveModel()/listModels().
3. Dans la composition, configurez le provider/model de l'agent-loop pour validation. Voir references/llm-adapter.md (inclut 7 obligations de protocole).

Scénario E : Empaquetage et installation

1. Créez un paquet de composition : package.json déclare dsh.bundle (pointant vers cordis.patch.yml), les lignes patch référencent le plugin par son nom de paquet ; les paquets de bibliothèque destinés uniquement à l'import ne déclarent pas dsh.bundle.
2. Installation : dsh plugin --profile add ; d'abord dsh --profile --dump-config pour valider la couche, puis démarrez.
3. Rappelez-vous l'ordre des couches et la sémantique de remplacement de ligne entière (references/packaging.md).

Scénario F : Créer un nouveau paquet dans le monorepo DSH

Suivez la liste fichier par fichier de references/workspace-package.md : créez le paquet (invariant package.json/tsconfig/src/README) → enregistrement dans la configuration racine → topologie et nommage du paquet (tableau des rôles) → structure Model Experience du README → commandes de validation.

Aide à la décision rapide

Je veux...	Mécanisme	Détails
Exposer une capacité à d'autres plugins	Service (forme classe)	references/services.md
Consommer une capacité existante	inject ou ctx.get()	references/services.md
Communication entre plugins / points d'extension	ctx.on / ctx.emit (cinq modes de distribution)	references/events.md
Rendre le plugin configurable	Config + Schemastery	references/config.md
Donner une capacité au modèle	defineTool → ctx.tools.register (ou JSON Schema brut)	references/tools.md
Intégrer un nouveau fournisseur de modèle	LlmAdapter + ctx.llm.registerAdapter	references/llm-adapter.md
Découpler une capacité remplaçable	Trois rôles (Definition/Provider/Consumer)	references/three-roles.md
Distribuer un plugin	Paquet de composition + profile	references/packaging.md
Consulter les services intégrés / emplacements	Répertoire seam, carte d'architecture	references/seams.md
Portée/stockage de service/API Fiber	ctx.extend/isolate/provide/mixin, fiber.*	references/context-api.md
Plugin d'accroche/UI/panneau/pont de protocole	Cinq formes d'extension + mappage fonction→mécanisme	references/plugin-forms.md
Panneau semi-navigateur appelant le processus principal	ctx.connection.rpc.handle/call, endpoint + enveloppe	references/connection-rpc.md
Créer un nouveau paquet dans le dépôt / nommage	Liste workspace + tableau des rôles	references/workspace-package.md

Checklist pré-achèvement

• Les interfaces ont été vérifiées sur les références générées (service/événement/clé ctx basés sur la génération), pas d'API devinée d'après le nom.
• Tous les enregistrements passent par ctx (événements/outils/adaptateurs/effect), nettoyables au déchargement ; les nettoyages dépendant de l'ordre sont placés dans le même ctx.effect.
• Les dépendances obligatoires sont correctement déclarées via inject ; les dépendances optionnelles ont une gestion undefined.
• Plugin avec configuration : Config utilise Schemastery, valeurs par défaut dans le schéma, configuration invalide échoue bruyamment au chargement.
• S'il y a un outil : execute retourne une valeur JSON standard ; render gère le lisible humain ; les stratégies passent par les événements tools/* ; respecte exec.signal ; la sécurité concurrente est déclarée avec isConcurrencySafe (non déclaré → exclusif).
• S'il y a un écouteur waterfall : appelle et retourne next() (sauf court-circuit intentionnel).
• S'il y a un adaptateur LLM : protocole StreamChunk complet (appariement des fragments, index selon première occurrence, usage avant finish, arguments en chaîne JSON brute tout du long) ; les erreurs suivent l'une des deux voies valides ; les champs non supportés lancent UNSUPPORTED ; si replay natif nécessaire, émet finish.replayState ; a transmis attributionHeaders et signal.
• Les lignes de composition et l'ordre des couches sont corrects ; les nouvelles lignes sont visibles dans --dump-config ; pas de registre résiduel après HMR/redémarrage.
• Si le contenu visible par le modèle change : repose sur un mécanisme reconstructible dans les logs.
• Panneaux de paramètres semi-navigateur : privilégient ctx.connection.rpc.handle/call ; interdiction d'utiliser nu @Remote, manifeste typert écrit à la main, createRequire pour accrocher le code source de harness ; les artefacts complets du générateur Typert + ./typert + ./remote restent valides.
• Nouveau paquet workspace : invariant package.json, un seul aggregate, nommage conforme au tableau des rôles, README avec structure Model Experience, et constraints/typecheck/lint/build/hygiene tout vert.

Fichiers de référence (à charger selon les besoins, pas tous à la fois)

Index complet et tableau « Quand lire » dans references/README.md.

• references/plugin-anatomy.md — à lire lors de l'écriture/modification d'un plugin, gestion du cycle de vie ou HMR
• references/services.md — à lire lors de la définition ou consommation d'un service, injection de dépendances
• references/events.md — à lire pour la communication par événements, écoute de points d'extension
• references/config.md — à lire pour rendre un plugin configurable
• references/context-api.md — à lire pour utiliser les portées, le stockage de service ou l'API Fiber
• references/three-roles.md — à lire pour découpler une capacité remplaçable
• references/tools.md — à lire lors du développement d'un outil pour modèle
• references/llm-adapter.md — à lire pour intégrer un nouveau fournisseur de modèle
• references/plugin-forms.md — à lire pour écrire un plugin d'accroche/UI/pont de protocole
• references/connection-rpc.md — à lire lorsqu'un panneau de paramètres npm doit appeler une méthode du processus principal ; à lire aussi si vous rencontrez du nu @Remote / manifeste écrit à la main / pont createRequire
• references/packaging.md — à lire pour l'empaquetage, l'installation et la livraison d'un plugin
• references/workspace-package.md — à lire lors de la création d'un nouveau paquet dans le monorepo
• references/seams.md — à lire pour consulter les services intégrés, les emplacements ou la carte d'architecture

Validation

• Auto-vérification du format : name en kebab-case et identique au nom du répertoire ; description non vide et concise (cette compétence est limitée à 500 caractères) ; corps en Markdown standard ; tous les fichiers de référence cités existent réellement.
• Nommage du répertoire : le nom (name) de cette compétence est dsh-plugin-dev, différent du nom du dépôt dsh-plugin-dev-skills — après clonage/décompression, le dossier doit être renommé en dsh-plugin-dev (pour correspondre à name), sinon le chargeur qui adresse par nom de répertoire pourrait ne pas trouver cette compétence.
• Dans un environnement avec CLI skills-ref, exécutez : skills-ref validate ./dsh-plugin-dev
• Déclenchement de régression : après modification de description, exécutez l'ensemble d'évaluation evals/trigger-queries.json (méthode dans le fichier evals/README.md du dépôt).
• Validation comportementale : suivez le scénario A pour un plugin minimal (logs de chargement + nettoyage au déchargement), puis le scénario B pour un outil de salutation.