Библиотека компонентов

Библиотека компонентов, это собственный набор элементов пользователя: разъёмы, регуляторы, пассивные компоненты и всё, что он хочет переиспользовать в каждом проекте, чтобы кабели и запасы переносились между проектами. Каждый компонент хранит своё УГО, посадочное место, 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 также принимает загрузку от поставщика, ZIP или папку, содержащую .kicad_mod и его модель STEP или VRML (SamacSys, SnapMagic и Ultra Librarian предоставляют это): он сопоставляет контактные площадки посадочного места поставщика с нашими по номеру, отказывается, если они смещены более чем на 0,1 мм, и записывает 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 пропускает оба поиска. Он загружает даташит (URL или PDF --datasheet, иначе 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 проверяет каждый компонент: у каждого вывода УГО есть контактная площадка, закреплённый даташит содержит номер детали и корпус (или количество выводов), имена выводов УГО присутствуют в нём, контур модели помещается в courtyard, отверстия, пазы и кольца посадочного места соответствуют минимальным требованиям JLCPCB, и каждый файл по-прежнему имеет тот же хеш, с которым он был добавлен. Выходит с кодом 1, если что-то не проходит.

check предупреждает (правило library), когда схема использует компонент вне библиотеки для роли, которая есть в библиотеке, указывая компонент из библиотеки, который нужно использовать: тот, у которого такое же количество выводов, предпочтительный идёт первым. Роль компонента определяется его полем role или следует из его обозначения: J/P разъём (rf connector для коаксиальных, SMA и U.FL, 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