SysML v2
ה-API וה-MCP בפרויקטים של SysML v2
קריאה, חיפוש ובדיקה של מודלים של SysML v2 מסקריפטים ומכלי AI עם אסימון גישה אישי, הצעת שינויים שאותם סוקרים ומחילים ב-Holarch, וקריאה וביצוע commit דרך Systems Modeling API, שבו ענפים הם בקשות שינוי.
בדף זה
סקירה כללית
פרויקטי SysML v2 עובדים עם אותם REST API, נקודת קצה של MCP ואסימוני גישה אישיים כמו פרויקטי LML. סקריפטים וכלי AI קוראים את המודל כאלמנטים וכטקסט SysML, בודקים טקסט לפני שהם משנים משהו, ומציעים שינויים. דבר במודל אינו משתנה עד שאדם סוקר את ההצעה ב-Holarch ומחיל אותה.
שלוש דרכי גישה:
- REST API:
https://app.holarch.app/api/v1/projects/<project>/…לסקריפטים וללוחות מחוונים. הוא קורא אלמנטים, דרישות, אבחונים וטקסט SysML, ומוסיף שינויים להצעה. - MCP:
https://app.holarch.app/mcpלכלי AI כמו Claude. כלי SysML v2 קוראים, מחפשים ובודקים את המודל ומציעים שינויים. - Systems Modeling API:
https://app.holarch.app/api/v1/sysml/…, במבנים של OMG Systems Modeling API עבור כלי SysML v2 אחרים. הענףmainהוא המודל החי והוא לקריאה בלבד; כל ענף אחר הוא בקשת שינוי, ו-commits נכנסים אליו. המודל החי משתנה רק כשמאשר מחיל את בקשת השינוי ב-Holarch.
אסימונים, הרשאות (scopes), רשימות פרויקטים, החלפת הארגון, מגבלות קצב וחיבור Claude זהים לאלה של פרויקטי LML. ראו API ו-MCP ליצירת אסימון ולחיבור כלי AI. הקריאות של מפת התוכנית (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace, וכלי ה-MCP program_map ו-trace_chain) כוללות פרויקטי SysML v2 ואת האלמנטים שלהם.
מושגים
- אלמנט: פריט אחד של מודל SysML v2, כמו הגדרת חלק, port או דרישה. לכל אלמנט יש מזהה (UUID). בכל מקום שבו נתיב או כלי מבקש מזהה, גם שם מלא כמו
Vehicles::Car::powertrainעובד. - תקציר: הצורה המקוצרת של אלמנט ברשימות:
id,type(המטא-מחלקה, כמוPartUsage),name,shortName,qualifiedNameו-owner. - חבילה ברמה העליונה: חבילה שאינה בתוך אלמנט אחר. טקסט ה-SysML של פרויקט הוא טקסט אחד לכל חבילה ברמה העליונה, ועוד טקסט אחד לאלמנטים שמחוץ לחבילות.
- אבחון: בעיה שליבת השפה מוצאת, עם
code,severity(errorאוwarning),elementId,elementו-args. אבחוני תחביר נותניםlineו-colבמקום אלמנט. - הצעה: השינויים שלקוח API או כלי AI אוספים לסקירה. הצעה אחת פתוחה לכל אסימון ופרויקט. הלקוח שולח אותה לסקירה עם כותרת ותקציר.
- תשובות בעמודים: רשימות מגיעות בעמודים (
limit,offset). טקסט SysML ארוך מגיע בעמודים של שורות (line,lines). תשובה שהשמיטה משהו מציינתtruncated: true.
איך להשתמש בה
כדאי להשתמש ב-API כשסקריפט או כלי AI זקוקים למודל: כדי לדווח על דרישות ללא אלמנטים שמספקים או מאמתים אותן, כדי לבדוק את טקסט ה-SysML של צוות מול המודל, או כדי לאפשר לכלי AI לנסח שינויים במודל שמהנדס סוקר אחר כך.
קריאת פרויקט 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, יש לפתוח את הפרויקט ואז את ✦ AI ▾ → סקירת “Add range attribute”… (או את ההתראה שתחת הפעמון).
- יש לבדוק את השורות וללחוץ על החלת הנבחרים.
השינויים המסומנים מוחלים עם השם שלך בהיסטוריה, וביטול פעולה אחד מחזיר הכול לאחור.
חיבור כלי AI לפרויקט SysML v2
- יש לחבר את כלי ה-AI ל-
https://app.holarch.app/mcpעם אסימון או עם כניסה לחשבון (ראו API ו-MCP). - אפשר לשאול על המודל, למשל “לסכם את מודל Hybrid Car ב-Holarch” או “אילו דרישות בפרויקט Hybrid Car אינן מאומתות?”.
כלי ה-AI משתמש ב-
model_summary, ב-list_elements, ב-list_requirementsובשאר כלי הקריאה. - אפשר לבקש שינוי, למשל “להציע תכונה
rangeב-Car”.כלי ה-AI קורא את החבילה עם
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, ה-portsfuelIn,outputו-ecu) והשימושים שהיא הטיפוס שלהם.GET /api/v1/projects/<project>/elements/Vehicles::Car/connectionsמפרט את הממשקdriveShaftמ-powertrain.outputאלfrontAxle.input.GET /api/v1/projects/<project>/requirements?status=unverifiedמפרט את הדרישות שאף verification case אינו מאמת, עם המזהים שלהן כמו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, ✦ AI ▾ → סקירת “…” מציג את שונה: עם הגדרת החלק והשדה
doc, ואת השוואת הטקסט שלVehicles. החלת הנבחרים מחיל אותו.
טיפים
- יש לקרוא חבילה עם
get_sysml(אוGET …/sysml?root=) לפני שמציעים עבורה טקסט חדש. אלמנטים שהושמטו מהטקסט המוצע מוסרים. - לשינויים קטנים עדיף להשתמש בעריכות אלמנטים. הן משנות רק את האלמנטים שצוינו ומשאירות את שאר טקסט החבילה כפי שהוא.
- יש לבדוק טקסט קודם עם
check_sysml(אוPOST …/sysml/check). הוא מחזיר את אותם אבחונים שבגללם הצעה הייתה נדחית. - בסקריפטים כדאי לציין אלמנטים לפי שם מלא. מזהים נשארים זהים כשאלמנט משנה שם; שמות מלאים אינם נשארים.
- כדאי לתת לכלי AI אסימון לקריאה בלבד כשהוא רק עונה על שאלות על המודל.
נתיבי 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 | חיבורים, ממשקים, קשירות, זרימות (עם הפריט), successions, מעברים, הקצאות ותלויות באלמנט או בתכונות שלו, ואלה שבבעלותו; 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. כלי AI מוצא פרויקטי 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 | קריאה | החיבורים, הממשקים, הקשירות, הזרימות, ה-successions, המעברים, ההקצאות והתלויות של אלמנט (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 מציגים את הסטטוס שלה. אסימון לקריאה בלבד מציג רק את כלי הקריאה.
שגיאות כלים חוזרות כתוצאת כלי עם ההודעה והאבחונים, כך שכלי ה-AI יכול לתקן את הטקסט שלו ולנסות שוב.
עריכות אלמנטים
כל עריכה ב-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
יש לפתוח את הפרויקט, ואז את ✦ AI ▾ → סקירת “<title>”…. כל שינוי הוא שורה עם תיבת סימון:
- נוסף, שונה ו-הוסר מפרטים את האלמנטים, עם השדות שהשתנו (20 הראשונים מכל אחד; “ועוד n” לשאר).
- השוואת טקסט, עם תווית החבילה, מציגה את טקסט ה-SysML לפני ואחרי.
- שינוי שמסיר אלמנטים מסומן ומתחיל ללא סימון.
- יש לפתוח את מודל SysML v2 כדי להחיל את השינוי הזה. המודל אינו טעון; יש לפתוח דף SysML v2 של הפרויקט.
- החבילה כבר לא במודל; דולג. החבילה הוסרה אחרי שהשינוי הוצע.
החלת הנבחרים מסנכרן כל שינוי טקסט שוב מול המודל הנוכחי ושומר עריכות שהאלמנטים שלהן עדיין קיימים. הוא בודק את כל הקבוצה ומחיל אותה כצעד ביטול אחד. שינויים שכבר אינם מתאימים מדולגים ומצוינים בהודעה קופצת. דחייה ומאוחר יותר פועלים כמו בהצעות LML, וכך גם תפקידים, תפוגה (7 ימים) ושמירה (ראו הצעות מלקוחות AI).
Systems Modeling API
כלי SysML v2 אחרים קוראים ומשנים מודלים של Holarch דרך נתיבים במבנים של OMG Systems Modeling API (REST/HTTP). כתובת הבסיס היא https://app.holarch.app/api/v1/sysml. הוא משתמש באותם אסימונים; כל תפקיד בפרויקט יכול לקרוא, ועורכים ובעלים יכולים לבצע commit.
- פרויקטים: רק פרויקטי SysML v2 מוצגים. ה-
@idשל פרויקט הוא UUID שה-API הזה נותן לו; גם מזהה הפרויקט של Holarch עובד. התשובה כוללתholarchIdו-url. - ענפים:
mainהוא המודל החי ואי אפשר לשנות אותו דרך ה-API. כל ענף אחר הוא בקשת שינוי בתהליך, בשם "CR-12 Title" ונושאholarchChangeRequest(id,label,status,url). בקשות שינוי שיושמו או נמשכו ב-30 הימים האחרונים עדיין מוצגות, עםdeletedמוגדר. - Commits: commit כותב שינויים לענף של בקשת שינוי. רק ראשי ענפים מוגשים: הראש של
mainהוא המודל החי, הראש של ענף בקשת שינוי הוא המודל החי עם השינויים של הבקשה. מזהי commit ישנים יותר עונים404; את הראש הנוכחי יש לקבל מהענף. - אלמנטים: לכל אלמנט יש כל מאפיין של המטא-מחלקה שלו בסכמת ה-JSON של OMG, כולל מאפיינים נגזרים (
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 | הראשים וה-commits שנשלחו לענפים, החדשים ביותר קודם |
POST /sysml/projects/<projectId>/commits?branchId=<branchId> | ביצוע commit לשינויים בענף (בהמשך) |
GET /sysml/projects/<projectId>/commits/<commitId> | commit ראש |
GET /sysml/projects/<projectId>/commits/<commitId>/changes | מה שהענף משנה מול המודל החי: DataVersion אחד לכל אלמנט |
GET /sysml/projects/<projectId>/commits/<commitId>/elements | כל האלמנטים של ה-commit, בעמודים |
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"
ביצוע commit לשינויים
כתיבה דורשת אסימון עם גישת קריאה וכתיבה, את תפקיד העורך או הבעלים, את תוכנית Team (גם לחשבונות אקדמיים ולחשבונות כיתה), וסקירת ענפים מופעלת בפרויקט (בקשות שינוי → הגדרות). מאשר סוקר ומחיל את בקשת השינוי ב-Holarch; אסימונים לעולם אינם מצביעים או מחילים.
- יצירת ענף: POST
/branchesעם{"@type": "Branch", "name": "Cabin heater"}. התשובה היא הענף עם ה-holarchChangeRequestשלו. - קריאת הראש של הענף ואת האלמנטים שלו.
- POST
/commits?branchId=<branch @id>עם רשימה שלDataVersions:
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 חדש ואת חברות הבעלות שלו (שנשלחת באותו commit) או
owner, שיוצר את החברות עבורך. - הסרת אלמנט:
payload: nullמסיר אותו עם כל מה שבבעלותו. - בדיקות: כל חבילה שה-commit נוגע בה חייבת להיות מודפסת ומנותחת שוב, וה-commit אינו רשאי להוסיף אבחוני שגיאה; אחרת מתקבל
422עם ה-diagnosticsלתיקון. - previousCommit: הראש שעליו נעשה השינוי שלך. אם הענף התקדם מאז, התשובה היא
409stale-headעם ה-headהנוכחי; יש לקרוא שוב ולבצע commit מעליו. - ניסיונות חוזרים: יש לשלוח כותרת
Idempotency-Key. ניסיון חוזר עם אותו מפתח ואותו גוף בתוך 24 שעות מקבל שוב את התשובה הראשונה. - Commits ל-
main: commit ללאbranchId, או עםmain, נכנס לבקשת השינוי בטיוטה של האסימון שלך ("API changes from <token name>"), שנוצרת ב-commit הראשון מסוג זה. התשובה מציינת איזו ב-holarchChangeRequestובכותרתWarning. - פרויקטים חדשים: בפרויקט שנוצר עם POST
/sysml/projectsסקירת הענפים מופעלת. ה-commit הראשון שלו ל-main, כל עוד אין בו חברים מלבדך, נכתב ישירות למודל, פעם אחת; commits מאוחרים יותר עוברים דרך בקשות שינוי.
יש להגיש את בקשת השינוי לסקירה עם POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API ו-MCP). תגים, מיזוגים ושינוי שם או מחיקה של פרויקט עונים 405 עם מה שיש לעשות במקום. שגיאות נושאות @type Error ו-description, כפי שה-API של OMG מגדיר אותן.
הודעות
הקודים של 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 | אין פרויקט, אלמנט, ענף או commit כזה (ה-Systems Modeling API מגיש רק ראשי ענפים) |
not-writable | 405 | תגים, מיזוגים, שינוי שם או מחיקה של פרויקט דרך ה-Systems Modeling API; יש לעשות זאת ב-Holarch |
main-protected | 405 | מחיקת main; יש למחוק במקום זאת ענף של בקשת שינוי |
stale-head | 409 | הענף התקדם מאז previousCommit; יש לקרוא את ה-head שלו ולבצע commit שוב |
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 של payload אינו מטא-מחלקה של 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) |
| DataVersions ב-commit אחד | 5,000 |
| פריטים שהשתנו בבקשת שינוי אחת | 5,000 |
| גוף ה-commit | 32 MB |
מגבלות הקצב, גודל הבקשה וכללי האסימונים הם אלה של API ו-MCP.
דפים קשורים
- API ו-MCP
- תחילת העבודה עם פרויקטים של SysML v2
- עורך הטקסט והדפדפן
- החלפת מודלים של SysML v2
- דרישות ואימות בפרויקטים של SysML v2
SysML® ו-OMG® הם סימנים מסחריים רשומים של Object Management Group, Inc. בארצות הברית ובמדינות אחרות.