内容
<div align="center">
# SysML v2 Studio
**在 VS Code 中编写、查看和编辑 SysML v2 (`.sysml` / `.kerml`)**
[](https://marketplace.visualstudio.com/items?itemName=engineer-fumi.sysml-v2-studio)
[](https://marketplace.visualstudio.com/items?itemName=engineer-fumi.sysml-v2-studio)
[](https://www.npmjs.com/package/@engineer-fumi/sysml-v2-mcp)
[](LICENSE)
**中文** · [日本語](README.ja.md) · [简体中文](README.zh-Hans.md)
一个具有完整语言支持的 SysML v2 扩展（高亮、诊断、补全、跳转到定义）以及 **8 种可编辑的图表** 和 **Claude (MCP) 集成**。
</div>
## 功能特点
- 🎨 **8 种图表类型** — 概览 / 模块定义 (BDD) / 内部模块 (IBD) / 需求 / 用例 / 状态 / 活动 / 序列
- ✏️ **直接在图表中编辑** — 移动、调整大小、连接、重命名和删除，所有更改 **自动写入文本** （手动布局保存到侧边栏）
- 🔎 **语言支持** — 语法高亮、实时诊断（语法 + 语义）、补全、大纲、跨文件跳转到定义和悬停提示
- 🔗 **双向同步** — 点击图表元素 ⇄ 跳转到源代码，编辑器光标位置 ⇄ 高亮显示在图表中
- 🤖 **Claude (MCP) 集成** — 分析、验证和查询模型 **作为结构** （Claude 代码 / 桌面版 / VS Code AI）
- 📦 **多文件 / 远程就绪** （Remote-SSH / WSL / Dev Containers），📚 **捆绑的标准库** + **官方 OMG 示例**
## 安装
在 VS Code 市场中搜索 **“SysML v2 Studio”** 并安装，或：
```bash
code --install-extension engineer-fumi.sysml-v2-studio
```
> 需要 VS Code **1.101 或更高版本**。要从源代码构建 `.vsix`，请参阅 [开发指南](docs/development.md)。
## 快速入门 — 预览图表
1. **打开 `.sysml` / `.kerml` 文件** （捆绑的 `samples/` 是最简单的开始）
2. 点击编辑器右上角的 **图表图标**，或从命令面板运行 **“SysML: 打开图表”**
→ 图表在编辑器旁边预览
3. 通过面板顶部的选择器在 8 种图表类型之间切换，或 **“SysML: 按类型打开图表”**
4. **拖动** 框以布局，**右键** 连接 / 更改线条样式 / 删除
→ 更改 **自动写入源代码** （布局保存到 `.sysml-layout.json`）
在图表中点击元素跳转到匹配的源代码行；编辑器光标位置在图表中高亮显示。
## Claude (MCP) 集成
扩展程序捆绑了一个 **独立的 MCP 服务器**，使 Claude 等 AI 能够将您的 `.sysml` 模型 **视为结构而非文本** — 暴露出用于解析、验证、需求列表和图表结构的工具。
**根据您使用的客户端，请执行以下两项操作之一。**
### ① 使用 VS Code 的 AI（Copilot / 代理）→ 无需配置
如果您已在 VS Code **1.101 或更高版本** 上安装了此扩展程序，则 **无需执行任何操作**。扩展程序会自动注册 MCP 服务器。打开 **“MCP: 列出服务器”** 从命令面板 — 如果 **“SysML v2 Studio”** 已列出，则它处于活动状态。
### ② 使用 Claude Code / Claude 桌面版 → 一行命令注册
对于 **Claude Code** （一个与 VS Code 分别的客户端），在项目根目录运行此命令（`npx`，因此无需事先安装）：
```bash
claude mcp add sysml -- npx -y @engineer-fumi/sysml-v2-mcp "$(pwd)"
```
对于 **Claude 桌面版**，将以下内容添加到配置文件中：
```jsonc
{ "mcpServers": { "sysml": {
"command": "npx",
"args": ["-y", "@engineer-fumi/sysml-v2-mcp", "<绝对路径到您的模型文件夹>"]
} } }
```
提供的工具：`list_files` / `outline` / `validate` / `find_element` / `list_requirements` / `describe_diagram`。有关注册变体（显式路径、自行构建）、工具详细信息和用法示例，请参阅 [Claude (MCP) 集成指南](docs/mcp.md)。
## 表示法 ↔ 图表
根据您选择的图表类型，相同的文本模型会呈现不同的结果。下面是 **每种图表类型及其实际渲染结果的最小示例** （上面的英雄概览图也是以相同方式生成的）。
### 模块定义图表（BDD）— 结构、组成、定义的专业化
```sysml
package Powertrain {
part def Vehicle;
part def Engine;
part def Cylinder;
part v : Vehicle { part engine : Engine; }
part e : Engine { part cylinders : Cylinder[4]; }
}
```
### 内部模块图表（IBD）— 部件内部的连接（端口 / 连接）
```sysml
package Hydraulics {
port def FluidPort;
part def Pump { port outlet : FluidPort; }
part def Tank { port inlet : FluidPort; }
part system {
part pump : Pump;
part tank : Tank;
connect pump.outlet to tank.inlet;
}
}
```
### 需求图表 — 需求和满足关系
```sysml
package Requirements {
requirement def MassLimit {
doc /* 車両総質量は 1500 kg 以下であること */ // "Total vehicle mass shall be at most 1500 kg"
attribute limit : Real = 1500.0;
}
requirement massReq : MassLimit;
part vehicle;
satisfy massReq by vehicle;
}
```
### 用例图表 — 带有执行者和执行的用例
```sysml
package Robot {
part def Operator;
use case def Operate { subject robot : Robot; actor operator : Operator; }
use case def Maintain { subject robot : Robot; actor operator : Operator; }
use case operate : Operate;
part operator : Operator { perform operate; }
}
```
### 状态转换图表 — 状态和转换（带有触发器）
```sysml
package Machine {
state def BrewCycle {
state off;
state idle;
state heating;
state brewing;
transition first off accept powerOn then idle;
transition first idle accept startCmd then heating;
transition first heating accept ready then brewing;
}
}
```
### 活动图表 — 带有连续 / 项目流的动作
```sysml
package Process {
item def Order;
action def Fulfill {
action validate;
action ship;
first validate then ship;
flow of Order from validate to ship;
}
}
```
> 有关图表类型、编辑操作和布局持久性的详细信息，请参阅 [图表功能指南](docs/diagrams.md)。
## SysML v2 一致性
此扩展程序实现了 OMG SysML v2 文本表示法的 **实用子集** （基于代码审计的概述；有关详细信息和证据，请参阅 [一致性矩阵](docs/conformance.md)）。
| 语言区域 | 级别 |
|---|---|
| 定义和用法（部分 / 项目 / 属性 / 端口 / 动作 / 状态 …） | **完整** |
| 专业化（`:` / `:>>` / `specializes` / `subsets` / `redefines`） | **完整** |
| 连接 / 接口 / 绑定 / 流 | **完整** （结构） |
| 需求 / 约束 / 满足・验证 | **完整** （结构）/ 表达式不透明 |
| 用例 / 执行者 / 包含・执行 | **完整** |
| 元数据 / 注解（`@`，`#`，`metadata def`） | **完整** （解析） |
| 注释 / 文档（`//`，`/* */`，`doc`，`comment`） | **完整** |
| 状态和转换 / 动作 / 计算 | **部分** （触发器 / 保护 / 效果和控制流不透明） |
| 视图 / 视角 / 渲染 | **部分** （渲染未实现） |
| 导入 / 别名 / 可见性 | **部分** （私有 / 受保护不强制执行） |
| 表达式（约束 / 计算主体和值） | **仅解析** （不透明文本，无类型检查） |
| 标准库 | **最小子集捆绑** （不是完整的 OMG 库） |
| KerML 基础层（分类器 / 特征 / 函数 …） | **仅解析** |
> 级别定义（完整 / 部分 / 仅解析 / 无）和每个区域的证据在 [一致性矩阵](docs/conformance.md) 中有详细记录。
## 文档
- [图表功能](docs/diagrams.md) — 图表类型、编辑、布局持久性
- [支持的表示法和限制](docs/syntax.md) — 支持的 SysML v2 子集
- [一致性矩阵](docs/conformance.md) — 详细的语言区域 × 级别表格
- [Claude (MCP) 集成指南](docs/mcp.md) — MCP 服务器注册、工具、用法
- [开发指南](docs/development.md) — 架构、构建、测试、发布
> 目前文档页面以日语编写。
## 许可证
[MIT](LICENSE)。官方 OMG 示例在 `samples/omg/` 下遵循 EPL-2.0 （[详情](samples/omg/README.md)）。捆绑的第三方组件（React 等）列在 [THIRD-PARTY-NOTICES.txt](THIRD-PARTY-NOTICES.txt) 中。
