# TIA Portal Openness 工具 —— 使用说明与介绍（v2.0）

## 一、这是什么

一个驱动西门子 **TIA Portal（博途）** 做自动化工程的工具：连接博途、建项目、加硬件（PLC / WinCC Unified HMI）、生成 PLC 程序（UDT / 全局 DB / 标签表 / SCL / 梯形图）、生成 HMI 画面与变量、编译诊断、保存——全程可由 AI 或一条命令完成。

底层走的是西门子官方唯一公开接口 **Openness**。支持 **TIA Portal V20 与 V21**（两个对应的 exe，按你装的版本选）。

### 它还"单纯是 MCP"吗？——不是了

从 **v2.0** 起，**同一个 exe 有两种用法**，共享同一个引擎：

| 模式 | 谁来用 | 怎么触发 | 典型场景 |
|---|---|---|---|
| **MCP 服务** | 支持 MCP 的 AI 客户端（Cursor / Claude / VS Code…） | 不带子命令启动，客户端用 MCP 协议驱动 | 在 IDE 里用自然语言对话式开发、边问边改 |
| **`tia` 命令行** | 人，或**任意** AI（不要求支持 MCP） | `tia gen spec.yaml` 等子命令 | 一条命令从零建/改工程、批处理、双击 .bat、CI |

> 一句话：**MCP 适合"对话式交互"，CLI 适合"一份 spec 一条命令搞定"**。能力完全相同，因为是同一个引擎。

---

## 二、快速开始

### 方式 A：当 MCP 服务用（在 IDE 里）

在你的 MCP 客户端配置里把 `command` 指向 exe（**V21 用 `bin\Release`，V20 用 `bin-v20\Release`**）：

```json
{
  "mcpServers": {
    "tia-portal": {
      "command": "C:\\...\\tools\\tiaportal-mcp\\src\\TiaMcpServer\\bin\\Release\\net48\\TiaMcpServer.exe",
      "args": ["--tia-portal-location", "D:\\app\\TIA21\\Portal V21", "--tia-major-version", "21"],
      "env": {}
    }
  }
}
```

各客户端配置文件位置：
- **Cursor**：项目根 `.cursor/mcp.json`
- **VS Code**（Copilot / Cline 等）：工作区 `.vscode/mcp.json`
- **Claude Desktop**：`%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Code**：`claude mcp add` 或 `~/.claude.json`

配好后在对话里直接说需求即可（例：「连接博途，建一个 S7-1500 + WinCC Unified 的启停控制工程」）。

### 方式 B：当命令行用（`tia`）

1. **让 `tia` 命令可用**（一次性）：交付包根目录有 `tia.cmd`（V21）/ `tia-v20.cmd`（V20）。把交付包根目录加入系统 `PATH`，之后任意目录都能 `tia ...`。（不配也行，直接用全路径 exe 一样。）
2. **跑命令**：
   ```
   tia gen   项目.yaml                # 从 spec 建完整工程
   tia gen   项目.yaml --dry-run      # 只离线校验 spec，不连博途
   tia patch 改动.yaml                # 把 spec 增量合并进已有工程
   tia compile  D:\proj\X.ap21 --plc PLC_1
   tia describe D:\proj\X.ap21 --plc PLC_1
   tia prewarm                        # 常驻 headless 实例，后续命令 ~1s 连上
   tia schema                         # 打印 spec 所有字段说明
   ```
   退出码：**0=成功 / 1=有失败步骤 / 2=错误**；加 `--json` 输出机器可读结果。

### 方式 C：纯小白（双击）

把一个 `spec.yaml` / `spec.json` **拖到 `scripts\生成工程.bat`** 上即可建工程。想更快先双击 `scripts\预热.bat`。

---

## 三、spec 长什么样

一份 YAML（或 JSON）描述你要的工程，`tia gen` / `tia patch` 和 MCP 的 `ScaffoldProject` 都用它：

```yaml
projectName: MyLine          # 必填
plcName: PLC_1
plcFamily: S7-1500
hmiName: HMI_1               # 省略则不建 HMI
udt:
  - name: UDT_Status
    members:
      - { name: Active, datatype: Bool, commentZhCn: 运行 }
tagTable:
  - tableName: IO
    tags:
      - { name: Start, dataTypeName: Bool, logicalAddress: "%I0.0" }
sclSourceFiles:              # 带算法/表达式的 FB/FC 用 .scl 外部源
  - D:\blocks\FB_Latch.scl
hmiScreens:
  - { screenName: 主画面, width: 800, height: 480, designJson: { ... } }
compile: true
save: true
```

- 完整字段：`tia schema`
- **现成模板**：`templates/project-blueprints/`（启停、电机，均编译 0 错）——**开箱即用**，里面 `__BUNDLE__` 路径会被 `tia` 自动解析，直接 `tia gen scaffold_spec_motor.json` 即可。
- 让 AI 帮你写 spec：见 `docs/AI_spec_prompt.md`（一段通用提示词，贴给任意 AI）。

---

## 四、能建什么

- **硬件**：PLC（S7-1200 / 1500）+ 可选 WinCC Unified HMI，自动建 HMI↔PLC 连接
- **PLC 程序**：UDT、全局 DB、PLC 标签表、SCL 块（外部源）、梯形图（S7DCL 文本格式）
- **HMI**：Unified 画面（按面板原生分辨率设计）、变量、绑定与动态化
- **编译诊断 / 保存**；以及导出/导入、在线状态、报警文本、OPC UA 等更多 MCP 工具

---

## 五、常见问题

- **慢？** 第一次连接冷启动 headless 博途约 10–28s；先 `tia prewarm`（或双击预热.bat）之后约 1s。`CreateProject / AddDevice / Save` 是 Openness 固有耗时，再快不了。
- **V20 还是 V21？** 用与你博途大版本匹配的 exe（`bin\Release`=V21、`bin-v20\Release`=V20），两者不能互换。
- **要看 GUI？** 加 `--with-ui`（MCP 在 `args` 里加，CLI 加在命令后）用完整界面启动（较慢）。
- **中文乱码？** 输出已强制 UTF-8；`.scl` 文件请存 UTF-8 **BOM**。
- **工程路径能写相对的吗？** CLI 的工程路径按你当前所在目录解析，相对/绝对都行。
- **HMI 画面比例不对/被裁剪？** `width/height` 要写目标面板的原生分辨率（如 800×480 / 1280×800）。
- **`hmiTags` 校验失败？** 尽量用绝对地址（`%M..` / `%DB..`），更容易通过回读校验。

---

## 六、进一步阅读

- `docs/CLI_quickstart.md` —— `tia` 命令 5 分钟上手
- `docs/AI_spec_prompt.md` —— 让任意 AI 生成 spec 的提示词
- `tools/tiaportal-mcp/skill/SKILL.md` —— 完整能力与配方（给 AI 看的）
- `README.md` —— 交付包总览、安装前提、目录结构
