plc-code-toolkit

PLC代码分析与审查工具包。12个维度系统化分析InoProShop/CoDeSys ST语言PLC代码，输出结构化报告和问题清单。

PLC Code Toolkit — PLC代码分析与审查工具包 v1.1

对 InoProShop / CoDeSys ST 语言的 PLC 代码进行系统化、多维度分析与审查，输出结构化报告，帮助工程师识别潜在问题、安全隐患、逻辑缺陷和可维护性不足之处。

两种模式

模式	目的	适用场景
分析模式	理解程序、梳理逻辑、描述程序做了什么	接手新项目、理解他人代码、文档化
审查模式	评判质量、找漏洞、给修改建议	代码投产前检查、质量审计、安全审查

---

工作流程

1. 读取目标文件 — 使用 Read 工具读取用户指定的 PLC 文件（.st / .action.st / .fb.st / .prg.st / .gvl / .dut）
2. 识别代码类型 — 判断是主控程序（ACT）、功能块（FB）、程序（PRG）还是全局变量（GVL）
3. 选择模式 — 分析模式（12个维度）或审查模式（6个核心维度）
4. 逐维度执行 — 按选择的维度逐一分析/审查
5. 汇总问题清单 — 按优先级（高/中/低）列出所有发现的问题
6. 给出改进建议 — 针对每个问题给出具体可操作的修改建议（附代码片段）

---

12 个分析/审查维度

维度1：程序结构

• PRG / FB / ACT 层级关系与组织是否清晰
• 功能块调用链与依赖关系
• 工位/模块划分的合理性
• 代码块的顺序是否符合执行逻辑

维度2：控制逻辑

• 使能条件的完整性和正确性
• 初始位判断条件是否充分
• 自动/手动模式切换逻辑是否完善
• 启动完成条件是否有实质性检查
• 重点检查：OR 与 AND 混用时的运算符优先级问题（ST语言中最常见的逻辑缺陷）
• 工位间的耦合逻辑是否可能造成死锁（A → B、B → A）
• 布尔运算优先级是否正确（混用时是否加括号）

维度3：安全联锁

• 急停回路（EStop）的覆盖完整性
• 安全门（防护装置）联锁一致性
• 各工位防护装置有效条件的差异分析
• 硬编码 TRUE 用于安全相关字段的风险评估
• 工位使能条件是否包含急停信号
• 设备启动条件是否存在可被 HMI 旁路的安全信号

高优先级标准：任何防护装置硬编码 TRUE、急停未覆盖的工位、可能被 HMI 绕过的安全联锁

维度4：信号映射

• DI（数字输入）信号使用情况梳理
• DO（数字输出）信号驱动关系
• 未连接的输出接口（悬空输出）检测
• 信号命名与实际用途的一致性
• FB 调用的输出接口是否全部连接（=> 后是否为空）
• 工位属性（初始位/急停正常/防护装置有效/启动完成）是否全部赋值

维度5：全局变量

• GVL 变量（g*、gb_*、gStru_*）的读写关系梳理
• 全局布尔量的赋值来源与使用去向
• 跨程序的变量依赖关系
• 数组变量的下标使用是否完整、有无遗漏索引
• HMI 功能数组（如 hmi_功能启用[n]）是否有未使用的索引

维度6：HMI 交互

• HMI 屏蔽功能（hmi_*屏蔽）的覆盖范围
• HMI 功能启用数组（hmi_功能启用[n]）的索引分配与语义
• 实体按钮与 HMI 按钮的双通道设计完整性
• HMI 相关变量命名的语义一致性
• 安全门按钮灯是否完整映射

维度7：状态机

• 流程步号（流程步号[n]）的状态流转分析
• 初始化请求与内部初始化的触发条件完整性
• 各工位/模块状态的互斥与依赖关系
• 状态机跨工位的耦合情况
• 状态导出变量（gb_*自动运行中 等）赋值条件是否完备

维度8：左右对称一致性

（适用于具有左右对称结构的工位/设备，如左右胀管机、左右倍速链等）

• 左右对称模块的代码一致性逐项对比
• 不一致项的合理性评估（是刻意差异还是遗漏）
• 对称模块中信号、FB调用、状态导出的完整性对比
• 防护装置来源是否一致
• 故障复位信号是否对称
• 状态导出变量是否对称

维度9：死代码与潜在问题

• 被注释掉的代码段（评估是否应恢复或删除）
• 悬空输出接口（out_xxx => 未连接）
• 硬编码 TRUE/FALSE 用于逻辑条件的潜在风险
• 重复赋值或无效赋值
• 未使用的数组索引或变量

维度10：可维护性

• 注释的覆盖率与质量（是否说明"为什么"而不仅是"是什么"）
• 变量命名规范的一致性
• 数组下标硬编码的可读性（是否需要枚举或常量替代）
• 被注释代码是否有说明注释原因
• 代码重复度（相似逻辑是否可抽象为 FB）
• 代码结构是否按工位/功能分段并有注释标题

维度11：工艺适配

• 工位顺序与实际生产工艺流程的匹配度
• 屏蔽/旁路逻辑对产线柔性的支持
• 机器人与外部设备启动完成条件的工艺含义
• 工位间协作条件是否体现工艺约束
• 产品类型/配方切换的支持程度（如有）

维度12：调试残留（合并自 plc-code-reviewer）

目标：确保调试临时代码在正式代码中已清除或已确认

检查项目：

• 安全相关字段是否存在硬编码 TRUE（调试时常见临时处理）
• 自动条件是否存在硬编码 TRUE（跳过实际自动条件的调试痕迹）
• 启动完成是否存在硬编码 TRUE（跳过设备就绪检测）
• 被注释的气缸/传感器原位检测（是否为调试阶段临时注释）
• 初始位是否存在比正常逻辑宽松的简化条件

注意：调试残留（维度12）中的硬编码 TRUE 若出现在安全相关字段，同时标记到维度3（安全联锁）

---

输出格式

分析/审查结论

每个维度按以下格式输出：

text

## 维度N：XXX

**总体评价**（一句话）
**结论**：通过 / 有问题 / 有风险

发现的问题：
1. [问题描述] → 位置：第X行   建议：[具体修改方案，附代码片段]

问题汇总清单

所有维度分析/审查完成后，输出汇总表格：

markdown

## 问题汇总清单
| 优先级 | 维度 | 问题描述 | 位置（行号）| 修改建议 |
|--------|------|----------|------------|----------|
| 高 | 安全联锁 | 左胀管机防护装置硬编码TRUE | 约8行 | 接入实际安全门信号 |
| 高 | 信号映射 | 停止按钮灯输出悬空 | 约3行 | 连接 do_主柜停止灯 |
| 中 | 可维护性 | 功能启用数组无注释 | 全文 | 添加索引含义注释 |

优先级定义：

• 高：存在安全风险或功能性错误，必须在投产前修复
• 中：存在可靠性隐患或明显不一致，建议尽快修复
• 低：影响可维护性或规范性，可纳入后续版本计划改进

---

深度选项

用户可指定分析/审查深度，默认完整分析（12个维度）：

模式	包含维度	适用场景
快速扫描	仅输出问题汇总表，不展开详细分析	大文件快速审阅
安全专项	维度3（安全联锁）+ 维度12（调试残留）	投产前安全检查
逻辑专项	维度2（控制逻辑）+ 维度4（信号映射）+ 维度8（一致性）	功能验证
完整分析	全部12个维度（默认）	全面代码审查

用户也可指定只分析特定维度（如"只分析安全联锁和信号映射"）。

---

适用文件类型

文件后缀	类型	分析/审查重点
.action.st	ACT 动作块	工位主控、状态分发、信号联锁、调试残留
.prg.st	PRG 主程序	调用结构、执行顺序、全局协调、调用完整性
.fb.st	FB 功能块	接口定义、内部逻辑、状态机、接口完整性
.gvl	全局变量	变量分组、命名规范、类型定义
.dut	结构体定义	字段完整性、命名规范、注释

---

注意事项

• 分析时优先关注安全相关逻辑（维度3），安全问题标记为高优先级
• 对于注释掉的代码，不要直接建议删除，先分析注释原因后再给建议
• 左右对称性分析（维度8）仅在代码中存在对称结构时才展开
• 如果用户只提供了单个文件，跨文件的变量引用无法完整追踪，需在报告中说明此限制
• 给出修改建议时，提供具体的代码片段而非泛泛描述
• 调试残留（维度12）中的硬编码 TRUE 若出现在安全相关字段，同时标记到维度3

---

版本历史

版本	日期	变更
v1.1.0	2026-07-31	合并 plc-code-analyzer + plc-code-reviewer，新增维度12调试残留、审查深度选项、修改建议格式
v1.0.0	-	初始版本（plc-code-analyzer）

---

Version 1.1.0 — 12维度PLC代码分析与审查工具包