PLC

用 TiaLink 为遗留的博途 PLC 项目生成文档

我劝你先别写那份说明。三页纸讲不清一套老程序，五张表可以，还能被抽查。

admin

— 阅读时间 12 分钟
分享
用 TiaLink 为遗留的博途 PLC 项目生成文档

你要交接一套跑了十几年的程序。设备还在跑，程序没人敢碰，注释是 M10.3、DB12.DBW4 这种缩写，写它的人已经不在了。

这时候最想干的事，是写三页纸，讲清楚它在干什么，签个名，交出去。

我劝你先别。

不是写得不好。是这么写出来的东西，接手的人没法拿它做任何事。

一、三页说明答不了的问题

交接的时候，真正卡住人的从来不是"这套程序在干什么"，是几件特别具体的事：

  • 现场这根线，接的是哪个点？
  • 我要动这个块，还有谁会跟着遭殃？
  • 这个 DB 里的字，是谁写进去的？

三页说明一个都答不了。它能给你的只有一句"本程序实现上料、夹紧、加工、下料的顺序控制"。你要是真照着这句话去改程序，那是你胆子大。

另一种写法也很常见：把博途手册抄一遍，配几张截图。讲的是 PLC 能做什么，不是这台设备在做什么。截图更麻烦——程序改一行，全部作废，还搜不到东西。

这两种写法都缺同一样东西：每一行都能翻回工程里指出来。

二、五张表，各回答一个问题

要说清一套老程序，就五张表。不是凑数，是五个不同的问题。

表 它回答什么 最容易出错的地方
IO 表 现场这根线，进的是哪个点？ 同一个地址，硬件组态和变量表里叫法不一样
块清单 一共多少块，哪一层在最外面？ 有 FB 从来没被调用过（以前做实验留下的）
接口表 这个块要什么、给什么？ 形参注释空着，实参传的是临时变量
调用关系 改这个块，谁会跟着受影响？ 调用它的不止 OB1，还有一个中断 OB
变量与 UDT 表 这个 DB 成员从哪来、到哪去？ UDT 套 UDT，真正的物理量在第三层

五张里最实用的是 IO 表——现场接线、停电复现、查点，都靠它。最容易糊弄的是接口表，因为字段多，看着填满就行，其实最容易填错。

最容易翻车的是调用关系。你以为只有 OB1 在调那个块，翻一下发现还有个中断 OB 也在调，改完之后平时不报错，一到特定工况就出问题。

五张表凑齐，"项目里有什么"才算说完了。缺哪张，那次交接就一定有人替你猜。

三、AI 最爱干的事，是替你把话说圆

让模型读一段梯形图再解释，它会给你一段很顺的话。我第一次看到这种东西时还挺高兴——"急停延时复位"这种词都用上了，看着挺懂行。

后来我盯着那句看了半天，发现它是编的。

❌ FB12 实现急停延时复位，确保安全门关闭后设备才能启动。

✅ FB12 读 I0.0、I0.1，写 Q0.2；被 OB1 第 3 段调用；块内没有置位。

第一句读着顺，但它自己补了一条因果链。更要命的是，"急停延时复位"意味着安全功能——安全功能本来就不该写在这段标准程序里，该在安全继电器或者安全 PLC 里。模型看见"急停"两个字，顺手就把整套安全逻辑补上了。

第二句干巴巴的，但每一句都能在工程里指出来：哪个输入、哪个输出、谁在调、有没有置位。这就是区别。

所以规则只有一句：注释是空的块，只写它读了什么、写了什么、被谁调用。想下业务结论，另起一页，标题就叫"我的推测"，让人签字。

四、每行加一栏，问题就解决一半

知道"要能指回去"以后，做法特别笨：每行多写一格，写清楚这条是从哪儿看到的。

结论 在哪看到的 工程里的原文
FB12 由 OB1 调用 调用关系 › OB1 CALL FB12 在 OB1 第 3 段
I0.0 是数字量输入 硬件树 › 槽 4 DI 16×24VDC，起始地址 0
M10.3 被两处写 交叉引用 › M10.3 写：FB12 第 7 网络；FB20 第 2 网络

（上面是格式示例，不是哪个工程的数据。）

就这么一格，把一份"读后感"变成了能抽查的东西。谁不信，翻到那一行，自己看。

两个地方别偷懒。

读不到就写"未读到"。 它本身就是个结论：可能是块被加密，可能是库里的块，也可能接口本来就是空的。留白最糟——下一个人分不清是"确实没有"还是"你漏了"。

名字对不上是常态。 硬件组态里一个名，变量表里一个名，程序里又一个名。三列都留着，现场才追得下去。

五、动笔之前，先把工程存一份

文档还有一栏，几乎所有人都会漏：它对应哪一天的工程。

三个月后有人问"这份还准吗"，你能给出的确定答案只有一句——"能对上某年某月某日存的那份"。所以顺序要反过来：

  1. 把块和工程导出，存到一处，记下路径、大小、sha256、时间；
  2. 记下博途版本（V19 / V20 / V21 的对象模型不完全一样）；
  3. 文档开头写一句"依据 <时间> 的存档"。

这么干还有个附带好处：写的过程中谁动了工程，最后核对时哈希对不上，你当场就知道。

六、这段话可以直接复制

真正省时间的不是"帮我写文档"这四个字，是把五张表、出处、不许猜这三件事一次说清。下面这段可以直接发过去：

只读，不要改工程。工程 <名>，按顺序做五张表：
IO 表、块清单、接口表、调用关系、变量与 UDT 表。

要求：
1) 每行写三格：结论 | 在哪看到的 | 工程里的原文；
   读不到就写"未读到"，不许推测、不许补全；
2) 注释是空的块，只写读了什么、写了什么、被谁调用，不写业务含义；
3) 五张表做完，另外列三节：没有被谁调用的块、引用了却找不到定义的符号、
   块类型分布与总数；
4) 最后写清楚五张表各有多少行、存档路径和 sha256、博途版本。

第 3 条别省。"没有被调用的块"和"引用了却找不到定义的符号"，往往比五张表本身更有用——前者是以前留下的雷，后者决定这次交接能不能收尾。

七、交出去之前，自己核四遍

AI 做的表看着整齐，错的地方很隐蔽。四遍都对着工程原件核，别对着文档自查。

  1. 块数对不对。 表里的块数，跟块目录里的条数一致才算过。差一个就重读那一块，别手补。
  2. 接口有没有漏。 抽三个块，逐项比对读回来的结果。漏了字段就重读，别照着截图补。
  3. 调用关系闭不闭合。 每一个被调用的块，都要能在调用者里找到。找不到，要么是动态调用，要么是根本没定义，单独写一句说明。
  4. 存档能不能复现。 同一组参数再导一次，sha256 一致才算过。不一致说明工程被人动过，存档重做。

第二条最容易翻车。接口表字段多，模型特别容易把静态变量和临时变量写进同一列——这两者活着的时间完全不一样，混在一起，后面做影响分析会得出相反的结论。

八、先把做不到的说清楚

这几句话最好开工前就跟接手的人说清，免得对方按"厂家手册"的预期来收。

能给的：五张表、导出的文件和哈希（可以拿两个版本比差在哪）、"改这个块会影响谁"这类查询结果。

给不了的：逐条网络的注释式说明（那得人一段段读）、带图排版的手册和符号表报表（那是博途插件的活）、安全功能的结论（安全逻辑本来就不在这段程序里）。

还有一点挺重要：这套活全程只读，不需要授权写入。你可以先拿一套老工程把五张表跑出来，看看质量，再决定要不要让 AI 碰改程序的事——真要让它写，先看AI 改博途程序的写保护与边界。

九、先装技能包

技能叫 tialink-tia-portal。只装这一个，一条命令：

npx skills add https://github.com/tia-forge/tiaforge-plugins --skill tialink-tia-portal

它自己认客户端：Claude Code、Cursor、Codex、GitHub Copilot、Windsurf、Gemini、Cline、AMP、Antigravity、OpenClaw、CodeBuddy，还有 pi——都在名单里，脚本会往各自的技能目录放。pi 收到的是 ~/.agents/skills/，它启动时正好扫这个目录，不用再改配置。

技能页在 skills.sh 上的 tialink 博途技能，内容跟着仓库里的 SKILL.md 走。

WorkBuddy 和 DSH 不在这个名单里，要单独装。

WorkBuddy：技能 → 技能市场 → SkillHub 分栏，搜「博途」或「TIA Portal」。市场里找不到的话，下这个压缩包（10 KB），在桌面端「上传技能」里传上去： https://github.com/tia-forge/tiaforge-plugins/raw/main/zip/tialink-tia-portal-1.0.9.zip

DSH：从界面装就行，不用碰命令行。打开 DSH，左上角【插件】→ 输入 dsh-tiaforge → 点安装 → 完全退出 DSH 再打开（服务连接是启动时建立的，不重开不生效）。DSH 没有"只装一个技能"的入口，装进去是整包五个，tialink 是其中一个。

pi 如果想把配套的几个服务一起配好，也有一条整包的装法：pi install npm:pi-tiaforge，装完 /skill: 补全里能看到五个。

装完先别让它写文档。让它读一遍工程、把块清单报出来，块数对得上，再往下走。想看它从空工程一路跑到仿真是什么样，可以照Claude Code 接博途的完整链路走一遍。

十、技能之外，还得有个网关

这点容易被跳过：技能只教它怎么做，真正读工程的是跑在博途同机上的那个 TiaLink 网关。 没有它，技能装得再对，第一步「打开工程」就会失败。

顺序是这样的：

  1. 准备机器。 Windows 64 位，博途 V19 / V20 / V21 已装已授权。跑网关的那个 Windows 账号要加进本地 Siemens TIA Openness 用户组——没有这一步，Openness 一律报授权错误；加完记得注销重登，组权限要重开会话才生效。
  2. 装网关。 先把它拷到最终目录（比如 C:\Program Files\TiaLink\）再运行，Openness 的白名单是按路径登记哈希的；跑一次自带的修复工具；用普通用户启动，别用管理员。
  3. 起博途，再起网关。 顺序反了连不上。网关起来后在浏览器打开 http://localhost:8080/，在那里配一个令牌。
  4. 把地址和令牌填进客户端。 地址必须以 /mcp 结尾（http://192.168.x.x:8080/mcp），令牌放在请求头 Authorization: Bearer <令牌> 里。只会 stdio 的客户端不用折腾，用现成的转发：TIALINK_URL=… TIALINK_TOKEN=… npx tialink-mcp。
  5. 先自测，别急着让它干活。 在客户端那台机器上跑：
curl -sS -o /dev/null -w "%{http_code}\n" http://<网关IP>:8080/mcp

返回 4xx 也算通（网络到了，只是缺令牌）；Connection refused 或者超时，才是网关没起来或者端口不对。

一个能省很多试错的事实：没授权也能读。 读工程、读块、读硬件树都不用授权，只有写入才需要。也就是说上面那个"跑一遍五张表看质量"的动作，在没买授权的情况下就能做完。

网关跟博途装同一台 Windows 上，下载和授权都在 TiaLink 博途 MCP 网关 这一页。

十一、明天先做三步

  1. 存档，数块。 导出、记哈希、数清有多少块、哪几种类型。这一步不用理解任何一段程序，但它决定后面所有核对有没有基准。
  2. 挑五个最常被问到的块，把接口补齐。 不用一次做全项目。先把"新人一定会问"的那几个做扎实，顺手把格式定下来。
  3. 把"我的推测"单独写一页，让人签字。 猜的东西不是不能写，是不能混在事实里。签字栏空着，这份文档就还不算交出去。

来源与口径：五张表、出处格式和四项核对来自 TiaLink 技能包（tialink-tia-portal）的"逆向文档"一节，CC BY 4.0；文中示例行只用于演示格式，不含任何真实工程数据。AI 整理出的文档必须人工复核后才能用于交接和生产。

本文由汇智网原创整理，转载请注明出处。

这是「AI × 工业 / PLC」专题的一部分。完整地图见：AI × 工业 / PLC 完全指南

阅读更多