dsh-plc-decode 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plc-decode contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,85 @@
+# dsh-plc-decode
+
+Read PLC project files directly inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). The plugin detects the format from the file header, decodes the project into readable reports and structured data, and provides project diffing, address audits, element-level read/write analysis and ladder-logic reconstruction.
+
+**Read-only**: project files are parsed, never modified.
+
+## Supported formats
+
+| Header | Format | Decoder |
+|---|---|---|
+| `50 4B 03 04` (ZIP) | CoDeSys V3.5 / LeadSysStudio `.project` (incl. Leadshine) | Bundled Python script: unpack → string table → restore POU ST sources |
+| `57 01 01 00` | Delta WPLSoft / ISPSoft `.dvp` | Bundled Python script: structure / section comments / device comments / instruction table |
+| `53 48 33 00` (SH3) | Siemens S7-200 SMART `.smart` | Embedded Node decoder: blocks / instruction records / operands / user & system symbol tables |
+| `44 45 4D 00` (DEM) | Siemens S7-200 SMART `.smartlib` | Embedded Node decoder: library variables and comment stream |
+
+> Leadshine LeadSysStudio saves CoDeSys-format `.project` files, so they decode through the same path: ST sources go to `pous/<POU>.txt`, and `/codesys-check` runs an equivalent compile check (struct members, array bounds, calls, address uniqueness, undeclared symbols).
+
+## Install
+
+Prerequisites:
+
+- DSH desktop app (the plugin runs inside DSH; Node version follows DSH);
+- Python 3.9+ on `PATH` for `.project` / `.dvp` (standard library only, no `pip install`);
+- Python is not needed for `.smart` / `.smartlib`.
+- Compatible with DSH 0.2.1-rc.5 (tested); 0.3 and later are not guaranteed.
+
+```sh
+dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
+```
+
+Restart DSH afterwards. The plugin has no npm runtime dependencies.
+
+## Usage
+
+### Tools (invoked by the model)
+
+| Tool | Purpose |
+|---|---|
+| `plc-decode` | Unified entry: detect the four formats and dispatch; args `file`, optional `outDir` |
+| `smart-pou-structure` | Internal structure of one POU: interface parameters (L-area address + type), box-level instruction chain, call sites and arguments |
+| `smart-lad` | Ladder reconstruction: per block/network LAD instruction sequence (LD/A/O/AN/ON, EU/ED, LPS/LRD/LPP, coils, comparisons, instruction-box placeholders) |
+| `smart-ladder-elements` | Element-level read/write judgement for one address (or a batch) |
+| `smart-net-trace` | Network trace: elements, write coils, boxes and constants in offset order |
+| `smart-box-pins` | Box pin table: pin name = actual argument for library call boxes (MBUS_CTRL, MBUS_MSG, TON, CTU, MOV_*, …) |
+| `smart-pin-dump` | Byte-level location: all occurrences of an address, or operand records in an offset range |
+| `smart-var-usage` | Variable audit: all references, overlapping byte forms, write-point judgement |
+| `smart-free-space` | Address usage and free ranges: pick new addresses when extending a program |
+| `smart-conflict` | Address conflicts: overlaps (real / suspected / registered only) and fragmented free space |
+| `smart-diff-project` | SMART project diff: block list, call chain, I/O references, symbol table |
+| `codesys-diff-project` | CoDeSys project diff: POU list, real logic changes, whitespace, string table, object table |
+
+### Slash commands
+
+`/plc-decode`, `/codesys-read`, `/dvp-read`, `/smart-read`, `/codesys-check`, `/codesys-diff`, `/smart-diff`, `/smart-free-space`, `/smart-conflict`, `/smart-ladder`, `/smart-lad`.
+
+## Output
+
+Decoded files go to `解码归档/<project folder name>/` (the literal folder name is Chinese for "decode archive"; it lives in the current workspace). Use `outDir` to override.
+
+- `.project` → `00-索引.md`, `pous/<POU>.txt`, `工程内容报告.md`, `全部字符串.txt`, `对象表.md`, `项目树.md`
+- `.dvp` → `00-索引.md`, `解码报告.md`
+- `.smart` / `.smartlib` → `00-目录.md`, `解码报告.md`, `程序.lad`, `元素记录.tsv`, `符号地址.tsv`, `分析.md`, `记录.json`, `字符串全录.txt`
+
+The smart decoder writes a source fingerprint (size + mtime) into the report and `记录.json`; re-check it after the project is edited.
+
+## Limitations
+
+- HMI projects (`.hmismart`, `.fsprj`) are out of scope.
+- Pin-level arguments of library call boxes (Slave / RW / Addr / Count / DataPtr) cannot be decoded; the tools say so instead of guessing.
+- Encrypted or specially compressed projects may fail to decode; the decoder reports an error rather than a half-true result.
+- Ladder series/parallel topology is reconstructed from instruction records (validated network-by-network against official STL exports); library call regions without standard box headers are not covered.
+- Inferred instruction names are marked with `?`; undecoded names keep their raw form `??xx`.
+
+## Development
+
+```sh
+npm run check                # syntax check
+npm run smoke                # load the plugin and verify registrations (12 tools / 11 commands)
+npm run smoke -- <project>   # decode one real project end-to-end
+npm pack --dry-run           # inspect package contents
+```
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# dsh-plc-decode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/icon-180.png" width="96" align="right" alt="dsh-plc-decode">
+
+在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）里直接读 PLC 工程文件：按文件头自动识别格式，把工程解成可读报告与结构化数据，再基于解码结果做新旧对比、地址体检、元素级读/写判定与连线还原。
+
+**只读**：解析工程文件，不改动原文件。
+
+## 支持的工程文件
+
+| 文件头 | 格式 | 解码方式 |
+|---|---|---|
+| `50 4B 03 04`（ZIP） | CoDeSys V3.5 / LeadSysStudio `.project`（含雷赛） | 自带 Python 脚本：解包 → 字符串表 → 逐对象恢复 POU ST 源码 |
+| `57 01 01 00` | 台达 WPLSoft / ISPSoft `.dvp` | 自带 Python 脚本：文件结构 / 段落注释 / 设备注释 / 指令表反汇编 |
+| `53 48 33 00`（SH3） | 西门子 S7-200 SMART `.smart` 工程 | 内嵌 Node 解码器：块 / 指令记录 / 操作数 / 用户与系统符号表 |
+| `44 45 4D 00`（DEM） | 西门子 S7-200 SMART `.smartlib` 库 | 内嵌 Node 解码器：库变量与注释流 |
+
+> 雷赛（Leadshine）用 LeadSysStudio 保存的 `.project` 与 CoDeSys 同格式，走同一条解码链：ST 源码导出到 `pous/<POU>.txt`，可用 `/codesys-check` 做等价编译校验（结构体成员、数组下标、调用存在性、地址唯一、未声明符号）。
+
+## 安装
+
+前提：
+
+- DSH 桌面端（插件运行在 DSH 内，Node 版本跟随 DSH）；
+- 解码 `.project` / `.dvp` 需要 Python 3.9+ 在 `PATH` 里（只用标准库，无需 pip 安装）；
+- 解码 `.smart` / `.smartlib` 不需要 Python。
+- 兼容 DSH 0.2.1-rc.5（实测通过）；0.3 起不保证。
+
+从 GitHub 安装：
+
+```sh
+dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
+```
+
+装完重启 DSH。本插件没有 npm 运行时依赖。
+
+## 使用
+
+### 工具（模型自动调用）
+
+| 工具 | 用途 |
+|---|---|
+| `plc-decode` | 统一入口：按文件头识别四格式并分发解码，参数 `file` + 可选 `outDir` |
+| `smart-pou-structure` | 某子程序的内部结构：接口参数（L 区地址 + 类型）、盒级指令链、调用点实参 |
+| `smart-lad` | 连线还原：按块、按网络打印 LAD 指令序列（LD/A/O/AN/ON、EU/ED、LPS/LRD/LPP、线圈、比较、指令盒占位） |
+| `smart-ladder-elements` | 元素级读/写判定：某地址（可一批）的每个落点是触点（读）还是写 |
+| `smart-net-trace` | 网络级轨迹：给偏移区间，按顺序列出触点 / 写元件 / 指令盒 / 常数 |
+| `smart-box-pins` | 盒级引脚表：库调用盒（MBUS_CTRL、MBUS_MSG、TON、CTU、MOV_* 等）的「引脚名 = 实参」 |
+| `smart-pin-dump` | 字节级定位：某地址的全部出现位置，或某偏移区间内的操作数记录 |
+| `smart-var-usage` | 变量使用体检：某地址的全部引用点、共用字节的其它地址形式、写入点判定 |
+| `smart-free-space` | 地址占用与空闲段：加功能前选新地址（有符号名的、预留坑都不动） |
+| `smart-conflict` | 地址冲突体检：重叠冲突（真冲突 / 疑似 / 仅登记）+ 连续空间被切碎 |
+| `smart-diff-project` | SMART 新旧工程对比：块清单、主程序调用链、I-O 引用、符号表差异 |
+| `codesys-diff-project` | CoDeSys 新旧工程对比：POU 清单、真实逻辑变化区段、空白差异、字符串表、对象表 |
+
+### 斜杠命令（人直接执行）
+
+| 命令 | 用途 |
+|---|---|
+| `/plc-decode <文件> [输出目录]` | 统一解码入口 |
+| `/plc-archive` | 查看当前生效的解码归档根目录、默认落点与改配置的方法 |
+| `/codesys-read <工程>` | 解码 `.project`（ST 源码 + 报告）或 `.dvp`（解码报告） |
+| `/dvp-read <工程>` | 台达 DVP 结构与指令表报告 |
+| `/smart-read <.smart/.smartlib> [输出目录]` | SMART 工程 / 库解码 |
+| `/codesys-check <工程>` | 解码 `.project` 后做等价编译静态校验（结构体 / 调用 / 地址唯一 / 未声明符号） |
+| `/codesys-diff <旧> <新>` | CoDeSys 新旧对比 |
+| `/smart-diff <旧> <新>` | SMART 新旧对比 |
+| `/smart-free-space <.smart>` | 地址占用与空闲段 |
+| `/smart-conflict <.smart>` | 地址冲突体检 |
+| `/smart-ladder <.smart> [地址]` | 元素级读/写判定 |
+| `/smart-lad <.smart> [块名] [网络号]` | 连线还原（LAD 指令序列） |
+
+## 输出位置
+
+默认写到**工作区**的 `解码归档/<工程所在文件夹名>/`（用文件夹名而不是工程文件名，避免不同文件夹里的同名工程互相覆盖；同一文件夹里有多个工程文件时用 `文件夹名_工程名`）。也可以在工具参数里用 `outDir` 指定。
+
+### 改归档地址（不用改代码）
+
+在 DSH profile 的 `cordis.patch.yml` 里给本插件那行加 `config`：
+
+```yaml
+- id: dsh-plc-decode
+  name: dsh-plc-decode
+  config:
+    archiveDir: D:/plc/解码归档
+```
+
+`archiveDir` 是归档**根目录**：相对路径按当前会话工作区解析，绝对路径原样使用；默认 `解码归档`。改完重启 dsh 生效，`/plc-archive` 可随时查看当前生效值。只想改一次就在解码时传 `outDir`。
+
+| 格式 | 主要产物 |
+|---|---|
+| `.project` | `00-索引.md`（先读这份）、`pous/<POU>.txt`（ST 源码）、`工程内容报告.md`、`全部字符串.txt`、`对象表.md`、`项目树.md` |
+| `.dvp` | `00-索引.md`、`解码报告.md`（结构 / 段落注释 / 设备注释 / 指令表）、可选 `程序解读.md` |
+| `.smart` / `.smartlib` | `00-目录.md`（先读这份）、`解码报告.md`、`程序.lad`、`元素记录.tsv`、`符号地址.tsv`、`分析.md`、`记录.json`、`字符串全录.txt` |
+
+`.smart` 的 `记录.json` 同时是各分析工具（地址占用、变量使用等）的输入，也是识别「已解码目录」的凭据；解码报告头部带**源文件指纹**（文件大小 + 修改时间），工程换版本后先核对指纹再用旧报告。
+
+## 已知边界
+
+- 不处理触摸屏（HMI）工程：`.hmismart`、`.fsprj` 不在本插件范围。
+- 库块调用区（如 MBUS_MSG 的 Slave / RW / Addr / Count / DataPtr）的引脚级实参解不出，工具会明确说明，不猜。
+- 加密或特殊压缩的工程可能解不出；解码器会报错而不是给出半真结果。
+- `.smart` 的串/并联拓扑由指令记录还原，已用官方导出的 STL 逐网络回归验证；库调用区（无标准盒头）不在覆盖范围内。
+- 指令名带 `?`（如 `?DRVI`）是推断名，报告末尾有推断对照表；`??xx` 是未定名，保持原样。
+
+## 开发与自检
+
+```sh
+npm run check                 # 语法检查
+npm run smoke                 # 装载插件 + 核对注册面（工具 12 个 / 命令 12 个）
+npm run smoke -- <工程文件>    # 额外对一个真实工程跑端到端解码，核对产物落盘
+npm pack --dry-run            # 看包里内容（node_modules、publish/ 不应进包）
+```
+
+## 目录结构
+
+```
+index.js                    插件入口：工具与命令注册、四格式分发、SMART 解码器
+invariant.js                伴随插件：登记包名所有权
+assets/decode-pack.mjs      解码产物落盘（索引/目录/表格/记录）
+assets/smart-lad.mjs        连线还原脚本（由 smart-lad 工具调用）
+assets/smart-net-trace.mjs  网络轨迹脚本（由 smart-net-trace 工具调用）
+assets/codesys-tools/       CoDeSys / DVP 解码 Python 脚本（只用标准库）
+scripts/smoke.mjs           冒烟测试
+```
+
+## 许可
+
+MIT

package/assets/codesys-tools/check_project.py

@@ -0,0 +1,390 @@
+# -*- coding: utf-8 -*-
+"""静态语义校验: 等价于编译检查 (无法驱动 LeadSysStudio GUI 编译时的替代验证)。
+校验: ① 结构体成员存在性 ② 被调用的程序/动作/方法存在性 ③ 地址唯一性 ④ 数组下标越界
+      ⑤ 未声明符号 (排除库/设备外部符号)。
+用法: python check_project.py <pous目录>
+"""
+import io
+import re
+import sys
+import glob
+import os
+
+if __name__ == "__main__" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+POUS = sys.argv[1] if len(sys.argv) > 1 else "."
+
+CJK = u"\u4e00-\u9fff"
+ID_RE = re.compile(u"[\\w" + CJK + u"]+")
+ST_HEADER_RE = re.compile(
+    r"^\s*(PROGRAM|FUNCTION_BLOCK|FUNCTION|METHOD|INTERFACE|CLASS|TYPE|VAR(?:_GLOBAL|_INPUT|_OUTPUT|_IN_OUT)?)\b",
+    re.M)
+
+KEYWORDS = {
+    "IF","THEN","ELSE","ELSIF","END_IF","FOR","TO","BY","DO","END_FOR","WHILE","REPEAT",
+    "UNTIL","END_WHILE","END_REPEAT","CASE","OF","END_CASE","VAR","END_VAR","VAR_IN_OUT",
+    "VAR_INPUT","VAR_OUTPUT","VAR_GLOBAL","VAR_GLOBAL_CONSTANT","VAR_GLOBAL_RETAIN",
+    "VAR_GLOBAL_PERSISTENT","VAR_GLOBAL_RETAIN_PERSISTENT","VAR_TEMP","STRUCT","END_STRUCT",
+    "TYPE","END_TYPE","FUNCTION_BLOCK","FUNCTION","PROGRAM","ACTION","METHOD","INTERFACE",
+    "IMPLEMENTS","EXTENDS","CONSTANT","RETAIN","PERSISTENT","ARRAY","OF","POINTER","AT",
+    "AND","OR","XOR","NOT","TRUE","FALSE","BOOL","INT","DINT","UDINT","UINT","REAL",
+    "LREAL","WORD","DWORD","BYTE","STRING","SINT","USINT","TIME","TOD","DATE","DT",
+}
+# 库/设备外部符号 (库函数/FB/类型/设备对象/库实例), 大小写不敏感
+STD = {
+    "MC_Power","MC_Stop","MC_Reset","MC_Halt","MC_Jog","MC_MoveVelocity","MC_SetPosition",
+    "MC_Home","MC_MoveAbsolute","MC_MoveRelative","MC_MoveAdditive","MC_GearIn","MC_GearOut",
+    "MC_Direction","SMC3_ReinitDrive","SMC3_PersistPosition","AXIS_REF","AXIS_REF_SM3",
+    "AXIS_REF_ETC_DS402_CS","ETCSlave","TON","TOF","TP","R_TRIG","F_TRIG","CTU","CTD","CTUD",
+    "LIMIT","MIN","MAX","ABS","ADR","SEL","MUX","MOVE","SHR","SHL","MOD","DWORD_TO_UDINT",
+    "LREAL_TO_REAL","TO_DINT","TO_UDINT","TO_DWORD","TO_INT","TO_UINT","TO_REAL","TO_LREAL",
+    "TO_BOOL","ANY_TO_TIME","INT_TO_DINT","DINT_TO_INT","TIME_TO","REAL_TO","STRING_TO",
+    "UDINT_TO","BYTE_TO","WORD_TO","DINT_TO_REAL","SM3_Basic","positive","negative","normal",
+    "Fastest","shortest","xConfigFinished","xDistributedClockInSync","xError","fbeFBError",
+    "wID","wStatusWord","dwDigitalInputs","wState","SetOpMode","wOpMode","bVirtual",
+    "wCommunicationState","bDriveStartRealState","bRegulatorRealState","nAxisState",
+    "fActVelocity","fSetPosition","fActPosition","fActTorque","dwPosOffsetForResiduals",
+    "In","Out","Master","Slave","Axis","Execute","Enable","Position","Velocity","Acceleration",
+    "Deceleration","Jerk","Direction","Distance","BufferMode","Done","Busy","Active",
+    "CommandAborted","Error","ErrorId","ErrorID","InGear","InVelocity","Status","bRegulatorOn",
+    "bDriveStart","Mode","RatioNumerator","RatioDenominator","Q","ET","CLK","IN","PT",
+    "JogForward","JogBackward",
+    "High_Speed_IO_Module","LocalBus_Master_Module",
+}
+STD_UPPER = {s.upper() for s in STD}
+PARAM_NAMES = {"IN","PT","Q","ET","CLK","CV","RESET","CU","PV","COUNT","MAXVALUE"}
+
+# 数组/结构体声明解析：从各 POU 的实际声明里取类型，不预设变量名
+ARRAY_DECL_RE = re.compile(u"ARRAY\\s*\\[\\s*(-?\\d+)\\s*\\.\\.\\s*(-?\\d+)\\s*\\]\\s*OF\\s+"
+                           u"(?:ARRAY\\s*\\[[^\\]]*\\]\\s*OF\\s+)?([\\w" + CJK + u"]+)")
+STRUCT_DECL_RE = re.compile(u"^([\\w" + CJK + u"]+)(?:\\s+AT\\s+%[^\\s]+)?\\s*:\\s*([\\w" + CJK + u"]+)\\s*(?:;|:=)")
+
+
+def parse_decl(line):
+    """声明行 → ('array', lo, hi, 元素类型) / ('struct', 类型名) / None"""
+    m = ARRAY_DECL_RE.search(line)
+    if m:
+        try:
+            return ("array", int(m.group(1)), int(m.group(2)), m.group(3))
+        except ValueError:
+            return None
+    m = STRUCT_DECL_RE.match(line)
+    if m:
+        return ("struct", m.group(2))
+    return None
+
+
+def read_pou(path):
+    txt = open(path, encoding="utf-8-sig").read()
+    body = [l for l in txt.splitlines() if not l.startswith("#")]
+    return "\n".join(body).lstrip()
+
+
+def strip_comments(txt):
+    """剥 ST 注释: // 行注释 + (* *) 块注释。栈式扫描, 正确处理嵌套/未闭合 ((* 之后全视为注释)。"""
+    out = []
+    i, depth, n = 0, 0, len(txt)
+    while i < n:
+        if txt.startswith("(*", i):
+            depth += 1
+            i += 2
+        elif txt.startswith("*)", i) and depth > 0:
+            depth -= 1
+            i += 2
+        elif depth > 0:
+            i += 1
+        elif txt.startswith("//", i):
+            j = txt.find("\n", i)
+            i = n if j == -1 else j + 1
+        else:
+            out.append(txt[i])
+            i += 1
+    return "".join(out)
+
+
+def extract_var_decls(txt):
+    decls = {}
+    for m in re.finditer(r"(?s)(?:VAR|VAR_IN_OUT|VAR_INPUT|VAR_OUTPUT|VAR_TEMP)\b(.*?)(?=\bEND_VAR)", txt):
+        for line in m.group(1).splitlines():
+            line = line.strip()
+            if not line or line.startswith(("//", "(*", "*)")):
+                continue
+            mm = re.match(u"^([\\w" + CJK + u"]+)\\s*:", line)
+            if mm:
+                decls[mm.group(1)] = line
+    return decls
+
+
+def extract_globals(txt):
+    names, addrs, decls = set(), {}, {}
+    for m in re.finditer(r"(?s)VAR_GLOBAL(.*?)(?=\bEND_VAR)", txt):
+        for line in m.group(1).splitlines():
+            line = line.strip()
+            if not line or line.startswith(("//", "(*", "*)")):
+                continue
+            am = re.search(r"AT\s+(%[A-Z][A-Za-z]*\d+(?:\.\d+)?)", line)
+            nm = re.match(u"^([\\w" + CJK + u"]+)", line)
+            if nm:
+                names.add(nm.group(1))
+                decls[nm.group(1)] = line
+                if am:
+                    addrs.setdefault(am.group(1), nm.group(1))
+    return names, addrs, decls
+
+
+def extract_dut_fields(txt):
+    fields = set()
+    for line in txt.splitlines():
+        line = line.strip()
+        if not line or line.startswith("//"):
+            continue
+        if ":" in line and not line.startswith(("TYPE", "END_TYPE", "STRUCT", "END_STRUCT")):
+            mm = re.match(u"^([\\w" + CJK + u"]+)\\s*:", line)
+            if mm:
+                fields.add(mm.group(1))
+    return fields
+
+
+def enum_members(txt):
+    m = set()
+    t = txt.split("END_TYPE")[0]
+    if "(" in t and "STRUCT" not in t:
+        body = t.split("(", 1)[1]
+        for mm in re.finditer(u"([\\w" + CJK + u"]+)\\s*(?::=\\s*\\d+)?", body):
+            m.add(mm.group(1))
+    return m
+
+
+# ---------------- 加载 ----
+pous = {}
+for f in glob.glob(os.path.join(POUS, "*.txt")):
+    name = os.path.basename(f)[:-4]
+    txt = read_pou(f)
+    # 跳过设备对象（fallback 文本提取，非 ST 代码）：前 2000 字符里找不到任何 ST 声明头
+    if not ST_HEADER_RE.search(txt[:2000]):
+        continue
+    pous[name] = txt
+
+dut_fields = {}
+declared = set()
+locals_map = {}
+globals_map = {}
+global_decls = {}         # 全局变量名 -> 声明行（数组/结构体类型推断用）
+enum_names = set()
+global_visible = set()   # 仅"跨 POU 可见"声明 (全局/枚举/DUT 类型与字段/调用 POU)
+local_pool = {}          # name -> {局部声明名: 原行}
+for name, txt in pous.items():
+    if txt.startswith("TYPE"):
+        if "STRUCT" in txt.split("END_TYPE")[0]:
+            m = re.match(u"TYPE\\s+([\\w" + CJK + u"]+)", txt)
+            dname = m.group(1) if m else name
+            dut_fields[dname] = extract_dut_fields(txt)
+            global_visible.add(dname)
+        else:
+            en = enum_members(txt)
+            if en:
+                enum_names |= en
+                declared |= en
+                global_visible |= en
+    elif "VAR_GLOBAL" in txt:
+        n, a, d = extract_globals(txt)
+        globals_map[name] = (n, a)
+        global_decls.update(d)
+        declared |= n
+        global_visible |= n
+    else:
+        loc = extract_var_decls(txt)
+        locals_map[name] = loc
+        local_pool[name] = loc
+        declared |= set(loc)
+callables = set(pous.keys())
+for flds in dut_fields.values():
+    declared |= flds
+    global_visible |= flds
+declared |= set(dut_fields.keys())   # DUT 类型名也是声明
+global_visible |= callables
+
+# ---------------- 校验 1: 结构体成员 + 数组下标 ----------------
+def decl_kinds(name):
+    """该 POU 可见的数组/结构体变量（全局 + 本 POU 局部）：{变量名: 声明解析结果}"""
+    kinds = {}
+    for var, line in global_decls.items():
+        k = parse_decl(line)
+        if k:
+            kinds[var] = k
+    for var, line in locals_map.get(name, {}).items():
+        k = parse_decl(line)
+        if k:
+            kinds[var] = k
+    return kinds
+
+
+struct_field_issues = []
+for name, txt in pous.items():
+    if txt.startswith("TYPE"):
+        continue
+    kinds = decl_kinds(name)
+    if not kinds:
+        continue
+    txt = strip_comments(txt)
+    # 数组元素成员：base[idx].field
+    for m in re.finditer(u"([\\w" + CJK + u"]+)\\s*\\[\\s*([^\\]]+?)\\s*\\]\\s*\\.\\s*([\\w" + CJK + u"]+)", txt):
+        base, idx, field = m.group(1), m.group(2).strip(), m.group(3)
+        k = kinds.get(base)
+        if not k or k[0] != "array":
+            continue
+        dut = k[3]
+        if dut in dut_fields and field not in dut_fields[dut]:
+            struct_field_issues.append(u"%s: %s[%s].%s 不是 %s 的字段" % (name, base, idx, field, dut))
+        if idx.isdigit() and not (k[1] <= int(idx) <= k[2]):
+            struct_field_issues.append(u"%s: %s[%s] 越界 (%d..%d)" % (name, base, idx, k[1], k[2]))
+    # 结构体实例成员：var.field
+    for m in re.finditer(u"([\\w" + CJK + u"]+)\\s*\\.\\s*([\\w" + CJK + u"]+)", txt):
+        var, field = m.group(1), m.group(2)
+        k = kinds.get(var)
+        if not k or k[0] != "struct":
+            continue
+        dut = k[1]
+        if dut in dut_fields and field not in dut_fields[dut]:
+            struct_field_issues.append(u"%s: %s.%s 不是 %s 的字段" % (name, var, field, dut))
+    # 纯数组下标越界：base[idx]（后面不跟 .field，避免与上一条重复）
+    for m in re.finditer(u"([\\w" + CJK + u"]+)\\s*\\[\\s*(\\d+)\\s*\\](?!\\s*\\.)", txt):
+        base, idx = m.group(1), int(m.group(2))
+        k = kinds.get(base)
+        if k and k[0] == "array" and not (k[1] <= idx <= k[2]):
+            struct_field_issues.append(u"%s: %s[%d] 越界 (%d..%d)" % (name, base, idx, k[1], k[2]))
+
+# ---------------- 校验 2: 调用存在性 ----------------
+call_issues = []
+for name, txt in pous.items():
+    if txt.startswith("TYPE"):
+        continue
+    txt = strip_comments(txt)
+    for m in re.finditer(u"(?<![\\w" + CJK + u"])([A-Z][\\w" + CJK + u"]*)\\s*\\(", txt):
+        callee = m.group(1)
+        if callee in callables or callee in KEYWORDS or callee.upper() in STD_UPPER:
+            continue
+        if callee.startswith(("MC_", "TON", "R_TRIG", "F_TRIG", "SM3", "CTU", "TP", "TOF")):
+            continue
+        if callee in declared:
+            continue
+        call_issues.append(u"%s: 调用未定义 %s()" % (name, callee))
+
+# ---------------- 校验 3: 地址唯一 ----------------
+addr_issues = []
+all_addrs = {}
+for gvl, (n, a) in globals_map.items():
+    for addr, var in a.items():
+        if addr in all_addrs and all_addrs[addr] != var:
+            addr_issues.append(u"地址重叠: %s 被 %s(%s) 与 %s 同时占用" % (addr, all_addrs[addr], gvl, var))
+        all_addrs.setdefault(addr, var)
+
+# ---------------- 校验 4: 未声明符号 ----------------
+undef_issues = []
+for name, txt in pous.items():
+    if txt.startswith("TYPE"):
+        continue
+    clean = strip_comments(txt)
+    for t in set(ID_RE.findall(clean)):
+        if t in KEYWORDS or t in declared or t in enum_names or t in callables:
+            continue
+        if t.upper() in STD_UPPER or t.upper() in PARAM_NAMES:
+            continue
+        if t.isdigit() or re.fullmatch(r"\d+[A-Za-z]+", t) or re.fullmatch(r"(MB|MW|MX|QX|QB|QI|IX|IW|QD)\d+", t):
+            continue
+        if t.startswith(("MC_", "SM3_", "SMC3", "AXIS", "ETC", "FB_", "ST_", "DUT_", "GVL",
+                         "TON", "R_TRIG", "F_TRIG", "CTU", "TP", "TOF")):
+            continue
+        if len(t) == 1 or t in ("LeadSysStudio",):
+            continue
+        undef_issues.append(u"%s: 未声明符号 %s" % (name, t))
+
+# ---------------- 校验 5: POU 声明头缺失 ----------------
+header_issues = []
+for name, txt in pous.items():
+    if txt.startswith("TYPE"):
+        continue
+    first = ""
+    for l in txt.splitlines():
+        l = l.strip()
+        if not l or l.startswith("//"):
+            continue
+        first = l
+        break
+    if not re.match(u"^(PROGRAM|FUNCTION_BLOCK|FUNCTION|VAR_GLOBAL)(?=\\s|$)", first):
+        header_issues.append(u"%s: 缺少 POU 声明头 (首行应为 PROGRAM/FUNCTION_BLOCK/FUNCTION/VAR_GLOBAL, 当前: %s)"
+                             % (name, first[:40] if first else "(空)"))
+
+# ---------------- 校验 6: 跨 POU 引用他人局部声明 ----------------
+cross_issues = []
+local_all = set()
+for loc in local_pool.values():
+    local_all |= set(loc)
+for name, txt in pous.items():
+    if txt.startswith("TYPE"):
+        continue
+    own = set(local_pool.get(name, {}))
+    clean = strip_comments(txt)
+    for t in set(ID_RE.findall(clean)):
+        if t in own or t in global_visible or t in KEYWORDS or t.isdigit():
+            continue
+        if t.upper() in STD_UPPER or t.upper() in PARAM_NAMES:
+            continue
+        if t in local_all:
+            for oname, loc in local_pool.items():
+                if oname != name and t in loc:
+                    cross_issues.append(u"%s: 引用了 %s 的局部声明 %s (编译将报未声明, 应把声明移到本 POU 或全局)"
+                                        % (name, oname, t))
+                    break
+
+# ---------------- 输出 ----------------
+print("=" * 64)
+print(u"静态语义校验  (等价编译检查)")
+print("=" * 64)
+print(u"POU 数 %d | DUT 字段组 %d | 全局声明 %d | 枚举成员 %d" %
+      (len(pous), len(dut_fields), sum(len(v[0]) for v in globals_map.values()), len(enum_names)))
+
+print(u"\n[1] 结构体成员/数组越界:")
+if struct_field_issues:
+    for e in sorted(set(struct_field_issues)):
+        print("  ✗", e)
+else:
+    print("  ✓ 全部有效")
+
+print(u"\n[2] 程序/动作/方法调用:")
+if call_issues:
+    for e in sorted(set(call_issues)):
+        print("  ✗", e)
+else:
+    print("  ✓ 全部存在")
+
+print(u"\n[3] AT 地址唯一性:")
+if addr_issues:
+    for e in sorted(set(addr_issues)):
+        print("  ✗", e)
+else:
+    print("  ✓ 无重叠")
+
+print(u"\n[4] 未声明符号 (排除库/设备外部, 需人工核对):")
+if undef_issues:
+    for e in sorted(set(undef_issues)):
+        print("  ?", e)
+else:
+    print("  ✓ 无")
+
+print(u"\n[5] POU 声明头:")
+if header_issues:
+    for e in sorted(set(header_issues)):
+        print("  ✗", e)
+else:
+    print("  ✓ 全部 POU 有声明头")
+
+print(u"\n[6] 跨 POU 非法局部引用:")
+if cross_issues:
+    for e in sorted(set(cross_issues)):
+        print("  ✗", e)
+else:
+    print("  ✓ 无")
+
+print(u"\n结论: 静态等价检查; 最终以 LeadSysStudio 编译为准 (工程已在 IDE 打开)")