Flujos de trabajo

Lo que evalúa una carrera

Los archivos de flujo de trabajo se confirman en .cadcamfun/workflows/ con un .yml o .yaml extensión. El sidecar los carga desde una referencia comprometida seleccionada. La edición de un dibujo o flujo de trabajo no confirmado no cambia los archivos vistos por una ejecución existente.

@cadcamfun/workflow analiza el YAML, valida dependencias, coincide con activadores y ejecuta funciones registradas. No ejecuta comandos de shell arbitrarios, imágenes de contenedores ni acciones descargadas. Cada uses el identificador debe existir en el registro actual del corredor antes de que comience cualquier paso.

Escribir un flujo de trabajo

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

Un flujo de trabajo tiene un nombre, on activadores y trabajos codificados por identificador. Un trabajo contiene al menos un paso y puede declarar needs. un paso tiene uses, opcional id y nombre, opcional with argumentos, if, y continueOnError.

Los identificadores comienzan con una letra y contienen como máximo 64 letras, dígitos, guiones bajos o guiones. Los identificadores de pasos son únicos en todo el flujo de trabajo. El análisis rechaza YAML no válido, errores de esquema, dependencias de trabajos desconocidos, dependencias cíclicas e identificadores de pasos duplicados.

Controles incorporados

• project/validate analiza archivos JSON comprometidos y verifica los ID de entidad de dibujo/componente/ruta de herramienta reconocidos con sus nombres de archivo y verifica sus nombres. Devuelve recuentos de recursos.
• project/require-gcode falla si una trayectoria comprometida tiene un código G vacío o faltante. No requiere que el proyecto contenga al menos una trayectoria.
• cam/verify genera solicitudes de reproducción a partir del código G de trayectoria de herramienta comprometida y Toolpath.data.request. Falla en los resultados de reproducción de gravedad de errores, o también en las advertencias cuando with.severity es warning. Los argumentos opcionales son toolpath y tolerance.
• cam/gcode se regenera a partir del comprometido data.request y compara su NC recortado con el texto comprometido. Acepta una opción toolpath selector.
• cam/sequence comprueba las solicitudes almacenadas en busca de asignaciones de números de herramientas conflictivas y solicitudes de mecanizado de restos cuya herramienta anterior no sea más grande que la herramienta activa.

Los pasos CAM leen el formato de solicitud del generador almacenado. NC faltantes, solicitudes de generación faltantes o solicitudes de verificación no admitidas se informan en skipped resultados cuando corresponda; no fallan automáticamente en el paso. Inspeccione el recuento verificado/coincidente y los motivos omitidos. Un flujo de trabajo ecológico que contenga únicamente trabajo CAM omitido no es prueba de un programa verificado.

Pasos respaldados por el servicio

El sidecar en vivo se registra vcs/commit, notify/push, y, una vez existido el servicio de asistente, ai/prompt. El registro es explícito: un ejecutor creado sin estos servicios falla en un flujo de trabajo que nombra un paso no disponible.

vcs/commit requiere un mensaje y acepta un files registro de texto bajo .cadcamfun/ con extensiones YAML, Markdown, JSON o texto. Actúa como cuenta de ejecución y obedece a la política de rama protegida. El argumento de archivo adicional no puede reemplazar directamente las rutas de la entidad CAD. La implementación actual delega la confirmación del proyecto sin verificar si hay una copia de trabajo limpia: también toma instantáneas de las ediciones actuales de la base de datos en la rama desprotegida, que puede diferir de la referencia que se está verificando. Ejecute este paso de escritura solo cuando se pretenda confirmar la rama actual y el estado de trabajo.

notify/push crea una notificación de aplicación para el actor de la ejecución, con título, cuerpo y resultado de éxito/fracaso opcionales. Es un paso de notificación persistente; por sí solo no establece la entrega a través de un proveedor push externo.

ai/prompt requiere un mensaje y, opcionalmente, acepta texto del sistema y un modelo. Puede sustituir el contenido del archivo confirmado y devuelve el texto de respuesta y la identidad del modelo. Las credenciales faltantes o un error del proveedor fallan en este paso; una respuesta modelo es un resultado de asesoramiento, independiente de las comprobaciones de geometría deterministas.

Los peldaños incorporados puros están registrados en builtinSteps (apps/sidecar/src/services/workflow-steps.ts): project/validate, project/require-gcode, cam/verify, cam/gcode, y cam/sequence. Sólo necesitan los archivos comprometidos y @cadcamfun/core, por lo que están disponibles incluso cuando el asistente no está en ejecución.

Ejecución, resultados y condiciones.

Los trabajos se ejecutan en niveles de dependencia, y los trabajos independientes en un nivel se ejecutan simultáneamente. Los pasos dentro de un trabajo se ejecutan secuencialmente. Se omiten los trabajos cuyas dependencias no tuvieron éxito. La condición de paso predeterminada es success; always se ejecuta después de cualquier resultado y failure se ejecuta después de un error de paso anterior no controlado en ese trabajo.

continueOnError: true registra un evento de paso fallido sin establecer el indicador de error del trabajo. De lo contrario, un paso fallido omitirá los pasos posteriores que solo sean exitosos y marcará el trabajo como fallido. El resultado general es el éxito sólo cuando cada trabajo tiene éxito.

Se puede hacer referencia a resultados de pasos con nombre anteriores en with valores utilizando la expresión que se muestra a continuación. Un valor que consta exactamente de una expresión conserva su tipo; la sustitución dentro de cadenas más largas convierte la salida en texto. Los trabajos deben declarar dependencias cuando consumen los resultados de otro trabajo.

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

Disparadores y despacho

on.push admite filtros globales de rama y de ruta modificada; on.pullRequest filtra la rama base; on.manual permite el envío explícito. Un solo asterisco coincide dentro de un segmento de ruta y un asterisco doble puede abarcar segmentos.

La integración de confirmación/envío HTTP actualmente proporciona una lista vacía de rutas modificadas al activador de envío automático. En consecuencia, un flujo de trabajo con un filtro de ruta de inserción no coincide con esos eventos. Utilice filtros de inserción solo para sucursales o envío manual para esta integración hasta que se proporcionen los datos de la ruta modificada.

Lea las definiciones comprometidas en GET /api/projects/:id/actions/workflows, opcionalmente con ref. Lea uno en /workflows/:name. Se devuelve un archivo con formato incorrecto con su contenido y un problem para que pueda ser reparado. Para editar una definición, incluya su ruta de flujo de trabajo segura en una confirmación del proyecto.

POST /api/projects/:id/actions/dispatch acepta una referencia opcional y envía todos los flujos de trabajo manuales coincidentes en esa referencia; no es un selector para un nombre de flujo de trabajo. Leer resultados guardados de GET /api/projects/:id/actions/runs.

Ejecutar persistencia y eventos

El corredor registra el flujo de trabajo, el evento, la referencia, el SHA de confirmación, el estado, las marcas de tiempo y los eventos acumulados en WorkflowRun. Los eventos laborales marcan el comienzo y el final; Los eventos de paso incluyen índice, identificador, estado, salidas opcionales y texto de error. El YAML no válido se conserva como una ejecución fallida con un evento de archivo no válido.

La ruta de activación HTTP actual espera a que los flujos de trabajo se establezcan y luego publica juntos los eventos en vivo iniciados y finalizados de la ejecución. No transmite cada paso de ejecución a través de esa solicitud HTTP. El corredor central expone un onEvent devolución de llamada para integraciones que necesitan un avance gradual.

Interpretar los resultados con precisión

Un flujo de trabajo informa sobre su compromiso capturado y las implementaciones de pasos registrados. No certifica ediciones posteriores de la copia de trabajo ni elimina una confirmación ya registrada en caso de falla. Inspeccione las comprobaciones omitidas, la política de advertencias y la evidencia de trayectoria de herramientas relevante antes de utilizar una ejecución exitosa como puerta de liberación.

La implementación se divide entre packages/workflow/src para esquema/disparador/ejecución y sidecar workflow-runner.ts, workflow-steps.ts, y workflow-service-steps.ts para datos de proyectos comprometidos, ejecuciones persistentes y servicios de aplicaciones.

Ejecute un ejemplo de motor de flujo de trabajo aislado

Un consumidor de paquete proporciona las funciones registradas y su contexto escrito. Este ejemplo analiza un flujo de trabajo manual, ejecuta una verificación registrada y devuelve el resultado del trabajo sin abrir SQLite ni invocar 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" } }

Ejecutar dentro de un espacio de trabajo dependiendo del efecto y @cadcamfun/workflow, como apps/sidecar. El paso personalizado anterior es local para el registro proporcionado; nombrarlo en un flujo de trabajo de escritorio no lo instala en el sidecar de producción.

Fuente: packages/workflow/src/schema.ts y run.ts.

Haga coincidir filtros y consuma resultados de forma segura

Un disparador de inserción requiere que su filtro de rama coincida y, cuando existe una lista de rutas, se proporciona al menos una ruta modificada para que coincida. Un filtro omitido no tiene restricciones; una lista explícitamente vacía no coincide con nada. Un evento manual requiere on.manual estar presente. La coincidencia de solicitudes de extracción utiliza la rama base, en lugar del nombre de la propuesta principal.

La sustitución de salida atraviesa registros y matrices anidados. Una expresión de salida exacta que falta se evalúa como indefinida; una salida ausente incrustada en una cadena más larga se convierte en texto vacío. No confíe en que un paso omitido o fallido haya producido un resultado. Declarar needs para consumidores de trabajos cruzados, por lo que la programación de dependencia establece el orden de los datos.

Paso if es uno de los tres modos literales, no un lenguaje de expresión general. Este motor no implementa variables de flujo de trabajo, interpolación de shell, compilaciones de matrices, condiciones arbitrarias de JavaScript ni carga de acciones de terceros. el separado ai/prompt sustitutos del manejador comprometidos files.<path> referencias en su mensaje; los pasos ordinarios no reciben esa sustitución adicional.

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

Un filtro de ruta o rama omitido coincide con todos los valores. Un envío manual coincide solo con flujos de trabajo que declaran on.manualy un evento de solicitud de extracción coincide con el flujo de trabajo branches globos contra la rama base de la solicitud de extracción (packages/workflow/src/trigger.ts).

Diagnosticar los resultados del flujo de trabajo

El historial de ejecución guardado devuelve las últimas 50 ejecuciones de forma predeterminada en el límite del servicio. Las notificaciones de eventos en vivo son canales secundarios de mejor esfuerzo: inspeccionar las filas persistentes para obtener el resultado de la ejecución duradera en lugar de tratar la entrega de notificaciones como el registro de ejecución.

Fuente: apps/sidecar/src/services/workflow-runner.ts, workflow-steps.ts, y http/vcs.ts.

Formato de archivo de flujo de trabajo

Un flujo de trabajo es un archivo YAML en .cadcamfun/workflows/<name>.yml en el repositorio del proyecto, versionado con el modelo que verifica. Su forma refleja las acciones de GitHub (on, jobs, needs, steps, uses, with), pero uses siempre nombra un paso registrado de CADCAMFUN. Un flujo de trabajo no puede ejecutar un comando de shell ni una imagen de contenedor.

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 coincidir dentro de un segmento de ruta y ** para hacer coincidir entre segmentos. Una lista de filtros omitida coincide con todo. toolpaths/*.json partidos toolpaths/a.json pero no toolpaths/x/a.json; toolpaths/** coincide con ambos.

Referencia de paso

Los pasos puros leen solo los archivos de la confirmación que se está verificando, nunca la base de datos activa, por lo que una ejecución informa exactamente sobre el árbol que se envió. Los pasos respaldados por el servicio se registran una vez que existe su servicio. Hasta entonces, nombrar uno es un error grave, no una operación silenciosa.

Malformado with los valores se leen de forma defensiva: se ignora un elemento que no es una cadena donde se espera una cadena, o un número no finito, en lugar de fallar la ejecución. Verifique las salidas para confirmar un filtro como toolpath realmente aplicado.

Salidas e interpolación

Un paso con un id almacena sus resultados en toda la ejecución, por lo que un trabajo puede leer los resultados de los trabajos que needs. Dentro de cualquier cadena en with, ${{ steps.<id>.outputs.<key> }} se reemplaza recursivamente a través de objetos y matrices. Cuando una cadena consta exactamente de una expresión, el valor mantiene su tipo (un número sigue siendo un número). Incrustado en otro texto, el valor se convierte en una cadena y un valor faltante se convierte en una cadena vacía. ai/prompt adicionalmente se expande ${{ files.<path> }} al texto de ese archivo en la confirmación (vacío si el archivo está ausente).

Ejecutar ciclo de vida y errores.

1. El evento desencadenante (push, pull request o manual) selecciona flujos de trabajo en el árbol de la referencia, leídos desde la confirmación en lugar de la copia de trabajo.
2. Cada archivo se analiza. Errores YAML (yaml), errores de esquema (schema), desconocido needs (needs), ciclos (cycle) y duplicar los ID de los pasos (duplicate-step-id) se informan como una ejecución no válida con el motivo.
3. Cada uses se compara con el registro antes de que se ejecute algo. Un paso desconocido falla la ejecución con Unknown step(s): ..., por lo que un error tipográfico nunca aplica un cambio a medias.
4. Los trabajos están ordenados en niveles. Cada nivel se ejecuta al mismo tiempo; un trabajo cuyo needs no todos tuvieron éxito se omiten.
5. Eventos de progreso (job-start, step con estado y salidas o mensaje, job-end) transmite al escritorio y al complemento, y la ejecución persiste con sus eventos.
6. La ejecución tiene éxito sólo si todos los trabajos se realizaron correctamente. Los trabajos omitidos se consideran no exitosos.

Eventos en vivo workflow.started (con el evento desencadenante) y workflow.finished (success, failure, o cancelled) se publican para cada ejecución.

Una ejecución completa, rastreada evento por evento

Este flujo de trabajo ejercita todas las reglas del motor a la vez: resultados pasados entre trabajos, un valor completo y una interpolación integrada, continueOnError, if: failure, un trabajo omitido porque falló su dependencia y un trabajo independiente. fue ejecutado con runWorkflow y cuatro controladores de pasos de prueba: demo/measure regresa { volume: 7842.92, part }, demo/check imprime lo que recibió, demo/fail falla con StepError("tolerance exceeded") y demo/notify no devuelve 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"}}

Coincidencia de disparadores, probado

Cada error de análisis, reproducido.

En tiempo de ejecución, cualquier uses sin un controlador registrado falla toda la ejecución antes del primer paso, enumerando cada identificación desconocida: Unknown step(s): demo/measure, demo/check, …. Por lo tanto, un error tipográfico nunca aplica a medias un flujo de trabajo.

En 3D