DDS Plugin SDK
Installa il DDS Plugin SDK pubblico 1.2 e usa flussi di lavoro, cache, flussi degli strumenti, LSP e API stabili.
Gli esempi di workspace utente sotto descrivono un host di sviluppo controllato dal cliente e connesso esplicitamente. Scegli WSL o un altro host per questi esempi autonomi dell’SDK. La normale app Windows Digital Design Studio usa il proprio runtime Windows nativo. Configura rilevamento, autorizzazioni e funzionalità dei plugin per l’host SDK selezionato; i job gestiti dei motori Cloud usano il proprio percorso di esecuzione.
1. Installa l'SDK
DDS Plugin SDK 1.2.1 offre API JavaScript, dichiarazioni TypeScript, provider di linguaggio, temi, strumenti per il workspace e job di comando. Gli archivi persistenti facoltativi aggiungono cronologia dei job, nuovi tentativi espliciti e snapshot verificati di testo e dati binari che sopravvivono alla cancellazione dei sorgenti e al riavvio del processo. Usa Node.js 22 o 24. Installa la versione stabile dell'SDK dalla release ufficiale su GitHub. Per un plugin di comando autonomo, usa Strumenti di sviluppo dopo l'installazione:
La versione 1.0.0 pubblica l'API stabile dell'SDK, 18 profili di conformità degli host, la politica di supporto e migrazione e verifiche misurate con carichi di lavoro combinati. I nuovi plugin usano >=1.0.0 <2.0.0. La release pubblicata dell’SDK attribuisce questi risultati alla convalida funzionale dell’SDK e degli host indipendenti.
La versione 0.13.0 aggiunge sei modelli di sviluppo, tipi e schemi generati, scenari di test deterministici e diagnostica locale facoltativa. L'SDK confezionato e i progetti generati funzionano al di fuori dell'albero dei sorgenti; la riproduzione sintetica e il debug su loopback vengono selezionati esplicitamente.
La versione 0.12.0 aggiunge impostazioni tipizzate con ambito definito e migrazioni esplicite, riferimenti a segreti limitati all'esecuzione, input e output strutturati dei comandi, cataloghi linguistici e metadati di accessibilità. L'SDK pubblico e gli esempi indipendenti verificano conflitti nelle impostazioni, input non valido, autorizzazioni revocate e fallback delle traduzioni.
La versione 0.11.0 aggiunge assistenza per le firme, completamento differito, frammenti con limiti definiti, modifiche e rinomine su più file sottoposte a revisione, formattazione e azioni sul codice, token semantici, riduzione dei blocchi, suggerimenti e simboli gerarchici. Proposte, revisione, controlli delle autorizzazioni correnti e applicazione condizionata sono fasi distinte dell’host. Gli host visualizzano e applicano i risultati solo mentre l’identità del documento è corrente. Queste funzionalità vengono esercitate dall’SDK pubblico e dagli esempi indipendenti.
La versione 0.10.0 aggiunge download in streaming nel browser, caricamenti di file selezionati, una coda mista di trasferimenti e il ripristino dei checkpoint Worker OPFS. I trasferimenti verificano le autorizzazioni correnti, l'identità dei file e gli hash dei blocchi e dell'intero contenuto, distinguendo l'avanzamento in byte dall'archiviazione verificata. Questi esempi esercitano host e client dell’SDK pubblico.
La versione 0.9.0 aggiunge alberi di progetto con ambito definito, ricerca per nome file e testo e osservazione delle modifiche nelle directory locali selezionate dall'operatore. Usali dal client HTTP o dall'helper del progetto, conservando gli snapshot delle modifiche e le bozze non salvate. Gli esempi di progetto riportati di seguito riguardano creazione, ricerca, modifiche esterne e gestione dei conflitti.
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"
Il primo esempio di diagnostica usa codice attendibile in un host di test locale. I temi usano l'importazione XML già disponibile in DDS. Per le integrazioni degli strumenti esistenti, consulta Plugin e strumenti di terze parti.
2. Scrivi il tuo primo plugin
Crea plugin.mjs nel nuovo progetto. Questo plugin controlla documenti di testo semplice e segnala una diagnostica informativa per ogni riga contenente 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);
},
}));
Il manifesto dichiara la versione 1 del protocollo, la funzionalità diagnostics, l'host test-host e le autorizzazioni document.read e diagnostics.publish. Il provider riceve uno snapshot del documento e un AbortSignal. Gli intervalli diagnostici usano righe con indice a partire da zero e offset dei caratteri UTF-16.
3. Eseguilo localmente
Crea run.mjs accanto a plugin.mjs. Attiva il plugin, fornisci un documento e richiedi la diagnostica. Rilascia sempre l'host al termine.
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
Output previsto (la riga e la colonna stampate partono da uno):
Testo
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. Testa il tuo plugin
Salva questo test come plugin.test.mjs. Verifica l'intervallo diagnostico e conferma che la modifica del documento elimina la diagnostica.
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
Il test dovrebbe riuscire. Aggiungi dati di test per il tuo linguaggio, l'annullamento, risultati non validi e documenti di grandi dimensioni. Mantieni aggiornata la versione del documento affinché i risultati di uno snapshot precedente vengano rifiutati.
5. Crea e applica un tema
Salva questa palette chiara e scura come theme.json. I sei colori di ciascuna palette sono obbligatori. I token semantici facoltativi personalizzano ricerca, selezioni, HintsBox e l'area di disegno GDS; i token omessi usano i valori predefiniti di 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
}
}
}
Crea export-theme.mjs accanto al file. parseTheme convalida i dati dei colori e serializeThemeXml esporta XML DDS versione 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
Il comando scrive hello-theme.xml e stampa Created hello-theme.xml. In DDS, apri Plugins → Installa tema…, seleziona l'XML, poi scegli Applica per Hello Ocean. Alterna l'aspetto chiaro e scuro per vedere entrambe le palette.
Puoi anche usare Impostazioni → Generali → Aspetto → Importa XML. Salva il tema corrente con Esporta XML prima di sostituirlo. L’importatore XML legge i dati sull’aspetto del tema.
La guida ai temi elenca tutti i token e le metriche supportati. L'esempio Hello Ocean include il tema completo, l'XML pronto da importare e un'anteprima HTML locale.
Riferimento XML dei temi
Scarica Hello Ocean XML e il relativo JSON modificabile. L'XML contiene palette chiare e scure complete, tutti i 28 colori di ruolo facoltativi in ciascuna modalità e quattro metriche esplicite. Salva il file XML localmente prima di importarlo. Questi esempi originali dell'SDK usano Apache-2.0; conserva l'avviso di licenza quando li condividi.
Inizia con Impostazioni → Generali → Aspetto → Esporta XML per eseguire il backup del tema corrente. Importa l'XML scaricato, esamina la bozza, poi scegli Applica. Scarta modifiche mantiene il tema applicato. Alterna aspetto chiaro/scuro per esaminare entrambe le palette. Per recuperare, scegli un tema integrato o importa la copia salvata. Un'importazione rifiutata conserva il tema corrente.
DDS, ALcad, gli editor condivisi, la navigazione del progetto, le impostazioni e le finestre popup usano la palette condivisa dell'ambiente di lavoro in quel profilo. Cloud e desktop usano lo stesso formato di tema; importalo separatamente in ciascun profilo. gdsBackground controlla l'area di disegno GDS in modo indipendente. Altri colori delle aree di progettazione, dei livelli e delle simulazioni possono avere impostazioni proprie. L’XML contiene la palette e le metriche dell’aspetto per questo profilo del tema.
Elemento | Regola |
|---|---|
| Un solo elemento radice; un nome di 1–80 unità di codice UTF-16 senza spazi iniziali o finali; al massimo 65536 byte UTF-8 per l'intero XML. |
| Entrambi obbligatori, ciascuno con i sei colori riportati di seguito. |
| Sovrascritture v2 facoltative. I ruoli omessi seguono i valori predefiniti DDS per quella modalità. |
| Sovrascritture numeriche v2 facoltative. |
Versione 1 | Solo entrambe le palette. I file v1 esistenti restano supportati; l'esportatore SDK produce v2. |
Chiave obbligatoria della palette | Uso |
|---|---|
| Sfondo esterno del workspace |
| Navigazione del progetto |
| Pannelli degli strumenti e controlli |
| Workspace principale e impostazioni |
| Testo principale |
| Testo secondario |
Chiavi di ruolo facoltative (28) | Uso |
|---|---|
| Sfondo, testo e segnaposto della ricerca condivisa |
| Campo di compatibilità; i campi di ricerca condivisa correnti sono senza bordi |
| Righe e testo selezionati |
| Schede dell'editor |
| Barre degli strumenti, bordi dei pannelli e finestre popup |
| Contorno del focus della tastiera |
| Colori di stato e sfondo della sfera AI |
| Sfondi dei suggerimenti e dei dettagli |
| Testo dei suggerimenti, dei dettagli e secondario |
| Suggerimento selezionato con la tastiera |
| Suggerimento su cui passa il puntatore |
| Sfondo dell'area di disegno del visualizzatore GDS |
HintsBox è la funzionalità condivisa di suggerimento del codice. Trovi i suoi colori in Personalizzato → Colori e forme dettagliati → HintsBox e lo sfondo GDS in Visualizzazione. Modifica insieme tutti e tre i colori della ricerca per ottenere un contrasto leggibile. Questo frammento va inserito in un tema v2; conserva le due palette complete:
Frammento XML v2
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
Metrica | Valori ammessi | Valore predefinito DDS corrente |
|---|---|---|
| Intero 0–24 | 14 |
| Intero 0–16 | 6 |
| Intero 0–24 | 16 |
| Numero 0,6–1 | 0,72 |
Scrivi le metriche come <number key="popoverOpacity" value="0.9"/> all'interno di <metrics> senza unità. I valori dei raggi sono espressi in pixel. L'SDK non aggiunge le metriche omesse; la release DDS installata fornisce i propri valori predefiniti. Imposta valori espliciti per un aspetto coerente. Hello Ocean imposta deliberatamente 16, 8, 12 e 0,9. Le impostazioni di trasparenza ridotta e colori forzati possono modificare il rendering finale.
Ogni colore deve essere un #RRGGBB a sei cifre; alpha, nomi CSS, variabili, URL e stili vengono rifiutati. Vengono rifiutati anche chiavi o modalità duplicate, elementi o attributi sconosciuti, namespace, DTD, entità e istruzioni di elaborazione. Dichiarazioni XML e commenti sono consentiti. Se l'importazione fallisce, controlla dimensioni del file, versione, completezza di entrambe le palette e valori supportati, poi riprova con il backup invariato. I temi di altri editor richiedono la conversione in questo formato DDS.
6. Esegui un workspace nel tuo ambiente
Esegui host, SDK, plugin e strumenti nel tuo ambiente WSL, container o server. I file del progetto restano nella radice che scegli. Il client SDK autonomo li legge e li modifica attraverso la connessione; riceve i metadati dei plugin e i risultati dei comandi, mentre il codice dei plugin viene eseguito nel tuo ambiente.
Nel progetto SDK creato sopra, salva questo helper come copy-workspace-example.mjs. Copia server, plugin, strumento e progetto di esempio modificabili, preservando la disposizione dei file di licenza dell'esempio.
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
Il progetto di esempio è user-host/examples/user-workspace/project. Avvia il server in quell'ambiente usando un token generato esplicito:
WSL / Linux / container
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
Il server stampa Workspace server: http://127.0.0.1:4777/dds/workspace/v1 insieme a un ID e a una generazione del workspace. Nel terminale del client, imposta DDS_WORKSPACE_TOKEN sul token generato. È una credenziale dell'operatore, distinta da un token DDS Account. Arresta il server di esempio con Ctrl+C.
Da un altro terminale nello stesso progetto, imposta DDS_WORKSPACE_TOKEN sullo stesso segreto ed esegui il client per sviluppatori:
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
Il client elenca i file di esempio ed esegue Ispeziona file di progetto per design.sv. Il risultato JSON include tool: "module-counter" e modules: 1, prodotti da un vero processo figlio. Aggiungi --edit al comando del client solo se vuoi che l'esempio aggiunga una nota al file di esempio.
Per usare il tuo progetto, passa la sua directory assoluta come ultimo argomento di server.mjs. Mantieni server, moduli dei plugin e strumenti installati nello stesso ambiente utente. server.mjs importa esplicitamente il plugin e associa il suo backend denominato a un eseguibile e ad argomenti fissi:
Associazione del backend in server.mjs
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
Sostituisci questa associazione con lo strumento installato approvato o con il tuo backend personalizzato. ctx.workspace.readFile e writeFile usano percorsi relativi alla radice selezionata; ctx.backends.invoke("module-counter", input, {signal}) richiama solo un nome di backend configurato. L'adattatore di processo invia JSON con limiti definiti su stdin e si aspetta JSON su stdout. Non usa comandi shell forniti dalla richiesta e non eredita variabili d'ambiente dall'host.
Per un server remoto, usa il tuo endpoint HTTPS autenticato o un tunnel privato che termini sul loopback locale. Configura l'associazione delle porte del container o TLS nel tuo ambiente. L'esempio si associa al loopback per impostazione predefinita; cambiare l'indirizzo di ascolto non aggiunge TLS. Plugin e strumenti attendibili vengono eseguiti con i privilegi del sistema operativo del processo host.
Consulta l'esempio di workspace utente e protocollo del workspace per configurazione del server, origini, revisioni dei file, annullamento e risultati con limiti definiti.
Funzionalità di linguaggio
SDK 0.7.0 offre completamento, informazioni al passaggio del puntatore, definizioni, riferimenti e simboli del documento in forma piatta. Dichiara ogni funzionalità nelle capabilities del manifesto v2, insieme alle autorizzazioni document.read e language.provide. L'host deve concedere esplicitamente entrambe le autorizzazioni. Salva questo esempio completo di informazioni al passaggio del puntatore come language-demo.mjs nel progetto creato sopra:
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
Il primo comando stampa A local LED signal. Il secondo esempio incluso verifica tutte e cinque le funzionalità usando un piccolo linguaggio didattico con let name = value; il provider proprio dell’esempio implementa quel linguaggio didattico.
Funzionalità | Input della richiesta | Dati del risultato |
|---|---|---|
|
| Fino a 500 elementi |
|
|
|
|
| Fino a 500 posizioni |
|
| Fino a 500 posizioni |
|
| Fino a 500 simboli |
Le posizioni usano righe con indice da zero e offset UTF-16. L'inserimento del completamento è testo letterale; le stringhe delle informazioni al passaggio del puntatore e dei dettagli sono testo semplice. Un host deve controllare file e intervalli di destinazione prima di seguire una posizione. Il risultato preserva l'identità della richiesta, del progetto/sessione e della versione del documento. Modifica dello snapshot, annullamento, timeout, rimozione della registrazione o rilascio terminano le richieste in sospeso e scartano i risultati tardivi.
Queste API operano nell’host autonomo attendibile dell’SDK. Usa un host SDK 0.3.0 o successivo per queste funzionalità di linguaggio e configura esplicitamente eventuali processi LSP tramite il bridge dedicato. Leggi Funzionalità di linguaggio per selettori, limiti e comportamento del ciclo di vita.
Sessioni di modifica del progetto
Importa createWorkspaceProject e applyTextEdits da @altifigence/dds-plugin-sdk/workspace-client. Dopo che l'host connette un createWorkspaceClient ed esamina identità, avviso e accesso del workspace, chiama createWorkspaceProject(client). Il progetto conserva l'associazione esatta della connessione. La riconnessione richiede un nuovo progetto sottoposto a revisione, anche quando tornano lo stesso ID e la stessa generazione del workspace.
API | Comportamento |
|---|---|
| Elenca una directory sotto la radice del workspace selezionata. |
| Legge un file e conserva contenuto immutabile e revisione in una sessione di modifica. |
| Crea solo se il file è assente, poi restituisce una sessione. |
| Legge l'ultimo |
| Salva solo se la revisione del server corrisponde ancora a quella conservata. |
| Applica modifiche |
| Legge esplicitamente gli ultimi contenuti e la revisione dopo un conflitto o una scrittura incerta. |
| Annulla il lavoro di propria competenza; il rilascio del progetto lascia connesso il client di proprietà del chiamante. |
Esegui l'esempio HTTP completo nel pacchetto installato. Crea un proprio workspace di esempio temporaneo, testa modifica, una seconda sessione in conflitto, ricaricamento esplicito, Unicode e riconnessione, poi chiude il server ed elimina la directory temporanea:
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs
Output previsto: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. Il sorgente dell'esempio mostra l'intera configurazione e pulizia di server e client.
Le opzioni accettano signal e timeoutMs. Una scrittura fallita dopo un tentativo lascia needs-reload; conserva separatamente eventuali bozze non salvate nell'interfaccia e ricarica esplicitamente prima di salvare di nuovo. L'SDK non unisce né ritenta automaticamente. Un timeout, un annullamento o una risposta persa possono verificarsi dopo che il server ha confermato la scrittura; annullare una richiesta lascia in vigore le modifiche già confermate. Ogni sessione consente un solo salvataggio o ricaricamento in sospeso.
Le modifiche al testo usano lo snapshot originale, righe con indice da zero e offset UTF-16. Sovrapposizioni, coppie di surrogati spezzate e intervalli non validi vengono rifiutati prima del salvataggio. I progetti consentono al massimo 64 sessioni aperte o in apertura e 500 modifiche per salvataggio. Questi helper usano il protocollo workspace v1 invariato, inclusi i server SDK 0.2.x, e mantengono le restrizioni della radice, dei percorsi protetti e della modalità di sola lettura. Leggi Progetti del workspace per i limiti di dimensione e ciclo di vita.
Riferimento API
Importa le API dei plugin da @altifigence/dds-plugin-sdk. Il pacchetto include dichiarazioni TypeScript per gli stessi elementi esportati.
API | Uso |
|---|---|
| Convalida il manifesto e dichiara la funzione di attivazione. |
| Registra |
| Costruisce un risultato convalidato usando l'identità della richiesta. |
| Registra un provider di linguaggio e costruisce un risultato con identità della richiesta convalidata. |
| Convalida versione del manifesto, identità, autorizzazioni, host supportati e modulo di ingresso. |
| Convalida URI, linguaggio, versione del modello, revisione del workspace e testo. |
| Convalida protocollo, richiesta, ambito, identità del documento e campi diagnostici. |
| Legge errori tipizzati, limiti delle risorse e versione del protocollo. |
Importa l'host per sviluppatori da @altifigence/dds-plugin-sdk/testing:
API dell'host di test | Uso |
|---|---|
| Crea un host locale. Entrambe le opzioni sono facoltative; le concessioni predefinite consentono lettura dei documenti e diagnostica. |
| Attiva il plugin e restituisce un'attivazione rilasciabile. |
| Imposta il documento corrente. Incrementa |
| Richiede la diagnostica a un provider corrispondente; entrambe le opzioni sono facoltative. |
| Richiede una funzionalità di linguaggio dichiarata con concessioni esplicite document.read e language.provide. |
| Rimuove le registrazioni e annulla il lavoro in sospeso; rilascia l'host quando il test termina. |
Le richieste includono requestId, scope di progetto/sessione e uno snapshot con uri, languageId, modelVersion, workspaceRevision e text. Usa createDiagnosticsResult per preservare questa identità. I risultati contengono un array diagnostics e omettono il testo sorgente.
Gli errori espongono un code, tra cui invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable e budget_exceeded. Il timeout predefinito delle richieste è 5 secondi; i timeout ammessi sono 1–30000 ms. Un documento è limitato a 262144 byte UTF-8 e un risultato a 500 diagnostiche. Leggi LIMITS per i limiti completi.
SDK 1.0.0 offre anche moduli separati. Le importazioni workspace e packaging disponibili solo in Node appartengono all'ambiente utente:
Importazione | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Confeziona e pubblica il tuo plugin
Inizia con il plugin pubblicabile incluso. Salva questo helper nel progetto SDK per copiarne i file in una nuova directory 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
Modifica plugin.json, plugin.mjs, disclosure.json e la licenza per descrivere il tuo plugin. L'informativa deve corrispondere a editore, ID del plugin, versione, licenza e visibilità del sorgente del manifesto. Elenca solo i file che intendi distribuire in dds-package.json:
dds-package.json
{
"schemaVersion": 1,
"files": [
"plugin.json",
"plugin.mjs",
"disclosure.json",
"LICENSE",
"NOTICE"
]
}
Convalida e confeziona l'esempio:
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist
Con i metadati dell'esempio invariati, pack crea dist/example-hello-publisher-1.0.0.tgz e dist/example-hello-publisher-1.0.0.tgz.release.json. Il JSON della release contiene SHA-256 dell'archivio finale, hash di manifesto e informativa e inventario dei file. Esamina questi file prima della distribuzione.
Nell'archivio entrano solo i file nell'elenco consentito, dds-package.json e i metadati npm generati. La convalida esamina i dati del pacchetto e il confezionamento crea l’archivio locale per il canale di distribuzione scelto. La CLI rifiuta configurazioni private, file di chiavi e percorsi collegati; esamina il contenuto dei file selezionati prima di condividerli.
Canale | Cosa fornire |
|---|---|
Release GitHub pubblica | Un archivio versionato, il relativo JSON di release esterno, la licenza e l'accesso ai sorgenti eventualmente richiesto. |
Registro privato o canale di download | Gli stessi file versionati, l'autorizzazione dei destinatari e le effettive condizioni del plugin. |
Il manifesto v2 dichiara runtime, le autorizzazioni richieste e source: {visibility, licenseFile, repository?}. Imposta la visibilità su open oppure closed e includi il vero file di licenza. Il codice di tua proprietà può usare condizioni open source o proprietarie; continuano ad applicarsi gli avvisi dell'SDK e delle dipendenze pertinenti. I destinatari ricevono il JavaScript eseguibile insieme ai metadati dichiarati di visibilità del sorgente e licenza.
Segui Pubblicazione e Licenze per i campi dell'informativa e i requisiti di distribuzione. Distribuisci l’archivio generato dall’SDK tramite il canale pubblico di release o il canale privato di download che scegli.
La CLI 1.2.1 registra >=1.0.0 <2.0.0 nei nuovi pacchetti di plugin. Gli archivi storici 0.3–0.13 e l'esatto 1.0.0-rc.1 conservano le dipendenze peer originali. Convalida e riconfeziona una nuova versione del plugin per l'installazione stabile; l’editore aggiorna esplicitamente l’intervallo delle dipendenze peer e i metadati della release durante il riconfezionamento.
Verifica un plugin scaricato
SDK 1.2.1 offre dds-plugin verify per gli esatti metadati dei plugin rilasciati 0.3.x–0.13.x, RC1 e della versione stabile corrente. Conserva insieme .tgz e .tgz.release.json. La verifica preserva la dipendenza peer originale. Controlla il pacchetto creato sopra:
Verifica l'esempio confezionato
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
Il comando verifica struttura gzip/tar con limiti definiti, elenchi consentiti esatti dei file, ogni hash dei file, manifesto, informativa, licenza e metadati npm generati. Rifiuta collegamenti, percorsi non sicuri o duplicati, file aggiuntivi e hook o dipendenze npm. Legge e convalida l’archivio locale sul posto come operazione sui dati. In caso di successo stampa una ricevuta JSON; in caso di rifiuto termina con codice 1.
Per download rinominati, usa --metadata con il JSON di release corrispondente. Ottieni lo SHA-256 previsto in modo indipendente attraverso un canale di release attendibile e passalo con --sha256 per vincolare i byte selezionati. L'API Node espone le stesse opzioni:
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);
Esegui verify-release.mjs con percorso dell'archivio, percorso dei metadati e hash minuscolo di 64 caratteri ottenuto indipendentemente come tre argomenti. checksumPinned è true solo quando l'hash fornito corrisponde. I limiti sono 12 MiB di input compresso, 10 MiB di contenuti dei file, 4 MiB per file, 256 file e 256 KiB di metadati esterni.
Il verificatore confronta i byte dell’archivio con i metadati abbinati. Ottieni l’hash previsto in modo indipendente da un canale di release attendibile per vincolare il confronto alla release scelta. L’host convalida separatamente l’editore, esamina il contenuto e la compatibilità dell’installazione DDS e concede autorizzazioni prima dell’esecuzione. Una ricevuta descrive i byte letti durante quella chiamata; ricontrolla i byte effettivi se il file può cambiare prima dell'uso. Gli archivi dei plugin esistenti 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 restano verificabili se rispettano la politica rafforzata sui file; l'installazione su 1.0 richiede comunque convalida da parte dell'editore e riconfezionamento. Rimuovi i file ora esclusi e pubblica una nuova versione del plugin se necessario. Questo verificatore riguarda i pacchetti di plugin DDS; i tarball npm dell'SDK usano lo SHA-256 della loro release.
Consulta Verifica degli archivi e l'esempio completo di confezionamento, verifica e alterazione.
Autorizzazioni, licenze e uso dei dati
Le autorizzazioni richieste in un manifesto sono distinte dalle concessioni dell'host che abilitano le operazioni. Fornisci agli utenti identità e versione del plugin, licenza effettiva, ambito del workspace e autorizzazioni richieste prima di abilitarlo. Spiega operatore del backend, dati inviati, finalità, conservazione e informativa sulla privacy prima di connettere quel backend.
Registrazione | Significato |
|---|---|
| Una decisione di accesso dell'host per l'esatto pacchetto, workspace e insieme di autorizzazioni. |
| Un utente ha confermato di aver letto un avviso informativo. |
| Un utente ha scelto se accettare le condizioni effettive dell'editore del plugin. |
| Una scelta separata quando il trattamento facoltativo si basa sul consenso. |
Un’approvazione del workspace SDK registra una decisione tecnica di accesso. Registra l’accettazione delle condizioni del plugin e il consenso facoltativo sui dati personali come scelte distinte. L’SDK è concesso in licenza Apache-2.0; consulta licenza e avvisi per le condizioni dell’SDK.
Gli sviluppatori degli host possono conservare un avviso versionato con gli helper asincroni portabili. Per esempio, salvalo come notice.mjs ed esegui 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 vincola un sottoinsieme di autorizzazioni richieste a manifesto v2, hash dell'artefatto e del manifesto, generazione del workspace, identità dell'host, avviso e scadenza. isPermissionGranted valuta le identità correnti e gli eventi di revoca forniti dall'host. revokeConsentReceipt crea un evento separato; l'host deve quindi interrompere le future chiamate autorizzate.
Questi helper convalidano registrazioni locali. L'host fornisce la scelta effettiva dell'utente, identità, archiviazione e applicazione delle regole. Leggi Autorizzazioni e consenso per i campi esatti e l'esempio interattivo sulle autorizzazioni per una dimostrazione esplicita di concessione, rifiuto e revoca. L’host mantiene gli accordi con gli editori e le relative registrazioni nel flusso applicativo che sceglie.
Sorgenti, release e contributi
Il repository ufficiale dell'SDK contiene sorgenti, schemi, esempi e test dei contratti. Per eseguire dai sorgenti l'esempio rilasciato e i test dell'SDK:
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
Segnala i bug dell'SDK tramite GitHub Issues, indicando versione dell'SDK e una riproduzione minima. L'SDK è distribuito con licenza Apache-2.0; consulta licenza e avvisi del repository. Usa la pagina delle release per archivi versionati e note di rilascio.
Questo repository è l’SDK pubblico per sviluppatori. La release contiene i file dichiarati dell’SDK, schemi, esempi e avvisi nel suo ambito pubblico. I controlli dei pacchetti applicano l'esatto inventario dei file pubblicati e rifiutano schemi noti di segreti e percorsi privati. Esamina il contenuto effettivo della release per individuare informazioni sensibili insieme a questi controlli basati su schemi.
Aggiornamenti di sicurezza e limiti degli host
Aggiorna sia il server del workspace sia il client SDK alla 0.3.2 o successiva. Installa l’aggiornamento del server per attivare i controlli dei file e i limiti delle richieste migliorati. Riavvia l'host aggiornato, esamina la nuova generazione e ottieni nuovamente l'approvazione prima di usare il workspace.
L'host workspace Node rifiuta collegamenti fisici che potrebbero riferirsi a file protetti o esterni alla radice selezionata. Copia un file di progetto intenzionalmente condiviso in un file regolare con un unico collegamento. Anche archivi di credenziali come .netrc, _netrc, .git-credentials, .gnupg, .kube e .docker, ulteriori nomi di chiavi SSH e alias dei dispositivi Windows sono bloccati. Confezionamento e verifica dei download applicano la corrispondente politica sui nomi delle credenziali.
Risorsa del server | Limite |
|---|---|
Corpi in ingresso simultanei | 16; ulteriori caricamenti ricevono HTTP 429 prima dell'inoltro |
Richieste in esecuzione | 64; l'annullamento usa un percorso di inoltro separato |
Connessioni / richieste per socket | 128 / 128 |
Richiesta e risposta / contenuto del file | 1600000 / 262144 byte UTF-8 |
Il client annulla risposte rifiutate non lette e flussi bloccati alla scadenza o all’annullamento. Un timeout dopo l’inizio di una scrittura può lasciarne incerto il risultato: rileggi il file prima di ritentare. Esamina il contenuto per individuare segreti insieme alle esclusioni esplicite dei percorsi ed esegui plugin attendibili con un accesso al sistema operativo del processo host scelto deliberatamente. Usa la guida all'aggiornamento di sicurezza e limiti del workspace durante il deployment di un host.
Strumenti di sviluppo
Dopo aver installato SDK 1.2.1 come sopra, crea un progetto separato di plugin di comando. Scegli una nuova destinazione per i file generati; installa le dipendenze ed esegui il plugin esplicitamente dopo la generazione della struttura. La struttura generata include un comando, test, manifesto, informativa, dipendenza SDK fissata e 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 legge i metadati e controlla Node, risoluzione dell'SDK, manifesto, licenza, informativa e file del pacchetto nell'elenco consentito senza importare il plugin. Gli errori producono stato di uscita 1; i valori di esempio per editore e supporto producono avvisi. Sostituiscili ed esamina le licenze prima della distribuzione.
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 richiede --trust-local-code. Esegue importazioni e attivazione di codice locale attendibile in un processo figlio e osserva solo i file consentiti più dds-package.json. Ogni esecuzione ha una scadenza e un limite di 256 KiB per stdout/stderr. Ctrl+C interrompe l'osservazione e ripulisce l'albero dei processi. Il processo figlio attendibile eredita il tuo ambiente e usa l’accesso al sistema operativo del tuo processo. L’host di test predefinito concede lettura dei documenti e pubblicazione dei diagnostici. Configura un host workspace separato con concessioni esplicite per workspace/backend per queste integrazioni.
Usa --job per stampare avanzamento e log dei job; usa --timeout-ms per impostare fino a 30 secondi per i comandi ordinari o 30 minuti per i job. Le API Node sono initPlugin, doctorPlugin e runPluginDev in /devtools. Consulta la guida agli strumenti di sviluppo per comportamento dell'osservazione e limiti della pulizia.
Job di comando di lunga durata
Abilita jobs: true su un host/server SDK 0.4.0 per eseguire comandi oltre la normale scadenza delle richieste. I job sono disabilitati per impostazione predefinita. Prova l'esempio HTTP locale completo, che segnala avanzamento, un log del backend denominato e un file di risultato vincolato tramite hash:
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs
Output previsto: Command job: progress, backend log and pinned result file verified. Un gestore di comando riceve job facoltativo in {signal, job}. Offre reportProgress, log, addArtifact e invokeBackend. Le concessioni workspace.read/write e backend.invoke esistenti continuano ad applicarsi; non è accettato alcun percorso arbitrario di eseguibile.
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);
}
Il frammento di polling presuppone un client connesso e un comando analyze configurato che registra report. Conserva l'ID del job prima di iniziare. Disconnettersi o interrompere una richiesta di polling non annulla l'esecuzione; riconnettiti alla stessa generazione e interroga o annulla esplicitamente. Nuovi avvii con lo stesso ID e input riutilizzano il job conservato; argomenti cambiati causano un conflitto. Il riavvio dell'host perde i record in memoria. Abilita l'archivio persistente separato 0.8 descritto sotto per recuperare i metadati confermati dopo il riavvio.
Gli stati sono running, succeeded, failed, cancelled e timed_out. L'output tardivo viene scartato dopo l'annullamento; gli effetti collaterali non vengono annullati. I provider non terminati mantengono i loro slot. Sono consentiti al massimo 4 job simultanei, 32 record conservati, 32 operazioni annidate per job, 256 eventi/64 KiB per job, 64 eventi per pagina e 16 artefatti. La durata predefinita è 5 minuti, con un massimo di 30 minuti. I record terminali conclusi scadono 15 minuti dopo il loro ultimo evento.
I file di risultato testuali sono UTF-8 relativi al workspace fino a 256 KiB. L'host li legge con la concessione esistente, registra SHA-256 e rifiuta le letture successive se i byte sono cambiati. Per output di simulazione binari o più grandi, usa l'API dei risultati binari. Artefatti parziali possono restare dopo l’annullamento; controlla lo stato terminale del job per confermarne il successo. I vecchi client 0.3 continuano a usare i metodi v1 esistenti; i job autonomi dell’SDK richiedono 0.4 su entrambi i lati. Consulta Job per contratti e limiti esatti.
Osserva i file del workspace
project.watchFiles() campiona 1–16 percorsi di file relativi espliciti. SDK 1.0.0 usa richieste di sola revisione sugli host che le supportano e le letture limitate esistenti sugli host più vecchi. L'esempio presuppone un client connesso e approvato dall'host. Modifica design.sv con un editor esterno per terminare il ciclo; lo snapshot di modifica conservato resta invariato.
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(); }
Gli eventi sono immutabili {kind, path, previousRevision, revision}. Il primo campione emette initial; le modifiche successive emettono created, changed o deleted. I file mancanti hanno revision null. includeInitial: false registra silenziosamente la situazione iniziale e revisioni uguali non producono eventi. Solo not_found indica eliminazione; errori di autorizzazione, percorso protetto, dimensioni e trasporto terminano l'osservazione.
Conserva separatamente il testo non salvato nell’interfaccia e scegli azioni esplicite di ricaricamento, unione e salvataggio delle bozze. Un salvataggio verifica la revisione conservata e può segnalare un conflitto. L’osservazione campiona i percorsi espliciti dei file uno alla volta, in ordine; le modifiche intermedie possono accorparsi. Usa le API di osservazione dei progetti sotto per rilevamento e sottoscrizioni alle directory con ambito definito. Le restrizioni esistenti su radice, dimensioni dei file e percorsi protetti si applicano ai server di sola lettura e scrivibili.
Gli osservatori di file e job iniziano al primo next(), non recuperano pagine in background mentre il consumatore è in pausa e condividono un massimo di otto osservatori attivi per client. Può essere in sospeso un solo next(); una lettura simultanea fallisce con conflict. break o return() fermano le letture in sospeso; il rilascio del progetto ferma i suoi osservatori di file e disconnessione, riconnessione o rilascio invalidano tutti i vecchi osservatori. AbortSignal termina l'osservazione con cancelled; le risposte tardive non possono produrre risultati.
intervalMs è 250–60000 ms (predefinito 1000), applicato tra passaggi sui file o letture inattive dei job. requestTimeoutMs è 1–30000 ms per richiesta, con la scadenza del client come valore predefinito. timeoutMs totale è 1–1800000 ms dal primo next(), comprese le pause del consumatore. Per impostazione predefinita i file non hanno timeout totale; i job hanno 30 minuti. Le scadenze segnalano budget_exceeded e liberano lo slot. Questi limiti sono esportati come WORKSPACE_OBSERVATION_LIMITS.
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs
Output previsto: Workspace observation: file changes, retained draft and resumed job verified. L'esempio completo crea un proprio workspace temporaneo e verifica modifiche ai file, conflitti delle bozze e ripresa esplicita dei job. Consulta Osservazione per tutte le opzioni e le regole di durata.
Osserva e riprendi i job
client.watchJob() segue un job esistente tramite jobs.events/get; waitForJob() restituisce il suo snapshot terminale. Il frammento presuppone un client connesso, un jobId avviato esplicitamente e un savedCursor (o undefined). Controlla getJobCapabilities() prima di avviare un job. L'osservazione non avvia, ritenta né annulla mai il comando.
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);
Ogni aggiornamento congelato contiene snapshot, events, after, nextCursor, dropped e hasMore. Gestisci al massimo 64 eventi per pagina e registra nextCursor dopo l'elaborazione, insieme a ID del job e identità del workspace. dropped segnala cronologia scaduta. Uno snapshot può essere più recente della sua pagina di eventi; continua a leggere gli snapshot terminali mentre hasMore è true. L'iteratore termina dopo l'ultima pagina. waitForJob() esaurisce le stesse pagine e restituisce succeeded, failed, cancelled o timed_out; esamina lo stato invece di considerare ogni promessa risolta un successo.
Fermare un iteratore o raggiungere il timeout interrompe solo l'osservazione. Il comando server continua fino al completamento o a una chiamata esplicita cancelJob(). Dopo una riconnessione approvata dall'host, verifica lo stesso ID e la stessa generazione del workspace, poi crea un nuovo osservatore con l'ID del job e il cursore salvati. I vecchi osservatori non sono validi anche se l'identità è invariata. Job mancanti o scaduti e guasti di trasporto vengono segnalati senza reinvio; i job in memoria non sopravvivono al riavvio dell'host. Il recupero persistente usa recoverJob() con una nuova connessione; gli osservatori attivi non riprendono tra generazioni diverse.
I contratti hello v1 e dei job esistenti restano invariati. L’osservazione dei file usa il fallback sugli host 0.3.2/0.4/0.5; quella dei job richiede un host 0.4 o successivo abilitato. Una funzionalità job disabilitata o non supportata restituisce un errore e preserva la scelta del chiamante sull’esecuzione dei comandi nell’host autonomo dell’SDK. Consulta Osservazione e Compatibilità.
Revisioni dei file e letture condizionali
SDK 0.6.0 aggiunge getFileCapabilities(), getFileRevision(path) e readFileIfChanged(path, knownRevision) ai client connessi. Le letture di revisione restituiscono {path, revision} senza contenuto. Una lettura condizionale corrispondente restituisce {path, revision, notModified: true}; un contenuto cambiato restituisce notModified: false e content. Passa knownRevision: null per il contenuto corrente. I file mancanti vengono rifiutati con 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);
Usa un client già connesso e autorizzato. Mantieni le bozze non salvate separate da questa cache. Le letture condizionali calcolano l'hash e restituiscono uno snapshot del file; una lettura successiva può osservare un'altra modifica. Salva con la revisione del contenuto restituito. Queste chiamate non aggiornano gli snapshot delle sessioni di modifica né uniscono bozze. Una risposta invariata non ha campo content; un file cambiato vuoto ha content: “”.
L'osservazione dei file usa automaticamente letture di sola revisione quando supportate. I metodi facoltativi fs.capabilities, fs.revision e fs.readIfChanged preservano hello v1 rigoroso e i metodi originali dei file. Gli host workspace SDK noti precedenti alla 0.6 usano fs.read senza sondaggio. Gli altri host devono rispondere al rilevamento o restituire un errore unsupported correttamente correlato. Ogni funzionalità false seleziona il proprio fallback di lettura completa limitata; la risposta del vecchio server trasferisce comunque l'intero contenuto.
Le funzionalità vengono memorizzate nella cache solo per la connessione corrente e azzerate alla riconnessione o revoca. Risposte non valide, discrepanze di percorso/revisione, autorizzazioni, autenticazione, guasti di trasporto e timeout non attivano il fallback. Le operazioni dichiarate che poi falliscono non vengono declassate silenziosamente. AbortSignal copre rilevamento e lettura; timeoutMs si applica a ogni richiesta HTTP. Un cambio di connessione invalida la vecchia operazione.
Il server esegue ancora una lettura completa protetta e il calcolo SHA-256 del file per ogni campione. Convalida UTF-8, limite di 262144 byte e controlli di percorsi protetti e collegamenti restano in vigore. Questo riduce i byte delle risposte di rete mantenendo le letture protette del disco e il calcolo dell’hash per ogni campione. Una misurazione locale su Windows con Node 22.23.1 di 20 campioni invariati da 200000 byte ha restituito 4003974 byte per letture complete, 3867 per revisioni (99,903% in meno) e 4247 per letture condizionali (99,894% in meno). Il rilevamento è incluso; intestazioni HTTP, TLS e la base iniziale hello/contenuto sono esclusi. Esegui npm run benchmark:files in un checkout per riprodurre il caso di test.
L’SDK ha ora un’API stabile 1.x con controlli funzionali documentati nella release. I client esistenti 0.3.2, 0.4, 0.5 e 0.6 mantengono le proprie API originali sugli host 0.7. Queste regole di compatibilità descrivono client e host autonomi dell’SDK. Consulta Revisioni dei file per il contratto completo e le regole di migrazione.
Risultati dei job di grandi dimensioni e binari
SDK 0.7.0 aggiunge un'estensione facoltativa per file di risultato binari. Un comando attendibile registra un file esistente del workspace; l'host ne registra SHA-256 e lunghezza. I client leggono al massimo 64 KiB per blocco e il downloader Node riprende un file parziale e verifica l'intero output. Il file registrato massimo è 1 GiB; le API esistenti per file UTF-8 e artefatti testuali di 256 KiB mantengono i propri limiti.
Abilita jobs: true e binaryArtifacts: true sull'host dei plugin di proprietà del server. Entrambi sono false per impostazione predefinita. Mantieni token esplicito, avviso dell'operatore, vincolo dell'artefatto del plugin revisionato e concessione workspace.read effettiva. Quanto segue si basa sulla configurazione del workspace sopra; i workspace di sola lettura possono registrare file già generati dallo strumento configurato dall'operatore.
Javascript
const server = await createWorkspaceServer({
root, workspaceId, token, notice,
plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'],
jobs: true, binaryArtifacts: true, writable: false,
});
Registra il risultato in un comando avviato con startCommandJob. La registrazione fa passare il file esistente attraverso SHA-256 con un buffer di 64 KiB. Il riferimento punta a quel file sorgente, non a una copia immutabile. Percorsi protetti, attraversamento delle directory, collegamenti e file non regolari vengono rifiutati; successive modifiche al sorgente falliscono con 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};
});
Usa un client già connesso e autorizzato e un ID di job esistente. La destinazione è un percorso assoluto in una directory reale esistente controllata dal chiamante. L'helper scrive destination + “.dds-part” e rifiuta di sovrascrivere un file finale esistente.
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);
Conserva l'intero riferimento {jobId, scope, artifact}. Dopo un'interruzione, riconnettiti esplicitamente alla stessa generazione dell'host e richiama l'helper con quel riferimento e resume: true. Ricalcola l'hash del prefisso salvato e richiede solo il suffisso mancante. Verifica SHA-256 di ogni blocco, dell'intero flusso ricevuto e del file di staging effettivo prima della pubblicazione. La ricevuta finale verified: true conferma il completamento; i callback sincroni di avanzamento restano non verificati. I file parziali corrotti richiedono rimozione esplicita o una nuova destinazione.
listJobBinaryArtifacts(jobId) restituisce metadati binari registrati separatamente dai risultati testuali esistenti. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) restituisce base64 canonico con SHA-256 del blocco, intervallo esatto e marcatore EOF. decodeBinaryArtifactData da /artifacts restituisce byte Uint8Array. I consumatori nel browser devono verificare autonomamente l'hash dell'intero file; i controlli dei singoli blocchi non provano che l'output assemblato corrisponda al riferimento.
Risultati binari e testuali condividono 16 slot e uno spazio di nomi per gli ID per job. Le operazioni di acquisizione/lettura binaria sono limitate a quattro per host/workspace e i download Node a quattro per processo. timeoutMs del download Node è una scadenza totale, predefinita al massimo di 30 minuti; requestTimeoutMs è predefinito a 5 secondi con massimo 30 secondi. La pubblicazione richiede supporto dei collegamenti fisici, come NTFS o ext4. Usa una destinazione controllata dal chiamante e un processo host attendibile; impedisci scritture simultanee ostili nella directory di destinazione mediante i controlli di accesso del sistema operativo.
I metodi facoltativi artifacts.capabilities, artifacts.list e artifacts.read preservano hello v1, snapshot dei job ed eventi esistenti. Gli host precedenti alla 0.7 segnalano l'estensione disabilitata; l’operazione binaria richiesta termina con tale risultato della funzionalità. Autenticazione, risposte malformate ed errori di trasporto restano errori. Riconnessione, revoca, scadenza del job o nuova generazione dell'host invalidano le vecchie operazioni. La conservazione dei job resta in memoria per 15 minuti dall'ultimo evento del job terminale. I job annullati possono lasciare output parziali registrati degli strumenti; conferma il successo in base allo stato terminale del job. Quanto descritto riguarda le API predefinite attive/sorgenti. L'API separata dei risultati archiviati sotto conserva i byte attraverso i riavvii.
Esegui npm run example:artifacts per un vero trasferimento di 2 MiB con interruzione, riconnessione e ripresa del solo suffisso; npm run benchmark:artifacts usa 8 MiB. Un'esecuzione locale Windows ha trasferito 8388625 byte in 129 richieste di blocchi, riprendendo un prefisso di 65536 byte e verificando lo SHA-256 finale. Base64 aggiunge overhead; i corpi JSON delle risposte hanno totalizzato 11257419 byte. I trasferimenti usano memoria limitata e blocchi codificati. Consulta Artefatti binari per il contratto completo. L’esempio esercita le API autonome di trasferimento dell’SDK.
Job persistenti, cronologia e nuovi tentativi espliciti
SDK 0.8.0 aggiunge archivi persistenti facoltativi in una directory dell'operatore esterna al workspace. Fornisci percorsi assoluti, ID stabile del workspace, codice del plugin revisionato, SHA-256 del pacchetto, token e avviso. L'esempio abilita anche la conservazione dei byte dei file; ometti artifacts da jobStorage per archiviare solo i metadati dei job. Le risposte v1 esistenti e i valori predefiniti solo in memoria restano compatibili.
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 provider inizia solo dopo il salvataggio del suo intento iniziale. I checkpoint successivi vengono accorpati; flushJobStore() attende i checkpoint richiesti, non il completamento del comando. Il recupero separa la connessione corrente dall'ambito dell'esecuzione originale e segnala live, completed, interrupted, expired, missing, corrupt o unsupported. Un job interrotto non riparte mai automaticamente; il suo unrecordedTail è sconosciuto.
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()});
La cronologia filtra per stato, esito del recupero, comando, ora di inizio e tentativo padre. Le pagine contengono fino a 32 voci, ordinate per ora di inizio decrescente e poi ID del job. Un cursore congela l'insieme per 60 secondi e deve riutilizzare la stessa query; nuovi job sono esclusi, record eliminati o non autorizzati sono saltati e la scadenza viene segnalata. Il riavvio perde i cursori. artifactCount, snapshotCount e resultAvailability descrivono riferimenti registrati, non prove dei file correnti.
Un nuovo tentativo esplicito richiede un nuovo ID del job, nuovi input convalidati, lo stesso pacchetto attualmente approvato e un comando disponibile. attemptOf collega la nuova esecuzione al padre invariato. Ripetere gli stessi ID, input, padre e timeout recupera il tentativo conservato senza rieseguirlo, anche dopo un riavvio. I record mancanti o scaduti non possono offrire questa garanzia. Un'esecuzione accettata può proseguire dopo l'annullamento della richiesta in attesa; interroga il nuovo ID del job prima di decidere se ritentare.
La conservazione predefinita omette input grezzi, corpi dei risultati, testo di avanzamento ed etichette degli artefatti; i log sono oscurati. Solo un redattore deterministico esplicito dell'host conserva testo revisionato. Token, segreti e consensi precedenti non vengono mai ripristinati. Identità corrente di workspace/plugin, autorizzazione di lettura e ogni concessione registrata vengono ricontrollate. I metadati dei job hanno valori predefiniti di 256 record, 64 MiB e 24 ore, con massimo sette giorni. Rimozione e pulizia sono operazioni esplicite dell'host.
L'archivio locale ha un solo scrittore, convalida identità di workspace/radice e verifica l'integrità dei metadati. Il recupero esplicito di un blocco obsoleto recupera solo un PID della stessa macchina dimostrabilmente terminato. I file sconosciuti o corrotti richiedono ispezione. Su Windows, sincronizzazione e rinomina dei file consentono il recupero dopo il riavvio del processo; la persistenza dipende dal filesystem e dal dispositivo di archiviazione. Consulta Archiviazione dei job, Cronologia e l'esempio durable-jobs.
Risultati archiviati e download dopo il riavvio
Con l'archivio degli artefatti abilitato, await job.addArtifact() o job.addBinaryArtifact() copia e verifica l'intero file prima della registrazione. Il testo resta limitato a 256 KiB; i file binari sono al massimo 1 GiB. Flusso sorgente e file di staging effettivo vengono verificati con SHA-256. Annullamento, errori di disco pieno, modifiche e scritture parziali non pubblicano risultati utilizzabili. File pubblicati prima di un arresto anomalo ma non registrati dal job possono restare per l'ispezione dell'operatore.
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);
L'elenco distingue riferimenti al sorgente e metadati degli snapshot e segnala snapshot retained, expired, missing, corrupt o unsupported. retained è uno stato dei metadati; getStoredJobArtifact() verifica metadati e intero file archiviato prima di restituire un riferimento nuovo della generazione corrente. Ogni lettura ricontrolla autorizzazioni correnti e identità del file. Sorgenti eliminati non influenzano i byte archiviati e snapshot mancanti non ricorrono mai a un sorgente modificabile. Per gli snapshot testuali chiama client.readStoredJobArtifactText(textReference).
Dopo un riavvio, riconnettiti con concessioni correnti e ottieni un nuovo riferimento. ID dello snapshot, ID dell'archivio e digest restano stabili; la vecchia generazione viene rifiutata. resume: true ricontrolla un prefisso .dds-part salvato rispetto a quello snapshot, verifica blocchi e intero file di staging e pubblica senza sovrascrivere la destinazione. Le letture richiedono metadati dei job conservati e byte dei file. I consumatori di blocchi nel browser devono verificare il digest completo; l’adattatore Worker sotto fornisce ripresa esplicita su disco nel browser.
L'archiviazione degli artefatti ha valori predefiniti di 256 file, 256 MiB e 24 ore, con archiviazione totale massima di 4 GiB e conservazione di sette giorni. I blocchi sono al massimo 64 KiB, con quattro letture simultanee. inspect() segnala utilizzo, scadenze, voci non valide e file orfani. remove(snapshot) e prune() sono operazioni esplicite dell'operatore. Job attivi e singole letture vengono mantenuti; scadenza o rimozione tra blocchi può fermare la lettura successiva. La pulizia facoltativa degli orfani rimuove solo file riconosciuti con un unico collegamento. Voci corrotte o ambigue richiedono ispezione.
La conservazione dei file archivia i byte effettivi del progetto indipendentemente dall'oscuramento dei log. Sceglila deliberatamente. Plugin/comando correnti, hash del pacchetto, workspace e concessioni registrate restano richiesti dopo il riavvio. Completa la manutenzione, poi attendi server.close(), artifacts.close() e store.close(), in quest'ordine. Questa release fornisce operazioni di conservazione dei file per gli host autonomi dell’SDK.
Esegui npm run example:stored-artifacts per un vero riavvio di un processo figlio, eliminazione del sorgente, ripresa verificata di un download parziale, cronologia e nuovo tentativo esplicito. npm run example:durable-jobs copre anche la terminazione forzata del processo. Consulta Risultati archiviati. Gli host noti 0.7 e precedenti segnalano l'archiviazione disabilitata senza sonde sconosciute. Le API attive/sorgenti esistenti mantengono il comportamento originale.
Osserva un progetto
L’operatore abilita esplicitamente i progetti e seleziona le radici consentite sul server autonomo dell’SDK. Questa configurazione ad attivazione esplicita usa filesystem locali Windows/Linux. Gli host SDK noti 0.3–0.8 segnalano direttamente l’indisponibilità della funzionalità e preservano il comportamento di rilevamento esistente. Usa l’esempio con il profilo supportato dei filesystem locali.
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();Il primo evento è uno snapshot completo. Le modifiche successive contengono delta rispetto a una revisione precedente; indicazioni perse, modifiche durante la scansione iniziale, scansioni incomplete e sovraccarico dovuto a un consumatore lento producono una vista completa di risincronizzazione con una motivazione. Le rinomine possono apparire come eliminazione/creazione. Ogni file viene verificato nel proprio momento di lettura; lo snapshot rappresenta tali stati campionati, con le scritture intermedie accorpate come descritto sopra.
Server e client consentono ciascuno quattro sottoscrizioni, con quattro eventi in coda per sottoscrizione nativa. La durata predefinita inattiva è 30 secondi; una lettura successiva può restituire not_found. Dopo una pausa lunga, crea un nuovo iteratore per uno snapshot iniziale. break/return, annullamento e rilascio liberano le sottoscrizioni; se una connessione interrotta impedisce la pulizia, le risorse remote rimanenti scadono con la loro durata.
I limiti predefiniti della scansione sono profondità 8, 512 voci, 1 MiB per file, 16 MiB totali e 10 secondi. I massimi configurabili sono profondità 32, 1000 voci, 16 MiB per file, 64 MiB totali e 30 secondi. I file limitati possono avere metadati senza hash del contenuto; controlla complete e reasons. Le scadenze vengono verificate tra chiamate al filesystem; scegli deliberatamente l’accesso al sistema operativo del processo host per queste chiamate.
Albero del progetto e ricerca
listTree restituisce un albero, searchFiles cerca nei nomi relativi dei file una sottostringa letterale o un glob limitato, e searchText trova testo letterale nei file UTF-8. root è obbligatorio; include/exclude sono relativi a esso. Le query usano le modalità documentate di testo letterale o glob. La corrispondenza senza distinzione tra maiuscole e minuscole normalizza solo ASCII A–Z affinché le posizioni UTF-16 originali restino stabili.
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);Le corrispondenze testuali includono SHA-256 del contenuto, intervallo UTF-16 con indice da zero e frammento limitato. Un cursore congela l'insieme originale per al massimo 60 secondi e richiede la stessa query. Le pagine successive ricontrollano il contenuto corrente e contrassegnano gli elementi current, changed, missing o unverified; i nuovi file appaiono solo in una nuova query. Corrispondenza e revisione acquisite restano invariate.
I file testuali sono limitati a 256 KiB, le query a 256 unità UTF-16 e i frammenti a 512 unità. I valori predefiniti sono 256 risultati (massimo 512), 32 elementi per pagina (massimo 64) e una risposta di 64 KiB (massimo 128 KiB). File binari, UTF-8 non valido e limiti di byte/profondità/tempo/risposta vengono segnalati come risultati incompleti con motivazioni. Vi sono due query simultanee e otto viste con cursore conservate; rilascia esplicitamente i cursori inutilizzati.
Bozze del progetto e riconnessione
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();Quando snapshotRevision di una query differisce da snapshot.revision osservata, rilascia il vecchio cursore e ripeti la stessa query di radice/filtro. L'osservazione non modifica mai edit.snapshot né il contenuto delle bozze del chiamante. Dopo una modifica, uno spostamento o un'eliminazione esterni, la condizione CAS originale segnala un conflitto; il chiamante sceglie un ricaricamento, un'unione o un salvataggio separato espliciti.
Il client verifica generazione della connessione, radice/filtro, hash della query, posizioni delle pagine, SHA-256 dello snapshot e continuità degli eventi. Le risposte tardive vengono scartate dopo revoca, disconnessione o riconnessione. I cursori di osservazione e quelli di query sono separati e non vengono ripristinati automaticamente. server.revokeProjects() termina l'accesso ai progetti; la riabilitazione richiede una nuova generazione del server.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browserGli esempi Node installati verificano creazione, ricerca, modifiche esterne, bozze conservate, conflitti CAS e riconnessione. Per l'esempio browser, apri l'URL loopback stampato e scegli Esegui scenario. Usa solo il proprio workspace temporaneo, eliminato quando il server dell'esempio si arresta. Le richieste HTTP hanno un valore predefinito di cinque secondi; configura deliberatamente i timeout di client e server per scansioni più grandi.
Osservazione del progetto · Contratti di albero e ricerca · Strumenti HTTP per i progetti
Trasmetti e verifica gli artefatti nel browser
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'helper compatibile con il browser riceve al massimo un blocco di 64 KiB alla volta, attende il destinatario selezionato e calcola incrementalmente l'hash dell'intero file. Convalida intervalli esatti, identità, base64 e hash di ogni blocco prima di scrivere. Un destinatario con rilettura rilegge poi indipendentemente i byte salvati; verification è stored solo dopo la corrispondenza di entrambi gli hash completi. Senza rilettura, verification è received e storedSha256 è null. L'avanzamento che raggiunge tutti i byte non equivale al completamento.
L’applicazione apre gli eventuali selettori, sceglie handle di file o directory OPFS, concede le autorizzazioni e fornisce la destinazione esatta agli adattatori SDK. I destinatari scrivibili asincroni per file/OPFS mantengono lo staging fino alla chiusura e lo scartano in caso di errore prima del commit. Per file parziali sicuri al ricaricamento, usa l'adattatore Worker dedicato sotto. I limiti sono 1 GiB per file, quattro flussi diretti simultanei e una scadenza totale di 30 minuti.
Carica file selezionati
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.I caricamenti sono disabilitati per impostazione predefinita. L'operatore configura un workspace Node locale, una directory di staging isolata, radici consentite e un unico principal, poi concede al plugin selezionato workspace.write per l'esatto hash vincolante dell'archivio. L'helper calcola preventivamente l'hash del sorgente selezionato. Il server accetta blocchi sequenziali di 64 KiB, verifica duplicati e contenuto completo e conferma solo dopo i controlli condizionali della destinazione. Nessun byte di staging appare negli elenchi ordinari del workspace.
expectedRevision: null richiede una destinazione assente; uno SHA-256 richiede la corrispondente destinazione corrente. L'annullamento conserva il prefisso confermato dal server. Una nuova operazione recover esplicita interroga le autorizzazioni correnti, convalida lo stesso sorgente e la stessa specifica e riprende solo il prefisso corrispondente. Una risposta di commit persa è incerta finché non viene interrogata; non autorizza a ripetere il commit o ripristinare un file. I massimi sono 1 GiB per file, 4 GiB per archivio e quattro sessioni attive; i valori predefiniti sono inferiori. Gli host noti 0.3–0.9 segnalano caricamenti disabilitati senza sondare nuovi metodi.
Pianifica i trasferimenti di file
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();Una coda di proprietà del chiamante combina job di caricamento, download attivi e download archiviati. Limita job conservati (32), fasi simultanee (4), concorrenza delle connessioni client, prenotazioni di blocchi decodificati (64–256 KiB), velocità e nuovi tentativi. Il lavoro idoneo può avanzare nonostante una connessione satura e anticipi di priorità limitati evitano che piccoli job idonei restino senza risorse. Un job in pausa termina la fase corrente e poi attende; la pausa può conservare un blocco di archiviazione. Le scadenze totali includono attesa in coda e pausa.
I nuovi tentativi automatici sono limitati a 429/503 riconosciuti dall'SDK, perdita di rete o timeout della richiesta durante un'operazione idempotente su un blocco esatto, con attesa progressiva limitata e variabilità casuale. Errori di begin/commit, autorizzazione, checksum, intervallo, sorgente o destinatario restituiscono il controllo al chiamante per una decisione esplicita sul recupero. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes e remainingBytes sono distinti; solo una ricevuta verificata produce completed. Un file già confermato rimane confermato dopo cancel/dispose.
Riprendi i download nel browser
// 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.Il recupero persistente richiede un Worker dedicato, accesso sincrono OPFS e Web Locks. Il chiamante riseleziona directory e UUID del file parziale dopo il ricaricamento e ottiene un nuovo riferimento archiviato approvato. Il destinatario conserva due nomi esatti di file dati/metadati, l'identità completa immutabile dello snapshot, la scadenza e gli hash del prefisso corrente e precedente. Non conserva token, concessioni né ambito della vecchia connessione. Ogni blocco di dati viene sincronizzato prima della chiusura del piccolo flusso di metadati.
Destinatario e helper ricalcolano indipendentemente l'hash del prefisso. Una coda priva di checkpoint viene tagliata solo dopo la corrispondenza del prefisso registrato. Metadati oltre la dimensione reale del file possono ricorrere al checkpoint precedente solo se byte e hash corrispondono; corruzione, voci mancanti, scadenza o snapshot diverso falliscono senza riavvio silenzioso. Un blocco esclusivo per l'intera origine rifiuta un'altra scheda, resta acquisito durante la rilettura e viene rilasciato alla chiusura o terminazione del Worker. La riapertura richiede quindi recupero esplicito.
I metadati locali sono limitati a 16 KiB e quattro sessioni aperte del destinatario. La conservazione predefinita è un'ora, con massimo 24 ore limitato dalla scadenza dello snapshot dell'host. Pianifica l’archiviazione in base alla quota e alla rimozione automatica del browser e proteggi script e dati dell’origine tramite la politica di sicurezza dell’applicazione. Qualifica il comportamento in caso di perdita di alimentazione nell’ambiente di archiviazione scelto. Chromium 154 su Windows è stato verificato per annullamento, ricaricamento, riavvio dell'host, conflitto tra due schede e terminazione della scheda proprietaria, con hash completi dei file salvati. Usa tale profilo misurato di browser/sistema operativo come riferimento per qualificare altre combinazioni.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeStreaming · Caricamenti · Coda dei trasferimenti · Recupero tramite Worker
Assistenza per firme e completamento
Dichiara signature-help, completion-resolve e completion-snippets secondo necessità nel manifesto v2; i modificatori di completamento richiedono anche completion. L'host deve concedere document.read e language.provide. I completamenti letterali esistenti restano validi. languageCapabilities() riporta l'implementazione SDK e i suoi limiti, senza concedere autorizzazioni.
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'applicazione fornisce posizione corrente e host; la preparazione restituisce dati senza scrivere un documento o file. L'assistenza per le firme supporta fino a 16 firme, 64 parametri ciascuna e offset UTF-16 delle etichette dei parametri. La risoluzione del completamento mantiene privati i dati del provider, restituisce un token host monouso e fissa etichetta, inserimento e intervallo selezionati. I token vincolano provider, ambito e documento, scadono dopo 60 secondi e sono limitati a 128 voci, 4 MiB e quattro operazioni effettive del resolver. Le modifiche a documento/provider li scartano.
I frammenti supportano $n, ${n}, ${n:literal}, $0 e le sequenze di escape documentate, con repliche e punti di tabulazione ordinati. Variabili, annidamento, scelte, trasformazioni e comandi eseguibili sono rifiutati. Sono verificati confini UTF-16/CRLF e modifiche aggiuntive sovrapposte. I provider vengono eseguiti come codice attendibile nello stesso processo con l’accesso al sistema operativo del processo host. Un annullamento ignorato mantiene occupato lo slot effettivo in sospeso fino al completamento del provider.
Modifiche del workspace e rinomina sottoposte a revisione
prepare-rename restituisce un intervallo/segnaposto convalidato o null; rename restituisce una proposta WorkspaceEdit o null. Le proposte supportano modifica, creazione, spostamento ed eliminazione su percorsi relativi di file disgiunti. Vengono controllati SHA-256 corrente del sorgente, assenza della destinazione, politica dei percorsi protetti, geometria delle modifiche UTF-16 e limiti. Le funzionalità di linguaggio autorizzano proposte; il client workspace fornisce accesso ai file e modifiche approvati separatamente.
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);Il chiamante usa un client workspace connesso e autorizzato e un registro attendibile. L'anteprima contiene snapshot completi prima/dopo e un digest; l'applicazione richiede planId/digest revisionati e una politica corrente dell'host che restituisca true. Ogni file viene verificato preliminarmente, poi ogni operazione usa il CAS per file esistente e le funzionalità correnti di scrittura/gestione. Il registro persiste e rilegge l'intento prima di ogni modifica e una ricevuta dopo. Conflitto o incertezza fermano ulteriori scritture; ogni operazione completata su un file ha il proprio risultato CAS e la propria ricevuta nel registro.
L'adattatore facoltativo workspace-edits-node archivia un registro limitato fuori dal workspace selezionato, ne vincola l'identità e usa un blocco per scrittore unico, file regolari e checkpoint con checksum. Dopo la terminazione del processo, recoverStaleLock è una scelta esplicita e recupera solo un proprietario dimostrabilmente terminato. Il recupero segnala applied/not-applied/conflicted/unknown dai byte correnti; il chiamante sceglie esplicitamente l’azione successiva. La compensazione crea una nuova proposta inversa per una nuova revisione. Su Windows, l’adattatore sincronizza i file ed esegue operazioni di rinomina. I controlli documentati coprono la terminazione del processo e il recupero; la persistenza dipende dal filesystem e dal dispositivo di archiviazione. I limiti includono 32 cambiamenti, 1000 modifiche, 256 KiB per file, un'anteprima di 8 MiB e 64 piani di registro conservati.
Formattazione e azioni sul codice diagnostico
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 e format-range richiedono percorso e opzioni tabSize/insertSpaces; solo la formattazione di intervallo prende una selezione. Un risultato è null o esattamente una modifica al file corrente con l'hash dello snapshot corrente. Le modifiche di intervallo restano nella selezione. endOfLine sceglie preserve, lf o crlf per il testo inserito; i byte non modificati restano invariati. Le proposte con contenuto identico vengono normalizzate a null. prepareFormatting non esegue scritture.
L'host vincola richieste di azioni e token di risoluzione alla revisione diagnostica accettata e allo snapshot corrente. Pubblicazioni diagnostiche successive, modifiche del documento o rilascio del provider invalidano le vecchie selezioni. Le chiamate diagnostiche fuori ordine non sovrascrivono il pacchetto accettato più recente. Fino a 100 azioni contengono etichette semplici, indici diagnostici limitati, modifiche proposte, dati privati di risoluzione o un motivo di disabilitazione. Campi sconosciuti di comando/URL/shell vengono rifiutati. Le modifiche delle azioni possono estendersi oltre la selezione, quindi esamina la proposta completa; formattazione e azioni non approvano mai le proprie scritture.
Visualizzazione semantica, riduzione dei blocchi, suggerimenti e simboli
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);I token semantici usano una legenda con nomi univoci e nove chiavi di stile dell'host, più cinque interi per token: delta di riga/inizio, lunghezza UTF-16, indice del tipo e bit dei modificatori. I token non possono sovrapporsi, spezzare un surrogato, attraversare una riga o uscire dal documento corrente. L'host restituisce sempre un array completo normalizzato e un UUID host, con updateKind full/delta/fallback. Una funzionalità separata semantic-tokens-delta abilita provideDelta rispetto a dati precedenti del provider; la cache archivia identità e dati dei token, non testo di documenti precedenti.
Una base della cache è vincolata a provider, ambito, URI e linguaggio, con massimo otto voci, 4 MiB e 60 secondi. Versioni del documento normalmente crescenti preservano una possibile base delta rendendo però obsoleto il vecchio risultato di visualizzazione. Una base persa/scaduta, un delta null o un ID base del provider non corrispondente consentono al massimo un fallback completo entro il timeout originale. Dati non validi o errori del provider falliscono senza nuovi tentativi. Disattivazione, rimozione della registrazione e sostituzione del documento cancellano le basi interessate. Chiama validateLanguageResult immediatamente prima del rendering; un oggetto copiato, rilasciato o obsoleto fallisce.
I limiti sono 20000 token semantici, 64 tipi di token, 16 modificatori e 64 modifiche delta; la riduzione dei blocchi consente 1000 intervalli con profondità 32 e rifiuta intervalli incrociati. I suggerimenti incorporati consentono 1000 etichette semplici su una riga entro l'intervallo richiesto. I simboli gerarchici consentono 1000 voci totali e 16 livelli, con figli/selezioni contenuti e fratelli ordinati senza sovrapposizioni. Il contratto originale document-symbols piatto è invariato. L'esempio browser verifica full/delta/fallback, riduzione dei blocchi, navigazione e ciclo di vita; un suggerimento simile a HTML resta testo letterale.
npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browserAssistenza · Modifiche revisionate · Formattazione/azioni · Visualizzazione
Impostazioni tipizzate e riferimenti a segreti
Il modulo /settings offre un archivio in memoria dell'operatore per un plugin. Una definizione versionata dichiara ogni chiave, schema dei dati, valore predefinito, ambiti utente/workspace consentiti e metadati di visualizzazione. I valori effettivi sostituiscono ogni chiave intera nell'ordine default < user < workspace. read(workspaceId) restituisce valori immutabili, origini e una revisione dell'intero archivio. Gli oggetti annidati non vengono uniti ricorsivamente; un valore mancante senza predefinito resta assente.
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}, ...}).Le scritture convalidano l'intera transazione e usano CAS expectedRevision. reset rimuove una chiave da un livello; readOnly richiede un valore predefinito e nessun ambito scrivibile. Le sottoscrizioni accorpano modifiche sincrone e restituiscono handle rilasciabili. migrate(nextDefinition, callback, options) esplicito convalida lo stato successivo e conferma solo se la sua revisione corrisponde ancora. Errore, annullamento o timeout preservano vecchia definizione e stato. Esportazione/importazione contiene dati semplici; persistenza e cifratura sono responsabilità dell'operatore. I limiti includono 64 chiavi, 32 livelli workspace, 1 MiB di stato esportato e una migrazione effettiva.
I plugin workspace dichiarano settings e settings.read e l'operatore monta l'archivio corrispondente con quella concessione. context.settings è di sola lettura e vincolato al plugin e al workspace selezionato. Il resolver /secrets emette separatamente riferimenti opachi per plugin, workspace, elenco consentito di comandi e durata. Il manifesto deve dichiarare secrets.resolve e l'host deve concederlo. I campi di input usano type: object con format: dds-secret-reference; stringhe ordinarie e oggetti simili non conferiscono autorizzazioni sui segreti.
Solo i riferimenti nell'input convalidato sono disponibili tramite options.secrets.withSecret di un comando. Ogni esecuzione ha un nuovo ID; il resolver verifica ambito, scadenza, revoca e autorizzazione corrente attorno alla risoluzione e al callback. Il callback restituisce undefined e riceve una copia cancellata all'interruzione e a ogni uscita. Gli errori dei provider vengono sanificati. Posiziona la concessione temporanea prima degli effetti che richiedono tale autorizzazione. La durata predefinita del riferimento è 60 secondi, al massimo un'ora; i limiti sono 128 riferimenti, 8 concessioni temporanee effettive e 16 KiB di materiale. Il codice attendibile nello stesso processo può conservare copie e usa l’accesso al sistema operativo del processo host. Mantieni il materiale segreto nel callback autorizzato e classifica esplicitamente le stringhe dell’applicazione prima di archiviare impostazioni, pacchetti, log o risultati.
Schemi e moduli strutturati dei comandi
I comandi possono dichiarare inputSchema e outputSchema usando un involucro schemaVersion: 1. I parametri primitivi esistenti restano supportati; dichiarare insieme parameters e inputSchema viene rifiutato. L'host convalida e applica i valori predefiniti dell'input prima di avviare un gestore o job, poi convalida l'output prima di pubblicare il successo. I valori predefiniti dell'output non vengono mai applicati. Nuovi metadati di schema/visualizzazione richiedono un peer compatibile con 0.12; i vecchi validatori rigorosi li rifiutano, mentre le definizioni legacy mantengono il loro comportamento.
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);Il sottoinsieme limitato supporta oggetti chiusi, array, stringhe, numeri finiti, interi sicuri, booleani, null, enumerazioni primitive, limiti e valori predefiniti convalidati. Parole chiave sconosciute, riferimenti remoti, regex, unioni, coercizione, accessor e prototipi personalizzati vengono rifiutati. Gli schemi consentono 32 KiB, profondità 8 e 128 nodi; i valori consentono 64 KiB. Un comando completo mantiene il budget di metadati di 16 KiB. DataValidationError locale espone code, reason e percorsi di campi noti come /input/options/names/0; errori HTTP e dei job espongono codici sicuri senza i valori rifiutati.
describeDataForm restituisce percorsi, tipi, scelte, valori predefiniti, indicatori obbligatori e suggerimenti per riferimenti a segreti. I metadati condivisi di visualizzazione contengono label/help/order letterali e nomi di accessibilità, descrizioni e suggerimenti da tastiera. Rendering e interazione sono responsabilità dell'host. Questi schemi descrivono dati semplici; l’host controlla esplicitamente rendering, accesso alle risorse ed esecuzione dei comandi.
Metadati di localizzazione e 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.I cataloghi usano tag base canonici BCP 47 e collegamenti espliciti di fallback aciclici. Fino a otto preferenze negoziano tag esatti, poi antenati e valore predefinito. La lingua predefinita definisce tutte le chiavi; le traduzioni possono ometterle ma non inventarle. La ricerca per chiave segue i collegamenti di fallback ordinati e poi la lingua predefinita. Ogni traduzione e i suoi argomenti devono corrispondere all'esatto insieme di segnaposto {name}. Si tratta di interpolazione letterale senza espressioni ICU. resolveMessage segnala lingua sorgente effettiva e direzione, affinché un fallback inglese in una pagina RTL possa mantenere lang=en e dir=ltr.
La formattazione numerica supporta decimali/percentuali; quella delle date usa un'epoca esplicita e UTC per impostazione predefinita; la selezione del plurale restituisce una categoria cardinale/ordinale Intl per la scelta del messaggio del chiamante. Dati e supporto Intl sono responsabilità degli host. validateLocalizedSurfaces controlla chiavi di manifesto/comandi/impostazioni/schemi e file accessori di visualizzazione dei temi, comprese lunghezze risolte e traduzioni mancanti. JSON/XML dei temi resta compatibile. I limiti dei cataloghi sono 32 lingue, 256 chiavi e 256 KiB; le etichette statiche non possono contenere segnaposto.
Gli helper /accessibility segnalano nomi mancanti, scorciatoie normalizzate duplicate e contrasto esplicito di coppie di colori opachi nei temi chiari/scuri. Gli host usano queste indicazioni per implementare scorciatoie da tastiera e valutare l’accessibilità delle proprie interfacce. L'esempio indipendente include EN/KO, arabo parziale e casi di test con etichette lunghe. Verifica impostazioni con ambito, riferimenti negati/revocati, campi non validi, Ctrl+Enter e cambi di lingua durante un comando attivo. Il layout browser è stato controllato nelle dimensioni desktop/mobile con temi chiari/scuri.
npm run example:configuration
npm run example:configuration-browserImpostazioni · Riferimenti a segreti · Schemi dei comandi · Localizzazione
Modelli di sviluppo e generazione
Sei modelli, dipendenze esatte dell'archivio, revisione della generazione, conservazione dei conflitti e controlli doctor.
Contratti completi, esempi e limiti
Test deterministici e riproduzione
Dati di test sintetici espliciti, tempo virtuale, guasti, tracce limitate contenenti solo hash e pulizia delle risorse.
Contratti completi, esempi e limiti
Diagnostica e debug locali
Profili locali facoltativi e un debugger figlio attendibile con endpoint loopback temporaneo e scadenza totale.
Contratti completi, esempi e limiti
Conformità degli host
18 profili versionati distinguono contratti supportati, non supportati e falliti; gli adattatori personalizzati mantengono autorizzazioni esplicite.
Contratti completi, esempi e limiti
Supporto e migrazione dell'SDK
Consulta inventario degli elementi esportati, politica stabile/facoltativa/sperimentale, peer esatti, date dei runtime ed esempi di migrazione.
Contratti completi, esempi e limiti
Accettazione della release
La release dell’SDK presenta carichi combinati con guasti e controlli misurati delle prestazioni come convalida funzionale dei contratti SDK e degli host indipendenti.
Contratti completi, esempi e limiti
1.1 Strumenti per dipendenze, provenienza e aggiornamenti
La versione 1.1.0 aggiunge pacchetti offline deterministici di dipendenze revisionate, SBOM CycloneDX, firme separate con chiavi Ed25519 dell'operatore, approvazione/attivazione/ripristino vincolati al digest e confronto esplicito con upstream. Cinque punti di ingresso disponibili solo in Node includono dichiarazioni, schemi ed esempi indipendenti. L’operatore concede esplicitamente l’esecuzione dopo aver esaminato la firma e i vecchi job mantengono il loro hash originale. L’operatore sceglie il flusso di distribuzione, deployment e monitoraggio. La release pubblicata dell’SDK documenta la convalida funzionale mediante i propri esempi indipendenti degli strumenti di release.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsGuida completa a pacchetti, firme, aggiornamenti e upstream
1.2 Flussi di lavoro, cache, flussi degli strumenti e LSP
La versione 1.2.0 aggiunge DAG di comandi revisionati con job/concessioni per ogni passo, checkpoint persistenti e recupero esplicito con nuovo tentativo; cache deterministica basata sul contenuto ed esecuzione incrementale; flussi limitati UTF-8/JSONL/testo degli strumenti; e un bridge stdio LSP 3.17 facoltativo. Sette nuovi punti di ingresso portano il pacchetto a 50 elementi esportati e 107 schemi con dichiarazioni ed esempi installati indipendenti, senza dipendenze npm a runtime. Il parser dei flussi degli strumenti funziona anche nei browser; flussi di lavoro, archivi, processi esterni e LSP richiedono Node. La release dell’SDK documenta controlli funzionali degli adattatori con TypeScript 5.9.3 e language-server 5.3.0. Il bridge accetta diagnostici vincolati a una versione del documento. L’host autonomo dell’SDK gestisce recupero esplicito con nuovo tentativo, archivi locali e configurazione dei processi.
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.mjs