Fluxos de trabalho

Um fluxo de trabalho é uma subpasta nomeada dentro de workflows/ que agrupa scripts relacionados, gatilhos de eventos, grupos de processos de trabalho, ferramentas MCP e visões de fila em uma unidade autônoma de automação. Fluxos permitem executar várias cadeias de automação dentro de um único espaço de trabalho sem que elas interfiram entre si.

Para fluxos longos, o Guida também pode manter um registro de rastreabilidade dos fluxos de trabalho durável com execuções, itens, estágios, estados, eventos, saídas vinculadas, reservas de execução, tentativas e ações de recuperação.

Estrutura de pastas

Fluxos ficam em workflows/ no espaço de trabalho. A existência da pasta declara o fluxo; não é necessário manifesto separado:

my-workspace/
  scripts/              # Scripts globais
  lib/                  # Bibliotecas compartilhadas
  views/                # Visões globais de fila
  events.json           # Gatilhos globais
  queues.json           # Grupos globais de processos de trabalho
  tools.json            # Ferramentas MCP globais
  store.db              # Armazenamento compartilhado de documentos
  queue.db              # Filas de trabalho compartilhadas
  workflow-ledger.db    # Histórico compartilhado de execuções/itens
  search-index/         # Índice de pesquisa compartilhado
  workflows/
    job-validation/
      events.json       # Ativo apenas quando este fluxo é selecionado
      queues.json       # Ativo apenas quando este fluxo é selecionado
      tools.json        # Ativo apenas quando este fluxo é selecionado
      views/
        review.json
      scripts/
        enqueue.js
        check.js
    rss-pipeline/
      events.json
      scripts/
        scrape.js

Carregamento em duas camadas

O Guida carrega configuração em duas camadas:

Global — events.json, queues.json, tools.json e views/ na raiz ficam sempre ativos, independentemente do fluxo selecionado.
Fluxo — as configurações do fluxo ativo são carregadas sobre a camada global.

Apenas um fluxo fica ativo por vez. Configurações globais nunca são afetadas por mudanças de fluxo.

Trocar de fluxo

Selecione um fluxo no menu suspenso da barra de ferramentas, visível quando o espaço de trabalho tem um diretório workflows/. Escolha “None” para rodar apenas com configurações globais.

Você também pode trocar por scripts ou MCP:

// A partir de um script
g.workflows.switch("job-validation");

Ao trocar de fluxo:

Gatilhos do fluxo anterior são desativados
Grupos de processos de trabalho do fluxo anterior são parados; itens em andamento terminam
Gatilhos e processos de trabalho do novo fluxo são ativados
Configurações globais permanecem inalteradas

Criar um fluxo

Clique com o botão direito no painel Workspace e selecione New Workflow. Informe um nome e, opcionalmente, escolha um modelo:

Blank — pasta de fluxo vazia com scripts/
Scraper — gatilho de evento + grupo de processos de trabalho + visão de fila
Monitor — gatilhos url-match para observar páginas
Processor — fluxo baseado em filas com visões

Recursos compartilhados

Todos os fluxos em um espaço de trabalho compartilham a mesma camada de dados:

Armazenamento (store.db) — mesmo armazenamento de documentos para todos os fluxos
Filas (queue.db) — filas são compartilhadas; fluxos podem processar itens uns dos outros
Registro de rastreabilidade (workflow-ledger.db) — histórico de execuções/itens é compartilhado e tem escopo por nome de fluxo
Índice de pesquisa — índice de texto completo compartilhado
Bibliotecas compartilhadas — use import padrão (JS), require() (Lua) ou (import ...) (Janet) para compartilhar código entre scripts. Bibliotecas globais na pasta lib/ da raiz também ficam disponíveis.

Isso permite que um fluxo de extração enfileire itens que um fluxo de processamento consome, sem copiar dados.

Workflow Control Console

O Workflow Control Console é a visão de operador para espaços de trabalho grandes em que muitas pastas de fluxo, módulos de rastreamento, filas e estágios do registro pertencem a uma mesma operação real.

Abra por View > Workflow Control Console. Ele não substitui o Queue Console nem o console do registro de rastreabilidade. Em vez disso, oferece ao operador um lugar para responder:

Que operação este espaço de trabalho está tentando executar?
O fluxo ativo está correto?
Existe um script de entrada ou esta operação é apenas retomável/inspecionável?
Quais filas e grupos de processos de trabalho são esperados?
Qual fase, módulo ou passagem precisa de atenção?
Onde devo investigar em seguida: fila, registro, runbook ou script?

O console é orientado por evidências. Ele vincula a detalhes de fila e registro quando tem uma fila, estágio, estado, filtro rápido ou termo de busca útil. Ele evita fingir que estado apenas do registro é trabalho executável em fila.

`workflow-operations.json`

Crie workflows/workflow-operations.json para descrever operações no nível do operador. Campos são opcionais salvo quando a operação precisa deles; uma operação mínima ainda pode carregar sem um runbook completo.

{
  "version": 1,
  "operations": [
    {
      "id": "careers-full-crawl",
      "title": "Rastreamento completo de carreiras",
      "workflowName": "careers-crawl",
      "summary": "Descobrir páginas de carreiras de empresas, buscar vagas e entregá-las aos processos de parse/index.",
      "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": "Buscar páginas de carreiras",
          "stages": ["fetch"],
          "queues": ["careers_fetch"],
          "workers": ["careers_fetch"]
        }
      ],
      "focusAreas": [
        {
          "id": "fetch-backlog",
          "title": "Acúmulo de busca",
          "stages": ["fetch"],
          "queues": ["careers_fetch"],
          "actions": ["resume-fetch"]
        }
      ],
      "actions": [
        {
          "id": "resume-fetch",
          "title": "Retomar processos de busca",
          "kind": "resume-workers",
          "queue": "careers_fetch",
          "targetConsole": "queue"
        }
      ],
      "relatedConsoles": ["workflowLedger", "queueConsole"]
    }
  ]
}

Campos úteis de operação:

Campo	Significado
`workflowName`	Fluxo que precisa estar ativo para inícios diretos
`entryScript`	Script inicial opcional; omita para operações apenas de inspeção, retomada ou recuperação
`summary`, `help`, `prerequisites`	Runbook e orientação ao operador
`expectedQueues`, `expectedWorkerPools`	Evidências de fila/processo de trabalho que o console deve procurar
`phases`	Estágios principais de trabalho, geralmente vinculados a filas, processos de trabalho e estágios do registro
`focusAreas`	Recortes acionáveis dentro de uma operação, como acúmulo, trabalho pronto para nova tentativa ou passagem
`actions`	Ações de operador suportadas, como iniciar, retomar processos de trabalho, abrir fila, abrir registro ou abrir script
`preflightChecks`	Lista opcional de linhas de controles preliminares integradas a exibir; omita para mostrar o conjunto padrão

Operações sem entryScript são válidas. O console as trata como superfícies de inspeção/retomada/recuperação e não gera uma ação Start, salvo se um manifesto define explicitamente uma, caso em que ela fica desativada com motivo.

Runbook e controles preliminares

Campos de runbook explicam finalidade, quando executar, o que a operação faz, entradas, resultado esperado, avisos e solução de problemas. Eles são opcionais, mas descrições detalhadas ajudam quando um espaço de trabalho tem muitos rastreadores e filas especializados.

Linhas de controles preliminares mostram se o espaço de trabalho está aberto, se o manifesto carregou, se o fluxo é conhecido, se o fluxo ativo corresponde, se o script de entrada existe, se o registro está disponível, se filas existem, se grupos de processos de trabalho são conhecidos e se há atenção no registro.

Controles preliminares são orientação e segurança. Ocultar uma linha com preflightChecks altera a guia exibida, não as regras rígidas de segurança para iniciar um script sob o fluxo errado.

Fases, áreas de foco e passagens

Fases modelam as etapas principais da operação. Áreas de foco modelam recortes acionáveis dentro dessas etapas: acúmulo de busca, trabalho pronto para nova tentativa, itens rejeitados, acúmulo de parse/index ou uma passagem que precisa de inspeção.

Passagens descrevem transições entre estágios, como fetch para parse_index. O console compara contagens de entrada e saída do registro para que o operador veja se o trabalho parou entre fases.

Use áreas de foco para reparo e retomada em vez de criar operações falsas de alto nível. Isso mantém o lado esquerdo do console focado em operações reais e ainda expõe o trabalho que precisa de atenção.

`workflow-map.json`

Use workflows/workflow-map.json quando um espaço de trabalho contém muitas pastas de fluxo, mas apenas alguns sistemas no nível do operador. O mapa agrupa fluxos em sistemas, cadeias de automação, grupos de módulos, estágios, filas, processos de trabalho, operações e passagens.

{
  "version": 1,
  "systems": [
    {
      "id": "careers",
          "title": "Rastreamento de carreiras",
      "pipelines": [
        {
          "id": "careers-crawl",
          "title": "Fluxo de rastreamento de carreiras",
          "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": "Rastreadores especializados de carreiras",
          "role": "adapter",
          "workflowNamePatterns": ["careers-*"],
          "excludeWorkflowNames": ["careers-crawl"]
        }
      ]
    }
  ]
}

O progresso de módulos é calculado a partir de agregados do registro para a execução selecionada, não da página visível de itens. Módulos sem evidência no registro aparecem como não tentados para que o operador decida se foram ignorados intencionalmente, ainda não enfileirados ou ausentes da execução.

API de scripts

// Verificar o que está ativo
const active = g.workflows.getActive();
if (active) g.log("Fluxo atual: " + active.name);

// Listar todos os fluxos
const workflows = g.workflows.list();
for (const w of workflows) {
  g.log(w.name + " — " + w.scriptCount + " scripts" +
    (w.hasEvents ? ", tem gatilhos" : ""));
}

// Trocar (fire-and-forget)
g.workflows.switch("rss-pipeline");

Veja a Referência da API para as assinaturas completas.

Próximos passos

Espaços de trabalho — estrutura e arquivos de configuração
Processos de trabalho das filas — grupos de processos no nível global ou de fluxo
Registro de rastreabilidade dos fluxos de trabalho — visibilidade durável de execuções e itens
Ferramentas personalizadas — defina ferramentas MCP por fluxo