component-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Search (LCSC + easyeda2kicad)

元件搜索（LCSC + easyeda2kicad）

Find and add component packages to a Zener project without relying on a private registry. The pipeline is:

MPN  ──►  LCSC C-number  ──►  easyeda2kicad  ──►  .kicad_sym + .kicad_mod + .step  ──►  Zener wrapper (.zen)

Use this workflow any time you need a part that isn't already in the workspace

components/

tree or covered by stdlib generics (

@stdlib/generics/Resistor.zen

Capacitor.zen

Led.zen

Thermistor.zen

, …).

无需依赖私有注册表，即可在Zener项目中查找并添加元件封装。流程如下：

MPN  ──►  LCSC C编号  ──►  easyeda2kicad  ──►  .kicad_sym + .kicad_mod + .step  ──►  Zener封装文件(.zen)

当你需要的元件不在工作区

components/

目录树中，也未被stdlib泛型（

@stdlib/generics/Resistor.zen

、

Capacitor.zen

、

Led.zen

、

Thermistor.zen

等）覆盖时，可使用此工作流。

Hard Stop Before Manual Creation

手动创建前的强制检查

If LCSC has no entry for the MPN, or

easyeda2kicad

fails on the resolved C-number, don't fall back to hand-drawing a symbol/footprint silently. Report what failed, offer manual creation as an option, and get explicit user confirmation.

如果LCSC中没有该MPN的条目，或者

easyeda2kicad

解析对应的C编号失败，请勿直接手动绘制符号/封装。请报告失败原因，将手动创建作为可选方案，并获得用户的明确确认。

Search Priority

搜索优先级

Always search in this order. Move down only when the higher tier doesn't apply.

Workspace
components/
tree —
```
glob
```
or
```
finder
```
for the MPN. If the part is already imported, reuse it via
```
Module("./components/<Mfr>/<MPN>/<MPN>.zen")
```
.
stdlib generics — for plain R, C, L, LED, diode, NPN/PNP, MOSFET, thermistor: use the generic, never import a vendor part.
LCSC + easyeda2kicad — for ICs, modules, connectors, crystals, anything with a specific MPN.

请始终按照以下顺序进行搜索。仅当更高优先级的选项不适用时，才向下选择。

工作区
components/
目录树 — 使用
```
glob
```
或
```
finder
```
查找MPN。如果元件已导入，请通过
```
Module("./components/<Mfr>/<MPN>/<MPN>.zen")
```
复用。
stdlib泛型 — 对于普通电阻（R）、电容（C）、电感（L）、LED、二极管、NPN/PNP三极管、MOSFET、热敏电阻：使用泛型元件，切勿导入供应商特定元件。
LCSC + easyeda2kicad — 适用于IC、模块、连接器、晶振等带有特定MPN的元件。

Step 1 — MPN → LCSC C-number

步骤1 — MPN → LCSC C编号

LCSC parts have a numeric

Cxxxxxx

ID. easyeda2kicad needs that ID, not the MPN. Use the agent's web tools:

web_search  query="<MPN> site:lcsc.com"
read_web_page  url=<top LCSC product page>  objective="Find the LCSC C-number (e.g. C25804) and confirm package."

Tips:

LCSC product URLs look like
```
https://www.lcsc.com/product-detail/.../C25804.html
```
— the trailing
```
Cxxxxx
```
before
```
.html
```
is the C-number.
The product page also lists package, datasheet, stock, and price — capture these for the user.
Some MPNs map to multiple C-numbers (different reels, suffixes, manufacturers). Pick the one that matches the requested package and shows real stock.
If no LCSC hit, try the base MPN family (drop
```
-TR
```
,
```
-R7
```
, reel/packaging suffixes).

When the user supplies a C-number directly, skip this step.

LCSC元件带有数字格式的

Cxxxxxx

ID。easyeda2kicad需要该ID，而非MPN。请使用Agent的网页工具：

web_search  query="<MPN> site:lcsc.com"
read_web_page  url=<LCSC顶级产品页面>  objective="查找LCSC C编号（例如C25804）并确认封装类型。"

小贴士：

LCSC产品URL格式为

https://www.lcsc.com/product-detail/.../C25804.html

—

.html

之前的末尾

Cxxxxx

即为C编号。

产品页面还会列出封装类型、 datasheet、库存和价格 — 请为用户收集这些信息。
部分MPN对应多个C编号（不同卷装、后缀、制造商）。请选择与请求封装匹配且有实际库存的编号。
如果未找到LCSC结果，尝试使用基础MPN系列（去掉
```
-TR
```
、
```
-R7
```
等卷装/包装后缀）。

如果用户直接提供了C编号，可跳过此步骤。

Step 2 — Import via easyeda2kicad

步骤2 — 通过easyeda2kicad导入

Resolve the manufacturer and a clean MPN slug first (no spaces, replace

with

). Pick a target package directory under

components/<Manufacturer>/<MPN>/

bash

mkdir -p components/<Manufacturer>/<MPN>
cd components/<Manufacturer>/<MPN>

easyeda2kicad --full --lcsc_id=Cxxxxx --output <MPN> --overwrite

This writes:

```
<MPN>.kicad_sym
```
— symbol library (single symbol)

<MPN>.pretty/<something>.kicad_mod

— footprint, inside a

.pretty

folder

```
<MPN>.3dshapes/<something>.{wrl,step}
```
— 3D model

Flatten the footprint so the Zener wrapper can reference it as a single file next to the

.zen

bash

mv <MPN>.pretty/*.kicad_mod ./<MPN>.kicad_mod
rmdir <MPN>.pretty

(Keep

<MPN>.3dshapes/

as a folder —

.kicad_mod

references the 3D model by relative path inside it.)

If the user wants to skip the 3D model for size, drop

--full

and use

--symbol --footprint

. Note that

pcb

does not require a 3D model to build.

首先解析制造商信息和整洁的MPN标识（无空格，将

替换为

）。在

components/<Manufacturer>/<MPN>/

下选择目标封装目录。

bash

mkdir -p components/<Manufacturer>/<MPN>
cd components/<Manufacturer>/<MPN>

easyeda2kicad --full --lcsc_id=Cxxxxx --output <MPN> --overwrite

此命令会生成：

```
<MPN>.kicad_sym
```
— 符号库（单个符号）

<MPN>.pretty/<something>.kicad_mod

— 封装，位于

.pretty

文件夹内

```
<MPN>.3dshapes/<something>.{wrl,step}
```
— 3D模型

扁平化封装结构，以便Zener封装文件可以在

.zen

旁引用单个文件：

bash

mv <MPN>.pretty/*.kicad_mod ./<MPN>.kicad_mod
rmdir <MPN>.pretty

（保留

<MPN>.3dshapes/

文件夹 —

.kicad_mod

会通过相对路径引用其中的3D模型。）

如果用户希望为节省空间跳过3D模型，可去掉

--full

参数，使用

--symbol --footprint

。注意

pcb

构建不需要3D模型。

Step 3 — Generate the Zener wrapper

步骤3 — 生成Zener封装文件

Use the bundled generator script to turn the imported

.kicad_sym

into a starter

.zen

bash

python3 <SKILL_DIR>/scripts/zener-wrap.py \
  --kicad-sym components/<Manufacturer>/<MPN>/<MPN>.kicad_sym \
  --footprint <MPN>.kicad_mod \
  --mpn <MPN> \
  --manufacturer "<Manufacturer>" \
  --output components/<Manufacturer>/<MPN>/<MPN>.zen

The generator parses the

.kicad_sym

and emits a

.zen

skeleton with:

top docstring (MPN, manufacturer, package — fill in description by hand)
```
mpn
```
/
```
manufacturer
```
configs
one
```
io()
```
per pin, classified as
```
Power
```
,
```
Ground
```
, or generic
```
Net
```
by name
```
Component(...)
```
with the
```
pins=
```
dict mapping the original KiCad pin names to those ios

After generation, read the file and clean it up by hand:

Group related ios (split power, signal, control bundles).
Rename ios to integrator-facing names where it improves clarity (
```
+IN_A
```
→
```
IN_POS_A
```
).
Add
```
voltage="..."
```
to every
```
Power
```
io per the datasheet.
Replace
```
Net
```
with
```
Analog
```
/
```
Digital
```
/ typed interfaces from
```
@stdlib/interfaces.zen
```
where appropriate.
Remove
```
no_connect
```
pins from the
```
pins=
```
dict — leave them out, don't expose as ios.
Drop the auto-generated docstring and replace with a short, integrator-facing one (one paragraph: what it is, where it's used, key constraint).

See

idiomatic-zener

for the full style rules. See

reference-design

if you want to grow the wrapper into a richer reusable design with surrounding circuitry.

使用内置的生成器脚本，将导入的

.kicad_sym

转换为初始

.zen

文件：

bash

python3 <SKILL_DIR>/scripts/zener-wrap.py \
  --kicad-sym components/<Manufacturer>/<MPN>/<MPN>.kicad_sym \
  --footprint <MPN>.kicad_mod \
  --mpn <MPN> \
  --manufacturer "<Manufacturer>" \
  --output components/<Manufacturer>/<MPN>/<MPN>.zen

生成器会解析

.kicad_sym

并输出一个

.zen

框架，包含：

顶部文档字符串（MPN、制造商、封装类型 — 需手动补充描述）
```
mpn
```
/
```
manufacturer
```
配置项
每个引脚对应一个
```
io()
```
，根据引脚名称分类为
```
Power
```
、
```
Ground
```
或通用
```
Net
```
```
Component(...)
```
带有
```
pins=
```
字典，将原始KiCad引脚名称映射到对应的io

生成后，请手动阅读并清理文件：

分组相关的io（拆分电源、信号、控制组）。
重命名io以提高清晰度（如
```
+IN_A
```
→
```
IN_POS_A
```
）。
根据datasheet为每个
```
Power
```
io添加
```
voltage="..."
```
属性。
适当使用
```
@stdlib/interfaces.zen
```
中的
```
Analog
```
/
```
Digital
```
或类型化接口替换
```
Net
```
。
从
```
pins=
```
字典中移除
```
no_connect
```
引脚 — 不要将其暴露为io。
删除自动生成的文档字符串，替换为面向集成人员的简短描述（一段文字：元件用途、适用场景、关键约束）。

完整的样式规则请参考

idiomatic-zener

。如果希望将封装扩展为包含周边电路的可复用设计，请参考

reference-design

。

Step 4 — Workspace manifest

步骤4 — 工作区清单

The new component package needs a

pcb.toml

so the workspace can resolve it. Create:

toml

undefined

新元件包需要

pcb.toml

文件，以便工作区解析。创建：

toml

undefined

components/<Manufacturer>/<MPN>/pcb.toml

[package] name = "<MPN>" description = "<one-line description>"


If the workspace `pcb.toml` declares `members = [..., "components/*", ...]` (most do), the package is auto-discovered. Verify with:

```bash
pcb build components/<Manufacturer>/<MPN>

Fix any errors before instantiating from a board.

[package] name = "<MPN>" description = "<单行描述>"


如果工作区的`pcb.toml`声明了`members = [..., "components/*", ...]`（大多数情况如此），则该包会被自动发现。可通过以下命令验证：

```bash
pcb build components/<Manufacturer>/<MPN>

在从电路板实例化元件前，请修复所有错误。

Step 5 — Use it

步骤5 — 使用元件

python

MyPart = Module("./components/<Manufacturer>/<MPN>/<MPN>.zen")

MyPart(
    name="U1",
    VDD=vdd_3v3,
    GND=gnd,
    # ...
)

python

MyPart = Module("./components/<Manufacturer>/<MPN>/<MPN>.zen")

MyPart(
    name="U1",
    VDD=vdd_3v3,
    GND=gnd,
    # ...
)

Verifying Sourcing with

pcb bom

使用

pcb bom

验证采购信息

Once the part is wired into a board, sanity-check sourcing:

bash

pcb bom boards/<Board>/<Board>.zen -f json

For an easyeda2kicad-imported part, the BOM will pick up the MPN you set in the wrapper (

mpn=

config default). LCSC stock is the same source easyeda2kicad pulled from, so the

Cxxxxx

you used is your sourcing record — capture it in the docstring or a

.zen

comment for traceability.

将元件接入电路板后，请检查采购信息是否正确：

bash

pcb bom boards/<Board>/<Board>.zen -f json

对于通过easyeda2kicad导入的元件，BOM会获取你在封装文件中设置的MPN（

mpn=

配置默认值）。LCSC库存与easyeda2kicad获取的来源一致，因此你使用的

Cxxxxx

即为采购记录 — 请将其记录在文档字符串或

.zen

注释中以便追溯。

Generator Script

生成器脚本

Path:

<SKILL_DIR>/scripts/zener-wrap.py

Usage:

bash

python3 zener-wrap.py \
  --kicad-sym path/to/<MPN>.kicad_sym \
  --footprint <MPN>.kicad_mod \
  --mpn <MPN> \
  --manufacturer "<Manufacturer>" \
  --output path/to/<MPN>.zen \
  [--datasheet docs/<MPN>.pdf]   # optional

Pin classification rules:

```
GND
```
,
```
VSS
```
,
```
VEE
```
,
```
AGND
```
,
```
DGND
```
,
```
V-
```
→
```
Ground
```
```
VCC
```
,
```
VDD
```
,
```
VPP
```
,
```
VBUS
```
,
```
VS
```
,
```
V+
```
,
```
AVDD
```
,
```
DVDD
```
,
```
VIN
```
,
```
VOUT
```
→
```
Power
```
everything else →
```
Net
```

The script never throws on unusual pin names — it sanitizes any string into a valid Zener identifier and falls back to

PIN_<num>

for unnamed pins.

路径：

<SKILL_DIR>/scripts/zener-wrap.py

用法：

bash

python3 zener-wrap.py \
  --kicad-sym path/to/<MPN>.kicad_sym \
  --footprint <MPN>.kicad_mod \
  --mpn <MPN> \
  --manufacturer "<Manufacturer>" \
  --output path/to/<MPN>.zen \
  [--datasheet docs/<MPN>.pdf]   # 可选

引脚分类规则：

```
GND
```
、
```
VSS
```
、
```
VEE
```
、
```
AGND
```
、
```
DGND
```
、
```
V-
```
→
```
Ground
```
```
VCC
```
、
```
VDD
```
、
```
VPP
```
、
```
VBUS
```
、
```
VS
```
、
```
V+
```
、
```
AVDD
```
、
```
DVDD
```
、
```
VIN
```
、
```
VOUT
```
→
```
Power
```
其他所有引脚 →
```
Net
```

脚本不会因异常引脚名称报错 — 它会将任何字符串清理为有效的Zener标识符，并对未命名引脚使用

PIN_<num>

作为 fallback。

Common Issues

常见问题

easyeda2kicad: HTTP 404 on C-number — wrong C-number, or the part has been delisted. Re-search LCSC or pick the alternate-source listing.
Pin names look like
~{NAME}
(with overbar markup) — KiCad wraps inverted pin names in
```
~{...}
```
. The generator strips the markup for the io identifier but preserves the original string in the
```
pins=
```
dict so the symbol still matches.
Footprint references a 3D model that wasn't downloaded — happens with
```
--symbol --footprint
```
only. Either re-run with
```
--full
```
, or edit the
```
.kicad_mod
```
to remove the
```
(model ...)
```
block.
Symbol uses
~
/
#
/ spaces in pin names — the generator handles these. If the resulting Zener identifier is awkward, rename the io by hand and update the
```
pins=
```
mapping to keep the original KiCad name on the right.

easyeda2kicad：C编号返回HTTP 404 — C编号错误，或元件已下架。重新搜索LCSC或选择替代来源的条目。
引脚名称显示为
~{NAME}
（带有上划线标记） — KiCad会将反相引脚名称用
```
~{...}
```
包裹。生成器会为io标识符去除标记，但在
```
pins=
```
字典中保留原始字符串，以确保符号匹配。
封装引用未下载的3D模型 — 仅使用
```
--symbol --footprint
```
参数时会发生此问题。可重新运行命令并添加
```
--full
```
参数，或编辑
```
.kicad_mod
```
文件移除
```
(model ...)
```
块。
符号引脚名称包含
~
/
#
/ 空格 — 生成器会处理这些情况。如果生成的Zener标识符不够直观，请手动重命名io并更新
```
pins=
```
映射，确保右侧保留原始KiCad名称。

component-search

Original

Translation

Component Search (LCSC + easyeda2kicad)

元件搜索（LCSC + easyeda2kicad）

Hard Stop Before Manual Creation

手动创建前的强制检查

Search Priority

搜索优先级

Step 1 — MPN → LCSC C-number

步骤1 — MPN → LCSC C编号

Step 2 — Import via easyeda2kicad

步骤2 — 通过easyeda2kicad导入

Step 3 — Generate the Zener wrapper

步骤3 — 生成Zener封装文件

Step 4 — Workspace manifest

步骤4 — 工作区清单

components/<Manufacturer>/<MPN>/pcb.toml

components/<Manufacturer>/<MPN>/pcb.toml

Step 5 — Use it

步骤5 — 使用元件

Verifying Sourcing with
`pcb bom`

使用
`pcb bom`
验证采购信息

Generator Script

生成器脚本

Common Issues

常见问题

component-search

Original

Translation

Component Search (LCSC + easyeda2kicad)

元件搜索（LCSC + easyeda2kicad）

Hard Stop Before Manual Creation

手动创建前的强制检查

Search Priority

搜索优先级

Step 1 — MPN → LCSC C-number

步骤1 — MPN → LCSC C编号

Step 2 — Import via easyeda2kicad

步骤2 — 通过easyeda2kicad导入

Step 3 — Generate the Zener wrapper

步骤3 — 生成Zener封装文件

Step 4 — Workspace manifest

步骤4 — 工作区清单

components/<Manufacturer>/<MPN>/pcb.toml

components/<Manufacturer>/<MPN>/pcb.toml

Step 5 — Use it

步骤5 — 使用元件

Verifying Sourcing with pcb bom

使用pcb bom验证采购信息

Generator Script

生成器脚本

Common Issues

常见问题

Verifying Sourcing with
`pcb bom`

使用
`pcb bom`
验证采购信息