# 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**

---