最近我在整理 Project Velocity 的 AI Skill。

很多人以为，AI Skill 就是一个更长的 Prompt。

但在嵌入式工程里，真正有用的 AI Skill，第一步不是让 AI 写代码，而是让 AI 先理解：

硬件是什么，边界在哪里，哪些地方不能乱动。

今天先做第一步：

把 STM32F103 MCU 的硬件资料整理成一个 AI 可以读取、理解和长期复用的硬件 Skill。

一、为什么今天不急着写 Zephyr 代码？

在 Project Velocity 中，STM32F103 节点不是一个简单的单片机示例。

它未来要成为 MCU–Edge–Cloud AIoT 系统中的底层节点。

它会接入传感器、执行器、CAN/CANopen、RK3588 Edge Gateway，最终进入 ThingsBoard 云平台。

但是，在这些工作开始之前，必须先完成一件事：

让 AI 编程 Agent 看懂 STM32F103 这块板子的硬件边界。

否则，AI 很容易写出这样的代码：

能编译；
看起来合理；
但真实板子跑不起来。

因为嵌入式系统不是纯软件系统。

引脚、供电、BOOT（启动模式 / 启动配置）、SWD（串行线调试）、USB、晶振、LED、电流限制，这些硬件事实不能靠 AI 猜。

二、这些 .md 文件是怎么来的？

在开始设计 STM32 Zephyr 节点的 Skill 之前，我先做了一件基础工作：

把原来的工程资料转换成 Markdown。

例如：

PDF 格式的 STM32F103 原理图；
Excel 格式的芯片引脚定义表；
图片格式的开发板管脚图；
Word 或 PDF 格式的设计说明文档；
后续还包括传感器、执行器、CANopen、测试计划等资料。

为什么要先转成 Markdown？

因为 AI Agent 最容易读取、检索和理解的工程资料，不是 PDF，也不是图片，而是结构化 Markdown。

原理图适合工程师看，
Markdown 更适合 AI 读。

Excel 适合人整理表格，
Markdown 更适合 AI 做上下文分析。

图片管脚图适合快速查阅，
Markdown 表格更适合 AI 检查引脚冲突。

关于如何把 PDF 原理图、Excel 引脚表、图片管脚图和设计文档转换成 Markdown，我在前面一篇已经专门写过：

《Markdown第三篇｜AI编程第一步：把 Excel、PDF、图片变成 Markdown——以 Project Velocity 的 STM32 为例》

这篇就不再展开转换方法，今天重点讲：

转换成 Markdown 之后，如何把这些文件组织成 STM32F103 Hardware Skill。

三、今天我完成了什么？

今天我先把 STM32F103 MCU 相关的硬件资料整理成了一个 Skill 目录。

目前目录大致如下：

stm32_zephyr_node_skill/
├── README.md
└── inputs/
    ├── board_photo_back.jpg
    ├── board_photo_front.jpg
    ├── hardware_constraints.md
    ├── jumper_setting.md
    ├── stm32f103_board_pinout.md
    ├── stm32f103_chip_pin_definition.md
    ├── stm32f103_schematic.md
    └── swd_connection.md

这不是普通资料归档。

它的目标是让 AI 编程 Agent 在生成 Zephyr 工程之前，先读懂硬件。

四、这些文件分别解决什么问题？

1. README.md：Skill 的入口文件

README.md 是整个 Skill 的入口。

它告诉 AI：

这个 Skill 用于什么硬件；
它属于 Project Velocity 哪一层；
有哪些输入文件；
哪些引脚需要保留；
生成代码前必须检查什么；
最终应该输出哪些工程文件。

也就是说，README.md 不是普通说明文档，而是 AI Agent 使用这个 Skill 的“工程导航图”。

AI Agent 打开这个目录后，应该先读它。

2. stm32f103_schematic.md：原理图结构化文件

这个文件来自 STM32F103 最小系统原理图。

它把原理图中的关键信息转换成 Markdown，包括：

电源输入；
5V 转 3.3V；
USB D+ / D-；
BOOT0 / BOOT1；
SWD 调试接口；
8MHz 主晶振；
32.768kHz RTC 晶振；
PC13 用户 LED；
扩展排针。

例如，这块板子的 USB D- 接 PA11，USB D+ 接 PA12；SWDIO 接 PA13，SWCLK 接 PA14；PC13 是用户 LED；主晶振是 8MHz。

这些信息将直接影响 Zephyr 的 Device Tree、GPIO 配置和调试方式。

3. stm32f103_board_pinout.md：开发板管脚图文件

这个文件来自 STM32F103 开发板管脚图。

它告诉 AI：

每个排针对应哪个 STM32 引脚；
每个引脚有哪些复用功能；
哪些引脚可做 ADC；
哪些引脚可做 USART、SPI、I2C、CAN；
哪些引脚和 USB、SWD、BOOT 相关。

例如：

PA9 / PA10 可用于 USART1；
PA11 / PA12 与 USB 和 CAN 功能相关；
PB6 / PB7 可用于 I2C1；
PB8 / PB9 可作为 I2C1 或 CAN 重映射候选。

这类资料非常重要。

因为 AI 如果只靠模型记忆，很容易把管脚复用关系写错。

4. stm32f103_chip_pin_definition.md：芯片引脚定义文件

开发板管脚图告诉 AI“板子上能看到什么”。

芯片引脚定义表则告诉 AI“芯片本身支持什么”。

这个文件包括：

芯片引脚编号；
主功能；
默认复用功能；
重定义功能；
哪些引脚是 5V tolerant；
哪些是电源、地、复位、BOOT、时钟引脚。

例如：

PA13 是 JTMS / SWDIO；
PA14 是 JTCK / SWCLK；
PB10 / PB11 可用于 I2C2 或 USART3；
PB12–PB15 可用于 SPI2 或 USART3。

这可以帮助 AI 判断：

哪些引脚适合用；
哪些引脚应该保留；
哪些功能之间可能冲突。

5. jumper_setting.md：BOOT 跳线说明文件

这个文件告诉 AI：

BOOT0 和 BOOT1 如何设置；
正常运行时应该如何启动；
什么时候进入 System Bootloader；
烧录完成后为什么要把 BOOT0 重新接回 GND。

对 STM32F103 来说，BOOT 设置非常关键。

如果 BOOT0 设置错了，代码可能已经烧录成功，但板子就是不运行。

所以这个文件的价值是：

让 AI 不仅会写代码，还能解释为什么板子启动不了。

6. swd_connection.md：SWD 烧录与调试连接文件

这个文件告诉 AI：

ST-Link 应该如何连接 STM32F103；
SWDIO 是 PA13；
SWCLK 是 PA14；
GND 必须共地；
3.3V 是目标参考电压；
NRST 是否建议连接；
烧录失败时应该先检查什么。

它还有一个非常重要的作用：

提醒 AI 不要随便占用 PA13 和 PA14。

因为这两个引脚是调试生命线。

如果 AI 把 PA13 / PA14 分配给普通 GPIO 或外设，后面调试和恢复都会变得很麻烦。

7. hardware_constraints.md：硬件约束文件

这是今天最重要的文件之一。

它告诉 AI：

哪些硬件边界不能违反。

例如：

STM32F103 工作在 3.3V；
不是所有 GPIO 都能承受 5V；
PC13 不能当普通大电流输出；
PA13 / PA14 应保留给 SWD；
BOOT0 / PB2 与启动模式有关；
PA11 / PA12 涉及 USB，也可能和 CAN 功能冲突；
引脚分配前必须检查复用冲突；
Zephyr overlay 不能脱离原理图生成。

这个文件相当于给 AI 设置“工程红线”。

AI 不是不能写代码，而是必须在这些红线内写代码。

五、为什么我要把这些资料都组织成 Skill？

因为 AI Agent 写嵌入式代码时，最大的问题不是不会写语法。

最大的问题是：

它不知道真实硬件边界。

如果 AI 不知道原理图，它可能乱用引脚。
如果 AI 不知道管脚复用，它可能制造外设冲突。
如果 AI 不知道 SWD，它可能占用调试口。
如果 AI 不知道 BOOT，它可能写不出正确烧录说明。
如果 AI 不知道 PC13 的板级连接，它可能连 LED 逻辑都写反。

所以 STM32 Zephyr Node Skill 的第一步，不是 main.c。

而是：

把 STM32F103 的硬件事实结构化。

六、这和 Vibe Coding 有什么不同？

Vibe Coding 通常是这样开始的：

“帮我写一个 STM32 Zephyr 程序。”

AI-Assisted Engineering 则是这样开始的：

“这里是 STM32F103 的原理图、管脚图、芯片引脚表、BOOT 设置、SWD 连接和硬件约束。请先读取这些资料，再生成 Zephyr 工程。”

区别就在这里。

前者依赖 AI 猜。

后者让 AI 在工程边界内工作。

对嵌入式系统来说，这个区别非常大。

因为嵌入式工程不是只要代码能编译。

它还必须能烧录；
能启动；
能调试；
不能占用错误引脚；
不能违反电气边界；
不能破坏系统通信链路。

七、今天这一步的核心价值

今天这个 Skill 还没有接传感器，也没有接执行器。

但它已经完成了一个很重要的基础工作：

把 STM32F103 的硬件事实变成 AI 可以调用的工程知识。

这意味着，后面无论是让 AI 生成：

Device Tree overlay；
prj.conf；
main.c；
GPIO 控制；
UART 日志；
CAN/CANopen 配置；
传感器驱动；
执行器控制逻辑；

AI 都不再是从空白开始猜。

它会先回到这个硬件Skill，确认硬件边界。

八、我暂时不把传感器和执行器放进今天这篇

今天只做 MCU 硬件输入层。

也就是：

STM32F103 本体；
开发板资源；
电源；
BOOT；
SWD；
USB；
晶振；
LED；
管脚复用；
硬件约束。

传感器和执行器我准备放到明天。

因为那是另一个层次的问题：

哪些传感器接到哪里；
哪些执行器由哪些 GPIO、PWM、ADC、I2C、SPI、CAN 控制；
这些外设如何进入 Zephyr Device Tree；
如何形成 Project Velocity 的节点数据模型。

今天先把地基打好。

九、结语

AI 写嵌入式代码，第一步不是写 main.c。

第一步是让 AI 看懂硬件。

这也是我设计 Project Velocity STM32 Zephyr Node Skill 的原因。

不是为了让 AI 多写几行代码。

而是为了把工程师过去存在脑子里的硬件经验，变成 AI 可以长期调用、可以检查、可以复用的 Skill。

今天完成的是第一层：

STM32F103 MCU Hardware Skill。

下一篇，我会继续整理：

如何把传感器和执行器加入这个 Skill，让 STM32 节点真正进入 Project Velocity 的 AIoT 系统。

文中提到的 STM32F103 相关 .md 文件，包括原理图、开发板管脚图、芯片引脚定义、BOOT 跳线、SWD 连接和硬件约束等，如果大家想参考，欢迎在公众号后台私信我。