# sysml

**Repository Path**: zcmmmm/sysml

## Basic Information

- **Project Name**: sysml
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-09
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NLP → SysML 模型生成智能体

根据自然语言描述自动生成 SysML 模型（.mdzip），并在 MagicDraw 中可直接打开、继续编辑。

## 整体架构

```
自然语言描述
    │
    ▼
[agent/nl2sysml.py]  Python 智能体
    │  调用 LLM（OpenAI 兼容接口），把自然语言转成结构化 JSON 规格
    ▼
spec.json（中间产物，可人工审查/修改）
    │
    ▼
[mdplugin]  Java 建模插件（通过 MagicDraw 命令行环境运行）
    │  读 JSON → 建包/块/需求/用例/关系/活动/状态机/图
    ▼
output/项目名.mdzip   ← MagicDraw 打开
```

## 环境要求

- MagicDraw 2022x（含 SysML 插件），默认安装路径 `F:\software\magicDraw2022`
- 有效的 MagicDraw 许可证（命令行运行同样需要）
- Python 3.9+（仅用标准库，无第三方依赖）
- 调用 LLM 需要 API Key；也可以跳过 LLM 直接提供规格 JSON

## 快速开始

### 1. 构建 Java 插件（只需一次）

在 PowerShell 中运行：

```powershell
powershell -ExecutionPolicy Bypass -File mdplugin\build.ps1
```

成功后会生成 `plugins\nlp2sysml\`（插件目录，含 jar 和 plugin.xml）。

### 2. 用示例规格做一次端到端验证（不需要 API Key）

```powershell
powershell -ExecutionPolicy Bypass -File scripts\run_build.ps1 `
  -Spec examples\coffee_machine_spec.json `
  -Out output\咖啡机系统.mdzip
```

也可以在项目根目录运行 Python 入口：

```bash
python agent/nl2sysml.py --spec examples/coffee_machine_spec.json
```

构建完成后用 MagicDraw 打开 `output\咖啡机系统.mdzip`，可以看到结构（块定义图）、需求图、用例图、活动图、状态机图。

### 3. 用自然语言生成模型

先设置环境变量：

```powershell
$env:OPENAI_API_KEY = "sk-..."
# 可选：
$env:OPENAI_BASE_URL = "https://api.openai.com/v1"   # 兼容接口（DeepSeek/Ollama 等也可）
$env:OPENAI_MODEL    = "gpt-4o-mini"
```

然后：

```bash
# 直接传文本
python agent/nl2sysml.py "设计一个无人机物流系统：包括无人机、地面站、充电站……"

# 从文件读
python agent/nl2sysml.py --file examples/coffee_machine.txt

# 管道输入
type my_system.txt | python agent/nl2sysml.py
```

生成过程：

1. 智能体调用 LLM，把自然语言整理为结构化规格 `output/<项目名>_spec.json`；
2. 自动校验规格（元素引用完整性）；
3. 调用 MagicDraw 命令行环境构建模型，保存为 `output/<项目名>.mdzip`。

`_spec.json` 是中间产物，你可以直接编辑它，然后加 `--spec` 重新构建，方便人工修正。

## Web 前端（聊天式交互）

项目自带一个零依赖的 Web 服务，可以在浏览器里用“提问-回答”的方式生成和迭代模型。

启动：

```powershell
powershell -ExecutionPolicy Bypass -File start_web.ps1
```

（或双击 `start_web.bat`）。服务启动后会自动打开 `http://127.0.0.1:7860`。

用法：

- 在聊天框输入系统描述，点击“发送”或按 `Ctrl+Enter`；
- 右上角“⚙ 设置”里填写 API Key / 接口地址 / 模型名（不填则用服务器环境变量）；
- 生成过程中实时显示“调用模型 → 校验规格 → 构建模型”的进度和日志；
- 完成后可下载 `.mdzip`、查看规格 JSON；
- 支持追问式修改：直接说“给咖啡机加一个温度传感器并补充对应需求”，会基于上一版规格继续生成；
- 没有 API Key 时，可点“示例规格演示（无需 API Key）”直接体验完整构建流程。

服务参数：

```powershell
python webapp\server.py --port 7860 --md-home F:\software\magicDraw2022
```

环境变量也可用：`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`、`MD_HOME`、`NLP2SYSML_PORT`。

### 模型接口配置

项目根目录的 `config.json` 保存默认模型配置（模型名、接口地址、API Key），Web 服务启动时会自动读取；
前端“⚙ 设置”里填写的值优先于配置文件；都没有时才用环境变量。

```json
{
  "model": "deepseek-chat",
  "base_url": "https://api.deepseek.com/v1",
  "api_key": "sk-..."
}
```

注意：请勿把含真实 Key 的 `config.json` 分享给他人或提交到公开仓库。

## 支持建模的内容

| 类别 | 说明 |
| --- | --- |
| 包 | 结构/需求/行为/用例等包 |
| 块 | SysML `«block»`，含值属性、部件属性、引用属性、端口、操作、约束 |
| 值类型 | `«valueType»`，可带 `«unit»` |
| 需求 | `«requirement»`，自动设置 Id/Text |
| 参与者/用例 | Actor 与 Use Case，自动建立关联 |
| 关系 | 组合、聚合、关联、泛化、依赖、`«satisfy»`、`«deriveReqt»`、`«trace»`、`«refine»`、`«verify»`、`«allocate»` |
| 行为 | 活动图（动作+控制流）、状态机（状态+转移+触发） |
| 图 | 块定义图(BDD)、需求图、用例图、活动图、状态机图（支持 ibd/parametric/package/sequence 类型） |

说明：块之间的组合/聚合会生成真实的 SysML 关联；涉及参与者、用例等非块元素的“关联”在无界面
模式下会被 MagicDraw 的模型完整性检查丢弃，因此自动降级为 UML 依赖关系（同样可以追溯），
如需标准连线可在 MagicDraw 中手动转换。

## 常见问题

- **提示找不到插件**：先运行 `mdplugin\build.ps1`，确认 `plugins\nlp2sysml\nlp2sysml.jar` 存在。
- **许可证错误**：MagicDraw 命令行运行需要有效许可证；请先在图形界面确认可以正常启动。
- **LLM 输出格式错误**：智能体会自动重试解析；若仍失败，请检查 API Key/网络，或改用 `--spec` 手动提供规格。
- **图布局不理想**：无界面模式下自动布局可能不生效，打开模型后在图中按 `Ctrl+Shift+A`（Arrange All）重新排布即可。
- **元素名不唯一**：关系/图中引用元素时尽量用 `包名::元素名` 完整路径；简单名只在唯一时有效。
- **控制台中文乱码**：脚本已自动以 UTF-8 输出；若在旧版终端中仍乱码，可先执行 `chcp 65001`。

## 项目结构

```
agent/               Python 智能体（LLM 调用、规格解析与校验、CLI）
mdplugin/            Java 建模插件源码 + build.ps1
plugins/nlp2sysml/   构建产物（jar + plugin.xml），运行时加载
scripts/             MagicDraw 命令行构建脚本（run_build.ps1 / .bat）
webapp/              Web 服务（server.py + 前端聊天界面 static/）
examples/            示例自然语言描述与示例规格
output/              生成的 mdzip 与中间规格
config.json          默认模型/接口/API Key 配置
start_web.ps1/.bat   Web 服务一键启动脚本
```