SysML v2
API i MCP w projektach SysML v2
Odczytuj, przeszukuj i sprawdzaj modele SysML v2 ze skryptów i narzędzi AI za pomocą osobistego tokenu dostępu, proponuj zmiany, które przegląda się i stosuje w Holarch, oraz odczytuj i zatwierdzaj zmiany przez Systems Modeling API, w którym gałęzie są wnioskami o zmianę.
Na tej stronie
Przegląd
Projekty SysML v2 działają z tym samym API REST, punktem końcowym MCP i osobistymi tokenami dostępu co projekty LML. Skrypty i narzędzia AI odczytują model jako elementy i tekst SysML, sprawdzają tekst, zanim cokolwiek zmienią, i proponują zmiany. Nic w modelu się nie zmienia, dopóki człowiek nie przejrzy propozycji w Holarch i jej nie zastosuje.
Trzy sposoby dostępu:
- API REST:
https://app.holarch.app/api/v1/projects/<project>/…dla skryptów i pulpitów. Odczytuje elementy, wymagania, diagnostyki i tekst SysML oraz dodaje zmiany do propozycji. - MCP:
https://app.holarch.app/mcpdla narzędzi AI takich jak Claude. Narzędzia SysML v2 odczytują, przeszukują i sprawdzają model oraz proponują zmiany. - Systems Modeling API:
https://app.holarch.app/api/v1/sysml/…, w kształtach OMG Systems Modeling API dla innych narzędzi SysML v2. Gałąźmainto model bieżący, tylko do odczytu; każda inna gałąź jest wnioskiem o zmianę, a commity trafiają do niej. Model bieżący zmienia się tylko wtedy, gdy zatwierdzający zastosuje wniosek o zmianę w Holarch.
Tokeny, zakresy, listy projektów, przełącznik organizacji, limity żądań i łączenie Claude działają tak samo jak w projektach LML. Tworzenie tokenu i łączenie narzędzia AI opisuje strona API i MCP. Wywołania Mapy programu (GET /api/v1/program-map, GET /api/v1/projects/<project>/items/<item>/trace oraz narzędzia MCP program_map i trace_chain) obejmują projekty SysML v2 i ich elementy.
Pojęcia
- Element: jedna pozycja modelu SysML v2, np. definicja części, port lub wymaganie. Każdy element ma id (UUID). Wszędzie tam, gdzie trasa lub narzędzie wymaga identyfikatora, działa również nazwa kwalifikowana, np.
Vehicles::Car::powertrain. - Skrót: krótka postać elementu na listach:
id,type(metaklasa, np.PartUsage),name,shortName,qualifiedNameiowner. - Pakiet najwyższego poziomu: pakiet, który nie znajduje się wewnątrz innego elementu. Tekst SysML projektu to jeden tekst na każdy pakiet najwyższego poziomu oraz jeden tekst dla elementów spoza pakietów.
- Diagnostyka: problem znaleziony przez rdzeń języka, z polami
code,severity(errorlubwarning),elementId,elementiargs. Diagnostyki składni podająlineicolzamiast elementu. - Propozycja: zmiany, które klient API lub narzędzie AI zbiera do przeglądu. Na token i projekt otwarta jest jedna propozycja. Klient wysyła ją do przeglądu z tytułem i podsumowaniem.
- Odpowiedzi stronicowane: listy przychodzą stronami (
limit,offset). Długi tekst SysML przychodzi stronami wierszy (line,lines). Odpowiedź, która coś pominęła, zawieratruncated: true.
Jak z niego korzystać
Używaj API, gdy skrypt lub narzędzie AI potrzebuje modelu: aby raportować wymagania bez elementów spełniających lub weryfikujących, aby sprawdzać tekst SysML zespołu względem modelu albo aby pozwolić narzędziu AI przygotować zmiany modelu, które następnie przegląda inżynier.
Odczyt projektu SysML v2 za pomocą curl
- Utwórz token w Ustawienia konta → Tokeny API (zobacz API i MCP).
- Wyświetl listę swoich projektów:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
Projekty SysML v2 mają "language": "sysml2".
- Pobierz podsumowanie modelu:
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model
Zobaczysz liczby elementów na metaklasę, pakiety najwyższego poziomu oraz liczbę błędów i ostrzeżeń.
- Znajdź elementy, na przykład każdą definicję części:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"
- Odczytaj tekst SysML pakietu:
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"
Długi tekst kończy się na "truncated": true i "next": wierszem, o który należy poprosić następnie za pomocą line.
Sprawdzenie tekstu SysML przed zaproponowaniem
- Wyślij nowy tekst pakietu na trasę sprawdzania:
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
- Przeczytaj odpowiedź.
okma wartośćtrue, gdy tekst nie ma błędów składni.diagnosticswymienia błędy składni zlineicoloraz błędy, które tekst dodałby do modelu.changesto liczba zmian modelu, które wprowadza tekst.
Sprawdzenie niczego nie zmienia. Wymaga tylko tokenu do odczytu.
Zaproponowanie zmiany i jej zastosowanie
Token do zapisu dodaje zmiany do otwartej propozycji tokenu. Klient wysyła następnie propozycję do przeglądu.
- Dodaj zmianę. Wyślij albo pełny nowy tekst pakietu, albo edycje elementów:
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
Otrzymasz 201 z propozycją, podsumowaniem zmiany oraz elementami, które dodaje, zmienia i usuwa. Zmiana, która dodaje diagnostyki błędów, jest odrzucana (zobacz Propozycje w projektach SysML v2).
- Dodawaj kolejne zmiany w ten sam sposób. Każda zmiana jest sprawdzana względem modelu z zastosowanymi wcześniejszymi zmianami propozycji.
- Wyślij propozycję do przeglądu:
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
- W Holarch otwórz projekt, a następnie otwórz ✦ AI ▾ → Przejrzyj „Add range attribute”… (lub powiadomienie pod dzwonkiem).
- Sprawdź wiersze i kliknij Zastosuj zaznaczone.
Zaznaczone zmiany są stosowane z Twoim nazwiskiem w historii, a jedno polecenie Cofnij wycofuje całość.
Połączenie narzędzia AI z projektem SysML v2
- Połącz narzędzie AI z
https://app.holarch.app/mcpza pomocą tokenu lub logowania (zobacz API i MCP). - Zapytaj o model, na przykład “Podsumuj model Hybrid Car w Holarch” lub “Które wymagania w projekcie Hybrid Car nie są zweryfikowane?”.
Narzędzie AI używa
model_summary,list_elements,list_requirementsi innych narzędzi do odczytu. - Poproś o zmianę, na przykład “Zaproponuj atrybut
rangewCar”.Narzędzie AI odczytuje pakiet za pomocą
get_sysml, proponuje tekst lub edycje elementów i poprawia diagnostyki zwrócone przez sprawdzenie. - Przejrzyj propozycję w Holarch i kliknij Zastosuj zaznaczone.
Przykład: projekt demonstracyjny Hybrid Car
Utwórz demo przez Zarządzaj projektami → Pliki projektów ▾ → Nowy projekt demonstracyjny → Hybrid Car (SysML v2), a następnie utwórz dla niego token do odczytu i zapisu.
GET /api/v1/projects/<project>/modelwymienia pakiety najwyższego poziomu, wśród nichVehicles,HybridCarArchitectureiVehicleBehavior.GET /api/v1/projects/<project>/elements?query=Engine&type=part%20defznajdujeVehicles::Engine.GET /api/v1/projects/<project>/elements/Vehicles::Enginezwraca definicję części z jej tekstem SysML, składowymi (displacement,cylinders,maxPower, portyfuelIn,outputiecu) oraz typowanymi przez nią użyciami.GET /api/v1/projects/<project>/elements/Vehicles::Car/connectionswymienia interfejsdriveShaftzpowertrain.outputdofrontAxle.input.GET /api/v1/projects/<project>/requirements?status=unverifiedwymienia wymagania, których nie weryfikuje żaden przypadek weryfikacji, z identyfikatorami takimi jakVR-4.1.POST /api/v1/projects/<project>/proposal/changesz{"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]}dodaje zmianę do propozycji.POST /api/v1/projects/<project>/proposalz tytułem ją wysyła.- W Holarch ✦ AI ▾ → Przejrzyj „…” pokazuje Zmieniono: z definicją części i polem
docoraz różnice tekstuVehicles. Zastosuj zaznaczone ją stosuje.
Wskazówki
- Odczytaj pakiet za pomocą
get_sysml(lubGET …/sysml?root=), zanim zaproponujesz dla niego nowy tekst. Elementy pominięte w proponowanym tekście są usuwane. - Przy małych zmianach preferuj edycje elementów. Zmieniają one tylko wskazane elementy, a resztę tekstu pakietu pozostawiają bez zmian.
- Najpierw sprawdź tekst za pomocą
check_sysml(lubPOST …/sysml/check). Zwraca te same diagnostyki, z którymi propozycja zostałaby odrzucona. - W skryptach wskazuj elementy przez nazwę kwalifikowaną. Identyfikatory nie zmieniają się przy zmianie nazwy elementu; nazwy kwalifikowane tak.
- Daj narzędziu AI token tylko do odczytu, gdy jedynie odpowiada na pytania o model.
Trasy REST dla projektów SysML v2
Adres bazowy: https://app.holarch.app/api/v1. Odpowiedzi są w JSON. /api/v1/openapi.json (OpenAPI 3.1) opisuje te trasy wraz z pozostałymi.
| Metoda i ścieżka | Co robi |
|---|---|
GET /projects/<project>/model | Liczby elementów na metaklasę, pakiety najwyższego poziomu z liczbami elementów oraz liczba błędów i ostrzeżeń |
GET /projects/<project>/elements | Wyszukiwanie: query (lub q; tekst w nazwie, nazwie skróconej, nazwie kwalifikowanej lub doc), type, owner, limit (1–500, domyślnie 50), offset; sortowane według nazwy kwalifikowanej |
GET /projects/<project>/elements/<id> | Jeden element z polami, doc, tekstem SysML, składowymi i typowanymi przez niego użyciami; members (0–200, domyślnie 100) |
GET /projects/<project>/elements/<id>/connections | Połączenia, interfejsy, wiązania, przepływy (z elementem przepływu), następstwa, przejścia, alokacje i zależności przy elemencie lub jego cechach oraz te, które posiada wewnątrz; limit (domyślnie 100) |
GET /projects/<project>/requirements | Wymagania z identyfikatorem, treścią (doc), satisfiedBy i verifiedBy; owner, status (unsatisfied lub unverified), limit (domyślnie 100), offset |
GET /projects/<project>/diagnostics | Diagnostyki modelu, najpierw błędy; ids (rozdzielone przecinkami: tylko te elementy i ich składowe), limit (domyślnie 200, najwyżej 500) |
GET /projects/<project>/sysml | Tekst SysML pakietu najwyższego poziomu (root), elementów spoza pakietów (bez root) lub jednego elementu (element); line (pierwszy wiersz, od 1), lines (domyślnie 2000, najwyżej 5000) |
POST /projects/<project>/sysml/check | Sprawdza text jako nowy tekst root (lub elementów spoza pakietów); niczego nie zmienia |
POST /projects/<project>/proposal/changes | Dodaje zmianę do otwartej propozycji: {text, root} lub {edits} |
GET /projects/<project>/proposal | Otwarta propozycja lub propozycja o identyfikatorze proposal, z jej statusem i zmianami |
POST /projects/<project>/proposal | Wysyła otwartą propozycję do przeglądu: title, summary |
DELETE /projects/<project>/proposal | Odrzuca otwartą propozycję przed wysłaniem |
GET /projects i GET /projects/<project> działają również dla projektów SysML v2. Zwracają "language": "sysml2", a odpowiedź dla projektu dodaje elements i types (liczby elementów na metaklasę).
Trasy encji LML (/entities, /relationships, /schema, kontrole modelu i kontrola jakości) zwracają w projekcie SysML v2 409 wrong-project-type. Trasy SysML v2 zwracają to samo w projekcie LML.
Wartości
- type: metaklasa, np.
PartUsagelubRequirementDefinition, albo słowo kluczowe zapisane jak w tekście SysML:part,part def,attribute,port,requirement,action,packagei inne słowa kluczowe elementów. - owner, id, element, root: identyfikator lub nazwa kwalifikowana.
rootprzyjmuje też nazwę pakietu najwyższego poziomu.rootmusi być pakietem najwyższego poziomu; aby odczytać tekst jednego elementu, użyjelement. - Długie wartości: doc na liście jest obcinany do 4000 znaków, doc pojedynczego elementu do 20 000, a własny tekst SysML elementu do 16 000 znaków.
Narzędzia MCP dla projektów SysML v2
Punkt końcowy MCP wymienia te narzędzia obok narzędzi LML. Narzędzie AI znajduje projekty SysML v2 za pomocą list_projects (language: sysml2). Każde narzędzie przyjmuje project.
Narzędzia do odczytu przyjmują też opcjonalny change_request (CR-12 lub jego identyfikator), aby odczytać model w postaci, jaką nadałby mu ten wniosek o zmianę; propose_sysml i propose_element_changes przyjmują go, aby wyliczyć zmianę względem modelu wniosku i po przeglądzie zastosować ją w tej wersji roboczej. Zasady opisuje sekcja Wnioski o zmianę.
| Narzędzie | Dostęp | Co robi |
|---|---|---|
model_summary | Odczyt | Liczby elementów na metaklasę, pakiety najwyższego poziomu i liczba diagnostyk |
list_elements | Odczyt | Znajduje elementy według tekstu (query), type i owner; stronicowane przez limit i offset |
get_element | Odczyt | Jeden element (id) z typami, specjalizacjami, licznością, wartością, końcami, doc, tekstem SysML, składowymi (members, najwyżej 200) i typowanymi przez niego użyciami |
get_connections | Odczyt | Połączenia, interfejsy, wiązania, przepływy, następstwa, przejścia, alokacje i zależności elementu (id, limit) |
list_requirements | Odczyt | Wymagania z identyfikatorem, treścią, satisfy i verify; owner, status (unsatisfied, unverified), limit, offset |
get_sysml | Odczyt | Tekst SysML pakietu najwyższego poziomu (root), elementów spoza pakietów lub jednego elementu (element); line, lines (najwyżej 5000); odpowiedź podaje next |
get_sysml_text | Odczyt | Tekst SysML całego modelu (każdy pakiet najwyższego poziomu, a potem elementy spoza pakietów) lub jednego pakietu (package), do 200 000 znaków na odpowiedź; odpowiedź wymienia pominięte pakiety |
check_sysml | Odczyt | Bez text: diagnostyki modelu (ids, limit). Z text (i root): błędy składni z wierszem i kolumną oraz błędy, które tekst by dodał. Niczego nie zmienia |
propose_sysml | Odczyt i zapis | Proponuje pełny nowy tekst (text) pakietu najwyższego poziomu (root) lub elementów spoza pakietów (bez root; także tam, gdzie trafia nowy pakiet) |
propose_element_changes | Odczyt i zapis | Proponuje edycje (edits, najwyżej 100) bez przepisywania tekstu: tworzenie, aktualizację, przeniesienie lub usunięcie |
list_diagrams, get_diagram i get_matrix działają także w projektach SysML v2: list_diagrams wymienia widoki (z ich rodzajem, np. InterconnectionView) i diagramy analizy przechowywane pod elementem; get_diagram podaje elementy, które widok udostępnia po zastosowaniu filtrów (według identyfikatora elementu lub nazwy kwalifikowanej); get_matrix podaje każde wymaganie z tym, co je spełnia i weryfikuje.
Narzędzia propozycji z projektów LML działają tu tak samo: propose_changes wysyła propozycję z tytułem i podsumowaniem, discard_proposal ją odrzuca, a get_proposal i list_proposals pokazują jej status. Token tylko do odczytu wymienia tylko narzędzia do odczytu.
Błędy narzędzi wracają jako wynik narzędzia z komunikatem i diagnostykami, aby narzędzie AI mogło poprawić tekst i spróbować ponownie.
Edycje elementów
Każda edycja w edits (MCP) lub {"edits": […]} (REST) jest obiektem z op:
| op | Pola |
|---|---|
create | kind (słowo kluczowe, np. part, part def, attribute, port, requirement, action, package) lub type (metaklasa); owner (pominięty: najwyższy poziom); name (wymagane); opcjonalnie shortName, typedBy, specializes, subsets, redefines, multiplicity, value, doc, direction (in, out, inout) |
update | id i pola do zmiany, jak przy tworzeniu; null lub "" czyści pole |
move | id i nowy owner |
remove | id; usuwa element wraz z jego składowymi |
typedBy,specializes,subsetsiredefinesto listy do 20 nazw: identyfikatorów, nazw kwalifikowanych lub nazw zapisanych jak w tekście (działają nazwy z biblioteki, np.MassValue).- Późniejsze edycje mogą wskazywać elementy utworzone wcześniej w tym samym wywołaniu jako
new:1,new:2… w kolejności tworzenia, na przykład jakoowner. Odpowiedź wymienia je wcreatedz nowymi identyfikatorami. - Zmiana nazwy elementu aktualizuje też odwołania, które wskazywały go starą nazwą.
Proponowany tekst
propose_sysmlzastępuje cały tekst pakietu. Elementy zachowują identyfikatory tam, gdzie tekst nadal je deklaruje. Elementy pominięte w tekście są usuwane.- Tekst musi dać się przeanalizować bez niczego niezastosowanego. Tekst, który nie zmienia modelu, jest odrzucany (
no-change).
Propozycje w projektach SysML v2
Każda proponowana zmiana jest sprawdzana przez rdzeń języka, zanim trafi do propozycji:
- Tekst daje się przeanalizować bez błędów składni, a edycje elementów dają się zastosować.
- Zmienione pakiety nadal dają się wydrukować jako tekst SysML i ponownie przeanalizować.
- Zmiana nie dodaje do modelu diagnostyk błędów, takich jak nierozwiązane nazwy lub błędy typów. Błędy, które model już miał, się nie liczą.
Zmiana, która nie przejdzie sprawdzenia, jest odrzucana z diagnostykami (do 50) do poprawienia. Nic nie jest zapisywane. Ostrzeżenia nie powodują odrzucenia zmiany.
Proponowanie wymaga tokenu do odczytu i zapisu oraz roli edytora lub właściciela w projekcie. Jedna propozycja zawiera najwyżej 200 zmian i 8 MB.
Przegląd propozycji SysML v2
Otwórz projekt, a następnie ✦ AI ▾ → Przejrzyj „<title>”…. Każda zmiana jest wierszem z polem wyboru:
- Dodano, Zmieniono i Usunięto wymieniają elementy ze zmienionymi polami (pierwsze 20 z każdej grupy; “i n więcej” dla reszty).
- Różnice tekstu, opisane nazwą pakietu, pokazują tekst SysML przed zmianą i po niej.
- Zmiana, która usuwa elementy, jest oznaczona i domyślnie odznaczona.
- Otwórz model SysML v2, aby zastosować tę zmianę. Model nie jest wczytany; otwórz stronę SysML v2 projektu.
- Pakietu nie ma już w modelu; pominięto. Pakiet został usunięty po zaproponowaniu zmiany.
Zastosuj zaznaczone ponownie synchronizuje każdą zmianę tekstu z bieżącym modelem i zachowuje edycje, których elementy nadal istnieją. Sprawdza cały zestaw i stosuje go jako jeden krok cofania. Zmiany, które już nie pasują, są pomijane i wymieniane w komunikacie. Odrzuć i Później działają jak w propozycjach LML, podobnie role, wygasanie (7 dni) i przechowywanie (zobacz Propozycje od klientów AI).
Systems Modeling API
Inne narzędzia SysML v2 odczytują i zmieniają modele Holarch przez trasy w kształtach OMG Systems Modeling API (REST/HTTP). Adres bazowy to https://app.holarch.app/api/v1/sysml. Używa tych samych tokenów; każda rola w projekcie może odczytywać, a edytorzy i właściciele mogą wykonywać commity.
- Projekty: wymieniane są tylko projekty SysML v2.
@idprojektu to UUID nadawany mu przez to API; działa też identyfikator projektu Holarch. Odpowiedź zawieraholarchIdiurl. - Gałęzie:
mainto model bieżący i nie można go zmienić przez API. Każda inna gałąź to trwający wniosek o zmianę, nazwany “CR-12 Title” i zawierającyholarchChangeRequest(id,label,status,url). Wnioski o zmianę wdrożone lub wycofane w ciągu ostatnich 30 dni są nadal wymieniane, z ustawionymdeleted. - Commity: commit zapisuje zmiany w gałęzi wniosku o zmianę. Udostępniane są tylko czoła gałęzi: czoło
mainto model bieżący, a czoło gałęzi wniosku o zmianę to model bieżący ze zmianami wniosku. Starsze identyfikatory commitów zwracają404; pobierz bieżące czoło z gałęzi. - Elementy: każdy element ma każdą właściwość swojej metaklasy ze schematu JSON OMG, łącznie z pochodnymi (
owner,ownedElement,qualifiedName,feature,typei podobne). Do elementów biblioteki standardowej odwołują się ich standardowe identyfikatory, te same, których inne narzędzia SysML v2 używają dla tego samego elementu biblioteki. - Tagi i zapisane zapytania: brak; ich listy są puste.
| Metoda i ścieżka | Co robi |
|---|---|
GET /sysml/projects | Twoje projekty SysML v2 |
POST /sysml/projects | Tworzy pusty projekt SysML v2 (name, description) |
GET /sysml/projects/<projectId> | Jeden projekt z jego gałęzią domyślną |
GET /sysml/projects/<projectId>/branches | main i gałęzie wniosków o zmianę |
POST /sysml/projects/<projectId>/branches | Tworzy gałąź: nowy wniosek o zmianę w stanie Draft (name to jego tytuł, description jego uzasadnienie) |
GET /sysml/projects/<projectId>/branches/<branchId> | Gałąź (jej @id lub main) z head |
DELETE /sysml/projects/<projectId>/branches/<branchId> | Wycofuje wniosek o zmianę |
GET /sysml/projects/<projectId>/commits | Czoła i commity wysłane do gałęzi, od najnowszych |
POST /sysml/projects/<projectId>/commits?branchId=<branchId> | Zatwierdza zmiany w gałęzi (commit; poniżej) |
GET /sysml/projects/<projectId>/commits/<commitId> | Commit czoła gałęzi |
GET /sysml/projects/<projectId>/commits/<commitId>/changes | Co gałąź zmienia względem modelu bieżącego: jeden DataVersion na element |
GET /sysml/projects/<projectId>/commits/<commitId>/elements | Wszystkie elementy commita, stronicowane |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId> | Jeden element |
GET /sysml/projects/<projectId>/commits/<commitId>/roots | Elementy najwyższego poziomu, stronicowane |
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationships | Relacje, w których element jest źródłem lub celem; direction to in, out lub both (domyślnie), stronicowane |
POST /sysml/projects/<projectId>/query-results | Elementy pasujące do zapytania (treść poniżej), stronicowane; commitId musi być czołem gałęzi |
GET /sysml/projects/<projectId>/tags, /queries, /commits/<commitId>/elements/<elementId>/projectUsages | Puste listy |
Odpowiedzi z listami to tablice JSON. Listy są stronicowane przez page[size] (domyślnie 100, najwyżej 1000) oraz page[after] (@id ostatniej pozycji poprzedniej strony) lub page[before] (@id pierwszej pozycji następnej strony). Nagłówek Link podaje następną stronę z rel="next" i poprzednią z rel="prev".
Zapytanie to obiekt JSON z opcjonalnymi polami where (PrimitiveConstraint z property, operator (=, in, <, <=, >, >= lub instanceOf), value i inverse albo CompositeConstraint z operator and lub or i constraint), scope (identyfikatory elementów: wyszukiwanie obejmuje je i to, co posiadają) oraz select (właściwości do zwrócenia; @id i @type są zwracane zawsze):
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"]}'
Odczytaj elementy modelu:
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"
Zatwierdzanie zmian (commit)
Zapis wymaga tokenu z dostępem do odczytu i zapisu, roli edytora lub właściciela, planu Team (także dla kont akademickich i zajęciowych) oraz włączonego przeglądu gałęzi w projekcie (Wnioski o zmianę → Ustawienia). Zatwierdzający przegląda i stosuje wniosek o zmianę w Holarch; tokeny nigdy nie głosują ani nie stosują zmian.
- Utwórz gałąź: POST
/branchesz{"@type": "Branch", "name": "Cabin heater"}. Odpowiedzią jest gałąź z jejholarchChangeRequest. - Odczytaj czoło gałęzi i jego elementy.
- POST
/commits?branchId=<branch @id>z listą obiektówDataVersion:
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>"}}}]}'
- Zmiana elementu: wyślij element w postaci, w jakiej go odczytano, ze zmienionymi właściwościami. Liczą się tylko właściwości posiadane (
declaredName,ownedRelationship,isAbstracti podobne); pochodne są ignorowane, więc odesłanie tego, co odczytano, niczego nie zmienia. Pominięta właściwość zachowuje swoją wartość; wyślijnulllub[], aby ją wyczyścić. - Nowe elementy: nadaj elementowi nowy UUID i podaj albo jego członkostwo właścicielskie (wysłane w tym samym commicie), albo
owner, który tworzy członkostwo automatycznie. - Usuwanie elementu:
payload: nullusuwa go wraz ze wszystkim, co posiada. - Kontrole: każdy pakiet, którego dotyczy commit, musi dać się wydrukować i ponownie przeanalizować, a commit nie może dodawać diagnostyk błędów; w przeciwnym razie
422zdiagnosticsdo poprawienia. - previousCommit: czoło, na którym wprowadzono zmianę. Jeśli gałąź od tego czasu się przesunęła, odpowiedzią jest
409stale-headz bieżącymhead; odczytaj ponownie i wykonaj commit na jego podstawie. - Ponowienia: wyślij nagłówek
Idempotency-Key. Ponowienie z tym samym kluczem i treścią w ciągu 24 godzin otrzymuje ponownie pierwszą odpowiedź. - Commity do
main: commit bezbranchIdlub zmaintrafia do własnego roboczego wniosku o zmianę tokenu (“API changes from <token name>”), tworzonego przy pierwszym takim commicie. Odpowiedź podaje, który to wniosek, wholarchChangeRequesti w nagłówkuWarning. - Nowe projekty: projekt utworzony przez POST
/sysml/projectsma włączony przegląd gałęzi. Jego pierwszy commit domain, gdy jesteś jego jedynym członkiem, jest jednorazowo zapisywany bezpośrednio w modelu; późniejsze commity przechodzą przez wnioski o zmianę.
Prześlij wniosek o zmianę do przeglądu przez POST /api/v1/projects/<project>/change-requests/<CR-12>/submit (API i MCP). Tagi, scalenia oraz zmiana nazwy lub usunięcie projektu zwracają 405 z informacją, co zrobić zamiast tego. Błędy mają @type Error i description, zgodnie z definicją w OMG API.
Komunikaty
Obowiązują kody ze strony API i MCP. Trasy i narzędzia SysML v2 dodają:
| Kod | Status | Znaczenie |
|---|---|---|
wrong-project-type | 409 | Operacja LML w projekcie SysML v2 lub operacja SysML v2 w projekcie LML |
syntax | 422 | Proponowany tekst ma błędy składni; diagnostyki podają wiersz i kolumnę |
invalid-model | 422 | Zmiana dodaje do modelu diagnostyki błędów; są one wymienione |
not-printable | 422 | Zmiany nie da się zapisać jako tekstu SysML |
invalid | 422 | Nie udało się zastosować zmiany do modelu |
no-change | 400 | Tekst nie zmienia modelu |
too-large | 413 | Tekst jest dłuższy niż 1 000 000 znaków lub propozycja jest większa niż 8 MB |
too-many | 413 lub 409 | Więcej niż 100 edycji w jednym wywołaniu (413) lub propozycja zawiera już 200 zmian (409) |
stale | 409 | Wcześniejsza zmiana tekstu w propozycji nie daje się już zastosować do modelu |
not-found | 404 | Nie ma takiego projektu, elementu, gałęzi ani commita (Systems Modeling API udostępnia tylko czoła gałęzi) |
not-writable | 405 | Tagi, scalenia, zmiana nazwy lub usunięcie projektu przez Systems Modeling API; wykonaj to w Holarch |
main-protected | 405 | Usunięcie main; zamiast tego usuń gałąź wniosku o zmianę |
stale-head | 409 | Gałąź przesunęła się od previousCommit; odczytaj jej head i wykonaj commit ponownie |
branch-base | 409 | Nowa gałąź musi zaczynać się od czoła main |
branch-review-off | 409 | Projekt nie używa przeglądu gałęzi; właściciel włącza go w Wnioski o zmianę → Ustawienia |
cr-not-draft | 409 | Wniosek o zmianę został przesłany lub zamknięty; można go zapisywać tylko w stanie Draft lub Rejected |
cr-full | 409 | Wniosek o zmianę zawiera 5000 zmienionych elementów lub projekt ma 20 MB wersji roboczych wniosków o zmianę |
plan-limit | 403 | Zapisy do wniosków o zmianę wymagają planu Team |
orphan | 422 | Nowy element nie ma właściciela; wyślij jego członkostwo właścicielskie lub owner |
unknown-metaclass | 422 | @type ładunku nie jest metaklasą SysML v2 |
idempotency-key-reused | 422 | Idempotency-Key został użyty z inną treścią; wyślij nowy klucz |
token-projects | 403 | Token ograniczony do listy projektów nie może utworzyć projektu |
bad-request | 400 | Brakująca lub błędna wartość, np. root, który nie jest pakietem najwyższego poziomu, nieznany op lub nowy element bez nazwy |
Limity
| Co | Limit |
|---|---|
| Elementy, wymagania lub połączenia na stronę | 500 |
| Składowe wymienione z elementem | 200 |
| Diagnostyki na odpowiedź | 500 |
| Wiersze tekstu SysML na odpowiedź | 5000 i najwyżej 400 000 bajtów (obcięte na granicy wiersza) |
| Tekst doc | 4000 znaków na listach, 20 000 dla jednego elementu |
| Własny tekst SysML elementu | 16 000 znaków |
Tekst w jednym wywołaniu propose_sysml | 1 000 000 znaków |
| Edycje w jednym wywołaniu | 100 |
| Elementy wymienione jako dodane, zmienione lub usunięte w jednej zmianie | Po 300 |
| Zmiany w jednej propozycji | 200 i 8 MB |
| Strona Systems Modeling API | 1000 elementów (domyślnie 100) |
| Obiekty DataVersion w jednym commicie | 5,000 |
| Zmienione elementy w jednym wniosku o zmianę | 5,000 |
| Treść commita | 32 MB |
Limity żądań, rozmiar żądań i zasady tokenów są takie jak na stronie API i MCP.
Powiązane strony
- API i MCP
- Pierwsze kroki z projektami SysML v2
- Edytor tekstu i Przeglądarka
- Wymiana modeli SysML v2
- Wymagania i weryfikacja w projektach SysML v2
SysML® i OMG® są zastrzeżonymi znakami towarowymi Object Management Group, Inc. w Stanach Zjednoczonych i innych krajach.