用蓝图生成 Qt 工程：把 AI 代码放进可审查的流水线

Qt Blueprint Generator 是一个用蓝图描述 Qt 6 Widgets 应用的桌面工具。它的目标不是做完整的 IDE，而是把“设计意图”变成可审查、可构建、可导出的工程。

为什么用蓝图作主数据源

如果让 AI 直接改代码，最大的问题是：改动不可比较，也难以判断哪些部分是契约、哪些部分是实现。这个项目把蓝图作为主数据源，节点、端口、连线和属性先落成结构化数据，再由确定性生成器维护公共契约与工程骨架。

一个蓝图工程包含两个文件：blueprint.json 保存语义，layout.json 保存画布位置。移动节点只改变布局，不会改变生成的中间表示；这样评审时可以只关注语义差异。

生成流程

蓝图设计 → 校验 → 生成 Candidate → 人工 Review
        → Accept / Reject → Build → Export

Candidate：AI 生成的代码先进入候选区，不会直接覆盖正式工程。
Review：逐文件对照当前实现与候选代码，可以选择接受、编辑后接受或拒绝。
Build：构建需要显式触发，使用真实的 CMake 工具链。
Export：导出可以独立重新构建的工程，而不是只保留当前工作区。

这条流程的核心约束是：AI 不拥有最终写入权。公共契约、程序入口、构建配置等受保护内容由确定性系统维护；生成失败也不会自动清空旧工程。

确定性与 AI 的边界

项目把职责拆成几层：

层	职责
Qt 编辑器	画布、属性、文档生命周期、候选审核
生成服务	校验、写候选、接受授权、脚手架与构建
目标插件	把蓝图语义 lowering 成具体目标工程
协议工具	Blueprint v2 与插件声明的离线校验

外部代码的导入也是同样的思路：C/C++ 文件以只读黑盒模块接入，绑定接口契约并校验 SHA-256；编辑器不假设自己可以安全地重写这些文件。

当前能力与限制

Phase 1 的运行时只接受一条线性链：

Start → 零个或多个 Logic Module → 可选的唯一末端 UI Page → End

Decision、External Code、多 End 等节点仍然可以编辑，但不属于这一阶段的运行时生成范围。节点编辑能力不等于运行时能力，这是 README 里反复强调的边界。

插件平台仍是 Draft：当前只实现了 TypeScript/Node 的声明校验与最小内存 Registry，不执行插件代码，也没有接入 Qt GUI。长期方向是“编辑器和目标插件分离”，但在协议冻结前，不把提案当成已交付能力。

构建与测试

项目使用 C++17、Qt 6 Widgets / Network、CMake 和 Ninja。Windows 下建议把构建目录放在纯 ASCII 路径，避免 MinGW 与 AutoMOC 在中文路径上出问题。

cmake -S . -B $buildRoot -G Ninja `
  -DBUILD_TESTING=ON `
  -DCMAKE_PREFIX_PATH="$qtRoot"
cmake --build $buildRoot
ctest --test-dir $buildRoot -C Debug --output-on-failure
& (Join-Path $buildRoot 'BlueprintEditor.exe')

CTest 使用 Fake AI 或离线网络替身，不读取真实密钥，也不产生模型费用；需要调用真实模型的集成程序不会注册进自动测试。

复盘

这个项目最有价值的部分不是“让 AI 写代码”，而是把 AI 放进一条有边界、可回滚的流水线：

结构化输入优先于自然语言提示。
生成结果先成为候选，再经过人工确认。
契约、入口和构建配置由确定性系统维护。
明确写出“当前不支持什么”，比模糊地承诺“未来都可以”更重要。

代码与文档采用 MIT License；Qt 和其他第三方依赖仍遵循各自许可证。