Plugin SDK: Entwicklung und Releases
Entwicklung, Prüfung, Release-Werkzeuge und Workflows in 1.2, inkrementeller Cache, externe Werkzeuge und öffentliche LSP-Brücke.
Entwicklungs-, Prüf- und Release-Leitfaden für DDS Plugin SDK 1.2.0. Das Sicherheitsaudit und die Prüfung auf Schwachstellen stehen noch aus; ein stabiler API-Status und funktionale Prüfungen stellen keine Sicherheitsabnahme dar.
SDK-Installation und API-Leitfaden
Entwicklungsvorlagen und Generierung
Wählen Sie command, language, theme, job, browser oder configuration. init --dry-run meldet Zielverzeichnis, Dateibestand, Hashes und Konflikte, ohne Dateien zu schreiben oder etwas zu installieren. Ein normaler init-Aufruf erfordert ein neues, echtes Verzeichnis. Jede Vorlage enthält Quellcode, Manifest, Offenlegung, Lizenz/Notice, Tests, einen typisierten Consumer und ein ausführbares Beispiel. Die browser- und configuration-Vorlagen enthalten eine Loopback-Demo. Generierte Abhängigkeiten sind auf das genaue GitHub-Archiv festgelegt.
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 enthält begrenzte JSON-Daten für Befehlsschemas, Einstellungen, Sprachkataloge und Designdaten. generate erzeugt Laufzeit-JSON, ESM-Exporte, rohe und validierte TypeScript-Eingabetypen, Ausgabe- und Einstellungstypen, JSON Schema und Design-XML. Standardwerte im JSON Schema sind Annotationen; nur die Eingabevalidierung des SDK wendet Standardwerte an. Die Generierung importiert Ihr Plugin nicht. doctor prüft Abweichungen, Metadaten, fehlende Module und ob die generierten Laufzeitdateien in der Paket-Zulassungsliste enthalten sind.
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>Das Ersetzen erfordert den exakten vorherigen Digest und unveränderte generierte Bytes. Manuelle Änderungen, zusätzliche Dateien, Links und veraltete Sperren verhindern das Ersetzen. Bei Fehlern werden nur unveränderte Einträge entfernt, die diesem Versuch gehören; geänderte oder unklare Einträge bleiben zur Prüfung erhalten. Die Grenzen liegen bei 256 Dateien, je 1 MiB und insgesamt 4 MiB. Die Sperre koordiniert kooperierende Generatoren; sie schützt weder vor einem feindlichen gleichzeitigen Dateisystemschreiber noch bietet sie eine atomare Transaktion über mehrere Verzeichnisse. Proprietäre Vorlagen erfordern vom Aufrufer bereitgestellte Bedingungen und bewahren geerbte SDK-Lizenz- und Notice-Dateien.
Deterministische Tests und Replay
createScenarioHost aus /testing bindet ausgewählte In-Memory-Fixtures für Dateien, Backend, Einstellungen, Geheimnisse und Jobs ausdrücklich ein. Der Host startet ohne Berechtigungen oder Fähigkeiten. createTestClock stellt gesetzte IDs, Zeit und Timer bereit, ohne globale Objekte zu verändern; Timer mit gleichem Zeitpunkt behalten ihre Einfügereihenfolge. Warten Sie auf das Fortschalten der Uhr, um virtuelle Wartevorgänge freizugeben. Die generierten UUIDs sind Testdaten, keine kryptografische Entropie. Die bestehenden Standardwerte von createTestHost bleiben kompatibel.
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();
}Fehlerports modellieren Verzögerungen, Ablehnungen, Verbindungsabbrüche, Beschädigung, Ressourcenerschöpfung und verworfene Aufrufe; Ereignis-Fixtures können verworfen, dupliziert oder umgekehrt werden, ohne externe Wirkungen zu wiederholen. replaceGrants deaktiviert Plugins, die ihre Befugnisse verlieren. In-Memory-Job-Snapshots validieren Identität, Revision und Hashes und modellieren eine Wiederherstellung nach Unterbrechung ohne automatische Ausführung. Diese Fixtures bilden weder die Dauerhaftigkeit des Dateisystems nach noch ermitteln sie Betriebssystem-Handles. Ein separates Eigentümerverzeichnis erfasst ausdrücklich registrierte Ressourcen. Beim Abbau bleiben ausstehende Zähler für Callbacks, die Abbruch ignorieren, erhalten, bis sie tatsächlich abgeschlossen sind. inspect für Einstellungen bleibt nun nach dem Freigeben lesbar; Datenlesevorgänge werden weiterhin abgelehnt.
Die Aufzeichnung erfordert synthetic: true und ein ausdrücklich festgelegtes, begrenztes Fixture-Inventar. Exportierte Traces enthalten nur Operationsarten, Fixture-IDs, Zeitangaben, Seed/Version und verkettete Hashes. Verwenden Sie nicht sensible IDs; Hashes anonymisieren keine erratbaren Daten, und das SDK kann beliebige Eingaben nicht als synthetisch klassifizieren. Reines Replay prüft Reihenfolge, Hashes und Fixture-Identität und gibt ausgewählte Fixture-Ausgaben zurück; es akzeptiert keinen Callback mit Seiteneffekten. Die Grenzen liegen bei 64 Fixtures, 1.024 Ereignissen und einem Trace von 1 MiB. Führen Sie das mitgelieferte development-tools-Beispiel aus, um Fehler, Wiederherstellung, Datenschutz und Bereinigung zu prüfen.
Lokale Diagnose und Fehlersuche
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();
}Diagnosen sind standardmäßig deaktiviert und ausschließlich lokal. Berichte enthalten feste Operations-, Status- und Fehlercodes, Korrelations-IDs, Laufzeiten und Ressourcenzähler; es gibt keine API für Dokumentinhalte, Pfade, Eingaben, Ausgabeinhalte oder beliebigen Ausnahmetext. Bytezahlen, Warteschlangentiefe und Speicherangaben sind ausdrücklich Schätzungen des Eigentümers. profileTransport misst, bis der umschlossene Aufruf abgeschlossen ist; bei fetch ist das der Empfang der Antwortheader und nicht der Abschluss des Antwortinhalts. Abgeschlossene Datensätze verwenden einen begrenzten Ringpuffer und passiven Ablauf; es gibt keine Diagnose-Hintergrundtimer oder Uploads. Die Standardwerte sind 128 Ereignisse/60 Sekunden; die Höchstwerte sind 256 Ereignisse/5 Minuten, 64 laufende Spans und 256 KiB je Bericht.
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"}'Der Debug-Modus stellt nur einen kurzlebigen 127.0.0.1-Inspector im eigenen Kindprozess bereit. --debug-wait hält vor dem Plugin-Import an und erfordert --debug. Das gesamte Laufzeitbudget umfasst auch das Warten auf den Debugger und beträgt höchstens 30 Sekunden. Abschluss, Abbruch und Zeitüberschreitung beenden den eigenen Kindprozess und Inspector. Sowohl Profiling als auch Debugging erfordern ausdrückliches Vertrauen in den lokalen Code; keines von beiden ist eine Sandbox. Abstürze oder erzwungene Beendigung können dazu führen, dass der Profilbericht fehlt; die rohe stdout/stderr-Ausgabe des Plugins bleibt ein separater begrenzter Datenstrom und wird nicht automatisch geschwärzt.
Entwicklungswerkzeuge · Tests · Diagnose · Kompatibilität
Host-Konformität
Das Modul /conformance führt versionierte synthetische Prüfungen gegen Ihre ausdrücklich bereitgestellten Adapter für Host, Einstellungen, Workspace, Lokalisierung, Tests, Diagnose und Entwicklung aus. Es unterscheidet unterstützte, nicht unterstützte und fehlgeschlagene Profile und erfasst Host/Version/Laufzeit/Plattform, Prüf-ID, Zeitangaben und Bereinigung. Eine deklarierte Funktion mit fehlendem oder defektem Adapter schlägt fehl; unbekannte optionale Funktionen werden ohne Prüfung erfasst. Befehle, Berechtigungen und Abbruch sind standardmäßig erforderlich.
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));Ersetzen Sie die Host-Factory durch Ihren Adapter und führen Sie auch Ihre Plugin-Tests aus. Der Node-Helfer /conformance-node erstellt nur neue temporäre Fixtures und kurzlebige Loopback-Server. Das Browser-Beispiel führt verfügbare Browser-Profile aus und meldet fehlende Node-Funktionen als nicht unterstützt. Schnellprüfungen testen Verträge stichprobenartig; verlinkte Beispiele und Release-Tests decken umfangreichere Sprach-, Wiederherstellungs- und Speicherpfade ab. Ein Bericht ist ein Testnachweis, kein Vertrauenszertifikat.
Fristen betragen standardmäßig 10 Sekunden je Fall, höchstens 30 Sekunden. Zeitüberschreitung oder Abbruch stoppen nachfolgende Fälle; ein Bereinigungsfehler lässt den Fall scheitern, und ausstehende Bereinigung bleibt ungeprüft. Vertrauenswürdige Adapter im selben Prozess können synchron blockieren und Umgebungsbefugnisse behalten. Berichte schließen Anbieter-Fehlertexte, Nutzdaten, Tokens und Pfade aus; wählen Sie nicht sensible Identitätsbezeichnungen. Kein Bericht wird automatisch hochgeladen.
SDK-Support und Migration
API_SUPPORT.json listet jedes exportierte Modul, jeden Laufzeitnamen, jede Deklaration, jeden Deklarations-Digest sowie Umgebung und Stabilität auf. Stabile 1.x-APIs folgen der semantischen Versionierung: Kompatible Ergänzungen erhalten ein Minor-Release, inkompatible stabile Änderungen erfordern eine neue Major-Version. artifact-resume-browser bleibt experimentell und benötigt eine exakte SDK-/Browser-Version mit erneuter Browser-Abnahme. Die Ermittlung optionaler Fähigkeiten und aktuelle Berechtigungen bleiben erforderlich.
Die Richtlinie für stabile Versionslinien gilt ab 1.0.0. Die neueste stabile Minor-Version erhält reguläre Korrekturen; die vorhergehende Minor-Version kann innerhalb einer unterstützten Laufzeit 90 Tage lang kritische Sicherheitskorrekturen erhalten. In 1.0.0 ist keine stabile API als veraltet gekennzeichnet. Abkündigungen werden mindestens zwei Minor-Releases und sechs Monate vor der Entfernung in einer Major-Version angekündigt. RCs und Vorschauversionen werden durch Nachfolger ersetzt. Diese Open-Source-Richtlinie verspricht keine kommerziellen Reaktionszeiten.
Die Server- und CLI-Abnahme umfasst Windows/Linux mit gepatchtem Node 22 oder 24 sowie Deklarationen mit TypeScript 5.9.3. Der Support für Node 22 endet am 2027-04-30 und für Node 24 am 2028-04-30. Release-Nachweise nennen die genauen Patch-Versionen, Betriebssystem-Images und den Browser-Build. Andere Laufzeiten und Browser-/Speicherkombinationen benötigen eine eigene Abnahme. Das SDK hat weiterhin keine npm-Laufzeitabhängigkeiten.
Stabile 1.0-Plugins verwenden >=1.0.0 <2.0.0; erhöhen Sie die Mindestversion, wenn Sie eine spätere API übernehmen. RC1-Pakete behalten ihre exakte 1.0.0-rc.1-Peer-Abhängigkeit. Validieren Sie erneut und veröffentlichen Sie eine neue Plugin-Version, um dies zu ändern; bewahren Sie frühere Archive unverändert auf. Legacy-Archive sind Eingaben für Interoperabilität, keine gepflegten Versionslinien. Stellen Sie nach einem Neustart eine neue Verbindung und aktuelle Berechtigungen her; die Wiederherstellung liest festgeschriebenen Zustand, ohne Arbeit erneut auszuführen.
Release-Abnahme
Das Sicherheitsaudit und die Prüfung auf Schwachstellen stehen aufgrund der Verschiebung durch den Eigentümer vom 2026-10-05 noch aus. Funktions-, Kompatibilitäts- und Leistungsergebnisse stellen keine Sicherheitsabnahme dar. Die zurückgestellte Prüfung wird separat fortgesetzt; dieses Release darf nicht als erfolgreich auditiert bezeichnet werden.
Die kombinierte Fixture testet gleichzeitig Sprache/Einstellungen, geprüfte Änderungen, Befehlsjobs, Projektüberwachung, Upload/Download und dauerhaften Speicher. Sie prüft Unterbrechungen, fehlerhafte Antworten, Entzug von Berechtigungen, Generationswechsel, Wiederherstellung und Ressourcenbereinigung. Separate Dateisystem-/Prozesstests decken beendete Kindprozesse, Beschädigung, fehlgeschlagene Schreibvorgänge, Ablauf und ignorierten Abbruch ab. Der RC-Abnahmebericht verlinkt reproduzierbare Befehle und die Grenzen jedes Ergebnisses.
Die Leistungsmessung erfasst je fünf Stichproben mit neuen Prozessen für jedes Windows-/Linux- und Node-22-/24-Profil, einschließlich Median/Streuung, CPU-Zeit, stichprobenartigem Speicherbedarf, Import-/Start-/Watch-Zeiten und logischen Zählern für Datenträger-/HTTP-Nutzdaten. Basisschwellen stammen aus diesen gemessenen Stichproben und sind grobe Schutzgrenzen gegen Regressionen, keine Latenz-SLA. Sie messen keinen physischen Datenträgerverkehr und garantieren nicht, dass jedes Betriebssystem-Handle ermittelt wird.
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-browserKonformität · API-Inventar · Support-Richtlinie · RC-Abnahme
Inhalt des stabilen 1.0-Releases
Das ursprüngliche 1.0-Paket enthält 38 Exporte und 86 Schemas mit Deklarationen, Beispielen, LICENSE und NOTICE. 1.1 ergänzt die nachfolgend beschriebenen Release-Werkzeuge; 1.2 ergänzt die nachfolgenden Abschnitte zu Workflows, Cache, Werkzeugen und LSP. Release-Nachweise unterscheiden genaue Quellstände/CI/Digests, neue Consumer und wiederverwendete Browser-Nachweise.
Für ein Downgrade stoppen Sie eigene Arbeit und wählen ausdrücklich aufbewahrte kompatible SDK-/Plugin-Archive sowie einen Konfigurationsexport aus. Prüfen Sie aktuelle Berechtigungen und stellen Sie eine neue Verbindung her. Ergebniswiederherstellung dient nur dem Rücklesen; externe Wirkungen und inkompatible Einstellungen werden nicht automatisch rückgängig gemacht. Testen Sie die tatsächlich verwendeten Formate und optionalen Funktionen.
Release-Inhalte, Migration und Support
Offline-Bundles und SBOM
SDK 1.1 ergänzt fünf optionale, ausschließlich für Node verfügbare Einstiegspunkte: /bundles, /provenance, /updates, /updates-node und /upstream. Das Paket enthält 43 Exporte, 96 Schemas, Deklarationen und ausführbare Beispiele ohne npm-Laufzeitabhängigkeiten. Bestehende 1.0-APIs und unsignierte DDS-.tgz-Archive bleiben kompatibel.
lockBundleDependency bindet einen geprüften ESM-/CommonJS-Dateibaum an eine exakte Version, HTTPS-Quelle, kanonischen Datei-Digest, eine Abhängigkeitszuordnung, LICENSE/NOTICE und eine ausdrückliche Entscheidung zur Weiterverteilung. Der Digest beschreibt den geprüften Baum; er ist kein Hash des Upstream-Archivs. createPluginBundle bettet das ursprüngliche DDS-Plugin-Archiv und Release-Metadaten, einen azyklischen Abhängigkeitsgraphen mit je einer Version sowie eine deterministische CycloneDX-1.6-SBOM ein.
verifyPluginBundle prüft den exakten begrenzten Byte-Snapshot. installPluginBundle erfordert dessen expectedSha256, approved: true und ein neues Verzeichnis unter einem vom Betreiber kontrollierten übergeordneten Verzeichnis. Es führt weder npm noch Lifecycle-Skripte, Downloads oder Plugin-Code aus. Abhängigkeiten erhalten keine neuen Berechtigungen. Das Host-SDK ist eine separate Abhängigkeit. Native Addons, Export-Maps und beliebige npm-Abhängigkeitsauflösung liegen außerhalb dieses Formats.
Grenzen: 32 Abhängigkeitspakete, 1.024 entpackte Dateien, 4 MiB je Abhängigkeitsdatei, 32 MiB entpackte Inhalte und 48 MiB kodiertes Bundle. Das ursprüngliche Root-Archiv hat eigene niedrigere Grenzen. Fehlende oder widersprüchliche Versionen, Zyklen, verwaiste Abhängigkeiten, geänderte Hashes, fehlende Lizenzen/NOTICE, Pfade/Links und Datei-Verzeichnis-Kollisionen werden abgelehnt. Fehlgeschlagene Installationen bewahren das neue Ziel zur Prüfung auf. Schließen Sie gleichzeitige Schreiber aus; dieses Werkzeug ist keine Betriebssystem-Sandbox.
Separate Signaturen und Betreibervertrauen
createProvenanceStatement bindet den genauen Bundle-Namen, Version und SHA-256, Herausgeber, Quellrevision sowie Ausstellungs- und Ablaufzeitpunkte. signPluginProvenance verwendet ein vom Aufrufer kontrolliertes Ed25519-KeyObject. canonicalProvenancePayload stellt DDS-PROVENANCE-V1 gefolgt von kanonischem JSON bereit, damit ein anderer Signierer dieselben Nutzdaten reproduzieren kann. Das SDK liefert weder einen privaten Signaturschlüssel noch die Befugnis, DDS-Produkte zu signieren.
verifyPluginProvenance übernimmt vom Betreiber gewählte Vertrauensanker, Herausgeber-/Subjektbindungen, aktuelle Zeit, Schlüsselgültigkeit/-widerruf und zeitgestempelte Widerrufsnachweise. Die Offline-Prüfung nutzt bereitgestellte Nachweise und wendet dasselbe Aktualitätsbudget an; sie ruft niemals selbst aktuelle Widerrufsinformationen ab. Ein neuer Paketschlüssel gilt als nicht vertrauenswürdig, bis der Betreiber ihn hinzufügt. Ausdrücklich überlappende Vertrauensanker ermöglichen Rotation. Die maximale Uhrabweichung beträgt fünf Minuten und das maximale Nachweisalter 30 Tage; wählen Sie bei Bedarf strengere Grenzen.
Nachweise behandeln Prüfsumme, Signatur, Herausgeber und Richtlinie getrennt und liefern immer executionAuthorized: false zurück. Eine Signatur belegt weder die Sicherheit des Codes noch erteilt sie Ausführungs-, Datenzugriffs- oder Sandbox-Befugnisse. Ältere unsignierte Pakete erfordern envelope: null und allowUnsigned: true und melden weiterhin unsigned sowie einen nicht verifizierten Herausgeber. Sicherheitsaudit und Schwachstellenprüfung stehen unabhängig davon noch aus.
Prüfen, aktivieren und zurückrollen
createPluginUpdatePlan vergleicht alte/neue Version, API, Berechtigungen, Abhängigkeitsquellen/-hashes, deklarierte Werkzeuge, Lizenzen, Einstellungshashes, Migrationsidentität, Signatur und Schlüssel und fixiert anschließend den Prüf-Digest. createPluginUpdateController kontrolliert den aktuell autorisierten Host und die Einstellungen sowie die getPolicy-/prepare-Ports des Betreibers. Stage prüft den Kandidaten und erstellt einen Snapshot; approve muss exakt mit Plan-Digest, Berechtigungen und Schlüssel-ID übereinstimmen. Activate prüft aktuelle Einstellungen und erneuert das Vertrauen vor und nach der Vorbereitung eines separaten Kandidaten-Hosts.
wait verschiebt die Aktivierung, solange Jobs laufen. retain-old belässt alte Jobs auf ihrem ursprünglichen Host mit ihren Einstellungen und Hashes und leitet neue Ausführungen nach dem Wechsel an den neuen Host. execute gibt mit jedem Ergebnis den Plugin-Hash zurück. Jobs werden nicht implizit abgebrochen. Das Ersetzen von Einstellungen macht eine ausstehende Freigabe ungültig; gleichzeitige Änderungen und fehlgeschlagene Vorbereitung bewahren den vorherigen Zustand oder melden ihn ausdrücklich. Rollback stellt das alte Paket und die alten Einstellungen als neues geprüftes Update bereit und erfordert aktuelles Vertrauen und eine neue Freigabe.
Vorbereitung und Migrationen laufen über vertrauenswürdige Ports des Betreibers. Weder Rollback noch Fehler machen externe Dateien, Netzwerkanfragen oder andere Wirkungen rückgängig. reversible ist Prüfmetadatum und kein Versprechen einer automatischen Rücknahme. Ein Node-Journal wird nur ergänzt, hat einen einzelnen Schreiber und liegt außerhalb des Workspace; es verwendet exaktes Revisions-CAS und Grenzen von 256 Datensätzen / 128 KiB je Envelope / insgesamt 8 MiB. Archivieren Sie es unter Betreiberkontrolle, bevor Sie bei Erreichen der Grenze ein neues Journal öffnen.
inspectNodeUpdateJournal liest persistierten Zustand ohne Replay. Ein Absturz während preparing oder eine unklare Bestätigung erfordert ausdrückliches Rücklesen von Host/Einstellungen; reconcilePluginUpdateJournal erfasst einen freigegebenen bekannten alten/neuen Digest und Einstellungshash. Beschädigte Enden erfordern Prüfung/Reparatur durch den Betreiber. recoverStaleLock stellt nur die Sperre eines nachweislich beendeten Schreibers auf demselben Rechner wieder her. Dies verspricht weder eine prozessübergreifende Host-/Einstellungstransaktion noch universelle Atomarität bei Stromausfall.
Ausdrückliche Upstream-Prüfungen und Kandidaten
fetchUpstreamArtifact benötigt einen ausdrücklichen Aufruf, enabled: true, exakte Quell-URL/Version/Digest, eine exakte URL-Zulassungsliste, Offline-Richtlinie, Bytebudget und Frist. Auch Weiterleitungsziele müssen zugelassen sein. Es sendet keine Cookies oder Authentifizierungsheader, wiederholt nichts automatisch und meldet verified / digest-mismatch / unavailable / offline / unverified mit Beobachtungszeit. Geänderte Tags oder Hashes benötigen eine neue Prüfung. Loopback-HTTP ist nur über eine ausdrückliche Fixture-Option verfügbar.
Adapter können ein geprüftes upstream-manifest mit API-Inventar, exakter Quellrevision, vollständigen Lizenz-/NOTICE-Angaben und Dateihashes veröffentlichen. inspectUpstreamManifest verknüpft diese Metadaten mit heruntergeladenen Bytes; es analysiert keinen beliebigen Quellcode und leitet keine Erlaubnis zur Weiterverteilung ab. createUpstreamCandidate liefert API-/Datei-/Lizenzunterschiede und einen Patch mit vorherigem Digest und Ersatzquelle. Eine Übereinstimmung mit einer exakten Versionsmatrix bleibt ohne funktionale Entwicklerprüfung unbestätigt; eine fehlende erforderliche API gilt als nicht unterstützt.
Auch ein unterstützter Kandidat erfordert menschliche Prüfung. Sein automaticActions-Array ist leer; diese APIs erstellen keinen Branch, führen kein Merge aus, veröffentlichen nichts, genehmigen keine neuen Berechtigungen und installieren keine Überwachung. Der Host kontrolliert Ausführung und Abbruch der Adaptertests. Das folgende vollständige öffentliche Beispiel verwendet nur lokale Fixtures. Workflow-/Cache-/Tool-/LSP-APIs stehen in den nachfolgenden 1.2-Abschnitten zur Verfügung.
node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjsTypen, API, Grenzen und vollständiger ausführbarer Quellcode
Befehlsworkflows und ausdrückliche Wiederherstellung
SDK 1.2 ergänzt sieben optionale Exporte: /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node und /lsp-node. Das aktuelle Paket enthält 50 Exporte, 107 Schemas, TypeScript-Deklarationen und unabhängige installierte Beispiele ohne npm-Laufzeitabhängigkeiten. Nur /tool-streams lässt sich im Browser verwenden; die anderen neuen Exporte erfordern Node. Das bestehende Workspace-Protokoll und die 1.x-APIs bleiben kompatibel. Ein Plugin, das eine neue 1.2-API importiert, muss 1.2.0 als Mindest-SDK-Version deklarieren.
prepareWorkflowPlan validiert registrierte Befehls-IDs, eindeutige Schritte, azyklische Abhängigkeiten, geschlossene Ein-/Ausgabedatenschemas und erforderliche Ausgabebindungen vor der Ausführung. Jede Eingabe ist ein Literal {value} oder eine {step, path}-Bindung an eine ausdrückliche Abhängigkeit. Schemaeinschränkungen müssen exakt übereinstimmen. Der unveränderliche Plan bindet seine Befehle, Berechtigungen, den Geltungsbereich und Eingaben an einen SHA-256. run erfordert approved: true und diesen exakten geprüften Digest. Die authorize- und execute-Ports des Hosts bleiben unter Betreiberkontrolle.
createCommandJobExecutor verbindet einen isolierten bestehenden PluginHost, der durch resolveHost ausgewählt wird; dieses liefert den genauen Host-Geltungsbereich, Schrittberechtigungen und Plugin-Hash zurück. Berechtigungen werden niemals über Schritte hinweg zusammengeführt. Aktuelle Autorisierung wird vor der Ausführung, nach Ergebnissen und vor Wiederverwendung geprüft. continue schließt unabhängige Zweige ab und blockiert Nachfolger fehlgeschlagener Schritte; fail-fast bricht verbleibende Schritte ab. Datensätze behalten übergeordnete Job-/Versuchs-IDs, einzelne Jobs, Ein-/Ausgabe-Digests, Artefakte, Gründe und Zeitstempel. Cache-Treffer erhalten keine neue Job-ID und dürfen keine veränderlichen Job-Artefakte beanspruchen.
recover liest einen gespeicherten Checkpoint und meldet ausstehende/laufende Arbeit als unterbrochen, ohne sie auszuführen. Ein manuelles resume übergibt den exakten vorherigen Datensatz und previousAttemptId in einer neuen Freigabe, erstellt einen neuen Versuch und übernimmt nur übereinstimmende, nicht abgelaufene erfolgreiche Ergebnisse. retrySteps führt ausgewählte Schritte und ihre Nachfolger auch in einem ungeordneten DAG erneut aus. Abgelaufene Ausgaben erfordern eine ausdrückliche Auswahl zur Wiederholung; geänderte Schemas, Eingaben, Berechtigungen oder Plugin-Hashes erfordern einen neuen Plan. Ein Executor, der Abbruch ignoriert, bleibt als nicht abgeschlossen gezählt und verhindert überlappende Wiederholungen.
createNodeWorkflowStore verwendet echte getrennte Speicher-/Workspace-Verzeichnisse, Geltungsbereichs- und Dateisystem-Identitätsmarker, einen Schreiber, Envelopes mit Prüfsummen und CAS-Checkpoints. Nach einem bekannten Absturz akzeptiert ein ausdrückliches recoverStaleLock nur einen nachweislich beendeten Eigentümer auf demselben Rechner. Die Standardbereinigung behandelt erkannte beschädigte Datensätze und unvollständige Schreibvorgänge und bewahrt unbekannte Dateien/Links. cleanup({expiredBefore}) kann auch abgelaufene abgeschlossene Datensätze entfernen; aktive Datensätze bleiben zur Wiederherstellung erhalten. Für Windows wird weder Verzeichnis-fsync noch Dauerhaftigkeit bei Stromausfall zugesichert. Grenzen: 64 Schritte, 8 gleichzeitige Schritte, 10 Minuten Workflow-Frist, 64 KiB je Ergebnis, 1 MiB kombinierte Ausgaben, 2 MiB Datensätze, 64 aufbewahrte Datensätze und höchstens 24 Stunden Aufbewahrung von Teilergebnissen.
Typen, API, Grenzen und vollständige ausführbare Beispiele
Deterministischer Cache und inkrementelle Ausführung
fingerprintWorkflowInputs hasht tatsächliche Dateibytes sowie SDK-Version, Workspace-/Sicherheitsgeltungsbereich, Befehlsschema/-eingabe, Plugin-/Tool-Hashes, Einstellungen, deklarierte Umgebung und Berechtigungen. mtime und Pfad allein sind niemals Inhaltsidentitäten. Der Betreiber deklariert optIn, deterministic, declaredInputsComplete und secretDependent ausdrücklich. Unbekannte oder unvollständige Eingaben, Nichtdeterminismus, Geheimnisabhängigkeit, fehlende/undeklarierte Umgebung und Eingaben mit Geheimnisreferenzen umgehen den Cache mit einer Begründung. Der Host muss außerdem rohe Geheimnisse und Seiteneffekte ausschließen; das SDK kann verborgene Eingaben nicht ableiten.
createWorkflowCache prüft aktuelle Autorisierung erneut bei lookup/fill/after-fill/hit/return und verifiziert Werthashes, Geltungsbereich, Berechtigungen und Ablauf. Gleichzeitige geeignete Cache-Fehlzugriffe teilen sich einen Berechnungsvorgang; der Abbruch eines Wartenden bricht andere nicht ab. Abgelaufene oder beschädigte Werte gelten als Fehlzugriffe. TTL/LRU, Eintrags-/Wertbudgets und Bereinigung des eigenen Speichers kontrollieren die Speicherung; bei Schreibfehlern bleiben berechnete Ergebnisse mit ausdrücklicher Begründung erhalten. Ergebnisse mit Geheimnisreferenzen werden niemals gespeichert. Fingerprint-Grenzen sind 64 Dateien, je 4 MiB und insgesamt 16 MiB; Cache-Grenzen sind 512 Einträge, 16 MiB gespeicherte Wertbytes, acht Berechnungsvorgänge und 60 Sekunden je Vorgang.
Das Workflow-Beispiel sucht erst im Cache, nachdem aktuelle Abhängigkeiten erfolgreich abgeschlossen sind. Eine geänderte Datei macht ihren Schritt ungültig; geänderte Ausgaben machen die Fingerprints abhängiger Eingaben ungültig. Eine fehlgeschlagene Abhängigkeit blockiert den übergeordneten Schritt, bevor ein zwischengespeichertes Ergebnis dieses Schritts gesucht wird. Nachweise unterscheiden hit, miss, shared und bypass, tatsächliche Ausführung und Wiederverwendung, Cache-Zähler, Speicherbytes und lokale Zeitmessungen. Dauerhafter Cache-Zustand verwendet getrennte Eigentümerverzeichnisse und atomares Ersetzen mit Wiederherstellung verwaister Schreibvorgänge und beschädigter Daten; er löscht keine Quelldateien.
Typen, API, Grenzen und vollständige ausführbare Beispiele
Ausgabedatenströme registrierter Werkzeuge
createToolStreamParser ist ein portabler, begrenzter UTF-8-JSONL-/Textdecoder. Warten Sie für Rückdruck auf write(bytes, stdout/stderr) und rufen Sie finish erst auf, nachdem beide Datenströme beendet sind. Er bewahrt aufgeteilte Mehrbytezeichen und letzte unvollständige Zeilen und erzeugt korrelierte Log-, Fortschritts-, Diagnose- und unbekannte Ereignisse. Ungültiges UTF-8 und harte Grenzen stoppen das Parsen. Relative Diagnosepfade, geordnete Positionen und Schweregrade werden validiert; der verwendende Editor muss Positionen zusätzlich gegen den aktuellen Dokumenttext prüfen. createJobToolEventSink verbindet Fortschritt/Logs mit einem bestehenden JobReporter und überlässt Diagnosen einem Sink des Aufrufers.
Der optionale Node-Runner akzeptiert feste Betreiberregistrierungen: Backend/Tool/Version, absolute ausführbare Datei und ausgewählte festgelegte Implementierungen, exakte Versionsprüfung, ausdrückliche Umgebung, geschlossenes Eingabeschema und erforderliche skalare Argumentplätze. Dateiplätze müssen bestehende relative Workspace-Dateien benennen. Ein Plugin-Aufruf wählt nur ein bereits registriertes Tool/eine Version und validierte Eingaben; er kann keine Shell oder ausführbare Datei wählen. Aktuelle Autorisierung wird vor Vorbereitung/Start, bei Ereignissen und nach Abschluss geprüft. Nachweise behalten Exit-Code, Abbruch-/Fehlergrund und Ausgabestatistiken.
Bekannte einzeilige Geheimnis-/Pfadliterale werden nach dem Zusammensetzen der Zeilen maskiert, auch bei aufgeteilten Chunks; kodierte oder unbekannte Geheimnisse werden nicht automatisch erkannt. Der Runner kontrolliert nur seinen direkten Kindprozess und dessen Pipes und schließt sie bei Abbruch oder close. Er durchsucht oder beendet weder fremde noch nachgeordnete Prozessbäume und ist keine Betriebssystem-Sandbox. Grenzen: 64 KiB Chunks, 16 KiB Zeilen, insgesamt 2 MiB Ausgabe, 4.096 Ereignisse, acht wartende Schreibvorgänge, fünf Sekunden für Sinks, 32 Werkzeuge und vier gleichzeitige Ausführungen. Eine separate Prüfung mit fünf Sekunden/16 KiB prüft die konfigurierte Version.
Die vom SDK erstellte, weiterverteilbare Tool-Fixture testet fragmentiertes UTF-8/JSONL, nachlaufende Ausgabe, Exit-Codes ungleich null, Abbruch und Grenzen. Der tatsächliche Adapter ist TypeScript 5.9.3 mit --noEmit --noLib --pretty false und einer wegwerfbaren Fixture für intrinsische Typen, die TS2322 erzeugt. Stellen Sie ausdrücklich ein vorhandenes freigegebenes TypeScript-Root bereit, um ihn auszuführen. Das SDK installiert oder lädt niemals automatisch ein externes Tool herunter; bereitgestellte Hashes authentifizieren dessen Herausgeber nicht unabhängig.
Typen, API, Grenzen und vollständige ausführbare Beispiele
Öffentliche Stdio-LSP-Brücke
createLspBridge verbindet einen ausdrücklich freigegebenen, auf eine bestimmte Version festgelegten Stdio-Prozess mit bestehenden SDK-Sprachanfragen/-Providern. Es handelt die unterstützte LSP-3.17-Teilmenge, UTF-16-Positionen und vollständige Snapshots aus. capabilities meldet angekündigte Unterstützung getrennt von erfolgreichen Ausführungen. Unterstützte Zuordnungen umfassen Vervollständigung, Hover, Definition, Referenzen, flache/hierarchische Symbole, Signaturhilfe, prepare-rename/rename, Dokument-/Bereichsformatierung, Codeaktionen, vollständige semantische Tokens, Faltung und Inlay-Hinweise: 15 SDK-Funktionen.
syncDocument und closeDocument behandeln didOpen/didChange/didClose. Änderungen der aktuellen Version und Generation brechen veraltete Arbeit ab, doppelte aktive Request-IDs werden abgelehnt und verspätete Antworten ignoriert. Lokale URIs müssen ohne Links innerhalb des Workspace aufgelöst werden; Quell- und Bearbeitungsziele erfordern aktuelle Autorisierung und einen offenen oder vom Host bereitgestellten exakten Snapshot. Ergebnisse von Umbenennung/Formatierung/Aktionen sind bedingte Workspace-Edit-Vorschläge mit Basishashes, niemals automatisch angewendete Änderungen oder ausführbare Befehle.
Diagnosen werden nur mit der aktuellen Dokumentversion akzeptiert. Unversionierte/veraltete Benachrichtigungen werden verworfen und gezählt. Ausdrücklich nicht unterstützte Funktionen sind completion resolve/snippets, code-action resolve, semantische Deltas, Serverbefehle, dynamische Fähigkeiten, Ressourcenoperationen, Socket-Transporte und unversionierte Diagnosen. workspace/applyEdit liefert applied:false zurück. Grenzen: 1 MiB Nachrichten, 8 KiB Header, 64 MiB/20.000 Nachrichten je Sitzung, 16 ausstehende Anfragen und wartende Schreibvorgänge, 32 Dokumente/4 MiB gesamter Text, Anfragefristen bis 30 Sekunden und 64 KiB verworfenes stderr.
close sendet shutdown/exit und führt begrenzte Bereinigung des direkten Prozesses und der Pipes durch; dabei unterscheidet es reguläre Bestätigung, verweigernde/abgestürzte Server und tatsächliches Prozessende. Ein Server kann shutdown bestätigen und dennoch ein Stoppen des eigenen Prozesses erfordern. Es gibt keinen automatischen Neustart oder Replay: Der Betreiber erstellt eine neue Brücke und sendet ausgewählte aktuelle Snapshots ausdrücklich erneut. Synthetische Tests decken fehlerhafte Rahmung, Absturz/Zeitüberschreitung, Abbruch/verspätete Antworten, Dokumentrennen, verweigertes Herunterfahren, nicht unterstützte Anfragen und jede zugeordnete Funktion ab.
Die tatsächliche unabhängige Serverprüfung verwendet den Community-Server typescript-language-server 5.3.0 mit TypeScript 5.9.3: Vervollständigung, Hover, Definition, Referenzen, Symbole, Signaturhilfe, Formatierung und semantische Tokens bestanden die Prüfung. Ausgewählte Implementierungsdateien und Node sind festgelegt, der tsserver-Pfad ist fixiert und der automatische Bezug von Typdeklarationen deaktiviert. Diese Serverversion lässt das optionale initialize.serverInfo aus und sendet unversionierte Diagnosen; ihre Diagnosen sind daher von dieser Brücke ausdrücklich nicht unterstützt. Versionierte Diagnosen werden mit dem unabhängigen synthetischen Server geprüft. Der Betreiber muss dem gesamten installierten Tool und dessen Betriebssystemzugriff vertrauen.
Die 1.2-Abnahme umfasst unabhängige gepackte Consumer, Deklarationen, 107 Schemas, die tatsächlichen Compiler-/Serveradapter und Interoperabilität mit historischen öffentlichen Archiven. Das Workflow-Beispiel unterscheidet dauerhafte Wiederherstellung und ausdrückliche Wiederholung von automatischem Replay. Sicherheitsaudit und Schwachstellenprüfung stehen aufgrund der Verschiebung durch den Eigentümer weiterhin aus. Dieses Release stellt keine Abnahme für DDS-UI, Engine, Cloud-Scheduler, Marketplace, Installer oder Sicherheits-Sandbox dar.
Typen, API, Grenzen und vollständige ausführbare Beispiele
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.mjsFür tatsächliche Adapter fügen Sie absolute Pfade zu bestehenden, vom Betreiber freigegebenen Installationen hinzu. Standardbeispiele verwenden nur SDK-eigene Fixtures und laden niemals ein Tool herunter.
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