Workflows

Ein Workflow ist ein benannter Unterordner in workflows/, der zusammengehörige Skripte, Ereignisauslöser, Worker-Pools, MCP-Werkzeuge und Queue-Ansichten zu einer eigenständigen Automatisierungseinheit bündelt. So können mehrere Pipelines in einem Arbeitsbereich laufen, ohne sich gegenseitig zu stören.

Für lange Workflows kann Guida außerdem ein dauerhaftes Workflow Ledger mit Runs, Items, Stages, States, Events, verknüpften Ausgaben, Leases, Wiederholungen und Wiederherstellungsaktionen pflegen.

Ordnerstruktur

Workflows liegen unter workflows/ im Arbeitsbereich. Der Ordner deklariert den Workflow; ein separates Manifest ist nicht nötig.

my-workspace/
  scripts/
  lib/
  views/
  events.json
  queues.json
  tools.json
  store.db
  queue.db
  workflow-ledger.db
  search-index/
  workflows/
    job-validation/
      events.json
      queues.json
      tools.json
      views/
        review.json
      scripts/
        enqueue.js
        check.js
    rss-pipeline/
      events.json
      scripts/
        scrape.js

Zweistufiges Laden

Guida lädt Konfiguration in zwei Stufen:

1. Global - events.json, queues.json, tools.json und views/ im Arbeitsbereichsstamm sind immer aktiv.
2. Workflow - Konfiguration des aktiven Workflows wird darübergelegt.

Nur ein Workflow ist gleichzeitig aktiv. Globale Konfiguration bleibt beim Wechsel unverändert.

Workflow wechseln

Wählen Sie den Workflow in der Toolbar-Dropdownliste. None nutzt nur globale Konfiguration.

g.workflows.switch("job-validation");

Beim Wechsel werden Trigger des vorherigen Workflows deaktiviert, dessen Worker-Pools gestoppt, Trigger und Worker des neuen Workflows aktiviert und globale Konfiguration beibehalten.

Workflow erstellen

Im Workspace-Panel können Sie New Workflow wählen. Vorlagen sind:

• Blank - leerer Workflow-Ordner mit scripts/
• Scraper - Ereignisauslöser, Worker-Pool und Queue-Ansicht
• Monitor - URL-Match-Trigger für Seitenbeobachtung
• Processor - queue-basierte Pipeline mit Ansichten

Gemeinsame Ressourcen

Alle Workflows teilen dieselbe Datenschicht:

• Store (store.db) - gemeinsamer Dokumentenspeicher
• Queues (queue.db) - gemeinsame Warteschlangen
• Workflow Ledger (workflow-ledger.db) - Run-/Item-Historie, nach Workflow-Namen scopingfähig
• Search Index - gemeinsamer Volltextindex
• Shared Libraries - gemeinsame Bibliotheken über import, require() oder (import ...)

Ein Scraping-Workflow kann also Items einreihen, die ein Verarbeitungsworkflow später übernimmt.

Workflow Control Console

Die Workflow Control Console ist die Operator-Ansicht für große Arbeitsbereiche, in denen viele Workflow-Ordner, Crawler-Module, Queues und Ledger-Stages zu einer realen Operation gehören.

Sie ersetzt nicht die Queue Console und nicht die Workflow Ledger Console. Sie beantwortet stattdessen:

• Welche Operation soll dieser Arbeitsbereich ausführen?
• Ist der aktive Workflow korrekt?
• Gibt es ein Startskript, oder ist die Operation nur prüfbar/wiederaufnehmbar?
• Welche Queues und Worker-Pools werden erwartet?
• Welche Phase, welches Modul oder welcher Handoff braucht Aufmerksamkeit?
• Wohin soll der Operator springen: Queue, Ledger, Runbook oder Skript?

Die Konsole ist evidenzgetrieben. Sie verlinkt auf Queue- und Ledger-Details, wenn Queue, Stage, State, Schnellfilter oder Suchbegriff hilfreich sind. Ledger-Zustand wird nicht als ausführbare Queue-Arbeit ausgegeben.

workflow-operations.json

workflows/workflow-operations.json beschreibt Operationen auf Operator-Ebene:

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

Wichtige Felder:

Feld	Bedeutung
workflowName	Workflow, der für direkte Starts aktiv sein muss
entryScript	Optionales Startskript; weglassen für reine Inspect/Resume/Recovery-Operationen
summary, help, prerequisites	Runbook und Operatorhinweise
expectedQueues, expectedWorkerPools	Queue-/Worker-Evidenz
phases	Hauptphasen, meist mit Queues, Workern und Ledger-Stages verbunden
focusAreas	Handlungsbereiche wie Backlog, retry-ready Arbeit oder Handoff
actions	Operatoraktionen wie Start, Resume Workers, Open Queue, Open Ledger oder Open Script
preflightChecks	Optionale eingebaute Vorabprüfungen

Operationen ohne entryScript sind gültig. Die Konsole behandelt sie als Inspect/Resume/Recovery-Oberflächen.

Runbook und Preflight

Runbook-Felder erklären Zweck, Zeitpunkt, Eingaben, erwartetes Ergebnis, Warnungen und Troubleshooting. Preflight-Zeilen prüfen unter anderem Arbeitsbereich, Manifest, aktiven Workflow, Startskript, Ledger, Queues, Worker-Pools und Ledger-Aufmerksamkeit.

Preflight ist Anleitung plus Sicherheit. Sichtbare Zeilen zu reduzieren ändert nicht die harten Sicherheitsregeln rund um Start unter falschem Workflow.

Phasen, Fokusbereiche und Handoffs

Phasen modellieren Hauptschritte. Fokusbereiche modellieren umsetzbare Ausschnitte: Fetch-Backlog, retry-ready Arbeit, Fehlerwarteschlangen, Parse/Index-Backlog oder einen Handoff, der Prüfung braucht.

Handoffs beschreiben Übergänge wie fetch zu parse_index. Die Konsole vergleicht Upstream- und Downstream-Ledger-Zählungen, damit sichtbar wird, ob Arbeit zwischen Phasen hängen bleibt.

workflow-map.json

workflows/workflow-map.json gruppiert viele Workflow-Ordner in Systeme, Pipelines, Modulgruppen, Stages, Queues, Worker, Operationen und Handoffs. Das ist nützlich, wenn ein Arbeitsbereich viele spezialisierte Crawler enthält, aber nur wenige Operator-Systeme.

Scripting-API

const workflows = g.workflows.list();
g.workflows.switch("careers-crawl");
const active = g.workflows.getActive();
g.log("Aktiver Workflow: " + active.name);

Nächste Schritte

• Workflow Ledger - dauerhafte Run-/Item-Wahrheit
• Warteschlangen und Prüfung - ausführbare Queue-Arbeit betreiben
• Warteschlangen-Worker - Worker-Pools konfigurieren
• Arbeitsbereiche - Arbeitsbereichsstruktur verstehen