Flujos de trabajo

Un flujo de trabajo es una subcarpeta con nombre dentro de workflows/ que agrupa scripts relacionados, disparadores de eventos, pools de procesos de trabajo, herramientas MCP y vistas de cola en una unidad de automatización autónoma. Los flujos permiten ejecutar varias canalizaciones dentro de un único espacio de trabajo sin que interfieran entre sí.

Para flujos de larga duración, Guida también puede mantener un Workflow Ledger duradero con ejecuciones, elementos, etapas, estados, eventos, resultados vinculados, reservas, reintentos y acciones de recuperación.

Estructura de carpetas

Los flujos viven bajo workflows/ dentro del espacio de trabajo. La existencia de la carpeta declara el flujo; no hace falta un manifiesto separado:

my-workspace/
  scripts/              # Global scripts
  lib/                  # Shared libraries
  views/                # Global queue views
  events.json           # Global triggers
  queues.json           # Global worker pools
  tools.json            # Global MCP tools
  store.db              # Shared document store
  queue.db              # Shared work queues
  workflow-ledger.db    # Shared workflow run/item history
  search-index/         # Shared search index
  workflows/
    job-validation/
      events.json       # Active only when this workflow is selected
      queues.json       # Active only when this workflow is selected
      tools.json        # Active only when this workflow is selected
      views/
        review.json
      scripts/
        enqueue.js
        check.js
    rss-pipeline/
      events.json
      scripts/
        scrape.js

Carga en dos niveles

Guida carga configuración en dos niveles:

Global — events.json, queues.json, tools.json y views/ en la raíz siempre están activos, independientemente del flujo seleccionado.
Flujo — la configuración del flujo activo se carga sobre la capa global.

Solo un flujo está activo a la vez. La configuración global nunca se ve afectada por cambios de flujo.

Cambiar de flujo

Seleccione un flujo desde el desplegable de la barra de herramientas, visible cuando el espacio de trabajo tiene un directorio workflows/. Elija “None” para funcionar solo con configuración global.

También puede cambiar desde scripts o MCP:

// From a script
g.workflows.switch("job-validation");

Al cambiar de flujo:

Los disparadores del flujo anterior se desactivan
Los pools de procesos del flujo anterior se detienen; los elementos en curso terminan
Los disparadores y procesos del nuevo flujo se activan
La configuración global permanece sin cambios

Crear un flujo

Haga clic derecho en el panel Workspace y seleccione New Workflow. Introduzca un nombre y, opcionalmente, elija una plantilla:

Blank — carpeta de flujo vacía con scripts/
Scraper — disparador de evento + pool de procesos + vista de cola
Monitor — disparadores url-match para observar páginas
Processor — canalización basada en colas con vistas

Recursos compartidos

Todos los flujos de un espacio de trabajo comparten la misma capa de datos:

Store (store.db) — el mismo almacén de documentos para todos los flujos
Queues (queue.db) — las colas son compartidas; los flujos pueden procesar elementos de cola de otros flujos
Workflow Ledger (workflow-ledger.db) — historial de ejecuciones/elementos compartido y limitado por nombre de flujo
Search Index — índice de texto completo compartido
Bibliotecas compartidas — use import estándar en JS, require() en Lua o (import ...) en Janet para compartir código entre scripts. Las bibliotecas globales de la carpeta raíz lib/ también están disponibles.

Esto significa que un flujo de scraping puede poner en cola elementos que recoge un flujo de procesamiento, sin copiar datos.

Workflow Control Console

La Workflow Control Console es la vista de operador para espacios de trabajo grandes donde muchas carpetas de flujo, módulos de crawler, colas y etapas del registro pertenecen a una operación real.

Ábrala desde View > Workflow Control Console. No sustituye a la Queue Console ni a la Workflow Ledger Console. En cambio, da al operador un lugar único para responder:

¿Qué operación intenta ejecutar este espacio de trabajo?
¿El flujo activo es correcto?
¿Hay un script de entrada, o esta operación solo se puede reanudar/inspeccionar?
¿Qué colas y pools de procesos se esperan?
¿Qué fase, módulo o traspaso necesita atención?
¿Dónde conviene profundizar ahora: cola, registro, runbook o script?

La consola se basa en evidencia. Enlaza a detalles de cola y registro cuando tiene una cola, etapa, estado, filtro rápido o término de búsqueda útil. Evita fingir que el estado que solo existe en el registro es trabajo ejecutable de cola.

`workflow-operations.json`

Cree workflows/workflow-operations.json para describir operaciones de nivel operador. Los campos son opcionales salvo que su operación los necesite; una operación mínima puede cargar sin un runbook completo.

{
  "version": 1,
  "operations": [
    {
      "id": "careers-full-crawl",
      "title": "Careers full crawl",
      "workflowName": "careers-crawl",
      "summary": "Discover company career pages, fetch postings, and hand them to parse/index workers.",
      "entryScript": "workflows/careers-crawl/scripts/enqueue.js",
      "ledgerRequired": true,
      "expectedQueues": ["careers_fetch", "careers_snapshot_parse"],
      "expectedWorkerPools": ["careers_fetch", "careers_snapshot_parse"],
      "relatedLedgerStages": ["portal_discovery", "fetch", "parse_index"],
      "phases": [
        {
          "id": "fetch",
          "title": "Fetch career pages",
          "stages": ["fetch"],
          "queues": ["careers_fetch"],
          "workers": ["careers_fetch"]
        }
      ],
      "focusAreas": [
        {
          "id": "fetch-backlog",
          "title": "Fetch backlog",
          "stages": ["fetch"],
          "queues": ["careers_fetch"],
          "actions": ["resume-fetch"]
        }
      ],
      "actions": [
        {
          "id": "resume-fetch",
          "title": "Resume fetch workers",
          "kind": "resume-workers",
          "queue": "careers_fetch",
          "targetConsole": "queue"
        }
      ],
      "relatedConsoles": ["workflowLedger", "queueConsole"]
    }
  ]
}

Campos útiles de operación:

Campo	Significado
`workflowName`	Flujo que debe estar activo para inicios directos
`entryScript`	Script de inicio opcional; omítalo para operaciones solo de inspección, reanudación o recuperación
`summary`, `help`, `prerequisites`	Runbook y guía para el operador
`expectedQueues`, `expectedWorkerPools`	Evidencia de cola/proceso que la consola debe buscar
`phases`	Etapas principales del trabajo, normalmente enlazadas con colas, procesos y etapas del registro
`focusAreas`	Secciones accionables dentro de una operación, como backlog, trabajo listo para reintento o traspaso
`actions`	Acciones de operador admitidas, como iniciar, reanudar procesos, abrir cola, abrir registro o abrir script
`preflightChecks`	Lista opcional de filas de controles preliminares que mostrar; omítala para mostrar el conjunto predeterminado

Las operaciones sin entryScript son válidas. La consola las trata como superficies de inspección, reanudación o recuperación y no genera una acción Start salvo que el manifiesto defina una explícitamente, en cuyo caso queda deshabilitada con un motivo.

Runbook y controles preliminares

Los campos de runbook explican propósito, cuándo ejecutar, qué hace la operación, entradas, resultado esperado, advertencias y resolución de problemas. Son opcionales, pero las descripciones detalladas ayudan cuando un espacio de trabajo tiene muchos crawlers y colas especializados.

Las filas de controles preliminares muestran si el espacio de trabajo está abierto, el manifiesto cargó, el flujo es conocido, el flujo activo coincide, el script de entrada existe, el registro está disponible, las colas existen, los pools de procesos son conocidos y hay atención del registro.

Los controles preliminares son guía más seguridad. Ocultar una fila con preflightChecks cambia la pestaña mostrada, no las reglas duras de seguridad al iniciar un script bajo el flujo equivocado.

Fases, áreas de foco y traspasos

Las fases modelan los pasos principales de la operación. Las áreas de foco modelan secciones accionables dentro de esos pasos: backlog de fetch, trabajo listo para reintento, rechazos, backlog de parse/index o un traspaso que necesita inspección.

Los traspasos describen transiciones entre etapas, como fetch a parse_index. La consola compara conteos del registro aguas arriba y aguas abajo para que el operador vea si el trabajo se detuvo entre fases.

Use áreas de foco para reparación y reanudación en lugar de crear operaciones falsas de nivel superior. Esto mantiene el lado izquierdo de la consola centrado en operaciones reales mientras sigue mostrando el trabajo que necesita atención.

`workflow-map.json`

Use workflows/workflow-map.json cuando un espacio de trabajo contenga muchas carpetas de flujo pero solo unos pocos sistemas de nivel operador. El mapa agrupa flujos en sistemas, canalizaciones, grupos de módulos, etapas, colas, procesos, operaciones y traspasos.

{
  "version": 1,
  "systems": [
    {
      "id": "careers",
      "title": "Careers Crawl",
      "pipelines": [
        {
          "id": "careers-crawl",
          "title": "Careers Crawl Pipeline",
          "workflowName": "careers-crawl",
          "operations": ["careers-full-crawl"],
          "ledgerWorkflowName": "careers-crawl",
          "stages": ["portal_discovery", "fetch", "parse_index"],
          "queues": ["careers_fetch", "careers_snapshot_parse"],
          "workers": ["careers_fetch", "careers_snapshot_parse"],
          "modules": ["career-crawlers"],
          "handoffs": [
            {
              "from": "fetch",
              "to": "parse_index",
              "viaQueue": "careers_snapshot_parse"
            }
          ]
        }
      ],
      "moduleGroups": [
        {
          "id": "career-crawlers",
          "title": "Specialized career crawlers",
          "role": "adapter",
          "workflowNamePatterns": ["careers-*"],
          "excludeWorkflowNames": ["careers-crawl"]
        }
      ]
    }
  ]
}

El progreso de módulos se calcula a partir de agregados del registro para la ejecución seleccionada, no desde la página visible de elementos. Los módulos sin evidencia de registro se muestran como no intentados para que el operador decida si se omitieron intencionadamente, todavía no se pusieron en cola o faltan en la ejecución.

API de scripting

// Check what's active
const active = g.workflows.getActive();
if (active) g.log("Current workflow: " + active.name);

// List all workflows
const workflows = g.workflows.list();
for (const w of workflows) {
  g.log(w.name + " — " + w.scriptCount + " scripts" +
    (w.hasEvents ? ", has triggers" : ""));
}

// Switch (fire-and-forget)
g.workflows.switch("rss-pipeline");

Vea la Referencia de API para las firmas completas.

Siguientes pasos

Espacios de trabajo — estructura y archivos de configuración del espacio de trabajo
Procesos de trabajo de cola — pools de procesos en nivel global o de flujo
Workflow Ledger — visibilidad duradera de ejecuciones y elementos
Herramientas personalizadas — definir herramientas MCP por flujo de trabajo