DDS Plugin SDK
Установите публичный DDS Plugin SDK 1.2 и используйте рабочие процессы, кеш, потоки инструментов, LSP и стабильные API.
Примеры пользовательской рабочей области ниже описывают явно подключённый хост разработки под управлением клиента. WSL — один из необязательных хостов этих примеров. Обычное приложение Digital Design Studio для Windows использует собственные файлы Windows и общую среду UI/WASM. Оператор настраивает обнаружение, разрешения и возможности плагинов для выбранного хоста SDK; управляемые задания движков Cloud используют свою модель выполнения.
1. Установите SDK
DDS Plugin SDK 1.2.1 предоставляет API JavaScript, объявления TypeScript, языковые провайдеры, темы, инструменты рабочей области и задания команд. Необязательные постоянные хранилища добавляют историю заданий, явный повтор и проверенные текстовые/бинарные снимки, сохраняющиеся после удаления исходника и перезапуска процесса. Используйте Node.js 22 или 24. Установите стабильный выпуск SDK из официального релиза GitHub. Для отдельного командного плагина после установки используйте Инструменты разработки:
Версия 1.0.0 публикует стабильный API SDK, 18 профилей соответствия хостов, политику поддержки и миграции и измеренные проверки совмещённых нагрузок. Новые плагины используют >=1.0.0 <2.0.0. Опубликованная функциональная проверка охватывает API SDK, соответствие хостов и совмещённые нагрузки. Используйте эти результаты для оценки поведения SDK, проверенного при выпуске.
Версия 0.13.0 добавляет шесть шаблонов разработки, генерируемые типы и схемы, детерминированные тестовые сценарии и необязательную локальную диагностику. Упакованный SDK и сгенерированные проекты работают вне дерева исходников; синтетическое воспроизведение и отладка через loopback выбираются явно.
Версия 0.12.0 добавляет типизированные настройки с ограниченной областью действия и явные миграции, ссылки на секреты в области выполнения, структурированный ввод/вывод команд, каталоги локализации и метаданные доступности. Публичный SDK и независимые примеры проверяют конфликты настроек, неверный ввод, отозванные полномочия и резервный перевод. Используйте эти возможности через API хоста автономного SDK и независимые примеры.
Версия 0.11.0 добавляет подсказки сигнатур, отложенное автодополнение, ограниченные сниппеты, проверяемые изменения нескольких файлов и переименование, форматирование и действия с кодом, семантические токены, сворачивание, подсказки и иерархические символы. Предложения проходят проверку и оценку текущих полномочий перед условным применением; отображение и применение требуют актуальных результатов документа. Независимые примеры проверяют эти возможности в явно настроенном публичном хосте SDK.
Версия 0.10.0 добавляет потоковое скачивание в браузере, загрузку выбранных файлов, смешанную очередь передач и восстановление контрольных точек Worker OPFS. Передачи проверяют текущие полномочия, идентичность файла и хеши частей и целого, различая прогресс передачи байтов и подтверждённое сохранение. Используйте эти примеры публичного SDK с явно настроенным хостом и интеграцией, которой управляет приложение.
Версия 0.9.0 добавляет деревья проектов с ограниченной областью действия, поиск по именам файлов и тексту и наблюдение за изменениями в локальных каталогах, выбранных оператором. Используйте их через HTTP-клиент или вспомогательный модуль проекта, сохраняя снимки редактирования и несохранённые черновики. Примеры проектов ниже охватывают создание, поиск, внешние изменения и обработку конфликтов.
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"
Первый пример диагностики использует доверенный код на локальном тестовом хосте. Темы используют существующий импорт XML DDS. Существующие интеграции инструментов описаны в разделе Плагины и сторонние инструменты.
2. Напишите первый плагин
Создайте plugin.mjs в новом проекте. Этот плагин проверяет обычные текстовые документы и выдаёт информационное диагностическое сообщение для каждой строки с 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);
},
}));
Манифест объявляет версию протокола 1, возможность diagnostics, хост test-host и разрешения document.read и diagnostics.publish. Провайдер получает снимок документа и объект AbortSignal. Диагностические диапазоны используют номера строк с нуля и смещения символов UTF-16.
3. Запустите локально
Создайте run.mjs рядом с plugin.mjs. Активируйте плагин, предоставьте документ и запросите диагностику. По завершении всегда освобождайте ресурсы хоста.
run.mjs
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
const host = createTestHost();
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'example-1',
text: 'Hello, DDS!\nNOTE: write a plugin.\n',
});
const result = await host.requestDiagnostics();
console.log(`${plugin.manifest.name}: ${result.diagnostics.length} diagnostic`);
for (const diagnostic of result.diagnostics) {
console.log(`${diagnostic.severity} ${diagnostic.range.start.line + 1}:${diagnostic.range.start.character + 1} ${diagnostic.message}`);
}
} finally {
host.dispose();
}
node run.mjs
Ожидаемый вывод (выводимые номера строки и столбца начинаются с единицы):
Текст
Hello Diagnostics: 1 diagnostic
info 2:1 Review this marked line before sharing the document.
4. Протестируйте плагин
Сохраните этот тест как plugin.test.mjs. Он проверяет диагностический диапазон и подтверждает, что редактирование документа удаляет диагностическое сообщение.
plugin.test.mjs
import assert from 'node:assert/strict';
import test from 'node:test';
import { createTestHost } from '@altifigence/dds-plugin-sdk/testing';
import plugin from './plugin.mjs';
test('reports a NOTE and clears it after editing', async () => {
const host = createTestHost();
try {
await host.activate(plugin);
const document = {
uri: 'memory:///hello.txt',
languageId: 'plaintext',
modelVersion: 1,
workspaceRevision: 'test-1',
text: 'NOTE: write a plugin.\n',
};
host.setDocument(document);
const result = await host.requestDiagnostics();
assert.equal(result.diagnostics.length, 1);
assert.equal(result.diagnostics[0].code, 'todo');
assert.deepEqual(result.diagnostics[0].range, {
start: {line: 0, character: 0},
end: {line: 0, character: 4},
});
host.setDocument({...document, modelVersion: 2, text: 'Done.\n'});
assert.equal((await host.requestDiagnostics()).diagnostics.length, 0);
} finally {
host.dispose();
}
});
node --test plugin.test.mjs
Тест должен пройти. Добавьте тестовые данные для своего языка, отмены, неверных результатов и больших документов. Поддерживайте актуальную версию документа, чтобы результаты более раннего снимка отклонялись.
5. Создайте и примените тему
Сохраните эту светлую/тёмную палитру как theme.json. Все шесть цветов каждой палитры обязательны. Необязательные семантические токены настраивают поиск, выделение, HintsBox и холст GDS; для пропущенных токенов используются значения 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
}
}
}
Создайте export-theme.mjs рядом с ней. parseTheme проверяет цветовые данные, а serializeThemeXml экспортирует XML DDS версии 2.
export-theme.mjs
import { readFile, writeFile } from 'node:fs/promises';
import { parseTheme, serializeThemeXml } from '@altifigence/dds-plugin-sdk/themes';
const theme = parseTheme(await readFile('./theme.json', 'utf8'));
await writeFile('./hello-theme.xml', serializeThemeXml(theme), 'utf8');
console.log('Created hello-theme.xml');
node export-theme.mjs
Команда записывает hello-theme.xml и выводит Created hello-theme.xml. В DDS откройте Плагины → Установить тему…, выберите XML, затем нажмите Применить для Hello Ocean. Переключитесь между светлым и тёмным оформлением, чтобы увидеть обе палитры.
Также можно использовать Настройки → Общие → Внешний вид → Импорт XML. Перед заменой сохраните текущую тему через Экспорт XML. При этом данные оформления XML импортируются в конфигурацию темы.
В руководстве по темам перечислены все поддерживаемые токены и метрики. Пример Hello Ocean включает полную тему, готовый к импорту XML и локальный предварительный просмотр HTML.
Справочник XML тем
Скачайте XML Hello Ocean и соответствующий редактируемый JSON. XML содержит полные светлую и тёмную палитры, все 28 необязательных ролевых цветов в каждом режиме и четыре явные метрики. Перед импортом сохраните XML локально. Эти оригинальные примеры SDK распространяются по лицензии Apache-2.0; при распространении сохраняйте уведомление.
Начните с Настройки → Общие → Внешний вид → Экспорт XML для резервного копирования текущей темы. Импортируйте скачанный XML, проверьте черновик и выберите Применить. Отменить изменения сохраняет применённую тему. Переключайте светлое/тёмное оформление для проверки обеих палитр. Для восстановления выберите встроенную тему или импортируйте сохранённую копию. Отклонённый импорт сохраняет текущую тему.
DDS, ALcad, общие редакторы, навигация по проекту, настройки и всплывающие окна используют общую палитру рабочей среды этого профиля. Cloud и настольное приложение используют одинаковый формат темы; импортируйте её отдельно в каждом профиле. gdsBackground независимо управляет холстом GDS. Цвета других проектных холстов, слоёв и симуляций могут иметь собственные настройки. XML содержит палитру и параметры оформления для этого профиля темы.
Элемент | Правило |
|---|---|
| Один корневой элемент; имя без краевых пробелов длиной 1–80 кодовых единиц UTF-16; не более 65536 байтов UTF-8 для всего XML. |
| Оба обязательны; каждый содержит шесть цветов ниже. |
| Необязательные переопределения v2. Пропущенные роли используют значения DDS по умолчанию для этого режима. |
| Необязательные числовые переопределения v2. |
Версия 1 | Только обе палитры. Существующие файлы v1 по-прежнему поддерживаются; экспортёр SDK создаёт v2. |
Обязательный ключ палитры | Назначение |
|---|---|
| Внешний фон рабочей области |
| Навигация по проекту |
| Панели инструментов и элементы управления |
| Основная рабочая область и настройки |
| Основной текст |
| Второстепенный текст |
Необязательные ключи ролей (28) | Назначение |
|---|---|
| Фон, текст и текст-заполнитель общего поиска |
| Поле совместимости; текущие общие поля поиска не имеют рамки |
| Выделенные строки и текст |
| Вкладки редактора |
| Панели инструментов, границы панелей и всплывающие окна |
| Контур клавиатурного фокуса |
| Цвета состояния и фон сферы ИИ |
| Фон предложений и подробностей |
| Текст предложений, подробностей и второстепенный текст |
| Предложение, выбранное клавиатурой |
| Предложение под указателем |
| Фон холста просмотрщика GDS |
HintsBox — общая функция подсказок кода. Её цвета находятся в разделе Своя палитра → Подробные цвета и форма → Подсказки, а фон GDS — в разделе Отображение. Изменяйте все три цвета поиска вместе для читаемого контраста. Этот фрагмент должен находиться внутри темы v2; сохраните две полные палитры:
Фрагмент XML v2
<tokens mode="dark">
<color key="search" value="#214556"/>
<color key="searchText" value="#e8f4fb"/>
<color key="searchPlaceholder" value="#adcadb"/>
</tokens>
Метрика | Допустимые значения | Текущее значение DDS по умолчанию |
|---|---|---|
| Целое число 0–24 | 14 |
| Целое число 0–16 | 6 |
| Целое число 0–24 | 16 |
| Число 0,6–1 | 0,72 |
Записывайте метрики как <number key="popoverOpacity" value="0.9"/> внутри <metrics> без единиц измерения. Радиусы указаны в пикселях. SDK оставляет пропущенные метрики отсутствующими; установленный выпуск DDS задаёт свои значения по умолчанию. Для единообразного оформления задайте явные значения. Hello Ocean намеренно задаёт 16, 8, 12 и 0,9. Уменьшение прозрачности и принудительные цвета могут изменить итоговое отображение.
Каждый цвет должен иметь шестизначный формат #RRGGBB; альфа-канал, имена CSS, переменные, URL и стили отклоняются. Повторяющиеся ключи или режимы, неизвестные элементы/атрибуты, пространства имён, DTD, сущности и инструкции обработки отклоняются. XML-декларации и комментарии разрешены. Если импорт не удался, проверьте размер файла, версию, обе полные палитры и допустимые значения, затем повторите с неизменённой резервной копией. Темы других редакторов требуют преобразования в этот формат DDS.
6. Запустите рабочую область в своей среде
Запустите хост, SDK, плагины и инструменты в собственной среде WSL, контейнере или на сервере. Файлы проекта остаются в выбранном вами корневом каталоге. Автономный клиент SDK читает и редактирует их через подключение; он получает метаданные плагинов и результаты команд, а код плагинов работает в вашей среде.
В созданном выше проекте SDK сохраните этот вспомогательный скрипт как copy-workspace-example.mjs. Он копирует редактируемый сервер, плагин, инструмент и пример проекта, сохраняя структуру файлов лицензии примера.
copy-workspace-example.mjs
import { cp, copyFile, mkdir } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await mkdir('./user-host/examples', {recursive: true});
await cp(path.join(sdkRoot, 'examples/user-workspace'), './user-host/examples/user-workspace', {
recursive: true, force: false, errorOnExist: true,
});
await copyFile(path.join(sdkRoot, 'LICENSE'), './user-host/LICENSE');
console.log('Created user-host');
node copy-workspace-example.mjs
Пример проекта находится в user-host/examples/user-workspace/project. Запустите сервер в этой среде, используя явно сгенерированный токен:
WSL / Linux / контейнер
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
Сервер выводит Workspace server: http://127.0.0.1:4777/dds/workspace/v1 вместе с идентификатором и поколением рабочей области. В терминале клиента задайте DDS_WORKSPACE_TOKEN равным сгенерированному токену. Это учётные данные оператора, отдельные от токена DDS Account. Остановите сервер примера сочетанием Ctrl+C.
В другом терминале того же проекта задайте DDS_WORKSPACE_TOKEN равным тому же секрету и запустите клиент разработчика:
node user-host/examples/user-workspace/client.mjs http://127.0.0.1:4777
Клиент перечисляет файлы примера и выполняет Проверить файл проекта для design.sv. Результат JSON содержит tool: "module-counter" и modules: 1, полученные от настоящего дочернего процесса. Добавляйте --edit к команде клиента только если хотите, чтобы пример дописал заметку в файл.
Для собственного проекта передайте его абсолютный каталог последним аргументом server.mjs. Сервер, модули плагинов и установленные инструменты должны находиться в той же пользовательской среде. server.mjs явно импортирует плагин и сопоставляет его именованный бэкенд с фиксированным исполняемым файлом и аргументами:
Сопоставление бэкенда в server.mjs
'module-counter': createProcessBackend({
executable: process.execPath,
args: [fileURLToPath(new URL('./tool.mjs', import.meta.url))],
cwd: root,
env: {},
})
Замените это сопоставление своим одобренным установленным инструментом или собственным бэкендом. ctx.workspace.readFile и writeFile используют пути относительно выбранного корня; ctx.backends.invoke("module-counter", input, {signal}) вызывает только настроенное имя бэкенда. Адаптер процесса отправляет ограниченный JSON через stdin и ожидает JSON в stdout. Он не использует команды оболочки из запроса и не наследует переменные среды хоста.
Для удалённого сервера используйте собственную аутентифицированную HTTPS-точку или приватный туннель, завершающийся на локальном loopback. Настройте проброс порта контейнера или TLS в своей среде. Пример по умолчанию слушает loopback; изменение адреса привязки не добавляет TLS. Доверенные плагины и инструменты работают с полномочиями ОС процесса хоста.
Смотрите пример пользовательской рабочей области и протокол рабочей области для настройки сервера, источников, ревизий файлов, отмены и ограниченных результатов.
Языковые возможности
SDK 0.7.0 предоставляет автодополнение, подсказки при наведении, определения, ссылки и плоские символы документа. Объявите каждую функцию в возможностях манифеста v2 вместе с разрешениями document.read и language.provide. Хост должен явно предоставить оба разрешения. Сохраните этот полный пример подсказок при наведении как language-demo.mjs в созданном выше проекте:
language-demo.mjs
import { definePlugin, createLanguageResult, createPluginHost } from '@altifigence/dds-plugin-sdk';
const plugin = definePlugin({
manifestVersion: 2,
id: 'hello-hover', name: 'Hello Hover', publisher: 'example', version: '1.0.0',
protocolVersion: 1, entry: './language-demo.mjs', runtime: 'ui',
capabilities: ['hover'],
permissions: ['document.read', 'language.provide'],
supportedHosts: ['test-host'], license: 'Apache-2.0',
source: {visibility: 'open', licenseFile: 'LICENSE'},
}, context => context.registerLanguageProvider('hover', {languages: ['dds-demo']}, {
provide(request, {signal}) {
signal.throwIfAborted();
return createLanguageResult(request, {text: 'A local LED signal.'});
},
}));
const host = createPluginHost({grants: ['document.read', 'language.provide']});
try {
await host.activate(plugin);
host.setDocument({
uri: 'memory:///demo.dds', languageId: 'dds-demo',
modelVersion: 1, workspaceRevision: 'demo-1', text: 'led',
});
const result = await host.requestLanguage('hover', {position: {line: 0, character: 1}});
console.log(result.data.text);
} finally {
host.dispose();
}
node language-demo.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/hello-language/run.mjs
Первая команда выводит A local LED signal. Второй встроенный пример проверяет все пять функций с помощью небольшого учебного языка с let name = value; собственный провайдер примера реализует этот учебный язык.
Функция | Ввод запроса | Данные результата |
|---|---|---|
|
| До 500 |
|
|
|
|
| До 500 |
|
| До 500 |
|
| До 500 плоских |
Позиции используют строки с нуля и смещения UTF-16. Вставка автодополнения — буквальный текст; строки подсказок при наведении и подробностей — обычный текст. Перед переходом к расположению хост обязан проверить целевые файлы и диапазоны. Результат сохраняет идентичность запроса, проекта/сеанса и версии документа. Изменение снимка, отмена, тайм-аут, отмена регистрации или освобождение ресурсов завершает ожидающие запросы и отбрасывает поздние результаты.
Эти API работают в доверенном хосте SDK. Приложение хоста интегрирует отображение языковых функций и явно настраивает процессы LSP. Для новых возможностей требуется хост версии 0.3.0 или новее. Прочитайте Языковые возможности о селекторах, ограничениях и жизненном цикле.
Сеансы редактирования проектов
Импортируйте createWorkspaceProject и applyTextEdits из @altifigence/dds-plugin-sdk/workspace-client. После того как хост подключит createWorkspaceClient и проверит идентичность рабочей области, уведомление и доступ, вызовите createWorkspaceProject(client). Проект сохраняет точную привязку подключения. Повторное подключение требует нового проверенного проекта, даже если возвращаются те же идентификатор и поколение рабочей области.
API | Поведение |
|---|---|
| Перечисляет один каталог под выбранным корнем рабочей области. |
| Читает файл и сохраняет его неизменяемое содержимое и ревизию в сеансе редактирования. |
| Создаёт только при отсутствии файла, затем возвращает сеанс. |
| Читает последнее подтверждённое |
| Сохраняет только если ревизия сервера по-прежнему совпадает с сохранённой ревизией. |
| Применяет изменения |
| Явно читает последние содержимое и ревизию после конфликта или записи с неопределённым исходом. |
| Отменяет принадлежащую ему работу; освобождение проекта оставляет клиент, принадлежащий вызывающему, подключённым. |
Запустите полный HTTP-пример из установленного пакета. Он создаёт собственную временную рабочую область, проверяет редактирование, конфликт второго сеанса, явную перезагрузку, Unicode и повторное подключение, затем закрывает сервер и удаляет временный каталог:
node node_modules/@altifigence/dds-plugin-sdk/examples/project-session/run.mjs
Ожидаемый вывод: Project session: HTTP edit, conflict, reload, Unicode and reconnect verified. Исходник примера показывает полную настройку сервера/клиента и очистку.
Параметры принимают signal и timeoutMs. Неудачная запись после попытки оставляет needs-reload; сохраняйте любой несохранённый черновик интерфейса отдельно и явно перезагрузите перед новым сохранением. SDK не объединяет изменения и не повторяет автоматически. Тайм-аут, отмена или потерянный ответ могут произойти после фиксации записи сервером; отмена запроса сохраняет уже зафиксированные изменения. Каждый сеанс допускает одно ожидающее сохранение или перезагрузку.
Текстовые изменения используют исходный снимок, строки с нуля и смещения UTF-16. Перекрытия, разделённые суррогатные пары и неверные диапазоны отклоняются перед сохранением. Проекты допускают не более 64 открытых или открывающихся сеансов и 500 изменений за сохранение. Эти помощники используют неизменённый протокол рабочей области v1, включая серверы SDK 0.2.x, и сохраняют ограничения корня, защищённых путей и режима только чтения. Прочитайте Проекты рабочих областей об ограничениях жизненного цикла и размера.
Справочник API
Импортируйте API плагинов из @altifigence/dds-plugin-sdk. Пакет включает объявления TypeScript для тех же экспортов.
API | Назначение |
|---|---|
| Проверяет манифест и объявляет функцию активации. |
| Регистрирует |
| Создаёт проверенный результат с идентичностью запроса. |
| Регистрирует языковой провайдер и создаёт результат с проверенной идентичностью запроса. |
| Проверяет версию манифеста, идентичность, разрешения, поддерживаемые хосты и входной модуль. |
| Проверяет URI, язык, версию модели, ревизию рабочей области и текст. |
| Проверяет протокол, запрос, область действия, идентичность документа и поля диагностики. |
| Читает типизированные ошибки, ограничения ресурсов и версию протокола. |
Импортируйте хост разработчика из @altifigence/dds-plugin-sdk/testing:
API тестового хоста | Назначение |
|---|---|
| Создаёт локальный хост. Оба параметра необязательны; разрешения по умолчанию допускают чтение документа и диагностику. |
| Активирует плагин и возвращает активацию с освобождением ресурсов. |
| Задаёт текущий документ. Увеличьте |
| Запрашивает диагностику подходящего провайдера; оба параметра необязательны. |
| Запрашивает объявленную языковую функцию с явными разрешениями document.read и language.provide. |
| Удаляет регистрации и отменяет ожидающую работу; освобождайте хост по завершении теста. |
Запросы включают requestId, идентификатор проекта/сеанса scope и снимок с uri, languageId, modelVersion, workspaceRevision и text. Используйте createDiagnosticsResult для сохранения этой идентичности. Результаты содержат массив diagnostics и не включают исходный текст.
Ошибки предоставляют поле code, включая invalid_contract, permission_denied, cancelled, stale_snapshot, provider_unavailable и budget_exceeded. Тайм-аут запроса по умолчанию — 5 секунд; допустимы 1–30000 ms. Документ ограничен 262144 байтами UTF-8, а результат — 500 диагностическими сообщениями. Прочитайте LIMITS для полного списка ограничений.
SDK 1.0.0 также предоставляет отдельные модули. Импорты рабочей области и упаковки только для Node относятся к пользовательской среде:
Импорт | API |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Упакуйте и опубликуйте плагин
Начните со встроенного плагина, готового к публикации. Сохраните этот вспомогательный скрипт в проекте SDK для копирования его файлов в новый каталог my-plugin.
copy-publishable-example.mjs
import { cp } from 'node:fs/promises';
import { createRequire } from 'node:module';
import path from 'node:path';
const require = createRequire(import.meta.url);
const sdkRoot = path.dirname(require.resolve('@altifigence/dds-plugin-sdk/package.json'));
await cp(path.join(sdkRoot, 'examples/publishable-plugin'), './my-plugin', {
recursive: true,
force: false,
errorOnExist: true,
});
console.log('Created my-plugin');
node copy-publishable-example.mjs
Измените plugin.json, plugin.mjs, disclosure.json и лицензию, чтобы описать собственный плагин. Раскрываемые сведения должны совпадать с издателем, идентификатором плагина, версией, лицензией и доступностью исходников в манифесте. Перечислите только файлы, предназначенные для распространения, в dds-package.json:
dds-package.json
{
"schemaVersion": 1,
"files": [
"plugin.json",
"plugin.mjs",
"disclosure.json",
"LICENSE",
"NOTICE"
]
}
Проверьте и упакуйте пример:
npx --no-install dds-plugin validate ./my-plugin
npx --no-install dds-plugin pack ./my-plugin --out ./dist
С неизменёнными метаданными примера pack создаёт dist/example-hello-publisher-1.0.0.tgz и dist/example-hello-publisher-1.0.0.tgz.release.json. JSON релиза содержит итоговый SHA-256 архива, хеши манифеста/раскрываемых сведений и перечень файлов. Проверьте эти файлы перед распространением.
В архив попадают только файлы из разрешённого списка, dds-package.json и сгенерированные метаданные npm. Проверка анализирует данные пакета, а упаковка создаёт локальный архив для выбранного канала распространения. CLI отклоняет приватную конфигурацию, файлы ключей и связанные пути; перед распространением проверьте содержимое выбранных файлов.
Канал | Что предоставить |
|---|---|
Публичный релиз GitHub | Версионированный архив, его внешний JSON релиза, лицензию и необходимый доступ к исходникам. |
Приватный реестр или канал скачивания | Те же версионированные файлы, авторизация получателей и фактические условия плагина. |
Манифест v2 объявляет runtime, запрашиваемые разрешения и source: {visibility, licenseFile, repository?}. Задайте видимость open или closed и включите фактический файл лицензии. Собственный код может распространяться на условиях открытого ПО или проприетарных условиях; применимые уведомления SDK и зависимостей всё равно действуют. Получатели получают исполняемый JavaScript вместе с объявленными метаданными видимости исходников и лицензии.
Следуйте разделам Публикация и Лицензирование для полей раскрываемых сведений и требований распространения. Распространяйте версионные архивы через выбранный релиз GitHub, частный реестр или канал скачивания.
CLI 1.2.1 записывает >=1.0.0 <2.0.0 в новые пакеты плагинов. Исторические архивы 0.3–0.13 и точной версии 1.0.0-rc.1 сохраняют исходные peer-зависимости. Проверьте и переупакуйте новую версию плагина для стабильной установки; издатель явно обновляет объявленный диапазон peer-зависимостей и метаданные релиза при переупаковке.
Проверьте скачанный плагин
SDK 1.2.1 предоставляет dds-plugin verify для метаданных точных выпущенных версий плагинов 0.3.x–0.13.x, RC1 и текущей стабильной версии. Храните .tgz и .tgz.release.json вместе. Проверка сохраняет исходную peer-зависимость. Проверьте созданный выше пакет:
Проверка упакованного примера
npx --no-install dds-plugin verify ./dist/example-hello-publisher-1.0.0.tgz
Команда проверяет ограниченную структуру gzip/tar, точные разрешённые списки файлов, каждый хеш файла, манифест, раскрываемые сведения, лицензию и сгенерированные метаданные npm. Она отклоняет ссылки, небезопасные или повторяющиеся пути, лишние файлы и хуки/зависимости npm. Она читает и проверяет локальный архив на месте как операцию только над данными. При успехе выводится квитанция JSON; при отклонении код выхода — 1.
Для переименованных скачанных файлов используйте --metadata с соответствующим JSON релиза. Получите ожидаемый SHA-256 независимо через доверенный канал релиза и передайте его через --sha256 для фиксации выбранных байтов. API Node предоставляет те же параметры:
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);
Запустите verify-release.mjs с путём архива, путём метаданных и независимо полученным 64-символьным хешем в нижнем регистре в качестве трёх аргументов. checksumPinned равен true только при совпадении переданного хеша. Ограничения: 12 MiB сжатого ввода, 10 MiB содержимого файлов, 4 MiB на файл, 256 файлов и 256 KiB внешних метаданных.
Парные метаданные обеспечивают целостность на основе хешей: замена обоих файлов может создать новые совпадающие хеши. Установите личность издателя через доверенный канал релизов, проверьте код на вредоносное содержимое, а выдачу разрешений и квалификацию установки DDS выполняйте как явные решения хоста. Квитанция описывает байты, прочитанные во время вызова; проверьте фактические байты повторно, если файл может измениться до использования. Существующие архивы плагинов 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 остаются проверяемыми, если удовлетворяют усиленной политике файлов; установка на 1.0 всё равно требует проверки издателя и переупаковки. При необходимости удалите вновь исключённые файлы и опубликуйте новую версию плагина. Этот проверяющий инструмент предназначен для пакетов плагинов DDS; npm-архивы SDK используют SHA-256 своего релиза.
Смотрите Проверка архивов и полный пример упаковки, проверки и подмены.
Разрешения, лицензии и использование данных
Запрашиваемые разрешения манифеста отделены от разрешений хоста, допускающих операции. Перед включением предоставьте пользователю идентичность плагина, версию, фактическую лицензию, область рабочей среды и запрашиваемые разрешения. Перед подключением бэкенда объясните его оператора, передаваемые данные, цель, срок хранения и уведомление о приватности.
Запись | Значение |
|---|---|
| Решение хоста о доступе для точного пакета, рабочей области и разрешений. |
| Пользователь подтвердил ознакомление с информационным уведомлением. |
| Пользователь выбрал, принимать ли фактические условия издателя плагина. |
| Отдельный выбор, когда необязательная обработка основана на согласии. |
Одобрение рабочей области SDK — техническое решение о доступе. Фиксируйте принятие условий плагина и согласие на необязательную обработку персональных данных как отдельные решения. Используйте SDK на условиях лицензии Apache-2.0.
Разработчики хоста могут сохранять версионированное уведомление переносимыми асинхронными помощниками. Например, сохраните это как notice.mjs и запустите 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 связывает запрашиваемое подмножество разрешений с манифестом v2, хешами артефакта и манифеста, поколением рабочей области, идентичностью хоста, уведомлением и сроком действия. isPermissionGranted оценивает текущие идентичности и события отзыва, предоставленные хостом. revokeConsentReceipt создаёт отдельное событие; после этого хост обязан прекратить будущие авторизованные вызовы.
Эти помощники проверяют локальные записи. Фактический выбор пользователя, идентичность, хранение и применение ограничений обеспечивает хост. Прочитайте Разрешения и согласие о точных полях и интерактивный пример разрешений для явной демонстрации разрешения, отказа и отзыва. Издатели и хосты управляют соглашениями через свои процессы распространения.
Исходники, релизы и участие
В официальном репозитории SDK находятся исходники, схемы, примеры и тесты контрактов. Для запуска выпущенного примера и тестов SDK из исходников:
git clone --branch v1.2.1 --depth 1 https://github.com/Altifigence/dds-plugin-sdk.git
cd dds-plugin-sdk
npm ci
npm test
npm run example
npm run example:language
npm run example:project
npm run example:verify
npm run example:jobs
npm run example:observe
npm run benchmark:files
npm run example:artifacts
npm run benchmark:artifacts
npm run example:durable-jobs
npm run example:stored-artifacts
Сообщайте об ошибках SDK через GitHub Issues, указав версию SDK и минимальный пример воспроизведения. SDK лицензирован по Apache-2.0; смотрите лицензию и уведомления репозитория. Используйте страницу релизов для версионированных архивов и примечаний к выпускам.
Этот репозиторий публикует SDK разработчика. Объявленные файлы SDK, схемы, примеры и уведомления определяют состав его публичной области. Проверки пакета обеспечивают точный опубликованный перечень файлов и отклоняют известные шаблоны секретов и приватных путей. Проверяйте выбранное содержимое релиза вместе с шаблонными проверками, чтобы выявлять раскрываемые данные в распространяемых файлах.
Обновления безопасности и ограничения хоста
Обновите сервер рабочей области и клиент SDK до 0.3.2 или новее. Установите обновление сервера для активации улучшенных проверок файлов и ограничений запросов. Перезапустите обновлённый хост, проверьте его новое поколение и вновь получите одобрение перед использованием рабочей области.
Хост рабочей области Node отклоняет жёсткие ссылки, способные указывать на защищённые файлы или файлы вне выбранного корня. Скопируйте намеренно общий файл проекта в обычный файл с одной ссылкой. Хранилища учётных данных, такие как .netrc, _netrc, .git-credentials, .gnupg, .kube и .docker, дополнительные имена SSH-ключей и псевдонимы устройств Windows также блокируются. Упаковка и проверка скачанного применяют соответствующую политику имён учётных данных.
Ресурс сервера | Ограничение |
|---|---|
Одновременно поступающие тела запросов | 16; последующие загрузки получают HTTP 429 до диспетчеризации |
Выполняемые запросы | 64; отмена использует отдельный путь диспетчеризации |
Подключения / запросы на сокет | 128 / 128 |
Запрос и ответ / содержимое файла | 1600000 / 262144 байта UTF-8 |
Клиент отменяет непрочитанные отклонённые ответы и зависшие потоки по сроку или отмене. Тайм-аут после начала записи может оставить результат неопределённым: перечитайте файл перед повтором. Проверяйте содержимое файлов вместе с исключениями путей для выявления секретов. Доверенный код плагина работает с доступом ОС процесса хоста. Используйте руководство по обновлению безопасности и ограничения рабочей области при развёртывании хоста.
Инструменты разработки
После установки SDK 1.2.1 выше создайте отдельный проект командного плагина. Выберите новый каталог для создаваемых файлов; явно выполните установку зависимостей и запуск плагина после создания каркаса. Каркас включает команду, тест, манифест, уведомление, закреплённую зависимость SDK и Apache-2.0 LICENSE/NOTICE.
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 читает метаданные и проверяет Node, разрешение SDK, манифест, лицензию, раскрываемые сведения и разрешённые файлы пакета, не импортируя плагин. Ошибки дают код выхода 1; примерные значения издателя/поддержки дают предупреждения. Замените их и проверьте лицензии перед распространением.
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 требует --trust-local-code. Он выполняет доверенные локальные импорты/активацию в дочернем процессе и наблюдает только разрешённые файлы плюс dds-package.json. Каждый запуск имеет срок и ограничение stdout/stderr 256 KiB. Ctrl+C прекращает наблюдение и очищает дерево процессов. Дочерний процесс работает с вашим доступом ОС и наследует вашу среду. Тестовый хост по умолчанию разрешает чтение документов и диагностику; для этих интеграций явно настройте хост рабочей области и разрешения рабочей области/бэкенда.
Используйте --job для вывода прогресса/журналов задания; --timeout-ms задаёт до 30 секунд для обычных команд или 30 минут для заданий. API Node: initPlugin, doctorPlugin и runPluginDev в /devtools. Смотрите руководство по инструментам разработки о наблюдении и ограничениях очистки.
Длительные задания команд
Включите jobs: true на хосте/сервере SDK 0.4.0 для выполнения команд дольше обычного срока запроса. По умолчанию задания отключены. Попробуйте полный локальный HTTP-пример, сообщающий прогресс, журнал именованного бэкенда и файл результата с фиксированным хешем:
node node_modules/@altifigence/dds-plugin-sdk/examples/command-jobs/run.mjs
Ожидаемый вывод: Command job: progress, backend log and pinned result file verified. Обработчик команды получает необязательное job в {signal, job}. Оно предоставляет reportProgress, log, addArtifact и invokeBackend. Существующие разрешения workspace.read/write и backend.invoke остаются обязательными; произвольный путь исполняемого файла не принимается.
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);
}
Фрагмент опроса предполагает подключённый клиент и настроенную команду analyze, регистрирующую report. Сохраните идентификатор задания до начала. Отключение или прерывание запроса опроса не отменяет выполнение; подключитесь к тому же поколению и явно запросите состояние или отмену. Повторные запуски с тем же ID и вводом используют сохранённое задание; изменённые аргументы вызывают конфликт. Перезапуск хоста теряет записи в памяти. Включите отдельное постоянное хранилище 0.8 ниже для восстановления зафиксированных метаданных после перезапуска.
Состояния: running, succeeded, failed, cancelled и timed_out. Поздний вывод после отмены отбрасывается; побочные эффекты не откатываются. Незавершённые провайдеры удерживают свои слоты. Допускается не более 4 одновременных заданий, 32 сохранённых записей, 32 вложенных операций на задание, 256 событий/64 KiB на задание, 64 событий на страницу и 16 артефактов. Время выполнения по умолчанию — 5 минут, максимум — 30 минут. Завершённые конечные записи истекают через 15 минут после последнего события.
Текстовые файлы результата — UTF-8 относительно рабочей области до 256 KiB. Хост читает их с существующим разрешением, записывает SHA-256 и отклоняет последующие чтения, если байты изменились. Для бинарного или более крупного вывода симуляции используйте необязательный API бинарных результатов. Частичные артефакты могут остаться после отмены; проверяйте конечное состояние задания для подтверждения успеха. Старые клиенты 0.3 продолжают использовать существующие методы v1; задания автономного SDK требуют 0.4 с обеих сторон и явно настроенных хоста/клиента. Смотрите Задания о точных контрактах и ограничениях.
Наблюдение за файлами рабочей области
project.watchFiles() периодически проверяет 1–16 явных относительных путей файлов. SDK 1.0.0 использует запросы только ревизий на поддерживающих хостах и существующее ограниченное чтение на старых. Пример предполагает подключённый клиент, одобренный хостом. Измените design.sv внешним редактором для завершения цикла; сохранённый снимок редактирования остаётся неизменным.
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(); }
События неизменяемы: {kind, path, previousRevision, revision}. Первая проверка выдаёт initial; последующие изменения — created, changed или deleted. У отсутствующих файлов revision равна null. includeInitial: false записывает исходное состояние без события, а одинаковые ревизии не создают события. Только not_found означает удаление; ошибки разрешений, защищённых путей, размера и транспорта завершают наблюдение.
Храните несохранённый текст интерфейса отдельно. Перезагрузка, объединение и сохранение черновика выполняются по явному решению вызывающего; сохранение изменений всё ещё может конфликтовать с сохранённой ревизией. Пути читаются по одному по порядку; это периодическое наблюдение, поэтому промежуточные изменения могут объединяться. Этот API опрашивает явно выбранные пути файлов; вызывающее приложение управляет обнаружением каталогов и обработкой переименований. Существующие ограничения корня, размера файла и защищённых путей действуют на серверах только для чтения и с записью.
Наблюдатели файлов и заданий запускаются при первом next(), не загружают страницы в фоне при паузе потребителя и совместно допускают максимум восемь активных наблюдателей на клиент. Один next() может ожидать; параллельное чтение завершается conflict. Break или return() прекращает ожидающие чтения; освобождение проекта прекращает его наблюдателей файлов, а отключение/повторное подключение/освобождение делает все старые наблюдатели недействительными. AbortSignal завершает наблюдение с cancelled; поздние ответы не могут выдавать результаты.
intervalMs — 250–60000 ms (по умолчанию 1000), применяется между обходами файлов или чтениями заданий без событий. requestTimeoutMs — 1–30000 ms на запрос, по умолчанию срок клиента. Общий timeoutMs — 1–1800000 ms с первого next(), включая паузы потребителя. У файлов по умолчанию нет общего тайм-аута; у заданий — 30 минут. Истечение срока выдаёт budget_exceeded и освобождает слот. Эти ограничения экспортируются как WORKSPACE_OBSERVATION_LIMITS.
node node_modules/@altifigence/dds-plugin-sdk/examples/workspace-observation/run.mjs
Ожидаемый вывод: Workspace observation: file changes, retained draft and resumed job verified. Полный пример создаёт собственную временную рабочую область и проверяет изменения файлов, конфликты черновиков и явное возобновление задания. Смотрите Наблюдение обо всех параметрах и правилах времени жизни.
Наблюдение и возобновление заданий
client.watchJob() отслеживает существующее задание через jobs.events/get; waitForJob() возвращает его конечный снимок. Фрагмент предполагает подключённый клиент, явно запущенный jobId и savedCursor (или undefined). Проверьте getJobCapabilities() перед запуском задания. Наблюдение никогда не запускает, не повторяет и не отменяет команду.
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);
Каждое замороженное обновление содержит snapshot, events, after, nextCursor, dropped и hasMore. Обрабатывайте максимум 64 события на страницу и сохраняйте nextCursor после её обработки вместе с ID задания и идентичностью рабочей области. dropped сообщает об истёкшей истории. Снимок может быть новее страницы событий; продолжайте читать конечные снимки, пока hasMore равен true. Итератор завершается после последней страницы. waitForJob() вычитывает те же страницы и возвращает succeeded, failed, cancelled или timed_out; проверяйте состояние, а не считайте каждый разрешённый promise успехом.
Остановка итератора или тайм-аут прекращает только наблюдение. Команда сервера продолжает работать до завершения или явного вызова cancelJob(). После одобренного хостом повторного подключения проверьте тот же ID и поколение рабочей области и создайте нового наблюдателя с сохранёнными ID задания и курсором. Старые наблюдатели недействительны даже при неизменной идентичности. Отсутствующие/истёкшие задания и ошибки транспорта сообщаются без повторной отправки; задания в памяти не переживают перезапуск хоста. Постоянное восстановление использует recoverJob() с новым подключением; живые наблюдатели не возобновляются между поколениями.
Существующие контракты v1 hello и заданий неизменны. Наблюдение файлов использует резервный вариант на хостах 0.3.2/0.4/0.5; наблюдение заданий требует включённого хоста 0.4 или новее. Хост сообщает ошибку для неподдерживаемых заданий, а вызывающий явно выбирает последующую команду. Эти API наблюдения работают через автономные хост/клиент SDK. Смотрите Наблюдение и Совместимость.
Ревизии файлов и условное чтение
SDK 0.6.0 добавляет getFileCapabilities(), getFileRevision(path) и readFileIfChanged(path, knownRevision) подключённым клиентам. Чтение ревизии возвращает {path, revision} без содержимого. Совпадающее условное чтение возвращает {path, revision, notModified: true}; изменённое содержимое возвращает notModified: false и content. Передайте knownRevision: null для текущего содержимого. Отсутствующие файлы отклоняются с 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);
Используйте уже подключённый авторизованный клиент. Храните несохранённые черновики отдельно от этого кеша. Условное чтение хеширует и возвращает один снимок файла; последующее чтение всё ещё может увидеть другое изменение. Сохраняйте с ревизией возвращённого содержимого. Эти вызовы не обновляют снимки сеансов редактирования и не объединяют черновики. Неизменённый ответ не имеет поля content; у пустого изменённого файла content: “”.
Наблюдение файлов автоматически использует чтение только ревизии при поддержке. Необязательные методы fs.capabilities, fs.revision и fs.readIfChanged сохраняют строгий v1 hello и исходные файловые методы. Известные хосты рабочей области SDK до 0.6 используют fs.read без пробных запросов. Другие хосты должны ответить на обнаружение или вернуть правильно сопоставленную ошибку unsupported. Каждая false-возможность выбирает собственное ограниченное полное чтение; ответ старого сервера всё ещё передаёт всё содержимое.
Возможности кешируются только для текущего подключения и сбрасываются при повторном подключении или отзыве. Неверные ответы, несовпадения пути/ревизии, разрешения, аутентификация, ошибки транспорта и тайм-ауты не запускают резервный вариант. Объявленные операции, впоследствии завершившиеся ошибкой, не понижаются молча. AbortSignal охватывает обнаружение и чтение; timeoutMs применяется к каждому HTTP-запросу. Смена подключения делает старую операцию недействительной.
Сервер всё ещё выполняет защищённое полное чтение файла и расчёт SHA-256 для каждой проверки. Проверка UTF-8, ограничение 262144 байта и проверки защищённых путей/ссылок остаются в силе. Это уменьшает байты сетевого ответа, сохраняя защищённое чтение с диска и расчёт SHA-256 для каждой проверки. Локальное измерение Node 22.23.1 в Windows для 20 неизменных проверок по 200000 байтов дало 4003974 байта полного чтения, 3867 для ревизий (на 99,903% меньше) и 4247 для условного чтения (на 99,894% меньше). Обнаружение включено; HTTP-заголовки, TLS и начальная база hello/content исключены. Запустите npm run benchmark:files в рабочей копии для воспроизведения тестовых данных.
SDK теперь имеет стабильный API 1.x с функциональными проверками документированного поведения ревизий файлов. Существующие клиенты 0.3.2, 0.4, 0.5 и 0.6 сохраняют исходные API на хостах 0.7. Используйте автономные хост/клиент SDK для проверки этих API. Смотрите Ревизии файлов для полного контракта и правил миграции.
Большие и бинарные результаты заданий
SDK 0.7.0 добавляет необязательное расширение бинарных файлов результатов. Доверенная команда регистрирует существующий файл рабочей области; хост записывает его SHA-256 и длину. Клиенты читают максимум 64 KiB на часть, а загрузчик Node возобновляет частичный файл и проверяет полный вывод. Максимальный зарегистрированный файл — 1 GiB; существующие API файлов UTF-8 и текстовых артефактов 256 KiB сохраняют ограничения.
Включите jobs: true и binaryArtifacts: true на принадлежащем серверу хосте плагинов. По умолчанию оба false. Сохраните явный токен, уведомление оператора, проверенную фиксацию артефакта плагина и действующее разрешение workspace.read. Следующий пример продолжает настройку рабочей области выше; области только для чтения могут регистрировать файлы, уже созданные настроенным инструментом оператора.
Javascript
const server = await createWorkspaceServer({
root, workspaceId, token, notice,
plugins: [{plugin, artifactSha256}],
grants: ['workspace.read'],
jobs: true, binaryArtifacts: true, writable: false,
});
Зарегистрируйте результат внутри команды, запущенной через startCommandJob. Регистрация потоково пропускает существующий файл через SHA-256 с буфером 64 KiB. Ссылка указывает на исходный файл, а не неизменяемую копию. Защищённые пути, обход каталогов, ссылки и не обычные файлы отклоняются; последующие изменения исходника вызывают 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};
});
Используйте уже подключённый авторизованный клиент и существующий ID задания. Назначение — абсолютный путь в существующем реальном каталоге под управлением вызывающего. Помощник записывает destination + “.dds-part” и отказывается перезаписывать существующий итоговый файл.
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);
Храните полную ссылку {jobId, scope, artifact}. После прерывания явно подключитесь к тому же поколению хоста и вновь вызовите помощник с этой ссылкой и resume: true. Он повторно хеширует сохранённый префикс и запрашивает только отсутствующий суффикс. Он проверяет SHA-256 каждой части, всего полученного потока и фактического промежуточного файла перед публикацией. Итоговая квитанция verified: true подтверждает завершение; синхронные обратные вызовы прогресса остаются непроверенными. Повреждённые частичные файлы требуют явного удаления или нового назначения.
listJobBinaryArtifacts(jobId) возвращает зарегистрированные бинарные метаданные отдельно от существующих текстовых результатов. readJobBinaryArtifactChunk(reference, offset, {length?, signal?, timeoutMs?}) возвращает канонический base64 с SHA-256 части, точным диапазоном и маркером EOF. decodeBinaryArtifactData из /artifacts возвращает байты Uint8Array. Браузерные потребители обязаны сами проверить хеш всего файла; проверки отдельных частей не доказывают соответствия собранного вывода ссылке.
Бинарные и текстовые результаты совместно используют 16 слотов и пространство ID на задание. Операции захвата/чтения бинарных данных ограничены четырьмя на хост/рабочую область, а скачивания Node — четырьмя на процесс. timeoutMs скачивания Node — общий срок, по умолчанию максимум 30 минут; requestTimeoutMs по умолчанию 5 секунд с максимумом 30 секунд. Публикация требует поддержки жёстких ссылок, например NTFS или ext4. Используйте доверенное назначение под контролем оператора и управляйте параллельными писателями; проверки файловой системы выполняются с полномочиями ОС процесса хоста.
Необязательные artifacts.capabilities, artifacts.list и artifacts.read сохраняют существующий v1 hello, снимки и события заданий. Хосты до 0.7 сообщают об отключённом расширении; вызывающий явно выбирает последующее чтение текста или команду. Ошибки аутентификации, неверных ответов и транспорта остаются ошибками. Повторное подключение, отзыв, истечение задания или изменение поколения хоста делают старые операции недействительными. Задания сохраняются в памяти 15 минут после последнего события конечного задания. Отменённые задания могут оставлять зарегистрированный частичный вывод инструмента; проверяйте конечное состояние задания для подтверждения успеха. Здесь описаны стандартные API живых/исходных данных. Отдельный API сохранённых результатов ниже сохраняет байты между перезапусками.
Запустите npm run example:artifacts для реальной передачи 2 MiB с прерыванием, повторным подключением и возобновлением только суффикса; npm run benchmark:artifacts использует 8 MiB. Локальный запуск Windows передал 8388625 байтов в 129 запросах частей, возобновив префикс 65536 байтов и проверив итоговый SHA-256. Base64 добавляет накладные расходы; тела ответов JSON составили 11257419 байтов. Эта передача с ограниченной памятью сохраняет байты файла и использует base64 для транспорта. Смотрите Бинарные артефакты для полного контракта. Используйте автономные хост/клиент SDK для этого процесса передачи.
Постоянные задания, история и явный повтор
SDK 0.8.0 добавляет необязательные постоянные хранилища в принадлежащем оператору каталоге вне рабочей области. Задайте абсолютные пути, стабильный ID рабочей области, проверенный код плагина, SHA-256 пакета, токен и уведомление. Пример также включает сохранение байтов файлов; исключите artifacts из jobStorage для сохранения только метаданных заданий. Существующие ответы v1 и стандартное хранение только в памяти остаются совместимыми.
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},
});
Провайдер запускается только после сохранения начального намерения. Последующие контрольные точки объединяются; flushJobStore() ждёт запрошенные контрольные точки, а не завершение команды. Восстановление отделяет текущее подключение от исходной области выполнения и сообщает live, completed, interrupted, expired, missing, corrupt или unsupported. Прерванное задание никогда не перезапускается автоматически; его unrecordedTail неизвестен.
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()});
История фильтрует состояние, результат восстановления, команду, время начала и родительскую попытку. Страницы содержат до 32 записей, упорядоченных по убыванию времени начала, затем ID задания. Курсор фиксирует состав на 60 секунд и требует того же запроса; новые задания исключены, удалённые или неавторизованные записи пропускаются, истечение сообщается. Перезапуск теряет курсоры. artifactCount, snapshotCount и resultAvailability описывают зарегистрированные ссылки, а не актуальное подтверждение файлов.
Явный повтор требует нового ID задания, нового проверенного ввода, того же актуально одобренного пакета и доступной команды. attemptOf связывает новый запуск с неизменённым родителем. Повторение того же ID, ввода, родителя и тайм-аута получает сохранённую попытку без нового выполнения, в том числе после перезапуска. Отсутствующие/истёкшие записи не дают этой гарантии. Принятое выполнение может продолжаться после отмены ожидающего запроса; запросите новый ID задания перед решением о повторе.
Стандартное хранение исключает сырой ввод, тела результатов, текст прогресса и метки артефактов; журналы очищаются от чувствительных данных. Только явный детерминированный очиститель хоста сохраняет проверенный текст. Токены, секреты и прежнее согласие никогда не восстанавливаются. Текущая идентичность рабочей области/плагина, разрешение чтения и каждое зарегистрированное разрешение проверяются вновь. Метаданные заданий по умолчанию ограничены 256 записями, 64 MiB и 24 часами, максимум — семь дней. Удаление и очистка устаревшего — явные операции хоста.
Локальное хранилище имеет одного писателя, проверяет идентичность рабочей области/корня и целостность метаданных. Явное восстановление устаревшей блокировки освобождает только доказанно мёртвый PID той же машины. Неизвестные/повреждённые файлы требуют проверки. В Windows синхронизация файлов и переименование поддерживают восстановление после перезапуска процесса; отдельно проверьте поведение при потере питания для целевой файловой системы. Смотрите Хранение заданий, История и пример постоянных заданий.
Сохранённые результаты и скачивание после перезапуска
При включённом хранилище артефактов await job.addArtifact() или job.addBinaryArtifact() копирует и проверяет полный файл перед регистрацией. Текст остаётся ограниченным 256 KiB; бинарные файлы — максимум 1 GiB. Исходный поток и фактический промежуточный файл проверяются SHA-256. Отмена, заполнение диска, изменение и частичная запись не публикуют пригодные результаты. Файлы, опубликованные до сбоя, но не зарегистрированные заданием, могут оставаться для проверки оператором.
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);
Список отделяет ссылки на исходники от метаданных снимков и сообщает retained, expired, missing, corrupt или unsupported. retained — статус метаданных; getStoredJobArtifact() проверяет метаданные и весь сохранённый файл перед возвратом новой ссылки текущего поколения. Каждое чтение вновь проверяет текущие полномочия и идентичность файла. Удаление исходников не влияет на сохранённые байты, а отсутствующие снимки никогда не заменяются изменяемым исходником. Для текстовых снимков вызовите client.readStoredJobArtifactText(textReference).
После перезапуска подключитесь с текущими разрешениями и получите новую ссылку. ID снимка, ID хранилища и дайджест остаются стабильными; старое поколение отклоняется. resume: true вновь проверяет сохранённый префикс .dds-part относительно снимка, проверяет части и весь промежуточный файл и публикует без перезаписи назначения. Чтение требует сохранённых метаданных задания вместе с байтами файлов. Браузерные потребители частей обязаны проверить полный дайджест; адаптер Worker ниже обеспечивает явное возобновление на диске браузера.
Хранилище артефактов по умолчанию ограничено 256 файлами, 256 MiB и 24 часами; общий максимум — 4 GiB и семь дней хранения. Части — максимум 64 KiB, с четырьмя одновременными чтениями. inspect() сообщает использование, сроки истечения, неверные записи и сироты. remove(snapshot) и prune() — явные операции оператора. Активные задания и отдельные чтения закреплены; истечение или удаление между частями может остановить следующее чтение. Необязательная очистка сирот удаляет только распознанные файлы с одной ссылкой. Повреждённые или неоднозначные записи требуют проверки.
Хранение файлов сохраняет фактические байты проекта независимо от очистки журналов. Выбирайте его осознанно. Текущий плагин/команда, хеш пакета, рабочая область и записанные разрешения остаются обязательными после перезапуска. Завершите обслуживание, затем последовательно ожидайте server.close(), artifacts.close() и store.close(). Используйте эти API хранения и завершения работы в явно настроенном автономном хосте SDK.
Запустите npm run example:stored-artifacts для реального перезапуска дочернего процесса, удаления исходника, проверенного возобновления частичного скачивания, истории и явного повтора. npm run example:durable-jobs также охватывает принудительное завершение процесса. Смотрите Сохранённые результаты. Известные хосты 0.7 и старше сообщают об отключённом хранении без неизвестных пробных запросов. Существующие API живых/исходных данных сохраняют исходное поведение.
Наблюдение за проектом
Оператор явно включает проекты и выбирает разрешённые корни на сервере. По умолчанию отключено. Известные хосты SDK 0.3–0.8 сообщают недоступность без нового запроса обнаружения. Поддерживаемый профиль файловой системы — локальное хранилище Windows/Linux. Этот пример автономного SDK использует явно настроенные хост/клиент.
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();Первое событие — полный снимок. Последующие изменения несут дельты относительно предыдущей ревизии; потерянные подсказки, изменения во время начального сканирования, неполное сканирование и переполнение при медленном потребителе создают полное представление повторной синхронизации с причиной. Переименования могут выглядеть как удаление/создание. Каждый файл проверяется отдельно. Ревизии снимка описывают опрошенные состояния файлов, а промежуточные записи могут объединяться между опросами.
Сервер и клиент допускают по четыре подписки, с четырьмя событиями в очереди каждой нативной подписки. Стандартная аренда при бездействии — 30 секунд; последующее чтение может вернуть not_found. После долгой паузы создайте новый итератор для начального снимка. break/return, отмена и освобождение ресурсов освобождают подписки; если разорванное подключение мешает очистке, оставшиеся удалённые ресурсы истекают вместе с арендой.
Стандартные ограничения сканирования: глубина 8, 512 записей, 1 MiB на файл, 16 MiB всего и 10 секунд. Настраиваемые максимумы: глубина 32, 1000 записей, 16 MiB на файл, 64 MiB всего и 30 секунд. Ограниченные файлы могут содержать метаданные без хеша содержимого; проверяйте complete и reasons. Сроки проверяются между вызовами файловой системы; используйте для них осознанно выбранный доступ ОС процесса хоста.
Дерево проекта и поиск
listTree возвращает дерево, searchFiles ищет относительные имена файлов по буквальной подстроке или ограниченному glob, а searchText ищет буквальный текст в файлах UTF-8. root обязателен; include/exclude задаются относительно него. Используйте поддерживаемые режимы буквального поиска и ограниченного glob. Поиск без учёта регистра преобразует только ASCII A–Z, сохраняя исходные позиции UTF-16.
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);Текстовые совпадения содержат SHA-256 содержимого, диапазон UTF-16 с нуля и ограниченный фрагмент. Курсор фиксирует исходный состав максимум на 60 секунд и требует того же запроса. Последующие страницы вновь проверяют текущее содержимое и помечают элементы current, changed, missing или unverified; новые файлы появляются только в новом запросе. Зафиксированные совпадение и ревизия неизменны.
Текстовые файлы ограничены 256 KiB, запросы — 256 единицами UTF-16, фрагменты — 512 единицами. По умолчанию: 256 результатов (максимум 512), 32 элемента на страницу (максимум 64) и ответ 64 KiB (максимум 128 KiB). Бинарные файлы, неверный UTF-8 и ограничения байтов/глубины/времени/ответа сообщаются как неполные результаты с причинами. Допускаются два одновременных запроса и восемь сохранённых курсорных представлений; явно освобождайте неиспользуемые курсоры.
Черновики проекта и повторное подключение
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();Когда snapshotRevision запроса отличается от наблюдаемого snapshot.revision, освободите старый курсор и повторите запрос с теми же корнем/фильтром. Наблюдение никогда не изменяет edit.snapshot или принадлежащий вызывающему черновик. После внешнего изменения, перемещения или удаления исходное условие CAS сообщает конфликт; вызывающий выбирает явную перезагрузку, объединение или отдельное сохранение.
Клиент проверяет поколение подключения, корень/фильтр, хеш запроса, позиции страниц, SHA-256 снимка и непрерывность событий. Поздние ответы отбрасываются после отзыва, отключения или повторного подключения. Курсоры наблюдения и запросов отдельны и автоматически не восстанавливаются. server.revokeProjects() завершает доступ к проектам; повторное включение требует нового поколения сервера.
npm run example:project-watch
npm run example:project-query
npm run example:project-tools
npm run example:project-browserУстановленные примеры Node проверяют создание, поиск, внешние изменения, сохранённые черновики, конфликты CAS и повторное подключение. Для браузерного примера откройте выведенный loopback URL и выберите «Запустить сценарий». Он использует только свою временную рабочую область, удаляемую при остановке сервера примера. HTTP-запросы по умолчанию имеют срок пять секунд; для более крупных сканирований осознанно настройте тайм-ауты клиента и сервера.
Наблюдение за проектом · Контракты дерева/поиска · HTTP-инструменты проектов
Потоковая передача и проверка браузерных артефактов
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);Безопасный для браузера помощник принимает не более одной части 64 KiB за раз, ожидает выбранный приёмник и последовательно хеширует весь файл. Перед записью он проверяет точные диапазоны, идентичность, base64 и хеш каждой части. Затем приёмник с обратным чтением независимо перечитывает сохранённые байты; статус stored выставляется только после совпадения обоих полных хешей. Без обратного чтения статус проверки — received, а storedSha256 равен null. Достижение прогрессом всех байтов не означает завершения.
Приложение выбирает дескрипторы файлов или каталоги OPFS и предоставляет необходимые разрешения. Передайте выбранное назначение и разрешения доступа адаптерам SDK; приложение управляет диалогом выбора и выбором назначения. Асинхронные записывающие приёмники файлов/OPFS удерживают промежуточные данные до close и отбрасывают их при сбое до фиксации. Для частичных данных, переживающих перезагрузку, используйте специальный адаптер Worker ниже. Ограничения: 1 GiB на файл, четыре прямых одновременных потока и общий срок 30 минут.
Загрузка выбранных файлов
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.Загрузки по умолчанию отключены. Оператор настраивает локальную рабочую область Node, изолированный промежуточный каталог, разрешённые корни и одного субъекта, затем предоставляет выбранному плагину workspace.write с точной фиксацией архива. Помощник заранее хеширует выбранный исходник. Сервер принимает последовательные части 64 KiB, проверяет дубликаты и полное содержимое и фиксирует только после условных проверок назначения. Промежуточные байты не появляются в обычных списках рабочей области.
expectedRevision: null требует отсутствующего назначения; SHA-256 требует совпадающего текущего назначения. Отмена сохраняет подтверждённый серверный префикс. Новая явная операция recover запрашивает текущие полномочия, проверяет тот же исходник/спецификацию и возобновляет только совпадающий префикс. Потерянный ответ commit остаётся неопределённым до запроса; это не разрешение повторить commit или откатить файл. Максимумы: 1 GiB на файл, 4 GiB на хранилище и четыре активных сеанса; значения по умолчанию ниже. Известные хосты 0.3–0.9 сообщают об отключённых загрузках без проб новых методов.
Планирование передач файлов
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();Очередь, принадлежащая вызывающему, смешивает задания загрузки, живого скачивания и скачивания сохранённого. Она ограничивает сохранённые задания (32), одновременные стадии (4), параллельность подключений клиента, резервирование декодированных частей (64–256 KiB), скорость и повторы. Допустимая работа проходит мимо насыщенного подключения, а ограниченное преимущество приоритетных заданий не даёт малым допустимым заданиям ждать бесконечно. Приостановленное задание завершает текущую стадию, затем ждёт; пауза может удерживать блокировку хранилища. Общие сроки включают ожидание в очереди и паузу.
Автоматический повтор ограничен распознанными SDK ошибками 429/503, потерей сети или тайм-аутом запроса во время идемпотентной операции точной части, с ограниченными задержкой и случайным разбросом. Обрабатывайте сбои begin/commit, авторизации, контрольной суммы, диапазона, исходника или приёмника явно. acknowledgedBytes, transferredBytes, attemptedBytes, retriedBytes, resumedBytes и remainingBytes отдельны; только проверенная квитанция даёт completed. cancel/dispose останавливают оставшуюся работу, а уже зафиксированные файлы сохраняют свои байты.
Возобновление браузерных скачиваний
// 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.Постоянное восстановление требует отдельного Worker, синхронного доступа OPFS и Web Locks. После перезагрузки вызывающий вновь выбирает каталог и UUID частичного файла и получает новую одобренную сохранённую ссылку. Приёмник сохраняет два точных имени файлов данных/метаданных, полную неизменяемую идентичность снимка, срок истечения и хеши текущего/предыдущего префикса. Он не хранит токен, разрешения или старую область подключения. Каждая часть данных сбрасывается на диск перед закрытием малого потока метаданных.
Приёмник и помощник независимо повторно хешируют префикс. Хвост без контрольной точки обрезается только после совпадения записанного префикса. Метаданные за фактическим размером файла могут вернуться к предыдущей контрольной точке лишь при совпадении её байтов и хеша; повреждение, отсутствие записей, истечение или другой снимок дают ошибку без молчаливого перезапуска. Исключительная блокировка всего origin отклоняет другую вкладку, удерживается во время обратного чтения и освобождается при close или завершении Worker. Повторное открытие затем требует явного восстановления.
Локальные метаданные ограничены 16 KiB и четырьмя открытыми сеансами приёмника. Хранение по умолчанию — один час, максимум 24 часа, ограниченный истечением снимка хоста. Хранение подчиняется квоте, вытеснению и полномочиям скриптов одного origin в браузере. Модель восстановления контрольных точек охватывает проверенные ниже сценарии прерывания процесса; проверьте поведение при потере питания в среде развёртывания. Chromium 154 в Windows проверялся на отмену, перезагрузку, перезапуск хоста, конфликт двух вкладок и завершение вкладки-владельца с полными хешами сохранённого файла. Выполните квалификационные сценарии на каждом целевом сочетании браузера/ОС.
npm run example:browser-artifacts
npm run example:uploads-browser
npm run example:transfer-queue-browser
npm run example:browser-resumeПотоковая передача · Загрузки · Очередь передач · Восстановление Worker
Подсказки сигнатур и помощь автодополнения
Объявляйте signature-help, completion-resolve и completion-snippets по необходимости в манифесте v2; модификаторы автодополнения также требуют completion. Хост должен предоставить document.read и language.provide. Существующие буквальные дополнения остаются допустимыми. languageCapabilities() сообщает реализацию SDK и её ограничения, не предоставляя разрешения.
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);Приложение предоставляет текущие позицию и хост; подготовка возвращает данные без записи документа или файла. Подсказки сигнатур поддерживают до 16 сигнатур, по 64 параметра и смещения меток параметров UTF-16. Разрешение автодополнения сохраняет приватность данных провайдера, возвращает одноразовый токен хоста и фиксирует выбранные метку/вставку/диапазон. Токены связывают провайдера, область и документ, истекают через 60 секунд и ограничены 128 записями, 4 MiB и четырьмя фактическими операциями разрешения. Изменения документа/провайдера их отбрасывают.
Сниппеты поддерживают $n, ${n}, ${n:literal}, $0 и документированные экранирования с зеркалами и упорядоченными точками перехода Tab. Переменные, вложение, варианты, преобразования и исполняемые команды отклоняются. Проверяются границы UTF-16/CRLF и перекрывающиеся дополнительные изменения. Провайдеры выполняются как доверенный код внутри процесса с полномочиями процесса хоста; проигнорированная отмена удерживает фактически ожидающий слот до завершения провайдера.
Проверяемые изменения рабочей области и переименование
prepare-rename возвращает проверенный диапазон/заполнитель или null; rename возвращает предложение WorkspaceEdit или null. Предложения поддерживают редактирование, создание, перемещение и удаление по непересекающимся относительным путям. Проверяются текущий SHA-256 исходника, отсутствие назначения, политика защищённых путей, геометрия изменений UTF-16 и ограничения. Языковые возможности разрешают предложения; клиент рабочей области обеспечивает отдельно одобренный доступ к файлам и изменения.
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);Вызывающий использует подключённый авторизованный клиент рабочей области и доверенный журнал. Предпросмотр содержит полные снимки до/после и дайджест; apply требует проверенных planId/digest и текущей политики хоста, возвращающей true. Каждый файл предварительно проверяется, затем каждая операция использует существующий CAS на файл и текущие возможности записи/управления. Журнал сохраняет и перечитывает намерение до каждого изменения и квитанцию после него. Конфликт или неопределённость прекращает дальнейшую запись; каждый файл сохраняет собственную границу транзакции CAS.
Необязательный адаптер workspace-edits-node хранит ограниченный журнал вне выбранной рабочей области, связывает её идентичность и использует блокировку одного писателя, обычные файлы и контрольные точки с контрольными суммами. После завершения процесса recoverStaleLock выбирается явно и освобождает только доказанно мёртвого владельца. Восстановление сообщает applied/not-applied/conflicted/unknown по текущим байтам; вызывающий явно определяет последующие действия. Компенсация создаёт новое обратное предложение для новой проверки. В Windows адаптер синхронизирует файлы и выполняет операции переименования; проверки охватывают завершение и восстановление процесса, а сохранность определяется файловой системой и устройством хранения. Ограничения: 32 изменения, 1000 правок, 256 KiB на файл, предпросмотр 8 MiB и 64 сохранённых плана журнала.
Форматирование и диагностические действия с кодом
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 и format-range требуют путь и параметры tabSize/insertSpaces; только форматирование диапазона принимает выделение. Результат — null или ровно одно изменение текущего файла с хешем текущего снимка. Изменения диапазона остаются в выделении. endOfLine выбирает preserve, lf или crlf для вставляемого текста; неизменённые байты сохраняются. Предложения с идентичным содержимым нормализуются в null. prepareFormatting не выполняет запись.
Хост связывает запросы действий и токены разрешения с принятой ревизией диагностики и текущим снимком. Позднейшая публикация диагностики, изменение документа или освобождение провайдера делает старые выборы недействительными. Диагностические вызовы не по порядку не перезаписывают более новый принятый набор. До 100 действий содержат обычные метки, ограниченные индексы диагностики, предлагаемые изменения, приватные данные разрешения или причину отключения. Неизвестные поля command/URL/shell отклоняются. Изменения действий могут выходить за выделение, поэтому проверяйте всё предложение; форматирование и действия никогда не одобряют собственную запись.
Семантическое отображение, сворачивание, подсказки и символы
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);Семантические токены используют легенду с уникальными именами и девятью принадлежащими хосту ключами стиля, плюс пять целых на токен: дельта строки/начала, длина UTF-16, индекс типа и биты модификатора. Токены не могут перекрываться, разделять суррогат, пересекать строку или выходить из текущего документа. Хост всегда возвращает полный нормализованный массив и UUID хоста с updateKind full/delta/fallback. Отдельная возможность semantic-tokens-delta включает provideDelta относительно прежних данных провайдера; кеш хранит идентичность и данные токенов, а не старый текст документа.
База кеша привязана к провайдеру, области, URI и языку; максимум восемь записей, 4 MiB и 60 секунд. Обычное увеличение версии документа сохраняет возможную базу дельты, делая старый результат отображения устаревшим. Потерянная/истёкшая база, null-дельта или несовпадающий ID базы провайдера допускает максимум один полный резервный запрос в исходном тайм-ауте. Неверные данные или ошибки провайдера дают отказ без повтора. Деактивация, отмена регистрации и замена документа очищают затронутые базы. Вызывайте validateLanguageResult непосредственно перед отображением; скопированный, освобождённый или устаревший объект не проходит проверку.
Ограничения: 20000 семантических токенов, 64 типа, 16 модификаторов и 64 дельта-изменения; сворачивание допускает 1000 диапазонов глубиной 32 и отклоняет пересечения. Встроенные подсказки допускают 1000 однострочных обычных меток в запрошенном диапазоне. Иерархические символы допускают всего 1000 записей и 16 уровней с вложенными детьми/выделениями и упорядоченными неперекрывающимися соседями. Исходный плоский контракт document-symbols неизменен. Браузерный пример проверяет full/delta/fallback, сворачивание, навигацию и жизненный цикл; HTML-подобная подсказка остаётся буквальным текстом.
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Помощь · Проверяемые изменения · Форматирование/действия · Отображение
Типизированные настройки и ссылки на секреты
Модуль /settings предоставляет принадлежащее оператору хранилище в памяти для одного плагина. Версионированное определение объявляет каждый ключ, схему данных, значение по умолчанию, разрешённые области пользователя/рабочей области и метаданные отображения. Действующие значения заменяют каждый ключ целиком в порядке default < user < workspace. read(workspaceId) возвращает неизменяемые значения, источники и ревизию всего хранилища. Вложенные объекты рекурсивно не объединяются; отсутствующее значение без значения по умолчанию остаётся отсутствующим.
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}, ...}).Запись проверяет всю транзакцию и использует CAS expectedRevision. reset удаляет ключ из одного слоя; readOnly требует значения по умолчанию и отсутствия записываемых областей. Подписки объединяют синхронные изменения и возвращают освобождаемые дескрипторы. Явный migrate(nextDefinition, callback, options) проверяет следующее состояние и фиксирует только при всё ещё совпадающей ревизии. Ошибка, отмена или тайм-аут сохраняют старое определение и состояние. Экспорт/импорт — обычные данные; сохранением и шифрованием управляет оператор. Ограничения: 64 ключа, 32 слоя рабочих областей, 1 MiB экспортируемого состояния и одна фактическая миграция.
Плагины рабочей области объявляют settings и settings.read, а оператор подключает соответствующее хранилище с этим разрешением. context.settings доступен только для чтения и привязан к плагину и выбранной рабочей области. Резолвер /secrets отдельно выдаёт непрозрачные ссылки для плагина, рабочей области, разрешённого списка команд и времени жизни. Манифест должен объявить secrets.resolve, а хост — предоставить его. Поля ввода используют type: object с format: dds-secret-reference; обычные строки и похожие объекты не дают полномочий доступа к секрету.
Только ссылки в проверенном вводе доступны через options.secrets.withSecret команды. Каждое выполнение имеет новый ID; резолвер проверяет область, истечение, отзыв и текущую авторизацию вокруг разрешения ссылки и обратного вызова. Обратный вызов возвращает undefined и получает копию, очищаемую при прерывании и каждом выходе. Ошибки провайдера очищаются от чувствительных данных. Получайте аренду до эффектов, требующих этих полномочий. Время жизни ссылки по умолчанию — 60 секунд, максимум один час; ограничения: 128 ссылок, 8 фактических аренд и 16 KiB материала. Выполняйте только доверенный код с полномочиями процесса хоста, поскольку он может сохранять копии. Никогда не помещайте материал в настройки, наборы, журналы или результаты; явно классифицируйте произвольные строки приложения при работе с секретами.
Структурированные схемы команд и формы
Команды могут объявлять inputSchema и outputSchema в оболочке schemaVersion: 1. Существующие примитивные параметры поддерживаются; совместное объявление parameters и inputSchema отклоняется. Хост проверяет и применяет значения ввода по умолчанию перед запуском обработчика или задания, затем проверяет вывод перед публикацией успеха. Значения вывода по умолчанию никогда не применяются. Новые метаданные схем/отображения требуют партнёра с поддержкой 0.12; старые строгие валидаторы отклоняют их, а прежние определения сохраняют поведение.
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);Ограниченное подмножество поддерживает закрытые объекты, массивы, строки, конечные числа, безопасные целые, булевы значения, null, примитивные перечисления, границы и проверенные значения по умолчанию. Неизвестные ключевые слова, удалённые ссылки, regex, объединения, приведение типов, аксессоры и пользовательские прототипы отклоняются. Схемы допускают 32 KiB, глубину 8 и 128 узлов; значения — 64 KiB. Полная команда сохраняет бюджет метаданных 16 KiB. Локальный DataValidationError предоставляет code, reason и известные пути полей вроде /input/options/names/0; HTTP и ошибки заданий выдают безопасные коды без отклонённых значений.
describeDataForm возвращает пути, типы, варианты, значения по умолчанию, признаки обязательности и подсказки ссылок на секреты. Общие метаданные отображения содержат буквальные label/help/order и имена доступности, описания и подсказки клавиатуры. Отображением и взаимодействием управляет хост. Эти схемы описывают буквальные данные для отображения под управлением хоста и явного взаимодействия.
Локализация и метаданные доступности
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.Каталоги используют канонические базовые теги BCP 47 и явные ациклические связи резервного выбора. До восьми предпочтений согласуют точные теги, затем предков и значение по умолчанию. Локаль по умолчанию определяет все ключи; переводы могут пропускать ключи, но не добавлять новые. Поиск каждого ключа следует упорядоченным резервным связям, затем локали по умолчанию. Каждый перевод и его аргументы должны совпадать с точным набором заполнителей {name}. Это буквальная интерполяция без выражений ICU. resolveMessage сообщает фактическую исходную локаль и направление, поэтому английский резервный текст внутри страницы RTL может сохранять lang=en и dir=ltr.
Форматирование чисел поддерживает десятичные числа/проценты; форматирование дат использует явную эпоху и UTC по умолчанию; выбор множественного числа возвращает категорию Intl cardinal/ordinal для выбора сообщения вызывающим. Данные и поддержку Intl обеспечивает хост. validateLocalizedSurfaces проверяет ключи manifest/command/settings/schema и сопутствующие данные отображения тем, включая итоговые длины отображения и отсутствующие переводы. JSON/XML тем остаётся совместимым. Ограничения каталогов: 32 локали, 256 ключей и 256 KiB; статические метки не могут содержать заполнители.
Помощники /accessibility сообщают отсутствующие имена, повторяющиеся нормализованные сочетания клавиш и явный контраст непрозрачных пар цветов в светлых/тёмных темах. Используйте эти подсказки при реализации привязок клавиш ОС под управлением хоста и оценке доступности. Независимый пример включает EN/KO, частичный арабский и тестовые данные длинных меток. Он проверяет настройки с областью действия, запрещённые/отозванные ссылки, неверные поля, Ctrl+Enter и смену языка во время ожидающей команды. Браузерная раскладка проверена в настольных/мобильных размерах со светлыми/тёмными темами.
npm run example:configuration
npm run example:configuration-browserНастройки · Ссылки на секреты · Схемы команд · Локализация
Шаблоны разработки и генерация
Шесть шаблонов, точные зависимости архивов, проверка генерации, сохранение конфликтов и проверки doctor.
Полные контракты, примеры и ограничения
Детерминированное тестирование и воспроизведение
Явные синтетические тестовые данные, виртуальное время, сбои, ограниченные трассы только с хешами и очистка ресурсов.
Полные контракты, примеры и ограничения
Локальная диагностика и отладка
Добровольно включаемые локальные профили и доверенный дочерний отладчик с временной loopback-точкой и общим сроком.
Полные контракты, примеры и ограничения
Соответствие хоста
18 версионированных профилей различают поддерживаемые, неподдерживаемые и нарушенные контракты; собственные адаптеры сохраняют явные полномочия.
Полные контракты, примеры и ограничения
Поддержка SDK и миграция
Смотрите перечень экспортов, политику стабильных/необязательных/экспериментальных функций, точные peer-зависимости, сроки сред выполнения и примеры миграции.
Полные контракты, примеры и ограничения
Приёмка релиза
Опубликованные проверки релиза объединяют нагрузки со сбоями и измеренные ограничения производительности для проверки испытанного поведения SDK.
Полные контракты, примеры и ограничения
1.1 Инструменты зависимостей, происхождения и обновления
Версия 1.1.0 добавляет детерминированные автономные наборы проверенных зависимостей, CycloneDX SBOM, отделённые подписи с ключами Ed25519 оператора, привязанные к дайджесту одобрение/активацию/откат и явное сравнение с upstream. Пять точек входа только для Node включают объявления, схемы и независимые примеры. Хосты явно разрешают выполнение, а старые задания сохраняют исходный хеш. Операторы управляют распространением, развёртыванием и мониторингом. Используйте независимые примеры для проверки контрактов наборов, подписей, обновлений и upstream.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsПолное руководство по наборам, подписям, обновлениям и upstream
1.2 Рабочие процессы, кеш, потоки инструментов и LSP
Версия 1.2.0 добавляет проверяемые DAG команд с заданиями/разрешениями на шаг, постоянными контрольными точками и явным восстановлением новой попыткой; детерминированный кеш по содержимому и инкрементальное выполнение; ограниченные потоки инструментов UTF-8/JSONL/текста; необязательный мост stdio LSP 3.17. Семь новых точек входа доводят пакет до 50 экспортов и 107 схем с объявлениями и независимыми установленными примерами, без runtime-зависимостей npm. Парсер потоков инструментов работает и в браузере; рабочие процессы, хранилища, внешние процессы и LSP требуют Node. Реальные адаптеры проверялись с TypeScript 5.9.3 и language-server 5.3.0, при этом мост требует версионной диагностики LSP. Операторы явно инициируют восстановление и настраивают интеграцию сервиса или продукта. Эти проверки адаптеров подтверждают испытанное поведение автономного SDK.
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Полное руководство по рабочим процессам, кешу, инструментам и LSP