Extratores

Um extrator é um componente reutilizável, identificado por um nome estável, que coleta um tipo específico de dado. No Guida 0.9, os descritores ficam no espaço de trabalho. O Guida os carrega em um catálogo pesquisável e permite validar, certificar e comparar resultados sem depender de listas informais.

O Guida Complete e o Guida Node executam os extratores. Guida Control apresenta os mesmos contratos por Remote Ops, sem manter um segundo catálogo.

Descritor e implementação

O descritor é o contrato público. Ele identifica implementação, origem, fluxo de trabalho, fila, entrada padrão, domínios de destino, contrato de saída e evidências exigidas. A implementação continua sendo código comum do espaço de trabalho.

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

Um pequeno arquivo raiz extractors.json pode incluir descritores, escolher perfis comuns e dividir um catálogo grande em partições determinísticas. Cada entrada preserva a própria identidade e o caminho de origem.

Contratos antes da execução

A validação encontra descritores inválidos, IDs duplicados, implementações ausentes, perfis não resolvidos, regras de domínio incorretas e contratos de entrada ou saída incompatíveis. As verificações de compatibilidade tornam explícito o limite entre um extrator e quem consome seus resultados.

A API de scripts oferece leitura síncrona com g.extractors.list(), g.extractors.get() e g.extractors.validate(). Clientes remotos usam workspace.extractors.* e workspace.extractors.contracts.*.

Certificação com evidências

A certificação é uma verificação operacional limitada, não um selo permanente. Quick verifica deliberadamente poucos destinos e fornece retorno rápido; Coverage amplia a verificação dentro dos limites declarados. Um resultado vazio só é aceitável com evidência de carregamento e permissão explícita no descritor. A evidência de seletores precisa ser observada. O Guida registra integridade e truncamento para não apresentar uma verificação parcial como cobertura completa.

Comece com workspace.extractors.certification.plan. O plano separa itens executáveis e bloqueados e mostra os limites aplicados. Iniciar, cancelar e exportar evidências continua sujeito às regras e confirmações locais do Guida.

O Guida separa o resultado mais recente do histórico que o explica. Execuções, resultados por extrator, estatísticas, anomalias, mudanças de contrato e evidências exportadas ficam disponíveis para análise. A política de retenção fica no espaço de trabalho e os dados operacionais, em operations.db.

O catálogo e as interfaces operacionais foram validados com 5.000 extratores em testes determinísticos em um único host. Isso não promete 5.000 sessões de navegador simultâneas nem representa a capacidade de uma frota Enterprise.

Uma pipeline semântica conecta a saída contratada a validadores, mapeadores e destinos. Pipelines geradas usam associações explícitas, como $extractor.id; o Guida não deduz significado de nomes de arquivos ou pastas.