DeepSeek Harness : atelier pratique : écrire une capacité remplaçable
Le chapitre précédent a introduit le concept des trois rôles ; dans celui-ci, nous allons le transformer en code en suivant le tutoriel officiel.
Nous allons implémenter une capacité appelée myCap : elle prend un morceau de texte en entrée et produit tout en majuscules. Elle est suffisamment petite pour être comprise d'un coup d'œil, tout en couvrant entièrement les trois paquets : Définition, Fournisseur et Consommateur.
Trois étapes : Définition du service (classe abstraite + type) → Fournisseur de service (sous-classe concrète) → Consommateur (defineTool).
Enfin, chargez le Fournisseur et le Consommateur ensemble dans cordis.yml.
Étape 1 : Écrire la définition du service
La définition du service déclare la capacité elle-même : le nom du service, la façon dont il est invoqué, et les types de requête et de résultat.
Il ne contient aucune logique d'implémentation, seulement une méthode abstraite et deux interfaces.
La classe abstraite MyCapService hérite de Service, viasuper(ctx, 'myCap')s'enregistre comme service nommé.
La fusion de déclarations declare module donne ses types à ctx.myCap ; cette technique a été abordée dans la partie 14.
Exemple
import { Service, type Context } from '@deepseek-ai/cordis'
// Fusion de déclarations : faire en sorte que ctx.myCap ait des indications de type en TypeScript
declare module '@deepseek-ai/cordis' {
interface Context {
myCap: MyCapService
}
}
// Classe abstraite : le paquet Definition ne déclare que des contrats, pas des implémentations.
export abstract class MyCapService extends Service {
constructor(ctx: Context) {
super(ctx, 'myCap') // S'enregistrer comme service nommé ctx.myCap
}
/** Exécuter la capacité. */
abstract execute(request: MyCapRequest): Promise<MyCapResult>
}
// Type de requête : l'appelant doit fournir une entrée
export interface MyCapRequest {
input: string
}
// Type de résultat : la capacité renvoie une sortie
export interface MyCapResult {
output: string
}
abstract execute est la seule méthode abstraite, et le fournisseur doit l’implémenter.
MyCapRequest possède un champ input, et MyCapResult possède un champ output.
Les types de requête et de résultat appartiennent au package Definition, et le fournisseur et le consommateur les importent depuis celui-ci.
Étape 2 : écrire le fournisseur de service
Le fournisseur de service hérite de la classe abstraite et implémente le comportement réel.
MyCapLocal convertit input en majuscules et le renvoie.
export const name déclare le nom du plugin ; dans apply, enregistrez l’implémentation du service via ctx.plugin(MyCapLocal).
Exemple
import type { Context } from '@deepseek-ai/cordis'
import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'
// Classe d'implémentation : ne dépend que du package Definition
class MyCapLocal extends MyCapService {
async execute(request: MyCapRequest): Promise<MyCapResult> {
// Comportement du fournisseur local.
return { output: request.input.toUpperCase() }
}
}
export const name = 'my-cap-local'
export function apply(ctx: Context) {
// Charge la classe d'implémentation en tant que plugin, l'enregistre comme service réel pour ctx.myCap
ctx.plugin(MyCapLocal)
}
Le fournisseur ne dépend que des classes abstraites et des types du package Definition.
Il ne se soucie pas de la façon dont le modèle l'appelle, ni de l'apparence de l'outil.
Si vous souhaitez passer à une autre implémentation plus tard, par exemple une qui s'exécute sur un serveur distant, il vous suffit d'écrire une autre sous-classe de fournisseur.
Étape 3 : écrire le côté Consumer
Le Consumer encapsule la capacité dans un outil que le modèle peut appeler.
La déclaration inject dépend de tools et myCap, garantissant que apply ne s'exécute qu'après que les deux services sont prêts.
defineTool déclare le schéma de l'outil ; une fois que le modèle voit l'outil my_cap, il passera les paramètres conformément à parameters.
Dans execute, appelez ctx.myCap.execute et renvoyez le résultat comme sortie de l'outil.
Exemple
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'tool-my-cap'
// Déclaration de dépendance : tools fournit l'entrée d'enregistrement, myCap fournit l'implémentation du service.
export const inject = ['tools', 'myCap']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'my_cap', // Nom de l'outil pour le modèle
description: 'Exécuter ma capacité.',
// Schéma des paramètres : le modèle génère les paramètres en fonction de celui-ci
parameters: {
input: { type: 'string', required: true },
},
// Schéma de sortie et méthode de rendu
output: {
schema: { type: 'string' },
render: (_args, value) => [{ type: 'text', text: value }],
},
// Exécution réelle : appeler le service de capacité
async execute(args) {
const result = await ctx.myCap.execute({ input: args.input })
return result.output
},
}))
}
Le modèle ne connaît pas ctx.myCap directement ; il ne connaît que l’outil my_cap.
Le Consumer est le pont entre les deux et est également responsable du rendu du résultat en texte visible par le modèle.
La structure à trois rôles de myCap et le flux de données
Lorsque les trois paquets sont assemblés, les données circulent depuis le modèle, à travers Consumer et Definition, et arrivent dans Provider.
Le modèle appelle d’abord l’outil my_cap ; cette étape ne se produit qu’au niveau de la couche Consumer.
Consumer transmet le parameterPackageCheng MyCapRequest,remet à ctx.myCap.execute(request)。
Definition délègue l’appel à l’implémentation Provider actuellement chargée.
Après que le Provider a calculé le résultat, il renvoie MyCapResult au Consumer en suivant le chemin d’origine.
Le Consumer effectue le rendu de la sortie en texte et la transmet au modèle comme résultat de l’outil.
Tout au long de la chaîne complète, lorsque le Provider est remplacé, ni le Consumer ni le modèle ne s’en aperçoivent.
Combinaison dans cordis.yml
Les trois paquets ne sont que des parties une fois écrits ; vous devez également charger Provider et Consumer ensemble dans cordis.yml.
Charger le Provider donne à ctx.myCap une implémentation ; charger le Consumer donne au modèle l'outil my_cap.
Exemple
# Charger d'abord le Provider pour que ctx.myCap ait une implémentation.
- name: '@deepseek-ai/dsh-my-cap-local'
Rechargez le Consumer pour que le modèle puisse utiliser l'outil my_cap
- name: '@deepseek-ai/dsh-tool-my-cap'
Quant à l'ordre de chargement, Cordis trie automatiquement par dépendance, donc peu importe que Provider ou Consumer vienne en premier.
Pour passer à un autre Provider, ne changez que la première ligne ; le Consumer reste inchangé.
Points de conception
La documentation officielle propose trois principes de conception ; il est préférable de les garder à l'esprit avant d'écrire une capacité.
Premièrement, ne pas découper de manière préventive.
Ne placez les rôles dans des paquets séparés que lorsqu'ils doivent évoluer indépendamment.
Les plugins d'outils simples n'ont pas besoin d'être scindés ; le fait qu'un seul paquet assume plusieurs rôles est parfaitement valide.
Deuxièmement, la Définition de service comporte des types Request/Result.
Provider et Consumer ne dépendent que du paquet Definition, donc les types request et result doivent être définis par Definition.
Troisièmement, l'explicite est préférable à l'implicite.
Les implémentations doivent gérer les valeurs par défaut au moyen d'une étape explicite resolve(request), plutôt que de cacher un ?? default à l'intérieur de run().
La couture Bash en est un exemple : workdir et timeoutMs de ShellExecRequest sont facultatifs ; la couche outil appelle d'abord ctx.shell.resolve(request) pour obtenir un ShellExecSpec avec tous les champs obligatoires, puis le passe à run().
Ne remplissez pas discrètement les valeurs par défaut dans run() ; appelez resolve d'abord, puis exécutez—c'est seulement alors que les frontières sont claires.
Résumé et auto-test
En une phrase : écrire une capacité remplaçable = classe abstraite Definition + sous-classe Provider + outil Consumer, plus un cordis.yml.
Question d'auto-test 1 : Dans quel paquet doivent être définis MyCapRequest et MyCapResult ?
Auto-test 2 : Existe-t-il une dépendance entre Provider et Consumer ?
Auto-test 3 : Pourquoi le découpage préventif n'est-il pas recommandé pour les plugins d'outils simples ?
autres extensions