Biblioteca de componentes

A biblioteca de componentes é o conjunto próprio do utilizador: os conectores, reguladores, componentes passivos e tudo o que ele quiser reutilizar em cada projeto, para que os cabos e o stock se mantenham entre projetos. Cada componente guarda o seu símbolo, footprint, modelo 3D, folha de dados e o último stock verificado, e um agente escolhe a partir dela antes de recorrer a qualquer coisa nova (MCP library_find, library_list, library_show, library_use, library_add). O fluxo de trabalho para cada componente de que um projeto precisa é procurar, adicionar, usar: find mostra os componentes da biblioteca que correspondem e, quando nenhum corresponde, os componentes atuais em stock nos distribuidores; o escolhido vai para a biblioteca com add e para a placa com use.

Fica em ~/.config/agentee/library/ ($AGENTEE_LIBRARY muda o local), e um projeto pode adicionar ou substituir componentes em .agentee/library/ na sua raiz. Cada componente é um diretório:

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 os componentes da biblioteca cujo nome, função, etiquetas, número de peça, valor, classificação, footprint ou notas correspondem a todas as palavras. Só quando nenhum corresponde (ou com --search) executa as mesmas palavras como pesquisa por palavra-chave em cada distribuidor com uma chave e lista os componentes que estão ativos (sem estado de obsoleto, fim de vida ou descontinuado) com pelo menos --need em stock (padrão 1), combinados por número de peça: stock total, os distribuidores que o têm, o melhor preço unitário nessa quantidade e o link da folha de dados. Os componentes em stock em mais distribuidores vêm primeiro, depois por stock; --limit limita a lista (padrão 15). Um componente listado que já está na biblioteca indica isso.

add toma o símbolo e o footprint de um ficheiro .sym.toml ou .fp.toml, de um símbolo ou footprint do projeto (-p), ou de uma Library:Name do KiCad; o footprint é por omissão o do símbolo. Copia o modelo 3D do footprint (dos diretórios de modelos do KiCad, da cache de modelos ou de um download), aponta o footprint para a cópia e define a sua height a partir do modelo quando não tem, para que um componente funcione offline e continue a funcionar quando uma instalação do KiCad ou um download de um fornecedor muda. Quando o KiCad não tem um modelo com esse nome, toma o corpo mais próximo na mesma pasta .3dshapes, o mesmo pacote com o pad exposto mais próximo (ou o corpo simples de um footprint _ThermalVias) e diz isso; a vista 3D e models fazem o mesmo. --model também toma um download de fornecedor, um ZIP ou pasta que contém um .kicad_mod e o seu modelo STEP ou VRML (SamacSys, SnapMagic e Ultra Librarian fornecem estes): corresponde os pads do footprint do fornecedor aos nossos por número, recusa quando estão a mais de 0,1 mm de distância e escreve o model_offset e model_rotate que colocam o modelo do fornecedor no nosso footprint. Sem modelo do KiCad ou --model, add procura o número de peça na lista de componentes JLCPCB/LCSC e toma o modelo EasyEDA, colocado da mesma forma pelos pads do footprint EasyEDA após verificar o modelo contra o contorno desse footprint; os files do componente registam-no como EasyEDA C258169 (easyeda.com). add e refresh guardam o número LCSC como lcsc, e use passa-o como o campo lcsc do componente, que bom-jlcpcb.csv lê. --no-distributors salta ambas as pesquisas. Obtém a folha de dados (URL ou PDF de --datasheet, senão a URL do símbolo, senão a dos distribuidores), fixa-a na cache de folhas de dados para que datasheet purge nunca a remova e regista o stock e as quebras de preço de cada listagem. As suas notas dizem quando nenhum distribuidor tem o componente em stock como componente ativo. --local adiciona à biblioteca do projeto em vez da global.

use copia o símbolo para symbols/, o footprint para footprints/ e o modelo para 3dmodels/ do projeto; um ficheiro que já existe e difere é recusado sem --force. Devolve o comando agentee edit sch que adiciona o componente com os seus campos mpn, mfr e library. datasheet text JST-PH-2 lê a cópia fixada sem uma chamada de rede.

refresh pede a cada distribuidor com uma chave, uma vez, por todos os números de peça da biblioteca e substitui cada [[stock]] do componente; um distribuidor que falha mantém a sua última listagem. list imprime a listagem mais barata em stock com a data em que foi verificada, para que o stock e o preço sejam conhecidos sem uma chamada de API, até essa data.

verify verifica cada componente: cada pino do símbolo tem um pad, a folha de dados fixada nomeia o número de peça e o pacote (ou um número de pinos), os nomes dos pinos do símbolo aparecem nela, o contorno do modelo cabe no courtyard, os furos, ranhuras e anéis do footprint cumprem os mínimos da JLCPCB e cada ficheiro ainda tem o hash com que foi adicionado. Termina com 1 quando um falha.

check avisa (regra library) quando um projeto usa um componente fora da biblioteca para uma função que a biblioteca tem, nomeando o componente da biblioteca a usar: o com o mesmo número de pinos, o preferido primeiro. A função de um componente é o seu campo role, ou segue da sua referência: J/P conector (rf connector para coaxial, SMA e U.FL, usb connector, modular connector, card socket), R resistor, C condensador, L indutor, FB ferrite, D díodo ou led, Q transistor, Y cristal, F fusível, SW interruptor, BT bateria, K relé. Um componente está na biblioteca quando o seu campo mpn ou library nomeia um componente da biblioteca, ou quando está no footprint de um generic. Defina o campo library = "no" do componente para manter um fora. library.toml na raiz da biblioteca define o quão forte ela empurra:

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