读懂一套没注释的博途老工程

本课做一件接手老项目时最费时间的事：把一套没注释的博途工程读明白，并产出一份能交接的文档包。你输入一段需求，agent 只读盘点、按块和网络讲清逻辑、把硬件/网络/点表/报警/参数/HMI 映射都整理出来，每条结论给出证据，最后交付《工程说明书》和《人工核对清单》，工程零改动。

本课流程已在 TiaLink 1.1.0.0 + TIA Portal V19 上实测：对象是一套 PLC_SCADA_HMI 工程——S7-1500（CPU 1513F-1 PN）+ 两套经典 HMI + ET200SP，5 个块（OB 1 / FB 2 / DB 2，全 LAD）、2 张变量表共 51 个标签、HMI 3 个画面 40 个变量。全程只读，读完工程状态与开始时一致。

这套示例工程是开源的（MIT）：rassulz/multirobot_painting_control_system。仓库里的 PLC/PLC_SCADA_HMI.zap19 就是本课用的工程，可以直接用博途 V19 打开——想复现本课，把它当练习对象即可。

这课的重点不是「让 AI 说点什么」，而是让它的每句话都能被你核对：已确认的、推断的、无法确认的，必须分开写；能自动读到的（硬件、网络、点表、参数）一条都不要漏。

口径：AI 是辅助理解，结论必须人工复核。读工程不产生修改，但给你的说明书可能含工艺/客户信息，外发前要脱敏。

• 只读盘点一套工程：设备与软件、块清单、变量表、HMI 规模、调用关系；
• 把硬件与网络读出来：CPU 型号/订货号/固件、机架模块、IO 地址、子网与设备 IP、PROFINET IO 系统；
• 把完整点表读出来：逐个标签（名称/类型/地址/注释），并标出未被 PLC 程序引用的标签；
• 把报警与仿真表读出来：每条报警/仿真位对应什么设备、被哪些块引用；
• 把参数读出来：定时器/计数器的类型、实例、设定值（从导出接线还原）；
• 让 agent 按「块 → 网络 → 变量」讲逻辑，每条结论带证据（块名 + 网络号）；
• 分清三类结论：已确认 / 推断（待核对）/ 无法确认；
• 产出一份可交接的《工程说明书》+《人工核对清单》，并确认工程零改动。

• Windows 机器，已安装 TIA Portal V19（TiaLink 当前基于 V19 与 Openness 构建）；
• TiaLink：在 TiaLink 页面 下载并启动，打开要读的工程。读工程是只读操作，但不要在没备份的工程上做实验；工程如果本来就有未保存修改，先记下状态当基线；
• 一个支持 Streamable HTTP MCP 的客户端（Claude Code、Cursor、VS Code 等），MCP 端点为 http://localhost:8080/mcp；
• 练习对象：你自己的老工程；想复现本课就用上面的开源示例工程（PLC/PLC_SCADA_HMI.zap19，MIT），或在示例库导入 分拣箱（Factory IO） 练手；
• 一条只读纪律：不要保存工程。另外，未编译一致的块导出会被挡——真需要读那部分时，先征得工程主人同意再编译。

真实使用只有一次输入：说清「只读、要哪些交付物、怎么给证据」。读设备、读硬件、导出网络、还原参数、归纳说明书都是 agent 自己做的。

第一步：配好 TiaLink 与 MCP

在博途那台机器上启动 TiaLink、打开工程。页首状态条会自动检测；然后在客户端里加一个 Streamable HTTP MCP 服务：

先在本页顶部点「设置」填一次地址（存在本机，示例库页面也用同一个地址），下面的 URL 会跟着更新，点「复制」贴进客户端配置：

{
  "mcpServers": {
    "tialink": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer <你的 TiaLink API Token>" }
    }
  }
}

看到什么：客户端列出 TiaLink 的工具（名字以 tialink_ 开头，覆盖健康检查、读工程、硬件、导出、编译、保存等）。工具数量随版本变化，不必对数字。

第二步：你输入的（全部内容）

把下面这段发给 agent（练习对象换成你的工程）：

只读，不要修改任何对象，也不要保存工程。请把当前工程整理成一份可交接的《工程说明书》：

1. 概况：设备与软件、CPU 型号/订货号/固件、HMI 类型、块清单（类型/编号/语言）、编辑语言、读取前的工程状态；
2. 硬件与网络：机架与模块（订货号）、各模块 IO 地址、子网与每台设备的 IP、PROFINET IO 系统；
3. 结构与调用关系：谁调用谁、实例 DB 归属；
4. 完整点表：逐个列出标签（名称、类型、地址、注释），并把「未被 PLC 程序引用」的标签单独标出来；
5. 报警与仿真表：每条报警/仿真位对应哪个设备、被哪些块引用；触发后的行为能确认才写；
6. 参数：定时器/计数器的类型、实例名、设定值（PT/PV），从导出接线还原；
7. HMI 与上位：画面清单、HMI 变量与 PLC 变量的映射、上位机/机器人接口的边界；
8. 逐块说明：每个块做什么、关键网络在做什么；
9. 问题清单、推断清单、无法确认清单。

每条结论标注依据（块名 + 网络号 / 硬件路径）；只能推断的标注「推断」，无法确认的标注「无法确认」。不要猜。

发完这一条，你等着看结果就行。下面是它实际会做的事（本次实测过程）。

agent 实际做了什么：盘点规模，再读硬件与网络

它先确认连接和项目名，然后盘点整套工程的规模——先有全局，再谈细节：

接着读硬件树和网络——这些是接手时最先要的"物理事实"：

• CPU 是 F 型（1513F-1 PN）：这可能意味着存在安全功能或至少是安全型硬件，但程序里没有 F 块——必须人工确认，说明书里单独列为安全项；
• IO 地址能对上工艺点：ET200SP 的 DI 8x24VDC ST_2 起始地址 Input29，正好对上 ZS-101..104 的 %I29.0–29.3——这种交叉验证能把"变量表"和"实物模块"绑在一起。

agent 实际做了什么：读接口与网络，收集逻辑证据

然后它读接口、导出块，按网络收集证据。Main 的模式选择网络长这样（由 agent 读的同一份导出渲染，示例库同款渲染器）：

把这张图和说明书里的结论对照，就是「证据绑定」的实际操作：结论说「Net1 由 PS103/HMI_PS103 选择 Auto_mode」，你可以直接在图里点着看。实测中立刻撞上老工程的三个典型形态：

• 空接口的 FB 不是空块：Auto_mode/Manu_mode 的接口区一个参数都没有，逻辑全写在对全局变量（ZS-*、CV-*、HMI_*、SIM_*）的读写上——这决定了「改动影响面」要用变量去追，而不是用接口；
• 单个巨型网络：两个 FB 各只有一个网络，Auto_mode 那个网络里有 36 个操作数；把它当「一条 rung」讲一定是错的，只能按功能段拆（传感器链、执行器链、报警/仿真、MATLAB 握手）。整张图长这样——一屏放不下，肉眼很难按时序读完：

• 空网络：Main 的 Network 3/4 什么都没有——老工程遗留，不影响运行但会干扰阅读，值得在说明书里单列。

agent 实际做了什么：把参数和"没人用"的标签也挖出来

交付级文档和"摘要"的区别就在这里：它从导出 XML 的接线里还原出定时器/计数器的设定值，又把 51 个标签和三个块实际引用的符号做了对账：

• 参数：Auto_mode 里有一个 TP 设定 5s、两个 100ms、一个 TON 1s，计数器 PV=100；Manu_mode 复用同样的 100ms/1s 与 PV=100。用途（比如 5s 对应哪一步）标成推断；
• 未引用标签：51 个里 6 个没有被任何 PLC 块引用——HMI_Main、HMI_PID、HMI_Status、Alarm_Collection、System_Byte、check。其中 HMI_PID 值得注意：HMI 里有 PID 画面，但 PLC 程序里没有 PID 块、HMI_PID 也没被引用——PID 回路可能没实现，需要人工确认。

agent 实际做了什么：产出《工程说明书》

最后它把证据整理成文档，并且把不确定的部分明确标出来：

完整产物如下（本次运行生成；展示时只做了排版，内容未改）：

你得到什么

• 一份交付级《工程说明书》：概况、硬件与网络、调用关系、完整点表、报警与仿真表、定时器/计数器参数、逐块说明、HMI 与上位边界、安全项；
• 一份《人工核对清单》：推断项（逐线核对）+ 无法确认项（去另一侧补齐）——这就是你接下来的工作面；
• 工程零改动：读之前记的 dirty 状态，读之后应当还是原样（本课实测全程无写入）。

需要你动手的地方（很少）

• 允许编译（可选）：遇到未编译的块，导出会被挡；如果确实要读，先确认能不能编译一次（编译属于改动，读完别保存）；
• 安全评审：F 型 CPU、急停链、联锁——必须人工确认，不能采信自动生成的结论；
• 核对「推断」项：按说明书里的指向，去博途里逐线看一遍；
• 去另一侧补齐：HMI 控件绑定、MATLAB/KUKA 协议、dirty 明细、M 区保持性；
• 确认零改动：博途里没有新的未保存修改。

可选：想逐步监督时的分步指令

正常使用不需要；如果你想在每一步停下来看，可以用这些指令：

• 读工程前后状态一致：没有新的未保存修改，也没有保存过；
• 说明书覆盖：概况、硬件与网络、块清单、调用关系、完整点表、报警表、参数表、HMI 与上位边界、安全项；
• 点表逐个列出（名称/类型/地址/注释），并标出未引用标签；
• 硬件与网络有订货号、IO 地址、设备 IP；关键 IO 与工艺点做过交叉验证；
• 定时器/计数器给出实例与设定值；
• 每条逻辑结论能指到块/网络；推断与无法确认都有明确标注；
• 老工程典型问题被列出（空网络、空接口、巨型网络、命名混乱……）；
• 未编译块被明确标出，或已征得同意后编译；
• 外发前做过脱敏（工程名、客户信息、工艺参数）。

• 只给「变量分组」不给完整点表：分组是摘要，交付要逐个标签；未引用标签往往藏着废弃变量或 HMI-only 变量。
• 忽略硬件与网络：CPU 型号、模块订货号、IO 地址、IP 是接手的物理事实，TiaLink 都读得到；不写进说明书就有缺口。
• F 型 CPU 的安全功能被当普通逻辑：程序里没有 F 块不代表没有安全要求；安全相关必须人工确认。
• 定时器/计数器参数靠猜：设定值要从导出接线还原（PT/PV），不要按名字猜时长。
• 把「接口为空」当「块是空的」：老工程常把所有逻辑写在全局变量上，接口区什么都看不到；必须读块内容。
• 把巨型网络当一条 rung 讲：几十个操作数的网络要按功能段拆，拆不出来就标「无法确认」，不要硬编故事。
• 忽略空网络/废弃块：不影响运行，但会让接手的人误判；说明书要单列。
• dirty 明细读不到：TiaLink 只报告 dirty，不列改动；接手前要在 TIA 里人工搞清楚。
• 导出被未编译块挡住：会提示先编译。只读场景下编译要先征得同意（编译会改动工程状态，读完别保存）。
• 只读也会点保存：agent 如果顺手调了保存，那就不再是只读——提示词里要写死「不要保存」。
• HMI 不在 PLC 说明书里：画面控件绑定、用户管理要单独读 HMI 侧；别把「PLC 里没读到」写成「不存在」。
• 说明书不配网络图：文字结论 + 同源渲染的网络图，核对成本最低；尤其模式选择、联锁这类关键网络，一张图比一段话有用。
• 说明书外发不脱敏：工程名、设备命名、工艺参数往往就是客户信息。

• 参考工程：rassulz/multirobot_painting_control_system（MIT）——本课实测用的开源工程，多机器人涂装线（S7-1500 + SCADA/HMI + MATLAB/Simulink 上位机），适合拿来反复练「读懂」；
• 想进一步知道「改一个 UDT / IO 地址会波及谁」，看下一课《变更影响分析》（待上线）；
• 想让 AI 直接动手写代码，看 《写一段 SCL：从需求到编译 0 错误 0 警告》；
• 练习工程：分拣箱（Factory IO）——从示例页导入后，用同样的提示词读一遍。