librarian

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Librarian

库管理员工作指南

Create sourceable, evidence-backed registry packages that board designers can search, trust, and instantiate.

Use this for new registry components, package fixes, family selectors, symbol/footprint cleanup, datasheet-backed reference circuitry, and requests produced by registry search during board work.

创建可采购、有依据的注册表包，供电路板设计师搜索、信任并实例化。

本指南适用于创建新注册表组件、修复包、系列选择器、符号/封装清理、基于Datasheet的参考电路，以及电路板设计过程中注册表搜索产生的需求。

Intake And Scope

需求接收与范围界定

Start by clarifying the deliverable:

primitive component package only
component package with built-in required support circuitry
separate
```
.zen
```
reference-design modules for one or more application circuits
connector/module wrapper around existing components
family selector covering multiple orderable MPNs

Search existing registry modules and components first:

bash

pcb search -m registry:modules <query> -f json
pcb search -m registry:components <query> -f json

Patch or extend an existing package when it is the right home. Create a new package only when no suitable package exists or the physical package/footprint, pinout, or fundamental schematic topology differs.

首先明确交付内容：

仅包含基础组件包
内置必要支持电路的组件包
用于一个或多个应用电路的独立
```
.zen
```
参考设计模块
基于现有组件的连接器/模块封装
涵盖多个可订购MPN的系列选择器

首先搜索现有注册表模块和组件：

bash

pcb search -m registry:modules <query> -f json
pcb search -m registry:components <query> -f json

若现有包是合适的载体，则对其进行补丁或扩展。仅当没有合适的包存在，或物理封装/引脚布局、引脚分配、基本原理图拓扑不同时，才创建新包。

Family-First, Symbol-First

优先考虑系列，优先考虑符号

When a request names one MPN, first look for the related part family before authoring. A good component package usually covers all parts with the same physical package/footprint, pinout, feature set, and fundamental schematic topology.

Curate symbols before writing reference-design

.zen

. The symbol library defines the functional variants and primitive interface that the

.zen

package will select and wire; an untrusted symbol makes the rest of the package untrustworthy.

A typical flow:

Understand the request and intended deliverable.
Find the related part group/family.
Fetch or import ECAD artifacts.
Clean the symbols against the datasheet.
Represent each functional variant symbol without duplicating order-code variants.
Clean the footprint and embedded STEP against the datasheet.
Write the reference circuitry or selector logic.

Treat this as the default direction, not a rigid script. Focused patches may only touch one stage, but do not write reusable circuitry on top of untrusted symbols.

Functional variants need symbols; order-code variants do not. For example, fixed-output LDO voltages get separate symbols because the selected silicon changes electrical behavior, but tape/reel, temperature grade, RoHS, and packing suffixes do not.

Use

kicad-symbol

for symbol-file structure, editing,

extends

, rendering, and signature rules. The librarian-level rule is to curate the family symbols before

.zen

work and to cover functional variants without duplicating order-code variants.

当请求指定单个MPN时，先查找相关部件系列再进行创作。一个优质的组件包通常涵盖所有具有相同物理封装/引脚布局、引脚分配、功能集和基本原理图拓扑的部件。

在编写参考设计

.zen

文件之前，先整理符号库。符号库定义了

.zen

包将选择和连接的功能变体及基础接口；不可信的符号会导致整个包失去可信度。

典型流程：

理解需求和预期交付内容。
找到相关部件组/系列。
获取或导入ECAD工件。
根据Datasheet清理符号。
为每个功能变体创建符号，避免重复订购代码变体。
根据Datasheet清理封装和嵌入的STEP模型。
编写参考电路或选择器逻辑。

将此视为默认流程，而非严格的脚本。针对性补丁可能仅涉及其中一个阶段，但不要在不可信符号之上编写可重用电路。

功能变体需要单独的符号；订购代码变体则不需要。例如，固定输出LDO的不同电压需要单独符号，因为所选芯片会改变电气特性，但卷带/盘装、温度等级、RoHS和包装后缀则不需要。

使用

kicad-symbol

处理符号文件结构、编辑、

extends

、渲染和签名规则。库管理员级别的规则是：在开展

.zen

工作前整理系列符号，覆盖功能变体且不重复订购代码变体。

Artifact Acquisition

工件获取

Use web component search only for registry authoring, not ordinary board consumption.

bash

pcb search -m web:components <MPN> -f json

web:components

results include

component_id

, source, model availability, datasheets, and availability. Prefer results with ECAD artifacts and STEP when they match the datasheet and the intended physical package.

Import web artifacts into a workspace with:

bash

pcb new component --component-id <ID> --part-number <MPN> --manufacturer <MFR>

Use

pcb new component <DIR>

when importing a downloaded local ECAD directory.

Fetched artifacts are starting points, not authority. Check every symbol, pin, footprint, datasheet link, sourcing field, and 3D model against the manufacturer datasheet. If a symbol, footprint, or pin map is unsafe, fix it before writing reusable circuitry.

If a footprint and STEP model were fetched separately, embed the STEP into the footprint:

bash

pcb embed-step <footprint.kicad_mod> <model.step>

pcb search

plus

pcb new component

often handles this, but separately fetched models should always be embedded in the

.kicad_mod

仅在注册表创作时使用Web组件搜索，普通电路板设计时请勿使用。

bash

pcb search -m web:components <MPN> -f json

web:components

的结果包含

component_id

、来源、模型可用性、Datasheet和供货情况。优先选择与Datasheet和预期物理包匹配且包含ECAD工件和STEP模型的结果。

使用以下命令将Web工件导入工作区：

bash

pcb new component --component-id <ID> --part-number <MPN> --manufacturer <MFR>

导入下载的本地ECAD目录时，使用

pcb new component <DIR>

。

获取的工件仅作为起点，而非权威依据。需对照厂商Datasheet检查每个符号、引脚、封装、Datasheet链接、采购字段和3D模型。若符号、封装或引脚映射不可靠，需在编写可重用电路前修复。

若封装和STEP模型是单独获取的，需将STEP模型嵌入封装：

bash

pcb embed-step <footprint.kicad_mod> <model.step>

pcb search

搭配

pcb new component

通常可处理此操作，但单独获取的模型应始终嵌入

.kicad_mod

文件中。

Package Shape

包结构

New reusable registry content belongs in a component package path:

text

components/<Manufacturer>/<NAME>/
├── <NAME>.zen
├── <NAME>.kicad_sym
├── <NAME or footprint>.kicad_mod
├── pcb.toml
├── docs/
│   └── <datasheet>.pdf
└── README.md

Include checked-in datasheet PDFs under

docs/

. Include a real

.kicad_mod

; note whether it is datasheet-exact, KiCad-stock-derived, vendor-derived, or intentionally adjusted.

The README is for realistic usage examples and concise integration notes only. Put rationale and design evidence in the

.zen

docstring.

Legacy

reference/

packages are examples, not placement for new reusable circuitry.

新的可重用注册表内容应放在以下组件包路径中：

text

components/<Manufacturer>/<NAME>/
├── <NAME>.zen
├── <NAME>.kicad_sym
├── <NAME or footprint>.kicad_mod
├── pcb.toml
├── docs/
│   └── <datasheet>.pdf
└── README.md

在

docs/

目录下存放已校验的Datasheet PDF文件。需包含真实的

.kicad_mod

文件，并注明其是否完全符合Datasheet、基于KiCad库存、供应商提供或经过有意调整。

README仅用于实际使用示例和简洁的集成说明。将设计依据和原理写入

.zen

的文档字符串中。

旧版

reference/

包仅作为示例，新的可重用电路不应放在此目录下。

Reference Circuit Quality

参考电路质量

A good reference design is one coherent schematic circuit around the curated symbols. It exposes application-level IO, keeps implementation-detail nodes internal unless access is necessary, and exposes only integrator-tunable choices.

Start from the primitive component: symbols, footprint, pins, and sourcing. Add surrounding schematic circuitry only when it is part of the reusable way to use the IC: required decoupling, compensation, feedback, bootstrap, bias, reset, straps, or a datasheet-recommended application circuit with clear defaults.

For decoupling, do not cargo-cult 100 nF or 100 nF + bulk pairs. Prefer one compact low-ESL MLCC, often 1 uF 0402, at each power pin when valid; check inrush and regulator stability.

Keep the package primitive if the surrounding circuit is board-specific, underspecified, already handled by another package, or blocked by untrusted symbol/footprint/pin data.

If one IC has fundamentally different schematic topologies for different modes, keep them in the same Zener package but use separate

.zen

reference-design modules.

The

.zen

docstring is the design document. It should explain:

circuit/application mode
exact IC/physical package or family and selector behavior
operating envelope, interfaces, configs, and assumptions
included support circuitry vs integrator-owned circuitry
evidence for important choices, footprint notes, and sourceability compromises

Capture the facts that drive the circuit:

typical application or recommended topology
rails, limits, sequencing, and required passives
straps, reset/enable, bias, compensation, timing, and mode selects
equations and datasheet-recommended example points
oscillator/crystal requirements and sensitive nets
physical-package caveats that affect the public API

Do not guess ambiguous passives, straps, sequencing, oscillators, or topology choices. Find evidence or ask.

优质的参考设计是围绕已整理符号构建的连贯原理图电路。它暴露应用级IO，将实现细节节点隐藏在内部（除非必须访问），仅提供集成者可调整的选项。

从基础组件开始：符号、封装、引脚和采购信息。仅当外围原理图电路是该IC的可重用使用方式的一部分时才添加：必要的去耦、补偿、反馈、自举、偏置、复位、配置引脚，或带有明确默认值的Datasheet推荐应用电路。

对于去耦电路，不要盲目使用100 nF或100 nF + 大容量电容组合。验证后，优先在每个电源引脚使用一个紧凑的低ESL MLCC（通常为1 uF 0402封装），并检查浪涌电流和稳压器稳定性。

若外围电路是电路板专用、规格不明确、已由其他包处理，或受不可信的符号/封装/引脚数据限制，则保持包的基础性。

若一个IC在不同模式下具有根本不同的原理图拓扑，可将它们放在同一个Zener包中，但使用单独的

.zen

参考设计模块。

.zen

的文档字符串是设计文档，应说明：

电路/应用模式
具体IC/物理包或系列及选择器行为
工作范围、接口、配置和假设
包含的支持电路与集成者负责的电路
重要选择的依据、封装说明和采购妥协

记录驱动电路设计的事实：

典型应用或推荐拓扑
电源轨、限制、时序和所需无源器件
配置引脚、复位/使能、偏置、补偿、时序和模式选择
公式和Datasheet推荐的示例参数
振荡器/晶体要求和敏感网络
影响公共API的物理包注意事项

不要猜测模糊的无源器件、配置引脚、时序、振荡器或拓扑选择。查找依据或询问相关人员。

Family Scope And Naming

系列范围与命名

One component Zener package may cover a part family when the parts share the same physical package/footprint, pinout, feature set, and fundamental schematic topology. Values or selected silicon may vary by config. Fixed-output LDO trims in the same physical package/pinout are a good grouping.

Use separate Zener packages when physical package/footprint, pinout, or fundamental schematic topology differs. Electrical grouping requires judgment: if the same schematic shape still applies, grouping is usually fine; if you are masking most of the MPN or combining unrelated feature sets, split the package.

Name the Zener package from the functional MPN pattern, not the full orderable SKU:

derive the name from the MPNs being covered
drop ordering-only suffixes such as temperature, tape/reel, and RoHS markings
use lowercase
```
x
```
to mask patterned MPN differences inside a family
if the name needs too many
```
x
```
s, the family is probably too broad

Examples:

DP83867ISRGZR

DP83867

;

TPS3430WDRCR

TPS3430WDRC

;

SN74LXC1T45DRYR

SN74AXC1T45QDRYRQ1

SN74x1T45-DRY

For selectable families, use a compact table/list of variants with MPN, symbol, limits, and properties. Filter by

config()

values, use the first match as

part=

, and put remaining drop-in matches in

properties={"alternatives": ...}

当部件具有相同的物理封装/引脚布局、引脚分配、功能集和基本原理图拓扑时，单个组件Zener包可覆盖整个部件系列。参数值或所选芯片可能因配置而异。同一物理封装/引脚分配的固定输出LDO调整版本是很好的分组案例。

当物理封装/引脚布局、引脚分配或基本原理图拓扑不同时，使用单独的Zener包。电气分组需要判断：若相同的原理图结构仍适用，通常可以分组；若需要掩盖大部分MPN或合并不相关的功能集，则应拆分包。

Zener包的名称应基于功能性MPN模式，而非完整的可订购SKU：

从所覆盖的MPN中衍生名称
删除仅与订购相关的后缀，如温度等级、卷带/盘装和RoHS标记
使用小写
```
x
```
掩盖系列内MPN的模式化差异
若名称需要过多的
```
x
```
，则该系列可能过于宽泛

示例：

DP83867ISRGZR

DP83867

；

TPS3430WDRCR

TPS3430WDRC

；

SN74LXC1T45DRYR

SN74AXC1T45QDRYRQ1

SN74x1T45-DRY

。

对于可选择的系列，使用紧凑的变体表格/列表，包含MPN、符号、限制和属性。通过

config()

值进行筛选，将第一个匹配项设为

part=

，其余可直接替换的匹配项放入

properties={"alternatives": ...}

中。

Sourceability And Style

可采购性与风格

Prefer strong registry exemplars:

TPS709-Q1

TPSM336xx-Q1

TCPP01-M12

SN74x1T45-DRY

SSM3KxxxCT

W25QxxUX

Wago/2060-4xx_998-404

FTSH-105-01-L-DV-K-A-P-TR

Prefer house-matchable generic choices when technically valid. If rounding, clamping, or substituting values, document why. If a generic cannot reasonably match, ask whether to use an explicit part or suppress the warning with justification. Inspect

.pcb/stdlib/bom/match_generics.zen

when generic matching matters.

Use comments for evidence and judgment only: datasheet section/table/equation references, rounded or clamped values, or stuffing strategy. Avoid comments that restate code. Do not add decorative banner/divider comments such as

====

----

优先选择优秀的注册表范例：

TPS709-Q1

、

TPSM336xx-Q1

、

TCPP01-M12

、

SN74x1T45-DRY

、

SSM3KxxxCT

、

W25QxxUX

、

Wago/2060-4xx_998-404

、

FTSH-105-01-L-DV-K-A-P-TR

。

在技术可行的情况下，优先选择可内部匹配的通用器件。若需要取整、钳位或替换参数，需记录原因。若通用器件无法合理匹配，询问是否使用明确部件或提供依据以抑制警告。当通用器件匹配很重要时，查看

.pcb/stdlib/bom/match_generics.zen

。

仅为依据和判断添加注释：Datasheet章节/表格/公式引用、取整或钳位的参数，或器件安装策略。避免重复代码内容的注释。不要添加装饰性横幅/分隔线注释，如

====

或

----

。

Verification

验证

Build after each major block:

bash

pcb build -Wstyle components/<Manufacturer>/<NAME>

Use BOM output when build warnings are not enough to understand sourcing:

bash

pcb bom components/<Manufacturer>/<NAME>/<NAME>.zen -f json

Format before finishing:

bash

pcb fmt components/<Manufacturer>/<NAME>

Before stopping, make sure existing registry packages were checked, important choices are evidence-backed, artifacts match the datasheet, sourceability compromises are documented, and

pcb build -Wstyle

warnings were reviewed.

完成每个主要模块后进行构建：

bash

pcb build -Wstyle components/<Manufacturer>/<NAME>

当构建警告不足以理解采购情况时，使用BOM输出：

bash

pcb bom components/<Manufacturer>/<NAME>/<NAME>.zen -f json

完成前进行格式化：

bash

pcb fmt components/<Manufacturer>/<NAME>

结束工作前，确保已检查现有注册表包、重要选择均有依据、工件与Datasheet匹配、采购妥协已记录，且已审核

pcb build -Wstyle

的警告。