Plugins

Wählen Sie die Erweiterungsfläche

@cadcamfun/plugin-sdk definiert den Worker-Plugin-Vertrag mit a plugin.json manifest und API-Version 1. Sein Host stellt funktionsgesteuerte Dienste bereit und führt Plugin-Funktionen in Bun-Workern aus. Der Produktionsassistent-Loader akzeptiert derzeit nur Plugins, die eine Anfrage stellen ai:tool.

Der /api/plugins Die HTTP-Familie verwendet einen anderen Browser-Plugin-Vertrag: ZIP-Pakete mit manifest.json, a main eintrag, Browserberechtigungen, Konfiguration und JavaScript-Bootstrap. Durch die Installation eines Pakets über diese API wird es nicht zu einem Worker-SDK-Plugin. Verwenden Sie das Manifest und den Lebenszyklus, die zur beabsichtigten Integration passen.

Worker-SDK-Manifest

{
  "id": "com.example.shop-helper",
  "name": "Shop helper",
  "version": "1.0.0",
  "apiVersion": "1",
  "entry": "index.js",
  "capabilities": ["ai:tool"],
  "contributes": {
    "aiTools": [{
      "id": "lookup",
      "description": "Look up the shop's documented inspection checklist.",
      "kind": "read",
      "parameters": { "type": "object", "properties": {} },
      "entry": "lookup"
    }]
  }
}

Identifikatoren verwenden eine Reverse-DNS-Form, die Version ist semantisch major.minor.patch mit einer optionalen Vorabversion und apiVersion muss sein "1". Eintragspfade sind relativ zum Plugin-Verzeichnis. Beiträge können Befehle, Panels, Postprozessoren, Operationen und Hilfstools deklarieren; Durch die Deklaration eines Beitrags wird diese Funktion nicht in jedem Host verankert.

Das Schema erlaubt optional signature und dev felder. Der aktuelle Worker-Host zeichnet diese Werte auf, führt jedoch während der Installation keine Überprüfung der kryptografischen Signatur durch. Ein Signaturfeld allein ist kein Beweis für einen verifizierten Herausgeber.

Moduleinstieg und KI-Funktionen

definePlugin ist ein typisierter Identitätshelfer für ein Modul mit einem Manifest und activate(ctx). Durch die Aktivierung wird möglicherweise eine Bereinigungsfunktion zurückgegeben und das Modul wird möglicherweise verfügbar gemacht deactivate. Das SDK beschreibt diese Lebenszyklus-Hooks; Ihre Verfügbarkeit hängt vom konkreten Worker-Bootstrap ab, wie unten beschrieben.

Assistentenfunktionen werden über exportiert aiTools aufzeichnen; der Beitrag entry benennt die Funktion in diesem Datensatz. Ein Tool-Beitrag umfasst seine Beschreibung, das JSON-Parameterschema und read oder write art. Ein Schreibtool wird über eine menschliche Genehmigungsanfrage im eingebetteten Assistenten weitergeleitet; Eine externe Bridge erhält nur zulässige Lese-Plugin-Tools.

Bündeln Sie den Worker-Eintrag als eigenständiges Modul. Der Worker-Host liest die Eintragsquelle und importiert sie über ein Blob-Modul. Behandeln Sie relative Paket- oder Dateiimporte als separates Integrationsproblem, anstatt von einem Dateisystemlader im Node-Stil auszugehen.

Fähigkeitsgesteuerte APIs

Das SDK erkennt drawing:read, drawing:write, toolpath:read, storage, ui:panel, und ai:tool. Zeichnendes Schreiben impliziert zeichnendes Lesen. Der allgemeine Host leitet effektive Funktionen aus dem installierten Manifest ab und überprüft sie auf RPC. Die Einbettungsanwendung entscheidet, welche Manifeste und Oberflächen sie laden möchte.

Der SDK-Kontext kann Zeichnungslesevorgänge und Add/Update/RemoveEntity-Patches, Werkzeugpfad-/Programmlesevorgänge, private Zeichenfolgen-Schlüsselwertspeicherung und deklarative Befehls-/Bedienfeldregistrierung verfügbar machen. Fehlende Dienste fehlen im Kontext. Verwendung von Speicherschlüsseln plugin:<id>: namespaces und lehnen absolute oder übergeordnete Schlüssel ab.

Der Produktionsassistent-Lader unterstützt nur ai:tool. Ein Manifest, das nach Zeichnungs-, Werkzeugweg-, Speicher- oder UI-Funktionen fragt, wird mit einer Warnung übersprungen. Diese Oberflächen werden nicht stillschweigend gewährt oder ihre umfassenderen Funktionen in den Assistenten-Host geladen.

Laden und Worker-Lebenszyklus

Um eine Assistentenerweiterung zu aktivieren, platzieren Sie diese plugin.json und gebündelter Eintrag unten <dataDir>/plugins/<id>/ und listen Sie die Kennung auf <dataDir>/plugins/enabled.json, ein JSON-Array. Die Ordnerkennung muss mit dem Manifest übereinstimmen. Das Laden erfolgt, während der Assistent-Plugin-Dienst erstellt wird. Ein fehlgeschlagenes Plugin protokolliert eine Warnung, ohne die Anwendung zu stoppen.

Der allgemeine Host unterstützt die Zustände „installiert“, „aktiviert“, „deaktiviert“ und „Fehler“ mit Installations-, Aktivierungs-, Deaktivierungs-, Deinstallations-, Befehlsaufruf-, AI-Tool-Aufruf- und Konfigurationsvorgängen. Enable erstellt einen Worker und schließt seinen Bootstrap-Handshake ab; Deaktivieren reißt es ab. Durch die Deinstallation werden der Registrierungsstatus und der Speichernamespace über die injizierten Abhängigkeiten des Hosts entfernt.

Worker beginnen mit einer leeren Umgebung und der Bootstrap entfernt ausgewählte globale APIs. Hierbei handelt es sich um eine Einschränkung auf Anwendungsebene, nicht um eine Betriebssystem-Sandbox: Bun-Globals bleiben erreichbar. Aktivieren Sie nur Erweiterungscode, der für die Ausführung innerhalb der Anwendungsprozessgrenze geeignet ist.

Laufzeitbegrenzungen

Der Host definiert eine Arbeitsspeichereinstellung von 256 MB, ein Ratenlimit von 2,000-Anrufen pro Minute und höchstens 64 ausstehende Anrufe pro Plugin. Das Befehls-Timeout-Verhalten wird vom einbettenden Host bereitgestellt. Der Ladeassistent benötigt 10 Sekunden. Für KI-Tool-Aufrufe gilt eine separate Frist von 30 Sekunden. Zeitüberschreitungen, fehlende Tools, Worker-Abstürze, Funktionsausfälle und Warteschlangenerschöpfung führen zu typisierten Hostfehlern oder lesbaren Tool-Ergebnissen.

Bei der Absturzverfolgung wird ein Plugin nach drei Abstürzen innerhalb von zehn Minuten fehlerhaft. Dieser Host steuert das gebundene kooperative RPC- und Lebenszyklusverhalten. Die an Bun übergebene Speichereinstellung ist kein Ersatz für eine separat isolierte ausführbare Datei.

Die Grenzen sind in definiert apps/sidecar/src/plugins/host.ts: CALL_TIMEOUT_MS (5,000 ms pro gewöhnlichem Anruf), AI_TOOL_TIMEOUT_MS (30,000 ms pro Aufruf des Assistententools), MEMORY_LIMIT_MB (256), CALL_RATE_LIMIT (2,000 Aufrufe pro Plugin pro Minute), MAX_PENDING_CALLS (64), und CRASH_LIMIT (3 stürzt innerhalb einer 10-Minute ab CRASH_WINDOW_MS, danach wird das Plugin automatisch deaktiviert).

ZIP-Installation und Browser-Plugin-API

POST /api/plugins/install akzeptiert ein mehrteiliges Archiv. Der Installer liest manifest.json aus dem ZIP-Stammverzeichnis oder einem einzelnen Verzeichnis der obersten Ebene, validiert das Browser-Plugin-Manifest und speichert seine Dateien darunter <dataDir>/storage/plugins/<id>/. Verwendung von Browsermanifesten main, engines.cadcamund eine Browser-Berechtigungsliste anstelle eines SDK entry, apiVersionund Fähigkeiten.

GET /api/plugins listet die installierten Einträge auf; detail, enable/disable, uninstall, update, and configuration endpoints operate on their registry. /api/plugins/bootstrap.js?id=… dient JavaScript; /api/plugins/serve?id=…&file=… stellt Plugin-Dateien bereit. Dies sind Text-/Binäroperationen mit ihren deklarierten Inhaltstypen.

Der lokale Registrierungsbrowser liest die Paketmetadaten darunter <dataDir>/plugins-registry. Es handelt sich um einen lokalen Manifestkatalog. Die Archivinstallation, die Registrierungsliste und das Laden der Worker Assistant-Erweiterung sind separate Vorgänge.

SDK-Helfer

effectiveCapabilities, hasCapability, und missingCapabilities überprüfung der Supportfähigkeit. requireCapability löst einen Fähigkeitsfehler aus, wenn eine angeforderte Kontextoberfläche fehlt. storageNamespace und storageKey namensraumschlüssel erstellen; parseManifest validiert JSON; manifestKey formatiert ein ID/Version-Paar.

Einstiegspunkte für die Implementierung

packages/plugin-sdk/src besitzt die öffentlichen Manifest-, Funktions-, Kontext-, Plugin- und Testhost-APIs. apps/sidecar/src/plugins/host.ts besitzt Worker-Lebenszyklus und RPC; services/ai-plugins.ts ist für das Laden der Einwilligungsdatei und die Assistentenregistrierung zuständig. Die Browserinstallation ist in implementiert http/plugins.ts und repos/plugin-registry-repo.ts.

Überprüfung der Erweiterung

Halten Sie die Beitragsschemata korrekt, geben Sie kleine strukturierte Ergebnisse zurück und geben Sie das Lese-/Schreibverhalten ehrlich an. Testen Sie mit dem tatsächlichen Einbettungshost: Die SDK-Verfügbarkeit stellt keinen Produktionszugriff auf Zeichnung, Speicher, Benutzeroberfläche oder Post-Registrierungen her. Der eigenständiges Nikcli-Plugin ist ein HTTP-Aktionsclient und hat einen anderen Zweck als in einen Worker geladener Code.

Füllen Sie das Beispiel-Assistentenmodul aus

Der plugin.json beispiel oben Namen aiTools.lookup. Dies ist die entsprechende Eigenständigkeit index.js. Der Modulcode der obersten Ebene wird beim Import ausgeführt. Die deklarierte Suchfunktion wird ausgeführt, wenn sie aufgerufen wird.

export const aiTools = {
  lookup: async () => ({
    ok: true,
    checklist: [
      "Compare the drawing revision with the job traveller.",
      "Record the measuring instrument and its calibration status.",
      "Record each inspected dimension and the measured value."
    ]
  })
}

Hierbei handelt es sich um Beispiel-Werkstattanweisungen, nicht um einen integrierten Prüfstandard. Ersetzen Sie sie durch den Inhalt, der Ihrer Erweiterung tatsächlich gehört. Um dieses Modul bei der nächsten Dienstinitialisierung zuzulassen, lautet die aktivierte Datei:

["com.example.shop-helper"]

Der laufende Katalog stellt eine von Plugin- und Tool-IDs abgeleitete Kennung bereit. Entdecken Sie es durch GET /api/ai/actions; gehen Sie nicht davon aus, dass die ZIP-Registrierung des Browsers die aktivierte Liste des Assistenten ist. Das Neuladen der Anwendung/des Dienstes ist die zuverlässige Möglichkeit, die Produktionseinwilligungsdatei erneut zu lesen. Von diesem Loader wird kein Dateisystem-Watcher konfiguriert.

Quelle: apps/sidecar/src/services/ai-plugins.ts, packages/ai/src/tools/plugin-tool.ts, und apps/sidecar/test/ai-plugin-tools.test.ts.

Argumentschemata und Lebenszyklusgrenzen

Die lokale ID eines Tools muss mit einem Kleinbuchstaben beginnen und Kleinbuchstaben, Ziffern oder Unterstriche enthalten, maximal jedoch 40-Zeichen. Beschreibungen enthalten 10–2,000 Zeichen. Der Beitrag muss eine nicht leere Eintragsfunktion und ein JSON-Parameterschema benennen. Der Anwendungsadapter validiert Argumente, bevor er den Worker aufruft. Eine Ablehnung kann eine strukturierte Rückgabe hervorrufen ok: false ergebnis, ohne das Plugin zu beenden.

Das öffentliche SDK beschreibt activate, aufräumen und deactivate einstiegspunkte. Die Aktivierungs-/Deaktivierungs-RPC-Handler des aktuellen Bun-Worker-Bootstraps bestätigen Lebenszyklusmeldungen, rufen diese exportierten Modulfunktionen jedoch nicht auf. Assistentenerweiterungen sollten daher ihr aufrufbares Verhalten einbinden aiTools und vermeiden Sie abhängig von der SDK-Aktivierung Rückrufe für die Einrichtung oder Bereinigung.

Der allgemeine Worker-Bootstrap enthält auch Platzhalter-Zeichnungs-/Werkzeugweg-/UI-Handler. Sie stellen keine Produktionszeichnung oder UI-Integration dar. Die Beschränkung des Hilfsladers auf ai:tool verhindert, dass diese nicht unterstützten Oberflächen als funktionierender Anwendungszugriff angekündigt werden.

Quelle: packages/plugin-sdk/src/manifest.ts, plugin.ts, apps/sidecar/src/plugins/host.ts (PLUGIN_BOOTSTRAP), und services/ai-plugins.ts.

Diagnostizieren Sie eine fehlende oder fehlerhafte Erweiterung

• Keine Werkzeuge im Katalog: überprüfen Sie den gültigen aktivierten JSON, die genaue Übereinstimmung von Ordner/Manifest-ID, die Manifest-Dekodierung und die ai:tool fähigkeit. Lesen Sie die Startwarnung für ein übersprungenes Plugin.
• Manifest fordert nicht unterstützte Oberflächen an: entfernen Sie nicht unterstützte Funktionen nur, wenn der Code sie wirklich nicht benötigt. Ein Assistenten-Plugin kann keinen Zeichen-/Schreibzugriff erhalten, indem es ihn einfach deklariert.
• NoSuchTool: machen contributes.aiTools[].entry einer exportierten Funktion unter entsprechen aiTools. Die Beitrags-ID und der Eintragsname dienen unterschiedlichen Zwecken.
• Fehler bei der Argumentvalidierung: überprüfen Sie das JSON-Schema und die erforderlichen Felder. Falsche Werte werden vor der Ausführung zurückgewiesen, wie die Real-Worker- und Anwendungsintegrationstests zeigen.
• Zeitüberschreitung oder fehlerhafter Zustand: untersuchen Sie blockierende Arbeiten, ungelöste Versprechen oder Abstürze. Wiederholte Abstürze beeinträchtigen das Plugin. Erst nach Behebung der Ursache wieder aktivieren.
• ZIP-Installer lehnt das Manifest ab: verwenden Sie das Browser-Plugin manifest.json vertrag für diesen Endpunkt. Umbenennen eines Arbeiters plugin.json übersetzt seine Felder nicht.

Quelle: apps/sidecar/test/plugins-ai-tools.test.ts, ai-plugin-tools.test.ts, plugins-http.test.ts, und src/plugins/host.ts.

Manifest-Referenz

Jedes Plugin enthält eine plugin.json. parseManifest(json) analysiert und validiert es in einem Schritt und wandelt einen JSON-Syntaxfehler in denselben Fehlerkanal wie einen Schemafehler um, sodass ein Installationsbildschirm nur einen Fehlertyp behandeln muss.

Helfer: manifestKey(m) kehrt zurück id@version; requestedCapabilities(m) gibt die sortierte Fähigkeitsliste zur Anzeige zurück; isDevPlugin(m) und isSigned(m) beantworten Sie die Fragen zu den Installationsrichtlinien.

Funktionen und der Plugin-Kontext

Funktionen sind das Einzige, durch das ein Plugin agieren kann. Das Manifest deklariert, was das Plugin benötigt, der Benutzer gewährt eine Teilmenge und der Host erstellt einen Kontext, der genau die gewährten Oberflächen enthält. Jede Oberfläche ist im Typ optional, sodass eine fehlende Funktion sowohl zur Kompilierungszeit als auch zur Laufzeit sichtbar ist und nicht zu einem stillen No-Op wird.

Testen Sie ein Plugin mit dem SDK-Testhost

import { cad } from "@cadcamfun/core"
import { createTestHost, definePlugin, requireCapability, testManifest } from "@cadcamfun/plugin-sdk"

const manifest = testManifest({
  id: "com.example.frame",
  capabilities: ["drawing:write", "storage", "ui:panel"],
})

const plugin = definePlugin({
  manifest,
  activate(ctx) {
    const drawing = requireCapability(ctx, "drawing:write", "drawing")
    ctx.ui?.registerCommand({ id: "frame.add", title: "Add frame line" })
    ctx.storage?.set("runs", "1")
    drawing.patch({
      _tag: "AddEntity",
      entity: { ...cad.baseEntity("frame-1"), _tag: "Line",
                start: { x: 0, y: 0 }, end: { x: 100, y: 0 } },
    })                                   // returns revision 1
    return () => ctx.log.info("teardown") // runs on deactivation
  },
})

const host = createTestHost({ manifest, drawing: cad.emptyDrawing("d1", "Demo") })
const stop = await host.activate(plugin)
host.drawing()?.entities.length     // 1
host.context.storage?.get("runs")   // "1"
host.ui.commands                    // [{ id: "frame.add", title: "Add frame line" }]
await stop()

// Without the grant, requireCapability throws:
const denied = createTestHost({ manifest, granted: ["storage"] })
await denied.activate(plugin)
// CapabilityError: Plugin com.example.frame may not use "drawing:write":
// it was not granted at install time

• testManifest(overrides) beginnt mit einem minimal gültigen Manifest (com.example.test-plugin, version 1.0.0, API 1, Eintrag index.js, keine Fähigkeiten).
• granted standardmäßig alles, was das Manifest verlangt. Übergeben Sie eine kleinere Liste, um die abgelehnten Pfade zu testen.
• host.storage ist ein Snapshot, der beim Erstellen des Hosts erstellt wird. Live-Werte durchlesen host.context.storage.
• host.on(commandId, handler) und host.invoke(commandId, args) registrierte Befehle ausführen.
• runPostProcessor führt einen beigesteuerten Beitrag für ein Programm aus und keyOf(pluginId, key) zeigt den Namespace-Speicherschlüssel an, damit Tests die Isolation bestätigen können.

Wie die Anwendung Assistenten-Plugins lädt

1. Beim Start lautet der Sidecar <data dir>/plugins/enabled.json, ein JSON-Array von Plugin-IDs. Es wird nichts geladen, es sei denn, es ist dort aufgeführt.
2. Für jede ID lautet es <data dir>/plugins/<id>/plugin.json und analysiert es. Der Ordnername muss mit dem Manifest übereinstimmen id.
3. Nur ai:tool ist in diesem Host verkabelt. Ein Manifest, das nach Zeichnung, Werkzeugweg, Speicher oder UI-Zugriff fragt, wird mit einer Warnung übersprungen und nicht mit Oberflächen geladen, die stillschweigend nichts tun würden.
4. Das Plugin wird auf einem Worker-Host installiert und aktiviert. Ein Plugin, das keine Protokolle laden kann Plugin <id> was not loaded: ... und stoppt nie den Start der Anwendung.
5. Jedes beigesteuerte Tool wird dem Assistenten als angeboten plugin_<slug of plugin id>_<tool id>, höchstens 80 Zeichen, wobei der Slug die ID in Kleinbuchstaben schreibt und andere Zeichen durch Unterstriche ersetzt. com.example.bolt-circle mit Werkzeug bolt_circle wird plugin_com_example_bolt_circle_bolt_circle.
6. Argumente werden anhand des JSON-Schemas des Tools validiert, bevor der Worker sie sieht. Wenn das Schema mehr als 20,000 Zeichen umfasst, kein Objektschema ist oder nicht konvertiert werden kann, akzeptiert der Host jedes Objekt und das Plugin muss validieren.
7. Ein Aufruf, der einen Fehler auslöst, eine Zeitüberschreitung verursacht oder feststellt, dass das Plugin nicht mehr vorhanden ist, wird zurückgegeben { ok: false, error } (fehlertext bis zu 500 Zeichen) an den Assistenten senden, anstatt den Zug zum Absturz zu bringen. A write das Tool wird vor jedem Anruf mit der Person bestätigt, unabhängig von den Argumenten.

Identifier- und Versionsregeln, getestet

Beitragsarten

Andere Manifestfelder: signature (Ed25519 über den Archiv-Hash, erforderlich für Paketinstallationen) und dev (lokales Entwicklungs-Plugin: überspringt Signaturprüfungen und zeigt ein Abzeichen an).

Fähigkeitsauflösung, getestet

import { effectiveCapabilities, missingCapabilities, storageKey, requireCapability } from "@cadcamfun/plugin-sdk"

effectiveCapabilities(["drawing:write", "storage"])
// ["drawing:read", "drawing:write", "storage"]   (write implies read; sorted)

missingCapabilities(["drawing:read", "toolpath:read", "ai:tool"], ["drawing:write"])
// ["toolpath:read", "ai:tool"]

storageKey("com.example.gear", "presets/m2")   // "plugin:com.example.gear:presets/m2"
storageKey("com.example.gear", "../x")
// RangeError: storage key "../x" may not escape the plugin namespace   (same for "/abs")

requireCapability(ctxWithoutDrawing, "drawing:read", "drawing")
// CapabilityError (_tag "CapabilityDenied"):
// Plugin com.example.gear may not use "drawing:read": it was not granted at install time

In 3D