Que fait Développement de plugins dsh ?
Développez des plugins pour DeepSeek Harness
(dsh), un framework agent basé sur Cordis. Les plugins sont des modules TypeScript exportant
apply(ctx: Context), composés via cordis.yml.
Référence rapide
Structure d'un plugin
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-plugin'
export function apply(ctx: Context) { /* enregistrer les capacités */ }
Trois formes : fonction (par défaut), objet ({ name, inject, apply }), classe
(extends Service — à utiliser uniquement lorsque vous fournissez un service à d'autres plugins).
Dépendances : export const inject = ['tools', 'llm'] — le framework maintient le plugin
en état PENDING jusqu'à ce que tous les services injectés soient prêts.
Nettoyage automatique : Tout ce qui est enregistré via ctx est un effet — le déchargement
nettoie automatiquement. Pour les ressources personnalisées (minuteries, connexions), enveloppez-les dans
ctx.effect(() => { ... return () => cleanup }).
Plugins enfants : const fiber = ctx.plugin(childPlugin) — les enfants héritent du
contexte parent ; await fiber.dispose() décharge récursivement.
États des fibres
PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
↘ FAILED
PENDING → dépendance de service manquante. FAILED → apply a levé une exception ou la validation
de configuration a échoué. La disparition d'un service à l'exécution supprime automatiquement ses dépendants.
Outils
import { defineTool } from '@deepseek-ai/dsh-tools'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'saluer', description: '...',
parameters: { name: { type: 'string', required: true } },
output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
async execute(args) { return `Bonjour, ${args.name}!` },
}))
}
defineTool convertit les paramètres en JSON Schema, valide les arguments, et se désenregistre automatiquement lors du déchargement.
Voir references/basic/tool.md pour les détails.
Configuration
import Schema from '@deepseek-ai/schemastery'
export interface Config { greeting: string; maxRetries: number }
export const Config: Schema<Config> = Schema.object({
greeting: Schema.string().default('Bonjour'),
maxRetries: Schema.number().default(3),
})
export function apply(ctx: Context, config: Config) { /* configuration validée */ }
Vous devez exporter À LA FOIS interface Config ET const Config: Schema<Config>.
Configuration invalide → état FAILED avec une erreur claire. Utilisez !!js dans YAML pour les valeurs
dynamiques : config: { apiKey: !!js process.env.API_KEY }.
Voir references/basic/config.md.
Services
Fournir : class extends Service { constructor(ctx) { super(ctx, 'nom') } }
declare module '@deepseek-ai/cordis' { interface Context { nom: NomService } }
Consommer : export const inject = ['nom'] → ctx.nom.methode().
Optionnel : ctx.get('nom') → renvoie undefined lorsque absent.
Isolation des services : group: true + isolate: { shell: true } donne à chaque groupe
sa propre instance de fournisseur. Voir references/framework/service.md.
Événements
| Mode | Appel | Utilisation |
|---|---|---|
emit | ctx.emit(n, ...args) | Diffusion synchrone, ignore les retours |
parallel | await ctx.parallel(n, ...args) | Écouteurs concurrents |
serial | await ctx.serial(n, ...args) | Séquentiel, premier non-nul gagne |
bail | ctx.bail(n, ...args) | Série synchrone |
waterfall | ctx.waterfall(n, ...args, next) | Chaîne middleware |
Les écouteurs waterfall doivent appeler next() sauf s'ils court-circuitent intentionnellement.
Événements clés de dsh : agent/step, tools/result, session/event.
Voir references/framework/events.md.
Adaptateurs LLM
class MonAdaptateur extends LlmAdapter {
async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
// Convertir → API du fournisseur → yield StreamChunk
}
}
ctx.llm.registerAdapter(['mon-fournisseur'], adaptateur)
Ordre StreamChunk par bloc : block-start → text-delta/tool-call-delta →
block-end → usage → finish. Levez LlmError avec des codes stables.
Voir references/practice/llm-adapter.md.
Conception de capacité en trois couches
Définition (classe abstraite Service) → Fournisseur (implémente) → Consommateur (outil)
Les trois partagent le même nom de service via inject. Ne séparez en packages
distincts que lorsque les rôles nécessitent une évolution indépendante.
Voir references/practice/index.md.
cordis.yml / Bundles
Développement local : --patch ./cordis.patch.yml
- insert:
- id: mon-plugin
name: '/chemin/absolu/vers/src/mon-plugin.ts'
config: { greeting: 'Salut' }
Distribution : package npm avec manifeste dsh.bundle + cordis.patch.yml.
Installation : dsh plugin --profile demo add ./hello-plugin.
Ordre des couches : bundles du profil → patch du profil → patch de l'utilisateur → surcouches --patch.
Les couches ultérieures gagnent par ligne (pas de fusion profonde).
Voir references/basic/publish.md.
HMR
Chargez @deepseek-ai/cordis-plugin-hmr + @deepseek-ai/cordis-plugin-logger-console
@deepseek-ai/cordis-plugin-timerpour recharger automatiquement à la sauvegarde de fichiers.
Diagnostiquer l'état PENDING
import { FiberState, type Context } from '@deepseek-ai/cordis'
for (const fiber of ctx.registry.values().flatMap(r => r.fibers))
if (fiber.state === FiberState.PENDING)
console.log(`${fiber.name} est PENDING`)
Documentation de référence
Guides détaillés dans le répertoire references/ :
| Chemin | Contenu |
|---|---|
references/basic/ | Premier plugin, outils, configuration, publication |
references/framework/ | Cycle de vie, services, événements |
references/practice/ | Conception en trois couches, adaptateurs LLM |
references/cordis-tutorial/ | Tutoriel pas à pas du framework Cordis |