dsh-mcp-tia 插件说明

[!IMPORTANT] 装完不能直接用。 本插件只是"接线"，它不含 TIA Portal，也不含任何 TIA Portal MCP Server 可执行文件——西门子没有官方 MCP Server。从插件市场/命令安装后，你还需要自己准备一个 Openness MCP Server（见 后端怎么选）并填好路径，mcp__tia__* 工具才会出现。

• 自己配：按下面的 安装后还需要三步 做。
• 让 AI 帮你配：把 这段提示词 原样发给你的 DSH 会话，剩下的交给它。

安装本身不会再让 DSH 崩溃（failOnStartupError 已默认 false）；配置不对时的表现是"没有工具"，而不是"起不来"。

这是什么

dsh-mcp-tia 是一个 DSH（DeepSeek Harness）桥接插件，用来把一个本地运行的 TIA Portal MCP Server 接入 DSH，让你能在 DSH 会话里用自然语言读写博途工程（创建项目/设备、生成块与变量、编译诊断、保存）。

它不是 MCP Server 本身，也不包含 TIA Portal、Openness DLL 或任何西门子软件。 它只负责"接线"：启动你指定的 Server 可执行文件，把它暴露的工具注册成 DSH 的 mcp__tia__* 工具。真正驱动博途的是那个 Server，它通过西门子官方的 TIA Portal Openness API 操作本地已安装的 TIA Portal。

底层使用 DSH 宿主自带的 @deepseek-ai/dsh-mcp-client，本插件只是提供一份配置（cordis.patch.yml）。

前置条件（必须先准备好）

1. Windows——Openness 只有 Windows 实现，别的系统没有替代。

2. TIA Portal 已安装（V15–V21 均被社区项目覆盖）。注意版本差异：

   • V21 的 Openness 是模块化的：PublicAPI\V21\net48\Siemens.Engineering.Base.dll、…Step7.dll、…WinCCUnified.dll 等一组 DLL，没有单一的 Siemens.Engineering.dll。
   • V20 及更早是单体 Siemens.Engineering.dll。
   • 所以后端 exe 必须和你的博途主版本匹配（多数项目靠 --tia-major-version 选择）。

3. .NET Framework 4.8（Openness API 本身要求）。

4. 当前 Windows 用户加入本地组 Siemens TIA Openness，然后注销/重登——组权限重登才生效。这是最常见的"一切看起来都对但没有工具/一调用就报权限错"的原因。管理员 PowerShell：

   net localgroup "Siemens TIA Openness" "%USERNAME%" /add
   

5. 博途侧允许 Openness 访问（V17 起有对应的安全设置项）。后端自带的 doctor 子命令会检查这一项，先跑它。

6. 一个 Openness MCP Server 可执行文件（见下）。本仓库不提供。

后端怎么选

三个维护中的开源后端，都能被这一个插件接进来（只换 command/args）：

选择建议：

• 要写 SCL/LAD 代码（本插件的主要用途）→ heilingbrunner（能读写真·文本格式，见 能写梯形图吗）或 bulaofen（自带 SCL/LAD 指令库与模板，中文文档）。
• 只要小而安全的工具面 → Czarnak（工具最少、写操作有 dryRun 与内容哈希守卫、带审计日志），但只支持 V21。
• 想少编译、拿现成 exe → bulaofen 的 Release 包里是预编译运行时；它的 配置MCP.bat 只认 Claude/Cursor/VS Code，不认 DSH，所以在 DSH 里仍然要按本文手写这一行。

博途工程是二进制，Openness 的写入只在内存生效，必须再调保存类工具才落盘；下载到 PLC/在线模式不属于 Openness 的自动化范围，仍需人工。

安装

dsh plugin --profile desktop add github:yh01010/dsh-mcp-tia

（desktop 换成你的 profile 名。）安装后重启 DSH 生效——但注意：重启后不会自动出现工具，还要做完 安装后还需要三步。

也可以把 dsh-mcp-tia 加入 profile 的 package.json → dsh.profile.bundles 后 pnpm install，重启生效。

注意：本包不发布到 npm，只能从 GitHub 安装。

安装后还需要三步

1. 拿到一个后端可执行文件（上表任选一个），放到固定目录，例如 %USERPROFILE%\.local\bin\。多数后端要求先编译一次，或用它的 Release 预编译包。
2. 确认环境：用后端自带的 doctor 自检 .NET Framework、Openness DLL、Siemens TIA Openness 组成员身份与博途访问开关。先跑 doctor，再谈接线。
3. 填真实路径并重启：按 配置 一节在 $DSH_HOME/cordis.patch.yml 里覆盖 command，重启 DSH，工具列表里应出现 mcp__tia__*。

让 AI 帮你完成配置

不想手改配置，就把下面这段原样发给你的 DSH 会话：

请帮我把 DSH 的博途插件（dsh-mcp-tia）配置到可用状态，参考
https://github.com/yh01010/dsh-mcp-tia 的 README。

现状：插件包已装好，但 mcp__tia__* 工具没出现，因为
cordis.patch.yml 里还是占位路径。

请依次做：
1. 先确认本机 TIA Portal 的主版本和安装根目录（例如
   C:\Program Files\Siemens\Automation\Portal V21）。V21 的 Openness
   是模块化的 PublicAPI\V21\net48\Siemens.Engineering.Base.dll，
   没有单体 Siemens.Engineering.dll，选后端时必须匹配。
2. 确认当前用户是否已在本地组 "Siemens TIA Openness" 里；不在就先
   告诉我需要管理员执行 net localgroup 命令并注销重登。
3. 检查我选定的后端可执行文件是否存在；不存在就告诉我该从哪个
   项目/Release 取、放到哪里，并先把它的 doctor 子命令跑通。
4. 编辑 $DSH_HOME/cordis.patch.yml，用「id 覆盖」写法（不要用 insert，
   否则会出现两行同 id，serverName 冲突导致启动中止）填上真实路径：
   command: 
   args: 
5. 提醒我重启 DSH，重启后确认 mcp__tia__* 工具是否出现；先只跑只读
   工具（列设备/导出块），确认无误后再决定是否打开写模式。

不要改动插件包内部的 cordis.patch.yml。
不要在没有备份的工程上执行任何写操作。

前提：会话要有该文件的写入权限。$DSH_HOME 通常在会话工作区之外，可能触发一次权限确认。

配置

本插件刻意不携带任何个人机器路径，cordis.patch.yml 里的 command/args 是占位符。你必须改成自己机器上的真实路径。

两种接法 二选一，不要同时用：

[!WARNING] 插件包已装、又在 home patch 里 insert 同一 id 的行 → 会得到两行同 id → 两个 mcp-client 实例抢 serverName: tia → DSH 启动时报 serverName "tia" is already in use by another mcp-client instance 并中止。这是最容易踩的坑。

id 覆盖写法（装了插件包时用这个，不会改到仓库文件）：

# $DSH_HOME/cordis.patch.yml
- id: mcp-tia
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: tia
    transport: stdio
    command: 'C:\Users\\.local\bin\TiaMcpServer.exe'
    args:
      - '--tia-major-version'
      - '21'
      # 确认只读可用后再加：
      # - '--allow-write'
    toolCallTimeoutMs: 180000
    failOnStartupError: false

关键配置项：

路径含空格：在 YAML 单引号字符串里直接写整串即可，例如 'D:\Program Files\your\tia\TiaMcpServer.exe'（注意本包内示例均用占位路径，真机路径只写在 home patch 里）。

能写梯形图吗（LAD/梯形图）

能——而且是文本写法。 但也不要手写 SimaticML FlgNet XML：这是后端写死的规则，GetAuthoringGuide('lad') 原文：

NEVER hand-write FlgNet XML for ladder logic — UId bookkeeping and entity escaping make it fail constantly.

可靠路径是 S7DCL 梯形图文本（SIMATIC SD，在 S7-1500 / V21 上编译验证过）：

AI 写 .s7dcl 梯形图文本（+ 可选 .s7res 承载中文文本）
   → ImportFromDocuments / ImportBlocksFromDocuments
   → CompileSoftware → SaveProject

S7DCL 梯形图长什么样

{ S7_Optimized := "TRUE"; S7_PreferredLanguage := "LAD"; S7_Version := "0.1" }
FUNCTION "Name" : Void
    VAR_INPUT  Start : Bool; END_VAR
    VAR_OUTPUT Run   : Bool; END_VAR
    { S7_Language := "LAD" }
    NETWORK
        RUNG wire#powerrail
            Contact( #Start )
            Coil( #Run )
        END_RUNG
    END_NETWORK
END_FUNCTION

三个最容易踩的坑：

1. 每个 NETWORK 前面都必须有它自己的 { S7_Language := "LAD" }。漏了会报 Syntax error 'NETWORK' expecting END_FUNCTION_BLOCK（真实导出的 10147 个网络里，每一个都带这个 pragma）。
2. 通用指令需要 { S7_Templates := "..." }，且模板名因指令而异（SrcType 用于比较/数学、DestType 用于 Convert、time_type 用于 IEC 定时器、date_type、str_type）。写错时错误信息会列出 Allowed Template Names:，照抄那串，别猜。
3. 编码是头号杀手：.s7dcl / .s7res 一律 UTF-8 带 BOM；.scl 只在纯 ASCII 时才可以不带 BOM，含中文要么加 BOM 要么注释全用 ASCII——否则会被当 GBK 读，得到乱码 + 假的语法错误。

一个块里混用 LAD + SCL

块头保持 S7_PreferredLanguage := "LAD"，每个 NETWORK 各带自己的 { S7_Language := "SCL" }，SCL 网络里写普通 SCL 语句（没有 RUNG）。这是"梯形图块里做算术"的官方做法。

读懂已有的 LAD

用 DescribeBlockLogic，不要把块导出来手工追线。它把每个 rung 还原成可读表达式（串联 ·、并联 +、常闭显示为 /操作数），列出线圈与 MOVE/比较/定时器框，并且会标出接在字面常量上的触点（⟨恒断·禁用本行⟩——常开触点接 FALSE 会静默废掉整行，肉眼几乎看不出来）。

实操建议

• 写 LAD/SCL 之前先 GetAuthoringGuide('lad' | 'scl' | 'db' | 'hmi' | 'errors')——后端反复强调 “Most quality problems come from skipping this”。
• 某个元件不确定写法：先对一个真实 LAD 块跑 ExportAsDocuments，抄它导出的 .s7dcl 结构（SD 比 XML 小约 9 倍且可读）。
• 只需要"调用一个 FC"的网络，可以直接用 BuildFlgNetCallXml / ComposePlcLadFcBlockXml，它们替你生成 XML。
• 写完必须 CompileSoftware（或 CompileAndDiagnosePlc），再 SaveProject——不会自动保存。
• 语言在建块时就定死：Openness 不会把 SCL 自动翻译成 LAD。
• F-LAD / 安全程序：PublicAPI 不暴露 F-CPU 编译，要在 TIA UI 里手工触发；安全块与安全变量也拒绝多数修改。

各后端的 LAD 路径：

安装后验证

1. 重启 DSH 后，看工具列表里是否出现 mcp__tia__*。

2. 若没有，先手动确认后端 exe 存在、且能独立启动并自检：

   Test-Path 'C:\Users\\.local\bin\TiaMcpServer.exe'
   & 'C:\Users\\.local\bin\TiaMcpServer.exe' --doctor
   

   后端能独立启动但工具仍不出现，说明问题在 DSH 接线（patch/配置），不在后端。

3. 接上后先只做只读：列设备、列块、导出块，确认 AI 看到的工程结构和你的一致，再考虑开写模式。

4. 装了 dsh-mcp-panel 的话，可以在设置页看这个 MCP 的连接状态、已注册工具、错误与重连计数。

排障

安全提醒

以下操作必须人工确认后再执行，且先备份工程：

• 写入任何东西到生产工程（先只读跑通，再开写模式）
• 修改硬件地址、网络参数、通信设置
• 删除设备、块、变量表、库
• 修改安全相关对象或 Know-how 保护对象
• 下载到 PLC/HMI、进入在线模式——不属于本插件范围，也不在 Openness 的自动化能力里

推荐在 PLCSIM（S7-PLCSIM / PLCSIM Advanced）的离线工程上先验证整条链路。

移除

dsh plugin --profile desktop remove dsh-mcp-tia

（或从 dsh.profile.bundles 移除后 pnpm install），重启生效。想临时停用，可在 profile 的 cordis.patch.yml 里给 mcp-tia 行加 disabled: true。

许可证

MIT。本插件与西门子（Siemens AG）无隶属关系；TIA Portal、SIMATIC、STEP 7、WinCC 是西门子商标。Openness DLL 与博途本体不随本包分发，需自行安装并遵守其许可条款。

说明来源

• 西门子官方：TIA Portal Openness API 文档
• 三个后端各自的 README（工具清单、doctor、写模式开关、已知限制）
• 社区汇总：TIA Openness / MCP 开源项目清单