TiaCommander

TiaCommander — Siemens TIA Portal 的 MCP 服务

版本	3.42.0
协议	MCP 2024-11-05 (stdio)
运行时	.NET Framework 4.8
TIA Portal	V17 – V20（Openness API，已在 V19 上测试）
许可证	专有（免费 Beta 版）

此版本新增内容： 全新的 technology_objects 工具，包含 15 项操作，可用于列出和读取工艺对象、更改参数、进行结构编辑、导出/导入，以及将对象连接到其硬件；支持按项目设置 PLC 凭据，并在 Manager 中新增 Credentials 选项卡——优先尝试项目自身的密码，失败时再使用全局密码；支持事务式覆盖块——导入前先导出块，如果导入失败则还原，并且覆盖时不再丢失属性、块编号或文件夹位置；编译器结果仅列出实际诊断，因此总数始终与编译器自身的计数一致。自 v3.15.2 以来还有数十项修复和改进——完整列表请参阅 CHANGELOG.md。

* 支持将 V17 至 V20 用于项目工作。检测到 V16 及更早版本时会明确提示并拒绝使用。只有 V19 经过全面测试；其他版本预计也能正常工作，因为 TIA Portal 在不同版本间保持 Openness API 向后兼容。

---

概述

TiaCommander 是一款通过 Openness API 将 AI 助手连接到 Siemens TIA Portal 的 MCP 服务。它可通过自然语言实现 AI 辅助 PLC 编程、项目管理、库操作、硬件配置、交叉引用分析和部署。

已测试的 AI 客户端： Claude Desktop、Claude Code、VS Code (Copilot)、Cursor、Windsurf、Codex CLI、Gemini CLI。

19 个工具、230 项操作，涵盖 TIA Portal 项目的完整生命周期。

工具	功能
admin	服务管理、使用统计、导出存储
alarm_text	报警文本和文本列表、XLSX 导入/导出
blocks_read	读取、检查和导出 FB / FC / OB / DB 块（XML、SCL）
blocks_write	创建和导入块（SCL、LAD、FBD、STL）
db	全局和实例数据块成员及值
diagnostics	连接设置、在线/离线比较、PLC 状态
download_upload	编译检查后下载到 PLC / 从 PLC 上传
folders	浏览和整理项目树中的组
get_info	服务功能和版本
hardware	设备、机架/插槽、网络和 I/O 配置
library	主副本、库类型、版本化实例化
live_data	运行中控制器的实时值和 CPU 诊断信息
open_manager	打开 TiaCommander Manager 窗口
session	打开、保存、归档和切换项目；连接生命周期管理
tag	PLC 标签表：创建、编辑、搜索、分配地址
technology_objects	轴和其他工艺对象：读取、调整、连接到硬件
udt	用户定义类型：创建、编辑成员、导入/导出
watch	监视表和强制表
xref	交叉引用：调用方、未使用的块、孤立的实例 DB

---

下载内容是什么？

TiaCommander-v3.42.0-portable/
├── bridge/                              ← Live PLC data helper (S7CommPlus / TLS)
│   ├── libcrypto-3-x64.dll
│   ├── libssl-3-x64.dll
│   ├── S7CommPlusDriver.dll
│   ├── TiaCommander.S7Bridge.exe
│   ├── TiaCommander.S7Classic.dll
│   └── zlib.net.dll
├── data/
│   └── exports/                         ← Export output folders
│       ├── alarm_text/
│       ├── hardware/
│       ├── tag/
│       └── watch/
├── docs/
│   ├── configs/
│   │   ├── claude_code.txt
│   │   ├── claude_desktop_config.json
│   │   ├── codex_cli_config.toml
│   │   ├── cursor_mcp.json
│   │   ├── gemini_cli_settings.json
│   │   ├── generic_stdio.json
│   │   ├── vscode_copilot_mcp.json
│   │   └── windsurf_mcp_config.json
│   ├── 1-QUICKSTART.md
│   ├── KNOWN_LIMITATIONS.md
│   ├── LICENSE.txt
│   ├── README.md
│   └── THIRD-PARTY.md
├── help/
│   ├── github-offline.html
│   └── readme-offline.html
├── licenses/                            ← Full third-party licence texts
│   ├── Apache-2.0.txt
│   ├── BSD-3-Clause.txt
│   ├── GPL-3.0.txt
│   ├── LGPL-3.0.txt
│   ├── Microsoft-WebView2-SDK.txt
│   ├── MIT.txt
│   └── Polyform-Noncommercial-1.0.0.txt
├── Resources/
│   ├── logoBlack.png
│   └── tiacommander.png
├── runtimes/                            ← WebView2 native loaders
│   ├── win-x64/native/WebView2Loader.dll
│   ├── win-x86/native/WebView2Loader.dll
│   └── win-arm64/native/WebView2Loader.dll
├── Templates/                           ← Block XML, alarm & diagnostics templates
│   ├── diagnostics/
│   │   ├── TC_Diag_1200.xml
│   │   └── TC_DiagOB.xml
│   ├── Fb.xml
│   ├── Fc.xml
│   ├── GlobalDb.xml
│   ├── Ob.xml
│   ├── Ob_FBD.xml
│   ├── Ob_LAD.xml
│   ├── Ob_SCL.xml
│   └── TextListTemplate.xlsx
├── x64/                                 ← SQLite native library (64-bit)
│   └── SQLite.Interop.dll
├── x86/                                 ← SQLite native library (32-bit)
│   └── SQLite.Interop.dll
├── CHANGELOG.md
├── EPPlus.dll
├── EPPlus.Interfaces.dll
├── icon.png
├── manifest.json
├── Microsoft.Bcl.AsyncInterfaces.dll
├── Microsoft.IO.RecyclableMemoryStream.dll
├── Microsoft.Web.WebView2.Core.dll
├── Microsoft.Web.WebView2.WinForms.dll
├── System.Buffers.dll
├── System.ComponentModel.Annotations.dll
├── System.Data.SQLite.dll
├── System.IO.Pipelines.dll
├── System.Memory.dll
├── System.Numerics.Vectors.dll
├── System.Runtime.CompilerServices.Unsafe.dll
├── System.Security.Cryptography.Xml.dll
├── System.Text.Encodings.Web.dll
├── System.Text.Json.dll
├── System.Threading.Tasks.Extensions.dll
├── THIRD-PARTY-NOTICES.md
├── TiaCommander.exe                     ← MCP server + Manager GUI
└── TiaCommander.exe.config

无需安装程序，不会更改注册表，也不会修改系统。解压、配置并运行即可。从 GitHub Releases 下载最新的 .zip 文件。

**Claude Desktop 用户：**从 Releases 下载 .mcpb 包，然后通过“设置 → 扩展 → 高级设置 → 安装扩展”进行安装。无需编辑配置文件。详情请参阅快速入门指南。

前置条件：必须在你的计算机上安装 Siemens TIA Portal V17 或更高版本，并启用 Openness 组件。TiaCommander 会在运行时直接从你的 TIA Portal 安装目录加载 Siemens Openness 库。若未安装 TIA Portal，服务将以降级模式启动，功能有限，并引导你完成设置。

---

为什么要开发这个工具？

首先，我们是软件开发人员和自动化工程师，每天都在自己的工厂、客户现场以及所有需要工业自动化的项目中使用 Siemens 产品。我们很喜欢它。Siemens 很简单——它就是能正常工作，每次都行，一直如此。

多年来，我们亲自使用 Siemens PLC 编程、接线、测试、调试并实现各种功能，因此开发了 TiaCommander，以满足自己的内部需求。这就是它存在的真实原因——我们为自己开发了它，而且觉得它非常棒。它能将工作效率提高十倍，有时甚至二十倍或更多——直到你忍不住问自己：我们以前到底是怎么完成这些工作的？！

你可以在不到一分钟内，通过 AI 助手获取完整的项目上下文。几秒钟内创建任意块——SCL、LAD、FBD、DB——获取接口结构、构建多重实例 DB、运行交叉引用、编译、调试、获取错误信息，还有更多功能。

你在下方工具地图中看到的每个工具，都是根据我们在日常使用 Siemens PLC 时的实际需求或用途构建的。无论你使用的是 S7-1200 还是 S7-1500 系列，都没有区别。只要 Siemens TIA Portal 支持，你就可以使用 TiaCommander 进行管理。

现在我们要公开这个工具了——我们非常希望了解你的开发工作流还缺少哪些功能。别客气——提交功能请求、报告错误，或者直接告诉我们你的想法。作为工程师之间的交流，我们会认真阅读每一条反馈。

祝你使用 TiaCommander 愉快。

---

架构

AI Clients
  Claude Desktop / Code · Cursor · VS Code / Copilot · Windsurf · Codex CLI · Gemini CLI
    │
    │  JSON-RPC 2.0 · stdio
    ▼
TiaCommander MCP Server
  19 tools · 230 actions · standalone I/O · .NET Framework 4.8
    │
    │  Siemens Openness API
    ▼
TIA Portal  (V17 – V20*, tested on V19)
    │
    ▼
S7-1200 · S7-1500 · S7-300 · S7-400 · ET 200

---

工具地图

工具 / 操作	#	描述
admin	13	服务管理
clear_exports		(可选 olderThanHours=24) 删除过期导出。
delete_export		(exportId) 删除单个导出。
get_device_profiles		服务见过的所有唯一设备。
get_export		(exportId; 可选 offset, length, raw=false) 分页获取导出内容。raw=true 仅返回内容，不含元数据头。
get_recent_errors		(可选 count=10) 最近 N 次失败的工具调用，含设备/固件上下文。
get_system_info		操作系统、.NET 版本、TIA Portal 版本、进程运行时长。
get_stats		(可选 top_n=20) 按工具+操作统计调用情况，按总调用次数排序。
get_version		服务版本、DB 路径、DB 大小。
list_exports		(可选 tool, limit=20) 导出 DB 中存储的最近导出结果。
open_file		(filePath) 使用 Windows 默认应用打开文件（.xlsx 用 Excel，.html 用浏览器等）。在任何导出操作后使用，让用户立即查看结果。
reset_device_catalog		清空本地设备目录，若已连接则从 TIA Portal 重新导出。
save_export		(exportId, outputPath) 将导出内容保存到文件。对二进制格式（XLSX）自动解码 base64。保存后，询问用户是否要打开文件（使用 admin action=open_file）。
search_device_catalog		(可选 filter, limit=50) 从本地 DB 搜索已安装的 TIA 硬件目录。无需 TIA Portal。用于硬件参考查询（订货号、CPU 型号、兼容模块）。
alarm_text	15	报警文本与文本列表
add_entries		(deviceName, textlistName, entries[]) 向文本列表添加条目。每个条目：{from, to, text}。
create_textlist		(deviceName, textlistName; 可选 listRange=Decimal, comment, entries[]) 创建新文本列表。可在空设备上工作（通过模板自动填充）。可选地一次性填充条目。
delete_entries		(deviceName, textlistName, fromValues[]) 按 From 值删除条目。
delete_textlist		(deviceName, textlistName) 删除用户文本列表。系统文本列表会被拒绝。
export_alarm_classes		(deviceName, outputPath) 导出报警类别定义。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_alarm_data		(deviceName, format:csv|xlsx; 可选 scope:alarm_texts|textlists|alarm_classes, outputPath, includeInfoText) 将报警数据导出为 CSV 或 XLSX 以供存档。默认为 exports_root\alarm_text\。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_alarm_texts		(deviceName, outputPath; 可选 includeInfoText) 将报警实例文本导出为 XLSX。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_textlists		(deviceName, outputPath; 可选 textListNames[]) 将文本列表导出为 XLSX。无筛选则导出全部。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
get_entries		(deviceName, textlistName) 读取文本列表的所有条目。
import_alarm_classes		(deviceName, filePath) 导入报警类别定义。
import_alarm_texts		(deviceName, filePath) 从 XLSX 导入报警实例文本。
import_textlists		(deviceName, filePath; 可选 overwrite) 从 XLSX 导入文本列表。
list_textlists		(deviceName) 列出系统和用户文本列表，含名称、ID、范围。
update_entries		(deviceName, textlistName, entries[]) 按 From 值更新条目。每个条目：{from, to?, text?}。
update_textlist_comment		(deviceName, textlistName, newComment) 直接更新文本列表注释。
blocks_read	17	读取与导出块
check_consistency		(deviceName) M10: IsConsistent 标志可能滞后于编译 — 请改用 compile_all 的输出。
compile_all		(deviceName) 全部编译。尽早运行以解决 F6。首次运行较慢（约 30-60 秒）。
compile_block		(deviceName, blockName) 编译单个块。
export_all_xml		(deviceName, outputDirectory) 将所有块导出为 .xml 文件。M5: 参数是 'outputDirectory' 而非 'outputPath'。导出后，询问用户是否要打开输出目录（使用 admin action=open_file）。
export_source		(deviceName, blockName; 可选 outputPath, returnInline, outputDirectory) SCL/STL 源代码。带 outputPath 时写入磁盘（M3: 必须是目录）；省略则应用 returnInline。LAD/FBD 返回空。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_xml_file		(deviceName, blockName; 可选 outputPath, returnInline, outputDirectory) 块 XML。带 outputPath 时写入磁盘；省略则应用 returnInline。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_xml_inline		(deviceName, blockName) 解析后的 XML 摘要。适用 F6。
get_all_interfaces_summary		(deviceName) 所有块各段的成员数量。
get_compiler_errors		(deviceName) 仅错误过滤。同样存在 M8 重新编译怪癖。
get_compiler_messages		(deviceName) M8: 触发全新编译。若刚编译过，优先使用 compile_all 的输出。
get_details		(deviceName, blockName) 类型、编号、语言、接口大小、一致性。
get_edit_capabilities		(deviceName, blockName; 可选 networkIndex) #232 P0: 发现调用。按网络：其自身的编译单元语言（块级别的在多语言块上具有误导性）、梯级模型能否往返、哪些写入操作适用，以及当都不适用时的回退路径。一次调用代替十几个零散的提示。仅花费一次导出 — 实测：没有按网络的对象模型重新...
get_element_pins		(deviceName, blockName, networkIndex; 可选 elementUId 或 elementIndex) “接线前先查看”卡片：对于 Call 或指令 Part，每个引脚含段、预期数据类型（从被调方接口/实例结构实时读取）和当前接线（操作数 + 其解析类型，或未接线的 OpenCon）。无选择器时：列出该网络的元素及其 UId。在 blocks_write u... 之前使用
get_interface		(deviceName, blockName) 完整接口段。F6: 在不一致的块上会出错 — 先执行 compile_all。
get_network		(deviceName, blockName, networkIndex; 可选 includeUIds) #171 梯级编辑器读取侧：将网络的扁平 Parts+Wires 图重构为 JSON 梯级模型 — 正是 create_block networks[].rungs 接受的词汇（contacts/parallelBranches/box/output/call，外加用于 ENO 级联调用链的 enFrom）。输出：{title, comment, editable, rungs[], unmodelled[]}。editable=true 表示该模...
get_xml_raw		(deviceName, blockName) 原始 XML 字符串。适用 F6。
list		(deviceName; 可选 typeFilter:all|code|OB|FB|FC|DB|GlobalDB|InstanceDB, includeInstanceDbs) 紧凑的块表格。
blocks_write	26	创建与导入块
add_interface_member		(deviceName, blockName, section, memberName, dataType; 可选 startValue, comment, confirm) #171 接口编辑器：向 FB/FC/OB 接口段（Input、Output、InOut、Static、Temp、Constant）添加成员。影响范围首先计算（调用点会过时的 xref 调用方 + FB 的实例 DB + #183 reinitializeDataBlocks 警告：下载会重置受影响的... 的实际值
add_multi_instance_member		(deviceName, parentFB, memberName, innerType; 可选 onCollision=fail|replace) 向 FB 添加类型化静态成员。innerType 必须存在于设备或 project.ProjectLibrary 中。
add_network		(deviceName, blockName; 可选 position, title, comment) 在指定位置插入空网络（默认：末尾）。仅限 LAD/FBD — SCL 块只有一个编译单元，不支持多个网络。之后使用 populate_network / insert_rung 添加逻辑。
copy_block		(deviceName, blockName, newName; 可选 targetFolder, createParents=false) 以新名称复制块（块名称在 PLC 范围内唯一，因此 newName 为必填并递归检查）。省略 targetFolder = 副本落在源块旁边。副本获得其类型的下一个空闲编号。源块从不被修改。需要离线。
create_block		(deviceName, blockName, blockType:FB|FC|OB, language; 可选 blockNumber, interface, sclCode, networks, blockTitle, blockComment, author, version, memoryLayout, secondaryType, overwrite, targetFolder, createParents) 完整创建块，含自定义接口和逻辑。省略 blockNumber 时自动分配 — 仅适用于真正的新块。使用 overwrite=true 更新现有块时（e...
create_fb		(deviceName, fbName; 可选 fbNumber, language:LAD|SCL|FBD（不支持 STL - Openness 限制）, author, version, autoCompile=true, targetFolder, createParents=false) 新建 FB。省略编号时自动分配。自动编译并返回错误。targetFolder（'Motors/Drives' 语法）直接在该文件夹内创建块；除非 createParents=true，否则缺失的文件夹会报错。
create_fc		(deviceName, fcName; 可选 fcNumber, language, returnType=Void, author, version, autoCompile=true, targetFolder, createParents=false) 新建 FC。省略编号时自动分配。自动编译并返回错误。targetFolder 同 create_fb。
create_ob		(deviceName, obName; 可选 obNumber, language, author, version, autoCompile=true, targetFolder, createParents=false) 新建 OB。省略编号时自动分配（从 123 开始）。obNumber=1 允许；2-122 保留。自动编译并返回错误。targetFolder 同 create_fb。
delete_block		(deviceName, blockName; 可选 force=false) 删除任意块。除非 force=true，否则拒绝实例 DB（用于孤立的实例 DB）。
delete_interface_member		(deviceName, blockName, memberName; 可选 section, confirm) 移除接口成员。同样的影响范围确认门控。仍引用该成员的逻辑将编译失败 — 先用 xref get_references 检查。
delete_network		(deviceName, blockName, networkIndex) 按 0 基索引移除网络。若为最后一个网络则拒绝。仅限 LAD/FBD。
delete_rung		(deviceName, blockName, networkIndex, rungIndex; 可选 expectTitle) 移除梯级 rungIndex。当下一梯级链接（enFrom）自被删除者时拒绝 — 先重定向或删除尾部。
delete_scl_statement		(deviceName, blockName, networkIndex, statementIndex, matchText) #232 P0: 一次调用从 SCL 网络中移除一条语句。先用 blocks_read action=get_network 读取语句，其以 0 基、空白规范化文本列出。matchText 为必填，在任何修改前与被 statementIndex 处的语句比较 — 索引在每次编辑下都会偏移，因此...
import_xml_file		(deviceName, filePath; 可选 overwrite, autoCompile=true, targetFolder, createParents=false) 从 XML 文件导入。自动编译并返回错误。大负载首选。targetFolder 同 import_xml_inline。覆盖是整体对象替换，而非合并：使用 overwrite=true 时，文档中缺失的任何元素都会被重置为默认值，而非保留（ImportOptions.Overrid...
import_xml_inline		(deviceName, xmlContent; 可选 overwrite, autoCompile=true, targetFolder, createParents=false) 从 XML 字符串导入块。自动编译并返回错误。已验证大负载（12KB+）。targetFolder 导入到该文件夹；不带它时，overwrite=true 自动定位到现有块所在的文件夹（归属组导入）。覆盖是整体对象替换，而非合并：使...
insert_rung		(deviceName, blockName, networkIndex, rung; 可选 position, expectTitle) #171 梯级编辑器：在现有 LAD 网络的指定位置（默认：追加）插入一个梯级（create_block 梯级词汇：contacts/parallelBranches/box/output 或 call{blockName,blockType,instanceDB,scope,pins}，可选用于 eno 链的 enFrom）。网络必须完全建模（get_network editable=true）— 拒绝...
move_block		(deviceName, blockName, targetFolder; 可选 createParents=false) 将块移动到另一个文件夹（'' 或 '/' = 容器根）。Openness V19 没有原生移动 — 这是导出 -> 删除 -> 导入到目标组，若导入失败则自动恢复到原文件夹。通过重新解析验证并随后重新编译。需要离线。
populate_network		(deviceName, blockName, networkIndex, rungs; 可选 overwriteExisting, expectTitle) 用 rungs[] 数组填充网络（create_block networks[].rungs 词汇，含 enFrom 链）。空网络（新 add_network）可直接填充；非空网络需要 overwriteExisting=true 且完全建模（先 get_network 以保留内容）。#164 风格的带 JSON 路径的导入前验证...
remove_multi_instance_member		(deviceName, parentFB, memberName) 移除静态多实例成员。
rename_block		(deviceName, blockName; 可选 newName, newNumber) 重命名/重新编号。不会自动级联到调用方。
replace_network		(deviceName, blockName, networkIndex; 可选 title, comment) 替换网络标题/注释。仅限 LAD/FBD — 不支持 sclCode（SCL XML 是分词的；使用 create_block 加 overwrite=true 重建 SCL 块）。
split_network		(deviceName, blockName, networkIndex, splitBefore[], titles[]) #232 P0: 在语句边界将一个 SCL 网络切割为多个，每个有自己的标题。splitBefore 列出新网络开始的语句索引：[2,4] 在 6 语句网络上得到 0-1、2-3、4-5 三个网络。titles[] 必须比 splitBefore 恰好多一个条目，且从不默认。是分区，不是...
update_interface_member		(deviceName, blockName, memberName; 可选 section, newName, newDataType, newStartValue, newComment, confirm) 更新或重命名（newName）接口成员。省略 section = 在所有段中搜索；未命中则按段列出成员。同样的影响范围确认门控。空字符串 newStartValue/newComment 表示移除。
update_network		(deviceName, blockName, networkIndex; 可选 title, comment) 更新网络标题/注释（0 基索引）。
update_network_element		(deviceName, blockName, networkIndex, elementUId 或 elementIndex; 可选 newInstance, newTarget, pinWires) 对 LAD/FBD 中 Call 元素的精细编辑。newInstance: 替换实例 DB。newTarget: 重定向到不同的 FB/FC（重新生成参数，保留匹配的接线）。pinWires: 将引脚名映射到新操作数的 JSON 对象 — 在任何变更前针对引脚声明的类型进行类型检查...
update_rung		(deviceName, blockName, networkIndex, rungIndex, rung; 可选 expectTitle) 用给定的 rung 对象替换梯级 rungIndex。与 insert_rung 相同的建模网络要求和重新编号注意事项。
db	11	数据块管理
add_member		(deviceName, dbName, memberName, dataType; 可选 comment, initialValue) 向全局 DB 添加成员。支持所有类型包括数组（如 Array[0..9] of Int）和 UDT 引用。仅限全局 DB — 拒绝实例 DB。
create		(deviceName, dbName; 可选 dbNumber, author, version, memoryLayout, targetFolder, createParents) 新建全局 DB。省略编号时自动分配。targetFolder（'Motors/Drives' 语法）直接在该文件夹内创建 DB；除非 createParents=true，否则缺失的文件夹会报错。对于实例 DB，请改用 create_instance_db。
create_instance_db		(deviceName, dbName, instanceOfName; 可选 dbNumber) 为 FB 创建实例 DB。TIA 从 FB 自动填充接口。instanceOfName 必须是现有 FB。省略编号时自动分配。
delete		(deviceName, dbName) 删除 DB。拒绝实例 DB（改为删除所属 FB）。
delete_member		(deviceName, dbName, memberName) 从全局 DB 移除成员。拒绝最后一个成员。
get_member		(deviceName, dbName, path; 可选 depth=2) #171 任意深度的实例数据读取：点分隔成员路径进入嵌套多实例链、指令实例、UDT/结构成员（如 'modbus.BWTT-RR8_Instance.mb_addr'）。卡片显示类型、起始值（含按数组元素）、注释、到指定深度的子项。适用于全局和实例 DB（例外：系统块 iDB 无法导出）。成员...
get_structure		(deviceName, dbName) 通过 XML 导出获取完整成员列表，含类型、起始值、属性。扁平列表（无嵌套层次）。
list		(deviceName) 所有全局和实例 DB。名称为限定的 'Folder/Sub/Name' 路径（#185）。
set_start_value		(deviceName, dbName, path, value | values{path:value,...}) #171 任意深度的实例数据写入，适用于全局和实例 DB（仅起始值，绝不涉及结构 — 多实例配置面，例如 poll DB 内站点调用的 mb_addr 默认值）。数组元素通过在最后一段上加 [index]（'Cfg_HwId[3]'）。值为字符串形式的 TIA 字面量（'33'、'TRUE'、'T#2S'、'16#00FF'）。所有参...
update_member		(deviceName, dbName, memberName; 可选 newDataType, newStartValue, newComment) 更新成员属性。至少需要一个字段。类型变更时保留起始值，除非显式提供 newStartValue。若 TIA 因类型/值不匹配而拒绝，提供兼容的 newStartValue。连续成员编辑可能使 DB 导出不一致 — 该工具会自动编译并重试 ON...
update_member_comment		(deviceName, dbName, memberName, newComment) 仅更新注释的快捷方式。关键：参数是 'newComment'，不是 'comment'。
diagnostics	7	PLC 诊断与连接
compare_online_offline		(deviceName) 比较离线项目与在线 PLC 之间的所有软件对象（块、变量、UDT、工艺对象）。若离线则自动连接。只读。返回逐项状态：相同/不同/仅 PLC 上/仅项目中。
configure_connection		(deviceName, pcInterfaceName, confirm; 可选 targetIp, skipConfirm=false) 以编程方式设置下载连接。targetIp 默认为设备在硬件配置中项目配置的 IP — 正常情况下省略它；仅当要定位不同地址时传入（如来自 scan_devices）。在 TargetInterface 内创建 ConfigurationAddress，然后应用配置...
get_device_ip		(deviceName) 只读。报告设备项目配置的 IP（configure_connection 和 download_to_device 的默认目标）以及每个网络接口的 IP/掩码/子网。调用此操作可从项目回答“该 PLC 使用哪个 IP” — 无需网络扫描。
get_plc_status		(deviceName) 连接状态（Online/Offline/NotReachable/Protected/...）、下载连接是否已配置，以及 CPU 的实际运行状态（实时读取）。RUN/STOP 完全不在工程 API 中，因此通过 live_data 获取状态：此操作解析你所命名设备的 IP，若有空闲则打开实时数据会话，对照 t... 确认 CPU 身份
go_offline		(deviceName) 断开与 PLC 的连接。
go_online		(deviceName) 通过 OnlineProvider 连接到 PLC。先（静默）运行 download_check 以验证接口已配置。
scan_devices		(可选 deviceName) 只读网络扫描。通过 GetAccessibleDevices() 发现可访问的 PLC。按 PcInterface 返回 IP、DeviceSeries、MAC、Name，每个标注 [IN PROJECT: ] 或 [NOT IN THIS PROJECT]。带 deviceName：通过 DownloadProvider 扫描。不带：通过 StationUploadProvider 扫描（项目范围）。无需确认。范围：这是二层 PROFINET DCP 广播 — 它...
download_upload	4	下载 / 上传到 PLC
download_check		(deviceName) 静默预检。在任何下载或 go_online 之前调用。调用前不要输出文本。判定：READY（所有门控已验证，含编译）、NOT READY（某门控失败 — 转达问题）、COMPILE UNVERIFIED（编译门控无法运行，例如设备在线 — 这不是通过；download_to_device 仍会自行离线编译，但检查未验证它）。
download_to_device		(deviceName, confirm; 可选 mode=software_changes, stopModules=false, startAfterDownload=true, reinitializeDataBlocks=false, pcInterfaceName) 破坏性。强制编译预检。confirm='I understand this will modify the PLC'。mode: software_changes|software|hardware_software|hardware。pcInterfaceName 选择经由哪个网络适配器路由（来自 scan_devices 结果）。hardware/...
upload_check		静默预检。在任何上传之前调用。调用前不要输出文本。若结果显示 READY，则继续 upload_station。若为 NOT READY，将问题转达给用户。
upload_station		(modeName, pcInterfaceName, confirm; 可选 addressIndex=0, readPassword, writePassword) 对项目破坏性（添加设备）。confirm='I understand this will add a device to the project'。
folders	5	项目树文件夹（组）
create_folder		(deviceName, container, path; 可选 createParents=false) 在 path 处创建文件夹。嵌套路径使用 '/'（如 'Motors/Drives'）。除非 createParents=true，否则缺失的中间文件夹会报错 — 绝不静默创建。
delete_folder		(deviceName, container, path; 可选 deleteContents=false, confirm) 破坏性。空文件夹立即删除。非空需要 deleteContents=true 且 confirm 包含 'I understand' — 删除会永久移除所有包含的项和子文件夹。
find		(deviceName, container, query; 可选 path, typeFilter, caseSensitive=false) 跨整个容器的 Glob 搜索：* 匹配任意序列，? 匹配一个字符（如 'mb_*'、'HMI'）。返回 Name [key=value, ...]（与 get_tree 相同的信封和按容器键）+ 每个匹配的文件夹位置；上限 200 并明确截断。get_tree 回答形状，find 回答身份 — 当 y... 时使用 find
get_tree		(deviceName, container; 可选 path, nested=true, includeItems=false, depth=0 无限制（1 = 直接子项）, typeFilter, limit) 一次调用的树视图：文件夹含项/子文件夹计数，includeItems=true 时还包括所含项。项行在每个容器上使用一个信封：Name [key=value, key=value]，键小写、逗号空格分隔、不适用的键省略。各容器的键...
rename_folder		(deviceName, container, path, newName) 仅适用于 technology_objects。在其余五个容器（program_blocks、tag_tables、udts、watch_tables、external_sources）上，文件夹 Name 在 Openness V19 中是仅获取的，此操作返回 Error: RenameFailed 及 AccessMode — 在 TIA Portal UI 中重命名那些。它们上均无移动 API。（#231 更正 14：先前文本称此为...
get_info	-	服务信息
hardware	14	硬件配置
compile_all		编译所有硬件。M4: 'Not compilable' = 无需重新编译（不是错误）。
compile_device		(deviceName) F1: NullReferenceException — 请改用 compile_all。
dump_catalog		将完整 TIA Portal 硬件目录（约 11K 条目）导出到本地 DB。首次 TIA 连接或 TIA 版本变更时自动运行。HSP 更新时手动触发。
export_csv		(outputPath) 设备列表到 CSV。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_hardware_map		(format:csv|xlsx; 可选 deviceName, outputPath) 将设备的原始 CAx/AML 硬件数据导出为扁平表格。显示西门子导出的所有内容：机架、CPU、子项、信号模块、通道、地址、变量。单工作表。默认为 exports_root/hardware/。文件名：{ProjectName}_{PLCName}hardware_map{timestamp}.{ext}。导出后，询问用户是否要打开文件（使用 admin ac...
export_io_map		(format:csv|xlsx; 可选 deviceName, outputPath) 导出完整设备 I/O 图，结合机架/插槽拓扑与变量分配。XLSX: 每个插槽一张工作表 + 摘要。CSV: 扁平合并。省略 deviceName 则导出所有设备（每个一个文件）。默认为 exports_root/hardware/。文件名：{ProjectName}_{PLCName}io_map{timestamp}.{ext}。导出后，询问用户是否要打开文件...
export_xlsx		(outputPath) 设备列表到 Excel。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
get_device		(deviceName) 单个设备的详细配置。
get_full_config		所有设备的完整硬件配置。
get_io_map		跨所有设备/模块的完整 I/O 地址图。
get_network		跨项目的子网、节点、IO 系统。
get_rack_slot_details		(deviceName) 含 I/O 地址分配的机架/插槽拓扑。
search_catalog		(filter) 实时搜索 TIA Portal 硬件目录。需要 TIA Portal 运行。上限 50 个结果。
set_network_config		(deviceName, confirm; 可选 ipAddress, subnetMask, useRouter, routerAddress, ipProtocolSelection, useIsoProtocol, pnDeviceNameAutoGeneration, stationName, pnDeviceName) 设置设备 PROFINET 接口的网络配置。pnDeviceName 直接设置 PROFINET 设备名（自动禁用自动生成）。stationName 重命名设备。仅修改项目配置 — 需要下载到 PLC...
library	29	库管理
add_to_multi_instance_fb		(deviceName, parentFB, memberName, path; 可选 library='project', version, onCollision=fail|replace) 解析库类型 + 委托给 blocks_write add_multi_instance_member。类型必须先用 instantiate_library_type 填充。
archive_global_library		(libraryName; 可选 targetDirectory, targetName, mode=Compressed) 创建 .zal19 归档。targetDirectory 默认为配置的 archives root — 除非用户明确指定不同路径，否则不要传入 targetDirectory。若 archives root 未配置，引导用户打开 open_manager → Paths 选项卡设置它。
close_global_library		(libraryName) 关闭已加载的全局库。
compare_to_target		(targetLibrary; 可选 library='project', includeIdentical=false) 比较库：only_in_source、only_in_target、differs、identical。只读。
create_global_library		(name; 可选 targetDirectory) 创建新的空 .al19。targetDirectory 默认为配置的 libraries root — 除非用户明确指定不同路径，否则不要传入 targetDirectory。若 libraries root 未配置，引导用户打开 open_manager → Paths 选项卡设置它。以 ReadWrite 打开。调用 save_global_library 以持久化。
create_library_folder		(folderPath; 可选 library='project', typeFilter=master_copies|types) 创建子文件夹（幂等，自动创建中间项）。typeFilter 选择段：master_copies（默认）或 types。只读全局库会以该原因被拒绝。
delete_library_folder		(folderPath; 可选 library='project', recursive=false, typeFilter=master_copies|types) 从指定段删除子文件夹。除非 recursive=true，否则拒绝非空。
delete_master_copy		(path; 可选 library='project') 按完整斜杠路径删除。
delete_unused_types		(可选 library='project', path, mode=preserve_default|delete_all, dryRun=true, confirm) 移除零实例的类型。默认 dryRun=true；设为 false + confirm 以执行。
export_type_xml		(library, path, outputPath; 可选 version, overwrite=false) 将类型版本导出为 XML 文件。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
find		(library, query; 可选 path, typeFilter:all|types|master_copies, caseSensitive=false, limit) Glob 搜索（* 和 ?）。递归遍历，上限 500 个匹配并在截断时大声提示；匹配携带与 get_tree 相同的信封。在庞大库上用 path 限定范围。section 已移除（使用 typeFilter）。
get_info		(library) 元数据：编辑模式、版本、作者、项计数、根文件夹。
get_master_copy		(library, path) 主副本元数据加内容清单：Contents (N)，每个被包装对象一行及友好的种类。主副本不携带依赖 — 单独发布被引用的块和 UDT。无 XML 主体可用：V19 Openness 中 MasterCopy 没有 Export 方法（#231 H11）。
get_type		(library, path; 可选 version='latest_committed', includeXml=false) 类型元数据 + 版本列表。includeXml=true 内联 XML 主体（上限约 30KB）。
get_tree		(library; 可选 path（默认根）, depth=0 无限制（1 = 直接子项）, nested=true, includeItems=false, typeFilter:all|types|master_copies, limit) 递归子树视图 — 参数、默认值和深度规则现与 folders get_tree 完全相同（v3.0.0）。nested=false = 扁平路径列表（机器契约）。上限 1000 项，截断时大声提示。类型行携带统一信封 [ve...
instantiate_library_type		(deviceName, path; 可选 library='project', version='latest_committed') 将类型版本实例化到设备块中。仅 Committed 版本。副作用：填充 project.ProjectLibrary。
instantiate_master_copy		(deviceName, path; 可选 library='project') 将主副本具体化到设备块中。
list_libraries		所有库（项目 + 已加载全局库）。返回用于 'library' 参数名称。保留名 'project' = 项目库。
open_global_library		(可选 path; 可选 openMode=ReadOnly|ReadWrite) 加载 .al19 文件。不带 path 时，从配置的 libraries root 列出可用库。
promote_to_global		(targetLibraryName; 可选 sourceLibrary='project', path, forceUpdateMode, structureConflictMode, deleteUnusedVersions) 将类型复制到可写全局库。
publish_block_as_master_copy		(deviceName, blockName; 可选 library='project', folderPath='', onCollision=autoRename|replace|fail) 将 FB/FC/OB/GlobalDB 发布为主副本。适用于不一致的块。
publish_plc_type_as_master_copy		(deviceName, udtName; 可选 library, folderPath, onCollision) 同上，针对 UDT。
reload_global_library		(libraryName; 可选 discardChanges=false) 在会话外更改后从磁盘重新读取全局库。Openness 没有刷新，因此这是一次受监督的关闭+打开：当库有未保存更改（IsModified）时拒绝，除非 discardChanges=true。重新加载前的每个路径或句柄都已失效。
rename_library_folder		(folderPath, newName; 可选 library='project', typeFilter=master_copies|types) 重命名任一段中的用户文件夹。该段的系统根不可重命名。（#231 H15）
rename_master_copy		(path, newName; 可选 library='project') 重命名主副本。被包装对象保留其自身名称 — ContentName 为只读 — 结果也会如此说明。（#231 H13）
rename_type		(path, newName; 可选 library='project') 重命名库类型。版本和已实例化的块不受影响。（#231 H15）
save_global_library		(libraryName) 将打开的全局库持久化到 .al19。
update_check		(可选 library='project', path, mode=ReportOutOfDateOnly) 预览 update_project 会更改什么。只读。
update_project		(可选 library='project', path, deleteUnusedVersions=false) 破坏性：将所有匹配块应用库类型更新。先运行 update_check。
live_data	11	实时 PLC 值 + 诊断
connect		(host; 可选 password) 通过加密连接（TCP 端口 102）连接到 PLC。host = PLC IP。仅当 CPU 访问级别需要时才用 password（从不记录/回显）。若省略 password 且已通过 set_credential 为此主机存储过，则自动使用。
delete_credential		(host; 可选 passwordClass, scope) 移除主机的存储凭据。scope='project' 移除打开项目的凭据；scope='global' 移除任何项目共享的那个。响应说明移除了哪个层级。
disconnect		释放实时数据会话。
get_status		实时数据就绪状态、连接状态、PLC 身份。任何时候都安全。
list_credentials		列出存储的凭据（host、SCOPE、class、label、时间戳）。绝不显示密钥。每行使用 scope 参数所接受的相同词汇说明 scope=project 或 scope=global，因此此处读取的行可直接传回 delete_credential；project 行还会命名其项目路径，并在其为 scope=project 会作用的那一个时标记 [OPEN in TIA]。
list_readable		(可选 root, limit) PLC 实际暴露可读取的内容，按根。无参数 = 每个根一行含叶计数；root=MArea（或 DB 名称）列出该根的叶。当变量返回未解析时使用此操作 — 它区分“未声明”与“整个区域为空”。
read_db		(dbName; 可选 members[]) 数据块（优化或标准）的实时值，符号化，带质量代码。members[] 限定到特定成员。
read_diagnostics		(可选 kind=all|identity|protection|alarms|buffer, maxEntries) CPU 订货号 + 固件（在线 — Openness 无法读取此）、保护级别、活动 + 配置的报警，以及 CPU 诊断缓冲区（kind=buffer 或 all）：与 TIA Portal 在 Online and Diagnostics 下显示的相同事件日志，最新在前，时间戳来自 CPU 时钟（UTC）。事件文本从目录本地解析，s...
read_tag_table		(deviceName, tagTableName; 可选 tags[]) PLC 变量表的实时值。变量可按符号名或绝对地址（%M1.0、%MB1、%MW20、%MD4，以及 %I/%Q 等价形式）。若命名设备的订货号与所连 CPU 不同则阻止。
read_watch_table		要么 (symbols[]) 用于完全限定符号，要么 (deviceName, watchTableName) 以解析项目监视表并实时读取其条目。同时传入二者会报错。
set_credential		(host, password; 可选 passwordClass, label, scope) 存储 CPU 密码，静态加密（机器绑定），使 connect 无需每次传入密码即可使用。密钥从不回显或记录。scope='project' 绑定到打开项目；scope='global' 适用于任何项目。connect 优先使用项目凭据，回退到全局凭据。
open_manager	-	打开 Manager 窗口
session	16	会话管理
archive		(可选 outputDirectory; 可选 archiveName, timestamp, archivationMode, saveChanges) 创建 .zapXX 归档。outputDirectory 默认为配置的 archives root — 除非用户明确指定不同路径，否则不要传入 outputDirectory。若 archives root 未配置，引导用户打开 open_manager → Paths 选项卡。timestamp=true 默认。archivationMode: None|Compressed|DiscardRestorabl...
close_project		(可选 saveChanges) 关闭项目。saveChanges: prompt|save|discard|auto。
configure		(可选 projectsRoot, archivesRoot, exportsRoot, librariesRoot, httpEnabled) 设置 create/open/archive/exports/libraries 的默认文件夹路径。验证目录存在（exportsRoot 若缺失则自动创建）。使用 open_manager GUI 作为替代。另外（#168）：preferredTiaBinding= 是 TIA Portal 选择器 — 在安装了多个 TIA Portal 的 PC 上，选择哪个 TiaCommander bin...
connect		(可选 withUI=true) 附加到运行中的 TIA Portal，自动加载第一个项目。先释放任何过期句柄。
create		(name; 可选 parentDirectory, withUI=true) 创建新项目。自包含：自动启动 TIA Portal 或附加到运行实例，清理过期句柄。仅 ASCII 名称（M12）。parentDirectory 默认为配置的 projects root — 除非用户明确指定不同路径，否则不要传入 parentDirectory。若 projects root 未配置，引导用户打开 open_manager → Paths ...
disconnect		(可选 saveChanges, closeTia) 释放 Openness 句柄。closeTia=true 还会终止 TIA 进程。
get_project		打开项目的名称、路径、版本、设备数量。
get_state		主动状态检查。返回状态级别（0-4）、TIA/项目/设备状态、许可证信息和重启标志。在会话开始时调用。在任何状态都可用。
info		服务版本、工具数量、工作流提示。
is_dirty		返回未保存更改的 true/false。
launch		(可选 withUI=true) 启动新的 TIA Portal（无项目）。先释放任何过期句柄。优先使用会自动启动的 create/open。
list_archives		(可选 archivesRoot) 从配置或显式 archives root 列出所有 .zap* 归档文件。显示文件名、大小、日期、TIA 版本。
list_devices		项目中的所有设备。为其他工具提供 deviceName。
open		(可选 projectPath; 可选 withUI=true) 打开项目，若需要则自动启动 TIA。幂等。不带 projectPath 时，从配置的 projects root 列出可用项目。
save		保存项目。需要离线：当任何设备在线时以 OnlineModeRestriction 拒绝 — 先运行 diagnostics go_offline。
save_as		(newName; 可选 newParentDirectory) 在新位置保存副本。若已设置，newParentDirectory 默认为配置的 projects root。
tag	16	PLC 变量管理
add_tag		(deviceName, tagTableName, tagName, dataType; 可选 logicalAddress, comment) 添加变量。dataType: Bool、Int、Real 等。logicalAddress: %%M0.0、%%MW100。
create_table		(deviceName, tagTableName; 可选 targetFolder, createParents=false) 新建空表。targetFolder（'Motors/Drives' 语法）在 PLC 变量树中直接在该文件夹内创建；除非 createParents=true，否则缺失的文件夹会报错。名称冲突在所有文件夹中递归检查。
delete_table		(deviceName, tagTableName) 删除表及所有变量。
delete_tag		(deviceName, tagTableName, tagName; 可选 tagNames, confirm) 删除单个变量。当变量带有注释或非默认可访问标志时拒绝，因为 add_tag 无法恢复它们 — 传入 confirm='I understand this destroys the comment and access flags' 以覆盖，或使用 action=move 无损重定位它。注意删除+添加不是重命名：它创建新对象且每个引用 t...
export_tag_table_data		(deviceName, tagTableName, format:csv|xlsx|xml; 可选 outputPath, returnInline=false) 将变量表导出为 CSV 或 XLSX 以供存档/分析，或导出为原始 TIA XML（format=xml）以通过 import_table 往返。列：Name、DataType、Address、Comment、ExternalAccessible、ExternalVisible、ExternalWritable。若无 outputPath 则默认为 exports_root\tag\，自动生成的名称会去重...
find_next_free		(deviceName; 可选 area:M|I|Q, startByte:int, dataType:Bool|Byte|Word|DWord|Int|Real|etc., mode:declared|used) 查找下一个空闲地址。mode=declared（默认，最安全）：跳过所有已声明变量地址。mode=used：仅跳过代码中引用的地址。对齐：Bool=任意位，Byte=字节，Word=偶数字节，DWord=4 字节。
get_assignment_list		(deviceName; 可选 area:M|I|Q|all, mode:declared|used|conflicts) M/I/Q 区域 + 硬件 I/O 的地址占用。mode=declared（默认）：所有变量地址。mode=used：仅块代码中引用的地址（对应 TIA 分配列表）。mode=conflicts：在 2 个以上块中使用的地址，含读/写详情 — 检测双重分配。
get_table_details		(deviceName, tagTableName) 所有变量含类型、地址和注释。
import_table		(deviceName, filePath 或 xmlContent 或 exportId; 可选 overwrite=false, targetFolder, createParents=false) 需要离线。从原始 TIA XML 导入变量表 — 即 export_tag_table_data format=xml 产生的文档。overwrite=false 会创建并在该表名已存在时拒绝。overwrite=true 替换现有表；这是整表导入，不是字段级合并，因此变量...
list_tables		(deviceName) 所有变量表，每行含限定的 'Folder/Sub/Name' 路径和统一信封 [type=PlcTagTable, tags=N]。总数与 folders get_tree（container=tag_tables）对账。
move		(deviceName, tagTableName, tagName, targetTable) 将一个变量移动到另一个表，保留其注释和所有三个可访问标志（ExternalAccessible/Visible/Writable）。用它代替 delete_tag + add_tag：add_tag 无法携带可访问标志，因此手工路线会静默重置它们。通过读回验证；若任何属性未存活则大声失败。
move_table		(deviceName, tagTableName, targetFolder; 可选 createParents=false) 需要离线。在文件夹之间移动变量表（'' = 容器根）。模拟为导出 -> 删除 -> 导入到目标文件夹（经 spike 验证完全保真）；失败时恢复到原位置。注意：变量表无法复制 — PLC 变量名在所有表中是全局的。
rename		(deviceName, tagTableName, tagName, newName) 有意拒绝，始终如此。Openness V19 不暴露变量重命名：PlcTag.Name 是仅获取的，SetAttribute('Name') 被以 AccessMode: Read 拒绝。也不通过导出/重新导入模拟 — 变量名是 PLC 全局的，且 Openness 不级联任何内容，因此重建的变量会使每个 LAD/FBD/STL/SCL 操作数仍命名旧符号，而 SCL 没有编程式 ...
search		(deviceName, tagName) 跨所有表的子字符串匹配。
set_access		(deviceName, tagTableName, tagName, accessible, visible, writable) 关键：参数是 accessible/visible/writable，不是 externalAccessible 等。
update_comment		(deviceName, tagTableName, tagName, newComment) 关键：参数是 'newComment'，不是 'comment'。
technology_objects	15	****
capabilities		(可选 family) 文档化的系列/版本/固件矩阵。无需 TIA 连接。
compile		(deviceName, name; 可选 scope=group) 立即运行；无演练。报告前后每个对象版本。
connect_hardware		(deviceName, name, interface, target; 可选 confirm) 重新接线通道。传感器索引为 1 基。
create		(deviceName, name, family, version; 可选 path, confirm) family 和 version 在创建时固定，之后无法更改。
create_from_master_copy		(deviceName, masterCopy; 可选 path, confirm) 主副本必须在 TIA UI 中创作；没有 Openness 调用能生成一个。
delete		(deviceName, name; 可选 confirm) 不可逆：重新创建的对象从默认值开始。
export		import — (deviceName, name | file; 可选 confirm) SimaticML。按系列版本门控；拒绝会命名所需版本及其手册章节。
find_parameter		(deviceName, name, parameter) 单个参数：值、类型、访问。首次读取对象参数较慢（实测约 5.5-7.5 秒 — 成本在 Openness 内）；后续读取约 150 毫秒，空闲后链接再次变冷。
get_hardware_connection		(deviceName, name) 只读接线报告。不适用于该系列的提供者会如此报告，而非报错。
get_parameters		(deviceName, name; 可选 prefix, summary, limit) 调试数据，带类型。prefix 过滤一个区域；summary=true 仅给出区域和计数。每行说明其访问；一个裸/下划线对折叠为一行并命名哪一半接受写入。
import
list		(deviceName; 可选 limit) 所有对象：Name [type=, version=<Vx.y>, parent=]。子级对象（输出凸轮、凸轮轨道、测量输入）挂在父轴下并包含在内。
rename		(deviceName, name, newName; 可选 confirm) 程序块按名称引用对象且不会更新。
set_parameter		(deviceName, name, parameter, value, expectedCurrentValue) 写入一个参数。expectedCurrentValue 为必填且必须与当前值匹配，否则写入被拒绝。只读参数会提前拒绝。回显旧 -> 新并附带可复制粘贴的撤销。
show_in_editor		(deviceName, name) 在 TIA UI 中打开它。
udt	11	用户定义类型管理
add_member		(deviceName, udtName, memberName, dataType; 可选 comment, initialValue) 通过 XML 往返添加成员。
create		(deviceName, udtName) 新建空 UDT。它使用占位成员 _placeholder（Bool）创建，因为 TIA 拒绝空 STRUCT — 用 delete_member 移除它，或传入 members[]（与 add_member 批量模式相同形状）则不创建占位符。可选 targetFolder（'Motors/Drives' 语法）+ createParents 直接在该文件夹中创建。（内部使用 SCL ExternalSources 变通...
delete		(deviceName, udtName) 删除 UDT。若仍被引用则拒绝。
delete_member		(deviceName, udtName, memberName) 通过 XML 往返移除成员。
export_xml		(deviceName, udtName; 可选 outputPath, returnInline, outputDirectory) 将 UDT 导出为 XML。带 outputPath 时写入磁盘；省略则应用 returnInline。
get_structure		(deviceName, udtName) 通过 XML 获取完整成员列表，含类型、注释、访问标志。
import_xml		(deviceName, filePath 或 xmlContent; 可选 overwrite) 从 XML 导入 UDT。filePath 从磁盘读取；xmlContent 接受内联 XML 字符串（无需文件工具）。往返可靠；对合成 XML 可能失败（改用 create+add_member）。覆盖是整体对象替换，而非合并：使用 overwrite=true 时，文档中缺失的任何元素都会被重置为默认值，而非 p...
list		(deviceName) 所有 UDT，每行含限定的 'Folder/Sub/Name' 路径、统一信封 [type=PlcStruct, num=N] 和修改日期。
move		(deviceName, udtName, targetFolder; 可选 createParents=false) 需要离线。在文件夹之间移动 UDT（'' = 容器根）。模拟为导出 -> 删除 -> 导入到目标文件夹（经 spike 验证）；失败时恢复到原位置。
update_member		(deviceName, udtName, memberName; 可选 newDataType, newInitialValue, newComment) 更新成员属性。至少需要一个字段。使用 SCL 往返。
update_member_comment		(deviceName, udtName, memberName, newComment) 关键：参数是 'newComment'，不是 'comment'。
watch	14	监视与强制表
add_entry		(deviceName, target, tableName, address; 可选 displayFormat, modifyValue[watch], forceValue[force], modifyTrigger[watch], monitorTrigger, comment)。重要：始终设置 displayFormat 以匹配源变量的数据类型 — Bool→Bool、Int/Word→DEC_signed、DInt/DWord→DEC_signed、Real→Float、Time→Time、String→String。绝不要保留默认的 Hex。从源 bloc... 查找数据类型
clear_table		(deviceName, watchTableName) 移除所有条目，保留表。
create_table		(deviceName, watchTableName; 可选 targetFolder, createParents=false) 新建空监视表。targetFolder 在监视/强制表树中直接在该文件夹内创建；除非 createParents=true，否则缺失的文件夹会报错。名称冲突递归检查（监视和强制表）。
delete_entry		(deviceName, target, watchTableName|forceTableName, address) 移除条目。地址形式：传入裸绝对地址（%%M60.0）或精确符号名。TIA 将变量拥有的地址符号化存储，因此当没有条目字面匹配裸形式时，会通过变量表解析，结果说明 'matched symbolically as ""TagName""'。若裸地址被多个变量拥有 t...
delete_table		(deviceName, watchTableName) 删除监视表。
export_force_data		(deviceName, forceTableName, format:csv|xlsx; 可选 outputPath) 将强制表导出为 CSV 或 XLSX 以供存档。默认为 exports_root\watch\。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_table		(deviceName, target, tableName, outputPath) 导出为 XML。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
export_watch_data		(deviceName, watchTableName, format:csv|xlsx; 可选 outputPath) 将监视表导出为 CSV 或 XLSX 以供存档。默认为 exports_root\watch\。导出后，询问用户是否要打开文件（使用 admin action=open_file）。
get_entries		(deviceName, target, watchTableName|forceTableName) 列出条目。
import_table		(deviceName, filePath 或 xmlContent; 可选 overwrite) 从 XML 导入。filePath 从磁盘读取；xmlContent 接受内联 XML 字符串（无需文件工具）。覆盖是整体对象替换，而非合并：使用 overwrite=true 时，文档中缺失的任何元素都会被重置为默认值，而非保留（ImportOptions.Override；实测 #231 P1）。提供完整文档 — 先导出 fi...
list_tables		(deviceName) 所有监视和强制表，每行含限定的 'Folder/Sub/Name' 路径和统一信封 [type=PlcWatchTable|PlcForceTable, entries=N, force=true|false]。总数与 folders get_tree（container=watch_tables）对账。
move_table		(deviceName, watchTableName, targetFolder; 可选 createParents=false) 需要离线。在文件夹之间移动监视/强制表（'' = 容器根）。模拟为导出 -> 删除 -> 导入到目标文件夹；失败时恢复到原位置。
rename_table		(deviceName, watchTableName, newName) 重命名（内部 XML 往返）。
update_entry		与 add_entry 相同的参数。无法清除字段（改为删除+重新添加）。接受任一地址形式 — 见 delete_entry。
xref	6	交叉引用分析
find_call_paths		(deviceName, blockName; 可选 maxDepth=10) 从 OB 根到目标块的所有调用路径，沿 CALL 边，例如 Main [OB1] -> ModbusPoll [FB2] -> mb_query [FB8]。补充 find_callers（find_callers = 仅直接调用方；此 = 来自 OB 的完整限定路径）。blockName 接受裸名称（跨所有文件夹递归解析）或文件夹限定路径。
find_callers		(deviceName, blockName) 反向查找：哪些块引用命名目标。目标可以是块（调用点）或 PLC 变量 — 对于变量，你会得到读和写的块，含 Access=Read/Write 和网络，因此无需单独的变量操作。遍历每个块。既不匹配块也不匹配变量的名称会如此说明，而非报告零引用。
find_orphaned_instance_dbs		(deviceName) 所属 FB 缺失或没有 TypeInstance/InstanceType 引用的实例 DB。
find_unused		(deviceName) 未从任何 OB 链调用的所有块。遍历每个块（每个约 5-10 毫秒）。
get_call_tree		(deviceName; 可选 blockName, maxDepth=10) 正向 CALL 树：根调用什么，递归到任意深度（默认根：所有 OB；blockName 接受裸名称或文件夹限定名称）。每个节点显示文件夹限定名、块编号、调用点网络、实例 DB；系统指令作为叶出现。循环安全；已显示的子树用标记折叠。
get_references		(deviceName, blockName; 可选 filter:AllObjects|ObjectsWithReferences|ObjectsWithoutReferences|UnusedObjects) 单块的交叉引用。显示被引用对象及访问类型（Read/Write/Call 等）和位置。
总计：19 个工具，230 个操作 — 本表中操作描述为缩写；每个操作的完整文本在机器可读工具列表（data/tool-list/tools.json）中。
每个元工具都会通过单个 action 参数将相关操作分组。get_info 和 open_manager 是独立实用工具，无需许可证即可使用。先使用 session 建立连接，然后使用其他任意工具。

---

已测试的硬件

TiaCommander 应可与 TIA Portal 和 Openness API 支持的任何 PLC 配合使用。以下设备已在内部完成测试，所有工具均已全面覆盖：

设备	订货号	固件	TIA Portal
S7-1200 CPU 1212C DC/DC/Rly	6ES7 212-1BE31-0XB0	V3.0	V19
S7-1200 CPU 1214C DC/DC/DC	6ES7 214-1AG31-0XB0	V3.0	V19
S7-1200 CPU 1214C DC/DC/DC	6ES7 214-1HG40-0XB0	V4.5	V19
S7-1200 CPU 1215C DC/DC/DC	6ES7 215-1AG31-0XB0	V3.0	V19
S7-1200 CPU 1215C DC/DC/Rly	6ES7 215-1BG31-0XB0	V3.0	V19
S7-1200 CPU 1217C DC/DC/DC	6ES7 217-1AG40-0XB0	V4.2	V19

查看社区实际在使用的设备 — tiacommander.com/stats。 实时兼容性列表展示了所有用户报告可正常使用的设备，包括订货号、固件以及对应的 TIA Portal 版本，同时还列出社区工具使用情况和 AI 客户端采用情况。该列表基于匿名汇总遥测数据构建，涵盖范围远超上方的内部测试表。

---

块创建

TiaCommander 可根据结构化 JSON 描述创建完整的 PLC 块：

• SCL 块 — 通过 External Source API 创建（与固件无关）
• LAD/FBD 块 — 通过 FlgNet XML 构建器创建，支持 69 种已验证的指令类型：
  • 位逻辑、定时器（TON/TOF/TP）、计数器（CTU/CTD/CTUD）
  • 数学运算（Add、Sub、Mul、Div、Mod、Abs、Sqrt、Sin、Cos 等）
  • 比较器（EQ、NE、GT、GE、LT、LE）
  • 移动与转换、字逻辑、移位与循环、选择
  • 程序流（带参数连线的 FB/FC 调用、JMP/JMPN、RET、LABEL）
• 块编号 — 可自动分配，也可显式指定
• 自定义接口 — Input、Output、InOut、Static、Temp、Constant 区段

---

实时数据

live_data 工具可直接从正在运行的 CPU 读取实际值，包括数据块、标签表、监控表以及完整的 CPU 诊断缓冲区。在调试和快速开发反馈循环中，TiaCommander 尤其能发挥作用：修改块、下载，然后观察数值变化，全程无需离开 AI 客户端。

• 独立管道 — 实时读取通过专用辅助进程（S7 bridge）直接经 TCP 端口 102 与 CPU 通信，不依赖 Openness 工程连接，因此读取实时值不会干扰 TIA Portal 会话。
• 无需许可证，无需额外安装 — 实时数据通路不需要 Openness 许可证或其他 Siemens 软件；它直接使用 S7 协议通信。
• 同时支持 TLS 和明文连接 — S7-1200 V4.5+ 和 S7-1500 V2.9+ 通过 TLS 连接；较旧的 CPU 使用明文连接。connect 会报告当前 CPU 实际协商使用的连接方式。
• 优化块和标准块 — read_db 会返回优化和非优化（标准）数据块中的符号值及其质量代码。
• 支持密码保护 — 只有当 CPU 的保护级别要求时，才需要 CPU 密码；密码可加密后静态存储（按项目或全局存储），以便 connect 自动使用，并且绝不会记录或回显密码。可在管理器 GUI 的 凭据 选项卡中保存密码，也可以直接让 AI 助手保存 — 按 PLC IP 地址全局保存，或按项目保存。

---

安全性

MCP 服务将 PLC 部署操作视为破坏性操作。执行这些操作前必须提供明确的确认字符串：

操作	功能
download_to_device	将软件/硬件下载到正在运行的 PLC
upload_station	将 PLC 站上传到项目中
delete_unused_types	删除实例数为零的库类型

其他所有操作都在 TIA Portal 项目内执行，并且在下载前均可撤销。

---

独立 I/O

TiaCommander 可完全独立运行——无需外部文件管理工具。

每次导入均支持三种输入模式：文件路径、内联内容或导出数据库引用。

每次导出均支持三种输出模式：内联（默认）、导出数据库或文件。

导出内容会在 24 小时后自动过期。可通过 admin 工具操作进行管理。

不过，我们强烈建议将 TiaCommander 与 Desktop Commander（GitHub）搭配使用，融入日常 AI Agent 工作流。Desktop Commander 可让 AI 助手访问终端、管理文件，并在整个操作系统中编辑代码。这不是付费推广——我们每天都在自己的工作中使用 Desktop Commander，而且它恰好由我们的拉脱维亚同胞 Eduards Ruzga 开发。它免费、开源，能让一切变得更好。

---

数据与隐私

所有数据都保留在你的设备上。本地 SQLite 数据库会存储工具调用统计信息、设备配置文件、错误日志和临时导出缓存。

TiaCommander 会收集有限的遥测数据以改进产品：

• 错误报告——工具调用失败时，会发送错误类型和上下文，以便我们识别并修复问题。
• 工具使用统计信息——记录最常用的工具和操作，以了解哪些功能最有价值。
• AI 客户端信息——记录所连接的 AI 助手（客户端名称和版本），以确保兼容性。

PLC 程序数据、项目文件或块内容绝不会被传输。

你在注册时提供的个人信息（姓名、姓氏、电子邮件）受欧盟 GDPR 规则约束。我们不会与第三方分享、出售或披露你的数据。除非你明确提出要求，否则我们绝不会向你发送营销材料，或发送任何与你使用 TiaCommander 没有直接关系的内容。

---

接下来

TiaCommander 正在积极开发中。以下是我们的开发计划：

• HMI 集成——访问 HMI 屏幕、标签和报警视图
• 扩大实时数据覆盖范围——覆盖更多运行中的 PLC 可提供的数据，以及更多 CPU 系列
• 仿真支持——使用 PLCSIM 进行离线开发和测试
• 扩大硬件验证范围——在内部验证更多设备系列和固件，并根据真实使用情况进行指导

有功能创意？在 GitHub 上提交。

---

快速开始

**Claude Desktop（一键安装）：**从 Releases 下载 TiaCommander.mcpb，然后通过“设置 -> 扩展 -> 高级设置 -> 安装扩展”进行安装。完成。

所有其他 AI 客户端：****下载便携版 ZIP，并参阅**快速入门指南**——只需 5 分钟即可完成启动所需的一切：解压、Openness 组设置、为所有 7 个经过测试的客户端配置 AI 客户端、激活许可证并运行首批命令。

每个 AI 客户端的即用型配置文件都位于 configs/ 文件夹中。

---

许可证与反馈

TiaCommander 是由 SIA A4 Studio 发布的专有软件。在 Beta 期间，该工具完全免费，可无限制使用，并且所有工具均可用，没有任何限制。

作为回报，我们希望你能帮助我们改进 TiaCommander。如果你遇到 Bug、有新功能的想法，或者只是想分享你如何在工作流中使用该工具，我们都期待听到你的反馈：

• Bug 报告：github.com/a4webdev/tiacommander-mcp/issues
• 功能请求：github.com/a4webdev/tiacommander-mcp/issues
• 用户评价与反馈：tiacommander.com/wf/github

每一份报告、每一条建议、每一条评论，都能帮助我们为 Siemens 自动化社区打造更好的工具。

完整条款请参阅 LICENSE.txt。访问 tiacommander.com 了解更多信息。

---

商标

TiaCommander™ 是 SIA A4 Studio 的商标。Siemens、TIA Portal、SIMATIC、S7-1200、S7-1500 是 Siemens AG 的商标。TiaCommander 与 Siemens AG 无关联，未获其认可或赞助。

---

致谢

感谢所有提交 Issue 或向我们发送反馈的人——这些反馈确实能帮助我们改进 TiaCommander，我们也会认真阅读每一条。如果你的使用体验很顺畅，没有任何问题需要反馈，我们也很感激你能在代码仓库中点个 Star——这虽是小小举动，却能帮助其他 Siemens 工程师找到这款工具。