HANDOFF — MCGS_File_Create

交接文档 · 当前状态快照。读完这一份就能接手干活,不用翻聊天记录、不用翻历史。 最后更新:2026-11-18(V0.10.8 启动页能力闭环:主人新对拍件 ground truth = MCGS 改启动页仅 2 处 diff(名字原位 + iID),set_startup_window 双向回放逐字节一致,startup_window 进 spec + 管线 5i 步(23 步)+ 19 条字节级测试;前轮 V0.10.7 存储点定位 + tools/mcp_diff.py 取证对拍脚本(更正 0.10.6「无存储点」定案);前次 V0.10.6 能力总表四项定案/落地:① 启动页存储点定位——存储点 = WndControl.lbObjects @794 区:u16 N + tagged 窗口名 + u16 N + u32 iID ×N + 同构内存窗口列表,四工程交叉验证(名单/iID 全对上,语义知识 L1766 互证);旧 C3 对拍件判无效(两件启动页同为窗口1,48 行表数据全同、22 页物理差异全为保存噪音);写入器待新对拍件回存定案② 文字颜色/字体节区定案并实现——编辑路线 = vendor edit_control 结构化定位(非固定偏移,变长名字/文本自动消化),标签 0x5008 / 输入 0x5025 / 按钮 0x5027 文字色 u32 原位改写、字体变长安全(宋体→微软雅黑 +4B/处 实测),controls[].text_color / font 进 spec + build 4b ③ 公共窗口槽定案并实现——槽 = 窗口 BLOB 尾 16B 槽块内 b[-8:-4] 单 u32(0xFFFFFFFF=空,否则公共窗 iID),754 窗全库对拍 0 异常、非空槽全部映射有效 iID,旧文档「0e 00 后 3 个 i32」证伪(0e 00 仅在载荷深处巧合命中,尾部 150B 零命中);windows[].common_window + 管线 5h 步 ④ 按钮按下态贴图早已闭环(V0.9.1)。新增 mcgslib/window/edits.py + tails.py 槽读写;21 条新测试全过(test_edits_common_window),管线快照 21→22 步。前次:V0.10.5 第六轮封膜包装机四页直复刻(examples/25)+ 潜缺陷十二修:PDF(威纶/Artrich 1024×600 四页:主画面/手动操作/登录对话框/菜单)→ spec 层直复刻,69 变量 / 439 控件 / 33 跳转 / 86 SVG;首压 visible_when / primitive_press_source / 克隆路线 primitive_picture 三条路线。十二修:①visible_when 导入漏改 ②图片改绑×可见动画投影–还原 ③节区链计数 80 碰撞 ④克隆空白窗尾名 ⑤Jet LVAL end 偏移掩码(DATA_56 读成 3161B vs OleDb 真值 601B)⑥V14 动画投影 ⑦A0 变体只读解析(21 变体/83 标准逐字节钉死,夹具入 test_button_readonly)⑧预览 SVG <svg 头 + sharp 本地回退 ⑨假 0x50XX 标记腐化几何(rect left=80 前导 00,5b 变长替换 −2B 补进坐标 → 80,16 变 -33554352,15)⑩预览窗口显示名取行 strName ⑪克隆路线图片改绑缺口(A0 母版顶层图片空 → texts 改名落空 → 瓦片柠檬黄;primitive_picture 扩展克隆路线 + window_refs.old_id,导航改克隆供体 Title 控件6)⑫预览 button_states 两态贴图映射反(抬起态应取顶层 picture)。视觉精修由离线对拍 PDF 四页驱动:pill 实绿白字 / 关态蓝轨 / 原语钮边缘色 / 点动反转文案 / 登录全彩背景+登框壳 / 急停初值对齐快照。交付件 mcgs-tools/out/第六轮_封膜包装机_1024x600.mcp verify V1–V14 总体 PASS(V11 MD5 86/86、V12 440 节区、V13 4 窗闭合、V14 104/104 无空引用),全量 pytest 125 过、doc_consistency PASS;组态三关通过(2026-11-17 主人裁决:打开/编译/仿真全正常,复刻效果确认「还不错」)。前次:V0.10.4 第五轮坑点能力化(发现 2/1/3,TDD 先红后绿):① export 控件分母改 0x50XX 节区链(window.section_controls,Pro 真实读取口径;旧类标签口径留 class_tag_controls,windows_parse.class_tag_blind 显式报盲点——纯 primitive 窗 28 节区/0 标签不再静默 0,原生窗 58 节区/91 标签不再多算);② template-probe/intent 识别图片跳转型首页(home_jump_labels ≥3 → hub_only,G系列真样例 10 标签钉死;多页护栏同口径拒首页摆内容,jump-hub 首页只放导航条);③ Jet 4 压缩文本读侧修复(根因翻转:写入侧正确——32位 Jet OleDb 读回真值取证;access_parser 把 FF FE 压缩前缀误当 BOM → db.py 内置 _jet4_text 解码补丁,四组 OleDb 写入样本字节钉死);发现 8 定案(主人确认 00:18 曾用 Pro 打开首构建件 → VARCOLLECTTABLE/COMM_CFG 重算=原厂编译行为,非工具写路径问题);全量 pytest 109 过(+16)、scan 18/18 PASS、交付件复验总体 PASS;发现 1/2/3 状态改「已能力化」留档 examples/README §24。第五轮交付件组态三关通过(2026-11-17 主人裁决:打开/编译/仿真全正常)。前次:V0.10.3 控件名改名分配器环扫修复 + 示例集 24(第五轮测试):第五轮=螺杆空压站集中监控六页 1024×600(N系列首页中枢 + 运行监控/手操控制/工艺参数/报警总览/仿真自检,40 变量 + 6 SVG 按钮图片对);真 Bug 修复 _free_control_name 向上-only 误报「同位数用尽」(首页 5 导航钮踩中控件6→9)→ 同位数环扫回绕(不造前导零名、真用尽仍 None),回归锁 tests/test_kinds.py、全量 pytest 93 过;示例集 24 = 意图 + 24_pics + 24_polish.py(spec 层补强:新页底色/导航条底 + 首页导航上移 98px 避模板第三行跳转标签同带交错);交付件 mcgs-tools/out/第五轮_空压站监控_1024x600.mcp verify V1–V14 总体 PASS(V11 SVG 38 全对 MD5 106/106、V12 472 节区、V13 17 窗闭合、V14 115/115),组态三关通过(2026-11-17 主人裁决);八项发现留档 examples/README §24(template-probe 对 G系列满幅背景首页误判 ok / export 类标签盲点纯原语窗 controls=0 / new_blank note 乱码 / V10 新页弹窗 advisory / 意图导航无 picture 钩子沿用原厂房子图标 / 首页导航同带交错 / fail-closed 三例正确拦截=页名冲突+母版类型不符+null-dtype / 侧车来源不明:00:18 件采集表呈 Pro 编译式重算但代码无写入点、对照重建干净→原件留档 anomaly_0018.mcp、交付换干净重建)。前次:V0.10.2 模板多页探查命令(template-probe):V0.10.0/0.10.1 意图层的模板探查取证机器(导航源 0x5027 + ltrb 矩形 + 首页 0x5009 原生网格底边 + 按钮图片对)提升为一等只读命令——template-probe <模板> [--home 首页] [--json],判定 ok / hub_only(首页只能当导航中枢)/ unusable(写多页 screens 意图前必跑);三接口同步(MCP mcgs_template_probe 17 tool / HTTP /api/template-probe 18 端点);intent.probe_template 返回值 +canvas;单测 +10(N 系列真样例事实钉死:hub_only / Title 0x5027#0 (742,438,792,475) / 图片10/图片11 / 网格底边 y=405 / TPC 头 3000x3000);命令数 24→25。前次:V0.10.1 图片按钮意图层(buttons[].picture):按钮背景图片——显式 [正常态,按下态] 图片名(≤3 字,须存在于工程图片库/pictures[],悬空引用 V14 FAIL 拦截)或 "template"(复用模板自身 0x5027 按钮图片对,N 系列实证=图片10/图片11,ButtonArchive 回环提取与 V0.9.1 改绑同一解析器);3 页 e2e V14 空引用 2→0 全 PASS;单测 20/20;examples 23 更新为图片按钮版(交付件无「空图片」警告)。前次:V0.10.0 多页导航意图层(screens 多页 + 自动导航条)+ 新建窗口空白窗机制(windows[].new_blank)+ 示例集 23:多页 screens(首页=home_window,内容页新名字自动建空白页,≤9 页)+ 自动导航条(克隆模板自身 0x5027 跳转按钮 + ltrb 定位(矩形实证 off=30 四个 int32)+ window_refs 重定向,种入顺序红线:指向原目标的按钮最后种);build 层 windows[].new_blank(78B 窗口头 + e4 00 未编译尾,首控件植入补写编译尾,尾名 3 字本名/其他占位「窗口1」——金标准 PhaseR 首跑 v6–v8:尾名≠行名、tail.iID=行 iID);fail-closed 护栏(页名冲突/缺首页/超页数/重名/hub 首页带读数/导航源缺失);16 项单测 + 3 页 e2e V1–V14 全 PASS;组态三关通过(2026-11-16 主人裁决:打开/编译/仿真全部正常),2 个非阻断「空图片」警告=内容页两个形状按钮(V14 离线预记,消除路线=图片按钮 primitive_picture,V0.9.1 已证)。前次:V0.9.2 指示灯意图层(indicators)+ V14 按钮图片引用 + donor-probe 修复 + 示例集 13:NL/图片意图层新增指示灯(数值显示框 0/1 + 彩色边框,fault=true 红边框;auto/preserve 双路线,变量自动补建 number 初值 0);verify 新规则 V14 按钮图片引用(0x5027 顶层背景名字引用:悬空引用/解析失败=FAIL,空引用=PASS+备注「空图片」警告,负例矩阵 16/16);修 donor-probe V0.9.0 拆包回归(isfile→is_file、mcgs.py 路径未随迁、export 报错被吞);第四轮单页小屏监控(blank+G系列+McgsIoT 13 通道,V1–V14 全 PASS)沉淀示例集 13;文档漂移修复(能力矩阵 §7/§8、SKILL.md、README)。前次:V0.9.1 原语按钮图片背景(primitive_picture):图片按钮,消除「空图片」警告:scaffold.schema.json + caps/build/spec.py 新增 primitive_picture([正常态,按下态] 图片名,仅按钮);caps/build/steps_controls.py _bind_button_picture(顶层 + 嵌套 background 指向真实图片名、开 words[16] 门,ButtonArchive 精确回环改绑);能力矩阵「按钮按下态贴图」⬜→✅;组态确认渲染 + V1–V13 全 PASS。前次:V0.9.0 结构重构:平铺文件 → 包分层(逻辑零改动,import 面零破坏):24 个 mcgs_*.py 薄壳 + probe_donor.py → caps/(去前缀);mcgs_build.py(2241 行)拆为 caps/build/ 包(14 模块);mcgslib/window.py(1947 行)拆为 mcgslib/window/ 包(12 子模块 + __init__ 全量重导出,AST 名字集差集 80/80 对拍);10 个测试 → tests/ pytest 化(conftest + pytest.ini);辅助脚本 → tools/;根目录只剩 mcgs.py + mcp_server.py 两个稳定入口,接口不变。前次:V0.8.17 蒸馏 mcgs-mcp-editor-skill fail-closed 纪律(仅方法论与门槛纪律,无新功能代码):build -o 防覆盖(+--force 显式放行);verify 新规则 V13 节区链完整(断裂=FAIL,扩展图片窗备注原生常态);scan/export 解析分母(窗口完整/断裂逐条报);新增 test_verify_negative.py V 规则内存损坏负例矩阵(15/15 抓出、5 条无负例如实报原因);TESTING.md §4.4 证据分层表 + 纪律。前次:C4 控件改绑变量名变长取样定案 + 写入器实现(V0.8.16,§5.15):主人把「参数设置」控件51 绑的 设置时 改名 设置时钟小时(3 字→6 字)另存 → 逐字节对拍定案控件节区 0x5025 变长只动 3 处:节区声明长 @4 + strfmt 串头字符数 + 串体原地变长(尾部整体后移零差异),绑定 [u32 id][u32 dtype] 不动(改名保 id),无计数字节、无尾部变量 id 条目(比按钮脚本更简);改名同时联动 0x5027 按钮脚本(与 §5.14 同原地变长机制);rebind_control_variable 变长版已实现且组态三关通过(2026-11-13)(字节级自测复现 MCGS 另存件)。前次:C1 变长取样定案 + 按钮脚本变长写入实现(V0.8.15):主人组态另存样本 → 逐字节对拍定案 6 处改动(§5.14,旧「绝对偏移失效」卡点撤销)→ window.replace_script_text + 5e 管线接入,构建产物节区与 MCGS 手笔逐字节一致,组态三关通过(2026-11-13);另修按钮普查把「操作属性」误标为脚本的 Bug(ab0da0d)。前次:Track A 复跑收尾(352e/f37d646 资产):A2 热接成功(根因=352c/352d 旧 CLSID COM 注册残留,已清)、A3 设备残留清零+新基线、A4 策略族 14 kind 执行链首跑、A5 refrename 5 kind 全 FAIL(内存已收敛干净、孤儿串容忍)、A6/A7 复核定论、A8 三处文档回填 → 见 docs/原生桥kind清扫-2026-11-11.md §9) 仓库:https://gitcode.com/linjian19901122/MCGS_File_Create 工具形态:WorkBuddy 环境下的 Python CLI(mcgs-tools/mcgs.py), 已封装为 WorkBuddy skill mcgs-file-create 文档导航:docs/WIKI.md ← 从这里进


0. 一分钟看懂

做什么:把「用昆仑通态 MCGS Pro 组态软件手工画屏」变成 「写一份 JSON spec → 命令行生成 .mcp 工程」。

为什么值得做:MCGS 的 .mcp 是 Access 数据库,界面里能画的一切 (控件、变量、设备、图片、脚本、跳转)都以明文或结构化字节存在文件里。 这套工具把这些结构逐个逆向出来并开放成可编程接口。

当前状态:V0.10.9,29 条命令、18 个 API 端点。 主链路全部打通并经组态软件实测通过;真实工程 30/30 verify PASS。 在线原生桥管道已验证可用(native selftest 全绿);业务 ABI 的定位已从 3 小时压到 ~15 分钟(稀疏目录 + 精简环境,见 §5.11)。原生桥资产已同步上游 f37d646(2026-11-12,Release v2026.11.10-online-flow:页激活 84.67s→3.42s / 接入→回读 157.07s→42.75s / ABI 缓存 112.16s→12.34s / 短路径,见 CHANGELOG 0.8.14);✅ 352e 部署面已用新资产重建并接入成功(2026-11-12/13,Track A):任务目录 F:/Studio/Code/MCGS_File/原生桥任务-352e/,352c/352d 旧 CLSID 注册已清,热接 ok=true。 原生桥部署准备阶段已成功跑通 6 步(V0.8.5,native deploy 2026-11-07 实测 ~16 分钟,稀疏目录 116/5874 签名 + 精简扫描):runtime/bootstrap/engineering 已 staged。索引完成瘦身——主索引 abi-target-profile-index.json 由 16.06MB 降到 0.24MB,完整诊断移入 abi-target-profile-supplement.json(18.47MB,C# 端不读、不参与哈希校验)。待在组态软件里手动 connect(见 §9.1)。

项目定位(最重要的一条,先读这个)

需求 → [脚手架阶段:工具链] → [人工精修阶段:组态软件] → 定版
        控件/变量/图片/连线      条件动作、对象调用、工艺细节
        ↑                              │
        └──── 精修成品回流入母版库 ←───┘

工具链加速的是脚手架阶段,不取代组态软件。 遇到做不了的能力(条件分支、对象方法调用、配方逻辑、文字颜色…), 第一反应不是硬啃逆向,而是「能不能变成一个人工精修件 + 一条收录命令」 —— 能做成母版反复复用,就已经是巨大的杠杆。

规程见 docs/人工精修模板的收录与复用.md。


1. 当前状态快照

维度 状态
版本 V0.10.9(mcgslib/__init__.py)
统一入口 29 条命令(mcgs.py <cmd>)
自检入口 mcgs.py selfcheck(注册表 / 文档 / 分层 / 负例 / 管线;--full 加环境)
HTTP 端点 18 个(按 HTTP method 计,FastAPI mcgs.py serve)
控件 kind 身份表 21 类 + 2 类「实测已知·身份未取证」(0x501E / 0x5026 功能=流动块)
可用控件 type 23 个(9 类固化母版 + 14 类本地登记),全部经组态实测
验证规则 V1–V15(mcgs.py verify)
自测套件 pytest 套件(python -m pytest 单闸;含 contract / lengths / pictures / kinds / scripts / window_deletes / nativebridge / serve_v2 / 语义三层一致 / verify_negative 负例矩阵 / layers 依赖护栏 / cli_registry 注册一致性 等)
示例集 12 个(mcgs-tools/examples/):9 个 ScaffoldSpec(6 基础 + 3 工控领域,check 全通过、旗舰 10 端到端 build→verify 实测 PASS)+ 3 个意图样例(20 NL / 21 图片 / 22 威纶通,作 compile-intent / image-to-spec 输入,非 spec、不走 check)
回归基线 官方样例 红线 0(18 件;13 件 V15 基线豁免输出保留,2026-11-18 主人裁决见 §13)+ 真实工程 30/30 PASS
格式基线 McgsPro 3.5.1.7267(起于此版本;3.5.2.12210 亦验证通过)
组态验收状态 第六轮封膜包装机四页交付件组态三关通过(2026-11-17 主人裁决:打开/编译/仿真全正常);第五轮空压站六页交付件组态三关通过(2026-11-17 主人裁决:打开/编译/仿真全正常);V0.8.16 控件改绑变量名变长写入组态三关通过(2026-11-13);核心能力均经组态三关;原生桥管道已通、业务 ABI 定位已提速到 ~15 分钟,主索引已瘦身(0.24MB + 18.47MB supplement);65 kind 清扫(2026-11-11):59 可测 kind 全部 inspect 通过,45 个跑完执行链(✅17 / 📖5 / ⚠️13 / ❌5 / ⏭1);Track A 复跑收尾(2026-11-13,352e/f37d646 资产):A2 热接成功(根因=352c/352d 旧 CLSID 残留,已清)、A3 残留清零+新基线、A4 策略族 14 kind 执行链首跑(2 PASS,4 个 NativeAbiUnavailable=稀疏目录定位缺失)、A5 refrename 5 kind 全 FAIL(fwd 生效 rev 拒,内存已收敛干净,孤儿串组态目视确认正常·容忍)、A6 reference-sync 从未执行、A7 三 FAIL 复核定论、device-node-rename 升级正向实测打通 → 详见 docs/原生桥kind清扫-2026-11-11.md §9
部署资产 上游 turnkey 完整包(1.3GB)已下载并分析 —— 结论见 §5.11
文档体系 WIKI 化(Phase 8)—— 见 docs/WIKI.md
待验证分支 chore/arch-guardrails-p2(P0–P2 工程化改造,待本机全量回归 → 见 §11)

完整能力清单见 docs/能力矩阵.md(含每项的验证方式与证据)。


2. 30 分钟上手

# ① 依赖(注意镜像,见 §8.2)
pip install access_parser jsonschema
pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com unicorn==2.1.4 pefile
pip install fastapi uvicorn httpx2

# ①b 环境自检(一条命令看能不能跑)
cd mcgs-tools
python mcgs.py doctor

# ② 看有哪些底版
python mcgs.py templates

# ③ 看官方样例里有什么控件 / 什么按钮带动作脚本
python mcgs.py kinds   "D:/McgsPro/Samples"
python mcgs.py buttons "D:/McgsPro/Samples" --with-script

# ④ 写一份 spec(契约见 mcgs-tools/SPEC.md 与 scaffold.schema.json)
#    写之前先看现有结构:
python mcgs.py inspect strategies 工程.mcp
python mcgs.py inspect recipes 工程.mcp

# ⑤ 生成 → 自检 → 交给人在组态软件里验收
python mcgs.py check spec.json
python mcgs.py build --template flat-cool --donor "D:/McgsPro/Samples/G系列样例演示工程1024x600.mcp" \
                     --spec spec.json -o 新工程.mcp
python mcgs.py verify 新工程.mcp
#    最后:MCGS Pro 组态软件 打开 / 编译 / 仿真下载 三关验收

最小可用 spec 骨架:

{
  "variables": [{"name": "加热状态", "type": "number", "init": "0"}],
  "windows":   [{"clone": "主页", "name": "报警页"}],
  "controls":  [{"from_mcp": "<样例.mcp>", "from_window": "参数设置",
                 "tag": "0x5025", "occurrence": 6, "window": "主页",
                 "bind": "设定时"}],
  "button_scripts": [{"window": "主页", "control": "控件1",
                      "find": "提示标志 = 0", "replace": "加热状态 = 0"}]
}

全量回归(改完代码跑这个):

cd mcgs-tools
for t in test_contract test_lengths test_pictures test_kinds test_scripts \
         test_window_deletes test_nativebridge test_serve_v2; do python $t.py; done
python mcgs.py scan F:/Work --quiet        # 真实工程集(2026-11-12 核:本机暂缺,待恢复)
python mcgs.py scan F:/BR_Project --quiet  # 同上

3. 仓库地图

MCGS_File_Create/
├── README.md                  ← 项目门面(是什么 / 怎么装 / 怎么用 / 导航)
├── HANDOFF.md                 ← 本文件:当前状态快照
├── docs/                      ← WIKI 文档体系
│   ├── WIKI.md                ← 文档地图(入口)
│   ├── 架构.md                ← 五层分层图 + 依赖规则 + 加功能落点
│   ├── 能力矩阵.md            ← 能力 × 命令 × 验证 × 验收状态
│   ├── 命令参考.md            ← 29 条命令用法
│   ├── 验证方法.md            ← 五道验证关卡
│   ├── 扩展指引.md            ← 加/删/改功能的标准流程
│   ├── MCGS语义知识.md        ← 语义知识层(含 §8–§11 实机知识)
│   ├── mcgs_semantics.json    ← 上一份的机器可读版(生成,可复现)
│   ├── 原生桥部署规程.md      ← 部署步骤 + 风险清单
│   ├── 人工精修模板的收录与复用.md
│   ├── MCGS工程文件(mcp)逆向分析与AI脚手架可行性.md
│   ├── Ghidra逆向提问卡_Stgy序列化链.md  ← 未解问题卡
│   └── archive/               ← 历史存档(只增不改,勿照搬旧结论)
├── mcgs-tools/                ← 工具链本体
│   ├── mcgs.py                ← 入口层:统一 CLI(29 条命令,COMMANDS 注册表)
│   ├── mcp_server.py          ← 入口层:MCP server(17 tool,subprocess 调 mcgs.py)
│   ├── caps/                  ← 能力层:原顶层 mcgs_*.py 薄壳(去 mcgs_ 前缀)
│   │   ├── build/             ← 构建管线(原 mcgs_build.py 按步拆分)
│   │   ├── verify.py          ← V1–V15 验证器
│   │   ├── serve.py(+v2)      ← FastAPI 无头模式(18 端点)
│   │   ├── writeback.py       ← 写回驱动(32 位 PS + .NET OleDb)
│   │   └── native.py / ...(其余逐命令一个文件)
│   ├── mcgslib/               ← 语义层 + 字节层
│   │   ├── window/            ← 原 window.py 按功能域拆包(__init__ 全量重导出)
│   │   ├── kinds.py           ← kind 身份表 + 可编辑集合
│   │   ├── objdata.py         ← 变量表解析与重打包
│   │   ├── stgyedit.py        ← 策略 / 配方读写
│   │   ├── primitives.py      ← 零母版控件构造
│   │   ├── semantics_extra.py ← 实机验证真值常量
│   │   ├── nativebridge.py    ← 在线原生桥客户端
│   │   ├── ui/                ← 离线预览 / 文字体检
│   │   ├── script/            ← 条件脚本字节码
│   │   └── vendor/            ← 上游移植的字节原语(改则同步 THIRD_PARTY)
│   ├── tools/                 ← 辅助脚本(doc_consistency/build_semantics/smoke_mcp/run_resolve_catalog)
│   ├── tests/                 ← pytest 化测试(python -m pytest 单闸)
│   ├── scaffold.schema.json   ← spec 契约(单一事实源)
│   ├── SPEC.md                ← ScaffoldSpec 全量字段与边界
│   ├── TESTING.md             ← 验收协议 + 回归矩阵
│   ├── CHANGELOG.md           ← 版本变更史
│   ├── THIRD_PARTY.md         ← 移植件出处与改动
│   ├── examples/              ← 12 个示例(9 spec + 3 意图样例)
│   ├── static/index.html      ← Web UI
│   └── assets/pro-native-bridge/  ← 上游原生桥资产(21MB,可选部署)
└── .gitignore

4. 能力清单

完整表格见 docs/能力矩阵.md。 这里只列结论:

4.1 ✅ 经组态软件实测通过

能力 spec 字段 / 命令 证据
设备注入 + 通道同名绑定 devices[] / device_bindings[] 写回与 MCGS 原生逐字节一致
变量增删改 variables[] 变长、ID/计数同步
设备图片注入 pictures[] SVG 信封定稿公式,round-trip 211/211
显示文本替换 texts[] 变长,需 force
窗口克隆 / 批量建页 windows[] / batch[] —
按钮跳转重定向 / 窗口改名 window_refs[] / renames[] —
23 类控件种入 controls[].type 全部经组态实测
标签绑定变量 label_bindings[] —
按钮动作赋值 button_actions[] 值域按变量类型守
面板机型码 + 尺寸适配 panel 含 skip_popups
策略脚本替换 scripts[] 双写 Stgy + StgyAndTrigger
控件 kind 知识层 + V12 mcgslib/kinds.py 21 类身份表 + 2 类身份未取证(0x501E / 0x5026 功能=流动块)
母版变体 catalog add --as + controls[].type="button@条件动作" —
整窗收录 catalog add-window 人工精修页一次入库
策略源码精确编辑 strategy_edits[] 组态用自己的编译器重编了源码(缓存 0→35B)
配方单元格改值 recipes[] 面包[1][1]=88、面包[3][2]=55 保留
按钮脚本改写 button_scripts[] 2026-10-30 组态三关
按钮脚本文本变长写入 button_scripts[](变长 replace) 2026-11-13 组态三关(V0.8.15,C1 取样定案 §5.14)
控件变量改绑 controls[].bind 2026-10-30 组态三关
控件改绑变量名变长写入 controls[].bind(变长) 2026-11-13 组态三关(V0.8.16,C4 取样定案 §5.15)
零母版从零造控件 controls[].from_primitive 组态另存后 9/9 控件存活
按钮按下态图片(图片按钮) controls[].primitive_picture / 意图层 buttons[].picture 2026-11-15 组态三关(V0.9.1;嵌套 background words[16] 门)
窗口删除(带引用护栏) window_deletes[] test_window_deletes
按钮普查 mcgs.py buttons 官方样例 183 个带动作按钮

4.2 原生桥(在线能力,2026-11-07)

能力 命令 状态
自测闭环(管道可用性) native selftest ✅ 全链路通过(2026-11-07;ping 的 dispatch_thread = UI 线程)
部署编排 native preflight / deploy / postdeploy / attach ✅ 准备阶段跑通;接入待人工执行
稀疏 ABI 目录 make_slim_catalog.py(新) ✅ 116 / 5874 条签名(2.0%) —— 定位从 3 小时压到 ~15 分钟
portable 路线(免编译) portable-engine/materialize.py 🔵 可纯离线跑;定位不全只让单个功能 unavailable,容错远高于 legacy

4.2 🔵 只读能力(不写工程)

verify(V1–V15)· scan(批量体检)· export · kinds · buttons · refs · inspect(策略/配方)· preview(离线渲染)· textfit(文字体检)· diff / salign(对比)· doctor(环境自检)· clipdump(剪贴板捕获)· native status / native ops

4.3 🟡 已实现,待组态实测

条件脚本字节码(mcgs.py script)—— 编译/检查/仿真语义已验证, 但适用对象是策略脚本,不是按钮动作。

4.4 ⬜ 明确未做

项 原因
0x503C/0x5028 控件改绑变量名变长 0x5025 已实现且组态三关通过(V0.8.16,C4 取样 §5.15);0x503C/0x5028 同机制预期适用但未单独取样,各自需取样 + 三关
数值型多位数赋值(=50) 与脚本文本变长同机制(V0.8.15 三关通过)自动解锁;如需独立用例可再跑
启动页(启动窗口列表) 已实现(V0.10.8,2026-11-18):存储点定案 = WndControl.lbObjects @796 区 u16 N + tagged 窗口名(ff fe ff + 1B 长 + UTF-16LE)+ u16 N + u32 iID ×N + 同构内存窗口列表(6 工程交叉验证,语义知识 L1766 互证);MCGS 写入行为 ground truth = 仅名字原位 + iID 2 处 diff,set_startup_window 新对拍件双向回放逐字节一致;startup_window 进 spec + 管线 5i 步(23 步);旧 C3 对拍件判无效(两件启动页同为窗口1);组态三关待交付件验收
文字颜色 / 字体节区 已实现(V0.10.6,2026-11-18):编辑路线 = vendor edit_control 结构化定位(非固定偏移),标签/输入/按钮文字色 u32 原位改(0x5008 payload@0xA2、0x5025 @0xB4、0x5027 两处 0x7C+0x289 实测)+ 字体变长安全;controls[].text_color / font;字节级测试全过,组态三关待交付件验收
0x5025 图片引用变长替换 实验 M/N 已证伪(4 字起「空图片」+ 级联损坏)
巨幅内嵌图片窗口克隆 「启动画面」这类超长 BLOB 不支持
0x501E 类名 实测存在但身份未取证
0x5026 流动块 功能已取证=MCGS 管道流动动画构件;字段未验证,不可改动
内容等比缩放 21 类 kind 矩形位置各异,未全取证
公共窗口槽写入(给窗口新设/改绑底板/侧栏) 已实现(V0.10.6,2026-11-18):槽布局定案 = 窗口 BLOB 尾 16B 槽块 b[-16:-12]=04 00 00 00、b[-12:-8]=00 00 06 00 常量 + b[-8:-4] u32 槽(0xFFFFFFFF=空,否则公共窗 iID)+ 末 4B 零;754 窗全库对拍 0 异常、非空槽全部映射有效 iID;旧「0e 00 后 3 个 i32」证伪;windows[].common_window + 管线 5h 步;组态三关待交付件验收

下列多数不必硬啃逆向 —— 走「人工精修 → 收录复用」更划算(见 §0 定位与 §9.2)。


5. 技术定案(踩坑换来的,接手前务必读)

这一节是本项目最贵的资产 —— 每一条都是逆向 + 实测得来的,改代码前先确认是否违反。

5.1 文件格式层

  • .mcp = Access Jet 4.0 MDB(本质是 .mdb)。
  • 表:System(全局键值)、ObjData(变量表)、 MCGS_PICTURE_LIST + MCGS_PICTURE_DATA_<n>(图片库)、 WndUser(窗口表,lbObjects 列 = 窗口 BLOB)。
  • 字符串编码:FF FE FF <len> + UTF16LE。len < 0xFF 时头 4 字节; len == 0xFF 时头 6 字节(后跟 u16 真实长度)。
  • 写回通道:64 位 Python 看不到 32 位 Jet 驱动 → 必须走 32 位 PowerShell + .NET OleDb(Jet 4.0)(caps/writeback.py)。 每条 UPDATE 严格校验 rows==1(静默 0 行曾把构建器坑过)。
  • ObjData 长记录:_find_id_anchor 的搜索窗口要渐进放宽 (164→384→1024→4096→8192)。真实工程的组对象记录 tagged 串在 ID 后 324 字节处, 窗口不够会整条链断在那。标准记录永远第一档命中 —— 官方样例零退化。

5.2 窗口 BLOB 与控件 kind

  • 窗口 BLOB = 节区链。每个节区首 u32 = kind(21 类,mcgslib/kinds.py), 决定 MCGS 把它还原成哪种控件。
  • 证据裁决规则:第三方 Ghidra 取证 ∪ 本仓库组态实测,实测优先。 写进 kinds.py 顶部注释,改动前先读。
  • 真实工程里还有 0x501E(实测 66 处 / 10 个工程)—— 官方样例与上游都没有,身份未取证 → 单列登记表, V12 判 PASS 但逐条列出,不进任何可编辑集合。
  • 新增 kind 的铁律:字段未取证 → 不可改。 宁可登记成「实测已知·身份未取证」,也不要给它开可编辑。
  • 补充:0x5026 已在 V0.8.6 经字节级取证登记为「流动块(管道流动动画)」功能身份(字段未验证,不可改动),是「身份未取证但功能可用」的第二个实例,也是「先取证再写」闭环的范例(见 §9.1.1)。

5.3 变量引用的四种形态(母版筛选与补建的核心)

形态 位置 出现在
A 变量名之前 8 字节 = [u32 id][u32 dtype] 输入框 0x5025
B 变量名编码之后 8 字节 = 同上 下拉框 0x503C
expr 节区里的表达式串(名字=值) 三维球 0x5023、矩形 0x5004、单位 0x503A…
script 脚本文本里按名字引用(明文,无 id) 按钮 0x5027

识别依据是「变量名匹配」而非固定偏移 —— 这样不会把普通数据误判成绑定点。

5.4 按钮动作 = 结构化存储,不是编译字节码

  • 动作在 0x5027 节区里存两处:控件属性区的常量明文(UTF16 '0'/'1')
    • 事件区的值槽位(u16)。两处必须同改,只改一处 MCGS 会按旧的执行。
  • 定位规则:变量名编码结束后 +64 字节 = 值(三样本跨工程验证)。
  • 值域按变量类型守:开关型只允许 0/1(写别的被解释成「取反」,主人实测); 数值型受等长限制;字符串型拒绝常量赋值。
  • 按钮的整个单击动作是一段明文脚本(FF FE FF <len> + UTF16LE), 多行脚本 / If-Else 条件 / ! 内置函数调用全在这一段里。
  • 脚本文本里的跨对象引用(MCGS.用户窗口.X.Y.方法()、!OpenSubWnd(X)) 指向别的窗口与控件 —— MCGS 按名字解析,同名同控件就有效,不需要重定向 id; 目标工程没有就是悬空引用 → 组态报「未知对象」。

5.5 「等长」是贯穿全局的硬约束

控件名、变量名、图片引用名 —— 一律等长。 变长要动嵌套长度字段或绝对偏移,属未实测路径。 (例外一:texts[] 文本替换走 force 开关,因其嵌套长度机制已破解。 例外二:button_scripts[] 脚本片段等长/变长均支持——C1 取样定案 §5.14, 按钮节区变长只动 6 处、无绝对偏移失效,2026-11-13 实现。)

5.6 母版(mcgs.py catalog)

  • 母版 = 某个 .mcp 里的一段控件节区字节。
  • 母版若写死了变量 id 或图片引用,种进别的工程就是悬空引用 → 干净度检测必须识别全部四种引用形态。
  • 母版控件名的位数决定等长改名空间(「控件8」只剩 10 个可换, 「控件48」还有 90 个)→ 批量登记时优先挑位数多的。
  • 母版变体:同一 kind 可登记多个母版,键 = type@变体名 (如 button@条件动作)。catalog add --as <变体名> 登记, controls[].type = "button@条件动作" 取用。 收录时会把依赖清单打出来:引用的变量(自动补建)、引用的图片(连带拷贝)、 跨对象引用(需目标工程有同名窗口/控件,唯一需要人工决策的)。
  • catalog.local.json 是本机登记文件,已 .gitignore。
  • 母版来源自愈:固化母版缺失 → 自动到官方样例里找无跨对象引用的同 kind 节区 代替(图片引用与变量引用不阻塞 —— 构建器会连带拷贝/补建)。 构建报告逐条标注用的是「本机精修 / 固化 / 官方样例替代」。

5.7 零母版路线(from_primitive)与字体坑

两条路线并存,不是替代:

路线 spec 写法 适合 代价
母版路线 type: "button" / from_mcp + tag 照抄已有控件业务(动画、权限、原厂样式) 要有母版;母版带走的变量要补建;控件名撞名要换名
原语路线 from_primitive: true + primitive_* 从零搭页面,要干净的新控件 类型限 8 类;新控件无旧动作/绑定/图片引用

关键实现细节:

  1. 节区格式与母版路线完全一致:tag(u32) + 长度(u16) + payload。 上游 ControlRecord.to_bytes() 与本仓库 window._validated_section 期待同一格式, 所以原语造的节区能直接走 append_control_section / plant_first_section。
  2. 字节兼容已实测:上游 WindowArchive.parse 解析本机 G 样例 15 个窗口, to_bytes() 与原始 BLOB 逐字节相等,15/15 通过。
  3. 变量 id:原语造控件时直接把目标工程的真实 id 写进节区(不是临时 id), 之后再用 window.retarget_variable_ids 复核一遍。
  4. 按钮双态是原生 press / release 两个字段,各自独立, 不受母版路线的等长替换限制 —— 这是原语路线比母版路线强的地方。
  5. 护栏:原语路线不认母版专属字段(from_mcp/tag/occurrence/bind/ltrb/texts), 写了直接报错,不静默忽略。

字体坑(2026-11-07 实测,静态验证抓不到):

  • 组态软件按中文名取资源名,写英文名(Microsoft YaHei)→ 打开工程时直接报错。
  • 扫全部 9 份官方样例:字体名只有 「宋体」(10984 次)与 「Arial」(426 次),从不写英文名。
  • 字体块结构:ff fe ff <字符数> + UTF16LE —— 长度是字符数,不是字节数。
  • 修法落在 mcgslib/primitives.py:KNOWN_FONTS / DEFAULT_FONT="宋体" / FONT_ALIAS / normalize_font() —— 不写 family 默认宋体; 写英文名自动转中文名;写组态不认的字体名在 check 阶段就拦下。
  • 直线/矩形原生无字体字段,写 font 明确报错(FONT_TYPES 常量区分)。

通用教训:MCGS 组态里凡是「按名字取的东西」(字体、图片), 值都要取自官方样例实测过的写法,不要凭直觉用英文系统名。

5.8 窗口删除与尺寸适配

  • 窗口删除是物理 DELETE,不软删:全盘样本(118 个 .mcp / 788+ WndUser 行) iDeleteFlag 全为 0,无软删先例,软删语义无从推断 → 盲写风险大。 物理 DELETE 语义确定(行没了 = 窗口没了)。
  • 删除前自动扫引用(护栏核心):别的窗口跳它或调它的控件方法, 目标被删后会变悬空 → 组态报「未知对象」→ 默认拒绝并列出引用清单, force: true 才放行。自引用不算外部引用(随窗口一起消失)。
  • 排在管线最后一步(5g):所有引用改写(5b–5e)完成后才执行。
  • panel.skip_popups:判定口径是「该窗当前页面尺寸 ≠ 模板原基座尺寸」→ 判为弹窗 → 跳过不改。 ⚠️ 基准是模板原尺寸(从 System.TPCInfo 第 2、3 段读), 不是目标 panel 尺寸 —— 用后者会把主页面也误判成弹窗(实测踩过:改写 0 处)。

5.9 语义知识层(真值来源)

  • docs/mcgs_semantics.json 是唯一机器可读真值源, 由 tools/build_semantics.py 从 mcgslib/semantics_extra.py 生成, 可复现(重跑字节零差异,契约测试守着)。
  • semantics_extra.py 是运行时可 import 的 Python 常量 —— 不只进文档,工具链代码能直接引用。
  • docs/MCGS语义知识.md §8–§11 是实机验证的知识(官方文档没写的部分)。
  • 四条最容易再踩的(详见语义知识 §8–§11):
    1. 文字左右留白 ≈ 6 像素(工具判据用 8,多留余量),框宽不足裁掉末字
    2. 离线预览 ≠ 原厂效果(3 处已知差异,见 §8.6)
    3. 驱动类型码写错 → 读正常、写静默失败(命令返回 0,PLC 收不到,也不报错)
    4. 存盘浏览首条 GetCellValue(1,1)、末条 GetCellValue(N,1)

5.10 验证器分级(宁可漏检不可误伤)

  • 信封格式错 = FAIL;同名/同 MD5 重复 = PASS + 备注 (导入期条目 ID 机制的产物,不影响使用)。
  • 尺寸比较加 ±1 像素容差(控件宽度是 float,token 存取整值)。
  • 弹窗豁免不要求多数派尺寸 == TPC 尺寸(TPC 与页面尺寸可以不同,是配置不是不一致)。
  • 宁可漏检不误伤 —— 误报会让工具链在真实工程上永远给不出结论 (Phase 5 教训:V0.3 之前只在官方样例上验证过,一上真实工程 0/30 全是误报)。

5.11 ABI 定位:三个加速杠杆 + 一个致命坑(2026-11-07 实测)

原生桥的「第 3 步(ABI 定位)」是全流程最重的步骤。三条路线的实测对比:

路线 引擎 定位量 编译 定位不全时
legacy(bind_common_delivery.v5.py) 现场编译 157 个源文件 5,874 条签名 要 编译失败(地址不全)
portable(portable-engine/materialize.py) 预编译 DLL,一字节不改地拷贝 5,874 条签名 不用 单个功能 unavailable,引擎仍可用
portable + 稀疏目录(本仓库新增) 同上 116 条(2.0%) 不用 同上

杠杆一 · 稀疏目录(abi-adapter/make_slim_catalog.py,本仓库新增)

业务引擎源码里真正被消费的地址点只有 162 个 → 反查 reference.json.gz 的 signatures 只命中 116 条(editor 96 / mfc 15 / qt5core 3 / common 2)。 其中 guard_length>=64 的重签名 12 条(全目录 438 条)—— 每条要扫固定的 110,616 个候选点,这是耗时的长尾来源。

预估候选点:4,845 万 → 133 万(约 1/36)。

python assets/pro-native-bridge/abi-adapter/make_slim_catalog.py --out slim.json
# → 签名: 116 / 5874 (2.0%)

杠杆二 · 精简环境(扫描根由环境变量决定)

abi-adapter/module_selection.py 的扫描根 = {editor.parent, install, install/Program} + $WINDIR/SysWOW64 + $WINDIR/System32 + $PATH 的每个目录。本机 16 个逻辑模块全在 D:\McgsPro\Program,其余全是无用扫描:

扫描根 候选 PE 文件
D:\McgsPro\Program 86
C:\Windows\SysWOW64 2,849
C:\Windows\System32 4,132(64 位 Python 上重定向到 SysWOW64 → 白扫一遍)
PATH 的 66 个目录 5,783
合计 ≈ 12,850

把 WINDIR 指向空目录、PATH 精简到 D:\McgsPro\Program;D:\McgsPro;C:\Windows\System32;C:\Windows → module_discovery 从 11 分钟降到 ~2 分钟。

⚠️ 精简只给子进程(env= 传参),shell 自己别动 —— 否则 Git Bash 的 rm/dirname 会失效(实测踩过)。

杠杆三 · 精确模块路径(--actual-module alias=绝对路径)

参考目录每个逻辑模块都记了 install_relative_path,据此构造绝对路径, 本机 16/17 命中(缺的 h5u_modbustcp.ui 是没安装的驱动)。 价值是正确性不是速度 —— 避免「System32 里有同名 DLL → 选错文件」。 (实测不减少扫描量:上游要扫完才能证明给的路径是最高优先级候选。)

致命坑 · 稀疏目录不能删顶层字段

abi_locator.py 最后阶段会读 catalog['profiles'](22,183 个 cache_addresses,是定位加速器):

abi_locator.py:1173
cache_addresses = [field for p in catalog['profiles'] for field in p['fields']] + ...
KeyError: 'profiles'

只裁剪 signatures,其余顶层字段原样保留 (schema / reference_modules / types / profiles / explicit_addresses / import_slots)。踩过这条:前面 23.7 分钟定位全部白跑 (上游不落盘中间结果,中断即全丢)。

另一条坑 · 进度里的 completed 不是文件数

preparation-progress.json 的 completed 是已解析的逻辑模块数, 真正的进度看 image_cache_hits。把 completed 当文件数会低估速率 5 倍。

第三条坑 · 稀疏目录下索引会触发 16MB 护栏(V0.8.5 已修:supplement 方案)

delivery/bind_common_delivery.v5.py:355 与 portable-engine/materialize.py:258 各有 need(len(index) <= 16*1024*1024, ...) 的体积护栏——但 16MB 只是 Python 端 的过时启发式。C# 运行时(abi-adapter/NativeAbiTargetProfiles.cs:63)用 MaxJsonLength = int.MaxValue,对索引体积无任何限制;details 仅作错误提示字符串、 entry_statuses 运行时根本不消费。

稀疏目录只削 signatures(116/5874),不削 profiles,于是 201 个 coverage/test profile 因字段未解析变 partial,unresolved_fields 诊断信息被整段塞进索引 details, 真实 json_bytes(ensure_ascii=False, indent=2)= 16,843,485 字节(≈16.06MB), 恰好压线超 16MB 护栏被误杀(V0.8.4 临时方案:护栏 16MB→64MB)。

根治(V0.8.5):abi_binding.py 的 index() 内部把完整 details/entry_statuses 诊断收集到 self.supplement,主索引行 details 只留短摘要、entry_statuses 置空;bind_common_delivery.v5.py 与 materialize.py 写盘时把 supplement 写成独立的 abi-target-profile-supplement.json (加入 copied 随产物分发,但排除出 ExpectedIndexSha256 校验链)。结果: 主索引 16.06MB → 0.24MB,supplement 18.47MB(C# 端不读),C# 运行时行为零变化。 护栏 64MB 仍保留作病理体积哨兵(C# 端 int.MaxValue 无真实限制)。

5.12 turnkey 完整包到底省什么(2026-11-07 实测)

林先生下载了上游 turnkey 完整包(F:\mcgs-engineering-turnkey-2026.11.06-bootstrap-win-x64\, 1.3GB)。分析结论:

问题 答案
代码比我们的 clone 新吗? 完全同版本 —— bundle.json 的 source_commit 就是我们 clone 的 HEAD d762247
ABI 目录更大吗? 字节完全相同(reference.json.gz 2674004 B / 5874 签名,两份一致)
能省掉定位吗? 不能 —— portable-engine/materialize.py 第 179 行照样调 TargetBinding
能省什么? 省编译(157 个源文件)+ 部分降级(定位不全只让单个功能 unavailable)
厂商介质用得上吗? 用不上 —— 包内是 3.5.2.12210,本机是 3.5.1.7267,SHA 与大小都不同,SHA 快速路径失效

结论:完整包的价值 = 预编译引擎 + 一键流程 + 部分降级; 定位这个固有成本它也躲不掉。我们用稀疏目录 + 精简环境达到了比它更快的效果。

可借用的资产(engine/business/McgsEngineering.Portable.dll,2.36MB, SHA 182b8921cf47b09ecfe04ee6f8db07f284659e5ee41eef30da101924af45c7d2)—— 它内嵌的 SourceCatalogSha256 与我们仓库的 source-addresses.json 完全一致, 可直接拷进我们的 portable 路线。


5.13 C# 引擎内存态流程与固化切口(2026-11-07 梳理)

「内存态」指活在 Pro 进程地址空间里的态,不是文件、不是 JSON:

  1. 触发:McgsHotAttach.exe --connect / PortableClient --connect
  2. 注入:SetWindowsHookEx 注入 Pro(x86) UI 线程;BootstrapLayout 强制 SamePath(宿主主模块 == 配置里的 editor),引擎只能活在 Pro 进程内
  3. 读原生态:各 profile 用 NativeMemory.Ptr/Readable/I32 直接读/写 Pro 原生内存(控件树、页面文档、MainCtrl 数组)
  4. ABI 解析:NativeAbiTargetProfiles 用 JavaScriptSerializer{MaxJsonLength=int.MaxValue} 加载 abi-target-profile-index.json(0.24MB,V0.8.5 瘦身)+ supplement(18.47MB),在内存构建 profile 表
  5. 强类型原生 API:NativeControlPropertyEditing 等消费,读写工程

关键约束:态严格绑定本次会话——NativeMainCtrlRestorationTrialProfile.SameHost 校验 process_id + ExpectedUiThreadId,换进程/线程即失效。

三条固化路线(代码已有雏形,未实现):

路线 固化对象 脱离 Pro? 现在能做? 改动量
A 构建期固化索引 ABI 索引在 dotnet build 烧进 DLL(嵌入资源 / Source Generator 强类型),运行时零 JSON 解析、自包含 不 ✅ 中(改 csproj/build)
B 内存态快照回放 首次成功 connect 后,把「已解析 ABI 表 + 原生结构」序列化(复用 Snapshot + MemoryPack)落盘,之后离线回放 / CI ✅ 回放时 ⚠️ 需先成功 connect 一次(目前 attached:false) 中
C 连接态持久化 把 MemoryMappedFile discovery + attempt/outcome receipt 固化到磁盘,重连/复用更稳 不 ✅ 小(已有雏形)

代码已存在的固化雏形:

  • Discovery():MemoryMappedFile 把 Pro 发现信息固化成命名共享内存 Local\McgsPortableBridge_v6_*,跨进程可见
  • attempt-*.json / outcome-*.json:把 connect 结果固化成 receipt(据第 76 行禁止重放失败)
  • Snapshot 机制(NativeLabelMetadataReadonlyProfile.Preserve):内存态快照,目前只用于校验,未用于回放

状态:仅文档固化(2026-11-07 林先生选定「先文档固化」),未写代码。固化优先级:先 connect 一次 Pro 后做 B 或 A。


5.14 按钮脚本文本变长写入(C1 取样定案,2026-11-13)

样本:官方 G系列样例「参数设置」控件6,脚本 !SetTime(设置年,…)(33 字符) → 组态里加一行 设置年 = 设置年(43 字符)另存。改前节区 937B → 改后 967B(Δ30)。

MCGS 手笔的字节级定案(改前/改后逐字节对拍):

  1. 脚本是节区里的单个 strfmt 串,原偏移原地变长:串头 @808 FF FE FF <字符数>(0x21=33 → 0x2B=43;<0xFF 仍用 4 字节头),串体 UTF16LE。 其后全部内容整体后移 +20B(33→43 字符 = +10 字符 = +20 字节)。
  2. 节区长度字段 @4(u16):937 → 967(MCGS 自己更新)。
  3. 标志/计数字节 @82:0x80 → 0x84(+4,伴随新增动作行出现;精确语义待更多样本,写入器按「+4/每新增一行」暂定)。
  4. 串后紧邻 u32 长度:0x39=57 → 0x43=67(+10 = 字符增量,脚本区字符计数)。
  5. 尾部追加 10B:两个 5 字节条目 26 9c 00 00 00 / 3e 9c 00 00 00 (u32 变量 id + 00 分隔)——新行 设置年=设置年 的变量引用进 id 表 (左值/右值各一条)。变量引用表按引用追加,不在串里。
  6. 此前担心的「绝对偏移指针失效」未出现:串前除 @4/@82 外逐字节一致; 实测出现过的 bc 02/86 03 u16 在两版中位置与值均未变——要么不是绝对指针, 要么指向未移动区域。MCGS 自己的写入器就靠以上 6 处改动完成变长。

连带解锁:

  • 脚本文本变长写入(按钮 button_scripts[] 的 replace 不再受等长限制)——✅ 已实现且组态三关通过(2026-11-13,V0.8.15)
  • 真脚本里的多位数赋值(=50)——同机制自动解锁(旧卡点系「操作属性误读成脚本」所致)
  • 控件改绑变量名变长(控件节区 0x5025):✅ 已实现且组态三关通过(V0.8.16,2026-11-13,C4 取样 §5.15);0x503C/0x5028 同机制待各自取样

写入器实现清单(照 MCGS 手笔复刻):改串(重打包 strfmt 串)→ 更新 @4 节区长 → 更新 @82 计数字节 → 更新串后 u32 字符计数 → 尾部追加变量 id 条目(每引用一条) → 其余内容原样后移。已实现(V0.8.15,2026-11-13),verify + 组态三关通过。

5.15 控件改绑变量名变长(C4 取样定案,2026-11-13)

样本:G 系列样例「参数设置」控件51 输入框(0x5025),绑定变量 设置时 (id=159,dtype=2,3 字)→ 组态里改名 设置时钟小时(6 字)另存。 改前节区声明长 425 → 改后 431(Δ+6 = +3 字符 × 2 字节)。

MCGS 手笔的字节级定案(改前/改后逐字节对拍):

  1. 变量名是节区里的单个 strfmt 串,原偏移原地变长:串头 @214 FF FE FF <字符数>(03 → 06),串体 @218 UTF16LE(6B → 12B), 其后全部内容整体后移 +6B。
  2. 节区声明长度字段 @4(u16):425 → 431(+6)。
  3. 绑定点 [u32 id][u32 dtype](@206,布局 A = 变量名前 8 字节)不动: id 仍 159、dtype 仍 2 —— 改名保 id,只名字串变长。
  4. 无计数字节、无 u32 字符计数、无尾部变量 id 条目: 比 0x5027 按钮脚本(「加行」场景要动 @82 计数字节 + 尾部 id 条目)更简。 尾部 207B 改前/改后逐字节一致,仅整体后移。
  5. 无绝对偏移失效 —— 与 §5.14 同结论。

全局引用面(MCGS 自动更新):这次改名同时更新了 2 处控件节区引用 ——

  • 0x5025 绑定(控件51,本次取样目标)
  • 0x5027 按钮脚本(!SetTime(…设置时…) 参数,同样原地变长,与 §5.14 同机制) 变量表 ObjData 随之改名(209 条不变、纯改名),旧名无残留。

对写入器的含义(rebind_control_variable 变长版):

  • 改名场景(同变量 old→new 名):只动 3 处 —— 节区声明长 @4 + strfmt 串头 字符数 + 串体原地变长(尾部整体后移);绑定 id/dtype 不动。
  • 改绑场景(换成另一个变量):另需把绑定点 [u32 id][u32 dtype] 改成目标变量 的 id/dtype(id 由 ObjData 查得)。
  • 待核对:0x5027 脚本串后紧邻 u32(值 57)在 C1「加行」场景随字符差变动 (57→67)、C4「改名」场景不动(57→57)—— 两者触发条件不一致,0x5027 支持 改名场景前需核对语义(疑与「新增变量引用/行数」相关而非纯字符数);不影响 0x5025。

状态:机制已定案,写入器已实现(V0.8.16)且组态三关通过(2026-11-13)——rebind_control_variable 变长版 + test_rebind.py 字节级自测(C4 复现 + 逆变换 + 等长回归 + 拒绝项 13 项全过);端到端 build→verify 全绿(V1–V12)、官方样例 scan 18/18。0x503C/0x5028 同机制预期适用,各自需取样 + 三关。


6. 红线与护栏

已有护栏(构建期强制):

护栏 拦什么
kind 级护栏 没验证过的字段(矩形 / 变长文本 / 绑定 / 事件)不允许改
值域护栏 开关型变量只能写 0/1
等长护栏 控件名长度不一致 → 拒绝(改长度 MCGS 读不出控件);变量名/脚本片段变长已解锁(§5.14 按钮脚本 / §5.15 控件改绑)
变长引用护栏 按钮脚本变长新增的变量引用必须是工程变量或已知内置参数 → 否则拒绝(compiled-op 条目算不出)
变量体检 脚本引用的变量不在工程里 → 拒绝(防「未知对象」)
跨对象引用体检(步骤 5f) 脚本引用的窗口/控件在目标工程不存在 → 拒绝并给三条走法
控件名占用 同位数空间用尽 → 拒绝并给两条走法
往返字节精确 解析 → 重打包必须字节相同,否则编辑能力已破坏
字体合法性 写组态不认的字体名 → check 阶段拦下

软约束(靠人守):

  1. 变量 / 图片名不能以数字开头。
  2. 0x5025 图片引用名 ≤3 字。
  3. 表达式 / 引用角色串不可当显示文本替换(除非显式 force)。
  4. 已知限制必须落成构建期护栏 —— 只写文档不算护栏 (Phase 10 交付坏工程就是这个教训)。
  5. 只改工程副本;生成后务必回组态软件验收。

7. 工作流程规矩

7.1 组态验收协议(详见 TESTING.md §4.2)

  1. 三关:打开(不报损坏)→ 编译 → 仿真下载。任一关失败即停。
  2. 另存回读:验收件在组态里另存,Agent 对拍 —— 12 张表逐行逐字段一致 = 零改写(字节层正确性的最高背书)。
  3. 失败件勿删:另存件交回(MCGS 的规范化输出是反推依据); 损坏本体归档为反面 ground truth。
  4. 交付到组态未锁过的新路径:组态打开工程会锁 .ldb, 期间工具链覆盖同名文件后,组态再另存会用内存里的旧状态写回,把新产物冲掉。 交付时说明文件名与校验值。
  5. 反馈要带原文:报错附控件名 + 错误描述原文/截图。 同一现象可能有多条根因。

7.2 改动流程(完整版见 docs/扩展指引.md)

改代码 → py_compile → 相关自测 → 6 示例 → scan 批量回归
       → 更新 SPEC/TESTING/CHANGELOG/能力矩阵 → commit → push → 克隆验证

五道验证关卡的完整清单见 docs/验证方法.md。

  • test_contract.py 会校验 SPEC.md 必须提及 schema 里的每个字段 —— 加了 spec 字段就必须在 SPEC.md 补一行。
  • test_contract.py 同时校验 TESTING.md §4.1 必须覆盖每条 V 规则 —— 加验证规则要同步立档。
  • 提交信息沿用项目约定:[agent:workbuddy] <主题> + 正文写清「做了什么 / 为什么 / 怎么验的」。
  • catalog.local.json / templates.local.json / *.ldb 不进仓库。

7.3 逆向取证纪律

  • 先有样本再固化:没有组态另存件佐证的行为,不写进实现。
  • 变长路径宁缺勿滥:未实测的变长写入宁可拒绝并说明,不要半吊子。
  • 宁可漏检不误伤:静态规则若会误伤原生工程,宁可撤回, 把防线放到有精确上下文的地方(build 阶段)。
  • 控件内部结构不能用固定偏移静态判定(id=0 是「未绑定」不是「悬空」)。
  • 真实工程优先:改字节层必跑 scan 全量(30 个真实工程 + 9 个官方样例)。

8. 环境与依赖

8.1 依赖

包 用途 必需性
access_parser 纯 Python 读 Jet DB 必需
jsonschema schema 强校验 可选(缺席时自动降级)
unicorn + pefile 条件脚本字节码(Unicorn 仿真原厂编辑器) 仅 script 子命令
fastapi + uvicorn 本地 HTTP API 仅 serve
httpx2 FastAPI TestClient 仅 test_serve_v2

8.2 本机环境的坑(踩过就别再踩)

  • pip 大二进制包经本机 MITM 代理会 stall → 用阿里云镜像: pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com <包名>
  • 写回必须 32 位 PowerShell(SYSWOW64)+ .NET OleDb;64 位 Python 看不到 Jet 驱动。
  • 组态软件路径:D:/McgsPro(Program/ 下有原厂二进制, Samples/ 下有 9 套官方模板 + G/E/N/4.3寸样例工程)。
  • 原厂二进制按 SHA256 钉死(换版本即拒绝执行,不猜)—— 见 THIRD_PARTY.md。
  • 原厂代码生成器是 Unicorn 纯内存仿真,不向 Windows 加载任何 DLL、不启动任何进程。
  • cmd.exe 在本沙箱被拦截;Add-Type 与 COM 实例化被安全策略拦。
  • PyPI 大 wheel 与 GitHub Release 二进制在本沙箱可能下不动; 能联网的机器上再补装。
  • 本机 .NET SDK 8.0.401/8.0.425/9.0.306 可用 —— 原生桥的 C# 编译在本机就能做(V0.8.0 实测推翻 Phase 6 的「沙箱里不行」: 安全策略拦的是 Add-Type(编译并加载程序集),直接调编译器当子进程不被拦)。
  • PowerShell 7 是 Microsoft Store 版(7.6.9),路径在 %LOCALAPPDATA%\Microsoft\WindowsApps\pwsh.exe(应用别名)—— 枚举 Program Files 那三个固定路径会误报「未安装」(V0.8.1 已修)。
  • 上游会把自测宿主 exe 写进组态安装目录 (D:\McgsPro\Program\OwnMessageLoopHost.exe)—— 手工跑上游脚本后记得清掉。
  • 本仓库 git 的 core.autocrlf 行为已由 .gitattributes 根治 (仓库内一律 LF,避免「已修改但 diff 为空」的幽灵状态)。

9. 下一步该做什么

9.1 立刻可做(不等任何人)

  1. 接入真实 Pro(手动步骤,需主人在组态软件里打开一个工程) —— 见 docs/原生桥部署规程.md(原部署清单已并入其 §12)。

    部署准备阶段已成功跑通 6 步(V0.8.5,native deploy,2026-11-07 实测 ~16 分钟,稀疏目录 + 精简扫描): runtime / bootstrap / engineering 已 staged。主索引 abi-target-profile-index.json 0.24MB, 完整诊断在 abi-target-profile-supplement.json(18.47MB,C# 端不读)。 产物根目录:F:\Studio\Code\MCGS_File\原生桥任务-sparse-v3\(目录已清理, 被 352c / 352d 部署取代;runtime runtime-20261107193635407 / bootstrap bootstrap-20261107193635407)。 ✅ 该目录的桥已于 2026-11-07 20:49 成功 connect 接入 Pro(PID 2432 / UI 线程 15648,管理员 RunAs 提权)。

    ✅ 首次新机器接入验收已完成(2026-11-07 20:49,PID 2432 / UI 线程 15648):

    • McgsHotAttach.exe --plan(只读)与 --connect(高风险注入)均由管理员 RunAs 执行 (Pro 以 High 完整性运行,沙箱 Medium 直接跑会「拒绝访问」—— 对应 upstream README 第 68 行的 High/HKLM 路径)。
    • 权限坑(必记):McgsHotAttach.exe 必须 Start-Process -Verb RunAs 提权运行;否则 OpenProcessToken/MainModule 被 Windows 完整性机制拦截,报「拒绝访问」。
    • --connect 结果落盘 runtime/hot-attach/native-2432.bin:hr=0x0, type=3, value=0, OK=True (自有 COM 已注册、WH_GETMESSAGE hook 已装、引擎在 UI 线程加载完成并返回 OwnPing)。
    • native postdeploy 验收通过:ping 探活 ui_thread_id=15648 匹配、host_bits=32、 native_business_method_called=false(未碰厂商业务)、project_writes_quarantined=true(写隔离)、 op 清单 34 只读 / 19 写工程 / 4 工程编辑;native-read-tree 等在线读 op 在 slim 目录部署下被引擎按「profile 未归类为 abi → 该 op 隔离」规则关闭、不可用(实测结论,非乐观描述),故后续在线内存态对拍未跑,详见 §9.1.1。
    • 后续(可选):若 Pro 当前打开了具体工程,提供其 .mcp 路径后重跑 postdeploy --project <工程.mcp> 即可补全「读内存态 + 与离线层对拍」(本次因未指定 --project 跳过)。

    ✅ 已知风险已修复(V0.8.5):稀疏目录下原 201 个 partial profile 的完整诊断(撑大索引至 16.06MB) 已移入 abi-target-profile-supplement.json,主索引降到 0.24MB。C# 端对 details/entry_statuses 不强依赖 (见 §5.11 第三条坑)。首次 connect 后仍建议立即跑 postdeploy 观察运行时告警;若具体 profile 报错,再补定位对应签名。

  2. 拿真实项目跑一把 —— 推荐 SVO-858 或多路温控, 零母版 + 预览 + 体检 + scan 四条链一起上,验证在真实业务里顺手不顺手。

  3. 补验证器规则 —— 每个都先在官方样例上试准,误伤就撤回。

9.1.1 真实工程离线体检(2026-11-07 泵房监控系统)

  • 对象:E:\xwechat_files\...\泵房监控系统.MCP_McgsPro 3.5.1.6963_0.mcp(实测解析为 McgsPro 3.5.1.7267,1024×600 TPC)。
  • verify(V1–V12):30/30 全 PASS。V12 曾报 18 个未知 kind 0x5026,经字节级取证确认为 MCGS「流动块」管道流动动画构件(见 V0.8.6 / kinds.py 的 UNDOCUMENTED_KINDS),重跑后 V12 PASS、总体 PASS。
  • 结构:8 窗口(主界面 46 控件为核心)、14 变量(泵组1–4/水箱1–2/流动块等内存变量)、0 设备通道(TPC-only 组态/演示工程,未接 PLC)、3 策略触发器。
  • textfit:98 处轻微控件交叠(6–10px×19px,多为相邻控件共用 1px 边线),非致命,建议 Pro 内目视确认。
  • 在线读树通道真相(修正 §9.1 原乐观描述):本机部署用稀疏目录(116/5874 签名),native-read-tree / engineering-project-lifecycle-read 等在线读 op 被引擎按「profile 未归类为 abi → 该 op 隔离」规则关闭;postdeploy --project 的在线内存态对拍未跑,且无法靠桥自动发现打开工程的 .mcp 路径。离线层(mcgs.py verify/export/kinds/inspect/textfit)全功能不受影响,秒级出结果。
  • 产物落盘(工作区,未入库):F:\Studio\10 Projects\MCGS_File_Create\体检\泵房监控系统_20261107\(目录已清理,结论保留在本节)。

9.1.2 北极星推进:ScaffoldSpec 契约固化 + 领域示例 + Agent 接入契约(2026-11-08)

用户终态:任何 AI Agent 用「需求关键词」或「图片模板」即可快速生成 MCGS 画面 + 驱动 + 策略(画面含对应控件)。

关键发现(已核实):mcgs-tools 生成基底早已具备——build(按 spec 生成工程)/device(驱动通道绑定)/script(策略脚本字节码)/catalog+templates+mother_source(控件母版库)/serve(无头 HTTP API)/builder(逐字节恒等重建)。北极星 = 在 build 管线外包「NL/图片 → spec.json」智能体 + 固化 spec 契约 + 积累工控母版库。

本次固化交付:

  • SPEC.md 已是完整契约文档(总流程/角色系统/安全护栏/kind 表/零母版路线/能力边界/AI 写 spec 清单);scaffold.schema.json(jsonschema Draft 7)做强校验。
  • 新增 AGENT_CONTRACT.md:把「任何 AI Agent 接入」固化成稳定接口——契约边界(稳定/可变)、标准闭环(templates→export→inspect→写 spec→check→build→verify)、两类需求入口(NL/图片)、字段速查、发现类命令、硬约束、本机已验证可跑组合、错误处理闭环、示例索引、与北极星关系。
  • 新增 3 份工控领域示例(examples/10–12,均 check 通过):
    • 10_泵房监控系统.json:旗舰,画面(零母版原语 18 控件) + 驱动(ModbusTCP 改名泵房PLC,237 通道同名绑定/前缀 PUMP_) + 策略(strategy_edits 1 处) 一体。已端到端 build+verify 实测 PASS(out/泵房监控系统_生成.mcp,1138KB,V1–V12 全 PASS),离线预览 out/预览_泵房/02_首页.png 可见植入的泵房面板。
    • 11_多路温控.json:batch[] 批量参数化建 4 个同构温区页(每区 {c} 变量)+ recipes[] 配方改值演示。
    • 12_供水加压.json:device_bindings + button_actions + window_refs + strategy_edits 综合演示(名字为示意,需按模板 inspect 确认)。
  • examples/README.md 补领域示例章节 + 本机实测模板/供体配对(含「本机供体不含 McgsIoT、工控用 ModbusTCP」关键提醒)。

驱动名重要提醒:本机供体 D:/McgsPro/Work/TPC上传工程.mcp 含 ModbusTCP/CODESYS_以太网_自由标签/通用TCP/IP父设备,不含 McgsIoT(SPEC.md 提到的含 McgsIoT 的 TPC上传工程是另一台机器的版本)。工控现场最常用 ModbusTCP,示例已统一改用。

待办 / 后续里程碑(北极星路线):

  1. ✅ NL→spec 智能体(吃需求关键词/自由抽取吐合法 spec,调 build 生成)—— 已落地(2026-11-08,见 §9.1.4),最快打通「任何 Agent 生成画面」。
  2. ✅ 图片模板→spec(截图/模板 → 布局 spec)—— 已落地(2026-11-08,见 §9.1.5),北极星第二阶段差异化能力打通。
  3. 工控母版库积累(泵房/供水/温控典型场景母版,靠 catalog add 持续攒)。
  4. 在线读通道(全量 ABI 目录 deploy + RunAs 注入)用于生成物回读对拍/反推 spec——属验证支线,非关键路径(见 §9.1 全量 deploy 状态)。

9.1.3 北极星推进:mcgs-mcp server(任何 AI Agent 程序化调用层)

把 mcgs-tools 包成 MCP server(mcgs-tools/mcp_server.py,FastMCP / stdio),与 mcgs-file-create Skill 互补不冲突:

  • Skill = 知识/契约层(让 Agent 知道「怎么写合法 spec、走什么流程」);
  • MCP server = 调用层(让 Agent 用 tool schema 直接调,输入/输出结构化)。

暴露的 17 个 tool:mcgs_health / check / build / verify / inspect / export / preview / textfit / templates / scan / kinds / doctor / buttons / native_status / compile_intent / image_to_spec / template_probe。覆盖完整生成闭环;compile_intent 即 NL→spec 智能体的程序化入口(见 §9.1.4),image_to_spec 即图片→spec 智能体的程序化入口(见 §9.1.5);native call 写操作刻意不暴露(与 serve 安全姿态一致),mcgs_native_status 仅只读读盘探查。(tool 数由 test_contract 护栏锁定,加 tool 必须同步此处与 SKILL/README)

关键设计:

  • 内部统一 subprocess 调 mcgs.py CLI,复用经「打开/编译/仿真下载」三关验收的管线,行为与离线工具链一致。
  • 双解释器隔离:MCGS_TOOL_DIR(定位 mcgs.py)+ MCGS_PYTHON(跑 mcgs.py 的解释器,默认 sys.executable)。当 mcp 与 mcgs-tools 依赖不在同一 python 时,用 MCGS_PYTHON 指向装有 mcgs-tools 依赖的那个即可。
  • 生成侧完全离线,无需 MCGS Pro 运行。

已实测:pip install mcp 后,mcp.list_tools() 注册 12 个工具;mcgs_templates() 经 MCGS_PYTHON 路由真实返回模板列表,证明 subprocess 接线正确。

接线:MCP_SERVER.md 含 WorkBuddy(~/.workbuddy/mcp.json)/Claude Desktop/VS Code 的 mcp.json 片段。WorkBuddy 配完需在连接器管理页点「信任」。

9.1.4 ✅ NL→spec 智能体(已落地,2026-11-08):自然语言意图 → 合法 ScaffoldSpec

定位:北极星「任何 AI Agent 用需求关键词/图片模板快速生成 MCGS 画面+驱动+策略」的核心落点,已实测闭环。

分层设计(把易错活交给确定性代码):

  1. AI 只抽 IntentSpec(字段少、语义高,是 LLM 该填的那一层)—— 契约见 mcgslib/intent.schema.json;
  2. 确定性编译器 mcgslib/intent.py:compile_intent() 把 IntentSpec 展开成完整 ScaffoldSpec——自动布局控件(标题栏矩形+标签、监控量/开关 2 列网格、按钮底部一排绿·红)、协议→驱动映射(modbus_tcp→ModbusTCP、modbus_rtu→ModbusRTU、opcua→OPCUA、codesys→CODESYS_以太网_自由标签、tcp_ip→通用TCP/IP父设备)、变量类型推断补建(monitors→number,switches/按钮 set→switch);
  3. 落入既有 check → build → verify 闭环,产物 100% 过 scaffold.schema.json 契约。

两条入口:

  • 关键词模板直出(工业范式固化):compile-intent --use-template 泵房 --param scale=4 -o spec.json。模板库 mcgslib/intent_templates.py 含 泵房/泵站、供水加压/恒压供水、多路温控/温控 三类(别名已收录)。
  • 自由抽取:Agent 把需求抽成 {"protocol","screens":[{"monitors","switches","buttons"}]} 意图 JSON,compile-intent --intent intent.json -o spec.json。

程序化接入(3 条路,面向「任何 AI Agent」):

  • CLI:mcgs.py compile-intent ...(详见 skills/mcgs-file-create/SKILL.md「NL→spec 智能体」专节);
  • MCP tool:mcgs_compile_intent(intent, build=False, template="", donor="", out=""),build=True 时一步到位 compile→build→verify;
  • Python:from mcgslib import intent; intent.compile_intent(spec_dict)。

实测:关键词「泵房」scale=3 → compile→check PASS(6 变量/16 控件)→ build→verify V1–V12 全 PASS,产物 out/泵房_NL生成.mcp 含 16 自动布局控件 + ModbusTCP 237 通道同名绑定(新建变量 150);自由抽取「冷却塔」意图 → compile→check PASS(3 变量/10 控件)。图片→spec 第二阶段差异化能力也已落地(2026-11-08,见 §9.1.5)。

9.1.5 ✅ 图片→spec 智能体(已落地,2026-11-08):截图/模板 → 合法 ScaffoldSpec

定位:北极星「任何 AI Agent 用需求关键词或图片模板快速生成 MCGS 画面+驱动+策略」的第二落点(与 NL→spec 同内核),已实测闭环。

核心设计(把易错活交给确定性代码):

  1. 视觉只抽语义清单(ImageIntent:标题、监控量、开关、按钮、协议,可选像素 bounds)—— 契约见 mcgslib/image_intent.schema.json;
  2. 确定性编译器 mcgslib/image_intent.py:image_to_intent() 把 ImageIntent 展开成完整 ScaffoldSpec——
    • auto(默认)路线收口成 IntentSpec 复用 compile_intent 的自动网格布局(视觉对 box 精度不敏感);
    • preserve 路线按识别到的 bounds 直接落 from_primitive(需较准框);
  3. 落入既有 check → build → verify 闭环,产物 100% 过 scaffold.schema.json 契约。

视觉后端(工具不内置视觉模型):extract_image_intent() 支持 manual(图片同名 .json 侧车 / --layout-json)与 vision(OpenAI 兼容接口,提示词 _VISION_PROMPT 已固化);Agent 也可自己看图产 ImageIntent 再走 CLI。

程序化接入(3 条路,面向「任何 AI Agent」):

  • CLI:mcgs.py image-to-spec --layout-json 意图.json -o spec.json(详见 skills/mcgs-file-create/SKILL.md「图片→spec 智能体」专节);
  • MCP tool:mcgs_image_to_spec(image_intent, build=False, template="", donor="", out=""),build=True 时一步到位 image→spec→build→verify;
  • Python:from mcgslib import image_intent; image_intent.image_to_intent(intent_dict)。

实测:泵房首页截图(out/预览_泵房/02_首页.png)→ image-to-spec 生成 16 控件 spec → build → verify V1–V12 全 PASS,产物 out/泵房_图片生成.mcp 含 ModbusTCP 改名 泵房PLC + 237 通道绑定(新建变量 156);auto / preserve 两种 layout_policy 均 check PASS。

后续增强(2026-11-08 V0.8.9):接入 F:/Studio/70-Media/Hmi_Sample/ 两份威纶通规范 MD(威纶通新工业UI开发范式总结.md / 威纶通UI配色与布局规范对比.md)+ _pages/ 19 张真实 HMI 截图作为工业 UI 参考语料(2026-11-12 核:该目录本机已不存在,语料路径仍以 mcgslib/image_intent.py 的 UI_REFERENCE 为准,需时请重新提供)——

  • _VISION_PROMPT 已注入工业 UI 范式(顶栏/导航/卡片栅格、八类标准页、语义色、数值三要素),视觉模型可输出 theme(dark/light)、page_type(8 类)、控件 semantic;
  • mcgslib/intent.py 新增 PALETTES(industrial/dark/light 三套,色值取自规范文档像素级取色:dark 头板 #182028、light 头板 #001848、启动绿 #22c55e/#16a34a、停止红 #dc2626),ImageIntent 的 theme/palette 字段透传,生成屏按主题上色;
  • UI_REFERENCE 常量登记语料路径,SKILL.md / AGENT_CONTRACT.md / examples/README 同步说明「把规范 MD 作上下文喂视觉模型可显著提升抽取质量」。

9.1.6 ✅ 原生桥在线闭环 + 关键 ABI 修复 + 真实编辑落盘(2026-11-09,V0.8.10)

这一节把原生桥从「读得通」推进到「改得动 + 改得准」,并修掉一个把大片在线能力隔离掉的真 bug。

① 在线读已闭环(承接 352b)

engineering-project-lifecycle-read → ok:true;postdeploy 退出码 0,结论「桥可用,对拍一致」, 工程字节哈希 2abc36dd…93e8 引擎读 == 离线读,root_modified=0。 在线页面清单 15 个(page-create 读入口)与离线窗口 id 与名称逐一对应(15/15)。

② 修复:abi_binding.py 漏搬「内容等价缓存」→ 9 个 kind 从 ABI 隔离中解锁

根因:TargetBinding 走 --trust-resolved 预置结果分支时会重建 self.result, 只搬了 rva_maps/functions/types/proofs/gaps/capabilities/adaptation_policy/local_actual_module_paths, 唯独漏掉 content_equivalence_cache。于是 abi_locator.write_resolved_profiles 里那条 「内容等价逃生通道」(按 reference_ordinal 收敛别名导出)永远不触发。

MFC110u.DLL 只有序号导出、没有任何名字导出(nnames=0 / naddr=14304), 同一函数体被 2–7 个别名序号指向 → CStringDtor/ordinal 等 4 条判为未解析 → 引擎源码守卫未替换 → 运行期 Native function field was not uniquely located: CStringDtor/ordinal → 把页面/策略/设备整片在线能力隔离掉。

修法(证据优先):新增 abi_binding.content_equivalence(catalog, modules), 只用本机实际文件的 SHA256 与 catalog 参考 SHA256 逐字节比对重算等价清单, 不采信预置结果里的声明(那份声明可能来自别的机器或已被改动)。

实测:

  • 本机 17 个参考模块 15 个与作者参考二进制逐字节一致(仅 mcgsiot.ui 不同);
  • 全量模拟:catalog 81/81 条 export 记录由 UNRESOLVED → resolved,0 残留;
  • 重跑 write_resolved_profiles:未完全 resolved 的 profile 19 → 5, strategy-write-guard-profile.json 由 partial → resolved;
  • 重新部署(原生桥任务-352c)后实测 kind 矩阵:page-create、device-catalog 由 BLOCKED → AVAILABLE, page-rename/size/delete/referenced-rename、strategy-rename/create-user/delete 由「ABI 隔离」降级为「只差 target」。剩余 BLOCKED 3 个:control-layer/group/ungroup (另一类 code_guards/0,与本修复无关);剩余未收敛 profile 5 个均为设备驱动专有符号。

③ 真实编辑落盘(engineering-edit-batch)已验证 —— T3 ✅

对 D:\McgsPro\Samples\G系列样例演示工程1024x600.mcp 的首页控件1(CDrawLabel)做 control-geometry 位移 6px:

阶段 结果
① commit=false(只改内存态) ok:true、status=native-edits-completed-persistence-deferred、root_save_called:false;在线回读 rectangle [366,24,663,66] → [366,30,663,72]、page_modified=1;磁盘 SHA256 未变(写隔离有效)
② commit=true + save_scope.root_save=true(落盘) ok:true、status=native-batch-completed-pending-consolidated-acceptance、native_save_return_verified=True、root_modified=0;磁盘 2abc36dd… → 055cbc6b…
③ 字节级对拍(mcgs.py diff) 首页 468 个 item 仅 2 处 4 字节差异:item#6 位[22] 18 00→1e 00(Y 24→30,正是我改的 6px)、item#458 位[17] cf 15→e0 15(MCGS 内部索引同步);其余 466 项逐字节一致,字符串差异 0 条 → 无任何附带改写
④ 还原 用字节级备份覆盖回原件 → SHA256 完全回到 2abc36dd…;最终离线条 diff 与原始备份零差异

④ 闭合/重开全流程(engineering-project-close-reopen-original)已验证 —— T4 ✅

ok:true、lifecycle_completed:true、close_confirmed_empty:true(关闭后 root 全局归零)、 open_confirmed_same_project:true、close/open entered+returned 全 True、 native_outcome_unknown=false(执行状态确定,不是未知)、state_after.root_modified=0; 闭合快照落盘 engineering/closed-copy-t4.mcp。

⑤ 本轮踩到的坑(务必记)

  1. prepare-close-reopen 的 permit 路径要求工程文件位于「任务根目录」内 (batch.owned_file 校验 TASK);厂商样例在 D:\McgsPro\Samples\ → 必然报 Permit/output must stay in the owned task directory。对任务根外的工程必须用 direct 模式 (close-reopen --project <工程>,默认路径本就「不需要 permit」)。
  2. close-reopen 的前提是「磁盘 == 内存态 且 root 未修改」(Need(root_modified==0 && Hash(project)==state.project_sha256))。 若先在外部覆盖磁盘再让它重开,Pro 会直接退出(本轮实测踩到)。还原工程必须先让 Pro 重开,再覆盖磁盘, 或覆盖后重新加载工程 —— 顺序反了就会崩。
  3. close-reopen 回执延迟可达 4 分钟以上(本轮实测 ~4min),客户端 --timeout 240 会先报 「No correlated response; execution is unknown, do not resubmit」。此时不可重发 —— 回执最终会落进 <runtime>/outbox/<request_id>.json,应去 outbox 等它。
  4. close-reopen 重开后 MCGS 会自己重写文件(original_open_changed_physical_sha=True), 改的是 System 表等运行时数据,窗口 BLOB 不变。因此「还原」的判据应是 窗口级 diff 归零,而不是整文件 SHA256 相等。
  5. 在线读分类口径:ok=true 不代表动作成功 —— 动作可能落在 unsupported_actions 里。 判定「某个 kind 可用」必须看它是否出现在 action_preimages。
  6. lifecycle-read 的 --closed-copy 目标文件不能已存在(_working_new 校验), 引擎也不会真的写出它(真正落盘由 close-reopen 完成)。

⑥ 当前在线能力实测快照(3.5.2.12210 + 352c 桥)

类别 数量 说明
AVAILABLE 6 page-create / device-catalog / picture-catalog / language-catalog / language-text-batch / root-flush
NEED_TARGET 45 ABI 已通,只差合法 page_id / module_id / control_path
BLOCKED 3 control-layer / control-group / control-ungroup(code_guards/0,另一类定位问题)

复现脚本与规格:F:\Studio\Code\MCGS_File\原生桥任务-352c\specs\(specs/ 已清理); kind 矩阵结果 原生桥任务-352c\specs-kindmatrix-result.json; 部署日志 F:\Studio\Code\MCGS_File\deploy-352c.log(已清理)。 Pro 进程已随本轮收尾退出(见坑 2),继续测需重新启动 Pro 并重新提权注入。

9.1.7 ✅ 第二类隔离根因修复 + 副本工程属性编辑实测(2026-11-09,V0.8.11)

接着 §9.1.6 的两个遗留项继续推进:解开剩余 3 个 code_guards/0 阻塞项,并在副本工程上复测落盘链路。

① code_guards/0 不是定位失败,是 profile 身份标签错配(真 bug,已修)

FactoryBytes() 是「放置工厂」与「绘图命令」两个 profile 共用的字节守卫校验函数, 却把期望的 profile 身份写死成 placement-factory v3:

// NativeCurrentTemplateControlFactories.cs
const string FactoryRelative=".../native-control-placement-factory-abi-profile.v3.json";
static void FactoryBytes(NativeEngine engine,Dictionary<string,object> row) {
   NativeAbiTargetProfiles.CheckEntry(row,"factory code guard",FactoryRelative);   // ← 硬编码

而 NativePreparedDrawingCommands.cs 拿自己的 225 条 code_guards 来调它。 CheckEntry 要求 row._abi_resolution.profile == profile → 两个身份串不同 → 必然不等 → 抛异常。

错误信息极具误导性:显示 /code_guards/0(225 条里第 0 行的 entry 恰好是这个指针), affected_profile 还报成 placement-factory —— 仿佛「工厂守卫坏了」, 实际坏的是「用 A 的身份去验 B 的行」。排查这类问题要看抛出点的第 3 个参数,别信 affected_profile。

修法(不放宽校验):FactoryBytes 增加带 profile 参数的重载(原两参版行为不变), NativePreparedDrawingCommands 新增 DrawingCommandRelative 常量并传入自己的身份。

实测(任务根 原生桥任务-352f,scope b8884e53…5e50):

kind 修复前 修复后
control-layer BLOCKED_ABI:not uniquely located: /code_guards/0 ABI 障碍解除,只差合法 page_id
control-group 同上 同上
control-ungroup 同上 同上

② 根治:源码地址目录的字符索引坐标与行尾绑死(既存雷)

abi-adapter/catalogs/source-addresses.json 用字符索引(read_bytes().decode('utf-8-sig') 后的 str 切片)记录 535 条字面量位置;CRLF 与 LF 的字符索引不同。 工作区 delivery/source/sources/*.cs 是 CRLF、git 内存 LF —— 一旦重新检出,535 条坐标整体偏移、补丁改错字面量,而仓库不显示任何差异。

修法:.gitattributes 固定该目录 CRLF 检出 + 把 5 个原本 LF 的源文件统一为 CRLF + 刷新两处指纹。 最终自检:535/535 坐标正确、163/163 sha 一致。

改 C# 源码后必须同步三处(部署会在 Selected staged C# changed 处拒绝): ① delivery/source/source-and-dependency-manifest.json → sources[].sha256 ② abi-adapter/catalogs/source-addresses.json → entries[].source_sha256 ③ 同 entries[] 的 start/end(字符索引;定位必须用 read_bytes().decode('utf-8-sig'), 不能用 read_text() —— 它做通用换行转换,会把 CRLF 当 LF,坐标全错)。

③ 副本工程上的属性编辑实测(T3 复测,C:\Users\linji\Desktop\261109.MCP)

  • 颜色是 COLORREF(0x00BBGGRR):原生 setter 把 255 规范化成 0xFF0000FF(补 alpha), 所以 after.value 必须传完整 COLORREF(白 = 4294967295), 否则后像比对失败(Typed property target postimage or untouched component values differ.)。
  • 字节级对拍:首页 468 个 item 仅 2 处 4 字节差异 (item#10 颜色 ff ff ff ff→ff 00 00 00 + item#458 MCGS 内部索引),其余零差异、字符串差异 0 条。
  • ⚠️ commit=false 并不保证磁盘零变化 —— 页面级 saveData 仍会落盘 (page_save_data_called=true)。「只改内存态」要选不触发页面 flush 的 kind (control-geometry 实测磁盘零变化)。
  • 还原方式:用编辑 API 一进一出(改绿 → 改白 + commit=true 落盘), 全程内存态与磁盘一致,最终窗口级 diff 只剩 MCGS 自己重排的 1 处索引(e0 15→e3 15)。

9.1.8 ✅ target 字典补齐 + 安全试改规程 + drawing command 首次真实执行(2026-11-09,V0.8.12)

① target 字典已补齐(新增 docs/原生桥target字典.md)

逐 kind 独立 inspect/execute 实测(副本 C:\Users\linji\Desktop\261109.MCP):

类别 target 实测状态
页面类 page-size / page-view-open / page-document-properties {page_id, page_name} ✅ AVAILABLE
control-geometry {page_id, page_name, class, control_name}(裸类名) ✅ AVAILABLE
control-properties {page_id, page_name, rtti, control_name}(要 RTTI) ✅ AVAILABLE
control-layer {page_id, page_name, controls:[{class, control_name}]} ✅ AVAILABLE(限当前打开页)
data-edit / data-rename {module_id:2, native_id, name} ✅ AVAILABLE
data-batch {module_id:2} ✅ AVAILABLE
recipe-cell / recipe-column {module_id:4, name, row_index, column_index} ✅ AVAILABLE
picture-replace / picture-create {module_id:11, name} ✅ AVAILABLE
device-rename {name:"设备1"} ✅ AVAILABLE
device-catalog / page-create / data-catalog 等读入口 {} ✅ AVAILABLE

module_id 映射:设备 1 / 数据 2 / 配方 4 / 图片 11(从 *-catalog 的 module_id 取)。

⚠️ class 与 rtti 两套语义别混用(同名控件的报错文案也不同): control-geometry/control-layer 走 Locate(裸类名,报 Template class/name is ambiguous…); control-properties 走 NativeControlPropertyEditing(要 RTTI,报 Top-level control name is not unique…)。

② drawing command 首次真实执行成功(不只是读通)

control-layer 打在当前打开页(控制中心 page_id=22,129 个顶层控件):

execute forward  → ok=true / apply.ok=true / write_attempted=true
读回顶层索引    → 1 → 2        (确实生效)
execute backward → 2 → 1       (完全还原)
磁盘 sha256      → 三次一致,全程零变化

关键约束:control-layer/control-group/control-ungroup 要求 目标页在 Pro 里正打开着(drawing view 已存在), 否则报 Original drawing commands require an already open drawing view; no project reopen is performed.

③ 安全试改规程(新增 docs/原生桥安全试改规程.md)

两条实测行为让「commit=false 就安全」成为误解:

  • 桥侧:commit=false + control-geometry ⇒ 磁盘零变化; 但 commit=false + control-properties ⇒ 仍落盘(页面级 saveData)。
  • Pro 侧:工程一旦变脏,Pro 会在某个不确定时刻自行保存一次(非周期性; 实测 16:01:28、16:19:29 各一次)—— 你什么都没做,文件也可能变了。

规程 = 副本 + 字节备份 → 只读探查 → commit=false 对称试改 → 核验磁盘零变化 → 读回确认生效 → 反向动作还原 → 监控 ≥5 分钟 → diff/verify 收尾。

④ 副本最终状态(已核验无残留)

试改 + 还原后:窗口级差异只剩 MCGS 自身重排的 z 序索引字段 (02 00 00 00→00 00 00 00),控件矩形/文本/属性零差异,离线 verify 总体 PASS。

9.1.9 ✅ 并行子代理产出汇总 + 下班交接(2026-11-09 18:00)

本轮用并行子代理推进:引擎请求走同一条队列(UI 线程串行), 真正的并行空间在离线分析与规格准备。三个子代理的产出全部沉淀如下。

① SubAgent A:control-layer/group/ungroup 规格离线考古(纯只读,零引擎请求)

target 顶层必填:page_id(int) / page_name(str) / controls(array)。 controls[] 每项的 page_id/page_name 由顶层值强制覆盖写入,故子项不应自带。

controls[] 元素的两种定位形态(NativeCurrentTemplateControlOperations.cs:76 Locate):

  • 形态 A:class(裸类名,如 CDrawLabel) + control_name
  • 形态 B:control_path(int[]) 附加 class + control_name (Match() 强制三者一致 → Control path resolved to another class/name.)
  • 唯一性检查是全 forest 范围(含嵌套子控件)→ 歧义报 Template class/name is ambiguous; supply its exact control_path.
  • ⚠️ 这条报错属 Locate 通道;control-properties 通道的歧义报错是 Top-level control name is not unique; use a native control_path.(rtti 语义,别混)

三个 kind 的差异:

kind controls[] 个数 额外约束
control-layer 恰好 1 无
control-group ≥1 目标不得有 CDrawCtrl 祖先类;子树不得含 External 类
control-ungroup 恰好 1 目标必须是 CDrawUnit 或 CDrawCell

after 结构:

  • control-layer:只有 direction ∈ {front,back,forward,backward}; 不需要 surviving_controls。索引基准 = 原生顶层 draw-list 顺序。
  • control-group / control-ungroup:必须 surviving_controls (每项必含 complete/name/rectangle/raw_DWORD60/properties, 且必须覆盖全部保留控件(含完全没碰的),数量不等即报 Expected survivors must cover every retained original control, including untouched controls.)
  • control-group 另需 group_rectangle(严格非退化);control-ungroup 不需要。

坐标系(关键):成组后子控件矩形用 0..10000 归一化坐标, 组容器用页面绝对坐标(源码注释 NativeCurrentTemplateControlOperations.cs:122-124

  • mcgslib/ui/离线预览.py:291 逆变换公式 + 实测页 4 控件41 矩形 = [0,0,10000,10000])。 control-group 实际创建的是 CDrawCell(type_id 0x5039),不是 CDrawUnit。

最短可验证路径:control-layer(after 最简)→ 已实测通过(见 §9.1.8)。

② SubAgent B:control-geometry 安全试改(独占副本第 6 页)

命题 结论
P1 ✅ commit=false + control-geometry ⇒ 磁盘字节零变化(8 次 execute 全程)
P2 ✅ 内存态逐次生效、4 次叠加、互不影响
P3 ✅ 反向编辑后 4 个控件全部回到原矩形
P4 ✅ 还原后 root_modified=1(「内存态改了但没落盘」状态确实存在)

⚠️ 最重要的一条安全认知:Pro 会在工程变脏后自行保存一次 —— 不是周期定时器, 是一次性事件,触发时机不确定(可能是 UI 空闲处理 / 页切换 / 任意交互)。 实测 16:01:28、16:19:29 各一次;16:01 那次之后 8 分钟内无第二次。 → 不能依赖「等一会就稳定」,只能靠「还原 + 监控 ≥5 分钟」双保险, 且监控期间不要对 Pro 做任何交互。 规程全文:docs/原生桥安全试改规程.md。

③ SubAgent C:可写能力探查(被用户中断,产出已回收)

4 次探查(wt_probeA/B/C/D,17:14–17:45)全部 ok=true,探出下列 kind 读层面可用:

kind before 结构
strategy-rename {abi_profile_sha256, kind, selected_block, copy_template, canonical_catalog, working_documents, trigger_native_rows, native_list_rows, next_strategy_id}
strategy-create-user {template_block}
reference-graph(全新 kind) {abi_profile_sha256, graph, pages, main_control, strategy_blocks, owners, module_models}
page-size {abi_profile_sha256, pages, owner, target_page}(4 个页面逐个验过)
recipe-cell {abi_profile_sha256, module_id, kind, module_known_catalog, module_dirty, record, cell_value}
picture-replace {abi_profile_sha256, kind, resource_catalog, reference_graph, root_modified, root_compile, native_image_registration_mode_raw_int32, target_picture, target_path}
data-rename {abi_profile_sha256, module_id, kind, module_known_catalog, module_dirty, record, incoming_reference_status}(遍历数十个变量逐个验过)

strategy-rename / strategy-create-user 此前卡在「给定关键字不在字典中」, 换用本轮探查得到的 target 后已通 —— 说明那不是 ABI 问题,是 target 字段问题。

④ 下班交接快照(2026-11-09 17:58 实测)

项 状态
MCGS Pro 已退出(17:57 核实)→ 352b / 352c / 352f 三条桥全部失效
桌面副本 261109.MCP sha256 5a350446…d961、size 4,546,560、mtime 15:52:28
↳ 为什么 mtime 回到 15:52 林先生关工程时,MCGS 用 .user.bak 把工程还原成 15:52 的干净版本,两份 .bak(.bak / .user.bak)随之被消耗(与 MEMORY 记的机制一致)→ 兜底备份消失,已重新补
↳ 窗口级校验 与最早原始备份(6ec3ea22…1942)逐字节一致(mcgs.py diff 无任何输出)→ 语义干净、无残留
↳ 离线校验 mcgs.py verify 总体 PASS(V1–V12 全过)
↳ 新基线备份 原生桥任务-352f/baseline/261109.CLEAN-20261109155228.MCP(5a350446…,与桌面副本逐字节相同)
厂商样例 G系列样例演示工程1024x600.mcp 2abc36dd…93e8,全程未动
仓库 V0.8.12 / 8026544 已推 GitCode

判据提醒:整文件哈希与最早备份不同不代表有污染 —— MCGS 会改写 System 表等运行时数据 (窗口 BLOB 不变)。判「是否被污染」必须看窗口级 diff。

⑤ 🚨 红线修正(覆盖本节 ③ 里「可尝试 group/ungroup」的说法)

第三轮 SubAgent 实测(15:43–15:48)已确证: control-group / control-ungroup 在真实工程上禁止执行 —— 回执 ok=false, 但命令已真实执行并落盘(automatic_rollback=false), 根因是后像校验走 NativeHistoryStoreProjection.AfterStoreSnapshot(), 它把历史存储的 common-state 换成指针,客户端在 JSON 里构造不出 → 后像必然不等。 ok=false ≠ 什么都没发生。 (该次踩坑把工程写坏,靠 MCGS 用户备份救回 → 详见 原生桥任务-352f/HANDOFF-20261109.md §7。)

⇒ 任何 drawing command 实验前,必须先在 baseline/ 留一份干净副本; MCGS 的 .user.bak 只在特定时机存在,关工程时会被消耗,不能当稳定恢复源。

⑥ 下一步清单(按建议顺序)

  1. 重启 Pro + 重新提权注入 352f(UAC 需人工点「是」)→ 复跑 postdeploy 确认对拍一致。 ⚠️ 桌面副本现在没有任何自动兜底(.bak 已消耗),开工前先 cp 一份到 baseline/。
  2. 补完 SubAgent C 未做完的写实测 ✅ [已闭环 2026-11-10 352d 本机实测]: page-size / data-rename / recipe-cell / picture-replace / control-layer backward / strategy-rename / strategy-create-user / strategy-delete / data-edit 共 9 个代表性写 kind 全绿 (对称还原 + 盘对拍;strategy-create-user 创建的 block15 已由 strategy-delete 删除还原, mcgs.py export 对拍备份 labels/scripts/triggers 全等)。 策略类规程:清单入口=inspect strategy-create target={};rename/delete 走 LifecyclePrepared(ABI cdbb14a7), after.reference_edges 恒必填全量边;preimage 保鲜期分钟级,inspect→execute 必须链式连发(详见 docs/原生桥安全试改规程.md 步骤 2 警示、docs/原生桥target字典.md §2.7)。 ⚠️ 覆盖面边界:9 kind ≠ 全集(compiled_kinds 几十个),其余 kind 按需续测。
  3. data-edit 零覆盖 ✅ 已闭环(并入上条,fwd/rev 对称成功、磁盘零变化)。
  4. control-group / control-ungroup:不在真工程上做(见 ⑤ 红线)。 如确需验证,只能用一次性副本,且验证后直接丢弃、绝不回流。
  5. data-group-create:需 expected_next_native_id(源码 NativeDataPrototypeEditing.v3.cs:27); 取值路径存在循环依赖(读它也要这个值),需另寻来源。
  6. 设备驱动类能力:需装对应驱动 DLL → 2026-11-11 已推翻:无需装 DLL,{module_id:1,path:["设备1"],driver_key:"monidevdrv"} 直接可用(见 §9.1.10 ②)。
  7. 延后项(按林先生 2026-11-09 16:04 的范围约束,不要主动提议): Skill 五端分发、打包 mcgs-tools.zip。

9.1.10 📌 65 kind 全量清扫收工(2026-11-11 20:40)→ 交给下一个 Agent

详细定论:docs/原生桥kind清扫-2026-11-11.md(逐 kind 结果表 + 证据 rid + 踩坑 + 接手顺序) target/after 勘误:docs/原生桥target字典.md §6(状态)/ §7(本轮勘误,优先于旧文)

① 这一轮做完了什么

项 结果
覆盖 §6 backlog 59 个可测 kind 全部 inspect 通过(含此前一直没通的 driver 族、control 复合视觉、page 引用/事件族)
执行链 45 个跑完 inspect→execute→复验/反向:✅ 17 PASS / 📖 5 只读 / ⚠️ 13 ENV_LIMITED / ❌ 5 / ⏭ 1
未跑 策略深水区 14 kind(inspect 已通,只差执行链;脚手架 chain_strat.py 已修好 rid 复用)
红线 control-group/ungroup、root-flush、device-driver-add/properties 未动

② 三个结论性发现(会影响后续所有设计)

  1. driver 族不需要驱动 DLL(推翻旧结论):{module_id:1,path:["设备1"],driver_key:"monidevdrv"} 即可 inspect / in-place / catalog / catalog-preserve-tree。
  2. 设备节点 path 必须是名字链(["设备1"]),不是索引 [0]——这是之前 device-node 族全军覆没的唯一原因。
  3. execute ok 已内含复验:凡 Apply 内部做 Same/VerifyCatalogs 对拍的 kind,执行后不必再 inspect。 据此把 referenced-rename 族从「每 kind 5 次全图 inspect」压到 1 次(该族单次 inspect 就要 10–15 分钟,是全程最大性能瓶颈)。

③ 现场残留(接手第一件事,先清干净再干活)

位置 残留 处置
盘 + 内存 变量 InputSTime → InputSTime_sw2tmp(17:03 已随原生保存落盘,且 system.json 还留 2 处旧名引用 = 半应用态) WB_temp\mcgs-kind-sweep2\restore_data_residue.py:反向改名 + data-flush 落盘,再用离线 mcgs.py export 复核
内存(未落盘) 设备根节点 设备1 → 设备1_sw2rn 反向改名即可;先别保存工程,否则会写进盘
兜底 — 原生桥任务-352d\backup\261109.PRE-TEST.MCP(全测试前原件,最后手段)

残留来源:data-referenced-rename 的 fwd 真实生效,但回执 2193 s 才落盘、客户端先超时 → 被误判 FAIL,rev 没跑。 教训:遇到 QueueTimeout 先 bridge2.late_reply(rid) 捞 engineering\reply-payloads\<rid>.json,绝不重发。

④ 环境硬约束(换机/换人必读)

  • 沙箱只放行 powershell.exe 访问其它进程:McgsHotAttach.exe(自编译 exe)在本机一律 GetProcessById 失败, 必须用 32 位 PowerShell 版 WB_temp\mcgs-kind-sweep2\attach_ps.ps1 <PID> <UI线程>。
  • 启动工程:Start-Process <xxx.MCP> 走文件关联才会加载工程;命令行传路径无效。
  • Pro 重启后视图丢失:drawing/flush 类 kind 前必须重开页 22(page-view-open,回「changed page identity」也算成功,以复验 target_open 为准)。
  • main-control-flush 本机 2/2 卡死宿主(2193 s / 1608 s 无回执,UI 线程死锁)→ 已判定环境破坏性并停测,勿自动重试。

⑤ 接手顺序

  1. 清残留(③ 两条 + 离线 export 复核)。
  2. python chain_strat.py --dry 看 spec → python chain_strat.py R7 跑 14 个策略 kind。
  3. python chain_refrename.py R7 跑剩 4 个 referenced-rename(快速协议已内置)。
  4. 结果回填本文 §1 与 原生桥kind清扫-2026-11-11.md。
  5. 清理 F:\Studio\WB_temp\mcgs-kind-sweep2\(先确认没有别的任务子目录)。

9.2 ⭐ 优先考虑「人工精修 → 收录复用」(而非硬啃逆向)

遇到做不了的能力,先问:能不能让人工做一个模板,然后收录复用?

# 人工在组态里做好并另存后:
python mcgs.py catalog add button <精修件.mcp> <窗口名> 0x5027 <序号> --as 条件动作
python mcgs.py catalog add-window <精修件.mcp> <窗口名>    # 整页入库
# spec 里取用:
{"controls": [{"type": "button@条件动作", "window": "主页"}]}

9.3 需要一次取样的(取样规程)

解锁「启动页写入器」(V0.10.8 已闭环):存储点 = WndControl.lbObjects @796 启动窗口列表;回存定案 = 新对拍件仅 2 处 diff(名字原位 + iID),写入器已落(set_startup_window + 管线 5i 步 + startup_window spec 字段),19 条字节级测试全过;余下 = 含 startup_window 的交付件过组态三关。

解锁「公共窗口槽写入」(2026-11-18 已定案并实现):槽 = 窗口 BLOB 尾 16B 槽块内 b[-8:-4] u32,754 窗对拍 0 异常;写入器已落(set_common_window_ref + 管线 5h 步),组态三关待交付件验收。

解锁「控件改绑变量名变长」(按钮脚本文本变长已于 2026-11-13 由 C1 取样定案并实现,见 §5.14; 同类机制但落点在控件节区,需同法另取样本):改绑一个更长的变量名再另存对拍。


10. 交接检查清单

接手后按顺序过一遍:


11. 待本机全量回归(分支 chore/arch-guardrails-p2,2026-11-17)

基线:main @ 6ee04bc。本分支只做工程化改造:不改字节写入路径、不改 spec 契约字段、不改 verify 规则语义。 请在本机 Windows + McgsPro + 官方样例环境按 §11.2 顺序跑;任一项与预期不符先停,不要合并。 作者侧(Linux、无 McgsPro 样本)已做的验证见 §11.4,可作为对照。

11.1 本次改了什么(三组)

组 改动 关键文件
P0 结构 spec 顶层字段契约从入口层 mcgs.py 下沉到 mcgslib/schemacheck.py;消除 caps/serve.py → mcgs 的反向依赖;新增五层依赖测试;文档护栏扩展(tool 数 / V 规则范围 / AGENTS 扫描) mcgslib/schemacheck.py、mcgs.py、caps/serve.py、tests/test_layers.py、tools/doc_consistency.py
P1 平台 写回通道 MCGS_PS32 环境变量可配置 + 运行期动态解析;非 Windows 上 doctor 明确降级为 SKIP 而非 FAIL;新增 requirements.txt caps/writeback.py、caps/doctor.py、requirements.txt
P2 CLI 命令清单(当时 25 条)收敛为 COMMANDS 单一注册表 (name, help, form, handler):argparse 注册 / 合法性白名单 / 分派链三合一;新增"禁止回退"护栏 mcgs.py、tests/test_cli_registry.py

不涉及:caps/build/ 构建管线、mcgslib/window/ 字节解析、caps/verify.py 的 V 规则实现、mcgslib/vendor/、assets/pro-native-bridge/。

11.2 回归步骤(按顺序)

git fetch origin
git checkout chore/arch-guardrails-p2
cd mcgs-tools
pip install -r requirements.txt

python mcgs.py --help                     # 期望:usage 列出 26 条命令(含 selfcheck)
python mcgs.py doctor                     # 期望:退出码 0 或 1;写回通道 32 位 PowerShell = [OK]
python -m pytest                          # 期望:0 failed
python tools/doc_consistency.py           # 期望:文档一致性 PASS
python mcgs.py scan D:/McgsPro/Samples    # 期望:9/9 PASS

11.3 重点手测(CLI 重构风险点)

  1. python mcgs.py check examples/01_最小_变量与克隆页.json → 构建前检查通过
  2. python mcgs.py build --template flat-cool --donor <本机供体.mcp> --spec examples/01_最小_变量与克隆页.json -o out/回归_01.mcp
    • 重点看 --template / --donor 参数顺序正确(P2 重构点)
  3. python mcgs.py verify out/回归_01.mcp → V1–V14 总体 PASS
  4. 26 条命令逐个 python mcgs.py <cmd> --help 冒烟
    • 注意:inspect --help 返回 2 是既有行为(先校验 strategies/recipes 参数),不是回归
  5. python mcgs.py serve → 起服务后访问 /api/health、/api/templates、/api/check
  6. 组态三关:MCGS Pro 打开 / 编译 / 仿真下载 上面 out/回归_01.mcp
  7. MCGS_PS32 覆盖验证:
    • 设成错误路径 → doctor 写回通道应报 FAIL
    • 设回正常路径(或删除变量)→ 应恢复 OK

11.4 预期与已知差异

项 预期
pytest(Windows + 官方样例) 0 failed。以下 4 条依赖 D:\McgsPro\Samples\G系列样例演示工程1024x600.mcp:test_scripts.py 的 3 条 + test_verify_negative.py::test_negative_matrix
pytest(作者侧 Linux,无样本) 123 passed / 4 failed / 10 skipped(selfcheck 批次后);4 failed 全部是缺 Windows 样本,与 P2 重构前基线同为这 4 条
mcgs.py --help 输出 与 P2 重构前逐字节一致(已归档;本批新增 selfcheck 后为 26 条)
templates / check / doctor --json 与 P2 重构前输出逐项一致(作者侧已 diff)
doctor(Linux) 写回通道报 [SKIP] 平台能力:只读能力可用,写回不可用,属预期降级

11.5 失败时怎么反馈

按 TESTING.md §4.2:带完整命令原文 + 完整报错 + 涉及文件路径,不要只写“报错了”。 回滚:git checkout main(分支未合并,随时可弃)。


12. 自检闭环(2026-11-17,自我升级第一批)

目标:把「散在 AGENTS.md 里、靠人记的四道门槛」变成一条命令 + 分级结论, 并把三类此前无人盯的空白变成红灯(负例覆盖 / 管线顺序 / 能力矩阵数字)。

12.1 新增与改动

项 内容
mcgs.py selfcheck 新增第 26 条命令:聚合注册表 / 文档 / 分层 / 负例 / 管线;--full 加 doctor,--json 机读;FAIL=2 / WARN=1 / OK=0;末尾只给一个可执行下一步
caps/selfcheck.py 编排层,不复制检查逻辑;不 import 入口层(命令清单由 _h_selfcheck 注入,守住五层依赖)
tools/negative_coverage.py V 规则负例覆盖审计:每条规则必须有负例,或在 SKIP_REASONS 登记「为什么构造不出来」;None 值不算覆盖
tests/test_pipeline_steps.py 21 步 STEPS 护栏:数量 / 唯一 / 顺序快照 / handler 可调用 / build() 未被绕过
tools/doc_consistency.py 检查项 9 → 10:加 mcgs.py 头注释版本、能力矩阵版本与端点、命令参考 V 范围、负例覆盖

文档同步:能力矩阵 §七 去掉 V0.9.2 / 10 套 / 14 个 等易漂数字;README / AGENTS / HANDOFF / 命令参考 / SKILL / WIKI 命令数 25 → 26。

12.2 本机回归(Windows + McgsPro)

git fetch origin && git checkout feat/selfcheck-guardrails   # 或等合并后 git pull
cd mcgs-tools && pip install -r requirements.txt
python mcgs.py selfcheck        # 期望:0 阻断,退出码 0
python mcgs.py selfcheck --full # 期望:写回通道 OK;环境警告按需处理
python -m pytest                # 期望:0 failed
python mcgs.py scan D:/McgsPro/Samples   # 期望:9/9 PASS
环境 预期
Windows + 官方样例 pytest 0 failed;selfcheck 0 阻断
Linux 无样例(作者侧) pytest 4 failed(test_scripts ×3 + test_verify_negative::test_negative_matrix,全部缺 D:\McgsPro 样本)/ 123 passed / 10 skipped;selfcheck 仍 0 阻断

12.3 设计取舍

  • 默认不跑 pytest / scan(慢且需样本),只做静态检查;--full 只加 doctor,--pytest 才跑全量。
  • doctor 的 FAIL 在 selfcheck 里降级为 WARN(环境问题不阻断代码提交),代码类检查才是阻断。
  • 新增护栏必须导出纯函数(audit() / _scan() / check()),测试与 selfcheck 共用,避免两套逻辑漂移。

13. UI 校验补给(2026-11-18,A 类三项)

来源:蒸馏 HMI-UI-Design-Skill(作者:工控北极熊)的方法论。 该仓库无 LICENSE,本批只借鉴规则口径,未复制其代码/脚本/资产(README 致谢段已声明)。

项 落地内容 关键文件
A3 按钮双态 新增 V15 按钮双态一致性:两态齐备 / 同画布尺寸 / 像素内容不同 / 锚点矩形一致;「无法取证」与「通过」分开报 caps/verify.py、tests/test_button_dual_state.py、TESTING §4.1
A2 分辨率越界预检 新增 caps/panel_check.py 纯函数;_step_7_panel_fit 改写尺寸前预检,结果写 panel_fit.bounds,只报不阻断(不改字节) caps/panel_check.py、caps/build/steps_panel.py、caps/mcgslib/report.py、tests/test_panel_check.py
A1 字体测量 数值包络(上下界/小数位/正负号 + 中间值)、C/B 两档余量、保中心扩框、碰撞检测;数值输入 0x5025 接入(小数位 0xFFFFFFFF 如实跳过) mcgslib/ui/文字容纳检查.py、tests/test_text_measure.py

验证(作者侧 Linux):selfcheck 0 阻断;doc_consistency PASS;负例覆盖 22 条规则、缺口 0;pytest 237 passed / 4 failed / 22 skipped(4 failed 仍为缺 D:\McgsPro 样本);V 范围全仓统一 V1–V15。

未做与依赖:

  • GDI 实测字宽需 Windows(当前 gen.text_width() 非 Windows 走 fail-closed 记 unsupported);
  • 像素级重排未实现,只给只读建议坐标(suggested_rect);
  • 原生写剪贴板(C1)需 Windows 剪贴板协议,未做。

建议本机验证:python mcgs.py verify <真实工程.mcp> 已含 V15;首次跑若报「两态画布尺寸不一致」,需主人判断是否既有合法工程。 主人裁决(2026-11-18,本机首跑后):官方样例 18 件中 13 件 V15 报告(两态画布不一致 / 缺一态) 全部属既有合法工程(厂商自带内容,两态贴图本就不同画布或只画按下态)→ 定案官方样例基线豁免: V15 规则本体不动、输出逐条保留,但不计回归红线。落地三处:caps/verify.py BASELINE_EXEMPT_RULES (豁免登记表,单一事实源)/ 负例矩阵基线改「V1–V14 全 PASS」且豁免规则负例按损坏前后 detail 对比归因 / scan 扫官方样例目录(.../McgsPro/Samples)时豁免规则不计退出码红线(JSON 新增 redline_fail / baseline_exempt 字段);扫真实工程目录时 V15 仍计红线(交付件口径不变)。


14. UI 设计契约补给(2026-11-18,B 类三项)

来源同 §13:HMI-UI-Design-Skill(工控北极熊,无 LICENSE),只借鉴规则口径。 本批把三块「契约型」内容变成可调用能力,新增 3 条只读命令(26 → 29)。

项 落地 关键文件
B1 布局预设 2 布局(左/底导航)× 4 色调;regions() 算状态栏 / 报警条 / 导航 / 内容区;左导航时报警条不压导航列 layouts/left.json、layouts/bottom.json、layouts/themes/*.json、caps/layouts.py、tests/test_layouts.py
B2 页面配方 6 类(总览/手动/参数/报警/IO/维护)共 31 个模块;suggest() 按页面名匹配,不猜;outline() 按 core→task→optional recipes/*.json、caps/recipes.py、tests/test_recipes.py
B3 交付对账 8 项检查(必备文件 / 路径安全 / 哈希清单 / spec 声明 / ZIP 一致);状态 pass/fail/blocked/not_checked;退出码 0/1/3 caps/delivery.py、tests/test_delivery.py
python mcgs.py layouts --list
python mcgs.py layouts --canvas 1024x600 --layout left --json
python mcgs.py recipes --list
python mcgs.py recipes --show 参数
python mcgs.py recipes --suggest 手动操作
python mcgs.py delivery --check <导出目录或.mcp> --spec spec.json --json

验证(作者侧 Linux):新增测试 78 + 29 全过;selfcheck 0 阻断;doc_consistency PASS;命令数 29。

14.1 本机拉取与自检(Windows)

git fetch origin
git checkout feat/ui-validation-backfill    # A/B 两批都在此分支;合并后改用 main
cd mcgs-tools
pip install -r requirements.txt

python mcgs.py selfcheck                    # 期望:0 阻断
python mcgs.py selfcheck --full             # 期望:写回通道 OK,环境警告按需
python -m pytest                            # 期望:0 failed
python mcgs.py layouts --canvas 1024x600 --layout left
python mcgs.py recipes --list
python mcgs.py verify <真实工程.mcp>        # 重点看 V15 是否误伤
环境 预期
Windows + 官方样例 pytest 0 failed;selfcheck 0 阻断;--help 列出 29 条;scan D:/McgsPro/Samples 红线 0(退出码 0;V15 豁免输出保留,汇总行标「红线 0,其中 N 个仅基线豁免项」)
Linux 无样本(作者侧) pytest 4 failed(test_scripts ×3 + test_verify_negative)、selfcheck 仍 0 阻断

若 V15 报「两态画布尺寸不一致」:这是新规则要报的问题。先确认该工程 s0/s1 图片是否本就不同画布;若属既有合法工程,请把样本路径 + 控件名 + 报错原文反馈,不要直接改规则。 (官方样例已按 2026-11-18 主人裁决定案豁免,见 §13;真实工程仍走本条反馈流程,V15 在真实工程上计红线。)

未做 / 下一步:

  • B1 尚未接入 compile-intent(建议:IntentSpec 加 layout/theme,用 regions() 定位公共区域后再排内容);
  • B2 尚未被 intent 引用(建议:只把 core 模块当硬校验,task 作提示,optional 交用户确认);
  • C1 原生写剪贴板:已有基础,不是从零——caps/clipdump.py 的 selftest 里已有一个独立子进程写剪贴板的写入器,scan/parse/diff 已能判读 MCGS_DRAW_OBJ;缺的是把写入器产品化为 clipdump copy 子命令 + 写后 SHA 回读校验(需 Windows + MCGS 会话安全)。

附:相关位置速查

内容 位置
WorkBuddy skill(对话里直接触发) C:/Users/<用户>/.workbuddy/skills/mcgs-file-create/SKILL.md(各机用户目录;分发真源 = 仓库 skills/mcgs-file-create/SKILL.md)
仓库正本 F:/Studio/10 Projects/MCGS_File_Create/(git remote → GitCode linjian19901122/MCGS_File_Create)
验收件交付区 F:/Studio/00 Inbox/mcgs_verify_20261029b/(4 件 + spec;目录已清理)
留档区 F:/Studio/Code/MCGS_File/Phase10_内容层/(已清理)
零母版留档 F:/Studio/Code/MCGS_File/Phase12_策略配方/(已清理)
逆向实验区 F:/Studio/Code/MCGS_File/(现余 原生桥任务-352c/352d + 测试工程)
工作日志(每日) F:/Studio/.workbuddy/memory/YYYY-MM-DD.md
官方样例工程 D:/McgsPro/Samples/(9 模板 + G/E/N/4.3寸)
原厂程序 D:/McgsPro/Program/(McgsSetPro.exe、script.dll)
真实工程集 F:/Work/(26 份)+ F:/BR_Project/(4 份)——2026-11-12 核:两目录本机已不存在,30/30 回归基线待工程集恢复

附:历史记录去哪了

原章节 去处
§11 本机接手记录(136 行流水账) 已删除 —— 历史在 git 与 CHANGELOG
§9.2/9.3/9.4 旧待办 已更新为本文件 §9
§4.2.1–4.2.8 逐 Phase 细节 压缩进本文件 §5;细节见 mcgs-tools/CHANGELOG.md
旧里程碑 RoadMap docs/archive/RoadMap-2026-10_历史里程碑.md
旧实验记录 docs/archive/实验说明-Phase2至V0.1.md
旧命令说明(八命令时代) docs/archive/mcgs.py说明-八命令时代.md

本文件由 Phase 8(2026-11-07)文档治理重写:750 行 → 精简为状态快照, 技术资产全部保留(§5 从 6 小节扩到 10 小节),历史流水账全部移除。