DeepSeek Harness Plugin-Konfiguration: Config und Schemastery

Das greet-Tool hartcodiert die Begrüßung im Code; für unterschiedliche Bereitstellungen wären Codeänderungen nötig, um sie zu ändern.

Dieses Kapitel ermöglicht es dem Plugin, Konfigurationen anzunehmen, die von cordis.yml übergeben werden, und erreicht damit die "Trennung von Konfiguration und Code".


Exportieren Sie den Config-Typ und das Schema mit demselben Namen

Im Plugin exportierst du eine Config-Schnittstelle und ein Schemastery-Schema mit demselben Namen.

Der Standardwert wird direkt auf das Schemafeld geschrieben.

Beispiel

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

export const name = 'my-plugin'

// Config-Schnittstelle: Definiert, welche Konfigurationsoptionen das Plugin akzeptiert
export interface Config {
  greeting: string    // Begrüßung
  maxRetries: number  // Maximale Wiederholungsanzahl
  verbose?: boolean   // Ob detaillierte Logs ausgegeben werden (optional)
}

// Config-Schema mit demselben Namen: Standardwerte werden hier eingetragen
export const Config: Schema<Config> = Schema.Objekt({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

// Das zweite Argument von apply ist die validierte Konfiguration
export function apply(ctx: Context, config: Config) {
  // Gibt den vom Benutzer übergebenen Wert oder den Standardwert des Schemas aus
  console.log(config.greeting)
}

Das Interface bietet TypeScript-Typen, während das Schema Laufzeitvalidierung und Standardwerte bereitstellt.

Beide haben denselben Namen, was eine Cordis-Konvention ist.

Exportiere kein gewöhnliches Objekt als Config.

Es erfüllt nicht die von Cordis geforderte Standard-Schema-Schnittstelle.


Übergebe die Konfiguration in cordis.yml.

Füge der neu eingefügten lokalen Plugin-Zeile ein config-Feld hinzu.

Beispiel

# Dateipfad: scratch-plugin/cordis.yml
- insert
:
    - id
: hello
      # Der Plugin-Pfad muss ein absoluter Pfad sein (siehe Teil 7)
      name
: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
      config
:
        greeting
: 'Hi there, example!'
        maxRetries
: 5

Wenn das Plugin geladen wird, validiert Cordis die Konfiguration über das exportierte Schema und füllt Standardwerte für nicht angegebene Felder ein.

In der obigen Konfiguration wurde verbose nicht angegeben; es übernimmt den Standardwert false aus dem Schema.


Schema-Validierung

Wenn eine strengere Validierung erforderlich ist, verwenden Sie Schemastery, um Einschränkungen auszudrücken.

Beispiel

// Dateipfad: 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                 // Erforderlich
  timeout: number                // Timeout Millisekunden
  mode: 'fast' | 'accurate'      // Kann nur einen dieser beiden Werte annehmen
}

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 wurde validiert und ist typsicher
}

Das Schema führt eine Validierung aus, wenn das Plugin geladen wird.

Wenn die Konfiguration ungültig ist, kann das Plugin nicht geladen werden und gibt eine klare Fehlermeldung aus.


Designprinzip: keine hartcodierten einstellbaren Parameter.

Die Harness-Konvention lautet: Jeder Parameter, der in verschiedenen Deployments potenziell unterschiedliche Werte annehmen muss, muss als Konfigurationsfeld definiert werden.

Falsche und korrekte Verwendung

// Fehler: Hartkodieren der Timeout-Zeit
const TIMEOUT = 30000

// Korrekt: Als Konfigurationsfeld definieren; der Standardwert wird weiterhin vom Schema bereitgestellt.
export interface Config {
  timeoutMs: number  // Standardwert 30000
}

Das Testkriterium in einem Satz: Kannst du diesen Wert in cordis.yml ändern, ohne den Code zu ändern?

Wenn ja, ist es ein qualifizierter einstellbarer Parameter; wenn nicht, sollte er zu einem Konfigurationsfeld befördert werden.

HartkodierungEs ist das Hartkodieren von Werten, die im Code einstellbar hätten sein sollen.

Es verwandelt „Konfiguration ändern“ in „Code ändern und erneut bereitstellen“, eine häufige Ursache für Produktionsvorfälle.


Konfigurationsfehler sollten laut sein

Formulieren Sie eigenständige Einschränkungen im Schema, sodass ungültige Konfigurationen beim Laden des Plugins fehlschlagen.

Verweise auf Dienste oder registrierte Ressourcen erfordern Dependency Injection; das Service-Tutorial wird diese Konvention vorstellen.


Arbeiten mit HMR: Heißer Konfigurationsaustausch.

Konfigurationsänderungen lösen Hot Module Replacement (HMR) für das Plugin aus.

Nach dem Ändern der Konfiguration eines Plugins in cordis.yml entlädt das Framework die alte Instanz und lädt die neue.

Da alle Registrierungen Effekte sind und automatisch bereinigt werden, werden die Registrierungen der alten Instanz nach dem Austausch nicht beibehalten.

配置校验与 HMR 流程


Zusammenfassung und Selbsttest

Exportieren Sie die Config-Schnittstelle und das gleichnamige Schema, schreiben Sie Standardwerte in das Schema, validieren Sie die Konfiguration beim Laden; alle anpassbaren Parameter gehören in die Konfiguration.

1. Warum Standardwerte im Schema statt im Code schreiben?

2. Was passiert, wenn die Konfiguration ungültig ist?

3. Was ist der Standard für die Überprüfung von „No Hardcoding“?

Weitere Erweiterungen