Plugin-Entwicklung & Implementierung

Steuerelement-Plugins

Steuerelement-Plugins fügen benutzerdefinierte Aktionsschaltflächen auf der linken Seite der unteren Steuerleiste im Vorschaufenster hinzu und ermöglichen schnelle Operationen und Integrationen externer Werkzeuge für die aktive Datei oder den aktiven Ordner.

Steuerelement-Plugin mit einem KI-Agenten erstellen

Ersetzen Sie den unten stehenden Platzhalter und geben Sie Ihrem Codierungs-Agenten die vollständige Anweisung:

Lesen und befolgen Sie die Seer-Steuerelement-Plugin-Entwicklungsanleitung unter https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Betrachten Sie sie als maßgebliche Quelle (Source of Truth) für Architektur, plugin.json, Implementierung, Validierung und Paketierung. Wenn die Anleitung nicht verfügbar ist, stoppen Sie und melden Sie dies, bevor Sie fortfahren.

Überprüfen Sie vor jeder Arbeit die folgende Requirement (Anforderung). Wenn sie fehlt, unveränderter Platzhaltertext ist oder zu ungenau für eine Implementierung ist, stellen Sie eine klärende Frage und warten Sie. Versuchen Sie nicht, die fehlende Anforderung zu erraten.

Sobald dies geklärt ist, implementieren Sie ein vollständiges, installierbares Steuerelement-Plugin gemäß dem Canonical v1-Prozessvertrag im aktuellen Arbeitsbereich. Nehmen Sie keine Änderungen an Seer selbst vor und bleiben Sie nicht bei Plänen oder Code-Snippets stehen.

Befolgen Sie jeden anwendbaren Validierungsschritt in der Anleitung und melden Sie die tatsächlichen Ergebnisse.

Requirement: [ERSETZEN SIE DIESEN PLATZHALTER durch Ihre Steuerelement-Plugin-Anforderung, z. B. VS Code im aktuellen Ordner öffnen oder absoluten Pfad in die Zwischenablage kopieren]

Architektur & Vertrag

• Prozessmodell: Implementiert den Canonical v1-Prozessvertrag (backend: "process", capabilities: ["control"]). Seer führt das Hilfsprogramm über die Befehlszeile (CLI) aus.
• Rückgabestatus & Fehlerberichterstattung:
  • Erfolg: Der Prozess wird mit Exit-Code 0 beendet (oder entspricht success_exit_codes). Wenn "close_after_success": true konfiguriert ist, schließt Seer das Vorschaufenster automatisch nach erfolgreicher Ausführung.
  • Fehler: Der Prozess wird mit einem Wert ungleich Null beendet. Alle in die Standardfehlerausgabe (stderr) geschriebenen Inhalte werden von Seer erfasst und als In-App-Toast-Fehlermeldung angezeigt.
• Benutzeroberfläche & Interaktion: Steuerelement-Plugins zeichnen keine eigenen dauerhaften Hauptfenster. Typische Helfer führen Hintergrundaufgaben aus, kopieren Text in die Zwischenablage oder rufen native Windows-Systemdialoge auf (z. B. Öffnen mit, Eigenschaften, Freigeben).

Befehlszeilen-Platzhalter

Ein Steuerelement-Hilfsprogramm empfängt ausschließlich den Zielpfad — ${input_file} sowie die universellen Platzhalter (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}), die im gemeinsamen Abschnitt Platzhalter & Matching-Token weiter unten aufgeführt sind.

plugin.json-Beispiele (Control)

Beispiel 1: Ordneraktion (Terminal Here)

Die Konfiguration des offiziellen Terminal Here-Plugins:

{
  "schema_version": 1,
  "id": "io.1218.seer.terminal-here",
  "name": "Terminal Here",
  "description": "Opens a terminal window in the current folder.",
  "version": "1.0.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "control"
  ],
  "extensions": [
    "${type_folder}"
  ],
  "command": "terminal_here.exe",
  "arguments": [
    "--input",
    "${input_file}"
  ],
  "close_after_success": false,
  "timeout_ms": 150000,
  "success_exit_codes": [
    0
  ]
}

Beispiel 2: Dateiaktion (Explorer Open With)

Die Konfiguration des offiziellen Explorer Open With-Plugins:

{
  "schema_version": 1,
  "id": "io.1218.seer.explorer-open-with",
  "name": "Open With",
  "description": "Opens the Windows Open With dialog for the current file.",
  "version": "1.1.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "control"
  ],
  "extensions": [
    "${type_file}"
  ],
  "command": "shellopenwith.exe",
  "arguments": [
    "--input",
    "${input_file}",
    "${use_backslash}"
  ],
  "timeout_ms": 30000,
  "success_exit_codes": [
    0
  ]
}

Den Quellcode offizieller Steuerelement-Plugins finden Sie unter: ccseer/Seer-Controls.

Eigenschaften-Plugins

Eigenschaften-Plugins erweitern die Metadaten-Prüfungs-Engine von Seer. Wenn ein Benutzer Strg + I auf einer in der Vorschau angezeigten Datei oder einem Ordner drückt (oder das Eigenschaftenfenster öffnet), extrahieren passende Eigenschaften-Plugins strukturierte Metadaten sowie grafische Oszilloskope/Diagramme und zeigen diese an.

Eigenschaften-Plugin mit einem KI-Agenten erstellen

Ersetzen Sie den unten stehenden Platzhalter und geben Sie Ihrem Codierungs-Agenten die vollständige Anweisung:

Lesen und befolgen Sie die Seer-Eigenschaften-Plugin-Entwicklungsanleitung unter https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Betrachten Sie sie als maßgebliche Quelle (Source of Truth) für Architektur, plugin.json, Implementierung, Validierung und Paketierung. Wenn die Anleitung nicht verfügbar ist, stoppen Sie und melden Sie dies, bevor Sie fortfahren.

Überprüfen Sie vor jeder Arbeit die folgende Requirement (Anforderung). Wenn sie fehlt, unveränderter Platzhaltertext ist oder zu ungenau für eine Implementierung ist, stellen Sie eine klärende Frage und warten Sie. Versuchen Sie nicht, die fehlende Anforderung zu erraten.

Sobald dies geklärt ist, implementieren Sie ein vollständiges, installierbares Eigenschaften-Plugin gemäß dem Canonical v1-Prozessvertrag und der Schema 1-JSON-Spezifikation im aktuellen Arbeitsbereich. Nehmen Sie keine Änderungen an Seer selbst vor und bleiben Sie nicht bei Plänen oder Code-Snippets stehen.

Befolgen Sie jeden anwendbaren Validierungsschritt in der Anleitung und melden Sie die tatsächlichen Ergebnisse.

Requirement: [ERSETZEN SIE DIESEN PLATZHALTER durch Ihre Eigenschaften-Plugin-Anforderung, z. B. Extrahieren und Anzeigen detaillierter Audio-/Videocodec-Parameter und Bitraten für MP4-Dateien]

Architektur & Vertrag

• Prozessmodell: Implementiert den Canonical v1-Prozessvertrag (backend: "process", capabilities: ["property"], result_schema: 1).
• CLI-Aufruf: Die Host-Anwendung übergibt: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Ausgabeveröffentlichung:
  • Der Host erweitert ${output_file} zu einem Basispfad ohne Dateierweiterung (z. B. <requestDir>/<md5>).
  • Das Plugin muss sein JSON-Ergebnis in <output-base>.json (d. h. ${output_file}.json) schreiben.
  • Visuelle Anhänge (Diagramme, Histogramme, Vektorskope) müssen in ${output_dir} gespeichert werden.
  • Einschränkung: ${no_cache} ist für Eigenschaften-Plugins verboten.
• Exit-Code-Richtlinie:
  • Erwartete Domänenergebnisse (z. B. nicht signierte Datei, kein Git-Repository, leere Metadaten) müssen mit Code 0 beendet werden und den Status in JSON beschreiben.
  • Ein Exit-Code ungleich Null darf nur bei schwerwiegenden Fehlern oder ungültigen Aufrufen zurückgegeben werden (Exits ungleich Null führen dazu, dass der Host das Anforderungsverzeichnis löscht).

Befehlszeilen-Platzhalter

Zusätzlich gelten die im gemeinsamen Abschnitt Platzhalter & Matching-Token aufgeführten universellen Platzhalter sowie die ${type_*}-Matcher-Token. ${no_cache} wird für Eigenschaften-Plugins abgelehnt.

Spezifikation für Ergebnis-JSON (Schema 1)

Die Ergebnisdatei ${output_file}.json muss gültiges UTF-8-JSON sein, das result_schema: 1 und ein data-Objekt enthält:

1. Flache Zeilen (Flat Rows)

Nur wenn das Gesamtergebnis eine einzelne Zeile ist (z. B. SHA-256):

{
  "result_schema": 1,
  "data": {
    "SHA-256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
  }
}

2. Untergruppe mit geordnetem Array von Einzelschlüssel-Objekten (Standard)

Alles, was mehr als eine Zeile erzeugt, muss als genau eine Untergruppe veröffentlicht werden, die nach dem Plugin benannt ist – lose Zeilen auf oberster Ebene kollidieren mit den Zeilen jedes anderen Plugins, die der Inspektor in einer einzigen Liste anzeigt. Die Array-Reihenfolge ist die Anzeigereihenfolge, daher ist dies die einzige Form, bei der das Plugin die Reihenfolge der Zeilen selbst bestimmen kann:

{
  "result_schema": 1,
  "data": {
    "Git": {
      "value": [
        { "Repository": "ccseer/Seer-Properties" },
        { "Branch": "main" },
        { "Status": "Clean" }
      ]
    }
  }
}

3. Untergruppe mit Wertobjekt

value kann auch ein einfaches Objekt sein, aber seine Zeilen werden in der Schlüsselreihenfolge des geparsten Objekts gerendert, die das Plugin nicht steuern kann. Verwenden Sie es nur, wenn die Zeilenreihenfolge keine Rolle spielt:

{
  "result_schema": 1,
  "data": {
    "Git": {
      "value": {
        "Branch": "main",
        "Status": "Working tree clean"
      }
    }
  }
}

4. Grafische Diagramme & Oszilloskope (Bildanhänge)

Speichern Sie generierte PNG-Diagramme in ${output_dir} und deklarieren Sie sie mit {"type": "image", "value": "relative_filename.png"}:

{
  "result_schema": 1,
  "data": {
    "Image Scopes": {
      "value": [
        { "RGB Histogram": { "type": "image", "value": "histogram.png" } },
        { "Luma Waveform": { "type": "image", "value": "waveform.png" } }
      ]
    }
  }
}

plugin.json-Beispiel (Property)

{
  "schema_version": 1,
  "id": "io.1218.seer.git-info",
  "name": "Git Info",
  "description": "Reports repository information for the current folder using Git.",
  "version": "1.0.0",
  "appMinVersion": "4.5.10",
  "backend": "process",
  "capabilities": [
    "property"
  ],
  "extensions": [
    "${type_folder}"
  ],
  "invocations": {
    "property": {
      "command": "git_info.exe",
      "arguments": [
        "--input",
        "${input_file}",
        "--output",
        "${output_file}",
        "--output-dir",
        "${output_dir}"
      ],
      "result_schema": 1,
      "timeout_ms": 30000,
      "success_exit_codes": [
        0
      ]
    }
  }
}

Den Quellcode offizieller Eigenschaften-Plugins finden Sie unter: ccseer/Seer-Properties.