SysML v2
holarch 命令列工具
使用 holarch 命令列工具與 Holarch Language Engine,在建置與 CI 中檢查、格式化並匯出 SysML v2 模型;GitHub Actions 與其他 CI 系統、JSON 與 SARIF 報告、結束代碼,以及使用 API 權杖或授權檔案登入。
本頁內容
概觀
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 專案之間移動模型,請使用匯入和匯出。
安裝
- 安裝 Python 3.9 或更新版本。
- 以 pip 為您的系統(Linux x86-64、Linux arm64 或 Apple silicon 上的 macOS)安裝此工具:
python3 -m pip install holarch-cli
- 檢查安裝:
holarch version會印出工具、引擎與庫的版本。
以 API 權杖登入
- 在 Holarch 中開啟帳戶設定 → API 權杖並建立權杖。唯讀存取權即已足夠。
- 將權杖放入
HOLARCH_API_KEY環境變數(在 CI 中:一個機密)。 - 執行
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 可讓警告也導致失敗。
格式化檔案
- 執行
holarch format models/。每個已變更的檔案會列為「reformatted <file>」。 - 若要在 CI 中檢查版面配置而不變更檔案,請執行
holarch format --check models/。它會列出「would reformat <file>」,並在有檔案會被變更時以 1 結束。 - 若要先查看變更,請執行
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 中執行
- 將 API 權杖新增為名為
HOLARCH_API_KEY的存放庫機密(Settings → Secrets and variables → Actions)。 - 新增一個工作流程檔案,例如
.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
- 推送。問題會以註記形式出現在提取要求中已變更的行上,當模型有錯誤或檔案不符合標準版面配置時,作業會失敗。若只要檢查模型,請省略
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 示範專案
- 建立示範:在管理專案上按一下專案檔案 ▾ → 新增示範專案 → Hybrid Car (SysML v2)。
- 開啟模型 → 匯入和匯出。在匯出下選擇整個模型與SysML v2 文字,按一下匯出,然後將下載的檔案解壓縮到您存放庫的
models資料夾中。 - 執行
holarch check models。結果為「6 files checked: 0 errors, 0 warnings.」 - 在
requirements.sysml中,將attribute maxCurbMass : MassValue改為MassValu,然後再次執行檢查。它會回報requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.並以 1 結束。 - 復原該變更。執行一次
holarch format models並提交檔案,讓之後的format --check執行能夠通過。 - 新增上述 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 KEY | HOLARCH_API_KEY | API 權杖(hol_…);建議使用環境變數,讓權杖不出現在日誌中 |
--license FILE | HOLARCH_LICENSE_FILE | 供離線使用的授權檔案 |
--server URL | HOLARCH_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 天內(授權的寬限期),此工具仍會運作並印出剩餘天數;之後它會停止,直到安裝續約的授權為止。
- Holarch Language Engine 授權:將引擎交付中的授權金鑰(以
超過 14 天的引擎金鑰同樣會使工具停止,直到安裝續約的金鑰為止。
Free 方案上帳戶的權杖會被拒絕,即使該帳戶透過學術電子郵件地址保有 API 也一樣。Individual 試用包含此工具。
CI 中的授權檔案
將授權存為機密,絕不放在存放庫中。在 CI 中,將機密寫入簽出目錄之外的檔案(在 GitHub Actions 中,放在 $RUNNER_TEMP 下),並將 HOLARCH_LICENSE_FILE 設為其路徑。
報告
JSON 輸出
--format json 與 --json FILE 會寫入:
| 欄位 | 意義 |
|---|---|
tool, version, engine | holarch、工具的版本、引擎的版本 |
files | 已檢查的檔案,以相對於工具執行所在資料夾的路徑表示 |
summary | errors, warnings, notes, files |
diagnostics | file、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檔案中宣告的名稱。