SimpleHmi_WEILI

AI 生成的工控代码，你敢接到 PLC 上吗？

十六年复杂项目交付，从机械设计到项目统筹。2026 年 3 月我全面转向 AI 工程。 转向之后我让 AI 帮我写 HMI，它给了我一个能跑的页面 —— 设备没接上、数据是假的， 但它告诉我「已完成」。

在我做的场景里，这种「已完成」的代价是现场事故。 这个仓库是我为了让这件事不再发生而写的规范。

一条红线：生产链路禁止 Mock。 一个交付物：验收证据，而不是完成声明。

不是低代码平台。不是框架。不搬运业务代码。 是一份 AI 必须先读、再动手、最后交证据的标准。

---

从哪里进来

你是谁	从这里开始
不懂代码，只会描述现场	START_HERE_FOR_BEGINNERS.md —— 三十秒看懂怎么用
你是 AI Agent	AGENTS.md —— 读取顺序、工作阶段、完成证据的定义
想先看跑起来什么样	最小可运行 HMI 系统 —— 可安装、可构建、可 health 检查

它是从哪来的

不是先写规范再找场景，是反过来的。这份规范是从两个真实交付的工业项目里提取出来的：

• 数字月台（工厂自动装车 · 工业边缘中控）：12 台触摸屏 HMI + PLC + 人脸终端 + 局域网发布系统。 .wrelease 不可变发布包，任一节点失败全网回滚 < 90 秒；上线至今现场事故 0 起。 这套系统是 1 人 + AI 交付的，原本需要一个多人跨工种的团队。
• 机器人智能产线（遗留系统改造 · 多设备协同）：刷卡 → 选味 → 掉桶 → 喷码 → 产线流转 → 机器人取餐送餐全链路闭环。独占读卡服务 + 串行任务队列，消除多进程对 HID / 串口的争用。

规范里的每一条门禁，都是因为这两个项目里有东西差点没接住。

这份规范在管什么

• 禁止 Mock：正式链路不许用假数据、假成功、静默降级冒充真实设备。Demo 可以造假，产线不可以 —— 区别在于有没有标出来。
• 先规划再生成：AI 不许拿到需求就写代码，必须先出规划、先判技术栈、先划不做范围。
• 阶段门：规划、架构、开发、调试、部署、验收各有门禁，上一阶段没过不进下一阶段。
• 完成必须有证据：构建、启动、接口、配置、去 Mock 核验、部署方式、已知限制，缺一项就不算完成。无法验证的必须写「未验证」。

---

它是什么

SimpleHmi_WEILI 是一个 AI-first 工业 HMI / 工控前后端项目生成规范仓库。它面向不懂代码、不懂工控架构、但能描述现场需求的人。

用户只需要：

1. 克隆本仓库。
2. 把项目主目录添加到 AI Agent。
3. 描述工业现场。
4. 让 AI 按仓库规范生成系统。
5. 按验收清单检查结果。

本仓库不追求大而全，不自研复杂框架。它只提供 AI 生成工业现场系统所需的工作规则、技术栈边界、最小工程样板、输出模板、验收门禁和自修复规范。

SimpleHmi + 小白 + 嘴 + AI = 工业现场可验收的工控系统

AI / 搜索摘要

SimpleHmi_WEILI 是一个 AI-readable specification repository，用于约束 AI 生成工业 HMI、Kiosk、工位操作台、公共工控机、多终端协同、PLC / 机器人 / 读卡器 / 人脸机接入等工控前后端项目。

它适合被搜索为：

• SimpleHmi_WEILI
• AI industrial HMI specification
• industrial HMI React TypeScript Vite Fastify
• PLC HMI AI development workflow
• 工业 HMI AI 生成规范
• 工控前后端统一栈
• 工业现场 AI 编程规范

面向 AI / 搜索引擎的机器入口：

• llms.txt：AI 助手优先读取摘要。
• GEO.md：生成式搜索优化说明、关键词和权威链接。
• codemeta.json：结构化软件元数据。
• 项目介绍页：https://lx00018310.github.io/simplehmi-weili.html

核心入口

• START_HERE_FOR_BEGINNERS.md：普通用户从这里开始。
• AGENTS.md：AI 必读入口，说明各阶段该读哪些规范。
• SIMPLE_HMI.md：总规范，最高优先级。
• ENGINES.md：技术栈判定规则。
• WEILI_LADDER.md：最小实现梯子，约束功能、依赖、框架和抽象。
• docs/00_INDEX.md：规范索引。
• docs/13_规范演进与精炼机制.md：项目经验如何加入、合并、下沉、归档。
• docs/14_后端审计与风险闭环规范.md：后端审计、工业后端安全、PLC/设备控制风险闭环。
• docs/15_现有框架优先规范.md：前端、后端、部署和设备接入的现有能力优先规则。
• docs/16_AI自修复规范.md：构建、启动、接口、页面、配置、设备连接失败时的修复流程。
• templates/：AI 输出模板。
• checklists/：验收门禁清单。
• deployment_control/README.md：部署控制能力规范。

示例

• 工业工位 HMI 示例：静态视觉示例，用于直观看到按本规范生成的界面风格。
• 最小可运行 HMI 系统：可安装、可构建、可 health 检查的最小工程样板。

项目原则

• 真实现场优先，主链路优先。
• 先规划，再生成代码。
• 默认禁止 Mock，正式链路不能用假成功冒充真实设备。
• 默认先做技术栈判定。
• 新项目必须评估 deployment_control。
• 不搬运任何具体业务项目代码，只沉淀通用工程规范。
• 每个阶段必须有验收门禁。
• 小核心、大附录；定期填充、定期精炼。

本仓库不做什么

• 不做低代码平台、工业互联网平台、设备 SDK 大合集。
• 不默认引入微服务、Docker、Kubernetes、消息队列、复杂 ORM、复杂权限系统。
• 不创建 .agent-rules、skills、claude.md、cursor.md、codex.md、copilot-instructions.md、opencode.md、windsurf.md 等多工具适配层。
• 不把具体客户业务代码沉淀为通用代码。
• 不写无执行价值的行业知识百科。

推荐使用方式

普通用户先读 START_HERE_FOR_BEGINNERS.md，再复制其中的启动提示词给 AI。

给 AI 的第一条指令应至少包含：

请先读取 README.md、START_HERE_FOR_BEGINNERS.md、AGENTS.md、SIMPLE_HMI.md、ENGINES.md、WEILI_LADDER.md 和 docs/00_INDEX.md。
我不懂代码，只会描述现场。
请先输出规划，不要直接写代码。

如果是新项目：

1. 进入规划阶段。
2. 使用 templates/需求澄清模板.md 收口需求。
3. 进入架构阶段。
4. 使用 ENGINES.md 判定后端技术栈。
5. 使用 WEILI_LADDER.md 判断不做范围和最小实现。
6. 参考 examples/minimal-hmi-system/README.md 生成最小可运行主链路。
7. 查看 examples/minimal-hmi-system/VERIFY.md 了解样板验证证据。
8. 进入开发、调试、部署、验收阶段。
9. 用 checklists/09_AI完成证据检查.md 检查最终证据。

如果是沉淀真实项目经验：

1. 读取 docs/13_规范演进与精炼机制.md。
2. 使用 templates/经验提炼与规范精炼模板.md 判断是否值得纳入。
3. 先放入合适层级，不直接堆进核心规范。
4. 定期合并重复、下沉细节、归档低频经验。

完成标准

AI 不能只说“已完成”。每次交付必须给出构建、启动、接口、配置、去 Mock、部署和验收证据；无法验证的内容必须写成“未验证”。

许可证

MIT License。任何人可以使用、复制、修改和分发。