Les trois rôles d'une capacité DeepSeek Harness : Définition / Fournisseur / Consommateur

La documentation officielle mentionne souvent la Définition de service, le Fournisseur de service et le Consommateur. Ensemble, ils forment la couture d'une capacité—c'est-à-dire l'interface de capacité remplaçable.

Ce chapitre clarifiera ce qu'est chacun des trois rôles, et pourquoi une capacité est divisée en trois rôles.

La capacité complète constitue sa couture ; aucun rôle isolé n'est une couture.


Quel est chacun des trois rôles ?

Lorsqu'une capacité est suffisamment générique et doit prendre en charge des fournisseurs remplaçables (par exemple, l'exécution de Bash), le harnais divise la capacité en trois rôles.

RôleDe quoi est-il responsable ?Prenons Bash comme exemple
Définition de service Interface + TypesDéfinir le service Cordis, ainsi que les types Request et Resultdsh-shell (enregistré sous ctx.shell)
Fournisseur de service ImplémentationImplémenter réellement cette capacité, généralement en ciblant un environnement d'exécution spécifiquedsh-bash-local (exécution locale)
Consommateur Outils orientés modèleExposer la capacité comme un outil que les modèles peuvent appelerdsh-tool-bash (outil bash)

La Définition de service déclare uniquement « quelles capacités existent et à quoi elles ressemblent », sans se soucier de la manière dont elles sont implémentées.

Le Fournisseur de service hérite de la classe abstraite de la Définition et remplit le comportement concret.

Le Consommateur fait face au modèle, en encapsulant la capacité dans des schémas d'outils afin que le modèle puisse l'appeler.

Les trois rôles peuvent être placés dans le même paquet, ou répartis dans différents paquets.

Il n'y a qu'un seul critère : si ces rôles doivent évoluer ou être remplacés indépendamment.


Comprendre les trois rôles de couture avec un seul diagramme

Les trois rôles dépendent de la Définition, tandis que le Fournisseur et le Consommateur ne dépendent pas l'un de l'autre.

能力 Seam 三角色关系图

L'encadré en pointillés dans le diagramme est la capacité complète, c'est-à-dire la couture.

La Définition se trouve au milieu ; le Fournisseur et le Consommateur ne dépendent que d'elle.

Le Fournisseur hérite de l'implémentation de la Définition, le Consommateur, viainject: ['shell']en dépend.

Il n'y a aucune dépendance entre le Fournisseur et le Consommateur.

Par conséquent, lors du remplacement du Fournisseur, ni la Définition ni le Consommateur n'a besoin d'une seule ligne de changement.


Prenons Bash comme exemple : les trois rôles de ctx.shell

L'exécution de Bash est la jointure la plus typique dans dsh ; chacun des trois rôles a son propre paquet.

La Définition de service est le paquet dsh-shell, enregistré en tant que service ctx.shell.

Il définit le type de requête pour BashShellExecRequestet le type de résultatShellRunResult。

Le Fournisseur de service est dsh-bash-local, qui exécute les commandes sur l'ordinateur local.

La même Définition possède d'autres Fournisseurs, tels que dsh-bash-sandbox qui s'exécute dans un bac à sable, et dsh-pwsh-local qui exécute PowerShell.

Le Consommateur est dsh-tool-bash, qui encapsule la capacité dans un outil bash appelable par le modèle.

tool-bash, via inject, déclare la dépendance ctx.shell, puis dans execute appelle ctx.shell.run(...).

Le document de référence officiel « Capability Seam and Core Services » utilise un tableau pour maintenir l'attribution des trois rôles de ctx.shell.

Clé ctxRôlePaquet affilié (Définition)Implémentation (Fournisseur)Consommateur direct (Consommateur)
ctx.shellseamshellbash-local / bash-sandbox / pwsh-localtool-bash / tool-pwsh / hooks-claude-code / hooks-codex

Les consommateurs incluent également deux plugins de pont de hooks : hooks-claude-code et hooks-codex.

Comme tool-bash, ils ne reconnaissent que l'interface ctx.shell et ne se soucient pas de l'exécuteur qui se trouve derrière.

Dans la couture Bash, la requête destinée au modèle ShellExecRequest (workdir, timeoutMs facultatif) est séparée de la spécification entièrement résolue ShellExecSpec (champs requis) réellement utilisée par l’exécuteur.

La couche outil appelle ctx.shell.resolve(request) entre les deux—c’est « l’explicite est préférable à l’implicite aux frontières de paquets ».


Pourquoi le diviser en trois rôles ?

Le premier avantage de cette séparation est que les fournisseurs sont remplaçables.

La même définition de service peut avoir plusieurs fournisseurs, sélectionnés via cordis.yml.

Exemple

# Chemin du fichier : cordis.yml
# Exécution locale
- name
: '@deepseek-ai/dsh-bash-local'

# Pour changer de fournisseur, remplacez simplement la ligne ci-dessus.
# Remplacez par la ligne ci-dessous pour passer à l’exécuteur sandbox :
# - name: '@deepseek-ai/dsh-bash-sandbox'

Lors du changement de fournisseur, la définition de service et le consommateur restent inchangés.

Le deuxième avantage de cette séparation est que les trois rôles peuvent évoluer indépendamment.

RôleLa liberté d'évoluer indépendamment
Définition de serviceUne fois que les appelants commencent à dépendre de ses conventions, elle change rarement.
Fournisseur de servicePeut optimiser indépendamment les performances et la sécurité
ConsommateurPeut ajuster la façon dont la capacité est présentée au modèle

Le troisième avantage de la séparation est le découplage des dépendances.

Le fournisseur de service dépend de la définition de service.

Le consommateur dépend de la définition de service.

Fournisseur de service et consommateurMutuellement indépendants。

Relations de dépendanceSi cela tient
Fournisseur → DéfinitionOui
Consommateur → DéfinitionOui
Fournisseur → Consommateurnon
Consommateur → Fournisseurnon

Analyse pratique : trouvez les trois rôles du seam que vous utilisez.

Le document de référence officiel « Capability Seam and Core Services » maintient une liste complète des services.

Choisissez un seam que vous connaissez, par exemple ctx.fs ou ctx.llm, et clarifiez-le en trois étapes.

Étape 1 : trouvez son package de Définition — c'est-à-dire la colonne « package d'appartenance » du tableau.

Étape 2 : trouvez son package de Fournisseur — c'est-à-dire la colonne « implémentation » du tableau.

Étape 3 : trouvez son Consommateur — c'est-à-dire la colonne « consommateur direct » du tableau.

Par exemple, pour ctx.llm, la Définition est le package llm, l'Implémentation est llm-deepseek et llm-pi-ai, et le consommateur direct est agent-loop et compaction-basic.

Un autre exemple est ctx.fs : la Définition est le package fs, les implémentations sont fs-local, fs-sandbox et fs-e2b, et le consommateur direct est tool-fs.

Une fois que vous êtes habitué à cette façon de penser, vous pouvez dire d’un coup d’œil à quel rôle appartient n’importe quel service intégré.


Résumé et auto-test

Résumé en une phrase : une capacité est divisée en trois rôles — Définition (interface et types), Fournisseur (implémentation) et Consommateur (outils destinés au modèle) — et ensemble, ils forment la couture.

Question d’auto-évaluation 1 : à quels paquets correspondent respectivement la Définition, le Fournisseur et le Consommateur de la capacité Bash ?

Question d’auto-évaluation 2 : lors du remplacement du Fournisseur de Bash, quels paquets peuvent rester inchangés ?

Question d’auto-évaluation 3 : pourquoi dit-on qu’« aucun rôle pris isolément n’est une couture » ?

autres extensions