Flux de travail

Un flux de travail est un sous-dossier nommé dans workflows/ qui regroupe scripts associés, déclencheurs d’événements, pools de processus, outils MCP et vues de file dans une unité d’automatisation autonome. Les flux permettent d’exécuter plusieurs pipelines dans un seul espace de travail sans qu’ils se gênent.

Pour les flux de longue durée, Guida peut aussi maintenir un registre de traçabilité des flux de travail durable avec exécutions, éléments, étapes, états, événements, résultats liés, prises en charge, réessais et actions de récupération.

Structure des dossiers

Les flux vivent sous workflows/ dans votre espace de travail. L’existence du dossier déclare le flux : aucun manifeste séparé n’est nécessaire.

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

Chargement en deux niveaux

Guida charge la configuration en deux niveaux :

Global — events.json, queues.json, tools.json et views/ à la racine sont toujours actifs, quel que soit le flux sélectionné.
Flux — les configurations du flux actif sont chargées au-dessus de la couche globale.

Un seul flux est actif à la fois. Les configurations globales ne sont jamais affectées par les changements de flux.

Changer de flux

Sélectionnez un flux depuis la liste de la barre d’outils, visible lorsque l’espace de travail contient un dossier workflows/. Choisissez « None » pour fonctionner uniquement avec les configurations globales.

Vous pouvez aussi changer de flux depuis des scripts ou MCP :

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

Lorsque vous changez de flux :

les déclencheurs du flux précédent sont désactivés ;
les pools de processus du flux précédent sont arrêtés, les éléments en cours se terminant ;
les déclencheurs et processus du nouveau flux sont activés ;
les configurations globales restent inchangées.

Créer un flux

Faites un clic droit dans le panneau Workspace et sélectionnez New Workflow. Entrez un nom et choisissez éventuellement un modèle :

Blank — dossier de flux vide avec scripts/
Scraper — déclencheur d’événement, pool de processus et vue de file
Monitor — déclencheurs url-match pour surveiller des pages
Processor — pipeline appuyé par des files avec vues

Ressources partagées

Tous les flux d’un espace de travail partagent la même couche de données :

Store (store.db) — même stockage de documents pour tous les flux
Queues (queue.db) — files partagées ; les flux peuvent traiter les éléments de file les uns des autres
Workflow Ledger (workflow-ledger.db) — historique des exécutions et éléments partagé, avec portée par nom de flux
Search Index — index plein texte partagé
Bibliothèques partagées — utilisez import (JS), require() (Lua) ou (import ...) (Janet) pour partager du code entre scripts. Les bibliothèques globales du dossier racine lib/ sont aussi disponibles.

Cela signifie qu’un flux de scraping peut mettre en file des éléments qu’un flux de traitement récupère, sans copie de données.

Workflow Control Console

La Workflow Control Console est la vue opérateur des grands espaces de travail où de nombreux dossiers de flux, modules de crawler, files et étapes du registre appartiennent à une même opération réelle.

Ouvrez-la depuis View > Workflow Control Console. Elle ne remplace pas la Queue Console ni la Workflow Ledger Console. Elle donne plutôt à l’opérateur un endroit unique pour répondre à ces questions :

Quelle opération cet espace de travail essaie-t-il d’exécuter ?
Le flux actif est-il le bon ?
Existe-t-il un script d’entrée, ou cette opération sert-elle seulement à reprendre et inspecter ?
Quelles files et quels pools de processus sont attendus ?
Quelle phase, quel module ou quel passage demande attention ?
Où faut-il creuser ensuite : file, registre, runbook ou script ?

La console est pilotée par les données de traçabilité. Elle lie vers les détails de file et de registre lorsqu’elle dispose d’une file, étape, état, filtre rapide ou terme de recherche utile. Elle évite de faire passer un état présent seulement dans le registre pour du travail exécutable en file.

`workflow-operations.json`

Créez workflows/workflow-operations.json pour décrire les opérations de niveau opérateur. Les champs sont facultatifs sauf si votre opération en a besoin ; une opération minimale peut se charger sans runbook complet.

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

Champs d’opération utiles :

Champ	Signification
`workflowName`	Flux qui doit être actif pour les démarrages directs
`entryScript`	Script de démarrage facultatif ; omettez-le pour les opérations uniquement inspectables, reprenables ou récupérables
`summary`, `help`, `prerequisites`	Runbook et consignes opérateur
`expectedQueues`, `expectedWorkerPools`	Données de file/processus que la console doit rechercher
`phases`	Grandes étapes de travail, généralement liées à des files, processus et étapes du registre
`focusAreas`	Tranches actionnables dans une opération : backlog, travail prêt à réessayer ou passage
`actions`	Actions opérateur prises en charge : start, resume workers, open queue, open ledger ou open script
`preflightChecks`	Liste facultative de lignes de contrôle préliminaire à afficher ; omettez-la pour afficher l’ensemble par défaut

Les opérations sans entryScript sont valides. La console les traite comme des surfaces d’inspection, reprise ou récupération et ne génère pas d’action Start sauf si un manifeste en définit une explicitement ; elle est alors désactivée avec une raison.

Runbook et contrôles préliminaires

Les champs de runbook expliquent l’objectif, quand exécuter l’opération, ce qu’elle fait, ses entrées, le résultat attendu, les avertissements et le dépannage. Ils sont facultatifs, mais des descriptions détaillées aident quand un espace de travail contient beaucoup de crawlers et files spécialisés.

Les lignes de contrôles préliminaires indiquent si l’espace de travail est ouvert, si le manifeste est chargé, si le flux est connu, si le flux actif correspond, si le script d’entrée existe, si le registre est disponible, si les files existent, si les pools sont connus et si le registre signale une attention.

Les contrôles préliminaires sont de la guidance et de la sécurité. Masquer une ligne avec preflightChecks change l’onglet affiché, pas les règles strictes autour du démarrage d’un script sous le mauvais flux.

Phases, focus areas et passages

Les phases modélisent les grandes étapes de l’opération. Les focus areas modélisent les tranches actionnables dans ces étapes : backlog de récupération, travail prêt à réessayer, rejets, backlog parse/index ou passage à inspecter.

Les passages décrivent les transitions entre étapes, par exemple de fetch vers parse_index. La console compare les compteurs du registre en amont et en aval pour que l’opérateur voie si le travail s’est arrêté entre phases.

Utilisez les focus areas pour le travail de réparation et de reprise plutôt que de créer de fausses opérations de premier niveau. Cela garde la partie gauche de la console centrée sur les vraies opérations tout en faisant remonter le travail qui demande attention.

`workflow-map.json`

Utilisez workflows/workflow-map.json quand un espace de travail contient beaucoup de dossiers de flux mais seulement quelques systèmes de niveau opérateur. La carte groupe les flux en systèmes, pipelines, groupes de modules, étapes, files, processus, opérations et passages.

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

La progression des modules est calculée depuis les agrégats du registre pour l’exécution sélectionnée, pas depuis la page d’éléments visible. Les modules sans preuve dans le registre sont affichés comme non tentés, afin que l’opérateur décide s’ils ont été ignorés volontairement, pas encore mis en file ou manquants dans l’exécution.

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");

Voir la référence API pour les signatures complètes.

Étapes suivantes

Espaces de travail — structure et fichiers de configuration d’un espace de travail
Processus de travail des files d’attente — pools au niveau global ou du flux
Registre de traçabilité des flux de travail — visibilité durable sur exécutions et éléments
Outils personnalisés — définir des outils MCP par flux