Warteschlangen-Worker

Warteschlangen-Worker verarbeiten Items aus Arbeitswarteschlangen mit parallelen Browser-Tabs. Jeder Worker erhält einen eigenen Tab, nimmt Items aus der Queue, führt ein Skript aus und markiert das Ergebnis als abgeschlossen oder abgebrochen.

Konzept

1. Sie stellen Arbeitsitems in eine Queue: URLs, Datensätze oder Aufgaben.
2. Worker entnehmen Items und verarbeiten sie jeweils in einem Browser-Tab.
3. Das Skript liest g.worker.getContext(), erledigt die Arbeit und ruft g.queue.commit() oder g.queue.abort() auf.

Worker deklarieren

Legen Sie im Arbeitsbereich eine queues.json an:

{
  "pools": [
    {
      "queue": "urls",
      "script": "scripts/process-url.js",
      "concurrency": 3,
      "throttle": 30,
      "layout": "horizontal",
      "clearTabs": true
    }
  ]
}

Feld	Erforderlich	Standard	Bedeutung
queue	Ja	-	Zu verarbeitende Queue
script	Ja	-	Skriptpfad relativ zum Arbeitsbereich
concurrency	Nein	1	Anzahl paralleler Worker/Tabs
throttle	Nein	60	Maximale Entnahmen pro Minute und Worker
layout	Nein	-	Tab-Layout: horizontal, vertical oder quad
clearTabs	Nein	false	Vor dem Start vorhandene Tabs schließen
requiresWorkflowEnvelope	Nein	false	Queue-Items müssen Workflow-Ledger-Metadaten enthalten

Deklarierte Pools lassen sich aus der Queue Console, dem Queues-Panel oder über MCP-Werkzeuge starten.

Programmatisch starten

async function main() {
  for (let i = 1; i <= 100; i++) {
    g.queue.enqueue("pages", {
      url: "https://example.com/page/" + i
    });
  }

  g.workers.start({
    clearTabs: true,
    layout: "horizontal",
    workers: [
      {
        queue: "pages",
        script: "scripts/scrape-page.js",
        concurrency: 4,
        throttle: { requestsPerMinute: 20 },
        requiresWorkflowEnvelope: false
      }
    ]
  });
}

g.workers.start() startet Worker unabhängig vom Skript, das sie auslöst.

Skript pro Item

Jeder Worker führt Ihr Skript einmal pro Queue-Item aus:

scripts/scrape-page.js

async function main() {
  const ctx = g.worker.getContext();
  const { item, tabId } = ctx;

  await g.nav.navigateToUrl(item.data.url, { browserTabId: tabId });
  await g.dom.waitForDomStable({ browserTabId: tabId });

  const title = await g.dom.extractContent("h1", { browserTabId: tabId });

  g.store.put("results", item.data.url, {
    title,
    scrapedAt: new Date().toISOString()
  });

  g.queue.commit(item.id);
}

Es gibt kein automatisches Commit. Das Skript muss jedes Item explizit abschließen oder abbrechen.

Fehler und Fehlerwarteschlangen

Wenn ein Item abgebrochen wird und maxRetries überschritten ist, landet es in der Fehlerwarteschlange (dead_{queueName}). Dort kann es geprüft und erneut versucht werden.

const deadItems = g.queue.deadLetter("pages");
g.log("Fehlgeschlagene Items: " + deadItems.length);

g.queue.retry("pages", deadItems[0].deadLetterId);

Worker steuern

Methode	Beschreibung
g.workers.stop()	Alle Worker stoppen
g.workers.stop("pages")	Worker einer bestimmten Queue stoppen
g.workers.pause()	Entnahmen pausieren; laufende Items beenden
g.workers.resume()	Entnahmen fortsetzen
g.workers.status()	Zustand aller Pools abfragen

Der Status nennt neben Zustand, Parallelität und Durchsatz auch inFlightItems, remainingKnown, eligibleRemaining, heldItemCount, heldGroupCount, nextEligibleAt, waitingReason, activeRunOneCount und runOneTaskId. Zeigen Sie remaining nur dann als exakte Tiefe, wenn remainingKnown wahr ist. Workflow-Holds und Queue-Gruppen-Cooldowns können Arbeit vorübergehend von eligibleRemaining ausschließen; das ist weder ein Fehler noch ein Beleg dafür, dass der Pool fertig ist.

Betrieb

Jede Worker-Item-Ausführung erscheint als Aufgabe im Task-Manager. Für täglichen Queue-Betrieb ist die Queue Console gedacht: Zählungen, Pending-Items, Fehlerwarteschlangen, Payloads, Worker-Zustand und Links zu Workflow-Ledger-Items.

Wenn ein Worker-Skript nach dem Checkout fehlschlägt, versucht Guida das Checkout abzubrechen, damit Arbeit nicht dauerhaft steckt. Bei Workflow-eigenen Queues kann requiresWorkflowEnvelope: true erzwingen, dass Items workflowName, runId, itemId und itemKey enthalten.

Das ist wichtig für lange Crawls, bei denen ausführbare Queue-Arbeit und Workflow Ledger-Wahrheit synchron bleiben müssen.

Queue- und Ledger-Ergebnisse werden ausdrücklich abgeglichen. Eine leere Queue oder ein gestoppter Pool beweist für sich allein nicht, dass alle Items erfolgreich waren.

Manuelle Prüfung

Für Queues, die menschliche Entscheidungen brauchen, bieten Review-Ansichten Aktionsbuttons, Tastenkürzel und Multi-Tab-Review. Siehe Warteschlangen und Prüfung.

Nächste Schritte

• Warteschlangen und Prüfung - Queues betreiben und Payloads prüfen
• Workflow Ledger - dauerhafte Workflow-Wahrheit prüfen
• Workflows - Operationen und Queue/Ledger-Handoffs modellieren
• URLs in eine Warteschlange stellen und verarbeiten
• Parallele Worker ausführen