Flux de travail

Ce qu'une exécution évalue

Les fichiers de workflow sont validés sous .cadcamfun/workflows/ avec un .yml ou .yaml extension. Le sidecar les charge à partir d’une référence validée sélectionnée. La modification d'un dessin ou d'un flux de travail non validé ne modifie pas les fichiers affichés par une exécution existante.

@cadcamfun/workflow analyse le YAML, valide les dépendances, fait correspondre les déclencheurs et exécute les fonctions enregistrées. Il n'exécute pas de commandes shell arbitraires, d'images de conteneur ou d'actions téléchargées. Chaque uses l'identifiant doit exister dans le registre actuel du coureur avant le début de toute étape.

Écrire un flux de travail

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

Un workflow a un nom, on déclencheurs et tâches saisies par identifiant. Un travail contient au moins une étape et peut déclarer needs. Une étape a uses, facultatif id et nom, facultatif with arguments, if, et continueOnError.

Les identifiants commencent par une lettre et contiennent au maximum 64 lettres, chiffres, traits de soulignement ou traits d'union. Les identifiants d'étape sont uniques dans l'ensemble du flux de travail. L'analyse rejette les YAML non valides, les échecs de schéma, les dépendances de tâches inconnues, les dépendances cycliques et les identifiants d'étape en double.

Contrôles intégrés

• project/validate analyse les fichiers JSON validés et vérifie les ID d'entité de dessin/composant/chemin d'outil reconnus par rapport à leurs noms de fichiers et vérifie leurs noms. Il renvoie le nombre de ressources.
• project/require-gcode échoue si un parcours d'outil validé a un G-code vide ou manquant. Il n'est pas nécessaire que le projet contienne au moins un parcours d'outil.
• cam/verify crée des demandes de relecture à partir du G-code de parcours d'outil validé et Toolpath.data.request. Il échoue sur les résultats de relecture de gravité d'erreur, ou également sur les avertissements lorsque with.severity est warning. Les arguments facultatifs sont toolpath et tolerance.
• cam/gcode se régénère de l'engagement data.request et compare son NC découpé avec le texte validé. Il accepte une option toolpath sélecteur.
• cam/sequence vérifie les requêtes stockées pour les attributions de numéros d'outils contradictoires et les requêtes de reprise d'usinage dont l'outil précédent n'est pas plus grand que l'outil actif.

Les étapes CAM lisent le format de requête du générateur stocké. Les NC manquantes, les demandes de génération manquantes ou les demandes de vérification non prises en charge sont signalées dans skipped résultats le cas échéant ; ils n’échouent pas automatiquement à l’étape. Inspectez le nombre vérifié/correspondant et les raisons ignorées. Un flux de travail vert contenant uniquement des travaux de FAO ignorés ne constitue pas la preuve d'un programme vérifié.

Étapes basées sur le service

Le sidecar en direct s'enregistre vcs/commit, notify/push, et, une fois le service assistant créé, ai/prompt. L'inscription est explicite : un exécuteur créé sans ces services échoue à un workflow nommant une étape indisponible.

vcs/commit nécessite un message et accepte un files enregistrement du texte sous .cadcamfun/ avec des extensions YAML, Markdown, JSON ou texte. Il fait office de compte d'exécution et obéit à la politique de branche protégée. L'argument extra-file ne peut pas remplacer directement les chemins d'entités CAO. L'implémentation actuelle délègue la validation du projet sans vérifier une copie de travail propre : elle capture également les modifications actuelles de la base de données sur la branche extraite, qui peuvent différer de la référence en cours de vérification. Exécutez cette étape d’écriture uniquement lorsque cette branche actuelle et cet état de fonctionnement sont destinés à être validés.

notify/push crée une notification d'application pour l'acteur de l'exécution, avec un titre, un corps et un résultat de réussite/échec facultatifs. Il s'agit d'une étape de notification persistante ; il n'établit pas en soi la livraison via un fournisseur push externe.

ai/prompt nécessite une invite et accepte éventuellement le texte du système et un modèle. Il peut remplacer le contenu du fichier validé et renvoie le texte de réponse et l'identité du modèle. Des informations d'identification manquantes ou une erreur du fournisseur échouent à cette étape ; une réponse modèle est une sortie consultative, distincte des vérifications géométriques déterministes.

Les étapes purement intégrées sont enregistrées dans builtinSteps (apps/sidecar/src/services/workflow-steps.ts): project/validate, project/require-gcode, cam/verify, cam/gcode, et cam/sequence. Ils n'ont besoin que des fichiers validés et @cadcamfun/core, ils sont donc disponibles même lorsque l'assistant n'est pas en cours d'exécution.

Exécution, résultats et conditions

Les tâches s'exécutent dans des niveaux de dépendance, les tâches indépendantes d'un niveau s'exécutant simultanément. Les étapes d'un travail s'exécutent de manière séquentielle. Les tâches dont les dépendances n'ont pas abouti sont ignorées. La condition d'étape par défaut est success; always s'exécute après l'un ou l'autre résultat et failure s'exécute après un échec d'étape non géré dans ce travail.

continueOnError: true enregistre un événement d'étape ayant échoué sans définir l'indicateur d'échec du travail. Sinon, une étape échouée ignore les étapes ultérieures réussies et marque l'échec de la tâche. Le résultat global n’est le succès que lorsque chaque travail réussit.

Les sorties d'étape nommées antérieures peuvent être référencées dans with valeurs en utilisant l’expression ci-dessous. Une valeur composée d’exactement une expression conserve son type ; la substitution à l'intérieur de chaînes plus longues convertit la sortie en texte. Les tâches doivent déclarer des dépendances lorsqu'elles consomment les sorties d'une autre tâche.

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

Déclencheurs et répartition

on.push prend en charge les filtres globaux de branche et de chemin modifié ; on.pullRequest filtre la branche de base ; on.manual permet une répartition explicite. Un seul astérisque correspond à un segment de chemin et un double astérisque peut s'étendre sur des segments.

L'intégration HTTP commit/push fournit actuellement une liste vide de chemins modifiés au déclencheur push automatique. Par conséquent, un workflow avec un filtre de chemin push ne correspond pas à ces événements. Utilisez des filtres push de branche uniquement ou une répartition manuelle pour cette intégration jusqu'à ce que les données de chemin modifié soient fournies.

Lisez les définitions engagées sur GET /api/projects/:id/actions/workflows, éventuellement avec ref. Lisez-en un sur /workflows/:name. Un fichier mal formé est renvoyé avec son contenu et un problem pour qu'il puisse être réparé. Pour modifier une définition, incluez son chemin de flux de travail sécurisé dans une validation de projet.

POST /api/projects/:id/actions/dispatch accepte une référence facultative et distribue chaque flux de travail manuel correspondant à cette référence ; il ne s'agit pas d'un sélecteur pour un nom de flux de travail. Lire les résultats enregistrés à partir de GET /api/projects/:id/actions/runs.

Exécuter la persistance et les événements

Le coureur enregistre le flux de travail, l'événement, la référence, la validation SHA, le statut, les horodatages et les événements accumulés dans WorkflowRun. Les événements de travail marquent le début et la fin ; les événements d'étape incluent l'index, l'identifiant, le statut, les sorties facultatives et le texte d'échec. Un YAML non valide est conservé comme une exécution ayant échoué avec un événement de fichier non valide.

Le chemin de déclenchement HTTP actuel attend que les flux de travail soient réglés, puis publie ensemble les événements en direct démarrés et terminés. Il ne diffuse pas chaque étape en cours via cette requête HTTP. Le coureur principal expose un onEvent rappel pour les intégrations qui nécessitent une progression progressive.

Interpréter les résultats avec précision

Un flux de travail rend compte de ses implémentations de validation capturées et d’étapes enregistrées. Il ne certifie pas les modifications ultérieures de la copie de travail ni ne supprime une validation déjà enregistrée en cas d'échec. Inspectez les vérifications ignorées, la politique d'avertissement et les preuves de parcours d'outil pertinentes avant d'utiliser une exécution réussie comme porte de sortie.

La mise en œuvre est répartie entre packages/workflow/src pour le schéma/déclencheur/exécution et sidecar workflow-runner.ts, workflow-steps.ts, et workflow-service-steps.ts pour les données de projet validées, les exécutions persistantes et les services d'application.

Exécuter un exemple de moteur de workflow isolé

Un consommateur de package fournit les fonctions enregistrées et leur contexte typé. Cet exemple analyse un flux de travail manuel, exécute une vérification enregistrée et renvoie le résultat de sa tâche sans ouvrir SQLite ni appeler 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" } }

Exécuté dans un espace de travail en fonction de l'effet et @cadcamfun/workflow, tel que apps/sidecar. L'étape personnalisée ci-dessus est locale au registre fourni ; le nommer dans un workflow de bureau ne l’installe pas dans le sidecar de production.

Source: packages/workflow/src/schema.ts et run.ts.

Faites correspondre les filtres et consommez les sorties en toute sécurité

Un déclencheur push nécessite que son filtre de branche corresponde et, lorsqu'une liste de chemins existe, qu'au moins un chemin modifié fourni corresponde. Un filtre omis n’est soumis à aucune restriction ; une liste explicitement vide ne correspond à rien. Un événement manuel nécessite on.manual être présent. La correspondance de demande d'extraction utilise la branche de base, plutôt que le nom de la proposition principale.

La substitution de sortie traverse les tableaux et les enregistrements imbriqués. Une expression de sortie manquante exacte est évaluée comme non définie ; une sortie absente intégrée dans une chaîne plus longue devient du texte vide. Ne comptez pas sur une étape sautée ou échouée pour avoir produit un résultat. Déclarer needs pour les consommateurs inter-tâches, la planification des dépendances établit l'ordre des données.

Étape if est l'un des trois modes littéraux, et non un langage d'expression général. Les variables de workflow, l'interpolation shell, les constructions de matrices, les conditions JavaScript arbitraires et le chargement d'actions tierces ne sont pas implémentés par ce moteur. Le séparé ai/prompt gestionnaire remplaçants engagés files.<path> références dans son invite ; les étapes ordinaires ne bénéficient pas de cette substitution supplémentaire.

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

Un filtre de branche ou de chemin omis correspond à chaque valeur. Une expédition manuelle correspond uniquement aux workflows qui déclarent on.manual, et un événement pull-request correspond à celui du flux de travail branches globs contre la branche de base de la demande d'extraction (packages/workflow/src/trigger.ts).

Diagnostiquer les résultats du flux de travail

L'historique d'exécution enregistré renvoie les 50 dernières exécutions par défaut à la limite du service. Les notifications d'événements en direct sont des canaux secondaires de meilleur effort : inspectez les lignes persistantes pour obtenir un résultat d'exécution durable au lieu de traiter la livraison des notifications comme un enregistrement d'exécution.

Source: apps/sidecar/src/services/workflow-runner.ts, workflow-steps.ts, et http/vcs.ts.

Format de fichier de flux de travail

Un workflow est un fichier YAML à l'adresse .cadcamfun/workflows/<name>.yml dans le référentiel du projet, versionné avec le modèle qu'il vérifie. Sa forme reflète les actions GitHub (on, jobs, needs, steps, uses, with), mais uses nomme toujours une étape CADCAMFUN enregistrée. Un workflow ne peut pas exécuter une commande shell ou une image de conteneur.

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

Utilisation des globes * pour correspondre dans un segment de chemin et ** pour correspondre à tous les segments. Une liste de filtres omise correspond à tout. toolpaths/*.json matchs toolpaths/a.json mais pas toolpaths/x/a.json; toolpaths/** correspond aux deux.

Référence de l'étape

Les étapes pures lisent uniquement les fichiers du commit en cours de vérification, jamais la base de données active, donc une exécution rend compte exactement de l'arborescence qui a été poussée. Les étapes basées sur un service sont enregistrées une fois que leur service existe. En attendant, en nommer un est une erreur grave, et non une opération silencieuse.

Malformé with les valeurs sont lues de manière défensive : une non-chaîne là où une chaîne est attendue, ou un nombre non fini, est ignoré plutôt que d'échouer l'exécution. Vérifiez les sorties pour confirmer un filtre tel que toolpath effectivement appliqué.

Sorties et interpolation

Une étape avec un id stocke ses sorties à l'échelle de l'exécution, afin qu'un travail puisse lire les sorties des travaux qu'il needs. À l’intérieur de n’importe quelle chaîne with, ${{ steps.<id>.outputs.<key> }} est remplacé de manière récursive par des objets et des tableaux. Lorsqu'une chaîne est constituée d'exactement une expression, la valeur conserve son type (un nombre reste un nombre). Incorporée dans un autre texte, la valeur est convertie en chaîne et une valeur manquante devient une chaîne vide. ai/prompt s'étend en outre ${{ files.<path> }} au texte de ce fichier dans le commit (vide si le fichier est absent).

Exécuter le cycle de vie et les erreurs

1. L'événement déclencheur (push, pull request ou manuel) sélectionne les workflows dans l'arborescence de la référence, lus à partir du commit plutôt que de la copie de travail.
2. Chaque fichier est analysé. Erreurs YAML (yaml), les erreurs de schéma (schema), inconnu needs (needs), cycles (cycle) et dupliquez les ID d'étape (duplicate-step-id) sont signalés comme une exécution non valide avec la raison.
3. Chaque uses est vérifié par rapport au registre avant que quoi que ce soit ne soit exécuté. Une étape inconnue fait échouer l'exécution avec Unknown step(s): ..., donc une faute de frappe n'applique jamais un changement à moitié.
4. Les tâches sont classées en niveaux. Chaque niveau s'exécute simultanément ; un travail dont needs tout n'a pas réussi est ignoré.
5. Événements de progression (job-start, step avec statut et sorties ou message, job-end) diffusent sur le bureau et le compagnon, et l'exécution est conservée avec ses événements.
6. L'exécution ne réussit que si chaque tâche a réussi. Les tâches ignorées sont considérées comme ayant échoué.

Événements en direct workflow.started (avec l'événement déclencheur) et workflow.finished (success, failure, ou cancelled) sont publiés pour chaque exécution.

Un run complet, tracé événement par événement

Ce workflow exécute toutes les règles du moteur à la fois : les sorties transmises entre les tâches, une valeur entière et une interpolation intégrée, continueOnError, if: failure, une tâche ignorée en raison de l'échec de sa dépendance et une tâche indépendante. Il a été exécuté avec runWorkflow et quatre gestionnaires d'étapes de test : demo/measure retours { volume: 7842.92, part }, demo/check imprime ce qu'il a reçu, demo/fail échoue avec StepError("tolerance exceeded") et demo/notify ne renvoie rien.

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

Correspondance des déclencheurs, testée

Chaque erreur d'analyse, reproduite

Au moment de l'exécution, n'importe quel uses sans gestionnaire enregistré, l'exécution complète échoue avant la première étape, répertoriant tous les identifiants inconnus : Unknown step(s): demo/measure, demo/check, …. Une faute de frappe n’applique donc jamais un flux de travail à moitié.

En 3D