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.mcpverify 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.mcpverify 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意图前必跑);三接口同步(MCPmcgs_template_probe17 tool / HTTP/api/template-probe18 端点);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-probeV0.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.pyV 规则内存损坏负例矩阵(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 skillmcgs-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 类;新控件无旧动作/绑定/图片引用 |
关键实现细节:
- 节区格式与母版路线完全一致:
tag(u32) + 长度(u16) + payload。 上游ControlRecord.to_bytes()与本仓库window._validated_section期待同一格式, 所以原语造的节区能直接走append_control_section/plant_first_section。 - 字节兼容已实测:上游
WindowArchive.parse解析本机 G 样例 15 个窗口,to_bytes()与原始 BLOB 逐字节相等,15/15 通过。 - 变量 id:原语造控件时直接把目标工程的真实 id 写进节区(不是临时 id),
之后再用
window.retarget_variable_ids复核一遍。 - 按钮双态是原生 press / release 两个字段,各自独立, 不受母版路线的等长替换限制 —— 这是原语路线比母版路线强的地方。
- 护栏:原语路线不认母版专属字段(
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):
- 文字左右留白 ≈ 6 像素(工具判据用 8,多留余量),框宽不足裁掉末字
- 离线预览 ≠ 原厂效果(3 处已知差异,见 §8.6)
- 驱动类型码写错 → 读正常、写静默失败(命令返回 0,PLC 收不到,也不报错)
- 存盘浏览首条
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:
- 触发:
McgsHotAttach.exe --connect/PortableClient --connect - 注入:
SetWindowsHookEx注入 Pro(x86) UI 线程;BootstrapLayout强制SamePath(宿主主模块 == 配置里的 editor),引擎只能活在 Pro 进程内 - 读原生态:各 profile 用
NativeMemory.Ptr/Readable/I32直接读/写 Pro 原生内存(控件树、页面文档、MainCtrl 数组) - ABI 解析:
NativeAbiTargetProfiles用JavaScriptSerializer{MaxJsonLength=int.MaxValue}加载abi-target-profile-index.json(0.24MB,V0.8.5 瘦身)+supplement(18.47MB),在内存构建 profile 表 - 强类型原生 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 手笔的字节级定案(改前/改后逐字节对拍):
- 脚本是节区里的单个 strfmt 串,原偏移原地变长:串头 @808
FF FE FF <字符数>(0x21=33 → 0x2B=43;<0xFF 仍用 4 字节头),串体 UTF16LE。 其后全部内容整体后移 +20B(33→43 字符 = +10 字符 = +20 字节)。 - 节区长度字段 @4(u16):937 → 967(MCGS 自己更新)。
- 标志/计数字节 @82:0x80 → 0x84(+4,伴随新增动作行出现;精确语义待更多样本,写入器按「+4/每新增一行」暂定)。
- 串后紧邻 u32 长度:0x39=57 → 0x43=67(+10 = 字符增量,脚本区字符计数)。
- 尾部追加 10B:两个 5 字节条目
26 9c 00 00 00/3e 9c 00 00 00(u32 变量 id + 00 分隔)——新行设置年=设置年的变量引用进 id 表 (左值/右值各一条)。变量引用表按引用追加,不在串里。 - 此前担心的「绝对偏移指针失效」未出现:串前除 @4/@82 外逐字节一致;
实测出现过的
bc 02/86 03u16 在两版中位置与值均未变——要么不是绝对指针, 要么指向未移动区域。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 手笔的字节级定案(改前/改后逐字节对拍):
- 变量名是节区里的单个 strfmt 串,原偏移原地变长:串头 @214
FF FE FF <字符数>(03 → 06),串体 @218 UTF16LE(6B → 12B), 其后全部内容整体后移 +6B。 - 节区声明长度字段 @4(u16):425 → 431(+6)。
- 绑定点 [u32 id][u32 dtype](@206,布局 A = 变量名前 8 字节)不动: id 仍 159、dtype 仍 2 —— 改名保 id,只名字串变长。
- 无计数字节、无 u32 字符计数、无尾部变量 id 条目: 比 0x5027 按钮脚本(「加行」场景要动 @82 计数字节 + 尾部 id 条目)更简。 尾部 207B 改前/改后逐字节一致,仅整体后移。
- 无绝对偏移失效 —— 与 §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 阶段拦下 |
软约束(靠人守):
- 变量 / 图片名不能以数字开头。
0x5025图片引用名 ≤3 字。- 表达式 / 引用角色串不可当显示文本替换(除非显式
force)。 - 已知限制必须落成构建期护栏 —— 只写文档不算护栏 (Phase 10 交付坏工程就是这个教训)。
- 只改工程副本;生成后务必回组态软件验收。
7. 工作流程规矩
7.1 组态验收协议(详见 TESTING.md §4.2)
- 三关:打开(不报损坏)→ 编译 → 仿真下载。任一关失败即停。
- 另存回读:验收件在组态里另存,Agent 对拍 —— 12 张表逐行逐字段一致 = 零改写(字节层正确性的最高背书)。
- 失败件勿删:另存件交回(MCGS 的规范化输出是反推依据); 损坏本体归档为反面 ground truth。
- 交付到组态未锁过的新路径:组态打开工程会锁
.ldb, 期间工具链覆盖同名文件后,组态再另存会用内存里的旧状态写回,把新产物冲掉。 交付时说明文件名与校验值。 - 反馈要带原文:报错附控件名 + 错误描述原文/截图。 同一现象可能有多条根因。
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 立刻可做(不等任何人)
-
接入真实 Pro(手动步骤,需主人在组态软件里打开一个工程) —— 见 docs/原生桥部署规程.md(原部署清单已并入其 §12)。
部署准备阶段已成功跑通 6 步(V0.8.5,
native deploy,2026-11-07 实测 ~16 分钟,稀疏目录 + 精简扫描): runtime / bootstrap / engineering 已 staged。主索引abi-target-profile-index.json0.24MB, 完整诊断在abi-target-profile-supplement.json(18.47MB,C# 端不读)。 产物根目录:F:\Studio\Code\MCGS_File\原生桥任务-sparse-v3\(目录已清理, 被 352c / 352d 部署取代;runtimeruntime-20261107193635407/ bootstrapbootstrap-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 个
partialprofile 的完整诊断(撑大索引至 16.06MB) 已移入abi-target-profile-supplement.json,主索引降到 0.24MB。C# 端对details/entry_statuses不强依赖 (见 §5.11 第三条坑)。首次 connect 后仍建议立即跑postdeploy观察运行时告警;若具体 profile 报错,再补定位对应签名。 -
拿真实项目跑一把 —— 推荐 SVO-858 或多路温控, 零母版 + 预览 + 体检 + scan 四条链一起上,验证在真实业务里顺手不顺手。
-
补验证器规则 —— 每个都先在官方样例上试准,误伤就撤回。
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 个未知 kind0x5026,经字节级取证确认为 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,示例已统一改用。
待办 / 后续里程碑(北极星路线):
- ✅ NL→spec 智能体(吃需求关键词/自由抽取吐合法 spec,调 build 生成)—— 已落地(2026-11-08,见 §9.1.4),最快打通「任何 Agent 生成画面」。
- ✅ 图片模板→spec(截图/模板 → 布局 spec)—— 已落地(2026-11-08,见 §9.1.5),北极星第二阶段差异化能力打通。
- 工控母版库积累(泵房/供水/温控典型场景母版,靠
catalog add持续攒)。 - 在线读通道(全量 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.pyCLI,复用经「打开/编译/仿真下载」三关验收的管线,行为与离线工具链一致。 - 双解释器隔离:
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 画面+驱动+策略」的核心落点,已实测闭环。
分层设计(把易错活交给确定性代码):
- AI 只抽
IntentSpec(字段少、语义高,是 LLM 该填的那一层)—— 契约见mcgslib/intent.schema.json; - 确定性编译器
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); - 落入既有
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 同内核),已实测闭环。
核心设计(把易错活交给确定性代码):
- 视觉只抽语义清单(
ImageIntent:标题、监控量、开关、按钮、协议,可选像素 bounds)—— 契约见mcgslib/image_intent.schema.json; - 确定性编译器
mcgslib/image_intent.py:image_to_intent()把 ImageIntent 展开成完整 ScaffoldSpec——auto(默认)路线收口成 IntentSpec 复用compile_intent的自动网格布局(视觉对 box 精度不敏感);preserve路线按识别到的bounds直接落from_primitive(需较准框);
- 落入既有
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。
⑤ 本轮踩到的坑(务必记)
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」)。- close-reopen 的前提是「磁盘 == 内存态 且 root 未修改」(
Need(root_modified==0 && Hash(project)==state.project_sha256))。 若先在外部覆盖磁盘再让它重开,Pro 会直接退出(本轮实测踩到)。还原工程必须先让 Pro 重开,再覆盖磁盘, 或覆盖后重新加载工程 —— 顺序反了就会崩。 - close-reopen 回执延迟可达 4 分钟以上(本轮实测 ~4min),客户端
--timeout 240会先报 「No correlated response; execution is unknown, do not resubmit」。此时不可重发 —— 回执最终会落进<runtime>/outbox/<request_id>.json,应去 outbox 等它。 - close-reopen 重开后 MCGS 会自己重写文件(
original_open_changed_physical_sha=True), 改的是 System 表等运行时数据,窗口 BLOB 不变。因此「还原」的判据应是 窗口级 diff 归零,而不是整文件 SHA256 相等。 - 在线读分类口径:
ok=true不代表动作成功 —— 动作可能落在unsupported_actions里。 判定「某个 kind 可用」必须看它是否出现在action_preimages。 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#458MCGS 内部索引),其余零差异、字符串差异 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 只在特定时机存在,关工程时会被消耗,不能当稳定恢复源。
⑥ 下一步清单(按建议顺序)
- 重启 Pro + 重新提权注入 352f(UAC 需人工点「是」)→ 复跑
postdeploy确认对拍一致。 ⚠️ 桌面副本现在没有任何自动兜底(.bak已消耗),开工前先cp一份到baseline/。 补完 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 全等)。 策略类规程:清单入口=inspectstrategy-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 按需续测。✅ 已闭环(并入上条,fwd/rev 对称成功、磁盘零变化)。data-edit零覆盖control-group/control-ungroup:不在真工程上做(见 ⑤ 红线)。 如确需验证,只能用一次性副本,且验证后直接丢弃、绝不回流。data-group-create:需expected_next_native_id(源码NativeDataPrototypeEditing.v3.cs:27); 取值路径存在循环依赖(读它也要这个值),需另寻来源。设备驱动类能力:需装对应驱动 DLL→ 2026-11-11 已推翻:无需装 DLL,{module_id:1,path:["设备1"],driver_key:"monidevdrv"}直接可用(见 §9.1.10 ②)。- 延后项(按林先生 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 未动 |
② 三个结论性发现(会影响后续所有设计)
- driver 族不需要驱动 DLL(推翻旧结论):
{module_id:1,path:["设备1"],driver_key:"monidevdrv"}即可 inspect / in-place / catalog / catalog-preserve-tree。 - 设备节点 path 必须是名字链(
["设备1"]),不是索引[0]——这是之前 device-node 族全军覆没的唯一原因。 - 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 线程死锁)→ 已判定环境破坏性并停测,勿自动重试。
⑤ 接手顺序
- 清残留(③ 两条 + 离线 export 复核)。
python chain_strat.py --dry看 spec →python chain_strat.py R7跑 14 个策略 kind。python chain_refrename.py R7跑剩 4 个 referenced-rename(快速协议已内置)。- 结果回填本文 §1 与
原生桥kind清扫-2026-11-11.md。 - 清理
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 重构风险点)
python mcgs.py check examples/01_最小_变量与克隆页.json→ 构建前检查通过python mcgs.py build --template flat-cool --donor <本机供体.mcp> --spec examples/01_最小_变量与克隆页.json -o out/回归_01.mcp- 重点看
--template/--donor参数顺序正确(P2 重构点)
- 重点看
python mcgs.py verify out/回归_01.mcp→ V1–V14 总体 PASS- 26 条命令逐个
python mcgs.py <cmd> --help冒烟- 注意:
inspect --help返回 2 是既有行为(先校验 strategies/recipes 参数),不是回归
- 注意:
python mcgs.py serve→ 起服务后访问/api/health、/api/templates、/api/check- 组态三关:MCGS Pro 打开 / 编译 / 仿真下载 上面
out/回归_01.mcp 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 小节),历史流水账全部移除。