> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 用 TiaLink 为遗留的博途 PLC 项目生成文档
- URL: https://www.hubwiz.com/blog/reverse-documentation-tia-portal/
- Published: 2026-11-07T08:25:54.000Z
- Updated: 2026-11-07T08:28:52.000Z
- Description: 我劝你先别写那份说明。三页纸讲不清一套老程序，五张表可以，还能被抽查。
- Author: admin
- Tags: PLC, 博途, TIA Portal, 工业 AI, AI Agent

你要交接一套跑了十几年的程序。设备还在跑，程序没人敢碰，注释是 `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. 文档开头写一句"依据 <时间> 的存档"。

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

---

## 六、这段话可以直接复制

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

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

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

```

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

---

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

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

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

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

---

## 八、先把做不到的说清楚

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

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

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

还有一点挺重要：**这套活全程只读**，不需要授权写入。你可以先拿一套老工程把五张表跑出来，看看质量，再决定要不要让 AI 碰改程序的事——真要让它写，先看[AI 改博途程序的写保护与边界](https://www.hubwiz.com/blog/tia-portal-openness-mcp-write-guards/)。

---

## 九、先装技能包

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

```bash
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 博途技能](https://www.skills.sh/tia-forge/tiaforge-plugins/tialink-tia-portal?ref=hubwiz.com)，内容跟着仓库里的 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 接博途的完整链路](https://www.hubwiz.com/blog/claude-code-tia-portal-mcp/)走一遍。

---

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

这点容易被跳过：**技能只教它怎么做，真正读工程的是跑在博途同机上的那个 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. **先自测，别急着让它干活。** 在客户端那台机器上跑：

```bash
curl -sS -o /dev/null -w "%{http_code}\n" http://<网关IP>:8080/mcp

```

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

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

网关跟博途装同一台 Windows 上，下载和授权都在 [TiaLink 博途 MCP 网关](https://tia.hubwiz.com/tia-link?utm%5Fsource=blog&utm%5Fmedium=article&utm%5Fcampaign=reverse-documentation-tia-portal&utm%5Fcontent=cta) 这一页。

---

## 十一、明天先做三步

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

---

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

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

> **这是「AI × 工业 / PLC」专题的一部分。**完整地图见：[AI × 工业 / PLC 完全指南](https://www.hubwiz.com/blog/ai-industrial-stack/)