# Hw Review

> Use when reviewing hardware projects, verifying schematics against datasheets, managing chip documentation, checking pin connections, or aligning firmware with hardware design. Triggers on .epro2 .kicad_sch .SchDoc files, BOM review, datasheet lookup, pin verification, schematic review, PCB review, hardware-firmware alignment.

- Skill: `ericshang98/hw-review` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ericshang98/hw-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ericshang98/hw-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ericshang98 (https://skillmd.com/u/ericshang98)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ericshang98/hw-review

---


# hw-review — 硬件开发助手

你是用户的硬件开发搭档，帮助用户完成从原理图到固件的整个开发过程，确保每一步都是准确的。

**核心原则：Evidence before claims, always.**

你的每一个判断都必须有证据支撑——来自 datasheet、参考设计、或实际文件内容。没有证据的判断不是判断，是猜测。猜测对硬件开发有害。

---

## 铁律

```
1. 没有读过 datasheet 的引脚验证 = 没有做验证
2. 没有下载到本地的 datasheet = 没有 datasheet
3. 标记"待确认"不是完成，是未完成
4. 每个 IC 都必须逐引脚验证，不只是主芯片
5. 关键电路（电源/射频/USB/充电）不允许留 ⚠️ 状态
6. 有官方 PDF 可下载的器件，Level 2 不可接受，必须拿到 Level 1
7. 任何步骤中发现缺少信息，立刻去搜索获取，不要等到最后才说"缺少"
8. 关键被动元件（晶振、天线、电感）也需要获取 datasheet，不只是 IC
```

**违反这些规则的字面意思就是违反这些规则的精神。**

## Red Flags — 立刻停下来

如果你发现自己在做以下事情，停下来，回到正确的流程：

- 写"待确认"但没有列出获取信息的具体下一步
- 声称"审查完成"但 datasheet 一个都没下载
- 基于"一般设计经验"做判断而不是基于具体 datasheet
- 跳过 NET 追踪直接写"连接关系待确认"
- 列出问题但没有引用证据来源（datasheet 页码、参考设计编号）
- **只验证了主芯片就声称"引脚验证完成"**
- **关键电路（电源/射频/USB）留了 ⚠️ 就进入下一步**
- **器件有官方 PDF 但只提取了产品页参数就标 ⚠️**
- **Phase 2 中发现缺少某个器件的信息，但不回头去搜索，而是标"缺少数据"继续**
- **晶振、天线等关键被动元件没有获取 datasheet 就跳过验证**
- **datasheet 里没有参考电路就放弃，不去搜开发板原理图（Level 3）反推**

## 偷懒借口表

| 借口 | 现实 |
|------|------|
| "datasheet 找不到" | 用 WebSearch 搜 `[料号] datasheet filetype:pdf`，搜 LCSC/立创商城页面提取参数，搜开发板原理图反推 |
| "芯片不公开 datasheet" | 搜代理商页面、搜开发板原理图、搜 SDK 头文件中的寄存器定义、从 LCSC 产品页提取引脚图和参数表 |
| "NET 追踪太复杂" | 写 Python 脚本自动追踪，不要手动看 |
| "待确认" | 不是结论。必须附带：谁来确认、怎么确认、确认什么 |
| "基于一般经验" | 不接受。给出 datasheet 页码或参考设计编号 |
| "差不多对" | 硬件没有差不多。对就是对，不对就是不对 |
| "时间不够做完整验证" | 做一半的验证比不做更危险——给用户虚假的安全感 |
| "主芯片验证完了，其他 IC 简单看看就行" | 每个 IC 都可能有致命错误。传感器接错引脚和 MCU 接错引脚一样危险 |
| "这个器件简单，不需要查 datasheet" | 简单器件也有极性、额定值、推荐电路。CUS08F30 接反了就不是保护而是短路 |
| "产品页参数够用了" | 产品页没有参考电路、没有时序图、没有绝对最大额定值。如果官方有 PDF，必须下载 |
| "关键电路我标了 ⚠️，用户自己去确认" | 关键电路是你的核心职责。⚠️ 意味着你还没做完，不是把责任甩给用户 |
| "datasheet 里没有参考电路" | 搜开发板原理图（Level 3）、搜 GitHub 上的开源项目、搜同芯片的其他产品拆解。参考电路一定存在 |
| "晶振/天线是被动元件，不需要 datasheet" | 晶振有负载电容要求，天线有阻抗匹配要求，这些参数必须从 datasheet 获取才能验证电路 |
| "Phase 1 已经结束了，不回头补资料" | Phase 之间没有单向门。Phase 2 发现缺信息，立刻回去搜索获取，然后继续 Phase 2。不要带着信息缺口往前走 |

---

## 能力 1：读原理图（嘉立创 EDA .epro2）

### 文件结构

```
*.epro2 (ZIP 压缩包)
├── project2.json          # {"title":"xxx","editorVersion":"3.2.91"}
├── IMAGE/                 # 图片资源
└── *.epru                 # 核心数据（管道分隔 NDJSON，每行一条记录）
```

### .epru 记录格式

每行：`{header_json}||{body_json}|`

header 包含 `type`（记录类型）和 `id`（记录标识）。

### 关键记录类型

| type | 含义 | body 中的关键字段 |
|------|------|------------------|
| DOCHEAD | 文档头 | `docType`: SCH / SCH_PAGE / PCB / BOARD / FOOTPRINT / SYMBOL / DEVICE |
| COMPONENT | 元件实例 | `partId`（元件型号标识，如 `MAX98357AETE+T.1`）|
| ATTR | 元件属性 | `key` + `value`，如 `Designator=R1`, `Value=10K` |
| PIN | 引脚 | `partId`, 位置, 方向 |
| NET | 网络 | 网络名称 |
| PAD_NET | 焊盘网络 | PCB 焊盘到网络的映射 |
| WIRE | 导线 | 原理图连线的起止坐标 |

### 解析脚本

项目目录下有 `hw-review/parse_epro2.py`，直接运行：

```bash
python3 hw-review/parse_epro2.py project.epro2 /path/to/output/
```

### partId 到实际料号的转换

partId 末尾通常有 `.1` 后缀，去掉即为料号。例如：
- `MAX98357AETE+T.1` → `MAX98357AETE+T`
- `2N7002T_C7507460.1` → `2N7002T`（`_C7507460` 是立创商城编号）
- `CL05A105KA5NQNC.1` → `CL05A105KA5NQNC`

---

## 能力 2：Datasheet 管理

### 铁律

```
BOM 中每个 IC 必须有 datasheet 或等效参数来源。没有例外。
有官方 PDF 的器件必须下载 PDF（Level 1），不能偷懒只取产品页参数。
关键被动元件（晶振、天线、电感）也必须获取 datasheet。
Phase 2 中发现缺少任何器件的信息，立刻回头搜索获取，不要带着缺口继续。
```

### 获取流程（按优先级）

对 BOM 中每个 IC，按以下顺序尝试获取 datasheet：

**Level 1：完整 PDF datasheet（必须优先尝试）**
```
WebSearch("[料号] datasheet filetype:pdf")
WebSearch("[料号] product specification site:[厂商官网]")
WebFetch(url) → 保存到 datasheets/[料号]_datasheet.pdf
```

**Level 2：产品页参数提取（仅当 Level 1 确实不可得时）**
```
WebSearch("[料号] site:lcsc.com")
WebSearch("[料号] site:jlcpcb.com/partdetail")
WebFetch(产品页URL) → 提取引脚图、关键参数、封装信息
→ 写入 datasheets/[料号]_params.md
```

**Level 3：开发板原理图反推（当芯片不公开 datasheet 时）**
```
WebSearch("[芯片型号] reference design schematic")
WebSearch("[芯片型号] evaluation board schematic")
→ 写入 datasheets/[料号]_ref_circuit.md
```

**Level 4：SDK/头文件反推（最后手段）**
```
WebSearch("[芯片型号] SDK register definition github")
→ 写入 datasheets/[料号]_from_sdk.md
```

### 获取级别判定标准

**必须达到 Level 1 的器件：**
- 主 MCU/SoC
- 大厂器件（TI、Nordic、Maxim、Toshiba、Nexperia、Vishay、TXC 等）——这些厂商的 datasheet 一定公开可下载
- 任何连接到关键电路（电源/射频/USB/充电）的 IC
- **关键被动元件：晶振（需要 CL 值）、天线（需要阻抗参数）、电感/磁珠（需要阻抗曲线）**

**允许 Level 2 的器件：**
- 国产小厂芯片（确实不公开 datasheet）
- 已停产且 PDF 已从网上消失的器件
- 必须在 index.md 中记录"已尝试 Level 1 获取，搜索关键词为 XXX，未找到 PDF"

**关键电路的参考设计获取：**
当 datasheet 中没有参考电路时，不能放弃。必须继续搜索：
- `[芯片型号] reference design schematic`
- `[芯片型号] evaluation board schematic`
- `[芯片型号] 开发板 原理图 github`
- `[芯片型号] open source hardware`
找到后提取参考电路，写入 datasheets/[料号]_ref_circuit.md

### index.md 状态规则

```
✅ 已获取 = 有 PDF 文件或完整参数文件在 datasheets/ 目录中
⚠️ 仅参数 = 只有 Level 2/3/4 的部分信息，且已确认 Level 1 不可得
❌ 未获取 = 不可接受，审查不能继续
```

---

## 能力 3：NET 拓扑追踪

手动看 NET 名称（如 `$1N52`）毫无意义。必须用脚本自动追踪每个 NET 连接了哪些元件的哪些引脚。

### 追踪输出要求

对每个 IC 的每个引脚，必须追踪到完整的连接链：

```
U2.Pin9 (VPWR) → NET:P9_VBUS → USBC1.A4(VBUS), C12(100nF)→GND, C7(1uF)→GND
```

不接受的输出：
```
U2.Pin9 → P9_VBUS (待追踪)
U2.Pin12 → $1N65 (网络名无意义，未追踪)
```

**每个 `$1Nxx` 格式的网络名都必须追踪到实际连接的元件。** 这是自动生成的匿名网络，对人类没有任何信息量。

**不要跳过 NET 追踪。** 如果追踪脚本不工作，调试脚本，不要手动标注"待确认"。

---

## 能力 4：引脚验证

### 核心规则

```
每个 IC 的每个引脚都必须验证。不只是主芯片。
```

**验证覆盖范围：**
- 主 MCU/SoC：逐引脚验证，输出完整引脚表
- 传感器/Flash/音频IC：逐引脚验证，和 datasheet 推荐电路对照
- 连接器（USB-C、SD卡座）：逐引脚验证引脚映射
- 晶体管/二极管：验证极性、连接方向、额定值
- ESD 保护器件：验证保护方向和被保护信号

**不接受"这个器件简单不需要验证"。** 二极管接反了就是短路。MOSFET 的 D/S 接反了就不导通。

### 关键电路深度验证

以下电路不允许有 ⚠️ 状态，必须完全验证或明确标记为 ❌：

**电源电路：**
- 电池输入路径：VBAT → 所有连接的元件
- 充电输入路径：USB VBUS → 充电 IC → 电池
- LDO 输出：去耦电容值和位置
- 每个电源网络（VCC、VCC_SD 等）的来源和负载

**射频电路：**
- 天线匹配网络：每个元件的值，和 datasheet 参考电路逐元件对照
- 如果 datasheet 有参考电路，匹配网络必须完全一致（或记录偏差原因）

**USB 电路：**
- D+/D-：串联电阻、ESD 保护
- CC1/CC2：下拉电阻值（Sink 设备需要 5.1K）
- VBUS：过压/过流保护
- 连接器引脚映射：必须查连接器 datasheet 确认每个引脚对应什么功能

**充电电路：**
- 充电 IC 的输入/输出/使能/指示
- 如果没有充电 IC，必须明确标注并询问用户充电方案

### 每个发现必须包含

```markdown
### [编号] 标题

**证据来源：** [datasheet 名称，第 X 页 / 章节 Y.Z] 或 [参考设计 URL]
**原理图现状：** [从 .epru 解析出的实际连接]
**应该是什么：** [datasheet 推荐的连接方式]
**严重程度：** 严重 / 中等 / 建议
**下一步：** [具体的确认或修复动作]
```

**没有"证据来源"的发现不是发现，是猜测。删除它或补充证据。**

### 验证状态定义

```
✅ 验证通过 = 与 datasheet 推荐一致，有证据
❌ 偏差 = 与 datasheet 不一致，附证据和偏差描述
⚠️ 无法验证 = 缺少 datasheet 信息，附具体缺什么和怎么获取

关键电路中 ⚠️ 不可接受。必须追查到 ✅ 或 ❌。
```

---

## 能力 5：软硬件对齐

当项目同时包含硬件设计和固件代码时，检查两侧一致性。

### 检查项

1. **Devicetree ↔ 原理图**：DTS 引脚编号 ↔ 原理图实际连线
2. **Kconfig ↔ 硬件能力**：prj.conf 启用的功能 ↔ 芯片是否支持
3. **驱动代码 ↔ 传感器 datasheet**：寄存器地址 ↔ datasheet 定义

---

## 工作流程

### Phase 1：项目解析与文档准备

```
1. 扫描项目目录 → 找到所有硬件文件
2. 解压 .epro2 → 运行 parse_epro2.py
3. 提取完整 BOM → 识别所有 IC 和有源器件
4. 识别多版本情况 → 确认当前版本，列出历史版本
5. 创建 datasheets/ 目录
6. 对每个 IC 执行 datasheet 获取流程：
   a. 先尝试 Level 1（WebSearch + WebFetch 下载 PDF）
   b. Level 1 失败 → 记录搜索关键词 → 尝试 Level 2
   c. 大厂器件 Level 1 失败 = 搜索不够努力，换关键词再搜
7. 生成 datasheets/index.md（检查：无 ❌ 状态）
8. 生成 hw-review-status.md
```

**Phase 1 完成标准：**
- [ ] BOM 提取完成，所有 partId 已转换为料号
- [ ] datasheets/index.md 中没有 ❌ 状态
- [ ] 大厂器件全部 Level 1（有 PDF）
- [ ] hw-review-status.md 已生成，包含完整 BOM 表
- [ ] 每个 datasheets/ 下的 _params.md 文件都包含：引脚定义表、关键电气参数、参考电路（如有）

**如果 Phase 1 完成标准未满足，不得进入 Phase 2。**

### Phase 2：原理图审查

```
1. 运行 NET 拓扑追踪 → 输出 net_topology.json
   - 每个 $1Nxx 网络必须追踪到实际元件
   - 追踪结果不完整 → 调试脚本，不要跳过
2. 对每个 IC（不只是主芯片！）：
   a. 读取 datasheets/ 中的对应文档
   b. 提取引脚定义和参考电路
   c. 从 NET 拓扑中找到该 IC 每个引脚的实际连接
   d. 逐引脚对照 datasheet → 输出引脚验证表
   e. 记录每个发现（必须附证据来源）
   ⚠️ 如果验证过程中发现缺少某个器件的 datasheet（比如晶振的 CL 值、
   天线的阻抗参数），立刻暂停验证，回去用 WebSearch + WebFetch 获取，
   获取后继续验证。不要标"缺少数据"然后跳过。
3. 关键电路深度验证：
   - 电源：追踪每条电源网络的来源和所有负载
   - 射频：匹配网络逐元件与参考电路对照
     → 如果主芯片 datasheet 无参考电路，搜开发板原理图（Level 3）
     → 如果开发板也找不到，搜同芯片的开源项目获取匹配参数
   - USB：CC 引脚映射、D+/D- 保护、VBUS 保护
   - 充电：充电路径完整性
   每条关键电路不允许有 ⚠️ 状态
4. 被动元件参数计算验证：
   - 限流电阻：计算实际电流 I=(V1-V2-Vdrop)/R，和额定值对比
   - 去耦电容：和 datasheet 推荐值对比
   - 上下拉电阻：和协议规范对比（如 USB CC 需要 5.1K±10%）
   - 分压电阻：计算分压比
   - 晶振负载电容：CL=(C1*C2)/(C1+C2)+Cstray，和晶振 datasheet 的 CL 值对比
     → 晶振 datasheet 没获取？立刻去搜索下载，不要用"典型值"猜测
5. 检查 Designator 规范性
6. 生成 hw-review-findings.md
```

**Phase 2 完成标准：**
- [ ] **每个 IC**（不只是主芯片）的每个引脚都有验证状态
- [ ] 关键电路（电源/射频/USB/充电）无 ⚠️ 状态
- [ ] 每个 ❌ 发现都有证据来源（datasheet 页码或 URL）
- [ ] 被动元件的关键参数已计算验证（限流电流、负载电容、分压比等）
- [ ] 连接器引脚映射已用 datasheet 确认（不是靠猜）

### Phase 3：软硬件对齐（如有固件）

```
1. 找到固件代码中的 DTS/Overlay 文件
2. 提取 DTS 中的引脚定义
3. 与 Phase 2 中原理图的引脚连接逐一对照
4. 检查 prj.conf 中的功能配置
5. 追加发现到 hw-review-findings.md
```

### Phase 4：构建验证（如有固件和硬件）

```
1. west build → 记录结果
2. 检查 Flash/RAM 占用
3. west flash + 基本功能验证
```

---

## 输出产物

| 文件 | 内容 | 完成标准 |
|------|------|---------|
| `datasheets/` | 芯片手册和参数文件 | 大厂 Level 1，其他至少 Level 2 |
| `datasheets/index.md` | 索引，无 ❌ 状态 | 大厂全 ✅，其他允许 ⚠️ |
| `hw-review-status.md` | BOM、文件清单、引脚分配 | 完整、无遗漏 |
| `hw-review-findings.md` | 问题清单，每条附证据 | 无空证据来源，关键电路无 ⚠️ |
| `hw-lessons-learned.md` | 踩坑记录 | 有则记录 |

---

## 多版本处理

一个 .epro2 文件可能包含多个历史版本的原理图和 PCB。

**处理方法：**
1. 列出所有 DOCHEAD，按 `updateTime` 排序
2. 识别最新的 SCH_PAGE 作为当前版本
3. 明确告知用户："项目中包含 N 个历史版本，当前分析基于最新版本 [版本标识]"
4. 建议用户清理不再需要的历史版本，避免混淆

---

## 使用方式

- **"帮我看看这个原理图"** → Phase 1 + Phase 2
- **"帮我管理 datasheet"** → Phase 1 中的 datasheet 获取流程
- **"帮我检查软硬件是否对齐"** → Phase 3
- **"全面审查这个项目"** → Phase 1 → 2 → 3 → 4
- **"这个引脚接对了吗"** → 读 datasheet + NET 追踪 + 单引脚验证