DeepSeek Harness Configuración de plugins: Config y Schemastery

La herramienta greet tiene el saludo codificado fijo en el código; en diferentes despliegues, cambiarlo requiere modificar el código.

Este capítulo hace que el plugin acepte la configuración proporcionada en cordis.yml, logrando la “separación de configuración y código”.

Exportar el tipo Config y el schema con el mismo nombre

En el plugin, exporta una interfaz Config y un schema de Schemastery con el mismo nombre.

Los valores predeterminados se escriben directamente en los campos del schema.

Ejemplo

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

export const name = 'my-plugin'

// Interfaz Config: define qué opciones de configuración acepta el plugin
export interface Config {
  greeting: string    // Saludo
  maxRetries: number  // Número máximo de reintentos
  verbose?: boolean   // Si se emiten registros detallados (opcional)
}

// Schema de Config con el mismo nombre: los valores predeterminados se escriben aquí
export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

// El segundo parámetro de apply es la configuración validada
export function apply(ctx: Context, config: Config) {
  // Se imprime el valor pasado por el usuario o el valor predeterminado del schema
  console.log(config.greeting)
}

La interfaz proporciona los tipos de TypeScript; el schema proporciona la validación en tiempo de ejecución y los valores predeterminados.

Que ambos tengan el mismo nombre es una convención de Cordis.

No exportes un objeto simple como Config.

No satisface la interfaz Standard Schema que exige Cordis.

Pasar la configuración en cordis.yml

En la línea del plugin local recién insertada, añade un campo config.

Ejemplo

# Ruta del archivo: scratch-plugin/cordis.yml
- insert:
    - id: hello
      # La ruta del plugin debe ser una ruta absoluta (ver artículo 7)
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
      config:
        greeting: 'Hi there, ejemplo!'
        maxRetries: 5

Al cargar el plugin, Cordis valida la configuración con el schema exportado y completa los valores predeterminados de los campos no proporcionados.

En la configuración anterior no se incluyó verbose; tomará el valor predeterminado false del schema.

Validación del schema

Cuando se necesita una validación más estricta, usa Schemastery para expresar las restricciones.

Ejemplo

// Ruta del archivo: 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                 // Obligatorio
  timeout: number                // Tiempo de espera en milisegundos
  mode: 'fast' | 'accurate'      // Solo puede tomar uno de estos dos valores
}

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 ya está validada, con seguridad de tipos
}

El schema realiza la validación al cargar el plugin.

Si la configuración no es válida, el plugin falla al cargar y muestra un mensaje de error claro.

Principio de diseño: parámetros ajustables sin hardcodear

La convención de Harness es: cualquier parámetro que pueda necesitar diferentes valores en distintos despliegues debe definirse como un campo de configuración.

Escritura incorrecta y correcta

// Incorrecto: hardcodear el tiempo de espera
const TIMEOUT = 30000

// Correcto: definirlo como campo de configuración; el valor predeterminado lo sigue proporcionando el schema
export interface Config {
  timeoutMs: number  // Predeterminado 30000
}

Criterio en una frase: ¿se puede cambiar este valor en cordis.yml sin modificar el código?

Si se puede, es un parámetro ajustable válido; si no, hay que convertirlo en un campo de configuración.

HardcodeConsiste en escribir en el código valores que deberían ser ajustables.

Convierte “cambiar la configuración” en “modificar el código y volver a desplegar”, y es una causa común de incidentes de producción.

Los errores de configuración deben ser evidentes

Expresa restricciones completas en el schema para que las configuraciones no válidas fallen durante la carga del plugin.

Las referencias a servicios o recursos registrados requieren inyección de dependencias; el tutorial de servicios introducirá esta convención.

Con HMR: reemplazo en caliente de la configuración

Los cambios de configuración activan el reemplazo en caliente (HMR) del plugin.

Después de modificar el config de un plugin en cordis.yml, el framework descarga la instancia anterior y carga la nueva.

Como los registros pertenecen a efectos y se limpian automáticamente, tras el reemplazo no se conservan los registros de la instancia anterior.

配置校验与 HMR 流程

Resumen y autoevaluación

Exporta la interfaz Config y el schema con el mismo nombre, escribe los valores predeterminados en el schema, valida la configuración en la carga; todos los parámetros ajustables van a la configuración.

1. ¿Por qué los valores predeterminados se escriben en el schema y no en el código?

2. ¿Qué ocurre cuando la configuración no es válida?

3. ¿Cuál es el criterio para comprobar “sin codificación fija”?

Otras extensiones