Arbeitsabläufe

Was für ein Lauf wertet

Workflowdateien werden unter festgeschrieben .cadcamfun/workflows/ mit einem .yml oder .yaml verlängerung. Der Sidecar lädt sie von einer ausgewählten Commit-Referenz. Durch das Bearbeiten einer nicht festgeschriebenen Zeichnung oder eines Arbeitsablaufs werden die von einem vorhandenen Lauf angezeigten Dateien nicht geändert.

@cadcamfun/workflow analysiert die YAML, validiert Abhängigkeiten, gleicht Trigger ab und führt registrierte Funktionen aus. Es führt keine beliebigen Shell-Befehle, Container-Images oder heruntergeladenen Aktionen aus. Jede uses der Bezeichner muss in der aktuellen Registrierung des Läufers vorhanden sein, bevor ein Schritt gestartet wird.

Schreiben Sie einen Workflow

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

Ein Workflow hat einen Namen, on auslöser und nach Kennung verschlüsselte Jobs. Ein Job enthält mindestens einen Schritt und kann deklariert werden needs. Ein Schritt hat uses, fakultativ id und Name, optional with argumente, if, und continueOnError.

Bezeichner beginnen mit einem Buchstaben und enthalten höchstens 64 Buchstaben, Ziffern, Unterstriche oder Bindestriche. Schrittbezeichner sind im gesamten Workflow eindeutig. Das Parsen lehnt ungültiges YAML, Schemafehler, unbekannte Jobabhängigkeiten, zyklische Abhängigkeiten und doppelte Schrittbezeichner ab.

Integrierte Schecks

• project/validate analysiert festgeschriebene JSON-Dateien, vergleicht erkannte Zeichnungs-/Komponenten-/Werkzeugweg-Entitäts-IDs mit ihren Dateinamen und verifiziert deren Namen. Es gibt die Anzahl der Ressourcen zurück.
• project/require-gcode schlägt fehl, wenn ein festgeschriebener Werkzeugweg leeren oder fehlenden G-Code hat. Es ist nicht erforderlich, dass das Projekt mindestens einen Werkzeugweg enthält.
• cam/verify erstellt Wiederholungsanforderungen aus festgeschriebenem Werkzeugweg-G-Code und Toolpath.data.request. Es schlägt bei Wiederholungsbefunden der Fehlerschwere fehl, oder auch bei Warnungen, wenn with.severity ist warning. Optionale Argumente sind toolpath und tolerance.
• cam/gcode regeneriert sich aus dem Begangenen data.request und vergleicht seinen getrimmten NC mit dem festgeschriebenen Text. Es akzeptiert eine optionale Option toolpath wähler.
• cam/sequence prüft gespeicherte Anfragen auf widersprüchliche Werkzeugnummernzuordnungen und Restbearbeitungsanfragen, deren Vorgängerwerkzeug nicht größer als das aktive Werkzeug ist.

Die CAM-Schritte lesen das gespeicherte Generatoranforderungsformat. Fehlende NC, fehlende Generierungsanfragen oder nicht unterstützte Verifizierungsanfragen werden in gemeldet skipped ggf. Ausgänge; Sie scheitern nicht automatisch am Schritt. Überprüfen Sie die überprüfte/abgeglichene Anzahl und die übersprungenen Gründe. Ein grüner Workflow, der nur übersprungene CAM-Arbeiten enthält, ist kein Beweis für ein verifiziertes Programm.

Servicegestützte Schritte

Der Live-Sidecar registriert sich vcs/commit, notify/push, und, nachdem der Assistenzdienst existiert, ai/prompt. Die Registrierung ist explizit: Ein Läufer, der ohne diese Dienste erstellt wurde, scheitert an einem Workflow, der einen nicht verfügbaren Schritt benennt.

vcs/commit erfordert eine Nachricht und akzeptiert eine files aufzeichnung des Textes unten .cadcamfun/ mit YAML, Markdown, JSON oder Texterweiterungen. Es fungiert als Konto des Laufs und befolgt die Richtlinie für geschützte Zweige. Das Extradatei-Argument kann CAD-Entitätspfade nicht direkt ersetzen. Die aktuelle Implementierung delegiert das Projekt-Commit, ohne nach einer sauberen Arbeitskopie zu suchen: Sie erstellt außerdem Snapshots aktueller Datenbankänderungen am ausgecheckten Zweig, der sich von der überprüften Referenz unterscheiden kann. Führen Sie diesen Schreibschritt nur aus, wenn der aktuelle Zweig und der aktuelle Arbeitsstatus festgeschrieben werden sollen.

notify/push erstellt eine Anwendungsbenachrichtigung für den Akteur des Laufs mit optionalem Titel, Text und Erfolgs-/Fehlerergebnis. Es handelt sich um einen dauerhaften Benachrichtigungsschritt. Es stellt nicht selbst die Zustellung über einen externen Push-Anbieter her.

ai/prompt erfordert eine Eingabeaufforderung und akzeptiert optional Systemtext und ein Modell. Es kann festgeschriebene Dateiinhalte ersetzen und gibt Antworttext und Modellidentität zurück. Fehlende Anmeldeinformationen oder ein Anbieterfehler schlagen diesen Schritt fehl; Eine Modellantwort ist eine Beratungsausgabe, die von deterministischen Geometrieprüfungen getrennt ist.

Die reinen Einbauschritte werden eingetragen builtinSteps (apps/sidecar/src/services/workflow-steps.ts): project/validate, project/require-gcode, cam/verify, cam/gcode, und cam/sequence. Sie benötigen nur die festgeschriebenen Dateien und @cadcamfun/core, sodass sie auch dann verfügbar sind, wenn der Assistent nicht ausgeführt wird.

Ausführung, Ausgaben und Bedingungen

Jobs werden in Abhängigkeitsebenen ausgeführt, wobei unabhängige Jobs in einer Ebene gleichzeitig ausgeführt werden. Schritte innerhalb eines Jobs werden nacheinander ausgeführt. Jobs, deren Abhängigkeiten nicht erfolgreich waren, werden übersprungen. Die Standardschrittbedingung ist success; always läuft nach einem der Ergebnisse und failure wird nach einem vorherigen nicht behandelten Schrittfehler in diesem Job ausgeführt.

continueOnError: true zeichnet ein fehlgeschlagenes Schrittereignis auf, ohne das Fehlerflag des Jobs zu setzen. Andernfalls überspringt ein fehlgeschlagener Schritt spätere, nur erfolgreiche Schritte und markiert den Job als fehlgeschlagen. Das Gesamtergebnis ist nur dann Erfolg, wenn jede Aufgabe erfolgreich ist.

Auf frühere Ausgaben benannter Schritte kann in verwiesen werden with werte mithilfe des unten gezeigten Ausdrucks berechnen. Ein Wert, der aus genau einem Ausdruck besteht, behält seinen Typ; Durch die Ersetzung innerhalb längerer Zeichenfolgen wird die Ausgabe in Text umgewandelt. Jobs sollten Abhängigkeiten deklarieren, wenn sie die Ausgaben eines anderen Jobs nutzen.

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

Auslöser und Versand

on.push unterstützt Verzweigungs- und Pfadänderungs-Globfilter; on.pullRequest filtert den Basiszweig; on.manual ermöglicht den expliziten Versand. Ein einzelnes Sternchen entspricht einem Pfadsegment und ein doppeltes Sternchen kann sich über Segmente erstrecken.

Die HTTP-Commit/Push-Integration liefert derzeit eine leere Liste geänderter Pfade an den automatischen Push-Trigger. Folglich passt ein Workflow mit einem Push-Pfadfilter nicht zu diesen Ereignissen. Verwenden Sie für diese Integration Push-Filter nur für Verzweigungen oder den manuellen Versand, bis Daten zum geänderten Pfad bereitgestellt werden.

Lesen Sie Commit-Definitionen unter GET /api/projects/:id/actions/workflows, optional mit ref. Lesen Sie einen unter /workflows/:name. Eine fehlerhafte Datei wird mit ihrem Inhalt zurückgegeben und a problem damit es repariert werden kann. Um eine Definition zu bearbeiten, fügen Sie ihren sicheren Workflow-Pfad in ein Projekt-Commit ein.

POST /api/projects/:id/actions/dispatch akzeptiert eine optionale Referenz und sendet jeden passenden manuellen Workflow an dieser Referenz aus; Es handelt sich nicht um einen Selektor für einen einzelnen Workflownamen. Lesen Sie gespeicherte Ergebnisse aus GET /api/projects/:id/actions/runs.

Führen Sie Persistenz und Ereignisse aus

Der Runner zeichnet Workflow, Ereignis, Ref, Commit-SHA, Status, Zeitstempel und akkumulierte Ereignisse auf WorkflowRun. Jobereignisse markieren Beginn und Ende; Zu den Schrittereignissen gehören Index, Bezeichner, Status, optionale Ausgaben und Fehlertext. Ungültiges YAML wird als fehlgeschlagene Ausführung mit dem Ereignis „Ungültige Datei“ beibehalten.

Der aktuelle HTTP-Triggerpfad wartet darauf, dass Arbeitsabläufe abgeschlossen sind, und veröffentlicht dann gemeinsam gestartete und beendete Live-Ereignisse. Es wird nicht jeder laufende Schritt über diese HTTP-Anfrage gestreamt. Der Kernläufer legt ein frei onEvent rückruf für Integrationen, die einen schrittweisen Fortschritt erfordern.

Ergebnisse präzise interpretieren

Ein Workflow berichtet über seine erfassten Commit- und registrierten Schrittimplementierungen. Spätere Bearbeitungen der Arbeitskopie werden nicht zertifiziert und ein bereits aufgezeichneter Commit wird bei einem Fehler nicht entfernt. Überprüfen Sie übersprungene Prüfungen, Warnrichtlinien und relevante Werkzeugwegnachweise, bevor Sie einen erfolgreichen Lauf als Freigabetor verwenden.

Die Umsetzung ist aufgeteilt packages/workflow/src für Schema/Trigger/Ausführung und Sidecar workflow-runner.ts, workflow-steps.ts, und workflow-service-steps.ts für festgeschriebene Projektdaten, persistente Ausführungen und Anwendungsdienste.

Führen Sie ein Beispiel für eine isolierte Workflow-Engine aus

Ein Paketkonsument stellt die registrierten Funktionen und ihren typisierten Kontext bereit. In diesem Beispiel wird ein manueller Workflow analysiert, eine registrierte Prüfung ausgeführt und das Auftragsergebnis zurückgegeben, ohne SQLite zu öffnen oder AI aufzurufen.

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

Je nach Effekt und innerhalb eines Arbeitsbereichs ausführen @cadcamfun/workflow, wie zum Beispiel apps/sidecar. Der oben beschriebene benutzerdefinierte Schritt ist lokal für die bereitgestellte Registrierung. Wenn Sie es in einem Desktop-Workflow benennen, wird es nicht im Produktions-Sidecar installiert.

Quelle: packages/workflow/src/schema.ts und run.ts.

Passen Sie Filter an und nutzen Sie Ausgänge sicher

Ein Push-Trigger erfordert, dass sein Verzweigungsfilter übereinstimmt und, wenn eine Pfadliste vorhanden ist, mindestens ein bereitgestellter geänderter Pfad übereinstimmt. Ein weggelassener Filter ist uneingeschränkt; Eine explizit leere Liste entspricht nichts. Ein manuelles Ereignis erfordert on.manual anwesend sein. Der Pull-Request-Abgleich verwendet den Basiszweig und nicht den Namen des Hauptvorschlags.

Die Ausgabeersetzung durchläuft verschachtelte Arrays und Datensätze. Ein exakt fehlender Ausgabeausdruck wird als undefiniert ausgewertet; Eine fehlende Ausgabe, die in eine längere Zeichenfolge eingebettet ist, wird zu leerem Text. Verlassen Sie sich nicht darauf, dass ein übersprungener oder fehlgeschlagener Schritt zu einer Ausgabe geführt hat. Erklären needs für jobübergreifende Verbraucher, sodass die Abhängigkeitsplanung die Datenreihenfolge festlegt.

Schritt if ist einer von drei Literalmodi, keine allgemeine Ausdruckssprache. Workflow-Variablen, Shell-Interpolation, Matrix-Builds, beliebige JavaScript-Bedingungen und das Laden von Aktionen von Drittanbietern werden von dieser Engine nicht implementiert. Das Getrennte ai/prompt hundeführer ersetzt verpflichtet files.<path> verweise in der Eingabeaufforderung; Normale Schritte erhalten diese zusätzliche Ersetzung nicht.

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

Ein ausgelassener Zweig- oder Pfadfilter entspricht jedem Wert. Ein manueller Versand entspricht nur Workflows, die deklarieren on.manual, und ein Pull-Request-Ereignis entspricht dem des Workflows branches globs gegen den Basiszweig der Pull-Anfrage (packages/workflow/src/trigger.ts).

Diagnostizieren Sie Workflow-Ergebnisse

Der gespeicherte Ausführungsverlauf gibt standardmäßig die letzten 50 Ausführungen an der Dienstgrenze zurück. Live-Ereignisbenachrichtigungen sind Best-Effort-Nebenkanäle: Überprüfen Sie persistente Zeilen auf das dauerhafte Ausführungsergebnis, anstatt die Benachrichtigungszustellung als Ausführungsdatensatz zu behandeln.

Quelle: apps/sidecar/src/services/workflow-runner.ts, workflow-steps.ts, und http/vcs.ts.

Workflow-Dateiformat

Ein Workflow ist eine YAML-Datei unter .cadcamfun/workflows/<name>.yml im Projekt-Repository, versioniert mit dem überprüften Modell. Seine Form spiegelt GitHub Actions wider (on, jobs, needs, steps, uses, with), aber uses benennt immer einen registrierten CADCAMFUN-Schritt. Ein Workflow kann keinen Shell-Befehl oder ein Container-Image ausführen.

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

Verwendung von Globs * innerhalb eines Pfadsegments übereinstimmen und ** segmentübergreifend übereinstimmen. Eine weggelassene Filterliste passt zu allem. toolpaths/*.json streichhölzer toolpaths/a.json aber nicht toolpaths/x/a.json; toolpaths/** passt zu beiden.

Schrittreferenz

Reine Schritte lesen nur die Dateien des überprüften Commits, niemals die Live-Datenbank, sodass ein Lauf genau über den Baum berichtet, der gepusht wurde. Servicegestützte Schritte werden registriert, sobald ihr Service vorhanden ist. Bis dahin ist die Benennung eines Namens ein schwerwiegender Fehler und kein stilles No-Op.

Missgebildet with werte werden defensiv gelesen: Ein Nicht-String, bei dem ein String erwartet wird, oder eine nicht endliche Zahl wird ignoriert, anstatt dass der Lauf fehlschlägt. Überprüfen Sie die Ausgaben, um einen Filter zu bestätigen, z toolpath tatsächlich angewendet.

Ausgaben und Interpolation

Ein Schritt mit einem id speichert seine Ausgaben laufweit, sodass ein Job die Ausgaben der von ihm ausgeführten Jobs lesen kann needs. Innerhalb einer beliebigen Zeichenfolge in with, ${{ steps.<id>.outputs.<key> }} wird rekursiv durch Objekte und Arrays ersetzt. Wenn eine Zeichenfolge aus genau einem Ausdruck besteht, behält der Wert seinen Typ (eine Zahl bleibt eine Zahl). Eingebettet in anderen Text wird der Wert in eine Zeichenfolge umgewandelt und ein fehlender Wert wird zu einer leeren Zeichenfolge. ai/prompt erweitert sich zusätzlich ${{ files.<path> }} zum Text dieser Datei im Commit (leer, wenn die Datei nicht vorhanden ist).

Lebenszyklus und Fehler ausführen

1. Das Triggerereignis (Push, Pull Request oder manuell) wählt Workflows in der Struktur der Referenz aus, die aus dem Commit und nicht aus der Arbeitskopie gelesen werden.
2. Jede Datei wird analysiert. YAML-Fehler (yaml), schemafehler (schema), unbekannt needs (needs), zyklen (cycle) und doppelte Schritt-IDs (duplicate-step-id) werden mit Angabe des Grundes als ungültiger Lauf gemeldet.
3. Jeder uses wird mit der Registrierung abgeglichen, bevor etwas ausgeführt wird. Ein unbekannter Schritt schlägt bei der Ausführung fehl Unknown step(s): ..., sodass ein Tippfehler niemals eine halbe Änderung bewirkt.
4. Jobs sind in Ebenen geordnet. Jedes Level läuft gleichzeitig; ein Job, dessen needs war nicht alles erfolgreich wird übersprungen.
5. Fortschrittsereignisse (job-start, step mit Status und Ausgängen oder Meldung, job-end) auf den Desktop und den Begleiter streamen und der Lauf wird mit seinen Ereignissen beibehalten.
6. Der Lauf ist nur dann erfolgreich, wenn jeder Job erfolgreich war. Übersprungene Jobs gelten als nicht erfolgreich.

Live-Events workflow.started (mit dem auslösenden Ereignis) und workflow.finished (success, failure, oder cancelled) werden für jeden Lauf veröffentlicht.

Ein vollständiger Lauf, der Ereignis für Ereignis verfolgt wird

Dieser Workflow übt alle Regeln der Engine auf einmal aus: Ausgaben, die zwischen Jobs übergeben werden, ein Ganzwert und eine eingebettete Interpolation, continueOnError, if: failure, ein Job, der übersprungen wurde, weil seine Abhängigkeit fehlgeschlagen ist, und ein unabhängiger Job. Es wurde mit gelaufen runWorkflow und vier Testschritthandler: demo/measure kehrt zurück { volume: 7842.92, part }, demo/check druckt, was es empfangen hat, demo/fail scheitert mit StepError("tolerance exceeded") und demo/notify gibt nichts zurück.

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

Trigger-Matching, getestet

Jeder Analysefehler wird reproduziert

Zur Laufzeit beliebig uses ohne einen registrierten Handler schlägt der gesamte Lauf vor dem ersten Schritt fehl und listet alle unbekannten IDs auf: Unknown step(s): demo/measure, demo/check, …. Ein Tippfehler führt daher niemals zur halben Umsetzung eines Workflows.

In 3D