SysML v2
واجهة API وMCP في مشاريع SysML v2
اقرأ نماذج SysML v2 وابحث فيها وافحصها من البرامج النصية وأدوات الذكاء الاصطناعي باستخدام رمز وصول شخصي، واقترح تغييرات تراجعها وتطبقها في Holarch، واقرأ والتزم عبر Systems Modeling API، حيث الفروع طلبات تغيير.
في هذه الصفحة
نظرة عامة
تعمل مشاريع 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
- أنشئ رمزًا تحت إعدادات الحساب ← رموز API (انظر واجهة API وMCP).
- اعرض مشاريعك:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
لمشاريع SysML v2 القيمة "language": "sysml2".
- احصل على ملخص النموذج:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model
ترى أعداد العناصر لكل فئة وصفية، والحزم ذات المستوى الأعلى، وعدد الأخطاء والتحذيرات.
- ابحث عن العناصر، مثل كل تعريف جزء:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
- اقرأ نص SysML لحزمة:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"
ينتهي النص الطويل بـ "truncated": true و"next": السطر الذي تطلبه بعد ذلك باستخدام line.
فحص نص SysML قبل اقتراحه
- أرسل النص الجديد لحزمة إلى مسار الفحص:
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
- اقرأ الرد. تكون
okهيtrueحين لا يكون في النص أخطاء صياغة. وتدرجdiagnosticsأخطاء الصياغة معlineوcol، والأخطاء التي سيضيفها النص إلى النموذج. وchangesهو عدد تغييرات النموذج التي يجريها النص.
لا يغيّر الفحص شيئًا. ولا يحتاج إلا إلى رمز قراءة.
اقتراح تغيير وتطبيقه
يضيف رمز الكتابة التغييرات إلى المقترح المفتوح للرمز. ثم يرسل العميل المقترح للمراجعة.
- أضف تغييرًا. أرسل إما النص الجديد الكامل لحزمة، أو تعديلات عناصر:
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).
- أضف مزيدًا من التغييرات بالطريقة نفسها. ويُفحص كل تغيير مقابل النموذج بعد تطبيق التغييرات السابقة في المقترح.
- أرسل المقترح للمراجعة:
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
- في Holarch، افتح المشروع، ثم افتح ✦ الذكاء الاصطناعي ▾ ← مراجعة “Add range attribute”… (أو الإشعار تحت الجرس).
- افحص الصفوف وانقر تطبيق المحدد.
تُطبَّق التغييرات المحددة مع اسمك في السجل، ويُلغي تراجع واحد ذلك كله.
ربط أداة ذكاء اصطناعي بمشروع SysML v2
- اربط أداة الذكاء الاصطناعي بـ
https://app.holarch.app/mcpبرمز أو بتسجيل الدخول (انظر واجهة API وMCP). - اسأل عن النموذج، مثل “لخّص نموذج Hybrid Car في Holarch” أو “ما المتطلبات غير المتحقَّق منها في مشروع Hybrid Car؟”.
تستخدم أداة الذكاء الاصطناعي
model_summaryوlist_elementsوlist_requirementsوأدوات القراءة الأخرى. - اطلب تغييرًا، مثل “اقترح سمة
rangeعلىCar”.تقرأ أداة الذكاء الاصطناعي الحزمة بـ
get_sysml، وتقترح نصًا أو تعديلات عناصر، وتصلح أي تشخيصات يعيدها الفحص. - راجع المقترح في Holarch وانقر تطبيق المحدد.
مثال تطبيقي: المشروع التوضيحي Hybrid Car
أنشئ المشروع التوضيحي بـ إدارة المشاريع ← ملفات المشروع ▾ ← مشروع توضيحي جديد ← Hybrid Car (SysML v2)، ثم أنشئ له رمزًا للقراءة والكتابة.
- يدرج
GET /api/v1/projects/<project>/modelالحزم ذات المستوى الأعلى، ومنهاVehiclesوHybridCarArchitectureوVehicleBehavior. - يجد
GET /api/v1/projects/<project>/elements?query=Engine&type=part%20defالعنصرVehicles::Engine. - يعيد
GET /api/v1/projects/<project>/elements/Vehicles::Engineتعريف الجزء مع نص SysML الخاص به، وأعضائه (displacementوcylindersوmaxPowerوالمنافذfuelInوoutputوecu) والاستخدامات المنمَّطة به. - يدرج
GET /api/v1/projects/<project>/elements/Vehicles::Car/connectionsالواجهةdriveShaftمنpowertrain.outputإلىfrontAxle.input. - يدرج
GET /api/v1/projects/<project>/requirements?status=unverifiedالمتطلبات التي لا تتحقق منها أي حالة تحقق، مع معرّفاتها مثلVR-4.1. - يضيف
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مع عنوان. - في 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 | الحقول |
|---|---|
create | kind (كلمة مفتاحية مثل part وpart def وattribute وport وrequirement وaction وpackage) أو type (فئة وصفية)؛ وowner (إن حُذف: المستوى الأعلى)؛ وname (مطلوب)؛ واختياريًا shortName وtypedBy وspecializes وsubsets وredefines وmultiplicity وvalue وdoc وdirection (in، out، inout) |
update | id والحقول المراد تغييرها، كما في الإنشاء؛ وnull أو "" يمسح الحقل |
move | id وowner الجديد |
remove | id؛ يزيل العنصر مع أعضائه |
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>/branches | main وفروع طلبات التغيير |
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؛ ولا تصوّت الرموز ولا تطبّق أبدًا.
- إنشاء فرع: POST
/branchesمع{"@type": "Branch", "name": "Cabin heater"}. والإجابة هي الفرع معholarchChangeRequestالخاص به. - اقرأ رأس الفرع وعناصره.
- 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: الرأس الذي أُجري عليه تغييرك. فإن تحرك الفرع منذئذ، تكون الإجابة
409stale-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-type | 409 | عملية LML في مشروع SysML v2، أو عملية SysML v2 في مشروع LML |
syntax | 422 | في النص المقترح أخطاء صياغة؛ وتعطي التشخيصات السطر والعمود |
invalid-model | 422 | يضيف التغيير تشخيصات أخطاء إلى النموذج؛ وهي مدرجة |
not-printable | 422 | لا يمكن كتابة التغيير كنص SysML |
invalid | 422 | تعذّر تطبيق التغيير على النموذج |
no-change | 400 | النص لا يغيّر النموذج |
too-large | 413 | النص أطول من 1,000,000 حرف، أو المقترح أكبر من 8 MB |
too-many | 413 أو 409 | أكثر من 100 تعديل في استدعاء واحد (413)، أو المقترح يحوي 200 تغيير بالفعل (409) |
stale | 409 | تغيير نصي سابق في المقترح لم يعد ينطبق على النموذج |
not-found | 404 | لا يوجد مشروع أو عنصر أو فرع أو إيداع كهذا (لا تقدّم Systems Modeling API إلا رؤوس الفروع) |
not-writable | 405 | الوسوم وعمليات الدمج وإعادة تسمية مشروع أو حذفه عبر Systems Modeling API؛ افعل ذلك في Holarch |
main-protected | 405 | حذف main؛ احذف فرع طلب تغيير بدلًا من ذلك |
stale-head | 409 | تحرك الفرع منذ previousCommit؛ اقرأ head الخاص به وأودع مجددًا |
branch-base | 409 | يجب أن يبدأ الفرع الجديد من رأس main |
branch-review-off | 409 | لا يستخدم المشروع مراجعة الفروع؛ يفعّلها مالك في طلبات التغيير ← الإعدادات |
cr-not-draft | 409 | طلب التغيير مقدَّم أو مغلق؛ ولا يمكن الكتابة فيه إلا وهو في حالة مسودة أو مرفوض |
cr-full | 409 | يحوي طلب التغيير 5,000 عنصر متغير، أو يحوي المشروع 20 MB من مسودات طلبات التغيير |
plan-limit | 403 | تحتاج الكتابة في طلبات التغيير إلى خطة Team |
orphan | 422 | لا مالك لعنصر جديد؛ أرسل عضويته المالكة أو owner |
unknown-metaclass | 422 | @type في حمولة ليس فئة وصفية في SysML v2 |
idempotency-key-reused | 422 | استُخدم Idempotency-Key مع جسم آخر؛ أرسل مفتاحًا جديدًا |
token-projects | 403 | لا يستطيع رمز مقيّد بقائمة مشاريع إنشاء مشروع |
bad-request | 400 | قيمة مفقودة أو خاطئة، مثل root ليس حزمة ذات مستوى أعلى، أو op غير معروف، أو عنصر جديد بلا اسم |
الحدود
| ماذا | الحد |
|---|---|
| العناصر أو المتطلبات أو الاتصالات لكل صفحة | 500 |
| الأعضاء المدرجون مع عنصر | 200 |
| التشخيصات لكل رد | 500 |
| أسطر نص SysML لكل رد | 5,000، وبحد أقصى 400,000 بايت (يُقطع عند سطر) |
| نص doc | 4,000 حرف في القوائم، و20,000 لعنصر واحد |
| نص SysML الخاص بالعنصر | 16,000 حرف |
النص في استدعاء propose_sysml واحد | 1,000,000 حرف |
| التعديلات في استدعاء واحد | 100 |
| العناصر المدرجة كمضافة أو متغيرة أو محذوفة في تغيير واحد | 300 لكل منها |
| التغييرات في مقترح واحد | 200، و8 MB |
| صفحة Systems Modeling API | 1,000 عنصر (الافتراضي 100) |
| DataVersion في إيداع واحد | 5,000 |
| العناصر المتغيرة في طلب تغيير واحد | 5,000 |
| جسم الإيداع | 32 MB |
حدود المعدل وحجم الطلب وقواعد الرموز هي تلك الواردة في واجهة API وMCP.
صفحات ذات صلة
- API وMCP
- البدء بمشاريع SysML v2
- محرر النص والمستعرض
- تبادل نماذج SysML v2
- المتطلبات والتحقق في مشاريع SysML v2
SysML® وOMG® علامتان تجاريتان مسجلتان لشركة Object Management Group, Inc. في الولايات المتحدة ودول أخرى.