KI-Assistent

Assistenzdienste

@cadcamfun/ai bietet Modellzugriff, Konversationsereignisse, den Aktionskatalog, Eingabeaufforderungen, Fertigkeiten, Kontextassemblierung und Hostintegration. Die Standard-Konversations-Engine ist eingebettetes Nikcli. AI SDK v7 bietet direkte Text-, Streaming- und strukturierte Ausgabeaufrufe. Der Sidecar fügt Handler für Projektmutationen, Bibliotheken, Verlauf und Anwendungsspeicher ein.

Chat kann ein Projekt durch registrierte Aktionen überprüfen und ändern. Zustandslose Titelgenerierung, Designanalyse, Parameterempfehlungen, G-Code-Optimierung und Zusammenfassungen von Designvorschlägen geben Ratschläge oder strukturierte Ausgaben zurück; Diese Dienstmethoden speichern keine Projektänderungen. Überprüfen Sie die generierten Bearbeitungsempfehlungen durch deterministisches CAM und Verifizierung, bevor Sie sich darauf verlassen.

Gespräche und Sitzungskontrollen

POST /api/ai/chat/stream gibt typisierte Ereignisse für Text, Begründung, Turn-/Schrittstatus, Werkzeugaufrufe und -ergebnisse, Diagnosen, Fragen, Berechtigungsanfragen, Wiederholungsversuche, Kontextänderungen, Ziele, Abschluss und Fehler aus. Client-Sitzungs-IDs sind an Host-Sitzungen gebunden und werden anhand ihres Projekts überprüft. Behalten Sie die Sitzungs-ID bei, um das gleiche Gespräch fortzusetzen.

POST /api/ai/sessions/state stellt den Besetztstatus, den angesammelten Text und die Aufgabeninformationen nach einem getrennten Stream wieder her. /api/ai/chat/queue gibt eine Fortsetzung eines aktiven Gesprächs zu; /api/ai/chat/abort stoppt die Runde und die damit verbundenen Arbeiter. Durch das Entfernen einer Sitzung werden die untergeordneten Sitzungen abgebrochen und zusammengeführt, bevor die Hostsitzung entfernt wird.

/api/ai/sessions/control supports status, detailed context inspection, compaction, memory consolidation, task cancellation, permission decisions, and answering or rejecting pending questions. Anfragen werden mit der übergeordneten Konversation und den zugelassenen untergeordneten Sitzungen abgeglichen. Eine Frage, die nicht mehr offen ist, kann nicht durch die Wiederverwendung ihrer alten Kennung beantwortet werden.

Direkte Modellaufrufe wiederholen vorübergehende Anbieterausfälle mit der gleichen Kurve wie nikcli: Die erste Verzögerung beträgt 2 Sekunden und verdoppelt sich bei jedem Versuch, dem eigenen eines Anbieters retry-after der Header wird berücksichtigt, und ohne einen solchen Header überschreitet die Verzögerung niemals 30 Sekunden. Standardmäßig führt eine Anfrage höchstens fünf Aufrufe durch, einschließlich des ersten; Die retryAttempts die Einstellung kann dies überschreiben (packages/ai/src/retry.ts, direct-model.ts). Wenn die Modellverbindung mitten in der Runde unterbrochen wird, wird die Chat-Schleife bis zu fünf Mal mit demselben Backoff von 2–30 Sekunden fortgesetzt und fordert das Modell auf, fortzufahren, ohne abgeschlossene Schritte zu wiederholen.

Anbieter und Referenzen

GET /api/ai/providers listet Anbietermetadaten und konfigurierten Status auf; GET /api/ai/models macht den Modellauswahlkatalog mit optional verfügbar configuredOnly=true. Lesevorgänge im eingebetteten Hostkatalog werden eine Minute lang zwischengespeichert. Konfiguration und Richtlinie beeinflussen, welche Anbieter aufgelistet und verwendbar sind.

Anmeldeinformationen festlegen mit PUT /api/ai/credentials und entfernen Sie sie mit DELETE /api/ai/credentials/:provider. Schlüssel dürfen nicht leer sein und eine bereitgestellte Basis-URL muss HTTP oder HTTPS sein. Die direkte Modellfabrik unterstützt Anthropic, OpenAI, MiniMax und das AI-Gateway. Andere Anbieter-IDs erfordern für direkte Aufrufe eine OpenAI-kompatible Basis-URL. Der eingebettete Host verwendet seinen eigenen Anbieterkatalog und sein eigenes Routing.

Der Sidecar behält die Anmeldeinformationen bei <dataDir>/ai/credentials.json verwenden einer temporären Datei, Nur-Eigentümer-Modus 0600 und Umbenennen. Eine fehlende oder beschädigte Datei wird als leer angezeigt. Ein fehlgeschlagener Persistenzschreibvorgang lässt den Schlüssel für den aktuellen Prozess verfügbar, garantiert jedoch nicht, dass er den Neustart übersteht. Statusantworten legen den Konfigurationsstatus und nicht die Rohschlüssel offen.

Anmeldeinformationen werden mit dargestellt Redacted innerhalb von Diensten gespeichert und über eine bereichsbezogene Anmeldeinformationssenke an den Host weitergegeben. Durch das Schließen des Bereichs wird die Kopie des Hosts gelöscht. Anmeldeinformationsänderungen aktualisieren eine Revision, die zur Unterscheidung zwischengespeicherter zustandsloser Ergebnisse verwendet wird.

Die Standardmodellstufe ist balanced, und MiniMax-Anfragen gehen an https://api.minimax.io/v1 es sei denn CADCAMFUN_AI_MINIMAX_BASE_URL überschreibt es (packages/ai/src/models.ts). Der Modellkatalog stammt aus der Öffentlichkeit https://models.dev/api.json endpunkt nur, wenn die zwischengespeicherte Datei fehlt und der Netzwerkzugriff erlaubt ist; Es werden keine Anmeldeinformationen gesendet, die Antworten sind auf 8 MiB begrenzt und ein Text mit weniger als 20 Anbietern wird als gekürzt abgelehnt.

Aktionen und Berechtigungen

Der Aktionskatalog deklariert jeden Aktionsbezeichner, jedes Parameterschema, jeden Effekt und jeden Ausführungspfad. Tools gruppieren verwandte Aktionen hinter einem erforderlichen action feld. Der Host validiert die Tool-Eingabe und Sidecar-Handler führen eine Domänenvalidierung und Ressourcenzugriffsprüfungen durch, bevor Änderungen übernommen werden.

Berechtigungsmodi sind approve, ask, und auto. Sie wirken sich darauf aus, wie normale Werkzeugaufrufe zugelassen werden. Werkzeuge, die destruktive Aktionen enthalten, unterliegen in jedem Modus einer menschlichen Genehmigungsregel. Ein Eingabeflag wie confirm: true ersetzt diese Erlaubnisanfrage nicht. Der Host stellt keine uneingeschränkten Shell- oder Dateibearbeitungstools als Ersatz für Anwendungsaktionen zur Verfügung.

Richtlinien in <dataDir>/ai/policy.json beschränken Sie die Nutzung von Anbietern, Tools und Bridge-Zugriffen. Sie werden von der Dienstkonfiguration geladen; Gehen Sie nicht davon aus, dass durch das Bearbeiten der Datei ein bereits ausgeführter Dienst aktualisiert wird. Projektbezogene Scratch-Verzeichnisse und isolierte Nikcli-Konfiguration halten den eingebetteten Host vom Standalone-Agent-Status eines Benutzers getrennt.

Die Fähigkeiten stellen CAD/CAM-Playbooks und vom Benutzer verfasste Anweisungen bereit. Sie leiten den Einsatz vorhandener Tools; Durch das Hinzufügen eines Skills wird keine neue Mutations-API hinzugefügt. Die Skills-HTTP-Endpunkte listen, speichern und löschen unterstützte Benutzer-Skill-Inhalte.

Registrierte Werkzeuggruppen

Die integrierten Gruppen sind cad, cad_edit, cam, cam_edit, library, parts, library_edit, memory, memory_edit, research, vcs, vcs_edit, und agent. cam_verify stellt die von der Verifiziererrolle benötigte Generierungs- und Verifizierungsteilmenge bereit, ohne das vollständige CAM-Bearbeitungstool zu gewähren.

Durch die Werkzeuggruppierung bleiben die Wirkungsgrenzen erhalten. Die schreibgeschützte Geometrieprüfung, die Bibliothekssuche und der Speicherabruf erfolgen getrennt von Änderungen an diesen Ressourcen. Die injizierte Registry kann auch Erweiterungstools zulassen; Doppelte Identifikatoren werden abgelehnt.

Entdecken Sie den aktuellen Katalog

GET /api/ai/actions gibt Werkzeugbeschreibungen, Aktionsnamen und -arten sowie JSON-Parameterschemata für externe Aufrufer zurück. Verwenden Sie es, um die Aktionen der laufenden Anwendung zu ermitteln, anstatt eine statische Liste in einen Client zu kopieren. POST /api/ai/actions/invoke nimmt eine Projekt-ID, eine Tool-ID und eine Eingabe mit dem Aktionsdiskriminator entgegen.

Integrierte Katalogeinträge werden unter verwaltet packages/ai/src/actions. Beispiele hierfür sind CAD-Inspektion und parametrische Prüfungen, CAD-Bearbeitungen, CAM-Planung und -Fertigung, Bibliothekssuche und -aktualisierungen, Projektspeicher, Forschung und VCS-Vorschläge. Ein Beitrag, der einen Anwendungsdienst erfordert, gibt ein nicht verfügbares Ergebnis zurück, wenn dieser Host seinen Handler nicht bereitgestellt hat.

Öffentliche Integrations-APIs

ACTION_CATALOGUE, ACTION_TOOL_IDS, EXPOSED_TOOL_IDS, actionById, toolKind, und runAction unterstützung von Katalogkonsumenten. ToolHandlers ist der Sidecar-Integrationsvertrag; ToolRegistry stellt integrierte und Erweiterungstools zusammen. AiService stellt Konversationen, Modellmetadaten, einmalige Aufrufe und Sitzungsvorgänge bereit.

assembleContext erstellt Turn-Kontext mit einem Standard-Gesamtbudget von 24,000 Zeichen. Es ordnet aktuelle Anforderungen, aktuelle Beobachtungen, UI-Snapshots, Speicher und unterstützende Referenzen, dedupliziert nach Identität und Inhalt und zeichnet ausgelassene oder abgeschnittene Quellen auf. Dieses Kontextbudget ist vom vollständigen Token-Fenster und dem Host-Komprimierungsschwellenwert des Modells getrennt.

Hintergrundarbeit und Beweise

Der Laufzeitplaner ermöglicht vier aktive Hintergrundaufgaben und sechzehn Aufgaben in der Warteschlange. Aufgaben gehören einem Projekt und einer übergeordneten Sitzung. Durch die Stornierung bleibt das aktive Eigentum erhalten, bis ein Arbeitnehmer aufhört; Durch das Stoppen oder Löschen des übergeordneten Elements wird auch die damit verbundene Arbeit gestoppt. Die Wiederherstellung des Lesevorgangs ist auf zwei Versuche beschränkt, während unterbrochene Bearbeitungsarbeiten als unsicher markiert und nicht blind wiederholt werden.

Der Erfolg eines Assistententools ist ein Ergebnis, das es zu überprüfen gilt. CAD-Operationen können Teilgeometriediagnosen zurückgeben; CAM-Artefakte haben ihre eigenen Ansprüche und Release-Level; Verlaufsdienste erzwingen geschützte Zweige. Ein Gesprächstext, eine als erledigt markierte Aufgabe und ein geometrisches Überprüfungsergebnis beschreiben unterschiedliche Beweise.

Der an das Modell gesendete Projektkontext ist budgetiert: Ein gespeichertes Projektkontextdokument kann bis zu 8,000 Zeichen enthalten, von denen 2,000 die Eingabeaufforderung erreichen, wobei jeweils 1,500 Zeichen für den Projektspeicher und die Benutzergewohnheiten stehen. Projektnotizen, die älter als 90 Tage sind und auf die der Projektkontext nicht verweist, werden gelöscht, wenn eine Sitzung beendet wird (packages/ai/src/project-context.ts).

Laufzeitauswahl

CADCAMFUN_AI_HOST wählt nikcli standardmäßig oder direct. Der direkte Pfad verwendet AI SDK-Aufrufe ohne die persistente Agent-Tool-Schleife und den speziellen Scheduler des eingebetteten Hosts. Zustandslose Vorgänge nutzen den direkten Modelldienst, auch wenn der eingebettete Host aktiviert ist.

Die XDG-Verzeichnisse des Hosts und die optionale Home-Override-Verzeichnis liegen unter Root <dataDir>/ai/nikcli. Das Laden der Projektkonfiguration und nicht verwandte geerbte Agenteneinstellungen werden vor dem SDK-Import deaktiviert oder bereinigt. Sein Arbeitsbereich ist ein Scratch-Verzeichnis pro Projektanwendung und nicht das Quellverzeichnis des Benutzers.

Eigenständiger Nikcli-Zugriff

@cadcamfunv2/cadcamfun-nikcli-plugin verbindet eine eigenständige Nikcli mit einer laufenden Anwendung. Konfigurieren Sie es url, token, und Standard projectId, oder verwenden CADCAMFUN_URL, CADCAMFUN_TOKEN, und CADCAMFUN_PROJECT. Geben Sie ein von der Anwendung ausgegebenes, bereichsbezogenes Bridge-Token für den Zugriff von außen an.

Bridge-Token sind auf ein Projekt und schreibgeschützte oder Lese-/Schreibaktionen beschränkt. Sie sind standardmäßig auf 30 Tage ausgelegt, haben eine Gültigkeit von 1–365 Tagen, können aufgelistet und widerrufen werden und geben ihr Geheimnis erst preis, wenn es herausgegeben wird. Sie lassen nur die beiden Aktionsbrückenrouten zu. Die Politik kann die sichtbaren Instrumente und Maßnahmen weiter einschränken.

Das Plugin ruft den Katalog aus der Anwendung ab und konvertiert seine Schemata in Nikcli-Tool-Argumente. Destruktive Aktionen werden auch mit einem Bestätigungsflag und in Bearbeitung abgelehnt agent delegationstool ist ausgeschlossen. Schreibfähige Plugin-Erweiterungstools werden über diese externe Brücke nicht verfügbar gemacht. HTTP 401 meldet ein abgelehntes Token; Aktionsablehnungen geben lesbare Fehlerergebnisse zurück.

Implementierungskarte

service.ts besitzt anwendungsorientierte KI-Operationen; direct-model.ts besitzt AI SDK-Aufrufe; credentials.ts besitzt Schlüsselstaat; nikcli/ besitzt Isolation, Sitzungen, Richtlinien, Kontext und Arbeiter; actions/ und tools/ eigene Fähigkeitsdefinitionen und Adapter. Sidecar services/ai.ts kabel-Projektabwickler und -Lagerung. packages/nikcli-plugin besitzt den externen HTTP-Client.

Ein Gespräch beginnen und wieder aufnehmen

Mit einem laufenden Sidecar und einem konfigurierten Modell öffnet diese Anfrage eine Konversation, ohne gespeicherten Arbeitsbereichskontext einzufügen. Satz CADCAMFUN_URL zur erkannten Loopback-Basis-URL und CADCAMFUN_TOKEN zu seinem aktuellen Anwendungstoken. Die folgende Sitzungskennung wird vom Kunden ausgewählt. Bewahren Sie es für spätere Zwecke auf.

curl --no-buffer --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Explain the difference between G0 and G1.","sessionId":"inspection-demo","includeContext":false,"mode":"gcode"}' \
  "$CADCAMFUN_URL/api/ai/chat/stream"

Geben Sie für einen Projektzug auch dessen Echtheit an projectId, und optional a drawingId die zu diesem Projekt gehören. Die Zeichnung bindet die Turn-Werkzeuge an diese Zeichnung. Die Wiederverwendung einer Sitzung unter einem anderen Projekt oder Konto wird abgelehnt.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"sessionId":"inspection-demo"}' \
  "$CADCAMFUN_URL/api/ai/sessions/state"

Die zurückgegeben busy, text, fakultativ events, und tasks die Ansicht rekonstruieren; Durch die Wiedergabe dieser gespeicherten Ereignisse werden die Tools nicht erneut ausgeführt. Um die Arbeit zu stoppen, senden Sie einen expliziten Abbruch. Das Schließen des Streams allein führt nicht dazu, dass die Mitarbeiter der Konversation beitreten.

Quelle: packages/api/src/groups/ai.ts, apps/sidecar/src/http/ai.ts, und packages/ai/src/service.ts.

Behandeln Sie Ereignisse, ohne den Status zu verlieren

Sitzungssteuerelemente akzeptieren nur ausstehende Berechtigungs-/Frage-IDs in dieser Konversation oder ihren untergeordneten Sitzungen. Eine Frage erfordert nicht leere Antworten; Eine Single-Choice-Frage lehnt mehrere ausgewählte Werte ab und eine Frage, die keine benutzerdefinierten Antworten zulässt, akzeptiert nur die aufgeführten Optionsbezeichnungen.

Quelle: packages/api/src/ai-events.ts, packages/ai/src/nikcli/session-controls.ts, und packages/ai/src/heartbeat.ts.

Anhänge und Benutzerkenntnisse

Jede Chat-Anfrage akzeptiert bis zu fünf Anhänge. Unterstützte Bilder sind PNG, JPEG, WebP und GIF mit jeweils einem Limit von 5 MiB; PDFs haben ein Limit von 10 MiB. Textanhänge akzeptieren bis zu 2,000,000 Zeichen, wobei Texte mit bis zu 6,000 Zeichen auch inline enthalten sind. Nicht unterstützte Dateien erzeugen einen Ablehnungsgrund, anstatt stillschweigend zu verschwinden.

Textanhänge werden in einem projektbezogenen In-Memory-Speicher für Importtools gespeichert: höchstens 32 Namen und 8,000,000 Zeichen pro Projekt und 32,000,000 Zeichen in höchstens 64 gespeicherten Projekten. Durch die Wiederverwendung eines Namens wird dessen vorheriger Text ersetzt. Durch einen Neustart des Dienstes bleibt dieser Anhangspeicher nicht erhalten. Eine Nichtübereinstimmung der PDF-Funktionen wird dem Modell von der Anbietertransformation gemeldet.

Benutzerfähigkeitsnamen bestehen aus Kleinbuchstaben/Ziffern, die durch Bindestriche verbunden sind, maximal 64 Zeichen. Die Beschreibungs- und Textbegrenzungen sind jeweils 300 und 20,000 Zeichen; Es können höchstens 50 Benutzerfähigkeiten geladen werden. Integrierte Skills können nicht über die Benutzer-Skill-API entfernt werden. Eine gespeicherte Fertigkeit live das Ergebnis gibt an, ob das erneute Laden des Hosts wirksam wurde.

Quelle: packages/ai/src/attachments.ts, packages/ai/src/skills/user.ts, und apps/sidecar/src/http/ai.ts.

Diagnostizieren Sie Ausfälle von Assistenten

• Kein konfiguriertes Modell: überprüfen /api/ai/status und /api/ai/providers, und legen Sie dann einen Schlüssel für einen aufgelisteten Anbieter fest. Ein konfiguriertes Flag beweist, dass ein gespeicherter Schlüssel vorhanden ist, nicht, dass der Anbieter ihn akzeptiert hat.
• Unbekannter Anbieter oder ungültige URL: verwenden Sie eine angekündigte Anbieter-ID und eine HTTP(S)-Basis-URL. Ein nicht integrierter Direktanbieter benötigt zusätzlich zu seinem Schlüssel einen kompatiblen Endpunkt.
• Sitzung nicht zugänglich: wiederherstellung unter Verwendung der ursprünglichen Projekt-/Konto-/Sitzungsidentität. Erfinden Sie keine Ersatzprojekt-ID für eine vorhandene Hostsitzung.
• Eine Runde wartet auf unbestimmte Zeit: überprüfen Sie den Status der Sitzungssteuerung auf ausstehende Berechtigungen oder Fragen, bevor Sie eine doppelte Eingabeaufforderung erneut versuchen. Verwenden Sie einen expliziten Abbruch, um die Runde abzubrechen und sich ihren Arbeitern anzuschließen.
• Ein Tool hat das Modell teilweise verändert: überprüfen Sie es tool_diagnostic, einschließlich mutationApplied, und lesen Sie dann die aktuelle Zeichnung. Wenn Sie eine Bearbeitungsaktion wiederholen, ohne das Ergebnis zu überprüfen, kann es zu einer Duplizierung der Geometrie kommen.

Tool-Ergebnisse und eingegebene Fehler behalten die fehlgeschlagene Phase bei. Ein Anbieterfehler nach erfolgreichen Tools führt nicht zu einem Rollback dieser Projektmutationen. Deterministische CAM- und Verlaufsprüfungen bleiben getrennt von der Modellantwort verfügbar.

Referenz zum Assistant-Endpunkt

Alle Hilfsrouten finden Sie unten /api/ai und erfordern das Anwendungsträgertoken. Ein Bridge-Token für ein eigenständiges Nikcli öffnet nur die Aktionslisten- und Aufrufrouten und nur für sein Projekt.

Modellgestützte Analyseantworten sind Modellausgaben in typisierter Form. Bei Werten wie Bearbeitungsparametern handelt es sich um Vorschläge zur Überprüfung anhand von Werkzeugdaten und Maschinengrenzen, nicht um verifizierte Schnittdaten.

Streaming-Anfragefelder

Grenzen und Standardwerte

Der vollständige Aktionskatalog

Der Assistent führt 83 deklarierte Aktionen in 13 Familien durch. Jede Aktion deklariert ihr Ergebnisschema und ihre effekte: was es über das Lesen des geöffneten Dokuments hinaus ändert oder bewirkt. Familien lesen (cad, cam, library, memory, research, vcs) haben meist keine Wirkung; ihre _edit gegenstücke ändern den dauerhaften Zustand. Die Effekte sind in Klammern aufgeführt.

Eine Leseaktion darf nur haben interface oder external; jeder Schreibvorgang benennt mindestens einen dauerhaften Effekt. Effekte werden pro Aktion deklariert und niemals von dem Tool abgeleitet, das sie implementiert.

So endet ein Aktionsaufruf

Schreibvorgänge sind an eine Zeichnungsrevision gebunden. Ein festgeschriebener Schreibvorgang gibt eine zurück ActionCommitted quittung mit previousRevision und revision; ein Schreiben gegen ein abgestandenes expectedRevision kehrt zurück ActionConflict mit beidem expectedRevision und actualRevision. Die gleiche Klassifizierung (actionOutcome) wird vom Host, dem Codemodus, dem Desktop und der Bridge gemeinsam genutzt.

{
  "ok": false,
  "_tag": "ActionConflict",
  "actionId": "cad_edit.modify",
  "projectId": "…", "drawingId": "…",
  "expectedRevision": 41, "actualRevision": 42,
  "message": "…"
}

In 3D