Programmation défensive DeeSeek Harness : rapport de résultats, nettoyage et identifiants

Après avoir écrit autant de plugins, vous pouvez rencontrer une classe de bugs de cas limites qui « ne peuvent pas être reproduits dans les tests, mais explosent au moment où ils passent en production. »

La documentation officielle les regroupe en « règles de catégories de bugs chèrement acquises » — chacune correspond à un bug qui a réellement été livré ou a failli l'être.

Cet article couvre les cinq modèles de programmation défensive les plus importants : signalement des résultats, quiescence de dispose, effacement des identifiants, suppression des liens et isolation des callbacks.

En une phrase : ces modèles empêchent « un simple cas limite de faire tomber tout l'Agent. »


Premier coup d'œil au tableau comparatif

Le schéma ci-dessous compare côte à côte de mauvais exemples avec de bons exemples, chacun tiré d'une catégorie de bug réelle.

防御性编程坏好示例对照图

La documentation officielle appelle ces modèles les règles « veuillez lire ceci avant d'écrire du code de cycle de vie, de concurrence, de processus enfant ou de nettoyage ».


Résultats orthogonaux signalés indépendamment

Un résultat peut avoir plusieurs propriétés simultanément : un processus peut avoir dépassé le délai d'attente mais quand même se terminer avec le code 0 parce qu'il a intercepté le signal de terminaison.

Chaque fait indépendant (timedOut、signal、exitCode) doit être signalé séparément.

Ne jamais imbriquer le signalement d’un indicateur dans la branche d’un autre indicateur ; sinon les appelants peuvent confondre une exécution interrompue prématurément avec un succès normal.

Exemple

// Chemin du fichier : packages/my-shell/src/run.ts
// Exécuter un processus enfant et signaler de manière orthogonale trois faits indépendants : timedOut, signal, exitCode.
import { spawn, type ChildProcess } from 'node:child_process'

export interface RunResult {
  timedOut: boolean      // Fait indépendant 1 : si le délai d’attente a été dépassé
  signal: NodeJS.Signals | null // Fait indépendant 2 : s’il a été terminé par un signal
  exitCode: number | null       // Fait indépendant 3 : code de sortie
  stdout: string
  stderr: string
}

export function run(argv: string[], timeoutMs: number): Promise<RunResult> {
  return new Promise((resolve, reject) => {
    const child: ChildProcess = spawn(argv[0], argv.slice(1), {
      stdio: ['ignore', 'pipe', 'pipe'],
    })
    let stdout = ''
    let stderr = ''
    child.stdout.on('data', (d: Buffer) => (stdout += d))
    child.stderr.on('data', (d: Buffer) => (stderr += d))

    // Fait indépendant 1, maintenu séparément : le timeout est un indicateur, sans rapport avec le code de sortie.
    let timedOut = false
    const timer = setTimeout(() => {
      timedOut = true
      child.kill('SIGTERM') // Le délai d'attente déclenche la terminaison
    }, timeoutMs)

    child.on('close', (code, signal) => {
      clearTimeout(timer)
      // Les trois champs sont renvoyés indépendamment : le processus peut avoir timedOut=true et exitCode=0,
      // Car il intercepte SIGTERM après le délai d'attente et se termine avec 0.
      resolve({ timedOut, signal, exitCode: code, stdout, stderr })
    })
    child.on('error', reject)
  })
}

Avec ce style, les appelants peuvent combiner les vérifications :timedOutest vrai maisexitCodeSi c'est 0, cela signifie « tué de force, mais le processus l'a masqué avec un 0. »

Si la remontée d'informations est imbriquée, cette combinaison ne peut jamais être exprimée.


dispose doit atteindre un état totalement arrêté.

Si le flux de nettoyage se contente d’envoyer un signal de terminaison ou d’abandon et revient sans attendre que le travail s’arrête réellement, il laisse des processus orphelins derrière lui.

La logique de nettoyage doit utiliser un flux asynchrone et attendre que le processus enfant se termine (envoyer un signal de terminaison, puis attendredone)。

Vous devez également fermer les registres d’écouteurs et les registres de notification avant de terminer le processus, afin de garder silencieux les événements d’achèvement tardifs.

Exemple

// Chemin du fichier : packages/my-shell/src/dispose.ts
// dispose doit s’arrêter complètement : après avoir envoyé le signal, attendre que le processus enfant se termine, plutôt que de revenir juste après l’envoi du signal.
import { once } from 'node:events'
import type { ChildProcess } from 'node:child_process'

export async function disposeQuiescent(child: ChildProcess): Promise<void> {
  // 1. Supprimez d’abord les écouteurs afin que les événements d’achèvement tardifs restent silencieux.
  child.removeAllListeners()

  // 2. Demander l'arrêt : émettre le signal de terminaison.
  child.kill('SIGTERM')

  // 3. Attendre que le processus enfant se termine réellement ; s'il ne s'est toujours pas terminé après le délai, passer à SIGKILL.
  // Promise.race garantit que dispose ne sera pas bloqué indéfiniment par un processus enfant qui refuse de se terminer.
  const forceKill = new Promise<void>((resolve) => {
    setTimeout(() => {
      child.kill('SIGKILL')
      resolve()
    }, 5_000)
  })

  await Promise.race([once(child, 'exit').then(() => undefined), forceKill])
}

De cette façon, lorsque dispose retourne, l'enfant a soit terminé, soit été tué de force avec SIGKILL.


Nettoyage des identifiants : ne jamais exposer les variables d'environnement à une sortie non fiable.

Les commandes lancées doivent utiliser un environnement nettoyé, en supprimant*KEY*、*SECRET*、*TOKEN*ou*PASSWORD*l'élément correspondant.

Sinon, les identifiants du harnais peuvent fuiter via la sortie de commande,envou des fuites de fichiers de déversement.

Les fichiers temporaires et les fichiers de déversement doivent être placés dans un répertoire privé avec des permissions 0700, utiliser des noms de fichiers aléatoires, et être ouverts de manière exclusive et accessible au propriétaire ('wx'、0o600)。

Exemple

// Chemin du fichier : packages/src/env.ts
// Nettoyer les variables d'environnement avant de lancer la commande pour empêcher les identifiants du harnais de fuiter via la sortie de commande ou l'environnement.
// Les éléments sensibles correspondant à *KEY* *SECRET* *TOKEN* *PASSWORD* sont tous supprimés.
const SENSITIVE_NAME = /.*(?:KEY|SECRET|TOKEN|PASSWORD).*/i

export function scrubEnv(env: NodeJS.ProcessEnv): Record<string, string> {
  const clean: Record<string, string> = {}
  for (const [key, value] of Object.entries(env)) {
    if (SENSITIVE_NAME.test(key)) continue // Ignorer directement les clés sensibles
    if (value !== undefined) clean[key] = value
  }
  return clean
}

// Utilisation : spawn(argv[0], argv.slice(1), { env: scrubEnv(process.env), ... })

Dans l'environnement d'exemple,DEEPSEEK_API_KEYCes variables doivent passer par ce chemin d'effacement.

Laisser la sortie de commande,envou les fichiers de débordement qui les transportent, ce qui équivaut à remettre les clés à tout ce qui peut lire la sortie.


Supprimer les liens symboliques avec unlink.

Un chemin qui peut être un lien symbolique ou une jonction Windows doit d'abord utiliserlstatSync().isSymbolicLink()Jugez, puis utilisezunlinkSyncSupprimez.

unlink ne supprime que le lien lui-même et refuse les vrais répertoires, donc il ne suit jamais un lien vers sa cible.

Appeler junction sous WindowsrmSync(link)Lèvera une exceptionERR_FS_EISDIR; la suppression récursive peut traverser la jonction vers sa cible.

Seuls les répertoires réels utilisent taperecursivedermSync。

Exemple

// Chemin de fichier : packages/my-fs/src/remove.ts
// Supprimer les chemins sous forme de lien avec unlink, ne jamais suivre récursivement les liens vers leurs cibles.
import { lstatSync, rmSync, unlinkSync } from 'node:fs'

export function removePath(p: string): void {
  // Vérifier d'abord s'il s'agit d'un lien symbolique (ou d'une jonction Windows).
  if (lstatSync(p).isSymbolicLink()) {
    // unlink ne supprime que le lien lui-même et refuse les répertoires réels ; il ne suit pas les liens.
    unlinkSync(p)
    return
  }
  // Après avoir confirmé qu'il s'agit du répertoire réel, utilisez rmSync avec recursive.
  rmSync(p, { recursive: true })
}

Isolation des exceptions de callback dans le dispatcher

Si un écouteur fourni par l'utilisateur lève une exception, elle ne doit pas entraîner le rejet de la promesse à laquelle il appartient, ni empêcher les écouteurs en file d'attente derrière lui de s'exécuter.

Enveloppez la boucle de dispatch dans un try/catch et journalisez les erreurs.

Un abonné défaillant ne doit jamais interrompre le cycle de vie principal.

Exemple

// Chemin du fichier : packages/my-events/src/dispatch.ts
// Le dispatcher isole les exceptions de callback : un abonné défaillant ne peut pas interrompre le cycle de vie principal.
export function dispatch(listeners: ReadonlyArray<() => void>): void {
  for (const listener of listeners) {
    try {
      listener()
    } catch (err) {
      // Journaliser et continuer à dispatcher, ne jamais rejeter, et ne jamais affamer les écouteurs suivants.
      console.error('[dispatch] un écouteur a échoué :', err)
    }
  }
}

Ce modèle est partout à l'intérieur de dsh :session/eventLes échecs d'observateur sont journalisés et isolés, plutôt que de laisser échouer des ajouts déjà validés.

Cela garantit qu'"un plugin qui fait planter son écouteur" n'arrêtera pas toute la boucle de l'Agent.


Aperçu des modes supplémentaires

La documentation officielle consigne également deux autres éléments à retenir :

ModeRègles
Les deux parties du contrat public doivent s'y conformerLorsque vous recevez plusieurs représentations du même résultat, normalisez-les avant de les renvoyer via l'API publique ; les consommateurs ne devraient pas avoir à deviner si les exceptions proviennent du fournisseur, de la couche d'encapsulation, ou de leur propre logique d'assemblage
L'état asynchrone n'est pas l'état synchroneN'utilisez pasagent/statusouwhenIdle()À titre d'exemplefollowup()le résultat de ; l'appelant qui possède réellement une exécution doit définir explicitement l'intervalle

Les contreparties de test de ces règles (chemins d'entrée réels, vérification des résultats réels, propriété des ressources) sont détaillées dans testing.md, qui sera abordé dans le prochain article.


Auto-test du résumé

La programmation défensive prévient à l'avance les pièges susceptibles d'échouer aux frontières : rapport de résultat orthogonal, dispose entièrement quiescé, effacement des identifiants, suppression sûre des liens et isolation des exceptions de rappel.

Questions d'auto-évaluation :

ProblèmeRéférence
Un processus a expiré, mais le code de sortie est 0 — qu'est-ce que cela signifie ?Il se peut qu'il ait intercepté le signal de terminaison et soit sorti avec 0 de lui-même ; timedOut et exitCode sont deux faits indépendants.
Quel est le risque de seulement envoyer SIGTERM et de revenir lors du nettoyage d'un processus enfant ?Cela laisse des processus orphelins ; vous devez attendre la sortie, puis passer à SIGKILL en cas d'expiration.
Que devez-vous utiliser pour supprimer un chemin qui peut être un lien symbolique ?Vérifiez d'abord avec lstatSync, puis utilisez unlinkSync ; n'utilisez rmSync recursive que pour de vrais répertoires.
autres extensions