reference-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Package Design

组件包设计

Grow component packages beyond a generated wrapper when the part benefits from reusable surrounding circuitry. A good component package captures the support circuitry, default mode, key equations, layout-sensitive notes, and evidence needed to use the part confidently.

当元器件可从可重用的周边电路中获益时，将组件包扩展为超出自动生成的封装。优质的组件包应包含支撑电路、默认模式、关键公式、布局敏感注意事项，以及让用户能放心使用该元器件所需的设计依据。

Hard Rules

硬性规则

Reuse before create. Search the workspace
```
components/
```
tree first; only import a new part with
```
component-search
```
(LCSC + easyeda2kicad) when nothing local fits.
New work lives in
```
components/<NAME>/
```
, alongside the imported
```
.kicad_sym
```
and
```
.kicad_mod
```
.
The
```
.kicad_sym
```
file is the source of truth for the primitive component interface and pin structure. Keep the
```
.zen
```
API aligned to it.
The
```
.zen
```
docstring is the canonical design document. The README is for usage examples only.
Review
```
pcb build
```
warnings, especially BOM/sourceability warnings such as
```
bom.match_generic
```
.
Don't guess ambiguous passives, straps, sequencing, or oscillator details. Get evidence or stop and ask.
Imitate only strong exemplars. Weak/generated packages are useful for pin lookup and starting structure, not authoring style.
Preserve
```
# pcb:sch ...
```
comments (tool-managed schematic layout metadata). When renaming a referenced component, module instance, or net, update the matching
```
# pcb:sch
```
names.

优先重用，再考虑创建。先搜索工作区的
```
components/
```
目录树；只有当本地没有合适的组件时，才通过
```
component-search
```
（LCSC + easyeda2kicad）导入新元器件。
新工作内容需放在
```
components/<NAME>/
```
目录下，与导入的
```
.kicad_sym
```
和
```
.kicad_mod
```
文件同级。
```
.kicad_sym
```
文件是原始组件接口和引脚结构的权威来源。保持
```
.zen
```
API与其对齐。
```
.zen
```
文档字符串是标准设计文档。README仅用于展示使用示例。
查看
```
pcb build
```
的警告信息，尤其是BOM/可采购性相关警告，如
```
bom.match_generic
```
。
不要对模糊的无源器件、跳线、时序或振荡器细节进行猜测。获取依据或暂停并咨询。
仅模仿优质范例。劣质/自动生成的包仅适用于引脚查询和初始结构搭建，不适用于作为编写风格参考。
保留
```
# pcb:sch ...
```
注释（工具管理的原理图布局元数据）。重命名引用的组件、模块实例或网络时，同步更新对应的
```
# pcb:sch
```
名称。

Reuse Before Create

优先重用再创建

Search the workspace
```
components/
```
tree (and any path-imported sibling repos) for the part — see
```
component-search
```
.
If the IC is missing, import it via the LCSC +
```
easyeda2kicad
```
flow in
```
component-search
```
. That gives you a starter wrapper to grow.
If a close-match package already exists, prefer extending it in place.
Grow a package beyond its generated signature only when it adds real reusable design judgment.

Do not grow the package yet if:

the datasheet does not clearly specify the required support circuitry
the topology still depends on unresolved system-level choices
the result would mostly duplicate an existing package with only minor edits
the IC symbol/component quality is too poor to wire confidently

在工作区的
```
components/
```
目录树（以及任何路径导入的同级仓库）中搜索目标元器件——参考
```
component-search
```
的使用方法。
如果IC缺失，通过
```
component-search
```
中的LCSC +
```
easyeda2kicad
```
流程导入。这会为你提供一个可扩展的初始封装。
如果存在近似匹配的包，优先在原基础上扩展。
仅当能添加真正可重用的设计判断时，才对包进行超出其自动生成签名的扩展。

在以下情况时，暂不扩展包：

数据手册未明确指定所需支撑电路
拓扑结构仍依赖未解决的系统级选择
结果将大部分复制现有包，仅做微小修改
IC符号/组件质量太差，无法可靠布线

Strong Vs Weak Exemplars

优质与劣质范例

Strong exemplars usually have most of these traits:

minimal, integrator-facing IO instead of exposing every raw IC pin
typed configs for real design choices
passive values traceable to datasheet tables, equations, or app-note guidance
optional features modeled cleanly, with evidence notes for non-obvious choices
sourceable generic choices or documented house-part compromises
useful usage examples, and layout/testbench artifacts when complexity warrants them

Weak/generated exemplars usually show warning signs such as:

mostly raw IC pins exposed directly
little or no design rationale, or magic values with no evidence
no attempt to capture the intended application circuit
no sourceability thinking
README content that is generic, marketing-like, or duplicated from the code

Use weak examples for package API lookup only.

优质范例通常具备以下多数特征：

面向集成商的极简IO，而非暴露所有原始IC引脚
针对实际设计选项的类型化配置
可追溯至数据手册表格、公式或应用笔记指导的无源器件值
对可选功能进行清晰建模，为非显而易见的选择添加依据说明
可采购的通用选型或有文档记录的厂用器件折中方案
实用的使用示例，当复杂度较高时提供布局/测试台工件

劣质/自动生成的范例通常存在以下警示信号：

直接暴露大部分原始IC引脚
几乎没有设计依据，或存在无来源的魔法值
未尝试捕捉预期的应用电路
未考虑可采购性
README内容通用、营销化或与代码重复

仅将劣质示例用于包API查询。

Quality Bar

质量标准

A high-quality component package is electrically faithful, narrowly scoped, reasonably sourceable, and evidence-backed. Treat the

.zen

file as the design artifact, not just executable code.

高质量的组件包应在电气上准确、范围明确、具备合理可采购性且有依据支撑。将

.zen

文件视为设计工件，而非仅作为可执行代码。

Evidence Extraction

依据提取

Extract at least:

the exact typical application circuit or recommended topology
supply rails, limits, sequencing, and required external passives
strap, mode-select, reset, enable, bias, compensation, and timing networks
equations for programmable values and any datasheet-recommended example points
oscillator or crystal requirements, sensitive analog/high-speed connections, and thermal/layout guidance
any package-specific caveats that change how the design should be exposed

When the datasheet is ambiguous, look for app notes, eval schematics, or nearby validated workspace designs before guessing.

至少提取以下内容：

确切的典型应用电路或推荐拓扑
电源轨、限制条件、时序要求及所需外部无源器件
跳线、模式选择、复位、使能、偏置、补偿和时序网络
可编程值的公式以及数据手册推荐的示例点
振荡器或晶体要求、敏感模拟/高速连接以及热/布局指导
任何会影响设计暴露方式的包特定注意事项

当数据手册内容模糊时，先查找应用笔记、评估原理图或已验证的工作区设计，再进行猜测。

Define The Public API First

先定义公共API

Package API rules:

Expose the application-level interface, not the raw pinout.
Keep layout-sensitive or implementation-detail nodes internal unless external access is genuinely required.
Expose configs only for choices an integrator should reasonably tune; do not expose every passive.
Prefer one narrow, coherent operating mode over a sprawling universal module.
If two operating modes materially change topology, consider separate designs instead of config explosion.

包API规则：

暴露应用级接口，而非原始引脚排列
除非确实需要外部访问，否则将布局敏感或实现细节节点设为内部节点
仅暴露集成商合理需要调整的配置选项；不要暴露所有无源器件
优先选择单一、连贯的工作模式，而非庞大的通用模块
如果两种工作模式会实质性改变拓扑结构，考虑设计独立版本，而非通过配置膨胀实现

Scaffold And Implement

搭建与实现

Directory layout and naming

目录结构与命名

Name the component package from the functional MPN, not the full orderable SKU.

Use these rules:

Start from the manufacturer part number.
Keep functional variation in the name: electrical options and package/pinout differences stay.
Replace non-functional variation with lowercase
```
x
```
: temperature grade, reel/tray packaging, RoHS/Pb-free, and other ordering-only suffixes.
If the only wildcarded characters would be trailing non-functional suffixes, omit the trailing
```
x
```
.
If there is only one functional variant, do not add an unnecessary
```
x
```
.
If the part exists in multiple footprint or pinout options, make a separate component package for each one.
If multiple manufacturers make footprint-compatible parts with different package suffixes, use the common base name plus a clear package suffix.

Examples:

```
DP83867ISRGZR
```
->
```
DP83867
```
```
TPS3430WDRCR
```
->
```
TPS3430WDRC
```
compatible cross-vendor variants with different package suffixes ->
```
L78L05_TO92
```

Use

<NAME>

for the resolved package name from the rules above, for example:

text

components/<NAME>/
├── <NAME>.zen
├── <NAME>.kicad_sym
├── pcb.toml
└── README.md

Scaffold with

pcb new package components/<NAME>

when creating a fresh package. If the component already exists, evolve the existing

components/...

package instead of creating a sibling package.

根据功能性MPN（制造商零件编号）命名组件包，而非完整的可订购SKU。

遵循以下规则：

以制造商零件编号为基础
在名称中保留功能性差异：电气选项和封装/引脚差异需保留
用小写
```
x
```
替换非功能性差异：温度等级、卷盘/托盘包装、RoHS/无铅及其他仅用于订购的后缀
如果通配符仅用于尾部非功能性后缀，省略尾部的
```
x
```
如果仅有一种功能变体，不要添加不必要的
```
x
```
如果元器件有多种封装或引脚选项，为每种选项创建独立的组件包
如果多个制造商生产封装兼容但后缀不同的元器件，使用通用基础名称加明确的封装后缀

示例：

```
DP83867ISRGZR
```
->
```
DP83867
```
```
TPS3430WDRCR
```
->
```
TPS3430WDRC
```
跨厂商兼容的不同封装后缀变体 ->
```
L78L05_TO92
```

使用上述规则确定的

<NAME>

作为最终包名称，例如：

text

components/<NAME>/
├── <NAME>.zen
├── <NAME>.kicad_sym
├── pcb.toml
└── README.md

创建新包时，使用

pcb new package components/<NAME>

搭建初始结构。如果组件已存在，升级现有

components/...

包，而非创建同级包。

File structure

文件结构

Organize the

.zen

file in this order:

Top-of-file docstring
```
load()
```
s and helper definitions
```
io()
```
and
```
config()
```
definitions
internal nets and imports
main IC instantiation and supporting circuitry grouped by function
layout / tool-managed metadata

Group support circuitry by electrical function: power, decoupling, feedback, straps, clocks, reset, interface conditioning, protection.

Keep the

# pcb:sch ...

block intact and in sync with renames. Treat the symbol file as canonical for pins and primitive interface naming.

按以下顺序组织

.zen

文件：

文件顶部的文档字符串
```
load()
```
语句和辅助定义
```
io()
```
和
```
config()
```
定义
内部网络和导入内容
主IC实例化及按功能分组的支撑电路
布局/工具管理的元数据

按电气功能对支撑电路分组：电源、去耦、反馈、跳线、时钟、复位、接口调理、保护。

保持

# pcb:sch ...

块完整，并与重命名操作同步。将符号文件视为引脚和原始接口命名的权威来源。

Docstring policy

文档字符串规范

Include:

what circuit/application mode this module implements
the exact IC/package or family it targets
the intended operating envelope, interfaces, configs, and assumptions
evidence notes for important choices and non-obvious layout guidance
sourceability compromises such as house-part rounding when relevant

Keep this in the

.zen

file so the code and rationale stay together.

需包含：

本模块实现的电路/应用模式
针对的确切IC/封装或系列
预期工作范围、接口、配置和假设
重要选择的依据说明及非显而易见的布局指导
相关的可采购性折中方案，如厂用器件取整

将这些内容放在

.zen

文件中，确保代码与依据保持同步。

Comment policy

注释规范

Good comment targets:

datasheet section/table/equation references
justification for rounded/clamped values
optional-feature stuffing strategy or layout-sensitive placement guidance

Avoid comments that merely restate the code.

适合添加注释的场景：

数据手册章节/表格/公式引用
取整/钳位值的理由
可选功能的填充策略或布局敏感的放置指导

避免仅重复代码内容的注释。

Sourceability And BOM Quality

可采购性与BOM质量

Read

.pcb/stdlib/bom/match_generics.zen

(resolved from the active workspace) when sourceability choices matter. The stdlib matcher only covers a constrained house catalog, so generic values, packages, dielectric choices, and voltage ratings affect whether parts match.

Use these rules:

Treat
```
pcb build
```
warnings as review items, especially
```
bom.match_generic
```
.
Prefer generic values/package/voltage combinations that match house parts when that does not compromise the design.
If the datasheet value does not match house parts, a nearby house value is acceptable only when the change is technically defensible.
Whenever you round, clamp, or substitute to land on a house-matchable value, document the reason in the docstring or a nearby comment.
If a generic cannot reasonably match, do not silently force a workaround. Ask the user whether they want to specify an explicit part or suppress the warning with justification.

Typical fixes are choosing the nearest valid house value above a datasheet minimum, clamping computed values to supported parts, or adjusting package/voltage choices without violating the design. Use

pcb bom <path> -f json

when you need sourcing detail beyond the matcher.

当可采购性选择至关重要时，阅读

.pcb/stdlib/bom/match_generics.zen

（从当前工作区解析）。标准库匹配器仅覆盖有限的厂用目录，因此通用值、封装、介质选择和电压等级会影响器件是否匹配。

遵循以下规则：

将
```
pcb build
```
警告视为需审核的项，尤其是
```
bom.match_generic
```
。
在不影响设计的前提下，优先选择与厂用器件匹配的通用值/封装/电压组合。
如果数据手册值与厂用器件不匹配，只有当修改在技术上合理时，才接受相近的厂用值。
每当通过取整、钳位或替换得到可匹配厂用器件的值时，在文档字符串或附近注释中记录原因。
如果通用器件无法合理匹配，不要静默采用变通方案。询问用户是要指定明确器件还是提供依据以抑制警告。

常见修复方式包括选择高于数据手册最小值的最近有效厂用值、将计算值钳位到支持的器件范围，或在不违反设计要求的前提下调整封装/电压选择。当需要匹配器之外的采购细节时，使用

pcb bom <path> -f json

命令。

Build Iteratively

迭代构建

Build after every major block, not just at the end.

bash

pcb build components/<NAME>

Typical problems:

wrong interface field names or package wiring
missing
```
load()
```
s, bad stdlib assumptions, or ambiguous optional-feature modeling
unmatched generics or values that are plausible electrically but not sourceable

Format when done:

bash

pcb fmt components/<NAME>

完成每个主要模块后立即构建，而非仅在最后构建。

bash

pcb build components/<NAME>

常见问题：

接口字段名称错误或包布线错误
缺失
```
load()
```
语句、错误的标准库假设或模糊的可选功能建模
不匹配的通用器件或电气上合理但不可采购的值

完成后格式化：

bash

pcb fmt components/<NAME>

README Policy

README规范

Use it for:

realistic instantiation examples
different application contexts when they materially change integration
concise consume-the-module notes only

Do not put general feature lists, design notes, or long rationale sections in the README. That belongs in the

.zen

docstring.

Minimal README shape:

markdown

undefined

README用于：

真实的实例化示例
当集成方式发生实质性变化时的不同应用场景
仅包含简洁的模块使用说明

不要在README中放置通用功能列表、设计说明或长篇依据内容。这些内容应放在

.zen

文档字符串中。

极简README模板：

markdown

undefined

<NAME>

Usage

使用方法

python

MyRef = Module("./components/<Manufacturer>/<NAME>/<NAME>.zen")

MyRef(
    name="U1",
    VIN=vin,
    VOUT=vout,
    GND=gnd,
)

python

MyRef = Module("./components/<Manufacturer>/<NAME>/<NAME>.zen")

MyRef(
    name="U1",
    VIN=vin,
    VOUT=vout,
    GND=gnd,
)

Other Usage Examples

其他使用示例

Add additional examples only when they show materially different integration patterns.

undefined

仅当展示实质性不同的集成模式时，才添加额外示例。

undefined

Stop Conditions

暂停条件

Stop and ask or gather more evidence when:

the datasheet is unclear about a required passive, strap, or topology choice
the design depends on unresolved system-level requirements
the imported component/symbol quality is too poor to wire safely
```
pcb build
```
warnings suggest unresolved correctness or sourceability issues
the design is drifting into a generic breakout instead of a reference module

在以下情况时暂停并咨询或收集更多依据：

数据手册对所需无源器件、跳线或拓扑选择不明确
设计依赖未解决的系统级需求
导入的组件/符号质量太差，无法安全布线
```
pcb build
```
警告提示存在未解决的正确性或可采购性问题
设计偏离参考模块方向，转向通用 breakout 板

Final Checklist

最终检查清单

Existing workspace packages were checked first. New parts came in through the
```
component-search
```
LCSC + easyeda2kicad flow.
The package implements one coherent reusable design around the part.
The symbol file remains the source of truth for the primitive component interface.
The docstring explains the design, evidence, and any sourceability compromises.
```
pcb build
```
was run and warnings were reviewed.
```
pcb fmt
```
was run, and the README contains usage examples only.

已检查现有工作区包。新元器件通过
```
component-search
```
的LCSC + easyeda2kicad流程导入。
包围绕元器件实现了一个连贯的可重用设计。
符号文件仍是原始组件接口的权威来源。
文档字符串说明了设计、依据及任何可采购性折中方案。
已运行
```
pcb build
```
并审核了警告。
已运行
```
pcb fmt
```
，且README仅包含使用示例。