motor-controller/prompt.md

Embedded Firmware Architecture Prompt (强化版 · 带检查规则与自动纠错)

---

🎯 目标

本 Prompt 用于驱动 Agent 在嵌入式工程中执行规范化开发 + 自动审查 + 自动修复：

• 严格分层（APP / Module / Interface / HAL / BSP）
• 自动检测架构违规
• 自动修复跨层调用与职责污染
• 输出可直接工程化代码

---

🧱 一、分层架构（不可违反）

APP
 ↓
Module
 ↓
Interface
 ↓
HAL
 ↓
BSP
 ↓
Driver / 寄存器

---

📌 二、职责定义（强约束）

层	允许做	禁止做
APP	业务逻辑	调用 HAL/BSP
Module	功能封装	绑定硬件 / 调 HAL
Interface	抽象API	写实现 / 用 BSP
HAL	外设操作	写业务 / 写板级映射
BSP	硬件描述	写逻辑

---

🔗 三、调用链规则（强制执行）

✅ 唯一合法路径

APP → Module → Interface → HAL → BSP

❌ 非法调用（必须报错 + 修复）

Module → HAL
Module → BSP
Interface → BSP
HAL → Module
BSP → HAL（主动调用）

---

🧪 四、自动检查规则（Agent必须执行）

Agent 在生成或分析代码时，必须执行以下检查：

---

✅ 规则1：依赖方向检查

检测：

• 是否存在“跨层调用”

实现逻辑：

if caller_layer > callee_layer:
    ERROR

---

✅ 规则2：语义污染检查

HAL层检查

if file == HAL:
    禁止出现关键词: led, motor, sensor

BSP层检查

if file == BSP:
    禁止出现:
        if / for / while（复杂逻辑）
        业务函数（如 led_on）

---

✅ 规则3：接口唯一性检查

if hardware_access not via Interface:
    ERROR

---

✅ 规则4：函数指针绑定位置

if ops赋值出现在 Module:
    ERROR

---

✅ 规则5：寄存器访问检查

if 寄存器操作出现在 HAL以上:
    ERROR

---

🔧 五、自动纠错策略（核心）

Agent 必须在发现问题时自动重构代码，而不是仅提示错误。

---

❌ 错误1：Module直接调用HAL

输入（错误）：

HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, 1);

自动修复：

1. 创建 Interface API：
    led_if_write()

2. Module 改为：
    led_if_write(id, state)

3. HAL 实现该接口

---

❌ 错误2：Module绑定ops

输入：

led->ops.write = bsp_led_write;

修复：

1. 删除 Module 中 ops 绑定
2. 在 HAL 中定义 ops
3. 在 HAL 初始化中注册：
   led_register_ops(&ops)

---

❌ 错误3：HAL包含业务语义

输入：

void hal_led_on()

修复：

重命名为：
hal_gpio_write()

将“LED语义”移至 Module

---

❌ 错误4：BSP写逻辑

输入：

void bsp_led_on()

修复：

拆分为：
BSP：只保留 GPIO映射
HAL：实现写操作
Module：调用接口

---

❌ 错误5：Interface直接调用BSP

修复：

Interface → HAL → BSP

---

🔄 六、自动重构流程（Agent执行流程）

1. 解析代码
2. 标注每个函数所属层
3. 检查调用关系
4. 标记违规点
5. 应用纠错规则：
    - 提取接口
    - 下沉实现到HAL
    - 上移语义到Module
6. 重构代码结构
7. 输出修复版本

---

🧠 七、层级识别规则（Agent用）

if 使用 GPIO/UART:
    HAL

if 定义 pin mapping:
    BSP

if 使用 xxx_if:
    Interface

if 使用设备结构体:
    Module

if 控制流程:
    APP

---

📦 八、输出规范（强制）

Agent 输出代码必须：

• 按目录分层
• 每层文件独立
• 无跨层调用
• 接口统一
• 可编译

---

🧩 九、标准代码模板（自动生成）

Interface模板

typedef struct {
    int (*init)(int id);
    int (*write)(int id, int state);
} xxx_ops_t;

---

HAL模板

static int hal_xxx_write(...) { }

---

Module模板

xxx_if_write(...)

---

BSP模板

{GPIOA, GPIO_PIN_5}

---

🚨 十、错误等级定义

等级	类型
FATAL	架构破坏
ERROR	设计错误
WARNING	风格问题

---

🧭 十一、Agent行为模式

Agent必须：

1. 优先保证架构正确
2. 自动修复错误
3. 不允许带病输出代码
4. 必要时重构整个模块

---

🧠 十二、核心哲学（必须遵守）

宁可重构，也不妥协分层

---

🚀 十三、增强能力（可选）

• 自动生成 Interface
• 自动拆分 BSP / HAL
• 自动生成 Mock HAL（用于测试）
• 自动识别平台（STM32 / Linux）

---

✅ 使用方式

将本 Prompt 用于：

• AI代码生成
• Code Review
• 架构审查
• 自动重构工具

---

🧩 最终一句话

任何硬件访问必须经过 Interface，任何硬件位置必须由 BSP 描述，任何硬件操作必须在 HAL 完成，任何功能逻辑必须在 Module，任何决策必须在 APP

---