TIA Portal Openness MCP

作者原文

Drive Siemens TIA Portal V20 or V21 from any MCP client (stdio or HTTP)

原始 SKILL.md

本站暂未展示原始 SKILL.md。 查看原始来源 ↗ 文件内容、许可与使用要求以原站为准。

版本历史

1. v2.7.11 2026-11-07 GitHub 仓库发布 ↗
   原版更新说明

   ## [2.7.11] - 2026-11-07 - 服务端只读模式、软件单元的变量表与按单元导出、认出交叉引用诊断节点 工具数不变（238）。`GetPlcTags`、`ExportBlocks`、`ExportBlocksAsDocuments` 各多一个可选参数 `softwareUnit`； 新增启动参数 `--read-only`。 ### 新增 - **服务端只读模式（#67 第一阶段，感谢 @BoykaHe）**：启动时加 `--read-only`（或 `TIA_MCP_READ_ONLY=1`）， 读取、导出、连接 / 打开 / 关闭工程照常；改工程、编译、保存、下载、写在线值、反射调用和不认识的工具一律拒绝， 被拒的调用什么都不执行。直接调用、`CallTool`、HTTP 走同一张表；`closeForeignProject=true` 和默认会改 Windows 用户组的 `Doctor` 也被拒（`Doctor(fix=false)` 放行）；打开旧版本工程不做升级；导出碰到 PLC 在线时不自动断开在线， 改为报错。导出会写入（并覆盖）调用方指定的路径。这个开关只管 MCP 服务端，和 `tia` 命令行动词一起用会报错退出。 `lite` / `full` 档位只管列出哪些工具，不是写保护。 - **软件单元里的变量表和用户常量（#68，感谢 @BoykaHe）**：`GetPlcTagTables` 列出单元变量表 （`Software units/<单元>/<表>`），`ExportPlcTagTable` 按这个路径导出；`GetPlcTags` 默认读 PLC 根目录加全部单元， `softwareUnit` 只读一个单元。常量的 `value` 是原始定义文本，不求值；注释带全部项目语言。单元读不出来时 `complete=false` 并给出警告；指定了不存在的单元直接报错并列出现有单元。 - **按软件单元批量导出（#66，感谢 @BoykaHe）**：`ExportBlocks` / `ExportBlocksAsDocuments` 加 `softwareUnit`， 只导这个单元的块，不混入根目录和其他单元；`preservePath` 时放在 `Software units/<单元>/` 下。 不指定单元时 `meta.scope=plcRoot`，`excludedSoftwareUnits` 和消息里写明哪些单元没包含。 ### 修复 - **交叉引用碰到博途的诊断节点时报成「完整、0 条」（#60 补充，感谢 @BoykaHe 提供复现）**：博途有时在源对象的位置 放一句「请重新创建交叉引用信息」的提示，节点不抛错、Path 为空、References / Children 都是空的。现在名字是这类提示 （中 / 英 / 德）且 Path 为空时，不再读它的分支，结果标为不完整并点名所在分支。两个条件缺一不判。 - **`ExportBlocks` 的逐块失败只进日志**：某个块导出失败（文件被占用、许可证、Openness 拒绝）时，结果仍报成功、 调用方看不到。现在 `meta.failures` 逐条列出、`meta.failedBlocks` 计数，有失败时 `success=false`。

2. v2.7.10 2026-11-07 GitHub 仓库发布 ↗
   原版更新说明

   ## [2.7.10] - 2026-11-07 - 交叉引用读进数据块成员、列块和类型覆盖软件单元、读 UDT 字段 工具数不变（238）。`GetTypeInfo` 多一个可选参数 `includeMembers`。 ### 修复 - **交叉引用读进子分支（#60 后半，感谢 @BoykaHe）**：`GetCrossReferences` 现在递归读取 `SourceObject.Children`。 V21 上全局 DB 和背景 DB 的引用都挂在成员子分支里，以前顶层读不到就是 0：真机上 `DB_HMI` 从 0 处变成 29 处， 一个背景 DB 从 2 处变成 84 处。每条结果新增 `SourceHierarchy`（如 `DB_HMI."DB_HMI".CmdStart`）。 某个分支读失败只停这个分支、兄弟分支照读，返回 `UnreadBranches` 列出没读到的分支；设深度和条数上限； 只读 Name / Path / References / Children / Locations，不碰 `UnderlyingObject`，不重试；博途进程退出直接报错。 删除预览里的引用也带层级路径。 - **`GetBlocksWithHierarchy` 漏掉软件单元里的块（#61，感谢 @BoykaHe）**：现在在顶层加一个 `Software units` 组、 每个单元一个子组，块路径为 `Software units/<单元>/<组>/<块>`，`ExportBlock` / `GetBlockInfo` 等直接认； 从根节点 `Program blocks/` 拼出来的路径也能解析。`meta.scope` 标明覆盖范围，单元读不出来时 `complete=false`、`excludedScopes` 列出被排除的范围。 - **绝对地址 HMI 变量的 PLC 同步自检空转**：`ValidateClassicHmiMinimalPackagePlcSync` 原来只核对符号寻址的 `ControllerTag`，全是绝对地址的包一个绑定都没核也报通过。现在 I/Q/M 地址按 PLC 清单里的地址逐个核对 （`%E`/`%A` 与 `%I`/`%Q` 视为同一地址），PLC 里没有变量的地址、清单不带地址、清单被截断、DB 地址无法离线核对， 都会给出警告和计数（绝对寻址本身不要求 PLC 变量，所以不阻断）。`GetPlcTags` 的结果可以原样传入。 ### 新增 - **软件单元里的 PLC 数据类型（#62，感谢 @BoykaHe）**：`GetTypes` 同时列出 PLC 根和各软件单元的类型，每项带 `TypePath`（如 `Software units/U1/UDT_A`）和 `Owner`；`GetTypeInfo` / `ExportType` / `ImportType` 等按这个路径 定位单元里的类型。单元读不出来时 `meta.complete=false`。 - **`GetTypeInfo(includeMembers=true)` 读 UDT 字段**：从导出结果里列出字段的层级路径、数据类型、显式初值（含数组元素 初值）和注释，同时支持 Member 直接嵌套和 Member → Sections → Section → Member 两种形状；文档里只要有没走到的 字段就 `complete=false` 并说明，原文仍以 `ExportType` 为准。类型未编译等原因导不出时，基本信息照常返回，字段部分 `complete=false` 并写明原因。

3. v2.7.9 2026-11-07 GitHub 仓库发布 ↗
   原版更新说明

   ## [2.7.9] - 2026-11-07 - 中文入参不再被 HTTP 解坏、交叉引用残缺不报成功、经典 HMI 变量表支持绝对地址 工具数不变（238）。 ### 修复 - **HTTP 传输把中文 / 特殊字符入参解坏（感谢 @FalseLeonLai，来自 PR #59）**：请求头 `Content-Type` 不带 charset 时， .NET Framework 的 `HttpListenerRequest.ContentEncoding` 返回系统默认编码（中文 Windows 上是 GBK），而不是 null， 原来的「取不到就用 UTF-8」从不生效。组名里的不换行空格 U+00A0 被解成「聽」，该组下的块全部 `Block not found`， 中文路径和注释同样损坏。现在默认按 UTF-8 解码，只有客户端明确写了 charset 才按它解。stdio 方式不受影响。 - **`GetCrossReferences` 查到一半出错仍报成功（#60，感谢 @BoykaHe）**：Openness 枚举中途抛异常时，原来吞掉异常、 把已收集的半截（甚至空表）当完整结果返回，`success=true`。现在返回已收集的部分，同时 `Complete=false`、 `Truncation` 写明原因，`success=false`；结果对象没有 `Sources`、某个源的 `References` 取不到、或某个源带有尚未展开的 子分支（`Children`），也一样标不完整。枚举中博途进程退出则直接报错，不当作部分结果。 `DeletePlcBlock` / `DeletePlcTagTable` / `DeletePlcType` 的预览同步加 `crossReferenceComplete` / `crossReferenceTruncation`， 不完整时给出警告，避免「只查到 4 处引用」被当成全部。（子分支 `Children` 里的引用的递归读取另行跟进。） - **`BuildClassicHmiTagTableXml` 不支持绝对地址、静默忽略未知参数（#57，来自 #13 @King618219 的实测）**： 变量带 `LogicalAddress`（或 `Address`，如 `%M10.0`）时生成 `AddressAccessMode=Absolute` + `LogicalAddress` + `Connection`， 结构与 #13 中 V21 导入验证过的一致；连接名可在表级 `ConnectionName` 给出、变量级 `Connection` 覆盖； 表级 `Absolute=true` 时每个变量都必须有地址。不认识的键直接报错并列出支持的键（错误码 `InvalidParams`），原来会悄悄生成内部变量。 `analysis` 新增 `absoluteBindingCount`。V21 上经典 / 精简面板的变量导入只认绝对地址。 ### 新增 - **导出被拒时的结构化错误上下文（#63，感谢 @BoykaHe）**：`ExportBlock` / `ExportType` 在导出前检查不过或导出本身失败时，错误文字末尾附一行 `ERROR_CONTEXT: {json}`，含 `code`、`phase`（`precheck` / `export`）、对象身份、`scope`（单对象为 `object`， 博途进程已退出或没打开工程为 `session`）、`reason`、`rootCauseKnown`、`retryable`（恒为 false）和博途原话 `nativeMessage`。 只凭 "not permitted" 判断不出是权限还是能力限制，所以 `reason=notPermitted` 时 `rootCauseKnown=false`。

4. v2.7.8 2026-10-26 GitHub 仓库发布 ↗
   原版更新说明

   ## [2.7.8] - 2026-10-26 - 读软件单元、Unified 离散报警、反射调用的拒绝文字说清楚 工具数 235 → 238；精简档不变（新工具用 FindTools 找、CallTool 调）。 ### 新增 - **`GetSoftwareUnits`（#55，感谢 @BoykaHe 的详细报告）**：列出 S7-1500 的软件单元（Software units）和每个单元里的块。 Openness 只能经 `PlcUnitProvider.UnitGroup.Units` 拿到单元，原来 `GetSoftwareTree` 和各块工具都看不到单元里的块。 - 每个块给出 `Software units/<单元>/<组>/<块>` 形式的路径，`ExportBlock`、`GetBlockInfo`、`DescribeBlockLogic` 等块工具直接认这个前缀，不用新参数。 - `GetSoftwareTree` 现在也列出各单元的块。 - **`EnsureUnifiedHmiDiscreteAlarm` / `GetUnifiedHmiDiscreteAlarms`（#54）**：建 / 改 WinCC Unified 离散报警并逐项读回； 列出现有报警和工程里实际有的报警类别。写入前先拒掉 TIA 会收下、但编译才报错的输入：触发变量不存在、 报警类别不存在、同一变量同一位已被别的报警占用、位号超出变量位宽，以及触发变量的数据类型不对—— V21 实测只有 Bool 和位串类型（Byte / Word / DWord / LWord）能当触发变量，整数（Int、UInt、DInt…）和 Real、String 都会在 HMI 编译时报 "The data type of the tag is not permitted for this type of alarm"。 ### 修复 - **反射调用的拒绝文字（#55）**：`InvokeService` / `InvokeObject` 在 `allowWrite=false` 时拒绝非白名单方法，原来返回 「Method not allowed (read-only mode)」，读起来像引擎整体处于只读模式。现在说明这是**这一次调用**的限制、 列出 `allowWrite=false` 时能调的方法，并指向 `GetObjectProperty` / `GetSoftwareUnits`。 ### 文档 - **`ApplyUnifiedHmiScreenDesignJson` 的字体（#54）**：每个控件可带 `font`，如 `{"Size": 28, "Weight": "Bold"}` （`Weight` / `Name` 用 TIA 的枚举名，如 `Bold`、`SiemensSans`），可用 `GetObjectProperty(propertyPath="Font.Size")` 读回。 原来已经支持，只是工具描述里没写。 - **一次放多个控件（#54）**：`ApplyUnifiedHmiScreenDesignJson` 一次调用放完整个画面（V21 实测 100 个控件约 9 秒， 单个控件 0.1–0.3 秒）；逐个调 `EnsureUnifiedHmiScreenItem` 时，每个控件都要多一轮模型往返。

5. v2.7.7 2026-10-22 GitHub 仓库发布 ↗
   原版更新说明

   工具数不变（235）。只影响 `EnsureUnifiedHmiConnection` 在 TIA V21 上新建连接的方式；V20 行为不变。 ### 修复 - **V21 上 `EnsureUnifiedHmiConnection` 改走硬件层连接接口（#13，感谢 @King618219 实测指出）。** V21 的 Openness 提供 `CommunicationManagement.Connections.Create<HmiConnection>(HMI 网口节点, PLC 的 CPU, PLC 网口节点)`： - **经典面板**（精简 / 精智，含二代屏）：现在能自动建 PLC↔HMI 连接。HMI 变量通过 XML 导入时用绝对地址 （`AddressAccessMode=Absolute` + `LogicalAddress`，非优化 DB）；起始画面仍需在博途界面里设一次。 - **WinCC Unified 面板**：新建的连接是**集成连接**（PLC 伙伴已设好），`EnsureUnifiedHmiTag` 可以直接按 PLC 变量名 符号绑定，不再必须用绝对地址和非优化 DB（#50、#53 相关）。 - 前提：两台设备的以太网口在同一条子网上（`ConnectDeviceNodesToProfinetSubnet`，HMI 端传接口模块，如 `HMI_1/HMI_1.IE_CP_1`）。没组网时直接拒绝并说明，不改任何东西。 - 同一对 HMI 和 PLC 之间已有连接时建不了第二条：报错会点名已有的连接，复用它的名字即可（已有的连接若是旧版 建的非集成连接、又需要符号绑定，在博途界面删掉后重跑本工具）。 - Unified 面板上硬件层建不成时退回原来的方式（非集成连接），并在结果里写明原因。 - **TIA V20**：没有这个接口，行为不变；经典面板的报错改为说明「V20 建不了、V21 可以」。

6. v2.7.6 2026-10-22 GitHub 仓库发布 ↗
   原版更新说明

   工具数 224 → 235；精简档 62 → 65（三个删除工具按惯例以本名列出，CallTool 不转发）。 ### 新增 - **`GetPlcTags`**：直接列 PLC 变量（名称 / 类型 / 地址 / 注释 / HMI 可见性），不用先导出 XML； 可按变量表、名字片段、地址前缀筛（`%Q` = 所有输出），查某个地址被谁占、哪些地址还空着。 - **`SetPlcTag`**：建一个变量，或原地改已有变量的名字 / 类型 / 地址 / 注释；改完读回。重名拒绝； 地址被别的变量占着时提示（不拦，TIA 本身也允许重叠）；注释语言不对时在任何改动之前就拒。 - **`DeletePlcTag`** / **`DeletePlcWatchTable`** / **`DeleteDevice`**：和 `DeletePlcBlock` 同一规格—— 默认 `dryRun=true` 只预览影响，确认后实删并读回。`DeleteDevice` 只认设备名或它的 CPU / 头模块名， 给模块名会拒绝（否则「删一个模块」会变成连程序删掉整个站）。 - **`CreatePlcTagTable`** / **`CreatePlcWatchTable`**：建空变量表 / 空监控表，可放进已有的组。 - **`CreateInstanceDB`**：直接给 FB 建背景 DB（默认名 `<FB>_DB`、自动编号），读回确认它属于这个 FB。 - **`RenamePlcObject`**：改块名 / 块号、数据类型名、变量表名、监控表名、设备名。先查重名；块开着 自动编号时改号会如实拒绝（Openness 关不掉自动编号）；改 DB 名会提醒 HMI 侧按符号绑定的变量会断链。 - **`CompileHardware`**：编译一台设备的硬件组态（模块、地址、网络、固件），返回 TIA 的错误 / 警告—— `CompileSoftware` 只编程序，插模块、改地址之后用它查硬件问题。 - **`ArchiveProject`**：把打开的工程归档成一个 `.zap21` / `.zap20` 文件（备份、交接）。有未保存改动时 拒绝（引擎不替用户保存）；同名归档不覆盖。 ### 修复 - **经典面板上调 `EnsureUnifiedHmiConnection` 只报 `Create(string) not found on ...ConnectionComposition`（#13 实测）。** 现在直接说明：这是经典 WinCC 面板（精简 / 精智），Openness 建不了经典 HMI 连接，要在博途界面里建一次； 这个工具只用于 WinCC Unified 面板。 - **V20 上导入 HMI 画面 / HMI 变量表 / HMI 连接 / 工艺对象 XML 会因版本头失败。** 这 4 个导入入口没像块、 数据类型、PLC 变量表那样先把 `<Engineering version="V21" />` 改成当前博途版本、补 UTF-8 BOM， 而引擎自己生成的 HMI XML 就写着 V21 头。现在 4 个入口都先做这一步（来源：fork GabrielSRR ffebe6e 指出）。 - **`Bootstrap` 和 `RunCapabilitySelfTest` 标称只读，却可能弹 UAC 把当前用户加进 Openness 组。** 两者调用的组检查在「不在组里」时会自动加组。现在只查不改；要加组请用 `EnsureOpennessUserGroup` 或 `Doctor`（fix=true）（来源：fork yaorb a0eeb38 指出）。

7. v2.7.5 2026-10-14 GitHub 仓库发布 ↗
   原版更新说明

   连接失败说清原因、CLI 参数顺序（#51）+ Unified 连接不再假成功（#50）。 ### 修复 - **连不上博途时只报最后一句（#51）。** 引擎先逐个附加正在运行的博途，全都附加不上才新起一个实例；原来新起也失败时只报 `Connection to TiaPortal failed`，前面每个进程为什么附加不上只进了日志。现在报错里逐个列出（附加超时 / 异常类型和首行）。 - **全局参数写在命令前面时被静默当成 MCP 服务器（#51）。** `TiaMcpServer.exe --tia-major-version 21 prewarm` 原来不报错、以服务器模式起来后 exit 0。现在照常执行该命令；`gen --tia-major-version 21 x.json` 也不再把 `21` 当成 spec 路径。 - **`EnsureUnifiedHmiConnection` 报 "ensured"，运行时却连不上（#50）。** `DisabledAtStartup` 原来保持 Openness 默认的 `True`（运行时不建立连接），`InitialAddress` 里的 IP 保持写死的 192.168.0.1/.2，伙伴 `Partner/Station/Node` 在 Openness 里只读、从未建立。现在 `DisabledAtStartup` 改为 `False`、两端 IP 按硬件组态改写，均读回确认；核对两端同子网；改不成就报失败。消息如实标注**非集成连接**：HMI 变量需用 `address` 绝对地址（非优化 DB）绑定；要按 PLC 符号绑定，请在博途「设备和网络 → 连接」里手动建集成连接。手动建的集成连接只读回、不改写地址。 - 工具说明、Bootstrap、SKILL 中「用符号绑定、不要绝对地址」的说法已更正。 ### 验证 - 离线自检 379/379。 - V21 隔离实例真机：连接被置为「启动不连 + 错 IP」时，2.7.4 照报成功、什么都没改；2.7.5 改正并读回。从零新建工程：2.7.4 建出的连接 `DisabledAtStartup=True`，2.7.5 为 `False`；V20 从零新建同样为 `False`。 ### 下载 `TIA_MCP_Delivery_v2.7.5_20261014.zip`：V21 + V20 双引擎，解压即用，用法同 2.7.4。

8. v2.7.4 2026-10-07 GitHub 仓库发布 ↗
   原版更新说明

   ## 下载 **`TIA_MCP_Delivery_v2.7.4_20261007.zip`（见下方 Assets）** —— 完整交付包，解压即用，**同时带 V21 和 V20 两个引擎**。 - **V21 用户**：解压后跑 `配置MCP.bat`（或 `tia.cmd`） - **V20 用户**：解压后跑 `配置MCP-v20.bat`（或 `tia-v20.cmd`） git 克隆只带 V21 运行时（`runtime/v21`），V20 引擎只在这个 zip 里。 --- 一轮整体审查与加固（PR #45，感谢 @zy13027），加上两个 HMI 只读批量工具（PR #44，感谢 @DenLucas）。工具数 222 → 224。完整条目见 [CHANGELOG](CHANGELOG.md)。 ## 修复（摘要） - **Openness 调用从不串行**：宿主并行发来的请求会同时进入同一个博途句柄。现在所有需要博途的工具排队过同一把闸。 - **CallTool 对 9 个工具是坏的**（异步工具返回 `Task` 对象、注入参数永远报缺参），现在与直接调用一致。 - **HTTP 桥**：超时一次就连累后续所有请求；两个客户端用同一个请求 id 会串响应；`localhost` 前缀实际监听全部网卡，没设 key 时局域网机器带 `Host: localhost` 就能进来——现在没设 key 时只接本机 TCP 连接。 - **下载**：`DataBlockReinitialization` 等 4 个提示的应答类型/取值不对，从来没生效；下载后 CPU 可能停在 STOP；`Ok=false` 无错误文本时报成功；在线模块与组态不一致时不再静默接受（会写进 Warnings）。中止测试/调试功能改为显式参数 `abortActiveTests`。 - **工程保护**：CloseProject 会关掉用户自己开着的工程；先开自己的工程再挂接到用户工程后，「是不是我们开的」判定会过期；OpenProject 路径写错会白白关掉当前工程。 - **假成功**：GoOffline 吞异常、GoOnline 的 `ipAddress` 从未生效、`CheckDownloadReadiness` 的一致性写死为 true、SetWatchTableModifyValue 没写进也报成功、MoveBlockToGroup 失败会丢块、`ImportBlocksFromDirectory(overwrite=false)` 仍可能覆盖。 - 引擎在部分 V21 机器（装在非 C: 盘）上根本起不来。 - 全部工具带 MCP annotations；会动 CPU 或删数据的 7 个工具以本名列出，`CallTool` 不转发它们。 ## 新增 - **`GetHmiTagDetails` / `GetHmiScreenItemDetails`**：一次调用读出整张 HMI 变量表（含变量表分组里的表）或整个画面的全部对象属性，只读。读不到的对象列入 `Failed`、拼错的属性名写进 `Meta.unreadableAttributes`，不会报假成功；传 PLC 路径会直接拒绝。 - `InvokeObject` / `InvokeService` 放行只读的 `GetAttributes`。 ## 验证 - 离线自检 355 条全过（本轮新增的下载应答用例先在原代码上跑出红，修后转绿）；V20 / V21 两个引擎 0 错误编译，版本号 2.7.4，exe 内无构建机路径；`Validate-Bundle -Strict`、死引用闸、精简档检查均通过。 - **TIA V21 隔离实例真机跑过**：建工程 + SCL + 编译 0 错、CallTool 建块组并移块后编译 0 错、CallTool 拒绝 DownloadToPlc、下载前预检、关闭自己建的工程；PLC + WinCC Unified PC 工程上读全部变量表、拼错属性名被报出、PLC 路径被拒、画面对象位置尺寸正确、未知画面报错。 **没验到的部分**：没有真 PLC / PLCSIM，**下载本身没有真机验证**（下载提示的应答只有离线用例 + 对 V21 程序集的反射核对）；经典 HMI（精智/精简面板）和 V20 引擎没有真机跑。遇到问题请开 issue。 **提示**：V21 的 Openness 白名单在 `HKLM\SOFTWARE\Siemens\Automation\Openness\AllowList\<exe 名>`，不是 `21.0\Whitelist`；无界面运行时没登记会挂一个「Openness 访问」窗口等人点。

9. v2.7.3 2026-09-16 GitHub 仓库发布 ↗
   原版更新说明

   ## 下载 **`TIA_MCP_Delivery_v2.7.3_20260916.zip`（见下方 Assets，约 11 MB）** —— 完整交付包，解压即用，**同时带 V21 和 V20 两个引擎**。 - **V21 用户**：解压后跑 `配置MCP.bat`（或 `tia.cmd`） - **V20 用户**：解压后跑 `配置MCP-v20.bat`（或 `tia-v20.cmd`） git 克隆只带 V21 运行时（`runtime/v21`），V20 引擎只在这个 zip 里。 --- 两条修复，都是「工具在，但一碰到真实工程就不干活」。工具数不变（222）。 ## 修复 **画面分组里的画面，对所有画面工具都是隐形的**（PR #41，感谢 @DenLucas 发现并修复）。 查画面只读 HMI 软件根上的 `Screens`，而真实的 WinCC Unified 工程几乎都用画面分组来组织画面（比如 `00_ScreenLayout/PopUps/LogOff`）。放进分组的画面 `GetHmiScreens` 列不出来、`DescribeHmiScreen` / `ExportHmiScreen` / `ExportHmiProgram` / `EnsureUnifiedHmiScreen` / 按钮动作绑定按名字找不到——只报一句「找不到」，没有任何迹象指向「是因为它在分组里」。现在这些工具都会递归进分组：Unified 走 `ScreenGroups → Groups`，经典 HMI 走 `ScreenFolder → Folders`。 合并时补了同一个坑的另外两处：反射桥的 `objectKind=HmiScreen` / `HmiScreenItem`（`DescribeObject`、`GetObjectProperty`、`InvokeObject` 等）原来也只查根目录。遍历逻辑抽成了不依赖 SDK 的独立文件，离线测试可以直接喂假对象。查找失败仍然当「找不到」处理，不会抛异常。 **写 Unified HMI 的 JS 事件脚本后强制跑 `SyntaxCheck()`，在 TIA V21 上会偶发把博途进程整个带走**（issue #36，感谢 @Moy-GH 报告）。 进程一没，刚写进去、还没保存的脚本也跟着丢。现在 `SetUnifiedHmiButtonEventScriptCode` 与 `EnsureUnifiedHmiButtonAction` 新增 `syntaxCheck` 参数，**默认 false**。不查的时候不再发 `syntaxErrorCount`（发个 `0` 就等于把「没查」谎报成「查过了没错」）；检查真把进程干掉时不再返回成功，而是如实报告并给出恢复步骤。 ## 验证 - 离线自检 147 条全过（新增 10 条画面分组用例；故意把遍历改回只查根目录，其中 6 条会变红，证明用例是有效的）。 - 属性名对照 V21 Openness 程序集核对过：`HmiSoftware.ScreenGroups` → `HmiScreenGroup.Groups` / `Screens`；`HmiTarget.ScreenFolder` → `Folders` / `Screens`。 - 分组遍历由 PR 作者在真实 V21 工程（WinCC Unified）上验过：21 个画面全部列出，两层深的 `LogOff` 能按名字找到。 - 两个引擎在打包版本上重新编译：版本号 2.7.3、源码提交一致、V20/V21 是两份不同的构建；`Validate-Bundle` PASSED。 **没验到的部分**：合并时补的那一版遍历没有重新跑真机（MCP 自身建不出画面分组，本机也没有带分组的 Unified 工程），所以没重跑；经典 HMI（精智/精简面板）嵌套文件夹这条路径只有离线用例和程序集核对，没有真机验证。遇到问题请开 issue。

10. v2.7.2 2026-09-05 GitHub 仓库发布 ↗
    原版更新说明

    ## 下载 **`TIA_MCP_Delivery_v2.7.2_20260905.zip`（见下方 Assets，约 12 MB）** —— 完整交付包，解压即用，**同时带 V21 和 V20 两个引擎**。 - **V21 用户**：解压后跑 `配置MCP.bat`（或 `tia.cmd`） - **V20 用户**：解压后跑 `配置MCP-v20.bat`（或 `tia-v20.cmd`） > 之前的版本里，`tia-v20.cmd` 会提示「V20 请到 GitHub Releases 下载交付 zip」， > 但历史发布**从来没有附过这个 zip** —— V20 用户按提示去下载，下不到。这一版补上了。 > git 克隆只带 V21 运行时（`runtime/v21`），V20 引擎只在这个 zip 里。 交付包已在**解压后的位置**独立验过：`Validate-Bundle` PASSED、两个引擎都起得来且 `tools/list` 都是 222。 --- 三条都来自 issue #33 的现场反馈，都是「工具在，但用不上」。 ## 修复 **名字里含 `/` 的设备项，从原理上寻不到址。** `deviceItemPath` 用 `/` 分段，而西门子的模块名本身常常自带 `/`：`DQ 16x24VDC/0.5A ST_1`、`AI 4xI 2-/4-wire ST_1`、`AQ 4xU/I ST_1`、`DI 6/DQ 4_1`。逐段比对的话，这些模块**不是找不到，是根本表达不出来**——所有按设备项路径取对象的硬件工具对它们一律失效。现在匹配子项时会把后续若干段拼回 `a/b/c` 再比，跨度从大到小试，先匹配更长（更具体）的那个。子项名是已知的有限集合，所以这不是猜；既不需要引入转义语法，也不改变原来能用的写法。 **设备项本级没有 I/O 地址时，只回一句「没有任何 I/O 地址」。** 地址在分布式 I/O（ET200 系列）和机架式站上常常挂在**子项**而不是模块对象本身，只说「没有」会让人以为工具读不到，转头去查一个没问题的组态。现在本级为空时会下钻一层，把**子项里有地址的**连同地址摘要一并列出来，可以直接换路径重试。 **`GetPlcTagTables` 返回空清单时，答不上来是哪一种空。** 三种成因返回的东西一模一样：这个 PLC 确实没有表 / `TagTables` 属性在这个版本上叫别的名字 / 读属性时抛了异常被吞掉。现在空清单会带上这次遍历的证据（`walkedGroupType` / `tagTablesPropertyFound` / `tagTablesPropertyError` / `groupsVisited` / `notes`），并明说「这不一定表示它没有表」。有表时行为一字不变。 ## 新增 **`ConnectIsolated`** —— 起一个全新的无头 TIA Portal 实例，不 attach、不修改、不关闭任何用户已经开着的窗口或工程。 这条是修一个**把人挡在门外**的组合缺陷：`Connect` 会优先接管**已经开着工程**的那个实例，而 `OpenProject` 又（正确地）拒绝动别人的工程——两条各自正确的行为叠在一起，结果是**只要用户在博途界面里开着任何工程，整台服务器就用不了**。有了这条路，可以一边在界面里干活，一边让 MCP 在自己的实例里跑自己的工程。 必须是该 MCP 进程里的第一个连接动作。已进 lite 默认档——挡掉这条出口等于让「用户正在用博途」变成一个无解的死局。 ## 验证 **V21**：真实工程副本（S7-1200 + S7-1500），全程在隔离实例里、没有碰当时正开着的用户工程（事后核对 portal 进程为证），合并 22/22。 **V20**：V20 引擎 + `--tia-major-version 20` + 一个 V20 工程副本，8/8。这轮顺带更正了 issue #33 里的两个推测： - **V20 读得到模块 I/O 地址**：同一台 S7-1200 上 `AI 2_1` 读到 1 条、`DI 6/DQ 4_1` 读到 2 条。所以「V20 的 Openness 不填充模块 I/O 地址」不是一条普遍限制——那更可能是分布式 I/O（ET200SP）特有的形态，地址挂在子项上，本版新增的子项提示正好用来定位它。 - **V20 的 `GetPlcTagTables` 枚举正常**：两个 PLC 分别列出 1 张和 5 张表。所以枚举返回空也不是 V20 的普遍问题，而是某个具体工程/软件对象的形态问题——本版新增的遍历证据字段就是为了把这种情况钉住。 反向哨兵覆盖：**拼出来的错名字仍必须报错**（防贪心匹配把错路径吃成对的）、普通模块照旧、`GetDeviceItemTree` 未被改坏、有变量表时不掺诊断字段、2.7.1 那批「假成功」修复无回归。 **仍未验到的部分**：手上的工程里没有 **ET200SP** 这种分布式 I/O 站，子项下钻是在 S7-1200 CPU 上验的（同一段代码，但没覆盖 ET200SP 的实际形态）。变量表枚举的**空清单分支**在这些工程上触发不到，改用临时插桩确认了证据字段确实被采集。 工具 221 → 222，lite 54 → 55（仍在 128 上限内）。离线套件 126/126，死引用闸门 PASS。

11. v2.7.1 2026-09-05 GitHub 仓库发布 ↗
    原版更新说明

    纯修复版，没有新功能，工具数不变。修的全是同一族缺陷：**把「没做成」说成一个确定的结论**。 这类缺陷比崩溃危险得多。崩溃会让调用方停下来；一句「找到 0 个」「已下线」「0 处差异」会让它**继续往下走**，并把这个错误结论当作事实带进后面每一步。对着 AI 客户端尤其如此——它没有第二个信息源来质疑你。 ## 怎么找出来的 新增发版前闸门 `scripts/Sweep-WrongPathHonesty.py`：拿真项目给**每个只读工具**喂一条不存在的路径，凡是「返回成功」的都列为嫌疑。第一轮跑出 10 个。 这条检查**离线跑不了**（要判断"路径不存在时的反应"就得有真项目），所以它不在 CI 里，是发版前的手工闸门。脚本自带反向哨兵：正确输入必须仍然成功——否则「所有工具一律报错」的坏实现也能满分通过，那时它测的就不是诚实，是「有没有全坏」。 ## 主要修复 **`CompareSoftwareToOnline` 是这批里最贵的一条。** 这个工具的全部价值就是回答「要不要下载」。路径写错时它返回 `Entries=null` 的正常响应 → 调用方读到「0 处差异」→ 得出「在线离线一致，不用下载」。比对**失败**时同样如此，而且其中一条路径还硬写 `IsOnline=true`——实测拿到的正是 "The operation is not permitted in offline mode"，即根本没在线，字段和消息自相矛盾。另外，以 `Identical` 结尾的比对状态被算成了差异，会把「一致」报成「N differences」。 **`GoOffline`** 路径写错、或 `OnlineProvider` 拿不到（那一路**什么都没做**），都回一句「'X' is now offline」。调用方以为在线会话已断开，实际它还挂着：后续 `CompileSoftware` / `Export*` 会被 "not permitted in online mode" 挡住，现场 CPU 的编程连接也一直被占。 **`GetSoftwareTree`** 路径不存在时把一句 "No PLC software found" 当作**树的内容**返回，工具层只判非空即算成功 → `message` 写着「Software tree retrieved from 'XXX'」而树体里写着找不到。同一个 `catch` 还把异常文本也当成树返回，**遍历炸在半路也报成功**。 **`GetTechnologyObjects`** 的「没连项目」「路径写错」「枚举炸了」三条全返回空列表，报成「找到 0 个技术对象」。空列表只有一个合法含义：解析到了这个 PLC，它确实没有 TO。 **`GetOnlineState` / `GoOnline`** 对不存在的 PLC 返回 `State="Offline"`——**给一个没测过的问题一个确定的答案**。拿不到 `OnlineProvider` 时改报 `State="Unknown"` 并说明「未测量 ≠ 离线」。 **反射桥 7 处 + HMI Describe 族 13 处**返回 `Message="Object not found"` + 空成员表。反射桥恰恰是**用来猜路径**的工具，猜错必须响，否则每次猜错都被记成一条「已确认为空」的事实，越猜越偏。这些现在报参数错误，不再是「服务器内部意外错误」。 **Describe 族的 `meta.success`** 原来写的是「成员表非空」，把**空**当成了**失败**：真实存在但没有成员的对象被报成失败，调用方于是去「修」一个没坏的东西。 **`ImportBlock` 的读回校验用文件名当块名**：把 OB100 的 XML 存成 `OB100.xml` 导进去，块在 TIA 里实际叫 `Startup`，于是一次成功的导入被报成 "NOT found after import"；反过来块若被静默降级成 OB1，光比名字也可能"对上"，只有块号抓得住。改为按 XML 里声明的**块名 + 块号**比对。 还修了 `GetPlcForceTables`，以及 FB/FC 构建器那条「照着报错改不动」的提示（它只报内部形参名，而调用方填的是另一个 JSON 字段）。 剩余 3 个嫌疑（`GetOpcUaConfig` / `GetPutGetAccess` / `ProbePlcMonitorOnlineCapabilities`）返回里带明确的 `ok=false`，自洽，**有意保留**。 ## 验证 真机跑在真实工程副本上（S7-1200 + S7-1500，V21）：嫌疑 **10 → 3**；没连项目时会明说要先 `Connect`；路径写错时会失败并列出可用 PLC；**正确路径但离线时，错误指向在线状态而不是「找不到 PLC」**（这条专门防修过头）。反向哨兵确认 38 个只读工具用正确路径照旧成功。离线套件 126/126，死引用闸门 PASS。

12. v2.7.0 2026-09-04 GitHub 仓库发布 ↗
    原版更新说明

    补的是**没有它就干不完活**的那类能力：以前能建块却删不掉块、能加整站却改不了模块地址、插不进信号板。同时修掉一条比缺功能更危险的静默错解析。 ## 新增（7 个工具，221 → 全量） **删除族**（#27）`DeletePlcBlock` / `DeletePlcTagTable` / `DeletePlcType` 默认 `dryRun=true`，预览给出解析到的完整路径、对象类型和**交叉引用**（删之前先看谁在用它）。真删之后**重新读一次**确认对象确实不在了才报成功，读不回来就明说「未验证」。删除路径**拒绝正则和通配符**——只接受一个精确路径。默认变量表拒删。 **硬件 I/O 地址**（#33）`GetDeviceItemIoAddresses` / `SetDeviceItemIoAddress` 地址是**引擎原值字节偏移**（`%I2.0` 就是 `startAddress=2`），返回里写明，不做换算。改地址默认 `dryRun=true`，实写后必定回读比对；地址重叠/越界/模块锁定由 TIA 判定，**具体原因原样报回**，不会静默成功。 **机架槽位**（#26）`GetDevicePlugLocations` / `PlugDeviceItem` 槽位号一律来自运行期 `GetPlugLocations()`，不硬编码。`PlugDeviceItem` 是「往已有设备插子模块」，和 `AddDevice`（新建整站）不是一回事。`dryRun` 走 Openness 真实可行性预检，不写工程。 ## 修复 **设备项路径打错一段，不再静默解析成它的父级。** 路径解析器在某一段匹配失败时会把窗口往后滑一格重试，最终被全局扫描命中路径中间的某一段并原样返回：`'S7-1200 station_1/PLC_1/不存在的模块'` 会解析成 `'PLC_1'` 本身——读地址读到父级的空清单、报「这个设备项没有 I/O 地址」，**改地址会改到父级头上**，调用方看不出任何异常。这条影响所有按设备项路径取对象的硬件工具，不只本版新增的。 **`SetDeviceItemIoAddress` 的负数起始地址在预演阶段就报错。** 原来校验只在实写那一路，`dryRun` 对负数一律回答「可以改」——预演反而成了误导。 ## 验证 真机跑在一份真实工程副本上（S7-1200 + S7-1500，V21），**19/19**：含实删块 + 独立回读确认块没了、实改地址 64→700 + 独立回读 + 还原、地址重叠必须失败且地址未变、再删已删掉的块必须报 NotFound。反向哨兵覆盖：`dryRun` 之后工程一字未改、正确的完整路径与省略站前缀的简写路径照旧解析、`GetDeviceItemTree` 未被路径解析器的改动改坏。离线套件 126/126，死引用闸门 PASS。 版本号从 2.5.4 跳到 2.7.0 是有意的：避免与另一条交付线的 2.6.0 撞号。

13. v2.5.4 2026-09-04 GitHub 仓库发布 ↗
    原版更新说明

    这一版没有新功能，全是修复。它们有一个共同形状：**失败不会被看见** —— 要么把读不回来的结果当成通过，要么把异常吞掉换成一句错的具体结论， 要么让模型照着描述去调一个根本没注册的工具。调用方（尤其是 AI 客户端） 看到的都是绿灯，于是继续往下走，代价推迟到很后面才炸。 ### 修复 - **路径写错不再报「成功，0 个块」。** `GetBlocks` / `GetTypes` 在 PLC 路径解析不到时 照样返回空列表，工具层于是报成功。对模型来说这是最坏的回答：它会据此认为 PLC 是空的， 转头去建一堆已经存在的块。现在解析不到就是明确失败，并列出可用的 PLC 路径。 - **块列表遍历炸在半路，不再把残缺结果当完整结果返回。**「少了几个块」比「一个都没有」 更难发现，因为它看起来完全正常。 - **非法正则不再退化成「没有匹配的块」。** 原来每个块都套一层 try/catch 去跑 Regex， 模式写错时每个块都被吞掉、最后返回空列表 —— 把「你的模式非法」说成了 「工程里没有这样的块」。现在当场报错并说清怎么改。 - **按名字取块不再返回错块。** 名字里含正则元字符时走的是不锚定匹配 + 取第一个， 而西门子块名常带 `.`：请求 `FB_Motor.V2` 会命中 `X_FB_MotorAV2_Old`， **错块被以你请求的名字标注返回**，调用方无从察觉；导出、交叉引用都跟着挂到错误对象上。 现在的次序是：字面精确同名 → 锚定匹配 → 命中多个就报歧义并列出候选。 - **编译结果读不回来不再算作零错误。** `ErrorCount` 是可空的，`null` 专门表示 「没读回来」。五处写成 `(ErrorCount ?? 0) == 0`，其中包括 `tia compile` 命令 —— 它会**退 0**，脚本和 CI 会据此认为编译干净。 - **HMI 模板的「执行 JSON 检查」曾是恒真的同义反复。** 检查委托缺省时它退化成 「前面没报错且有条目」，判据里已经含着「没报错」，永远不可能新增一条错误。 而走这条空转路径的正是发版前的离线验收闸，以及描述里承诺检查 "execution JSON shape" 的那个工具。委托现在是必填的，编译期堵死。 - **批量 HMI 绑定不再把「没抛异常」当成绑上了。** 回读调了却把返回值扔掉； 而 Portal 层会把异常吞成 `success=false` 返回，调用方的 try/catch 永远看不到， 属性名不被控件接受时 TIA 也只是静默忽略。现在判据只认硬证据，读不回来显式标未验证。 - **设备树遍历出错不再被说成「你路径写错了」。** 遍历中途的异常被吞成「找不到」， 于是叫用户去改一个本来就对的路径。真因现在跟着原消息一起给出。 - **连接被拒不再制造孤儿 TIA 进程。** 授权/白名单被拒时继续扫下一个候选毫无意义， 扫空之后会去新起一个无头实例 —— 那次同样会被拒，但进程已经拉起来了， 在用户机器上空转。 - **工具描述不再点名不存在的工具。** 三个名字（`SetForceTableEntry`、`GetCpuOnlineState`、 `GetAxisParameters`）在 209 个注册工具里一个都没有。AI 客户端照做只会撞 tool-not-found，然后自己去找别的路子绕 —— 而其中一个撞上的正是「强制写值」 这种安全敏感操作。现在如实说明事实与真实存在的替代路径。 - **`SetWatchTableModifyValue` 补上物理安全提示。** 它是会真正驱动物理世界的动作里 唯一一个描述中没有一句警示的。 - **反射工具族（`GetObjectProperty` / `ListObjectChildren` / `InvokeObject` / `DescribeService` / `InvokeService`）补齐 `objectPath` 指引** —— 同族的 `DescribeObject` 写清了不同对象类型该填什么，这五个漏了，调用方必然要试错一次。 - **清掉一批恒返回 null 的死后备分支**，以及两个「算了没人看、而且算错」的返回值 （子组递归里写的是覆盖不是累积，最终只反映最后一个子组）。 ### 行为变化（升级前请看） 以前**静默成功**的几种情况现在是**明确失败**：PLC 路径写不对、正则写错、 块列表没读全、编译结果读不回来。如果你的脚本依赖「返回空列表 = 没有」， 需要改成处理错误 —— 那个空列表本来就可能是「没查成」，只是分不出来。 ### 新增：离线自检套件与 CI 这个仓库此前**没有任何测试工程、没有任何 CI**，上面这些修复因此没有东西盯着。 现在有了 `tools/tiaportal-mcp/tests/TiaMcpServer.Tests`（22 条，纯离线、不连 TIA） 和 `.github/workflows/offline-checks.yml`（回归套件 + 工具描述死引用对拍）。 每组用例都带反向哨兵；「执行 JSON 检查」那组还盯 API 形状 —— 委托一旦被改回可选参数，空转路径立刻复活，而所有传了委托的运行期用例一条都不会红。 ### 验证 - **真机**：TIA Portal V21，真实工程副本（101 个块），全程只读。8/8 —— 含 4 条反向哨兵 （正常列块不受影响、合法正则照常过滤 15/101、全限定真名照常取到、真实编译照常拿回 errorCount）。 - **离线**：22/22，并做过故障注入（把委托改回可选 → 2 条如期变红 → 字节级还原 → 全绿）。 - **未能真机复现、只有反向哨兵覆盖的**：编译结果读不回来那一支（无法让 TIA 造出这个状态）、 设备树遍历异常那一支（健康工程上造不出）、授权被拒那一支（复现它意味着故意触发一次授权拒绝）。 这三条的正常路径在上面的真机跑里都验过没被改坏，但**异常分支本身只有代码级依据**，如实标注。

14. v2.5.3 2026-08-31 GitHub 仓库发布 ↗
    原版更新说明

    ## 新增：`CompileAndDiagnoseHmi` —— AI 能自己读 HMI 的编译错误（#24） `CompileAndDiagnosePlc` 的 HMI 对应版本。生成完画面/变量之后可以直接编译并拿回**结构化的错误与警告**（逐条带 `State` / `Description` / `Path`），模型据此自己改，不必再让工程师去博途界面里手工编译、再把报错文本贴回来。 - **WinCC Unified**：`HmiSoftware` 自身不可编译，实际编译的是**它所属的设备** —— 这与你在博途界面里编译 HMI 时发生的事情一致。因此**硬件组态的诊断会和画面诊断出现在同一份结果里**，这是预期行为。 - **经典屏（精智 / Comfort）**：编译 HMI software 自身。 工具数 208 → 209；精简档（默认）48 → 49，新工具属于金路径，默认档即可直接调用。 ## 发布前的真机验证 TIA Portal V21，MTP700 Unified Basic（6AV2 123-3GB32-0AW0）： | 用例 | 结果 | |---|---| | Unified 屏（未配置起始画面，必然编译失败） | `State=Error`，`errorCount=3`，三条错误结构化返回（起始画面未配置 / 两条运行系统密码策略） | | 同工程内 S7-1513 PLC（回归） | `CompileAndDiagnosePlc` → `State=Success`，0 错 0 警 | 第一版实现在 Unified 上其实是**坏的**：编译目标的判据写成了「该对象是不是 `IEngineeringServiceProvider`」，而 Openness 里几乎所有对象都实现该接口——于是代码取到软件的直接父 `DeviceItem` 就收工，那一层却并不持有 `ICompilable`。`GetService<T>()` 在服务不存在时只返回 `null` 而不抛异常，所以它在 PLC 与经典屏上都能过，只在 Unified 上失败： ``` HmiSoftware via DeviceItemImpl.GetService<ICompilable>() returned null ``` 正式判据因此改为「**它到底给不给得出 `ICompilable`**」，并沿 owner 链逐层向上查找（Unified PC 站是 `Device → DeviceItem → DeviceItem` 的嵌套，层数不该被写死）。若一路都找不到，错误信息会把走过的每一层及其结果一并列出。 先前只在经典屏上验过 `Success 0/0`，**那仅覆盖 `HmiTarget` 一条分支**，不足以说明 Unified 可用——本版把两条分支分别验过才发布。 ## 修复：编译诊断不再被静默吞掉 `CompileAndDiagnosePlc` / `CompileAndDiagnoseHmi` 共用的诊断收集逻辑此前整体套在一个 `catch { }` 里。编译诊断是 Openness 代理对象树，代理可能在遍历途中失效（切换工程、TIA 界面抢走句柄）；集合代理一旦在枚举时抛异常，**已经读到的诊断会连同异常一起被丢弃**，而 TIA 报出的 `errorCount` 仍是真实值。调用方看到的是 `errorCount: 5` 配上空的 `errors: []`，并且无从分辨「收集失败」与「本来就没有明细」。 现在逐条兜异常：能读到多少返回多少，读取过程中的问题写入 `info`（前缀 `[诊断收集不完整]`），并新增 `meta.diagnosticsComplete` 布尔字段供程序判断。 ## 升级说明 - 引擎二进制已更新（`runtime/v21/TiaMcpServer.exe`，2.5.3）。**替换引擎后 Openness 白名单需要重新登记一次**：以管理员身份运行 `runtime\v21\TiaMcpServer.exe whitelist-register --tia-major-version 21`，或在 TIA 助手的「环境体检」里点一键修复。 - `Validate-Bundle` 全绿；版本在 CHANGELOG / csproj / manifest / runtime 引擎四处一致（2.5.3）；`tools-list` 与 manifest 工具数一致（209）。

15. v2.5.2 2026-08-25 GitHub 仓库发布 ↗
    原版更新说明

    ## 修复 ### `GetPlcTagTables` 恒返回空列表（#22） 拿到的对象已经是 `PlcTagTableComposition` 了，代码却又去它身上找一个 `.TagTables` 属性——找不到；而且非空的属性提示列表还绕开了"直接当集合枚举"的分支，helper 把这一路吞成空列表。 于是**任何 S7-1200/1500 工程调这个工具都返回 `{"items":[], "success":true}`**，看着像"这个 PLC 没有变量表"。 与报告人怀疑的 DLL 补丁级别、槽位名 `-7A1` 都无关——换一台机器、换一个正常命名的 S7-1500 工程照样空。 已在一个含 7 个 PLC 的真实工程上验证：修复前每个 PLC 都返回 `[]`，修复后各自列出 1～6 张变量表，按名导出得到可用的 XML；传入不存在的表名会明确报错并列出可用表名。 同批： - **嵌在用户分组里的变量表现在也能列出/导出**（此前只扫根层）。分组内的表以 `分组名/表名` 返回，`ExportPlcTagTable` 两种写法都收。 - **枚举失败不再伪装成"没有变量表"**，拿不到容器时明确报错。 - `ExportPlcTagTable` 不再把"没这张表"和"找到了但导出被拒"报成同一句话。 ### vci-watch：不再自己拉起博途 判断"博途开着"此前数的是 `Siemens.Automation.Portal.exe` 的进程数。实测**一个开着工程的 GUI 就是 3 个进程**（GUI + HMICompiler + SearchReplaceBackgroundProcess），而一台没开任何工程、只剩一个 Openness 无头残留的机器同样数到 1。 后者会自维持：判定"博途开着" → 起引擎 → 引擎找不到能附着的工程 → **自己再拉起一个无头实例** → 600 秒超时被掐断 → 留下的残留让下一轮继续为真。实测整夜每 72 分钟空转一次。 现在两道闸：带 `-bootstrapper=` 的一律不算会话；起引擎后、`Connect` 之前先用 `ListPortalProcessProjects`（只探测、不拉起）确认真有工程可搭。另外无头残留会被记 PID、下一轮按完整命令行核对后补杀。 ### 版本一致性 `scripts/Validate-Bundle.ps1` 新增检查：CHANGELOG 首条、`csproj` 的 `AssemblyVersion`、manifest 的 `bundleVersion`/`packageName`、以及 `runtime\v21` 里 exe 的 FileVersion 必须一致，对不上直接判失败。 > 2.5.1（vci-watch 退避修复）此前只推到了 `v21` 分支，没进 `master`、没打 tag，**公开发布里从未出现过**；本版一并带上。 --- 工具数仍为 **208**（未增删工具）。完整说明见 [CHANGELOG.md](https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/blob/master/CHANGELOG.md)。

16. v2.5.0 2026-08-22 GitHub 仓库发布 ↗
    原版更新说明

    **这版的主角**：TIA V21 的版本控制接口（Version Control Interface）。博途工程是二进制的， Git 没法 diff；VCI 把工程映射成一个普通文件夹、每个对象一份文本文件，于是"改了哪个块、改了哪一行" 第一次变得可 diff、可 review、可回滚。本版把整圈做成命令，**不需要在博途界面里点任何东西**。 ### 怎么用（三步） ``` 1) CreateVersionControlWorkspace(workspaceName="git", folderPath="D:\repos\my-plc") 2) ConnectProjectToWorkspace(dryRun=false) ← 整工程自动纳管，几百个块一条命令 3) SyncVersionControlWorkspace(direction="ProjectToWorkspace", dryRun=false) 然后：git add -A && git commit ``` 之后每次想知道改了什么：`GetVersionControlStatus(changedOnly=true)` —— 精确到块， 这就是 change log 的输入。完整指南见 **`docs/version-control-git.md`**。 ### 新增 - **VCI 五件套进入本包（工具数 203 → 208）**：`CreateVersionControlWorkspace` / `ConnectProjectToWorkspace` / `GetVersionControlWorkspaces` / `GetVersionControlStatus` / `SyncVersionControlWorkspace`。其中 `ConnectProjectToWorkspace` 是全新工具：递归遍历工程树，逐对象询问 `GetSupportedFileFormats`，支持的就纳管。**粗粒度优先**（能整体纳管就不往下拆）， 不支持的对象**逐条报出**而非静默丢弃。默认 `dryRun=true`。 - **`tools/vci-watch/`**：约 300 行的看门狗，程序一改一编译就自动导出、写 CHANGELOG、`git commit`。 只用免费档工具；只读附着、绝不打开工程、绝不写工程、绝不替你编译；无变更时完全静默不产生空提交。 ### 分层调整：按“方向”分，不按“工具”分 免费档现在覆盖**完整闭环**——`CreateVersionControlWorkspace`、`ConnectProjectToWorkspace`、 `GetVersionControlWorkspaces`、`GetVersionControlStatus`，以及 `SyncVersionControlWorkspace(direction='ProjectToWorkspace')`（导出）。 这些**只读工程、只写文本**。唯一需要 Pro 的是 `direction='WorkspaceToProject'` （把 Git 里的版本灌回工程，**会覆盖工程里的块**）。 此前 Create/Connect/Sync 全在 Pro 侧，免费用户能查出"哪些块变了"却建不了工作区、导不出文本 —— 用不起来。 ### 修复 - **`GetVersionControlStatus` 返回的是类型名而不是状态**：`MappedObject.GetStatus()` 返回 `IndividualObjectCompareResult`，直接 `ToString()` 得到类名。改取 `.CompareState` （`Equal` / `Unequal` / `WorkspaceFileMissing` / `Unknown`）。此前整列状态都是无意义字符串。 - **同步会对已一致的对象报错**：Openness 拒绝对状态为 `Equal` 的映射调用 `Synchronize` （`Synchronize cannot be called on a workspace mapping that has a compare status of equal`）， 在一个 345 对象的工程上会一次报出 345 条失败。现在 `Equal` 一律跳过，并在汇总里报出跳过数。 - **代理对象生命周期硬化**：Openness 的调用**一抛异常就会 dispose 掉相关对象**——问一次 "工程支不支持纳管"得到"不支持"，`Workspace` 句柄当场作废，后续全报 `Access to a disposed object`（看着像博途崩了，其实没有）。扫描逻辑现在每次失败后重取句柄。 另外，通用反射桥 `GetComposition` 返回的是**临时代理，拿到即死**，遍历改为类型化。 ### 已知边界（工具会明说，不会假装成功） - **硬件组态进不了 VCI**（设备/模块/子网一律"不支持"），仍需 `.ap21` 备份或 CAx 导出。 - **专有技术保护的块导不出**：`The block is know-how protected. Export is not possible.` - **块改动后必须编译才导得出**：`The block is inconsistent. Compile the block prior to export.` 检测不受影响（未存盘也能检测到），只是导出要等编译。 - **`Unequal` 不等于内容变了**：`git checkout`/`pull` 把文件原样重写（时间戳变）同样判 `Unequal`， 自动化脚本提交前应再看一眼 `git status` 有没有真差异。 ### 验证 真实起重机项目（5 台 PLC、159 MB 工程）：**345 个对象自动纳管**（约 165 秒）， 文本仓 345 个 `.xml` / 22 MB；在博途界面里改块并编译 → 看门狗自动导出并提交，diff 就是那处改动； 反向（从 Git 版本还原回工程）→ 编译 0 错 0 警告。MCP 回归 **287/287**，V20/V21 双编译 0 错 0 警告。

17. v2.4.1 2026-08-20 GitHub 仓库发布 ↗
    原版更新说明

    **这是一个会真实丢数据的缺陷修复，建议 v2.4.0 及更早版本用户尽快升级。** ## 现象 让 AI「新建一个工程」或「打开另一个工程」，结果它把你在博途界面里**正开着、正在改的**那个工程关掉了，**未保存的编辑一起丢**。 ## 根因 两个各自合理的设计叠加： 1. `Connect` 遍历运行中的 TIA 进程时，**优先接管「已经打开了工程」的那个** —— 这对 `AttachToOpenProject` 是正确的； 2. `CreateProject` / `OpenProject` 的第一步都是关闭当前工程。 叠加之后，「新建一个工程」实际执行的是「关掉工程师正在改的那个工程」。 **`Connect` 从来不保证给你一个隔离实例** —— 这是最容易误判的一点。 ## 修复 引擎现在区分「这个工程是不是本会话打开的」。检测到是**用户自己打开**的工程时，`CreateProject` / `OpenProject` **直接拒绝**，并给出两条出路： - 想在那个工程上干活 → 改用 `AttachToOpenProject` - 确实要关掉它 → 显式传 `closeForeignProject=true`（**先问用户**） 护栏放在工具层最前面：工具原本在委托给引擎之前就已经先关了工程，护栏放在下层来不及。 ## 验证 三阶段复现测试： - **A** 引擎建工程后留在 TIA 里并退出 - **B** 引擎全新连接，继承了一个自己没打开的工程（正是出事的场景）→ `CreateProject` 与 `OpenProject` **双双被拒** - **对照检查**：两次拒绝之后工程**仍然开着** —— 证明不是「关完再报错」 - `closeForeignProject=true` 逃生通道正常放行 ## 升级方式 下载下方 zip 解压覆盖，双击 `配置MCP.bat` 重新注册，重启 AI 客户端即可。v2.4.0 的精简工具档位与 `FindTools`/`CallTool` 全部保留。 sha256: `0ec207efc546306c756989d469e38a6ec996b76e23cf0f57f28e268c1a198430`

18. v2.4.0 2026-08-20 GitHub 仓库发布 ↗
    原版更新说明

    本次不是加功能，是把「AI 拿到这个包能不能直接干活」这件事修对。 ## 问题：工具清单本身就是最大的开销 实测本版 V21 引擎： | | 工具数 | `tools/list` 体积 | 每轮 token | |---|---|---|---| | v2.3.2（默认） | 203 | 152 KB | ~38,800 | | **v2.4.0（默认）** | **48** | **33 KB** | **~8,500** | 宿主**每一轮对话**都要把工具 schema 重发给模型。更硬的是兼容性： - VS Code / GitHub Copilot 的 agent 模式**超过 128 个工具直接拒绝加载** - Windsurf 上限 **100** 也就是说，旧的默认档在这两个宿主上根本起不来。 启动本身不是瓶颈：热启 ~770 ms，`tools/list` ~25 ms。 ## 解决：精简档做默认，但留一条通往全部工具的路 **能力一个不少。** 没列出来的 155 个工具随用随取： ``` FindTools("watch table") → 工具名 + 参数签名 + 完整说明 CallTool("ExportPlcWatchTable", "{...}") → 照常执行，与直接调用无差别 ``` 这两个桥接工具本身约 700 tokens，换来全部 203 个工具的可达性。 **不用你交代 AI**：握手指令和 `Bootstrap` 都会说明「你看到的列表不是全部，缺什么先跑 FindTools，别下结论说做不到」。任何宿主、任何模型拿到就会用。 ## 档位怎么切 | 档位 | 怎么开 | 列出工具 | |---|---|---| | 精简（默认） | 什么都不用做 | ~48 | | 完整 | `配置MCP.bat --full`，或 `TiaMcpServer.exe --profile full`，或 `TIA_MCP_PROFILE=full` | 203 | 新增 `--profile lite|full` 命令行参数，优先级高于环境变量；**拼错的值一律退回 lite**，不会静默把宿主顶爆。 ## 其它修正 - **解压后第一次跑 tia.cmd 不再打出 `The system cannot find the path specified.`**：交付包只带 `runtime\v21`，但启动器过去先探 `bin\Release` 必然失败一次，新用户第一眼像是包坏了。改为优先用 `runtime`。 - **发布的 exe 不再嵌入构建机的绝对路径**（Release 不发 .pdb，那条调试记录只剩泄露路径的作用）。 - **交付包体积 11.5 MB → 5.9 MB**：旧包把引擎装了两份（`bin\Release` 一份、`runtime\v21` 一份），本版只留 `runtime\v21`——这也正是「启动器可能跑到另一个更旧的引擎」的根源。 - 引擎版本号补正 2.3.1 → 2.4.0（上一次发布是 v2.3.2，但 exe 里的版本号停在 2.3.1）。 ## 校验 - 全部工具逐个冒烟调用：无崩溃、无服务端掉线 - 桥接反例全部正确失败：错工具名（给出候选，含中间打错字）、非法 JSON、缺参数（打印完整签名）、自递归 - `Validate-Bundle.ps1` 新增引擎桥接门禁；`Check-LiteProfile.py` 修掉一处空跑通过（默认改 lite 后两次探测返回同一份清单，断言全部失效），并已用反例验证它确实会 FAIL - 交付 zip 解压后实跑：`tia 2.4.0.0`，默认 48 工具 **安装**：下载下方 zip 解压，双击 `配置MCP.bat` 即可注册进本机检测到的 AI 客户端。连不上就跑 `tia.cmd doctor`。 sha256: `cdbf54e0a146c300f00ed76e3397fe2cb453498a45ab6ff61de285a86920e603`

19. v2.3.2 2026-08-19 GitHub 仓库发布 ↗
    原版更新说明

    本轮全部围绕「新机装完到第一次跑通」这一段。**工具能力零新增**，全是让现有能力更容易被用对。 > 累积 v2.3.1 与本轮内容（v2.3.1 此前只写进 CHANGELOG 未发布，一并在此发出）。 ## doctor：3 项 → 6 项，中文环境说中文 新机上最常卡住的三件事，此前一件都不查： | 新增检查 | 为什么必要 | |---|---| | **Openness 接口 DLL 能否真解析** | 装了 TIA ≠ 装了 Openness。旧检查只问注册表，于是「体检 OK、首次调用 FileLoadException」。现在复用 resolver 自己的搜索路径去探，两者不会再分叉 | | **MOTW（文件被标记为网络来源）** | 从下载的 zip 解压即中，.NET 拒绝加载 DLL，报错和「你的下载被 Windows 拦了」毫无关系 | | **.NET Framework 4.8** | README 的第一条前置条件 | CLI `tia doctor` 与 MCP `Doctor` 工具改为共用同一套检查，不会再各写一份。 doctor 还会区分「注册了」和「能用」：配置从别的机器带过来、或交付包换了位置，条目还在但 exe 已经不在，宿主只会静默起不来——现在直接报出失效路径并给修复命令。 ## AI 宿主 4 → 8 新增 **Codex(TOML) / Gemini CLI / Windsurf / Cline**。 - Codex 走 TOML 段落合并，保留你已有的其它 server，并写入 `startup_timeout_sec = 120`——TIA 启动远超 Codex 默认的 10 秒，不写会被当成崩溃杀掉。 - JSON 写入改为「临时文件 + 替换」的原子写：写到一半崩掉不会截断你的配置。 - `tia config --host codex|gemini|windsurf|cline`（按名字模糊匹配）；`--print` 也会给出 Codex 片段。 ## 一键配置默认精简档 + lite 补齐金路径（含 2.3.1） - `tia config` 默认写 `TIA_MCP_PROFILE=lite`；要全量工具面显式 `--full`。 - lite 改为**显式工具名白名单**（不再按描述前缀过滤，成员不会随文案变动漂移），并补齐说明书点名的金路径工具：`ImportFromDocuments` / `GenerateBlocksFromExternalSource` / `GetBlocks` / `ExportAsDocuments` / `ImportBlocksFromDocuments` / `ExportBlocksAsDocuments` / `GetPlcTagTables` / `GetCrossReferences` 等，共 46 个，仍远低于 VS Code 的 128 上限。 - 新增 `scripts/Check-LiteProfile.py`，把「lite 必须能走完金路径」变成可执行断言。 ## git clone 开箱即用（含 2.3.1） 全部启动脚本双布局自动回退：先找交付 zip 布局，找不到改用 `runtime\v21`。`Validate-Bundle` 新增启动器哨兵，解析每个 `.cmd`/`.bat` 实际会启动的 exe 并核实存在。 > **V20 用户请注意**：本版交付包为 `TIA_MCP_Delivery_v2.3.2_V21only.zip`，**只含 V21 引擎**——本轮的 V20 二进制 > 尚未重新构建（需要装有 TIA V20 的机器）。V20 用户请继续使用 [v2.3.0](https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/tag/v2.3.0) 的双引擎交付包， > 或自行用 `TiaMcpServer.V20.csproj` 构建；本版的源码改动对两个版本都适用。V20 引擎补齐后会另发一版。 ## LAD 指南补三条（均以 1052 个真实 .s7dcl 语料核过） - 每个 NETWORK 前必须有独立 `{ S7_Language := "LAD" }` pragma——**10147/10147 个网络无一例外**；缺了报 `Syntax error 'NETWORK' expecting END_FUNCTION_BLOCK`。 - `P_Trig(mem)` 一个参数，`P_Contact(signal, mem)` 两个参数，不可混用。 - 泛型指令模板名随指令而异（实见 `SrcType`/`DestType`/`time_type`/`date_type`/`str_type`），报错会列出 `Allowed Template Names`，照读即可。 ## 修复 - `DownloadToPlc` 在多网卡机器上选错 PG/PC 接口（#14）：改为按 IP 同网段排序选路，可用 `pgPcInterface` / `targetIpAddress` 显式指定，`CheckDownloadReadiness` 的 `meta.downloadRoutes` 可先行诊断。排序只用于**排序**，绝不否决下载。 ## 分支体例 新增官方 `v21` / `v20` 分支（与 v16~v19 同体例）。双版本共用的改动仍进 `master`，只有版本专属适配才进版本分支。

20. v2.3.0 2026-07-04 GitHub 仓库发布 ↗
    原版更新说明

    回应"分析慢/准确率低/只敢用 SCL 躲梯形图"的痛点——加一个让模型/人像读 SCL 一样读 LAD 的工具： - **新工具 `DescribeBlockLogic(softwarePath, blockPath)`**［L1，lite 档也含］：导出块后把每个 LAD 网络**重建成可读的能流表达式**——串联触点用 `·`、并联用 `+`、常闭显示 `/操作数`；线圈 `( )/(S)/(R)`、MOVE/比较/定时器盒带管脚操作数；SCL/STL 网络内联成代码。**关键**：自动标注接到字面常量的触点——`⟨恒断·禁用本行⟩`(常开触点接 FALSE=永久断开、静默禁用整行，肉眼几乎看不出)、`⟨恒通⟩`(恒导通旁路)。比导出 FlgNet XML 手工追线又快又准。 - 实证：对 5T车 原生 `Auto_SpeedSet`(LAD+SCL+STL 混编)一眼标出"初始化切换"里被恒 FALSE 触点禁用的 `0006/0007` 握手行(`TP(..).Q · 0 ⟨恒断·禁用本行⟩`)——正是之前手工追半天才发现的坑；复位行 `MOVE 16#04FE` 无禁用标记=有效。端到端(测试PLC/FC_Alarm)输出 `"DemoData.HighAlarm" ( ) ⇐ ("DemoData.Temp" >= "DemoData.Limit")`。 - ServerInstructions 与 GetAuthoringGuide('lad') 补指引：**读 LAD 用 DescribeBlockLogic，别手解 XML**。 - 纯只读、Siemens-free 渲染器(`LadTextRenderer`)，工具数 200→201。V20/V21 双编译 0 错，渲染器离线对真实块 + 端到端各验证一遍。 --- **同时包含 v2.2.9 修复**：ImportFromDocuments 嵌套组不再失败/丢块号 + 导入导出错误上抛真实原因。 **下载** `TIA_MCP_Delivery_v2.3.0_20260704.zip`（V21/V20 双 exe）：解压→双击 `配置MCP.bat` 一键注册；读梯形图让 AI 调 `DescribeBlockLogic`；排障 `tia.cmd doctor`。

21. v2.2.8 2026-07-04 GitHub 仓库发布 ↗
    原版更新说明

    围绕「外部环境部署 + 弱 AI + 出错率」（lite 档位与 Doctor 此前只存在于 SKILL 文档、代码在迁仓时丢失，本版补齐并超越原实现）： - **lite 工具档位（弱模型/受限宿主）**：`TIA_MCP_PROFILE=lite` 环境变量生效——`tools/list` 只暴露 [L0]/[L1] 共 42 个核心工具（full=200），弱模型不再被 200 个工具淹没，VS Code 的 128 工具上限也不再爆。一键写入：`tia config --lite`（宿主配置里自动带 `env`），GUI 配置向导同步提供勾选。stdio 实测 full=200 / lite=42、核心工具（Bootstrap/Connect/GetProjectTree/ScaffoldProject/CompileSoftware/SaveProject/Doctor）全在。 - **`Doctor` 工具回归 + 新 CLI `tia doctor`**：MCP 工具版一次体检 TIA 安装/Openness 用户组/连接与项目状态，逐项给出精确修法，`fix=true` 自动补 Openness 组；**CLI 版 `tia doctor [--fix]` 在 MCP 宿主根本起不来 server 的时候也能用**（正是最需要体检的场景），额外检查 exe 编译版本与本机 TIA 版本匹配、四宿主配置是否已注册。stdio 调用与 CLI 实测输出正确。 - **启动失败不再无声**：TIA 未装（Openness 初始化 FileNotFound）与用户不在 Openness 组两条失败路径，stderr/日志给出中英文修复指引（指向 `tia doctor`），后者退出码从 0 改为 2，MCP 宿主能感知失败。 - **写操作默认干跑（约束加强）**：`ScaffoldProject` 的 `dryRun` 默认值 false→**true**——默认调用只做离线校验、不连 TIA 不建工程，干跑干净后需显式 `dryRun=false` 才真跑；干跑结果消息里明确指引下一步。与 ServerInstructions「永远先 dryRun」铁律一致，弱模型一把梭建废工程的路径被堵死。（行为变更：依赖旧默认值的调用方需显式传 `dryRun=false`。） - **VS Code 工具校验修复随本版 exe 发布**（源码 38043e9 已在 master）：`InvokeObject`/`InvokeService` 数组入参 schema 补 `items`，VS Code 不再拒收。 - **配置脚本加固**：`配置MCP.bat`/`配置MCP-v20.bat` 先检查引擎 exe 存在（防"只拷了 bat"），完成后提示 `--lite`/`doctor`/`--print` 三条路。 - 验证：V20/V21 双编译 0 错；stdio 握手实测（full/lite 工具数、Doctor 诊断内容、instructions 下发）；`tia doctor`/`tia config --print --lite` CLI 实测。 --- **下载**：`TIA_MCP_Delivery_v2.2.8_20260703.zip`（含 V21/V20 双 exe，解压后双击 `配置MCP.bat` 一键注册进 Claude Desktop / Claude Code / Cursor / VS Code；弱模型加 `--lite`；排障跑 `tia.cmd doctor`）。

22. v2.2.7 2026-07-02 GitHub 仓库发布 ↗
    原版更新说明

    两个真实用户痛点的系统性修复：①配置要人肉填路径/版本（issue #9）②非 Claude 的 AI 生成代码质量差、耗时长。 ## 降门槛 - **版本自路由（修 #8 根因）**：拿错 exe 不再崩——exe 启动时按实际 TIA 版本自动转投旁边的兄弟 exe（V20↔V21，stdio 继承，MCP/CLI 全程无感） - **修多版本机器程序集解析劫持**：`TiaPortalLocation` 环境变量不再压过版本专属注册表（V20+V21 双装机器上 V20 exe 报 "Could not find DLL for version 20" 的根因） - **`tia config` 一键配置扩到 4 宿主（修 #9）**：Claude Desktop / Claude Code / Cursor / **VS Code** 全自动写入——自动发现自身路径、注册表版本、版本匹配的 exe；只写检测到的宿主；`--print` 出双 schema 片段 ## 提生成质量（其它 AI 也能写对代码） - **initialize 下发 instructions**：黄金路径 + BOM 编码规则 + 纪律，所有 MCP 客户端自动注入（不再依赖 SKILL.md） - **新工具 `GetAuthoringGuide(topic)`**：workflow/scl/lad/db/hmi/errors 六主题已验证语法速查，模型写码前一次拿全约束 - Bootstrap OperatingRules 补齐写码前置 ## 验证 双编译 0 错；V20 exe 自路由真机实测；config --print 实测；MCP 握手实测（199 工具 + instructions 下发 + 指南内容正确）。 ## 附件 `TIA_MCP_Delivery_v2.2.7_20260702.zip`（17.2MB）= 源码 + V20/V21 双 exe（均 2.2.7） > 含 v2.2.6 的全部内容（god-file 拆分重构 + CLI describe 增强 + Claude Code 插件清单），见 CHANGELOG。

23. v2.2.4 2026-06-15 GitHub 仓库发布 ↗
    原版更新说明

    降低上手门槛——**无需第三方软件、无需手改配置文件**，把本 MCP 一键注册进 AI 宿主。 ### 新增 - **`tia config` 子命令**：自动把 `tia-portal` 写进 **Claude Desktop / Cursor** 配置——填入**正确的 exe 绝对路径**（不再有 `REPLACE_ME`）+ **自动检测的 TIA 版本**；**合并**进现有配置（保留你已有的其它 MCP server），原文件自动备份为 `*.bak`。 - `tia config`（写全部已知宿主）/ `--host claude|cursor`（指定其一）/ `--print`（只打印片段，供 Claude Code 等手动粘贴）。 - **双击脚本**：交付包根目录的 `配置MCP.bat`（V21）/ `配置MCP-v20.bat`（V20），双击即配。 ### 取代 原先要手动改 `cursor-mcp.example.json` 里的 `REPLACE_ME`、自己找配置文件位置、自己合并——现在一步搞定。 ### 验证 V20/V21 编译 0 错；`config --print` 真机输出正确（自动 exe 路径 + 版本）；合并/备份/幂等逻辑单测通过。纯新增，不改动现有工具与行为，工具数不变（189）。 交付包 `TIA_MCP_Delivery_v2.2.4_20260615.zip` 解压后双击 `配置MCP.bat` 即可。

24. v2.2.3 2026-06-15 GitHub 仓库发布 ↗
    原版更新说明

    针对"较弱的 AI 驱动本 MCP 时仍会出 bug"的反馈，从源头降低出错与卡死。**工具数不变（189），无破坏性改动。** ### 改进 - **自愈连接/绑定**：调用工具前忘了 Connect/Attach 时——若本机已有 TIA 在运行，自动附加并绑定其已打开的工程；已连接但未绑定则自动重绑；本机无 TIA 在运行则不擅自启动、直接给可执行提示。修复了"不按顺序调用→原始空引用崩溃"。 - **可恢复的错误指引**：新增异常翻译器（`McpHints`），按异常链识别 7 类常见失败（未连接 / 无工程 / 工程已被打开 / 名称路径错→提示查 GetProjectTree·GetSoftwareTree / TIA 版本不匹配 / Openness 用户组 / know-how 保护），统一注入 185 处通用 catch。错误从"只报原始异常"变为"告诉 AI 下一步该做什么"。 - **首调操作规则**：`Bootstrap` 新增 `OperatingRules`（调用顺序 / 写后必 Compile+Save / 名称要精确 / 读错误照做 / 大任务用 ScaffoldProject）。宿主即便不加载 SKILL.md，AI 第一次调用就拿到正确用法。 - **更清晰的前置错误**：误导性的 "No project is open" 改为可执行指引。 ### 验证 - V20 / V21 编译 0 错；翻译器离线单测 7/7 通过；对构建产物 stdio smoke test 通过（189 工具、5 条 OperatingRules）。 > 注：v2.2.2 已被既有的「S7DCL skill 文档」Release 占用，故本代码版本顺延为 2.2.3（已包含该 skill 文档内容）。 交付包 `TIA_MCP_Delivery_v2.2.3_20260615.zip` 含 V20+V21 双 exe + 完整源码 + skill + 模板，解压即用。

25. v2.2.2 2026-06-11 GitHub 仓库发布 ↗
    原版更新说明

    ## v2.2.2 — S7DCL LAD/SCL 混编授权法（规范/文档 + 已验证样板） **纯文档/技能更新，无代码或工具改动**（LAD/S7DCL 相关工具早已具备：`ImportFromDocuments`/`ImportBlocksFromDocuments`/`ExportAsDocuments`/`ComposePlcLadFcBlockXml` 等）。本版把"如何正确用 `.s7dcl` 授权 LAD 及 LAD/SCL 混编"的实战知识固化进 skill。 ### 更新内容（`tools/tiaportal-mcp/skill/SKILL.md §9a`） - **关键纠错：LAD 导入语法 ≠ 导出语法。** 导入须用 `GT/LT/EQ/NE_Contact{ SrcType }( in1:=, in2:= )`、`P_Trig( #bit )`、`Move( in:=, out1=> )`；从导出文件抄来的 `Gt/Lt/Ne/Eq`、`PBox`、`Move{ Card; DisableENO }` 会导入失败。新增"导入 vs 导出"指令对照表。 - **逐网络 LAD/SCL 判断准则（不强行 LAD）**：互锁/限位/抱闸/工步/指示→LAD；算术/调用/状态机/通信/复杂条件→SCL。 - **LAD+SCL 混编已验证**：`S7_PreferredLanguage:="LAD"` 的块可逐网络插入 `{ S7_Language:="SCL" }` 网络。 - 纠正导入工作流为 `ImportFromDocuments`/`ImportBlocksFromDocuments` + `CompileAndDiagnosePlc`（含 `.s7res`/UTF-8 BOM/`Override` 保号要点）。 - 标题须 `MLC_*` 引用或省略（内联中文标题会导入失败）。 ### 新增样板 - `tools/tiaportal-mcp/skill/lad-cookbook/MCPVerify_Mixed_LADSCL.s7dcl(+.s7res)` —— 自包含的 LAD+SCL 混编 FB 模板（方向互锁 / 比较+定时 / SCL 算术 / 边沿），全用 import-verified 形式，导入编译 **0 错**。 ### 实证 江夏 5T车 V21：7 个块（02/03/04/09 手动 + A3_2/3/5 机构）按"逐网络判断"重做为 LAD/SCL 混编，全工程编译 0 错；A0_1/A4_1/通信类按判断保留 SCL。

26. v2.2.1 2026-06-09 GitHub 仓库发布 ↗
    原版更新说明

    ## v2.2.1 — v2.2.0 在线工具真机验证 + 因果溯源在线模式消息修复 v2.2.0 新增的 3 个在线只读监控工具已在**真实 PLC（CPU 1211C @ 192.168.0.32）**端到端验证通过，并修复了真机验证中发现的一个消息误导问题。工具数不变（**189**，全部 `[L2]` 只读）。 ### 真机验证结果 - **`GetPlcRunStateS7`** — 正确读到 `RUN`；该 1211C 的 SZL 诊断缓冲不可用时按设计**干净降级**（仍给出 RUN/STOP）。 - **`SamplePlcLiveValuesS7`** — 采样 DB34 心跳/标志位，时间序列与 `min/max/avg` 正确（心跳随时间递增）。 - **`TraceTagCauseLive`** — 离线追溯 `EMG_STOP`，正确命中其在 `Crane_Communication` 网络4 的赋值及两个门控条件，并正确判定门控操作数为 DB 成员（无绝对地址 → 提示用 OPC UA 符号读）。 ### 修复 `TraceTagCause` / `TraceTagCauseLive`：当 TIA 与 PLC **在线连接**时，Openness 无法导出块（`Export ... not supported in online mode`）。此前所有块导出失败仍报 `No block writes 'X'`，会误导为"解析后无写入"。 - 新增 `analyzedBlockCount` 字段；当无任何块成功导出时返回 `INCONCLUSIVE`，并在在线模式失败时提示**先在 TIA 转至离线再重试**（S7 实时读为独立直连，不受转离线影响）。 - 两个工具的 Description 补充该离线导出前置条件。 ### 包含 - 双运行时：`TiaMcpServer.exe`（V21）+ `bin-v20`（V20），net48。 - 完整源码、Skill 规格、静态工具表、能力矩阵、PLC/HMI 模板、一键工程蓝图、手册。 > 免费开源（MIT），无许可证密钥。运行需 Windows + .NET Framework 4.8 + TIA Portal V20/V21，当前用户加入 `Siemens TIA Openness` 本地组。

27. v2.1.0 2026-06-09 GitHub 仓库发布 ↗
    原版更新说明

    TIA Openness 是工程接口，读不到运行中 CPU 的实时值。本版新增一条独立于 Openness 的**运行时只读通道**，直连 CPU 读实时值。 ## 新增 5 个工具（全部 [L2]，纯只读：不写 / 不强制 / 不改运行模式），工具数 181 → 186 - **ReadPlcLiveValuesS7** / **ProbeS7CpuIdentity** — S7 协议（ISO-on-TCP, 端口 102），绝对地址 `DB34.DBD116:DINT` / `M0.0` / `IW76`，单次几十~几百 ms。`expectModuleContains` 身份护栏。S7-1200/1500 需开 PUT/GET 且读非优化 DB。 - **ReadPlcLiveValuesOpcUa** — OPC UA（端口 4840，匿名无加密），会话按 endpoint 缓存复用（首次 ~1.7s，之后 ~150-220ms），失效自动重建一次；对锁的等待有界，避免不可达服务器导致后续调用堆积。 - **MonitorWatchTableLiveS7** — 经 Openness 取已有监控表条目地址（只读）+ S7 实时读，按 TIA `DEC_signed` 显示格式映射有符号类型。 - **TraceTagCause** — 离线静态溯因：导出代码块解析 SimaticML（LAD 线圈 S/R/= 与 ST 的 `:=`），找写入网络 + 门控条件操作数，再用 ReadPlcLiveValuesS7 实时读判断当前由谁驱动。 每个响应都带 `safety` 自证字段。真机（CPU 1211C @192.168.0.32）S7 / OPC UA / 监控表三法与博途显示逐字节交叉核对一致。双构建 V20/V21 均 0 错，FileVersion 2.1.0，runtime tools/list 实测 186。 中文使用指南见 `docs/在线实时读值_使用指南.md`。 ## 下载 `TIA_MCP_Delivery_v2.1.0_20260609.zip`：完整源码 + V20/V21 双 exe（含 .exe.config 与 Sharp7 / Workstation.UaClient 依赖）。解压即用。

28. v2.0.2 2026-06-08 GitHub 仓库发布 ↗
    原版更新说明

    V20 兼容性修复小版本（修复 GitHub issue #2）。仍为双 V20/V21 binary、MIT。工具数 180 → **181**（新增 1 个离线工具）。 ## 修复 — V20 导入标签表报 `The engineering version 'V21' ... is not supported` `Portal.ImportPlcTagTable` 现在统一走 `PrepareXmlForImport`，把硬编码的 `<Engineering version="V21"/>` 头改写为当前连接的博途版本（并补 UTF-8 BOM）。此前块 / 类型导入已做此处理，唯独标签表漏过滤，导致 V20 上 `PlcBuildAndImport` 生成的变量表被 Openness 拒绝。 ## 新增 — `WritePlcSclSourceFile`（离线，第 181 个工具） 把 SCL 源文本写成本地 `.scl` 外部源文件（**UTF-8 带 BOM**，中文注释不乱码）。不连接博途、不导入，只落盘并返回路径与手动导入指引。 作为 V20 用户的稳妥后路：当 FC 逻辑块 XML 因 `Cannot create SW.Blocks.CompileUnit... token not supported`（V21 SimaticML 令牌）被 V20 拒绝时，改用博途「外部源文件 → 从源生成块」手动导入，绕开严格的 XML 令牌校验。 --- 下载 `TIA_MCP_Delivery_v2.0.2_20260608.zip`，解压即用（含双 V20/V21 exe + 依赖 + tia.cmd）。

29. v2.0.1 2026-06-04 GitHub 仓库发布 ↗
    原版更新说明

    安全与隐私小版本，无行为变更、无新工具（仍 180 工具、双 V20/V21 binary、MIT）。 ## 安全 — 修复 XML 外部实体注入（XXE） 导入/解析 XML 工程产物（块 / 画面 / 变量表 / 监控表）的 6 处 `XmlDocument.Load(...)` 之前统一设置 `XmlResolver = null`，禁用外部实体与 DTD 解析。修复在 .NET Framework 4.8 上导入**第三方恶意 XML 文件**时可被 XXE 利用（本地文件读取 / SSRF / billion-laughs DoS）的风险。`XDocument.Load/Parse` 路径默认 `DtdProcessing.Prohibit`，本就安全。 ## 隐私 — 移除源码中的开发机个人路径 清除 `Program.cs` 中 11 处硬编码的作者机器路径，改为中性兜底（`Directory.GetCurrentDirectory()` / MyDocuments）。仅出现在 `--run-*` 开发者自测处理器，正常 MCP/CLI 运行不受影响。 下载 `TIA_MCP_Delivery_v2.0.1_20260604.zip`，解压即用（含双 exe + 依赖 + tia.cmd）。

30. v2.0.0 2026-06-03 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- 声明式 `tia` 命令行大版本：同一个 exe 既是 MCP 服务，也是命令行。任意 AI 产出一份 YAML/JSON spec，任意工程师跑一条命令即可从零建/改博途工程——无需 MCP 客户端、无需安装。 ## 亮点 - `tia gen <spec>`：一条命令从 spec 建完整工程（PLC+HMI+UDT/DB/标签表+SCL/LAD+编译+保存）。 - `tia patch <spec>`：增量 upsert 进已有工程。 - 还有 `compile/describe/export/import/prewarm/schema`，退出码 0/1/2。 - YAML + JSON 双解析；`--dry-run` 离线校验；`--json` 机器可读。 ## 上手优化（本版） - **`tia` 命令入口**：根目录 `tia.cmd`(V21)/`tia-v20.cmd`(V20)，加 PATH 即可随处 `tia gen`。 - **模板开箱即用**：自动解析 spec 里的 `__BUNDLE__`，现成启停/电机模板无需手改路径。 - **修复相对工程路径**；`.bat` V21 缺失自动回退 V20。 ## 验证 - live 实机回归全过（真连 TIA V21）：`tia gen` 16/16 步、编译 Success 0 错；patch/compile/describe/export/import/prewarm 全 rc=0。 - 双 V20/V21 binary、0 编译错误。 仍是完整 MCP 服务（`tia` verb 之外行为不变），CLI 与 MCP 共享同一引擎。 交付 zip：`TIA_MCP_Delivery_v2.0.0_20260603.zip`（源码 183 + 双版本 exe/依赖 116，6.07MB）。

31. v1.0.0 2026-06-02 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- 首个 1.0 大版本，聚焦「快、好用、不出错」。 ## 性能 - **默认 headless 启动**：冷启动约 200–340s → 约 10–28s（全量回归 21/21 通过，含 WinCC Unified HMI）。需 GUI 检查时启动加 `--with-ui`。 - **常驻实例（可选）**：`python scripts/prewarm_tia.py` 保活后，后续会话 Connect 约 0.8–1s。 ## 新工具 - **`ScaffoldProject`（L1）**：单个 JSON spec 一次调用生成完整工程（建项目→PLC/HMI 硬件→UDT/DB/标签表→SCL/LAD→编译→HMI 连接/画面/变量→保存）。支持 `dryRun=true` 离线校验。现成模板：`scaffold_spec_start_stop.json`（启停）、`scaffold_spec_motor.json`（电机）。 ## 可靠性 - HMI 软件路径自动探测（不再写死 `HMI_RT_1`） - 连接对挂死/孤儿 TIA 实例加超时跳过 - 单块导入回读校验（`Meta.verified`） ## 工具收敛 - 184 → **180**：下线 4 个 `Export*ToTemp` 变体 + 易混 Export/Import 工具补消歧描述 ## 安装 解压附件 zip，把 MCP 配置 `command` 指向包内 `tools/tiaportal-mcp/src/TiaMcpServer/bin/Release/net48/TiaMcpServer.exe`（V20 用 `bin-v20/Release/net48/`）。需 Windows + TIA Portal V20/V21 + .NET 4.8。

32. v0.0.40 2026-06-02 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- ## 0.0.40 ### 示例库质量 - 5 个 `scl-examples/*.scl` 重写：块头说明 + 每个接口变量（VAR_INPUT/OUTPUT/VAR）逐行中文注释 + 逻辑分区注释；逻辑更丰富（运行/剩余/完成百分比、限幅、方向、偏差%）。 - `FB_TimerCounterDemo` 用静态累计器消除"输出未初始化"告警 → 编译 0 错 0 警。 - `UDT_BasicStatus` / `DB_BasicStatus` 每个成员补 `commentZhCn` 中文注释。 ### 仓库管理 - 编译产物（exe/DLL/.config）移出 git 跟踪，改由本 Release zip 分发；消除"clean 误删 tracked 二进制 → MCP 启动崩溃"隐患。 ### 交付包 `TIA_MCP_Delivery_v0.0.40_20260602.zip` 含完整源码 + V21/V20 双 exe（0.0.40）+ 配置。clone 仓库需自行 build 或用本 zip。

33. v0.0.37 2026-05-31 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- ## 错误处理统一（E） 将 6 个错误域（Connect / Hmi / PlcGen / Compile / Import / AddDevice）的失败信号从 `return false/null` + 可变 `LastXxxError` 侧信道，统一为 `throw PortalException(code, msg)`，工具层统一 `catch (PortalException)` → `McpException`（结构化错误码进消息）。 - 删除 5 个侧信道字段（`LastHmiError`/`LastPlcGenError`/`LastCompileError`/`LastImportError`/`LastAddDeviceError`）；`LastConnectError` 故意保留（喂 Bootstrap 诊断 + OpenProject/OpenSession 共用失败分支）。 - `throw PortalException` 19→90，`catch (PortalException)` 1→28；仅改 `Portal.cs` + `McpServer.cs`，净减 ~94 行。 - 批量导入逐项 `try/catch` 收集 `ImportFailure`，并修正了块/类型导入原先"一条失败中断整批"的不一致。 - 重建 V20/V21 双版本 exe（0.0.37，0 错误）。 > 本版同时包含 0.0.36（A：移除 4 个纯别名工具，削减工具表面）—— 0.0.36 未单独发布。 详见 CHANGELOG.md。zip 为仓库 tracked 内容（含双版本预编译 exe）。

34. v0.0.35 2026-05-31 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- -

35. v0.0.34 2026-05-31 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- -

36. v0.0.33 2026-05-28 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- TIA Portal MCP Server v0.0.33 (V20 + V21). ## 本次改进 - **去除内部"商业"措辞**：发布质检工具 `CommercialReadinessGateBuilder` → `ReleaseReadinessGateBuilder`，相关 JSON 键/Markdown 标题统一改为中性的 "Release Readiness Gate"（行为不变）。 - README 删除过时的"商业锁"说明（自 v0.0.32 起仓库已无任何授权代码，纯 MIT 开源）。 （延续 v0.0.31 的版本能力层 / Did-you-mean / HTTP 修复，及 v0.0.32 的商业授权移除。） ## 交付包 - `TIA_MCP_Delivery_v0.0.33_20260528.zip`：完整离线交付包（V20/V21 预编译 exe + skill + 模板 + 文档）。

37. v0.0.32 2026-05-28 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- TIA Portal MCP Server v0.0.32 (V20 + V21). ## 本次改进 - **移除商业授权脚手架**：删除 `CommercialLicense.cs`（机器码 / RSA license / `commercial.lock` 启动拦截）及 `--license-machine-code`、`--license-check` 两个 CLI 标志。仓库现为**纯 MIT 开源**，无任何授权代码，无需 license key。 - 重建 V20/V21 exe（serverVersion=0.0.32，0 错误），启动正常、版本能力门控不变。 （功能延续 v0.0.31：版本能力层 / Did-you-mean / HTTP transport 修复。） ## 交付包 - `TIA_MCP_Delivery_v0.0.32_20260528.zip`：完整离线交付包（V20/V21 预编译 exe + skill + 模板 + 文档 + manifest）。 详见 CHANGELOG.md。

38. v0.0.31 2026-05-28 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- TIA Portal MCP Server v0.0.31 (V20 + V21). ## 本次改进 - **版本能力层**：新增 `Capability` 单一真源 + `Bootstrap` 的 `Capabilities` 字段；模型一上来即知当前 TIA 版本支持哪些功能（V21 支持硬件 HMI 连接，V20 不支持）。新增错误码 `NotSupportedOnVersion`。 - **Did-you-mean**：块/类型找不到时返回候选名（`ExportBlock` 已有，新增 `ExportType`）。 - **HTTP transport 修复**：此前 `POST /mcp` 因异步 I/O 在 HttpListener 上挂起而永久阻塞，现改为同步 I/O + 30s 超时返回 504；curl 端到端实测通过。 ## 交付包 - `TIA_MCP_Delivery_v0.0.31_20260528.zip`：完整离线交付包（含 V20/V21 预编译 exe、skill、模板、文档、manifest）。 - 免费开源（MIT），无需 license key。运行时 `tools/list` 为工具清单权威来源。 详见 CHANGELOG.md。

39. v0.0.30 2026-05-28 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- **Fix**: Openness imports are now normalized to the connected portal version, so importing into **TIA Portal V20** no longer fails with `The engineering version 'V21' ... is not supported`. Applies to `ImportBlock` / `ImportType` / `PlcBuildAndImport`. **Also in this release** - Full source committed (the repo now compiles from source; CI builds V20 + V21). - Rebuilt **V20** (`bin-v20/Release`) and **V21** (`bin/Release`) executables, both `FileVersion 0.0.30`, end-to-end verified against live TIA V20 and V21. - MIT licensed; English `README.en.md` added. **Asset**: `TIA_MCP_Delivery_v0.0.30_20260528.zip` — prebuilt bundle (both exes + full source + docs + templates). Pick the exe by TIA version; see README. 修复：导入按所连博途版本归一化 `<Engineering version>`，V20 不再报 "engineering version 'V21' is not supported"。含完整源码、V20/V21 双 exe（均 0.0.30，实测通过）、MIT 协议、英文 README。

40. v0.0.29 2026-05-26 GitHub 仓库发布 ↗
    原版更新说明

    > ⚠️ **此历史版本的下载包已下架。** 请使用最新版 → https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases/latest （v2.0.1，已修复 XXE 并清理）。 --- ## v0.0.29 完整离线交付包 - **V21 运行时**: `tools/tiaportal-mcp/src/TiaMcpServer/bin/Release/net48/TiaMcpServer.exe` - **V20 运行时**: `tools/tiaportal-mcp/src/TiaMcpServer/bin-v20/Release/net48/TiaMcpServer.exe` - 含模板、文档、Skill、源码；解压即用，无需再编译 - 相对 v0.0.28：仓库纳入双版本 exe/DLL；本 Release 附 `TIA_MCP_完整交付包_v0.0.29.zip` 详见 [CHANGELOG.md](CHANGELOG.md)。

当前收录版本

introduction-20261106

核对来源版本 ↗

安全评级与访问范围

caution · 静态证据核验，不代表运行安全保证。

使用前请由宿主核对并授权实际文件读写、外部服务和联网目的地；本站的核验不会授予任何运行权限。