Holarch

SysML v2

واجهة API وMCP في مشاريع SysML v2

اقرأ نماذج SysML v2 وابحث فيها وافحصها من البرامج النصية وأدوات الذكاء الاصطناعي باستخدام رمز وصول شخصي، واقترح تغييرات تراجعها وتطبقها في Holarch، واقرأ والتزم عبر Systems Modeling API، حيث الفروع طلبات تغيير.

طريقة استخدامها ←

في هذه الصفحة
  1. نظرة عامة
  2. المفاهيم
  3. طريقة استخدامها
    1. قراءة مشروع SysML v2 باستخدام curl
    2. فحص نص SysML قبل اقتراحه
    3. اقتراح تغيير وتطبيقه
    4. ربط أداة ذكاء اصطناعي بمشروع SysML v2
    5. مثال تطبيقي: المشروع التوضيحي Hybrid Car
    6. نصائح
  4. مسارات REST لمشاريع SysML v2
    1. القيم
  5. أدوات MCP لمشاريع SysML v2
    1. تعديلات العناصر
    2. النص المقترح
  6. المقترحات في مشاريع SysML v2
    1. مراجعة مقترح SysML v2
  7. Systems Modeling API
    1. إيداع التغييرات
  8. الرسائل
  9. الحدود
  10. صفحات ذات صلة

نظرة عامة

تعمل مشاريع SysML v2 مع REST API نفسها ونقطة نهاية MCP نفسها ورموز الوصول الشخصية نفسها التي تعمل معها مشاريع LML. تقرأ البرامج النصية وأدوات الذكاء الاصطناعي النموذج كعناصر ونص SysML، وتفحص النص قبل أن تغيّر أي شيء، وتقترح التغييرات. ولا يتغير شيء في النموذج حتى يراجع شخص المقترح في Holarch ويطبّقه.

ثلاث طرق للدخول:

  • REST API: https://app.holarch.app/api/v1/projects/<project>/… للبرامج النصية ولوحات المعلومات. تقرأ العناصر والمتطلبات والتشخيصات ونص SysML، وتضيف التغييرات إلى مقترح.
  • MCP: https://app.holarch.app/mcp لأدوات الذكاء الاصطناعي مثل Claude. تقرأ أدوات SysML v2 النموذج وتبحث فيه وتفحصه وتقترح التغييرات.
  • Systems Modeling API: https://app.holarch.app/api/v1/sysml/…، بأشكال OMG Systems Modeling API لأدوات SysML v2 الأخرى. الفرع main هو النموذج الحي وهو للقراءة فقط؛ وكل فرع آخر طلب تغيير، وتذهب الإيداعات إليه. ولا يتغير النموذج الحي إلا حين يطبّق معتمِد طلب التغيير في Holarch.

الرموز والنطاقات وقوائم المشاريع ومبدّل المؤسسة وحدود المعدل وربط Claude هي نفسها كما في مشاريع LML. انظر واجهة API وMCP لإنشاء رمز وربط أداة ذكاء اصطناعي. وتشمل استدعاءات خريطة البرنامج (GET /api/v1/program-map، وGET /api/v1/projects/<project>/items/<item>/trace، وأداتا MCP program_map وtrace_chain) مشاريع SysML v2 وعناصرها.

المفاهيم

  • العنصر: عنصر واحد من نموذج SysML v2، مثل تعريف جزء أو منفذ أو متطلب. لكل عنصر id (معرّف UUID). وحيثما يطلب مسار أو أداة معرّفًا، يصلح أيضًا اسم مؤهل مثل Vehicles::Car::powertrain.
  • الموجز: الشكل المختصر للعنصر في القوائم: id وtype (الفئة الوصفية، مثل PartUsage) وname وshortName وqualifiedName وowner.
  • الحزمة ذات المستوى الأعلى: حزمة ليست داخل عنصر آخر. ونص SysML لمشروع هو نص واحد لكل حزمة ذات مستوى أعلى، إضافة إلى نص واحد للعناصر الواقعة خارج الحزم.
  • التشخيص: مشكلة تجدها نواة اللغة، مع code وseverity (error أو warning) وelementId وelement وargs. وتعطي تشخيصات الصياغة line وcol بدل عنصر.
  • المقترح: التغييرات التي يجمعها عميل API أو أداة ذكاء اصطناعي للمراجعة. ويُفتح مقترح واحد لكل رمز ومشروع. ويرسله العميل للمراجعة بعنوان وملخص.
  • الردود المقسّمة إلى صفحات: تأتي القوائم في صفحات (limit، offset). ويأتي نص SysML الطويل في صفحات من الأسطر (line، lines). والرد الذي ترك شيئًا يقول truncated: true.

طريقة استخدامها

استخدم الواجهة البرمجية حين يحتاج برنامج نصي أو أداة ذكاء اصطناعي إلى النموذج: للإبلاغ عن المتطلبات التي لا عناصر تستوفيها أو تتحقق منها، أو لفحص نص SysML لفريق مقابل النموذج، أو للسماح لأداة ذكاء اصطناعي بصياغة تغييرات على النموذج يراجعها مهندس بعد ذلك.

قراءة مشروع SysML v2 باستخدام curl

  1. أنشئ رمزًا تحت إعدادات الحساب ← رموز API (انظر واجهة API وMCP).
  2. اعرض مشاريعك:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

لمشاريع SysML v2 القيمة "language": "sysml2".

  1. احصل على ملخص النموذج:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

ترى أعداد العناصر لكل فئة وصفية، والحزم ذات المستوى الأعلى، وعدد الأخطاء والتحذيرات.

  1. ابحث عن العناصر، مثل كل تعريف جزء:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
  1. اقرأ نص SysML لحزمة:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

ينتهي النص الطويل بـ "truncated": true و"next": السطر الذي تطلبه بعد ذلك باستخدام line.

فحص نص SysML قبل اقتراحه

  1. أرسل النص الجديد لحزمة إلى مسار الفحص:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"root": "Vehicles", "text": "package Vehicles { … }"}' \
  https://app.holarch.app/api/v1/projects/<project>/sysml/check
  1. اقرأ الرد. تكون ok هي true حين لا يكون في النص أخطاء صياغة. وتدرج diagnostics أخطاء الصياغة مع line وcol، والأخطاء التي سيضيفها النص إلى النموذج. وchanges هو عدد تغييرات النموذج التي يجريها النص.

لا يغيّر الفحص شيئًا. ولا يحتاج إلا إلى رمز قراءة.

اقتراح تغيير وتطبيقه

يضيف رمز الكتابة التغييرات إلى المقترح المفتوح للرمز. ثم يرسل العميل المقترح للمراجعة.

  1. أضف تغييرًا. أرسل إما النص الجديد الكامل لحزمة، أو تعديلات عناصر:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"edits": [{"op": "create", "kind": "attribute", "owner": "Vehicles::Car", "name": "range", "typedBy": ["LengthValue"]}]}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes

تحصل على 201 مع المقترح، وملخص التغيير والعناصر التي يضيفها ويغيّرها ويزيلها. ويُرفض التغيير الذي يضيف تشخيصات أخطاء (انظر المقترحات في مشاريع SysML v2).

  1. أضف مزيدًا من التغييرات بالطريقة نفسها. ويُفحص كل تغيير مقابل النموذج بعد تطبيق التغييرات السابقة في المقترح.
  2. أرسل المقترح للمراجعة:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "Add range attribute", "summary": "Adds Car::range for the range requirement."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal
  1. في Holarch، افتح المشروع، ثم افتح ✦ الذكاء الاصطناعي ▾ ← مراجعة “Add range attribute”… (أو الإشعار تحت الجرس).
  2. افحص الصفوف وانقر تطبيق المحدد.

    تُطبَّق التغييرات المحددة مع اسمك في السجل، ويُلغي تراجع واحد ذلك كله.

ربط أداة ذكاء اصطناعي بمشروع SysML v2

  1. اربط أداة الذكاء الاصطناعي بـ https://app.holarch.app/mcp برمز أو بتسجيل الدخول (انظر واجهة API وMCP).
  2. اسأل عن النموذج، مثل “لخّص نموذج Hybrid Car في Holarch” أو “ما المتطلبات غير المتحقَّق منها في مشروع Hybrid Car؟”.

    تستخدم أداة الذكاء الاصطناعي model_summary وlist_elements وlist_requirements وأدوات القراءة الأخرى.

  3. اطلب تغييرًا، مثل “اقترح سمة range على Car”.

    تقرأ أداة الذكاء الاصطناعي الحزمة بـ get_sysml، وتقترح نصًا أو تعديلات عناصر، وتصلح أي تشخيصات يعيدها الفحص.

  4. راجع المقترح في Holarch وانقر تطبيق المحدد.

مثال تطبيقي: المشروع التوضيحي Hybrid Car

أنشئ المشروع التوضيحي بـ إدارة المشاريع ← ملفات المشروع ▾ ← مشروع توضيحي جديد ← Hybrid Car (SysML v2)، ثم أنشئ له رمزًا للقراءة والكتابة.

  1. يدرج GET /api/v1/projects/<project>/model الحزم ذات المستوى الأعلى، ومنها Vehicles وHybridCarArchitecture وVehicleBehavior.
  2. يجد GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def العنصر Vehicles::Engine.
  3. يعيد GET /api/v1/projects/<project>/elements/Vehicles::Engine تعريف الجزء مع نص SysML الخاص به، وأعضائه (displacement وcylinders وmaxPower والمنافذ fuelIn وoutput وecu) والاستخدامات المنمَّطة به.
  4. يدرج GET /api/v1/projects/<project>/elements/Vehicles::Car/connections الواجهة driveShaft من powertrain.output إلى frontAxle.input.
  5. يدرج GET /api/v1/projects/<project>/requirements?status=unverified المتطلبات التي لا تتحقق منها أي حالة تحقق، مع معرّفاتها مثل VR-4.1.
  6. يضيف POST /api/v1/projects/<project>/proposal/changes مع {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} التغيير إلى المقترح. ويرسله POST /api/v1/projects/<project>/proposal مع عنوان.
  7. في Holarch، يُظهر ✦ الذكاء الاصطناعي ▾ ← مراجعة “…” القسم متغير: مع تعريف الجزء والحقل doc، وفرق النص لـ Vehicles. ويطبّقه تطبيق المحدد.

نصائح

  • اقرأ الحزمة بـ get_sysml (أو GET …/sysml?root=) قبل اقتراح نص جديد لها. فالعناصر المستبعدة من النص المقترح تُزال.
  • فضّل تعديلات العناصر للتغييرات الصغيرة. فهي لا تغيّر إلا العناصر المسمّاة وتُبقي باقي نص الحزمة كما هو.
  • افحص النص بـ check_sysml (أو POST …/sysml/check) أولًا. فهو يعيد التشخيصات نفسها التي سيُرفض بها المقترح.
  • سمِّ العناصر باسمها المؤهل في البرامج النصية. تبقى المعرّفات كما هي عند إعادة تسمية عنصر؛ أما الأسماء المؤهلة فلا.
  • أعطِ أداة الذكاء الاصطناعي رمزًا للقراءة فقط حين لا تفعل سوى الإجابة عن أسئلة حول النموذج.

مسارات REST لمشاريع SysML v2

العنوان الأساسي: https://app.holarch.app/api/v1. والإجابات بصيغة JSON. ويصف /api/v1/openapi.json (OpenAPI 3.1) هذه المسارات مع غيرها.

الطريقة والمسارما الذي يفعله
GET /projects/<project>/modelأعداد العناصر لكل فئة وصفية، والحزم ذات المستوى الأعلى مع أعداد عناصرها، وعدد الأخطاء والتحذيرات
GET /projects/<project>/elementsالبحث: query (أو q؛ نص في الاسم أو الاسم المختصر أو الاسم المؤهل أو doc)، وtype، وowner، وlimit (1–500، والافتراضي 50)، وoffset؛ مرتبة حسب الاسم المؤهل
GET /projects/<project>/elements/<id>عنصر واحد مع حقوله وdoc ونص SysML وأعضائه والاستخدامات المنمَّطة به؛ members (0–200، والافتراضي 100)
GET /projects/<project>/elements/<id>/connectionsالاتصالات والواجهات والروابط والتدفقات (مع العنصر المتدفق) والتعاقبات والانتقالات والتخصيصات والتبعيات عند العنصر أو ميزاته، وتلك المملوكة داخله؛ limit (الافتراضي 100)
GET /projects/<project>/requirementsالمتطلبات مع معرّفها وعبارتها (doc) وsatisfiedBy وverifiedBy؛ owner، وstatus (unsatisfied أو unverified)، وlimit (الافتراضي 100)، وoffset
GET /projects/<project>/diagnosticsتشخيصات النموذج، الأخطاء أولًا؛ ids (مفصولة بفواصل: تلك العناصر وأعضاؤها فقط)، وlimit (الافتراضي 200، وبحد أقصى 500)
GET /projects/<project>/sysmlنص SysML لحزمة ذات مستوى أعلى (root)، أو للعناصر الواقعة خارج الحزم (دون root)، أو لعنصر واحد (element)؛ line (السطر الأول، بدءًا من 1)، وlines (الافتراضي 2000، وبحد أقصى 5000)
POST /projects/<project>/sysml/checkفحص text كنص جديد لـ root (أو للعناصر الواقعة خارج الحزم)؛ لا يغيّر شيئًا
POST /projects/<project>/proposal/changesإضافة تغيير إلى المقترح المفتوح: {text, root} أو {edits}
GET /projects/<project>/proposalالمقترح المفتوح، أو مقترح بمعرّف proposal، مع حالته وتغييراته
POST /projects/<project>/proposalإرسال المقترح المفتوح للمراجعة: title، summary
DELETE /projects/<project>/proposalتجاهل المقترح المفتوح قبل إرساله

يعمل GET /projects وGET /projects/<project> أيضًا لمشاريع SysML v2. ويعطيان "language": "sysml2"، وتضيف إجابة المشروع elements وtypes (أعداد العناصر لكل فئة وصفية).

تجيب مسارات كيانات LML (/entities و/relationships و/schema وفحوص النموذج وفحص الجودة) بـ 409 wrong-project-type في مشروع SysML v2. وتجيب مسارات SysML v2 بالشيء نفسه في مشروع LML.

القيم

  • type: فئة وصفية مثل PartUsage أو RequirementDefinition، أو كلمة مفتاحية كما تُكتب في نص SysML: part وpart def وattribute وport وrequirement وaction وpackage وكلمات العناصر المفتاحية الأخرى.
  • owner، id، element، root: معرّف أو اسم مؤهل. ويقبل root أيضًا اسم حزمة ذات مستوى أعلى. ويجب أن يكون root حزمة ذات مستوى أعلى؛ ولقراءة نص عنصر واحد، استخدم element.
  • القيم الطويلة: يُقطع doc في قائمة عند 4,000 حرف، وdoc لعنصر منفرد عند 20,000، ونص SysML الخاص بالعنصر عند 16,000 حرف.

أدوات MCP لمشاريع SysML v2

تدرج نقطة نهاية MCP هذه الأدوات بجانب أدوات LML. وتجد أداة الذكاء الاصطناعي مشاريع SysML v2 بـ list_projects (language: sysml2). وكل أداة تأخذ project.

تأخذ أدوات القراءة أيضًا change_request اختياريًا (CR-12 أو معرّفه) لقراءة النموذج كما سيجعله طلب التغيير ذلك؛ ويأخذه propose_sysml وpropose_element_changes لحساب التغيير مقابل نموذج الطلب وتطبيقه في تلك المسودة بعد المراجعة. انظر طلبات التغيير للقواعد.

الأداةالوصولما الذي يفعله
model_summaryقراءةأعداد العناصر لكل فئة وصفية، والحزم ذات المستوى الأعلى وعدد التشخيصات
list_elementsقراءةالبحث عن العناصر بالنص (query) وtype وowner؛ مقسّمة إلى صفحات بـ limit وoffset
get_elementقراءةعنصر واحد (id) مع أنواعه وتخصيصاته وتعدديته وقيمته وأطرافه وdoc ونص SysML وأعضائه (members، 200 على الأكثر) والاستخدامات المنمَّطة به
get_connectionsقراءةالاتصالات والواجهات والروابط والتدفقات والتعاقبات والانتقالات والتخصيصات والتبعيات لعنصر (id، limit)
list_requirementsقراءةالمتطلبات مع معرّفها وعبارتها وsatisfy وverify؛ owner، وstatus (unsatisfied، unverified)، وlimit، وoffset
get_sysmlقراءةنص SysML لحزمة ذات مستوى أعلى (root)، أو للعناصر الواقعة خارج الحزم، أو لعنصر واحد (element)؛ line، lines (5000 على الأكثر)؛ ويعطي الرد next
get_sysml_textقراءةنص SysML للنموذج كله (كل حزمة ذات مستوى أعلى، ثم العناصر الواقعة خارج الحزم) أو لحزمة واحدة package، حتى 200,000 حرف لكل إجابة؛ وتسمّي الإجابة الحزم المستبعدة
check_sysmlقراءةدون text: تشخيصات النموذج (ids، limit). ومع text (وroot): أخطاء الصياغة مع السطر والعمود، والأخطاء التي سيضيفها النص. لا يغيّر شيئًا
propose_sysmlقراءة وكتابةاقتراح text الجديد الكامل لحزمة ذات مستوى أعلى (root)، أو للعناصر الواقعة خارج الحزم (دون root؛ وهو أيضًا موضع الحزمة الجديدة)
propose_element_changesقراءة وكتابةاقتراح edits (100 على الأكثر) دون إعادة كتابة النص: إنشاء أو تحديث أو نقل أو إزالة

تعمل list_diagrams وget_diagram وget_matrix في مشاريع SysML v2 أيضًا: تدرج list_diagrams العروض (مع نوعها، مثل InterconnectionView) ومخططات التحليل المحفوظة تحت عنصر؛ وتعطي get_diagram العناصر التي يكشفها عرض بعد مرشحاته (بمعرّف العنصر أو اسمه المؤهل)؛ وتعطي get_matrix كل متطلب مع ما يستوفيه ويتحقق منه.

تعمل أدوات المقترحات في مشاريع LML بالطريقة نفسها هنا: يرسل propose_changes المقترح بعنوان وملخص، ويتجاهله discard_proposal، ويُظهر get_proposal وlist_proposals حالته. والرمز المخصص للقراءة فقط لا يدرج إلا أدوات القراءة.

تعود أخطاء الأدوات كنتيجة أداة مع الرسالة والتشخيصات، لتتمكن أداة الذكاء الاصطناعي من إصلاح نصها والمحاولة مجددًا.

تعديلات العناصر

كل تعديل في edits (MCP) أو {"edits": […]} (REST) كائن فيه op:

opالحقول
createkind (كلمة مفتاحية مثل part وpart def وattribute وport وrequirement وaction وpackage) أو type (فئة وصفية)؛ وowner (إن حُذف: المستوى الأعلى)؛ وname (مطلوب)؛ واختياريًا shortName وtypedBy وspecializes وsubsets وredefines وmultiplicity وvalue وdoc وdirection (in، out، inout)
updateid والحقول المراد تغييرها، كما في الإنشاء؛ وnull أو "" يمسح الحقل
moveid وowner الجديد
removeid؛ يزيل العنصر مع أعضائه
  • typedBy وspecializes وsubsets وredefines قوائم حتى 20 اسمًا: معرّفات، أو أسماء مؤهلة، أو أسماء كما تُكتب في النص (تصلح أسماء المكتبة مثل MassValue).
  • يمكن للتعديلات اللاحقة تسمية العناصر المنشأة سابقًا في الاستدعاء نفسه بـ new:1 وnew:2 … بترتيب إنشائها، مثلًا كـ owner. ويدرجها الرد تحت created مع معرّفاتها الجديدة.
  • إعادة تسمية عنصر تحدّث أيضًا المراجع التي سمّته باسمه القديم.

النص المقترح

  • يستبدل propose_sysml نص الحزمة كله. وتحتفظ العناصر بمعرّفاتها حيث ما زال النص يعلنها. وتُزال العناصر المستبعدة من النص.
  • يجب أن يُحلَّل النص دون أن يبقى شيء غير مطبَّق. ويُرفض النص الذي لا يغيّر النموذج (no-change).

المقترحات في مشاريع SysML v2

تفحص نواة اللغة كل تغيير مقترح قبل أن ينضم إلى المقترح:

  • يُحلَّل النص دون أخطاء صياغة، وتُطبَّق تعديلات العناصر.
  • ما زالت الحزم المتغيرة تُطبع كنص SysML وتُحلَّل مجددًا.
  • لا يضيف التغيير تشخيصات أخطاء إلى النموذج، مثل الأسماء غير المحلولة أو أخطاء الأنواع. ولا تُحسب الأخطاء التي كانت في النموذج من قبل.

يُرفض التغيير الفاشل مع التشخيصات (حتى 50) المراد إصلاحها. ولا يُخزَّن شيء. ولا ترفض التحذيرات أي تغيير.

يحتاج الاقتراح إلى رمز للقراءة والكتابة ودور المحرر أو المالك في المشروع. ويحوي المقترح الواحد 200 تغيير و8 MB على الأكثر.

مراجعة مقترح SysML v2

افتح المشروع، ثم ✦ الذكاء الاصطناعي ▾ ← مراجعة “<title>”…. كل تغيير صف بمربع تحديد:

  • تدرج مضاف ومتغير ومحذوف العناصر، مع الحقول المتغيرة (أول 20 من كل منها؛ و“وn أخرى” للباقي).
  • يُظهر فرق نصي، موسوم بالحزمة، نص SysML قبل التغيير وبعده.
  • يُعلَّم التغيير الذي يزيل عناصر ويبدأ غير محدد.
  • افتح نموذج SysML v2 لتطبيق هذا التغيير. النموذج غير محمَّل؛ افتح صفحة SysML v2 في المشروع.
  • لم تعد الحزمة في النموذج؛ تم التخطي. أُزيلت الحزمة بعد اقتراح التغيير.

يزامن تطبيق المحدد كل تغيير نصي مجددًا مقابل النموذج الحالي ويُبقي التعديلات التي ما زالت عناصرها موجودة. ويفحص المجموعة كلها ويطبّقها كخطوة تراجع واحدة. وتُتخطى التغييرات التي لم تعد ملائمة وتُسمّى في إشعار. ويعمل رفض ولاحقًا كما في مقترحات LML، وكذلك الأدوار وانتهاء الصلاحية (7 أيام) والاحتفاظ (انظر المقترحات من عملاء الذكاء الاصطناعي).

Systems Modeling API

تقرأ أدوات SysML v2 الأخرى نماذج Holarch وتغيّرها عبر مسارات بأشكال OMG Systems Modeling API (REST/HTTP). والعنوان الأساسي https://app.holarch.app/api/v1/sysml. وتستخدم الرموز نفسها؛ ويمكن لأي دور في المشروع القراءة، ويمكن للمحررين والمالكين الإيداع.

  • المشاريع: لا تُدرج إلا مشاريع SysML v2. و@id للمشروع معرّف UUID تعطيه إياه هذه الواجهة؛ ويصلح أيضًا معرّف مشروع Holarch. وتتضمن الإجابة holarchId وurl.
  • الفروع: main هو النموذج الحي ولا يمكن تغييره عبر الواجهة. وكل فرع آخر طلب تغيير قيد التنفيذ، مسمّى “CR-12 Title” ويحمل holarchChangeRequest (id، label، status، url). وطلبات التغيير المنفَّذة أو المسحوبة في آخر 30 يومًا تبقى مدرجة، مع ضبط deleted.
  • الإيداعات: يكتب الإيداع التغييرات في فرع طلب تغيير. ولا تُقدَّم إلا رؤوس الفروع: رأس main هو النموذج الحي، ورأس فرع طلب التغيير هو النموذج الحي مع تغييرات الطلب. وتجيب معرّفات الإيداعات الأقدم بـ 404؛ احصل على الرأس الحالي من الفرع.
  • العناصر: لكل عنصر كل خصائص فئته الوصفية في مخطط OMG JSON، بما في ذلك المشتقة منها (owner وownedElement وqualifiedName وfeature وtype وما شابهها). ويُشار إلى عناصر المكتبة القياسية بمعرّفاتها القياسية، وهي المعرّفات التي تستخدمها أدوات SysML v2 الأخرى لعنصر المكتبة نفسه.
  • الوسوم والاستعلامات المحفوظة: لا شيء؛ وقوائمها فارغة.
الطريقة والمسارما الذي يفعله
GET /sysml/projectsمشاريع SysML v2 الخاصة بك
POST /sysml/projectsإنشاء مشروع SysML v2 فارغ (name، description)
GET /sysml/projects/<projectId>مشروع واحد، مع فرعه الافتراضي
GET /sysml/projects/<projectId>/branchesmain وفروع طلبات التغيير
POST /sysml/projects/<projectId>/branchesإنشاء فرع: طلب تغيير جديد في حالة مسودة (name عنوانه، وdescription سببه)
GET /sysml/projects/<projectId>/branches/<branchId>الفرع (@id الخاص به أو main)، مع head
DELETE /sysml/projects/<projectId>/branches/<branchId>سحب طلب التغيير
GET /sysml/projects/<projectId>/commitsالرؤوس والإيداعات المرسلة إلى الفروع، الأحدث أولًا
POST /sysml/projects/<projectId>/commits?branchId=<branchId>إيداع التغييرات في فرع (أدناه)
GET /sysml/projects/<projectId>/commits/<commitId>إيداع رأس
GET /sysml/projects/<projectId>/commits/<commitId>/changesما يغيّره الفرع مقابل النموذج الحي: DataVersion واحد لكل عنصر
GET /sysml/projects/<projectId>/commits/<commitId>/elementsكل عناصر الإيداع، مقسّمة إلى صفحات
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>عنصر واحد
GET /sysml/projects/<projectId>/commits/<commitId>/rootsالعناصر ذات المستوى الأعلى، مقسّمة إلى صفحات
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationshipsالعلاقات التي يكون العنصر مصدرها أو هدفها؛ وdirection هو in أو out أو both (الافتراضي)، مقسّمة إلى صفحات
POST /sysml/projects/<projectId>/query-resultsالعناصر المطابقة لاستعلام (الجسم أدناه)، مقسّمة إلى صفحات؛ ويجب أن يكون commitId رأسًا
GET /sysml/projects/<projectId>/tags، /queries، /commits/<commitId>/elements/<elementId>/projectUsagesقوائم فارغة

إجابات القوائم مصفوفات JSON. وتُقسَّم القوائم إلى صفحات بـ page[size] (الافتراضي 100، وبحد أقصى 1000) وpage[after] ( @id لآخر عنصر في الصفحة السابقة) أو page[before] ( @id لأول عنصر في الصفحة التالية). ويعطي الترويسة Link الصفحة التالية بـ rel="next" والسابقة بـ rel="prev".

الاستعلام كائن JSON فيه اختياريًا where ( PrimitiveConstraint مع property وoperator (= أو in أو < أو <= أو > أو >= أو instanceOf) وvalue وinverse، أو CompositeConstraint مع operator and أو or وconstraint)، وscope (معرّفات عناصر: يشملها البحث وما تملكه) وselect (الخصائص المراد إعادتها؛ ويعود @id و@type دائمًا):

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  "https://app.holarch.app/api/v1/sysml/projects/<projectId>/query-results" \
  -d '{"@type": "Query", "where": {"@type": "PrimitiveConstraint", "property": "@type", "operator": "=", "value": "PartDefinition", "inverse": false}, "select": ["name", "qualifiedName"]}'

قراءة عناصر نموذج:

curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects/<projectId>/branches/main
curl -i -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits/<head id>/elements?page[size]=500"

إيداع التغييرات

تحتاج الكتابة إلى رمز بصلاحية القراءة والكتابة، ودور المحرر أو المالك، وخطة Team (وكذلك للحسابات الأكاديمية وحسابات الفصول)، وتفعيل مراجعة الفروع للمشروع (طلبات التغيير ← الإعدادات). ويراجع معتمِد طلب التغيير ويطبّقه في Holarch؛ ولا تصوّت الرموز ولا تطبّق أبدًا.

  1. إنشاء فرع: POST /branches مع {"@type": "Branch", "name": "Cabin heater"}. والإجابة هي الفرع مع holarchChangeRequest الخاص به.
  2. اقرأ رأس الفرع وعناصره.
  3. POST /commits?branchId=<branch @id> مع قائمة من DataVersion:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits?branchId=<branch id>" \
  -d '{"@type": "Commit", "description": "Add the heater",
       "previousCommit": {"@id": "<head id>"},
       "change": [{"@type": "DataVersion", "identity": {"@id": "<new uuid>"},
                   "payload": {"@type": "PartDefinition", "declaredName": "CabinHeater", "owner": {"@id": "<package id>"}}}]}'
  • تغيير عنصر: أرسل العنصر كما قرأته مع تغيير الخصائص. ولا تُحسب إلا الخصائص المملوكة (declaredName وownedRelationship وisAbstract وما شابهها)؛ وتُتجاهل المشتقة، فإرسال ما قرأته كما هو لا يغيّر شيئًا. والخاصية التي تستبعدها تحتفظ بقيمتها؛ أرسل null أو [] لمسحها.
  • العناصر الجديدة: أعطِ العنصر معرّف UUID جديدًا ومعه إما عضويته المالكة (المرسلة في الإيداع نفسه) أو owner، الذي ينشئ العضوية لك.
  • إزالة عنصر: payload: null يزيله مع كل ما يملكه.
  • الفحوص: يجب أن تُطبع كل حزمة يمسّها الإيداع وتُحلَّل مجددًا، ويجب ألا يضيف الإيداع تشخيصات أخطاء؛ وإلا فالإجابة 422 مع diagnostics المراد إصلاحها.
  • previousCommit: الرأس الذي أُجري عليه تغييرك. فإن تحرك الفرع منذئذ، تكون الإجابة 409 stale-head مع head الحالي؛ اقرأ مجددًا وأودع فوقه.
  • إعادة المحاولة: أرسل ترويسة Idempotency-Key. وإعادة المحاولة بالمفتاح والجسم نفسيهما خلال 24 ساعة تحصل على الإجابة الأولى مجددًا.
  • الإيداعات في main: الإيداع دون branchId، أو مع main، يذهب إلى طلب التغيير المسودة الخاص برمزك (“API changes from <token name>”)، المنشأ عند أول إيداع من هذا النوع. وتذكر الإجابة أيّه في holarchChangeRequest وفي ترويسة Warning.
  • المشاريع الجديدة: المشروع المنشأ بـ POST /sysml/projects تكون مراجعة الفروع فيه مفعّلة. وأول إيداع له في main، ما دمت عضوه الوحيد، يُكتب في النموذج مباشرة، مرة واحدة؛ وتمر الإيداعات اللاحقة عبر طلبات التغيير.

قدّم طلب التغيير للمراجعة بـ POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (واجهة API وMCP). وتجيب الوسوم وعمليات الدمج وإعادة تسمية مشروع أو حذفه بـ 405 مع ما يجب فعله بدلًا من ذلك. وتحمل الأخطاء @type Error وdescription، كما يعرّفها OMG API.

الرسائل

تنطبق رموز واجهة API وMCP. وتضيف مسارات SysML v2 وأدواتها:

الرمزالحالةالمعنى
wrong-project-type409عملية LML في مشروع SysML v2، أو عملية SysML v2 في مشروع LML
syntax422في النص المقترح أخطاء صياغة؛ وتعطي التشخيصات السطر والعمود
invalid-model422يضيف التغيير تشخيصات أخطاء إلى النموذج؛ وهي مدرجة
not-printable422لا يمكن كتابة التغيير كنص SysML
invalid422تعذّر تطبيق التغيير على النموذج
no-change400النص لا يغيّر النموذج
too-large413النص أطول من 1,000,000 حرف، أو المقترح أكبر من 8 MB
too-many413 أو 409أكثر من 100 تعديل في استدعاء واحد (413)، أو المقترح يحوي 200 تغيير بالفعل (409)
stale409تغيير نصي سابق في المقترح لم يعد ينطبق على النموذج
not-found404لا يوجد مشروع أو عنصر أو فرع أو إيداع كهذا (لا تقدّم Systems Modeling API إلا رؤوس الفروع)
not-writable405الوسوم وعمليات الدمج وإعادة تسمية مشروع أو حذفه عبر Systems Modeling API؛ افعل ذلك في Holarch
main-protected405حذف main؛ احذف فرع طلب تغيير بدلًا من ذلك
stale-head409تحرك الفرع منذ previousCommit؛ اقرأ head الخاص به وأودع مجددًا
branch-base409يجب أن يبدأ الفرع الجديد من رأس main
branch-review-off409لا يستخدم المشروع مراجعة الفروع؛ يفعّلها مالك في طلبات التغيير ← الإعدادات
cr-not-draft409طلب التغيير مقدَّم أو مغلق؛ ولا يمكن الكتابة فيه إلا وهو في حالة مسودة أو مرفوض
cr-full409يحوي طلب التغيير 5,000 عنصر متغير، أو يحوي المشروع 20 MB من مسودات طلبات التغيير
plan-limit403تحتاج الكتابة في طلبات التغيير إلى خطة Team
orphan422لا مالك لعنصر جديد؛ أرسل عضويته المالكة أو owner
unknown-metaclass422@type في حمولة ليس فئة وصفية في SysML v2
idempotency-key-reused422استُخدم Idempotency-Key مع جسم آخر؛ أرسل مفتاحًا جديدًا
token-projects403لا يستطيع رمز مقيّد بقائمة مشاريع إنشاء مشروع
bad-request400قيمة مفقودة أو خاطئة، مثل root ليس حزمة ذات مستوى أعلى، أو op غير معروف، أو عنصر جديد بلا اسم

الحدود

ماذاالحد
العناصر أو المتطلبات أو الاتصالات لكل صفحة500
الأعضاء المدرجون مع عنصر200
التشخيصات لكل رد500
أسطر نص SysML لكل رد5,000، وبحد أقصى 400,000 بايت (يُقطع عند سطر)
نص doc4,000 حرف في القوائم، و20,000 لعنصر واحد
نص SysML الخاص بالعنصر16,000 حرف
النص في استدعاء propose_sysml واحد1,000,000 حرف
التعديلات في استدعاء واحد100
العناصر المدرجة كمضافة أو متغيرة أو محذوفة في تغيير واحد300 لكل منها
التغييرات في مقترح واحد200، و8 MB
صفحة Systems Modeling API1,000 عنصر (الافتراضي 100)
DataVersion في إيداع واحد5,000
العناصر المتغيرة في طلب تغيير واحد5,000
جسم الإيداع32 MB

حدود المعدل وحجم الطلب وقواعد الرموز هي تلك الواردة في واجهة API وMCP.

SysML® وOMG® علامتان تجاريتان مسجلتان لشركة Object Management Group, Inc. في الولايات المتحدة ودول أخرى.