DDS Plugin SDK
Installez le DDS Plugin SDK 1.2 public et utilisez les workflows, le cache, les flux d’outils, LSP et les API stables.
Les exemples d’espace de travail utilisateur ci-dessous décrivent un hôte de développement explicitement connecté et contrôlé par le client. Choisissez WSL ou un autre hôte pour ces exemples autonomes du SDK. L’application Windows Digital Design Studio ordinaire utilise son environnement d’exécution Windows natif. Configurez la découverte, les autorisations et les capacités de plugin pour l’hôte SDK sélectionné ; les tâches de moteur Cloud gérées utilisent leur propre voie d’exécution.
1. Installer le SDK
DDS Plugin SDK 1.2.1 fournit des API JavaScript, des déclarations TypeScript, des fournisseurs de langage, des thèmes, des outils d’espace de travail et des tâches de commande. Les stockages durables facultatifs ajoutent un historique des tâches, une relance explicite et des instantanés texte/binaires vérifiés qui persistent après la suppression des sources et le redémarrage du processus. Utilisez Node.js 22 ou 24. Installez la version stable du SDK depuis la version officielle sur GitHub. Pour un plugin de commande autonome, utilisez Outils de développement après l’installation :
1.0.0 publie l’API stable du SDK, 18 profils de conformité des hôtes, une politique de prise en charge/migration et des vérifications mesurées de charges de travail combinées. Les nouveaux plugins utilisent >=1.0.0 <2.0.0. La publication du SDK attribue ces résultats à la validation fonctionnelle du SDK et des hôtes indépendants.
0.13.0 ajoute six modèles de développement, des types et schémas générés, des scénarios de test déterministes et des diagnostics locaux facultatifs. Le SDK empaqueté et les projets générés fonctionnent en dehors de l’arborescence des sources ; la relecture synthétique et le débogage en boucle locale sont sélectionnés explicitement.
0.12.0 ajoute des paramètres typés avec portée et des migrations explicites, des références de secrets limitées à une exécution, des entrées/sorties de commande structurées, des catalogues de langues et des métadonnées d’accessibilité. Le SDK public et les exemples indépendants vérifient les conflits de paramètres, les entrées invalides, les droits révoqués et le repli des traductions.
0.11.0 ajoute l’aide à la signature, la complétion à la demande, des extraits bornés, les modifications multifichiers et les renommages soumis à révision, le formatage/les actions de code, les jetons sémantiques, le repliage, les indications et les symboles hiérarchiques. Les propositions, leur examen, les contrôles des droits actuels et l’application conditionnelle sont des étapes distinctes de l’hôte. Les hôtes affichent et appliquent les résultats uniquement tant que l’identité de leur document est actuelle. Ces fonctionnalités sont exercées par le SDK public et des exemples indépendants.
0.10.0 ajoute les téléchargements en flux dans le navigateur, les téléversements de fichiers sélectionnés, une file de transferts mixtes et la récupération à partir de points de contrôle Worker OPFS. Les transferts vérifient les droits actuels, l’identité du fichier et les empreintes des blocs/du fichier entier, tout en distinguant la progression en octets du stockage vérifié. Ces exemples exercent les hôtes et clients du SDK public.
0.9.0 ajoute des arborescences de projet avec portée, la recherche par nom de fichier/texte et l’observation des changements pour les répertoires locaux choisis par l’opérateur. Utilisez-les depuis le client HTTP ou l’utilitaire de projet tout en conservant les instantanés de modification et les brouillons non enregistrés. Les exemples de projet ci-dessous couvrent la création, la recherche, les changements externes et la gestion des conflits.
mkdir hello-dds-plugin
cd hello-dds-plugin
npm init -y
npm install --ignore-scripts --save-exact "https://github.com/Altifigence/dds-plugin-sdk/releases/download/v1.2.1/altifigence-dds-plugin-sdk-1.2.1.tgz"
Le premier exemple de diagnostic utilise du code de confiance dans un hôte de test local. Les thèmes utilisent l’import XML existant de DDS. Pour les intégrations d’outils existantes, consultez Plugins et outils tiers.
2. Écrire votre premier plugin
Créez plugin.mjs dans le nouveau projet. Ce plugin vérifie les documents en texte brut et signale un diagnostic informatif sur chaque ligne contenant NOTE.
plugin.mjs
import { createDiagnosticsResult, definePlugin } from '@altifigence/dds-plugin-sdk';
export default definePlugin({
manifestVersion: 1,
id: 'hello-diagnostics',
name: 'Hello Diagnostics',
publisher: 'example',
version: '0.1.0',
protocolVersion: 1,
entry: './plugin.mjs',
capabilities: ['diagnostics'],
permissions: ['document.read', 'diagnostics.publish'],
supportedHosts: ['test-host'],
license: 'Apache-2.0',
}, context => context.registerDiagnosticsProvider({languages: ['plaintext']}, {
provideDiagnostics(request, {signal}) {
signal.throwIfAborted();
const diagnostics = [];
const lines = request.snapshot.text.split(/\r\n|\n|\r/);
for (let line = 0; line < lines.length; line++) {
const character = lines[line].indexOf('NOTE');
if (character !== -1) diagnostics.push({
range: {start: {line, character}, end: {line, character: character + 4}},
severity: 'info',
code: 'todo',
source: 'hello-diagnostics',
message: 'Review this marked line before sharing the document.',
});
}
return createDiagnosticsResult(request, diagnostics);
},
}));
Le manifeste déclare la version 1 du protocole, la fonctionnalité diagnostics, l’hôte test-host et les autorisations document.read et diagnostics.publish. Le fournisseur reçoit un instantané du document et un AbortSignal. Les plages de diagnostic utilisent des lignes numérotées à partir de zéro et des décalages de caractères UTF-16.
3. L’exécuter localement
Créez run.mjs à côté de plugin.mjs. Activez le plugin, fournissez un document et demandez des diagnostics. Libérez toujours les ressources de l’hôte lorsque vous avez terminé.
run.mjs
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
const host = createTestHost();
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'example-1',
text: 'Hello, DDS!\nNOTE: write a plugin.\n',
});
const result = await host.requestDiagnostics();
console.log(`${plugin.manifest.name}: ${result.diagnostics.length} diagnostic`);
for (const diagnostic of result.diagnostics) {
console.log(`${diagnostic.severity} ${diagnostic.range.start.line + 1}:${diagnostic.range.start.character + 1} ${diagnostic.message}`);
}
} finally {
host.dispose();
}
node run.mjs
Sortie attendue (la ligne et la colonne affichées sont numérotées à partir de un) :
Texte
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. Tester votre plugin
Enregistrez ce test sous plugin.test.mjs. Il vérifie la plage du diagnostic et confirme que la modification du document efface le diagnostic.
plugin.test.mjs
import assert from 'node:assert/strict';
import test from 'node:test';
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
test('reports a NOTE and clears it after editing', async () => {
const host = createTestHost();
try {
await host.activate(plugin);
const document = {
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'test-1',
text: 'NOTE: write a plugin.\n',
};
host.setDocument(document);
const result = await host.requestDiagnostics();
assert.equal(result.diagnostics.length, 1);
assert.equal(result.diagnostics[0].code, 'todo');
assert.deepEqual(result.diagnostics[0].range, {
start: {line: 0, character: 0},
end: {line: 0, character: 4},
});
host.setDocument({...document, modelVersion: 2, text: 'Done.\n'});
assert.equal((await host.requestDiagnostics()).diagnostics.length, 0);
} finally {
host.dispose();
}
});
node --test plugin.test.mjs
Le test devrait réussir. Ajoutez des jeux de données pour votre propre langage, l’annulation, les résultats invalides et les documents volumineux. Maintenez la version du document à jour afin de rejeter les résultats issus d’un instantané antérieur.
5. Créer et appliquer un thème
Enregistrez cette palette claire/sombre sous theme.json. Les six couleurs de chaque palette sont obligatoires. Les jetons sémantiques facultatifs personnalisent la recherche, les sélections, HintsBox et le canevas GDS ; les jetons omis utilisent les valeurs par défaut de DDS.
theme.json
{
"name": "Hello Ocean",
"colors": {
"light": {
"backdrop": "#dbe8ef",
"navigation": "#edf5f8",
"tool": "#f3f8fb",
"main": "#ffffff",
"text": "#183b4e",
"muted": "#486477"
},
"dark": {
"backdrop": "#0c1922",
"navigation": "#102430",
"tool": "#17303e",
"main": "#1c3949",
"text": "#e8f4fb",
"muted": "#adcadb"
},
"metrics": {
"panelRadius": 16,
"controlRadius": 8
}
}
}
Créez export-theme.mjs à côté. parseTheme valide les données de couleur et serializeThemeXml exporte le XML DDS version 2.
export-theme.mjs
import { readFile, writeFile } from 'node:fs/promises';
import { parseTheme, serializeThemeXml } from '@altifigence/dds-plugin-sdk/themes';
const theme = parseTheme(await readFile('./theme.json', 'utf8'));
await writeFile('./hello-theme.xml', serializeThemeXml(theme), 'utf8');
console.log('Created hello-theme.xml');
node export-theme.mjs
La commande écrit hello-theme.xml et affiche Created hello-theme.xml. Dans DDS, ouvrez Plugins → Installer le thème…, sélectionnez le XML, puis choisissez Appliquer pour Hello Ocean. Passez de l’apparence claire à l’apparence sombre pour voir les deux palettes.
Vous pouvez aussi utiliser Paramètres → Général → Apparence → Importer XML. Enregistrez le thème actuel avec Exporter XML avant de le remplacer. L’importateur XML lit les données d’apparence du thème.
Le guide des thèmes répertorie tous les jetons et toutes les métriques pris en charge. L’exemple Hello Ocean comprend le thème complet, un XML prêt à importer et un aperçu HTML local.
Référence XML des thèmes
Téléchargez le XML Hello Ocean et son JSON modifiable. Le XML contient des palettes claire et sombre complètes, les 28 couleurs de rôle facultatives dans chaque mode et quatre métriques explicites. Enregistrez le fichier XML localement avant de l’importer. Ces exemples originaux du SDK utilisent Apache-2.0 ; conservez la notice lorsque vous les partagez.
Commencez par Paramètres → Général → Apparence → Exporter XML pour sauvegarder votre thème actuel. Importez le XML téléchargé, examinez le brouillon, puis choisissez Appliquer. Annuler les modifications conserve le thème appliqué. Alternez entre apparence claire et sombre pour examiner les deux palettes. Pour récupérer, choisissez un thème intégré ou importez votre copie enregistrée. Un import refusé préserve le thème actuel.
DDS, ALcad, les éditeurs partagés, la navigation dans le projet, les paramètres et les fenêtres contextuelles utilisent la palette partagée de l’atelier dans ce profil. Le même format de thème est utilisé par Cloud et la version de bureau ; importez-le séparément dans chaque profil. gdsBackground contrôle le canevas GDS indépendamment. Les autres couleurs de canevas de conception, de couches et de simulation peuvent disposer de leurs propres paramètres. Le XML contient la palette et les métriques d’apparence de ce profil de thème.
Élément | Règle |
|---|---|
| Une seule racine ; un nom de 1 à 80 unités de code UTF-16 après suppression des espaces de début et de fin ; au plus 65536 octets UTF-8 pour l’ensemble du XML. |
| Les deux sont obligatoires, chacun avec les six couleurs ci-dessous. |
| Surcharges v2 facultatives. Les rôles omis suivent les valeurs par défaut de DDS pour ce mode. |
| Surcharges numériques v2 facultatives. |
Version 1 | Les deux palettes uniquement. Les fichiers v1 existants restent pris en charge ; l’exportateur du SDK produit du v2. |
Clé de palette obligatoire | Utilisation |
|---|---|
| Arrière-plan extérieur de l’espace de travail |
| Navigation dans le projet |
| Panneaux et commandes d’outils |
| Espace de travail principal et paramètres |
| Texte principal |
| Texte secondaire |
Clés de rôle facultatives (28) | Utilisation |
|---|---|
| Arrière-plan, texte et texte indicatif de la recherche partagée |
| Champ de compatibilité ; les champs de recherche partagés actuels n’ont pas de bordure |
| Lignes et texte sélectionnés |
| Onglets de l’éditeur |
| Barres d’outils, limites des panneaux et fenêtres contextuelles |
| Contour de focus clavier |
| Couleurs d’état et arrière-plan de la boule IA |
| Arrière-plans des suggestions et des détails |
| Texte des suggestions, des détails et texte secondaire |
| Suggestion sélectionnée au clavier |
| Suggestion survolée avec le pointeur |
| Arrière-plan du canevas du visualiseur GDS |
HintsBox est la fonctionnalité partagée de suggestion de code. Retrouvez ses couleurs dans Personnalisé → Couleurs et formes détaillées → HintsBox et l’arrière-plan GDS dans Affichage. Modifiez ensemble les trois couleurs de recherche pour obtenir un contraste lisible. Ce fragment appartient à un thème v2 ; conservez les deux palettes complètes :
Fragment XML v2
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
Métrique | Valeurs autorisées | Valeur par défaut actuelle de DDS |
|---|---|---|
| Entier de 0 à 24 | 14 |
| Entier de 0 à 16 | 6 |
| Entier de 0 à 24 | 16 |
| Nombre de 0,6 à 1 | 0,72 |
Écrivez les métriques sous la forme <number key="popoverOpacity" value="0.9"/> dans <metrics> sans unité. Les rayons sont exprimés en pixels. Le SDK laisse les métriques omises absentes ; la version installée de DDS fournit ses valeurs par défaut. Définissez des valeurs explicites pour une apparence cohérente. Hello Ocean définit délibérément 16, 8, 12 et 0,9. Les paramètres de transparence réduite et de couleurs forcées peuvent modifier le rendu final.
Chaque couleur doit être un #RRGGBB à six chiffres ; l’alpha, les noms CSS, les variables, les URL et les styles sont rejetés. Les clés ou modes en double, les éléments/attributs inconnus, les espaces de noms, les DTD, les entités et les instructions de traitement sont rejetés. Les déclarations et commentaires XML sont autorisés. Si l’import échoue, vérifiez la taille du fichier, la version, les deux palettes complètes et les valeurs prises en charge, puis réessayez avec votre sauvegarde inchangée. Les thèmes provenant d’autres éditeurs doivent être convertis dans ce format DDS.
6. Exécuter un espace de travail dans votre environnement
Exécutez l’hôte, le SDK, les plugins et les outils dans votre propre environnement WSL, conteneur ou serveur. Les fichiers du projet restent sous la racine que vous choisissez. Le client SDK autonome les lit et les modifie via la connexion ; il reçoit les métadonnées des plugins et les résultats des commandes pendant que leur code s’exécute dans votre environnement.
Dans le projet SDK créé plus haut, enregistrez cet utilitaire sous copy-workspace-example.mjs. Il copie le serveur modifiable, le plugin, l’outil et le projet d’exemple tout en préservant l’organisation des fichiers de licence de l’exemple.
copy-workspace-example.mjs
import { cp, copyFile, mkdir } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await mkdir('./user-host/examples', {recursive: true});
await cp(path.join(sdkRoot, 'examples/user-workspace'), './user-host/examples/user-workspace', {
recursive: true, force: false, errorOnExist: true,
});
await copyFile(path.join(sdkRoot, 'LICENSE'), './user-host/LICENSE');
console.log('Created user-host');
node copy-workspace-example.mjs
Le projet d’exemple est user-host/examples/user-workspace/project. Démarrez le serveur dans cet environnement avec un jeton généré explicite :
WSL / Linux / conteneur
export DDS_WORKSPACE_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
node user-host/examples/user-workspace/server.mjs
PowerShell
$env:DDS_WORKSPACE_TOKEN = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
node user-host/examples/user-workspace/server.mjs
Le serveur affiche Workspace server: http://127.0.0.1:4777/dds/workspace/v1 ainsi qu’un identifiant d’espace de travail et une génération. Dans le terminal du client, définissez DDS_WORKSPACE_TOKEN avec le jeton généré. Il s’agit d’un identifiant d’opérateur, distinct d’un jeton DDS Account. Arrêtez le serveur d’exemple avec Ctrl+C.
Depuis un autre terminal du même projet, définissez DDS_WORKSPACE_TOKEN avec le même secret, puis exécutez le client de développement :
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
Le client répertorie les fichiers d’exemple et exécute Inspecter le fichier du projet pour design.sv. Le résultat JSON comprend tool: "module-counter" et modules: 1, produits par un véritable processus enfant. Ajoutez --edit à la commande du client uniquement si vous souhaitez que l’exemple ajoute une note au fichier d’exemple.
Pour utiliser votre propre projet, passez son répertoire absolu comme dernier argument à server.mjs. Conservez le serveur, les modules de plugin et les outils installés dans ce même environnement utilisateur. server.mjs importe explicitement le plugin et associe son backend nommé à un exécutable et à des arguments fixes :
Association du backend dans server.mjs
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
Remplacez cette association par votre outil installé approuvé ou par un backend personnalisé. ctx.workspace.readFile et writeFile utilisent des chemins relatifs à la racine sélectionnée ; ctx.backends.invoke("module-counter", input, {signal}) appelle uniquement un nom de backend configuré. L’adaptateur de processus envoie du JSON borné sur stdin et attend du JSON sur stdout. Il n’utilise aucune commande shell fournie par la requête et n’hérite d’aucune variable d’environnement de l’hôte.
Pour un serveur distant, utilisez votre propre point de terminaison HTTPS authentifié ou un tunnel privé aboutissant à la boucle locale. Configurez le mappage des ports du conteneur ou TLS dans votre environnement. L’exemple écoute sur la boucle locale par défaut ; modifier son adresse d’écoute n’ajoute pas TLS. Les plugins et outils de confiance s’exécutent avec les droits système du processus hôte.
Consultez l’exemple d’espace de travail utilisateur et le protocole de l’espace de travail pour la configuration du serveur, les origines, les révisions de fichiers, l’annulation et les résultats bornés.
Fonctionnalités de langage
Le SDK 0.7.0 fournit la complétion, le survol, la définition, les références et les symboles de document non hiérarchiques. Déclarez chaque fonctionnalité dans les capacités du manifeste v2, ainsi que les autorisations document.read et language.provide. L’hôte doit accorder explicitement les deux autorisations. Enregistrez cet exemple complet de survol sous language-demo.mjs dans le projet créé plus haut :
language-demo.mjs
import { definePlugin, createLanguageResult, createPluginHost } from '@altifigence/dds-plugin-sdk';
const plugin = definePlugin({
manifestVersion: 2,
id: 'hello-hover', name: 'Hello Hover', publisher: 'example', version: '1.0.0',
protocolVersion: 1, entry: './language-demo.mjs', runtime: 'ui',
capabilities: ['hover'],
permissions: ['document.read', 'language.provide'],
supportedHosts: ['test-host'], license: 'Apache-2.0',
source: {visibility: 'open', licenseFile: 'LICENSE'},
}, context => context.registerLanguageProvider('hover', {languages: ['dds-demo']}, {
provide(request, {signal}) {
signal.throwIfAborted();
return createLanguageResult(request, {text: 'A local LED signal.'});
},
}));
const host = createPluginHost({grants: ['document.read', 'language.provide']});
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///demo.dds', languageId: 'dds-demo',
modelVersion: 1, workspaceRevision: 'demo-1', text: 'led',
});
const result = await host.requestLanguage('hover', {position: {line: 0, character: 1}});
console.log(result.data.text);
} finally {
host.dispose();
}
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs
La première commande affiche A local LED signal. Le deuxième exemple fourni vérifie les cinq fonctionnalités avec un petit langage pédagogique utilisant let name = value ; le fournisseur propre à l’exemple implémente ce langage pédagogique.
Fonctionnalité | Entrée de la requête | Données du résultat |
|---|---|---|
|
| Jusqu’à 500 éléments au format |
|
|
|
|
| Jusqu’à 500 emplacements |
|
| Jusqu’à 500 emplacements |
|
| Jusqu’à 500 symboles |
Les positions utilisent des lignes numérotées à partir de zéro et des décalages UTF-16. L’insertion de complétion est du texte littéral ; les chaînes de survol et de détail sont du texte brut. Un hôte doit vérifier les fichiers et plages cibles avant de suivre un emplacement. Le résultat conserve l’identité de la requête, du projet/de la session et de la version du document. Modifier l’instantané, annuler, dépasser le délai, désinscrire ou libérer les ressources termine les requêtes en attente et écarte les résultats tardifs.
Ces API fonctionnent dans l’hôte autonome de confiance du SDK. Utilisez un hôte SDK 0.3.0 ou ultérieur pour ces fonctionnalités de langage et configurez explicitement tout processus LSP avec la passerelle dédiée. Consultez Fonctionnalités de langage pour les sélecteurs, les limites et le comportement du cycle de vie.
Sessions de modification de projet
Importez createWorkspaceProject et applyTextEdits depuis @altifigence/dds-plugin-sdk/workspace-client. Une fois que votre hôte a connecté un createWorkspaceClient et examiné l’identité de l’espace de travail, la notice et les accès, appelez createWorkspaceProject(client). Le projet conserve la liaison de connexion exacte. Une reconnexion nécessite un projet nouvellement examiné, même si le même identifiant et la même génération d’espace de travail sont renvoyés.
API | Comportement |
|---|---|
| Répertorier un répertoire sous la racine de l’espace de travail sélectionné. |
| Lire un fichier et conserver son contenu immuable et sa révision dans une session de modification. |
| Créer uniquement si le fichier est absent, puis renvoyer une session. |
| Lire le dernier |
| Enregistrer uniquement si la révision du serveur correspond toujours à la révision conservée. |
| Appliquer les modifications |
| Lire explicitement le contenu et la révision les plus récents après un conflit ou une écriture incertaine. |
| Annuler les opérations appartenant au projet ; libérer ses ressources laisse connecté le client détenu par l’appelant. |
Exécutez l’exemple HTTP complet dans le package installé. Il crée son propre espace de travail d’exemple temporaire, teste les modifications, une deuxième session en conflit, le rechargement explicite, Unicode et la reconnexion, puis ferme son serveur et supprime ce répertoire temporaire :
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs
Sortie attendue : Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. Le code source de l’exemple présente la configuration complète du serveur/client et le nettoyage.
Les options acceptent signal et timeoutMs. Une écriture qui échoue après une tentative laisse needs-reload ; conservez séparément tout brouillon d’interface non enregistré et rechargez explicitement avant un nouvel enregistrement. Le SDK ne fusionne ni ne relance automatiquement. Un délai dépassé, une annulation ou une réponse perdue peuvent survenir après que le serveur a validé l’écriture ; annuler une requête laisse en place les modifications déjà validées. Chaque session autorise un seul enregistrement ou rechargement en attente.
Les modifications de texte utilisent l’instantané original, des lignes numérotées à partir de zéro et des décalages UTF-16. Les chevauchements, les paires de substituts scindées et les plages invalides sont rejetés avant l’enregistrement. Les projets autorisent au plus 64 sessions ouvertes ou en cours d’ouverture et 500 modifications par enregistrement. Ces utilitaires utilisent le protocole d’espace de travail v1 inchangé, y compris les serveurs SDK 0.2.x, et conservent les restrictions de racine, de chemins protégés et de lecture seule. Consultez Projets d’espace de travail pour le cycle de vie et les limites de taille.
Référence de l’API
Importez les API de plugin depuis @altifigence/dds-plugin-sdk. Le package inclut des déclarations TypeScript pour les mêmes exports.
API | Utilisation |
|---|---|
| Valider le manifeste et déclarer la fonction d’activation. |
| Inscrire |
| Construire un résultat validé à partir de l’identité de la requête. |
| Inscrire un fournisseur de langage et construire un résultat avec une identité de requête validée. |
| Valider la version du manifeste, l’identité, les autorisations, les hôtes pris en charge et le module d’entrée. |
| Valider l’URI, le langage, la version du modèle, la révision de l’espace de travail et le texte. |
| Valider le protocole, la requête, la portée, l’identité du document et les champs de diagnostic. |
| Lire les erreurs typées, les limites de ressources et la version du protocole. |
Importez l’hôte de développement depuis @altifigence/dds-plugin-sdk/testing :
API de l’hôte de test | Utilisation |
|---|---|
| Créer un hôte local. Les deux options sont facultatives ; les droits par défaut autorisent la lecture du document et les diagnostics. |
| Activer le plugin et renvoyer une activation dont les ressources peuvent être libérées. |
| Définir le document actuel. Augmenter |
| Demander des diagnostics à un fournisseur correspondant ; les deux options sont facultatives. |
| Demander une fonctionnalité de langage déclarée avec des droits explicites document.read et language.provide. |
| Supprimer les inscriptions et annuler les opérations en attente ; libérer les ressources de l’hôte à la fin du test. |
Les requêtes comprennent requestId, le scope du projet/de la session et un instantané avec uri, languageId, modelVersion, workspaceRevision et text. Utilisez createDiagnosticsResult pour préserver cette identité. Les résultats contiennent un tableau diagnostics et omettent le texte source.
Les erreurs exposent un code, notamment invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable et budget_exceeded. Le délai de requête par défaut est de 5 secondes ; les délais acceptés vont de 1 à 30000 ms. Un document est limité à 262144 octets UTF-8 et un résultat à 500 diagnostics. Consultez LIMITS pour les limites complètes.
Le SDK 1.0.0 fournit également des modules distincts. Les imports d’espace de travail et d’empaquetage réservés à Node appartiennent à l’environnement utilisateur :
Import | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Empaqueter et publier votre plugin
Commencez avec le plugin publiable inclus. Enregistrez cet utilitaire dans votre projet SDK pour copier ses fichiers dans un nouveau répertoire my-plugin.
copy-publishable-example.mjs
import { cp } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await cp(path.join(sdkRoot, 'examples/publishable-plugin'), './my-plugin', {
recursive: true,
force: false,
errorOnExist: true,
});
console.log('Created my-plugin');
node copy-publishable-example.mjs
Modifiez plugin.json, plugin.mjs, disclosure.json et la licence pour décrire votre propre plugin. La déclaration doit correspondre à l’éditeur, à l’identifiant du plugin, à la version, à la licence et à la visibilité du code source du manifeste. Répertoriez uniquement les fichiers que vous comptez distribuer dans dds-package.json :
dds-package.json
{
"schemaVersion": 1,
"files": [
"plugin.json",
"plugin.mjs",
"disclosure.json",
"LICENSE",
"NOTICE"
]
}
Validez et empaquetez l’exemple :
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist
Avec les métadonnées inchangées de l’exemple, pack crée dist/example-hello-publisher-1.0.0.tgz et dist/example-hello-publisher-1.0.0.tgz.release.json. Le JSON de publication contient le SHA-256 final de l’archive, les empreintes du manifeste/de la déclaration et l’inventaire des fichiers. Inspectez ces fichiers avant toute distribution.
Seuls les fichiers de la liste autorisée, dds-package.json et les métadonnées npm générées entrent dans l’archive. La validation inspecte les données du package et l’empaquetage crée l’archive locale pour le canal de distribution de votre choix. La CLI rejette les configurations privées, les fichiers de clés et les chemins liés ; examinez le contenu des fichiers choisis avant de les partager.
Canal | Éléments à fournir |
|---|---|
Version publique sur GitHub | Une archive versionnée, son JSON de publication externe, la licence et tout accès requis au code source. |
Registre privé ou canal de téléchargement | Les mêmes fichiers versionnés, l’autorisation du public destinataire et les conditions réelles du plugin. |
Le manifeste v2 déclare runtime, les autorisations demandées et source: {visibility, licenseFile, repository?}. Définissez la visibilité sur open ou closed et incluez le fichier de licence réel. Le code que vous possédez peut utiliser des conditions open source ou propriétaires ; les notices applicables du SDK et des dépendances restent requises. Les destinataires reçoivent le JavaScript exécutable avec les métadonnées déclarées de visibilité du code source et de licence.
Suivez Publication et Licences pour les champs de déclaration et les exigences de distribution. Distribuez l’archive produite par le SDK par le canal de publication public ou de téléchargement privé de votre choix.
La CLI 1.2.1 inscrit >=1.0.0 <2.0.0 dans les nouveaux packages de plugin. Les archives historiques 0.3–0.13 et les archives exactement en 1.0.0-rc.1 conservent leurs dépendances homologues originales. Validez et réempaquetez une nouvelle version du plugin pour une installation stable ; l’éditeur met explicitement à jour la plage de versions homologues et les métadonnées de publication lors du réempaquetage.
Vérifier un plugin téléchargé
Le SDK 1.2.1 fournit dds-plugin verify pour les métadonnées exactes de plugins publiés en 0.3.x–0.13.x, RC1 et dans la version stable actuelle. Conservez ensemble les fichiers .tgz et .tgz.release.json. La vérification préserve la dépendance homologue originale. Vérifiez le package créé plus haut :
Vérifier l’exemple empaqueté
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
La commande vérifie la structure gzip/tar bornée, les listes exactes de fichiers autorisés, l’empreinte de chaque fichier, le manifeste, la déclaration, la licence et les métadonnées npm générées. Elle rejette les liens, les chemins dangereux ou en double, les fichiers supplémentaires et les hooks/dépendances npm. Elle lit et valide l’archive locale sur place dans une opération portant sur les données. En cas de réussite, elle affiche un reçu JSON ; en cas de rejet, elle se termine avec le code 1.
Pour les téléchargements renommés, utilisez --metadata avec le JSON de publication correspondant. Obtenez indépendamment le SHA-256 attendu via un canal de publication de confiance et passez-le avec --sha256 pour fixer les octets sélectionnés. L’API Node expose les mêmes options :
verify-release.mjs
import { verifyPluginArchive } from '@altifigence/dds-plugin-sdk/publishing';
const receipt = await verifyPluginArchive(process.argv[2], {
metadataPath: process.argv[3],
expectedSha256: process.argv[4],
});
console.log(receipt.pluginId, receipt.pluginVersion, receipt.artifact.sha256);
Exécutez verify-release.mjs avec, comme trois arguments, le chemin de l’archive, celui des métadonnées et l’empreinte de 64 caractères minuscules obtenue indépendamment. checksumPinned vaut true uniquement lorsque l’empreinte fournie correspond. Les limites sont de 12 MiB d’entrée compressée, 10 MiB de contenu de fichiers, 4 MiB par fichier, 256 fichiers et 256 KiB de métadonnées externes.
Le vérificateur compare les octets de l’archive à leurs métadonnées associées. Obtenez l’empreinte attendue indépendamment auprès d’un canal de publication de confiance pour lier la comparaison à la version choisie. L’hôte valide séparément l’éditeur, examine le contenu du package et la compatibilité de l’installation DDS, puis accorde les autorisations avant l’exécution. Un reçu décrit les octets lus pendant cet appel ; revérifiez les octets réels si le fichier peut changer avant son utilisation. Les archives de plugins 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x existantes restent vérifiables lorsqu’elles respectent la politique de fichiers renforcée ; leur installation sur 1.0 exige toujours la validation de l’éditeur et un réempaquetage. Supprimez les fichiers nouvellement exclus et publiez une nouvelle version du plugin si nécessaire. Ce vérificateur concerne les packages de plugins DDS ; les archives npm du SDK utilisent le SHA-256 de leur publication.
Consultez Vérification des archives et l’exemple complet d’empaquetage/vérification/altération.
Autorisations, licences et utilisation des données
Les autorisations demandées dans un manifeste sont distinctes des droits accordés par l’hôte qui permettent les opérations. Présentez aux utilisateurs l’identité du plugin, sa version, sa licence réelle, la portée de l’espace de travail et les autorisations demandées avant de l’activer. Expliquez tout opérateur de backend, les données envoyées, leur finalité, leur conservation et la notice de confidentialité avant de connecter ce backend.
Enregistrement | Signification |
|---|---|
| Une décision d’accès de l’hôte pour le package, l’espace de travail et les autorisations exacts. |
| Un utilisateur a confirmé avoir pris connaissance d’une notice d’information. |
| Un utilisateur a choisi d’accepter ou non les conditions réelles de l’éditeur du plugin. |
| Un choix distinct lorsqu’un traitement facultatif repose sur le consentement. |
Une approbation d’espace de travail SDK enregistre une décision d’accès technique. Enregistrez l’acceptation des conditions du plugin et le consentement facultatif relatif aux données personnelles comme des choix distincts. Le SDK est sous licence Apache-2.0 ; consultez sa licence et ses notices pour les conditions applicables au SDK.
Les développeurs d’hôtes peuvent conserver une notice versionnée avec les utilitaires asynchrones portables. Par exemple, enregistrez ceci sous notice.mjs et exécutez node notice.mjs :
notice.mjs
import { createNotice, parseNotice } from '@altifigence/dds-plugin-sdk/consent';
const notice = await createNotice({
id: 'greet-data-use',
version: '1.0.0',
locale: 'en',
purpose: 'Explain the greet command',
text: 'The greet command uses the name you enter to return a greeting. It does not read project files or contact another backend.',
});
await parseNotice(notice);
console.log(notice.text);
console.log(`Notice text SHA-256: ${notice.contentSha256}`);
createPermissionGrant lie un sous-ensemble d’autorisations demandées au manifeste v2, aux empreintes de l’artefact et du manifeste, à la génération de l’espace de travail, à l’identité de l’hôte, à la notice et à l’expiration. isPermissionGranted évalue les identités actuelles et les événements de révocation fournis par l’hôte. revokeConsentReceipt crée un événement distinct ; l’hôte doit ensuite arrêter les futurs appels autorisés.
Ces utilitaires valident des enregistrements locaux. L’hôte fournit le choix réel de l’utilisateur, l’identité, le stockage et l’application des règles. Consultez Autorisations et consentement pour les champs exacts et l’exemple interactif d’autorisations pour une démonstration explicite d’autorisation/refus/révocation. L’hôte conserve les accords avec les éditeurs et leurs enregistrements dans le flux applicatif de son choix.
Sources, versions et contributions
Le dépôt officiel du SDK contient les sources, les schémas, les exemples et les tests de contrat. Pour exécuter l’exemple publié et les tests du SDK à partir des sources :
git clone --branch v1.2.1 --depth 1 https://github.com/Altifigence/dds-plugin-sdk.git
cd dds-plugin-sdk
npm ci
npm test
npm run example
npm run example:language
npm run example:project
npm run example:verify
npm run example:jobs
npm run example:observe
npm run benchmark:files
npm run example:artifacts
npm run benchmark:artifacts
npm run example:durable-jobs
npm run example:stored-artifacts
Signalez les bugs du SDK via GitHub Issues, avec la version du SDK et une reproduction minimale. Le SDK est sous licence Apache-2.0 ; consultez la licence et les notices du dépôt. Utilisez la page des versions pour les archives versionnées et les notes de version.
Ce dépôt est le SDK public de développement. Sa publication contient les fichiers SDK déclarés, les schémas, les exemples et les notices dans son périmètre public. Les contrôles du package imposent l’inventaire exact des fichiers publiés et rejettent les motifs connus de secrets et de chemins privés. Examinez le contenu réel de la publication pour repérer les informations sensibles en complément de ces contrôles de motifs.
Mises à jour de sécurité et limites de l’hôte
Mettez à jour votre serveur d’espace de travail et votre client SDK vers 0.3.2 ou une version ultérieure. Installez la mise à jour du serveur pour activer ses contrôles de fichiers et limites de requête améliorés. Redémarrez l’hôte mis à niveau, examinez sa nouvelle génération et obtenez à nouveau une approbation avant d’utiliser l’espace de travail.
L’hôte d’espace de travail Node rejette les liens physiques qui pourraient servir d’alias à des fichiers protégés ou à des fichiers hors de la racine sélectionnée. Copiez un fichier de projet volontairement partagé dans un fichier ordinaire à lien unique. Les stockages d’identifiants tels que .netrc, _netrc, .git-credentials, .gnupg, .kube et .docker, les noms supplémentaires de clés SSH et les alias de périphériques Windows sont également bloqués. L’empaquetage et la vérification des téléchargements appliquent la politique correspondante sur les noms d’identifiants.
Ressource serveur | Limite |
|---|---|
Corps entrants simultanés | 16 ; les téléversements supplémentaires reçoivent HTTP 429 avant leur traitement |
Requêtes en cours d’exécution | 64 ; l’annulation utilise une voie de traitement distincte |
Connexions / requêtes par socket | 128 / 128 |
Requête et réponse / contenu du fichier | 1600000 / 262144 octets UTF-8 |
Le client annule les réponses rejetées non lues et les flux bloqués lors d’un dépassement de délai ou d’une annulation. Un délai dépassé après le début d’une écriture peut laisser son résultat incertain : relisez le fichier avant de réessayer. Examinez les fichiers pour repérer les secrets en complément des exclusions explicites de chemins et exécutez les plugins de confiance avec des droits système du processus hôte choisis délibérément. Utilisez le guide de mise à niveau de sécurité et les limites de l’espace de travail lors du déploiement d’un hôte.
Outils de développement
Après l’installation de SDK 1.2.1 ci-dessus, créez un projet distinct de plugin de commande. Choisissez une nouvelle destination pour les fichiers générés ; lancez explicitement l’installation des dépendances et l’exécution du plugin après la génération du squelette. Le squelette comprend une commande, un test, un manifeste, une déclaration, une dépendance SDK épinglée et les fichiers LICENSE/NOTICE Apache-2.0.
npx --no-install dds-plugin init ../my-command-plugin --id my-command-plugin --publisher example
cd ../my-command-plugin
npm install --ignore-scripts
npm run doctor
npm test
npx --no-install dds-plugin dev . --trust-local-code --command greet --input '{"name":"Ada"}'
Doctor lit les métadonnées et vérifie Node, la résolution du SDK, le manifeste, la licence, la déclaration et les fichiers de la liste autorisée sans importer le plugin. Les erreurs produisent un statut de sortie 1 ; les valeurs d’exemple pour l’éditeur/le support sont des avertissements. Remplacez ces valeurs et examinez les licences avant toute distribution.
npx --no-install dds-plugin doctor . --json
npx --no-install dds-plugin dev . --trust-local-code --watch
npx --no-install dds-plugin dev . --trust-local-code --job --command greet --input '{"name":"Ada"}'
npm run pack:plugin
Dev exige --trust-local-code. Il exécute les imports/l’activation locaux de confiance dans un processus enfant et surveille uniquement les fichiers de la liste autorisée ainsi que dds-package.json. Chaque exécution a une échéance et une limite de 256 KiB pour stdout/stderr. Ctrl+C arrête la surveillance et nettoie son arborescence de processus. Le processus enfant de confiance hérite de votre environnement et s’exécute avec les droits système de votre processus. L’hôte de test par défaut accorde la lecture de documents et la publication de diagnostics. Configurez un hôte d’espace de travail distinct avec des droits explicites d’espace de travail/backend pour ces intégrations.
Utilisez --job pour afficher la progression/les journaux des tâches ; utilisez --timeout-ms pour définir jusqu’à 30 secondes pour les commandes ordinaires ou 30 minutes pour les tâches. Les API Node sont initPlugin, doctorPlugin et runPluginDev dans /devtools. Consultez le guide des outils de développement pour le comportement de surveillance et les limites de nettoyage.
Tâches de commande de longue durée
Activez jobs: true sur un hôte/serveur SDK 0.4.0 pour exécuter des commandes au-delà de l’échéance des requêtes ordinaires. Les tâches sont désactivées par défaut. Essayez l’exemple HTTP local complet, qui signale la progression, un journal de backend nommé et un fichier de résultat fixé par empreinte :
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs
Sortie attendue : Command job: progress, backend log and pinned result file verified. Un gestionnaire de commande reçoit un job facultatif dans {signal, job}. Il fournit reportProgress, log, addArtifact et invokeBackend. Les droits workspace.read/write et backend.invoke existants restent applicables ; aucun chemin d’exécutable arbitraire n’est accepté.
Javascript
await client.connect();
if (!(await client.getJobCapabilities()).enabled) throw new Error("Jobs are unavailable");
const jobId = crypto.randomUUID(); // Save before sending.
let job = await client.startCommandJob(pluginId, "analyze", {}, artifactSha256, {jobId, timeoutMs: 300_000});
let after = 0;
for (;;) {
const page = await client.getJobEvents(jobId, after);
after = page.nextCursor;
if (page.dropped) console.log("Expired events:", page.dropped);
for (const event of page.events) console.log(event.kind, event.data);
job = await client.getJob(jobId);
if (job.state !== "running" && !page.hasMore && after >= job.lastSequence) break;
await new Promise(resolve => setTimeout(resolve, 250));
}
if (job.state === "succeeded") {
const file = await client.readJobArtifact(jobId, "report");
console.log(file.content);
}
L’extrait d’interrogation suppose un client connecté et une commande analyze configurée qui inscrit report. Conservez l’identifiant de tâche avant de démarrer. Se déconnecter ou interrompre une requête d’interrogation n’annule pas l’exécution ; reconnectez-vous à la même génération et interrogez/annulez explicitement. Les relances de démarrage avec le même identifiant et la même entrée réutilisent la tâche conservée ; les arguments modifiés provoquent un conflit. Un redémarrage de l’hôte perd les enregistrements en mémoire. Activez le stockage durable distinct de 0.8 ci-dessous pour récupérer les métadonnées validées après un redémarrage.
Les états sont running, succeeded, failed, cancelled et timed_out. Les sorties tardives sont écartées après l’annulation ; les effets de bord ne sont pas annulés. Les fournisseurs non terminés conservent leurs emplacements. Il y a au plus 4 tâches simultanées, 32 enregistrements conservés, 32 opérations imbriquées par tâche, 256 événements/64 KiB par tâche, 64 événements par page et 16 artefacts. La durée d’exécution par défaut est de 5 minutes et est plafonnée à 30 minutes. Les enregistrements terminaux stabilisés expirent 15 minutes après leur dernier événement.
Les fichiers de résultats texte sont relatifs à l’espace de travail et en UTF-8, jusqu’à 256 KiB. L’hôte les lit avec le droit existant, enregistre leur SHA-256 et rejette les lectures ultérieures si les octets ont changé. Pour les sorties de simulation binaires ou plus volumineuses, utilisez l’API de résultats binaires. Des artefacts partiels peuvent subsister après une annulation ; vérifiez l’état terminal de la tâche pour confirmer sa réussite. Les anciens clients 0.3 continuent d’utiliser les méthodes v1 existantes ; les tâches autonomes du SDK nécessitent 0.4 des deux côtés. Consultez Tâches pour les contrats et limites exacts.
Observer les fichiers de l’espace de travail
project.watchFiles() échantillonne de 1 à 16 chemins de fichiers relatifs explicites. Le SDK 1.0.0 utilise des requêtes de révision seule sur les hôtes compatibles et les lectures bornées existantes sur les hôtes plus anciens. L’exemple suppose un client connecté et approuvé par l’hôte. Modifiez design.sv avec un éditeur externe pour terminer la boucle ; l’instantané de modification conservé reste inchangé.
Javascript
import {createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
const project = createWorkspaceProject(client);
const edit = await project.openFile('design.sv');
const original = edit.snapshot;
try {
for await (const change of project.watchFiles(['design.sv'], {intervalMs: 1000})) {
console.log(change.kind, change.path, change.previousRevision, change.revision);
if (change.kind !== 'initial') break;
}
console.log(edit.snapshot === original);
} finally { project.dispose(); }
Les événements sont immuables : {kind, path, previousRevision, revision}. Le premier échantillon émet initial ; les changements suivants émettent created, changed ou deleted. Les fichiers absents ont une révision null. includeInitial: false enregistre la référence silencieusement, et les révisions égales ne produisent aucun événement. Seul not_found signifie une suppression ; les erreurs d’autorisation, de chemin protégé, de taille et de transport mettent fin à l’observation.
Conservez séparément le texte d’interface non enregistré et choisissez des actions explicites de rechargement, de fusion et d’enregistrement des brouillons. Un enregistrement vérifie la révision conservée et peut signaler un conflit. L’observation échantillonne les chemins explicites un par un dans l’ordre ; les changements intermédiaires peuvent être regroupés. Utilisez les API d’observation de projet ci-dessous pour la découverte et les abonnements aux répertoires avec portée définie. Les restrictions existantes de racine, de taille de fichier et de chemin protégé s’appliquent aux serveurs en lecture seule et en écriture.
Les observateurs de fichiers et de tâches démarrent à leur premier next(), ne récupèrent aucune page en arrière-plan lorsque le consommateur est en pause et partagent un maximum de huit observateurs actifs par client. Un seul next() peut être en attente ; une lecture simultanée échoue avec conflict. Break ou return() arrête les lectures en attente ; la libération du projet arrête ses observateurs de fichiers, et la déconnexion/reconnexion/libération invalide tous les anciens observateurs. AbortSignal met fin à l’observation avec cancelled ; les réponses tardives ne peuvent produire aucun résultat.
intervalMs va de 250 à 60000 ms (1000 par défaut), appliqué entre les parcours des fichiers ou les lectures de tâches inactives. requestTimeoutMs va de 1 à 30000 ms par requête et utilise par défaut l’échéance du client. Le timeoutMs total va de 1 à 1800000 ms à partir du premier next(), pauses du consommateur comprises. Les fichiers n’ont pas de délai total par défaut ; celui des tâches est de 30 minutes. Les échéances signalent budget_exceeded et libèrent l’emplacement. Ces limites sont exportées sous WORKSPACE_OBSERVATION_LIMITS.
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs
Sortie attendue : Workspace observation: file changes, retained draft and resumed job verified. L’exemple complet crée son propre espace de travail temporaire et vérifie les modifications de fichiers, les conflits de brouillon et la reprise explicite des tâches. Consultez Observation pour toutes les options et les règles de durée de vie.
Observer et reprendre les tâches
client.watchJob() suit une tâche existante avec jobs.events/get ; waitForJob() renvoie son instantané terminal. L’extrait suppose un client connecté, un jobId démarré explicitement et un savedCursor (ou undefined). Vérifiez getJobCapabilities() avant de démarrer une tâche. L’observation ne démarre, ne relance et n’annule jamais la commande.
Javascript
let after = savedCursor ?? 0;
for await (const update of client.watchJob(jobId, {after, intervalMs: 1000})) {
if (update.dropped) console.log('Expired events:', update.dropped);
for (const event of update.events) console.log(event.kind, event.data);
console.log(update.snapshot.state, update.snapshot.progress);
after = update.nextCursor;
}
const result = await client.waitForJob(jobId, {after, timeoutMs: 120000});
if (result.state === 'succeeded') console.log(result.result);
else console.log(result.state, result.error.code);
Chaque mise à jour figée contient snapshot, events, after, nextCursor, dropped et hasMore. Traitez au plus 64 événements par page et enregistrez nextCursor après son traitement, avec l’identifiant de tâche et l’identité de l’espace de travail. dropped signale l’historique expiré. Un instantané peut être plus récent que sa page d’événements ; poursuivez la lecture des instantanés terminaux tant que hasMore vaut true. L’itérateur se termine après la dernière page. waitForJob() consomme les mêmes pages et renvoie succeeded, failed, cancelled ou timed_out ; inspectez state au lieu de considérer toute promesse résolue comme une réussite.
Arrêter un itérateur ou dépasser un délai arrête uniquement l’observation. La commande du serveur continue jusqu’à sa fin ou jusqu’à un appel explicite à cancelJob(). Après une reconnexion approuvée par l’hôte, vérifiez le même identifiant et la même génération d’espace de travail, puis créez un nouvel observateur avec l’identifiant de tâche et le curseur enregistrés. Les anciens observateurs sont invalides même si l’identité est inchangée. Les tâches absentes/expirées et les échecs de transport sont signalés sans nouvelle soumission ; les tâches en mémoire ne survivent pas au redémarrage de l’hôte. La récupération durable utilise recoverJob() avec une nouvelle connexion ; les observateurs actifs ne reprennent pas entre générations.
Les contrats hello v1 et de tâches existants restent inchangés. L’observation de fichiers utilise un repli sur les hôtes 0.3.2/0.4/0.5 ; l’observation de tâches nécessite un hôte activé 0.4 ou ultérieur. Une capacité de tâches désactivée ou non prise en charge renvoie une erreur et préserve le choix de l’appelant concernant l’exécution des commandes sur l’hôte autonome du SDK. Consultez Observation et Compatibilité.
Révisions de fichiers et lectures conditionnelles
Le SDK 0.6.0 ajoute getFileCapabilities(), getFileRevision(path) et readFileIfChanged(path, knownRevision) aux clients connectés. Les lectures de révision renvoient {path, revision} sans contenu. Une lecture conditionnelle concordante renvoie {path, revision, notModified: true} ; un contenu modifié renvoie notModified: false et content. Passez knownRevision: null pour le contenu actuel. Les fichiers absents sont rejetés avec not_found.
Javascript
let cached = await client.readFile('design.sv');
const current = await client.readFileIfChanged(cached.path, cached.revision);
if (!current.notModified) cached = current;
console.log(cached.content);
const metadata = await client.getFileRevision('design.sv');
console.log(metadata.revision);
Utilisez un client déjà connecté et autorisé. Conservez les brouillons non enregistrés séparément de ce cache. Les lectures conditionnelles calculent l’empreinte et renvoient un instantané de fichier ; une lecture ultérieure peut encore observer un autre changement. Enregistrez avec la révision appartenant au contenu renvoyé. Ces appels ne mettent pas à jour les instantanés des sessions de modification et ne fusionnent pas les brouillons. Une réponse inchangée n’a pas de champ content ; un fichier vide modifié a content: “”.
L’observation des fichiers utilise automatiquement les lectures de révision seule lorsqu’elles sont prises en charge. Les méthodes facultatives fs.capabilities, fs.revision et fs.readIfChanged préservent le hello v1 strict et les méthodes de fichiers originales. Les hôtes d’espace de travail SDK connus antérieurs à 0.6 utilisent fs.read sans sondage. Les autres hôtes doivent répondre à la découverte ou renvoyer une erreur unsupported correctement corrélée. Chaque capacité false sélectionne son propre repli de lecture complète bornée ; la réponse de l’ancien serveur transfère toujours le contenu entier.
Les capacités sont mises en cache uniquement pour la connexion actuelle et réinitialisées lors d’une reconnexion ou d’une révocation. Les réponses invalides, les discordances de chemin/révision, les autorisations, l’authentification, les échecs de transport et les délais dépassés ne déclenchent pas de repli. Les opérations annoncées qui échouent ensuite ne sont pas silencieusement dégradées. AbortSignal couvre la découverte et la lecture ; timeoutMs s’applique à chaque requête HTTP. Un changement de connexion invalide l’ancienne opération.
Le serveur effectue toujours une lecture complète du fichier avec protections et un calcul SHA-256 pour chaque échantillon. La validation UTF-8, la limite de 262144 octets et les contrôles de chemins/liens protégés restent en vigueur. Cela réduit les octets des réponses réseau tout en conservant les lectures disque protégées et le calcul d’empreinte pour chaque échantillon. Une mesure locale Node 22.23.1 sous Windows, sur 20 échantillons inchangés de 200000 octets, a renvoyé 4003974 octets pour les lectures complètes, 3867 pour les révisions (99,903 % de moins) et 4247 pour les lectures conditionnelles (99,894 % de moins). La découverte est incluse ; les en-têtes HTTP, TLS et la référence initiale hello/contenu sont exclus. Exécutez npm run benchmark:files dans une copie de travail pour reproduire le jeu de données.
Le SDK dispose désormais d’une API stable 1.x avec des contrôles fonctionnels documentés dans sa publication. Les clients 0.3.2, 0.4, 0.5 et 0.6 existants conservent leurs API originales sur les hôtes 0.7. Ces règles de compatibilité décrivent les clients et hôtes autonomes du SDK. Consultez Révisions de fichiers pour le contrat complet et les règles de migration.
Résultats de tâches volumineux et binaires
Le SDK 0.7.0 ajoute une extension facultative de fichiers de résultat binaires. Une commande de confiance inscrit un fichier d’espace de travail existant ; l’hôte enregistre son SHA-256 et sa longueur. Les clients lisent au plus 64 KiB par bloc, et le téléchargeur Node reprend un fichier partiel et vérifie la sortie complète. Le fichier enregistré est limité à 1 GiB ; les API existantes de fichiers UTF-8 et d’artefacts texte à 256 KiB conservent leurs limites.
Activez jobs: true et binaryArtifacts: true sur l’hôte de plugin détenu par le serveur. Les deux valent false par défaut. Conservez le jeton explicite, la notice de l’opérateur, l’empreinte examinée de l’artefact de plugin et le droit workspace.read effectif. L’exemple suivant s’appuie sur la configuration d’espace de travail ci-dessus ; les espaces de travail en lecture seule peuvent inscrire des fichiers déjà générés par l’outil configuré par l’opérateur.
Javascript
const server = await createWorkspaceServer({
root, workspaceId, token, notice,
plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'],
jobs: true, binaryArtifacts: true, writable: false,
});
Inscrivez le résultat dans une commande démarrée avec startCommandJob. L’inscription fait passer le fichier existant dans SHA-256 avec un tampon de 64 KiB. La référence pointe vers ce fichier source, et non vers une copie immuable. Les chemins protégés, les traversées de répertoire, les liens et les fichiers non ordinaires sont rejetés ; les modifications ultérieures de la source échouent avec conflict.
Javascript
context.registerCommand({id: 'collect', title: 'Collect trace'}, async (_, {job}) => {
if (!job) throw new Error('Start this command as a job');
const artifact = await job.addBinaryArtifact({
id: 'trace', path: 'outputs/trace.fst', label: 'Simulation trace',
});
return {artifactId: artifact.id};
});
Utilisez un client déjà connecté et autorisé ainsi qu’un identifiant de tâche existant. La destination est un chemin absolu dans un répertoire réel existant contrôlé par l’appelant. L’utilitaire écrit destination + “.dds-part” et refuse d’écraser un fichier final existant.
Javascript
import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
destination: absoluteDownloadPath, resume: true,
signal: abortController.signal,
onProgress({receivedBytes, totalBytes}) {
console.log(receivedBytes, totalBytes);
},
});
console.log(receipt.verified, receipt.revision);
Conservez l’ensemble de la référence {jobId, scope, artifact}. Après une interruption, reconnectez-vous explicitement à la même génération d’hôte et rappelez l’utilitaire avec cette référence et resume: true. Il recalcule l’empreinte du préfixe enregistré et demande uniquement le suffixe manquant. Il vérifie le SHA-256 de chaque bloc, du flux complet reçu et du fichier intermédiaire réel avant la publication. Le reçu final verified: true confirme l’achèvement ; les rappels de progression synchrones restent non vérifiés. Les fichiers partiels corrompus nécessitent une suppression explicite ou une nouvelle destination.
listJobBinaryArtifacts(jobId) renvoie les métadonnées binaires enregistrées séparément des résultats texte existants. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) renvoie du base64 canonique avec le SHA-256 du bloc, la plage exacte et un marqueur EOF. decodeBinaryArtifactData de /artifacts renvoie des octets Uint8Array. Les consommateurs dans le navigateur doivent vérifier eux-mêmes l’empreinte du fichier entier ; les contrôles de blocs individuels ne prouvent pas que la sortie assemblée correspond à la référence.
Les résultats binaires et texte partagent 16 emplacements et un espace de noms d’identifiants par tâche. Les opérations de capture/lecture binaires sont limitées à quatre par hôte/espace de travail, et les téléchargements Node à quatre par processus. Le timeoutMs des téléchargements Node est une échéance totale, avec un maximum de 30 minutes par défaut ; requestTimeoutMs vaut 5 secondes par défaut, avec un maximum de 30 secondes. La publication nécessite la prise en charge des liens physiques, par exemple NTFS ou ext4. Utilisez une destination contrôlée par l’appelant et un processus hôte de confiance ; protégez le répertoire de destination contre les écritures simultanées hostiles avec les contrôles d’accès du système d’exploitation.
Les méthodes facultatives artifacts.capabilities, artifacts.list et artifacts.read préservent le hello v1, les instantanés de tâches et les événements existants. Les hôtes antérieurs à 0.7 signalent l’extension comme désactivée ; l’opération binaire demandée se termine avec ce résultat de capacité. L’authentification, les réponses mal formées et les erreurs de transport restent des erreurs. Une reconnexion, une révocation, l’expiration d’une tâche ou une génération d’hôte modifiée invalident les anciennes opérations. La conservation des tâches reste en mémoire pendant 15 minutes après le dernier événement de la tâche terminale. Les tâches annulées peuvent laisser une sortie partielle d’outil enregistrée ; confirmez la réussite à partir de l’état terminal de la tâche. Cela décrit les API actives/source par défaut. L’API distincte de résultats stockés ci-dessous conserve les octets entre les redémarrages.
Exécutez npm run example:artifacts pour un transfert réel de 2 MiB avec interruption, reconnexion et reprise du suffixe uniquement ; npm run benchmark:artifacts utilise 8 MiB. Une exécution locale sous Windows a transféré 8388625 octets en 129 requêtes de blocs, en reprenant un préfixe de 65536 octets et en vérifiant le SHA-256 final. Le base64 ajoute une surcharge ; les corps des réponses JSON totalisaient 11257419 octets. Les transferts utilisent une mémoire bornée et des blocs encodés. Consultez Artefacts binaires pour le contrat complet. L’exemple exerce les API autonomes de transfert du SDK.
Tâches durables, historique et relance explicite
Le SDK 0.8.0 ajoute des stockages durables facultatifs dans un répertoire détenu par l’opérateur, hors de l’espace de travail. Fournissez des chemins absolus, un identifiant d’espace de travail stable, du code de plugin examiné, le SHA-256 du package, un jeton et une notice. L’exemple active également la conservation des octets des fichiers ; omettez artifacts de jobStorage pour stocker uniquement les métadonnées de tâches. Les réponses v1 existantes et les valeurs par défaut en mémoire uniquement restent compatibles.
Javascript
import {createNodeJobStore} from '@altifigence/dds-plugin-sdk/job-storage-node';
import {createNodeArtifactStore} from '@altifigence/dds-plugin-sdk/artifact-storage-node';
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
const store = await createNodeJobStore({directory, workspaceRoot: root, workspaceId});
const artifacts = await createNodeArtifactStore({jobStore: store});
const server = await createWorkspaceServer({
root, workspaceId, token, notice, plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'], jobs: true, binaryArtifacts: true,
jobStorage: {store, artifacts},
});
Un fournisseur démarre uniquement après l’enregistrement de son intention initiale. Les points de contrôle suivants sont regroupés ; flushJobStore() attend les points de contrôle demandés, et non la fin de la commande. La récupération distingue la connexion actuelle de la portée d’exécution originale et signale live, completed, interrupted, expired, missing, corrupt ou unsupported. Une tâche interrompue ne redémarre jamais automatiquement ; son unrecordedTail est inconnu.
Javascript
const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});
L’historique filtre l’état, le statut de récupération, la commande, l’heure de début et la tentative parente. Les pages contiennent jusqu’à 32 entrées, triées par heure de début décroissante puis par identifiant de tâche. Un curseur fige l’appartenance pendant 60 secondes et doit réutiliser la même requête ; les nouvelles tâches sont exclues, les enregistrements supprimés ou non autorisés sont ignorés et l’expiration est signalée. Le redémarrage perd les curseurs. artifactCount, snapshotCount et resultAvailability décrivent des références enregistrées, pas une preuve actuelle des fichiers.
Une relance explicite exige un nouvel identifiant de tâche, une nouvelle entrée validée, le même package actuellement approuvé et une commande disponible. attemptOf relie la nouvelle exécution à son parent inchangé. Répéter les mêmes identifiant, entrée, parent et délai récupère la tentative conservée sans la réexécuter, y compris après un redémarrage. Les enregistrements absents/expirés ne peuvent pas fournir cette garantie. Une exécution acceptée peut continuer après l’annulation de la requête en attente ; interrogez le nouvel identifiant de tâche avant de décider d’une relance.
La conservation par défaut omet l’entrée brute, les corps de résultats, le texte de progression et les libellés d’artefacts ; les journaux sont expurgés. Seul un mécanisme explicite et déterministe d’expurgation de l’hôte conserve du texte examiné. Les jetons, les secrets et les anciens consentements ne sont jamais restaurés. L’identité actuelle de l’espace de travail/du plugin, l’autorisation de lecture et chaque droit enregistré sont revérifiés. Les métadonnées de tâches sont limitées par défaut à 256 enregistrements, 64 MiB et 24 heures, avec un maximum de sept jours. La suppression et le nettoyage sont des opérations explicites de l’hôte.
Le stockage local n’a qu’un seul écrivain, valide l’identité de l’espace de travail/de la racine et vérifie l’intégrité des métadonnées. La récupération explicite d’un verrou périmé ne récupère qu’un PID de la même machine dont l’arrêt est prouvé. Les fichiers inconnus/corrompus nécessitent une inspection. Sous Windows, la synchronisation et le renommage des fichiers permettent la récupération après redémarrage du processus ; la persistance dépend du système de fichiers et du périphérique de stockage. Consultez Stockage des tâches, Historique et l’exemple de tâches durables.
Résultats stockés et téléchargements après redémarrage
Avec le stockage d’artefacts activé, await job.addArtifact() ou job.addBinaryArtifact() copie et vérifie le fichier entier avant son inscription. Le texte reste limité à 256 KiB ; les fichiers binaires font au plus 1 GiB. Le flux source et le fichier intermédiaire réel sont vérifiés par SHA-256. Une annulation, un disque plein, une modification et des écritures partielles ne publient pas de résultats utilisables. Les fichiers publiés avant un plantage mais non enregistrés par la tâche peuvent subsister pour inspection par l’opérateur.
Javascript
import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);
La liste distingue les références source des métadonnées d’instantané et signale les instantanés retained, expired, missing, corrupt ou unsupported. retained est un statut de métadonnées ; getStoredJobArtifact() vérifie les métadonnées et l’ensemble du fichier stocké avant de renvoyer une nouvelle référence de la génération actuelle. Chaque lecture revérifie les droits actuels et l’identité du fichier. Les sources supprimées n’affectent pas les octets stockés, et les instantanés absents ne se replient jamais sur une source modifiable. Pour les instantanés texte, appelez client.readStoredJobArtifactText(textReference).
Après un redémarrage, reconnectez-vous avec les droits actuels et obtenez une nouvelle référence. L’identifiant de l’instantané, celui du stockage et l’empreinte restent stables ; l’ancienne génération est rejetée. resume: true revérifie un préfixe .dds-part enregistré par rapport à cet instantané, vérifie les blocs et le fichier intermédiaire complet, puis publie sans écraser la destination. Les lectures nécessitent à la fois des métadonnées de tâches conservées et les octets du fichier. Les consommateurs de blocs dans le navigateur doivent vérifier l’empreinte complète ; l’adaptateur Worker ci-dessous fournit une reprise explicite sur disque dans le navigateur.
Le stockage d’artefacts est limité par défaut à 256 fichiers, 256 MiB et 24 heures, avec un stockage total maximal de 4 GiB et une conservation de sept jours. Les blocs font au plus 64 KiB, avec quatre lectures simultanées. inspect() signale l’utilisation, les dates d’expiration, les entrées invalides et les orphelins. remove(snapshot) et prune() sont des opérations explicites de l’opérateur. Les tâches actives et les lectures individuelles sont protégées contre la suppression ; une expiration ou une suppression entre deux blocs peut arrêter la lecture suivante. Le nettoyage facultatif des orphelins supprime uniquement les fichiers reconnus à lien unique. Les entrées corrompues ou ambiguës doivent être inspectées.
La conservation des fichiers stocke les octets réels du projet indépendamment de l’expurgation des journaux. Choisissez-la délibérément. Le plugin/la commande actuels, l’empreinte du package, l’espace de travail et les droits enregistrés restent requis après un redémarrage. Terminez la maintenance, puis attendez server.close(), artifacts.close() et store.close(), dans cet ordre. Cette version fournit les opérations de conservation des fichiers pour les hôtes autonomes du SDK.
Exécutez npm run example:stored-artifacts pour un véritable redémarrage de processus enfant, la suppression de la source, la reprise vérifiée d’un téléchargement partiel, l’historique et une relance explicite. npm run example:durable-jobs couvre également l’arrêt forcé du processus. Consultez Résultats stockés. Les hôtes 0.7 et antérieurs connus signalent le stockage comme désactivé sans sondages inconnus. Les API actives/source existantes conservent leur comportement original.
Observer un projet
L’opérateur active explicitement les projets et sélectionne les racines autorisées sur le serveur autonome du SDK. Cette configuration à activation explicite utilise les systèmes de fichiers locaux Windows/Linux. Les hôtes SDK 0.3–0.8 connus signalent directement l’indisponibilité de la capacité et préservent leur comportement de découverte existant. Utilisez l’exemple avec le profil pris en charge de système de fichiers local.
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
import {createWorkspaceClient, createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
// The operator chooses the workspace and its allowed local directories.
const server = await createWorkspaceServer({
root: operatorWorkspace, workspaceId, token, notice,
projects: {roots: ['rtl'], fileSystem: 'local'},
});
const client = createWorkspaceClient({url: server.url, token});
await client.connect();
const project = createWorkspaceProject(client);
if (!(await project.getProjectCapabilities()).enabled) {
throw new Error('Project tools are unavailable');
}
const observer = project.watchProject({
root: 'rtl', include: ['**/*.sv'], exclude: ['build/**'],
intervalMs: 1000, debounceMs: 50,
}, {signal});
for await (const event of observer) {
renderExternalView(event.snapshot, event.kind, event.reason);
}
project.dispose(); client.dispose(); await server.close();Le premier événement est un instantané complet. Les changements suivants contiennent des deltas par rapport à une révision précédente ; les indications perdues, les changements pendant l’analyse initiale, les analyses incomplètes et le débordement lié à un consommateur lent produisent une vue de resynchronisation complète accompagnée d’une raison. Les renommages peuvent apparaître comme suppression/création. Chaque fichier est vérifié à son propre instant de lecture ; l’instantané représente ces états échantillonnés, avec regroupement des écritures intermédiaires comme décrit ci-dessus.
Le serveur et le client autorisent chacun quatre abonnements, avec quatre événements en file par abonnement natif. Le bail d’inactivité par défaut est de 30 secondes ; une lecture ultérieure peut renvoyer not_found. Après une longue pause, créez un nouvel itérateur pour obtenir un instantané initial. break/return, l’annulation et la libération des ressources libèrent les abonnements ; si une connexion interrompue empêche le nettoyage, les ressources distantes restantes expirent avec leur bail.
Les limites d’analyse par défaut sont une profondeur de 8, 512 entrées, 1 MiB par fichier, 16 MiB au total et 10 secondes. Les maxima configurables sont une profondeur de 32, 1000 entrées, 16 MiB par fichier, 64 MiB au total et 30 secondes. Les fichiers limités peuvent porter des métadonnées sans empreinte de contenu ; vérifiez complete et reasons. Les échéances sont contrôlées entre les appels au système de fichiers ; choisissez délibérément les droits système du processus hôte pour ces appels.
Arborescence et recherche de projet
listTree renvoie une arborescence, searchFiles recherche les noms de fichiers relatifs par sous-chaîne littérale ou glob borné, et searchText recherche du texte littéral dans les fichiers UTF-8. root est requis ; include/exclude lui sont relatifs. Les requêtes utilisent les modes documentés de texte littéral ou de glob. La recherche insensible à la casse ne normalise que les lettres ASCII A–Z afin de préserver les positions UTF-16 originales.
const tree = await project.listTree({root: 'rtl', pageSize: 16});
const names = await project.searchFiles({root: 'rtl', query: '**/*.sv', mode: 'glob'});
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module ', pageSize: 16};
let page = await project.searchText(query);
for (const item of page.items) {
console.log(item.entry.path, item.entry.revision, item.match.range, item.match.snippet);
}
if (page.nextCursor) {
const next = await project.searchText({...query, cursor: page.nextCursor});
console.log(next.stale, next.items.map(item => item.state));
if (next.nextCursor) await project.releaseProjectQuery(next.nextCursor);
}
if (tree.nextCursor) await project.releaseProjectQuery(tree.nextCursor);
if (names.nextCursor) await project.releaseProjectQuery(names.nextCursor);Les correspondances de texte comprennent un SHA-256 du contenu, une plage UTF-16 numérotée à partir de zéro et un extrait borné. Un curseur fige l’appartenance originale pendant au plus 60 secondes et exige la même requête. Les pages suivantes revérifient le contenu actuel et marquent les éléments current, changed, missing ou unverified ; les nouveaux fichiers n’apparaissent que dans une nouvelle requête. La correspondance et la révision capturées restent inchangées.
Les fichiers texte sont limités à 256 KiB, les requêtes à 256 unités UTF-16 et les extraits à 512 unités. Les valeurs par défaut sont de 256 résultats (maximum 512), 32 éléments par page (maximum 64) et une réponse de 64 KiB (maximum 128 KiB). Les fichiers binaires, l’UTF-8 invalide et les limites d’octets/profondeur/temps/réponse sont signalés comme des résultats incomplets avec leurs raisons. Il y a deux requêtes simultanées et huit vues de curseur conservées ; libérez explicitement les curseurs inutilisés.
Brouillons de projet et reconnexion
const edit = await project.openFile('rtl/counter.sv');
const original = edit.snapshot;
const draft = original.content + '\n// unsaved draft';
const query = {root: 'rtl', include: ['**/*.sv'], query: 'module '};
let page = await project.searchText(query);
for await (const event of project.watchProject({root: 'rtl', include: query.include}, {signal})) {
if (event.snapshot.revision !== page.snapshotRevision) {
if (page.nextCursor) await project.releaseProjectQuery(page.nextCursor);
page = await project.searchText(query); // keep the same explicit scope
}
renderTreeAndMatches(event.snapshot, page); // draft remains caller-owned
}
// A changed file causes conflict; a move/deletion can cause not_found.
try { await edit.save(draft); }
catch (error) {
if (!['conflict', 'not_found'].includes(error.code)) throw error;
showResolutionChoice(error, draft, original);
}
// Only an explicit edit.reload() replaces the edit snapshot.
project.dispose(); client.disconnect(); await client.connect();
const freshProject = createWorkspaceProject(client);
const freshObserver = freshProject.watchProject({root: 'rtl'});
console.log((await freshObserver.next()).value.cursor); // 1: full initial view
await freshObserver.return(); freshProject.dispose();Lorsque le snapshotRevision d’une requête diffère du snapshot.revision observé, libérez l’ancien curseur et répétez la même requête de racine/filtre. L’observation ne modifie jamais edit.snapshot ni le contenu de brouillon détenu par l’appelant. Après un changement externe, un déplacement ou une suppression, la condition CAS originale signale un conflit ; l’appelant choisit un rechargement explicite, une fusion ou un enregistrement distinct.
Le client vérifie la génération de connexion, la racine/le filtre, l’empreinte de la requête, les positions des pages, le SHA-256 de l’instantané et la continuité des événements. Les réponses tardives sont écartées après une révocation, une déconnexion ou une reconnexion. Les curseurs de surveillance et de requête sont distincts et ne sont pas restaurés automatiquement. server.revokeProjects() met fin à l’accès au projet ; sa réactivation exige une nouvelle génération du serveur.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browserLes exemples Node installés vérifient la création, la recherche, les changements externes, les brouillons conservés, les conflits CAS et la reconnexion. Pour l’exemple dans le navigateur, ouvrez l’URL de boucle locale affichée et choisissez Run scenario. Il utilise uniquement son espace de travail temporaire, supprimé à l’arrêt du serveur d’exemple. Les requêtes HTTP ont un délai par défaut de cinq secondes ; configurez délibérément les délais du client et du serveur pour les analyses plus volumineuses.
Observation de projet · Contrats d’arborescence/recherche · Outils de projet HTTP
Diffuser et vérifier les artefacts dans le navigateur
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
import {createOpfsFileSink} from '@altifigence/dds-plugin-sdk/artifact-transfer-browser';
// selectedDirectory belongs to the application; no picker or grant is opened by the SDK.
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = await createOpfsFileSink(selectedDirectory, 'trace.bin', {overwrite: false});
const receipt = await streamStoredJobArtifact(client, reference, {sink, signal});
if (receipt.verification === 'stored') showSavedHash(receipt.storedSha256);L’utilitaire compatible navigateur reçoit au plus un bloc de 64 KiB à la fois, attend le récepteur sélectionné et calcule progressivement l’empreinte du fichier entier. Il valide les plages exactes, l’identité, le base64 et l’empreinte de chaque bloc avant l’écriture. Un récepteur avec relecture relit ensuite indépendamment les octets enregistrés ; la vérification est stored uniquement lorsque les deux empreintes complètes concordent. Sans relecture, la vérification est received et storedSha256 vaut null. Une progression atteignant tous les octets ne signifie pas l’achèvement.
L’application ouvre les sélecteurs nécessaires, sélectionne les handles de fichiers ou les répertoires OPFS, accorde les autorisations et fournit la destination exacte aux adaptateurs SDK. Les récepteurs asynchrones inscriptibles de fichiers/OPFS conservent les données intermédiaires jusqu’à close et les abandonnent en cas d’échec avant validation. Pour les fichiers partiels résistants au rechargement, utilisez l’adaptateur Worker dédié ci-dessous. Les limites sont de 1 GiB par fichier, quatre flux directs simultanés et une échéance totale de 30 minutes.
Téléverser des fichiers sélectionnés
import {uploadFile} from '@altifigence/dds-plugin-sdk/uploads';
import {createBrowserUploadSource} from '@altifigence/dds-plugin-sdk/uploads-browser';
// The operator separately configures uploads.directory/principalId/roots/fileSystem
// on the Node workspace server, and grants workspace.write to this pinned plugin.
const source = createBrowserUploadSource(selectedFile);
const status = await uploadFile(client, source, {
uploadId: crypto.randomUUID(), pluginId, artifactSha256: pluginPin,
path: 'input/trace.bin', expectedRevision: null, signal,
});
if (status.state === 'committed' && status.commitReceipt.verified) {
showCommittedUpload(status.commitReceipt);
}
// To recover a previously selected upload ID, pass the same specification and
// source with recover: true. The helper queries current authority and rehashes it.Les téléversements sont désactivés par défaut. L’opérateur configure un espace de travail Node local, un répertoire intermédiaire isolé, les racines autorisées et un seul principal, puis accorde workspace.write au plugin sélectionné pour l’empreinte exacte de son archive. L’utilitaire calcule au préalable l’empreinte de la source sélectionnée. Le serveur accepte des blocs séquentiels de 64 KiB, vérifie les doublons et le contenu complet, puis ne valide qu’après les contrôles conditionnels de la cible. Aucun octet intermédiaire n’apparaît dans les listes ordinaires de l’espace de travail.
expectedRevision: null exige une cible absente ; un SHA-256 exige la cible actuelle correspondante. Une annulation conserve le préfixe confirmé par le serveur. Une nouvelle opération recover explicite interroge les droits actuels, valide la même source/spécification et reprend uniquement le préfixe concordant. Une réponse de validation perdue reste incertaine jusqu’à son interrogation ; elle n’autorise pas à répéter commit ou à restaurer un fichier. Les limites maximales sont de 1 GiB par fichier, 4 GiB par stockage et quatre sessions actives ; les valeurs par défaut sont inférieures. Les hôtes 0.3–0.9 connus signalent les téléversements comme désactivés sans sonder les nouvelles méthodes.
Planifier les transferts de fichiers
import {createTransferQueue} from '@altifigence/dds-plugin-sdk/transfer-queue';
const queue = createTransferQueue({
concurrency: 2, perConnection: 1, bufferBytes: 131072,
bytesPerSecond: 1048576, attempts: 3,
});
const unsubscribe = queue.subscribe(view => renderTransfer(view));
const download = queue.enqueueStoredDownload(client, reference, {sink});
download.pause(); // finishes the current stage, then waits at the next boundary
download.resume();
const receipt = await download.result;
queue.release(download.id);
unsubscribe(); await queue.dispose();Une file détenue par l’appelant mélange les tâches de téléversement, de téléchargement actif et de téléchargement stocké. Elle borne les tâches conservées (32), les étapes simultanées (4), la concurrence des connexions client, les réservations de blocs décodés (64–256 KiB), le débit et les relances. Les opérations admissibles progressent au-delà d’une connexion saturée, et des avances de priorité bornées évitent que les petites tâches admissibles soient privées de ressources. Une tâche mise en pause termine son étape actuelle puis attend ; la pause peut conserver un verrou de stockage. Les échéances totales incluent l’attente dans la file et la pause.
La relance automatique est limitée aux erreurs 429/503 reconnues par le SDK, aux pertes réseau ou aux délais de requête dépassés pendant une opération de bloc exacte et idempotente, avec un délai croissant borné et une variation aléatoire. Les échecs begin/commit, d’autorisation, de somme de contrôle, de plage, de source ou de récepteur rendent le contrôle à l’appelant pour une décision explicite de récupération. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes et remainingBytes sont distincts ; seul un reçu vérifié produit completed. Un fichier déjà validé reste validé après cancel/dispose.
Reprendre les téléchargements dans le navigateur
// Run inside an application-owned dedicated Worker with OPFS + Web Locks.
import {createOpfsArtifactSink} from '@altifigence/dds-plugin-sdk/artifact-resume-browser';
import {streamStoredJobArtifact} from '@altifigence/dds-plugin-sdk/artifact-transfer';
await client.connect();
const fresh = await client.getStoredJobArtifact(pluginId, jobId, artifactId, pluginPin);
const sink = createOpfsArtifactSink({
directory: selectedDirectory, partialId: selectedPartialId, reference: fresh,
});
const receipt = await streamStoredJobArtifact(client, fresh, {sink, resume: true, signal});
console.log(receipt.resumedBytes, receipt.receivedBytes, receipt.storedSha256);
// The first transfer omits resume, and refuses any existing files for that ID.
// A queue can use the same sink and explicit resume: true on a new stored download.La récupération persistante exige un Worker dédié, l’accès synchrone OPFS et Web Locks. Après le rechargement, l’appelant sélectionne à nouveau son répertoire et l’UUID du fichier partiel, puis obtient une nouvelle référence stockée approuvée. Le récepteur stocke deux noms exacts de fichiers de données/métadonnées, l’identité complète de l’instantané immuable, son expiration et les empreintes des préfixes actuel/précédent. Il ne stocke aucun jeton, droit ou ancienne portée de connexion. Chaque bloc de données est synchronisé avant la fermeture du petit flux de métadonnées.
Le récepteur et l’utilitaire recalculent indépendamment l’empreinte du préfixe. Une fin de fichier sans point de contrôle n’est tronquée qu’après concordance du préfixe enregistré. Les métadonnées dépassant la taille réelle du fichier peuvent revenir au point de contrôle précédent uniquement si ces octets et leur empreinte concordent ; la corruption, les entrées absentes, l’expiration ou un instantané différent provoquent un échec sans redémarrage silencieux. Un verrou exclusif à l’échelle de l’origine rejette un autre onglet, reste détenu pendant la relecture et est libéré lors de close ou de l’arrêt du Worker. La réouverture exige alors une récupération explicite.
Les métadonnées locales sont limitées à 16 KiB et quatre sessions ouvertes de récepteur. La conservation est d’une heure par défaut, avec un maximum de 24 heures plafonné par l’expiration de l’instantané de l’hôte. Planifiez le stockage selon le quota et l’éviction du navigateur, et protégez les scripts et données de l’origine avec la politique de sécurité de l’application. Qualifiez le comportement face aux coupures de courant dans l’environnement de stockage cible. Chromium 154 sous Windows a été testé pour l’annulation, le rechargement, le redémarrage de l’hôte, le conflit entre deux onglets et l’arrêt de l’onglet propriétaire avec des empreintes complètes de fichiers enregistrés. Utilisez ce profil navigateur/système mesuré comme référence pour qualifier d’autres combinaisons.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeDiffusion en flux · Téléversements · File de transferts · Récupération Worker
Aide à la signature et assistance à la complétion
Déclarez signature-help, completion-resolve et completion-snippets selon les besoins dans le manifeste v2 ; les modificateurs de complétion exigent également completion. L’hôte doit accorder document.read et language.provide. Les complétions littérales existantes restent valides. languageCapabilities() indique l’implémentation SDK et ses limites, sans accorder d’autorisation.
const signatures = await host.requestLanguage('signature-help', {
position, context: {triggerKind: 'invoked', isRetrigger: false},
});
const list = await host.requestLanguage('completion', {position});
if (list.data.length) {
const detailed = list.data[0].resolveToken
? await host.resolveCompletion(list.data[0].resolveToken) : list;
const preview = host.prepareCompletion(detailed, 0);
showInsertionPreview(preview.content, preview.tabstops);
host.releaseCompletion(detailed);
}
host.releaseCompletion(list);L’application fournit la position actuelle et l’hôte ; la préparation renvoie des données sans écrire de document ni de fichier. L’aide à la signature prend en charge jusqu’à 16 signatures, 64 paramètres chacune et des décalages UTF-16 des libellés de paramètres. La résolution de complétion garde privées les données du fournisseur, renvoie un jeton d’hôte à usage unique et fixe le libellé/l’insertion/la plage sélectionnés. Les jetons lient le fournisseur, la portée et le document, expirent après 60 secondes et sont limités à 128 entrées, 4 MiB et quatre opérations réelles de résolution. Les changements de document/fournisseur les invalident.
Les extraits prennent en charge $n, ${n}, ${n:literal}, $0 et les échappements documentés, avec des miroirs et des points d’arrêt de tabulation ordonnés. Les variables, l’imbrication, les choix, les transformations et les commandes exécutables sont rejetés. Les limites UTF-16/CRLF et les modifications supplémentaires qui se chevauchent sont vérifiées. Les fournisseurs s’exécutent comme du code de confiance dans le processus avec les droits système du processus hôte. Une annulation ignorée garde l’emplacement réel en attente occupé jusqu’à la fin du fournisseur.
Modifications d’espace de travail et renommage soumis à révision
prepare-rename renvoie une plage/un texte indicatif validé ou null ; rename renvoie une proposition WorkspaceEdit ou null. Les propositions prennent en charge edit, create, move et delete sur des chemins relatifs de fichiers disjoints. Le SHA-256 actuel de la source, l’absence de destination, la politique des chemins protégés, la géométrie des modifications UTF-16 et les limites sont vérifiés. Les fonctionnalités de langage autorisent les propositions ; le client d’espace de travail fournit l’accès aux fichiers et les modifications approuvés séparément.
import {previewWorkspaceEdit, applyWorkspaceEdit, recoverWorkspaceEdit}
from '@altifigence/dds-plugin-sdk/workspace-edits';
const preview = await previewWorkspaceEdit(client, proposal);
// Show every change, conflict and required capability; obtain this exact review.
const receipt = await applyWorkspaceEdit(client, preview, {
reviewed: approvedReview, // {planId, digest} from that review
journal,
authorize: (request, {signal}) => currentHostPolicy(request, signal),
});
// After interruption, current-authority readback does not replay changes.
const observed = await recoverWorkspaceEdit(client, journal, preview.planId);L’appelant utilise un client d’espace de travail connecté et autorisé ainsi qu’un journal de confiance. L’aperçu contient des instantanés complets avant/après et une empreinte ; apply exige le planId/l’empreinte examinés et une politique actuelle de l’hôte renvoyant true. Chaque fichier est contrôlé au préalable, puis chaque opération utilise le CAS par fichier existant et les capacités actuelles d’écriture/gestion. Le journal persiste et relit l’intention avant chaque modification et un reçu ensuite. Un conflit ou une incertitude arrête les écritures suivantes ; chaque opération de fichier achevée possède son propre résultat CAS et son reçu dans le journal.
L’adaptateur facultatif workspace-edits-node stocke un journal borné hors de l’espace de travail sélectionné, lie son identité et utilise un verrou à écrivain unique, des fichiers ordinaires et des points de contrôle par somme de contrôle. Après l’arrêt du processus, recoverStaleLock est un choix explicite et ne récupère qu’un propriétaire dont l’arrêt est prouvé. La récupération signale applied/not-applied/conflicted/unknown à partir des octets actuels ; l’appelant choisit explicitement l’action suivante. La compensation crée une nouvelle proposition inverse pour un nouvel examen. Sous Windows, l’adaptateur synchronise les fichiers et effectue des opérations de renommage. Les contrôles documentés couvrent l’arrêt du processus et la récupération ; la persistance dépend du système de fichiers et du périphérique de stockage. Les limites comprennent 32 changements, 1000 modifications, 256 KiB par fichier, un aperçu de 8 MiB et 64 plans de journal conservés.
Formatage et actions de code de diagnostic
const formatted = await host.requestLanguage('format-range', {
path: 'main.dds', range: selectedRange,
formatOptions: {tabSize: 2, insertSpaces: true, endOfLine: 'preserve'},
});
const formatProposal = host.prepareFormatting(formatted);
await host.requestDiagnostics();
const actions = await host.requestLanguage('code-actions', {
path: 'main.dds', range: selectedRange,
context: {triggerKind: 'invoked', only: ['quickfix']},
});
if (actions.data.length && !actions.data[0].disabled) {
const selected = actions.data[0].resolveToken
? await host.resolveCodeAction(actions.data[0].resolveToken) : actions;
if (!selected.data[0].disabled) {
const fixProposal = host.prepareCodeAction(selected, 0);
showWorkspaceEditProposal(fixProposal); // separate preview, review and apply
}
host.releaseCodeActions(selected);
}
host.releaseCodeActions(actions);format-document et format-range exigent un chemin et les options tabSize/insertSpaces ; seul le formatage de plage prend une sélection. Un résultat vaut null ou contient exactement une modification du fichier actuel avec l’empreinte de l’instantané actuel. Les modifications de plage restent dans la sélection. endOfLine sélectionne preserve, lf ou crlf pour le texte inséré ; les octets non modifiés restent inchangés. Les propositions au contenu identique sont normalisées en null. prepareFormatting n’effectue aucune écriture.
L’hôte lie les requêtes d’action et les jetons de résolution à la révision de diagnostic acceptée et à l’instantané actuel. Une publication ultérieure de diagnostics, un changement de document ou la libération du fournisseur invalident les anciennes sélections. Les appels de diagnostic reçus dans le désordre n’écrasent pas le groupe accepté plus récent. Jusqu’à 100 actions portent des libellés simples, des indices de diagnostic bornés, des modifications proposées, des données de résolution privées ou une raison de désactivation. Les champs inconnus de commande/URL/shell sont rejetés. Les modifications d’action peuvent dépasser la sélection ; examinez donc la proposition complète. Le formatage et les actions n’approuvent jamais leurs propres écritures.
Affichage sémantique, repliage, indications et symboles
import {decodeSemanticTokens} from '@altifigence/dds-plugin-sdk';
const tokens = await host.requestLanguage('semantic-tokens',
previousResultId ? {previousResultId} : {});
host.validateLanguageResult(tokens); // actual current host-owned result only
renderWhitelistedTokens(decodeSemanticTokens(tokens.data, currentDocumentText));
const folds = await host.requestLanguage('folding-ranges', {});
const hints = await host.requestLanguage('inlay-hints', {range: visibleRange});
const symbols = await host.requestLanguage('document-symbol-tree', {});
for (const result of [folds, hints, symbols]) host.validateLanguageResult(result);
// Render labels as text nodes. Release results when no longer retained.
host.releaseLanguageResult(tokens);Les jetons sémantiques utilisent une légende avec des noms uniques et neuf clés de style détenues par l’hôte, ainsi que cinq entiers par jeton : delta de ligne/début, longueur UTF-16, indice de type et bits de modificateur. Les jetons ne peuvent pas se chevaucher, scinder un substitut, traverser une ligne ou sortir du document actuel. L’hôte renvoie toujours un tableau complet normalisé et un UUID d’hôte, avec updateKind full/delta/fallback. Une capacité semantic-tokens-delta distincte active provideDelta par rapport aux données précédentes détenues par le fournisseur ; le cache stocke l’identité et les données de jetons, pas l’ancien texte du document.
Une base de cache est liée au fournisseur, à la portée, à l’URI et au langage, avec au plus huit entrées, 4 MiB et 60 secondes. Les versions de document ordinaires croissantes conservent une éventuelle base de delta tout en rendant obsolète l’ancien résultat d’affichage. Une base perdue/expirée, un delta null ou un identifiant de base de fournisseur discordant permettent au plus un repli complet dans le délai original. Les données invalides ou les erreurs du fournisseur échouent sans relance. La désactivation, la désinscription et le remplacement du document effacent les bases concernées. Appelez validateLanguageResult juste avant le rendu ; un objet copié, libéré ou obsolète échoue.
Les limites sont de 20000 jetons sémantiques, 64 types de jetons, 16 modificateurs et 64 modifications delta ; le repliage autorise 1000 plages avec une profondeur de 32 et rejette les plages qui se croisent. Les indications intégrées autorisent 1000 libellés simples sur une seule ligne dans la plage demandée. Les symboles hiérarchiques autorisent 1000 entrées au total et 16 niveaux, avec des enfants/sélections contenus et des éléments de même niveau ordonnés sans chevauchement. Le contrat original de document-symbols non hiérarchiques reste inchangé. L’exemple dans le navigateur teste full/delta/fallback, le repliage, la navigation et le cycle de vie ; une indication ressemblant à du HTML reste du texte littéral.
npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browserAssistance · Modifications soumises à révision · Formatage/actions · Affichage
Paramètres typés et références de secrets
Le module /settings fournit un stockage en mémoire détenu par l’opérateur pour un plugin. Une définition versionnée déclare chaque clé, son schéma de données, sa valeur par défaut, les portées utilisateur/espace de travail autorisées et ses métadonnées d’affichage. Les valeurs effectives remplacent chaque clé entière dans l’ordre default < user < workspace. read(workspaceId) renvoie des valeurs immuables, des sources et une révision couvrant tout le stockage. Les objets imbriqués ne sont pas fusionnés récursivement ; une valeur absente sans valeur par défaut reste absente.
import {createSettingsStore} from '@altifigence/dds-plugin-sdk/settings';
const settings = createSettingsStore({schemaVersion: 1, pluginId: 'example',
version: 1, settings: {count: {
schema: {schemaVersion: 1, schema: {
type: 'integer', minimum: 1, maximum: 10, default: 2,
}}, scopes: ['user', 'workspace'], display: {label: 'Count'},
}},
});
settings.update({workspaceId: 'selected-project', scope: 'workspace',
expectedRevision: settings.read('selected-project').revision, values: {count: 4}});
const effective = settings.read('selected-project');
// Mount as createPluginHost({settings: {example: settings}, ...}).Les écritures valident toute la transaction et utilisent expectedRevision CAS. reset retire une clé d’une couche ; readOnly exige une valeur par défaut et aucune portée inscriptible. Les abonnements regroupent les changements synchrones et renvoient des handles dont les ressources peuvent être libérées. migrate(nextDefinition, callback, options) explicite valide l’état suivant et ne le valide définitivement que si sa révision correspond encore. Un échec, une annulation ou un délai dépassé préserve l’ancienne définition et l’ancien état. L’export/import est constitué de données simples ; l’opérateur gère la persistance et le chiffrement. Les limites comprennent 64 clés, 32 couches d’espace de travail, 1 MiB d’état exporté et une seule migration réelle.
Les plugins d’espace de travail déclarent settings et settings.read, et l’opérateur monte le stockage correspondant avec ce droit. context.settings est en lecture seule et lié au plugin et à l’espace de travail sélectionné. Le résolveur /secrets émet séparément des références opaques pour un plugin, un espace de travail, une liste de commandes autorisées et une durée de vie. Le manifeste doit déclarer secrets.resolve et l’hôte doit l’accorder. Les champs d’entrée utilisent type: object avec format: dds-secret-reference ; les chaînes ordinaires et les objets similaires ne confèrent aucun droit sur les secrets.
Seules les références dans une entrée validée sont disponibles via options.secrets.withSecret d’une commande. Chaque exécution possède un nouvel identifiant ; le résolveur vérifie la portée, l’expiration, la révocation et l’autorisation actuelle autour de la résolution et du rappel. Le rappel renvoie undefined et reçoit une copie effacée à l’interruption et à chaque sortie. Les erreurs du fournisseur sont assainies. Placez le bail avant les effets qui exigent ces droits. La durée de vie par défaut d’une référence est de 60 secondes, au plus une heure ; les limites sont de 128 références, 8 baux réels et 16 KiB de données. Le code de confiance dans le processus peut conserver des copies et s’exécute avec les droits système du processus hôte. Gardez les secrets dans le rappel autorisé et classez explicitement les chaînes de l’application avant de stocker paramètres, paquets, journaux ou résultats.
Schémas et formulaires de commandes structurées
Les commandes peuvent déclarer inputSchema et outputSchema avec une enveloppe schemaVersion: 1. Les paramètres primitifs existants restent pris en charge ; déclarer parameters et inputSchema ensemble est rejeté. L’hôte valide et applique les valeurs d’entrée par défaut avant de démarrer un gestionnaire ou une tâche, puis valide la sortie avant de publier la réussite. Les valeurs de sortie par défaut ne sont jamais appliquées. Les nouvelles métadonnées de schéma/affichage nécessitent un pair compatible 0.12 ; les anciens validateurs stricts les rejettent, tandis que les définitions historiques conservent leur comportement.
import {parseCommandInput, parseCommandOutput} from '@altifigence/dds-plugin-sdk';
const command = {id: 'summarize', title: 'Summarize',
inputSchema: {schemaVersion: 1, schema: {
type: 'object', additionalProperties: false,
properties: {names: {type: 'array', minItems: 1, maxItems: 8,
items: {type: 'string', minLength: 1, maxLength: 64}}}, required: ['names'],
}}, outputSchema: {schemaVersion: 1, schema: {type: 'integer', minimum: 0}},
};
const input = parseCommandInput({names: ['Ada']}, command);
parseCommandOutput(input.names.length, command);Le sous-ensemble borné prend en charge les objets fermés, les tableaux, les chaînes, les nombres finis, les entiers sûrs, les booléens, null, les énumérations primitives, les bornes et les valeurs par défaut validées. Les mots-clés inconnus, les références distantes, les expressions régulières, les unions, les conversions forcées, les accesseurs et les prototypes personnalisés sont rejetés. Les schémas autorisent 32 KiB, une profondeur de 8 et 128 nœuds ; les valeurs autorisent 64 KiB. Une commande complète conserve le budget de métadonnées de 16 KiB. DataValidationError local expose code, reason et les chemins de champs connus tels que /input/options/names/0 ; les échecs HTTP et de tâches exposent des codes sûrs sans les valeurs rejetées.
describeDataForm renvoie les chemins, types, choix, valeurs par défaut, indicateurs de champs obligatoires et indications de références de secrets. Les métadonnées d’affichage partagées portent les valeurs littérales label/help/order et les noms d’accessibilité, descriptions et indications clavier. L’hôte gère le rendu et les interactions. Ces schémas décrivent des données simples ; l’hôte contrôle explicitement le rendu, l’accès aux ressources et l’exécution des commandes.
Métadonnées de localisation et d’accessibilité
import {parseLocaleCatalog, resolveMessage, localizeDisplay}
from '@altifigence/dds-plugin-sdk/localization';
const catalog = parseLocaleCatalog({schemaVersion: 1, defaultLocale: 'en',
messages: {en: {title: 'Run', done: '{count} results'},
ko: {title: '실행', done: '결과 {count}개'}, ar: {}}, fallbacks: {ar: ['en']},
});
const message = resolveMessage(catalog, 'ko-KR', 'done', {count: 2});
const display = localizeDisplay(catalog, 'ko', {
labelKey: 'title', accessibility: {nameKey: 'title', shortcut: 'Control+Enter'},
});
// Render message.text as textContent; use message.locale and message.direction.
// Preserve raw values and command IDs when the display language changes.Les catalogues utilisent des étiquettes de base BCP 47 canoniques et des liens de repli explicites acycliques. Jusqu’à huit préférences négocient les étiquettes exactes, puis leurs ancêtres et la valeur par défaut. La langue par défaut définit toutes les clés ; les traductions peuvent omettre des clés, mais ne peuvent pas en inventer. La recherche par clé suit les liens de repli ordonnés, puis la valeur par défaut. Chaque traduction et ses arguments doivent correspondre à l’ensemble exact de paramètres {name}. Il s’agit d’une interpolation littérale sans expressions ICU. resolveMessage indique la langue source et la direction réelles, afin qu’un repli en anglais dans une page RTL puisse conserver lang=en et dir=ltr.
Le formatage des nombres prend en charge decimal/percent ; le formatage des dates utilise une époque explicite et UTC par défaut ; la sélection du pluriel renvoie une catégorie cardinale/ordinale Intl pour le choix de message de l’appelant. Les hôtes gèrent les données et la prise en charge d’Intl. validateLocalizedSurfaces vérifie les clés du manifeste/des commandes/des paramètres/des schémas et les fichiers d’affichage annexes des thèmes, y compris les longueurs d’affichage résolues et les traductions absentes. Le JSON/XML des thèmes reste compatible. Les limites de catalogue sont de 32 langues, 256 clés et 256 KiB ; les libellés statiques ne peuvent pas contenir de paramètres.
Les utilitaires /accessibility signalent les noms absents, les raccourcis normalisés en double et le contraste de paires de couleurs opaques explicites dans les thèmes clairs/sombres. Les hôtes utilisent ces indications pour implémenter les raccourcis clavier et évaluer l’accessibilité de leurs interfaces. L’exemple indépendant comprend EN/KO, de l’arabe partiel et des jeux de libellés longs. Il teste les paramètres avec portée, les références refusées/révoquées, les champs invalides, Ctrl+Enter et les changements de langue pendant une commande active. La mise en page dans le navigateur a été vérifiée aux tailles ordinateur/mobile dans les thèmes clairs/sombres.
npm run example:configuration
npm run example:configuration-browserParamètres · Références de secrets · Schémas de commandes · Localisation
Modèles de développement et génération
Six modèles, dépendances d’archive exactes, examen de la génération, préservation des conflits et contrôles doctor.
Contrats complets, exemples et limites
Tests déterministes et relecture
Jeux de données synthétiques explicites, temps virtuel, défauts, traces bornées d’empreintes uniquement et nettoyage des ressources.
Contrats complets, exemples et limites
Diagnostics locaux et débogage
Profils locaux facultatifs et débogueur enfant de confiance avec un point de terminaison éphémère en boucle locale et une échéance totale.
Contrats complets, exemples et limites
Conformité des hôtes
18 profils versionnés distinguent les contrats pris en charge, non pris en charge et en échec ; les adaptateurs personnalisés conservent des droits explicites.
Contrats complets, exemples et limites
Prise en charge du SDK et migration
Consultez l’inventaire des exports, la politique stable/facultative/expérimentale, les pairs exacts, les dates des environnements d’exécution et les exemples de migration.
Contrats complets, exemples et limites
Validation des versions
La publication du SDK présente les charges de travail combinées avec défauts et les garde-fous de performance mesurés comme validation fonctionnelle de ses contrats SDK et des hôtes indépendants.
Contrats complets, exemples et limites
1.1 Outils de dépendances, de provenance et de mise à jour
1.1.0 ajoute des paquets déterministes hors ligne de dépendances examinées, des SBOM CycloneDX, des signatures détachées avec des clés Ed25519 détenues par l’opérateur, l’approbation/l’activation/la restauration liées à une empreinte et la comparaison explicite avec l’amont. Cinq points d’entrée réservés à Node comprennent des déclarations, des schémas et des exemples indépendants. L’opérateur accorde explicitement l’exécution après examen de la signature et les anciennes tâches conservent leur empreinte originale. L’opérateur choisit son flux de distribution, de déploiement et de surveillance. La publication du SDK documente la validation fonctionnelle à travers ses exemples indépendants d’outils de publication.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsGuide complet des paquets, signatures, mises à jour et de l’amont
1.2 Flux de travail, cache, flux d’outils et LSP
1.2.0 ajoute des DAG de commandes examinés avec des tâches/droits par étape, des points de contrôle durables et une récupération explicite par nouvelle tentative ; un cache déterministe fondé sur le contenu et l’exécution incrémentale ; des flux d’outils UTF-8/JSONL/texte bornés ; et une passerelle stdio LSP 3.17 facultative. Sept nouveaux points d’entrée portent le package à 50 exports et 107 schémas avec déclarations et exemples indépendants installés, sans dépendance npm à l’exécution. L’analyseur de flux d’outils fonctionne également dans les navigateurs ; les flux de travail, stockages, processus externes et LSP nécessitent Node. La publication du SDK documente des contrôles fonctionnels des adaptateurs avec TypeScript 5.9.3 et language-server 5.3.0. La passerelle accepte les diagnostics liés à une version de document. L’hôte autonome du SDK gère la récupération explicite par nouvelle tentative, les stockages locaux et la configuration des processus.
node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjsGuide complet des flux de travail, du cache, des outils et de LSP