AI Agent + AGENTS.md 知识库——嵌入式开发的 AI 辅助体系实战（双 Agent + 45 Skills + MCP + 项目宪法）

Babel36acl 嵌入式实战 无~ 17 次阅读 预计阅读时间: 18 分钟 发布于 2 天前 最后更新于 1 小时前 3924 字

很多搞嵌入式的朋友看到 AI 辅助开发，第一反应是「那玩意儿写写前端还行，嵌入式能用？」

坦白说，两年前我也是这么想的。但现在我的开发环境里 AI 不是聊天玩具——它是我每天都在用的工作搭档。

这篇文章不讲虚的，直接把我系统里 AI 接入嵌入式开发的完整方案摊开。从双 Agent 架构、45+ 技能分类、AGENTS.md 知识库体系到 MCP 桥接自动发博客，每一项都是实际在用的。

一、整体架构

我的 WSL 环境里跑着两个 AI Agent，分工非常明确：

Hermes Agent（主 AI 助手）
├── 远程模型：DeepSeek V4 Flash（通过 API）
├── 45+ 技能（Skills）
├── MCP 桥接（WordPress REST API）
├── 可调度子 Agent（claude-code、codex、opencode）
└── 角色：环境扫描、技术规划、代码审查、博客生成

Codex CLI（副 AI 代理）
├── 本地运行（独立会话 + 记忆系统）
├── AGENTS.md 知识库体系（5 个文件 + 14 个模块文档）
├── 项目级行为规范
└── 角色：代码生成、项目规则执行

Hermes 是「大脑」——分析、规划、审查、调度。Codex 是「手」——在 repo 层面执行，带着 AGENTS.md 的规则写代码。两者互补，不冲突。

二、Hermes Agent 实际配置

2.1 模型

当前通过 DeepSeek API 调用 deepseek-v4-flash，没有跑本地模型。虽然 RTX 3050 4GB 显卡装着 CUDA 13.3 驱动，但还没装 ollama/llama.cpp 这类本地推理引擎。

model:
  default: deepseek-v4-flash
  provider: deepseek
  base_url: https://api.deepseek.com

agent:
  max_turns: 90
  gateway_timeout: 1800
  api_max_retries: 3
  reasoning_effort: medium

2.2 45+ Skills 全分类

Skills 是 Hermes 能做事的基础。每个 Skill 是一个 markdown 文件，里面写着怎么做某类事情——包含步骤、命令、坑点。

类别 数量 代表性技能 用途场景
嵌入式/软件开发 10+ test-driven-development、systematic-debugging、requesting-code-review、writing-plans、embedded-rtos-debugging、embedded-protocol-documentation、firmware-protocol-bridge、android-usb-serial TDD 流程、4 阶段根因分析、代码审查、嵌入式协议文档、Android USB 串口调试
AI/ML 推理部署 6 llama-cpp、serving-llms-vllm、evaluating-llms-harness、dspy、weights-and-biases、huggingface-hub 本地 GGUF 推理、模型评估、声明式 LLM 编程、HF 模型搜索下载
内容创作 9 baoyu-article-illustrator、baoyu-comic、baoyu-cover-image、baoyu-infographic、baoyu-slide-deck、baoyu-xhs-images、baoyu-post-to-wechat、baoyu-post-to-weibo、baoyu-post-to-x 文章插图、知识漫画、封面、信息图、幻灯片、小红书/公众号/微博/X 多平台发文
代理/自动化 4 claude-code、codex、opencode、kanban-orchestrator 委托其他 AI 代理、任务分解编排
创意 6 ascii-art、ascii-video、excalidraw、architecture-diagram、p5js、pixel-art ASCII 艺术、手绘风格图、SVG 架构图、创意编程
数据/生产力 6 notion、obsidian、google-workspace、airtable、linear、powerpoint 笔记管理、Google 套件、Airtable 数据、项目管理
GitHub 5 github-code-review、github-issues、github-pr-workflow、github-repo-management、codebase-inspection PR 审查、Issue 管理、仓库管理、代码量分析
MCP/协议 2 native-mcp、cronjob MCP 服务集成、后台定时任务
其他 3 devops/dev-environment-audit、webhook-subscriptions、red-teaming/godmode 环境审计、Webhook 驱动、LLM 越狱测试

实际使用场景举例：

  1. 「检查我的开发环境」 — Hermes 自动扫系统工具版本、执行一次真实编译、检查 VSCode 配置、输出完整报告。不需要我手动 --version 一个个查。
  2. 「审核代码」 — 加载 requesting-code-review 技能和 systematic-debugging 技能，自动 diff 分析、检查安全漏洞、输出结构化评审。
  3. 「写博客发布」 — 加载 upgrade-tech-tutorial-to-engineering-guide 技能，按步骤扩写文章，通过 MCP 调用 WordPress API 自动发布。
  4. 「分析 git 历史」 — 加载 msr-git-history-analysis 技能，分析数月 commit 数据，输出文件级和 commit 级证据的结构化报告。

2.3 人格系统

Hermes 内置了 10+ 种人格，通过配置文件切换：

personalities:
  helpful: "You are a helpful, friendly AI assistant."
  technical: "You are a technical expert. Provide detailed, accurate technical information."
  teacher: "You are a patient teacher. Explain concepts clearly with examples."
  pirate: "Arrr! Ye be talkin' to Captain Hermes..."
  noir: "The rain hammered against the terminal like regrets on a guilty conscience."
  hype: "YOOO LET'S GOOOO!!! 🔥🔥🔥"

平时用 technical 做技术工作，写博客切 teacher 风格，心情好切个 pirate 让 terminal 变成海盗船。

三、Codex CLI + AGENTS.md：项目的「不遗忘」机制

3.1 为什么需要 AGENTS.md

AI 有一个致命缺陷——它会忘。上周你告诉它「不要直接在状态机里调用 HAL_GPIO」，这周它又写了同样的代码。

AGENTS.md 就是用来解决这个问题的：把架构规则、历史踩坑、协议细节写进文件，AI 每次进项目先读、再动手。

3.2 系统里现在的 AGENTS.md

文件 行数 覆盖范围
/root/.codex/AGENTS.md 307 行 Codex 全局行为基线（24 条规则）
/root/develop/HMI/AGENTS.md 159 行 Flutter 上位机完整知识库
/root/develop/Packaging_machine_V1.0/AGENTS.md 271 行 打包机固件，最详尽
/root/develop/XYZ/AGENTS.md 71 行 XYZ 固件项目知识库

3.3 以打包机固件为例：271 行 AGENTS.md 写了什么

AGENTS.md（271 行）
├── 1. 文件角色 —— 什么情况下读取
├── 2. 项目一眼结论 —— MCU（STM32F103RCT6）、技术栈、3 路 UART、7 任务
├── 3. Codex 进入仓库后的默认动作（信息优先级 10 级）
├── 4. 全局路由表 —— 22 种问题类型→哪个模块文档
├── 5. 全局硬规则（4 大类）
│   ├── 5.1 分层边界——APP 不能直接调 BSP
│   ├── 5.2 并发与中断——临界区规范
│   ├── 5.3 通信口径——USART3 主协议 vs USART1 调试口
│   └── 5.4 配置与接口——运行时参数走 EEPROM
├── 6. 修改代码时的检查点（12 种类型）
│   ├── 改协议 → 同时看 3 个文件 + 同步文档
│   ├── 改状态机 → 看 app_packer_sm + state_handler
│   ├── 改执行器 → 改 action table，不散落 switch
│   ├── 改 ADC/功率 → 不改变主流程结果
│   ├── 改串口/DMA → 先查 ISR 竞争
│   ├── 改监控/报警 → 确认锁存/清除/快照一致
│   ├── 改打印机/屏幕 → 必须在 CommTask 异步
│   ├── 改 USART1 HMI → 同步核对 HMI Dart 解码
│   ├── 改线程/任务模型 → 注册栈大小宏
│   ├── 改构建/调试 → 同步 VSCode launch.json
│   ├── 改 app_define.h → grep 确认零引用再删除
│   └── 改步进保护 → 传感器轴=超时，纯开环轴=脉冲溢出
├── 7. 文档回写规则
└── 8. 一句话执行原则

这就是 AI 版的项目「宪法」。每次改代码前先查，不靠记忆力，不翻聊天记录。

3.4 .agents/ 模块级知识库

除了顶层的 AGENTS.md，还有 14 个模块级文档放在 .agents/ 目录里：

.agents/
├── index.md                   # 模块入口索引
├── SKILL.md                   # 架构约束、线程模型、历史故障
├── app/
│   ├── app_packer_proto.md    # 协议分发/命令校验/响应字段
│   ├── app_packer_sm.md       # 顶层状态机/流程
│   └── app_monitor.md         # 监控/报警/喂狗
├── service/
│   ├── packer_state_handler.md  # 状态注册表
│   ├── packer_actuator.md       # 执行器映射/点动/换算
│   ├── io_adapters.md           # 串口/屏幕/打印机/输入/ADC
│   └── runtime_support.md       # 运行时标志/故障锁存/快照
├── bsp/
│   ├── bsp_uart.md           # UART/DMA/IDLE/日志/StreamBuffer
│   ├── bsp_motion.md         # 步进/电机/继电器/功率
│   └── bsp_misc.md           # GPIO/ADC/EEPROM/IWDG
├── common/
│   ├── project-baseline.md   # 软件架构/分层/任务/临界区
│   ├── protocol-and-io.md    # 固定协议/串口/HMI/输入输出
│   └── build-debug-rules.md  # 构建/clangd/OpenOCD/VSCode
└── refactoring/
    └── define-to-runtime-migration-log.md  # 编译期宏迁移记录

架构规则、协议细节、IO 映射、状态机约束、UART 配置、步进电机驱动——每个模块都有自己的 md 文档。AI 进入项目后先读 index.md 定位入口，再按路由表找到对应模块文档。

3.5 AGENTS.md 的 24 条全局行为规则

Codex 的全局 AGENTS.md 定义了 24 条规则，核心几条：

规则 内容
两层结构 全局（/root/.codex/AGENTS.md）+ 项目本地（/AGENTS.md）
优先顺序 当前任务事实 > 项目 AGENTS.md > 文档 > 源码 > 全局 AGENTS.md
执行纪律 改前读文档、只改必要行、避免多余抽象
Docs-First 先读文档再查代码，用代码确认而不是用代码推导
硬件优先 以 .ioc、网表、原理图为准
IWYU Pragma 嵌入式工程中标记必须保留的头文件，防止 clangd 自动删除
验证说明 任何未验证的操作要标注「Build not verified」「Flash path not verified」

这套规则让 AI 的行为可预期、可约束、可审计。

四、MCP（Model Context Protocol）桥接

MCP 是 AI 和外部工具之间的「API 网关」。我的系统里配置了 WordPress MCP 桥接：

Hermes Agent → MCP Server → WordPress REST API
  ├── create_post       → 创建/更新文章
  ├── list_categories   → 查看文章分类
  └── get_user_info     → 获取用户信息

MCP 服务器脚本在 ~/.hermes/scripts/wp_mcp_server.py，通过 WordPress 的 REST API 直接操作。

实际使用场景： 让 Hermes 写一篇技术文章，它加载写作 skill，按步骤扩写内容，然后通过 MCP 调用 WordPress API 设置分类、发布。全程不需要打开浏览器、不需要登录 WP 后台、不需要复制粘贴。一句话完成。

系统里 WordPress 的实际分类：

ID 名称 已发文章
6 学习笔记 4 篇
13 嵌入式实战 7 篇
14 工程复盘 2 篇
15 架构与重构 1 篇
16 方法与工具 3 篇

五、AI 辅助的实际工作流

最后说说这套东西每天都在怎么用。

场景 1：环境快查

# 一句话
「检查我的 STM32 开发环境」

Hermes 自动扫描系统、执行一次编译验证、检查 VSCode 所有配置、输出完整的报告——工具版本、缺失项、项目状态。原来手动 --version 一个一个查需要 10 分钟，现在 30 秒。

场景 2：代码审查

AI 加载 requesting-code-review + codebase-inspection + systematic-debugging 三个技能，自动：

  1. 拉取 git diff
  2. 检查安全违规（硬编码、缓冲区溢出）
  3. 检查代码风格（中文注释、Doxygen 格式）
  4. 检查分层违规（APP 直接调 BSP）
  5. 给出结构化评审

场景 3：写技术文章

AI 加载 upgrade-tech-tutorial-to-engineering-guide 技能：

  1. 先审计现有文章结构
  2. 补充官方文档细节
  3. 添加架构深度分析
  4. 小白提示和检查清单
  5. 通过 MCP 发布到 WordPress

场景 4：调试分析

HardFault 命中后，hardfault_info 打印异常帧。把寄存器值贴给 Hermes，它直接解读 CFSR 寄存器各位的含义——是因为访问了不存在的地址（IMPRECISERR）还是指令访问了不可执行区域（IACCVIOL）。不用翻 ref manual。

六、当前限制和后续规划

限制

项目 状态 说明
本地模型推理 未启用 依赖远程 API，离线不能用
GPU（RTX 3050 4GB） 闲置 驱动已装（CUDA 13.3），但没装推理引擎
Docker 未安装 AI 沙箱环境待搭建
CICD 集成 未接入 AI 审查结果还没进 GitHub Actions

后续

  1. 装 ollama 跑本地模型 — 3B/7B Q4 量化小模型在 RTX 3050 上能跑，离线也能用
  2. MCP 扩展 — 接入 GitHub MCP（自动创建 PR、打标签），接入 Jira/Linear MCP（自动同步任务状态）
  3. AGENTS.md 自动化检 — 开发一个脚本自动检查 AGENTS.md 规则是否被违反
  4. CICD 集成 — AI 代码审查结果作为 GitHub Actions 的门禁

七、一句话

AGENTS.md 是项目的法，Skills 是 AI 的手，MCP 是 AI 的眼睛——三样加在一起，AI 才真正嵌入开发流程，而不是一个高级聊天框。

相关文章

此作者没有提供个人介绍。
最后更新于 2026-05-30