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 芯片的 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文件中声明的名称。