renode-stm32/AGENTS.md

RENODE-STM32

完成板卡程序的完全仿真

架构与职责

C#写法

• 优先使用当前目标框架支持的最新C#语法简化代码，但不能牺牲业务语义 可读性和并发安全
• 单语句控制分支省略大括号并保持紧凑，能够使用表达式体时不要展开为冗长写法
• 不要过度抽象，仅被一个方法调用一次的private方法通常应内联到调用方，并使用有效的行间注释说明流程
• 参数数量较少且单行长度合理时保持在同一行，不要为了排版把参数列表拆成多行
• 连续声明且共同描述组件状态或协作依赖的字段需要在同一列添加对齐的行尾注释
• 连续声明的const常量必须在同一列添加对齐的行尾注释，并分别说明协议或业务含义
• 只有显式字段仅用于一个属性存储且不被其他方法直接访问时才使用C#的field关键字消除
• MVVM和响应式状态对象优先使用源代码生成器简化通知属性

文档与注释

• 注释使用中文且行尾不添加中文标点
• 所有类型都必须添加说明实际职责的XML summary
• 所有public成员必须完整说明参数 返回值 异常和关键行为边界
• 非public成员不以可见性决定是否添加注释
• 承担状态转换、并发同步、队列策略、重试判断、生命周期或异常边界的非public成员必须添加XML summary
• 简单自动属性 直接字段访问和语义完全显然的单行转发不机械添加无价值注释
• 复杂方法需要在关键阶段添加说明原因和行为边界的有效行间注释

summary注释格式

/// <summary>
/// 当前是否已经停止接受新的命令
/// </summary>

注意！不要写成一行了

依赖与日志

Git提交

• Commit标题使用Conventional Commits格式 <type>[!]: <description> 默认不添加(board)等scope 除非用户明确要求
• Commit标题和正文使用中文 标题只说明本次提交的核心结果
• 标题之后空一行 正文使用多个-列表项分别说明实际变更 不把多个子系统压缩成一个长段落
• 正文所有内容均使用-列表项 包括限制和补充说明 不得追加独立段落
• Commit只描述实际变更 不写测试结果 验证结论 通过数量或构建检查输出 这些信息仅在对话中汇报
• 每个列表项写清楚改变了什么行为或组件 不使用improve optimize等无法单独验证的概括词
• 存在公开API或配置兼容性变化时在type后添加! 并在正文末尾添加BREAKING CHANGE:说明迁移影响
• 提交前必须确认构建 自检和git diff --check结果 提交后必须确认工作区状态和最终提交内容

命令调度核心规则

• 命令调度分为Pending缓存和最多五项的Ready执行窗口 Consumer只按Ready顺序执行完整原子命令
• Control命令优先于Maintenance Foreground和Scheduled并使用独立预留容量 普通容量满载不得阻止停止命令准入
• Foreground容量满载时直接返回Rejected 不允许提交方无限等待或静默丢弃
• Foreground按数字优先级降序排列 同优先级必须保持全局Sequence对应的FIFO
• Stop和EmergencyStop通过Tag声明能够失效的旧命令 Stop只失效运动命令 EmergencyStop失效板卡行为命令
• EmergencyStop只是一次性向板卡写入A012=1 调度器不维护持续急停状态也不引入解除急停命令
• 一条命令中的多次寄存器交互始终视为一个不可拆分原子命令 Control只能调整尚未开始命令的顺序
• 失败命令等待重试时形成顺序屏障 后续Foreground不能越过 之后到达的匹配Control可以终止该重试
• Scheduled按稳定Key最多保留一个等待项 全部Scheduled在Ready中最多占一个位置且默认只在前台空闲时执行
• Scheduled连续延期三次 等待超过自身周期三倍或累计执行失败三次后晋升到Foreground之前 成功执行后清空债务
• 调度语义验证放在Laserweld.Board.Demo的Program入口中 不再向Command测试项目添加新测试
• Maintenance不是定时任务 连接正常时由真实业务命令和状态轮询自然证明通信可用
• Consumer发布每次原子命令的成功或失败 Modbus桥接层只累计连续疑似通信失败且任意成功通信立即清零
• 连续疑似通信失败达到ConnectionManagerOptions.FailureThreshold后才提交一次Maintenance探测 探测失败进入关闭和重连流程
• Consumer唤醒必须使用容量为一的合并异步信号 队列状态变化次数不得累计为历史令牌并在空队列时造成忙循环
• 六轴机械配置按X到C读取各轴配置块前四个保持寄存器 写入必须逐寄存器使用Modbus功能码0x06且不能使用0x10连续写入

标准示例

private readonly ICommandCodec _codec;                  // 将板卡命令转换为有序协议交互
private readonly ICommunicationChannel _channel;        // 实际发送和接收协议字节

private const ushort MoveSpeed = 10;             // 方向键移动使用的板卡速度原始值
private const double DirectionalTarget = 1_000;  // 持续移动使用的远端绝对坐标

/// <summary>
/// 当前是否已经停止接受新的命令
/// </summary>
private bool IsStopping
{
    get => Volatile.Read(ref field);
    private set => Volatile.Write(ref field, value);
}

/// <summary>
/// 判断异常链中是否包含超时异常
/// </summary>
/// <param name="exception">需要检查的异常</param>
/// <returns>异常链中包含超时异常时返回true</returns>
private static bool IsTimeout(Exception exception) =>
    exception is TimeoutException
    || exception.InnerException is not null
    && IsTimeout(exception.InnerException);

Commit流程规范

默认使用中文commit提交

1. 你需要先判断的当前的diff内容
2. 确保没有需要 gitignore 的内容被漏添加
3. 执行 git add . 添加所有内容
4. 编写合适的commit

典型commit规范如下

feat: 添加任务自动化程序和相关UI设计

- 修复了自动化前置条件错误问题
- 增加了xxx
...

总结来说，一个合格的commit为

<tags>: ... (oneline)

- summary1
- summary2
...

外部参考