dsh-plc-decode 0.1.4 → 0.2.0

package/assets/zzuser-hmi-decode-workflow.md

@@ -0,0 +1,53 @@
+# zzuser-hmi-decode-workflow —— 触摸屏工程读取工作流
+
+触摸屏（HMI）工程走**本入口**，与 PLC 分开：PLC 工程（`.project` / `.dvp` / `.smart` / `.smartlib`）用 `zzuser-plc-decode`，屏工程用 `zzuser-hmi-decode`。
+
+## 一、先认类型（别拿错工具）
+
+| 文件 | 是什么 | 用哪个 |
+|---|---|---|
+| `.hmismart` | 西门子 WinCC flexible SMART 触摸屏工程（Smart Line 屏） | 工具 `zzuser-hmi-decode`（解码）／`zzuser-hmi-diff-project`（新旧对比） |
+| `.fsprj` 或含 `HMI\Frame` 的目录 | 繁易 FStudio / Flexem 触摸屏工程 | 工具 `zzuser-hmi-decode`（扫文本）／`zzuser-fstudio-scan-texts`／`zzuser-fstudio-i18n`（多语言出表） |
+| `<工程名>.设备_1.srt`（同目录） | 项目文本侧的序列化存储 | 主文件被锁时的旁路，见第三节 |
+| `Screens.xls` / `Others.xls` / `Messages.xls` | WinCC flexible「项目文本」导出成的 Excel 三件套 | 工具 `zzuser-wincc-text-i18n`（分型／回写／自检），流程见技能 `zzuser-wincc-text-i18n-workflow` |
+
+**第一原则与 PLC 侧相同：先要"软件里能导出的东西"**。触摸屏这边对应的是：画面清单/变量表（软件里能导 CSV 或看变量表）——导出来对账，比在工程里挖快一个数量级。
+
+## 二、西门子 `.hmismart`（主文件可全解）
+
+它**不是压缩包、也没加密**，是 WinCC flexible SMART 的工程数据库单文件：
+
+- **容器**：魔数 `01 0F 00 00 08 02 00 00`，4096 字节严格页对齐。
+- **明文对象记录**：`36` + UUID(16B) + 若干字段 + 名称(UTF-16LE)。UUID 是**对象类别**，同类共用一个；判据是同一 UUID 出现 ≥3 次才算真类型。
+- **压缩块**：gzip 头 + **裸 deflate，没有 CRC/ISIZE 尾部**——标准 `gunzip` 只能解出一小部分，必须 `inflateRaw`。解出的内容是「属性名 + 属性值」序列与软件自带的多语言系统消息。
+- **内嵌 DDL**：`Hmi*` 表的建表脚本明文可读（HmiScreenTable / HmiTagTable / HmiConnectionTable / HmiScreenItemTable …），即工程数据的逻辑模型——**查某张表有哪些字段，先看它**。
+- **一次跑完**：`assets/hmismart-decode.mjs`（原始产物）+ `assets/hmismart-report.mjs`（人读报告），产物落 `<工作区>\解码归档\<工程名>\HMI解码\`，只读源文件。
+- **新旧差异**：`assets/hmismart-diff.mjs`（工具 `zzuser-hmi-diff-project`）——比 ①起始画面配置 ②画面表记录 ③画面名清单 ④配套文件差异。**"重启后跳到别的画面"先看第 1 节**：`StartScreenId` 指向 `Deleted=true` 的画面时，面板启动找不到它就退到列表里的其它画面。
+- **查某个地址/变量时别做大范围 grep**：含压缩块原文的几份产物里宽 pattern（如 `VW`）会刷出几百行垃圾、把上下文冲掉；要查就用具体串。另：**地址表里出现 ≠ 画面绑定**，要知道挂在哪个控件上，得回对象记录再查一层。
+
+### 两台软件同时唱着的时候：直接读旁系 `.data`（省一次解锁）
+
+`.hmismart` 被 WinCC 打开时是**独占锁**（连 `FileShare.ReadWrite` 都打不开）。这时不必关软件，同目录的 `{{GUID}}.data` 就是工程数据的旁路：
+
+- 结构：`ES2RT` 头（前 10 字节）+ gzip 流（`1F 8B 08` 起），解出来是 .NET 序列化对象图（20MB 量级），**UTF-8，字符串可读**。
+- 你能直接从中拿到：**变量表全部标签名**（含 `文件夹_N\MW5212` 这类「以地址命名」的标签与中文命名标签）、**连接与驱动名**（如 `driver.Modicon MODBUS Standard V3`）、画面/控件文本。
+- 拿不到：**变量的 Modbus 地址号**（二进制存，工程里没有明文字样）——读不到就直说读不到，别编；判定靠现场按一下看对应位是否变，或让用户从变量表导一份出来。
+- 用法：按具体串搜（`MW5212`、`驱动名`、中文标签名），避开宽 pattern。
+
+## 三、`.srt` 项目文本（主文件锁着时的另一条旁路）
+
+- **结构**：头文本 `Sm@RT-Transfer` + 0x0E 起 UTF-16LE 链式记录 `[u16 字符数][字符串]`，按「画面 → 控件引用（按钮_N/文本域_N/IO 域_N）→ 中文文本 → 英文文本」交替存放；另有西门子系统消息区（官方中英对照，无需翻译）。
+- **解析要点**：Node `Buffer.toString('utf16le')` 直接可用；链式记录用「从锚点向前回退找链头 → 正向延伸」法；单条扫描会撞二进制假阳性，必须链式 + 可打印字符校验。
+- **陷阱**：① 中文不要用 GBK 解（UTF-16 才对齐）；② 抽「中文→英文」对时跳过元素引用/变量地址/空串；③ 截图「项目文本」页可与 `.srt` 内容逐条吻合，能当真值校准。
+- **旁系文件**：`*.transfer`（UTF-16 XML，含设备型号/页面清单）、`*.data`（见上）、`*.chk/.cnk/.rdf/.pwx`（校验/密码，跳过）。
+
+## 四、繁易 FStudio（多语言另见专篇）
+
+- 工具：`zzuser-hmi-decode`（读工程→扫元件文本）、`zzuser-fstudio-scan-texts`（只看要翻什么）、`zzuser-fstudio-i18n`（出对照表 + 可导入文本库的表）。
+- 方法与踩坑见同插件技能 **`zzuser-fstudio-i18n-workflow`**：列名逐字符一致、元件文字常写死不走文本库、原工程英文槽常是错填。
+
+## 五、交付与边界
+
+- 产物约定：`.hmismart` 写 `<工作区>\解码归档\<工程名>\HMI解码\`；FStudio 写 `<工程目录>\多语言产出\`。**不写系统临时目录、不污染工程目录**。
+- 只读源工程；`解码归档` 里的报告是某个版本的快照，拿旧报告对账前先比源文件的**大小 + 修改时间**。
+- 屏上地址为什么长成"不是西门子那种格式"（M 区名、Modbus 号、命名习惯）：见 PLC 侧技能 `zzuser-codesys-teach-workflow` §5——那是工程地址面的事，不在这里重复。

package/assets/zzuser-nb-textlib-workflow.md

@@ -0,0 +1,93 @@
+# NB 系列触摸屏文本库翻译（.nbp / .whe）
+
+`拓宇`这类用 NB 软件做的屏，工程是 `.nbp`（主工程 XML）＋ `HMI0\HMI0.whe`（画面 XML），
+文本库另导出成 `TextLib.csv`。三个文件都是纯文本，可直接解析，不需要开软件。
+
+## 一、认格式
+
+- `.nbp`：`<NBProject DBVersion="...">`，画面内容不在这里，只存工程设置与 PLC 配置。
+- `.whe`：`<HMI>` → `<Frames>` → `<Window ProjectID Name>` → `<Parts>` → `<Part Type=...>` → `<Lable>`。
+  22 个画面，系统画面名是英文（Login Window、HEX/ASCII/NUM Keyboard、Confirm Action Window 等）。
+- `TextLib.csv`：UTF-16LE + BOM，**LF** 换行，四列制表符＋双引号，条目之间空行。
+  结构是每组：`"Name:"\t"条目名"` / `"Status:"\t"状态数"` / `"Language"\t"Language1"\t"Language2"\t"Language3"` / 若干数据行。
+- 数据行里的 `$_return_$$_enter_$` 是软件内的换行控制符（不是字面量），原版英文靠它分行。
+
+## 二、走库怎么判（最容易判错的一处）
+
+元件文字全在 `<Lable>` 里，两个属性决定：
+
+- `UseTextLibrary="Yes"` / `"No"`
+- `LibraryTextName="条目名"`（对应 CSV 的 `"Name:"`，不是中文列）
+
+**勾了库 ≠ 走库**：必须再核 `LibraryTextName` 是否真的在库条目名里。条目不存在时，软件回退显示
+`<Font>` 里内嵌的字，屏上看着正常、切换语种却不变——和没走库一个效果，肉眼看不出来。
+
+判定顺序：
+
+1. `UseTextLibrary=Yes` 且库里有该条目 → 正常走库，跳过。
+2. `UseTextLibrary=Yes` 但库里查无此条目 → **假走库**，当作翻不到处理。
+3. `UseTextLibrary=No` → 未走库。文字在 `<Font>文字</Font>`；多状态元件每个 `<State>` 一组。
+
+## 三、扫什么
+
+- 遍历**所有** `<Lable>`：静态标签、按钮、开关、指示灯的文字都在这，别只扫一种元件。
+- 系统画面（画面名是英文的那批）不管。
+- IO 地址标注（纯编号如 `100.03`、`0.9`）不管。
+- 报警单独看，见第六节。
+
+## 四、翻译口径
+
+- 字典优先：中文命中字典的逐字照用，不改写、不压缩、不换同义词。
+- 字典没有的：英文保留原版英文（不是我造的），第三语种留空，绝不自行翻译。
+- 字典备注列写「请删除」的条目：不翻、保持原样，也不进缺译表。
+- 原文本身是英文（中文列不含汉字）的条目：三语填同一个值。
+- 纯英文且没勾库的控件文字：不管。
+- 原版英文含 `$_return_$$_enter_$` 时：译文单行显示宽度超过原版最长行才按原行数在空格处切分
+  （全角字符按 2 计宽），不改变文字内容。
+
+## 五、缺译清单
+
+- 固定三列：中文 / 英文 / 韩语，没有的留空；按中文去重（一源一译）。
+- 内容 = 库内缺译（英文空或第三语种空）+ 翻不到的控件文字（未勾库的 + 假走库的）。
+- 已在库内缺译里出现的中文不重复列。
+
+## 六、报警
+
+- `.nbp` 里 `<AlarmObjects>` / `<EventObjects>` / `<Event>` 都是空节点 = 没有自定义报警/事件配置。
+- 屏上的报警通常是 Word Lamp 读某个文本库条目的状态字（状态显示类）。要核条目 `Status` 是否
+  覆盖元件 `StateCount`，不够时多出来的状态会显示空白。
+
+## 七、切了语种显示不出目标语言（韩文/日文/俄文）
+
+文字有没有、走不走库都正常，但切过去画面上不出字——按下面四处依次断，四处都通才显示：
+
+1. **语种槽有没有字**：`.nbp` 的 `<TextObjects>/<LableText>/<States>/<State>` 下 `<Text>` 的个数＝语种数，
+   第 N 个就是语种 N。某语种槽空＝切过去空白。
+2. **字体有没有该语种的字形**（最常见的一处）：
+   - 语种默认字体在 `.nbp` 的 `<DefaultLangFontInfo>`，几条 `<VectorFont>` 就是几个语种；
+   - 元件标签的三语字体在 `.whe` 的 `<Lable>/<Text>/<VectorFontList>`，三个 `<VectorFont>` 按语种顺序；
+   - 这两处字体名一样、且该字体不含目标语种字形，就画不出来（软件用方格或空白顶上）。
+   - 软件自带向量字体清单在 `<安装目录>\vectorfonts.xml`，按语种给默认字体：
+     **DFHEI5＝简体中文（20976 汉字、0 谚文）**、DFNB-TW＝繁体、DFNB-EN＝西文、
+     **DFNB-KR＝韩文（2350 个韩文音节）**、DFNB-JP / DFGNB-JP / DFPNB-JP＝日文。
+   - 核对办法：读 ttf 的 cmap 数 U+AC00–U+D7A3 有没有字形，比看字体名可靠。
+3. **下载包里带没带**：编译输出 `tar\HMI0\font_*.ttf` 是按工程实际用到的字裁出来的子集。
+   里面没有目标语种字形，屏上一样不显示——改完字体必须重新编译下载。
+4. **切语种入口**：运行时靠 LW9130 切语种（`LW9130＝语种序号−1`，0 起）；切语种的画面上要有对应按钮，
+   否则屏上没法切过去。
+
+改字体：
+
+- 入口：【HMI 属性】→【触摸屏扩展属性】→【语种设置】（文本库窗口里也能进）→ 当前编辑语种 →
+  字体类型选矢量字体 → 字体属性里选该语种字体。
+- 【语种设置】**不会**改已有元件标签的字体。两种刷新法：
+  ① 逐个元件把【标签】页「使用文本库」取消勾选再勾上；
+  ② 把工程当前编辑语种切到该语种，全选元件，用字体工具栏统一设字体（工具栏改的是当前状态、当前语种）。
+- 韩文字形 2350 个，改完屏端字体体积会明显变大，下载前留意屏的存储余量。
+
+## 八、改文件
+
+- 只改数据行第 3、4 列（英文、第三语种），中文列与全部结构行原样；写回 UTF-16LE+BOM、LF。
+- 改前备份原件（`E:\chajian\_backup\<日期>-<主题>\` 保留原相对路径）。
+- 目标 xlsx 正被 Excel 打开时：用 COM 连活动实例（`Get-ActiveObject`），**先查 `Saved=True`** 再改；
+  有未保存改动就不动，问用户。改完 `Workbook.Save()`，不要 `Quit`。

package/assets/zzuser-wincc-text-i18n-workflow.md

@@ -0,0 +1,96 @@
+# zzuser-wincc-text-i18n-workflow —— 西门子触摸屏项目文本翻译
+
+`Screens.xls / Others.xls / Messages.xls` 是 WinCC flexible（SMART）把工程文字按「画面 / 其它 / 报警」三处导出成的 Excel。英文列多半是半成品：有的空着，有的还是中文，更多是**串位**——这类表不能当成"填空"，得当校对。
+
+## 一、格式契约（动之前先认清这四条）
+
+- 第 1 行 `$_Languages`，第 2 行是语言名（第 1 列＝源语言，第 2 列＝目标语言），第 3 行 `$_Typ(...)`，再几行 `//` 注释。
+- **第 1 列是匹配键**：导入时按它回工程里找对应文本。改一个字，那一行就对不上、白改。所以只改第 2 列。
+- 文本通常被 `<text>…</text>` 包着；**换行是真换行**（Excel 单元格里 Alt+Enter 那种），不是字面 `\n`。映射文件里用 `\n` 表示，脚本读入时还原。
+- 目标列出现 `$_ignore`：这句源文本在工程里已经有多个不同译文，导出时被替换掉了。**它不是"不用翻"，照样译、照样填进目标列**（空文本 `<text />`、纯符号/缩写除外）。导入时软件若仍按多译文冲突跳过，那几处屏上才不会变，这时才需要进工程手动统一。留着 `$_ignore` 交给用户＝表里还是中文，等于没翻。
+
+## 二、四步
+
+1. `scan`：出「待译清单.tsv」＋「分型报告.md」。
+2. 逐条出译文，写成 `map.tsv`（一列中文原文、一列英文，制表符分隔）。
+3. `apply`：回写目标列，出**同扩展名**.xls。
+4. `check`：键列没动、没有未译、没有残留 `$_ignore`、没有串位（源无中文而译文更长）、没有一源多译。
+
+工具：`zzuser-wincc-text-i18n`，`action=scan | apply | check`。
+
+## 三、分型只解决一半
+
+scan 判得出来的是：空译、中文残留、`$_ignore`、非中文同形（编号／日期格式）、**编号行挂词**——源文本不含中文（纯编号／代号）而译文更长的行，例如 `Q10` 对 `Q10 top box`、`Q23` 对 `Q3 Reject`。这一类就是串位：别行的功能词落到这一行了，按「源只有编号，译文也只留编号」处理；日期格式串（`yyyy-M-d H:mm:ss`）两列本来就不一样，不算。
+
+判不出来的仍是错译：中文对得上、译文却是另一个意思的那种，必须逐行看一遍。错译常见的三种样子：
+
+- 同类多行共用一句：`Q80~Q87` 全写 `Q15 Jet Glue 1`，`I80~I87` 全写 `I20`。
+- 上一行的话落到下一行：`Q20~Q27` 写着 `Q0 / Q1 / Q2 / Q3 Reject…`，那是 Q3~Q7 的。
+- 明显张冠李戴：`拓宇LOOG` → `Air pressure alarm Off`，`返回` → `Adjustment Screen`，`中性` → `Air pressure alarm On`。
+
+## 四、几条判据
+
+- **字典优先于模型译法**：用户给了字典文件（中文→英文的对照表）时，字典里有的条目逐字照用——不为词形统一而改写、不为屏宽而压缩、不换同义词；只有字典里没有的条目才自行翻译。字典里没有的条目，外语撑不住控件时按控件宽度切成多行（见入口技能「外语撑破控件就分段」）。字典自身可能一词多形（`Bag Opening Servo` 与 `Bag Open Servo Not Reset` 并存），按条目各照原样，不做全局统一。写回 XML 文本节点时 `&`/`<`/`>` 用实体（`&amp;` 等），导入后还原成原字符。
+- **以中文为准**。英文顺不顺口是次要的，和中文对得上才要紧。
+- 用户给的字典文件可能一表多语且列位错开（实测 `HMI information .xls`：中文在 A、英文在 B、越南语前半段在 G、报警段错到 K），取某语种时两列都要读，别只看一列就下"字典没有"的结论。
+- **一源一译**：同一句中文，全表只能有一个英文。同一文本两种译法，导回工程就产生多译文，下次再导出又变成 `$_ignore`，越改越乱。
+- **I/O 点位中文只写编号的，英文也只写编号**。别拿英文列里的话反推功能——那多半是别行串过来的。中文写了功能的（`Q5剔废`），才补功能。
+- 历史用词能用就不动（`Coder` 不改 `Encoder`），免得现场对不上。
+- 型号、电话、日期格式、公司名：原样，不翻译。
+- 地址这类改过的信息，以中文那一条为准重译，英文里常留着旧厂址。
+
+## 五、术语表（这台包装机的固定译法）
+
+| 中文 | 英文 |
+|---|---|
+| 工位 | Station |
+| 位置 | Position |
+| 吸盒 | Suck carton |
+| 走盒 | Carton feed |
+| 顶盒 | top box |
+| 联机 | Online |
+| 剔废 | Reject |
+| 堵料 | Jam |
+| 飞料 | Flying material |
+| 整料 | whole material |
+| 加料 | Feeding |
+| 测料 | Product detection |
+| 测盒 | Carton detection |
+| 测高 | Height detection |
+| 喷胶 | Glue spray |
+| 备用 | Backup |
+| 缺盒 | Carton shortage |
+| 缺纸 | Paper lack |
+| 光电 | sensor |
+
+一句里的拼法：`xxx Station`／`xxx Position` 与中文的「xxx工位／xxx位置」一一对应；`xxx开／关` 写成两行 `xxx` + `On`／`Off`，与源里的真换行对齐。
+
+## 六、出表细节
+
+- **产物写回源文件同路径、同名覆盖**，不要新建「翻译_项目文本」之类的目录另存——用户按原路径找文件，挪走或改名他就找不到。覆盖前先备份原件（项目侧放工作区 `_过程产物\`，不在源目录堆 `.bak`）。附加件（对照表等）放 `_过程产物`，不污染源目录。
+- **只改目标单元格，别整表重写**：`xlwt` 重建整表会吞行（实测 394 行写完剩 393，之后整表错位），也会丢掉别的列。`apply` 默认走 Excel COM：复制源表 → 只改变化的格子（PowerShell 调 `Excel.Application`，不需要 pywin32）→ `Save`，行数、列数、格式、其他列全原样；没有 Excel 才退到 xlwt，且写完回读核对行数与键列，对不上直接报错。
+- 必须出 **.xls**：软件的导入对话框按扩展名过滤，给 .xlsx 会选不到。
+- 新版导出表会带第 3 列元件路径（`\设备_1\HmiScreenFolder\…`），能定位这句文字在哪个画面——别丢。
+- 写 `.xls` 首选 Excel COM（`apply` 内置，Windows 有 Excel 就能用），无 Excel 时用 `xlwt`（`<python> -m pip install xlwt`）；读 .xls 借 LibreOffice Kit 转 xlsx。LibreOffice Kit 只能 xls→xlsx，不能 xlsx→xls，别拿它当写 .xls 的退路。
+- 空列照写：原表有几列，产物就几列。
+
+## 七、交付前必须交代的一件事：导入≠保存
+
+项目文本导入只改内存里的工程，**不保存工程就等于没导**——关掉重开就回到上次保存的版本，屏上还是中文。判断有没有真写进去，看同目录 `.hmismart` 的修改时间：导入并保存后会变成刚才的时间，不变就是没保存。
+
+**复核要拿工程重新导出的表来核，不能核自己手里那份。** 自己的表里全对，只说明表对；工程里对没对，要让它自己导一份出来比。工程重新导出时，第 5 行的导出时间注释会变（`//$_导出…`），比对键列时把这类注释行排除。
+
+所以交付话术里固定三步：导入 → **保存工程** → 点「刷新」复核。
+另外两个会让人误判的点：
+
+- 项目文本列表打开后不自动刷新，导入完要手动点「刷新」才看到新值。
+- 工程里存在多译文冲突时，导出表会多出一行 `//至少一个文本存在多种不同的翻译…`。等这些条目被统一后，这行注释会消失、表少一行——这不是格式坏了，是冲突清掉了。
+
+## 八、导入与导出按文本类型分开，一次一类
+
+Screens（画面）、Others（其它）、Messages（报警）是**三个独立文件**：导出时按类型各出一个文件，导入时一次只吃一个文件（软件按文件里的 `$_Typ` 判断类别）。所以：
+
+- 导回一个工程要**分别导三次**（Screens.xls、Others.xls、Messages.xls），只导一个文件，另外两类的屏上文字仍是原文。
+- 导出同理：切换文本类型分别导，或导出后确认目录里三个文件都在。
+- 导出日志（输出窗口）会逐类打印 `导出: 画面 / 导出: Others`，可以据此核对有没有漏类。
+

package/cordis.patch.yml

@@ -1,4 +1,6 @@
-# dsh-plc-decode：一个插件行，注册 12 个分析工具与 11 个斜杠命令。
+# dsh-plc-decode：一个插件行，注册 PLC 解码与触摸屏解码两类工具。
+# PLC：统一入口、SMART 子程序结构、新旧对比、地址体检、连线还原等。
+# HMI：触摸屏统一入口（.hmismart / .fsprj / .nbp / .mcp）、新旧对比、FStudio 文本与多语言、WinCC 项目文本。
 - insert:
     - id: dsh-plc-decode
       name: dsh-plc-decode