Flussi di lavoro

Un flusso di lavoro è una sottocartella nominata dentro workflows/ che raggruppa script correlati, generazione di eventi, pool di processi di lavoro, strumenti MCP e viste di coda in un’unità di automazione autonoma. I flussi di lavoro permettono di eseguire più flussi di automazione dentro un singolo spazio di lavoro senza interferenze reciproche.

Per flussi di lavoro di lunga durata, Guida può anche mantenere un registro di tracciabilità dei flussi di lavoro persistente con esecuzioni, elementi, fasi, stati, eventi, risultati collegati, prese in carico, tentativi e azioni di ripristino.

Struttura delle cartelle

I flussi di lavoro vivono sotto workflows/ nello spazio di lavoro. L’esistenza della cartella dichiara il flusso: non serve un manifest separato.

my-workspace/
  scripts/              # Script globali
  lib/                  # Librerie condivise
  views/                # Viste di coda globali
  events.json           # Trigger globali
  queues.json           # Pool di processi di lavoro globali
  tools.json            # Strumenti MCP globali
  store.db              # Archivio documenti condiviso
  queue.db              # Code di lavoro condivise
  workflow-ledger.db    # Cronologia condivisa di esecuzioni/elementi
  search-index/         # Indice di ricerca condiviso
  workflows/
    job-validation/
      events.json       # Attivo solo quando questo flusso è selezionato
      queues.json       # Attivo solo quando questo flusso è selezionato
      tools.json        # Attivo solo quando questo flusso è selezionato
      views/
        review.json
      scripts/
        enqueue.js
        check.js
    rss-pipeline/
      events.json
      scripts/
        scrape.js

Caricamento a due livelli

Guida carica la configurazione in due livelli:

1. Globale — events.json, queues.json, tools.json e views/ nel percorso principale (root) sono sempre attivi, indipendentemente dal flusso di lavoro selezionato.
2. Flusso di lavoro — le configurazioni del flusso attivo vengono caricate sopra il livello globale.

Solo un flusso di lavoro è attivo alla volta. Le configurazioni globali non vengono mai modificate dai cambi di flusso.

Cambio flusso di lavoro

Seleziona un flusso di lavoro dal menu a discesa della barra strumenti, visibile quando lo spazio di lavoro contiene una cartella workflows/. Scegli “Nessuno” (None) per eseguire solo configurazioni globali.

Puoi cambiare flusso anche da script o MCP:

// Da uno script
g.workflows.switch("job-validation");

Quando cambi flusso di lavoro:

• I trigger del flusso precedente vengono disattivati
• I pool di processi di lavoro del flusso precedente vengono fermati; gli elementi già in corso finiscono
• I trigger e i processi di lavoro del nuovo flusso vengono attivati
• Le configurazioni globali restano invariate

Creazione di un flusso di lavoro

Fai clic con il tasto destro nel pannello Spazio di lavoro (Workspace) e seleziona Nuovo flusso di lavoro (New Workflow). Inserisci un nome e, facoltativamente, scegli un modello:

• Vuoto (Blank) — cartella di flusso vuota con scripts/
• Scraper — generatore di evento, pool di processi di lavoro e vista di coda
• Monitor — trigger url-match per monitorare pagine
• Processore (Processor) — flusso basato su code con viste

Risorse condivise

Tutti i flussi di lavoro in uno spazio di lavoro condividono lo stesso livello dati:

• Archiviazione (Store, store.db) — stesso archivio documenti per tutti i flussi
• Code (queue.db) — le code sono condivise; i flussi possono elaborare elementi di coda creati da altri flussi
• Registro di tracciabilità dei flussi di lavoro (workflow-ledger.db) — la cronologia di esecuzioni/elementi è condivisa e segmentata per nome del flusso
• Indice di ricerca — indice testuale condiviso
• Librerie condivise — usa import standard (JS), require() (Lua) o (import ...) (Janet) per condividere codice tra script. Sono disponibili anche le librerie globali nella cartella lib/ del percorso principale (root) dello spazio di lavoro.

Questo significa che un flusso di estrazione può mettere in coda elementi che un flusso di elaborazione raccoglie, senza copiare dati.

Workflow Control Console

La Workflow Control Console è la vista operativa per spazi di lavoro grandi, in cui molte cartelle di flusso di lavoro, moduli crawler, code e fasi del registro appartengono a una sola operazione reale.

Aprila da View > Workflow Control Console. Non sostituisce la Queue Console o la Workflow Ledger Console. Offre invece all’operatore un punto unico per rispondere a domande come:

• Quale operazione sta cercando di eseguire questo spazio di lavoro?
• Il flusso di lavoro attivo è quello corretto?
• Esiste uno script di ingresso, o questa operazione è solo riprendibile/ispezionabile?
• Quali code e pool di processi di lavoro sono attesi?
• Quale fase, modulo o passaggio tra fasi richiede attenzione?
• Dove conviene entrare nel dettaglio: coda, registro, runbook o script?

La console è basata sulle prove disponibili. Apre dettagli di coda e registro quando ha una coda, fase, stato, filtro rapido o termine di ricerca utile. Evita di presentare lo stato solo nel registro come se fosse lavoro eseguibile in coda.

workflow-operations.json

Crea workflows/workflow-operations.json per descrivere operazioni a livello di operatore. I campi sono opzionali a meno che l’operazione ne abbia bisogno; un’operazione minima può comunque essere caricata senza 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"]
    }
  ]
}

Campi utili dell’operazione:

Campo	Significato
workflowName	Flusso di lavoro che deve essere attivo per avvii diretti
entryScript	Script di avvio opzionale; omettilo per operazioni solo di ispezione, ripresa o ripristino
summary, help, prerequisites	Runbook e guida per l’operatore
expectedQueues, expectedWorkerPools	Prove di code/processi di lavoro che la console dovrebbe cercare
phases	Fasi principali del lavoro, di solito collegate a code, processi e fasi del registro
focusAreas	Porzioni azionabili dentro un’operazione, come backlog, elementi pronti per nuovo tentativo o passaggi tra fasi
actions	Azioni operative supportate, come avvio, ripresa dei processi, apertura coda, apertura registro o apertura script
preflightChecks	Elenco opzionale dei controlli preliminari (preflight) da visualizzare; omettilo per mostrare il set predefinito

Le operazioni senza entryScript sono valide. La console le tratta come superfici di ispezione, ripresa o ripristino e non genera un’azione di avvio, salvo che il manifest la definisca esplicitamente; in quel caso resta visibile ma disabilitata con una motivazione.

Runbook e controlli preliminari

I campi del runbook spiegano scopo, quando eseguire, cosa fa l’operazione, input, risultato atteso, avvisi e risoluzione dei problemi. Sono opzionali, ma descrizioni dettagliate aiutano quando uno spazio di lavoro contiene molti crawler specializzati e molte code.

I controlli preliminari mostrano se lo spazio di lavoro è aperto, il manifest è stato caricato, il flusso è noto, il flusso attivo corrisponde, lo script di ingresso esiste, il registro è disponibile, le code esistono, i pool di processi sono noti e sono presenti elementi del registro che richiedono attenzione.

Il preflight è guida più sicurezza. Nascondere una riga con preflightChecks cambia la scheda visualizzata, non le regole rigide che impediscono di avviare uno script sotto il flusso di lavoro sbagliato.

Fasi, focus area e passaggi tra fasi

Le fasi modellano i passaggi principali dell’operazione. Le focus area modellano porzioni azionabili dentro quei passaggi: backlog fetch, lavoro pronto per nuovo tentativo, code degli scarti, backlog parse/index o un passaggio tra fasi che richiede ispezione.

I passaggi tra fasi descrivono transizioni tra fasi, per esempio da fetch a parse_index. La console confronta conteggi del registro a monte e a valle, così l’operatore può capire se il lavoro si è fermato tra due fasi.

Usa focus area per lavoro di riparazione e ripresa invece di creare finte operazioni di primo livello. Così il lato sinistro della console resta concentrato sulle vere operazioni, senza nascondere il lavoro che richiede attenzione.

workflow-map.json

Usa workflows/workflow-map.json quando uno spazio di lavoro contiene molte cartelle di flusso di lavoro ma solo pochi sistemi a livello operativo. La mappa raggruppa i flussi in sistemi, pipeline, gruppi di moduli, fasi, code, processi, operazioni e passaggi tra fasi.

{
  "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"]
        }
      ]
    }
  ]
}

Il progresso dei moduli viene calcolato dagli aggregati del registro per l’esecuzione selezionata, non dalla pagina di elementi visibile. I moduli senza prove nel registro sono mostrati come non tentati, così l’operatore può decidere se siano stati saltati intenzionalmente, non ancora messi in coda o mancanti dall’esecuzione.

API di scripting

// Controlla cosa è attivo
const active = g.workflows.getActive();
if (active) g.log("Flusso corrente: " + active.name);

// Elenca tutti i flussi di lavoro
const workflows = g.workflows.list();
for (const w of workflows) {
  g.log(w.name + " — " + w.scriptCount + " script" +
    (w.hasEvents ? ", con trigger" : ""));
}

// Cambia flusso, senza attendere
g.workflows.switch("rss-pipeline");

Vedi il Riferimento API per le firme complete dei metodi.

Passi successivi

• Spazi di lavoro — struttura dello spazio di lavoro e file di configurazione
• Processi di lavoro delle code — pool di processi a livello globale o di flusso
• Registro di tracciabilità dei flussi di lavoro — visibilità persistente su esecuzioni ed elementi
• Strumenti personalizzati — definisci strumenti MCP per singolo flusso di lavoro