agentee

元件

元件库

agentee 库：用户自己的元件，包含其符号、封装、模型、数据手册和库存，可在每个设计中发现、添加和使用。

元件库是用户自己的一套元件：连接器、稳压器、无源器件以及其他希望每个设计都复用的东西，这样线缆和库存就能在项目之间延续。每个元件保存其符号、封装、3D 模型、数据手册和上次检查的库存，智能体在寻找新元件之前会先从库中挑选（MCP library_find、library_list、library_show、library_use、library_add）。设计所需的每个元件的工作流程是查找、添加、使用：find 显示库中匹配的元件，若无匹配项，则显示分销商当前有库存的元件；选定的元件通过 add 加入库，通过 use 放到电路板上。

它位于 ~/.config/agentee/library/（$AGENTEE_LIBRARY 可移动位置），项目可以在其根目录的 .agentee/library/ 中添加或覆盖元件。每个元件是一个目录：

JST-PH-2/
  part.toml
  JST-PH-2.sym.toml            # the symbol, renamed to the part
  JST_PH_S2B-PH-K_1x02_P2.00mm_Horizontal.fp.toml
  3dmodels/JST_PH_S2B-PH-K_1x02_P2.00mm_Horizontal.step
role = "connector"
mpn = "S2B-PH-K-S"
manufacturer = "JST"
lcsc = "C131337"               # the JLCPCB/LCSC part number, looked up by `add` and `refresh`
value = "PH 2-pin"
rating = "2 A, 100 V"
preferred = true               # the first choice for its role
# generic = true               # any value on this footprint is this part (a resistor series)
# pins = 2                     # default the symbol's pin count
tags = ["power", "battery"]
notes = "power input, 2 A max, use XH for motors"
symbol = "JST-PH-2.sym.toml"
footprint = "JST_PH_S2B-PH-K_1x02_P2.00mm_Horizontal.fp.toml"
model = "3dmodels/JST_PH_S2B-PH-K_1x02_P2.00mm_Horizontal.step"
added = "2026-10-09"

[datasheet]                    # pinned in the datasheet cache
url = "http://www.farnell.com/datasheets/4648554.pdf"
sha256 = "dd60971f..."

[[files]]                      # where each file came from and its hash when added
path = "JST-PH-2.sym.toml"
source = "kicad Connector_Generic:Conn_01x02, KiCad 9.0"
sha256 = "42b88f96..."

[[stock]]                      # one per distributor listing, from add or refresh
distributor = "Farnell"
sku = "9491902"
stock = 338281
currency = "EUR"
breaks = [[100.0, 0.0841], [1000.0, 0.0655]]
min = 100
url = "https://ie.farnell.com/search?st=9491902"
checked = "2026-10-09"
agentee library add S2B-PH-K-S --name JST-PH-2 --role connector \
    --symbol Connector_Generic:Conn_01x02 \
    --footprint Connector_JST:JST_PH_S2B-PH-K_1x02_P2.00mm_Horizontal \
    --manufacturer JST --rating "2 A, 100 V" --notes "power input" --preferred
agentee library find 3.3V buck --role regulator   # library matches, else stocked parts to add
agentee library find USB-C receptacle --need 100 --search
agentee library list                           # every part, by role, with stock and price
agentee library list --role connector 2-pin power
agentee library show JST-PH-2
agentee library use JST-PH-2 -p board/         # copy its files in, print the edit that places it
agentee library refresh                        # stock and price of every part, one lookup each
agentee library verify

find WORDS 列出库中名称、角色、标签、料号、值、额定值、封装或备注匹配所有单词的元件。仅当无匹配项时（或使用 --search），它才使用这些单词作为关键词在每个有密钥的分销商处进行搜索，并列出处于激活状态（无停产、生命周期结束或停售状态）且库存至少为 --need（默认 1）的元件，按料号合并：总库存、有货的分销商、该数量下的最佳单价，以及数据手册链接。在多个分销商有货的元件排在前面，然后按库存排序；--limit 限制列表长度（默认 15）。已存在于库中的列出的元件会注明。

add 从 .sym.toml 或 .fp.toml 文件、项目中的符号或封装（-p），或 KiCad Library:Name 中获取符号和封装；封装默认使用符号对应的封装。它会复制封装的 3D 模型（来自 KiCad 模型目录、模型缓存或下载），将封装指向该副本，并在封装没有 height 时从模型设置其值，以便元件在离线状态下可用，且在 KiCad 安装或供应商下载变更时保持可用。当 KiCad 没有该名称的模型时，它会选取同一 .3dshapes 文件夹中最近的主体，或同一封装中焊盘最接近的裸露焊盘（或 _ThermalVias 封装的普通主体），并予以说明；3D 视图和 models 也执行相同操作。--model 还接受供应商下载，即包含 .kicad_mod 及其 STEP 或 VRML 模型的 ZIP 或文件夹（SamacSys、SnapMagic 和 Ultra Librarian 提供这些）：它按编号将供应商封装的焊盘与我们的焊盘匹配，当两者间距超过 0.1 mm 时拒绝，并写入 model_offset 和 model_rotate，将供应商模型放置在我们的封装上。若 KiCad 或 --model 均无模型，add 会在 JLCPCB/LCSC 元件列表中查找元件编号，并采用 EasyEDA 模型，该模型通过 EasyEDA 封装的焊盘以相同方式放置，并在检查模型与该封装轮廓后确定位置；元件的 files 将其记录为 EasyEDA C258169 (easyeda.com)。add 和 refresh 将 LCSC 编号存储为 lcsc，use 将其作为元件的 lcsc 字段传递，bom-jlcpcb.csv 会读取该字段。--no-distributors 跳过这两项查找。它获取数据手册（--datasheet URL 或 PDF，否则为符号的 URL，否则为分销商的 URL），将其固定在数据手册缓存中，以便 datasheet purge 永不删除它，并记录每个列表的库存和价格阶梯。其备注说明当没有分销商有该元件的活跃库存时的情况。--local 添加到项目库中，而不是全局库。

use 将符号复制到项目的 symbols/，封装复制到 footprints/，模型复制到 3dmodels/；已存在且不同的文件在没有 --force 的情况下被拒绝。它返回 agentee edit sch 命令，该命令添加带有其 mpn、mfr 和 library 字段的元件。datasheet text JST-PH-2 读取固定的副本，无需网络调用。

refresh 向每个有密钥的分销商一次性请求库中所有料号，并替换每个元件的 [[stock]]；失败的分销商保留其上次列表。list 打印有库存的最便宜列表及其检查日期，因此无需 API 调用即可知道截至该日期的库存和价格。

verify 检查每个元件：每个符号引脚都有焊盘，固定的数据手册命名了料号和封装（或引脚数），符号的引脚名称出现在其中，模型的轮廓适合占位区，封装的孔、槽和环满足 JLCPCB 的最小值，且每个文件仍具有添加时的哈希值。若有一个失败，它退出代码 1。

check 在设计使用库外元件执行库中持有的角色时发出警告（规则 library），并指明要使用的库元件：引脚数相同的那个，首选的排在前面。元件的角色是其 role 字段，或由其参考推导：J/P 连接器（同轴、SMA 和 U.FL 为 rf connector，usb connector，modular connector，card socket），R 电阻，C 电容，L 电感，FB 铁氧体，D 二极管或 led，Q 晶体管，Y 晶振，F 保险丝，SW 开关，BT 电池，K 继电器。当元件的 mpn 或 library 字段命名了库元件，或它位于 generic 元件的封装上时，该元件在库中。设置元件的 library = "no" 字段以排除一个。library.toml 在库根目录设置其推动力度：

check = "warning"              # warning | info | off
# roles = ["connector"]        # only these roles

docs/format.md · 面向智能体的 Markdown