# 枢途

**Repository Path**: wangfeng233/shutu

## Basic Information

- **Project Name**: 枢途
- **Description**: 让 AI 用自然语言“写”西门子 PLC 程序：基于 TIA Portal Openness 的 MCP 服务端（约 265 个工具）+ 一套现代化 WPF 上位机/HMI 框架。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 6
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 枢途 — TIA Portal 自动化生成台（MCP + WPF）

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于 TIA Portal Openness API 的博途程序自动生成工具。提供两大部分：

1. **MCP 服务器 `TiaOpennessMcp`**（.NET Framework 4.8）：封装 Openness，对外暴露 **276 个**工具，既供外部 AI 客户端调用，也由 WPF 操作台在本地拉起与托管。支持两种传输：
   - **stdio**（JSON-RPC 2.0，旧行为，供 AI 客户端直接拉起）；
   - **HTTP/SSE**（加 `--url <地址>` 启动，例如 `http://localhost:5180`）—— 经 `GET /sse` 建立事件流、`POST /messages` 收发请求，WPF 与任意 AI 客户端都可用“访问地址”连接。
2. **WPF 主机 `TiaOpennessWpf`**（.NET 10 / Windows）：使用与 `PlcHmi.Framework.UI` 一致的 Fluent 风格界面，既作为“人工操作台”驱动 MCP 服务器，也内嵌并管理该服务器（可配置其访问地址）。

## MCP 服务器就在 WPF 项目中

`TiaOpennessMcp`（net48）是 Openness 的必然宿主（Openness 为 .NET Framework 程序集，无法直接加载进 net10 进程），因此它与 WPF 分离编译，但：

- 它作为**同一解决方案**中的项目存在；
- 生成时自动复制进 WPF 输出目录的 `Server\` 子目录，与 WPF 一同分发；
- 由 WPF **按需拉起、配置访问地址、连接**（HTTP/SSE）；
- 在“设置”页可自由填写访问地址（如 `http://localhost:5180`）并选择传输方式。

> 如果你希望把服务器源码物理上移入 `TiaOpennessWpf\` 目录，告诉我即可调整项目结构。

## 解决方案

`TiaOpenness.slnx` 包含以下可构建项目：

| 项目 | 目标框架 | 作用 |
|------|----------|------|
| `TiaOpennessMcp` | net48 | Openness MCP 服务器（支持 stdio 与 HTTP/SSE；由 WPF 启动与配置） |
| `TiaOpennessWpf` | net10.0-windows | WPF 操作台（含 `PlcHmi.Framework.UI` 同款主题资源 + 梯形图渲染器） |

> 工作区中还附带了 `PlcHmi.Framework` / `PlcHmi.Framework.UI` 源码：`PlcHmi.Framework.UI` 是 WPF 真实依赖的共享 UI 库（提供统一色板/样式/主题管理器与通用控件，见 `TiaOpennessWpf.csproj` 的 `<ProjectReference>`）；`PlcHmi.Framework` / `PlcHmi.Net`（PLC 通信库）由 `PlcHmi.Framework.UI` 间接依赖。命名沿用来源项目。

## 系统要求

### 最终用户（运行安装包）

| 项 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11 **专业版/企业版/教育版**（家庭版不支持 Openness） |
| .NET 运行时 | **无需另装**——安装包已自包含 .NET 10 Desktop Runtime；仅需 Win10 1809+ 自带的 .NET Framework 4.8 |
| TIA Portal | V16 ~ V21（编译基线 V16，V15 及更早不在支持范围——低版本 Openness 程序集缺少所引用的类型，运行时会崩溃），安装时勾选 **TIA Portal Openness** 组件（V21 内核随安装包按需附带——构建机装有 V21 SDK 时自动打入 `TiaOpennessMcpV21.exe`，并支持 SD 文本通道） |
| 用户权限 | 当前 Windows 用户需加入本地组 **Siemens TIA Openness**（应用内「设置 → 运行环境」可一键修复，需管理员权限） |
| 磁盘空间 | %TEMP% 必须可写（自包含单文件首次启动时会解压原生库到 `%TEMP%\.net\`，约几 MB） |

## 快速开始（安装包用户）

1. **下载**：到 [Gitee Releases](https://gitee.com/zmx371525/shutu/releases) 下载最新版 `枢途_x.x.x_安装程序.exe`。
2. **安装**：双击运行。若 Windows 弹出 **SmartScreen** 蓝色提示"已保护你的电脑"（因安装包未做代码签名），点击 `更多信息` → `仍要运行`。
3. **首次启动**：安装完成会自动打开枢途，默认落在「变量表」页。
4. **启动 MCP 服务**：在窗口**右下角状态栏**找到「MCP 服务」区域，点击展开弹窗 → 点「启动 / 停止」开启服务（首次启动会提示加入 Siemens TIA Openness 用户组，可在「设置 → 运行环境」一键修复，需管理员权限）。
5. **连接 TIA Portal**：到「连接 / 项目」页，按引导三步走（启动 MCP → 打开项目 → 选 PLC）。
6. **开始使用**：在程序开发页（变量表、程序块、硬件等）操作 TIA Portal；到「AI 客户端配置」页查看如何让外部 AI 通过 MCP 自动驱动 TIA，或直接使用内置「AI 助手」面板（配好 API 密钥即可开工）。

> 💡 遇到问题：关于页有崩溃日志 / 数据目录入口；反馈可通过邮箱 `zmx371525@outlook.com` 或 Gitee Issue。

### 开发者（构建源码）

- 上述全部 + .NET 10 SDK + .NET Framework 4.8 Developer Pack
- 已安装的 TIA Portal（Openness 目录通过环境变量 `OPENNESS_SDK_DIR` 或 `Directory.Build.props.local` 指向，默认 V18）

## 构建

需要：Windows + .NET 10 SDK + .NET Framework 4.8 targeting pack + 已安装的 TIA Portal V18（Openness 目录为 `C:\Program Files\Siemens\Automation\Portal V18\PublicAPI\V18`）。

```powershell
dotnet build TiaOpenness.slnx -c Release
```

生成产物：

- `TiaOpennessWpf\bin\Release\net10.0-windows\TiaOpennessWpf.exe` —— WPF 操作台
- `TiaOpennessWpf\bin\Release\net10.0-windows\Server\TiaOpennessMcp.exe` —— 自动复制进来的 MCP 服务器及其 Openness 依赖

> 构建时会出现 `NU1702` 警告：WPF（net10）引用了 net48 的 `TiaOpennessMcp` 项目，这是预期的（MCP 服务器本就需要在 net48 上运行以加载 Openness）。只要最终提示 `0 个错误` 即为成功。

### 生成器测试（无需 TIA Portal）

LAD/SD 生成器（`LadXmlBuilder` / `SdBuilder` 及其配方表）的纯生成逻辑由 `tests\TiaOpennessMcp.Generators.Tests` 以 **golden-file 模式**守护：测试项目用 `<Compile Include="..\..\TiaOpennessMcp\..." Link="..." />` 链接编译生成器源码（不 ProjectReference，不引用 Siemens.Engineering.dll），**未安装 TIA Portal / Openness SDK 的机器（含 CI）也能跑**：

```powershell
dotnet test tests\TiaOpennessMcp.Generators.Tests\TiaOpennessMcp.Generators.Tests.csproj
```

- **XML 通道**（9 例）：起保停、TON/CTU、MOVE、比较+并联 OR、P 边沿、SR 盒、FB 调用带背景 DB、PID_Compact → 与 `tests\Golden\*.xml` 逐字符比对；**SD 通道**（7 例）：与 `tests\GoldenSd\*.sd` 比对，并联支路断言 `wire#w` 合流点与 `END_RUNG wire#w`，嵌套并联断言“无实机样本”告警；另有查表/归一化纯函数断言（23 例）、异步指令 REQ 自动改接（4 例）、库指令实例 scope 预检（4 例）、**SD 通道对齐与加固（33 例，v1.5.0：线圈别名 S/R/P/N、VAR_CONSTANT、EQ_Type 大小写、in3 缺失、条件调用 REQ 表达式、Wire 转义、段名归一）**——全量 90 例。
- 期望文件不存在时首次运行自动写入基线；之后严格比对（行尾与 `<Created>` 时间戳归一）。生成器行为有意变更时，设 `GOLDEN_UPDATE=1` 重跑（或删除对应 golden 文件）刷新基线并随提交入库。
- CI：`.github\workflows\ci.yml`（GitHub Actions）与 `.workflow\ci.yml`（Gitee Go，命令等效）在 push/PR 时仅运行此测试项目（windows-latest 自带 net48 targeting pack，另装 .NET SDK 10）——不构建全解决方案，因其依赖本机 Openness DLL 路径。

## 运行（WPF 操作台）

直接运行 `TiaOpennessWpf.exe`。界面左侧为导航，右侧为对应功能页：

- **连接 / 项目**：打开/新建项目、连接运行中的 TIA Portal 实例、列出并选择 PLC、按 MLFB 订货号添加 PLC CPU（或在「硬件目录」页按 TypeIdentifier 添加）；超时/脏会话后可「恢复会话」一键重连。
- **硬件目录**：按关键字搜索 TIA 硬件目录（返回 TypeIdentifier 与订货号），复制到项目、删除设备、向机架插入模块、创建/列出子网、设置接口主/从站模式。
- **数据类型 (UDT)**：用完整 SCL `TYPE` 源码创建用户数据类型，并支持列出/删除。
- **PLC 变量**：创建变量表，表格化批量录入变量（名称/类型/地址/初始值/注释）并创建；也支持 PLC 常量、删除变量表。
- **程序块**：创建 FB/FC/OB（贴入完整 SCL 源码）或全局 DB（成员表格）；也支持 LAD 梯形图块、自定义 Openness(SimaticML) XML 导入、删除块、块组创建/删除/列出、批量导出全部块、从文件导入块。
- **程序生成**：把多张变量表、多个程序块（FB/FC/OB/DB/导入 XML）组织成一个**离线工程**，保存为 `.tiaopen.json` 文件；连接 TIA Portal 后一键按序生成全部内容（适合批量搭建可复用的标准程序模板）。
- **代码预览 / 梯形图**：列出当前 PLC 程序块，导出并预览其源码；SCL 块显示 SCL 源码，LAD/FBD 块在下方**渲染成梯形图**（左母线 + 触点/线圈/方框 + 连线，含并行分支）。
- **编译 / 保存**：编译整个软件或指定块，保存项目，关闭并断开。
- **下载与在线**：获取 PLC 在线状态、下载/上传程序、比较离线在线差异。
- **交叉引用**：分析整个 PLC 软件（或指定块）的对象引用关系——谁引用了某变量/块、在哪里引用（需项目已编译，手册 5.11.2.8）。
- **工艺对象**：列出/创建运动控制等工艺对象，并为已有对象设置参数（手册 5.11.4）。
- **HMI 画面**：列出/导出 HMI（WinCC）画面，并可创建空白画面与画面文件夹（更深入的 HMI 编辑）。
- **协作与集成**：UMAC 用户权限、多用户项目、版本控制接口（VCI，含导出/导入同步）、OPC UA 配置、SiVArc 画面自动生成。
- **高级功能中心**：卡片式集中入口，二级功能以弹窗打开——HMI 管理 (WinCC)、库/主副本、协作与集成、导入导出中心，以及「指令配方采集」（调 `tia_harvest_lad_pins` 采集当前项目 LAD 指令管脚配方 TSV，可保存为文件供指令生成器使用）。
- **AI 助手**：常驻侧边面板的内置 Agent 循环，可驱动全部 MCP 工具自动完成多步工程任务（如“建变量表 → 建 FB → 编译 → 按报错自修”闭环）；支持 OpenAI/Anthropic 两种方言接入各家模型（GLM/Kimi/Claude 等，密钥经 DPAPI 加密仅存本机）、思考模式（自动/快速/深度）与上下文压缩设置、工具调用进度显示与会话存档续聊。
- **设置**：配置 MCP 服务器的**访问地址**与传输方式（HTTP/SSE 或 stdio），可选“本机自动启动”；修改后点“应用并连接”。另有：**危险操作前自动快照**（默认开）、**Git 提交后自动 VCI 导出**（默认关）、**语言**（zh-CN / en-US，重启后完全生效）。
- **运行日志**：实时显示操作日志与服务器日志（`Server\TiaOpennessMcp.log`）。

顶部“🌓 切换主题”可在浅色/深色间切换（偏好保存在 `%LOCALAPPDATA%\TiaOpennessWpf`）。

### 前置权限

当前 Windows 用户需加入本地组 **Siemens TIA Openness**（控制面板 → 计算机管理 → 本地用户和组 → 组），否则 Openness 无法启动 TIA Portal。若未加入，可在 WPF 状态栏左侧点“运行环境”弹窗中的“修复用户组”（需管理员权限）。

## 作为 MCP 服务器对接 AI

`TiaOpennessMcp` 两种接线方式：

- **stdio（AI 直接拉起）**：配置示例见 `mcp-config-example.json`：
  ```json
  { "mcpServers": { "tia-openness": { "command": "C:\\path\\to\\TiaOpennessMcp.exe" } } }
  ```
- **HTTP/SSE（可远程/被 WPF 统一托管）**：用 `--url` 启动后，AI 客户端通过 SSE 连接：
  ```json
  { "mcpServers": { "tia-openness": { "url": "http://localhost:5180/sse" } } }
  ```
  > 服务器基于 `TcpListener` 实现（不经 http.sys），普通用户权限即可监听 `localhost`，无需 `netsh http add urlacl`。

### 工具清单（共 276 个）

**一、项目与设备**
`tia_open_project` / `tia_create_project` / `tia_attach` / `tia_list_devices` / `tia_refresh_devices` / `tia_add_plc` / `tia_delete_device` / `tia_search_hardware` / `tia_add_device` / `tia_select_plc`

**二、PLC 变量与块（核心）**
`tia_create_tag_table` / `tia_delete_tag_table` / `tia_create_tag` / `tia_create_plc_constant` / `tia_create_data_block` / `tia_create_function_block` / `tia_create_function` / `tia_create_organization_block` / `tia_create_lad_block` / `tia_create_udt` / `tia_list_udts` / `tia_delete_udt` / `tia_delete_block` / `tia_create_block_group` / `tia_delete_block_group` / `tia_list_block_groups` / `tia_search_lad_recipe`（查 LAD 指令配方真值，生成 LAD 前先查表） / `tia_harvest_lad_pins`（从当前项目采集 LAD 指令管脚真值）

**三、导入 / 导出 / 编译**
`tia_import_block_xml` / `tia_import_block_from_file` / `tia_list_blocks` / `tia_export_block` / `tia_export_block_to_file` / `tia_export_all_blocks` / `tia_compile` / `tia_export_sd` / `tia_import_sd` / `tia_create_block_sd` / `tia_create_lad_block_sd`（SD 文本通道，仅 V21 内核，人类可读、Git 友好，详见 `docs/sd-channel-guide.md`）

**四、下载与在线**
`tia_download` / `tia_upload` / `tia_online_state` / `tia_compare_online` / `tia_cross_references`

**五、硬件与网络**
`tia_plug_module` / `tia_create_subnet` / `tia_list_subnets` / `tia_set_interface_mode`

**六、库 / 主副本**
`tia_open_library` / `tia_close_library` / `tia_list_master_copies` / `tia_create_from_master_copy`

**七、块保护 / 校验和**
`tia_protect_block` / `tia_unprotect_block` / `tia_get_checksum`

**八、工艺对象 / Motion Control**
`tia_list_technology_objects` / `tia_create_technology_object` / `tia_set_technology_parameter`

**九、HMI 画面**
`tia_list_hmi_screens` / `tia_export_hmi_screen` / `tia_create_hmi_screen`（创建空白画面） / `tia_create_hmi_folder`（创建画面文件夹）

**十、UMAC / VCI / 多用户**
`tia_list_umac` / `tia_list_vci_workspaces` / `tia_vci_sync`（与版本控制系统同步：导出/导入） / `tia_list_multiuser_projects`

**十一、OPC UA / SiVArc（探测式）**
`tia_get_opcua_config` / `tia_get_sivarc_info`

**十二、会话**
`tia_save` / `tia_close`

## 说明

- **autoVerify 自动校验（默认关闭）**：9 个创建/导入类工具（`tia_create_data_block` / `tia_create_function_block` / `tia_create_function` / `tia_create_organization_block` / `tia_create_lad_block` / `tia_create_lad_block_sd` / `tia_create_udt` / `tia_import_block_xml` / `tia_create_block_sd`）默认 `autoVerify=false`——仅生成不校验，批量生成时先建完所有块再统一 `tia_compile` 一次（逐块即编即校验单次约 10~60 秒，大批量下反而更慢）；需单块即时校验时显式传 `autoVerify=true`，创建/导入成功后服务器立即自动编译该块并返回**结构化错误**（错误位置/对象/原因，紧凑格式），AI 可按错误直接修正参数重新生成。`tia_compile` 仍用于全项目编译与下载前总校验。
- **progress 进度通知**：stdio 与 HTTP/SSE 两种传输均支持——客户端在请求 `params._meta.progressToken` 携带进度令牌（opt-in）时，工具执行期间经 stdout / SSE 事件流推送 `notifications/progress`；未传令牌不推送，行为与旧版一致。
- **代码预览 / 梯形图**：`tia_export_block` 通过 Openness 把块导出为 XML 并回传。SCL 块抽取 `<SclSource>` 显示源码；LAD/FBD 块解析 `<NetworkSource>/<FlgNet>` 的 `Parts` 与 `Wires`，由 `LadderRenderer` 做分层布局后画成梯形图。该梯形图为“尽力而为”的预览渲染，复杂嵌套分支的视觉精度可能有限。
- **SCL 逻辑**：服务器将你提供的完整 SCL 源码写入 `.scl` 外部源，再经 `GenerateBlocksFromSource` 编译为块（接口由 `FUNCTION_BLOCK`/`FUNCTION`/`ORGANIZATION_BLOCK` 里的 `VAR` 段自动推导），对 V16+ 通用。UDT 同样走外部源路径（`TYPE ... END_TYPE`）。若你的版本对结构有特殊要求，可用 `tia_import_block_xml` 直接传 XML（已作为兜底工具）。
- **LAD 块**：`tia_create_lad_block` 按官方手册 FlgNet v4 架构，由“网络数组”描述逻辑（每网络是一串从左母线向右串联的元件：contact/coil/move/box/call，以及 parallel 并联支路），生成 SimaticML 后导入。
- **添加 PLC** 的 `mlfb` 需按实际硬件/固件版本填写（示例 `OrderNumber:6ES7 511-1AK02-0AB0/V2.9` 仅供参考）；也可在「硬件目录」页搜索后直接按 `TypeIdentifier` 添加，更不易出错。
- **交叉引用** 依赖项目已编译（先 `tia_compile`），未编译时可能返回空。
- 服务器日志写到其目录下的 `TiaOpennessMcp.log`，排错时查看。
- **切换 TIA Portal 版本**：Openness V16~V20 均基于 .NET Framework 4.x，`TiaOpennessMcp` 始终用 net48，**无需改 TargetFramework**。只需在 `Directory.Build.props.local`（已 gitignore）或环境变量 `OPENNESS_SDK_DIR` 指向目标版本的 `PublicAPI\VV` 目录即可（见 `Directory.Build.props` 的三级回退说明）。