Pipeline d'exécution des outils et porte de permissions de DeepSeek Harness

Dans les chapitres précédents, nous avons appris à utiliser defineTool pour enregistrer des outils, et nous avons également appris à utiliser le système d'événements pour écouter divers points d'extension.

Mais maintenant, une question se pose : après que le modèle émet un appel d'outil, jusqu'à ce que l'outil s'exécute réellement et que le résultat revienne au modèle, quelles étapes se produisent réellement entre les deux ?

Dans ce chapitre, nous expliquerons en détail le « pipeline d’exécution des outils » de dsh, et comment implémenter des portes de permission avec des plugins de hook.

En une phrase : un appel d’outil passe par plusieurs étapes dans un ordre fixe, chaque étape est responsable d’une catégorie de politique, et les plugins de hook peuvent autoriser, refuser ou demander au sein de celles-ci.


L’ordre global du pipeline

L’exécution d’un outil n’est pas aussi simple qu’un « appel de fonction » ; c’est un pipeline avec un ordre fixe.

La documentation officielle résume l’ordre ainsi :tools/pre-execute → Monotonic guard → tools/execute → tools/post-execute → finalizeContent → tools/result。

Parmi eux, les trois premiers waterfalls peuvent réécrire un appel une fois, tandis que finalizeContent et tools/result, contrôlés par la définition elle-même, s’exécutent après eux.

工具执行流水线流程图

Tout d’abord, examinons deux concepts facilement confondus :

waterfall(événement Waterfall) est un modèle de dispatch d’événements ; les écouteurs peuventnext()déléguer l’autorité de décision à la suite, ou renvoyer directement une décision pour court-circuiter.

Monotonic guard(garde monotone) est une dernière ligne de défense qui n’autorise que le resserrement, jamais la révocation.

Ci-dessous, nous expliquons chaque étape une par une.


tools/pre-execute : une couche de politique réordonnable

tools/pre-executeC'est la première cascade du pipeline, responsable de porter des politiques réorganisables telles que « hooks, permissions, sandbox ».

La raison pour laquelle il est appelé « réorganisable » est que les listeners peuventnext()transmettre l'autorité de décision au listener suivant, et l'ordre de plusieurs plugins de politique peut être ajusté dans la configuration.

Cette cascade renvoie une décision typéePreToolDecisionIl y a trois valeurs possibles :

DécisionSignificationComportement ultérieur
{ kind: 'allow' }Autoriser cet appelContinuer avec le garde monotone et les étapes suivantes.
{ kind: 'deny'; reason: string }Rejeter cet appelIl est matérialisé en un résultat d'erreur, et le corps de l'outil est ignoré.
{ kind: 'ask'; reason?: string }Demander à l'utilisateurUniquement lorsque le service d'approbation renvoieallowed-onceEnsuite, continuer, sinon rejeter.

RemarqueaskBranche : elle se déclencheractx.approvalcomme une requête ponctuelle ; cette partie sera laissée pour le prochain article.

Les paramètres ne peuvent pas être modifiés, car l'historique, l'audit, l'UI et l'exécution doivent rester cohérents.

Quand utiliser pre-execute ?

Lorsqu'une politique a besoin de l'une des trois actions — « allow, deny ou ask » — et que les politiques doivent pouvoir être ordonnées librement, utilisez-le.

Les plugins tels que sandbox, permission et plan-mode utilisent tous ce point d'extension.


Garde monotone : un rejet final irrévocable.

L'inconvénient de waterfall est que les écouteurs enregistrés plus tard peuvent renverser les décisions des écouteurs précédents.

Lorsqu'un invariant exige « un refus final, et que personne ne puisse le révoquer », utilisezctx.tools.guard()。

Le type de garde estToolGuardIl n'a délibérément aucun résultat allow : renvoyer une chaîne indique un rejet, renvoyerundefinedIndique le maintien du statu quo.

// ToolGuard:感知作用域的最终预分派策略
type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined

Comme la garde n'a aucun résultat allow, l'ordre des écouteurs ne peut jamais retransformer un rejet en approbation.

Voici ce que signifie « monotone » : uniquement diminuer, jamais augmenter ; uniquement révoquer des permissions, jamais les accorder.

Principes pratiques: Placez les politiques réorganisables ici.tools/pre-execute; les invariants qui doivent être « définitifs et irrévocables » vont dansctx.tools.guard()。


tools/execute et tools/post-execute

tools/executeIl est responsable de « around dispatch », c'est-à-dire d'encapsuler l'invocation réelle du corps de l'outil.

Timeout, réessai et collecte de métriques sont tous gérés à cette couche ; ce qu'il encapsule est le cycle de vie réel du dispatch.

La vue qu'il obtient estToolDispatchExecution: seule cette vue peut remplacer le requisexec.signal, utilisé pour imposer une échéance.

La règle de remplacement est : il peut être remplacé, mais pas supprimé ; le registre re-fusionnera le signal de l'appelant avant d'invoquer le corps de l'outil.

tools/post-executeIl est responsable de vérifier ou de réécrire après l'exécution de l'outil et avant la normalisation du résultat ; il retournePostToolDecision:

DécisionSignification
{ kind: 'accept'; content? }Accepter le résultat, peut remplacer le contenu affiché (en conservant la valeur canonique et les métadonnées).
{ kind: 'accept'; value }Accepter le résultat, peut remplacer la valeur canonique (revalidera et recalculera le contenu).
{ kind: 'block'; feedback }Bloquez le résultat, en transformant un retour correctif en résultat d'erreur.

Le remplacement de contenu est une politique d'affichage, pas une politique de confidentialité.

Pour masquer une valeur programmatique, vous devez remplacer cette valeur ou bloquer le résultat.


finalizeContent et tools/result

finalizeContentC'est un callback appartenant au ToolDefinition lui-même, et le registre l'appelle exactement une fois.

C'est le "dernier invariant portant uniquement sur le contenu" : exécuté de manière synchrone, il n'autorise que les corrections finales au niveau du contenu.

Après cela, le registre matérialise et fige le résultat accepté, puis déclenchetools/result。

tools/resultC'est une notification synchrone, utilisée pour l'observation.Résultat faisant autorité, figé et immuable。

Les observateurs ne peuvent pas transformer le résultat, et les défaillances des observateurs sont isolées, sans affecter le flux principal.

Utilisez-le lorsque vous avez besoin de "audit, métriques, capture du résultat final" ; utilisez-le uniquement lorsque vous devez "transformer le résultat ou y attacher du contexte".tools/post-execute。

Moyen mnémotechnique pour la sélection : pre-execute décide "si cela peut être fait", execute décide "comment le faire", post-execute décide "comment le résultat est présenté", result n'est responsable que d'"un coup d'œil au résultat final".


Exemple pratique : écrire un plugin de contrôle des permissions.

La documentation officielle utilise « barrière de permissions » comme exemple pour montrer comment les plugins de hook utilisenttools/pre-execute。

Les plugins de hook sont des plugins Cordis ordinaires et ne nécessitent pas de protocole externe.

Exemple

// Chemin de fichier : my-plugins/permission-gate/src/index.ts
// Un plugin de barrière de permissions basé sur tools/pre-execute.
// Il renvoie une décision typée : refuser si sur liste noire, sinon appeler next() pour déléguer.
import type { Context } from '@deepseek-ai/cordis'
import type { PreToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'

// Liste noire : outils dont l'écriture directe dans le système de fichiers est interdite dans le projet d'exemple.
// Ici, nous utilisons un ensemble simple à des fins de démonstration ; dans de vrais projets, vous pouvez interroger une base de données ou consulter un service d'approbation.
const DENY_TOOLS = new Set(['fs_write', 'fs_edit'])

// Fonction de décision de politique : renvoie si cet appel est autorisé.
// exec transporte une identité d'appel immuable (callId, name, arguments, agent, token, signal).
async function isAllowed(exec: ToolExecution): Promise<booléen> {
  if (DENY_TOOLS.has(exec.name)) return false
  // Exemple supplémentaire : dans la démo d'exemple, la modification des fichiers .env est interdite (les arguments sont gelés avant d'entrer dans la politique).
  const raw = exec.arguments as { path?: string }
  if (typeof raw.path === 'string' && raw.path.includes('.env')) return false
  return true
}

export const name = 'permission-gate'

export function apply(ctx: Context) {
  // tools/pre-execute fonctionne en cascade : les écouteurs peuvent renvoyer une décision, ou appeler next() pour déléguer.
  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
    if (!(await isAllowed(exec))) {
      // Renvoyer deny terminera immédiatement cet appel ; les écouteurs suivants ne seront pas exécutés.
      return { kind: 'deny', reason: 'Refusé par la politique : cet outil n'est pas autorisé dans l'espace de travail d'exemple.' }
    }
    // transmettre : confier la décision aux écouteurs suivants du pipeline.
    return next()
  })
}

Après le chargement de ce plugin, chaque appel d'outil effectué par le modèle passera d'abord par lui.

Un outil qui figure sur la liste noire recevra un résultat d'erreur avec une raison, et le corps de l'outil est ignoré.

Comme il renvoie une décision typée, les autres plugins de stratégie peuvent encore continuer à participer à la décision après lui.


Exemple pratique : ajouter un timeout avec tools/execute

Le timeout relève de la problématique « around dispatch » et doit être encapsulé avectools/execute, plutôt que d'être écrit dans le corps de l'outil.

Exemple

// Chemin de fichier : my-plugins/tool-guard/src/index.ts
// Utilisez tools/execute pour envelopper le cycle de vie réel de dispatch : ajoutez un timeout de 30 secondes à chaque appel d'outil.
import type { Context } from '@deepseek-ai/cordis'

export const name = 'tool-guard'

export function apply(ctx: Context) {
  // tools/execute est un waterfall : il faut appeler next() pour exécuter le corps réel de l'outil.
  ctx.on('tools/execute', async (exec, next) => {
    // Remarque : seule la vue tools/execute peut remplacer exec.signal.
    // Ici, le signal de l'appelant est combiné à un délai de 30 secondes, remplaçant le signal d'origine.
    const originalSignal = exec.signal
    const deadline = AbortSignal.timeout(30_000)
    exec.signal = AbortSignal.any([originalSignal, deadline])
    try {
      // Déléguer à l'exécution réelle de l'outil execute() ; le délai d'attente ou l'annulation de l'appelant déclenchera l'abandon.
      return await next()
    } finally {
      // Restaurer le signal d'origine après utilisation pour éviter de polluer les appels suivants.
      exec.signal = originalSignal
    }
  })
}

Règle : exec.signal peut être remplacé, mais ne peut pas être supprimé.

Le registre re-fusionnera le signal de l'appelant avant d'invoquer le corps de la fonction de l'outil, il est donc sûr que la couche d'encapsulation remplace le signal.


Exemple pratique : rejet monotone avec ctx.tools.guard()

Lorsqu'un invariant exige « refus final, irrévocable », utilisezctx.tools.guard()。

Notez que le type de retour du guard eststring | undefined, il n'existe pas de branche d'autorisation.

Exemple

// Chemin du fichier : my-plugins/invariant-guard/src/index.ts
// Un rejet final irrévocable : interdit l'exécution de run_code dans l'environnement de démonstration d'exemple.
import type { Context } from '@deepseek-ai/cordis'

export const name = 'invariant-guard'

export function apply(ctx: Context) {
  // Enregistrer un guard monotone. Renvoyer une chaîne signifie un rejet ; renvoyer undefined signifie aucun changement.
  const disposer = ctx.tools.guard((execution) => {
    if (execution.name === 'run_code') {
      return 'run_code est désactivé dans le profil de démonstration d'exemple.'
    }
    return undefined // Laisser passer : conserver la décision pre-execute inchangée
  })

  // guard() renvoie une fonction de nettoyage précise ; le framework l'appelle automatiquement lorsque le plugin est déchargé.
  ctx.effect(() => disposer)
}

Parce que le guard n'a pas de résultat allow, même si un listener ultérieur veut allowrun_code, il ne peut pas reconvertir ce rejet en approbation.


Auto-test du résumé

Le pipeline d'exécution des outils découple les "policies" du "tool body", permettant aux hooks de s'étendre sur différentes familles d'outils sans coupler les outils à un service de politiques spécifique.

Questions d'auto-évaluation :

ProblèmeRéférence
Si vous voulez qu'un outil soit "jamais approuvable par quiconque", devez-vous utiliser pre-execute ou guard ?guard, car le guard n'a pas de résultat allow, il est irrévocable.
Pour ajouter un délai d'attente unifié à tous les outils, à quel événement devez-vous vous abonner ?tools/execute, il enveloppe dispatch et peut remplacer signal
Si vous voulez seulement enregistrer le résultat final pour l'audit sans rien changer, quelle étape devez-vous utiliser ?tools/resultIl observe le résultat faisant autorité figé
autres extensions