Holarch

SysML v2

holarch 命令列工具

使用 holarch 命令列工具與 Holarch Language Engine,在建置與 CI 中檢查、格式化並匯出 SysML v2 模型;GitHub Actions 與其他 CI 系統、JSON 與 SARIF 報告、結束代碼,以及使用 API 權杖或授權檔案登入。

使用方式 →

本頁內容
  1. 概觀
  2. 概念
  3. 使用方式
    1. 使用時機與原因
    2. 安裝
    3. 以 API 權杖登入
    4. 檢查模型
    5. 格式化檔案
    6. 將模型匯出為 SysML v2 JSON
    7. 在 GitHub Actions 中執行
    8. 在其他 CI 系統中執行
    9. 實作範例:Hybrid Car 示範專案
    10. 提示與良好做法
    11. 常見錯誤
    12. 與其他功能的關聯
  4. 命令
    1. check 的選項
    2. format 的選項
    3. export 的選項
    4. 每個需要登入之命令的選項
  5. 工具的登入
    1. CI 中的授權檔案
  6. 報告
    1. JSON 輸出
    2. SARIF
    3. GitHub 註記
  7. 結束代碼
  8. 訊息
  9. 限制
  10. 相關頁面

概觀

holarch 是一個命令列工具,它以 Holarch Language Engine(與 Holarch 編輯器使用的引擎相同)檢查 SysML v2 文字檔案。您可以在自己的電腦或建置中執行它:它會讀取資料夾中的每個 .sysml 檔案,以檔案、行與欄回報問題,並在模型有錯誤時以非零代碼結束,因此含有損壞模型的提取要求會無法通過檢查。

此工具會做三件事:

  • 檢查:語法、名稱、型別、特化、多重性、單位與引擎的其他規則,涵蓋模型的所有檔案。以文字、JSON、SARIF(用於程式碼掃描)或 GitHub 註記回報。
  • 格式化:以一種標準版面配置(四個空格縮排、每行一個元素、標準間距)改寫檔案,並保留每個註解。
  • 匯出:將模型寫成 SysML v2 JSON,也就是 Systems Modeling API 的交換格式。

此工具隨附於 Individual 與 Team 方案(包括試用)、Holarch Language Engine 授權以及自行託管版授權。它不需要 Holarch 專案:它處理的是您存放庫中的檔案。

概念

  • 模型:您指定之資料夾(預設:目前資料夾)下的所有 .sysml 檔案,作為一個模型讀取。在一個檔案中宣告的名稱可在其他檔案中解析,就像 Holarch 專案中的套件一樣。名稱以點開頭的資料夾(例如 .git)會被略過。
  • KerML 檔案:可讀取 KerML 的引擎版本會將 .kerml 檔案作為 KerML 檢查。較舊的引擎版本會將其列為已略過,這不是錯誤。
  • 診斷:每個問題都有代碼(例如 name.unresolved)、嚴重性(錯誤、警告或附註)、位置,以及與 Holarch 編輯器用語相同的訊息。只有錯誤會使檢查失敗,除非您加上 --warnings-as-errors。
  • 登入:此工具每天檢查一次您的 API 權杖是否屬於 Individual 或 Team 方案,或在不存取網路的情況下讀取授權檔案。請參閱工具的登入。
  • 引擎:此工具包含已編譯的 Holarch Language Engine 與 SysML v2 標準庫。holarch version 會印出它們的版本與引擎的著作權聲明。

使用方式

使用時機與原因

當 SysML v2 文字存放在原始碼存放庫中時,請使用此工具:設計者以自己選擇的編輯器編輯 .sysml 檔案,而每項變更在合併之前都會經過檢查。它會在每次提交時回答「這個模型是否仍然完整一致?」,就像編譯器對程式碼所做的一樣。請使用 Holarch 編輯器進行建模、繪圖與審查;使用此工具在編輯之間守護檔案。若要在存放庫與 Holarch 專案之間移動模型,請使用匯入和匯出。

安裝

  1. 安裝 Python 3.9 或更新版本。
  2. 以 pip 為您的系統(Linux x86-64、Linux arm64 或 Apple silicon 上的 macOS)安裝此工具:
python3 -m pip install holarch-cli
  1. 檢查安裝:holarch version 會印出工具、引擎與庫的版本。

以 API 權杖登入

  1. 在 Holarch 中開啟帳戶設定 → API 權杖並建立權杖。唯讀存取權即已足夠。
  2. 將權杖放入 HOLARCH_API_KEY 環境變數(在 CI 中:一個機密)。
  3. 執行 holarch whoami。它會印出您的方案與帳戶,例如 "plan": "team"。

檢查模型

holarch check models/

每個問題一行,接著是摘要:

models/requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. Check the spelling, or import its package.
6 files checked: 1 error, 0 warnings.

模型有錯誤時結束代碼為 1,否則為 0。加上 --warnings-as-errors 可讓警告也導致失敗。

格式化檔案

  1. 執行 holarch format models/。每個已變更的檔案會列為「reformatted <file>」。
  2. 若要在 CI 中檢查版面配置而不變更檔案,請執行 holarch format --check models/。它會列出「would reformat <file>」,並在有檔案會被變更時以 1 結束。
  3. 若要先查看變更,請執行 holarch format --diff models/。

有語法錯誤的檔案不會被格式化(「not formatted: the file has syntax errors.」)。註解會留在原處:元素之前的附註留在其上方,行尾的附註留在該行行尾。

將模型匯出為 SysML v2 JSON

holarch export models/ -o model.json

該檔案包含 Systems Modeling API 的標準元素陣列。相同的檔案一律產生相同的 JSON,因此匯出結果可以提交並比較。有錯誤的模型不會匯出(「The model has errors, so it was not exported.」);加上 --force 可強制匯出。加上 --holarch-fields 可保留只有 Holarch 會讀取的內容(元素順序、拼寫),以便精確匯入 Holarch 專案。

在 GitHub Actions 中執行

  1. 將 API 權杖新增為名為 HOLARCH_API_KEY 的存放庫機密(Settings → Secrets and variables → Actions)。
  2. 新增一個工作流程檔案,例如 .github/workflows/sysml.yml:
name: SysML model
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install holarch-cli
      - run: holarch check models --format github --sarif holarch.sarif
        env:
          HOLARCH_API_KEY: ${{ secrets.HOLARCH_API_KEY }}
      - run: holarch format --check models
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: holarch.sarif
  1. 推送。問題會以註記形式出現在提取要求中已變更的行上,當模型有錯誤或檔案不符合標準版面配置時,作業會失敗。若只要檢查模型,請省略 holarch format --check 步驟。

最後一個步驟會將 SARIF 報告上傳到程式碼掃描,問題會列在 Security → Code scanning 下。若您的存放庫不使用程式碼掃描,請省略此步驟:註記不需要它也能運作。

在其他 CI 系統中執行

任何具有 Python 3.9 或更新版本的 CI 系統都能執行相同的命令。安裝工具、從機密設定權杖、執行檢查:

python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json

例如 GitLab CI(.gitlab-ci.yml,並將 HOLARCH_API_KEY 設為遮罩的 CI/CD 變數):

sysml:
  image: python:3.12
  script:
    - pip install holarch-cli
    - holarch check models/ --sarif gl-holarch.sarif
    - holarch format --check models/
  artifacts:
    when: always
    paths: [gl-holarch.sarif]

Jenkins、Azure Pipelines、CircleCI 等系統的運作方式相同:一個步驟安裝工具,下一個步驟執行 holarch check;非零的結束代碼會使建置失敗。若您想在儀表板中呈現數字,請將 JSON 報告(--json)保留為建置成品。

實作範例:Hybrid Car 示範專案

  1. 建立示範:在管理專案上按一下專案檔案 ▾ → 新增示範專案 → Hybrid Car (SysML v2)。
  2. 開啟模型 → 匯入和匯出。在匯出下選擇整個模型與SysML v2 文字,按一下匯出,然後將下載的檔案解壓縮到您存放庫的 models 資料夾中。
  3. 執行 holarch check models。結果為「6 files checked: 0 errors, 0 warnings.」
  4. 在 requirements.sysml 中,將 attribute maxCurbMass : MassValue 改為 MassValu,然後再次執行檢查。它會回報 requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. 並以 1 結束。
  5. 復原該變更。執行一次 holarch format models 並提交檔案,讓之後的 format --check 執行能夠通過。
  6. 新增上述 GitHub 工作流程。之後每個破壞模型的提取要求都會無法通過檢查。

提示與良好做法

  • 將每個檔案的內容放在一個套件中。任何套件外的元素也能運作,但每個檔案一個套件可讓名稱在檔案之間保持唯一。
  • 為 CI 使用唯讀權杖,且不限定任何專案:此工具不需要專案存取權。
  • 在開啟 format-check 之前先格式化一次並提交結果,否則第一次執行會在每個檔案上失敗。
  • 在 CI 中固定工具的版本(holarch-cli==<version>),以免新的引擎發行版在審查進行中改變結果。
  • 沒有網際網路存取的執行器改用授權檔案而非權杖。

常見錯誤

  • 「No .sysml or .kerml files found」:路徑錯誤,或檔案位於名稱以點開頭的資料夾中。
  • 名稱只在一個檔案中無法解析:該檔案使用了另一個檔案所宣告的名稱,而那個檔案有語法錯誤。請先修正語法錯誤;報告會說明哪些檔案被省略。
  • 作業以結束代碼 3 失敗:權杖遺失、錯誤,或屬於 Free 方案上的帳戶。訊息會說明是哪一種。

與其他功能的關聯

  • 檢查內容與 Holarch 編輯器的 SysML v2 文字檢查以及 SysML v2 專案的模型檢查相同,訊息也相同(SysML v2 文字編輯器)。
  • 從專案匯出的檔案(匯入和匯出)可以無誤通過檢查;此工具匯出的 JSON 可以匯入專案。
  • 對於應在 Holarch 中經過審查、而非透過檔案進行的變更,請使用 API 或 Python 用戶端,其變更會以提案形式送達。

命令

命令功能
holarch check [paths]檢查模型;回報問題;有錯誤時以 1 結束
holarch format [paths]以標準版面配置改寫檔案
holarch export [paths]將模型寫成 SysML v2 JSON
holarch whoami顯示權杖或授權檔案允許的內容
holarch version印出工具、引擎與庫的版本以及引擎的著作權聲明(不需登入)

路徑為檔案或資料夾;預設為目前資料夾。資料夾會連同其子資料夾一起搜尋。

check 的選項

選項意義
--format human|json|sarif|github標準輸出上的報告(預設 human)
--output FILE改為將該報告寫入檔案
--sarif FILE同時寫入 SARIF 2.1.0 報告
--json FILE同時寫入 JSON 報告
--warnings-as-errors警告時也以 1 結束

format 的選項

選項意義
--check不變更任何內容;有檔案會被變更時以 1 結束
--diff不變更任何內容;以統一差異格式印出變更
--stdout印出單一檔案格式化後的文字,而不寫入

export 的選項

選項意義
-o FILE, --output FILE寫入檔案(預設:標準輸出)
--holarch-fields加入只有 Holarch 會讀取的欄位,以便精確往返
--force匯出有錯誤的模型(有語法錯誤者絕不匯出)

每個需要登入之命令的選項

選項環境變數意義
--api-key KEYHOLARCH_API_KEYAPI 權杖(hol_…);建議使用環境變數,讓權杖不出現在日誌中
--license FILEHOLARCH_LICENSE_FILE供離線使用的授權檔案
--server URLHOLARCH_SERVER檢查權杖的 Holarch 伺服器(https 位址)
--timeout SECONDS每個引擎步驟的時間限制(預設 60)

工具的登入

當下列其中一項存在時,此工具即可執行:

  • Individual 或 Team 方案的 API 權杖,包括 Individual 試用。此工具會詢問伺服器一次,並將回應保留在快取檔案中一天(~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIR 可變更其位置)。快取保存方案與帳戶電子郵件,絕不保存權杖。當無法連線到伺服器時,最多 7 天前的回應仍然有效,並附上附註。
  • 授權檔案,適用於 Holarch Language Engine 被授權者、自行託管版客戶,以及沒有網際網路存取的執行器。此工具會自行檢查檔案的簽章,絕不連線到伺服器。每個有效授權都包含此工具,無須額外付費:
    • Holarch Language Engine 授權:將引擎交付中的授權金鑰(以 l1. 開頭的文字)儲存到檔案中,例如 holarch-engine.key,並將 --license 或 HOLARCH_LICENSE_FILE 指向它。電子郵件加入的換行不影響。金鑰中的授權網址與伺服器使用範圍適用於您產品中的引擎,而非此工具。在金鑰到期日後的 14 天內,此工具仍會運作並印出提醒。
    • 自行託管版授權:直接使用您 Holarch 伺服器的授權檔案。在最後 30 天內,此工具會印出提醒。在到期日後的 30 天內(授權的寬限期),此工具仍會運作並印出剩餘天數;之後它會停止,直到安裝續約的授權為止。

超過 14 天的引擎金鑰同樣會使工具停止,直到安裝續約的金鑰為止。

Free 方案上帳戶的權杖會被拒絕,即使該帳戶透過學術電子郵件地址保有 API 也一樣。Individual 試用包含此工具。

CI 中的授權檔案

將授權存為機密,絕不放在存放庫中。在 CI 中,將機密寫入簽出目錄之外的檔案(在 GitHub Actions 中,放在 $RUNNER_TEMP 下),並將 HOLARCH_LICENSE_FILE 設為其路徑。

報告

JSON 輸出

--format json 與 --json FILE 會寫入:

欄位意義
tool, version, engineholarch、工具的版本、引擎的版本
files已檢查的檔案,以相對於工具執行所在資料夾的路徑表示
summaryerrors, warnings, notes, files
diagnosticsfile、line、column、endLine、endColumn(從 1 開始)、severity(error、warning、info)、code、message、args
skipped未檢查的檔案及原因(使用較舊引擎時的 KerML 檔案)
excluded有語法錯誤的檔案,已從跨檔案檢查中省略

欄以 Unicode 字元(碼位)計算。

SARIF

--format sarif 與 --sarif FILE 會寫入 SARIF 2.1.0,每個診斷代碼一條規則,嚴重性為 error、warning 或 note,路徑相對於工具執行所在的資料夾。請在存放庫根目錄執行此工具,讓程式碼掃描能找到檔案。

GitHub 註記

--format github 會為每個問題印出一個工作流程命令(::error file=…,line=…,col=…::message),GitHub Actions 會將其顯示為註記,最後印出摘要行。

結束代碼

代碼意義
0沒有錯誤(format:沒有需要變更的內容)
1模型有錯誤;format --check 或 --diff:有檔案會被變更,或有檔案無法格式化;export:因錯誤而拒絕
2用法錯誤:未知的選項、不存在的路徑、沒有模型檔案
3未登入或無權使用:沒有權杖或授權檔案、權杖被拒絕、Free 方案、授權檔案無效、遭變更或已過期
4引擎無法執行,或因模型過大或檢查過慢而拒絕

訊息

訊息意義
「The holarch command line tool needs a Holarch API token of an Individual or Team plan (HOLARCH_API_KEY, or --api-key) or a Holarch Language Engine license file (HOLARCH_LICENSE_FILE, or --license).」(holarch 命令列工具需要 Individual 或 Team 方案的 Holarch API 權杖,或 Holarch Language Engine 授權檔案。)權杖與授權檔案都未設定
「The holarch command line tool comes with the Individual and Team plans. Choose a plan in Account Settings → Plan & Billing, or use a Holarch Language Engine license file.」(holarch 命令列工具隨附於 Individual 與 Team 方案。請在帳戶設定 → 方案與帳單中選擇方案,或使用 Holarch Language Engine 授權檔案。)權杖的帳戶使用 Free 方案
「The API and MCP come with the Individual and Team plans.」(API 與 MCP 隨附於 Individual 與 Team 方案。)權杖的帳戶使用 Free 方案,且也沒有 API 存取權
「The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.」(API 權杖無效:權杖錯誤、已撤銷或已過期,或其帳戶無法登入。)建立新的權杖
「The license file's signature does not verify. Use the file exactly as it was delivered.」(授權檔案的簽章驗證失敗。請使用與交付時完全相同的檔案。)授權檔案遭變更或損毀
「License <id> expired on <date>. Install a renewed license file.」(授權 <id> 已於 <date> 到期。請安裝續約的授權檔案。)自行託管版授權已結束超過 30 天,或引擎授權金鑰已結束超過 14 天
「The engine license key's signature does not verify. Use the key exactly as it was delivered.」(引擎授權金鑰的簽章驗證失敗。請使用與交付時完全相同的金鑰。)檔案中的金鑰遭變更,或來自其他產品
「The engine license key is not complete. Copy the whole key (l1.….…) into the file.」(引擎授權金鑰不完整。請將整個金鑰複製到檔案中。)金鑰的一部分遺失
「… cannot be reached to check the API token」(無法連線到 … 以檢查 API 權杖)沒有連線,且快取中沒有近期的回應;請再試一次,或使用授權檔案
「<file>: not formatted: the file has syntax errors.」(未格式化:檔案有語法錯誤。)執行 holarch check 以查看錯誤
「<file>: not formatted: a comment could not be kept in place.」(未格式化:有註解無法保留在原處。)檔案保持不變;此工具絕不會捨棄註解
「The model has errors, so it was not exported.」(模型有錯誤,因此未匯出。)修正錯誤,或加上 --force
「The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.」(已安裝的引擎沒有 Holarch Language Engine 著作權聲明,因此不是正版的 Holarch 建置。)重新安裝此工具

限制

  • 一個模型中每種語言最多 8 MB 的 SysML 文字,每行最多 64 KB,與編輯器相同。
  • 一次執行最多 10,000 個檔案。
  • 每個引擎步驟在 --timeout 秒後停止(預設 60)。
  • 名稱在同一語言的檔案之間解析:.sysml 檔案看不到 .kerml 檔案中宣告的名稱。