# ea-skill

Adopt this skill: https://proskills.md/skills/other/jzl-maker-ea-skill

Page: https://proskills.md/skills/other/jzl-maker-ea-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8027
upstream: https://github.com/jzl-maker/ea-skill/blob/HEAD/SKILL.md

````text
---
name: ea-skill
description: 嵌入式 AI 开发管家（EA-SKILL）— 面向单片机/嵌入式工程（Keil/CubeMX/ESP-IDF/PlatformIO/Arduino）的需求澄清与方案确认、新功能开发、单元测试、板级工装测试、编译烧录、J-Link 调试与验证。当用户要对嵌入式新老项目开发新功能、加外设、改业务逻辑、排查硬件 bug、验证固件、生成测试用例，或需求描述不清晰需要讨论确认方案、需要读取 PDF/Word/Excel 文档（芯片手册/需求规格/引脚表）时使用；对话提到 编译/烧录/串口/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. **GBK 编码**：Keil 工程 `.c`/`.h` 为 GB2312 编码，读取按 `encoding="gbk"`，修改用字节级操作，禁止 UTF-8 编辑器直接改中文（会整文件乱码）。
6. **Git push 禁止**：AI 只提议 commit，`git push` 必须用户手动执行。

## 状态目录布局

```
<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 <命令>`
````

## File: README.md
upstream: https://github.com/jzl-maker/ea-skill/blob/HEAD/README.md

````text
<div align="center">

# EA-SKILL · 嵌入式 AI 开发管家

**让 Claude Code 直接接管你的单片机** —— 编译、烧录、串口、调试、寄存器查询、示波器测量，全部一句话搞定。

```
输入 /ea new "给 LED 加 500ms 定时翻转"   →   自动完成 规划 → 编译 → 烧录 → 验证
```

```
[build]  Keil MDK 编译通过 ✅   (0 errors, 0 warnings)
[flash]  OpenOCD 烧录完成 ✅   (N32G4FR, 12.4s)
[scope]  CHAN1: 1.00kHz 方波, Vpp 3.08V, 50% 占空比 ✅   ← 真机实测
[svd]    RCC.CR = 0x0100XX00 → HSEON 已置位 ✅
```

测不准的时候，它不会硬给你一个数：

```
[scope]  ⚠️ 占空比在窗口内变化：逐周期 20.0% → 79.5%（极差 59.5 个百分点）
             上面报的 duty_pct=49.75% 只是整段窗口的均值      →  退出码 2
```

</div>

## 🎯 为什么值得用

| 痛点 | EA-SKILL 解决 |
|------|----------------|
| 需求说不清楚，做完才发现理解偏了 | `/ea new` 阶段 0 主动提问澄清（每题带推荐答案）→ 确认方案再动手 |
| 需求文档 / 引脚表 / 芯片手册得手抄进对话 | `/ea doc` 直接解析 PDF / Word / Excel |
| 编译烧录要在 Keil/OpenOCD 之间来回点 | 一句话 `/ea build flash`，AI 全程接管 |
| 查寄存器要翻 1500 页参考手册 | `/ea svd` 免断点读值 + 位域/枚举自动解码 |
| 调变量要打断点 halt 住 CPU，中断就停 | **OpenOCD 免断点内存监控**，运行中实时采样 |
| 看波形要手动抓示波器再导出分析 | `/ea scope` 直接 SCPI 抓取 + 测量 + 出图 |
| 测出一个数，但不知道它可不可信 | 削顶/平线/不等周期/**占空比在变**一律标注 + 退出码 2，不静默给均值 |
| 固件超 Flash/RAM 了才知道 | `/ea size` 编译即报占用率 + 超限预警 |

## ✨ 差异化亮点

- 🧭 **需求澄清**：描述不规范先提问坐实（9 维度扫描 + 带推荐答案的选择题），避免嵌入式返工（改引脚=改板）
- 📄 **文档直读**：PDF / Word / Excel 转 Markdown；DOCX/XLSX 零依赖，只有 PDF 需要装包
- 🔓 **免断点调试**：OpenOCD TCL 协议直接读内存，CPU 不 halt，中断/外设持续运行
- 📖 **SVD 寄存器地图**：自动发现 Keil Pack SVD，derivedFrom 继承展开，免查手册
- 🔬 **仪器直连**：Rigol 示波器（SCPI 抓取/测量）+ Saleae 逻辑分析仪 + 正点原子 DS100 CSV 解析
- 🎯 **不给会误导判断的数**：数据不可信时明说而不是硬报一个值——削顶/平线/噪声边沿/不等周期/占空比在窗口内变化，全部进 `warnings` 并置退出码 `2`，按 rc 分支就不会把"取到但不可信"当成成功
- 🧪 **无硬件回归测试**：199 条用例驱动全部工具脚本，合成数据 + 假可执行文件，不接任何仪器也能跑（`tests/`）
- 🧱 **硬件红线保护**：禁止 AI 改启动文件/链接脚本/中断向量表，需 `/ea approve` 显式授权
- 🛡️ **AI 行为约束**：增量修改默认给 diff，防 AI 整文件重写搞坏工程

## 🚀 快速上手

**安装（一句话）：** 在 Claude Code 或 Cline 等支持 Agent Skills 的客户端对话中，直接输入：
```
帮我安装 https://github.com/jzl-maker/EA-SKILL.git 的 skill
```
AI 会自动克隆仓库、安装到技能目录并初始化环境。然后接入你的工程：

```
/ea setup        # 环境/工具初始化（权限、工具路径、CLAUDE.md 触发器）
/ea si .          # 存量项目接入 → AI 生成上下文
/ea new "..."     # 说人话描述功能，AI 规划并开发
```

## 🔌 大模型适配

skill 的加载机制由**宿主客户端**提供，与模型本身解耦——DeepSeek 及任何 Anthropic 兼容端点的模型都能直接使用 EA-SKILL。

| 模型 × 客户端 | 支持 | 说明 |
|---------------|------|------|
| Claude × Claude Code | ✅ 开箱即用 | 原生 skill 机制 |
| **DeepSeek × Claude Code** | ✅ | Claude Code 设置 `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic`，`/ea setup` 全流程不变 |
| DeepSeek × Cline | ✅ | Cline 配 DeepSeek 端点 + 安装到 `.claude/skills`，setup 微调（见下）|
| 其他 Anthropic 兼容模型 × agent 客户端（Gemini CLI / Cursor）| ✅ | 需客户端支持 Agent Skills，setup 微调 |
| 纯聊天客户端（Copilot Chat / Chatbox / 网页版）| ❌ | 无「读文档 → 执行命令」的 agent 工具机制 |

> ✅ 已用 DeepSeek（deepseek-v4）真机跑通编译 / 烧录 / 示波器 / SVD 全流程。

**换客户端时 setup 微调**（skill 本体无需改动）：
- **权限**：跳过 `~/.claude/settings.json` 那步（Cline 等会自动弹权限确认），或换成该客户端的权限格式
- **触发器**：改跑 `py register_claude_md.py --target <该客户端记忆文件>`（如 `.cursor/rules` / `AGENTS.md`），或手动写等效规则

## 📦 命令总览（20 个）

| 分类 | 命令 |
|------|------|
| 环境 / 项目 | `/ea setup` `/ea init` `/ea si` `/ea rec` |
| 开发 / 测试 | `/ea new`（含需求澄清）`/ea doc`（PDF/Word/Excel）`/ea test` |
| 构建 / 烧录 | `/ea build` `/ea flash` |
| 调试 / 寄存器 | `/ea debug` `/ea svd` |
| 仪器 | `/ea la`（逻辑分析仪）`/ea scope`（示波器） |
| 资源分析 | `/ea size`（Flash/RAM/栈）`/ea map`（.map 解析） |
| 验证 / 记录 | `/ea verify` `/ea record` `/ea stat` `/ea help` |

## ✅ 真机验证

| 能力 | 硬件 | 状态 |
|------|------|------|
| 烧录 | ST-Link / DAP | ✅ |
| 波形抓取/测量 | Rigol DS1074Z / DS2302A | ✅ |
| 深内存抓取（`--mode RAW`） | Rigol DS2302A（140 万点 @2 GSa/s） | ✅ |
| CSV 解析 | 正点原子 DS100 | ✅ |
| SVD 寄存器地图 | N32G4FR | ✅ |
| OpenOCD 免断点 | ST-Link/DAP | ⏳ 待实机 |
| 回归测试（无需硬件） | — | ✅ 199 条全绿 |

## 🔧 系统要求

Windows 10/11 + Claude Code + Python 3.9+（`py`）+ Keil MDK + OpenOCD（J-Link / ST-Link 可选）

## 🧱 目录结构

```
EA-SKILL/
├── SKILL.md          # 入口（命令表 + 红线）
├── commands/         # 20 个命令文档（AI 按需读取，不污染上下文）
├── workflows/        # 验证四连 / HVR / 需求澄清 / 新功能流程
├── tools/            # build / flash / serial / debug / svd / instrument / doc-reader / resource ...
├── tests/            # 无硬件回归测试（199 条，见 tests/README.md）
└── mcp-servers/      # 串口 MCP
```

## 📄 License

[MIT](LICENSE) © 2026 jzl-maker

---

**Star 一下 ⭐，让嵌入式开发更 AI。**
````
