Sviluppo e implementazione di plugin

Plugin barra di controllo

I plugin della barra di controllo aggiungono pulsanti di azione personalizzati sul lato sinistro della barra di controllo inferiore nella finestra di anteprima, consentendo operazioni rapide e integrazioni con strumenti esterni per il file o la cartella corrente.

Creare un plugin barra di controllo con un agente IA

Sostituisci il segnaposto sottostante, quindi fornisci l'istruzione completa al tuo agente di programmazione:

Leggi e segui la guida allo sviluppo dei plugin della barra di controllo di Seer all'indirizzo https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Considerala come l'unica fonte di verità per architettura, plugin.json, implementazione, convalida e creazione del pacchetto. Se la guida non è disponibile, fermati e segnalalo prima di procedere.

Prima di iniziare qualsiasi attività, esamina la Requirement qui sotto. Se è mancante, contiene il testo segnaposto invariato o è troppo ambigua per essere implementata, poni una domanda di chiarimento e attendi. Non dedurre il requisito mancante.

Una volta chiarito, implementa un plugin di controllo completo e installabile che rispetti il contratto di processo Canonical v1 nello spazio di lavoro corrente. Non modificare Seer stesso e non fermarti a un piano o a frammenti di codice.

Segui ogni passaggio di convalida applicabile indicato nella guida e segnala i risultati effettivi.

Requirement: [SOSTITUISCI QUESTO SEGNAPOSTO con il requisito del tuo plugin di controllo, ad es. aprire VS Code nella cartella corrente o copiare il percorso assoluto negli appunti]

Architettura e contratto

• Modello di processo: Implementa il contratto de processo Canonical v1 (backend: "process", capabilities: ["control"]). Seer esegue l'helper tramite CLI.
• Stato restituito e segnalazione errori:
  • Successo: Il processo termina con codice 0 (o corrisponde a success_exit_codes). Se è configurato "close_after_success": true, Seer chiude automaticamente la finestra di anteprima dopo l'esecuzione con successo.
  • Errore: Il processo termina con un codice diverso da zero. Tutto ciò che viene scritto sullo standard error (stderr) viene catturato da Seer e mostrato come una notifica di errore Toast nell'app.
• Interfaccia utente e interazione: I plugin della barra di controllo non disegnano finestre principali permanenti proprie. I tipici helper eseguono attività in background, copiano testo negli appunti o richiamano finestre di dialogo di sistema native di Windows (ad es. Apri con, Proprietà, Condividi).

Segnaposto per la riga di comando

Un helper di controllo riceve solo il percorso di destinazione: ${input_file} oltre ai segnaposto universali (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) elencati nella sezione condivisa Segnaposto e token di corrispondenza sottostante.

Esempi di plugin.json (Control)

Esempio 1: Azione per cartella (Terminal Here)

La configurazione ufficiale del 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
  ]
}

Esempio 2: Azione per file (Explorer Open With)

La configurazione ufficiale del 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
  ]
}

Per il codice sorgente dei plugin di controllo ufficiali, consulta: ccseer/Seer-Controls.

Plugin delle proprietà

I plugin delle proprietà estendono il motore di ispezione dei metadati di Seer. Quando un utente preme Ctrl + I su un file o una cartella in anteprima (o apre la finestra Proprietà), i plugin delle proprietà corrispondenti estraggono e visualizzano metadati strutturati e grafici/istogrammi visivi.

Creare un plugin delle proprietà con un agente IA

Sostituisci il segnaposto sottostante, quindi fornisci l'istruzione completa al tuo agente di programmazione:

Leggi e segui la guida allo sviluppo dei plugin delle proprietà di Seer all'indirizzo https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Considerala come l'unica fonte di verità per architettura, plugin.json, implementazione, convalida e creazione del pacchetto. Se la guida non è disponibile, fermati e segnalalo prima di procedere.

Prima di iniziare qualsiasi attività, esamina la Requirement qui sotto. Se è mancante, contiene il testo segnaposto invariato o è troppo ambigua per essere implementata, poni una domanda di chiarimento e attendi. Non dedurre il requisito mancante.

Una volta chiarito, implementa un plugin delle proprietà completo e installabile che rispetti il contratto di processo Canonical v1 e la specifica Schema 1 JSON nello spazio di lavoro corrente. Non modificare Seer stesso e non fermarti a un piano o a frammenti di codice.

Segui ogni passaggio di convalida applicabile indicato nella guida e segnala i risultati effettivi.

Requirement: [SOSTITUISCI QUESTO SEGNAPOSTO con il requisito del tuo plugin delle proprietà, ad es. estrarre e visualizzare parametri dettagliati del codec audio/video e bitrate per file MP4]

Architettura e contratto

• Modello di processo: Implementa il contratto di processo Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Invocazione da CLI: L'host passa i seguenti parametri: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Pubblicazione dell'output:
  • L'host espande ${output_file} in un percorso base senza estensione (ad es. <requestDir>/<md5>).
  • Il plugin deve scrivere il proprio risultato JSON in <output-base>.json (ovvero ${output_file}.json).
  • Gli allegati visivi (grafici, istogrammi, vettorscopi) devono essere salvati in ${output_dir}.
  • Vincolo: ${no_cache} è proibito per i plugin delle proprietà.
• Politica dei codici di uscita:
  • I risultati di dominio previsti (ad es. file non firmato, non è un repository git, metadati vuoti) devono uscire con codice 0 e descrivere lo stato nel JSON.
  • Esci con un codice diverso da zero solo in caso di errori irreversibili o chiamate non valide (le uscite diverse da zero inducono l'host a cancellare la directory della richiesta).

Segnaposto per la riga di comando

Oltre ai segnaposto universali elencati nella sezione condivisa Segnaposto e token di corrispondenza sottostante, che descrive anche i token di corrispondenza ${type_*}. ${no_cache} viene rifiutato per i plugin delle proprietà.

Specifica del risultato JSON (Schema 1)

Il file di risultato ${output_file}.json deve essere un JSON UTF-8 valido contenente result_schema: 1 e un oggetto data:

1. Righe semplici (Flat Rows)

Solo quando l'intero risultato è una singola riga (ad es. SHA-256):

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

2. Sottogruppo con array ordinato di oggetti a chiave singola (Predefinito)

Tutto ciò che produce più di una riga deve essere pubblicato come esattamente un sottogruppo intitolato al plugin: le righe isolate di primo livello collidono con le righe di tutti gli altri plugin, che l'Inspector mostra in un unico elenco. L'ordine dell'array è l'ordine di visualizzazione, quindi questa è l'unica forma che consente al plugin di decidere la sequenza con cui appaiono le righe:

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

3. Sottogruppo con un oggetto valore

value può anche essere un oggetto semplice, ma le sue righe vengono visualizzate nell'ordine delle chiavi dell'oggetto analizzato, che il plugin non può controllare. Usalo solo quando l'ordine delle righe non importa:

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

4. Grafici e visualizzazioni (Allegati immagine)

Salva i grafici PNG generati in ${output_dir} e dichiarali con {"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" } }
      ]
    }
  }
}

Esempio di 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
      ]
    }
  }
}

Per il codice sorgente dei plugin delle proprietà ufficiali, consulta: ccseer/Seer-Properties.