内容
# SysML
[](https://gitlab.com/nomograph/sysml/-/pipelines)
[](LICENSE)
[](https://gitlab.com/nomograph/sysml)
[](https://crates.io/crates/nomograph-sysml)
SysML v2 的命令行原生知识图谱工具包。单个二进制文件，双模式（命令行 + MCP 服务器）。 [Nomograph Labs](https://nomograph.ai) 的一部分。
**仓库地址**: [gitlab.com/nomograph/sysml](https://gitlab.com/nomograph/sysml)
## 什么是 SysML
SysML 建立在 [tree-sitter-sysml](https://gitlab.com/nomograph/tree-sitter-sysml) 之上，用于解析，并受到 GitLab 的 [Global Knowledge Graph](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/gkg/) 架构的启发。提供了一个用于解析、查询和遍历 SysML v2 模型的命令行工具，以及一个用于 AI 代理集成的 MCP 服务器。
## 安装
需要 Rust 1.85 或更高版本。
```bash
cargo install nomograph-sysml
```
启用 MCP 服务器支持：
```bash
cargo install nomograph-sysml --features mcp
```
从源代码安装：
```bash
cargo install --path crates/sysml-cli # 二进制文件安装为 'sysml'
```
## 快速入门
```bash
# 从 SysML v2 文件构建知识图谱
sysml index path/to/model/
# 搜索元素
sysml search "ShieldModule"
# => {"total_candidates":42,"results_returned":1,"results":[{"qualified_name":"ShieldModule","kind":"PartDefinition","score":1.0,...}]}
# 跟踪元素的关联
sysml trace ShieldModule --hops 3
# 检查模型完整性
sysml check all --detail
# 查询特定类型的关联
sysml query --source-name "ShieldModule" --rel satisfy
# 将问题分解为可执行步骤
sysml plan "Does ShieldModule satisfy MFRQ01?" --execute
# 启动 MCP 服务器（需要 --features mcp）
sysml --mcp
```
## 命令
| 命令 | 描述 |
|---------|-------------|
| `parse` | 解析 SysML v2 源文件 |
| `validate` | 检查 SysML v2 源文件错误 |
| `index` | 从文件构建知识图谱 |
| `search` | 搜索知识图谱 |
| `inspect` | 精确名称元素查找，附带完整上下文 |
| `trace` | 跟踪元素的关联 |
| `check` | 运行结构和元模型完整性检查 |
| `query` | 基于谓词的关联搜索 |
| `render` | 基于模板的报告（追溯性矩阵、需求表、完整性） |
| `stat` | 模型健康仪表盘 |
| `plan` | 将问题分解为可执行的命令行命令 |
| `diff` | 比较两个知识图谱索引 |
| `scaffold` | 生成 SysML v2 框架文本 |
| `skill` | 生成代理技能文件 |
所有命令输出 JSON 到标准输出。使用 `--format pretty` 获取缩进输出。
## 架构
```
tree-sitter-sysml（语法，git 依赖）
|
nomograph-core （通用特征：图、索引、解析器、评分器、词汇表）
|
sysml-core （SysML v2 领域：遍历器、图、词汇表、渲染、元模型）
|
sysml-cli （命令行：clap | MCP：rmcp，特性门控）
```
领域逻辑位于 `sysml-core`。命令行和 MCP 是薄的传输包装器，委托给相同的函数。
## GitLab CI/CD 集成
SysML 在 `ci/` 中提供 CI 模板，用于模型验证门控和合并请求差异。
### 模型验证门控
添加到您的 `.gitlab-ci.yml` 中：
```yaml
include:
- local: ci/nomograph-sysml.gitlab-ci.yml
variables:
NOMOGRAPH_MODEL_DIR: "model/"
NOMOGRAPH_FAIL_ON_FINDINGS: "true"
```
这在 `.sysml` 文件更改时运行两个作业：
- **sysml-validate**：检查所有 `.sysml` 文件的语法错误（如果有则失败管道）
- **sysml-check**：索引模型，运行所有完整性检查，生成健康徽章
### 合并请求模型差异
```yaml
include:
- local: ci/nomograph-mr-diff.gitlab-ci.yml
```
在合并请求管道中运行，当 `.sysml` 文件更改时。比较基准分支模型与头部分支模型，并生成 `model-diff.json` 工件。
### 健康徽章
```bash
sysml stat --badge > model-health.svg
```
生成一个 shields.io 样式的 SVG 徽章，显示完整性百分比和元素/关联计数。颜色：绿色（100%），黄色（>=80%），橙色（>=50%），红色（<50%）。
## 开发
```bash
cargo build --workspace
cargo test --workspace
cargo clippy --workspace # 必须干净
cargo fmt --all
```
参见 [PRD.md](PRD.md) 获取完整的规格和阶段历史。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取语法同步过程和覆盖测试文档。
## 许可证
MIT -- 参见 [LICENSE](LICENSE)
## 引用
```bibtex
@software{dunn2026sysml,
author = {Dunn, Andrew},
title = {nomograph-sysml: {CLI}-native 知识图谱工具包，用于 {SysML} v2},
year = {2026},
url = {https://gitlab.com/nomograph/sysml},
note = {Nomograph Labs}
}
```
---
[Nomograph Labs](https://nomograph.ai) 的一部分。
