Saltar al contenido principal

Sistema de parámetros

Los workflows pueden definir parámetros configurables que muestran un cuadro de diálogo de configuración para que el usuario los complete antes de ejecutar. El sistema de parámetros soporta múltiples tipos y fuentes de datos dinámicas.

Definición de parámetros​

Los parámetros se definen en el campo parameters de workflow.json:

{
  "parameters": {
    "language": {
      "type": "string",
      "title": "Output Language",
      "description": "Select the language for output content",
      "default": "en-US",
      "enum": ["en-US", "zh-CN", "ja-JP"],
      "allowCustom": true
    },
    "maxResults": {
      "type": "number",
      "title": "Maximum Results",
      "description": "Upper limit on the number of results returned",
      "default": 10,
      "min": 1,
      "max": 100
    },
    "enableFilter": {
      "type": "boolean",
      "title": "Enable Filtering",
      "description": "Whether to enable result filtering",
      "default": true,
      "visible_if": { "parameter": "language", "equals": false }
    }
  }
}

Tipos de parámetros​

TipoDescripciónControl aplicable
stringCadena de textoCuadro de texto / desplegable / selector dinámico
numberNúmeroEntrada numérica (soporta restricciones min/max)
booleanBooleanoInterruptor / casilla de verificación

Parámetros requeridos​

Establezca required: true cuando un flujo de trabajo no pueda ejecutarse sin un parámetro:

{
  "collectionScope": {
    "type": "string",
    "required": true,
    "title": "Collection Scope"
  }
}

Las cadenas requeridas deben ser no vacías, los números requeridos deben ser finitos, y ambos valores de un booleano requerido son válidos. Los valores requeridos faltantes se rechazan antes del dispatch del proveedor. Los parámetros permanecen opcionales cuando required es false o se omite.

Valores enum y valores personalizados​

{
  "language": {
    "type": "string",
    "enum": ["en-US", "zh-CN", "ja-JP"],
    "allowCustom": true,
    "default": "en-US"
  }
}
  • enum: Lista de valores preestablecidos sugeridos. Se muestra como opciones seleccionables en el menú desplegable
  • allowCustom (solo tipo string): Cuando se establece en true, los valores de enum son solo recomendaciones; los usuarios pueden ingresar libremente otros valores. Cuando se establece en false o se omite, los usuarios solo pueden seleccionar de enum

Visualización condicional​

{
  "advancedMode": {
    "type": "boolean",
    "title": "Advanced Mode",
    "default": false
  },
  "customEndpoint": {
    "type": "string",
    "title": "Custom Endpoint",
    "visible_if": { "parameter": "advancedMode", "equals": true }
  }
}

visible_if controla la visualización/ocultación de parámetros en el cuadro de diálogo de configuración:

  • equals: true — Mostrar solo cuando el valor del parámetro objetivo sea verdadero
  • equals: false — Mostrar solo cuando el valor del parámetro objetivo sea falso

Ejemplo: Mostrar/Ocultar vinculado

{
  "auto_tag_regulator": {
    "type": "boolean",
    "title": "Auto Tag Regulator",
    "default": true
  },
  "auto_tag_infer_tag": {
    "type": "boolean",
    "title": "Infer tags",
    "default": true,
    "visible_if": { "parameter": "auto_tag_regulator", "equals": true }
  }
}

Cuando auto_tag_regulator está desmarcado, el parámetro auto_tag_infer_tag se oculta automáticamente.

Fuentes de opciones dinámicas​

Las opciones de valores de parámetros pueden provenir de datos en vivo de Zotero:

{
  "targetCollection": {
    "type": "string",
    "title": "Target Collection",
    "default": "",
    "optionsSource": {
      "kind": "zotero.collections",
      "library": "current",
      "includeEmpty": true,
      "valueFormat": "collectionRef",
      "labelFormat": "path"
    }
  },
  "relatedTopic": {
    "type": "string",
    "title": "Related Topic",
    "optionsSource": {
      "kind": "synthesis.topics",
      "filter": "updatable"
    }
  }
}

Fuentes de opciones soportadas​

kindDescripciónParámetros disponibles
zotero.collectionsLista de colecciones en la biblioteca actual de Zoterolibrary (current/user/number), includeEmpty, valueFormat (collectionRef), labelFormat (path/title)
synthesis.topicsLista de temas en el Synthesis Workbenchfilter (all/updatable), valueFormat (topicId), labelFormat (title)

Parámetros comunes de optionsSource​

ParámetroDescripción
libraryÁmbito de biblioteca. "current" (biblioteca actual), "user" (biblioteca de usuario), número (ID de biblioteca específica)
includeEmptySi incluir una opción vacía (para "sin selección")
valueFormatFormato de los valores de opción: "collectionRef" / "topicId"
labelFormatFormato de visualización de las etiquetas de opción: "path" / "title"
allowStalePermitir el uso de datos en caché (evita solicitar nuevamente cada vez que se abre la configuración)
filterCondición de filtrado (varía según kind)

Restricciones para parámetros numéricos​

{
  "confidence": {
    "type": "number",
    "title": "Confidence Threshold",
    "default": 0.8,
    "min": 0,
    "max": 1
  }
}

min y max restringen el rango de valores de entrada.

Lectura de parámetros en Hooks​

En buildRequest, filterInputs, y applyResult, puedes leer los valores de parámetros establecidos por el usuario a través de executionOptions.workflowParams:

export function buildRequest({ executionOptions, runtime }) {
  const params = executionOptions?.workflowParams || {};
  const language = params.language || "en-US";
  const maxResults = params.maxResults || 10;

  return {
    kind: "skillrunner.job.v1",
    create: { skill_id: "my-skill" },
    parameter: { language, max_results: maxResults },
  };
}

Localización de parámetros​

El title y description de los parámetros soportan localización:

{
  "i18n": {
    "messages": {
      "zh-CN": {
        "parameters.language.title": "Language",
        "parameters.language.description": "Select the language for output content"
      }
    }
  }
}

Consulta la página de Localización para el mecanismo completo de localización.

Próximos pasos​