DeepSeek Harness Système d’événements : emit / bail / serial / waterfall
Comment les plugins communiquent-ils de manière faiblement couplée ? Les événements sont le mécanisme de communication central de Cordis.
Harness utilise largement les événements pour mettre en œuvre des points d'extension extensibles. Cet article explique clairement les cinq modes de distribution.
Utilisation de base
Les événements se divisent en deux volets : l'écoute et le déclenchement.
Exemple
ctx.on('event-name', (payload) => {
// Gérer les événements
})
// Déclencher un événement : diffuser à tous les écouteurs
ctx.emit('event-name', payload)
Les écouteurs enregistrés via `ctx.on` sont automatiquement supprimés lorsque le plugin est déchargé.
Cinq modes de distribution
Cordis fournit plusieurs modes de distribution, adaptés à différents contrats d'interaction.
| Mode | Méthode de distribution | S'il faut attendre | Séquence | S'il y a une valeur de retour | Scénarios typiques |
|---|---|---|---|---|---|
| emitDiffusion | ctx.emit | non | Dans l'ordre d'enregistrement | non | Type de notification : tous les écouteurs observent |
| bailCourt-circuit | ctx.bail | non | Dans l'ordre d'enregistrement | Oui | Type de décision : la première valeur de retour valide l'emporte |
| serialSéquence | ctx.serial | Oui | Dans l'ordre d'enregistrement | Oui | Initialisation par phases : exécuter dans l'ordre et attendre |
| waterfallPipeline | ctx.waterfall | non | Dans l'ordre d'enregistrement | Oui | Chaîne de traitement : envelopper les valeurs de retour en aval couche par couche |
| parallelParallélisme | ctx.parallel | Oui | Tout en parallèle | non | Fan-out : plusieurs écouteurs traitent en parallèle |
Chaque événement possède exactement un mode de distribution et ne peut être distribué que par la méthode correspondante.
La documentation officielle de démarrage marque `waterfall` comme « not await » ; toutefois, comme les écouteurs sont généralement des fonctions async, les exemples de tutoriel écrivent couramment `await ctx.waterfall(...)` pour attendre le résultat final de toute la chaîne de traitement. Rappelez-vous simplement cette différence – les deux styles sont acceptables.
emit : diffusion
Tous les écouteurs s'exécutent de manière synchrone et les valeurs de retour sont ignorées.
Exemple
ctx.emit('my-plugin/ready', { id: 'example-worker-1' })
// Écouteur : reçoit le message ready, affiche le journal
ctx.on('my-plugin/ready', ({ id }) => {
console.log(`${id} est prêt`)
})
bail : court-circuit
Les écouteurs s'exécutent dans l'ordre ; la première valeur de retour qui n'est ni `null`, ni `false`, ni `undefined` devient le résultat final.
Exemple
const result = ctx.bail('some-check', input)
// Écouteur : si la condition d'interception est remplie, renvoie 'blocked', sinon continue
ctx.on('some-check', (input) => {
if (shouldBlock(input)) return 'blocked'
// Renvoyer null / false / undefined pour indiquer « je n'ai pas d'objection », en laissant les écouteurs suivants continuer.
})
serial : exécuter séquentiellement
Les écouteurs s'exécutent un par un dans l'ordre d'enregistrement, en attendant les résultats asynchrones.
La première valeur de retour qui n'est ni null, ni false, ni undefined met fin à l'exécution ultérieure.
Exemple
await ctx.serial('setup-phase', context)
waterfall : pipeline
Chaque écouteur peut envelopper la valeur de retour en aval, formant une chaîne de traitement.
Les écouteurs reçoivent (...args, next) ; appeler next() exécute les écouteurs en aval, et la valeur de retour en aval est renvoyée à la couche d'enveloppement actuelle via next().
Exemple
const output = await ctx.waterfall('my-plugin/transform', input, async () => input)
// Côté écouteur : doit appeler next(), après avoir obtenu le résultat en aval, le traiter une fois puis retourner.
ctx.on('my-plugin/transform', async (_input, next) => {
const downstream = await next()
return downstream.trim()
})
Les écouteurs Waterfall doivent appeler next(). Ne pas appeler next() court-circuite tout le pipeline ; c'est une conception intentionnelle pour implémenter une logique d'interception ou de passerelle.
Les écouteurs Strategy, lorsqu'ils détiennent l'autorité de décision, peuvent retourner directement sans appeler next(), bloquant ainsi toute la chaîne.
Les écouteurs qui ne font qu'annoter ou observer doivent déléguer en aval.
Événements avec sécurité de type
Utilisez la fusion de déclarations TypeScript pour assurer la sécurité de type des événements.
Exemple
import '@deepseek-ai/cordis'
// Fusion de déclarations : enregistrer le nom et la signature de l'événement
declare module '@deepseek-ai/cordis' {
interface Events {
'my-plugin/ready': (payload: { id: string }) => void
'my-plugin/check': (input: string) => boolean | undefined
'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
}
}
// Après cela, ctx.on('my-plugin/ready', ...) et ctx.emit('my-plugin/ready', ...)
// les arguments seront automatiquement inférés ; une faute d'orthographe dans les noms d'événements ou les types de paramètres provoquera des erreurs de compilation
Événements Cordis et enregistrements de session
Les événements Cordis de Harness suivent la convention de nommage namespace/action, par ex., agent/step, agent/request, agent/request-error, tools/result et session/event.
Notez la distinction entre deux types d'événements :
| Événements | De quoi s'agit-il | Comment observer |
|---|---|---|
| agent/step, tools/result, etc. | Événements Cordis, distribués en temps réel | Directement ctx.on('tools/result', ...) |
| turn/*、step/*、tool/call、tool/result、compaction/* | Types d'événements de session persistés | Écouter session/event, vérifier event.type |
turn/*, step/*, tool/call, tool/result et compaction/* sont des types d'événements de session persistés, et non les événements Cordis du même nom.
Pour les observer, écouter session/event et vérifier event.type.
Exemple pratique : plugin de journalisation
La documentation officielle utilise le plugin suivant pour journaliser les appels d'outils et les résultats d'outils, en écoutant l'événement Cordis `tools/result`.
Exemple
import type { Context } from '@deepseek-ai/cordis'
import '@deepseek-ai/dsh-tools'
export const name = 'tool-logger'
export function apply(ctx: Context) {
// Écouter l'événement tools/result : déclenché à chaque fois qu'une exécution d'outil se termine.
ctx.on('tools/result', (exec, result) => {
// Afficher le nom de l'outil et les arguments
console.log(`[tool] ${exec.name}(${JSON.stringify(exec.arguments)})`)
// Concaténer les blocs de texte dans le contenu du résultat, et n'afficher que les 100 premiers caractères.
const text = result.content
.map(block => block.type === 'text' ? block.text : '')
.join('')
console.log(`[résultat de l'outil] ${text.slice(0, 100)}`)
})
}
Ce plugin affiche le nom de l'outil, les paramètres et un résumé du résultat dans le terminal après chaque appel d'outil par l'Agent.
Les écouteurs sont enregistrés via `ctx.on` et sont automatiquement supprimés lorsque le plugin est déchargé.
Auto-test du résumé
Les cinq modes de dispatch couvrent cinq types de contrats : broadcast, decision, sequential, pipeline et parallel ; waterfall doit appeler next() ; la fusion de modules declare fournit des garanties de type pour les noms et paramètres d'événements.
Testez-vous :
- Quelle méthode déclenche chacun des cinq modes de dispatch ? Lesquels ont des valeurs de retour ?
- Que se passe-t-il si un listener waterfall n'appelle pas next() ? Est-ce un bug ou un comportement intentionnel ?
- Pour les événements de session persistants comme turn/start, quel événement faut-il écouter, et quel champ faut-il vérifier ?