Guide des plugins DeepSeek Harness (dsh-plugin-guide)

Développement de plugins DeepSeek Harness (dsh-plugin-guide)

Développez des plugins DeepSeek Harness selon la documentation officielle. Cette compétence constitue un flux de travail et une liste de contraintes ; tous les détails factuels doivent citer le texte original de la base de connaissances, sans invention de mémoire. Toutes les clauses « doit/ne doit pas » proviennent du dépôt officiel AGENTS.md, de docs/ et du site de documentation ; en cas de conflit, le texte officiel prévaut.

Emplacement de la base de connaissances (chercher dans l'ordre, utiliser le premier trouvé)

Cette compétence et la base de connaissances sont distribuées dans le même répertoire (le répertoire contenant ce SKILL.md est la racine de la base de connaissances) ; les chemins sont relatifs. Si vous copiez ce fichier seul sans guide/, references/, cherchez selon les chemins de repli suivants :

1. Même répertoire que ce fichier : ./guide/ (guide complet + antisèches + index des liens de documentation), ./references/ (rapports d'étude et copies complètes de la documentation officielle references/official-docs/docs/), ./downloads/ (téléchargements bruts, optionnel)
2. Copie principale locale : D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\ (chemin d'exemple, à adapter selon l'installation réelle)
3. Checkout du dépôt officiel : D:\deepseek-harness\ (docs/, vendor/cordis/, packages/, examples/)
4. En ligne : https://github.com/deepseek-ai/deepseek-harness , https://deepseek-harness.github.io/deepseek-harness/develop/basic/ , https://github.com/cordiverse/cordis

Les chemins relatifs ci-dessous sont relatifs au point 1 ci-dessus (répertoire contenant ce fichier de compétence).

Prérequis au développement (à faire en premier)

1. Si vous n'avez pas encore lu les concepts Cordis : lisez references/official-docs/docs/cordis-primer.md (5 concepts, 5 minutes) ; pour une mise en pratique, suivez references/official-docs/docs/cordis-tutorial/ 01-07 (exécutable sans clé API).
2. Ouvrez guide/quick-reference.md (antisèche des contrats) + guide/plugin-dev-guide.md (chemin complet). Les correspondances d'URL documentation officielle/communauté sont dans guide/links.md.
3. Confirmez le point d'extension cible : lisez le tableau « Where new behavior goes » dans references/official-docs/docs/architecture.md et le tableau feature→mechanism dans references/official-docs/docs/cookbook/extension-cookbook.md — tout nouveau comportement doit être attaché à un point d'extension documenté ; ne modifiez pas l'agent-loop.

Contrats de plugin obligatoires (lignes rouges officielles, à vérifier point par point)

• Plugin = export du module name + apply(ctx, config) (optionnellement inject: string[]) ; les services dépendants sont prêts avant l'appel de apply ; si un service dépendant disparaît, le plugin se désinstalle automatiquement et se recharge automatiquement après son retour.
• Enregistrement = effet : toute contribution passe par ctx.effect() / ctx.on() / register() du service (retourne un disposer) ; ne jamais utiliser manuellement removeListener/clearInterval pour le nettoyage.
• Les écouteurs waterfall doivent appeler next() ; ne pas l'appeler = court-circuit volontaire (sémantique d'interception). La sémantique de emit/waterfall/parallel/serial/bail est dans l'antisèche.
• Visible par le modèle ⟺ enregistré : tout ce qui entre dans une requête modèle doit pouvoir être reconstruit à partir des journaux de session ; toute nouvelle entrée visible par le modèle doit ajouter un événement de session SessionEventMap.
• Les événements/services typés utilisent le declaration merging (declare module '@deepseek-ai/cordis') ; les événements sont documentés avec @mode.
• La configuration utilise Schema<Config> de Schemastery (pas d'objet simple) ; une configuration invalide échoue bruyamment au chargement ; ne pas coder en dur des paramètres ajustables (jugez si cordis.yml peut les modifier).
• Les outils utilisent defineTool : execute ne retourne que des valeurs JSON conformes au schéma déclaré dans output.schema ; respecte exec.signal ; le contenu lisible par l'humain est placé dans output.render ; le presenter de carte UI est une fonction pure (pas d'I/O, d'horloge ou de hasard).
• Les capacités remplaçables suivent une conception à trois couches : Service Definition / Provider / Consumer ; ne pas décomposer prématurément.
• Packaging : manifeste de bundle "dsh":{"bundle":{"patch":"..."}} ; la surcharge remplace toute la ligne de config par id ; !!js (double point d'exclamation) ; l'installation par git nécessite un script prepare et allowBuilds côté utilisateur ; la publication npm/tarball ne nécessite pas d'autorisation de build.

Chemins de développement par type de tâche

(Les chemins ci-dessous se trouvent dans references/official-docs/, copies complètes de la documentation officielle)

• Nouvel outil : docs/user/develop/basic/tool.md (tutoriel) → docs/cookbook/adding-a-tool.md (contrat complet : validation des paramètres, valeurs conformes, tâche en arrière-plan ctx.jobs, hooks de stratégie, Code Mode, carte UI) → implémentation de référence packages/shell/tool-bash (checkout local).
• Nouveau service/capacité : docs/user/develop/framework/service.md + docs/user/develop/practice/ (code complet de la séparation en trois couches).
• Interception/stratégie/hook : docs/cookbook/extension-cookbook.md (exemple permission-gate) + docs/event-producer-consumer.md (matrice complète des événements).
• Nouveau fournisseur LLM : docs/user/develop/practice/llm-adapter.md (protocole StreamChunk).
• Nœud UI/session : docs/cookbook/adding-a-conversation-node.md + docs/subsystems/session.md, client-modules.md.
• Packaging/publication : docs/user/develop/basic/publish.md (bundle/profile, ordre des couches, pièges d'installation git).
• Recherche d'une signature précise de service/événement : docs/subsystems/*.md (zone API Cordis générative) + docs/cordis-api/* ; ne créez pas une deuxième liste statique. La correspondance URL du site ↔ copie locale est dans guide/links.md ; la liste complète des liens communautaires est dans references/community-ecosystem.md.
• Implémentations communautaires de référence et pièges éprouvés : references/community-ecosystem.md, references/community-repo-deep-dive.md (analyse approfondie de 15 dépôts de développement), downloads/community-repos/ (copies complètes du code source, à générer d'abord avec scripts/download-community-repos.ps1). Les changements de mécanisme déjà confirmés par la communauté (ex. retrait de repository-plugin en 0811, double canal bundle vs cordis pur) et 20 pièges éprouvés (double copie de cordis, trio tsconfig, zstd multi-trame, junction Windows, etc.) se trouvent dans guide/plugin-dev-guide.md §7.

Validation (avant livraison)

• Validation du chargement : dsh --profile <nom> --dump-config pour vérifier que la ligne de patch est appliquée ; les logs de démarrage ne doivent pas contenir FAILED.
• Validation du comportement : test avec Web UI ou dsh --profile headless "…" ; les retours d'outil/texte visible par le modèle constituent le comportement ; toute modification doit être retestée.
• Pour les modifications dans le dépôt : vérification de type, tests du paquet cible, snapshot sans clé (le comportement visible par le modèle/produit doit avoir une transcription snapshot après assemblage), documentation bilingue par paire, Agent Note (pour tout changement non trivial dans la même PR).
• Paquet de plugin indépendant : pnpm pack puis installation dans un profil propre pour validation (incluant les artefacts de build dans lib/).

Maintenance de la base de connaissances (si nécessaire)

• Synchronisation des copies de documentation officielle : pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <checkout deepseek-harness>] — synchronise uniquement les fichiers suivis par git (les brouillons non suivis et les commits non poussés ne seront pas inclus) et rafraîchit references/official-docs/SNAPSHOT.md ; la date et le numéro de commit de « dernière vérification » dans le README doivent faire référence à SNAPSHOT.md, ne pas les modifier manuellement. Vérification des dérives : pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>.
• Rafraîchissement des ressources en ligne : pwsh -File ./scripts/download-sources.ps1 ; rafraîchissement des dépôts communautaires : pwsh -File ./scripts/download-community-repos.ps1 (les deux scripts sont idempotents, les résultats vont dans ./downloads/). Re-comptage des listes de sujets : pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <rép> -MaxPages 20 (API de recherche GitHub q=topic:dsh-plugin ; limite de pagination 1000 résultats ; le nombre de dédoublonnements et le total_count de l'API doivent être enregistrés dans sources.md §D.2).
• Installation/rafraîchissement d'une copie de la compétence agent : pwsh -File ./scripts/install-skill.ps1 -Target <répertoire de la compétence> (saute downloads/ et .github/, vérification octet par octet).
• Arbitrage des conflits : en cas de conflit avec la documentation officielle, references/official-docs/ (texte original du dépôt officiel) prévaut.

Limites

• Cette compétence est un « guide + contraintes + index de ressources », pas une exécution mécanique de scripts/listes ; les API précises sont référencées de manière générative.
• Ne modifiez pas les fichiers du dépôt harness en dehors de la base de connaissances, sauf demande explicite de l'utilisateur ; vendor/ et .agents/notes/archived/ sont en lecture seule.
• Avant de citer le contenu de downloads/, vérifiez qu'il existe (ce répertoire n'est pas dans git, il doit être généré par les scripts ci-dessus) ; les archives de awesome-dsh-plugins sont uniquement pour référence locale, ne doivent pas être redistribuées avec le dépôt (leur amont impose des contraintes d'usage interne, voir NOTICE.md).