利用AI 的Agent能力进行昆仑通态的触摸屏工程的脚手架工程生成。
Access rate limit exceeded. Please log in to continue.
MCGS_File_Create
利用 AI 的 Agent 能力进行昆仑通态触摸屏工程的脚手架工程生成。
一句话:从自然语言需求出发,生成可直接在 MCGS Pro 组态软件里
打开 / 编译 / 仿真下载的 .mcp 工程。
北极星:任何 AI Agent 用「需求关键词」或「图片模板」,即可快速生成 MCGS 画面 + 驱动 + 策略(画面含对应控件)—— NL→spec 与 图片→spec 两条智能体链路均已落地实测(V0.8.7–V0.8.9)。
(工具链当前版本 V0.10.5,python mcgs.py --version 查询;
变更记录见 mcgs-tools/CHANGELOG.md;
文档导航见 docs/WIKI.md;
任何 AI Agent 接入前先读 mcgs-tools/AGENT_CONTRACT.md。)
快速上手
最快路径:一句话生成画面(NL→spec 智能体,自动布局 + 驱动 + 变量):
cd mcgs-tools
python mcgs.py compile-intent --use-template 泵房 --param scale=4 -o spec.json
python mcgs.py check spec.json
python mcgs.py build --template flat-cool \
--donor "D:/McgsPro/Samples/G系列样例演示工程1024x600.mcp" \
--spec spec.json -o out/泵房.mcp
python mcgs.py verify out/泵房.mcp
常规路径(手写/编辑 spec 后生成):
cd mcgs-tools
python mcgs.py doctor # ① 环境自检:一条命令看能不能跑
cat examples/README.md # ② 挑一个示例 spec
python mcgs.py build --template flat-cool \
--donor "D:/McgsPro/Samples/G系列样例演示工程1024x600.mcp" \
--spec examples/01_最小_变量与克隆页.json -o out/示例1.mcp
python mcgs.py verify out/示例1.mcp # ③ V1–V13 静态对拍
# 最后:MCGS Pro 组态软件 打开 / 编译 / 仿真下载 三关验收
安装依赖:
pip install access_parser # 必需:纯 Python Jet DB 读取器(只读)
pip install jsonschema # 可选:schema 强校验(缺席时自动降级)
pip install fastapi uvicorn # 可选:仅 serve 需要
pip install unicorn pefile # 可选:仅 script compile/simulate 需要
pip install httpx2 # 可选:仅 test_serve_v2 需要
⚠️ pip 大包在本机 MITM 代理下会 stall —— 用阿里云镜像:
pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com <包名>
文档导航
不确定读哪份?从 docs/WIKI.md 进。
| 文档 | 内容 | 什么时候读 |
|---|---|---|
| docs/WIKI.md | 文档地图 | 入口 |
| docs/架构.md | 五层分层图 + 依赖规则 + 加功能落点 | 动代码前 |
| docs/能力矩阵.md | 能力 × 命令 × 验证方式 × 验收状态 | 想知道「能不能做、怎么验」 |
| docs/命令参考.md | 25 条命令的用法与参数 | 写命令、写 spec 前 |
| docs/验证方法.md | 五道验证关卡 | 提交前自查 |
| docs/扩展指引.md | 加/删/改功能的标准流程 | 任何代码改动前 |
| docs/原生桥target字典.md | 每个 kind 的 target / before / after 字段配方 | 走原生桥写操作 |
| docs/原生桥kind清扫-2026-11-11.md | 65 个 kind 全量清扫台账(逐 kind 结果 + 接手顺序) | 续做原生桥 |
| HANDOFF.md | 当前状态快照 + 技术定案 | 接手第一份 |
| mcgs-tools/AGENT_CONTRACT.md | 任何 AI Agent 接入契约(稳定边界 + 标准闭环) | Agent 接入前 |
| mcgs-tools/SPEC.md | ScaffoldSpec 字段契约 | 写 spec |
| mcgs-tools/MCP_SERVER.md | mcgs-mcp server 接线(各宿主 mcp.json 片段) | Agent 程序化调用 |
| mcgs-tools/TESTING.md | 组态三关验收协议 | 交付给主人前 |
| docs/MCGS语义知识.md | 语义知识层(含 §8–§11 实机知识) | 查格式事实 |
仓库结构
mcgs-tools/ 工具链正本(Python)
├── mcgs.py 入口层:统一 CLI(25 条命令)
├── mcp_server.py 入口层:MCP server(17 个 tool,subprocess 调 mcgs.py)
├── caps/ 能力层:原顶层 mcgs_*.py 薄壳(去 mcgs_ 前缀,逐命令一个文件)
│ ├── build/ 构建管线(原 mcgs_build.py 按步拆分)
│ ├── verify.py / export.py / scan.py / diff.py / ...(只读能力)
│ └── native.py / native_deploy.py / ...(原生桥部署链)
├── mcgslib/ 语义层 + 字节层
│ ├── window/ 原 window.py 按功能域拆包(__init__ 全量重导出)
│ ├── vendor/ 移植自 mcgs-engineering-skill 的原生字节层(MIT)
│ ├── ui/ 离线预览 / 文字体检
│ ├── script/ 条件脚本字节码
│ └── intent.py / image_intent.py / intent_templates.py ← 北极星:NL/图片 → spec 确定性编译器
├── tools/ 辅助脚本:doc_consistency / build_semantics / smoke_mcp / run_resolve_catalog
├── tests/ 10 个测试(pytest 化,python -m pytest 单闸)
├── examples/ 12 个示例(9 个 ScaffoldSpec + 3 个意图样例)
├── static/ Web UI
├── assets/ 上游原生桥资产(21MB,可选部署)
├── scaffold.schema.json / SPEC.md ← spec 契约(单一事实源)
├── AGENT_CONTRACT.md ← 任何 AI Agent 接入契约
├── MCP_SERVER.md ← MCP 接线说明
└── TESTING.md / CHANGELOG.md / THIRD_PARTY.md
docs/ WIKI 文档体系(+ archive/ 历史存档)
HANDOFF.md 交接文档:现状快照 + 技术定案
能力总表
完整表格(含每项的验证方式与证据)见 docs/能力矩阵.md。
| 能力 | 状态 |
|---|---|
NL→spec 智能体(compile-intent,关键词模板 / 自由抽取) |
✅ 实测闭环:compile→check→build→verify 全 PASS(V0.8.7) |
图片→spec 智能体(image-to-spec,auto/preserve 双策略 + dark/light 主题调色板) |
✅ 实测闭环:真实截图 → 16 控件 spec → V1–V12 全 PASS(V0.8.8–V0.8.9) |
| mcgs-mcp server(17 个 tool,任何 AI Agent 程序化调用层) | ✅ subprocess 接线实测(V0.8.7);写操作刻意不暴露 |
| 23 类控件种入(9 类固化母版 + 14 类本地登记) | ✅ 组态打开 + 仿真实测通过 |
零母版从零造控件(controls[].from_primitive) |
✅ 组态三关通过(2026-11-07;字节级 15/15 回环) |
按钮动作赋值(button_actions[]) |
✅ 值域按变量类型守(开关型 {0,1},数值型受等长限制) |
按钮脚本改写(button_scripts[]) |
✅ 组态三关通过(2026-10-30;零改写对拍 0 差异) |
控件变量改绑(controls[].bind) |
✅ 组态三关通过(2026-10-30;零改写对拍 0 差异) |
策略源码精确编辑(strategy_edits[]) |
✅ 组态三关通过(2026-11-07;组态用自己的编译器重编了源码) |
配方单元格改值(recipes[]) |
✅ 组态三关通过(2026-11-07) |
窗口删除(window_deletes[]) |
✅ 带引用护栏:外部引用默认拒绝并列清单 |
| 变量增改 / 设备注入 / 通道同名绑定 | ✅ 已验收 |
窗口克隆 / 批量参数化建页(batch[]) |
✅ 已验收 |
| 文本变长替换 / 图片注入(SVG 信封定稿公式) | ✅ 已验收 |
面板机型码 + 尺寸适配(panel.fit_windows / skip_popups) |
✅ 已验收 |
| 按钮跳转重定向 / 窗口改名 | ✅ 已验收 |
| 策略脚本替换(Stgy + StgyAndTrigger 双写) | ✅ 已验收 |
母版变体 + 整窗收录(catalog add --as / add-window) |
✅ 收录时输出依赖清单 |
| 控件 kind 知识层(21 类身份表 + kind 级护栏 + V12) | ✅ 官方样例 458 节区零表外 kind |
离线预览(mcgs.py preview) |
✅ 官方样例 12 窗渲染读入错误 0 |
文字体检(mcgs.py textfit) |
✅ 文字放不下 / 控件交叠 |
批量工程体检(mcgs.py scan) |
✅ 真实工程 30/30 PASS(修复前 0/30) |
策略 / 配方排查(mcgs.py inspect) |
✅ 写 spec 前先看,不用猜行列号 |
窗口引用扫描(mcgs.py refs) |
✅ 删窗前必扫 |
条件脚本字节码(mcgs.py script) |
🟡 语义已验证;适用对象是策略脚本不是按钮动作 |
在线原生桥接入(mcgs.py native) |
✅ 已部署并接入验收(352e/f37d646,2026-11-13):65 kind 全量清扫 + Track A 复跑收尾 → 见 docs/原生桥kind清扫-2026-11-11.md §9 |
| 启动页存储点 / 按钮按下态贴图 / 文字颜色字体节区 | ⏳ 未做,见 能力矩阵 §八 |
统一入口(25 条命令)
| 命令 | 做什么 |
|---|---|
doctor |
环境自检:依赖 / 组态目录 / 官方样例 / 写回通道 / 母版目录 |
templates |
列出官方风格、样例与自积累模板;add/remove 管理自积累 |
check spec.json |
只检查 spec(schema 强校验 + 语义校验),不生成工程 |
build |
按 spec 生成 .mcp |
export |
工程导出成 JSON(--pictures / --full 完整 round-trip) |
verify |
V1–V12 静态对拍 |
diff / salign |
两工程的窗口 BLOB 差异(item 级 / 按 0x50XX 节区对齐) |
kinds |
普查控件 kind 分布,列出可当母版的节区 |
buttons |
普查按钮:哪些带单击动作脚本、条件脚本、母版候选 |
catalog |
母版目录:scan / add / add-window / remove / list / auto |
script |
条件脚本字节码:compile / inspect / simulate / symbols |
serve |
本地 HTTP API(18 端点)+ Web UI(无头模式) |
clipdump |
截获/判读组态软件剪贴板(Windows) |
refs |
窗口引用扫描(只读):谁指向了哪个窗口 —— 删窗前必扫 |
primitive |
零母版控件工厂:list / preview(不写工程) |
preview |
离线预览:渲染窗口 → PNG + HTML 索引(只读) |
textfit |
文字体检:文字放不下 / 控件框交叠(只读) |
inspect |
策略 / 配方排查(只读,写 spec 前先看) |
scan |
批量工程体检:递归扫 .mcp 逐个 verify 并汇总(只读) |
native |
在线原生桥:状态 / op 清单 / 调用(未部署则优雅降级) |
compile-intent |
NL→spec 智能体:--use-template 泵房 --param scale=4 或 --intent 意图.json |
image-to-spec |
图片→spec 智能体:--layout-json 意图.json(manual)或 --backend vision |
template-probe |
模板多页探查(只读):导航源 0x5027 / 按钮图片对 / 首页原生网格 + 判定 ok/hub_only/unusable(写多页意图前必跑) |
注:
--help里只列 21 条 ——compile-intent/image-to-spec走 main 手动分发、 未注册进 argparse 子解析器(待补,见推进计划「仓库卫生」)。
详细参数见 docs/命令参考.md(权威来源是 mcgs.py --help 与源码 docstring)。
七个值得单独说的能力
① 零母版从零造控件
除了「克隆母版」,还有一条不需要任何母版的路:用内建的原生原语直接造控件。
python mcgs.py primitive list # 看能造什么
{
"controls": [{
"window": "首页", "from_primitive": true, "type": "button",
"primitive_name": "启动按钮", "primitive_bounds": [40, 80, 200, 145],
"primitive_caption": "启动",
"primitive_press_source": "运行标志=1", "primitive_release_source": "运行标志=1"
}]
}
支持 8 类:label / line / rectangle / button / numeric-input /
character-input / numeric-display / character-display(也接受中文名)。
字体要写中文名:组态软件按中文名取字体,写英文名(如
Microsoft YaHei) 会让组态打开工程时直接报错。实测 9 份官方样例里出现过的字体名 只有「宋体」(10984 次) 与「Arial」(426 次)。不写字体默认「宋体」; 写组态不认的字体名会在check阶段就拦下。
② 离线预览与文字体检
不打开组态软件,也能看到画面、查出排版问题。
python mcgs.py preview 工程.mcp -o out/预览/ # 每窗口一张 PNG + HTML 索引
python mcgs.py textfit 工程.mcp -o out/体检.json # 文字放不下 / 控件交叠
preview 覆盖 21 类控件的原生样式:按钮两态、输入框只读态、趋势曲线、
报警表、配方表、存盘浏览等。全程只读 —— 不写工程、不启动厂商程序。
textfit 查两件事:文字放不下(按微软雅黑实际字宽;
实机观察原厂左右各留约 6 像素,工具判据用 8 像素多留余量)
与控件框交叠。
边界:离线字段渲染,不是原厂截图,也不代表 GUI 或运行验收; 动态值一律占位。已知与原厂的差异有 3 处(见语义知识 §8.6)。
这两个工具的实际价值:2026-11-07 就是靠离线预览发现 「label 默认文字色是纯白、白底板上白字看不见」—— 节区里有、组态也认、不报错,但就是看不见。 没有预览,这类问题只能靠人眼在组态里碰巧发现。
③ 策略源码精确编辑与配方改值
{
"strategy_edits": [{
"strategy": "取温度取转速", "action_path": [0, 0, 0],
"source": "巡检监控 = 1\r\n故障监控 = 1\r\n"
}],
"recipes": [{ "group": "面包", "row": 1, "column": 1, "value": "88" }]
}
strategy_edits[]按策略名精确匹配 +action_path=[行,列,动作]定位, 只清被改动作的编译缓存,其它动作与其它策略逐字节不变; 变长安全(策略容器按记录长度重排)。recipes[]改「记录 × 字段」矩阵:行 = 配方条目,列 = 字段。 只改值,不增删行列(改结构会牵动 DrawRecipe 控件的列绑定与容量合同)。- 构建器双写
Stgy表 +System.StgyAndTrigger(MCGS 加载后者)。
写 spec 前先看一眼(全程只读,行列号不用猜):
python mcgs.py inspect strategies 工程.mcp
python mcgs.py inspect recipes 工程.mcp
④ 批量工程体检
python mcgs.py scan F:/Work # 递归扫 .mcp 逐个 verify 并汇总
python mcgs.py scan F:/Work --only-fail # 只列有问题的
只读。用途:改完工具链跑一次,就知道有没有把哪个工程搞坏。
2026-11-07 就是靠它发现问题 —— V0.3 之前工具链只在官方 9 份样例上验证过,
拿真实项目一测,verify 报的是误报(ObjData 只解析 37.9%、
19 条图片不识别、表外 kind 判损坏)。修复后:真实工程 30/30 PASS。
⑤ 在线原生桥(读内存态 / 编译)
离线层读磁盘上的 .mcp;原生桥读组态软件内存里那个已打开的工程 —— 走厂商自己的 API、走 UI 线程。在线的不可替代价值:改完能编译。
7 个子命令:
python mcgs.py native status # 桥在不在(只查目录)
python mcgs.py native status --probe # 探活(发一次 ping)
python mcgs.py native ops # 34 只读 / 19 写 / 4 工程编辑
python mcgs.py native call native-read-tree --project 工程.mcp
# —— 部署三步(详见 docs/原生桥部署规程.md)——
python mcgs.py native selftest # ⓪ 自测闭环(自有宿主,不碰厂商程序)
python mcgs.py native preflight # ① 部署预检(只读,逐项 OK/WARN/BLOCK)
python mcgs.py native deploy --editor <组态EXE> --task-root <任务目录>
# ② 准备+编译+自检(上游 6 步编排)
python mcgs.py native postdeploy --runtime <runtime目录> --project 工程.mcp
# ③ 验证(探活+读内存态+与离线层对拍)
python mcgs.py native attach --client <exe> --config <json> --pid <PID> --ui-thread <TID> --yes
# 接入已运行的 Pro(🔴 高风险,必须 --yes)
桥不是本仓库的一部分。接入会注册 COM、在厂商进程里装线程 hook —— 高风险操作,本仓库不自动执行, 请按 docs/原生桥部署规程.md 走(含风险清单、验证边界与卸载步骤)。
未部署时:工具链全部离线能力照常工作,本命令给出降级说明。
本机实测现状(2026-11-13):已部署并 65 kind 全量清扫 + Track A 复跑收尾 ——
352e 部署面(f37d646 资产)在线,热接验收通过;59 个可测 kind 全部 inspect 通过,45 个跑完
「inspect→execute→复验/反向」执行链(✅17 / 📖5 / ⚠️13 / ❌5 / ⏭1);
Track A 复跑定论与孤儿残留容忍口径见清扫台账 §9。ABI 定位经稀疏目录 + 精简环境
从 3 小时压到 ~15 分钟。逐 kind 结果与接手顺序见
docs/原生桥kind清扫-2026-11-11.md、
target 配方见 docs/原生桥target字典.md。
红线:control-group/ungroup、root-flush、device-driver-add/properties 不动;
main-control-flush 本机卡死宿主,环境破坏性停测。
⑥ 北极星:需求 / 图片 → spec(两条智能体链路)
用户终态:任何 AI Agent 用「需求关键词」或「图片模板」即可快速生成
MCGS 画面 + 驱动 + 策略。核心设计是把易错活交给确定性代码——
AI 只填一层语义高、字段少的意图(IntentSpec / ImageIntent),
确定性编译器把它展开成 100% 过 scaffold.schema.json 契约的完整 ScaffoldSpec,
再落入既有 check → build → verify 闭环。
# 关键词模板直出(泵房/泵站、供水加压/恒压供水、多路温控/温控 三类范式)
python mcgs.py compile-intent --use-template 泵房 --param scale=4 -o spec.json
# 自由抽取(Agent 把需求抽成意图 JSON)
python mcgs.py compile-intent --intent intent.json -o spec.json
# 截图 / 模板 → spec(manual 侧车 / vision 后端;auto 自动网格 / preserve 保留识别框)
python mcgs.py image-to-spec --layout-json 首页.json -o spec.json
三条程序化接入路(面向「任何 AI Agent」):CLI 命令、MCP tool
(mcgs_compile_intent / mcgs_image_to_spec,build=True 一步到位
compile→build→verify)、Python(mcgslib.intent / mcgslib.image_intent)。
实测:关键词「泵房」scale=3 → 16 控件 + ModbusTCP 237 通道绑定,
V1–V12 全 PASS;真实 HMI 截图 → 16 控件 spec → 全 PASS(详见
HANDOFF §9.1.4 / §9.1.5)。
⑦ mcgs-mcp server(任何 AI Agent 程序化调用层)
mcgs-tools/mcp_server.py(FastMCP / stdio)把工具链包成 17 个 tool,
与 mcgs-file-create Skill 互补不冲突:Skill = 知识/契约层
(Agent 知道「怎么写合法 spec、走什么流程」);MCP server = 调用层
(tool schema 直接调,输入/输出结构化)。
mcgs_health / check / build / verify / inspect / export / preview / textfit /
templates / scan / kinds / native_status / compile_intent / image_to_spec
内部统一 subprocess 调 mcgs.py CLI,复用经三关验收的管线;
双解释器隔离(MCGS_TOOL_DIR + MCGS_PYTHON);生成侧完全离线。
native 写操作刻意不暴露(与 serve 安全姿态一致)。
各宿主(WorkBuddy / Claude Desktop / VS Code)的 mcp.json 片段见
mcgs-tools/MCP_SERVER.md。
人工精修模板的收录与复用
工具链加速的是脚手架阶段;条件动作、对象方法调用、工艺细节这类能力, 人工在组态软件里做好 → 收录成母版 → 反复复用,比硬啃逆向划算得多。
python mcgs.py catalog add button <精修件.mcp> <窗口名> 0x5027 <序号> --as 条件动作
python mcgs.py catalog add-window <精修件.mcp> <窗口名> # 整页入库
# spec 里取用:{"controls": [{"type": "button@条件动作", "window": "主页"}]}
完整规程见 docs/人工精修模板的收录与复用.md。
来源与致谢
这个仓库站在别人的肩膀上。有三处移植件,都是原作者无偿公开的成果:
| 移植件 | 来源 | 作者 | 许可 |
|---|---|---|---|
条件脚本字节码(mcgslib/script/)+ fail-closed 纪律蒸馏(TESTING.md §4.4) |
mcgs-mcp-editor | Babel36acl | GPL-3.0-or-later |
原生字节层与控件原语(mcgslib/vendor/、mcgslib/primitives.py) |
mcgs-engineering-skill | SuperWater925 | MIT |
实机验证知识 C1–C6 + 在线原生桥资产(mcgslib/semantics_extra.py、assets/pro-native-bridge/) |
同上(references/ 与 assets/) |
SuperWater925 | MIT |
关于 mcgs-engineering-skill
2026-11-07,「零母版从零造控件」这条能力是从 mcgs-engineering-skill 移植来的。 原作者 SuperWater925 把 MCGS Pro 的原生窗口结构逆向成了 20 个纯 Python 字节模块, 并做了一份「脱敏原语库」,让工具能不靠母版直接造出标签、按钮、输入框。
移植时改了三处,都不动业务逻辑:去掉上游 sys.path 注入与 parents[3] 硬编码路径、
把模块间的扁平 import 改成包内相对导入、补上项目自己的护栏与中文类型名。
每一个开发者都不容易。 能把厂商私有格式逆向到「能批量生成工程」这一步,需要的是大量试错与耐心。 SuperWater925 把这份成果开源出来,本仓库才有「零母版造控件」这条能力。 这份致谢就是这份致谢的全部意思——我们不要求任何人给任何项目点 Star, 不设 Star 门槛,不写「必须 Star 才能用」的条款。 开源成果该被使用,也该被署名;至于要不要点 Star,那是使用者自己的自由。
关于 mcgs-mcp-editor-skill(V0.8.17 纪律蒸馏)
条件脚本字节码层(Unicorn 仿真原厂 x86 VM + 原厂编辑器代码生成,明细见 THIRD_PARTY.md) 是本仓库从 mcgs-mcp-editor-skill 移植来的移植件。 2026-11-13 又从该仓库蒸馏了方法论与门槛纪律(无代码移植):构建输出防覆盖 (「输出文件须为新路径」)、解析分母(「拒绝窗口不得当零控件」→ verify V13 + scan/export 分母)、 V 规则内存损坏负例矩阵(「坏文件不进宿主或设备」)、证据分层表与 skill 同步纪律—— 全部固化进 TESTING.md §4.4 与对应代码(V0.8.17)。
两个仓库互为引用:对方的 variable-ids.md 引用了本仓库的变量 id 机制;
本仓库的 mcgslib/script/ 移植自对方。
来源清单、移植改动与 SHA256 钉死值见 mcgs-tools/THIRD_PARTY.md。
验收底线
生成物必须通过 MCGS Pro 组态软件 打开 / 编译 / 仿真下载 三关; 静态验证(V1–V13)是前置闸,不能替代组态实测。
两条交付规矩(见 TESTING.md §4.2):
- 验收件交付到组态未锁过的新路径 —— 组态打开工程会锁文件, 期间若工具链覆盖同名文件,组态另存会用内存里的旧状态写回,把新产物冲掉。
- 反馈带控件名 + 报错原文 —— 同一现象可能有多条根因,凭印象容易修错地方。