dsh-plc-decode 0.1.5 → 0.2.1

package/README.en.md

@@ -1,5 +1,7 @@
 # dsh-plc-decode
 
+[中文](README.md) | **English**
+
 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.
@@ -22,7 +24,7 @@ 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 the DSH 0.2.1 line (alpha / rc / stable); 0.3 and later are not guaranteed.
+- Requires DSH >= 0.2.1-alpha.3; verified on 0.2.1-alpha.3 and 0.2.2-rc.1, later versions untested.
 
 ```sh
 dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
@@ -65,7 +67,7 @@ The smart decoder writes a source fingerprint (size + mtime) into the report and
 
 ## Limitations
 
-- HMI projects (`.hmismart`, `.fsprj`) are out of scope.
+- HMI projects (`.hmismart`, `.fsprj`, `.nbp`, `.mcp`) are decoded by the same plugin row: screens / controls / tags / addresses, tables written to `解码归档/<project>/`. Control-to-tag references in `.hmismart` are partial (only same-segment and UUID hits); the rest is reported as "未解出".
 - 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.
@@ -80,6 +82,13 @@ npm run smoke -- <project>   # decode one real project end-to-end
 npm pack --dry-run           # inspect package contents
 ```
 
+## Feedback
+
+- Open an issue: https://github.com/taoziliyouchong/dsh-plc-decode/issues — searchable, and others can help.
+- Or reach me on QQ: **2171960697** (mention which plugin you installed when adding the contact).
+
+Please include: DSH version, plugin version, the exact error text, and a screenshot.
+
 ## License
 
 MIT

package/README.md

@@ -2,7 +2,9 @@
 
 <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 工程文件：按文件头自动识别格式，把工程解成可读报告与结构化数据，再基于解码结果做新旧对比、地址体检、元素级读/写判定与连线还原。
+**中文** | [English](README.en.md)
+
+在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）里直接读 PLC 工程文件：按文件头自动识别格式，把工程解成可读报告与结构化数据，再基于解码结果做新旧对比、地址体检、元素级读/写判定与连线还原。同一插件行里也承接触摸屏（HMI）工程：画面、控件、变量与地址。
 
 **只读**：解析工程文件，不改动原文件。
 
@@ -17,6 +19,15 @@
 
 > 雷赛（Leadshine）用 LeadSysStudio 保存的 `.project` 与 CoDeSys 同格式，走同一条解码链：ST 源码导出到 `pous/<POU>.txt`，可用 `/codesys-check` 做等价编译校验（结构体成员、数组下标、调用存在性、地址唯一、未声明符号）。
 
+### 触摸屏（HMI）工程
+
+| 文件 | 品牌 | 解出 |
+|---|---|---|
+| `.hmismart` | 西门子 WinCC flexible SMART（Smart Line 屏） | 画面 / 元件 / 文本 / 设备表；旁系 `{{GUID}}.data` 里解变量名、控件名、绑定候选、类型表 |
+| `.fsprj` 或含 `HMI\Frame` 的目录 | 繁易 FStudio / Flexem | 画面 / 控件 / 控件地址（读 `HMI\System\fs2.s3db` 与 `Bin\fshmi.bin`） |
+| `.nbp` | 欧姆龙 NB-Designer | 画面 / 控件 / 地址（XML 直读） |
+| `.mcp` / `.mcgs` | 昆仑通态 MCGS / LSTP Studio | 画面 / 变量 / 报警 / 策略（Access 库） |
+
 ## 安装
 
 前提：
@@ -24,7 +35,7 @@
 - DSH 桌面端（插件运行在 DSH 内，Node 版本跟随 DSH）；
 - 解码 `.project` / `.dvp` 需要 Python 3.9+ 在 `PATH` 里（只用标准库，无需 pip 安装）；
 - 解码 `.smart` / `.smartlib` 不需要 Python。
-- 兼容 DSH 0.2.1 系列（alpha / rc / 正式版均可）；0.3 起不保证。
+- 兼容 DSH 0.2.1-alpha.3 ～ 0.2.2-rc.1（本机实际运行验证过的最高版本）；更高版本未验证。
 
 从 GitHub 安装：
 
@@ -52,6 +63,12 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
 | `smart-conflict` | 地址冲突体检：重叠冲突（真冲突 / 疑似 / 仅登记）+ 连续空间被切碎 |
 | `smart-diff-project` | SMART 新旧工程对比：块清单、主程序调用链、I-O 引用、符号表差异 |
 | `codesys-diff-project` | CoDeSys 新旧工程对比：POU 清单、真实逻辑变化区段、空白差异、字符串表、对象表 |
+| `hmi-decode` | 触摸屏统一入口：按文件识别 `.hmismart` / `.fsprj` / `.nbp` / `.mcp` 并解码 |
+| `hmi-diff-project` | 新旧 `.hmismart` 对比：起始画面、画面表、画面名、配套文件 |
+| `fstudio-scan-texts` | 繁易工程元件文本扫描（按语种槽） |
+| `fstudio-i18n` | 繁易多语言对照表与文本库导入表 |
+| `fstudio-retag` | 已导出文本库表换语种列 |
+| `wincc-text-i18n` | WinCC 项目文本三件套（Screens / Others / Messages）翻译与回写 |
 
 ### 斜杠命令（人直接执行）
 
@@ -69,6 +86,9 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
 | `/smart-conflict <.smart>` | 地址冲突体检 |
 | `/smart-ladder <.smart> [地址]` | 元素级读/写判定 |
 | `/smart-lad <.smart> [块名] [网络号]` | 连线还原（LAD 指令序列） |
+| `/hmi-decode <.hmismart / .fsprj / .nbp / .mcp> [输出目录]` | 触摸屏工程解码 |
+| `/hmi-diff <旧 .hmismart> <新 .hmismart>` | 触摸屏新旧对比 |
+| `/fstudio-retag <TextLib 表> <词典> [输出]` | 文本库表换语种列 |
 
 ## 输出位置
 
@@ -79,17 +99,14 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
 | `.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` |
+| `.hmismart` | `10-画面.tsv`、`11-元件.tsv`、`12-文本.tsv`、`13-设备.tsv`、`20-变量.data.tsv`、`21-控件.data.tsv`、`23-控件绑定.data.tsv`、`24-类型表.tsv` |
+| `.fsprj` | `画面.tsv`、`控件.tsv`、`控件地址.tsv`、`变量.tsv` |
+| `.nbp` / `.mcp` | `解码报告.md` + 画面/控件（或变量/报警/策略）JSON |
 
 ### 改归档地址（不用改代码）
 
-在 DSH profile 的 `cordis.patch.yml`（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）末尾加这几行：
+在 DSH profile 的 `cordis.patch.yml`（`$DSH_HOME/profiles/<profile>/cordis.patch.yml`）末尾给本插件那一行加 config（只写 `archiveDir`：归档根目录）：
 
-```yaml
-- id: dsh-plc-decode
-  name: dsh-plc-decode
-  config:
-    archiveDir: D:/plc/解码归档
-```
 
 `archiveDir` 是归档**根目录**：相对路径按当前会话工作区解析，绝对路径原样使用；默认 `解码归档`。改完重启 dsh 生效，`/plc-archive` 可随时查看当前生效值；只想改一次就在解码时传 `outDir`。
 
@@ -97,7 +114,7 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
 
 ## 已知边界
 
-- 不处理触摸屏（HMI）工程：`.hmismart`、`.fsprj` 不在本插件范围。
+- 触摸屏工程：`.hmismart` 里只有模板骨架，真实画面与控件在旁系 `{{GUID}}.data`（ES2RT 序列化流），变量名与控件名能解，控件到变量的引用只解出同段共现与 UUID 命中那部分，其余标「未解出」；繁易工程若没建变量，控件地址只在 `Bin\fshmi.bin` 的动作表里；昆仑通态工程需本机有 `.mcp` 样本才能验证。
 - 库块调用区（如 MBUS_MSG 的 Slave / RW / Addr / Count / DataPtr）的引脚级实参解不出，工具会明确说明，不猜。
 - 加密或特殊压缩的工程可能解不出；解码器会报错而不是给出半真结果。
 - `.smart` 的串/并联拓扑由指令记录还原，已用官方导出的 STL 逐网络回归验证；库调用区（无标准盒头）不在覆盖范围内。
@@ -107,7 +124,7 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-plc-decode
 
 ```sh
 npm run check                 # 语法检查
-npm run smoke                 # 装载插件 + 核对注册面（工具 12 个 / 命令 12 个）
+npm run smoke                 # 装载插件 + 核对注册面（工具 18 个 / 命令 15 个）
 npm run smoke -- <工程文件>    # 额外对一个真实工程跑端到端解码，核对产物落盘
 npm pack --dry-run            # 看包里内容（node_modules、publish/ 不应进包）
 ```
@@ -116,14 +133,29 @@ npm pack --dry-run            # 看包里内容（node_modules、publish/ 不应
 
 ```
 index.js                    插件入口：工具与命令注册、四格式分发、SMART 解码器
+hmi.js                      触摸屏解码模块（工具/命令/技能注册，由 index.js 调用）
 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 脚本（只用标准库）
+assets/hmismart-decode.mjs  西门子 .hmismart 解码器（结构表 + .data 名字/绑定/类型表）
+assets/hmismart-diff.mjs    .hmismart 新旧对比
+assets/fstudio-tables.py    繁易画面 / 控件 / 控件地址表
+assets/nb-decode.mjs        欧姆龙 NB-Designer 解码器
+assets/mcgs-decode.mjs      昆仑通态 MCGS / LSTP 解码器
 scripts/smoke.mjs           冒烟测试
 ```
 
+## 反馈
+
+插件有问题，按这个顺序：
+
+1. 开 Issue：https://github.com/taoziliyouchong/dsh-plc-decode/issues —— 能留痕、能搜历史，别人也可能已经遇过；
+2. 急着问或不想开 Issue，QQ 号：**2171960697**（加好友请注明装的是哪个插件）。
+
+反馈时带上：DSH 版本、插件版本、报错原文、截图。少一样多半要再问一轮。
+
 ## 许可
 
 MIT

package/assets/FStudio/346/226/207/346/234/254/345/272/223/345/257/274/345/205/245/346/240/274/345/274/217.md

@@ -0,0 +1,45 @@
+# FStudio 文本库导入格式（繁易 Flexem）
+
+做多语言时，给 FStudio 文本库**导入**用的表，格式必须与软件**导出**的 TextLib 表逐字符一致，
+否则软件报"文件格式不正确"。踩过一次坑，记在这里。
+
+## 表结构
+
+单表，表名随意（软件导出叫 `TextLib`）。表头**必须**是这 5 列（有俄语就 6 列）：
+
+| 列 | 内容 | 说明 |
+|---|---|---|
+| 1 | `Guid` | 条目唯一标识，UUID 形如 `20c4864f-29ba-46c4-b9a5-beef83fbcad2`。新条目自己生成 UUID4 |
+| 2 | `Name` | 条目名，建议 ≤50 字，勿换行（软件里列表显示用） |
+| 3 | `Status` | 状态号，**数字**：默认值节点写 `0`，多状态依次 1、2… |
+| 4 | `1-Chinese (Simplified, PRC)-2052` | 简体中文（LCID 2052） |
+| 5 | `2-English (United States)-1033` | 英文（LCID 1033） |
+| 6 | `3-Russian (Russia)-1049` | 俄语（LCID 1049），不用就别加这列 |
+
+- 列名里空格、括号、连字符都不能改；`Guid`/`Name`/`Status` 首字母大写。
+- 简体中文那列的列名尤其容易写错成"中文"——**写"中文"就导不进去**。
+- 一个条目若有多状态，导出的表是"Guid 只在首行、后续行 Guid 留空"，同 `Name`、`Status` 递增。
+  自己造导入表时**每行都给 Guid** 更稳。
+
+## 生成脚本
+
+`出文本库导入表.py`：把中文英文对照表转成上面的格式。
+
+```
+python 出文本库导入表.py <对照表.xlsx> [输出.xlsx]
+```
+
+- 输入表要求：有一列列名含「中文」、一列含「英文」或 `English`。
+- 输出：**一份**可导入的 `.xlsx`（默认只出一份，别一次给多个表）。需要 `.xls` 时加参数：`--xls`。
+- 每个条目 Guid 自动生成、Status=0、Name 取中文前 50 字、英文为空的行标黄底提示。
+
+## 导入前自查（3 条）
+
+1. 表头逐字符对：`Guid` / `Name` / `Status` / `1-Chinese (Simplified, PRC)-2052` / `2-English (United States)-1033`。
+2. Guid 无重复、非空；Status 是数字不是文本。
+3. 库里已有的条目先核一遍，别把同名条目导成两条。
+
+## 相关
+
+- 文本库在工程里的位置：`Global\TextLibConfigInfo.cfg`；语言表：`HMI\System\LanguageConfigInfo.cfg`。
+- 画面元件想随语种变，还得逐个元件勾「使用文本库」指到条目（FStudio 使用手册 4.13.8 标签编辑器，p.570-571）。

package/assets/fstudio-i18n-workflow.md

@@ -0,0 +1,165 @@
+# FStudio 触摸屏多语言翻译 · 工作流
+
+适用：繁易 Flexem FStudio 的触摸屏工程（`.fsprj` + `HMI\Frame` + `Global\TextLibConfigInfo.cfg`）。
+目标：让画面上的文字随语种切换而变。
+
+## 一句话看清机制（先懂这个，省掉一半返工）
+
+FStudio 里画面文字的显示有**两条路**：
+
+1. **元件自带文字**：静态文本元件内部按语种分槽存字（`LanguageSN` 1 中文 / 2 英文 / 3 俄语），
+   切语种时软件自动取对应槽。**存的是字本身，不是引用**。
+2. **走文本库**：元件勾「使用文本库」并指向某条目，内容由文本库按语种提供。
+   同一个词在多处引用同一条，改一处全局生效。
+
+**实测经验**：这类工程的画面文字绝大多数走第 1 条路——库里只有几十条系统文本，元件上是写死的字。
+「切语种不变」的根因是：**字没进文本库，元件也没勾引用**。
+
+## 正确工作流（三步，别多）
+
+### 第 1 步 · 扫（一次扫全，别一页页看）
+插件工具 `fstudio-i18n`（或 `fstudio-scan-texts` 只看清单）。
+
+- 扫什么：`HMI\Frame\**\*.wcfg` 里**所有**带语种文字的元件，两条路都要收：
+  ① 静态文本：`StaticTextContentInfo` 的 `LanguageSN` + `LabelContent`；
+  ② 按钮/开关/指示灯：`Tag/Statuses/TagStatus/TagStatusLanguage` 的 `LanguageId` + `Text`。
+  **只扫 ① 会漏掉整批按钮标签**（2026-09-22 踩过：888 → 1899 个元件）。
+- 同时读 `Global\TextLibConfigInfo.cfg` 看库里已有什么。
+- 产出：`元件文本扫描.json` + 中文去重清单。
+
+### 第 2 步 · 译（口径先定，再动手）
+两条口径，开工前先问清用哪条（2026-09-22 一台设备上被改了三回）：
+
+- **定版优先（默认）**：词典译文一律覆盖元件里原有的英文，术语统一、机翻味清掉。
+  元件的原英文槽仍写进对照表第 6 列备查。
+- **原件优先**：元件里原本有英文的一律沿用，只补空白项；只有当原件英文属于
+  「词不达意 / 填错内容 / 张冠李戴」三类明显失误时才换成定版，并在表里标出来。
+  （判据集合见插件 `fstudio_i18n.py` 的 `FORCE_FIX`。）
+
+其余口径共通：
+- **元件里"中文标签 ↔ 英文标签"成对的要点**——那是工程自带的人工译文，可作译法参考。
+- 现场操作员扫一眼要懂；动词用设备惯用语（Start / Stop / Reset / Jog / Home）；
+  厂名音译（拓宇机械 → Tuoyu Machinery）；单位与代号按行业写法（mm、°/s、packs/min、S/N、DHCP IP）。
+- **注意**：原工程英文槽常有错填（同一画面几十条都写着 `current position`、`Platen`；
+  甚至有把数字 `8` 当英文的），那是串槽不是译文。
+- 外语比中文长、元件放不下的：按元件在屏上的可用宽度切成多行（真换行）；同一句中文全表一个切法（见入口技能「外语撑破控件就分段」）。
+
+### 包装机术语口径（纸品包装线，2026-09-22 定）
+先判断设备类型（画面名/工序词一看就知道），是包装机就按这套：
+
+**产品层级（量词别混）**
+| 实物 | 用词 | 说明 |
+|---|---|---|
+| 软抽小包（盒／包） | **pack** | 生产线成品单位；节拍写 `packs/min`（不要 boxes/min） |
+| 瓦楞外箱（箱） | **carton** | `carton infeed / opening / stop / press cylinder` |
+| 泛称"盒子" | 不用 box | box 是泛称，现场分不清层级；文档场景才用 |
+
+**工序词（按行业叫法）**
+| 中文 | 用 | 别用 |
+|---|---|---|
+| 上/下折封 | Top / Bottom folding seal | Top seal |
+| 折角 | Corner tuck | Corner fold |
+| 扯膜 | Film pull | Film tearing |
+| 下膜／上膜 | Bottom / Top film | Lower / Upper film |
+| 送卷、放卷 | Film unwind | Unwind speed |
+| 压纸输送 | Paper press conveyor | Platen conveying |
+| 推纸 | Paper pushing | Push paper |
+| 打码 / 冲孔 | Coding / Perforation | Coder / Punching |
+| 定长 / 追标 | Fixed length / Mark chasing | — |
+| 单光电 / 双光电 | Single / Dual photocell | Single sensor |
+| 测纸长 | Paper length measurement | Measure length |
+| 产品规格 | Pack height / width / length | Tissue height |
+
+仅校准工序与产品词；权限、网络、系统提示等非工艺词保持常规译法，别扩散。
+
+### 食品包装机术语口径（气调保鲜 / 转盘灌装封口，2026-09-28 定）
+先认设备：画面里有真空室、充气、封切的是**气调保鲜包装机**，有落杯/出杯/灌装/搅拌的是**转盘式灌装封口机**；同一工程的文本库常混着两类。
+
+| 中文 | 用 | 中文 | 用 |
+|---|---|---|---|
+| 真空 / 充气 | Vácuo / Injeção de gás | 杯 / 盒 | copo / embalagem |
+| 封切 / 封口 | Selagem e corte / Selagem | 落杯 / 出杯 | Queda do copo / Saída do copo |
+| 收膜 | Tração do filme | 灌装 / 搅拌 | Enchimento / Mistura |
+| 上真空室 | Câmara de vácuo superior | 打码 / 上胶 | Impressão de código / Colagem |
+| 顶盒 | Elevação da embalagem | 上料 / 光电 | Alimentação / Fotocélula |
+
+- **开／关成对词用同一词干 + Ligada/Desligada**（机械夹爪的开合用 Aberta/Fechada）。
+- 开＝`Atraso Inicial`、关＝`Tempo Final`（软件原本就是这套写法）；`权限N`＝`Permissão N`。
+- 葡语品牌词照抄不译：N2 / CO2 / O2 / OFF / ON / AT / I/O / WiFi / HMI / SD / Pen Drive。
+
+
+### 第 3 步 · 出导入表（格式由代码保证）
+`fstudio-i18n` 直接产出 `文本库导入表.xlsx`，列名与软件导出逐字符一致：
+
+```
+Guid | Name | Status | 1-Chinese (Simplified, PRC)-2052 | 2-English (United States)-1033
+```
+
+- 每行一个条目：Guid＝UUID4、Status＝数字 0（默认值节点）、Name 取中文前 50 字。
+- **第三语种按工程实际声明的语种来**（看 `HMI\System\LanguageConfigInfo.cfg` 的 `Lcid`），列名逐字符照抄、别自己拼；只有中英就别加。插件 `LANG_HEADS` 已备好常用列名：`pt` = `3-Portuguese (Brazil)-1046`、`pt-pt` = `3-Portuguese (Portugal)-2070`、`ko` = `3-Korean (Korea)-1042`、`ru` = `3-Russian (Russia)-1049`、`es`/`vi`/`th`/`ar` 同理。**换语种（如去韩语上葡语）时列名里的 LCID 必须与软件里加的语种一致**，否则导进去列对不上。
+- 多语词典写法：python 里加 `ELEMENT_PT`/`LONG_PT`（英表仍是 `ELEMENT_EN`/`LONG_EN`），或 json 写成 `{"en": {…}, "pt": {…}}`；只给英表就只出中英两列。
+- 导入：FStudio 文本库 → 导入 → 选这份表。
+- **状态要够数**：元件有 N 个状态（开关/指示灯/多状态按钮），挂库时取的是**库条目第 N 个状态**的内容；条目只有 1 个状态时，元件状态 1 就是空白（中文也空）。所以「开/关」「上一页/下一页」这类成对元件，条目必须做成多状态条目——导出表里表现为：首行带 Guid＋Status 0，后续状态行 **Guid 必须留空**＋Status 1/2、Name 与首行相同（重建/生成表时别顺手给后续状态行补 Guid，补了就不是同一条目的第二个状态了，2026-09-26 犯过、被用户当场看出）。单状态的元件用单状态条目即可；拿不准就把条目统一补到 2 状态，第二状态文字取成对词，没有成对词就与原状态同字（工程里原本就是这么写的：定位夹关→定位夹开 是成对，温度控制→温度控制 是同字）。
+- 导入后逐元件勾「使用文本库」指到条目（FStudio 使用手册 4.13.8 标签编辑器，p.570-571）。
+
+### 第 3 步的另一条路 · 已有导出表，只换语种列（retag）
+工程里文本库已经建好、软件也能导出表时**别重扫工程**，直接把导出的 TextLib 表整列换语种：
+
+```
+python <插件>/assets/fstudio_i18n.py retag <导出的TextLib表.xls> <输出.xlsx> <词典.json> pt 2
+# 或工具/命令：fstudio-retag <源表> <词典.json> [输出.xlsx] [语种键] [最少状态数]
+#                                                        ↑ 写 2 = 状态不够的条目补到 2 状态
+```
+
+- **只动第 6 列**：Guid、Name、Status、中文列、英文列逐行原样；多状态行的「首行带 Guid＋Status 0、后续行 Guid 留空＋Status 递增」结构照原样保留（软件导出的就是这个结构，别顺手给后续行补 Guid）。
+- 译文按**该行自己的中文列**取，不是按条目首行——多状态条目第二条常是成对词（成型关→成型开 译成 `Moldagem Desligada` / `Moldagem Ligada`）。
+- **状态数不够就补（最少状态数参数）**：屏上开关/指示灯是双状态元件，库条目只有一个状态时状态 1 会显示空白。补出来的行 Guid 留空、Status 递增、各语种文字与**首行相同**（软件导出的表里就是这么写的，不自己造词）。
+- 交付前机器校验四条：行数一致、前 5 列逐行一致、第三列无空/无汉字/无旧语种残留、抄参考表的译文与参考表逐字一致。
+
+### 要保留原表格式：就地改，走 Excel COM
+换语种列若要求「格式与原表一致」（用户会这么说），别用 xlwt/openpyxl 另存——**用 Excel COM 打开原件改再保存**，列宽/字体/合并等原样保留。要点与坑：
+
+- 改前先备份原件（`*.原件备份.xls`），中途出错直接从备份恢复重做。
+- **`Rows.Insert` 的 CopyOrigin 只管格式来源，不搬内容**——新行是空的，得自己把上一行的 `Range(...).Value` 搬过去（第一版只设了 CopyOrigin，三行全空，被"缺译 3"提示逮住）。插多行时**从下往上插**，行号才不漂。
+- 批量写值要**整块赋值**（`Range(A1:A9).Value = tuple(...)`），逐格 COM 往返慢十倍。
+- 写完 Excel 会把列宽/行高按字符重算（列宽 ±10/256 字符、行高 255→250 twips）：列宽用 `Columns(c).ColumnWidth = 原值`（Excel 单位）写回，行高用 `Rows("1:N").RowHeight = 12.75`（=255 twips）写回，写回后与原件一致。
+- 判"格式一致"要用 Excel 的口径（COM 读 `ColumnWidth`/`RowHeight`），别拿 xlrd 的 1/256 原始值硬比——那是文件内部表示，差几十分之一字符是重存的取整差。
+- 控件：`DispatchEx("Excel.Application")` 开独立实例、`Visible=False`、`DisplayAlerts=False`，`finally` 里 `Quit()`；别 `taskkill excel`（用户可能自己开着 Excel）。
+- **词典不一定要留**：改好的表里「中文列 ↔ 目标语种列」本身就是词典，要复用就从成品表反推，不必额外存一份。
+
+## 踩过的坑（照这个避）
+
+| 坑 | 现象 | 正解 |
+|---|---|---|
+| 列名不一致 | 导入报「文件格式不正确」 | 表头逐字符对；第 4 列是中英混排长名，不能写成「中文」 |
+| 以为要逐页看 | 大量时间翻画面 | 元件文本一次全扫，上千条几秒出 |
+| 拿元件英文槽当译文 | 译文一堆重复的 current position / Platen | 先查"同一英文被多少中文共用"，共用多的是串槽，按中文重译 |
+| 自己造表 | 交出去导不进 | 用插件出表，格式由代码保证 |
+| 一次交多个表 | "怎么又三个表格" | **只交最终能用的那一份**；对照表仅在你需要核对时才给 |
+| 「切韩语/俄语什么都不显示」 | 文本库三语都填了，屏上还是空白 | 按顺序查三处：① **元件语种槽有没有字**（本机实测 494 个元件只有 30 个韩文槽有字，275 个连韩语槽都没有）；② **元件有没有勾「使用文本库」**（30 个画面里只有 4 个用到库，光导库画面上什么都没变）；③ **该语种的字体**——工程 `HMI\System\LanguageConfigInfo.cfg` 每行一个字体，实测三行的字体类型都是「图形字体」（＝按字符串截位图存工程，多语种拿不到字模），且韩语行写的 `Microsoft YaHei` 经 cmap 表实测**不含韩文**（宋体、Arial 也不含；Malgun Gothic 含）。正解：该语种字体类型改**矢量字体**、字体换成含目标语言的（韩文用 Malgun Gothic），再重新下载工程（字模随工程打包）。判据：读字体文件 cmap 表查 U+AC00（韩文）／U+0400（西里尔）是否在覆盖区间内 |
+| 以为元件"挂了库"就会跟着库翻译 | 数出一堆带 TextLibId 的元件，以为导入文本库就能上英文 | 拷贝元件会连着上一条的 `TextLibId` 一起复制。先把每个 TextLibId 解到条目、与元件自身文字比对：对不上的就是拷贝残留（本机实测 494 个元件里 107 个带 TextLibId，98 个能解出条目，其中 **97 个全指向同一条**）。导入库≠上屏，还要逐元件勾「使用文本库」 |
+| 默认带俄语 | "不需要俄语" | 先确认语言范围；不要就不出那列 |
+| 译文写死在脚本里 | 改词要动代码 | 词典单独一个文件（`ELEMENT_EN`/`LONG_EN` 或 json），脚本只调用 |
+
+## 交付约定
+
+- 交付目录（你取用处）**只放最终可用件**：`文本库导入表.xlsx`。
+- 过程件（扫描 JSON、对照表、脚本）留在 `解码归档\<工程名>\` 或插件内。
+- 工程原件只读；不写 `Global\TextLibConfigInfo.cfg`、不改 `.wcfg`。
+
+## 词典
+
+插件不带词典也能跑（会列出缺译文的中文条目）。给某台设备配词典就写一个 py 文件：
+
+```python
+ELEMENT_EN = {"拓宇机械": "Tuoyu Machinery", "进料1速度": "Feed 1 speed"}
+LONG_EN = {"说明：...": "Note: ..."}   # 长句放这里
+ELEMENT_PT = {"定位夹": "Garra de Posicionamento"}   # 第三语种按语种键命名：PT / KO / RU / ES…
+LONG_PT = {}
+```
+
+```json
+{"en": {"启动1": "Start 1"}, "pt": {"启动1": "Partida 1"}}
+```
+
+再用 `fstudio-i18n` / `fstudio-retag` 的 `dict` 参数传入。

package/assets/fstudio-tables.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""fstudio-tables.py —— FStudio(.fsprj) 工程出结构化表（画面/控件）
+用法: python fstudio-tables.py <工程目录或 .fsprj> [输出目录]
+工程目录须含 HMI/System/fs2.s3db；输出 画面.tsv / 控件.tsv / 变量.tsv。
+"""
+import os
+import sqlite3
+import sys
+
+def main():
+    if len(sys.argv) < 2:
+        print("用法: python fstudio-tables.py <工程目录或 .fsprj> [输出目录]")
+        return 2
+    src = os.path.abspath(sys.argv[1])
+    root = os.path.dirname(src) if src.lower().endswith('.fsprj') else src
+    db = os.path.join(root, 'HMI', 'System', 'fs2.s3db')
+    if not os.path.exists(db):
+        print(f"找不到 {db}（FStudio 工程结构不符）")
+        return 3
+    out = os.path.abspath(sys.argv[2]) if len(sys.argv) > 2 else os.path.join(root, '解码归档', os.path.basename(root))
+    os.makedirs(out, exist_ok=True)
+
+    c = sqlite3.connect(db)
+    def rows(sql):
+        try:
+            return c.execute(sql).fetchall()
+        except Exception:
+            return []
+
+    windows = rows("select WindowId, Name, FullName, WindowType, OrderId from WindowsInfo order by OrderId")
+    comps = rows("select ComponentId, Name, GraphicType, WindowId from OperationRecordComponent order by WindowId, Id")
+    tags = rows("select * from VariableTagDetailsV2 limit 0")  # 只探存在性
+
+    win_name = {w[0]: (w[2] or w[1]) for w in windows}
+    with open(os.path.join(out, '画面.tsv'), 'w', encoding='utf-8') as f:
+        f.write('画面ID\t名称\t全名\t类型\t排序\n')
+        for w in windows:
+            f.write('\t'.join(str(x if x is not None else '') for x in w) + '\n')
+    with open(os.path.join(out, '控件.tsv'), 'w', encoding='utf-8') as f:
+        f.write('画面\t控件名\t类型\t控件ID\n')
+        for comp in comps:
+            f.write('\t'.join([win_name.get(comp[3], comp[3] or ''), comp[1] or '', comp[2] or '', comp[0] or '']) + '\n')
+    tag_cols = [r[1] for r in c.execute('pragma table_info("VariableTagDetailsV2")')]
+    with open(os.path.join(out, '变量.tsv'), 'w', encoding='utf-8') as f:
+        f.write('变量名\t类型\t地址\t未解出说明\n')
+        if not tag_cols:
+            f.write('\t\t\t本工程无 VariableTagDetailsV2 表\n')
+        else:
+            n = c.execute('select count(*) from VariableTagDetailsV2').fetchone()[0]
+            if not n:
+                f.write('\t\t\t本工程变量表为空（控件地址在 Bin/fshmi.bin，见 控件地址.tsv）\n')
+
+    # 控件地址：Bin/fshmi.bin 是编译后的屏程序，里面是「指令编号 + 地址」流
+    # （SW n=开关/位、NE n=数值设定、AE n=字符串、OL n=…，后跟 D420/M45/Y4/SRW426 这类地址）
+    import re
+    fm = os.path.join(root, 'Bin', 'fshmi.bin')
+    addr_rows = []
+    if os.path.exists(fm):
+        txt = open(fm, 'rb').read().decode('utf-8', errors='ignore')
+        pending = None
+        for t in re.findall(r'(?:SW|NE|AE|OL|SRB|SRW)\s?\d+|[A-Z]{1,3}\d+', txt):
+            if re.match(r'^(SW|NE|AE|OL)\s?\d+$', t):
+                pending = t
+            elif pending and re.match(r'^[A-Z]{1,3}\d+$', t):
+                addr_rows.append((pending, t))
+                pending = None
+    with open(os.path.join(out, '控件地址.tsv'), 'w', encoding='utf-8') as f:
+        f.write('指令编号\t地址\t来源\n')
+        for a, b2 in addr_rows:
+            f.write(f'{a}\t{b2}\tfshmi.bin\n')
+
+    print(f"OK {root}")
+    print(f"  画面 {len(windows)} / 控件 {len(comps)} / 控件地址 {len(addr_rows)} → {out}")
+    return 0
+
+if __name__ == '__main__':
+    sys.exit(main())