---
name: ea-skill
description: 嵌入式 AI 开发管家，支持 Keil/CubeMX 与 ESP32 的 ESP-IDF/PlatformIO/Arduino 工程。当用户要求嵌入式功能开发、外设接入、编译烧录、串口/JTAG/RTT 调试、固件验证、测试生成或芯片文档解析时使用。
version: 1.2.0
---

# EA-SKILL（Embedded AI）

> 嵌入式 + AI：对新老嵌入式工程做「新功能开发 → 测试 → 调试 → 验证 → 记录」闭环。
> 命令统一前缀 `/ea`。

你接收到的参数：`$ARGUMENTS`

## 路径约定（重要）

命令文档里的 `<SKILL>` 指**本 skill 的安装根目录**——也就是你正在读的 `SKILL.md`
所在的那个目录。执行任何命令前，先把它换成真实绝对路径。

```
<SKILL> = 本 SKILL.md 所在目录
```

例：本文档装在 `D:\tools\EA-SKILL`，则文档里的

```
py <SKILL>/tools/shared/detect_tools.py --detect
```

要执行成

```
py D:/tools/EA-SKILL/tools/shared/detect_tools.py --detect
```

**不要照抄 `<SKILL>` 字面量去跑**（`<` `>` 在 shell 里是重定向符号）。
同理，文档里的 `<STATE_DIR>` 指工程的状态目录（`.ea/` 优先，`.em/` 兼容老项目）。

> 为什么要这样：skill 可能被装到 `~/.claude/skills/`、`.cursor/skills/`、`.trae/skills/`
> 或任意目录，写死路径会让命令在别的安装位置全部失效。

## 快速开始

```
1. /ea setup          # 首次：环境/工具初始化（权限 / 工具路径 / CLAUDE.md 触发器）
2. /ea init <名>      # 新项目    或  /ea si [路径]   存量项目接入（建 context + 基线）
3. /ea doc <文档>     # 可选：先解析需求/引脚/手册文档（PDF / Word / Excel）
4. /ea new <功能描述>  # 新功能开发（需求澄清 → 轻 / 标准 两档）
5. /ea test ...       # 生成测试用例 + 可运行测试代码（unit / board）
6. /ea verify s<N>    # 验证：编译 → 烧录 → J-Link 运行验证 → 串口
7. /ea record s<N>    # 输出修改记录（文件 + diff + 测试证据）
```

**首次进入项目**：

| 场景 | 命令 |
|------|------|
| 全新项目 | `/ea init <name>` |
| 存量项目（无状态目录）| `/ea si [path]` |
| 恢复已有项目 | `/ea rec` |

## 命令表（20 个）

| 命令 | 用途 | 文档 |
|------|------|------|
| `/ea setup` | 环境/工具初始化（权限、工具路径、CLAUDE.md 触发器）| [setup.md](commands/setup.md) |
| `/ea init` | 新项目初始化（建 context 骨架 + 基线快照）| [init.md](commands/init.md) |
| `/ea si` | 存量项目接入（代码审计 + context + 基线快照）| [si.md](commands/si.md) |
| `/ea rec` | 恢复项目（state + context 摘要，只读）| [rec.md](commands/rec.md) |
| `/ea new` | 新功能开发（需求澄清 → 两档分流，嵌入式硬件维度）| [new.md](commands/new.md) |
| `/ea doc` | 文档识别（PDF / Word / Excel → Markdown / JSON）| [doc.md](commands/doc.md) |
| `/ea test` | 生成测试用例 + 测试代码：`unit` / `board` | [test.md](commands/test.md) |
| `/ea build` | Keil 编译 | [build.md](commands/build.md) |
| `/ea flash` | 烧录（OpenOCD / J-Link 原生双通道，后者含独立回读校验）| [flash.md](commands/flash.md) |
| `/ea serial` | 串口监控（CLI/MCP）| [serial.md](commands/serial.md) |
| `/ea debug` | 调试（J-Link RTT 取证/断点/内存/寄存器/复位放行；OpenOCD ST-Link/DAP 免停机监控）| [debug.md](commands/debug.md) |
| `/ea svd` | SVD 寄存器地图（外设/位域/枚举 + 免断点读值）| [svd.md](commands/svd.md) |
| `/ea la` | Saleae 逻辑分析仪（抓取/协议解码）| [la.md](commands/la.md) |
| `/ea scope` | Rigol 示波器（波形抓取/测量）| [scope.md](commands/scope.md) |
| `/ea size` | 固件资源分析（Flash/RAM/栈 + 超限预警）| [size.md](commands/size.md) |
| `/ea map` | Map 文件解析（对象排行/分段分布/符号映射）| [map.md](commands/map.md) |
| `/ea verify` | 步骤验证（HVR + 四连 + 保护区审计）| [verify.md](commands/verify.md) |
| `/ea record` | 输出修改记录（文件 + diff + 测试证据）| [record.md](commands/record.md) |
| `/ea stat` | 状态查看（默认极简，`-v` 全景）| [stat.md](commands/stat.md) |
| `/ea help` | 帮助 | [help.md](commands/help.md) |

> **子命令路由约定**：AI 执行任一命令时，读取 `commands/<cmd>.md`，严格按文档执行，不自行发明流程。

## 红线规则（必须遵守）

1. **保护区文件禁止随意修改**：`startup_*.s`、中断向量表、链接脚本（`*.sct`/`*.ld`/`*.icf`）、`system_*.c` 核心初始化。必须修改时：先给方案+理由 → 用户显式 `/ea approve <文件> <理由>` → 最小 diff。
2. **老工程默认增量修改**：禁止整文件重写、禁止全盘重写工程；单文件改动 ≥30% 或触碰核心逻辑 → 先给 diff 计划，用户确认。
3. **所有修改给出 diff**：先用 [git_state.py](tools/shared/git_state.py) 判断 `git diff` 是否真的可用（仓库无提交、或仓库根是工程的父目录时它会**静默返回空**，空 diff 会被误当成"没改动"）；不可用则用 [project_guard.py](tools/shared/project_guard.py) `--check --diff` 基线比对。
4. **先读 context 再动手**：`new`/`debug`/`verify`/`record` 执行前先读 `<STATE_DIR>/context.md`。
5. **保持源文件编码**：先检测工程实际编码；已有 GB2312/GBK 的 Keil 源文件禁止直接转成 UTF-8。ESP32 新文件默认 UTF-8，不套用 Keil 编码规则。
6. **Git push 禁止**：AI 只提议 commit，`git push` 必须用户手动执行。

## ESP32 平台路由

- 用户提到 ESP32/Espressif，或工程包含 ESP-IDF、`platformio.ini` 的 espressif32 平台、ESP32 Arduino 配置时，先读取 [ESP32 适配流程](workflows/esp32.md)，再读取对应命令文档。
- `setup/init/si/new/build/flash/serial/debug/size/map/verify` 均按该流程的平台分支执行；其规则覆盖下文及命令文档中的 Keil、ARM、SWD、J-Link 默认值，保留其他项目管理流程。
- 沿用现有框架和 SDK 版本。ESP32 编译使用 `idf.py`、`pio` 或 `arduino-cli`；烧录沿用框架地址配置，调试优先串口日志与匹配 ELF，JTAG 可选。
- ESP32 项目无需 Keil 或 J-Link；不运行 ARM 专用烧录/调试脚本，不将 GCC MAP 交给 Keil 解析器。
- 分区、SDK 配置、启动/链接及安全配置列入保护区；不自动擦除 Flash/NVS 或修改 eFuse。

## 状态目录布局

```
<STATE_DIR>/   ← .ea/ (优先) 或 .em/ (兼容老项目)
├── state.md           # 最小状态（≤50 行，rec 只读）
├── project.json       # { type:"embedded", name, chip, toolchain, interface }
├── context.md         # ⭐ 工程上下文（芯片/外设/模块地图/保护区/基线哈希）
├── project-spec.md    # 步骤表
├── decisions.md       # 决策日志
├── problem-log.md     # 问题追踪
├── approvals.md       # 保护区改动审批日志
├── sessions/          # 每会话一文件
├── discussion/        # 讨论目录（需求澄清 requirement.md / brainstorm / milestones）
├── docs/              # 文档解析缓存（/ea doc 输出，按内容哈希）
├── checkpoints/       # HVR 文件
├── history/           # 归档
├── logs/              # 串口/编译日志
├── records/           # 修改记录（/ea record 输出）
└── tests/             # 单测代码 + 板级用例（/ea test 输出）
```

状态目录定位：

```python
def get_state_dir(root):
    for d in (".ea", ".em"):
        p = os.path.join(root, d)
        if os.path.isdir(p):
            return p
    return None
```

## 详细文档

- `commands/` — 20 个命令定义
- `workflows/` — 工作流：context-build（上下文构建）、chip-learning（芯片学习）、req-clarify（需求澄清）、new-light / new-standard（两档）、verify-flow（编译→烧录→J-Link→串口）、hvr-workflow
- `templates/` — 模板：state / context / project / hvr / approvals / requirement / 单测与板级测试
- `tools/` — 工具：build-keil / flash-openocd / flash-jlink（J-Link 原生烧录 + 回读校验）/ serial-mcp / serial-monitor / jlink-debug / svd / instrument（la+scope）/ doc-reader（pdf+docx+xlsx）/ resource（size+map）/ shared / test-runner
- `mcp-servers/` — serial-mcp MCP server 配置

查看详细：`/ea help <命令>`