AiHummer
Français▾
ConnexionCompte
v1.1.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Place de marché et plugins/SDK de plugin

SDK de plugin

v1.1.x · mis à jour 2026-06-27

Un plugin est décrit par Une manifest.json. Le contrat qui valide le manifeste lors du développement est le même que celui que la plateforme applique au moment de l’installation, donc un manifeste qui passe validate est un manifeste que le marché acceptera. Le aihummer plugin L’interface en ligne de commande couvre tout le cycle de vie : de l’ossature à la signature et à la publication.

Un manifeste, un contrat

Un plugin n’a qu’une seule source de vérité — sa manifest.json. Il déclare le type de plugin (kind), comment il est configuré (config[]), ses capacités, et — pour les services natifs de l’hôte — le install[] les étapes et la commande de démarrage que le Déployeur Systemd fonctionne. Parce que le développement et l’installation utilisent le même contrat de validation, « manifeste valide » et « plugin installable » signifient la même chose.

[!NOTE] Le manifeste décrit un plugin contrat, pas son nom sur la page du magasin. Le machine slug provient du nom du répertoire/paquet (chargement latéral privé) ou de la soumission que vous remplissez «Mes plugins» lors de la publication d’un plugin communautaire — voir Publier un plugin.

CLI

aihummer plugin regroupe les commandes de développement, d’emballage et de publication :

# Scaffold a manifest (kind: connector | service | openapi | mcp)
aihummer plugin init <kind> [dir]

# Validate a manifest against the install contract
aihummer plugin validate <manifest.json>

# Generate an ed25519 author key (writes <prefix>.key and <prefix>.pub)
aihummer plugin keygen [--out <prefix>]

# Build and package the plugin into a release tarball + .sha256
aihummer plugin package <dir> [--out <file>] [--slug <slug>] [--build "<cmd>"]

# Sign the release identity (slug\0version\0source_ref); with --manifest the
# signature is embedded into the manifest.signature field
aihummer plugin sign --key <priv> [--manifest <m.json>] <bundle|dir>

# Upload a private plugin into your own instance (side-load)
aihummer plugin publish --private --instance <url> --token <admin> <bundle.tar.gz>

Publier un communauté plugin pour tout le monde, tu fais pas utilisez une commande CLI — vous téléchargez l’artéfact emballé et signé depuis votre Mes plugins dans le cabinet personnel (téléverser → révision par l’IA → modération). Voir Soumettre un plugin.

Commande Ce que cela fait
init <kind> [dir] Écrit un démarreur manifest.json pour le type choisi.
validate <m.json> Valide le manifeste avec le même contrat que l’installation.
keygen Génère la paire de clés de l’auteur : .key (privé, garder secret) et .pub, imprime le key id.
package <dir> Construire (opt.) --build) et se range dans <slug>-<version>.tar.gz avec un --strip-components=1 mise en page, écrit .sha256. Ne jamais emballer .env, *.key, node_modules, .git.
sign --key <priv> Signe l’identité de la libération ; imprime la signature et key id; avec --manifest intègre la signature dans le manifeste.
publish --private Télécharge un paquet sur l’instance de votre POST /v1/admin/modules/upload.

Les deux voies de publication — le téléchargement latéral privé et la publication communautaire via le cabinet personnel — sont détaillées sur Publier un plugin.

Champs de manifeste

Que ce champ soit obligatoire dépend de gentil et selon que le plugin est public. Champs de base et d’identité :

Champ Type Requis But
kind chaîne toujours Gentil : connector | service | openapi | mcp.
version chaîne oui Version du plugin (semver), par exemple 1.0.0.
contract chaîne pour les chaînes ID du contrat, par exemple aihummer.channel.v1.
scope chaîne non Modèle d’accès : shared (par défaut) ou personal.
capabilities tableau de chaînes non Capacités déclarées.
config objet[] non Champs du formulaire de configuration ; chacun en a besoin key, plus label, secret, required.
oauth objet non OAuth2 (authorize_url, token_url, scopes[]) pour connecter le compte d’un utilisateur.
signature chaîne lors de la signature signature ed25519 en base64 sur l’identité de la release (intégrée par sign).

Champs spécifiques au type — exactement un le bloc est rempli en fonction de kind:

Champ Pour aimable Requis But
host_native.exec_start connecteur, service oui Commande qui exécute le service de longue durée.
host_native.runtime connecteur, service, mcp non node | python | binary.
host_native.install connecteur, service, mcp non Étapes d’installation (tableau de commandes shell), à exécuter sur l’hôte après extraction.
host_native.port connecteur, service non Port TCP préféré (le déployeur peut le réaffecter via $PORT).
host_native.health_path connecteur, service non Chemin de vérification de santé (par défaut /healthz).
openapi.spec_url openapi oui URL de la spécification OpenAPI 3.x.
openapi.base_url openapi non Anuler servers[0].url.
openapi.allowed_hosts openapi non Liste blanche de sortie pour les outils synthétisés.
openapi.auth openapi non Carte securityScheme → nom secret.
openapi.tool_prefix openapi non Préfixe du nom de l’outil.
mcp.transport mcp oui stdio ou http.
mcp.command / mcp.args mcp (stdio) oui pour stdio Exécutable du serveur et arguments.
mcp.url mcp (http) oui pour http URL du point de terminaison MCP.
mcp.auth_header / mcp.secret_token_key mcp (http) non En-tête et clé secrète pour le jeton porteur.

Page de magasin et champs d’identité (pour les plugins communautaires)

Le manifeste peut également contenir l’identité de l’éditeur et les champs de la page de magasin. Pour un communauté plugin ce sont ce que le catalogue montre, mais vous les entrez normalement dans le «Mes plugins» page de magasin dans votre cabinet personnel au moment de la soumission (nom, descriptions, icône, captures d’écran, catégorie, lien de don) plutôt que manuellement dans le manifeste. Un chargement latéral privé n’a besoin d’aucun d’eux — un tel plugin est approuvé au niveau de l’instance.

Champ Type Requis But
visibility chaîne non public | private | unlisted. Vide = héritage/première partie (aucune exigence d’identité).
publisher chaîne pour le public Espace de noms de l’éditeur, ^[a-z0-9][a-z0-9-]{1,38}$. Les limaces publiques sont nommées @publisher/slug.
publisher_key_id chaîne pour le public key id de la clé avec laquelle l’artéfact est signé.
description chaîne pour le public Texte de présentation de la page du magasin dans le catalogue.
icon chaîne pour le public Icône du plugin : un https:// URL ou un data: URI.
screenshots tableau de chaînes non Captures d’écran de la page du magasin (tableau de https:// URLs ; chacune non vide).

[!TIP] Courir aihummer plugin validate avant de soumettre. L’installation et la validation les contrats sont identiques, donc un manifeste qui passe localement sera accepté dans les deux cas par le déployeur de la place de marché et par l’examen de la place de marché dans votre cabinet personnel.

Manifestes minimaux

A service échafaudage (quoi aihummer plugin init service écrit):

{
  "version": "1.0.0",
  "kind": "service",
  "scope": "shared",
  "contract": "aihummer.channel.v1",
  "host_native": {
    "runtime": "node",
    "install": ["npm ci --omit=dev"],
    "exec_start": "node dist/main.js",
    "port": 8800,
    "health_path": "/healthz"
  },
  "config": [
    { "key": "api_token", "label": "API token", "secret": true, "required": true }
  ]
}

Un zéro-code openapi le manifeste est encore plus court — il renvoie simplement à la spécification :

{
  "version": "1.0.0",
  "kind": "openapi",
  "scope": "shared",
  "openapi": {
    "spec_url": "https://api.example.com/openapi.json",
    "tool_prefix": "example_",
    "allowed_hosts": ["api.example.com"],
    "auth": { "bearerAuth": "api_token" }
  },
  "config": [
    { "key": "api_token", "label": "API token", "secret": true, "required": true }
  ]
}

une mcp manifeste (transport stdio):

{
  "version": "1.0.0",
  "kind": "mcp",
  "scope": "shared",
  "host_native": { "runtime": "node", "install": ["npm ci --omit=dev"] },
  "mcp": { "transport": "stdio", "command": "node", "args": ["server.js"] }
}

Du manifeste au marché

Après validation, un plugin est empaqueté (package), signé (sign) et publié de l’une des deux manières :

  • Privé (pour vous-même) — chargez en externe dans votre instance via l’interface d’administration ou publish --private. L’artefact ne quitte jamais l’instance.
  • Communauté (pour tous) — téléchargez l’artefact empaqueté et signé depuis le Mes plugins dans votre cabinet personnel ; après examen par l’IA et modération humaine, il est signé et publié à la communauté catalogue.

Voir Publier un plugin pour la visite complète.

Où ensuite