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