Extraktoren

Ein Extraktor ist eine benannte, wiederverwendbare Komponente zum Erfassen einer bestimmten Art von Daten. In Guida 0.9 liegen seine Deskriptoren im Arbeitsbereich. Guida lädt sie in einen durchsuchbaren Katalog und macht Validierung, Zertifizierung, Vergleiche und Betriebsergebnisse nachvollziehbar.

Guida Complete und Guida Node führen Extraktoren aus. Guida Control zeigt dieselben Verträge über Remote Ops an, führt aber keinen zweiten Katalog.

Deskriptor und Implementierung

Der Deskriptor ist der öffentliche Vertrag. Er benennt Implementierung, Quelle, Workflow, Queue, Standardeingaben, Zieldomains, Ausgabevertrag und geforderte Nachweise. Die Implementierung bleibt normaler Code im Arbeitsbereich.

{
  "$schema": "../../../extractors.schema.json",
  "id": "careers.example.jobs",
  "profile": "web.discovery.browser",
  "label": "Example engineering jobs",
  "domain": "careers",
  "workflowName": "careers-example",
  "queueName": "careers_example",
  "implementation": {
    "module": "lib/careers-example-worker.js",
    "export": "discoverExampleJobs",
    "language": "javascript"
  },
  "source": {
    "kind": "web",
    "url": "https://example.com/careers"
  },
  "targetDomains": ["example.com"],
  "input": {
    "defaultUrl": "https://example.com/careers",
    "defaultCompanyName": "Example",
    "defaultSlug": "example"
  },
  "evidence": {
    "requiresPageLoaded": true,
    "requiresResultEvidence": true,
    "allowQualifiedEmpty": true
  }
}

Eine kleine Stammdatei extractors.json kann Deskriptordateien einbinden, gemeinsame Profile wählen und einen großen Katalog in deterministische Shards teilen. Jeder Eintrag behält seine eigene Identität und seinen Quellpfad.

Verträge vor der Ausführung

Die Validierung findet fehlerhafte Deskriptoren, doppelte IDs, fehlende Implementierungen, nicht aufgelöste Profile, ungültige Domainregeln und unvereinbare Ein- oder Ausgabeverträge. Kompatibilitätsprüfungen machen die Grenze zwischen Extraktor und Verbraucher ausdrücklich sichtbar.

Für synchrone, schreibgeschützte Katalogabfragen stehen g.extractors.list(), g.extractors.get() und g.extractors.validate() bereit. Remote-Clients verwenden workspace.extractors.* und workspace.extractors.contracts.*.

Zertifizierung mit Nachweisen

Zertifizierung ist eine begrenzte betriebliche Prüfung, kein dauerhaftes Gütesiegel. Quick prüft bewusst wenige Ziele für eine schnelle Rückmeldung; Coverage erweitert die Prüfung innerhalb klarer Grenzen. Ein leeres Ergebnis gilt nur mit Lade- und Ergebnisnachweis als zulässig. Selektornachweise müssen beobachtet sein. Vollständigkeit und Kürzung einer Traversierung werden gespeichert, damit eine Teilprüfung nicht als volle Abdeckung erscheint.

Plane zuerst mit workspace.extractors.certification.plan. Der Plan nennt ausführbare und blockierte Einträge sowie die geltenden Grenzen. Start, Abbruch und Nachweisexport bleiben durch Guidas lokale Richtlinien und Bestätigungen geschützt.

Guida trennt das jüngste Prüfergebnis von seinem Verlauf. Läufe, Einzelergebnisse, Statistiken, Auffälligkeiten, Vertragsänderungen und exportierte Nachweise bleiben prüfbar. Die Aufbewahrungsregeln liegen im Arbeitsbereich, die Betriebsdaten in operations.db.

Katalog und Bedienoberflächen wurden mit 5.000 Extraktoren in deterministischen Tests auf einem einzelnen Host validiert. Das ist keine Zusage für 5.000 gleichzeitige Browsersitzungen oder eine Enterprise-Flotte.

Ein Extraktor liefert Daten nach Vertrag. Eine semantische Pipeline verbindet sie mit Validierungsstufen, Mappern und Zielen. Generierte Pipelines verwenden ausdrückliche Bindungen wie $extractor.id; Guida leitet keine Bedeutung aus Datei- oder Verzeichnisnamen ab.