DDS Plugin SDK

Instale el DDS Plugin SDK 1.2 público y use flujos de trabajo, caché, flujos de herramientas, LSP y API estables.

Los ejemplos de espacios de trabajo de usuario siguientes describen un host de desarrollo conectado explícitamente y controlado por el cliente. Elija WSL u otro host para estos ejemplos independientes del SDK. La aplicación habitual de Windows de Digital Design Studio utiliza su entorno de ejecución nativo de Windows. Configure el descubrimiento, los permisos y las capacidades de plugins para el host SDK seleccionado; los trabajos gestionados del motor Cloud utilizan su propia vía de ejecución.

1. Instalar el SDK

DDS Plugin SDK 1.2.1 proporciona API de JavaScript, declaraciones de TypeScript, proveedores de lenguaje, temas, herramientas del espacio de trabajo y trabajos de comandos. Los almacenes persistentes opcionales añaden historial de trabajos, reintentos explícitos e instantáneas verificadas de texto y binarios que sobreviven a la eliminación del código fuente y al reinicio del proceso. Utilice Node.js 22 o 24. Instale la versión estable del SDK desde la versión oficial de GitHub. Para un plugin de comandos independiente, utilice Herramientas de desarrollo después de instalar:

1.0.0 publica la API estable del SDK, 18 perfiles de conformidad de anfitriones, la política de soporte y migración y comprobaciones medidas de cargas de trabajo combinadas. Los plugins nuevos utilizan >=1.0.0 <2.0.0. La versión publicada del SDK atribuye estos resultados a la validación funcional del SDK y de anfitriones independientes.

0.13.0 añade seis plantillas de desarrollo, tipos y esquemas generados, escenarios de prueba deterministas y diagnósticos locales opcionales. El SDK empaquetado y los proyectos generados funcionan fuera del árbol de código fuente; la reproducción sintética y la depuración mediante loopback se seleccionan explícitamente.

0.12.0 añade ajustes tipados con ámbitos y migraciones explícitas, referencias de secretos limitadas a la ejecución, entradas y salidas estructuradas de comandos, catálogos de idiomas y metadatos de accesibilidad. El SDK público y los ejemplos independientes comprueban conflictos de ajustes, entradas inválidas, autoridad revocada y traducciones alternativas.

0.11.0 añade ayuda de firmas, completado diferido, fragmentos acotados, ediciones y renombrados revisados de múltiples archivos, formato y acciones de código, tokens semánticos, plegado, sugerencias y símbolos jerárquicos. Las propuestas, su revisión, las comprobaciones de autoridad actual y la aplicación condicional son pasos distintos del anfitrión. Los anfitriones muestran y aplican resultados solo mientras la identidad de su documento siga siendo actual. Estas funciones se prueban mediante el SDK público y ejemplos independientes.

0.10.0 añade descargas en streaming del navegador, subidas de archivos seleccionados, una cola mixta de transferencias y recuperación de puntos de control OPFS de Worker. Las transferencias comprueban la autoridad actual, la identidad del archivo y los hashes de los fragmentos y del conjunto, distinguiendo el progreso de bytes del almacenamiento verificado. Estos ejemplos prueban anfitriones y clientes del SDK público.

0.9.0 añade árboles de proyecto con ámbito, búsqueda de nombres y texto de archivos y observación de cambios para directorios locales seleccionados por el operador. Utilícelos desde el cliente HTTP o el asistente de proyectos, conservando las instantáneas de edición y los borradores sin guardar. Los ejemplos de proyectos siguientes abarcan la creación, la búsqueda, los cambios externos y la gestión de conflictos.

Bash
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"

El primer ejemplo de diagnósticos utiliza código confiable en un anfitrión local de pruebas. Los temas utilizan la importación XML existente de DDS. Para integraciones de herramientas existentes, consulte Plugins y herramientas de terceros.

2. Escribir su primer plugin

Cree plugin.mjs en el proyecto nuevo. Este plugin comprueba documentos de texto sin formato y comunica un diagnóstico informativo en cada línea que contenga 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);
  },
}));

El manifiesto declara la versión 1 del protocolo, la capacidad diagnostics, el anfitrión test-host y los permisos document.read y diagnostics.publish. El proveedor recibe una instantánea del documento y una AbortSignal. Los rangos de diagnóstico utilizan líneas basadas en cero y desplazamientos de caracteres UTF-16.

3. Ejecutarlo localmente

Cree run.mjs junto a plugin.mjs. Active el plugin, proporcione un documento y solicite diagnósticos. Libere siempre los recursos del anfitrión al 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();
}
Bash
node run.mjs

Salida esperada (la línea y la columna impresas están basadas en uno):

Texto

Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.

4. Probar su plugin

Guarde esta prueba como plugin.test.mjs. Comprueba el rango del diagnóstico y confirma que editar el documento elimina el 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();
  }
});
Bash
node --test plugin.test.mjs

La prueba debería pasar. Añada casos de prueba para su propio lenguaje, cancelación, resultados inválidos y documentos grandes. Mantenga actualizada la versión del documento para que se rechacen resultados de una instantánea anterior.

5. Crear y aplicar un tema

Guarde esta paleta clara y oscura como theme.json. Los seis colores de cada paleta son obligatorios. Los tokens semánticos opcionales personalizan las búsquedas, las selecciones, HintsBox y el lienzo GDS; los tokens omitidos utilizan los valores predeterminados de DDS.

theme.json

{
  "name": "Hello Ocean",
  "colors": {
    "light": {
      "backdrop": "#dbe8ef",
      "navigation": "#edf5f8",
      "tool": "#f3f8fb",
      "main": "#ffffff",
      "text": "#183b4e",
      "muted": "#486477"
    },
    "dark": {
      "backdrop": "#0c1922",
      "navigation": "#102430",
      "tool": "#17303e",
      "main": "#1c3949",
      "text": "#e8f4fb",
      "muted": "#adcadb"
    },
    "metrics": {
      "panelRadius": 16,
      "controlRadius": 8
    }
  }
}

Cree export-theme.mjs junto a ella. parseTheme valida los datos de colores y serializeThemeXml exporta XML de DDS versión 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');
Bash
node export-theme.mjs

El comando escribe hello-theme.xml e imprime Created hello-theme.xml. En DDS, abra Complementos → Instalar tema…, seleccione el XML y después elija Aplicar para Hello Ocean. Alterne entre apariencia clara y oscura para ver ambas paletas.

También puede usar Configuración → Generalidades → Apariencia → Importar XML. Guarde el tema actual con Exportar XML antes de sustituirlo. El importador XML lee los datos de apariencia del tema.

La guía de temas enumera todos los tokens y métricas admitidos. El ejemplo Hello Ocean incluye el tema completo, XML listo para importar y una vista previa HTML local.

Referencia de XML de temas

Descargue XML de Hello Ocean y su JSON editable. El XML contiene paletas claras y oscuras completas, los 28 colores opcionales de roles de cada modo y cuatro métricas explícitas. Guarde el archivo XML localmente antes de importarlo. Estos ejemplos originales del SDK utilizan Apache-2.0; conserve el aviso al compartirlos.

Empiece con Configuración → Generalidades → Apariencia → Exportar XML para respaldar el tema actual. Importe el XML descargado, revise el borrador y elija Aplicar. Descartar cambios conserva el tema aplicado. Alterne entre apariencia clara y oscura para revisar ambas paletas. Para recuperar, elija un tema integrado o importe su copia guardada. Una importación rechazada conserva el tema actual.

DDS, ALcad, los editores compartidos, la navegación de proyectos, los ajustes y las ventanas emergentes utilizan la paleta del entorno de trabajo compartido en ese perfil. Cloud y escritorio utilizan el mismo formato de tema; impórtelo por separado en cada perfil. gdsBackground controla el lienzo GDS de forma independiente. Otros colores de lienzos de diseño, capas y simulación pueden tener sus propios ajustes. El XML contiene la paleta y las métricas de apariencia para este perfil de tema.

Elemento

Regla

<dds-theme version="2" name="Hello Ocean">

Una raíz; un nombre sin espacios en los extremos de 1 a 80 unidades de código UTF-16; como máximo 65536 bytes UTF-8 para todo el XML.

<palette mode="light">, <palette mode="dark">

Ambos obligatorios, cada uno con los seis colores siguientes.

<tokens mode="light">, <tokens mode="dark">

Sobrescrituras opcionales de v2. Los roles omitidos siguen los valores predeterminados de DDS para ese modo.

<metrics>

Sobrescrituras numéricas opcionales de v2.

Versión 1

Solo ambas paletas. Los archivos v1 existentes siguen siendo compatibles; el exportador del SDK genera v2.

Clave de paleta obligatoria

Uso

backdrop

Fondo exterior del espacio de trabajo

navigation

Navegación de proyectos

tool

Paneles de herramientas y controles

main

Espacio de trabajo principal y ajustes

text

Texto principal

muted

Texto secundario

Claves opcionales de roles (28)

Uso

search, searchText, searchPlaceholder

Fondo, texto y marcador de posición de búsqueda compartida

searchBorder

Campo de compatibilidad; los campos actuales de búsqueda compartida no tienen bordes

selection, selectionText

Filas y texto seleccionados

tabActive, tabInactive, tabText

Pestañas del editor

rail, panelBorder, popover

Barras de herramientas, límites de paneles y ventanas emergentes

focus

Contorno del foco de teclado

success, warning, danger, info, aiBall

Colores de estado y fondo de la esfera de IA

hintsBoxBackground, hintsBoxDetailsBackground

Fondos de sugerencias y detalles

hintsBoxText, hintsBoxDetailsText, hintsBoxMutedText

Texto de sugerencias, detalles y texto secundario

hintsBoxSelectedBackground, hintsBoxSelectedText

Sugerencia seleccionada mediante teclado

hintsBoxHoverBackground, hintsBoxHoverText

Sugerencia bajo el puntero

gdsBackground

Fondo del lienzo del visor GDS

HintsBox es la función compartida de sugerencias de código. Encuentre sus colores en Personalizado → Colores y forma detallados → HintsBox y el fondo GDS en Pantalla. Edite juntos los tres colores de búsqueda para lograr un contraste legible. Este fragmento pertenece a un tema v2; conserve las dos 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

Valor predeterminado actual de DDS

panelRadius

Entero de 0 a 24

14

controlRadius

Entero de 0 a 16

6

popoverRadius

Entero de 0 a 24

16

popoverOpacity

Número de 0,6 a 1

0,72

Escriba las métricas como <number key="popoverOpacity" value="0.9"/> dentro de <metrics> sin unidades. Los valores de radio se expresan en píxeles. El SDK deja ausentes las métricas omitidas; la versión instalada de DDS aporta sus valores predeterminados. Establezca valores explícitos para lograr una apariencia coherente. Hello Ocean fija deliberadamente 16, 8, 12 y 0,9. Los ajustes de transparencia reducida y colores forzados pueden cambiar la representación final.

Cada color debe ser un #RRGGBB de seis dígitos; se rechazan el canal alfa, los nombres CSS, las variables, las URL y los estilos. Se rechazan claves o modos duplicados, elementos o atributos desconocidos, espacios de nombres, DTD, entidades e instrucciones de procesamiento. Se permiten declaraciones XML y comentarios. Si falla la importación, compruebe el tamaño del archivo, la versión, ambas paletas completas y los valores admitidos; después reintente con la copia de seguridad sin modificar. Los temas de otros editores necesitan convertirse a este formato de DDS.

6. Ejecutar un espacio de trabajo en su entorno

Ejecute el anfitrión, el SDK, los plugins y las herramientas en su propio entorno WSL, contenedor o servidor. Los archivos del proyecto permanecen bajo la raíz que elija. El cliente independiente del SDK los lee y edita mediante la conexión; recibe metadatos de plugins y resultados de comandos mientras el código de los plugins se ejecuta en su entorno.

En el proyecto SDK creado arriba, guarde este asistente como copy-workspace-example.mjs. Copia el servidor editable, el plugin, la herramienta y el proyecto de muestra, preservando la disposición de los archivos de licencia del ejemplo.

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');
Bash
node copy-workspace-example.mjs

El proyecto de muestra es user-host/examples/user-workspace/project. Inicie el servidor en ese entorno utilizando un token generado explícito:

WSL / Linux / contenedor

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

El servidor imprime Workspace server: http://127.0.0.1:4777/dds/workspace/v1 junto con un ID y una generación del espacio de trabajo. Establezca DDS_WORKSPACE_TOKEN con el token generado en el terminal del cliente. Es una credencial del operador, independiente de un token de DDS Account. Detenga el servidor de muestra con Ctrl+C.

Desde otro terminal en el mismo proyecto, establezca DDS_WORKSPACE_TOKEN en el mismo secreto y ejecute el cliente de desarrollo:

Bash
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777

El cliente enumera los archivos de muestra y ejecuta Inspeccionar archivo del proyecto para design.sv. El resultado JSON incluye tool: "module-counter" y modules: 1, producidos por un proceso hijo real. Añada --edit al comando del cliente solo cuando quiera que el ejemplo añada una nota al archivo de muestra.

Para utilizar su propio proyecto, pase su directorio absoluto como argumento final a server.mjs. Mantenga el servidor, los módulos de plugins y las herramientas instaladas en ese mismo entorno del usuario. server.mjs importa explícitamente el plugin y asigna su backend con nombre a un ejecutable y argumentos fijos:

Asignación del backend en server.mjs

'module-counter': createProcessBackend({
  executable: process.execPath,
  args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
  cwd: root,
  env: {},
})

Sustituya esta asignación por su herramienta instalada aprobada o su backend personalizado. ctx.workspace.readFile y writeFile utilizan rutas relativas a la raíz seleccionada; ctx.backends.invoke("module-counter", input, {signal}) invoca únicamente un nombre de backend configurado. El adaptador de procesos envía JSON acotado por stdin y espera JSON en stdout. No utiliza ningún comando de shell proporcionado por la solicitud ni hereda variables de entorno del anfitrión.

Para un servidor remoto, utilice su propio punto de conexión HTTPS autenticado o un túnel privado que termine en loopback local. Configure la asignación de puertos del contenedor o TLS en su entorno. El ejemplo se vincula a loopback por defecto; cambiar su dirección de escucha no añade TLS. Los plugins y herramientas confiables se ejecutan con la autoridad del sistema operativo de su proceso anfitrión.

Consulte el ejemplo de espacio de trabajo del usuario y el protocolo del espacio de trabajo para la configuración del servidor, los orígenes, las revisiones de archivos, la cancelación y los resultados acotados.

Funciones del lenguaje

SDK 0.7.0 proporciona completado, información al pasar el puntero, definición, referencias y símbolos planos del documento. Declare cada función en las capacidades del manifiesto v2, junto con los permisos document.read y language.provide. El anfitrión debe conceder explícitamente ambos permisos. Guarde este ejemplo completo de información al pasar el puntero como language-demo.mjs en el proyecto creado arriba:

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();
}
Bash
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs

El primer comando imprime A local LED signal. El segundo ejemplo incluido comprueba las cinco funciones mediante un pequeño lenguaje didáctico con let name = value; el proveedor propio del ejemplo implementa ese lenguaje didáctico.

Función

Entrada de solicitud

Datos de resultado

completion

position

Hasta 500 {label, insertText, detail?, range?} elementos

hover

position

{text, range?} o null

definition

position

Hasta 500 ubicaciones {path, range} relativas al espacio de trabajo

references

position, opcional includeDeclaration

Hasta 500 ubicaciones {path, range} relativas al espacio de trabajo

document-symbols

{}

Hasta 500 {name, kind, range, selectionRange, detail?} símbolos planos

Las posiciones utilizan líneas basadas en cero y desplazamientos UTF-16. La inserción del completado es texto literal; las cadenas de información al pasar el puntero y detalles son texto sin formato. Un anfitrión debe comprobar los archivos y rangos de destino antes de seguir una ubicación. El resultado conserva la identidad de la solicitud, del proyecto o sesión y de la versión del documento. Editar la instantánea, cancelar, agotar el tiempo, retirar el registro o liberar recursos finaliza las solicitudes pendientes y descarta los resultados tardíos.

Estas API funcionan en el anfitrión independiente y confiable del SDK. Utilice un anfitrión SDK 0.3.0 o posterior para estas capacidades de lenguaje y configure explícitamente cualquier proceso LSP mediante el puente específico. Consulte Funciones del lenguaje para los selectores, límites y comportamiento del ciclo de vida.

Sesiones de edición de proyectos

Importe createWorkspaceProject y applyTextEdits desde @altifigence/dds-plugin-sdk/workspace-client. Después de que su anfitrión conecte un createWorkspaceClient y revise la identidad, el aviso y el acceso del espacio de trabajo, invoque createWorkspaceProject(client). El proyecto conserva el vínculo exacto de la conexión. Reconectar requiere un proyecto revisado de nuevo, aunque vuelvan el mismo ID y generación del espacio de trabajo.

API

Comportamiento

project.listFiles(path?, options?)

Enumerar un directorio bajo la raíz del espacio de trabajo seleccionado.

project.openFile(path, options?)

Leer un archivo y conservar su contenido y revisión inmutables en una sesión de edición.

project.createFile(path, content, options?)

Crear solo cuando el archivo no exista y después devolver una sesión.

session.snapshot / session.state

Leer la última {path, content, revision} confirmada y el estado actual de la operación.

session.save(content, options?)

Guardar únicamente si la revisión del servidor sigue coincidiendo con la revisión conservada.

session.saveEdits(edits, options?)

Aplicar ediciones {range, text} sobre una instantánea y después realizar un guardado con comprobación de revisión.

session.reload(options?)

Leer explícitamente el contenido y revisión más recientes después de un conflicto o una escritura incierta.

project.dispose() / session.dispose()

Cancelar el trabajo propio; liberar el proyecto deja conectado el cliente que pertenece al llamante.

Ejecute el ejemplo HTTP completo del paquete instalado. Crea su propio espacio de trabajo temporal de muestra, prueba la edición, una segunda sesión en conflicto, la recarga explícita, Unicode y la reconexión; después cierra su servidor y elimina ese directorio temporal:

Bash
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs

Salida esperada: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. El código fuente del ejemplo muestra la configuración y limpieza completas del servidor y cliente.

Las opciones aceptan signal y timeoutMs. Una escritura fallida después de un intento deja needs-reload; preserve por separado cualquier borrador de interfaz sin guardar y vuelva a cargar explícitamente antes de otro guardado. El SDK no combina ni reintenta automáticamente. Un tiempo de espera agotado, una cancelación o una respuesta perdida pueden ocurrir después de que un servidor haya confirmado la escritura; cancelar una solicitud deja intactos los cambios ya confirmados. Cada sesión permite un guardado o recarga pendiente.

Las ediciones de texto utilizan la instantánea original, líneas basadas en cero y desplazamientos UTF-16. Los solapamientos, pares sustitutos divididos y rangos inválidos se rechazan antes de guardar. Los proyectos permiten como máximo 64 sesiones abiertas o en apertura y 500 ediciones por guardado. Estos asistentes utilizan el protocolo de espacios de trabajo v1 sin cambios, incluidos los servidores SDK 0.2.x, y conservan las restricciones de raíz, rutas protegidas y solo lectura. Consulte Proyectos del espacio de trabajo para los límites de ciclo de vida y tamaño.

Referencia de API

Importe las API de plugins desde @altifigence/dds-plugin-sdk. El paquete incluye declaraciones TypeScript para las mismas exportaciones.

API

Uso

definePlugin(manifest, activate)

Validar el manifiesto y declarar la función de activación.

context.registerDiagnosticsProvider(selector, provider)

Registrar provideDiagnostics(request, {signal}) para IDs de lenguaje seleccionados; devolver un registro cuyos recursos se pueden liberar.

createDiagnosticsResult(request, diagnostics)

Construir un resultado validado utilizando la identidad de la solicitud.

context.registerLanguageProvider(kind, selector, provider) / createLanguageResult(request, data)

Registrar un proveedor de lenguaje y construir un resultado con identidad de solicitud validada.

parseManifest(value)

Validar la versión del manifiesto, la identidad, los permisos, los anfitriones admitidos y el módulo de entrada.

parseDocumentSnapshot(value)

Validar URI, lenguaje, versión del modelo, revisión del espacio de trabajo y texto.

parseDiagnosticsRequest(value) / parseDiagnosticsResult(value)

Validar protocolo, solicitud, ámbito, identidad del documento y campos de diagnóstico.

PluginSdkError / ErrorCode / LIMITS / PROTOCOL_VERSION

Consultar errores tipados, límites de recursos y versión del protocolo.

Importe el anfitrión de desarrollo desde @altifigence/dds-plugin-sdk/testing:

API del anfitrión de pruebas

Uso

createTestHost({scope, grants})

Crear un anfitrión local. Ambas opciones son opcionales; las autorizaciones predeterminadas permiten la lectura de documentos y los diagnósticos.

await host.activate(plugin)

Activar el plugin y devolver una activación cuyos recursos se pueden liberar.

host.setDocument(snapshot)

Establecer el documento actual. Incremente modelVersion o cambie workspaceRevision al cambiar su texto.

await host.requestDiagnostics({signal, timeoutMs})

Solicitar diagnósticos de un proveedor coincidente; ambas opciones son opcionales.

await host.requestLanguage(kind, input, {signal, timeoutMs})

Solicitar una función declarada del lenguaje con autorizaciones explícitas de document.read y language.provide.

host.deactivate(pluginId) / host.dispose()

Retirar registros y cancelar el trabajo pendiente; libere los recursos del anfitrión cuando termine la prueba.

Las solicitudes incluyen requestId, scope de proyecto o sesión y una instantánea con uri, languageId, modelVersion, workspaceRevision y text. Utilice createDiagnosticsResult para preservar esta identidad. Los resultados contienen una matriz diagnostics y omiten el texto fuente.

Los errores exponen un code, incluidos invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable y budget_exceeded. El tiempo de espera predeterminado de la solicitud es de 5 segundos; los tiempos aceptados son de 1 a 30000 ms. Un documento está limitado a 262144 bytes UTF-8 y un resultado a 500 diagnósticos. Consulte LIMITS para conocer los límites completos.

SDK 1.0.0 también proporciona módulos separados. Las importaciones de espacios de trabajo y empaquetado exclusivas de Node deben estar en el entorno del usuario:

Importación

API

@altifigence/dds-plugin-sdk

createPluginHost — comandos v2, puertos explícitos de espacio de trabajo y backend

@altifigence/dds-plugin-sdk/themes

parseTheme, serializeThemeXml

@altifigence/dds-plugin-sdk/workspace-node

createNodeWorkspace, createProcessBackend, createWorkspaceServer, downloadJobBinaryArtifact, downloadStoredJobArtifact

@altifigence/dds-plugin-sdk/workspace-client

createWorkspaceClient, createWorkspaceProject, applyTextEdits, WORKSPACE_OBSERVATION_LIMITS; getFileCapabilities, getFileRevision, readFileIfChanged, watchFiles, watchJob, waitForJob; getBinaryArtifactCapabilities, listJobBinaryArtifacts, getJobBinaryArtifact, readJobBinaryArtifactChunk; getJobStorageCapabilities, listJobHistory, recoverJob, retryCommandJob; getArtifactStorageCapabilities, listStoredJobArtifacts, getStoredJobArtifact, readStoredJobArtifactChunk, readStoredJobArtifactText

@altifigence/dds-plugin-sdk/publishing

validatePluginPackage, packPlugin

@altifigence/dds-plugin-sdk/consent

createNotice, createPermissionGrant, isPermissionGranted, revokeConsentReceipt

@altifigence/dds-plugin-sdk/devtools

initPlugin, doctorPlugin, runPluginDev

@altifigence/dds-plugin-sdk/jobs

JOB_LIMITS, parseJobSnapshot, parseJobEvents, tipos de trabajos

@altifigence/dds-plugin-sdk/artifacts

BINARY_ARTIFACT_LIMITS, parseBinaryArtifactReference, parseBinaryArtifactChunk, decodeBinaryArtifactData

/job-storage / /job-storage-node

createNodeJobStore, tipos de trabajos persistentes

/job-history

parseJobHistoryQuery, parseJobHistoryPage, relaciones de reintentos

/artifact-storage / /artifact-storage-node

createNodeArtifactStore, tipos de resultados almacenados

Empaquetar y publicar su plugin

Comience con el plugin publicable incluido. Guarde este asistente en su proyecto SDK para copiar sus archivos a un directorio my-plugin nuevo.

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');
Bash
node copy-publishable-example.mjs

Edite plugin.json, plugin.mjs, disclosure.json y la licencia para describir su propio plugin. La declaración debe coincidir con el editor del manifiesto, el ID del plugin, la versión, la licencia y la visibilidad del código fuente. Enumere únicamente los archivos que pretenda distribuir en dds-package.json:

dds-package.json

{
  "schemaVersion": 1,
  "files": [
    "plugin.json",
    "plugin.mjs",
    "disclosure.json",
    "LICENSE",
    "NOTICE"
  ]
}

Valide y empaquete el ejemplo:

Bash
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist

Con los metadatos del ejemplo sin cambios, pack crea dist/example-hello-publisher-1.0.0.tgz y dist/example-hello-publisher-1.0.0.tgz.release.json. El JSON de la versión contiene el SHA-256 final del archivo comprimido, los hashes del manifiesto y la declaración y el inventario de archivos. Inspeccione estos archivos antes de distribuirlos.

Solo los archivos de la lista permitida, dds-package.json y los metadatos npm generados entran en el archivo comprimido. La validación inspecciona los datos del paquete y el empaquetado crea el archivo local para el canal de distribución que elija. La CLI rechaza la configuración privada, los archivos de claves y las rutas enlazadas; revise el contenido de los archivos elegidos antes de compartirlos.

Canal

Qué proporcionar

Versión pública de GitHub

Un archivo comprimido con versión, su JSON de versión externo, la licencia y cualquier acceso al código fuente requerido.

Registro o canal de descarga privado

Los mismos archivos con versión, la autorización del público destinatario y las condiciones reales del plugin.

El manifiesto v2 declara runtime, los permisos solicitados y source: {visibility, licenseFile, repository?}. Establezca la visibilidad en open o closed e incluya el archivo real de licencia. El código de su propiedad puede utilizar condiciones de código abierto o propietario; siguen siendo aplicables los avisos del SDK y de las dependencias. Los destinatarios reciben el JavaScript ejecutable junto con los metadatos declarados de visibilidad del código fuente y licencia.

Consulte Publicación y Licencias para los campos de declaración y los requisitos de distribución. Distribuya el archivo generado por el SDK mediante el canal público de versiones o el canal privado de descarga que elija.

La CLI 1.2.1 registra >=1.0.0 <2.0.0 en los paquetes nuevos de plugins. Los archivos históricos 0.3–0.13 y exactamente 1.0.0-rc.1 conservan sus dependencias pares originales. Valide y vuelva a empaquetar una versión nueva del plugin para la instalación estable; el editor actualiza explícitamente el intervalo de dependencias pares y los metadatos de versión al volver a empaquetar.

Verificar un plugin descargado

SDK 1.2.1 proporciona dds-plugin verify para los metadatos de plugins de las versiones exactas publicadas 0.3.x–0.13.x, RC1 y la estable actual. Mantenga juntos el .tgz y el .tgz.release.json. La verificación conserva la dependencia par original. Compruebe el paquete creado arriba:

Verificar el ejemplo empaquetado

npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz

El comando comprueba la estructura acotada de gzip/tar, las listas exactas de archivos permitidos, cada hash de archivo, el manifiesto, la declaración, la licencia y los metadatos npm generados. Rechaza enlaces, rutas inseguras o duplicadas, archivos adicionales y hooks o dependencias npm. Lee y valida el archivo local en su ubicación como una operación sobre datos. Si tiene éxito, imprime un comprobante JSON; si se rechaza, sale con código 1.

Para descargas cuyo nombre se haya cambiado, utilice --metadata con el JSON de versión correspondiente. Obtenga el SHA-256 esperado de forma independiente mediante un canal de versiones confiable y páselo con --sha256 para fijar los bytes seleccionados. La API de Node expone las mismas opciones:

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);

Ejecute verify-release.mjs con la ruta del archivo comprimido, la ruta de los metadatos y el hash en minúsculas de 64 caracteres obtenido independientemente como sus tres argumentos. checksumPinned solo es true cuando ese hash suministrado coincide. Los límites son 12 MiB de entrada comprimida, 10 MiB de contenido de archivos, 4 MiB por archivo, 256 archivos y 256 KiB de metadatos externos.

El verificador compara los bytes del archivo con sus metadatos emparejados. Obtenga el hash esperado de forma independiente mediante un canal de versiones confiable para vincular la comparación con la versión elegida. El anfitrión valida por separado al editor, revisa el contenido y la compatibilidad de la instalación DDS y concede permisos antes de ejecutar. Un comprobante describe los bytes leídos durante esa llamada; vuelva a comprobar los bytes reales si el archivo puede cambiar antes de utilizarlo. Los archivos 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 existentes siguen siendo verificables si cumplen la política reforzada de archivos; instalarlos en 1.0 sigue requiriendo validar al editor y volver a empaquetarlos. Retire los archivos recién excluidos y publique una versión nueva del plugin si es necesario. Este verificador sirve para paquetes de plugins de DDS; los tarballs npm del SDK utilizan el SHA-256 de su versión.

Consulte Verificación de archivos comprimidos y el ejemplo completo de empaquetado, verificación y manipulación.

Permisos, licencias y uso de datos

Los permisos solicitados en un manifiesto son independientes de las autorizaciones del anfitrión que habilitan las operaciones. Proporcione a los usuarios la identidad del plugin, la versión, la licencia real, el ámbito del espacio de trabajo y los permisos solicitados antes de habilitarlo. Explique cualquier operador de backend, los datos enviados, la finalidad, la conservación y el aviso de privacidad antes de conectar ese backend.

Registro

Significado

pluginPermissionGrant

Una decisión de acceso del anfitrión para el paquete, espacio de trabajo y permisos exactos.

noticeAcknowledgement

Un usuario confirmó haber leído un aviso informativo.

pluginLicenseAcceptance

Un usuario eligió si aceptaba las condiciones reales del editor del plugin.

optionalPersonalDataConsent

Una decisión separada cuando un tratamiento opcional utiliza el consentimiento como fundamento.

Una aprobación del espacio de trabajo SDK registra una decisión técnica de acceso. Registre la aceptación de las condiciones del plugin y el consentimiento opcional sobre datos personales como decisiones propias. El SDK tiene licencia Apache-2.0; consulte su licencia y avisos para conocer las condiciones del SDK.

Los desarrolladores de anfitriones pueden preservar un aviso con versión mediante los asistentes asíncronos portátiles. Por ejemplo, guarde esto como notice.mjs y ejecute 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 un subconjunto de permisos solicitados al manifiesto v2, los hashes del artefacto y del manifiesto, la generación del espacio de trabajo, la identidad del anfitrión, el aviso y la caducidad. isPermissionGranted evalúa las identidades actuales y los eventos de revocación suministrados por el anfitrión. revokeConsentReceipt crea un evento separado; el anfitrión debe entonces detener futuras llamadas autorizadas.

Estos asistentes validan registros locales. El anfitrión aporta la decisión real del usuario, la identidad, el almacenamiento y la aplicación de las restricciones. Consulte Permisos y consentimiento para los campos exactos y el ejemplo interactivo de permisos para una demostración explícita de permitir, denegar y revocar. El anfitrión mantiene los acuerdos con editores y sus registros en el flujo de aplicación que elija.

Código fuente, versiones y contribuciones

El repositorio oficial del SDK contiene el código fuente, los esquemas, los ejemplos y las pruebas de contratos. Para ejecutar el ejemplo publicado y las pruebas del SDK desde el código fuente:

Bash
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

Comunique los errores del SDK a través de GitHub Issues, con la versión del SDK y una reproducción mínima. El SDK tiene licencia Apache-2.0; consulte la licencia y los avisos del repositorio. Utilice la página de versiones para los archivos comprimidos con versión y las notas de versión.

Este repositorio es el SDK público para desarrolladores. Su versión contiene los archivos declarados del SDK, esquemas, ejemplos y avisos dentro de su ámbito público. Las comprobaciones de paquetes exigen el inventario exacto de archivos publicados y rechazan patrones conocidos de secretos y rutas privadas. Revise el contenido real de la versión para detectar información sensible junto con estas comprobaciones de patrones.

Actualizaciones de seguridad y límites del anfitrión

Actualice tanto el servidor de su espacio de trabajo como el cliente SDK a 0.3.2 o posterior. Instale la actualización del servidor para activar sus comprobaciones de archivos y límites de solicitudes mejorados. Reinicie el anfitrión actualizado, revise su nueva generación y obtenga aprobación de nuevo antes de utilizar el espacio de trabajo.

El anfitrión Node del espacio de trabajo rechaza enlaces duros que podrían crear alias de archivos protegidos o de archivos fuera de la raíz seleccionada. Copie un archivo de proyecto compartido deliberadamente a un archivo normal con un único enlace. Los almacenes de credenciales como .netrc, _netrc, .git-credentials, .gnupg, .kube y .docker, los nombres adicionales de claves SSH y los alias de dispositivos de Windows también se bloquean. El empaquetado y la verificación de descargas aplican la política correspondiente de nombres de credenciales.

Recurso del servidor

Límite

Cuerpos de solicitudes entrantes simultáneos

16; las subidas adicionales reciben HTTP 429 antes de su despacho

Solicitudes en ejecución

64; la cancelación utiliza una vía de despacho separada

Conexiones / solicitudes por socket

128 / 128

Solicitud y respuesta / contenido de archivo

1600000 / 262144 bytes UTF-8

El cliente cancela respuestas rechazadas no leídas y flujos bloqueados al llegar a un plazo o producirse una cancelación. Un tiempo de espera agotado después de iniciar una escritura puede dejar su resultado incierto: vuelva a leer el archivo antes de reintentar. Revise el contenido para detectar secretos junto con las exclusiones explícitas de rutas y ejecute plugins confiables con acceso al sistema operativo del proceso anfitrión elegido deliberadamente. Utilice la guía de actualización de seguridad y los límites del espacio de trabajo al desplegar un anfitrión.

Herramientas de desarrollo

Tras instalar SDK 1.2.1 como se indicó arriba, cree un proyecto independiente de plugin de comandos. Elija un destino nuevo para los archivos generados; instale las dependencias y ejecute el plugin explícitamente después de generar el esqueleto. El esqueleto incluye un comando, una prueba, un manifiesto, una declaración, una dependencia SDK fijada y LICENSE/NOTICE Apache-2.0.

Bash
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 lee metadatos y comprueba Node, la resolución del SDK, el manifiesto, la licencia, la declaración y los archivos permitidos del paquete sin importar el plugin. Los errores producen un estado de salida 1; los valores de ejemplo de editor y soporte son advertencias. Sustituya esos valores y revise las licencias antes de distribuir.

Bash
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 requiere --trust-local-code. Ejecuta importaciones y activación locales confiables en un proceso hijo y observa únicamente los archivos permitidos, además de dds-package.json. Cada ejecución tiene un plazo y un límite de 256 KiB para stdout/stderr. Ctrl+C detiene la observación y limpia su árbol de procesos. El proceso hijo confiable hereda su entorno y se ejecuta con el acceso de su proceso al sistema operativo. El anfitrión de pruebas predeterminado concede lectura de documentos y publicación de diagnósticos. Configure un anfitrión de espacio de trabajo separado con autorizaciones explícitas de espacio de trabajo y backend para esas integraciones.

Utilice --job para imprimir el progreso y los registros del trabajo; utilice --timeout-ms para establecer hasta 30 segundos para comandos normales o 30 minutos para trabajos. Las API de Node son initPlugin, doctorPlugin y runPluginDev en /devtools. Consulte la guía de herramientas de desarrollo para el comportamiento de observación y los límites de limpieza.

Trabajos de comandos de larga duración

Habilite jobs: true en un anfitrión o servidor SDK 0.4.0 para ejecutar comandos más allá del plazo normal de la solicitud. Los trabajos están deshabilitados por defecto. Pruebe el ejemplo HTTP local completo, que comunica progreso, un registro de backend con nombre y un archivo de resultados con hash fijado:

Bash
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs

Salida esperada: Command job: progress, backend log and pinned result file verified. Un controlador de comandos recibe un job opcional en {signal, job}. Este proporciona reportProgress, log, addArtifact e invokeBackend. Siguen aplicándose las autorizaciones existentes de workspace.read/write y backend.invoke; no se acepta ninguna ruta arbitraria de ejecutable.

Javascript

await client.connect();
if (!(await client.getJobCapabilities()).enabled) throw new Error("Jobs are unavailable");
const jobId = crypto.randomUUID(); // Save before sending.
let job = await client.startCommandJob(pluginId, "analyze", {}, artifactSha256, {jobId, timeoutMs: 300_000});
let after = 0;
for (;;) {
  const page = await client.getJobEvents(jobId, after);
  after = page.nextCursor;
  if (page.dropped) console.log("Expired events:", page.dropped);
  for (const event of page.events) console.log(event.kind, event.data);
  job = await client.getJob(jobId);
  if (job.state !== "running" && !page.hasMore && after >= job.lastSequence) break;
  await new Promise(resolve => setTimeout(resolve, 250));
}
if (job.state === "succeeded") {
  const file = await client.readJobArtifact(jobId, "report");
  console.log(file.content);
}

El fragmento de sondeo presupone un cliente conectado y un comando analyze configurado que registra report. Conserve el ID del trabajo antes de iniciar. Desconectar o abortar una solicitud de sondeo no cancela la ejecución; reconecte a la misma generación y consulte o cancele explícitamente. Los inicios reintentados con el mismo ID y entrada reutilizan el trabajo conservado; los argumentos cambiados generan un conflicto. Reiniciar el anfitrión pierde los registros en memoria. Habilite el almacén persistente separado de 0.8 descrito abajo para recuperar los metadatos confirmados después de reiniciar.

Los estados son running, succeeded, failed, cancelled y timed_out. La salida tardía se descarta después de cancelar; los efectos secundarios no se revierten. Los proveedores que aún no han concluido conservan sus plazas. Hay como máximo 4 trabajos simultáneos, 32 registros conservados, 32 operaciones anidadas por trabajo, 256 eventos/64 KiB por trabajo, 64 eventos por página y 16 artefactos. La duración predeterminada es de 5 minutos y está limitada a 30 minutos. Los registros concluidos en estado final caducan 15 minutos después de su último evento.

Los archivos de resultados de texto son UTF-8 relativos al espacio de trabajo y de hasta 256 KiB. El anfitrión los lee mediante la autorización existente, registra su SHA-256 y rechaza lecturas posteriores si cambiaron los bytes. Para salidas de simulación binarias o mayores, utilice la API de resultados binarios. Pueden quedar artefactos parciales después de cancelar; compruebe el estado final del trabajo para confirmar el éxito. Los clientes 0.3 anteriores siguen utilizando los métodos v1 existentes; los trabajos independientes del SDK requieren 0.4 en ambos extremos. Consulte Trabajos para los contratos y límites exactos.

Observar archivos del espacio de trabajo

project.watchFiles() muestrea entre 1 y 16 rutas relativas explícitas de archivos. SDK 1.0.0 utiliza solicitudes de solo revisión en los anfitriones compatibles y las lecturas acotadas existentes en los anteriores. El ejemplo presupone un cliente conectado y aprobado por el anfitrión. Cambie design.sv con un editor externo para finalizar el bucle; la instantánea de edición conservada permanece sin cambios.

Javascript

import {createWorkspaceProject} from '@altifigence/dds-plugin-sdk/workspace-client';
const project = createWorkspaceProject(client);
const edit = await project.openFile('design.sv');
const original = edit.snapshot;
try {
  for await (const change of project.watchFiles(['design.sv'], {intervalMs: 1000})) {
    console.log(change.kind, change.path, change.previousRevision, change.revision);
    if (change.kind !== 'initial') break;
  }
  console.log(edit.snapshot === original);
} finally { project.dispose(); }

Los eventos son objetos inmutables {kind, path, previousRevision, revision}. El primer muestreo emite initial; los cambios posteriores emiten created, changed o deleted. Los archivos ausentes tienen revision null. includeInitial: false registra la referencia inicial sin emitir eventos, y las revisiones iguales no producen eventos. Solo not_found significa eliminación; los errores de permisos, rutas protegidas, tamaño y transporte terminan la observación.

Conserve por separado el texto de la interfaz sin guardar y elija acciones explícitas para recargar, combinar y guardar borradores. Guardar una edición comprueba la revisión conservada y puede comunicar un conflicto. La observación muestrea las rutas explícitas de archivos de una en una y en orden; los cambios intermedios pueden agruparse. Utilice las API de observación de proyectos descritas abajo para descubrir directorios y suscribirse a ellos con un ámbito definido. Las restricciones existentes de raíz, tamaño de archivo y rutas protegidas se aplican tanto en servidores de solo lectura como de escritura.

Los observadores de archivos y trabajos comienzan en su primer next(), no obtienen páginas en segundo plano mientras el consumidor está en pausa y comparten un máximo de ocho observadores activos por cliente. Puede haber un next() pendiente; una lectura concurrente falla con conflict. Break o return() detiene las lecturas pendientes; liberar el proyecto detiene sus observadores de archivos, y desconectar, reconectar o liberar recursos invalida todos los observadores antiguos. AbortSignal termina la observación con cancelled; las respuestas tardías no pueden generar resultados.

intervalMs es de 250 a 60000 ms (predeterminado 1000) y se aplica entre pasadas de archivos o lecturas de trabajos inactivos. requestTimeoutMs es de 1 a 30000 ms por solicitud y utiliza por defecto el plazo del cliente. El timeoutMs total es de 1 a 1800000 ms desde el primer next(), incluidas las pausas del consumidor. Los archivos no tienen tiempo de espera total por defecto; los trabajos tienen 30 minutos. Al agotarse el plazo se informa de budget_exceeded y se libera la plaza. Estos límites se exportan como WORKSPACE_OBSERVATION_LIMITS.

Bash
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs

Salida esperada: Workspace observation: file changes, retained draft and resumed job verified. El ejemplo completo crea su propio espacio de trabajo temporal y comprueba cambios de archivos, conflictos de borradores y reanudación explícita de trabajos. Consulte Observación para todas las opciones y reglas de duración.

Observar y reanudar trabajos

client.watchJob() sigue un trabajo existente mediante jobs.events/get; waitForJob() devuelve su instantánea final. El fragmento presupone un cliente conectado, un jobId iniciado explícitamente y un savedCursor (o undefined). Compruebe getJobCapabilities() antes de iniciar un trabajo. La observación nunca inicia, reintenta ni cancela el comando.

Javascript

let after = savedCursor ?? 0;
for await (const update of client.watchJob(jobId, {after, intervalMs: 1000})) {
  if (update.dropped) console.log('Expired events:', update.dropped);
  for (const event of update.events) console.log(event.kind, event.data);
  console.log(update.snapshot.state, update.snapshot.progress);
  after = update.nextCursor;
}
const result = await client.waitForJob(jobId, {after, timeoutMs: 120000});
if (result.state === 'succeeded') console.log(result.result);
else console.log(result.state, result.error.code);

Cada actualización congelada contiene snapshot, events, after, nextCursor, dropped y hasMore. Gestione como máximo 64 eventos por página y registre nextCursor después de procesarla, junto con el ID del trabajo y la identidad del espacio de trabajo. dropped informa de historial caducado. Una instantánea puede ser más reciente que su página de eventos; siga leyendo instantáneas finales mientras hasMore sea true. El iterador termina después de la última página. waitForJob() consume las mismas páginas y devuelve succeeded, failed, cancelled o timed_out; inspeccione el estado en lugar de considerar un éxito toda promesa resuelta.

Detener un iterador o agotar su tiempo solo detiene la observación. El comando del servidor continúa hasta que termine o se invoque cancelJob() explícitamente. Tras una reconexión aprobada por el anfitrión, verifique el mismo ID y generación del espacio de trabajo y después cree un observador nuevo con el ID del trabajo y cursor guardados. Los observadores antiguos no son válidos aunque la identidad no cambie. Los trabajos ausentes o caducados y los fallos de transporte se comunican sin volver a enviar; los trabajos en memoria no sobreviven al reinicio del anfitrión. La recuperación persistente utiliza recoverJob() con una conexión nueva; los observadores en vivo no se reanudan entre generaciones.

Los contratos existentes de hello v1 y trabajos permanecen sin cambios. La observación de archivos utiliza la alternativa en anfitriones 0.3.2/0.4/0.5; la observación de trabajos requiere un anfitrión 0.4 o posterior habilitado. Una capacidad de trabajos deshabilitada o no admitida devuelve un error y conserva la decisión del llamante sobre la ejecución de comandos en el anfitrión independiente del SDK. Consulte Observación y Compatibilidad.

Revisiones de archivos y lecturas condicionales

SDK 0.6.0 añade getFileCapabilities(), getFileRevision(path) y readFileIfChanged(path, knownRevision) a los clientes conectados. Las lecturas de revisión devuelven {path, revision} sin contenido. Una lectura condicional coincidente devuelve {path, revision, notModified: true}; si cambia el contenido, devuelve notModified: false y content. Pase knownRevision: null para obtener el contenido actual. Los archivos ausentes se rechazan con not_found.

Javascript

let cached = await client.readFile('design.sv');
const current = await client.readFileIfChanged(cached.path, cached.revision);
if (!current.notModified) cached = current;
console.log(cached.content);
const metadata = await client.getFileRevision('design.sv');
console.log(metadata.revision);

Utilice un cliente ya conectado y autorizado. Mantenga los borradores sin guardar separados de esta caché. Las lecturas condicionales calculan el hash y devuelven una instantánea de un archivo; una lectura posterior todavía puede observar otro cambio. Guarde con la revisión correspondiente al contenido devuelto. Estas llamadas no actualizan instantáneas de sesiones de edición ni combinan borradores. Una respuesta sin cambios no tiene campo content; un archivo vacío que ha cambiado tiene content: “”.

La observación de archivos utiliza automáticamente lecturas de solo revisión cuando se admiten. Los métodos opcionales fs.capabilities, fs.revision y fs.readIfChanged preservan el hello v1 estricto y los métodos originales de archivos. Los anfitriones conocidos de espacios de trabajo SDK anteriores a 0.6 utilizan fs.read sin sondear. Otros anfitriones deben responder al descubrimiento o devolver un error unsupported correlacionado correctamente. Cada capacidad false selecciona su propia alternativa de lectura completa acotada; la respuesta del servidor antiguo sigue transfiriendo el contenido completo.

Las capacidades se almacenan en caché solo para la conexión actual y se restablecen al reconectar o revocar. Las respuestas inválidas, las discrepancias de ruta o revisión, los permisos, la autenticación, los fallos de transporte y los tiempos de espera agotados no activan una alternativa. Las operaciones anunciadas que después fallen no se degradan silenciosamente. AbortSignal cubre el descubrimiento y la lectura; timeoutMs se aplica a cada solicitud HTTP. Un cambio de conexión invalida la operación antigua.

El servidor sigue realizando una lectura completa protegida del archivo y un cálculo SHA-256 para cada muestreo. Siguen vigentes la validación UTF-8, el límite de 262144 bytes y las comprobaciones de rutas protegidas y enlaces. Esto reduce los bytes de respuesta de red y conserva las lecturas protegidas del disco y el cálculo del hash para cada muestreo. Una medición local con Node 22.23.1 en Windows de 20 muestreos sin cambios de 200000 bytes devolvió 4003974 bytes con lecturas completas, 3867 con revisiones (99,903 % menos) y 4247 con lecturas condicionales (99,894 % menos). Se incluye el descubrimiento; se excluyen las cabeceras HTTP, TLS y la referencia inicial de hello y contenido. Ejecute npm run benchmark:files en una copia del repositorio para reproducir el caso de prueba.

El SDK tiene ahora una API estable 1.x con comprobaciones funcionales documentadas en su versión publicada. Los clientes existentes 0.3.2, 0.4, 0.5 y 0.6 conservan sus API originales en anfitriones 0.7. Estas reglas de compatibilidad describen clientes y anfitriones independientes del SDK. Consulte Revisiones de archivos para el contrato completo y las reglas de migración.

Resultados de trabajos grandes y binarios

SDK 0.7.0 añade una extensión opcional de archivos de resultados binarios. Un comando confiable registra un archivo existente del espacio de trabajo; el anfitrión registra su SHA-256 y longitud. Los clientes leen como máximo 64 KiB por fragmento, y el descargador de Node reanuda un archivo parcial y verifica la salida completa. El tamaño máximo del archivo registrado es 1 GiB; las API existentes de archivos UTF-8 y artefactos de texto de 256 KiB conservan sus límites.

Habilite jobs: true y binaryArtifacts: true en el anfitrión de plugins propiedad del servidor. Ambos son false por defecto. Conserve el token explícito, el aviso del operador, la referencia fijada y revisada del artefacto del plugin y la autorización efectiva workspace.read. Lo siguiente se basa en la configuración del espacio de trabajo anterior; los espacios de solo lectura pueden registrar archivos ya generados por la herramienta configurada del operador.

Javascript

const server = await createWorkspaceServer({
  root, workspaceId, token, notice,
  plugins: [{plugin, artifactSha256}],
  grants: ['workspace.read'],
  jobs: true, binaryArtifacts: true, writable: false,
});

Registre el resultado dentro de un comando iniciado con startCommandJob. El registro transmite el archivo existente a través de SHA-256 utilizando un búfer de 64 KiB. La referencia apunta a ese archivo fuente, no a una copia inmutable. Se rechazan las rutas protegidas, los recorridos fuera de la ruta, los enlaces y los archivos no regulares; los cambios posteriores del archivo fuente fallan con conflict.

Javascript

context.registerCommand({id: 'collect', title: 'Collect trace'}, async (_, {job}) => {
  if (!job) throw new Error('Start this command as a job');
  const artifact = await job.addBinaryArtifact({
    id: 'trace', path: 'outputs/trace.fst', label: 'Simulation trace',
  });
  return {artifactId: artifact.id};
});

Utilice un cliente ya conectado y autorizado y un ID de trabajo existente. El destino es una ruta absoluta en un directorio real existente controlado por el llamante. El asistente escribe destination + “.dds-part” y se niega a sobrescribir un archivo final existente.

Javascript

import {downloadJobBinaryArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';

const capabilities = await client.getBinaryArtifactCapabilities();
if (!capabilities.enabled) throw new Error('Binary results are not enabled');
const reference = await client.getJobBinaryArtifact(jobId, 'trace');
const receipt = await downloadJobBinaryArtifact(client, reference, {
  destination: absoluteDownloadPath, resume: true,
  signal: abortController.signal,
  onProgress({receivedBytes, totalBytes}) {
    console.log(receivedBytes, totalBytes);
  },
});
console.log(receipt.verified, receipt.revision);

Conserve la referencia completa {jobId, scope, artifact}. Tras una interrupción, reconecte explícitamente a la misma generación del anfitrión y vuelva a invocar el asistente con esa referencia y resume: true. Vuelve a calcular el hash del prefijo guardado y solicita únicamente el sufijo faltante. Comprueba el SHA-256 de cada fragmento, del flujo completo recibido y del archivo temporal real antes de publicar. El comprobante final verified: true confirma la finalización; las funciones de progreso síncronas siguen sin verificar. Los archivos parciales corruptos requieren eliminación explícita o un destino nuevo.

listJobBinaryArtifacts(jobId) devuelve los metadatos binarios registrados por separado de los resultados de texto existentes. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) devuelve base64 canónico con un SHA-256 del fragmento, un rango exacto y un marcador EOF. decodeBinaryArtifactData de /artifacts devuelve bytes Uint8Array. Los consumidores del navegador deben verificar por sí mismos el hash del archivo completo; las comprobaciones individuales de fragmentos no demuestran que la salida ensamblada coincida con la referencia.

Los resultados binarios y de texto comparten 16 plazas y un espacio de nombres de IDs por trabajo. Las operaciones de captura y lectura binaria están limitadas a cuatro por anfitrión o espacio de trabajo, y las descargas de Node a cuatro por proceso. El timeoutMs de descarga de Node es un plazo total, con un máximo predeterminado de 30 minutos; requestTimeoutMs es de 5 segundos por defecto, con un máximo de 30 segundos. La publicación necesita compatibilidad con enlaces duros, como NTFS o ext4. Utilice un destino controlado por el llamante y un proceso anfitrión confiable; impida mediante controles de acceso del sistema operativo que procesos hostiles escriban simultáneamente en el directorio de destino.

Los métodos opcionales artifacts.capabilities, artifacts.list y artifacts.read preservan el hello v1 existente, las instantáneas de trabajos y los eventos. Los anfitriones anteriores a 0.7 informan de que la extensión está deshabilitada; la operación binaria solicitada termina con ese resultado de capacidad. La autenticación, las respuestas mal formadas y los errores de transporte siguen siendo errores. Reconectar, revocar, la caducidad del trabajo o un cambio de generación del anfitrión invalidan las operaciones antiguas. Los trabajos se conservan en memoria durante 15 minutos después del último evento del trabajo finalizado. Los trabajos cancelados pueden dejar registrada salida parcial de la herramienta; confirme el éxito a partir del estado final del trabajo. Esto describe las API predeterminadas en vivo y de archivos fuente. La API separada de resultados almacenados descrita abajo conserva bytes entre reinicios.

Ejecute npm run example:artifacts para una transferencia real de 2 MiB con interrupción, reconexión y reanudación solo del sufijo; npm run benchmark:artifacts utiliza 8 MiB. Una ejecución local de Windows transfirió 8388625 bytes en 129 solicitudes de fragmentos, reanudando un prefijo de 65536 bytes y verificando el SHA-256 final. Base64 añade sobrecarga; los cuerpos JSON de las respuestas sumaron 11257419 bytes. Las transferencias utilizan memoria acotada y fragmentos codificados. Consulte Artefactos binarios para el contrato completo. El ejemplo prueba las API independientes de transferencia del SDK.

Trabajos persistentes, historial y reintentos explícitos

SDK 0.8.0 añade almacenes persistentes opcionales en un directorio propiedad del operador fuera del espacio de trabajo. Proporcione rutas absolutas, un ID estable de espacio de trabajo, código de plugin revisado, SHA-256 del paquete, token y aviso. El ejemplo también habilita la conservación de bytes de archivos; omita artifacts de jobStorage para almacenar solo metadatos de trabajos. Las respuestas v1 existentes y los valores predeterminados de solo memoria siguen siendo compatibles.

Javascript

import {createNodeJobStore} from '@altifigence/dds-plugin-sdk/job-storage-node';
import {createNodeArtifactStore} from '@altifigence/dds-plugin-sdk/artifact-storage-node';
import {createWorkspaceServer} from '@altifigence/dds-plugin-sdk/workspace-node';
const store = await createNodeJobStore({directory, workspaceRoot: root, workspaceId});
const artifacts = await createNodeArtifactStore({jobStore: store});
const server = await createWorkspaceServer({
  root, workspaceId, token, notice, plugins: [{plugin, artifactSha256}],
  grants: ['workspace.read'], jobs: true, binaryArtifacts: true,
  jobStorage: {store, artifacts},
});

Un proveedor comienza únicamente después de guardar su intención inicial. Los puntos de control posteriores se agrupan; flushJobStore() espera a los puntos de control solicitados, no a la finalización del comando. La recuperación separa la conexión actual del ámbito de ejecución original e informa de live, completed, interrupted, expired, missing, corrupt o unsupported. Un trabajo interrumpido nunca se reinicia automáticamente; su unrecordedTail es desconocido.

Javascript

const capabilities = await client.getJobStorageCapabilities();
const query = {limit: 16, commandId: 'analyze'};
const page = await client.listJobHistory(pluginId, artifactSha256, query);
const prior = await client.recoverJob(pluginId, previousJobId, artifactSha256);
const attempt = await client.retryCommandJob(pluginId, previousJobId,
  reviewedFreshInput, artifactSha256, {jobId: crypto.randomUUID()});

El historial filtra por estado, clasificación de recuperación, comando, hora de inicio e intento padre. Las páginas contienen hasta 32 entradas, ordenadas por hora de inicio descendente y después por ID de trabajo. Un cursor congela los miembros durante 60 segundos y debe reutilizar la misma consulta; se excluyen trabajos nuevos, se omiten registros eliminados o no autorizados y se informa de la caducidad. Reiniciar pierde los cursores. artifactCount, snapshotCount y resultAvailability describen referencias registradas, no pruebas actuales de archivos.

Un reintento explícito necesita un ID de trabajo nuevo, una entrada nueva validada, el mismo paquete aprobado actualmente y un comando disponible. attemptOf vincula la ejecución nueva con su padre sin cambios. Repetir el mismo ID, entrada, padre y tiempo de espera recupera el intento conservado sin volver a ejecutarlo, incluso después de reiniciar. Los registros ausentes o caducados no pueden proporcionar esa garantía. Una ejecución aceptada puede continuar después de cancelar la solicitud que esperaba; consulte el ID del trabajo nuevo antes de decidir reintentar.

La conservación predeterminada omite las entradas sin procesar, los cuerpos de resultados, el texto de progreso y las etiquetas de artefactos; los registros se redactan para ocultar datos sensibles. Solo un filtro explícito y determinista del anfitrión conserva texto revisado. Nunca se restauran tokens, secretos ni consentimientos antiguos. Se vuelven a comprobar la identidad actual del espacio de trabajo y plugin, el permiso de lectura y todas las autorizaciones registradas. Los metadatos de trabajos tienen valores predeterminados de 256 registros, 64 MiB y 24 horas, con un máximo de siete días. La eliminación y la depuración son operaciones explícitas del anfitrión.

El almacén local tiene un único proceso escritor, valida la identidad del espacio de trabajo y raíz y comprueba la integridad de los metadatos. La recuperación explícita de bloqueos obsoletos solo reclama un PID del mismo equipo cuya terminación puede demostrarse. Los archivos desconocidos o corruptos requieren inspección. En Windows, la sincronización y el renombrado de archivos permiten la recuperación tras reiniciar procesos; la persistencia depende del sistema de archivos y del dispositivo de almacenamiento. Consulte Almacenamiento de trabajos, Historial y el ejemplo de trabajos persistentes.

Resultados almacenados y descargas tras reiniciar

Con el almacén de artefactos habilitado, await job.addArtifact() o job.addBinaryArtifact() copia y verifica el archivo completo antes de registrarlo. El texto sigue limitado a 256 KiB; los archivos binarios tienen como máximo 1 GiB. Se comprueba el SHA-256 del flujo fuente y del archivo temporal real. La cancelación, los errores de disco lleno, las modificaciones y las escrituras parciales no publican resultados utilizables. Los archivos publicados antes de un fallo pero no registrados por el trabajo pueden permanecer para que los inspeccione el operador.

Javascript

import {downloadStoredJobArtifact} from '@altifigence/dds-plugin-sdk/workspace-node';
const list = await client.listStoredJobArtifacts(pluginId, jobId, artifactSha256);
const reference = await client.getStoredJobArtifact(pluginId, jobId, artifactId, artifactSha256);
const receipt = await downloadStoredJobArtifact(client, reference, {
  destination: absoluteOutputPath, resume: true,
});
console.log(receipt.storage, receipt.snapshotId, receipt.verified);

La lista separa referencias fuente de metadatos de instantáneas e informa de instantáneas retained, expired, missing, corrupt o unsupported. retained es un estado de metadatos; getStoredJobArtifact() verifica los metadatos y todo el archivo almacenado antes de devolver una referencia nueva de la generación actual. Cada lectura vuelve a comprobar la autoridad actual y la identidad del archivo. Los archivos fuente eliminados no afectan a los bytes almacenados, y las instantáneas ausentes nunca recurren a un archivo fuente modificable. Para instantáneas de texto, invoque client.readStoredJobArtifactText(textReference).

Después de reiniciar, reconecte con las autorizaciones actuales y obtenga una referencia nueva. El ID de la instantánea, el ID del almacén y el resumen criptográfico permanecen estables; se rechaza la generación antigua. resume: true vuelve a comprobar un prefijo .dds-part guardado frente a esa instantánea, verifica los fragmentos y el archivo temporal completo y publica sin sobrescribir el destino. Las lecturas necesitan tanto los metadatos del trabajo conservados como los bytes del archivo. Los consumidores de fragmentos del navegador deben verificar el resumen completo; el adaptador Worker descrito abajo proporciona reanudación explícita en disco desde el navegador.

El almacenamiento de artefactos tiene valores predeterminados de 256 archivos, 256 MiB y 24 horas, con un máximo de almacenamiento total de 4 GiB y conservación de siete días. Los fragmentos son de hasta 64 KiB, con cuatro lecturas simultáneas. inspect() informa del consumo, las horas de caducidad, las entradas inválidas y los archivos huérfanos. remove(snapshot) y prune() son operaciones explícitas del operador. Los trabajos activos y las lecturas individuales se mantienen protegidos; la caducidad o eliminación entre fragmentos puede detener la siguiente lectura. La depuración opcional de huérfanos elimina únicamente archivos reconocidos de un solo enlace. Las entradas corruptas o ambiguas necesitan inspección.

La conservación de archivos almacena bytes reales del proyecto con independencia de la ocultación de datos sensibles en registros. Elíjala deliberadamente. El plugin y comando actuales, el hash del paquete, el espacio de trabajo y las autorizaciones registradas siguen siendo necesarios después de reiniciar. Termine el mantenimiento y después espere a server.close(), artifacts.close() y store.close(), en ese orden. Esta versión proporciona operaciones de conservación de archivos para anfitriones independientes del SDK.

Ejecute npm run example:stored-artifacts para un reinicio real de proceso hijo, eliminación del archivo fuente, reanudación verificada de una descarga parcial, historial y reintento explícito. npm run example:durable-jobs también abarca la terminación forzada del proceso. Consulte Resultados almacenados. Los anfitriones conocidos 0.7 y anteriores informan de que el almacenamiento está deshabilitado sin sondeos desconocidos. Las API existentes en vivo y de archivos fuente conservan su comportamiento original.

Observar un proyecto

El operador habilita explícitamente los proyectos y selecciona las raíces permitidas en el servidor independiente del SDK. Esta configuración de activación explícita utiliza sistemas de archivos locales Windows y Linux. Los anfitriones conocidos SDK 0.3–0.8 informan directamente de que la capacidad no está disponible y conservan su comportamiento existente de descubrimiento. Utilice el ejemplo con el perfil admitido de sistemas de archivos locales.

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();

El primer evento es una instantánea completa. Los cambios posteriores contienen diferencias respecto a una revisión anterior; las indicaciones perdidas, los cambios durante el escaneo inicial, los escaneos incompletos y el desbordamiento por un consumidor lento producen una vista completa de resincronización con un motivo. Los renombrados pueden aparecer como eliminación y creación. Cada archivo se verifica en su propio momento de lectura; la instantánea representa esos estados muestreados, con los cambios intermedios agrupados como se ha descrito.

El servidor y el cliente permiten cuatro suscripciones cada uno, con cuatro eventos en cola por suscripción nativa. La concesión predeterminada de inactividad es de 30 segundos; una lectura posterior puede devolver not_found. Tras una pausa larga, cree un iterador nuevo para una instantánea inicial. break/return, la cancelación y la liberación de recursos liberan las suscripciones; si una conexión rota impide limpiar, los recursos remotos restantes caducan con su concesión.

Los límites predeterminados de escaneo son profundidad 8, 512 entradas, 1 MiB por archivo, 16 MiB en total y 10 segundos. Los máximos configurables son profundidad 32, 1000 entradas, 16 MiB por archivo, 64 MiB en total y 30 segundos. Los archivos limitados pueden contener metadatos sin hash de contenido; compruebe complete y reasons. Los plazos se comprueban entre llamadas al sistema de archivos; elija deliberadamente el acceso del proceso anfitrión al sistema operativo para esas llamadas.

Árbol del proyecto y búsqueda

listTree devuelve un árbol, searchFiles busca nombres relativos de archivos mediante subcadenas literales o patrones glob acotados, y searchText encuentra texto literal en archivos UTF-8. root es obligatorio; include/exclude son relativos a él. Las consultas utilizan los modos documentados de texto literal o patrones glob. Las coincidencias sin distinción de mayúsculas y minúsculas solo normalizan ASCII A–Z, de modo que las posiciones UTF-16 originales permanezcan estables.

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);

Las coincidencias de texto incluyen un SHA-256 del contenido, un rango UTF-16 basado en cero y un fragmento acotado. Un cursor congela los miembros originales durante como máximo 60 segundos y exige la misma consulta. Las páginas posteriores vuelven a comprobar el contenido actual y marcan elementos como current, changed, missing o unverified; los archivos nuevos aparecen únicamente en una consulta nueva. La coincidencia y revisión capturadas permanecen sin cambios.

Los archivos de texto están limitados a 256 KiB, las consultas a 256 unidades UTF-16 y los fragmentos a 512 unidades. Los valores predeterminados son 256 resultados (máximo 512), 32 elementos por página (máximo 64) y una respuesta de 64 KiB (máximo 128 KiB). Los archivos binarios, UTF-8 inválido y los límites de bytes, profundidad, tiempo o respuesta se comunican como resultados incompletos con motivos. Hay dos consultas simultáneas y ocho vistas de cursor conservadas; libere explícitamente los cursores sin utilizar.

Borradores del proyecto y reconexión

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();

Cuando el snapshotRevision de una consulta difiera del snapshot.revision observado, libere el cursor antiguo y repita la misma consulta de raíz y filtros. La observación nunca modifica edit.snapshot ni el contenido del borrador propiedad del llamante. Tras un cambio externo, traslado o eliminación, la condición CAS original informa de un conflicto; el llamante elige recargar, combinar o guardar por separado explícitamente.

El cliente comprueba la generación de la conexión, la raíz y filtros, el hash de la consulta, las posiciones de página, el SHA-256 de la instantánea y la continuidad de eventos. Las respuestas tardías se descartan tras revocar, desconectar o reconectar. Los cursores de observación y los de consultas son separados y no se restauran automáticamente. server.revokeProjects() termina el acceso a proyectos; habilitarlo de nuevo requiere una generación nueva del servidor.

npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browser

Los ejemplos instalados de Node verifican creación, búsqueda, cambios externos, borradores conservados, conflictos CAS y reconexión. Para el ejemplo del navegador, abra la URL loopback impresa y elija Ejecutar escenario. Utiliza únicamente su espacio de trabajo temporal, que se elimina cuando se detiene el servidor del ejemplo. Las solicitudes HTTP tienen un tiempo predeterminado de cinco segundos; configure deliberadamente los tiempos del cliente y servidor para escaneos mayores.

Observación de proyectos · Contratos de árbol y búsqueda · Herramientas HTTP de proyectos

Transmitir y verificar artefactos en el 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);

El asistente compatible con navegador recibe como máximo un fragmento de 64 KiB cada vez, espera al destino seleccionado y calcula incrementalmente el hash de todo el archivo. Valida los rangos exactos, la identidad, el base64 y el hash de cada fragmento antes de escribir. Un destino con lectura posterior vuelve a leer independientemente los bytes guardados; verification es stored solo cuando coinciden ambos hashes completos. Sin lectura posterior, verification es received y storedSha256 es null. Que el progreso llegue a todos los bytes no significa finalización.

La aplicación abre los selectores necesarios, selecciona referencias de archivos o directorios OPFS, concede permisos y proporciona el destino exacto a los adaptadores SDK. Los destinos asíncronos de escritura de archivos y OPFS mantienen el almacenamiento temporal hasta close y lo descartan si falla antes de confirmar. Para archivos parciales que sobrevivan a una recarga, utilice el adaptador específico de Worker descrito abajo. Los límites de archivos son 1 GiB, cuatro flujos directos simultáneos y un plazo total de 30 minutos.

Subir archivos seleccionados

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.

Las subidas están deshabilitadas por defecto. El operador configura un espacio de trabajo local Node, un directorio aislado de almacenamiento temporal, raíces permitidas y un único principal; después concede workspace.write al plugin seleccionado en la referencia exacta fijada de su archivo comprimido. El asistente calcula previamente el hash del archivo fuente seleccionado antes de comenzar. El servidor acepta fragmentos secuenciales de 64 KiB, verifica duplicados y el contenido completo y confirma únicamente después de las comprobaciones condicionales del destino. Ningún byte temporal aparece en las listas normales del espacio de trabajo.

expectedRevision: null exige que el destino no exista; un SHA-256 exige un destino actual coincidente. La cancelación conserva el prefijo del servidor confirmado. Una operación recover explícita nueva consulta la autoridad actual, valida el mismo archivo fuente y especificación y reanuda solo el prefijo coincidente. Una respuesta de confirmación perdida es incierta hasta consultarla; no autoriza repetir la confirmación ni revertir un archivo. Los límites máximos son 1 GiB por archivo, 4 GiB por almacén y cuatro sesiones activas; los valores predeterminados son menores. Los anfitriones conocidos 0.3–0.9 informan de que las subidas están deshabilitadas sin sondear métodos nuevos.

Programar transferencias de archivos

import {createTransferQueue} from '@altifigence/dds-plugin-sdk/transfer-queue';
const queue = createTransferQueue({
  concurrency: 2, perConnection: 1, bufferBytes: 131072,
  bytesPerSecond: 1048576, attempts: 3,
});
const unsubscribe = queue.subscribe(view => renderTransfer(view));
const download = queue.enqueueStoredDownload(client, reference, {sink});
download.pause(); // finishes the current stage, then waits at the next boundary
download.resume();
const receipt = await download.result;
queue.release(download.id);
unsubscribe(); await queue.dispose();

Una cola propiedad del llamante mezcla trabajos de subida, descarga en vivo y descarga almacenada. Limita los trabajos conservados (32), las etapas simultáneas (4), la concurrencia de conexiones del cliente, las reservas de fragmentos decodificados (64–256 KiB), la velocidad y los reintentos. El trabajo apto progresa aunque una conexión esté saturada, y las ventajas iniciales acotadas de prioridad impiden que los trabajos pequeños aptos esperen indefinidamente. Un trabajo pausado termina su etapa actual y después espera; la pausa puede conservar un bloqueo de almacenamiento. Los plazos totales incluyen la espera en cola y las pausas.

El reintento automático se limita a 429/503 reconocidos por el SDK, pérdida de red o tiempo de espera agotado durante una operación idempotente de fragmento exacto, con espera creciente acotada y variación aleatoria. Begin/commit y los fallos de autorización, suma de comprobación, rango, archivo fuente o destino devuelven el control al llamante para decidir explícitamente la recuperación. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes y remainingBytes son independientes; solo un comprobante verificado produce completed. Un archivo ya confirmado permanece confirmado después de cancel/dispose.

Reanudar descargas en el 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.

La recuperación persistente requiere un Worker dedicado, acceso síncrono OPFS y Web Locks. El llamante vuelve a seleccionar su directorio y UUID parcial después de recargar y obtiene una referencia almacenada aprobada nueva. El destino almacena dos nombres exactos de archivos de datos y metadatos, la identidad completa de la instantánea inmutable, la caducidad y los hashes de prefijo actual y anterior. No almacena tokens, autorizaciones ni el ámbito antiguo de la conexión. Cada fragmento de datos se vacía al almacenamiento antes de cerrar el pequeño flujo de metadatos.

Tanto el destino como el asistente recalculan independientemente el hash del prefijo. Una cola sin punto de control solo se recorta después de que coincida el prefijo registrado. Los metadatos que exceden el tamaño real del archivo pueden recurrir al punto de control anterior únicamente si coinciden esos bytes y su hash; la corrupción, las entradas ausentes, la caducidad o una instantánea diferente fallan sin reiniciar silenciosamente. Un bloqueo exclusivo para todo el origen rechaza otra pestaña, se mantiene durante la lectura posterior y se libera al cerrar o terminar el Worker. Reabrir requiere entonces recuperación explícita.

Los metadatos locales están limitados a 16 KiB y cuatro sesiones abiertas de destino. La conservación predeterminada es de una hora, con un máximo de 24 horas limitado por la caducidad de la instantánea del anfitrión. Planifique el almacenamiento según la cuota y la expulsión de datos del navegador y proteja los scripts y datos del origen mediante la política de seguridad de la aplicación. Evalúe el comportamiento ante cortes eléctricos en el entorno de almacenamiento elegido. Chromium 154 en Windows se probó con cancelación, recarga, reinicio del anfitrión, conflicto entre dos pestañas y terminación de la pestaña propietaria, con hashes completos de archivos guardados. Utilice ese perfil medido de navegador y sistema operativo como referencia para evaluar otras combinaciones.

npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resume

Streaming · Subidas · Cola de transferencias · Recuperación de Worker

Ayuda de firmas y asistencia de completado

Declare signature-help, completion-resolve y completion-snippets según sea necesario en el manifiesto v2; los modificadores de completado también requieren completion. El anfitrión debe conceder document.read y language.provide. Los completados literales existentes siguen siendo válidos. languageCapabilities() informa de la implementación del SDK y sus límites sin conceder permisos.

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);

La aplicación proporciona la posición y el anfitrión actuales; la preparación devuelve datos sin escribir un documento ni archivo. La ayuda de firmas admite hasta 16 firmas, 64 parámetros cada una y desplazamientos UTF-16 de las etiquetas de parámetros. La resolución del completado mantiene privados los datos del proveedor, devuelve un token de anfitrión de un solo uso y fija la etiqueta, inserción y rango seleccionados. Los tokens vinculan proveedor, ámbito y documento, caducan a los 60 segundos y están limitados a 128 entradas, 4 MiB y cuatro operaciones reales de resolución. Los cambios de documento o proveedor los descartan.

Los fragmentos admiten $n, ${n}, ${n:literal}, $0 y escapes documentados, con repeticiones sincronizadas y puntos de tabulación ordenados. Se rechazan variables, anidamientos, opciones, transformaciones y comandos ejecutables. Se comprueban los límites UTF-16/CRLF y las ediciones adicionales solapadas. Los proveedores se ejecutan como código confiable dentro del proceso con el acceso del proceso anfitrión al sistema operativo. Una cancelación ignorada mantiene ocupada la plaza pendiente real hasta que el proveedor termine.

Ediciones revisadas del espacio de trabajo y renombrado

prepare-rename devuelve un rango y marcador de posición validados o null; rename devuelve una propuesta WorkspaceEdit o null. Las propuestas admiten editar, crear, mover y eliminar sobre rutas relativas de archivos disjuntas. Se comprueban el SHA-256 actual del archivo fuente, la ausencia del destino, la política de rutas protegidas, la geometría UTF-16 de edición y los límites. Las capacidades del lenguaje autorizan propuestas; el cliente del espacio de trabajo proporciona el acceso a archivos y las modificaciones aprobados por separado.

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);

El llamante utiliza un cliente conectado y autorizado del espacio de trabajo y un diario confiable. La vista previa contiene instantáneas completas anteriores y posteriores y un resumen criptográfico; apply requiere el planId y resumen revisados y una política actual del anfitrión que devuelva true. Cada archivo pasa una comprobación preliminar y después cada operación utiliza el CAS existente por archivo y las capacidades actuales de escritura y gestión. El diario persiste y vuelve a leer la intención antes de cada modificación y un comprobante después. Un conflicto o incertidumbre detiene las escrituras posteriores; cada operación de archivo completada tiene su propio resultado CAS y comprobante en el diario.

El adaptador opcional workspace-edits-node almacena un diario acotado fuera del espacio de trabajo seleccionado, vincula su identidad y utiliza un bloqueo de escritor único, archivos regulares y puntos de control de sumas de comprobación. Tras terminar el proceso, recoverStaleLock es una decisión explícita y solo reclama a un propietario cuya terminación esté demostrada. La recuperación informa de applied/not-applied/conflicted/unknown a partir de los bytes actuales; el llamante elige explícitamente la acción siguiente. La compensación crea una propuesta inversa nueva para una nueva revisión. En Windows, el adaptador sincroniza archivos y realiza operaciones de renombrado. Las comprobaciones documentadas abarcan la terminación de procesos y la recuperación; la persistencia depende del sistema de archivos y del dispositivo de almacenamiento. Los límites incluyen 32 cambios, 1000 ediciones, 256 KiB por archivo, una vista previa de 8 MiB y 64 planes de diario conservados.

Formato y acciones 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 y format-range requieren una ruta y las opciones tabSize/insertSpaces; solo el formato de rango recibe una selección. Un resultado es null o exactamente una edición del archivo actual con el hash de la instantánea actual. Las ediciones de rango permanecen dentro de la selección. endOfLine selecciona preserve, lf o crlf para el texto insertado; los bytes no editados permanecen sin cambios. Las propuestas de contenido idéntico se normalizan a null. prepareFormatting no realiza escrituras.

El anfitrión vincula las solicitudes de acciones y los tokens de resolución a la revisión aceptada del diagnóstico y a la instantánea actual. La publicación posterior de diagnósticos, un cambio de documento o la liberación del proveedor invalida selecciones antiguas. Las llamadas de diagnósticos fuera de orden no sobrescriben el paquete aceptado más reciente. Hasta 100 acciones contienen etiquetas de texto sin formato, índices acotados de diagnósticos, ediciones propuestas, datos privados de resolución o un motivo de deshabilitación. Se rechazan los campos desconocidos de comando, URL o shell. Las ediciones de acciones pueden extenderse más allá de la selección, así que revise la propuesta completa; el formato y las acciones nunca aprueban sus propias escrituras.

Visualización semántica, plegado, sugerencias y 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);

Los tokens semánticos utilizan una leyenda con nombres únicos y nueve claves de estilo propias del anfitrión, además de cinco enteros por token: diferencias de línea e inicio, longitud UTF-16, índice de tipo y bits de modificador. Los tokens no pueden solaparse, dividir un par sustituto, cruzar una línea ni salir del documento actual. El anfitrión siempre devuelve una matriz normalizada completa y un UUID de anfitrión, con updateKind full/delta/fallback. Una capacidad separada semantic-tokens-delta habilita provideDelta sobre datos anteriores propios del proveedor; la caché almacena identidad y datos de tokens, no texto antiguo del documento.

Una base de caché está vinculada al proveedor, ámbito, URI y lenguaje, con como máximo ocho entradas, 4 MiB y 60 segundos. Los incrementos normales de versión del documento conservan una posible base delta mientras vuelven obsoleto el resultado visual anterior. Una base perdida o caducada, un delta null o un ID de base del proveedor discordante permiten como máximo una alternativa completa dentro del tiempo de espera original. Los datos inválidos o errores del proveedor fallan sin reintentar. Desactivar, retirar el registro y reemplazar el documento borran las bases afectadas. Invoque validateLanguageResult inmediatamente antes de representar; un objeto copiado, liberado u obsoleto falla.

Los límites son 20000 tokens semánticos, 64 tipos de token, 16 modificadores y 64 ediciones delta; el plegado admite 1000 rangos con profundidad 32 y rechaza rangos cruzados. Las sugerencias insertadas admiten 1000 etiquetas de texto sin formato de una línea dentro del rango solicitado. Los símbolos jerárquicos admiten 1000 entradas en total y 16 niveles, con hijos y selecciones contenidos y hermanos ordenados sin solapamiento. El contrato original plano document-symbols permanece sin cambios. El ejemplo del navegador prueba full/delta/fallback, plegado, navegación y ciclo de vida; una sugerencia similar a HTML permanece como 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-browser

Asistencia · Ediciones revisadas · Formato y acciones · Visualización

Ajustes tipados y referencias de secretos

El módulo /settings proporciona un almacén en memoria propio del operador para un plugin. Una definición con versión declara cada clave, esquema de datos, valor predeterminado, ámbitos de usuario y espacio de trabajo permitidos y metadatos de visualización. Los valores efectivos sustituyen cada clave completa en el orden default < user < workspace. read(workspaceId) devuelve valores y fuentes inmutables y una revisión de todo el almacén. Los objetos anidados no se combinan recursivamente; un valor ausente sin valor predeterminado sigue 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}, ...}).

Las escrituras validan toda la transacción y utilizan CAS con expectedRevision. reset elimina una clave de una capa; readOnly exige un valor predeterminado y ningún ámbito con escritura. Las suscripciones agrupan cambios síncronos y devuelven referencias cuyos recursos se pueden liberar. migrate(nextDefinition, callback, options) explícito valida el estado siguiente y confirma solo si su revisión sigue coincidiendo. Un fallo, cancelación o tiempo de espera agotado conserva la definición y el estado anteriores. La exportación e importación son datos sin formato especial; el operador es responsable de la persistencia y el cifrado. Los límites incluyen 64 claves, 32 capas de espacios de trabajo, 1 MiB de estado exportado y una migración real.

Los plugins del espacio de trabajo declaran settings y settings.read, y el operador monta el almacén correspondiente con esa autorización. context.settings es de solo lectura y está vinculado al plugin y espacio de trabajo seleccionado. El resolvedor /secrets emite por separado referencias opacas para un plugin, espacio de trabajo, lista permitida de comandos y duración. El manifiesto debe declarar secrets.resolve y el anfitrión debe concederlo. Los campos de entrada utilizan type: object con format: dds-secret-reference; las cadenas normales y los objetos similares no transmiten autoridad sobre secretos.

Solo las referencias de una entrada validada están disponibles mediante options.secrets.withSecret del comando. Cada ejecución tiene un ID nuevo; el resolvedor comprueba ámbito, caducidad, revocación y autorización actual antes y después de resolver y de la función de retorno. La función devuelve undefined y recibe una copia que se borra al abortar y en cada salida. Los errores del proveedor se limpian de datos sensibles. Sitúe la concesión temporal antes de los efectos que requieran esa autoridad. La duración predeterminada de la referencia es de 60 segundos y como máximo una hora; los límites son 128 referencias, 8 concesiones reales y 16 KiB de material. El código confiable dentro del proceso puede conservar copias y se ejecuta con el acceso del proceso anfitrión al sistema operativo. Mantenga el material secreto dentro de la función de retorno autorizada y clasifique explícitamente las cadenas de la aplicación antes de almacenar ajustes, paquetes, registros o resultados.

Esquemas estructurados de comandos y formularios

Los comandos pueden declarar inputSchema y outputSchema mediante un sobre schemaVersion: 1. Los parámetros primitivos existentes siguen siendo compatibles; declarar parameters e inputSchema juntos se rechaza. El anfitrión valida y aplica valores predeterminados de entrada antes de iniciar un controlador o trabajo y después valida la salida antes de publicar el éxito. Los valores predeterminados de salida nunca se aplican. Los metadatos nuevos de esquema y visualización requieren un par que reconozca 0.12; los validadores estrictos anteriores los rechazan, mientras que las definiciones heredadas conservan su comportamiento.

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);

El subconjunto acotado admite objetos cerrados, matrices, cadenas, números finitos, enteros seguros, booleanos, null, enumeraciones primitivas, límites y valores predeterminados validados. Se rechazan palabras clave desconocidas, referencias remotas, expresiones regulares, uniones, coerciones, accesores y prototipos personalizados. Los esquemas permiten 32 KiB, profundidad 8 y 128 nodos; los valores permiten 64 KiB. Un comando completo mantiene el presupuesto de metadatos de 16 KiB. DataValidationError local expone code, reason y rutas de campos conocidas como /input/options/names/0; los fallos HTTP y de trabajos exponen códigos seguros sin los valores rechazados.

describeDataForm devuelve rutas, tipos, opciones, valores predeterminados, indicadores de obligatoriedad y sugerencias de referencias de secretos. Los metadatos compartidos de visualización contienen label/help/order literales y nombres, descripciones y sugerencias de teclado de accesibilidad. El anfitrión controla la representación y la interacción. Estos esquemas describen datos sin formato especial; el anfitrión controla explícitamente la representación, el acceso a recursos y la ejecución de comandos.

Metadatos de localización y accesibilidad

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.

Los catálogos utilizan etiquetas base canónicas BCP 47 y relaciones explícitas y acíclicas de idiomas alternativos. Hasta ocho preferencias negocian etiquetas exactas, después sus antecesoras y el valor predeterminado. El idioma predeterminado define todas las claves; las traducciones pueden omitir claves, pero no inventarlas. La búsqueda por clave sigue las relaciones alternativas ordenadas y después el valor predeterminado. Cada traducción y sus argumentos deben coincidir con el conjunto exacto de marcadores {name}. Es una interpolación literal sin expresiones ICU. resolveMessage informa del idioma de origen real y la dirección, para que una alternativa en inglés dentro de una página RTL pueda conservar lang=en y dir=ltr.

El formato de números admite decimal/porcentaje; el formato de fechas utiliza una época explícita y UTC por defecto; la selección de plurales devuelve una categoría cardinal u ordinal de Intl para la elección de mensajes del llamante. Los anfitriones son responsables de los datos y la compatibilidad de Intl. validateLocalizedSurfaces comprueba las claves de manifiestos, comandos, ajustes y esquemas y los archivos complementarios de visualización de temas, incluidas las longitudes resueltas de visualización y las traducciones ausentes. El JSON/XML de temas sigue siendo compatible. Los límites de catálogo son 32 idiomas, 256 claves y 256 KiB; las etiquetas estáticas no pueden contener marcadores de posición.

Los asistentes /accessibility informan de nombres ausentes, atajos normalizados duplicados y contraste explícito entre pares de colores opacos en temas claros y oscuros. Los anfitriones utilizan estas indicaciones para implementar atajos de teclado y evaluar la accesibilidad de sus interfaces. El ejemplo independiente incluye EN/KO, árabe parcial y casos de prueba de etiquetas largas. Prueba ajustes con ámbitos, referencias denegadas o revocadas, campos inválidos, Ctrl+Enter y cambios de idioma durante un comando activo. La disposición del navegador se comprobó a tamaños de escritorio y móvil con temas claros y oscuros.

npm run example:configuration
npm run example:configuration-browser

Configuración · Referencias de secretos · Esquemas de comandos · Localización

Plantillas de desarrollo y generación

Seis plantillas, dependencias exactas de archivos comprimidos, revisión de generación, preservación de conflictos y comprobaciones de doctor.

Contratos completos, ejemplos y límites

Pruebas deterministas y reproducción

Casos de prueba sintéticos explícitos, tiempo virtual, fallos, trazas acotadas solo de hashes y limpieza de recursos.

Contratos completos, ejemplos y límites

Diagnósticos locales y depuración

Perfiles locales de aceptación explícita y un depurador confiable de procesos hijos con un punto de conexión loopback efímero y un plazo total.

Contratos completos, ejemplos y límites

Conformidad del anfitrión

18 perfiles con versión distinguen contratos admitidos, no admitidos y fallidos; los adaptadores personalizados conservan la autoridad explícita.

Contratos completos, ejemplos y límites

Soporte y migración del SDK

Consulte el inventario de exportaciones, la política estable, opcional y experimental, los pares exactos, las fechas de entornos de ejecución y los ejemplos de migración.

Contratos completos, ejemplos y límites

Aceptación de versiones

La versión publicada del SDK presenta las cargas de trabajo con fallos combinados y las comprobaciones de rendimiento medidas como validación funcional de los contratos SDK y anfitriones independientes.

Contratos completos, ejemplos y límites

1.1 Herramientas de dependencias, procedencia y actualización

1.1.0 añade paquetes deterministas sin conexión de dependencias revisadas, SBOM CycloneDX, firmas separadas con claves Ed25519 propias del operador, aprobación, activación y reversión vinculadas al resumen criptográfico y comparación explícita con el origen. Cinco puntos de entrada exclusivos de Node incluyen declaraciones, esquemas y ejemplos independientes. El operador concede explícitamente la ejecución después de revisar la firma y los trabajos antiguos conservan su hash original. El operador elige el flujo de distribución, implementación y supervisión. La versión publicada del SDK documenta la validación funcional mediante sus ejemplos independientes de herramientas de publicación.

node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjs

Guía completa de paquetes, firmas, actualizaciones y origen

1.2 Flujos de trabajo, caché, flujos de herramientas y LSP

1.2.0 añade DAG de comandos revisados con trabajos y autorizaciones por paso, puntos de control persistentes y recuperación explícita mediante intentos nuevos; caché determinista basada en contenido y ejecución incremental; flujos acotados de herramientas UTF-8/JSONL/texto; y un puente opcional LSP 3.17 mediante stdio. Siete puntos de entrada nuevos elevan el paquete a 50 exportaciones y 107 esquemas con declaraciones y ejemplos instalados independientes, sin dependencias npm en tiempo de ejecución. El analizador de flujos de herramientas también funciona en navegadores; los flujos de trabajo, almacenes, procesos externos y LSP requieren Node. La versión publicada del SDK documenta comprobaciones funcionales de adaptadores con TypeScript 5.9.3 y language-server 5.3.0. El puente acepta diagnósticos vinculados a una versión del documento. El anfitrión independiente del SDK gestiona la recuperación explícita mediante nuevos intentos, los almacenes locales y la configuración de procesos.

node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs

Guía completa de flujos de trabajo, caché, herramientas y LSP