368 lines
5.5 KiB
Markdown
368 lines
5.5 KiB
Markdown
# Embedded Firmware Architecture Prompt (强化版 · 带检查规则与自动纠错)
|
||
|
||
---
|
||
|
||
# 🎯 目标
|
||
|
||
本 Prompt 用于驱动 Agent 在嵌入式工程中执行**规范化开发 + 自动审查 + 自动修复**：
|
||
|
||
* 严格分层（APP / Module / Interface / HAL / BSP）
|
||
* 自动检测架构违规
|
||
* 自动修复跨层调用与职责污染
|
||
* 输出可直接工程化代码
|
||
|
||
---
|
||
|
||
# 🧱 一、分层架构（不可违反）
|
||
|
||
```text
|
||
APP
|
||
↓
|
||
Module
|
||
↓
|
||
Interface
|
||
↓
|
||
HAL
|
||
↓
|
||
BSP
|
||
↓
|
||
Driver / 寄存器
|
||
```
|
||
|
||
---
|
||
|
||
# 📌 二、职责定义（强约束）
|
||
|
||
| 层 | 允许做 | 禁止做 |
|
||
| --------- | ----- | ------------ |
|
||
| APP | 业务逻辑 | 调用 HAL/BSP |
|
||
| Module | 功能封装 | 绑定硬件 / 调 HAL |
|
||
| Interface | 抽象API | 写实现 / 用 BSP |
|
||
| HAL | 外设操作 | 写业务 / 写板级映射 |
|
||
| BSP | 硬件描述 | 写逻辑 |
|
||
|
||
---
|
||
|
||
# 🔗 三、调用链规则（强制执行）
|
||
|
||
## ✅ 唯一合法路径
|
||
|
||
```text
|
||
APP → Module → Interface → HAL → BSP
|
||
```
|
||
|
||
## ❌ 非法调用（必须报错 + 修复）
|
||
|
||
```text
|
||
Module → HAL
|
||
Module → BSP
|
||
Interface → BSP
|
||
HAL → Module
|
||
BSP → HAL（主动调用）
|
||
```
|
||
|
||
---
|
||
|
||
# 🧪 四、自动检查规则（Agent必须执行）
|
||
|
||
Agent 在生成或分析代码时，必须执行以下检查：
|
||
|
||
---
|
||
|
||
## ✅ 规则1：依赖方向检查
|
||
|
||
**检测：**
|
||
|
||
* 是否存在“跨层调用”
|
||
|
||
**实现逻辑：**
|
||
|
||
```pseudo
|
||
if caller_layer > callee_layer:
|
||
ERROR
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 规则2：语义污染检查
|
||
|
||
### HAL层检查
|
||
|
||
```pseudo
|
||
if file == HAL:
|
||
禁止出现关键词: led, motor, sensor
|
||
```
|
||
|
||
### BSP层检查
|
||
|
||
```pseudo
|
||
if file == BSP:
|
||
禁止出现:
|
||
if / for / while（复杂逻辑）
|
||
业务函数（如 led_on）
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 规则3：接口唯一性检查
|
||
|
||
```pseudo
|
||
if hardware_access not via Interface:
|
||
ERROR
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 规则4：函数指针绑定位置
|
||
|
||
```pseudo
|
||
if ops赋值出现在 Module:
|
||
ERROR
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 规则5：寄存器访问检查
|
||
|
||
```pseudo
|
||
if 寄存器操作出现在 HAL以上:
|
||
ERROR
|
||
```
|
||
|
||
---
|
||
|
||
# 🔧 五、自动纠错策略（核心）
|
||
|
||
Agent 必须在发现问题时**自动重构代码**，而不是仅提示错误。
|
||
|
||
---
|
||
|
||
## ❌ 错误1：Module直接调用HAL
|
||
|
||
### 输入（错误）：
|
||
|
||
```c
|
||
HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, 1);
|
||
```
|
||
|
||
### 自动修复：
|
||
|
||
```text
|
||
1. 创建 Interface API：
|
||
led_if_write()
|
||
|
||
2. Module 改为：
|
||
led_if_write(id, state)
|
||
|
||
3. HAL 实现该接口
|
||
```
|
||
|
||
---
|
||
|
||
## ❌ 错误2：Module绑定ops
|
||
|
||
### 输入：
|
||
|
||
```c
|
||
led->ops.write = bsp_led_write;
|
||
```
|
||
|
||
### 修复：
|
||
|
||
```text
|
||
1. 删除 Module 中 ops 绑定
|
||
2. 在 HAL 中定义 ops
|
||
3. 在 HAL 初始化中注册：
|
||
led_register_ops(&ops)
|
||
```
|
||
|
||
---
|
||
|
||
## ❌ 错误3：HAL包含业务语义
|
||
|
||
### 输入：
|
||
|
||
```c
|
||
void hal_led_on()
|
||
```
|
||
|
||
### 修复：
|
||
|
||
```text
|
||
重命名为：
|
||
hal_gpio_write()
|
||
|
||
将“LED语义”移至 Module
|
||
```
|
||
|
||
---
|
||
|
||
## ❌ 错误4：BSP写逻辑
|
||
|
||
### 输入：
|
||
|
||
```c
|
||
void bsp_led_on()
|
||
```
|
||
|
||
### 修复：
|
||
|
||
```text
|
||
拆分为：
|
||
BSP：只保留 GPIO映射
|
||
HAL：实现写操作
|
||
Module：调用接口
|
||
```
|
||
|
||
---
|
||
|
||
## ❌ 错误5：Interface直接调用BSP
|
||
|
||
### 修复：
|
||
|
||
```text
|
||
Interface → HAL → BSP
|
||
```
|
||
|
||
---
|
||
|
||
# 🔄 六、自动重构流程（Agent执行流程）
|
||
|
||
```pseudo
|
||
1. 解析代码
|
||
2. 标注每个函数所属层
|
||
3. 检查调用关系
|
||
4. 标记违规点
|
||
5. 应用纠错规则：
|
||
- 提取接口
|
||
- 下沉实现到HAL
|
||
- 上移语义到Module
|
||
6. 重构代码结构
|
||
7. 输出修复版本
|
||
```
|
||
|
||
---
|
||
|
||
# 🧠 七、层级识别规则（Agent用）
|
||
|
||
```pseudo
|
||
if 使用 GPIO/UART:
|
||
HAL
|
||
|
||
if 定义 pin mapping:
|
||
BSP
|
||
|
||
if 使用 xxx_if:
|
||
Interface
|
||
|
||
if 使用设备结构体:
|
||
Module
|
||
|
||
if 控制流程:
|
||
APP
|
||
```
|
||
|
||
---
|
||
|
||
# 📦 八、输出规范（强制）
|
||
|
||
Agent 输出代码必须：
|
||
|
||
* 按目录分层
|
||
* 每层文件独立
|
||
* 无跨层调用
|
||
* 接口统一
|
||
* 可编译
|
||
|
||
---
|
||
|
||
# 🧩 九、标准代码模板（自动生成）
|
||
|
||
## Interface模板
|
||
|
||
```c
|
||
typedef struct {
|
||
int (*init)(int id);
|
||
int (*write)(int id, int state);
|
||
} xxx_ops_t;
|
||
```
|
||
|
||
---
|
||
|
||
## HAL模板
|
||
|
||
```c
|
||
static int hal_xxx_write(...) { }
|
||
```
|
||
|
||
---
|
||
|
||
## Module模板
|
||
|
||
```c
|
||
xxx_if_write(...)
|
||
```
|
||
|
||
---
|
||
|
||
## BSP模板
|
||
|
||
```c
|
||
{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**
|
||
|
||
---
|