STM32 智能工程生成 Agent

从需求描述到可编译 Keil 工程，一键完成

ChipWhisper 是一个面向 STM32 的工程型 AI Agent，能够将自然语言需求自动转化为可编译的 Keil5 工程，覆盖从引脚规划到业务代码生成的完整链路：

需求描述 → 智能规划 → 工程生成 → HAL驱动导入 → 编译验证 → 自动修复

不是 让大模型随手吐几段 C 代码，而是 生成完整的、可编译的、结构规范的 Keil5 工程。

• STM32F103 (C8T6 / RBT6)
• STM32G431 (RBT6) — 蓝桥杯竞赛平台

• CT117E (蓝桥杯官方开发板 G431)
• Blue Pill (STM32F103C8T6 最小系统板)
• Nucleo-F103RB
• STM32F103C8 / F103RB 最小系统板
• STM32F103RB 实训板

ChipWhisper 使用 LangGraph 编排完整的工程生成流程，支持人机交互确认、自动修复循环和两阶段增量编译：

graph TD
    A[START] --> B[retrieve<br/>检索项目上下文]
    B --> C[draft<br/>LLM 理解需求]
    C --> D{validate_request<br/>请求校验}
    D -->|合法| E[plan<br/>引脚规划+资源分配]
    D -->|无效| Z[END]
    E -->|可行| F[draft_app_logic<br/>生成业务逻辑IR]
    E -->|不可行| Z
    F --> G{review<br/>人机确认闸门}
    G -->|确认| H[scaffold<br/>生成工程文件+可选Makefile]
    G -->|打回| C
    H --> I[import_drivers<br/>导入 HAL 驱动]
    I --> J[build<br/>编译工程 Keil/GCC]
    J -->|成功+基础阶段| K[advance_phase<br/>推进到业务逻辑阶段]
    J -->|成功+最终阶段| L[simulate<br/>Renode 仿真]
    J -->|失败| M[repair<br/>自动修复]
    K --> F
    L --> N{evaluate<br/>评估结果}
    N -->|通过| Z
    N -->|失败| M
    M -->|重试编译| J
    M -->|重新生成| H
    M -->|重新规划| C
    M -->|放弃| Z

第一阶段 (infrastructure)          第二阶段 (app_logic)
┌──────────────────────┐           ┌──────────────────────┐
│  HAL 初始化代码       │    ──→    │  业务逻辑 app_main.c  │
│  外设驱动文件         │  编译通过  │  状态机 / 任务调度     │
│  引脚宏定义           │  后推进    │  传感器采集 / 显示     │
└──────────────────────┘           └──────────────────────┘

先编译验证硬件层，确保基础代码无误后，再在其上生成业务逻辑。大幅降低复杂项目的编译失败率。

编译失败时，repair 节点会：

1. 错误分类 — 识别 missing #include、undefined symbol、type mismatch 等常见模式
2. API 上下文注入 — 从项目头文件中提取函数原型，作为修复参考
3. LLM 结构化修复 — 生成 search/replace 补丁，白名单校验后应用
4. 有限重试 — 最多 3 轮自动修复，失败则回退人工复核

每个模块附带经过验证的 app_logic_snippets，包含 init / loop / API 摘要，LLM 生成代码时被强制引用这些片段，避免编造不存在的 API：

{
  "app_logic_snippets": {
    "init": "AHT20_Init(&hi2c1);",
    "loop": "AHT20_Read(&hi2c1, &temperature, &humidity);",
    "api_summary": "AHT20_Init(hi2c) AHT20_Read(hi2c, &temp, &hum)",
    "notes": "Call AHT20_Read every 2+ seconds."
  }
}

11 个预定义场景模板（含 6 个蓝桥杯真题），系统根据请求中的模块组合自动匹配最佳场景，为 LLM 提供完整的需求上下文：

request.json → match_scenarios() → 匹配 "temp_humidity_display" 场景
                                  → 注入 LCD 显示格式 + 采集周期 + 阈值逻辑

PID 控制器、移动平均滤波、环形缓冲区等算法模块提供 验证过的 C/H 模板，直接复制到工程中，不依赖 LLM 生成：

7 个高频模块提供完整的 C/H 驱动模板，基于真实数据手册编写：

业务逻辑通过结构化 IR (中间表示) 描述，而非直接生成 C 代码，支持：

• 类型定义 — enum 和 struct
• 宏定义 — #define 常量
• 全局变量 — 带初始值和注释
• 辅助函数 — helpers 内联声明
• 状态机 — 状态/转移/超时/重试计数
• 定时任务 — 周期执行 + 事件触发
• 验收条件 — 串口输出关键字检查

• Python 3.10+
• Keil MDK-ARM 5 — 编译 STM32 工程
• STM32CubeMX — 芯片引脚配置 + HAL 驱动包管理
• ARM GNU Toolchain — 可选，免费 GCC 编译验证（无需 Keil 也能验证代码正确性）
• Renode — 可选，仿真验证（无需实体硬件）

💡 安装后需配置路径，参考 stm32_agent.paths.example.json：

{
  "keil_uv4_path": "D:\\Keil_v5\\UV4\\UV4.exe",
  "stm32cubemx_install_path": "D:\\STM32CubeMX",
  "stm32cube_repository_path": "C:\\Users\\你的用户名\\STM32Cube\\Repository",
  "renode_exe_path": "D:\\Renode\\renode.exe",
  "arm_gcc_path": "D:\\Arm GNU Toolchain arm-none-eabi\\14.3 rel1\\bin\\arm-none-eabi-gcc.exe"
}

git clone https://github.com/yourname/ChipWhisper.git
cd ChipWhisper
pip install -r requirements-desktop.txt

# 从 request.json 一键生成可编译的 Keil5 工程
python -m stm32_agent generate request.json ./output

# 1. 规划引脚和资源
python -m stm32_agent plan request.json

# 2. 生成 Keil5 工程
python -m stm32_agent scaffold request.json ./output

# 3. 生成工程 + Makefile（启用 GCC 编译验证）
python -m stm32_agent scaffold request.json ./output --makefile

# 4. 导入 HAL 驱动
python -m stm32_agent import-cubef1-drivers ./output

# 5. 编译工程（Keil 或 GCC 自动检测）
python -m stm32_agent build-keil ./output
python -m stm32_agent build-project ./output          # 自动检测 Keil/GCC
python -m stm32_agent build-project ./output --gcc     # 强制使用 GCC

ChipWhisper 提供基于 PySide6 的桌面工作台，深色 IDE 风格界面：

# 安装桌面依赖
pip install -r requirements-desktop.txt
# 或使用 conda
conda env create -f environment.yml && conda activate stm32-agent

# 启动桌面端
python -m stm32_agent.desktop

桌面端功能：

{
  "summary": "温湿度采集并显示在OLED屏幕上，超过阈值蜂鸣器报警",
  "chip": {"name": "STM32F103C8T6"},
  "modules": [
    {"kind": "aht20_i2c", "name": "sensor"},
    {"kind": "ssd1306_i2c", "name": "oled"},
    {"kind": "active_buzzer", "name": "buzzer"}
  ],
  "requirements": [
    "每2秒采集温湿度",
    "OLED显示温度和湿度",
    "温度超过30度蜂鸣器报警"
  ]
}

ChipWhisper/
├── stm32_agent/           # 核心 Agent 代码
│   ├── graph/             # LangGraph 工作流（两阶段生成+自动修复）
│   ├── templates/         # Jinja2 工程模板
│   ├── catalog.py         # 内置芯片/模块目录
│   ├── planner.py         # 引脚规划器
│   ├── keil_generator.py  # Keil5 工程生成器
│   ├── keil_generator_makefile.py # Makefile + 链接脚本生成（GCC 编译用）
│   ├── gcc_builder.py     # ARM GCC 编译后端
│   ├── builder.py         # 构建抽象层（Keil / GCC 自动切换）
│   ├── app_logic_ir.py    # 业务逻辑中间表示
│   ├── app_logic_drafter.py # LLM 业务代码生成
│   ├── cli.py             # CLI 命令入口
│   └── ...
├── packs/                 # 扩展包
│   ├── modules/           # 50+ 模块定义和驱动模板
│   └── scenarios/         # 11 场景模板（含蓝桥杯真题）
├── tests/                 # 测试用例 (188 passed)
├── docs/                  # 设计文档
└── README.md

内置 6 个蓝桥杯高级场景模板，基于真题资料：

python -m pytest tests/ -q
# 188 passed ✅

复制配置模板并填入 API Key：

cp stm32_agent.llm.example.json stm32_agent.llm.json

支持 OpenAI / Azure / 本地兼容 API。

• 架构设计
• LangGraph 工作流
• 扩展包机制
• 蓝桥杯支持
• CT117E-G431 适配
• 路径配置

• ✅ STM32 课程设计和实验
• ✅ 蓝桥杯嵌入式竞赛备赛
• ✅ 毕业设计快速原型
• ✅ 常见模块项目快速起步
• ⚠️ 需要 RTOS 的复杂项目（暂不支持）
• ⚠️ 图像处理/USB 设备类项目（暂不支持）

MIT License