Schreiben Sie ein Assistenten-Tool-Plugin

Wählen Sie das Assistentenerweiterungsformat

Der Erweiterungslader des Produktionsassistenten akzeptiert ein Verzeichnis, das „plugin.json“ und einen gebündelten JavaScript-Eintrag enthält. Es importiert das Modul in einen Bun-Worker und stellt dem Assistenten deklarierte Funktionen aus seinem aiTools-Datensatz zur Verfügung. Die derzeit unterstützte Funktion ist ai:tool. In dieser Anleitung wird ein schreibgeschützter Lochkreisrechner erstellt, der Koordinaten zurückgibt. Es wird keine Geometrie in eine Zeichnung eingefügt.

Es gibt auch eine Browser-Plugin-ZIP-API unter /api/plugins mit manifest.json, main, Browserberechtigungen und Bootstrap-Assets. Dieses Installationsprogramm aktiviert das hier beschriebene Worker-Plugin nicht. Der plugin-HTTP-Referenz dokumente, die das Format trennen; Plugins erklärt beide Oberflächen. Übersetzen Sie nicht zwischen ihnen, indem Sie einfach ein Manifest umbenennen.

Ein Assistententool ist Code, der innerhalb der Laufzeitgrenze der Anwendung ausgeführt wird. Host-Fähigkeitsprüfungen begrenzen den Zugriff über Host-RPC, aber der aktuelle Worker ist keine Betriebssystem-Sandbox. Verwenden Sie Erweiterungscode, dessen Ausführung für diese Umgebung geeignet ist, und sorgen Sie dafür, dass das deklarierte Lese-/Schreibverhalten mit der tatsächlichen Funktion der Funktion übereinstimmt.

Erstellen Sie das Verzeichnis und den Einwilligungsdatensatz

Verwenden Sie das genaue Anwendungsdatenverzeichnis des Sidecars, das Sie erweitern möchten. Erstellen Sie diese Struktur und halten Sie dabei die Verzeichnis-ID identisch mit der Reverse-DNS-ID des Manifests:

<dataDir>/plugins/
  enabled.json
  com.example.bolt-circle/
    plugin.json
    index.js

Der Produktionslader liest „enabled.json“ als JSON-Array sicherer Bezeichner. Es ignoriert doppelte/ungültige Einträge und fehlerhaftes oder fehlendes JSON bedeutet, dass keine Plugins aktiviert sind. Ein nicht aufgeführter Ordner wird nicht geladen. Der Loader lehnt auch eine Nichtübereinstimmung zwischen Ordner und Manifest-ID sowie Manifeste ab, die nicht unterstützte Funktionen anfordern.

Der Ladevorgang erfolgt, wenn der Assistenten-Plugin-Dienst initialisiert wird. Es wird kein Dateisystem-Watcher für das Hot-Reload konfiguriert. Bereiten Sie zuerst die Dateien vor und validieren Sie sie, dann aktivieren/starten Sie diese Instanz neu. Ein fehlgeschlagenes Plugin protokolliert eine Warnung, während andere Plugins und der Anwendungsstart fortgesetzt werden. Überprüfen Sie diese Warnungen, anstatt davon auszugehen, dass ein aktivierter Dateieintrag garantiert, dass das Tool ausgeführt wird.

Erklären Sie einen genauen Werkzeugvertrag

Dieses vollständige Manifest benennt ein einzelnes Lesetool. Die Beitrags-ID ist die dem Modell zugewandte lokale Kennung. Der Eintrag benennt die vom Modul exportierte Funktion. Diese Zeichenfolgen können unterschiedlich sein, wie es hier bei „bolt_circle“ und „boltCircle“ der Fall ist.

{
  "id": "com.example.bolt-circle",
  "name": "Bolt circle calculator",
  "version": "1.0.0",
  "apiVersion": "1",
  "entry": "index.js",
  "capabilities": ["ai:tool"],
  "contributes": {
    "aiTools": [{
      "id": "bolt_circle",
      "description": "Calculate equally spaced XY hole centers around the origin for a bolt circle. Returns coordinates without changing a drawing.",
      "kind": "read",
      "entry": "boltCircle",
      "parameters": {
        "type": "object",
        "properties": {
          "count": { "type": "integer", "minimum": 1, "maximum": 64 },
          "radius": { "type": "number", "exclusiveMinimum": 0 }
        },
        "required": ["count", "radius"],
        "additionalProperties": false
      }
    }]
  }
}

Das SDK erfordert Reverse-DNS-IDs mit 3–128 Zeichen, eine semantische Major.Minor.patch-Version mit optionaler Vorabversion, eine API-Version „1“, einen nicht leeren Namen/Eintrag und erkannte Funktionen. Werkzeug-IDs beginnen mit einem Kleinbuchstaben und verwenden Kleinbuchstaben, Ziffern oder Unterstriche mit bis zu 40 Zeichen. Beschreibungen enthalten 10–2,000 Zeichen. Der Werkzeugtyp ist Lesen oder Schreiben; Es gibt keine destruktive Erweiterungsart.

Halten Sie das Parameterschema klein und beschreibend. Seine Aufgabe besteht darin, dem Modell dabei zu helfen, gültige Argumente zu generieren und dem Adapter zu ermöglichen, gewöhnliche Fehler vor der Ausführung zurückzuweisen. Es ersetzt nicht die Validierung innerhalb des Codes.

Implementieren Sie das eigenständige Modul

Der Eintrag exportiert aiTools mit der im Manifest genannten Eintragsfunktion. Es validiert Laufzeitargumente erneut und gibt ein kleines JSON-kompatibles Ergebnis zurück. Endliche Koordinatenarithmetik und begrenzte Zählung verhindern, dass fehlerhafte Eingaben eine unbegrenzte Liste oder eine bedeutungslose Ausgabe erzeugen.

export const aiTools = {
  boltCircle: async (args) => {
    if (!args || typeof args !== "object") {
      return { ok: false, error: "Expected count and radius" }
    }
    const { count, radius } = args
    if (!Number.isInteger(count) || count < 1 || count > 64) {
      return { ok: false, error: "count must be an integer from 1 to 64" }
    }
    if (typeof radius !== "number" || !Number.isFinite(radius) || radius <= 0) {
      return { ok: false, error: "radius must be a positive finite number" }
    }
    const holes = Array.from({ length: count }, (_, index) => {
      const angle = 2 * Math.PI * index / count
      return {
        x: Number((radius * Math.cos(angle)).toFixed(4)),
        y: Number((radius * Math.sin(angle)).toFixed(4))
      }
    })
    return { ok: true, units: "mm", holes }
  }
}

Count 4 and radius 10 return centers at approximately (10,0), (0,10), (−10,0), and (0,−10), in counter-clockwise order around the origin. The result deliberately contains no database mutation or drawing identifier. A client wanting to insert holes must use a separate supported application action with its own access and permission behavior.

Bündeln Sie Abhängigkeiten im Eintrag, anstatt davon auszugehen, dass relative Importe im Node-Stil aufgelöst werden. Der Host liest den Eintragstext und importiert ihn über ein Blob-Modul. Der Code der obersten Ebene des Moduls wird beim Import ausgeführt. Vermeiden Sie daher Nebenwirkungen, die allein durch das Laden eines Taschenrechners entstehen.

Validieren Sie das Manifest und beide Argumentpfade

Überprüfen Sie, bevor Sie das Plugin zu „enabled.json“ hinzufügen. Diese Entwicklungsprüfung verwendet denselben SDK-Manifest-Parser und AI-Schema-Adapter wie die Anwendung. Platzieren Sie das Skript in einem Arbeitsbereich mit diesen Abhängigkeiten, z. B. „apps/sidecar“, und übergeben Sie das absolute Plugin-Verzeichnis als Argument.

import { join } from "node:path"
import { Effect } from "effect"
import { parseManifest } from "@cadcamfun/plugin-sdk"
import { pluginParameters } from "@cadcamfun/ai"

const directory = process.argv[2]
if (!directory) throw new Error("Pass the absolute plugin directory")
const manifest = await Effect.runPromise(parseManifest(
  await Bun.file(join(directory, "plugin.json")).text()))
if (manifest.capabilities.some((capability) => capability !== "ai:tool")) {
  throw new Error("This production loader accepts only ai:tool")
}
const contribution = manifest.contributes?.aiTools?.[0]
if (!contribution) throw new Error("No tool contribution")
const parameters = pluginParameters(contribution.parameters)
console.log(parameters.safeParse({ count: 4, radius: 10 }).success) // true
console.log(parameters.safeParse({ count: 0, radius: 10 }).success) // false
const module = await import(join(directory, manifest.entry))
console.log(await module.aiTools[contribution.entry]({ count: 4, radius: 10 }))
console.log(await module.aiTools[contribution.entry]({ count: 0, radius: 10 }))

Die letzten beiden Aufrufe testen das Verhalten auf Funktionsebene unabhängig von der Adapterablehnung. Das SDK validiert die Manifeststruktur, aber der Produktionslader fügt seine eigenen Funktionen und Ordner-ID-Regeln hinzu. Testen Sie alle drei Grenzen: Deklaration, Argumentadapter und tatsächliche Modulfunktion.

Aktivieren und ermitteln Sie die tatsächliche Werkzeugkennung

Aktivieren Sie nach der Validierung die ID im Anwendungsdatenverzeichnis:

["com.example.bolt-circle"]

Starten/initialisieren Sie den vorgesehenen Sidecar-Dienst neu und überprüfen Sie die Protokolle auf Ladewarnungen. Dann auflisten GET /api/ai/actions. Lese-Plugin-Tools werden dort sowie dem eingebetteten Assistenten zur Verfügung gestellt; Die Richtlinie kann den Katalog einschränken. Die Tool-ID wird aus der Plugin-ID und der lokalen Tool-ID generiert, normalisiert und an die ID-Größe des Hosts gebunden.

Für dieses Manifest lautet die aktuelle abgeleitete ID plugin_com_example_bolt_circle_bolt_circle. Entdecken Sie es, anstatt die Namensregel in jedem Client neu zu implementieren. Eine lange Plugin-ID kann gekürzt werden, um Platz für das Tool-Suffix zu schaffen. Die Beschreibung des Katalogs enthält den Plugin-Namen, damit der Benutzer die Quelle identifizieren kann.

Ein Schreibwerkzeug ist im eingebetteten Assistenten für die menschliche Genehmigung markiert, unabhängig vom normalen Berechtigungsmodus. Die externe Bridge stellt nur Lese-Plugin-Tools zur Verfügung und lehnt Schreiberweiterungsaufrufe auch mit einem Lese-/Schreibtoken ab. Halten Sie die Art korrekt; Die Anwendung kann keine beliebigen Modulnebenwirkungen aus einem JSON-Schema ableiten.

Rufen Sie ein Lesetool über einen bereichsbezogenen externen Zugriff auf

Verwenden Sie einen von der Anwendung ausgegebenen Bridge-Token für ein reales Projekt. Sein Träger öffnet nur GET /api/ai/actions und POST /api/ai/actions/invoke. Es erlaubt Aufrufern nicht, Plugins zu installieren, Anmeldeinformationen zu bearbeiten oder nicht verwandte Projekte aufzulisten. Das Projekt/der Modus des Tokens wird vom Aktionshandler überprüft; Für einen eigenständigen Taschenrechner-Client ist ein anwendungsweites Token nicht erforderlich.

{
  "projectId": "replace-with-your-project-id",
  "tool": "plugin_com_example_bolt_circle_bolt_circle",
  "input": { "count": 4, "radius": 10 }
}

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @bridge-call.json \
  "$CADCAMFUN_URL/api/ai/actions/invoke"

Plugin-Eingaben sind das deklarierte Argumentobjekt; Im Gegensatz zu integrierten gruppierten Tools erfordert dieses Lese-Plugin keinen Aktionsdiskriminator innerhalb der Eingabe. Die Brücke umschließt den zurückgegebenen Wert mit Werkzeug-/Aktionsmetadaten. Die Aktion wird ausgeführt. Auf Funktionsebene bleibt ok=false ein lesbares Ergebnis und kein erfolgreicher HTTP-Transport, der eine nützliche Koordinatenliste beweist.

Die Bridge-Richtlinie prüft „tool.use“ und „bridge.use“. Ein fehlendes, abgelaufenes, widerrufenes oder falsches Token führt zu einem Autorisierungsfehler. Ein an ein anderes Projekt gebundenes Token ist keine Möglichkeit, den Umfang dieses Aufrufs zu erweitern.

Machen Sie sich mit der Schemakonvertierung und den Leistungsgrenzen vertraut

Der Adapter konvertiert das JSON-Schema des Beitrags in zod, wenn es darstellbar ist. Wenn die Konvertierung fehlschlägt, das Schema mehr als 20,000 serialisierte Zeichen aufweist oder kein Objekt beschreibt, wird auf ein Schema für beliebige Objekte zurückgegriffen. Aus diesem Grund prüft die Beispielfunktion selbst Anzahl und Radius. Die lokale Übergabe der negativen Fixture eines unterstützten Schemas beweist nicht, dass alle Schemafunktionen darstellbar bleiben.

Das SDK erkennt Drawing:Read, Drawing:Write, Toolpath:Read, Storage, UI:Panel und Ai:Tool. Das Zeichnen des Schreibens impliziert das Zeichnen des Lesens. Der Production Assistant Loader akzeptiert derzeit nur ai:tool. Das Hinzufügen von „drawing:write“ zu diesem Manifest führt dazu, dass es übersprungen wird und kein Zeichnungseditor-Kontext gewährt wird.

Der allgemeine Worker-Bootstrap enthält Platzhalter-Zeichnungs-/Werkzeugweg-/UI-Handler. Bei diesen Handlern handelt es sich nicht um eine Integration der Produktionsgeometrie. Ebenso führt die Deklaration von Postprozessor- oder Betriebsbeiträgen nicht dazu, dass der Hilfslader diese in Fertigungsregistern verdrahtet. Wählen Sie eine unterstützte Anwendungsaktion, wenn die Funktion echte CAD/CAM-Daten ändern muss.

Entwerfen Sie rund um den implementierten Worker-Lebenszyklus

Das SDK beschreibt ein Modul mit Manifest-, Aktivierungs-, optionalen Bereinigungs- und Deaktivierungs-Hooks. Der aktuelle Produktions-KI-Pfad importiert den Eintrag und ruft exportierte aiTools-Funktionen auf. Seine Worker-Aktivierungs-/Deaktivierungs-RPC-Handler bestätigen Lebenszyklusmeldungen, rufen jedoch keine exportierten Modul-Hooks auf. Ein Rechner kann daher das hier gezeigte Minimalmodul nutzen, ohne auf Aktivierungsrückrufe angewiesen zu sein.

Der Host startet einen Worker pro aktiviertem Plugin, korreliert Antworten mit RPC-IDs und verfolgt ausstehende Anrufe. Eine Funktionsausnahme schlägt diesen Aufruf fehl; Gezielte Tests an echten Mitarbeitern zeigen, dass spätere Anrufe immer noch erfolgreich sein können. Geben Sie strukturierte Ablehnungen für erwartete ungültige Eingaben zurück und reservieren Sie ausgelöste Fehler für unerwartete Berechnungsfehler.

Ein Aufruf-Timeout beendet seinen Worker und verursacht sofort einen Fehler im Plugin. Worker-Abstürze und Posting-Fehler entfernen auch die laufende Instanz und markieren sie als fehlerhaft. Der Absturzverlauf hat ein Zehn-Minuten-Fenster, aber der aktuelle Handler gibt beim ersten Absturz einen Fehler aus; es wartet nicht auf drei erfolgreiche Neustartversuche. Korrigieren Sie die Quelle und laden Sie sie bewusst neu/aktivieren Sie sie erneut, anstatt von einem automatischen Neustart auszugehen.

Halten Sie die Laufzeitgarantien im Verhältnis

Der Produktionslader stellt ein 10-Sekunden-Hostbudget für gewöhnlichen Lebenszyklus-/Befehls-RPC bereit. Für KI-Tool-Aufrufe gilt eine separate Frist von 30 Sekunden. Der Host begrenzt ein Plugin auf 2,000 Anrufe pro Minute und 64 ausstehende Anrufe. Beim Erstellen des Workers wird eine Ressourcenlimiteinstellung von 256 MB an Bun übergeben. Hierbei handelt es sich um Laufzeitkontrollen, nicht um eine separate Prozess- oder Betriebssystem-Eindämmungsrichtlinie.

Der Bootstrap beginnt mit einer leeren Umgebung und versucht, ausgewählte Prozess-/Netzwerk-Globals zu löschen. Das Löschen ist die beste Lösung und einige Bun-Globals bleiben weiterhin erreichbar. Die Fähigkeitsprüfung ist daher für die vom Host bereitgestellten APIs von Bedeutung, kann jedoch nicht als vollständige Isolierung von beliebigem JavaScript dargestellt werden.

Im Manifestschema sind optionale Signatur- und Entwicklungsfelder vorhanden. Der aktuelle Worker-Installationspfad zeichnet Signaturtext ohne kryptografische Überprüfung auf. Kennzeichnen Sie einen Herausgeber nicht als verifiziert, da dieses Feld vorhanden ist. Eine eigenständige Quellüberprüfung und Installationsrichtlinie bleiben getrennte Entscheidungen von der Schemaakzeptanz.

Plugins, die innerhalb von zehn Minuten dreimal abstürzen, werden automatisch deaktiviert und ein Aufruf des Assistententools wird nach 30 Sekunden gestoppt. Beide Werte sind Konstanten in apps/sidecar/src/plugins/host.ts.

Aktualisieren, entfernen und diagnostizieren Sie ein Tool

Bearbeiten und validieren Sie für ein Update das gebündelte Modul/Manifest, bevor Sie den Zieldienst neu starten. Halten Sie die ID stabil, wenn es sich um dieselbe Erweiterung handelt, und erhöhen Sie die Version, um zu identifizieren, was geladen wurde. Um das Laden bei einer zukünftigen Initialisierung zu stoppen, entfernen Sie seine ID aus „enabled.json“ und starten/initialisieren Sie es neu. Das alleinige Ändern der Datei führt nicht dazu, dass ein bereits ausgeführter Worker gelöscht wird.

Wenn das Tool fehlt, überprüfen Sie das aktivierte Array, die genaue Ordner-/Manifest-ID-Gleichheit, die Liste der unterstützten Funktionen und den Manifest-Dekodierungsfehler in den Protokollen. NoSuchTool bedeutet normalerweise, dass der Eintrag eine exportierte aiTools-Funktion nicht benennt. Eine Argumentverweigerung verweist auf den Schema- oder Funktionswächter. Eine Zeitüberschreitung weist auf eine blockierende Arbeit oder ein ungelöstes Versprechen hin. Die ZIP-Enable/Config-Endpunkte des Browsers verwalten diese Worker-Zustimmungsdatei nicht.

Fokussierte Berichterstattung ist angesagt apps/sidecar/test/plugins-ai-tools.test.ts für tatsächliche Arbeitnehmer und ai-plugin-tools.test.ts für Produktionsladen, Argumentvalidierung, Lese-/Schreibfreigabe und Bridge-Verhalten. Implementierungsquellen sind packages/plugin-sdk/src/manifest.ts, packages/ai/src/tools/plugin-tool.ts, apps/sidecar/src/plugins/host.ts, und services/ai-plugins.ts. Nutzen Sie diese Grenzen, um zu bestimmen, was ein erfolgreicher Test tatsächlich bewiesen hat.

Vertragsregeln auf einen Blick

Schreiben Sie die Beschreibung für das Modell. Geben Sie an, was das Tool berechnet, welche Einheiten es hat und wann es verwendet werden soll. Beispiel: „Gibt die Lochmitten eines Lochkreises in Millimetern zurück. Verwenden Sie diese Option, wenn der Benutzer gleichmäßig verteilte Löcher auf einem Durchmesser anfordert.“ Ungenaue Beschreibungen führen dazu, dass Tools zum falschen Zeitpunkt oder gar nicht aufgerufen werden.

Checkliste vor der Veröffentlichung

1. Bündeln Sie den Eintrag in einem einzigen, eigenständigen Modul. Der Worker kann Arbeitsbereichsimporte nicht zur Laufzeit auflösen.
2. Laufen parseManifest auf das Finale plugin.json und jedes gemeldete Problem beheben.
3. Rufen Sie jede exportierte Toolfunktion direkt mit gültigen, Grenz- und ungültigen Argumenten auf und bestätigen Sie, dass ungültige Eingaben zu einem lesbaren Fehlerergebnis und nicht zu einer entkommenen Ausnahme führen.
4. Halten Sie die Ergebnisse klein und JSON-kompatibel. Der Assistent liest sie vor, und große Ausgaben verdrängen den Kontext.
5. Wählen read es sei denn, das Tool ändert etwas. A write das Tool fordert den Benutzer vor jedem Anruf auf.
6. Legen Sie den Ordner darunter <data dir>/plugins/<id>/, fügen Sie die ID hinzu enabled.json, starten Sie den Sidecar neu und bestätigen Sie die abgeleitete Werkzeug-ID aus der Werkzeugliste des Assistenten.
7. Stoßen version für jede Änderung, die Sie versenden und behalten id stabil, sodass sich die abgeleitete Werkzeug-ID nicht ändert.

Fehlerbehebungsmatrix

Erstellen Sie vor der Installation ein Manifest

import { decodeManifest, requestedCapabilities } from "@cadcamfun/plugin-sdk"
import { Effect } from "effect"

const raw = JSON.parse(await Bun.file(process.argv[2] ?? "plugin.json").text())
const manifest = await Effect.runPromise(decodeManifest(raw))   // throws a SchemaError naming the bad field
console.log(manifest.id, manifest.version, requestedCapabilities(manifest))
for (const tool of manifest.contributes?.aiTools ?? [])
  console.log(`plugin_${manifest.id}_${tool.id}`, tool.kind)

In 3D