Holarch

SysML v2

ה-API וה-MCP בפרויקטים של SysML v2

קריאה, חיפוש ובדיקה של מודלים של SysML v2 מסקריפטים ומכלי AI עם אסימון גישה אישי, הצעת שינויים שאותם סוקרים ומחילים ב-Holarch, וקריאה וביצוע commit דרך Systems Modeling API, שבו ענפים הם בקשות שינוי.

אופן השימוש ←

בדף זה
  1. סקירה כללית
  2. מושגים
  3. איך להשתמש בה
    1. קריאת פרויקט SysML v2 עם curl
    2. בדיקת טקסט SysML לפני שמציעים אותו
    3. הצעת שינוי והחלתו
    4. חיבור כלי AI לפרויקט 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. ביצוע commit לשינויים
  8. הודעות
  9. מגבלות
  10. דפים קשורים

סקירה כללית

פרויקטי 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

  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, יש לפתוח את הפרויקט ואז את ✦ AI ▾ → סקירת “Add range attribute”… (או את ההתראה שתחת הפעמון).
  2. יש לבדוק את השורות וללחוץ על החלת הנבחרים.

    השינויים המסומנים מוחלים עם השם שלך בהיסטוריה, וביטול פעולה אחד מחזיר הכול לאחור.

חיבור כלי AI לפרויקט SysML v2

  1. יש לחבר את כלי ה-AI ל-https://app.holarch.app/mcp עם אסימון או עם כניסה לחשבון (ראו API ו-MCP).
  2. אפשר לשאול על המודל, למשל “לסכם את מודל Hybrid Car ב-Holarch” או “אילו דרישות בפרויקט Hybrid Car אינן מאומתות?”.

    כלי ה-AI משתמש ב-model_summary, ב-list_elements, ב-list_requirements ובשאר כלי הקריאה.

  3. אפשר לבקש שינוי, למשל “להציע תכונה range ב-Car”.

    כלי ה-AI קורא את החבילה עם 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, ה-ports 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 מפרט את הדרישות שאף verification case אינו מאמת, עם המזהים שלהן כמו 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, ✦ 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שדות
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

יש לפתוח את הפרויקט, ואז את ✦ 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>/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הראשים וה-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; אסימונים לעולם אינם מצביעים או מחילים.

  1. יצירת ענף: POST /branches עם {"@type": "Branch", "name": "Cabin heater"}. התשובה היא הענף עם ה-holarchChangeRequest שלו.
  2. קריאת הראש של הענף ואת האלמנטים שלו.
  3. 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: הראש שעליו נעשה השינוי שלך. אם הענף התקדם מאז, התשובה היא 409 stale-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-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אין פרויקט, אלמנט, ענף או commit כזה (ה-Systems Modeling API מגיש רק ראשי ענפים)
not-writable405תגים, מיזוגים, שינוי שם או מחיקה של פרויקט דרך ה-Systems Modeling API; יש לעשות זאת ב-Holarch
main-protected405מחיקת main; יש למחוק במקום זאת ענף של בקשת שינוי
stale-head409הענף התקדם מאז previousCommit; יש לקרוא את ה-head שלו ולבצע commit שוב
branch-base409ענף חדש חייב להתחיל מהראש של main
branch-review-off409הפרויקט אינו משתמש בסקירת ענפים; בעלים מפעיל אותה בבקשות שינוי → הגדרות
cr-not-draft409בקשת השינוי הוגשה או נסגרה; אפשר לכתוב אליה רק כשהיא בטיוטה או נדחתה
cr-full409בקשת השינוי מכילה 5,000 פריטים שהשתנו, או שהפרויקט מכיל 20 MB של טיוטות בקשות שינוי
plan-limit403כתיבה לבקשות שינוי דורשת את תוכנית Team
orphan422לאלמנט חדש אין בעלים; יש לשלוח את חברות הבעלות שלו או את owner
unknown-metaclass422ה-@type של payload אינו מטא-מחלקה של 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_sysml1,000,000 תווים
עריכות בקריאה אחת100
אלמנטים שמוצגים כנוספו, שונו או הוסרו בשינוי אחד300 לכל אחד
שינויים בהצעה אחת200, ו-8 MB
עמוד של Systems Modeling API1,000 אלמנטים (ברירת מחדל 100)
DataVersions ב-commit אחד5,000
פריטים שהשתנו בבקשת שינוי אחת5,000
גוף ה-commit32 MB

מגבלות הקצב, גודל הבקשה וכללי האסימונים הם אלה של API ו-MCP.

SysML® ו-OMG® הם סימנים מסחריים רשומים של Object Management Group, Inc. בארצות הברית ובמדינות אחרות.