DDS Plugin SDK
Instale o DDS Plugin SDK 1.2 público e use fluxos de trabalho, cache, streams de ferramentas, LSP e APIs estáveis.
Os exemplos de espaço de trabalho do usuário abaixo descrevem um host de desenvolvimento explicitamente conectado e controlado pelo cliente. Escolha WSL ou outro host para esses exemplos independentes do SDK. O aplicativo Windows comum do Digital Design Studio usa seu runtime nativo do Windows. Configure descoberta, permissões e recursos de plugins para o host SDK selecionado; jobs gerenciados de mecanismos Cloud usam seu próprio caminho de execução.
1. Instalar o SDK
DDS Plugin SDK 1.2.1 oferece APIs JavaScript, declarações TypeScript, provedores de linguagem, temas, ferramentas de espaço de trabalho e jobs de comandos. Armazenamentos duráveis opcionais acrescentam histórico de jobs, novas tentativas explícitas e snapshots verificados de texto/binários que sobrevivem à exclusão da origem e ao reinício do processo. Use Node.js 22 ou 24. Instale a versão estável do SDK a partir do lançamento oficial no GitHub. Para um plugin de comando independente, use Ferramentas de desenvolvimento após a instalação:
A 1.0.0 publica a API estável do SDK, 18 perfis de conformidade do host, a política de suporte/migração e verificações medidas de cargas de trabalho combinadas. Novos plugins usam >=1.0.0 <2.0.0. A versão publicada do SDK atribui esses resultados à validação funcional do SDK e de hosts independentes.
A 0.13.0 acrescenta seis modelos de desenvolvimento, tipos e esquemas gerados, cenários determinísticos de teste e diagnósticos locais opcionais. O SDK empacotado e os projetos gerados são executados fora da árvore de código-fonte; reprodução sintética e depuração em loopback são selecionadas explicitamente.
A 0.12.0 acrescenta configurações tipadas com escopo e migrações explícitas, referências a segredos com escopo de execução, entrada/saída estruturadas de comandos, catálogos de idiomas e metadados de acessibilidade. O SDK público e exemplos independentes verificam conflitos de configuração, entradas inválidas, autoridade revogada e fallback de tradução.
A 0.11.0 acrescenta ajuda de assinaturas, conclusão sob demanda, snippets limitados, edições e renomeações revisadas em vários arquivos, formatação/ações de código, tokens semânticos, dobramento, dicas e símbolos hierárquicos. Propostas, revisão, verificações da autoridade atual e aplicação condicional são etapas distintas do host. Os hosts exibem e aplicam resultados somente enquanto a identidade do documento estiver atual. Esses recursos são exercitados pelo SDK público e por exemplos independentes.
A 0.10.0 acrescenta downloads em streaming no navegador, uploads de arquivos selecionados, uma fila mista de transferências e recuperação de checkpoints OPFS em Worker. As transferências verificam a autoridade atual, a identidade do arquivo e hashes de blocos e do arquivo inteiro, separando o progresso em bytes do armazenamento verificado. Esses exemplos exercitam hosts e clientes do SDK público.
A 0.9.0 acrescenta árvores de projetos com escopo, pesquisa por nome de arquivo/texto e observação de alterações em diretórios locais selecionados pelo operador. Use-os pelo cliente HTTP ou auxiliar de projeto, mantendo snapshots de edição e rascunhos não salvos. Os exemplos de projeto abaixo cobrem criação, pesquisa, alterações externas e tratamento de conflitos.
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"
O primeiro exemplo de diagnósticos usa código confiável em um host local de teste. Temas usam a importação XML existente do DDS. Para integrações de ferramentas existentes, consulte Plugins e ferramentas de terceiros.
2. Escrever seu primeiro plugin
Crie plugin.mjs no novo projeto. Este plugin verifica documentos de texto simples e relata um diagnóstico informativo em cada linha que contém 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);
},
}));
O manifesto declara a versão 1 do protocolo, o recurso diagnostics, o host test-host e as permissões document.read e diagnostics.publish. O provedor recebe um snapshot do documento e um AbortSignal. Os intervalos de diagnóstico usam linhas com índice a partir de zero e deslocamentos de caracteres UTF-16.
3. Executar localmente
Crie run.mjs junto de plugin.mjs. Ative o plugin, forneça um documento e solicite diagnósticos. Sempre descarte o host quando terminar.
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
Saída esperada (a linha e a coluna impressas começam em um):
Texto
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. Testar seu plugin
Salve este teste como plugin.test.mjs. Ele verifica o intervalo do diagnóstico e confirma que editar o documento remove o diagnóstico.
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
O teste deve passar. Adicione fixtures para sua própria linguagem, cancelamento, resultados inválidos e documentos grandes. Mantenha a versão do documento atualizada para rejeitar resultados de snapshots anteriores.
5. Criar e aplicar um tema
Salve esta paleta clara/escura como theme.json. As seis cores de cada paleta são obrigatórias. Tokens semânticos opcionais personalizam pesquisa, seleções, HintsBox e o canvas GDS; tokens omitidos usam os padrões do 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
}
}
}
Crie export-theme.mjs junto dela. parseTheme valida os dados de cores e serializeThemeXml exporta XML DDS versão 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
O comando grava hello-theme.xml e imprime Created hello-theme.xml. No DDS, abra Plugins → Instalar o tema..., selecione o XML e escolha Aplicar para Hello Ocean. Alterne entre aparência clara e escura para ver as duas paletas.
Você também pode usar Configurações → Geral → Aparência → Importar XML. Salve o tema atual com Exportar XML antes de substituí-lo. O importador XML lê os dados de aparência do tema.
O guia de temas lista todos os tokens e métricas compatíveis. O exemplo Hello Ocean inclui o tema completo, XML pronto para importar e uma prévia HTML local.
Referência de XML de temas
Baixe XML do Hello Ocean e seu JSON editável. O XML contém paletas completas claras e escuras, todas as 28 cores opcionais de funções em cada modo e quatro métricas explícitas. Salve o arquivo XML localmente antes de importá-lo. Esses exemplos originais do SDK usam Apache-2.0; mantenha o aviso ao compartilhá-los.
Comece com Configurações → Geral → Aparência → Exportar XML para fazer backup do tema atual. Importe o XML baixado, revise o rascunho e escolha Aplicar. Descartar alterações mantém o tema aplicado. Alterne a aparência clara/escura para revisar ambas as paletas. Para recuperar, escolha um tema integrado ou importe a cópia salva. Uma importação recusada preserva o tema atual.
DDS, ALcad, editores compartilhados, navegação de projetos, configurações e pop-ups usam a paleta compartilhada do ambiente de trabalho nesse perfil. O mesmo formato de tema é usado na Cloud e no desktop; importe-o separadamente em cada perfil. gdsBackground controla o canvas GDS de forma independente. Outras cores de canvas de projeto, camadas e simulação podem ter configurações próprias. XML carrega a paleta e as métricas de aparência desse perfil de tema.
Elemento | Regra |
|---|---|
| Uma raiz; um nome sem espaços nas extremidades com 1–80 unidades de código UTF-16; no máximo 65536 bytes UTF-8 para todo o XML. |
| Ambas obrigatórias, cada uma com as seis cores abaixo. |
| Substituições opcionais da v2. Funções omitidas seguem os padrões do DDS para esse modo. |
| Substituições numéricas opcionais da v2. |
Versão 1 | Somente as duas paletas. Arquivos v1 existentes continuam compatíveis; o exportador do SDK emite v2. |
Chave obrigatória da paleta | Uso |
|---|---|
| Fundo externo do espaço de trabalho |
| Navegação do projeto |
| Painéis e controles de ferramentas |
| Espaço de trabalho principal e configurações |
| Texto principal |
| Texto secundário |
Chaves opcionais de funções (28) | Uso |
|---|---|
| Fundo, texto e marcador do campo de pesquisa compartilhada |
| Campo de compatibilidade; os campos atuais de pesquisa compartilhada não têm bordas |
| Linhas e texto selecionados |
| Abas do editor |
| Barras de ferramentas, limites de painéis e pop-ups |
| Contorno de foco do teclado |
| Cores de estado e fundo da esfera de IA |
| Fundos de sugestões e detalhes |
| Texto de sugestões, detalhes e texto secundário |
| Sugestão selecionada pelo teclado |
| Sugestão sob o ponteiro |
| Fundo do canvas do visualizador GDS |
HintsBox é o recurso compartilhado de sugestões de código. Encontre suas cores em Personalizado → Cores e formas detalhadas → HintsBox e o fundo GDS em Exibição. Edite as três cores de pesquisa juntas para obter um contraste legível. Este fragmento pertence a um tema v2; mantenha as duas paletas completas:
Fragmento XML v2
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
Métrica | Valores permitidos | Padrão atual do DDS |
|---|---|---|
| Inteiro 0–24 | 14 |
| Inteiro 0–16 | 6 |
| Inteiro 0–24 | 16 |
| Número 0,6–1 | 0,72 |
Escreva as métricas como <number key="popoverOpacity" value="0.9"/> dentro de <metrics> sem unidades. Os valores de raio são em pixels. O SDK mantém ausentes as métricas omitidas; a versão instalada do DDS fornece seus padrões. Defina valores explícitos para uma aparência consistente. Hello Ocean define deliberadamente 16, 8, 12 e 0,9. Configurações de transparência reduzida e cores forçadas podem alterar a renderização final.
Cada cor deve ser um #RRGGBB de seis dígitos; alpha, nomes CSS, variáveis, URLs e estilos são rejeitados. Chaves ou modos duplicados, elementos/atributos desconhecidos, namespaces, DTDs, entidades e instruções de processamento são rejeitados. Declarações e comentários XML são permitidos. Se a importação falhar, confira o tamanho do arquivo, a versão, as duas paletas completas e os valores compatíveis; depois tente novamente com seu backup inalterado. Temas de outros editores precisam ser convertidos para este formato DDS.
6. Executar um espaço de trabalho no seu ambiente
Execute o host, o SDK, os plugins e as ferramentas no seu próprio ambiente WSL, contêiner ou servidor. Os arquivos do projeto permanecem sob a raiz escolhida. O cliente SDK independente os lê e edita pela conexão; recebe metadados de plugins e resultados de comandos enquanto o código do plugin é executado no seu ambiente.
No projeto SDK criado acima, salve este auxiliar como copy-workspace-example.mjs. Ele copia o servidor editável, o plugin, a ferramenta e o projeto de exemplo, preservando a organização dos arquivos de licença do exemplo.
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
O projeto de exemplo é user-host/examples/user-workspace/project. Inicie o servidor nesse ambiente usando um token gerado explícito:
WSL / Linux / contêiner
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
O servidor imprime Workspace server: http://127.0.0.1:4777/dds/workspace/v1 mais um ID e uma geração do espaço de trabalho. No terminal do cliente, defina DDS_WORKSPACE_TOKEN com o token gerado. Ele é uma credencial do operador, separada de um token DDS Account. Pare o servidor de exemplo com Ctrl+C.
Em outro terminal no mesmo projeto, defina DDS_WORKSPACE_TOKEN com o mesmo segredo e execute o cliente de desenvolvimento:
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
O cliente lista os arquivos de exemplo e executa Inspecionar arquivo do projeto para design.sv. O resultado JSON inclui tool: "module-counter" e modules: 1, produzidos por um processo filho real. Adicione --edit ao comando do cliente somente quando quiser que o exemplo acrescente uma nota ao arquivo de exemplo.
Para usar seu próprio projeto, passe seu diretório absoluto como último argumento para server.mjs. Mantenha o servidor, os módulos de plugin e as ferramentas instaladas nesse mesmo ambiente do usuário. server.mjs importa explicitamente o plugin e mapeia seu backend nomeado para um executável e argumentos fixos:
Mapeamento de backend em server.mjs
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
Substitua esse mapeamento pela sua ferramenta instalada aprovada ou por um backend personalizado. ctx.workspace.readFile e writeFile usam caminhos relativos à raiz selecionada; ctx.backends.invoke("module-counter", input, {signal}) invoca somente um nome de backend configurado. O adaptador de processo envia JSON limitado em stdin e espera JSON em stdout. Ele não usa comandos de shell fornecidos na solicitação e não herda variáveis de ambiente do host.
Para um servidor remoto, use seu próprio endpoint HTTPS autenticado ou um túnel privado que termine no loopback local. Configure o mapeamento de portas do contêiner ou TLS no seu ambiente. O exemplo se vincula ao loopback por padrão; mudar seu endereço de escuta não adiciona TLS. Plugins e ferramentas confiáveis são executados com a autoridade do sistema operacional do processo do host.
Consulte o exemplo de espaço de trabalho do usuário e protocolo de espaço de trabalho para configuração do servidor, origens, revisões de arquivos, cancelamento e resultados limitados.
Recursos de linguagem
O SDK 0.7.0 oferece conclusão, informações ao passar o ponteiro, definição, referências e símbolos simples do documento. Declare cada recurso nas capacidades do manifesto v2, além das permissões document.read e language.provide. O host deve conceder explicitamente as duas permissões. Salve este exemplo completo de informações ao passar o ponteiro como language-demo.mjs no projeto criado acima:
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
O primeiro comando imprime A local LED signal. O segundo exemplo incluído verifica todos os cinco recursos usando uma pequena linguagem didática com let name = value; o provedor do próprio exemplo implementa essa linguagem didática.
Recurso | Entrada da solicitação | Dados do resultado |
|---|---|---|
|
| Até 500 |
|
|
|
|
| Até 500 locais |
|
| Até 500 locais |
|
| Até 500 símbolos |
Posições usam linhas com índice a partir de zero e deslocamentos UTF-16. A inserção de conclusão é texto literal; strings de informações ao passar o ponteiro e detalhes são texto simples. Um host deve verificar os arquivos e intervalos de destino antes de seguir um local. O resultado preserva a identidade da solicitação, do projeto/sessão e da versão do documento. Editar o snapshot, cancelar, exceder o tempo limite, remover o registro ou descartar encerra solicitações pendentes e elimina resultados tardios.
Essas APIs operam no host independente confiável do SDK. Use um host SDK 0.3.0 ou posterior para esses recursos de linguagem e configure explicitamente qualquer processo LSP pela ponte dedicada. Leia Recursos de linguagem para conhecer seletores, limites e comportamento do ciclo de vida.
Sessões de edição do projeto
Importe createWorkspaceProject e applyTextEdits de @altifigence/dds-plugin-sdk/workspace-client. Depois que seu host conectar um createWorkspaceClient e revisar a identidade, o aviso e o acesso do espaço de trabalho, chame createWorkspaceProject(client). O projeto mantém o vínculo exato da conexão. Reconectar exige um projeto recém-revisado, mesmo quando o mesmo ID e a mesma geração do espaço de trabalho retornam.
API | Comportamento |
|---|---|
| Listar um diretório sob a raiz do espaço de trabalho selecionado. |
| Ler um arquivo e reter seu conteúdo e sua revisão imutáveis em uma sessão de edição. |
| Criar somente quando o arquivo estiver ausente e então retornar uma sessão. |
| Ler o último |
| Salvar somente se a revisão do servidor ainda corresponder à revisão retida. |
| Aplicar edições |
| Ler explicitamente o conteúdo e a revisão mais recentes após um conflito ou uma gravação incerta. |
| Cancelar o trabalho pertencente ao projeto; descartar o projeto deixa conectado o cliente que pertence ao chamador. |
Execute o exemplo HTTP completo no pacote instalado. Ele cria seu próprio espaço de trabalho temporário de exemplo, testa a edição, uma segunda sessão em conflito, recarregamento explícito, Unicode e reconexão; depois fecha o servidor e remove esse diretório temporário:
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs
Saída esperada: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. O código-fonte do exemplo mostra a configuração completa de servidor/cliente e a limpeza.
As opções aceitam signal e timeoutMs. Uma gravação que falha após uma tentativa deixa needs-reload; preserve qualquer rascunho não salvo da UI separadamente e recarregue explicitamente antes de salvar novamente. O SDK não mescla nem tenta novamente automaticamente. Um tempo limite, cancelamento ou resposta perdida pode ocorrer depois que o servidor confirmou a gravação; cancelar uma solicitação mantém as alterações já confirmadas. Cada sessão permite um salvamento ou recarregamento pendente.
Edições de texto usam o snapshot original, linhas com índice a partir de zero e deslocamentos UTF-16. Sobreposições, pares substitutos divididos e intervalos inválidos são rejeitados antes de salvar. Projetos permitem no máximo 64 sessões abertas ou em abertura e 500 edições por salvamento. Esses auxiliares usam o protocolo de espaço de trabalho v1 inalterado, incluindo servidores SDK 0.2.x, e mantêm restrições de raiz, caminhos protegidos e somente leitura. Leia Projetos de espaço de trabalho para conhecer o ciclo de vida e os limites de tamanho.
Referência da API
Importe APIs de plugins de @altifigence/dds-plugin-sdk. O pacote inclui declarações TypeScript para os mesmos exports.
API | Uso |
|---|---|
| Validar o manifesto e declarar a função de ativação. |
| Registrar |
| Construir um resultado validado usando a identidade da solicitação. |
| Registrar um provedor de linguagem e construir um resultado com identidade validada da solicitação. |
| Validar versão do manifesto, identidade, permissões, hosts compatíveis e módulo de entrada. |
| Validar URI, linguagem, versão do modelo, revisão do espaço de trabalho e texto. |
| Validar protocolo, solicitação, escopo, identidade do documento e campos de diagnóstico. |
| Ler erros tipados, limites de recursos e versão do protocolo. |
Importe o host de desenvolvimento de @altifigence/dds-plugin-sdk/testing:
API do host de teste | Uso |
|---|---|
| Criar um host local. As duas opções são opcionais; as concessões padrão permitem leitura de documentos e diagnósticos. |
| Ativar o plugin e retornar uma ativação descartável. |
| Definir o documento atual. Aumente |
| Solicitar diagnósticos de um provedor correspondente; as duas opções são opcionais. |
| Solicitar um recurso declarado de linguagem com concessões explícitas de document.read e language.provide. |
| Remover registros e cancelar trabalho pendente; descartar o host ao terminar o teste. |
Solicitações incluem requestId, scope de projeto/sessão e um snapshot com uri, languageId, modelVersion, workspaceRevision e text. Use createDiagnosticsResult para preservar essa identidade. Os resultados contêm um array diagnostics e omitem o texto-fonte.
Os erros expõem um code, incluindo invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable e budget_exceeded. O tempo limite padrão da solicitação é de 5 segundos; tempos limites aceitos são de 1–30000 ms. Um documento é limitado a 262144 bytes UTF-8 e um resultado a 500 diagnósticos. Leia LIMITS para conhecer todos os limites.
O SDK 1.0.0 também oferece módulos separados. Imports de espaço de trabalho e empacotamento exclusivos de Node pertencem ao ambiente do usuário:
Importação | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Empacotar e publicar seu plugin
Comece com o plugin publicável incluído. Salve este auxiliar no seu projeto SDK para copiar seus arquivos para um novo diretório 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
Edite plugin.json, plugin.mjs, disclosure.json e a licença para descrever seu próprio plugin. A declaração deve corresponder ao publicador, ao ID do plugin, à versão, à licença e à visibilidade do código-fonte no manifesto. Liste somente os arquivos que você pretende distribuir em dds-package.json:
dds-package.json
{
"schemaVersion": 1,
"files": [
"plugin.json",
"plugin.mjs",
"disclosure.json",
"LICENSE",
"NOTICE"
]
}
Valide e empacote o exemplo:
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist
Com os metadados inalterados do exemplo, pack cria dist/example-hello-publisher-1.0.0.tgz e dist/example-hello-publisher-1.0.0.tgz.release.json. O JSON do lançamento contém o SHA-256 final do arquivo, hashes do manifesto/declaração e o inventário de arquivos. Inspecione esses arquivos antes de distribuir.
Somente arquivos na lista permitida, dds-package.json e metadados npm gerados entram no arquivo. A validação inspeciona os dados do pacote e o empacotamento cria o arquivo local para o canal de distribuição escolhido. A CLI rejeita configurações privadas, arquivos de chaves e caminhos vinculados; revise o conteúdo dos arquivos escolhidos antes de compartilhar.
Canal | O que fornecer |
|---|---|
Lançamento público no GitHub | Um arquivo versionado, seu JSON externo de lançamento, a licença e qualquer acesso necessário ao código-fonte. |
Registro privado ou canal de download | Os mesmos arquivos versionados, autorização do público e os termos efetivos do plugin. |
O manifesto v2 declara runtime, permissões solicitadas e source: {visibility, licenseFile, repository?}. Defina a visibilidade como open ou closed e inclua o arquivo de licença efetivo. Código que pertence a você pode usar termos de código aberto ou proprietários; avisos aplicáveis do SDK e das dependências continuam valendo. Os destinatários recebem o JavaScript executável junto com os metadados declarados de visibilidade do código-fonte e licença.
Siga Publicação e Licenciamento para conhecer os campos da declaração e os requisitos de distribuição. Distribua o arquivo gerado pelo SDK pelo canal público de lançamento ou privado de download escolhido.
A CLI 1.2.1 registra >=1.0.0 <2.0.0 em novos pacotes de plugins. Arquivos históricos 0.3–0.13 e exatamente 1.0.0-rc.1 mantêm seus peers originais. Valide e reempacote uma nova versão do plugin para instalação estável; o publicador atualiza explicitamente o intervalo de peers e os metadados do lançamento ao reempacotar.
Verificar um plugin baixado
O SDK 1.2.1 fornece dds-plugin verify para metadados exatos de plugins lançados das versões 0.3.x–0.13.x, RC1 e estável atual. Mantenha .tgz e .tgz.release.json juntos. A verificação preserva o peer original. Confira o pacote criado acima:
Verificar o exemplo empacotado
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
O comando verifica a estrutura limitada de gzip/tar, listas exatas de arquivos permitidos, cada hash de arquivo, manifesto, declaração, licença e metadados npm gerados. Ele rejeita links, caminhos inseguros ou duplicados, arquivos extras e hooks/dependências npm. Lê e valida o arquivo local em seu lugar como uma operação sobre dados. O sucesso imprime um comprovante JSON; a rejeição encerra com código 1.
Para downloads renomeados, use --metadata com o JSON de lançamento correspondente. Obtenha o SHA-256 esperado de forma independente por um canal de lançamento confiável e passe-o com --sha256 para fixar os bytes selecionados. A API Node expõe as mesmas opções:
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);
Execute verify-release.mjs com o caminho do arquivo, o caminho dos metadados e o hash de 64 caracteres minúsculos obtido independentemente como seus três argumentos. checksumPinned é true somente quando esse hash fornecido corresponde. Os limites são 12 MiB de entrada comprimida, 10 MiB de conteúdo de arquivos, 4 MiB por arquivo, 256 arquivos e 256 KiB de metadados externos.
O verificador compara os bytes do arquivo com seus metadados associados. Obtenha o hash esperado de forma independente por um canal de lançamento confiável para vincular a comparação à versão escolhida. O host valida separadamente o publicador, revisa o conteúdo e a compatibilidade da instalação DDS e concede permissões antes da execução. Um comprovante descreve os bytes lidos durante aquela chamada; confira novamente os bytes efetivos se o arquivo puder mudar antes do uso. Arquivos existentes de plugins 0.3.x/0.4.x/0.5.x/0.6.x/0.7.x/0.8.x/0.9.x/0.10.x/0.11.x continuam verificáveis quando atendem à política reforçada de arquivos; instalá-los na 1.0 ainda exige validação do publicador e reempacotamento. Remova arquivos recém-excluídos e publique uma nova versão do plugin, se necessário. Esse verificador é para pacotes de plugins DDS; tarballs npm do SDK usam o SHA-256 do lançamento.
Consulte Verificação de arquivos e o exemplo completo de empacotamento/verificação/adulteração.
Permissões, licenças e uso de dados
Permissões solicitadas em um manifesto são separadas das concessões do host que habilitam operações. Forneça aos usuários a identidade do plugin, a versão, a licença efetiva, o escopo do espaço de trabalho e as permissões solicitadas antes de habilitá-lo. Explique qualquer operador de backend, os dados enviados, a finalidade, a retenção e o aviso de privacidade antes de conectar esse backend.
Registro | Significado |
|---|---|
| Uma decisão de acesso do host para o pacote, espaço de trabalho e permissões exatos. |
| Um usuário confirmou um aviso informativo. |
| Um usuário escolheu aceitar ou não os termos efetivos do publicador do plugin. |
| Uma escolha separada quando o processamento opcional usa consentimento como base. |
Uma aprovação de espaço de trabalho do SDK registra uma decisão técnica de acesso. Registre a aceitação dos termos do plugin e o consentimento opcional para dados pessoais como escolhas próprias. O SDK usa a licença Apache-2.0; consulte sua licença e seus avisos para os termos do SDK.
Desenvolvedores de hosts podem preservar um aviso versionado com os auxiliares assíncronos portáteis. Por exemplo, salve isto como notice.mjs e execute 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 vincula um subconjunto de permissões solicitadas ao manifesto v2, aos hashes do artefato e do manifesto, à geração do espaço de trabalho, à identidade do host, ao aviso e à expiração. isPermissionGranted avalia as identidades atuais e os eventos de revogação fornecidos pelo host. revokeConsentReceipt cria um evento separado; o host deve então impedir chamadas autorizadas futuras.
Esses auxiliares validam registros locais. O host fornece a escolha real do usuário, a identidade, o armazenamento e a aplicação das regras. Leia Permissões e consentimento para conhecer os campos exatos e o exemplo interativo de permissões para uma demonstração explícita de permitir/negar/revogar. O host mantém os acordos com publicadores e seus registros no fluxo de aplicativo escolhido.
Código-fonte, lançamentos e contribuições
O repositório oficial do SDK contém o código-fonte, os esquemas, os exemplos e os testes de contratos. Para executar o exemplo lançado e os testes do SDK a partir do código-fonte:
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
Relate bugs do SDK em GitHub Issues, com a versão do SDK e uma reprodução mínima. O SDK é licenciado sob Apache-2.0; consulte a licença e os avisos do repositório. Use a página de lançamentos para arquivos versionados e notas de lançamento.
Este repositório é o SDK público de desenvolvedor. Seu lançamento contém os arquivos declarados do SDK, esquemas, exemplos e avisos dentro do seu escopo público. Verificações do pacote impõem o inventário exato de arquivos publicados e rejeitam padrões conhecidos de segredos e caminhos privados. Revise o conteúdo real do lançamento para identificar informações sensíveis junto com essas verificações de padrões.
Atualizações de segurança e limites do host
Atualize tanto seu servidor de espaço de trabalho quanto o cliente SDK para 0.3.2 ou posterior. Instale a atualização do servidor para ativar suas verificações de arquivos e limites de solicitações aprimorados. Reinicie o host atualizado, revise sua nova geração e obtenha aprovação novamente antes de usar o espaço de trabalho.
O host Node de espaço de trabalho rejeita hardlinks que possam criar aliases para arquivos protegidos ou arquivos fora da raiz selecionada. Copie um arquivo de projeto intencionalmente compartilhado para um arquivo comum com um único link. Armazenamentos de credenciais como .netrc, _netrc, .git-credentials, .gnupg, .kube e .docker, nomes adicionais de chaves SSH e aliases de dispositivos Windows também são bloqueados. O empacotamento e a verificação de downloads aplicam a política correspondente de nomes de credenciais.
Recurso do servidor | Limite |
|---|---|
Corpos de entrada simultâneos | 16; uploads adicionais recebem HTTP 429 antes do despacho |
Solicitações em execução | 64; o cancelamento usa um caminho de despacho separado |
Conexões / solicitações por socket | 128 / 128 |
Solicitação e resposta / conteúdo de arquivo | 1600000 / 262144 bytes UTF-8 |
O cliente cancela respostas rejeitadas não lidas e streams parados ao atingir um prazo ou no cancelamento. Um tempo limite depois de começar uma gravação pode deixar seu resultado incerto: leia o arquivo novamente antes de tentar de novo. Revise o conteúdo em busca de segredos junto com as exclusões explícitas de caminhos e execute plugins confiáveis com acesso ao sistema operacional do processo do host escolhido deliberadamente. Use o guia de atualização de segurança e limites de espaço de trabalho ao implantar um host.
Ferramentas de desenvolvimento
Após instalar o SDK 1.2.1 acima, crie um projeto separado de plugin de comando. Escolha um novo destino para os arquivos gerados; instale dependências e execute o plugin explicitamente após gerar a estrutura. A estrutura gerada inclui comando, teste, manifesto, divulgação, dependência SDK fixada 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 lê metadados e verifica Node, resolução do SDK, manifesto, licença, declaração e arquivos do pacote na lista permitida sem importar o plugin. Erros produzem código de saída 1; valores de exemplo para publicador/suporte geram avisos. Substitua esses valores e revise as licenças antes de distribuir.
npx --no-install dds-plugin doctor . --json
npx --no-install dds-plugin dev . --trust-local-code --watch
npx --no-install dds-plugin dev . --trust-local-code --job --command greet --input '{"name":"Ada"}'
npm run pack:plugin
Dev exige --trust-local-code. Ele executa imports/ativação locais confiáveis em um processo filho e observa somente os arquivos permitidos e dds-package.json. Cada execução tem um prazo e um limite de 256 KiB para stdout/stderr. Ctrl+C interrompe a observação e limpa a árvore de processos. O processo filho confiável herda seu ambiente e usa o acesso do seu processo ao sistema operacional. O host padrão de teste concede leitura de documentos e publicação de diagnósticos. Configure um host separado de espaço de trabalho com concessões explícitas de espaço de trabalho/backend para essas integrações.
Use --job para imprimir progresso/logs do job; use --timeout-ms para definir até 30 segundos para comandos comuns ou 30 minutos para jobs. As APIs Node são initPlugin, doctorPlugin e runPluginDev em /devtools. Consulte o guia de ferramentas de desenvolvimento para conhecer o comportamento de observação e os limites de limpeza.
Jobs de comandos de longa duração
Habilite jobs: true em um host/servidor SDK 0.4.0 para executar comandos além do prazo comum de solicitação. Jobs são desabilitados por padrão. Experimente o exemplo HTTP local completo, que informa progresso, um log de backend nomeado e um arquivo de resultado fixado por hash:
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs
Saída esperada: Command job: progress, backend log and pinned result file verified. Um handler de comando recebe job opcional em {signal, job}. Ele fornece reportProgress, log, addArtifact e invokeBackend. As concessões existentes de workspace.read/write e backend.invoke continuam se aplicando; nenhum caminho arbitrário de executável é aceito.
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);
}
O trecho de polling pressupõe um cliente conectado e um comando analyze configurado que registra report. Guarde o ID do job antes de começar. Desconectar ou abortar uma solicitação de polling não cancela a execução; reconecte à mesma geração e consulte/cancele explicitamente. Novas tentativas de início com o mesmo ID e entrada reutilizam o job retido; argumentos alterados geram conflito. Reiniciar o host perde os registros em memória. Habilite o armazenamento durável separado da 0.8 abaixo para recuperar metadados confirmados após o reinício.
Os estados são running, succeeded, failed, cancelled e timed_out. Saídas tardias são descartadas após o cancelamento; efeitos colaterais não são revertidos. Provedores ainda não finalizados mantêm seus slots. Há no máximo 4 jobs simultâneos, 32 registros retidos, 32 operações aninhadas por job, 256 eventos/64 KiB por job, 64 eventos por página e 16 artefatos. O runtime padrão é de 5 minutos e tem limite de 30 minutos. Registros terminais finalizados expiram 15 minutos após seu último evento.
Arquivos de resultados de texto são UTF-8 relativos ao espaço de trabalho, com até 256 KiB. O host os lê usando a concessão existente, registra SHA-256 e rejeita leituras posteriores se os bytes mudarem. Para saídas binárias ou maiores de simulação, use a API opcional de resultados binários. Artefatos parciais podem permanecer após cancelamento; verifique o estado terminal do job para confirmar o sucesso. Clientes antigos da 0.3 continuam usando métodos v1 existentes; jobs independentes do SDK exigem 0.4 nos dois lados. Consulte Jobs para conhecer contratos e limites exatos.
Observar arquivos do espaço de trabalho
project.watchFiles() amostra de 1 a 16 caminhos relativos explícitos de arquivos. O SDK 1.0.0 usa solicitações apenas de revisão em hosts compatíveis e leituras limitadas existentes em hosts antigos. O exemplo pressupõe um cliente conectado e aprovado pelo host. Altere design.sv com um editor externo para encerrar o loop; o snapshot de edição retido permanece inalterado.
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(); }
Os eventos são imutáveis: {kind, path, previousRevision, revision}. A primeira amostra emite initial; alterações posteriores emitem created, changed ou deleted. Arquivos ausentes têm revision null. includeInitial: false registra a base silenciosamente, e revisões iguais não produzem evento. Apenas not_found significa exclusão; erros de permissão, caminho protegido, tamanho e transporte encerram a observação.
Guarde o texto não salvo da UI separadamente e escolha ações explícitas para recarregar, mesclar e salvar rascunhos. Um salvamento verifica a revisão retida e pode informar um conflito. A observação amostra os caminhos explícitos de arquivos um de cada vez, em ordem; alterações intermediárias podem ser combinadas. Use as APIs de observação de projetos abaixo para descoberta e assinaturas de diretórios com escopo definido. As restrições existentes de raiz, tamanho de arquivo e caminhos protegidos se aplicam a servidores somente leitura e com gravação.
Observadores de arquivos e de jobs começam no primeiro next(), não buscam páginas em segundo plano enquanto o consumidor está pausado e compartilham um máximo de oito observadores ativos por cliente. Um next() pode ficar pendente; uma leitura simultânea falha com conflict. Break ou return() interrompe leituras pendentes; descartar o projeto interrompe seus observadores de arquivos, e desconexão/reconexão/descarte invalida todos os observadores antigos. AbortSignal encerra a observação com cancelled; respostas tardias não podem produzir resultados.
intervalMs é de 250–60000 ms (padrão 1000), aplicado entre passagens de arquivos ou leituras de jobs ociosas. requestTimeoutMs é de 1–30000 ms por solicitação, usando o prazo do cliente por padrão. O timeoutMs total é de 1–1800000 ms a partir do primeiro next(), incluindo pausas do consumidor. Arquivos não têm tempo limite total por padrão; jobs usam 30 minutos. Prazos excedidos informam budget_exceeded e liberam o slot. Esses limites são exportados como WORKSPACE_OBSERVATION_LIMITS.
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs
Saída esperada: Workspace observation: file changes, retained draft and resumed job verified. O exemplo completo cria seu próprio espaço de trabalho temporário e verifica alterações de arquivos, conflitos de rascunhos e retomada explícita de jobs. Consulte Observação para conhecer todas as opções e regras de duração.
Observar e retomar jobs
client.watchJob() acompanha um job existente usando jobs.events/get; waitForJob() retorna seu snapshot terminal. O trecho pressupõe um cliente conectado, um jobId iniciado explicitamente e um savedCursor (ou undefined). Confira getJobCapabilities() antes de iniciar um job. A observação nunca inicia, tenta novamente ou cancela o comando.
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);
Cada atualização congelada contém snapshot, events, after, nextCursor, dropped e hasMore. Processe no máximo 64 eventos por página e registre nextCursor depois de processá-la, junto do ID do job e da identidade do espaço de trabalho. dropped informa histórico expirado. Um snapshot pode ser mais recente que sua página de eventos; continue lendo snapshots terminais enquanto hasMore for true. O iterador termina após a última página. waitForJob() consome as mesmas páginas e retorna succeeded, failed, cancelled ou timed_out; inspecione o estado em vez de tratar toda promise resolvida como sucesso.
Interromper um iterador ou exceder o tempo limite apenas interrompe a observação. O comando do servidor continua até terminar ou até cancelJob() ser chamado explicitamente. Após uma reconexão aprovada pelo host, verifique o mesmo ID e a mesma geração do espaço de trabalho e crie um novo observador com o ID e cursor salvos do job. Observadores antigos são inválidos mesmo se a identidade não mudar. Jobs ausentes/expirados e falhas de transporte são informados sem reenvio; jobs em memória não sobrevivem ao reinício do host. A recuperação durável usa recoverJob() com uma nova conexão; observadores em tempo real não retomam entre gerações.
Os contratos v1 existentes de hello e jobs permanecem inalterados. A observação de arquivos usa fallback em hosts 0.3.2/0.4/0.5; a observação de jobs exige um host 0.4 ou posterior com o recurso habilitado. Uma capacidade de jobs desabilitada ou incompatível retorna um erro, preservando a escolha do chamador sobre executar comandos no host independente do SDK. Consulte Observação e Compatibilidade.
Revisões de arquivos e leituras condicionais
O SDK 0.6.0 acrescenta getFileCapabilities(), getFileRevision(path) e readFileIfChanged(path, knownRevision) aos clientes conectados. Leituras de revisão retornam {path, revision} sem conteúdo. Uma leitura condicional correspondente retorna {path, revision, notModified: true}; conteúdo alterado retorna notModified: false e content. Passe knownRevision: null para obter o conteúdo atual. Arquivos ausentes são rejeitados com not_found.
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);
Use um cliente já conectado e autorizado. Mantenha rascunhos não salvos separados deste cache. Leituras condicionais calculam o hash e retornam um snapshot do arquivo; uma leitura posterior ainda pode observar outra mudança. Salve com a revisão pertencente ao conteúdo retornado. Essas chamadas não atualizam snapshots de sessões de edição nem mesclam rascunhos. Uma resposta inalterada não tem campo content; um arquivo vazio alterado tem content: “”.
A observação de arquivos usa automaticamente leituras apenas de revisão quando há suporte. Os métodos opcionais fs.capabilities, fs.revision e fs.readIfChanged preservam o hello v1 estrito e os métodos originais de arquivo. Hosts conhecidos de espaço de trabalho SDK anteriores à 0.6 usam fs.read sem sondagem. Outros hosts devem responder à descoberta ou retornar um erro unsupported corretamente correlacionado. Cada recurso false seleciona seu próprio fallback limitado de leitura completa; a resposta do servidor antigo ainda transfere todo o conteúdo.
Recursos são armazenados em cache somente para a conexão atual e redefinidos na reconexão ou revogação. Respostas inválidas, divergências de caminho/revisão, permissões, autenticação, falhas de transporte e tempos limites não acionam fallback. Operações anunciadas que falham posteriormente não são rebaixadas silenciosamente. AbortSignal cobre a descoberta e a leitura; timeoutMs é aplicado a cada solicitação HTTP. Uma mudança de conexão invalida a operação antiga.
O servidor ainda faz uma leitura completa protegida do arquivo e calcula SHA-256 para cada amostra. Validação UTF-8, limite de 262144 bytes e verificações de caminhos/links protegidos continuam em vigor. Isso reduz bytes de resposta na rede mantendo as leituras protegidas de disco e o cálculo do hash para cada amostra. Uma medição local no Windows com Node 22.23.1 de 20 amostras inalteradas de 200000 bytes retornou 4003974 bytes para leituras completas, 3867 para revisões (99,903% menos) e 4247 para leituras condicionais (99,894% menos). A descoberta está incluída; headers HTTP, TLS e a base inicial de hello/conteúdo estão excluídos. Execute npm run benchmark:files em um checkout para reproduzir a fixture.
O SDK agora tem uma API 1.x estável com verificações funcionais documentadas no lançamento. Clientes existentes 0.3.2, 0.4, 0.5 e 0.6 mantêm suas APIs originais em hosts 0.7. Essas regras de compatibilidade descrevem clientes e hosts independentes do SDK. Consulte Revisões de arquivos para conhecer o contrato completo e as regras de migração.
Resultados grandes e binários de jobs
O SDK 0.7.0 acrescenta uma extensão opcional de arquivos de resultados binários. Um comando confiável registra um arquivo existente do espaço de trabalho; o host registra seu SHA-256 e comprimento. Clientes leem no máximo 64 KiB por bloco, e o downloader Node retoma um arquivo parcial e verifica a saída completa. O arquivo registrado máximo é de 1 GiB; as APIs existentes de arquivo UTF-8 e artefato de texto de 256 KiB mantêm seus limites.
Habilite jobs: true e binaryArtifacts: true no host de plugins pertencente ao servidor. Ambos usam false por padrão. Mantenha o token explícito, o aviso do operador, a fixação revisada do artefato de plugin e a concessão efetiva de workspace.read. O exemplo a seguir se baseia na configuração de espaço de trabalho acima; espaços de trabalho somente leitura podem registrar arquivos já gerados pela ferramenta configurada do operador.
const server = await createWorkspaceServer({
root, workspaceId, token, notice,
plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'],
jobs: true, binaryArtifacts: true, writable: false,
});
Registre o resultado dentro de um comando iniciado com startCommandJob. O registro processa o arquivo existente em streaming por SHA-256 usando um buffer de 64 KiB. A referência aponta para esse arquivo de origem, e não uma cópia imutável. Caminhos protegidos, travessia de diretórios, links e arquivos não regulares são rejeitados; alterações posteriores na origem falham com conflict.
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};
});
Use um cliente já conectado e autorizado e um ID de job existente. O destino é um caminho absoluto em um diretório real existente controlado pelo chamador. O auxiliar grava destination + “.dds-part” e se recusa a sobrescrever um arquivo final existente.
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);
Guarde a referência inteira {jobId, scope, artifact}. Após uma interrupção, reconecte explicitamente à mesma geração do host e chame o auxiliar novamente com essa referência e resume: true. Ele recalcula o hash do prefixo salvo e solicita apenas o sufixo ausente. Verifica SHA-256 de cada bloco, do stream completo recebido e do arquivo efetivo de staging antes de publicar. O comprovante final verified: true confirma a conclusão; callbacks síncronos de progresso continuam não verificados. Arquivos parciais corrompidos exigem remoção explícita ou um novo destino.
listJobBinaryArtifacts(jobId) retorna metadados binários registrados separadamente dos resultados de texto existentes. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) retorna base64 canônico com SHA-256 do bloco, intervalo exato e marcador EOF. decodeBinaryArtifactData de /artifacts retorna bytes Uint8Array. Consumidores no navegador devem verificar por conta própria o hash do arquivo inteiro; verificações individuais de blocos não provam que a saída montada corresponde à referência.
Resultados binários e de texto compartilham 16 slots e um namespace de IDs por job. Operações de captura/leitura binária são limitadas a quatro por host/espaço de trabalho, e downloads Node a quatro por processo. O timeoutMs de download Node é um prazo total, com padrão máximo de 30 minutos; requestTimeoutMs usa 5 segundos por padrão, com máximo de 30 segundos. A publicação exige suporte a hardlinks, como NTFS ou ext4. Use um destino controlado pelo chamador e um processo de host confiável; impeça gravadores simultâneos hostis no diretório de destino por meio dos controles de acesso do sistema operacional.
artifacts.capabilities, artifacts.list e artifacts.read opcionais preservam o hello v1, os snapshots e os eventos de jobs existentes. Hosts anteriores à 0.7 informam que a extensão está desabilitada; a operação binária solicitada termina com esse resultado de capacidade. Autenticação, respostas malformadas e erros de transporte continuam sendo erros. Reconexão, revogação, expiração do job ou mudança de geração do host invalidam operações antigas. A retenção de jobs permanece em memória por 15 minutos após o último evento do job terminal. Jobs cancelados podem deixar saídas parciais registradas da ferramenta; confirme o sucesso a partir do estado terminal do job. Isso descreve as APIs padrão de resultados em tempo real/origem. A API separada de resultados armazenados abaixo mantém bytes entre reinícios.
Execute npm run example:artifacts para uma transferência real de 2 MiB com interrupção, reconexão e retomada apenas do sufixo; npm run benchmark:artifacts usa 8 MiB. Uma execução local no Windows transferiu 8388625 bytes em 129 solicitações de blocos, retomando um prefixo de 65536 bytes e verificando o SHA-256 final. Base64 acrescenta sobrecarga; os corpos JSON de resposta totalizaram 11257419 bytes. As transferências usam memória limitada e blocos codificados. Consulte Artefatos binários para conhecer o contrato completo. O exemplo exercita as APIs independentes de transferência do SDK.
Jobs duráveis, histórico e novas tentativas explícitas
O SDK 0.8.0 acrescenta armazenamentos duráveis opcionais em um diretório do operador fora do espaço de trabalho. Forneça caminhos absolutos, um ID estável de espaço de trabalho, código revisado do plugin, SHA-256 do pacote, token e aviso. O exemplo também habilita bytes retidos de arquivos; omita artifacts de jobStorage para armazenar somente metadados de jobs. Respostas v1 existentes e padrões apenas em memória continuam compatíveis.
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},
});
Um provedor só inicia depois que sua intenção inicial é salva. Checkpoints posteriores são combinados; flushJobStore() aguarda os checkpoints solicitados, e não a conclusão do comando. A recuperação separa a conexão atual do escopo original de execução e informa live, completed, interrupted, expired, missing, corrupt ou unsupported. Um job interrompido nunca reinicia automaticamente; seu unrecordedTail é desconhecido.
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()});
O histórico filtra estado, classificação da recuperação, comando, horário de início e tentativa pai. As páginas contêm até 32 entradas, ordenadas por horário de início decrescente e depois por ID de job. Um cursor congela a composição por 60 segundos e deve reutilizar a mesma consulta; novos jobs são excluídos, registros removidos ou não autorizados são ignorados e a expiração é informada. O reinício perde os cursores. artifactCount, snapshotCount e resultAvailability descrevem referências registradas, e não comprovação atual de arquivos.
Uma nova tentativa explícita exige um novo ID de job, nova entrada validada, o mesmo pacote atualmente aprovado e um comando disponível. attemptOf vincula a nova execução ao seu pai inalterado. Repetir o mesmo ID, entrada, pai e tempo limite recupera a tentativa retida sem executá-la novamente, inclusive após reinício. Registros ausentes/expirados não podem fornecer essa garantia. Uma execução aceita pode continuar após o cancelamento da solicitação em espera; consulte o novo ID de job antes de decidir tentar novamente.
A retenção padrão omite entrada bruta, corpos de resultados, texto de progresso e rótulos de artefatos; logs têm dados sensíveis ocultados. Somente um redator determinístico explícito do host retém texto revisado. Tokens, segredos e consentimentos antigos nunca são restaurados. A identidade atual de espaço de trabalho/plugin, a permissão de leitura e cada concessão registrada são verificadas novamente. Metadados de jobs usam por padrão 256 registros, 64 MiB e 24 horas, com máximo de sete dias. Remoção e limpeza são operações explícitas do host.
O armazenamento local tem um único gravador, valida a identidade do espaço de trabalho/raiz e verifica a integridade dos metadados. A recuperação explícita de lock obsoleto só recupera um PID comprovadamente morto na mesma máquina. Arquivos desconhecidos/corrompidos exigem inspeção. No Windows, sincronização e renomeação de arquivos permitem recuperação após reinício do processo; a persistência depende do sistema de arquivos e do dispositivo de armazenamento. Consulte Armazenamento de jobs, Histórico e o exemplo de jobs duráveis.
Resultados armazenados e downloads após reinício
Com o armazenamento de artefatos habilitado, aguardar job.addArtifact() ou job.addBinaryArtifact() copia e verifica o arquivo completo antes do registro. Texto permanece limitado a 256 KiB; arquivos binários têm no máximo 1 GiB. O stream de origem e o arquivo efetivo de staging têm SHA-256 verificado. Cancelamento, erros de disco cheio, mutações e gravações parciais não publicam resultados utilizáveis. Arquivos publicados antes de uma falha, mas não registrados pelo job, podem permanecer para inspeção do operador.
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);
A lista separa referências de origem de metadados de snapshots e informa snapshots retained, expired, missing, corrupt ou unsupported. retained é um estado de metadados; getStoredJobArtifact() verifica os metadados e o arquivo armazenado inteiro antes de retornar uma referência nova da geração atual. Cada leitura verifica novamente a autoridade atual e a identidade do arquivo. Origens excluídas não afetam os bytes armazenados, e snapshots ausentes nunca recorrem a uma origem mutável. Para snapshots de texto, chame client.readStoredJobArtifactText(textReference).
Após um reinício, reconecte com as concessões atuais e obtenha uma nova referência. O ID do snapshot, o ID do armazenamento e o digest permanecem estáveis; a geração antiga é rejeitada. resume: true verifica novamente um prefixo .dds-part salvo contra esse snapshot, verifica os blocos e o arquivo completo de staging e publica sem sobrescrever o destino. Leituras precisam dos metadados retidos do job além dos bytes do arquivo. Consumidores de blocos no navegador devem verificar o digest completo; o adaptador Worker abaixo fornece retomada explícita em disco no navegador.
O armazenamento de artefatos usa por padrão 256 arquivos, 256 MiB e 24 horas, com armazenamento total máximo de 4 GiB e retenção de sete dias. Blocos têm no máximo 64 KiB, com quatro leituras simultâneas. inspect() informa consumo, horários de expiração, entradas inválidas e órfãos. remove(snapshot) e prune() são operações explícitas do operador. Jobs ativos e leituras individuais ficam fixados; expiração ou remoção entre blocos pode interromper a leitura seguinte. A limpeza opcional de órfãos só remove arquivos reconhecidos com um único link. Entradas corrompidas ou ambíguas precisam de inspeção.
A retenção de arquivos armazena bytes reais do projeto independentemente da ocultação de dados nos logs. Escolha-a deliberadamente. Plugin/comando atual, hash do pacote, espaço de trabalho e concessões registradas continuam necessários após reinício. Termine a manutenção e aguarde server.close(), artifacts.close() e store.close(), nessa ordem. Esta versão fornece operações de retenção de arquivos para hosts independentes do SDK.
Execute npm run example:stored-artifacts para um reinício real de processo filho, exclusão de origem, retomada verificada de download parcial, histórico e nova tentativa explícita. npm run example:durable-jobs também cobre encerramento forçado do processo. Consulte Resultados armazenados. Hosts conhecidos da 0.7 e anteriores informam armazenamento desabilitado sem sondagens desconhecidas. APIs existentes de resultados em tempo real/origem mantêm seu comportamento original.
Observar um projeto
O operador habilita projetos explicitamente e seleciona raízes permitidas no servidor independente do SDK. Essa configuração de ativação explícita usa sistemas de arquivos locais Windows/Linux. Hosts SDK conhecidos de 0.3–0.8 informam diretamente a indisponibilidade da capacidade, preservando seu comportamento existente de descoberta. Use o exemplo com o perfil compatível de sistema de arquivos local.
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
import {createWorkspaceClient, createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
// The operator chooses the workspace and its allowed local directories.
const server = await createWorkspaceServer({
root: operatorWorkspace, workspaceId, token, notice,
projects: {roots: ['rtl'], fileSystem: 'local'},
});
const client = createWorkspaceClient({url: server.url, token});
await client.connect();
const project = createWorkspaceProject(client);
if (!(await project.getProjectCapabilities()).enabled) {
throw new Error('Project tools are unavailable');
}
const observer = project.watchProject({
root: 'rtl', include: ['**/*.sv'], exclude: ['build/**'],
intervalMs: 1000, debounceMs: 50,
}, {signal});
for await (const event of observer) {
renderExternalView(event.snapshot, event.kind, event.reason);
}
project.dispose(); client.dispose(); await server.close();O primeiro evento é um snapshot completo. Alterações posteriores carregam deltas contra uma revisão anterior; dicas perdidas, mudanças durante a varredura inicial, varreduras incompletas e estouro causado por consumidor lento produzem uma visualização de ressincronização completa com uma razão. Renomeações podem aparecer como exclusão/criação. Cada arquivo é verificado em seu próprio momento de leitura; o snapshot representa esses estados amostrados, com gravações intermediárias combinadas conforme descrito acima.
O servidor e o cliente permitem quatro assinaturas cada, com quatro eventos na fila por assinatura nativa. O lease ocioso padrão é de 30 segundos; uma leitura posterior pode retornar not_found. Após uma pausa longa, crie um novo iterador para um snapshot inicial. break/return, cancelamento e descarte liberam assinaturas; se uma conexão rompida impedir a limpeza, os recursos remotos restantes expiram com seu lease.
Os limites padrão de varredura são profundidade 8, 512 entradas, 1 MiB por arquivo, 16 MiB no total e 10 segundos. Os máximos configuráveis são profundidade 32, 1000 entradas, 16 MiB por arquivo, 64 MiB no total e 30 segundos. Arquivos limitados podem carregar metadados sem um hash de conteúdo; confira complete e reasons. Prazos são verificados entre chamadas do sistema de arquivos; escolha deliberadamente o acesso do processo do host ao sistema operacional para essas chamadas.
Árvore do projeto e pesquisa
listTree retorna uma árvore, searchFiles pesquisa nomes relativos de arquivos por substring literal ou glob limitado, e searchText encontra texto literal em arquivos UTF-8. root é obrigatório; include/exclude são relativos a ele. As consultas usam os modos documentados de texto literal ou glob. A correspondência sem diferenciar maiúsculas de minúsculas normaliza apenas ASCII A–Z para manter estáveis as posições UTF-16 originais.
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);Correspondências de texto incluem um SHA-256 do conteúdo, intervalo UTF-16 com índice a partir de zero e um trecho limitado. Um cursor congela a composição original por no máximo 60 segundos e exige a mesma consulta. Páginas posteriores verificam novamente o conteúdo atual e marcam itens como current, changed, missing ou unverified; novos arquivos só aparecem em uma nova consulta. A correspondência e a revisão capturadas permanecem inalteradas.
Arquivos de texto são limitados a 256 KiB, consultas a 256 unidades UTF-16 e trechos a 512 unidades. Os padrões são 256 resultados (máximo 512), 32 itens por página (máximo 64) e uma resposta de 64 KiB (máximo 128 KiB). Arquivos binários, UTF-8 inválido e limites de bytes/profundidade/tempo/resposta são informados como resultados incompletos com razões. Há duas consultas simultâneas e oito visualizações retidas de cursor; libere explicitamente cursores não usados.
Rascunhos do projeto e reconexão
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 o snapshotRevision de uma consulta diferir do snapshot.revision observado, libere o cursor antigo e repita a mesma consulta de raiz/filtro. A observação nunca altera edit.snapshot nem o conteúdo de rascunhos pertencentes ao chamador. Após uma mudança externa, movimentação ou exclusão, a condição CAS original informa um conflito; o chamador escolhe recarregamento explícito, mesclagem ou salvamento separado.
O cliente verifica geração da conexão, raiz/filtro, hash da consulta, posições de páginas, SHA-256 do snapshot e continuidade dos eventos. Respostas tardias são descartadas após revogação, desconexão ou reconexão. Cursores de observação e de consulta são separados e não são restaurados automaticamente. server.revokeProjects() encerra o acesso ao projeto; habilitá-lo novamente exige uma nova geração do servidor.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browserExemplos Node instalados verificam criação, pesquisa, alterações externas, rascunhos retidos, conflitos CAS e reconexão. Para o exemplo no navegador, abra a URL de loopback impressa e escolha Executar cenário. Ele usa somente seu espaço de trabalho temporário, removido quando o servidor de exemplo para. Solicitações HTTP usam cinco segundos por padrão; configure deliberadamente os tempos limites de cliente e servidor para varreduras maiores.
Observação do projeto · Contratos de árvore/pesquisa · Ferramentas HTTP de projeto
Transferir em streaming e verificar artefatos no navegador
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);O auxiliar compatível com navegador recebe no máximo um bloco de 64 KiB por vez, espera o destino selecionado e calcula incrementalmente o hash de todo o arquivo. Ele valida intervalos exatos, identidade, base64 e cada hash de bloco antes de gravar. Um destino com releitura então lê novamente, de forma independente, os bytes salvos; verification é stored somente quando os dois hashes completos correspondem. Sem releitura, verification é received e storedSha256 é null. O progresso atingir todos os bytes não é conclusão.
O aplicativo abre os seletores necessários, seleciona handles de arquivos ou diretórios OPFS, concede permissões e fornece o destino exato aos adaptadores SDK. Os destinos assíncronos graváveis de arquivo/OPFS mantêm staging até o fechamento e o descartam se houver falha antes do commit. Para arquivos parciais seguros entre recarregamentos, use o adaptador dedicado de Worker abaixo. Os limites são 1 GiB por arquivo, quatro streams diretos simultâneos e um prazo total de 30 minutos.
Enviar arquivos selecionados
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.Uploads são desabilitados por padrão. O operador configura um espaço de trabalho Node local, um diretório isolado de staging, raízes permitidas e uma entidade de acesso; depois concede workspace.write ao plugin selecionado na fixação exata do seu arquivo. O auxiliar calcula previamente o hash da origem selecionada antes de começar. O servidor aceita blocos sequenciais de 64 KiB, verifica duplicatas e o conteúdo completo e confirma somente após verificações condicionais do destino. Nenhum byte de staging aparece nas listagens normais do espaço de trabalho.
expectedRevision: null exige um destino ausente; um SHA-256 exige o destino atual correspondente. O cancelamento mantém o prefixo reconhecido pelo servidor. Uma nova operação explícita de recover consulta a autoridade atual, valida a mesma origem/especificação e retoma apenas o prefixo correspondente. Uma resposta de commit perdida é incerta até ser consultada; ela não autoriza repetir o commit nem reverter um arquivo. Os limites máximos são 1 GiB por arquivo, 4 GiB por armazenamento e quatro sessões ativas; os padrões são menores. Hosts conhecidos de 0.3–0.9 informam uploads desabilitados sem sondar novos métodos.
Programar transferências de arquivos
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();Uma fila pertencente ao chamador mistura jobs de upload, download de origem em tempo real e download de resultados armazenados. Ela limita jobs retidos (32), etapas simultâneas (4), simultaneidade de conexões do cliente, reservas de blocos decodificados (64–256 KiB), taxa e novas tentativas. Trabalho elegível avança apesar de uma conexão saturada, e vantagens iniciais limitadas por prioridade evitam que pequenos jobs elegíveis fiquem indefinidamente sem atendimento. Um job pausado termina sua etapa atual e então espera; a pausa pode manter um lock de armazenamento. Prazos totais incluem espera na fila e pausa.
Novas tentativas automáticas são limitadas a 429/503 reconhecidos pelo SDK, perda de rede ou tempo limite de solicitação durante uma operação idempotente de bloco exato, com backoff e jitter limitados. Falhas de begin/commit, autorização, checksum, intervalo, origem ou destino devolvem o controle ao chamador para uma decisão explícita de recuperação. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes e remainingBytes são separados; somente um comprovante verificado produz completed. Um arquivo já confirmado continua confirmado após cancel/dispose.
Retomar downloads no navegador
// 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.A recuperação persistente exige um Worker dedicado, acesso síncrono OPFS e Web Locks. O chamador seleciona novamente seu diretório e UUID parcial após recarregar e obtém uma nova referência armazenada aprovada. O destino armazena dois nomes exatos de arquivos de dados/metadados, a identidade completa imutável do snapshot, a expiração e os hashes dos prefixos atual/anterior. Ele não armazena token, concessões ou escopo antigo de conexão. Cada bloco de dados é sincronizado antes de fechar o pequeno stream de metadados.
O destino e o auxiliar recalculam independentemente o hash do prefixo. Uma cauda sem checkpoint só é truncada depois que o prefixo registrado corresponde. Metadados além do tamanho real do arquivo só podem recorrer ao checkpoint anterior se esses bytes e seu hash corresponderem; corrupção, entradas ausentes, expiração ou um snapshot diferente falham sem reiniciar silenciosamente. Um lock exclusivo para toda a origem rejeita outra aba, permanece mantido durante a releitura e é liberado no fechamento ou no encerramento do Worker. Reabrir então exige recuperação explícita.
Metadados locais são limitados a 16 KiB e quatro sessões abertas de destino. A retenção padrão é de uma hora, com máximo de 24 horas limitado pela expiração do snapshot do host. Planeje o armazenamento conforme a quota e a remoção de dados pelo navegador e proteja scripts e dados da origem por meio da política de segurança do aplicativo. Qualifique o comportamento diante de perda de energia no ambiente de armazenamento escolhido. Chromium 154 no Windows foi exercitado com cancelamento, recarregamento, reinício do host, conflito entre duas abas e encerramento da aba proprietária, com hashes completos dos arquivos salvos. Use esse perfil medido de navegador/sistema operacional como referência para qualificar outras combinações.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeStreaming · Uploads · Fila de transferências · Recuperação em Worker
Ajuda de assinaturas e assistência à conclusão
Declare signature-help, completion-resolve e completion-snippets conforme necessário no manifesto v2; modificadores de conclusão também exigem completion. O host deve conceder document.read e language.provide. Conclusões literais existentes continuam válidas. languageCapabilities() informa a implementação do SDK e seus limites, sem conceder permissão.
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);O aplicativo fornece a posição atual e o host; a preparação retorna dados sem gravar um documento ou arquivo. A ajuda de assinaturas suporta até 16 assinaturas, 64 parâmetros cada e deslocamentos UTF-16 dos rótulos de parâmetros. A resolução de conclusão mantém privados os dados do provedor, retorna um token de host de uso único e fixa o rótulo/inserção/intervalo selecionados. Tokens vinculam provedor, escopo e documento, expiram após 60 segundos e são limitados a 128 entradas, 4 MiB e quatro operações reais de resolução. Mudanças no documento/provedor os descartam.
Snippets suportam $n, ${n}, ${n:literal}, $0 e escapes documentados, com espelhos e paradas de tabulação ordenadas. Variáveis, aninhamento, escolhas, transformações e comandos executáveis são rejeitados. Limites UTF-16/CRLF e edições extras sobrepostas são verificados. Provedores executam como código confiável dentro do processo com o acesso do processo do host ao sistema operacional. Um cancelamento ignorado mantém ocupado o slot pendente real até o provedor concluir.
Edições revisadas do espaço de trabalho e renomeação
prepare-rename retorna um intervalo/marcador validado ou null; rename retorna uma proposta WorkspaceEdit ou null. Propostas suportam edit, create, move e delete em caminhos relativos distintos de arquivos. São verificados o SHA-256 atual da origem, a ausência do destino, a política de caminhos protegidos, a geometria das edições UTF-16 e os limites. Recursos de linguagem autorizam propostas; o cliente de espaço de trabalho fornece acesso a arquivos e mutações aprovados separadamente.
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);O chamador usa um cliente conectado e autorizado de espaço de trabalho e um journal confiável. A prévia contém snapshots completos de antes/depois e um digest; apply exige o planId/digest revisado e uma política atual do host que retorne true. Cada arquivo passa por verificação preliminar, e cada operação usa o CAS existente por arquivo e os recursos atuais de gravação/gerenciamento. O journal persiste e relê a intenção antes de cada mutação e um comprovante depois. Um conflito ou incerteza interrompe gravações posteriores; cada operação de arquivo concluída tem seu próprio resultado CAS e comprovante no journal.
O adaptador opcional workspace-edits-node armazena um journal limitado fora do espaço de trabalho selecionado, vincula sua identidade e usa um lock de gravador único, arquivos regulares e checkpoints de checksum. Após o encerramento do processo, recoverStaleLock é uma escolha explícita e só recupera um proprietário comprovadamente morto. A recuperação informa applied/not-applied/conflicted/unknown a partir dos bytes atuais; o chamador escolhe explicitamente a próxima ação. A compensação cria uma nova proposta inversa para nova revisão. No Windows, o adaptador sincroniza arquivos e executa operações de renomeação. As verificações documentadas abrangem encerramento do processo e recuperação; a persistência depende do sistema de arquivos e do dispositivo de armazenamento. Os limites incluem 32 mudanças, 1000 edições, 256 KiB por arquivo, uma prévia de 8 MiB e 64 planos retidos no journal.
Formatação e ações de código de diagnósticos
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 exigem um caminho e opções tabSize/insertSpaces; somente a formatação de intervalo recebe uma seleção. Um resultado é null ou exatamente uma edição do arquivo atual com o hash do snapshot atual. Edições de intervalo ficam dentro da seleção. endOfLine seleciona preserve, lf ou crlf para o texto inserido; bytes não editados permanecem inalterados. Propostas com conteúdo idêntico são normalizadas para null. prepareFormatting não realiza gravação.
O host vincula solicitações de ações e tokens de resolução à revisão aceita do diagnóstico e ao snapshot atual. Publicação posterior de diagnósticos, mudança de documento ou descarte do provedor invalida seleções antigas. Chamadas de diagnósticos fora de ordem não sobrescrevem o pacote aceito mais recente. Até 100 ações carregam rótulos simples, índices limitados de diagnósticos, edições propostas, dados privados de resolução ou uma razão de desabilitação. Campos desconhecidos de comando/URL/shell são rejeitados. Edições de ações podem ir além da seleção, então revise a proposta completa; formatação e ações nunca aprovam suas próprias gravações.
Exibição semântica, dobramento, dicas e símbolos
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);Tokens semânticos usam uma legenda com nomes exclusivos e nove chaves de estilo do host, além de cinco inteiros por token: delta de linha/início, comprimento UTF-16, índice de tipo e bits de modificadores. Tokens não podem se sobrepor, dividir um substituto, cruzar uma linha ou sair do documento atual. O host sempre retorna um array completo normalizado e um UUID do host, com updateKind full/delta/fallback. Um recurso separado semantic-tokens-delta habilita provideDelta em relação a dados anteriores do provedor; o cache armazena identidade e dados de tokens, e não texto antigo do documento.
Uma base de cache é vinculada ao provedor, escopo, URI e linguagem, com no máximo oito entradas, 4 MiB e 60 segundos. Versões de documento normalmente crescentes preservam uma possível base de delta enquanto tornam desatualizado o resultado antigo de exibição. Uma base perdida/expirada, delta null ou ID de base do provedor divergente permite no máximo um fallback completo dentro do tempo limite original. Dados inválidos ou erros de provedor falham sem nova tentativa. Desativação, remoção de registro e substituição de documento limpam as bases afetadas. Chame validateLanguageResult imediatamente antes de renderizar; um objeto copiado, liberado ou desatualizado falha.
Os limites são 20000 tokens semânticos, 64 tipos de tokens, 16 modificadores e 64 edições de delta; dobramento permite 1000 intervalos com profundidade 32 e rejeita intervalos cruzados. Inlay hints permitem 1000 rótulos simples de uma linha dentro do intervalo solicitado. Símbolos hierárquicos permitem 1000 entradas totais e 16 níveis, com filhos/seleções contidos e irmãos ordenados sem sobreposição. O contrato original simples de document-symbols permanece inalterado. O exemplo no navegador exercita full/delta/fallback, dobramento, navegação e ciclo de vida; uma dica semelhante a HTML permanece texto literal.
npm run example:assistance
npm run example:workspace-edits
npm run example:language-editing
npm run example:language-display
npm run example:language-display-browserAssistência · Edições revisadas · Formatação/ações · Exibição
Configurações tipadas e referências a segredos
O módulo /settings fornece um armazenamento em memória do operador para um plugin. Uma definição versionada declara cada chave, esquema de dados, padrão, escopos permitidos de usuário/espaço de trabalho e metadados de exibição. Valores efetivos substituem cada chave inteira na ordem default < user < workspace. read(workspaceId) retorna valores e origens imutáveis e uma revisão de todo o armazenamento. Objetos aninhados não são mesclados recursivamente; um valor ausente sem padrão permanece ausente.
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}, ...}).Gravações validam toda a transação e usam CAS com expectedRevision. reset remove uma chave de uma camada; readOnly exige um padrão e nenhum escopo gravável. Assinaturas combinam alterações síncronas e retornam handles descartáveis. migrate(nextDefinition, callback, options) explícito valida o próximo estado e confirma somente se sua revisão ainda corresponder. Falha, cancelamento ou tempo limite preserva a definição e o estado antigos. Exportação/importação são dados simples; o operador é responsável pela persistência e criptografia. Os limites incluem 64 chaves, 32 camadas de espaço de trabalho, 1 MiB de estado exportado e uma migração real.
Plugins de espaço de trabalho declaram settings e settings.read, e o operador monta o armazenamento correspondente com essa concessão. context.settings é somente leitura e vinculado ao plugin e ao espaço de trabalho selecionado. O resolver /secrets emite separadamente referências opacas para um plugin, espaço de trabalho, lista permitida de comandos e duração. O manifesto deve declarar secrets.resolve, e o host deve concedê-lo. Campos de entrada usam type: object com format: dds-secret-reference; strings comuns e objetos parecidos não conferem autoridade sobre segredos.
Somente referências presentes na entrada validada estão disponíveis por options.secrets.withSecret de um comando. Cada execução tem um novo ID; o resolver verifica escopo, expiração, revogação e autorização atual ao redor da resolução e do callback. O callback retorna undefined e recebe uma cópia apagada no abort e em toda saída. Erros de provedores têm dados sensíveis removidos. Obtenha o lease antes dos efeitos que exigem essa autoridade. A duração padrão de referência é de 60 segundos, no máximo uma hora; os limites são 128 referências, 8 leases reais e 16 KiB de material. Código confiável dentro do processo pode reter cópias e usa o acesso do processo do host ao sistema operacional. Mantenha o material secreto dentro do callback autorizado e classifique explicitamente as strings do aplicativo antes de armazenar configurações, pacotes, logs ou resultados.
Esquemas e formulários estruturados de comandos
Comandos podem declarar inputSchema e outputSchema usando um envelope schemaVersion: 1. Parâmetros primitivos existentes continuam compatíveis; declarar parameters e inputSchema juntos é rejeitado. O host valida e aplica padrões de entrada antes de iniciar um handler ou job e então valida a saída antes de publicar sucesso. Padrões de saída nunca são aplicados. Novos metadados de esquema/exibição exigem um peer compatível com 0.12; validadores estritos antigos os rejeitam, enquanto definições legadas mantêm seu 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);O subconjunto limitado suporta objetos fechados, arrays, strings, números finitos, inteiros seguros, booleanos, null, enums primitivos, limites e padrões validados. Palavras-chave desconhecidas, referências remotas, regex, unions, coerção, accessors e protótipos personalizados são rejeitados. Esquemas permitem 32 KiB, profundidade 8 e 128 nós; valores permitem 64 KiB. Um comando completo mantém o orçamento de 16 KiB de metadados. DataValidationError local expõe code, reason e caminhos conhecidos de campos, como /input/options/names/0; falhas de HTTP e jobs expõem códigos seguros sem os valores rejeitados.
describeDataForm retorna caminhos, tipos, escolhas, padrões, indicadores de obrigatoriedade e dicas de referência a segredos. Metadados compartilhados de exibição carregam label/help/order literais e nomes, descrições e dicas de teclado de acessibilidade. O host é responsável pela renderização e interação. Esses esquemas descrevem dados simples; o host controla explicitamente renderização, acesso a recursos e execução de comandos.
Metadados de localização e acessibilidade
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.Catálogos usam tags base canônicas BCP 47 e arestas explícitas acíclicas de fallback. Até oito preferências negociam tags exatas, depois ancestrais e o padrão. O idioma padrão define todas as chaves; traduções podem omitir chaves, mas não inventá-las. A busca por chave segue arestas ordenadas de fallback e depois o padrão. Cada tradução e seus argumentos devem corresponder ao conjunto exato de marcadores {name}. Isso é interpolação literal sem expressões ICU. resolveMessage informa o idioma e a direção reais da origem, permitindo que um fallback em inglês dentro de uma página RTL mantenha lang=en e dir=ltr.
A formatação de números suporta decimal/percentual; a formatação de datas usa um epoch explícito e UTC por padrão; a seleção de plural retorna uma categoria cardinal/ordinal de Intl para a escolha da mensagem pelo chamador. Hosts são responsáveis pelos dados e pelo suporte de Intl. validateLocalizedSurfaces verifica chaves de manifesto/comando/configurações/esquema e arquivos auxiliares de exibição de temas, incluindo comprimentos resolvidos de exibição e traduções ausentes. JSON/XML de temas continua compatível. Os limites de catálogo são 32 idiomas, 256 chaves e 256 KiB; rótulos estáticos não podem conter marcadores.
Os auxiliares de /accessibility informam nomes ausentes, atalhos normalizados duplicados e contraste explícito de pares de cores opacas em temas claros/escuros. Os hosts usam essas dicas para implementar atalhos de teclado e avaliar a acessibilidade das próprias interfaces. O exemplo independente inclui fixtures EN/KO, árabe parcial e rótulos longos. Ele exercita configurações com escopo, referências negadas/revogadas, campos inválidos, Ctrl+Enter e mudanças de idioma durante um comando ativo. O layout no navegador foi verificado em tamanhos de desktop/mobile nos temas claro/escuro.
npm run example:configuration
npm run example:configuration-browserConfigurações · Referências a segredos · Esquemas de comandos · Localização
Modelos de desenvolvimento e geração
Seis modelos, dependências exatas de arquivos, revisão da geração, preservação de conflitos e verificações de doctor.
Contratos, exemplos e limites completos
Testes determinísticos e reprodução
Fixtures sintéticas explícitas, tempo virtual, falhas, rastros limitados apenas com hashes e limpeza de recursos.
Contratos, exemplos e limites completos
Diagnósticos locais e depuração
Perfis locais de adesão explícita e um depurador filho confiável com endpoint temporário de loopback e prazo total.
Contratos, exemplos e limites completos
Conformidade do host
18 perfis versionados distinguem contratos compatíveis, incompatíveis e com falha; adaptadores personalizados mantêm autoridade explícita.
Contratos, exemplos e limites completos
Suporte e migração do SDK
Consulte o inventário de exports, a política estável/opcional/experimental, os peers exatos, as datas de runtimes e os exemplos de migração.
Contratos, exemplos e limites completos
Aceitação de lançamento
O lançamento do SDK apresenta cargas de trabalho combinadas de falhas e salvaguardas medidas de desempenho como validação funcional de seus contratos SDK e hosts independentes.
Contratos, exemplos e limites completos
1.1 Ferramentas de dependências, proveniência e atualização
A 1.1.0 acrescenta pacotes offline determinísticos de dependências revisadas, SBOMs CycloneDX, assinaturas separadas com chaves Ed25519 do operador, aprovação/ativação/rollback vinculados a digests e comparação explícita com upstream. Cinco pontos de entrada exclusivos de Node incluem declarações, esquemas e exemplos independentes. O operador concede execução explicitamente após revisar a assinatura, e jobs antigos mantêm seu hash original. O operador escolhe o fluxo de distribuição, implantação e monitoramento. A versão publicada do SDK documenta validação funcional por meio de seus exemplos independentes de ferramentas de lançamento.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsGuia completo de pacotes, assinaturas, atualizações e upstream
1.2 Fluxos de trabalho, cache, streams de ferramentas e LSP
A 1.2.0 acrescenta DAGs revisados de comandos com jobs/concessões por etapa, checkpoints duráveis e recuperação explícita por nova tentativa; cache determinístico baseado em conteúdo e execução incremental; streams limitados de ferramentas UTF-8/JSONL/texto; e uma ponte opcional stdio LSP 3.17. Sete novos pontos de entrada levam o pacote a 50 exports e 107 esquemas, com declarações e exemplos independentes instalados, sem dependências npm de runtime. O parser de streams de ferramentas também funciona em navegadores; fluxos de trabalho, armazenamentos, processos externos e LSP exigem Node. O lançamento do SDK documenta verificações funcionais de adaptadores com TypeScript 5.9.3 e language-server 5.3.0. A ponte aceita diagnósticos vinculados a uma versão do documento. O host independente do SDK gerencia recuperação explícita por nova tentativa, armazenamentos locais e configuração de processos.
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.mjsGuia completo de fluxos de trabalho, cache, ferramentas e LSP