سير العمل

ما تقييم المدى

يتم الالتزام بملفات سير العمل ضمن .cadcamfun/workflows/ مع أ .yml أو .yaml امتداد. يقوم السايدكار بتحميلها من مرجع مخصص محدد. لا يؤدي تحرير الرسم أو سير العمل غير الملتزم به إلى تغيير الملفات التي يشاهدها التشغيل الحالي.

@cadcamfun/workflow يوزع YAML، ويتحقق من التبعيات، ويطابق المشغلات، وينفذ الوظائف المسجلة. ولا ينفذ أوامر shell التعسفية أو صور الحاوية أو الإجراءات التي تم تنزيلها. كل 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-code و 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 أو الامتدادات النصية. إنه بمثابة حساب التشغيل ويتبع سياسة الفرع المحمي. لا يمكن لوسيطة الملف الإضافي أن تحل محل مسارات كيان CAD مباشرةً. يفوض التنفيذ الحالي التزام المشروع دون التحقق من وجود نسخة عمل نظيفة: فهو أيضًا يلتقط لقطات لتحريرات قاعدة البيانات الحالية في الفرع المسحوب، والتي يمكن أن تختلف عن المرجع الذي يتم التحقق منه. قم بتشغيل خطوة الكتابة هذه فقط عندما يكون من المقرر الالتزام بالفرع الحالي وحالة العمل.

notify/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 حاليًا قائمة فارغة للمسارات المتغيرة لمشغل الدفع التلقائي. وبالتالي فإن سير العمل مع مرشح مسار الدفع لا يتطابق مع تلك الأحداث. استخدم عوامل تصفية الدفع للفرع فقط أو الإرسال اليدوي لهذا التكامل حتى يتم توفير بيانات المسار المتغير.

اقرأ التعريفات الملتزمة على 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 أو استدعاء الذكاء الاصطناعي.

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.

مطابقة المرشحات واستهلاك المخرجات بأمان

يتطلب مشغل الدفع أن يتطابق مرشح الفرع الخاص به، وفي حالة وجود قائمة مسارات، يتم توفير مسار واحد على الأقل تم تغييره للمطابقة. عامل التصفية المحذوف غير مقيد؛ القائمة الفارغة بشكل صريح لا تتطابق مع أي شيء. يتطلب الحدث اليدوي 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 الكرات مقابل الفرع الأساسي لطلب السحب (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 المسجلة. لا يمكن لسير العمل تشغيل أمر shell أو صورة حاوية.

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. يحدد حدث التشغيل (طلب الدفع أو السحب أو اليدوي) مهام سير العمل في شجرة المرجع، ويتم قراءتها من الالتزام بدلاً من نسخة العمل.
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د