Рабочие процессы

Что оценивает пробег

Файлы рабочего процесса фиксируются под .cadcamfun/workflows/ с .yml или .yaml расширение. Sidecar загружает их из выбранной зафиксированной ссылки. Редактирование незафиксированного чертежа или рабочего процесса не приводит к изменению файлов, видимых при существующем запуске.

@cadcamfun/workflow анализирует YAML, проверяет зависимости, сопоставляет триггеры и выполняет зарегистрированные функции. Он не выполняет произвольные команды оболочки, образы контейнеров или загруженные действия. Каждый uses идентификатор должен существовать в текущем реестре бегуна до начала любого шага.

Напишите рабочий процесс

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

Рабочий процесс имеет имя, on триггеры и задания, связанные с идентификатором. Задание содержит хотя бы один шаг и может объявлять needs. Шаг имеет uses, необязательный id и имя, необязательно with аргументы, if, и continueOnError.

Идентификаторы начинаются с буквы и содержат не более 64 букв, цифр, символов подчеркивания или дефисов. Идентификаторы шагов уникальны для всего рабочего процесса. Анализ отклоняет недопустимый YAML, сбои схемы, неизвестные зависимости заданий, циклические зависимости и повторяющиеся идентификаторы шагов.

Встроенные проверки

• project/validate анализирует зафиксированные файлы JSON и сверяет распознанные идентификаторы объектов чертежа/компонента/траектории с их именами файлов и проверяет их имена. Он возвращает количество ресурсов.
• project/require-gcode завершается сбоем, если зафиксированная траектория имеет пустой или отсутствующий G-код. Не требуется, чтобы проект содержал хотя бы одну траекторию.
• cam/verify создает запросы воспроизведения на основе G-кода фиксированной траектории инструмента и Toolpath.data.request. Он не работает при обнаружении повторов серьезности ошибок или при появлении предупреждений. with.severity это warning. Необязательные аргументы: toolpath и tolerance.
• cam/gcode восстанавливается от совершенных data.request и сравнивает его обрезанный NC с зафиксированным текстом. Он принимает необязательный toolpath селектор.
• cam/sequence проверяет сохраненные запросы на наличие конфликтующих назначений номеров инструментов и запросы на остальную обработку, предыдущий инструмент которых не больше активного инструмента.

Шаги CAM считывают сохраненный формат запроса генератора. Об отсутствии NC, отсутствующих запросах на создание или неподдерживаемых запросах на проверку сообщается в skipped результаты, где это применимо; они не проваливают этот шаг автоматически. Проверьте количество проверенных/совпадающих и пропущенных причин. Зеленый рабочий процесс, содержащий только пропущенные операции CAM, не является доказательством проверенной программы.

Шаги, поддерживаемые сервисом

Живая сайдкар регистрируется vcs/commit, notify/push, и после того, как служба помощника существует, ai/prompt. Регистрация является явной: бегун, созданный без этих служб, завершает рабочий процесс с ошибкой, указывая недоступный шаг.

vcs/commit требует сообщения и принимает files запись текста под .cadcamfun/ с YAML, Markdown, JSON или текстовыми расширениями. Он действует как учетная запись запуска и подчиняется политике защищенных ветвей. Аргумент extra-file не может напрямую заменять пути к объектам САПР. Текущая реализация делегирует фиксацию проекта без проверки наличия чистой рабочей копии: она также делает снимки текущих изменений базы данных в извлеченной ветке, которые могут отличаться от проверяемой ссылки. Выполняйте этот шаг записи только в том случае, если текущая ветвь и рабочее состояние должны быть зафиксированы.

notify/push создает уведомление приложения для актера выполнения с необязательным заголовком, текстом и результатом успеха/неудачи. Это постоянный этап уведомления; он сам по себе не устанавливает доставку через внешнего поставщика push-уведомлений.

ai/prompt требует подсказки и при необходимости принимает системный текст и модель. Он может заменять зафиксированное содержимое файла и возвращает текст ответа и идентификатор модели. Отсутствие учетных данных или ошибка поставщика не позволяют выполнить этот шаг; ответ модели — это рекомендательный вывод, отдельный от проверок детерминированной геометрии.

Чистые встроенные шаги регистрируются в builtinSteps (apps/sidecar/src/services/workflow-steps.ts): project/validate, project/require-gcode, cam/verify, cam/gcode, и cam/sequence. Им нужны только зафиксированные файлы и @cadcamfun/core, поэтому они доступны, даже если помощник не запущен.

Выполнение, результаты и условия

Задания выполняются на уровнях зависимости, при этом независимые задания на уровне выполняются одновременно. Шаги внутри задания выполняются последовательно. Задания, зависимости которых не удалось выполнить, пропускаются. Условие шага по умолчанию: success; always выполняется после любого результата и failure запускается после предыдущего необработанного сбоя шага в этом задании.

continueOnError: true записывает событие неудачного шага без установки флага неудачного задания. В противном случае неудачный шаг пропускает последующие успешные шаги и отмечает, что задание не выполнено. Общий результат будет успешным только тогда, когда каждая работа будет успешной.

На более ранние результаты именованного шага можно ссылаться в with значения, используя выражение, показанное ниже. Значение, состоящее ровно из одного выражения, сохраняет свой тип; замена внутри более длинных строк преобразует вывод в текст. Задания должны объявлять зависимости, когда они потребляют результаты другого задания.

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

Триггеры и диспетчеризация

on.push поддерживает фильтры ветвей и измененных путей; on.pullRequest фильтрует базовую ветку; on.manual обеспечивает явную отправку. Одиночная звездочка соответствует сегменту пути, а двойная звездочка может охватывать сегменты.

Интеграция HTTP-фиксации и отправки в настоящее время предоставляет пустой список измененных путей для автоматического триггера отправки. Следовательно, рабочий процесс с фильтром пути отправки не соответствует этим событиям. Для этой интеграции используйте push-фильтры только для ветвей или ручную отправку, пока не будут предоставлены данные об измененном пути.

Прочтите принятые определения на GET /api/projects/:id/actions/workflows, опционально с ref. Прочитайте один на /workflows/:name. Некорректный файл возвращается со своим содержимым и problem так что его можно починить. Чтобы изменить определение, включите его безопасный путь рабочего процесса в фиксацию проекта.

POST /api/projects/:id/actions/dispatch принимает необязательную ссылку и отправляет каждый соответствующий ручной рабочий процесс по этой ссылке; это не селектор для одного имени рабочего процесса. Прочитать сохраненные результаты из GET /api/projects/:id/actions/runs.

Запуск настойчивости и событий

Средство запуска записывает рабочий процесс, событие, ссылку, SHA фиксации, статус, временные метки и накопленные события в WorkflowRun. События задания отмечают начало и конец; События шага включают индекс, идентификатор, статус, дополнительные выходные данные и текст ошибки. Недопустимый YAML сохраняется как неудачный запуск с событием недопустимого файла.

Текущий путь триггера HTTP ожидает завершения рабочих процессов, а затем вместе публикует запущенные и завершенные динамические события. Он не передает каждый текущий шаг через этот HTTP-запрос. Основной бегун предоставляет onEvent обратный вызов для интеграций, требующих поэтапного прогресса.

Точно интерпретируйте результаты

Рабочий процесс сообщает о зафиксированных реализациях фиксации и зарегистрированных шагов. Он не подтверждает последующие изменения рабочей копии и не удаляет уже записанную фиксацию в случае сбоя. Проверьте пропущенные проверки, политику предупреждений и соответствующие данные о траекториях инструментов, прежде чем использовать успешный запуск в качестве шлюза для выпуска.

Реализация разделена между packages/workflow/src для схемы/триггера/выполнения и вспомогательного кода workflow-runner.ts, workflow-steps.ts, и workflow-service-steps.ts для зафиксированных данных проекта, постоянных запусков и служб приложений.

Запуск примера изолированного механизма рабочего процесса

Потребитель пакета предоставляет зарегистрированные функции и их типизированный контекст. В этом примере анализируется ручной рабочий процесс, выполняется одна зарегистрированная проверка и возвращается результат задания без открытия SQLite или вызова 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" } }

Запуск в рабочей области в зависимости от эффекта и @cadcamfun/workflow, такой как apps/sidecar. Описанный выше пользовательский шаг является локальным для предоставленного реестра; присвоение ему имени в рабочем процессе рабочего стола не приводит к установке его в производственную версию.

Источник: packages/workflow/src/schema.ts и run.ts.

Сопоставьте фильтры и безопасно используйте выходные данные

Push-триггер требует, чтобы его фильтр ветвей соответствовал и, если список путей существует, по крайней мере один предоставленный измененный путь для соответствия. Опущенный фильтр не имеет ограничений; явно пустой список ничему не соответствует. Для ручного события требуется on.manual присутствовать. Сопоставление запроса на включение использует базовую ветвь, а не имя головного предложения.

Подстановка вывода проходит через вложенные массивы и записи. Точное отсутствующее выходное выражение оценивается как неопределенное; отсутствующий вывод, встроенный в более длинную строку, становится пустым текстом. Не полагайтесь на пропущенный или неудачный шаг для получения результата. Объявить needs для потребителей перекрестных заданий, поэтому планирование зависимостей устанавливает порядок данных.

Шаг if — это один из трех буквальных модусов, а не общий язык выражений. Переменные рабочего процесса, интерполяция оболочки, построение матриц, произвольные условия JavaScript и загрузка сторонних действий не реализуются этим движком. Отдельный ai/prompt замены обработчика зафиксированы files.<path> ссылки в его подсказке; обычные шаги не получают такой дополнительной замены.

Источник: packages/workflow/src/trigger.ts, run.ts, и apps/sidecar/src/services/workflow-service-steps.ts.

Фильтр пропущенных ветвей или путей соответствует каждому значению. Отправка вручную соответствует только рабочим процессам, которые объявляют on.manual, а событие запроса на включение соответствует событию рабочего процесса branches globs для базовой ветки запроса на включение (packages/workflow/src/trigger.ts).

Диагностика результатов рабочего процесса

Сохраненная история запусков по умолчанию возвращает последние запуски 50 на границе службы. Уведомления о событиях в реальном времени являются дополнительными каналами с максимальными усилиями: проверяйте сохраненные строки на предмет долговременного результата выполнения вместо того, чтобы рассматривать доставку уведомления как запись выполнения.

Источник: apps/sidecar/src/services/workflow-runner.ts, workflow-steps.ts, и http/vcs.ts.

Формат файла рабочего процесса

Рабочий процесс — это YAML-файл по адресу .cadcamfun/workflows/<name>.yml в репозитории проекта, версия которого соответствует проверяемой модели. Его форма отражает действия GitHub (on, jobs, needs, steps, uses, with), но uses всегда называет зарегистрированный шаг CADCAMFUN. Рабочий процесс не может запускать команду оболочки или образ контейнера.

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

Использование глобусов * для сопоставления в пределах одного сегмента пути и ** для сопоставления между сегментами. Опущенный список фильтров соответствует всему. toolpaths/*.json спички toolpaths/a.json но не toolpaths/x/a.json; toolpaths/** соответствует обоим.

Ссылка на шаг

Чистые шаги считывают только файлы проверяемого коммита, а не действующую базу данных, поэтому при запуске сообщается именно о том дереве, которое было отправлено. Шаги, поддерживаемые службой, регистрируются, как только их служба существует. До тех пор, называние одного из них является серьезной ошибкой, а не молчаливым бездействием.

искаженный with значения считываются в целях защиты: нестроковые значения, где ожидается строка, или неконечное число игнорируются, а не приводят к сбою выполнения. Проверьте выходные данные, чтобы подтвердить фильтр, например toolpath действительно применяется.

Выходы и интерполяция

Шаг с id хранит свои выходные данные в масштабе всего цикла, поэтому задание может читать выходные данные своих заданий. needs. Внутри любой строки в with, ${{ steps.<id>.outputs.<key> }} заменяется рекурсивно через объекты и массивы. Когда строка состоит ровно из одного выражения, значение сохраняет свой тип (число остается числом). Встроенное в другой текст значение преобразуется в строку, а отсутствующее значение становится пустой строкой. ai/prompt дополнительно расширяет ${{ files.<path> }} к тексту этого файла в коммите (пусто, если файл отсутствует).

Жизненный цикл запуска и ошибки

1. Событие триггера (push, pull request или вручную) выбирает рабочие процессы в дереве ссылки, считываемые из фиксации, а не из рабочей копии.
2. Каждый файл анализируется. Ошибки YAML (yaml), ошибки схемы (schema), неизвестный needs (needs), циклы (cycle) и повторяющиеся идентификаторы шагов (duplicate-step-id) сообщается как недействительный запуск с указанием причины.
3. Каждый uses проверяется по реестру перед запуском чего-либо. Неизвестный шаг приводит к сбою выполнения с Unknown step(s): ..., поэтому опечатка никогда не применяет изменение наполовину.
4. Работы упорядочены по уровням. Каждый уровень работает одновременно; работа, чья needs не всё удалось пропускается.
5. События прогресса (job-start, step со статусом и выходами или сообщением, job-end) транслируется на рабочий стол и в компаньон, а запуск сохраняется с его событиями.
6. Запуск завершается успешно только в том случае, если все задания выполнены успешно. Пропущенные задания считаются неуспешными.

Живые события workflow.started (с инициирующим событием) и workflow.finished (success, failure, или cancelled) публикуются для каждого запуска.

Полный запуск, отслеживание событий за событиями

Этот рабочий процесс одновременно применяет все правила движка: выходные данные, передаваемые между заданиями, целые значения и встроенную интерполяцию, continueOnError, if: failure, задание, пропущенное из-за сбоя его зависимости, и независимое задание. Оно проводилось с runWorkflow и четыре обработчика шагов тестирования: demo/measure возвращает { volume: 7842.92, part }, demo/check печатает то, что получил, demo/fail терпит неудачу с StepError("tolerance exceeded") и demo/notify ничего не возвращает.

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

Соответствие триггеров, проверено

Каждая ошибка синтаксического анализа воспроизводится

Во время выполнения любой uses без зарегистрированного обработчика весь запуск перед первым шагом завершается неудачей, перечисляя все неизвестные идентификаторы: Unknown step(s): demo/measure, demo/check, …. Поэтому опечатка никогда не влияет на рабочий процесс наполовину.

Через 3Д