Разработка и выпуски Plugin SDK
Разработка, проверка, инструменты выпуска и рабочие процессы 1.2, инкрементальный кэш, внешние инструменты и публичный мост LSP.
Рекомендации по разработке, проверке и выпуску DDS Plugin SDK 1.2.0. Аудит безопасности и проверка уязвимостей ожидают выполнения; стабильность API и функциональные проверки не означают подтверждения безопасности.
Установка SDK и руководство по API
Шаблоны разработки и генерация
Выберите command, language, theme, job, browser или configuration. init --dry-run сообщает каталог назначения, перечень файлов, хэши и конфликты, не записывая и не устанавливая ничего. Обычный init требует нового реального каталога. Каждый шаблон включает исходный код, манифест, сведения о поведении, лицензию и уведомления, тесты, типизированный пример использования и исполняемый пример. Шаблоны browser и configuration содержат демонстрацию через loopback. Генерируемые зависимости закрепляют точный архив GitHub.
npx --no-install dds-plugin init example-plugin --template configuration --dry-run
npx --no-install dds-plugin init example-plugin --template configuration
cd example-plugin
npm install --ignore-scripts
npm run doctor
npm test
npm run typecheck
npm run example
npm run browserdds-dev.json — ограниченные JSON-данные для схем команд, настроек, каталогов локализации и тем. generate создает JSON для выполнения, экспорты ESM, исходные и проверенные входные типы TypeScript, типы выходных данных и настроек, JSON Schema и XML темы. Значения по умолчанию в JSON Schema — аннотации; применяет их только проверка входных данных SDK. Генерация не импортирует ваш плагин. doctor проверяет расхождения, метаданные, отсутствующие модули и включение генерируемых файлов выполнения в разрешенный перечень пакета.
npx --no-install dds-plugin generate . --check
npx --no-install dds-plugin generate . --dry-run
# Review the new files, then use the previous digest from the report:
npx --no-install dds-plugin generate . --expected-digest <previous-digest>Для замены нужны точный предыдущий дайджест и неизмененные байты генерируемых файлов. Ручные правки, дополнительные файлы, ссылки и устаревшие блокировки останавливают замену. При сбое удаляются только неизмененные элементы, принадлежащие этой попытке; измененные элементы и элементы с неопределенным состоянием сохраняются для проверки. Ограничения: 256 файлов, 1 МиБ каждый и 4 МиБ всего. Блокировка координирует взаимодействующие генераторы; она не защищает от враждебного параллельного процесса записи в файловую систему и не обеспечивает атомарную транзакцию между каталогами. Проприетарные шаблоны требуют условий, предоставленных вызывающей стороной, и сохраняют унаследованные файлы лицензии и уведомлений SDK.
Детерминированное тестирование и воспроизведение
createScenarioHost из /testing явно подключает выбранные тестовые объекты файлов в памяти, бэкенда, настроек, секретов и заданий. Начальное состояние не содержит разрешений и возможностей. createTestClock предоставляет идентификаторы с заданным seed, время и таймеры без подмены глобальных объектов; таймеры на одинаковое время сохраняют порядок добавления. Дождитесь продвижения часов, чтобы разблокировать виртуальное ожидание. Генерируемые UUID — тестовые данные, а не криптографическая энтропия. Существующие значения по умолчанию createTestHost остаются совместимыми.
import {createScenarioHost} from '@altifigence/dds-plugin-sdk/testing';
const scenario = createScenarioHost({seed: 7, start: 1000,
files: {'example.txt': 'synthetic'}, grants: ['workspace.read'],
});
try {
// Activate your explicitly imported test plugin on scenario.host.
scenario.faults.enqueue({operation: 'file.read', kind: 'delay', delayMs: 25});
// Start its command, then await scenario.clock.advance(25).
} finally {
await scenario.dispose();
scenario.assertClean();
}Порты сбоев моделируют задержки, отказы, разрывы соединений, повреждение, исчерпание ресурсов и потерянные вызовы; тестовые события можно пропускать, дублировать и разворачивать, не повторяя внешних эффектов. replaceGrants деактивирует плагины, теряющие полномочия. Снимки заданий в памяти проверяют идентичность, ревизию и хэши и моделируют восстановление после прерывания без автоматического выполнения. Эти тестовые объекты не эмулируют надежность хранения файловой системы и не обнаруживают дескрипторы ОС. Отдельный реестр владельца отслеживает явно зарегистрированные ресурсы. Очистка сохраняет счетчики ожидающих завершения обратных вызовов, игнорирующих отмену, до их фактического завершения. Просмотр настроек теперь доступен после освобождения объекта; чтение данных по-прежнему отклоняется.
Запись требует synthetic: true и явного ограниченного перечня тестовых объектов. Экспортируемые трассы содержат только типы операций, идентификаторы тестовых объектов, временные данные, seed и версию, а также цепочку хэшей. Используйте нечувствительные идентификаторы: хэши не обезличивают угадываемые данные, и SDK не может распознать произвольный ввод как синтетический. Чистое воспроизведение проверяет порядок, хэши и идентичность тестовых объектов и возвращает выбранные тестовые результаты; обратные вызовы с побочными эффектами оно не принимает. Ограничения: 64 тестовых объекта, 1 024 события и трасса размером 1 МиБ. Запустите поставляемый пример development-tools для проверки сбоев, восстановления, конфиденциальности и очистки.
Локальная диагностика и отладка
import {createDiagnosticSession, profileHost}
from '@altifigence/dds-plugin-sdk/diagnostics';
const session = createDiagnosticSession({enabled: true, sampleEvery: 10});
const measured = profileHost(host, session);
try {
await measured.executeCommand('example', 'run', {});
} finally {
measured.dispose();
console.log(session.snapshot());
session.dispose();
}Диагностика по умолчанию отключена и работает только локально. Отчеты содержат фиксированные коды операций, состояний и ошибок, идентификаторы корреляции, длительности и счетчики ресурсов; API для тел документов, путей, входных данных, тел результатов или произвольного текста исключений нет. Число байтов, глубина очереди и показатели памяти — явные оценки владельца. profileTransport измеряет время до завершения обернутого вызова: для fetch это получение заголовков ответа, а не завершение чтения тела. Завершенные записи хранятся в ограниченном кольцевом буфере с пассивным истечением срока; фоновых диагностических таймеров и отправки отчетов нет. По умолчанию: 128 событий и 60 секунд; максимум: 256 событий и 5 минут, 64 незавершенных интервала и 256 КиБ на отчет.
npx --no-install dds-plugin dev . --trust-local-code --profile --command greet --input '{"name":"Ada"}'
npx --no-install dds-plugin dev . --trust-local-code --debug --debug-wait --timeout-ms 30000 --command greet --input '{"name":"Ada"}'Режим отладки открывает только временный инспектор 127.0.0.1 в принадлежащем инструменту дочернем процессе. --debug-wait приостанавливает выполнение до импорта плагина и требует --debug. Общий лимит времени включает ожидание отладчика и не превышает 30 секунд. Завершение, отмена и тайм-аут прекращают работу дочернего процесса и инспектора. И профилирование, и отладка требуют явного доверия к локальному коду; ни одно из них не является песочницей. При аварии или принудительном завершении отчет профилирования может отсутствовать, а необработанные stdout/stderr плагина остаются отдельным ограниченным потоком без автоматического удаления чувствительных данных.
Инструменты разработки · Тестирование · Диагностика · Совместимость
Соответствие хоста
Модуль /conformance запускает версионированные синтетические проверки для явно предоставленных адаптеров хоста, настроек, рабочего пространства, локализации, тестирования, диагностики и разработки. Он различает поддерживаемые, неподдерживаемые и не прошедшие проверку профили и включает хост, версию, среду выполнения, платформу, идентификатор проверки, временные данные и очистку. Заявленная функция с отсутствующим или неисправным адаптером не проходит проверку; неизвестные необязательные функции регистрируются без проверки. По умолчанию обязательны команды, разрешения и отмена.
import {runConformance, formatConformanceReport}
from '@altifigence/dds-plugin-sdk/conformance';
import {createPluginHost} from '@altifigence/dds-plugin-sdk';
const report = await runConformance({
identity: {host: 'My host', version: '1.0.0', runtime: 'Node 24', platform: 'linux-x64'},
features: ['commands', 'permissions', 'cancellation'],
adapters: {host: options => createPluginHost(options)},
});
console.log(formatConformanceReport(report));Замените фабрику хоста своим адаптером и также запустите тесты плагина. Вспомогательный модуль Node /conformance-node создает только новые временные тестовые объекты и временные loopback-серверы. Пример для браузера запускает доступные браузерные профили и отмечает отсутствующие функции Node как неподдерживаемые. Быстрые проверки выборочно проверяют контракты; связанные примеры и тесты выпуска охватывают более широкие сценарии языков, восстановления и хранения. Отчет — свидетельство тестирования, а не сертификат доверия.
Лимит времени по умолчанию — 10 секунд на случай, максимум 30 секунд. Тайм-аут или отмена останавливают последующие случаи; сбой очистки означает неуспех случая, а незавершенная очистка остается непроверенной. Доверенные адаптеры внутри процесса могут синхронно блокировать работу и сохранять полномочия среды. Отчеты не включают тела ошибок провайдера, полезную нагрузку, токены и пути; выбирайте нечувствительные метки идентичности. Отчеты автоматически не отправляются.
Поддержка SDK и миграция
API_SUPPORT.json перечисляет каждый экспортируемый модуль, имя во время выполнения, декларацию, дайджест декларации, среду и стабильность. Стабильные API 1.x следуют семантическому версионированию: совместимые дополнения выходят в минорной версии, а несовместимые стабильные изменения требуют новой мажорной версии. artifact-resume-browser остается экспериментальным и требует точной версии SDK и браузера с новой приемочной проверкой в браузере. Обнаружение необязательных возможностей и действующие разрешения по-прежнему обязательны.
Политика стабильной ветки действует с 1.0.0. Последняя стабильная минорная версия получает обычные исправления; предыдущая минорная версия может получать критические исправления безопасности в течение 90 дней при использовании поддерживаемой среды выполнения. В 1.0.0 ни один стабильный API не объявлен устаревшим. Об устаревании сообщают минимум за две минорные версии и шесть месяцев до удаления в мажорной версии. RC и предварительные версии заменяются последующими выпусками. Эта политика открытого ПО не обещает коммерческих сроков ответа.
Приемочные проверки сервера и CLI охватывают Windows/Linux с обновленным Node 22 или 24 и декларации с TypeScript 5.9.3. Поддержка Node 22 заканчивается 2027-04-30, Node 24 — 2028-04-30. Подтверждения выпуска указывают точные патч-версии, образы ОС и сборку браузера. Другие среды выполнения и сочетания браузера и хранилища требуют собственных приемочных проверок. У SDK по-прежнему нет npm-зависимостей времени выполнения.
Стабильные плагины 1.0 используют >=1.0.0 <2.0.0; повышайте минимальную версию при использовании более нового API. Пакеты RC1 сохраняют точную peer-зависимость 1.0.0-rc.1. Чтобы изменить ее, выполните повторную проверку и выпустите новую версию плагина; старые архивы сохраняйте неизменными. Устаревшие архивы служат входными данными для проверки совместимости, а не поддерживаемыми ветками. После перезапуска установите новое соединение и действующие разрешения; восстановление считывает зафиксированное состояние без повторного выполнения работы.
Приемка выпуска
Аудит безопасности и проверка уязвимостей ожидают выполнения в соответствии с отсрочкой владельца от 2026-10-05. Функциональные результаты, совместимость и производительность не означают подтверждения безопасности. Отложенная проверка будет возобновлена отдельно; этот выпуск нельзя описывать как прошедший данный аудит.
Объединенный тестовый сценарий одновременно проверяет языки и настройки, проверенные правки, задания команд, наблюдение за проектом, загрузку и скачивание, а также сохраняемое хранилище. Он проверяет прерывания, некорректные ответы, отзыв полномочий, изменения поколений, восстановление и очистку ресурсов. Отдельные тесты файловой системы и процессов охватывают принудительно завершенные дочерние процессы, повреждение, неудачную запись, истечение срока и игнорирование отмены. Отчет приемки RC содержит ссылки на воспроизводимые команды и границы каждого результата.
Измерения производительности включают пять запусков в новых процессах для каждого профиля Windows/Linux и Node 22/24, медиану и разброс, процессорное время, выборочные показатели памяти, время импорта, запуска и наблюдения, а также логические объемы дисковых и HTTP-данных. Базовые пороги получены из этих измерений и служат грубой защитой от регрессий, а не SLA задержки. Они не измеряют физический дисковый трафик и не гарантируют обнаружение каждого дескриптора ОС.
npm ci --ignore-scripts
npm run check
npm run example:conformance -- --json
npm run example:combined -- --faults
npm run benchmark:combined
npm run example:conformance-browserСоответствие · Перечень API · Политика поддержки · Приемка RC
Содержимое стабильного выпуска 1.0
Исходный пакет 1.0 включает 38 экспортов и 86 схем с декларациями, примерами, LICENSE и NOTICE. Версия 1.1 добавляет инструменты выпуска, описанные ниже; 1.2 — следующие разделы о рабочих процессах, кэше, инструментах и LSP. Подтверждения выпуска различают точный исходный код, CI и дайджесты, новые проверки потребителей и повторно использованные свидетельства браузерных проверок.
Для возврата к старой версии остановите принадлежащую вам работу и явно выберите сохраненные совместимые архивы SDK и плагина и экспорт конфигурации. Проверьте действующие разрешения и создайте новое соединение. Восстановление результатов ограничивается считыванием; внешние эффекты и несовместимые настройки автоматически не отменяются. Проверяйте именно используемые форматы и необязательные функции.
Содержимое выпуска, миграция и поддержка
Офлайн-пакеты и SBOM
SDK 1.1 добавляет пять необязательных точек входа только для Node: /bundles, /provenance, /updates, /updates-node и /upstream. Пакет содержит 43 экспорта, 96 схем, декларации и запускаемые примеры без npm-зависимостей времени выполнения. Существующие API 1.0 и неподписанные архивы DDS .tgz остаются совместимыми.
lockBundleDependency закрепляет проверенное дерево файлов ESM/CommonJS за точной версией, HTTPS-источником, каноническим дайджестом файлов, картой зависимостей, LICENSE/NOTICE и явным решением о распространении. Дайджест описывает проверенное дерево, а не хэш исходного архива. createPluginBundle включает исходный архив плагина DDS и метаданные выпуска, ациклический граф зависимостей с одной версией каждого пакета и детерминированную SBOM CycloneDX 1.6.
verifyPluginBundle проверяет точный ограниченный снимок байтов. installPluginBundle требует его expectedSha256, approved: true и новый каталог внутри родительского каталога оператора. Он не запускает npm, lifecycle-скрипты, скачивание или код плагина. Зависимости не наследуют новых разрешений. SDK хоста — отдельная зависимость. Нативные дополнения, карты экспортов и произвольное разрешение npm-зависимостей не входят в этот формат.
Ограничения: 32 пакета зависимостей, 1 024 распакованных файла, 4 МиБ на файл зависимости, 32 МиБ распакованного содержимого и 48 МиБ закодированного пакета. Исходный корневой архив имеет собственные меньшие ограничения. Отклоняются отсутствующие или конфликтующие версии, циклы, зависимости без связей, измененные хэши, отсутствующие лицензии и NOTICE, недопустимые пути и ссылки, а также конфликты файлов и каталогов. При неудачной установке новый каталог сохраняется для проверки. Исключите параллельную запись; этот инструмент не является песочницей ОС.
Отдельные подписи и доверие оператора
createProvenanceStatement связывает точное имя, версию и SHA-256 пакета, издателя, ревизию исходного кода и время создания и истечения срока. signPluginProvenance использует предоставленный вызывающей стороной Ed25519 KeyObject. canonicalProvenancePayload предоставляет DDS-PROVENANCE-V1 с последующим каноническим JSON, чтобы другой подписывающий инструмент мог воспроизвести ту же полезную нагрузку. SDK не предоставляет закрытый ключ подписи или полномочия подписи продукта DDS.
verifyPluginProvenance принимает выбранные оператором корни доверия, привязки издателя и субъекта, текущее время, сведения о действии и отзыве ключей и свидетельства отзыва с временными метками. Офлайн-проверка использует предоставленные свидетельства и тот же лимит актуальности; она сама не запрашивает свежие сведения об отзыве. Новый ключ пакета не считается доверенным, пока оператор его не добавит. Явно перекрывающиеся корни поддерживают ротацию. Максимальное расхождение часов — пять минут, максимальный возраст свидетельств — 30 дней; при необходимости выбирайте более строгие пределы.
Подтверждения отдельно фиксируют контрольную сумму, подпись, издателя и политику и всегда возвращают executionAuthorized: false. Подпись не доказывает безопасность кода и не дает полномочий на выполнение, доступ к данным или работу в песочнице. Старые неподписанные пакеты требуют envelope: null и allowUnsigned: true; при этом по-прежнему указываются отсутствие подписи и непроверенный издатель. Аудит безопасности и проверка уязвимостей независимо от этого ожидают выполнения.
Проверка, активация и откат
createPluginUpdatePlan сравнивает старую и новую версии, API, разрешения, источники и хэши зависимостей, заявленные инструменты, лицензии, хэши настроек, идентичность миграции, подпись и ключ, затем фиксирует дайджест проверки. createPluginUpdateController управляет текущими авторизованными хостом и настройками, а также портами getPolicy/prepare оператора. Этап stage проверяет кандидата и делает его снимок; approve должен соответствовать точным дайджесту плана, разрешениям и идентификатору ключа. Activate проверяет текущие настройки и обновляет доверие до и после подготовки отдельного хоста-кандидата.
wait откладывает активацию, пока выполняются задания. retain-old оставляет старые задания на исходном хосте с прежними настройками и хэшем и после переключения направляет новые выполнения на новый хост. execute возвращает хэш плагина с каждым результатом. Задания не отменяются неявно. Замена настроек аннулирует ожидающее одобрение; параллельные изменения и неудачная подготовка сохраняют прежнее состояние либо явно сообщают о нем. Откат подготавливает старые пакет и настройки как новое проверяемое обновление и требует действующего доверия и нового одобрения.
Подготовка и миграции выполняются через доверенные порты оператора. Ни откат, ни сбой не отменяют внешние файлы, сетевые запросы или другие эффекты. reversible — метаданные проверки, а не обещание автоматической отмены. Журнал Node допускает только добавление, одного писателя и хранится вне рабочего пространства; он использует точный CAS ревизии и ограничения: 256 записей, 128 КиБ на конверт и 8 МиБ всего. При достижении предела архивируйте журнал под контролем оператора, прежде чем открыть новый.
inspectNodeUpdateJournal считывает сохраненное состояние без воспроизведения. Сбой во время preparing или неоднозначное подтверждение требует явного считывания хоста и настроек; reconcilePluginUpdateJournal записывает одобренный известный старый или новый дайджест и хэш настроек. Поврежденный конец журнала требует проверки и исправления оператором. recoverStaleLock восстанавливает блокировку только при доказанном завершении писателя на той же машине. Это не обещает межпроцессную транзакцию хоста и настроек или универсальную атомарность при потере питания.
Явные проверки upstream и кандидаты
fetchUpstreamArtifact требует явного вызова, enabled: true, точных URL источника, версии и дайджеста, точного разрешенного списка URL, офлайн-политики, лимита байтов и времени. Адреса перенаправлений также должны быть разрешены. Он не отправляет cookies или заголовки авторизации, ничего автоматически не повторяет и сообщает verified / digest-mismatch / unavailable / offline / unverified со временем наблюдения. Измененные теги или хэши требуют новой проверки. Loopback HTTP доступен только через явную опцию тестового объекта.
Адаптеры могут публиковать проверенный upstream-manifest с перечнем API, точной ревизией исходного кода, полными LICENSE/NOTICE и хэшами файлов. inspectUpstreamManifest связывает эти метаданные со скачанными байтами; он не анализирует произвольный исходный код и не выводит из него право на распространение. createUpstreamCandidate возвращает различия API, файлов и лицензий и патч с предыдущим дайджестом и источником замены. Совпадение с точной матрицей версий без функциональной проверки разработчиком остается непроверенным; отсутствие обязательного API означает отсутствие поддержки.
Даже поддерживаемый кандидат требует проверки человеком. Его массив automaticActions пуст; эти API не создают ветку, не выполняют слияние или публикацию, не одобряют новые разрешения и не устанавливают монитор. Хост отвечает за выполнение и отмену тестов адаптера. Полный публичный пример ниже использует только локальные тестовые объекты. API рабочих процессов, кэша, инструментов и LSP доступны в следующих разделах 1.2.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsТипы, API, ограничения и полный запускаемый исходный код
Рабочие процессы команд и явное восстановление
SDK 1.2 добавляет семь необязательных экспортов: /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node и /lsp-node. Текущий пакет содержит 50 экспортов, 107 схем, декларации TypeScript и независимые установленные примеры без npm-зависимостей времени выполнения. Только /tool-streams переносим в браузер; другие новые экспорты требуют Node. Существующий протокол рабочего пространства и API 1.x остаются совместимыми. Плагин, импортирующий новый API 1.2, должен объявить 1.2.0 минимальной версией SDK.
prepareWorkflowPlan перед выполнением проверяет зарегистрированные идентификаторы команд, уникальные шаги, ациклические зависимости, закрытые схемы входных и выходных данных и обязательные привязки выходных данных. Каждый вход — литерал {value} или привязка {step, path} к явной зависимости. Ограничения схем должны точно совпадать. Неизменяемый план связывает команды, разрешения, область и входные данные с SHA-256. run требует approved: true и именно этот проверенный дайджест. Порты authorize и execute хоста остаются под управлением оператора.
createCommandJobExecutor подключает изолированный существующий PluginHost, выбранный resolveHost, который возвращает точную область хоста, разрешения шага и хэш плагина. Разрешения разных шагов никогда не объединяются. Действующая авторизация проверяется до выполнения, после результатов и перед повторным использованием. continue завершает независимые ветви и блокирует потомков неудачных шагов; fail-fast отменяет оставшиеся шаги. Записи сохраняют идентификаторы родительского задания и попытки, отдельные задания, дайджесты входов и выходов, артефакты, причины и временные метки. Попадания в кэш не имеют нового идентификатора задания и не могут заявлять изменяемые артефакты задания.
recover считывает сохраненную контрольную точку и отмечает ожидающую и выполняющуюся работу как прерванную без выполнения. Ручное возобновление предоставляет точную предыдущую запись и previousAttemptId в новом одобрении, создает новую попытку и сохраняет только совпадающие успешные результаты с неистекшим сроком. retrySteps повторно выполняет выбранные шаги и их потомков даже в неупорядоченном DAG. Просроченный результат требует явного выбора повторной попытки; изменение схемы, ввода, разрешений или хэша плагина требует нового плана. Исполнитель, игнорирующий отмену, остается незавершенным в учете и препятствует перекрывающимся повторным попыткам.
createNodeWorkflowStore использует реальные раздельные каталоги хранилища и рабочего пространства, маркеры области и идентичности файловой системы, одного писателя, конверты с контрольными суммами и контрольные точки CAS. После известного сбоя явный recoverStaleLock принимает только доказанно завершившегося владельца на той же машине. Очистка по умолчанию обрабатывает распознанные поврежденные записи и незавершенную запись, сохраняя неизвестные файлы и ссылки. cleanup({expiredBefore}) также может удалить просроченные конечные записи; активные записи остаются для восстановления. В Windows не заявляется fsync каталогов или надежность хранения при потере питания. Ограничения: 64 шага, 8 параллельных шагов, 10 минут на процесс, 64 КиБ на результат, 1 МиБ суммарных выходов, записи 2 МиБ, 64 сохраняемые записи и не более 24 часов хранения частичных результатов.
Типы, API, ограничения и полные запускаемые примеры
Детерминированный кэш и инкрементальное выполнение
fingerprintWorkflowInputs хэширует реальные байты файлов, версию SDK, область рабочего пространства и безопасности, схему команды и ввод, хэши плагина и инструментов, настройки, объявленную среду и разрешения. Только mtime и путь никогда не определяют идентичность содержимого. Оператор явно объявляет optIn, deterministic, declaredInputsComplete и secretDependent. Неизвестный или неполный ввод, недетерминизм, зависимость от секретов, отсутствующая или необъявленная среда и входы со ссылками на секреты обходят кэш с указанием причины. Хост также должен исключить необработанные секреты и побочные эффекты; SDK не может обнаружить скрытые входы.
createWorkflowCache повторно проверяет действующую авторизацию при поиске, заполнении, после заполнения, попадании и возврате и проверяет хэши значений, область, разрешения и срок действия. Одновременные подходящие промахи используют одно заполнение; отмена одного ожидающего не отменяет остальных. Просроченные или поврежденные значения считаются промахами. TTL/LRU, лимиты записей и значений и очистка собственного хранилища регулируют хранение; при сбое записи вычисленные результаты сохраняются с явной причиной. Результаты со ссылками на секреты никогда не сохраняются. Ограничения отпечатка: 64 файла, 4 МиБ каждый, 16 МиБ всего; кэша: 512 записей, 16 МиБ сохраняемых значений, восемь заполнений и 60 секунд на заполнение.
Пример рабочего процесса обращается к кэшу только после успешного выполнения текущих зависимостей. Измененный файл аннулирует свой шаг; измененные выходы аннулируют отпечатки входов зависимых шагов. Неудачная зависимость блокирует родительский шаг до поиска его результата в кэше. Подтверждения различают hit, miss, shared и bypass, фактическое выполнение и повторное использование, счетчики кэша, объем хранения и локальные временные измерения. Устойчивое состояние кэша использует раздельные каталоги владельца и атомарную замену с восстановлением незавершенных записей и повреждений; исходные файлы не удаляются.
Типы, API, ограничения и полные запускаемые примеры
Потоки вывода зарегистрированных инструментов
createToolStreamParser — переносимый ограниченный декодер UTF-8 JSONL/текста. Ожидайте write(bytes, stdout/stderr) для обратного давления и вызывайте finish только после завершения обоих потоков. Он сохраняет разделенные многобайтовые символы и последние неполные строки, создавая коррелированные события журналов, прогресса, диагностики и неизвестного типа. Некорректный UTF-8 и жесткие ограничения останавливают разбор. Относительные пути диагностики, упорядоченные позиции и уровни серьезности проверяются; редактор-потребитель также должен сверить позиции с текущим текстом документа. createJobToolEventSink соединяет прогресс и журналы с существующим JobReporter, оставляя диагностику приемнику вызывающей стороны.
Необязательный исполнитель Node принимает фиксированные регистрации оператора: бэкенд, инструмент и версию, абсолютный путь исполняемого файла и закрепленные части реализации, точную проверку версии, явную среду, закрытую схему ввода и обязательные скалярные позиции аргументов. Файловые позиции должны указывать существующие относительные файлы рабочего пространства. Вызов плагина выбирает только уже зарегистрированные инструмент и версию и проверенный ввод; выбирать оболочку или исполняемый файл он не может. Действующая авторизация проверяется до подготовки и запуска, при событиях и после завершения. Подтверждения сохраняют код выхода, причину отмены или сбоя и статистику вывода.
Известные однострочные литералы секретов и путей маскируются после сборки строки, включая разделенные фрагменты; закодированные и неизвестные секреты автоматически не обнаруживаются. Исполнитель владеет только прямым дочерним процессом и его каналами и закрывает их при отмене или закрытии. Он не сканирует и не завершает посторонние деревья процессов или деревья потомков и не является песочницей ОС. Ограничения: фрагменты 64 КиБ, строки 16 КиБ, 2 МиБ общего вывода, 4 096 событий, восемь ожидающих записей, пять секунд для приемников, 32 инструмента и четыре параллельных выполнения. Отдельная проверка с лимитами пять секунд и 16 КиБ проверяет настроенную версию.
Созданный SDK распространяемый тестовый инструмент проверяет фрагментированный UTF-8/JSONL, завершающий вывод, ненулевые коды выхода, отмену и ограничения. Реальный адаптер — TypeScript 5.9.3 с --noEmit --noLib --pretty false и одноразовым тестовым набором встроенных типов, создающим TS2322. Для запуска явно укажите существующий одобренный корневой каталог TypeScript. SDK никогда автоматически не устанавливает и не скачивает внешний инструмент; предоставленные хэши сами по себе не подтверждают его издателя.
Типы, API, ограничения и полные запускаемые примеры
Публичный мост LSP через stdio
createLspBridge соединяет явно одобренный закрепленный процесс stdio с существующими языковыми запросами и провайдерами SDK. Он согласует поддерживаемое подмножество LSP 3.17, позиции UTF-16 и полные снимки. capabilities отдельно сообщает заявленную поддержку и успешные выполнения. Поддерживаемые соответствия охватывают автодополнение, подсказку при наведении, определение, ссылки, плоские и иерархические символы, подсказки сигнатур, prepare-rename/rename, форматирование документа и диапазона, действия с кодом, полные семантические токены, сворачивание и встроенные подсказки: 15 функций SDK.
syncDocument и closeDocument обрабатывают didOpen/didChange/didClose. Изменения текущей версии и поколения отменяют устаревшую работу, повторяющиеся идентификаторы активных запросов отклоняются, поздние ответы игнорируются. Локальные URI должны разрешаться внутри рабочего пространства без ссылок; исходные документы и цели правок требуют действующей авторизации и открытого либо предоставленного хостом точного снимка. Результаты переименования, форматирования и действий — условные предложения правок рабочего пространства с базовыми хэшами, а не автоматически применяемые правки или исполняемые команды.
Диагностика принимается только с текущей версией документа. Уведомления без версии или с устаревшей версией отбрасываются и учитываются. Явно не поддерживаются разрешение автодополнений и snippets, разрешение действий с кодом, семантические дельты, серверные команды, динамические возможности, операции с ресурсами, сокетные транспорты и диагностика без версии. workspace/applyEdit возвращает applied:false. Ограничения: сообщения 1 МиБ, заголовки 8 КиБ, сессии 64 МиБ/20 000 сообщений, 16 ожидающих запросов и записей, 32 документа/4 МиБ совокупного текста, тайм-ауты запросов до 30 секунд и 64 КиБ отбрасываемого stderr.
close отправляет shutdown/exit и выполняет ограниченную очистку прямого процесса и каналов, различая корректное подтверждение, отказавшие или аварийно завершенные серверы и фактическое закрытие процесса. Сервер может подтвердить shutdown и все же потребовать остановки принадлежащего инструменту процесса. Автоматического перезапуска или воспроизведения нет: оператор создает новый мост и явно повторно отправляет выбранные текущие снимки. Синтетические тесты охватывают некорректное кадрирование, аварии и тайм-ауты, отмену и поздние ответы, гонки документов, отказ завершения, неподдерживаемые запросы и каждую сопоставленную функцию.
Реальная проверка независимого сервера использует community typescript-language-server 5.3.0 с TypeScript 5.9.3: автодополнение, наведение, определение, ссылки, символы, подсказки сигнатур, форматирование и семантические токены прошли проверку. Выбранные файлы реализации и Node закреплены, путь tsserver фиксирован, автоматическое получение типов отключено. Эта версия сервера не передает необязательный initialize.serverInfo и отправляет диагностику без версии, поэтому его диагностика явно не поддерживается этим мостом; диагностика с версией проверена независимым синтетическим сервером. Оператор должен доверять всему установленному инструменту и его доступу к ОС.
Приемка 1.2 включает независимых потребителей упакованного SDK, декларации, 107 схем, реальные адаптеры компилятора и сервера и совместимость с историческими публичными архивами. Пример рабочего процесса различает устойчивое восстановление и явную повторную попытку от автоматического воспроизведения. Аудит безопасности и проверка уязвимостей остаются отложенными владельцем. Этот выпуск не является приемкой интерфейса DDS, Engine, планировщика Cloud, Marketplace, установщика или песочницы безопасности.
Типы, API, ограничения и полные запускаемые примеры
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
node node_modules/@altifigence/dds-plugin-sdk/examples/tool-streams-browser/serve.mjsДля реальных адаптеров добавьте абсолютные пути к существующим установкам, одобренным оператором. Примеры по умолчанию используют только созданные SDK тестовые объекты и никогда не скачивают инструмент.
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs --typescript-root /absolute/path/to/typescript
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs --typescript-root /absolute/path/to/typescript --language-server-root /absolute/path/to/typescript-language-server