Libreria di componenti

La libreria dei componenti è l'insieme di componenti dell'utente: i connettori, i regolatori, i passivi e qualsiasi altra cosa che si vuole riutilizzare in ogni progetto, in modo che i cavi e lo stock passino da un progetto all'altro. Ogni componente contiene il suo simbolo, footprint, modello 3D, datasheet e ultimo stock verificato, e un agente lo sceglie da lì prima di cercare altrove (MCP library_find, library_list, library_show, library_use, library_add). Il flusso di lavoro per ogni componente di cui un progetto ha bisogno è trova, aggiungi, usa: find mostra i componenti della libreria che corrispondono e, se nessuno corrisponde, i componenti attualmente in stock presso i distributori; quello scelto viene aggiunto alla libreria con add e sulla scheda con use.

Si trova in ~/.config/agentee/library/ ($AGENTEE_LIBRARY lo sposta) e un progetto può aggiungere o sovrascrivere componenti in .agentee/library/ alla sua radice. Ogni componente è una directory:

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 elenca i componenti della libreria il cui nome, ruolo, tag, part number, valore, rating, footprint o note corrispondono a ogni parola. Solo quando nessuno corrisponde (o con --search) esegue le stesse parole come ricerca per parola chiave presso ogni distributore con una chiave ed elenca i componenti attivi (senza stato di obsoleto, fine vita o dismesso) con almeno --need in stock (default 1), uniti per part number: stock totale, i distributori che lo hanno, il miglior prezzo unitario a quella quantità e il link al datasheet. I componenti in stock presso più distributori vengono prima, poi per stock; --limit limita l'elenco (default 15). Un componente elencato già presente nella libreria lo indica.

add prende il simbolo e il footprint da un file .sym.toml o .fp.toml, da un simbolo o footprint del progetto (-p), o da una Library:Name di KiCad; il footprint predefinito è quello del simbolo. Copia il modello 3D del footprint (dalle directory dei modelli di KiCad, dalla cache dei modelli o da un download), punta il footprint alla copia e imposta il suo height dal modello quando non ce l'ha, in modo che un componente funzioni offline e continui a funzionare quando un'installazione di KiCad o un download del vendor cambia. Quando KiCad non ha un modello di quel nome, prende il corpo più vicino nella stessa cartella .3dshapes, lo stesso package con la piazzola esposta più vicina (o il corpo semplice di un footprint _ThermalVias) e lo indica; la vista 3D e models fanno lo stesso. --model accetta anche un download del vendor, un ZIP o una cartella contenente un .kicad_mod e il suo modello STEP o VRML (SamacSys, SnapMagic e Ultra Librarian li forniscono): corrisponde le piazzole del footprint del vendor alle nostre per numero, rifiuta quando sono distanti più di 0,1 mm e scrive model_offset e model_rotate che posizionano il modello del vendor sul nostro footprint. Senza modello da KiCad o --model, add cerca il part number nell'elenco dei componenti JLCPCB/LCSC e prende il modello EasyEDA, posizionato allo stesso modo dalle piazzole del footprint EasyEDA dopo aver verificato il modello rispetto al contorno di quel footprint; il record files del componente lo indica come EasyEDA C258169 (easyeda.com). add e refresh salvano il numero LCSC come lcsc, e use lo passa come campo lcsc del componente, che bom-jlcpcb.csv legge. --no-distributors salta entrambe le ricerche. Recupera il datasheet (URL o PDF di --datasheet, altrimenti l'URL del simbolo, altrimenti quello dei distributori), lo fissa nella cache dei datasheet in modo che datasheet purge non lo rimuova mai, e registra lo stock e le fasce di prezzo di ogni elenco. Le sue note indicano quando nessun distributore ha il componente in stock come componente attivo. --local aggiunge alla libreria del progetto.

use copia il simbolo in symbols/, il footprint in footprints/ e il modello in 3dmodels/ del progetto; un file che esiste già e differisce viene rifiutato senza --force. Restituisce il comando agentee edit sch che aggiunge il componente con i suoi campi mpn, mfr e library. datasheet text JST-PH-2 legge la copia fissata senza una chiamata di rete.

refresh chiede a ogni distributore con una chiave, una volta sola, tutti i part number della libreria e sostituisce ogni [[stock]] del componente; un distributore che fallisce mantiene il suo ultimo elenco. list stampa l'elenco più economico in stock con la data in cui è stato verificato, in modo che stock e prezzo siano noti senza una chiamata API, a quella data.

verify verifica ogni componente: ogni pin del simbolo ha una piazzola, il datasheet fissato indica il part number e il package (o un numero di pin), i nomi dei pin del simbolo compaiono in esso, il contorno del modello sta nel courtyard, i fori, le fessure e gli anelli del footprint rispettano i minimi di JLCPCB, e ogni file ha ancora l'hash con cui è stato aggiunto. Esce con 1 quando uno fallisce.

check avvisa (regola library) quando un progetto usa un componente fuori dalla libreria per un ruolo che la libreria detiene, indicando il componente della libreria da usare: quello con lo stesso numero di pin, il preferito per primo. Il ruolo di un componente è il suo campo role, o deriva dalla sua referenza: J/P connettore (rf connector per coassiale, SMA e U.FL, usb connector, modular connector, card socket), R resistore, C condensatore, L induttore, FB ferrite, D diodo o led, Q transistor, Y cristallo, F fusibile, SW interruttore, BT batteria, K relè. Un componente è nella libreria quando il suo campo mpn o library indica un componente della libreria, o quando si trova sul footprint di uno generic. Imposta il campo library = "no" del componente per escluderlo. library.toml alla radice della libreria imposta quanto spinge:

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