Packs & SDK d'authoring
Un SDK, un cycle de vie — créez des Intégrations, Ontologies, Workflows, Flux de processus et Sources de données, et livrez-les sous forme d'archives prêtes à téléverser
@scrydon/sdk-authoring est le SDK unique pour la création d'extensions de plateforme. Il dispose de cinq surfaces de sous-chemin — une par artefact que vous pouvez livrer :
Intégrations
Connecteurs fournisseurs avec authentification, blocs, outils et runtimes de capacités (LLM, STT, TTS, embeddings, OCR, vidéo, webhooks).
Ontologies
Types d'objets typés, types de liens, types d'actions, règles d'identité et liaisons livrés sous forme de pack versionné.
Workflows
Workflows de graphe de blocs exécutables (portes HITL, approbations, automatisations) livrés dans un Pack aux côtés d'un Flux de processus.
Flux de processus
Flux de processus réutilisables avec stages, tâches, personas, déclencheurs vocaux et modèles d'actions.
Sources de données
Sources de données déclaratives en mode poll — spécification de requête REST, DSL de correspondance de champs bornée, et liste de colonnes typées — livrées sous forme de JSON pur dans un Pack.
Pack vs Intégration
Il existe deux types d'archives de niveau supérieur que vous téléversez dans Scrydon. Choisissez en fonction de ce que vous modélisez :
- Intégration — un bundle de capacités fournisseur. ESM compilé + manifeste + SBOM, s'exécute en sandbox dans la plateforme. Utilisez-le pour connecter Scrydon à un service externe (Slack, OpenAI, Twilio) et exposer des capacités — LLM, STT, TTS, embeddings, OCR, vidéo, webhooks, blocs et outils. Créé avec
defineVendor, buildé avecbunx @scrydon/sdk-authoring integrations build. - Pack — un package de contenu de domaine. Regroupe une Ontologie (types d'objets typés, types de liens, types d'actions), zéro ou plusieurs Workflows (portes HITL, routes d'approbation, automatisations), un Flux de processus (stages, tâches, personas, modèles d'actions), zéro ou plusieurs Sources de données (sources de poll déclaratives — requête REST, DSL de correspondance de champs, liste de colonnes typées), et zéro ou plusieurs intégrations personnalisées dans une archive prête à téléverser. Un tableau
contents[]de pack peut mélanger les typesontology,workflow,process-flow,data-sourceetintegration. Utilisez-le pour livrer un modèle de domaine avec son playbook standard, ses flux de données et toute intégration fournisseur personnalisée dont il dépend. Créé avecdefineScrydonPack, buildé avecbunx @scrydon/sdk-authoring pack build.
En résumé : Les Intégrations apportent des capacités dans la plateforme ; les Packs apportent du contenu de domaine — et peuvent inclure des intégrations personnalisées. Les Intégrations se téléversent via Paramètres → Plateforme → Intégrations → Personnalisées ; les Packs se téléversent via Paramètres → Plateforme → Packs.
Installation
bun add -d @scrydon/sdk-authoring zodnpm install --save-dev @scrydon/sdk-authoring zodConfirmez que l'installation s'est correctement résolue :
bunx @scrydon/sdk-authoring --versionFonctionnement de l'authoring
Chaque artefact utilise la même structure :
Composez votre artefact avec les helpers define*(). Ce sont des fonctions d'identité à l'exécution — leur rôle est de restreindre les types afin que votre IDE détecte les erreurs avant le build.
Un schéma Zod de manifeste (ManifestSchema, OntologyManifestSchema, ProcessFlowManifestSchema) valide l'artefact lors du build et à nouveau sur le serveur lors du téléversement.
Exécutez la CLI correspondante pour produire un .tar.gz prêt à téléverser. Les bundles d'intégration contiennent de l'ESM compilé + un SBOM CycloneDX ; les archives de Pack (ontologie, flux de processus, …) sont du JSON pur.
Téléversez via Paramètres → Plateforme → Intégrations → Personnalisées (Intégrations) ou Paramètres → Plateforme → Packs (Packs), ou l'API d'administration correspondante. La plateforme valide le manifeste, persiste l'artefact et l'enregistre dans le catalogue. Aucun redéploiement requis.
CLI
@scrydon/sdk-authoring livre un seul binaire avec deux sous-commandes. Invoquez-le via la forme qualifiée par le package — cela fonctionne que le package soit installé localement ou non :
| Sous-commande | Auteurs | Commandes |
|---|---|---|
@scrydon/sdk-authoring integrations | Bundles d'intégration fournisseur | init, build, test |
@scrydon/sdk-authoring pack | Scrydon Packs (ontologie + workflows + flux de processus + sources de données + intégrations) | build, inspect, validate |
Les packs d'ontologie sont livrés comme sous-répertoire du Scrydon Pack. Les packages d'ontologie autonomes utilisent le même SDK defineOntology sans CLI nécessaire (ils sont intégrés dans des Packs ou livrés via npm).
bunx @scrydon/sdk-authoring --version
bunx @scrydon/sdk-authoring --help
bunx @scrydon/sdk-authoring integrations --help
bunx @scrydon/sdk-authoring pack --help
bunx @scrydon/sdk-authoring integrations build --entry src/index.ts
# pack build accepte un répertoire — il découvre automatiquement pack.ts | pack.mjs | pack.js | pack.json,
# puis dérive un répertoire source pour CHAQUE entrée `contents[]` déclarée à
# <baseDir>/<entry.path>. Cela couvre tous les types de contenu — ontology,
# workflow, process-flow, data-source et integration — donc un pack mélangeant
# les types se construit sans aucun flag par type.
bunx @scrydon/sdk-authoring pack build .
bunx @scrydon/sdk-authoring pack build ./my-pack
# `--ontology` / `--process-flow` restent des remplacements optionnels pour
# l'emplacement des sous-répertoires de ces deux types ; tout autre type est
# pris depuis contents[].path.
bunx @scrydon/sdk-authoring pack build pack.json --ontology ./ontology --process-flow ./process-flowValider un pack construit — la porte de synchronisation de la plateforme, en local
pack validate pointé vers un répertoire de pack construit (dont le
manifeste est un pack.json — p. ex. dist/<pack> dans un dépôt de source
de packs Git) exécute localement la porte de synchronisation complète de la
plateforme : règles de fichiers et d'extensions, agencement des
sous-répertoires déclarés, schéma pack.json et chaque schéma
manifest.json par type. Les règles et messages d'erreur sont exactement
ceux que l'inspecteur de bundles de la plateforme applique à chaque
synchronisation — un pack qui passe ici ne peut pas échouer à la validation
côté synchronisation : un contents[].kind invalide ou un répertoire non
déclaré fait échouer votre PR au lieu de la prochaine synchronisation.
# Validation complète (porte de synchronisation) d'un répertoire de pack construit.
# Sources de packs Git : exécutez ceci sur chaque dist/<pack> en CI.
bunx @scrydon/sdk-authoring pack validate ./dist/my-pack
# Validation du manifeste seul (manifestes source : pack.ts | pack.mjs | pack.json)
bunx @scrydon/sdk-authoring pack validate ./my-pack/pack.ts
bunx @scrydon/sdk-authoring pack validate ./my-pack --manifest-onlypack build exécute la même validation manifeste + schémas par type pendant
la construction : les flux basés sur des archives obtiennent les mêmes
garanties au moment du build.
Construire une source de packs Git — pack build-dist
Les sources de packs Git committent des répertoires dist/<pack>/
construits que la plateforme archive et inspecte à chaque synchronisation.
pack build-dist prend en charge toute la transformation src→dist : un dépôt
de packs n'a plus besoin de script de build maison :
# src/<pack> → dist/<pack> : compile pack.ts / manifest.ts (manifestVersion
# injecté pour les entrées DSL ontology + workflow), construit les sources
# d'intégration de manière déterministe (SBOM stable + bundle.tar.gz stable
# au octet près), ignore les répertoires préfixés par _, copie les assets —
# puis exécute la porte de synchronisation complète sur le résultat.
bunx @scrydon/sdk-authoring pack build-dist src/my-pack --outDir dist/my-packLes types de contenu proviennent du contents[] du manifeste — jamais du
nom des répertoires. Reconstruire un pack inchangé produit une sortie
identique au octet près : le dist/ committé ne dérive jamais d'une machine
à l'autre.
Pour un dépôt de source de packs complet, pack build-source est la seule
commande de build nécessaire — plus aucun script de build :
# Construit chaque src/<pack> → dist/<pack> via build-dist, puis vérifie les
# versions des entrées scrydon.yaml contre les artefacts construits (un écart
# est ce que la plateforme rejette comme version_mismatch à la synchronisation).
bunx @scrydon/sdk-authoring pack build-source . --check-catalog
# --waive rétrograde l'échec d'un pack nommé en avertissement visible — pour
# du contenu délibérément en avance sur la plateforme (p. ex. un type de
# contenu pas encore livré). Tout le reste fait toujours échouer le build.
bunx @scrydon/sdk-authoring pack build-source . --check-catalog --waive my-experimental-packFormats d'archive
| Artefact | Archive | Code ? | Validé par |
|---|---|---|---|
| Intégration | <vendorId>-<version>.bundle.tar.gz | ESM compilé + manifeste + SBOM | ManifestSchema (Zod), inspecteur CycloneDX, garde de dépendances natives |
| Scrydon Pack | <package.id>-<package.version>.scrydon-pack.tar.gz (ontologie + zéro ou plusieurs sous-répertoires workflow + flux de processus + zéro ou plusieurs sous-répertoires data-source) | Aucun — JSON pur | PackBundleManifestSchema, ProcessFlowManifestSchema, OntologyManifestSchema, WorkflowManifestSchema, DataSourceManifestSchema, validateur de cycle de DAG |
Les bundles d'intégration s'exécutent en sandbox dans un Worker Thread avec une liste de blocage de modules Node ; les flux de processus et les packs d'ontologie sont des données pures et n'exécutent jamais le code fourni par l'appelant.
Créer votre premier Pack
La façon la plus rapide d'apprendre la surface est de livrer un Pack de bout en bout. Chaque étape renvoie au guide complet par artefact :
Définissez les types d'objets, types de liens, types d'actions et règles d'identité. → Authoring : Ontologies
Portes HITL, routes d'approbation, automatisations que les actions du flux invoqueront par slug. → Authoring : Workflows
Stages, modèles de tâches, personas, modèles d'actions, déclencheurs vocaux. → Authoring : Flux de processus
Sources de poll déclaratives : spécification de requête REST, DSL de correspondance de champs, colonnes typées. → Authoring : Sources de données
bunx @scrydon/sdk-authoring pack build ./my-packProduit <package.id>-<package.version>.scrydon-pack.tar.gz — JSON pur, validé par les schémas de manifeste et le validateur de cycle de DAG.
Paramètres → Plateforme → Packs (ou l'API d'administration). Une installation atomique : ontologie, workflows, flux de processus, sources de données.
Pour aller plus loin
Créer une Intégration personnalisée
Connecteurs fournisseurs — defineVendor, capacités, blocs, outils, et la boucle build / upload.
Créer un pack d'Ontologie
Définissez les types d'objets, types de liens, types d'actions, règles d'identité et liaisons.
Créer un Workflow
Portes HITL, routes d'approbation et automatisations référencées par les Flux de processus via slug.
Livrer un Flux de processus
Stages, modèles de tâches, personas, modèles d'actions et déclencheurs vocaux.
Créer une Source de données
Sources de données déclaratives en mode poll — requête REST, DSL de correspondance bornée et colonnes typées — livrées sous forme de JSON pur dans un Pack.