Flussi di lavoro

Ciò che valuta una corsa

I file del flusso di lavoro vengono sottoposti a commit in .cadcamfun/workflows/ con a .yml o .yaml estensione. Il sidecar li carica da un rif impegnato selezionato. La modifica di un disegno o di un flusso di lavoro non confermato non modifica i file visualizzati da un'esecuzione esistente.

@cadcamfun/workflow analizza lo YAML, convalida le dipendenze, abbina i trigger ed esegue le funzioni registrate. Non esegue comandi shell arbitrari, immagini contenitore o azioni scaricate. Ogni uses l'identificatore deve esistere nel registro corrente del corridore prima dell'inizio di qualsiasi passaggio.

Scrivi un flusso di lavoro

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

Un flusso di lavoro ha un nome, on trigger e lavori codificati in base all'identificatore. Un lavoro contiene almeno un passaggio e può dichiarare needs. Un passo ha uses, facoltativo id e nome, facoltativo with argomenti, if, e continueOnError.

Gli identificatori iniziano con una lettera e contengono al massimo 64 lettere, cifre, trattini bassi o trattini. Gli identificatori dei passaggi sono univoci nell'intero flusso di lavoro. L'analisi rifiuta YAML non validi, errori di schema, dipendenze di processi sconosciuti, dipendenze cicliche e identificatori di passaggi duplicati.

Controlli integrati

• project/validate analizza i file JSON impegnati e controlla gli ID entità disegno/componente/percorso utensile riconosciuti rispetto ai nomi file e ne verifica i nomi. Restituisce i conteggi delle risorse.
• project/require-gcode fallisce se un percorso utensile impegnato ha un codice G vuoto o mancante. Non è necessario che il progetto contenga almeno un percorso utensile.
• cam/verify crea richieste di riproduzione dal codice G del percorso utensile impegnato e Toolpath.data.request. Fallisce in base ai risultati della riproduzione della gravità degli errori o anche agli avvisi quando with.severity è warning. Gli argomenti facoltativi sono toolpath e tolerance.
• cam/gcode si rigenera dall'impegno data.request e confronta il suo NC tagliato con il testo impegnato. Accetta un optional toolpath selettore.
• cam/sequence controlla le richieste memorizzate per le assegnazioni di numeri utensile in conflitto e le richieste di ripresa della lavorazione il cui utensile precedente non è più grande dell'utensile attivo.

I passaggi CAM leggono il formato di richiesta del generatore memorizzato. Vengono segnalate NC mancanti, richieste di generazione mancanti o richieste di verifica non supportate skipped risultati ove applicabile; non falliscono automaticamente il passaggio. Esamina il conteggio verificato/corrispondente e i motivi saltati. Un flusso di lavoro verde contenente solo lavoro CAM saltato non è la prova di un programma verificato.

Passaggi supportati dal servizio

Il sidecar live si registra vcs/commit, notify/pushe, una volta esistente il servizio di assistenza, ai/prompt. La registrazione è esplicita: un corridore creato senza questi servizi fallisce un flusso di lavoro che nomina un passaggio non disponibile.

vcs/commit richiede un messaggio e accetta a files registrazione del testo sotto .cadcamfun/ con YAML, Markdown, JSON o estensioni di testo. Funziona come account della corsa e obbedisce alla politica del ramo protetto. L'argomento extra-file non può sostituire direttamente i percorsi delle entità CAD. L'implementazione attuale delega al commit del progetto senza verificare la presenza di una copia funzionante pulita: inoltre esegue uno snapshot delle modifiche correnti del database sul ramo estratto, che può differire dal riferimento controllato. Esegui questo passaggio di scrittura solo quando si intende eseguire il commit del ramo corrente e dello stato di lavoro.

notify/push crea una notifica dell'applicazione per l'attore dell'esecuzione, con titolo, corpo e esito di successo/fallimento facoltativi. È un passaggio di notifica persistente; non stabilisce di per sé la consegna tramite un fornitore push esterno.

ai/prompt richiede un prompt e facoltativamente accetta testo di sistema e un modello. Può sostituire il contenuto del file salvato e restituire il testo della risposta e l'identità del modello. Credenziali mancanti o un errore del provider non consentono questo passaggio; una risposta del modello è un output consultivo, separato dai controlli della geometria deterministica.

I passaggi integrati puri vengono registrati in builtinSteps (apps/sidecar/src/services/workflow-steps.ts): project/validate, project/require-gcode, cam/verify, cam/gcode, e cam/sequence. Hanno bisogno solo dei file impegnati e @cadcamfun/core, quindi sono disponibili anche quando l'assistente non è in esecuzione.

Esecuzione, output e condizioni

I lavori vengono eseguiti in livelli di dipendenza, con lavori indipendenti in un livello eseguiti contemporaneamente. I passaggi all'interno di un lavoro vengono eseguiti in sequenza. I lavori le cui dipendenze non hanno avuto esito positivo vengono ignorati. La condizione del passaggio predefinita è success; always corre dopo uno dei risultati e failure viene eseguito dopo un precedente errore di passaggio non gestito in quel lavoro.

continueOnError: true registra un evento di passaggio non riuscito senza impostare il flag di fallimento del lavoro. In caso contrario, un passaggio non riuscito salta i passaggi successivi di sola riuscita e contrassegna il processo come non riuscito. Il risultato complessivo è il successo solo quando ogni lavoro ha successo.

È possibile fare riferimento ai precedenti output dei passaggi con nome with valori utilizzando l'espressione mostrata di seguito. Un valore costituito esattamente da un'espressione mantiene il proprio tipo; la sostituzione all'interno di stringhe più lunghe converte l'output in testo. I lavori dovrebbero dichiarare le dipendenze quando consumano gli output di un altro lavoro.

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

Trigger e invio

on.push supporta i filtri glob di ramo e percorso modificato; on.pullRequest filtra il ramo base; on.manual consente l'invio esplicito. Un singolo asterisco corrisponde all'interno di un segmento di percorso e un doppio asterisco può estendersi su più segmenti.

L'integrazione HTTP commit/push attualmente fornisce un elenco vuoto di percorsi modificati al trigger push automatico. Di conseguenza un flusso di lavoro con un filtro del percorso push non corrisponde a tali eventi. Utilizza i filtri push solo per il ramo o l'invio manuale per questa integrazione fino a quando non vengono forniti i dati del percorso modificato.

Leggi le definizioni impegnate su GET /api/projects/:id/actions/workflows, opzionalmente con ref. Leggine uno su /workflows/:name. Viene restituito un file non valido con il suo contenuto e un file problem quindi può essere riparato. Per modificare una definizione, includi il percorso sicuro del flusso di lavoro in un commit del progetto.

POST /api/projects/:id/actions/dispatch accetta un riferimento opzionale e invia ogni flusso di lavoro manuale corrispondente a quel riferimento; non è un selettore per un nome di flusso di lavoro. Leggi i risultati salvati da GET /api/projects/:id/actions/runs.

Esegui persistenza ed eventi

Il runner registra il flusso di lavoro, l'evento, il riferimento, il commit SHA, lo stato, i timestamp e gli eventi accumulati WorkflowRun. Gli eventi lavorativi segnano l'inizio e la fine; gli eventi del passaggio includono indice, identificatore, stato, output opzionali e testo di errore. Il file YAML non valido viene conservato come esecuzione non riuscita con un evento file non valido.

Il percorso del trigger HTTP corrente attende la stabilizzazione dei flussi di lavoro e quindi pubblica insieme gli eventi live avviati e terminati. Non esegue lo streaming di ogni passaggio in esecuzione tramite la richiesta HTTP. Il core runner espone un onEvent richiamata per le integrazioni che necessitano di passaggi di avanzamento.

Interpretare i risultati con precisione

Un flusso di lavoro riporta il commit acquisito e le implementazioni dei passaggi registrati. Non certifica le successive modifiche alla copia di lavoro né rimuove un commit già registrato in caso di errore. Esaminare i controlli saltati, la politica di avviso e le prove pertinenti del percorso utensile prima di utilizzare un'esecuzione riuscita come cancello di rilascio.

L'implementazione è divisa tra packages/workflow/src per schema/trigger/esecuzione e sidecar workflow-runner.ts, workflow-steps.ts, e workflow-service-steps.ts per dati di progetto impegnati, esecuzioni persistenti e servizi applicativi.

Esegui un esempio di motore di flusso di lavoro isolato

Un consumatore di pacchetto fornisce le funzioni registrate e il loro contesto tipizzato. Questo esempio analizza un flusso di lavoro manuale, esegue un controllo registrato e restituisce il risultato del lavoro senza aprire SQLite o richiamare 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" } }

Esegui all'interno di un'area di lavoro a seconda dell'effetto e @cadcamfun/workflow, ad esempio apps/sidecar. Il passaggio personalizzato riportato sopra è locale per il registro fornito; nominarlo in un flusso di lavoro desktop non lo installa nel sidecar di produzione.

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

Abbina i filtri e consuma gli output in modo sicuro

Un trigger push richiede che il filtro del ramo corrisponda e, quando esiste un elenco di percorsi, almeno un percorso modificato fornito corrisponda. Un filtro omesso non ha restrizioni; un elenco esplicitamente vuoto non corrisponde a nulla. Un evento manuale richiede on.manual essere presente. La corrispondenza delle richieste pull utilizza il ramo base anziché il nome della proposta principale.

La sostituzione dell'output attraversa array e record nidificati. Un'espressione di output mancante esatta viene valutata come indefinita; un output assente incorporato in una stringa più lunga diventa testo vuoto. Non fare affidamento su un passaggio saltato o non riuscito per aver prodotto un output. Dichiarare needs per i consumatori cross-job, quindi la pianificazione delle dipendenze stabilisce l'ordine dei dati.

Fare un passo if è uno dei tre modi letterali, non un linguaggio di espressione generale. Le variabili del flusso di lavoro, l'interpolazione della shell, le build di matrici, le condizioni JavaScript arbitrarie e il caricamento di azioni di terze parti non sono implementati da questo motore. Il separato ai/prompt sostituti del conduttore impegnati files.<path> riferimenti nel suo prompt; i passaggi ordinari non ricevono quella sostituzione extra.

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

Un filtro di ramo o percorso omesso corrisponde a ogni valore. Un invio manuale corrisponde solo ai flussi di lavoro che dichiarano on.manuale un evento pull-request corrisponde a quello del flusso di lavoro branches glob contro il ramo base della richiesta pull (packages/workflow/src/trigger.ts).

Diagnosticare i risultati del flusso di lavoro

Per impostazione predefinita, la cronologia delle esecuzioni salvate restituisce le ultime 50 esecuzioni al limite del servizio. Le notifiche degli eventi in tempo reale sono i canali secondari più efficaci: ispeziona le righe persistenti per il risultato dell'esecuzione durevole invece di considerare la consegna delle notifiche come il record di esecuzione.

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

Formato file del flusso di lavoro

Un flusso di lavoro è un file YAML in .cadcamfun/workflows/<name>.yml nel repository del progetto, versione con il modello che controlla. La sua forma rispecchia le azioni GitHub (on, jobs, needs, steps, uses, with), ma uses nomina sempre un passaggio CADCAMFUN registrato. Un flusso di lavoro non può eseguire un comando shell o un'immagine del contenitore.

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 dei globi * per corrispondere all'interno di un segmento del percorso e ** per abbinare tra i segmenti. Un elenco di filtri omesso corrisponde a tutto. toolpaths/*.json partite toolpaths/a.json ma no toolpaths/x/a.json; toolpaths/** corrisponde ad entrambi.

Riferimento al passo

I passaggi puri leggono solo i file del commit da controllare, mai il database live, quindi un'esecuzione riporta esattamente l'albero che è stato inviato. I passaggi supportati dal servizio vengono registrati una volta che il servizio esiste. Fino ad allora, nominarne uno è un grave errore, non un silenzio-no-op.

Malformato with i valori vengono letti in modo difensivo: una non stringa in cui è prevista una stringa o un numero non finito viene ignorata anziché fallire l'esecuzione. Controlla le uscite per confermare un filtro come toolpath effettivamente applicato.

Uscite e interpolazione

Un passo con un id memorizza i suoi output a livello di esecuzione, in modo che un lavoro possa leggere gli output dei lavori in esso contenuti needs. All'interno di qualsiasi stringa with, ${{ steps.<id>.outputs.<key> }} viene sostituito ricorsivamente attraverso oggetti e array. Quando una stringa è composta esattamente da un'espressione, il valore mantiene il suo tipo (un numero rimane un numero). Incorporato in altro testo, il valore viene convertito in una stringa e un valore mancante diventa una stringa vuota. ai/prompt inoltre si espande ${{ files.<path> }} al testo di quel file nel commit (vuoto se il file è assente).

Esegui il ciclo di vita e gli errori

1. L'evento trigger (push, pull request o manuale) seleziona i flussi di lavoro nell'albero del riferimento, letto dal commit anziché dalla copia di lavoro.
2. Ogni file viene analizzato. Errori YAML (yaml), errori di schema (schema), sconosciuto needs (needs), cicli (cycle) e ID passaggio duplicati (duplicate-step-id) vengono segnalati come esecuzione non valida con il motivo.
3. Ogni uses viene confrontato con il registro prima che venga eseguito qualsiasi cosa. Un passaggio sconosciuto fallisce l'esecuzione Unknown step(s): ..., quindi un errore di battitura non applica mai una modifica a metà.
4. I lavori sono ordinati in livelli. Ogni livello viene eseguito contemporaneamente; un lavoro il cui needs non tutto è riuscito è saltato.
5. Eventi di avanzamento (job-start, step con stato e uscite o messaggio, job-end) trasmettono in streaming al desktop e al compagno e l'esecuzione viene mantenuta con i relativi eventi.
6. L'esecuzione ha esito positivo solo se tutti i processi hanno avuto esito positivo. I lavori saltati vengono considerati non riusciti.

Eventi dal vivo workflow.started (con l'evento scatenante) e workflow.finished (success, failure, o cancelled) vengono pubblicati per ogni esecuzione.

Un percorso completo, ripercorso evento per evento

Questo flusso di lavoro esercita tutte le regole del motore contemporaneamente: output passati tra lavori, un valore intero e un'interpolazione incorporata, continueOnError, if: failure, un lavoro ignorato perché la sua dipendenza non è riuscita e un lavoro indipendente. È stato gestito con runWorkflow e quattro gestori delle fasi di test: demo/measure ritorna { volume: 7842.92, part }, demo/check stampa ciò che ha ricevuto, demo/fail fallisce con StepError("tolerance exceeded") e demo/notify non restituisce nulla.

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

Corrispondenza del trigger, testata

Ogni errore di analisi, riprodotto

In fase di esecuzione, qualsiasi uses senza un gestore registrato fallisce l'intera esecuzione prima del primo passaggio, elencando ogni ID sconosciuto: Unknown step(s): demo/measure, demo/check, …. Un errore di battitura quindi non applica mai a metà un flusso di lavoro.

Nel 3D