Biblioteca de componentes

La biblioteca de componentes es el propio conjunto de componentes del usuario: los conectores, reguladores, pasivos y lo demás que quiera reutilizar en cada diseño, para que los cables y el stock se mantengan entre proyectos. Cada componente guarda su símbolo, huella, modelo 3D, hoja de datos y el último stock verificado, y un agente elige de ella antes de buscar nada nuevo (MCP library_find, library_list, library_show, library_use, library_add). El flujo de trabajo para cada componente que necesita un diseño es buscar, añadir y usar: find muestra los componentes de la biblioteca que coinciden y, si ninguno lo hace, los componentes actuales en stock en los distribuidores; el elegido se añade a la biblioteca con add y a la placa con use.

Se guarda en ~/.config/agentee/library/ ($AGENTEE_LIBRARY lo mueve), y un proyecto puede añadir o sobrescribir componentes en .agentee/library/ en su raíz. Cada componente es un directorio:

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 lista los componentes de la biblioteca cuyo nombre, rol, etiquetas, número de pieza, valor, clasificación, huella o notas coinciden con cada palabra. Solo cuando ninguno coincide (o con --search) ejecuta esas mismas palabras como búsqueda por palabras clave en cada distribuidor con una clave y lista los componentes que están activos (sin estado de obsoleto, fin de vida o discontinuado) con al menos --need en stock (por defecto 1), fusionados por número de pieza: stock total, los distribuidores que lo tienen, el mejor precio unitario en esa cantidad y el enlace a la hoja de datos. Los componentes con stock en más distribuidores van primero, luego por stock; --limit limita la lista (por defecto 15). Un componente listado que ya está en la biblioteca lo indica.

add toma el símbolo y la huella de un archivo .sym.toml o .fp.toml, de un símbolo o huella del proyecto (-p) o de una Library:Name de KiCad; la huella por defecto es la del símbolo. Copia el modelo 3D de la huella (de los directorios de modelos de KiCad, de la caché de modelos o de una descarga), apunta la huella a la copia y fija su height desde el modelo si no la tiene, para que un componente funcione sin conexión y siga funcionando cuando cambie una instalación de KiCad o una descarga de un proveedor. Cuando KiCad no tiene un modelo con ese nombre, toma el cuerpo más cercano en la misma carpeta .3dshapes, el mismo paquete con el pad expuesto más cercano (o el cuerpo plano de una huella _ThermalVias) y lo indica; la vista 3D y models hacen lo mismo. --model también toma una descarga de proveedor, un ZIP o carpeta con un .kicad_mod y su modelo STEP o VRML (SamacSys, SnapMagic y Ultra Librarian los incluyen): coincide los pads de la huella del proveedor con los nuestros por número, se niega si están a más de 0,1 mm de distancia y escribe el model_offset y el model_rotate que colocan el modelo del proveedor sobre nuestra huella. Sin modelo de KiCad ni --model, add busca el número de pieza en la lista de componentes de JLCPCB/LCSC y toma el modelo de EasyEDA, colocado de la misma manera por los pads de la huella de EasyEDA tras comprobar el modelo contra el contorno de esa huella; el campo files del componente lo registra como EasyEDA C258169 (easyeda.com). add y refresh guardan el número de LCSC como lcsc, y use lo pasa como el campo lcsc del componente, que bom-jlcpcb.csv lee. --no-distributors omite ambas búsquedas. Descarga la hoja de datos (URL o PDF de --datasheet, si no la URL del símbolo, si no la de los distribuidores), la fija en la caché de hojas de datos para que datasheet purge nunca la elimine y registra el stock y las escalas de precio de cada listado. Sus notas indican cuándo ningún distribuidor tiene el componente en stock como parte activa. --local añade a la biblioteca del proyecto en su lugar.

use copia el símbolo en symbols/, la huella en footprints/ y el modelo en 3dmodels/ del proyecto; un archivo que ya existe y difiere se rechaza sin --force. Devuelve el comando agentee edit sch que añade el componente con sus campos mpn, mfr y library. datasheet text JST-PH-2 lee la copia fijada sin una llamada de red.

refresh pide a cada distribuidor con una clave una vez por todos los números de pieza de la biblioteca y reemplaza cada [[stock]] del componente; un distribuidor que falle mantiene su último listado. list imprime el listado más barato en stock con la fecha en que se verificó, para que el stock y el precio se conozcan sin una llamada a la API, a fecha de esa fecha.

verify comprueba cada componente: cada pin del símbolo tiene un pad, la hoja de datos fijada nombra el número de pieza y el paquete (o un número de pines), los nombres de los pines del símbolo aparecen en ella, el contorno del modelo cabe en el courtyard, los agujeros, ranuras y anillos de la huella cumplen los mínimos de JLCPCB y cada archivo sigue teniendo el hash con el que se añadió. Sale con 1 si uno falla.

check avisa (regla library) cuando un diseño usa un componente fuera de la biblioteca para un rol que la biblioteca tiene, nombrando el componente de la biblioteca que usar: el que tiene el mismo número de pines, el preferido primero. El rol de un componente es su campo role, o se deduce de su referencia: J/P conector (rf connector para coaxial, SMA y U.FL, usb connector, modular connector, card socket), R resistencia, C condensador, L inductor, FB ferrita, D diodo o led, Q transistor, Y cristal, F fusible, SW interruptor, BT batería, K relé. Un componente está en la biblioteca cuando su campo mpn o library nombra un componente de la biblioteca, o cuando está sobre la huella de uno generic. Fija el campo library = "no" del componente para excluir uno. library.toml en la raíz de la biblioteca fija con qué fuerza lo empuja:

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