Holarch

SysML v2

SysML v2 專案中的 API 與 MCP

使用個人存取權杖,從指令碼和 AI 工具讀取、搜尋並檢查 SysML v2 模型,提出由您在 Holarch 中審查並套用的變更,並透過 Systems Modeling API 讀取與提交,其中分支即為變更請求。

使用方式 →

本頁內容
  1. 概觀
  2. 概念
  3. 使用方式
    1. 使用 curl 讀取 SysML v2 專案
    2. 提議之前先檢查 SysML 文字
    3. 提議變更並套用
    4. 將 AI 工具連接到 SysML v2 專案
    5. 實作範例:Hybrid Car 示範專案
    6. 提示
  4. SysML v2 專案的 REST 路由
    1. 數值
  5. SysML v2 專案的 MCP 工具
    1. 元素編輯
    2. 提議的文字
  6. SysML v2 專案中的提案
    1. 審查 SysML v2 提案
  7. Systems Modeling API
    1. 提交變更
  8. 訊息
  9. 限制
  10. 相關頁面

概觀

SysML v2 專案使用與 LML 專案相同的 REST API、MCP 端點與個人存取權杖。指令碼與 AI 工具會以元素與 SysML 文字讀取模型,在變更任何內容之前檢查文字,並提議變更。在有人於 Holarch 中審查提案並套用之前,模型不會有任何變更。

三種存取方式:

  • REST API:https://app.holarch.app/api/v1/projects/<project>/…,供指令碼與儀表板使用。它會讀取元素、需求、診斷與 SysML 文字,並將變更加入提案。
  • MCP:https://app.holarch.app/mcp,供 AI 工具使用。SysML v2 工具會讀取、搜尋並檢查模型,並提議變更。
  • Systems Modeling API:https://app.holarch.app/api/v1/sysml/…,採用 OMG Systems Modeling API 的格式,供其他 SysML v2 工具使用。分支 main 是即時模型,且為唯讀;其他每個分支都是一個變更請求,提交會進入其中。只有在核准者於 Holarch 中套用變更請求時,即時模型才會變更。

權杖、範圍、專案清單、組織切換、速率限制與連接 AI 應用程式的方式都與 LML 專案相同。關於建立權杖與連接 AI 工具,請參閱 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)。凡是路由或工具要求 ID 之處,也可使用 Vehicles::Car::powertrain 這類限定名稱。
  • 簡述(Brief):清單中元素的簡短形式: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。

使用方式

當指令碼或 AI 工具需要模型時,請使用 API:例如回報沒有滿足或驗證元素的需求、依模型檢查團隊的 SysML 文字,或讓 AI 工具草擬模型變更,再由工程師審查。

使用 curl 讀取 SysML v2 專案

  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. 詢問有關模型的問題,例如「Summarize the Hybrid Car model in Holarch」或「Which requirements in the Hybrid Car project are not verified?」。

    AI 工具會使用 model_summary、list_elements、list_requirements 與其他讀取工具。

  3. 要求變更,例如「Propose a range attribute on 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,以及埠 fuelIn、output 與 ecu)以及以它為型別的用法。
  4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections 會列出從 powertrain.output 到 frontAxle.input 的介面 driveShaft。
  5. GET /api/v1/projects/<project>/requirements?status=unverified 會列出沒有任何驗證案例驗證的需求,並附上其 ID,例如 VR-4.1。
  6. 以 {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} 呼叫 POST /api/v1/projects/<project>/proposal/changes 會將變更加入提案。以標題呼叫 POST /api/v1/projects/<project>/proposal 會送出提案。
  7. 在 Holarch 中,✦ AI ▾ → 審查「…」會顯示已變更:,包括零件定義與欄位 doc,以及 Vehicles 的文字差異。套用所選項會套用它。

提示

  • 在為套件提議新文字之前,先以 get_sysml(或 GET …/sysml?root=)讀取它。提議的文字中省略的元素會被移除。
  • 小變更請優先使用元素編輯。它們只會變更指定的元素,並讓套件文字的其餘部分保持原樣。
  • 先以 check_sysml(或 POST …/sysml/check)檢查文字。它會傳回與提案被拒絕時相同的診斷。
  • 在指令碼中以限定名稱指稱元素。元素重新命名時 ID 保持不變;限定名稱則會改變。
  • 當 AI 工具只需回答有關模型的問題時,請給它唯讀權杖。

SysML v2 專案的 REST 路由

基礎位址: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需求及其 ID、陳述(doc)、satisfiedBy 與 verifiedBy;owner、status(unsatisfied 或 unverified)、limit(預設 100)、offset
GET /projects/<project>/diagnostics模型的診斷,錯誤優先;ids(以逗號分隔:只包含這些元素及其成員)、limit(預設 200,最多 500)
GET /projects/<project>/sysml頂層套件(root)、套件外元素(不帶 root)或單一元素(element)的 SysML 文字;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 ID 指定的提案,以及其狀態與變更
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、模型檢查與品質檢查)在 SysML v2 專案中會回應 409 wrong-project-type。SysML v2 路由在 LML 專案中也會如此回應。

數值

  • type:元類別,例如 PartUsage 或 RequirementDefinition,或 SysML 文字中所寫的關鍵字:part、part def、attribute、port、requirement、action、package 與其他元素關鍵字。
  • owner、id、element、root:ID 或限定名稱。root 也接受頂層套件的名稱。root 必須是頂層套件;若要讀取單一元素的文字,請使用 element。
  • 過長的值:清單中的 doc 會在 4,000 個字元處截斷,單一元素的 doc 在 20,000 個字元處截斷,元素本身的 SysML 文字則在 16,000 個字元處截斷。

SysML v2 專案的 MCP 工具

MCP 端點會將這些工具與 LML 工具並列。AI 工具會以 list_projects(language: sysml2)找到 SysML v2 專案。每個工具都接受 project。

讀取工具也接受選用的 change_request(CR-12 或其 ID),以讀取該變更請求所產生的模型;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讀取需求及其 ID、陳述、satisfy 與 verify;owner、status(unsatisfied、unverified)、limit、offset
get_sysml讀取頂層套件(root)、套件外元素或單一元素(element)的 SysML 文字;line、lines(最多 5000);回應會提供 next
get_sysml_text讀取整個模型(每個頂層套件,然後是套件外元素)或單一 package 的 SysML 文字,每次回應最多 200,000 個字元;回應會列出被省略的套件
check_sysml讀取不帶 text:模型的診斷(ids、limit)。帶 text(與 root):帶有行與欄的語法錯誤,以及該文字會新增的錯誤。不會變更任何內容
propose_sysml讀取與寫入提議頂層套件(root)或套件外元素(不帶 root;新套件也放在此處)的完整新 text
propose_element_changes讀取與寫入不重寫文字而提議 edits(最多 100 個):create、update、move 或 remove

list_diagrams、get_diagram 與 get_matrix 也適用於 SysML v2 專案:list_diagrams 會列出檢視(包括其種類,例如 InterconnectionView)以及保存在元素下的分析圖;get_diagram 會提供檢視在套用篩選後所公開的元素(依元素 ID 或限定名稱);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 與要變更的欄位,與 create 相同;null 或 "" 會清除欄位
moveid 與新的 owner
removeid;移除該元素及其成員
  • typedBy、specializes、subsets 與 redefines 是最多 20 個名稱的清單:ID、限定名稱,或文字中所寫的名稱(MassValue 這類庫名稱也可以)。
  • 後續的編輯可依建立順序以 new:1、new:2 … 指稱同一次呼叫中先前建立的元素,例如作為 owner。回應會將它們連同新 ID 列在 created 下。
  • 重新命名元素也會更新以舊名稱指稱它的參照。

提議的文字

  • propose_sysml 會取代套件的整份文字。文字仍宣告的元素會保留其 ID。文字中省略的元素會被移除。
  • 文字必須能剖析,且不得留下任何未套用的部分。不會變更模型的文字會被拒絕(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 工具會透過採用 OMG Systems Modeling API(REST/HTTP)格式的路由讀取並變更 Holarch 模型。基礎位址為 https://app.holarch.app/api/v1/sysml。它使用相同的權杖;任何專案角色都能讀取,編輯者與擁有者可以提交。

  • 專案:只會列出 SysML v2 專案。專案的 @id 是此 API 賦予的 UUID;Holarch 專案 ID 也可以使用。回應包含 holarchId 與 url。
  • 分支:main 是即時模型,無法透過 API 變更。其他每個分支都是進行中的變更請求,名稱為「CR-12 Title」,並帶有 holarchChangeRequest(id、label、status、url)。過去 30 天內已實作或撤回的變更請求仍會列出,並設定 deleted。
  • 提交:提交會將變更寫入變更請求的分支。只提供分支頭:main 的分支頭是即時模型,變更請求分支的分支頭是加上該請求變更的即時模型。較舊的提交 ID 會回應 404;請從分支取得目前的分支頭。
  • 元素:每個元素都具有 OMG JSON 結構描述中其元類別的所有屬性,包括衍生屬性(owner、ownedElement、qualifiedName、feature、type 等)。標準庫元素以其標準 ID 參照,也就是其他 SysML v2 工具對同一庫元素所使用的 ID。
  • 標籤與已儲存的查詢:沒有;其清單為空。
方法與路徑功能
GET /sysml/projects您的 SysML v2 專案
POST /sysml/projects建立空的 SysML v2 專案(name、description)
GET /sysml/projects/<projectId>一個專案及其預設分支
GET /sysml/projects/<projectId>/branchesmain 與變更請求分支
POST /sysml/projects/<projectId>/branches建立分支:一個新的草稿變更請求(name 是其標題,description 是其原因)
GET /sysml/projects/<projectId>/branches/<branchId>該分支(其 @id 或 main),附 head
DELETE /sysml/projects/<projectId>/branches/<branchId>撤回變更請求
GET /sysml/projects/<projectId>/commits分支頭與送到各分支的提交,最新的在前
POST /sysml/projects/<projectId>/commits?branchId=<branchId>將變更提交到分支(見下文)
GET /sysml/projects/<projectId>/commits/<commitId>一個分支頭提交
GET /sysml/projects/<projectId>/commits/<commitId>/changes該分支相對於即時模型所做的變更:每個元素一個 DataVersion
GET /sysml/projects/<projectId>/commits/<commitId>/elements該提交的所有元素,分頁
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>一個元素
GET /sysml/projects/<projectId>/commits/<commitId>/roots頂層元素,分頁
GET /sysml/projects/<projectId>/commits/<commitId>/elements/<elementId>/relationships以該元素為來源或目標的關係;direction 為 in、out 或 both(預設),分頁
POST /sysml/projects/<projectId>/query-results符合查詢(本文見下)的元素,分頁;commitId 必須是分支頭
GET /sysml/projects/<projectId>/tags、/queries、/commits/<commitId>/elements/<elementId>/projectUsages空清單

清單回應為 JSON 陣列。清單以 page[size](預設 100,最多 1000)與 page[after](上一頁最後一個項目的 @id)或 page[before](下一頁第一個項目的 @id)分頁。Link 標頭以 rel="next" 提供下一頁,以 rel="prev" 提供上一頁。

查詢是一個 JSON 物件,包含選用的 where(帶有 property、operator(=、in、<、<=、>、>= 或 instanceOf)、value 與 inverse 的 PrimitiveConstraint,或帶有 operator and 或 or 以及 constraint 的 CompositeConstraint)、scope(元素 ID:搜尋涵蓋這些元素及其擁有的內容)與 select(要傳回的屬性;@id 與 @type 一律會傳回):

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

讀取模型的元素:

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

提交變更

寫入需要具有讀寫存取權的權杖、編輯者或擁有者角色、Team 方案(學術與課程帳戶亦同),以及該專案已開啟分支審查(變更請求 → 設定)。核准者會在 Holarch 中審查並套用變更請求;權杖永遠不會投票或套用。

  1. 建立分支:以 {"@type": "Branch", "name": "Cabin heater"} 呼叫 POST /branches。回應是該分支及其 holarchChangeRequest。
  2. 讀取分支的分支頭及其元素。
  3. 以 DataVersion 清單呼叫 POST /commits?branchId=<branch @id>:
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits?branchId=<branch id>" \
  -d '{"@type": "Commit", "description": "Add the heater",
       "previousCommit": {"@id": "<head id>"},
       "change": [{"@type": "DataVersion", "identity": {"@id": "<new uuid>"},
                   "payload": {"@type": "PartDefinition", "declaredName": "CabinHeater", "owner": {"@id": "<package id>"}}}]}'
  • 變更元素:將元素依您讀取時的樣子傳送,並變更屬性。只有擁有的屬性才算數(declaredName、ownedRelationship、isAbstract 等);衍生屬性會被忽略,因此將讀取的內容原樣傳回不會變更任何內容。您省略的屬性會保留其值;傳送 null 或 [] 可清除它。
  • 新元素:為元素指定新的 UUID,並提供其擁有成員關係(在同一次提交中傳送)或 owner(會自動為您建立成員關係)。
  • 移除元素:payload: null 會移除該元素及其擁有的一切。
  • 檢查:提交所涉及的每個套件都必須能再次輸出並剖析,且提交不得新增錯誤診斷;否則會傳回 422 以及需要修正的 diagnostics。
  • previousCommit:您的變更所依據的分支頭。若分支自那之後已移動,回應為 409 stale-head 並附上目前的 head;請重新讀取並在其上提交。
  • 重試:傳送 Idempotency-Key 標頭。在 24 小時內以相同金鑰與本文重試,會再次得到第一次的回應。
  • 提交到 main:不帶 branchId 或帶有 main 的提交,會進入您權杖專屬的草稿變更請求(「API changes from <token name>」),該請求在第一次這類提交時建立。回應會在 holarchChangeRequest 與 Warning 標頭中說明是哪一個。
  • 新專案:以 POST /sysml/projects 建立的專案已開啟分支審查。在您是其唯一成員期間,其第一次提交到 main 會直接寫入模型,僅此一次;之後的提交會經由變更請求。

以 POST /api/v1/projects/<project>/change-requests/<CR-12>/submit 將變更請求送交審查(API 與 MCP)。標籤、合併以及重新命名或刪除專案會回應 405,並說明應改用的做法。錯誤帶有 @type Error 與 description,依 OMG API 的定義。

訊息

API 與 MCP 的代碼同樣適用。SysML v2 路由與工具另外新增:

代碼狀態意義
wrong-project-type409在 SysML v2 專案中執行 LML 操作,或在 LML 專案中執行 SysML v2 操作
syntax422提議的文字有語法錯誤;診斷會提供行與欄
invalid-model422變更為模型新增了錯誤診斷;這些診斷會列出
not-printable422變更無法寫成 SysML 文字
invalid422變更無法套用到模型
no-change400文字不會變更模型
too-large413文字超過 1,000,000 個字元,或提案大於 8 MB
too-many413 或 409單次呼叫超過 100 個編輯(413),或提案已包含 200 項變更(409)
stale409提案先前的某項文字變更已不再適用於模型
not-found404沒有此專案、元素、分支或提交(Systems Modeling API 只提供分支頭)
not-writable405透過 Systems Modeling API 進行標籤、合併、重新命名或刪除專案;請在 Holarch 中進行
main-protected405刪除 main;請改為刪除變更請求分支
stale-head409分支自 previousCommit 以來已移動;請讀取其 head 後再次提交
branch-base409新分支必須從 main 的分支頭開始
branch-review-off409此專案未使用分支審查;擁有者可在變更請求 → 設定中開啟
cr-not-draft409變更請求已送出或已關閉;只能在草稿或已拒絕狀態下寫入
cr-full409變更請求包含 5,000 個已變更項目,或專案的變更請求草稿達 20 MB
plan-limit403寫入變更請求需要 Team 方案
orphan422新元素沒有擁有者;請傳送其擁有成員關係或 owner
unknown-metaclass422承載內容的 @type 不是 SysML v2 元類別
idempotency-key-reused422Idempotency-Key 已搭配其他本文使用過;請傳送新的金鑰
token-projects403限定於專案清單的權杖無法建立專案
bad-request400缺少值或值錯誤,例如 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 相同。

SysML® 與 OMG® 是 Object Management Group, Inc. 在美國及其他國家的註冊商標。