Publicarea unui plugin — AiHummer Documentație

Ai construit un plugin cu SDK-ul pentru plugin-uri? Îl poți publica în două moduri:

Privat (pentru tine) — încărcare laterală în instanța ta. Artefactul nu o părăsește niciodată.
Public (pentru toți) — îl trimiți în catalogul oficial AiHummer curatoriat printr-un PR.

Analogie: instalarea manuală a unui .vsix (privat) vs. publicarea în VS Code Marketplace (public); un registru npm privat vs. cel public.

Mod privat — încărcare laterală în instanța ta

Folosește acest mod atunci când doar tu ai nevoie de plugin: un conector intern, o integrare personalizată, o versiune de test.

Pași

Împachetează și semnează pachetul:

aihummer plugin package ./my-plugin
aihummer plugin sign --key author.key --manifest ./my-plugin/manifest.json my-plugin-1.0.0.tar.gz

Încarcă-l în instanță într-unul din două moduri:
- Interfața de administrare → Plugins → „Upload plugin” — trage pachetul; sau
- CLI:
```
aihummer plugin publish --private --instance https://your-instance \
  --token <admin-token> my-plugin-1.0.0.tar.gz
```
În culise, acesta este POST /v1/admin/modules/upload (multipart, integrations:write): artefactul ajunge în magazinul de blob-uri al instanței (AIHUMMER_BLOB_DIR) sub o referință blob:, iar un rând de catalog este înregistrat cu origin = local-private, visibility = private.
Plugin-ul apare în marketplace etichetat Private și se instalează prin calea normală — unitate systemd izolată + poartă de sănătate.

Încredere: cheia fixată și magazinul de încredere

Artefactele private trebuie semnate. Când încarci un plugin semnat cu o cheie necunoscută, interfața de administrare îți cere să aprobi cheia autorului în magazinul de încredere al instanței (un singur clic). Odată aprobată, semnătura este verificată la fiecare instalare și actualizare.

Artefactele din sursa oficială sunt verificate față de cheia de registru fixată în nucleu — de încredere în mod implicit, fără pas suplimentar.
Artefactele private sunt verificate față de cheile din magazinul de încredere al instanței.
Pachetele nesemnate sunt respinse — cu excepția modului de dezvoltare pentru iterație locală: AIHUMMER_PLUGIN_DEV_UNSIGNED=1.

[!WARNING] AIHUMMER_PLUGIN_DEV_UNSIGNED=1 dezactivează verificarea semnăturii și este destinat doar dezvoltării locale. Nu-l activa niciodată pe o instanță accesibilă din exterior.

Mod public — registrul public

Pentru a face un plugin disponibil pentru fiecare instanță, trimite-l în registrul public AiHummer/marketplace-catalog printr-un PR: verificări automate + recenzie, iar la aprobare AiHummer contrasemnează lansarea.

Pași

O singură dată — înregistrează editorul. Generează o cheie și rezervă spațiul de nume:
```
aihummer plugin keygen                # prints the public key (base64) and key id
```
Aceasta rezervă spațiul de nume @you. Păstrează cheia privată doar pentru tine — ea semnează fiecare trimitere.
Găzduiește artefactul la o adresă URL HTTPS stabilă (artefactul este găzduit de autor, nu de AiHummer).

Deschide un PR către catalog:

aihummer plugin publish --public --dir ./my-plugin --key author.key \
  --artifact-url https://you.example.com/my-plugin-1.0.0.tar.gz \
  --publisher you --description "What the plugin does" --icon https://you.example.com/icon.svg \
  [--screenshot https://you.example.com/1.png ...] [--channel stable|beta] \
  [--register-key author.pub]

--register-key adaugă publishers/<you>.json (necesar doar la prima ta trimitere).

Porțile CI validează trimiterea (vezi mai jos), recenzia AI postează un verdict de risc, iar un menținător AiHummer revizuiește și fuzionează manual.
La fuziune, lansarea este contrasemnată cu cheia de registru fixată și publicată într-un community-catalog.json separat pe CDN. Fiecare instanță care a adăugat această sursă vede plugin-ul; nucleul îl consideră de încredere prin cheia fixată — fără pas de încredere per operator.

Contractul de trimitere

Un PR adaugă două fișiere (forma este generată de publish --public și este stabilă):

publishers/<publisher>.json — înregistrare unică:

{
  "publisher": "acme",
  "public_key": "<base64 std ed25519 public key>",
  "key_id": "<sha256(public_key)[:16] in hex>",
  "contact": "you@example.com"
}

catalog/<publisher>/<slug>/plugin.json — o trimitere (una per linie de versiune):

{
  "publisher": "acme",
  "slug": "hello-tool",
  "namespaced_slug": "@acme/hello-tool",
  "version": "1.0.0",
  "channel": "stable",
  "artifact_url": "https://acme.example.com/hello-tool-1.0.0.tar.gz",
  "license": "MIT",
  "publisher_key_id": "bd68f2deedad25b1",
  "signature": "<base64 ed25519 over the release identity>",
  "manifest": { "...the full Manifest object..." }
}

namespaced_slug trebuie să fie egal cu @<publisher>/<slug>.
channel ∈ stable | beta.
artifact_url este .tar.gz-ul găzduit de autor.
publisher_key_id trebuie să corespundă cu key_id-ul editorului înregistrat.
Identitatea de lansare semnată = octeții slug \x00 version \x00 artifact_url.
Pentru o trimitere publică, manifest-ul încorporat trebuie să poarte description, icon (și, opțional, screenshots) — consultă câmpurile paginii de magazin.

[!TIP] aihummer plugin publish --public asamblează aceste fișiere în forma corectă și deschide PR-ul pentru tine — nu este nevoie să editezi JSON-ul manual.

Moderare

Fiecare trimitere trece printr-o verificare automată (contractul de trimitere, semnătura și o scanare de securitate), apoi printr-o recenzie consultativă AI a riscului și, în final, printr-o recenzie umană obligatorie de către echipa AiHummer. Nici automatizarea, nici AI-ul nu fuzionează niciodată pe cont propriu — decizia aparține întotdeauna unui menținător, iar nimic nu ajunge în catalog fără aprobarea acestuia. Un plugin publicat care se dovedește ulterior a fi rău intenționat sau defect poate fi revocat și eliminat din catalog la următoarea sincronizare.

Catalogul comunității ca sursă suplimentară

Plugin-urile publice sunt publicate într-un community-catalog.json separat care nu suprascrie catalogul oficial curatoriat. O instanță îl adaugă ca sursă suplimentară în Plugins → Sources (sau POST /v1/admin/modules/catalog/sources). Consultă Instalare și actualizări și Prezentare generală și niveluri.

Unde mergi mai departe

SDK pentru plugin-uri — câmpurile manifestului și comenzile aihummer plugin.
Instalare și actualizări — surse multiple, modelul de încredere, actualizări semnate, clasament.
Marketplace: prezentare generală și niveluri — registrul oficial vs. cel al comunității.