Configuration du plugin DeepSeek Harness : Config et Schemastery

L'outil greet code en dur la salutation dans le code ; différents déploiements nécessiteraient des modifications du code pour la changer.

Ce chapitre permet au plugin d'accepter une configuration transmise depuis cordis.yml, réalisant ainsi « séparation de la configuration et du code ».


Exporter le type Config et le schéma avec le même nom

Dans le plugin, exportez une interface Config et un schéma Schemastery du même nom.

La valeur par défaut est écrite directement sur le champ du schéma.

Exemple

// Chemin du fichier : scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'my-plugin'

// Interface Config : définit quelles options de configuration le plugin accepte.
export interface Config {
  greeting: string    // Salutation
  maxRetries: number  // Nombre maximal de tentatives
  verbose?: boolean   // Indique s'il faut produire des journaux détaillés (facultatif)
}

// Schéma Config du même nom : les valeurs par défaut sont écrites ici
export const Config: Schema<Config> = Schema.objet({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

// Le deuxième argument de apply est la configuration validée
export function apply(ctx: Context, config: Config) {
  // Affiche la valeur transmise par l'utilisateur ou la valeur par défaut du schéma
  console.log(config.greeting)
}

L'interface fournit des types TypeScript, tandis que le schéma assure la validation à l'exécution et fournit des valeurs par défaut.

Les deux ont le même nom, ce qui est une convention de Cordis.

N'exportez pas un objet ordinaire comme Config.

Il ne satisfait pas à l'interface Standard Schema requise par Cordis.


Passez la configuration dans cordis.yml.

Ajoutez un champ config à la ligne de plugin local nouvellement insérée.

Exemple

# Chemin du fichier : scratch-plugin/cordis.yml
- insert
:
    - id
: hello
      # Le chemin du plugin doit être un chemin absolu (voir Partie 7)
      name
: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
      config
:
        greeting
: 'Hi there, example!'
        maxRetries
: 5

Lorsque le plugin se charge, Cordis valide la configuration via le schéma exporté et renseigne les valeurs par défaut pour les champs non fournis.

Dans la configuration ci-dessus, verbose n'est pas écrit ; il prendra la valeur par défaut false du schéma.


Validation de schéma

Lorsqu'une validation plus stricte est nécessaire, utilisez Schemastery pour exprimer des contraintes.

Exemple

// Chemin du fichier : scratch-plugin/src/validated-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'validated-plugin'

export interface Config {
  apiKey: string                 // Requis
  timeout: number                // Délai en millisecondes
  mode: 'fast' | 'accurate'      // Ne peut prendre qu'une de ces deux valeurs
}

export const Config = Schema.object({
  apiKey: Schema.string().required(),
  timeout: Schema.number().default(30000),
  mode: Schema.union(['fast', 'accurate']).default('fast'),
})

export function apply(ctx: Context, config: Config) {
  // config a été validée et est sûre au niveau des types
}

Le schéma exécute la validation lorsque le plugin se charge.

Si la configuration n'est pas valide, le plugin ne pourra pas se charger et fournira un message d'erreur clair.


Principe de conception : aucun paramètre réglable codé en dur.

La convention Harness est la suivante : tout paramètre susceptible de prendre des valeurs différentes selon les déploiements doit être défini comme un champ de configuration.

Utilisation incorrecte et correcte

// Erreur : codage en dur du délai d'expiration
const TIMEOUT = 30000

// Correct : définir comme un champ de configuration ; la valeur par défaut est toujours fournie par le schéma.
export interface Config {
  timeoutMs: number  // Par défaut 30000
}

Le critère de test en une phrase : pouvez-vous modifier cette valeur dans cordis.yml sans modifier le code ?

Si oui, il s'agit d'un paramètre ajustable qualifié ; sinon, il doit être promu au rang de champ de configuration.

Codage en durIl s'agit de coder en dur des valeurs qui auraient dû être ajustables dans le code.

Cela transforme « modifier la configuration » en « modifier le code et redéployer », une source courante d'incidents de production.


Les erreurs de configuration doivent être visibles

Exprimez des contraintes autonomes dans le schéma, afin que les configurations invalides échouent au chargement du plugin.

Les références à des services ou à des ressources enregistrées nécessitent l'injection de dépendances ; le tutoriel sur les services introduira cette convention.


Travailler avec HMR : remplacement à chaud de la configuration.

Les changements de configuration déclenchent le remplacement de module à chaud (HMR) pour le plugin.

Après avoir modifié la configuration d'un plugin dans cordis.yml, le framework décharge l'ancienne instance et charge la nouvelle.

Comme tous les enregistrements sont des effets et sont automatiquement nettoyés, les enregistrements de l'ancienne instance ne seront pas conservés après le remplacement.

配置校验与 HMR 流程


Résumé et auto-test

Exportez l'interface Config et le schéma du même nom, écrivez les valeurs par défaut dans le schéma, validez la configuration au chargement ; tous les paramètres ajustables vont dans la configuration.

1. Pourquoi écrire les valeurs par défaut dans le schéma plutôt que dans le code ?

2. Que se passe-t-il lorsque la configuration est invalide ?

3. Quel est le critère pour vérifier l'absence de « codage en dur » ?

autres extensions