AI Library

Creat: 7 septembrie 2026, ultima actualizare: 7 septembrie 2026

Instrucțiunile pentru agenții AI de programare tind să se acumuleze separat în fiecare repository. O regulă TypeScript este copiată în mai multe proiecte, un flux de linting se schimbă într-unul dintre ele, iar copiile ajung treptat să se contrazică. Un singur document comun reduce o parte din duplicare, dar nu poate exprima toate combinațiile de arhitectură, limbaj și instrumente fără să impună fiecărui repository reguli de care nu are nevoie.

ai-lib este un CLI TypeScript și un catalog pentru compunerea acestor instrucțiuni. Selectează modulele potrivite unui repository, le rezolvă dependențele, activează reguli pentru anumite combinații de module și instalează instrucțiunile și skill-urile rezultate ca fișiere locale. Pachetul se numește @sabinmarcu/ai, iar executabilul este ai.

Ce gestionează

Catalogul conține instrucțiuni, nu un model AI sau un serviciu de inferență. Modulele sale acoperă arhitectura proiectelor Node.js, TypeScript, React, Yarn, ESLint, hook-uri Git și convenții pentru commit-uri. Fișierele sursă includ instrucțiuni și skill-uri care explică unui agent cum să lucreze cu aceste tehnologii.

Aplicarea unei configurații scrie fișierele AI selectate și un punct de intrare gestionat. Nu instalează, prin ea însăși, ESLint, nu rescrie codul aplicației și nu execută fiecare pas descris de un skill. Instrucțiunile sunt folosite de un agent care lucrează în repository-ul țintă.

Distincția contează: ai-lib face setul de instrucțiuni reproductibil și inspectabil. Nu garantează că un agent îl va respecta sau că aplicația rezultată va fi configurată corect.

De la indicii din repository la un set de instrucțiuni

Detectarea inspectează structura repository-ului și informațiile despre pachete. Un modul poate furniza propriul detector, care întoarce o decizie de aplicabilitate, o explicație și dovezile folosite. Astfel, logica prin care TypeScript sau un anumit instrument devine relevant rămâne lângă modulul care îi furnizează instrucțiunile.

Configurația selectată nu reprezintă întregul set de instrucțiuni. Un preset furnizează o listă de ID-uri de module, iar modulele obișnuite pot depinde de alte module. Rezolvarea extinde aceste dependențe și respinge selecțiile incompatibile. Mixin-urile sunt evaluate după acest pas: se activează doar atunci când toate modulele obișnuite cerute sunt prezente.

De exemplu, instrucțiunile TypeScript și cele ESLint pot exista independent. Când ambele module sunt selectate, un mixin TypeScript și ESLint furnizează regulile de integrare. Nu este încă o opțiune pe care utilizatorul trebuie să-și amintească să o selecteze.

Exemplu de flux de rezolvare

O aplicație web Node tipică ce folosește TypeScript și ESLint ilustrează modul în care este construită o configurație. Selectarea preset-ului node-web și adăugarea modulului tooling/eslint începe cu două intrări explicite, care se extind în opt module efective și activează automat două mixin-uri:

Fluxul funcționează în etape clare:

1. Selecții de intrare: Utilizatorul sau detectorul solicită preset-ul node-web și modulul tooling/eslint.
2. Extinderea preset-ului: node-web se extinde în modulele sale componente (lang/typescript, arch/react, arch/web-application, guardrails/web-platform, guardrails/web-style, tooling/yarn și global/core).
3. Rezolvarea dependențelor tranzitive: arch/web-application și tooling/eslint declară ambele o dependență de arch/node-package, care este adăugat automat în setul de module efective.
4. Activarea mixin-urilor automate: Rezolvitorul evaluează condițiile mixin-urilor înregistrate în raport cu lista modulelor efective. Deoarece lang/typescript și tooling/eslint sunt ambele prezente, mixin/typescript-eslint se activează. În mod similar, arch/react și tooling/eslint activează mixin/react-eslint.
5. Materializarea: Toate modulele efective și mixin-urile active își scriu fișierele sursă la căile țintă sub .github/instructions/shared/ și asamblează .ai/AGENTS.md.

Fișiere locale cu proprietar înregistrat

Modul implicit de gestionare a fișierelor materializează resursele catalogului în repository-ul consumator. Acesta își păstrează astfel instrucțiunile fără să aibă nevoie de o conexiune permanentă la repository-ul sursă ai-lib în timpul lucrului obișnuit.

Trei fișiere descriu instalarea:

O referință din fișierul AGENTS.md de la rădăcină îndrumă agenții către punctul de intrare gestionat. Fișierele modulelor și mixin-urilor păstrează marcaje de proveniență care identifică proprietarul din catalog și versiunea sa.

Adaptările specifice repository-ului aparțin locațiilor locale, nu copiilor comune. Hash-urile înregistrate permit CLI-ului să distingă o actualizare din catalog de o modificare locală înainte de înlocuirea unui fișier.

Reconciliere pe măsură ce repository-ul se schimbă

O configurație de instrucțiuni poate deveni nepotrivită chiar dacă nimeni nu îi editează fișierele. Adăugarea TypeScript, eliminarea unui instrument sau schimbarea rolului unui proiect modifică regulile aplicabile.

Reconcilierea compară configurația existentă cu o selecție detectată din nou. Planul include schimbări ale modulelor selectate și efective, activarea sau dezactivarea mixin-urilor, schimbări ale locațiilor locale și probleme ale fișierelor gestionate. Aplicarea planului actualizează fișierele și configurația salvată, apoi se asigură că referința din punctul de intrare de la rădăcină există.

Nu este o înlocuire necondiționată cu rezultatul detectării. Preset-urile existente rămân selectate, iar modulele selectate explicit care nu au detector sunt păstrate. Modulele cu detector sunt reevaluate în raport cu starea curentă a repository-ului.

Limite

Fluxul implicit copiază instrucțiunile comune local; nu cere repository-ului consumator să importe o bibliotecă la execuție. Modul alternativ source leagă direct fișierele catalogului, dar cere ca acestea să se afle în repository-ul țintă. Este util când lucrezi la un catalog chiar în repository-ul care îl consumă, nu ca referință către un checkout extern arbitrar.

Implementarea separă și sincronizarea fișierelor de îmbinarea modificărilor locale. Divergențele trebuie inspectate și rezolvate deliberat, nu tratate ca text care poate fi îmbinat automat în orice situație. Transferul controlat al schimbărilor comune înapoi în sursa centrală este un obiectiv declarat al proiectului; nu este o comandă CLI înregistrată în sursa descrisă aici.