Développement et implémentation de plugins

Plugins de barre de contrôle

Les plugins de barre de contrôle ajoutent des boutons d'action personnalisés sur le côté gauche de la barre de contrôle inférieure dans la fenêtre d'aperçu, permettant des opérations rapides et des intégrations d'outils externes pour le fichier ou dossier actif.

Créer un plugin de barre de contrôle avec un agent IA

Remplacez le texte d'emplacement ci-dessous, puis donnez l'instruction complète à votre agent de codage :

Lisez et suivez le guide de développement de plugins de contrôle Seer disponible sur https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Considérez-le comme la source unique de vérité pour l'architecture, plugin.json, l'implémentation, la validation et l'empaquetage. Si le guide n'est pas disponible, arrêtez-vous et signalez-le avant de continuer.

Avant tout travail, inspectez la Requirement ci-dessous. Si elle est manquante, inchangée par rapport au texte d'origine ou trop ambiguë pour être implémentée, posez une question de clarification et attendez. N'induisez pas l'exigence manquante.

Une fois clair, implémentez un plugin de contrôle complet et installable respectant le contrat de processus Canonical v1 dans l'espace de travail actuel. Ne modifiez pas Seer lui-même et ne vous arrêtez pas à un plan ou à des extraits de code.

Suivez chaque étape de validation applicable dans le guide et signalez les résultats réels.

Requirement: [REMPLACEZ CE TEXTE D'EMPLACEMENT par votre exigence de plugin de contrôle, ex. ouvrir VS Code dans le répertoire actuel ou copier le chemin absolu dans le presse-papiers]

Architecture et contrat

• Modèle de processus : Implémente le contrat de processus Canonical v1 (backend: "process", capabilities: ["control"]). Seer exécute l'outil auxiliaire via la CLI.
• Code de retour et rapport d'erreurs :
  • Succès : Le processus se termine avec le code 0 (ou correspond à success_exit_codes). Si "close_after_success": true est configuré, Seer ferme automatiquement la fenêtre d'aperçu après le succès de l'exécution.
  • Échec : Le processus se termine avec un code non nul. Tout ce qui est écrit sur la sortie d'erreur standard (stderr) est capturé par Seer et affiché sous forme de notification d'échec Toast dans l'application.
• Interface utilisateur et interaction : Les plugins de barre de contrôle ne dessinent pas de fenêtre principale permanente qui leur soit propre. Les outils auxiliaires typiques exécutent des tâches en arrière-plan, copient du texte dans le presse-papiers ou appellent des boîtes de dialogue système natives de Windows (ex. Ouvrir avec, Propriétés, Partager).

Variables de ligne de commande

Un outil auxiliaire de contrôle reçoit uniquement le chemin cible — ${input_file} plus les variables universelles (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) répertoriées dans la section partagée Variables et jetons de correspondance ci-dessous.

Exemples de plugin.json (Control)

Exemple 1 : Action sur un dossier (Terminal Here)

La configuration officielle du plugin Terminal Here :

{
  "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
  ]
}

Exemple 2 : Action sur un fichier (Explorer Open With)

La configuration officielle du plugin Explorer Open With :

{
  "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
  ]
}

Pour le code source des plugins de contrôle officiels, voir : ccseer/Seer-Controls.

Plugins de propriétés

Les plugins de propriétés étendent le moteur d'inspection des métadonnées de Seer. Lorsqu'un utilisateur appuie sur Ctrl + I sur un fichier ou dossier prévisualisé (ou ouvre la fenêtre des propriétés), les plugins de propriétés correspondants extraient et affichent des métadonnées structurées ainsi que des diagrammes/graphiques visuels.

Créer un plugin de propriétés avec un agent IA

Remplacez le texte d'emplacement ci-dessous, puis donnez l'instruction complète à votre agent de codage :

Lisez et suivez le guide de développement de plugins de propriétés Seer disponible sur https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Considérez-le comme la source unique de vérité pour l'architecture, plugin.json, l'implémentation, la validation et l'empaquetage. Si le guide n'est pas disponible, arrêtez-vous et signalez-le avant de continuer.

Avant tout travail, inspectez la Requirement ci-dessous. Si elle est manquante, inchangée par rapport au texte d'origine ou trop ambiguë pour être implémentée, posez une question de clarification et attendez. N'induisez pas l'exigence manquante.

Une fois clair, implémentez un plugin de propriétés complet et installable respectant le contrat de processus Canonical v1 et la spécification JSON Schema 1 dans l'espace de travail actuel. Ne modifiez pas Seer lui-même et ne vous arrêtez pas à un plan ou à des extraits de code.

Suivez chaque étape de validation applicable dans le guide et signalez les résultats réels.

Requirement: [REMPLACEZ CE TEXTE D'EMPLACEMENT par votre exigence de plugin de propriétés, ex. extraire et afficher les paramètres détaillés de codec audio/vidéo et le débit pour les fichiers MP4]

Architecture et contrat

• Modèle de processus : Implémente le contrat de processus Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Appel en ligne de commande : L'hôte transmet les paramètres suivants : --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Publication de la sortie :
  • L'hôte développe ${output_file} en un chemin de base sans extension (ex. <requestDir>/<md5>).
  • Le plugin doit écrire son résultat JSON dans <output-base>.json (c'est-à-dire ${output_file}.json).
  • Les pièces jointes visuelles (graphiques, histogrammes, vecteursopes) doivent être enregistrées dans ${output_dir}.
  • Contrainte : ${no_cache} est interdit pour les plugins de propriétés.
• Politique de code de sortie :
  • Les résultats normaux du domaine (ex. fichier non signé, pas un dépôt git, métadonnées vides) doivent se terminer avec le code 0 et décrire l'état dans le JSON.
  • Quitter avec un code non nul uniquement en cas d'erreurs fatales ou d'appels non valides (les sorties non nulles incitent l'hôte à vider le répertoire de la requête).

Variables de ligne de commande

Auxquelles s'ajoutent les variables universelles répertoriées dans la section partagée Variables et jetons de correspondance ci-dessous, qui décrit également les jetons de correspondance ${type_*}. ${no_cache} est rejeté pour les plugins de propriétés.

Spécification du résultat JSON (Schema 1)

Le fichier de résultat ${output_file}.json doit être un JSON UTF-8 valide contenant result_schema: 1 et un objet data :

1. Lignes simples (Flat Rows)

Uniquement lorsque le résultat entier tient en une seule ligne (ex. SHA-256) :

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

2. Sous-groupe avec un tableau ordonné d'objets à clé unique (Par défaut)

Tout résultat produisant plus d'une ligne doit être publié comme un seul sous-groupe nommé d'après le plugin — les lignes isolées de premier niveau entrent en conflit avec celles de tous les autres plugins, que l'inspecteur affiche dans une seule liste. L'ordre du tableau est l'ordre d'affichage : c'est donc la seule forme qui permet au plugin de décider de la séquence d'apparition des lignes :

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

3. Sous-groupe avec un objet de valeur

value peut aussi être un objet simple, mais ses lignes sont rendues dans l'ordre des clés de l'objet analysé, que le plugin ne peut pas contrôler. À utiliser uniquement lorsque l'ordre des lignes n'a pas d'importance :

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

4. Graphiques et représentations visuelles (Pièces jointes d'images)

Enregistrez les graphiques PNG générés dans ${output_dir} et déclarez-les avec {"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" } }
      ]
    }
  }
}

Exemple de plugin.json (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
      ]
    }
  }
}

Pour le code source des plugins de propriétés officiels, voir : ccseer/Seer-Properties.