bom

BOM 管理

BOM 数据存储在 KiCad 原理图符号属性中，作为唯一事实来源。此技能负责协调完整生命周期：分析原理图、搜索分销商、验证元件、将属性写回、导出跟踪 CSV，并生成订购文件。

相关技能

技能	用途
kicad	读取/分析原理图、PCB、封装
digikey	搜索 DigiKey、下载数据手册（原型首选来源）
mouser	搜索 Mouser（原型备用来源）
lcsc	搜索 LCSC（生产/JLCPCB 元件）
element14	搜索 Newark/Farnell/element14（国际渠道）
jlcpcb	PCB 制造与组装订购
pcbway	备选 PCB 制造与组装

脚本

使用 <skill-path> 指代 BOM 技能目录。

# Analyze schematic (JSON output, recursive sub-sheets)
python3 <skill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive

# Export BOM tracking CSV (creates new or merges with existing)
python3 <skill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive

# Generate per-distributor order files (5 boards + 2 spares/line)
python3 <skill-path>/scripts/bom_manager.py order bom/bom.csv --boards 5 --spares 2

# Quick single-distributor order (bypasses Chosen_Distributor column)
python3 <skill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey

# Write properties to schematic (dry-run first, then apply)
echo '{"R1": {"MPN": "RC0805FR-0710KL", "Manufacturer": "Yageo"}}' \
  | python3 <skill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch --dry-run

# Sync datasheet URLs from manifest.json back into schematic Datasheet properties
python3 <skill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive --dry-run

# Translate KiCad/Altium BOM and CPL files into JLCPCB upload format
# (`pnp --bom` filter drops orphan designators — see skills/jlcpcb/SKILL.md
# for the 3-step PCBA upload workflow)
python3 <skill-path>/scripts/translate_bom_pnp.py bom input_bom.csv -o jlc_bom.csv
python3 <skill-path>/scripts/translate_bom_pnp.py pnp input_cpl.csv -o jlc_cpl.csv --bom jlc_bom.csv

工作流

跳过不适用的步骤。常见快捷操作：

• “添加 Mouser PNs” — 按 MPN 搜索每个元件的 Mouser → 验证 → 写入原理图 → 更新 CSV
• “补全缺失项” — 使用 --gaps-only 运行分析器，逐项处理缺失字段
• “更新数据手册 URL” — 运行 sync_datasheet_urls.py，从数据手册清单补全空的 Datasheet 字段
• “准备生产” — 确保每个元件都有 LCSC 编号，检查库存，将 Chosen_Distributor 设为 LCSC

步骤 1：了解项目

python3 <skill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive

输出会告知你项目的字段命名惯例、已填写哪些分销商信息、缺少哪些信息，以及首选分销商。还要在项目目录或 bom/ 文件夹中查找现有的 BOM 跟踪 CSV。

该脚本覆盖了常见模式，但有些项目会使用内部编号系统或参数字段。完整目录请参阅 references/part-number-conventions.md。如果有任何异常，请阅读原理图。

步骤 2：同步数据手册

立即执行此步骤。 数据手册是验证和元件选型的重要参考。先运行首选分销商的同步脚本；如果有些下载失败，再尝试其他分销商——它们共用同一个 datasheets/ 目录，并会跳过已下载的元件。

python3 <digikey-skill-path>/scripts/sync_datasheets_digikey.py path/to/schematic.kicad_sch --recursive
python3 <lcsc-skill-path>/scripts/sync_datasheets_lcsc.py path/to/schematic.kicad_sch --recursive
python3 <element14-skill-path>/scripts/sync_datasheets_element14.py path/to/schematic.kicad_sch --recursive

DigiKey 最佳（提供直接 PDF URL）。element14 较可靠（没有机器人防护）。LCSC 适用于仅在 LCSC 销售的元件。Mouser 是最后的选择（经常阻止下载）。

告知用户数据手册所在位置（例如 hardware/<project>/datasheets/）。他们会经常查阅这些文件。

跨修订版本项目： 在项目级别使用一个共享的数据手册目录，而不要为每个修订版本单独创建目录。相同 MPN 的数据手册不会因修订版本而变化。

写入新的 MPN 后（步骤 5）重新同步——这些脚本具有幂等性。然后将数据手册 URL 补入原理图：

python3 <skill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive

此脚本会读取 datasheets/manifest.json（仍支持旧名称 index.json），并将发现的数据手册 URL 写入原理图中空白的 Datasheet 属性。这是机会式补全——只填充空白项。如果原理图中已有不同的 URL，它会警告不匹配，但不会覆盖（使用 --overwrite 替换）。先使用 --dry-run 运行以预览结果。

步骤 3：收集元件信息

留意以逗号分隔的 MPN。 有些符号会记录多个实物元件（例如电池座 + 电池夹）。按逗号拆分，并分别搜索每个 MPN——搜索合并后的字符串会匹配到错误的产品。

根据现有信息选择搜索策略：

• 有 MPN → 按 MPN 搜索分销商，获取其 PN 和库存信息
• 有分销商 PN 但没有 MPN → 在该分销商处搜索，获取 MPN，再搜索其他分销商
• 只有 Value + Footprint → 按描述搜索（例如 “100nF 0402 X7R 16V”）

优先使用项目的首选分销商，再尝试其他渠道。原型：DigiKey 为首选，Mouser 为备用。生产：LCSC。

步骤 4：验证匹配结果

不要假定现有的 PN 正确——经销商 PN 可能会过时（停产、重新编号）。通过 API 验证现有 PN 是否有效。如果 PN 返回 404，请标记并替换。

对于每个匹配项，请验证：

1. 封装与原理图封装相符（请参见下方的交叉引用表）
2. 规格相符（电容、电阻、电压、容差）
3. 描述合理（电阻的位号应对应电阻）
4. 生命周期——未停产或 EOL
5. 数据手册 URL 是直接 PDF 链接（而非产品页面）

如果无法确定，请询问用户。错误的器件比缺少器件更糟。

步骤 5：更新原理图

与 KiCad 共存。 脚本会检测 KiCad 的锁文件并发出警告，但仍会继续运行。KiCad 不会自动检测外部更改——它会保留内存中的副本。如果 KiCad 处于打开状态，请告知用户：“关闭并重新打开原理图（File → Open Recent）以查看更改。请勿先从 KiCad 保存。”

如果 KiCad 中有未保存的工作，请先让用户保存（Ctrl+S），然后运行脚本，再重新打开。

echo '{"R1": {"MPN": "RC0805FR-0710KL", "Manufacturer": "Yageo", "DigiKey": "311-10.0KCRCT-ND"}}' \
  | python3 <skill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch

备份： 默认不会创建 .bak 文件（git 会跟踪更改）。如果原理图不在 git 仓库中，或有用户想要保留的未提交更改，请传入 --backup。

遵循项目的惯例。 如果现有字段是 "Digi-Key_PN"，就写入该字段，而不是 "DigiKey"。仅在新项目中使用规范名称。

始终将 Manufacturer 与 MPN 一并写入——每个 API 都会返回该数据，且无需额外费用。

步骤 6：更新 BOM 跟踪 CSV

python3 <skill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive

CSV 列是动态的——只有项目使用的经销商才会有对应列。基础列：Reference、Qty、Value、Footprint、MPN、Manufacturer。每个启用的经销商都会有一个 PN 列和一个库存列。末尾列：Chosen_Distributor、Datasheet、Validated、DNP、Notes。

首次导出时，Notes 列会从原理图的 BOM Comments 属性（或 Notes、Remarks、Ordering Notes 等别名）填充。重新导出时，CSV 中用户所做的编辑优先——现有 Notes 值会被保留，原理图中的注释不会覆盖这些值。

合并行为： 重新导出时会保留由用户管理的列（库存、Chosen_Distributor、Validated、Notes），同时更新源自原理图的列。

步骤 7：检查库存

对于每个具有经销商 PN 的器件，通过对应的经销商技能查询当前库存。更新 CSV 中的库存列。库存数据会过时——请注明日期，并在下单前重新检查。

如果所选经销商缺货，请标记并建议备选经销商。

步骤 8：设置所选经销商

考虑因素：库存情况、订购数量对应的价格、起订量/倍数、交货时间、运输整合（经销商越少，发货次数越少）。

对于原型，尽量集中在 1 至 2 家经销商（DigiKey + Mouser）。对于量产，LCSC/JLCPCB 最便宜。

步骤 9：重新同步数据手册和 URL

重新执行步骤 2（下载 + URL 回填），以获取步骤 3 至 5 中添加的器件。速度很快——已下载的文件会跳过。

步骤 10：根据设计验证数据手册

阅读已下载的数据手册，验证器件在电路中是否功能正确。这可以发现步骤 4 可能遗漏的器件料号错误。

按类型检查：

• 无源器件——额定电压与电源轨电压是否匹配、温度系数、功耗
• 稳压器——Vin 范围、Vout、最大电流、静态电流
• MCU/IC——电源电压、I/O 电平、外设、引脚排列
• 连接器——引脚数、间距、电流/电压额定值
• MOSFET——Vds、Rds(on)、栅极阈值、热耗散
• 二极管——Vf、Vr、电流额定值、恢复时间

对于大型 BOM（50 个以上器件），重点检查电源器件、关键信号路径，以及用户标记的器件。常见无源器件通常无需深入审查。

步骤 11：生成订单文件

如果尚不清楚，请询问有几块板 — 这将设置 --boards 倍数。

生成前检查： 确认没有缺漏、CSV 为最新版本、已设置 Chosen_Distributor（或使用 --distributor 标志），且库存信息为最新。

# Using Chosen_Distributor column, 5 boards + 2 spares
python3 <skill-path>/scripts/bom_manager.py order bom/bom.csv -o bom/orders/ --boards 5 --spares 2

# Or quick single-distributor order
python3 <skill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey

--boards 会将所有数量相乘。--spares 会在相乘后为每一行额外增加固定数量。--distributor 会跳过 Chosen_Distributor，为所有具有该分销商 PN 的零件生成订单。

逗号分隔的 PN（配件）会自动拆分为单独的订单行。排除 DNP 零件。脚本会为每个分销商生成一个文件，格式与其上传格式相匹配（格式详情请参阅 references/ordering-and-fabrication.md）。

展示订单摘要，并让用户在下单前检查和编辑。

成本估算： 生成订单文件后，根据订单数量查询分销商 API 的价格，并列出每个分销商的总价。成本摘要模板请参阅 references/ordering-and-fabrication.md。

BOM 特殊情况与单个元件备注

实际项目中的 BOM 往往有一些无法整齐归入标准字段的特殊情况。这些信息可能在设计和下单之间遗失——例如仅用于原型制作的连接器、两块板共用的线缆，或必须从特定供应商批次订购的零件。进行 BOM 分析时，请主动查找这些信息；不要等用户提起。

BOM Comments 字段

BOM Comments 符号属性（规范名称）用于记录单个元件的自由格式备注。该信息会写入导出 CSV 的 Notes 列。脚本可以识别许多别名：BOM Notes、Ordering Notes、Assembly Notes、Notes、Remarks、Comment，以及使用下划线或空格的变体。

建议添加 BOM Comments 的情况：

• 元件仅用于原型制作（量产时 DNP，或反之）
• 元件有订购限制（最低订购量、交期较长、指定供应商批次）
• 元件与另一块板共用（排线、配对连接器、共用线束）
• 元件有装配备注（方向有要求、仅限手工焊接、回流焊后安装）
• 元件有替代规则（可接受的替代品、引脚兼容的替换件）
• 元件有条件装配要求（不同产品变体/SKU 使用不同规格）

示例值：

"Proto only — DNP in production"
"Shares ribbon cable with power board — don't double-order"
"Must be Murata GRM series, no substitution (validated for EMI)"
"Hand-solder after reflow — temperature sensitive"
"Order 10% extra — fragile QFN rework difficult"
"Use 10K for rev A, 4.7K for rev B"
"Mating connector: Molex 39-01-2040 on cable side"

还可从哪些位置查找 BOM 特殊信息

原理图符号属性是记录单个元件备注的最佳位置，但项目可能会将这些信息分散在各处。请检查以下所有位置：

1. 原理图文本注释 — 放置在原理图页上的自由文本。kicad 技能的分析器会将这些内容提取为 text_annotations。查找元件附近有关订购、装配或产品变体的备注。

2. 标题栏注释 — 标题栏包含带编号的注释字段，有时会用于记录板级 BOM 备注（“所有无源元件均为 0402，另有标注的除外”“原型请从 DigiKey 订购”）。

3. 项目 README / 文档 — 查找 README.md、docs/、bom/README.md，或任何提及零件、订购或装配的文本文件。这些通常包含 BOM 决策中的最高层级信息。

4. 现有 BOM CSV 的 Notes 列 — 如果已存在 bom.csv，请阅读 Notes 列。用户可能已在其中添加原理图里没有的备注。

5. 项目级配置（.kicad-happy.json）— preferred_suppliers 设置采购优先级，bom 部分设置字段命名和分组约定。完整架构请参阅 skills/kicad/references/config-reference.md。

6. 原理图符号的 Description 字段 — 有时该字段用于记录装配备注，而不是零件描述（例如：“100nF 去耦电容——安装在靠近 U3 引脚 4 的位置”）。

7. 名称不标准的 KiCad 自定义字段 — Assembly、Order、Variant、Config、SKU 等字段可能包含与 BOM 相关的信息。分析器会将这些标记为 unrecognized_fields。

8. 附带说明的 DNP 元件 — 对于 DNP 元件，可能需要注明其 DNP 的原因以及何时应进行装配。KiCad 的 DNP 标志是布尔值，原因应记录在 BOM Comments 中。

多板／系统级 BOM 注意事项

当一个项目包含多个电路板（例如主板 + 子板，或发送板 + 接收板）时：

• 共用线缆／连接器 — 在两块板上都注明各连接器的配对关系，并在两块板共用的线缆旁注明“不要重复订购”
• 共用电源 — 如果多块板共用一个电源，请注明由哪块板的 BOM 包含该电源
• 多块板共用的元件 — 订购时，合并统计各板上的数量。在每块板的 BOM 中注明哪些元件为共用元件
• 板卡特定变体 — 如果同一块 PCB 采用不同的焊接选项（例如针对不同输出电压使用不同阻值的电阻），请在 BOM Comments 中说明变体规则

非 BOM 项目

有些项目专用物品不会出现在原理图上，但需要与 BOM 一起订购。以下物品经常被遗漏：

• 配对连接器和线缆 — 如果原理图中有连接器，也需要订购与之配对的另一半（板对板连接器、排线、线束）
• 钢网 — 与 PCB 一起订购带框钢网（从 JLCPCB／PCBWay 订购约 $7）
• 编程／调试适配器 — Tag-Connect 线缆、SWD 排线，或适用于电路板调试连接器的专用 USB 线缆
• 天线线缆 — 如果电路板有 RF 连接器，则需要 U.FL 转 SMA 尾纤
• 安装硬件 — 适配外壳的隔离柱、螺钉、螺母
• 热管理用品 — 特定元件所需的散热器、导热垫

将这些物品作为行记录在 BOM CSV 中，Reference = -- 并填写备注；也可以单独记录在 bom/non-bom-items.csv 中。在成本估算中单独列出这些物品。

展示 BOM 备注

生成报告或订购摘要时，务必醒目地展示 BOM 备注 — 这些备注体现了设计者对例外情况和易忽略问题的说明。不要将其埋在其他内容中。在订购摘要中，主表格之后单独列出带有 BOM 备注的元件，确保用户在点击“订购”之前就能看到这些备注。

封装／焊盘交叉索引

英制	公制	KiCad 封装
0201	0603	R_0201_0603Metric
0402	1005	R_0402_1005Metric
0603	1608	R_0603_1608Metric
0805	2012	R_0805_2012Metric
1206	3216	R_1206_3216Metric

根据需要将 R_ 替换为 C_ 或 L_。前缀使用 Resistor_SMD:、Capacitor_SMD: 等。

BOM 差异比较

原理图在不同版本之间发生变化时，比较新旧 BOM，以识别新增、移除和变更的元件。突出显示需要采购的新增元件。

交互式 BOM（ibom）

生成一个 HTML 页面，显示元件在 PCB 上的位置 — 对手工组装至关重要。

pip install InteractiveHtmlBom
generate_interactive_bom board.kicad_pcb \
  --dest-dir bom/ --name-format "%f_ibom_%r" \
  --extra-fields "MPN,Manufacturer,DigiKey,Mouser,LCSC" \
  --group-fields "Value,Footprint,MPN" \
  --checkboxes "Sourced,Placed" --dnp-field "DNP" --no-browser

参考文件

需要详细查询数据时，请阅读以下文件：

• references/kicad-fields.md — 字段定义、别名、S 表达式格式、料号模式
• references/ordering-and-fabrication.md — 分销商粘贴格式、Gerber 导出、CPL、成本模板
• references/part-number-conventions.md — 对 56+ 个真实项目中命名模式的详细分析

生产就绪检查清单

• 所有元件都有 MPN 和 LCSC 编号（用于 JLCPCB），或 MPN（用于 PCBWay）
• 没有过时或已停产的元件
• 已验证库存，并区分基础元件和扩展元件
• 已按正确格式导出 BOM 和 CPL
• 已导出并验证 Gerber 文件
• 设计规则符合制造商的最低要求（参见 jlcpcb 或 pcbway 技能）
• 原型已完成全面测试

生成的文件与清理

BOM 和分销商技能会在项目目录树中创建文件。了解这些文件是什么，以便清理它们或将其加入 .gitignore。

在项目目录中创建的文件

文件/目录	创建者	用途	是否纳入 git？
datasheets/	DigiKey、LCSC、element14、Mouser 同步脚本	下载的 PDF 数据手册	否 — 大型二进制文件，可重新下载
datasheets/manifest.json	数据手册同步脚本	跟踪每个 MPN 的下载状态（旧名称：index.json）	否 — 由同步脚本重新生成
bom/bom.csv	bom_manager.py export	BOM 跟踪表格	是 — 用户整理的数据
bom/orders/*.csv	bom_manager.py order	各分销商的订单上传文件	否 — 每次下单前重新生成
*.YYYYMMDD_HHMMSS.bak	edit_properties.py --backup	编辑前的原理图备份	否 — 请改用 git

kicad 技能还会创建分析器 JSON 和设计评审 Markdown 报告，文件名由用户指定 — 请参阅其“生成的文件”部分，了解跟踪和清理指南。

临时文件（项目外）

文件	位置	用途
digikey_token_cache.json	系统临时目录	OAuth 令牌缓存（TTL 为 9 分钟，模式为 0600）
manifest.tmp	datasheets/	原子写入暂存文件 — 重命名为 manifest.json，不会持久保留

清理命令

# Remove downloaded datasheets (re-downloadable)
rm -rf datasheets/

# Remove order files (regenerate before ordering)
rm -rf bom/orders/

# Remove schematic backups
rm -f *.bak

# Remove KiCad analyzer/report files (filenames vary — check project instructions file)

建议添加到 .gitignore 的内容

# BOM skill working files
datasheets/
bom/orders/
*.bak

请将 bom/bom.csv 纳入版本控制 — 其中包含无法仅从原理图重新生成的用户整理数据（Chosen_Distributor、Validated、Notes）。

提示

• MPN 是通用键 — 请先填写，以便交叉引用所有内容
• 原理图是事实来源 — 所有 BOM 数据都在符号属性中，按需导出
• 原型制作优先使用 DigiKey，其次使用 Mouser；量产使用 LCSC
• CSV 往返处理 — 使用 Edit Symbol Fields > Export/Import CSV 进行批量更新
• Field Name Templates（KiCad 9+）— 预先定义 MPN、Manufacturer、LCSC、DigiKey、Mouser
• DigiKey 令牌复用 — 缓存到临时文件，TTL 为 9 分钟；每次调用无需重新验证身份
• 第二来源 — 对关键元件使用 AltMPN 字段
• 目标数量对应的价格 — 原型价格 ≠ 量产价格
• BOM 备注 — 对于无法放入标准字段的订购/组装特殊情况，请使用 BOM Comments 符号属性。内容会写入 CSV 的 Notes 列。也请检查原理图文本注释、README 和现有 CSV 备注，查找零散的 BOM 信息。