Fluxos de trabalho

O que uma corrida avalia

Os arquivos de fluxo de trabalho são confirmados em .cadcamfun/workflows/ com um .yml ou .yaml extensão. O sidecar os carrega a partir de uma referência confirmada selecionada. A edição de um desenho ou fluxo de trabalho não confirmado não altera os arquivos vistos por uma execução existente.

@cadcamfun/workflow analisa o YAML, valida dependências, combina gatilhos e executa funções registradas. Ele não executa comandos shell arbitrários, imagens de contêiner ou ações baixadas. Cada uses o identificador deve existir no registro atual do executor antes do início de qualquer etapa.

Escreva um fluxo de trabalho

name: Project checks
on:
  manual: true
jobs:
  validate:
    steps:
      - id: structure
        uses: project/validate
      - uses: project/require-gcode
      - uses: cam/sequence

Um fluxo de trabalho tem um nome, on gatilhos e trabalhos codificados por identificador. Um trabalho contém pelo menos uma etapa e pode declarar needs. Um passo tem uses, opcional id e nome, opcional with argumentos, if, e continueOnError.

Os identificadores começam com uma letra e contêm no máximo 64 letras, dígitos, sublinhados ou hifens. Os identificadores de etapas são exclusivos em todo o fluxo de trabalho. A análise rejeita YAML inválido, falhas de esquema, dependências de trabalho desconhecidas, dependências cíclicas e identificadores de etapas duplicados.

Verificações integradas

• project/validate analisa arquivos JSON confirmados e verifica IDs de entidade de desenho/componente/percurso reconhecidos em relação aos seus nomes de arquivo e verifica seus nomes. Ele retorna contagens de recursos.
• project/require-gcode falha se um percurso confirmado tiver código G vazio ou ausente. Não requer que o projeto contenha pelo menos um percurso.
• cam/verify constrói solicitações de repetição a partir do código G do percurso da ferramenta confirmado e Toolpath.data.request. Ele falha nas descobertas de repetição da gravidade do erro ou também nos avisos quando with.severity é warning. Argumentos opcionais são toolpath e tolerance.
• cam/gcode regenera do comprometido data.request e compara seu NC aparado com o texto confirmado. Aceita um opcional toolpath seletor.
• cam/sequence verifica solicitações armazenadas em busca de atribuições de números de ferramenta conflitantes e solicitações de usinagem de repouso cuja ferramenta anterior não seja maior que a ferramenta ativa.

As etapas CAM leem o formato de solicitação do gerador armazenado. NC ausente, solicitações de geração ausentes ou solicitações de verificação não suportadas são relatadas em skipped resultados, quando aplicável; eles não falham automaticamente na etapa. Inspecione a contagem verificada/correspondente e os motivos ignorados. Um fluxo de trabalho verde contendo apenas trabalho CAM ignorado não é prova de um programa verificado.

Etapas apoiadas pelo serviço

O sidecar ao vivo registra vcs/commit, notify/push, e, após a existência do serviço assistente, ai/prompt. O registro é explícito: um executor criado sem esses serviços falha em um fluxo de trabalho nomeando uma etapa indisponível.

vcs/commit requer uma mensagem e aceita uma files registro de texto sob .cadcamfun/ com extensões YAML, Markdown, JSON ou texto. Ela atua como conta da corrida e obedece à política de agência protegida. O argumento extra-file não pode substituir diretamente os caminhos da entidade CAD. A implementação atual delega o commit do projeto sem verificar uma cópia de trabalho limpa: ela também captura as edições atuais do banco de dados na ramificação com check-out, que pode ser diferente da referência que está sendo verificada. Execute esta etapa de escrita somente quando a ramificação atual e o estado de trabalho forem confirmados.

notify/push cria uma notificação de aplicativo para o ator da execução, com título, corpo e resultado de sucesso/falha opcionais. É uma etapa de notificação persistente; ele não estabelece por si só a entrega por meio de um provedor de envio externo.

ai/prompt requer um prompt e, opcionalmente, aceita texto do sistema e um modelo. Ele pode substituir o conteúdo do arquivo confirmado e retornar texto de resposta e identidade do modelo. Credenciais ausentes ou erro do provedor falham nesta etapa; uma resposta do modelo é um resultado consultivo, separado das verificações de geometria determinística.

As etapas integradas puras são registradas em builtinSteps (apps/sidecar/src/services/workflow-steps.ts): project/validate, project/require-gcode, cam/verify, cam/gcode, e cam/sequence. Eles precisam apenas dos arquivos confirmados e @cadcamfun/core, portanto, eles estarão disponíveis mesmo quando o assistente não estiver em execução.

Execução, saídas e condições

Os trabalhos são executados em níveis de dependência, com trabalhos independentes em um nível sendo executados simultaneamente. As etapas de um trabalho são executadas sequencialmente. Os trabalhos cujas dependências não tiveram êxito serão ignorados. A condição de etapa padrão é success; always é executado após qualquer resultado e failure é executado após uma falha de etapa anterior não tratada nesse trabalho.

continueOnError: true registra um evento de etapa com falha sem definir o sinalizador de falha do trabalho. Caso contrário, uma etapa com falha ignora as etapas posteriores somente com êxito e marca a tarefa como falha. O resultado geral só é sucesso quando todos os trabalhos são bem-sucedidos.

As saídas de etapas nomeadas anteriores podem ser referenciadas em with valores usando a expressão mostrada abaixo. Um valor que consiste exatamente em uma expressão mantém seu tipo; a substituição dentro de strings mais longas converte a saída em texto. Os trabalhos devem declarar dependências quando consumirem as saídas de outro trabalho.

with:
  body: "Checked drawings: ${{ steps.structure.outputs.drawings }}"

Gatilhos e envio

on.push suporta filtros glob de ramificação e caminho alterado; on.pullRequest filtra o branch base; on.manual permite o envio explícito. Um único asterisco corresponde a um segmento de caminho e um asterisco duplo pode abranger segmentos.

A integração de confirmação/push HTTP fornece atualmente uma lista vazia de caminhos alterados para o acionador de envio automático. Consequentemente, um fluxo de trabalho com um filtro de caminho push não corresponde a esses eventos. Use filtros push somente de ramificação ou envio manual para essa integração até que os dados do caminho alterado sejam fornecidos.

Leia as definições confirmadas em GET /api/projects/:id/actions/workflows, opcionalmente com ref. Leia um em /workflows/:name. Um arquivo malformado é retornado com seu conteúdo e um problem para que possa ser reparado. Para editar uma definição, inclua seu caminho de fluxo de trabalho seguro em uma confirmação do projeto.

POST /api/projects/:id/actions/dispatch aceita uma referência opcional e despacha todos os fluxos de trabalho manuais correspondentes nessa referência; não é um seletor para um nome de fluxo de trabalho. Ler resultados salvos de GET /api/projects/:id/actions/runs.

Execute persistência e eventos

O executor registra fluxo de trabalho, evento, referência, commit SHA, status, carimbos de data/hora e eventos acumulados em WorkflowRun. Os eventos do trabalho marcam o início e o fim; eventos de etapa incluem índice, identificador, status, saídas opcionais e texto de falha. YAML inválido é retido como uma execução com falha com um evento de arquivo inválido.

O caminho do gatilho HTTP atual aguarda a liquidação dos fluxos de trabalho e, em seguida, publica eventos ao vivo iniciados e concluídos em execução juntos. Ele não transmite cada etapa em execução dessa solicitação HTTP. O corredor principal expõe um onEvent retorno de chamada para integrações que precisam de progresso de etapa.

Interprete os resultados com precisão

Um fluxo de trabalho relata seu commit capturado e implementações de etapas registradas. Ele não certifica edições posteriores da cópia de trabalho nem remove um commit já registrado em caso de falha. Inspecione as verificações ignoradas, a política de aviso e as evidências relevantes do percurso da ferramenta antes de usar uma execução bem-sucedida como porta de liberação.

A implementação é dividida entre packages/workflow/src para esquema/gatilho/execução e sidecar workflow-runner.ts, workflow-steps.ts, e workflow-service-steps.ts para dados de projeto confirmados, execuções persistentes e serviços de aplicativos.

Execute um exemplo de mecanismo de fluxo de trabalho isolado

Um consumidor de pacote fornece as funções registradas e seu contexto digitado. Este exemplo analisa um fluxo de trabalho manual, executa uma verificação registrada e retorna o resultado do trabalho sem abrir o SQLite ou invocar o AI.

import { Effect } from "effect"
import { parseWorkflow, runWorkflow } from "@cadcamfun/workflow"

const source = [
  "name: Isolated check", "on:", "  manual: true", "jobs:",
  "  inspect:", "    steps:", "      - id: checked", "        uses: inspection/check"
].join("\n")
const result = await Effect.runPromise(Effect.gen(function* () {
  const workflow = yield* parseWorkflow(source)
  return yield* runWorkflow(workflow, {
    ctx: { drawingCount: 2 },
    registry: { "inspection/check": ({ ctx }) => Effect.succeed({ drawings: ctx.drawingCount }) }
  })
}))
console.log(result) // { status: "success", jobs: { inspect: "success" } }

Execute em um espaço de trabalho dependendo do efeito e @cadcamfun/workflow, como apps/sidecar. A etapa personalizada acima é local para o registro fornecido; nomeá-lo em um fluxo de trabalho de desktop não o instala no sidecar de produção.

Fonte: packages/workflow/src/schema.ts e run.ts.

Combine filtros e consuma saídas com segurança

Um gatilho push requer que seu filtro de ramificação corresponda e, quando existe uma lista de caminhos, pelo menos um caminho alterado fornecido para corresponder. Um filtro omitido é irrestrito; uma lista explicitamente vazia não corresponde a nada. Um evento manual requer on.manual estar presente. A correspondência de solicitação pull usa o branch base, em vez do nome da proposta principal.

A substituição de saída percorre matrizes e registros aninhados. Uma expressão de saída exata ausente é avaliada como indefinida; uma saída ausente incorporada em uma string mais longa torna-se um texto vazio. Não confie em uma etapa ignorada ou com falha para produzir uma saída. Declarar needs para consumidores entre empregos, portanto, o agendamento de dependência estabelece a ordem dos dados.

Etapa if é um dos três modos literais, não uma linguagem de expressão geral. Variáveis de fluxo de trabalho, interpolação de shell, construções de matrizes, condições arbitrárias de JavaScript e carregamento de ações de terceiros não são implementados por este mecanismo. O separado ai/prompt substitutos do manipulador comprometidos files.<path> referências em seu prompt; etapas comuns não recebem essa substituição extra.

Fonte: packages/workflow/src/trigger.ts, run.ts, e apps/sidecar/src/services/workflow-service-steps.ts.

Uma ramificação ou filtro de caminho omitido corresponde a cada valor. Um envio manual corresponde apenas a fluxos de trabalho que declaram on.manual, e um evento de solicitação pull corresponde ao fluxo de trabalho branches globs em relação ao branch base da solicitação pull (packages/workflow/src/trigger.ts).

Diagnosticar resultados de fluxo de trabalho

O histórico de execução salvo retorna as últimas 50 execuções por padrão no limite de serviço. Notificações de eventos ao vivo são canais secundários de melhor esforço: inspecionar linhas persistentes para obter o resultado de execução durável em vez de tratar a entrega de notificação como o registro de execução.

Fonte: apps/sidecar/src/services/workflow-runner.ts, workflow-steps.ts, e http/vcs.ts.

Formato de arquivo de fluxo de trabalho

Um fluxo de trabalho é um arquivo YAML em .cadcamfun/workflows/<name>.yml no repositório do projeto, versionado com o modelo que ele verifica. Sua forma reflete as ações do GitHub (on, jobs, needs, steps, uses, with), mas uses sempre nomeia uma etapa CADCAMFUN registrada. Um fluxo de trabalho não pode executar um comando shell ou uma imagem de contêiner.

name: Release check
on:
  push:
    branches: [main, "release/*"]
    paths: ["toolpaths/**"]
  pullRequest:
    branches: [main]
  manual: {}
jobs:
  validate:
    steps:
      - uses: project/validate
      - uses: project/require-gcode
  verify:
    needs: [validate]
    steps:
      - id: verify
        uses: cam/verify
        with: { severity: warning }
  gcode:
    needs: [validate]
    steps:
      - uses: cam/gcode
      - uses: cam/sequence
  report:
    needs: [verify, gcode]
    steps:
      - id: review
        uses: ai/prompt
        with:
          prompt: "Summarise risks in this program: ${{ files.toolpaths/op1.json }}"
        continueOnError: true
      - uses: notify/push
        if: always
        with:
          title: "Release check finished"
          body: "${{ steps.review.outputs.text }}"

Uso de globos * para corresponder dentro de um segmento de caminho e ** para combinar entre segmentos. Uma lista de filtros omitida corresponde a tudo. toolpaths/*.json partidas toolpaths/a.json mas não toolpaths/x/a.json; toolpaths/** combina com ambos.

Referência de etapa

As etapas puras leem apenas os arquivos do commit que estão sendo verificados, nunca o banco de dados ativo, portanto, uma execução relata exatamente a árvore que foi enviada. As etapas apoiadas pelo serviço são registradas assim que o serviço existe. Até então, nomear um é um erro grave, não uma operação silenciosa.

Malformado with os valores são lidos defensivamente: uma não-string onde uma string é esperada, ou um número não finito, é ignorado em vez de falhar na execução. Verifique as saídas para confirmar um filtro como toolpath efetivamente aplicado.

Saídas e interpolação

Um passo com id armazena suas saídas em toda a execução, para que um trabalho possa ler as saídas dos trabalhos que needs. Dentro de qualquer string em with, ${{ steps.<id>.outputs.<key> }} é substituído recursivamente por meio de objetos e matrizes. Quando uma string consiste em exatamente uma expressão, o valor mantém seu tipo (um número permanece um número). Incorporado em outro texto, o valor é convertido em uma string e um valor ausente se torna uma string vazia. ai/prompt expande adicionalmente ${{ files.<path> }} ao texto desse arquivo no commit (vazio se o arquivo estiver ausente).

Ciclo de vida de execução e erros

1. O evento acionador (push, pull request ou manual) seleciona fluxos de trabalho na árvore da referência, lidos no commit em vez da cópia de trabalho.
2. Cada arquivo é analisado. Erros YAML (yaml), erros de esquema (schema), desconhecido needs (needs), ciclos (cycle) e IDs de etapas duplicados (duplicate-step-id) são relatados como uma execução inválida com o motivo.
3. Todo uses é verificado no registro antes de qualquer execução. Uma etapa desconhecida falha na execução com Unknown step(s): ..., portanto, um erro de digitação nunca aplica uma alteração pela metade.
4. Os trabalhos são ordenados em níveis. Cada nível é executado simultaneamente; um trabalho cujo needs nem todos tiveram sucesso foi ignorado.
5. Eventos de progresso (job-start, step com status e saídas ou mensagem, job-end) transmite para a área de trabalho e o complemento, e a execução persiste com seus eventos.
6. A execução só será bem-sucedida se todos os trabalhos forem bem-sucedidos. Os trabalhos ignorados contam como não bem-sucedidos.

Eventos ao vivo workflow.started (com o evento desencadeador) e workflow.finished (success, failure, ou cancelled) são publicados para cada execução.

Uma execução completa, rastreada evento por evento

Este fluxo de trabalho exercita todas as regras do mecanismo de uma só vez: saídas passadas entre tarefas, um valor total e uma interpolação incorporada, continueOnError, if: failure, um trabalho ignorado porque sua dependência falhou e um trabalho independente. Foi executado com runWorkflow e quatro manipuladores de etapas de teste: demo/measure retorna { volume: 7842.92, part }, demo/check imprime o que recebeu, demo/fail falha com StepError("tolerance exceeded") e demo/notify não retorna nada.

name: Release check
on:
  push: { branches: [main, "release/**"], paths: ["parts/**/*.json"] }
  manual: {}
jobs:
  measure:
    steps:
      - id: size
        uses: demo/measure
        with: { part: bracket }
  verify:
    needs: [measure]
    steps:
      - uses: demo/check
        with: { volume: "${{ steps.size.outputs.volume }}", label: "vol=${{ steps.size.outputs.volume }} mm3" }
      - uses: demo/fail
        continueOnError: true
      - uses: demo/fail
      - uses: demo/notify
        if: failure
      - uses: demo/notify
  publish:
    needs: [verify]
    steps:
      - uses: demo/notify
  lint:
    steps:
      - uses: demo/notify

levels [["measure","lint"],["verify"],["publish"]]
{"type":"job-start","job":"measure"}
{"type":"step","job":"measure","index":0,"uses":"demo/measure","status":"success","outputs":{"volume":7842.92,"part":"bracket"}}
{"type":"job-end","job":"measure","status":"success"}
{"type":"job-start","job":"lint"}
{"type":"step","job":"lint","index":0,"uses":"demo/notify","status":"success","outputs":{}}
{"type":"job-end","job":"lint","status":"success"}
{"type":"job-start","job":"verify"}
  check got {"volume":7842.92,"label":"vol=7842.92 mm3"}
{"type":"step","job":"verify","index":0,"uses":"demo/check","status":"success","outputs":{"ok":true}}
{"type":"step","job":"verify","index":1,"uses":"demo/fail","status":"failure","message":"Cause([Fail(StepError: tolerance exceeded)])"}
{"type":"step","job":"verify","index":2,"uses":"demo/fail","status":"failure","message":"Cause([Fail(StepError: tolerance exceeded)])"}
{"type":"step","job":"verify","index":3,"uses":"demo/notify","status":"success","outputs":{}}
{"type":"step","job":"verify","index":4,"uses":"demo/notify","status":"skipped"}
{"type":"job-end","job":"verify","status":"failure"}
{"type":"job-end","job":"publish","status":"skipped"}
result {"status":"failure","jobs":{"measure":"success","lint":"success","verify":"failure","publish":"skipped"}}

Correspondência de gatilho, testada

Cada erro de análise, reproduzido

Em tempo de execução, qualquer uses sem um manipulador registrado falha em toda a execução antes da primeira etapa, listando todos os IDs desconhecidos: Unknown step(s): demo/measure, demo/check, …. Portanto, um erro de digitação nunca aplica um fluxo de trabalho pela metade.

Em 3D