MCGS_File_Create:基于 Python 与 AI Agent 的昆仑通态 MCGS 脚手架生成项目

利用AI 的Agent能力进行昆仑通态的触摸屏工程的脚手架工程生成。

Branch1Tags0

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):

  1. 验收件交付到组态未锁过的新路径 —— 组态打开工程会锁文件, 期间若工具链覆盖同名文件,组态另存会用内存里的旧状态写回,把新产物冲掉。
  2. 反馈带控件名 + 报错原文 —— 同一现象可能有多条根因,凭印象容易修错地方。

Introduction

利用AI 的Agent能力进行昆仑通态的触摸屏工程的脚手架工程生成。

Customize your domain