cr-st-expert：一本给 AI 看的《企业级ST标准化编程规范手册》

上一篇介绍的 SyncBridge让 CODESYS 工程代码进入 AI 工作流它把 CODESYS 工程里受支持的对象导出成 AI 和 Git 能读懂的文件让工程师看清修改差异再决定哪些内容写回 IDE让代码写回达到“工程师级的安全、可控”。工程和 AI 的工作流连接起来以后不管你是自动化工程师还是技术部门负责人亦或是公司的老板以下三个非常实际的问题你是否认真思考过很多资深或经验丰富的自动化工程师通常都有或多或少的“代码洁癖”不论你使用文本语言还是图形化语言他们都对程序结构、代码工整、注释、变量命名等的规范都有近乎“偏执”的迷恋和坚持大佬之所以是大佬他们的代码就像状元的卷面整洁得让人舍不得打勾就像蜜蜂的蜂巢结构规整得令人肃然起敬首先我自豪地承认我一直严格要求我自己向大佬看齐其次我坚信只有这样追求才能练就非凡的代码能力。在我走访咨询过的这么多声称将要或者已经在推动全方位“企业标准化”落地的公司中很长时间过去了就连推动程序代码标准化都磕磕绊绊、举步维艰。有多少推动标准化的负责人抱怨着“我们公司为了推动标准化有模板、有文件、有规定什么都有但张工、李工、王工都各个阳奉阴违现在程序功能迭代、人员离职接手程序全都是头疼的问题那个xx工写的程序自带‘加密’功能换了谁都看不懂这个项目实施周期紧张得不得了最后实在没办法又花了几个w的冤枉钱把他请过来先把这个项目应付过去”……诸如此类。如果你已经使用过AI来进行ST代码辅助编程你一定会发现AI 写出来的代码看起来像 ST写回 CODESYS IDE 后却各种报错或者即便编译通过了执行逻辑仍然不对、注释永远不满足我的要求、缩进换行五花八门……怎么办cr-st-expert的作用针对以上实际的问题和痛点我基于大佬的习惯、个人的经验以及适合CodeSys平台ST编程的规则等整理成了 cr-st-expert。cr-st-expert 是一套独立的 CODESYS ST 编程规范技能它就是按照极高的工程级标准和要求整理出来的一本给AI看的《企业级ST标准化编程规范手册》让 AI 写代码、改代码、审查代码时有规则可查。用大白话说没有这个技能AI 也照样能写 ST有了这套资料AI 能够按照工程师级的统一标准、高质量、更准确、可复用地完成代码编写、修改和检查。懂 IEC 标准还要懂 CODESYS 的平台规则首先希望大家能了解CODESYS 毫无疑问实现并满足 IEC 61131-3 标准同时在标准之外还有很多语法、关键字等是平台或者厂家独有的拓展。因此AI就算已经完全吃透IEC61131-3标准但是它对各个平台或厂家的独有的知识和规则是没有完整认知的这就导致了前面提到的”AI看似会写ST“的幻觉当遇到这些拓展规则和知识的时候AI很可能出现遗漏、混用、乱编的情况最终导致代码写回IDE出现报错。因此懂通用 ST不等于能准确使用 CODESYS 的全部语法和平台规则。cr-st-expert 将 CODESYS 平台工程规范与已整理的部分平台规则明确交给 AI让生成、修改和审查有据可查。例如AND_THEN是 CODESYS 文档明确标注的标准扩展全局变量的限定访问、严格枚举等也有具体使用限制。CODESYS 官方说明同样的功能按规范写出来有什么不同cr-st-expert一共对八类规则进行了总结下面就带大家看一看每一类规则约定什么、使用前后代码怎样变化、工程师得到什么一起对照。01 命名与接口PascalCase 匈牙利命名法对象用 PascalCase帕斯卡命名法每个单词首字母大写配合类型前缀例如FB_DelayAlarm、F_CalculateAverage、PRG_Main。前缀后只保留一个分隔下划线不写成FB_Delay_Alarm。变量用匈牙利命名法类型前缀小写、后续单词首字母大写例如 BOOL 用b、INT 用i、DINT 用di、REAL 用r、TIME 用t常量统一用cn。自定义接口统一为bEnable、bBusy、bError、diErrorID等输入说明安全默认值、单位和边界外部库固定参数保留原名。未按规范整理用途要靠猜FUNCTION_BLOCK alarm_delay VAR_INPUT enable : BOOL; delay : TIME : T#2s; END_VAR VAR_OUTPUT error : BOOL; errorNo : DINT; END_VAR按 cr-st-expert 整理接口含义明确FUNCTION_BLOCK FB_DelayAlarm VAR_INPUT bEnable : BOOL : FALSE; // 使能FALSE 时复位 tDelay : TIME : T#2s; // 延时连续成立时间 [s] END_VAR VAR_OUTPUT bError : BOOL; // 故障发生错误时置位 diErrorID : DINT; // 错误码0 表示无故障 END_VAR收益看名字就知道对象种类、变量类型和接口含义减少“同一功能各起各名”。这是统一命名的工程约定修改已有公共接口时要先确认兼容性并同步调用方。02 注释与格式工整更能交接四空格缩进与列对齐禁止 Tab变量声明的:、:、注释按块对齐命名参数一行一个输入:和输出对齐。工程语义注释使用//、///变量注释采用“概括说明”物理单位用[unit]关键逻辑交代工况、公式、边界或异常原因不机械翻译每行代码。实现区统一标记为// IMPLEMENTATION 。未按规范整理逻辑挤在一起IF bEnable THEN bAlarm:tonDelay.Q; // 赋值 ELSE bAlarm:FALSE; END_IF;按 cr-st-expert 整理说明实际工况// 禁用时撤销对外告警 IF bEnable THEN bAlarm : tonDelay.Q; // 报警置位 ELSE bAlarm : FALSE; END_IF;收益相同逻辑更容易读懂。前版的问题是可读性不是功能一定错误。03 对象与文件组织单一职责FBFUNCTIONPROGRAM 各司其职先选对程序单元POU定时、锁存等需要跨周期保存状态的功能用FB温度换算等无状态计算用FUNCTIONPROGRAM负责顶层任务入口和协调。按单一职责原则组织避免一个主程序把计算、状态、诊断全部包办。再把职责落实到文件顶层对象与 ST 文件一一对应DUTs 放枚举和结构体GVLs 放共享变量POUs 下分别组织 FBs、FCs、PRGs。下面用“延时告警温度换算”看文件怎样变化。未按规范整理职责和文件混在一起Main.st 任务入口、计时、告警、温度换算 Tools.st 枚举、结构体、共享变量混放按 cr-st-expert 整理每个对象有明确职责DUTs/ E_AlarmState.st ← 告警状态枚举 GVLs/ GVL_Status.st ← 共享状态 POUs/PRGs/ PRG_Main.st ← 周期调用与协调 POUs/FBs/ FB_DelayAlarm.st ← 保存定时、告警状态 POUs/FCs/ F_CelsiusToFahrenheit.st ← 无状态换算收益改延时告警就定位到FB_DelayAlarm复用温度换算就找对应 FUNCTION不必从主程序中剪出整段逻辑。这是源码文本组织建议既有 IDE 工程可保留原布局内置交换格式将 Method、Action、Property 聚合在父 FB 中不是要求在 IDE 中把所有对象合成一个。04 类型与计算计算过程更明确显式类型转换与数值边界选择符合范围的 INTDINT、REALLREAL用INT_TO_REAL等明确转换窄化转换先检查范围不能把转换函数当作防溢出保护。浮点容差与除零保护REALLREAL 不直接用相等判断改用ABS(差值) 容差除法先检查除数计数和无符号长度运算先检查上下限。未按规则核对整数先除再赋给 REAL// iTotal、iCount 均为 INT rAverage : iTotal / iCount; bAtTarget : rAverage rTarget;按 cr-st-expert 整理先转 REAL再检查除数IF iCount 0 THEN rAverage : INT_TO_REAL(iTotal) / INT_TO_REAL(iCount); END_IF; bAtTarget : ABS(rAverage - rTarget) cnAverageTol;收益避免把整数除法的小数损失、除零和浮点尾差留到调试时排查。cnAverageTol应按实际单位和精度确定除数为零时示例保留原值实际工程须约定是否清零或报错。05 扫描周期条件解除也能更新状态型功能块与实例生命周期TONTOFTP、R_TRIGF_TRIG 每扫描周期稳定调用实例放在能保持状态的VAR不放VAR_TEMP。一个被检测信号对应一个触发器实例不复用同一实例检测多个信号。调用后读取结果先调用、再读取.Q内部判断不为.Q创建多余中转变量公开输出仍可以使用含义明确的变量。TON 用ton前缀上升沿实例用rtrig不是全部统称fb。未按规则核对条件解除就跳过调用IF bCondition THEN tonDelay( IN : TRUE, PT : tDelay ); END_IF; bAlarm : tonDelay.Q;按 cr-st-expert 整理每周期传入当前条件tonDelay( IN : bCondition, PT : tDelay ); bAlarm : tonDelay.Q;收益条件解除时 TON 接收到 FALSE执行复位。外层对象也须按周期调用不调用不能当成已经复位。TON 官方说明06 状态与诊断异常有出口严格枚举与限定访问状态用 ENUM 表达带strict和qualified_onlyINT 底层的成员用i前缀例如E_Mode.iRun成员值唯一不随意与整数混算。可诊断状态机CASE 必须有 ELSE区分进入动作与持续动作等待反馈要有超时。错误使用bErrordiErrorID保留触发状态和关键输入原因未解除时不盲目复位。未按规则核对未处理非法状态CASE eMode OF E_Mode.iIdle: bBusy : FALSE; E_Mode.iRun: bBusy : TRUE; END_CASE;按 cr-st-expert 整理保留异常出口CASE eMode OF E_Mode.iIdle: bBusy : FALSE; E_Mode.iRun: bBusy : TRUE; ELSE // 1001非法状态示例码 bBusy : FALSE; bError : TRUE; diErrorID : 1001; eFaultState : eMode; END_CASE;收益从“出错了”变成“哪个状态出了什么错”便于调试和交接。eFaultState保存触发状态1001 是示例错误码实际枚举定义、错误锁存和复位条件须按业务完善。07 边界与共享数据访问前先核对条件防御性编程数组访问先检查下标字符串操作先检查容量指针先判空并确认长度、生命周期。需要短路保护时采用已确认的AND_THEN不能把普通 AND 当作短路运算。共享数据所有权与同步同一个 FB 实例不由多个任务同时调用跨任务数据明确写入方和一致性策略。大型结构体优先用VAR_IN_OUT引用传递实际同步机制按目标平台确认。未按规则核对下标直接进入数组// aValues 下标范围为 0..9 rValue : aValues[iIndex];按 cr-st-expert 整理限定可访问范围IF (iIndex 0) AND (iIndex 9) THEN rValue : aValues[iIndex]; ELSE bError : TRUE; END_IF;收益超出范围不再直接访问。此例只展示下标保护跨任务共享数据仍需核对读写职责和同步方式不能据此宣称线程安全。08 依赖声明与审查不把猜测当事实库依赖契约文件头写LibraryId或LibraryIdVersion多个库用英文分号分隔无外部库写“暂无”未知版本标为待确认不编造函数名、参数或版本号。有范围的规范审查结论包含检查范围、问题位置、原因、建议和未确认项。代码片段只能得出片段结论人工审查、可选脚本、编译和功能测试分别说明。未按规范整理没有交代依赖FUNCTION_BLOCK FB_DelayAlarm VAR tonDelay : TON; END_VAR按 cr-st-expert 整理依赖可追溯/// 功能 : 条件连续成立后告警 /// 库依赖 : Standard // 库版本待目标工程确认 FUNCTION_BLOCK FB_DelayAlarm VAR tonDelay : TON; END_VAR收益接手时知道需要核对哪个库。依赖声明不证明库已安装、接口正确或编译通过这里仅展示声明区。这就是那句大白话的具体落点把统一标准落实到名字、注释、组织和执行检查上让代码更容易读、比、改也更容易继续维护。怎么用如果你还没接触过 Skill可以把它理解成一套给 AI 编程助手读取的工作说明和配套资料。cr-st-expert 包含入口文件、详细规范、模板和示例安装时应保留完整目录不能只复制入口文件。把完整技能目录部署到支持 Skill 的 AI 助手中具体位置以助手的技能配置为准。确认它已识别、加载cr-st-expert就可以用普通的话提出任务。基础使用不要求 Python、CLI、ST Graph 或运动技能附带检查脚本可以选择使用。写代码请按 cr-st-expert 编写一个功能块实现【功能需求】。输入输出和工况是【具体条件】。缺少的信息先指出不要自行猜测。改代码请按 cr-st-expert 整理以下代码保留现有公共接口和业务逻辑。说明修改点涉及逻辑变化的部分先列出建议。审查代码请按 cr-st-expert 审查以下代码列出问题位置、原因和修改建议。暂不修改无法确认的内容单独说明。它和 SyncBridge 怎么搭配和分工两者搭配时SyncBridge 导出受支持的对象 → AI 按 cr-st-expert 审查或修改 → Compare 核对差异 → 确认写回 IDE → 编译和功能测试。SyncBridge 负责工程对象与文件之间的同步cr-st-expert 提供编程规范和审查依据。如果暂时不用 SyncBridge也可以直接把一段 ST 交给 AI 做规范审查。它不是编译器也不承诺零报错cr-st-expert 让代码更规范帮助减少错误它不是编译器不负责确保所有代码完全零报错。AI 仍可能漏检或误解需求技能也没有覆盖全部平台版本、库接口和业务场景。它不承担庞大的 CODESYS 库的完整接口知识不负责设备连接、仿真或下载。最终是否能编译、是否满足功能和现场要求仍需在实际工程中验证并由工程师复核。遇到不明确的库接口需要提供实际资料遇到不同平台或版本的行为差异需要在目标环境中确认。符合规范、编译通过、功能正确是三个不同的检查结果不能互相替代。规范审查也不能保证代码一定正确。模型可能漏看问题、误解要求因此生成结果仍然需要复核。符合规范、编译通过、功能正确不能互相替代。系列导航上一篇《SyncBridge一个 CODESYS 工程与 AI 之间工程师级的同步工具》介绍工程同步这一篇介绍编程规范。配套视频将演示技能安装、审查和修改。开源分享我把cr-st-expert 作为一个开源技能分享给大家。完整技能目录、部署说明和使用示例已经上传到 GitHubGitHub 仓库BenPeng0205/cr-st-expert如果你准备尝试第一步不必很大选一个自己熟悉的功能块让 AI 按 cr-st-expert 审查一次。看看它指出的问题是否成立修改建议是否保留了原来的功能还有哪些要求需要补充。SyncBridge 把工程代码带进 AI 工作流cr-st-expert 则把编程要求也带进来。我希望这套规范能帮助大家少重复交代一些要求让生成结果更容易阅读、比较和继续维护。