ワークフロー

実行が評価するもの

ワークフロー ファイルは以下でコミットされます .cadcamfun/workflows/ と .yml または .yaml 拡大。サイドカーは、選択されたコミットされた参照からそれらをロードします。コミットされていない図面またはワークフローを編集しても、既存の実行で表示されるファイルは変更されません。

@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 トリガー、および識別子をキーとしたジョブ。ジョブには少なくとも 1 つのステップが含まれており、次のことを宣言できます。 needs。ステップには uses、オプション id および名前 (オプション) with 引数、 if、 そして continueOnError.

識別子は文字で始まり、最大 64 個の文字、数字、アンダースコア、またはハイフンを含みます。ステップ識別子はワークフロー全体で一意です。解析では、無効な YAML、スキーマの失敗、不明なジョブの依存関係、循環依存関係、重複したステップ ID が拒否されます。

組み込みチェック

• project/validate コミットされた JSON ファイルを解析し、認識された図面/コンポーネント/ツールパス エンティティ ID をファイル名と照合してチェックし、それらの名前を検証します。リソース数を返します。
• project/require-gcode コミットされたツールパスに空の G コードまたは欠落している G コードがある場合は失敗します。プロジェクトに少なくとも 1 つのツールパスが含まれている必要はありません。
• 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 引数は CAD エンティティ パスを直接置き換えることはできません。現在の実装は、クリーンな作業コピーをチェックせずにプロジェクトのコミットを委任します。また、チェックアウトされたブランチ上で現在のデータベース編集のスナップショットを作成します。これは、チェックされている参照とは異なる場合があります。この書き込みステップは、現在のブランチと作業状態をコミットする場合にのみ実行してください。

notify/push オプションのタイトル、本文、成功/失敗の結果を含む、実行のアクターのアプリケーション通知を作成します。これは永続的な通知ステップです。それ自体では、外部プッシュ プロバイダーを介した配信を確立しません。

ai/prompt プロンプトが必要で、オプションでシステム テキストとモデルを受け入れます。コミットされたファイルの内容を置き換えて、応答テキストとモデル ID を返すことができます。資格情報が欠落している場合、またはプロバイダー エラーがある場合は、このステップは失敗します。模範解答はアドバイス出力であり、確定的な幾何学チェックとは別のものです。

純粋な組み込みステップは、 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 以下の式を使用して値を計算します。 1 つの式だけで構成される値は、その型を保持します。長い文字列内の置換により、出力がテキストに変換されます。ジョブは、別のジョブの出力を消費するときに依存関係を宣言する必要があります。

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

トリガーとディスパッチ

on.push ブランチおよび変更されたパスのグロブ フィルターをサポートします。 on.pullRequest ベースブランチをフィルタリングします。 on.manual 明示的なディスパッチを有効にします。単一のアスタリスクはパス セグメント内で一致し、二重アスタリスクはセグメントにまたがることができます。

現在、HTTP コミット/プッシュ統合は、自動プッシュ トリガーに空の変更パス リストを提供します。したがって、プッシュ パス フィルターを備えたワークフローは、これらのイベントと一致しません。変更されたパスのデータが提供されるまで、この統合にはブランチのみのプッシュ フィルターまたは手動ディスパッチを使用してください。

コミットされた定義を次の場所で読み取ります。 GET /api/projects/:id/actions/workflows、オプションで ref。で 1 つお読みください /workflows/:name。不正な形式のファイルがその内容とともに返されます。 problem それで修理可能です。定義を編集するには、プロジェクトのコミットにその安全なワークフロー パスを含めます。

POST /api/projects/:id/actions/dispatch オプションの ref を受け入れ、その ref で一致するすべての手動ワークフローをディスパッチします。これは、1 つのワークフロー名のセレクターではありません。保存された結果を読み取る 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 を呼び出したりすることなく、手動ワークフローを解析し、登録された 1 つのチェックを実行し、そのジョブ結果を返します。

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.

フィルターを照合し、出力を安全に消費します

プッシュ トリガーでは、ブランチ フィルターが一致する必要があり、パス リストが存在する場合は、少なくとも 1 つの指定された変更されたパスが一致する必要があります。省略されたフィルターには制限がありません。明示的に空のリストは何も一致しません。手動イベントには次のものが必要です on.manual 存在すること。プル リクエストのマッチングでは、ヘッド プロポーザル名ではなくベース ブランチを使用します。

出力置換は、ネストされた配列とレコードを横断します。正確に欠落している出力式は未定義と評価されます。長い文字列に埋め込まれた出力が存在しない場合は、空のテキストになります。スキップされたステップまたは失敗したステップによって出力が生成されたことに依存しないでください。宣言する needs クロスジョブコンシューマーの場合、依存関係のスケジューリングによってデータの順序が確立されます。

ステップ if は 3 つのリテラル モードの 1 つであり、一般的な表現言語ではありません。ワークフロー変数、シェル補間、行列構築、任意の JavaScript 条件、およびサードパーティ アクションの読み込みは、このエンジンでは実装されません。別個の ai/prompt ハンドラー代替がコミットされました files.<path> references in its prompt;通常のステップでは、そのような追加の置換は行われません。

ソース： packages/workflow/src/trigger.ts, run.ts、 そして apps/sidecar/src/services/workflow-service-steps.ts.

省略されたブランチまたはパス フィルターはすべての値と一致します。手動ディスパッチは、次の宣言を行うワークフローのみに一致します。 on.manual、プルリクエスト イベントがワークフローの branches プル リクエストのベース ブランチに対するグロブ (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 }}"

グロブの使用 * 1 つのパス セグメント内で一致し、 ** セグメント間で一致させるため。省略されたフィルタ リストはすべてに一致します。 toolpaths/*.json マッチ toolpaths/a.json しかしそうではありません toolpaths/x/a.json; toolpaths/** 両方に一致します。

ステップリファレンス

純粋なステップでは、チェック対象のコミットのファイルのみが読み取られ、ライブデータベースは読み取られないため、実行ではプッシュされたツリーが正確にレポートされます。サービスによってサポートされるステップは、サービスが存在すると登録されます。それまでは、名前を付けることは重大な間違いであり、何もしないで済むわけではありません。

不正な形式 with 値は防御的に読み取られます。文字列が予期される非文字列、または非有限の数値は、実行に失敗するのではなく無視されます。出力をチェックして、次のようなフィルターを確認します。 toolpath 実際に適用しました。

出力と補間

とのステップ id 実行全体にわたって出力を保存するため、ジョブは実行中のジョブの出力を読み取ることができます。 needs。任意の文字列の内側 with, ${{ steps.<id>.outputs.<key> }} オブジェクトと配列を通じて再帰的に置き換えられます。文字列が 1 つの式だけで構成されている場合、値はその型を維持します (数値は数値のままです)。他のテキストに埋め込まれている場合、値は文字列に変換され、欠損値は空の文字列になります。 ai/prompt さらに拡張します ${{ files.<path> }} コミット内のそのファイルのテキストに追加されます (ファイルが存在しない場合は空です)。

実行ライフサイクルとエラー

1. トリガー イベント (プッシュ、プル リクエスト、または手動) は、参照のツリー内のワークフローを選択し、作業コピーではなくコミットから読み取ります。
2. 各ファイルが解析されます。 YAML エラー (yaml)、スキーマエラー(schema）、 未知 needs (needs)、サイクル(cycle)、重複したステップ ID (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 および 4 つのテスト ステップ ハンドラー: 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 登録されたハンドラーがないと、最初のステップの前に実行全体が失敗し、不明な ID がすべてリストされます。 Unknown step(s): demo/measure, demo/check, …。したがって、タイプミスによってワークフローが中途半端に適用されることはありません。

3Dで