Utvikling og implementering av tillegg

Kontroll-tillegg

Kontroll-tillegg legger til egendefinerte handlingsknapper på venstre side av den nedre kontrollinjen i forhåndsvisningsvinduet, noe som muliggjør raske handlinger og integrasjon med eksterne verktøy for den aktive filen eller mappen.

Bygg et kontroll-tillegg med en KI-agent

Erstatt plassholderen nedenfor, og gi deretter den fullstendige instruksjonen til kodingsagenten din:

Les og følg Seer-utviklingsveiledningen for kontrolltillegg på https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Behandle den som den eneste sannhetskilden for arkitektur, plugin.json, implementering, validering og pakking. Hvis veiledningen ikke er tilgjengelig, stopp og rapporter det før du fortsetter.

Før du gjør noe arbeid, inspiser Requirement (Krav) nedenfor. Hvis det mangler, er uendret plassholdertekst, eller for tvetydig til å implementeres, still ett avklarende spørsmål og vent. Ikke gjett det manglende kravet.

Når det er avklart, implementer et fullstendig, installerbart kontrolltillegg som overholder Canonical v1-prosesskontrakten i gjeldende arbeidsområde. Ikke endre Seer i seg selv eller stopp ved en plan eller kodeutdrag.

Følg hvert gjeldende valideringstrinn i veiledningen og rapporter de faktiske resultatene.

Requirement: [ERSTATT DENNE PLASSHOLDEREN med kravet til kontrolltillegget ditt, f.eks. åpne VS Code i gjeldende mappe eller kopier absolutt bane til utklippstavlen]

Arkitektur og kontrakt

• Prosessmodell: Implementerer Canonical v1-prosesskontrakten (backend: "process", capabilities: ["control"]). Seer kjører hjelpeprogrammet via CLI.
• Returstatus og feilrapportering:
  • Vellykket: Prosessen avsluttes med kode 0 (eller samsvarer med success_exit_codes). Hvis "close_after_success": true er konfigurert, lukker Seer automatisk forhåndsvisningsvinduet etter vellykket kjøring.
  • Feil: Prosessen avsluttes med en kode ulik null. Alt som skrives til standardfeil (stderr), fanges opp av Seer og vises som et Toast-feilvarsel i appen.
• Brukergrensesnitt og interaksjon: Kontroll-tillegg tegner ikke egne permanente hovedvinduer. Vanlige hjelpeprogrammer utfører bakgrunnsoppgaver, kopierer tekst til utklippstavlen eller åpner opprinnelige dialoger i Windows (f.eks. Åpne med, Egenskaper, Del).

Kommandolinje-plassholdere

Et kontroll-tillegg mottar kun målbanen — ${input_file} pluss de universelle plassholderne (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) som er oppført i den felles delen Plassholdere og samsvarskoder nedenfor.

plugin.json-eksempler (Control)

Eksempel 1: Mappehandling (Terminal Here)

Konfigurasjon for det offisielle Terminal Here-tillegget:

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

Eksempel 2: Filhandling (Explorer Open With)

Konfigurasjon for det offisielle Explorer Open With-tillegget:

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

For kildekoden til offisielle kontrolltillegg, se: ccseer/Seer-Controls.

Egenskaps-tillegg

Egenskaps-tillegg utvider Seers motor for inspeksjon av metadata. Når en bruker trykker Ctrl + I på en forhåndsvist fil eller mappe (eller åpner egenskapsvinduet), vil samsvarende egenskapstillegg hente ut og vise strukturerte metadata og grafiske oscilloskoper/diagrammer.

Bygg et egenskaps-tillegg med en KI-agent

Erstatt plassholderen nedenfor, og gi deretter den fullstendige instruksjonen til kodingsagenten din:

Les og følg Seer-utviklingsveiledningen for egenskapstillegg på https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Behandle den som den eneste sannhetskilden for arkitektur, plugin.json, implementering, validering og pakking. Hvis veiledningen ikke er tilgjengelig, stopp og rapporter det før du fortsetter.

Før du gjør noe arbeid, inspiser Requirement (Krav) nedenfor. Hvis det mangler, er uendret plassholdertekst, eller for tvetydig til å implementeres, still ett avklarende spørsmål og vent. Ikke gjett det manglende kravet.

Når det er avklart, implementer et fullstendig, installerbart egenskapstillegg som overholder Canonical v1-prosesskontrakten og Schema 1 JSON-spesifikasjonen i gjeldende arbeidsområde. Ikke endre Seer i seg selv eller stopp ved en plan eller kodeutdrag.

Følg hvert gjeldende valideringstrinn i veiledningen og rapporter de faktiske resultatene.

Requirement: [ERSTATT DENNE PLASSHOLDEREN med kravet til egenskapstillegget ditt, f.eks. hente ut og vise detaljerte parametere for lyd-/videokodeker og bithastighet for MP4-filer]

Arkitektur og kontrakt

• Prosessmodell: Implementerer Canonical v1-prosesskontrakten (backend: "process", capabilities: ["property"], result_schema: 1).
• CLI-kall: Verten sender: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Publisering av utdata:
  • Verten utvider ${output_file} til en basisbane uten filtype (f.eks. <requestDir>/<md5>).
  • Tillegget må skrive sitt JSON-resultat til <output-base>.json (det vil si ${output_file}.json).
  • Visuelle vedlegg (diagrammer, histogrammer, vektorskoper) må lagres i ${output_dir}.
  • Begrensning: ${no_cache} er forbudt for egenskapstillegg.
• Retningslinjer for returkoder:
  • Forventede domenestatuser (f.eks. usignert fil, ikke et git-arkiv, tomme metadata) må avsluttes med kode 0 og beskrive statusen i JSON.
  • Avslutt med kode ulik null kun ved uopprettelige feil eller ugyldige anrop (avslutning ulik null fører til at verten tømmer forespørselsmappen).

Kommandolinje-plassholdere

I tillegg kommer de universelle plassholderne som er oppført i den felles delen Plassholdere og samsvarskoder nedenfor, som også dekker ${type_*}-samsvarskodene. ${no_cache} avvises for egenskapstillegg.

Spesifikasjon for resultat-JSON (Schema 1)

Resultatfilen ${output_file}.json må være gyldig UTF-8 JSON som inneholder result_schema: 1 og et data-objekt:

1. Flate rader (Flat Rows)

Kun når hele resultatet er en enkelt rad (f.eks. SHA-256):

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

2. Undergruppe med sortert matrise av objekter med én nøkkel (Standard)

Alt som produserer mer enn én rad må publiseres som nøyaktig én undergruppe oppkalt etter tillegget – løse rader på toppnivå kolliderer med radene til alle andre tillegg, som inspektøren viser i én liste. Matriserekkefølgen er visningsrekkefølgen, så dette er den eneste formen der tillegget kan bestemme rekkefølgen radene vises i:

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

3. Undergruppe med et verdiobjekt

value kan også være et vanlig objekt, men radene gjengis i nøkkelrekkefølgen til det parsede objektet, som tillegget ikke kan kontrollere. Bruk det bare når radrekkefølgen ikke er viktig:

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

4. Grafiske diagrammer og oscilloskoper (Bildevedlegg)

Lagre genererte PNG-diagrammer i ${output_dir}, og deklarer dem med {"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-eksempel (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
      ]
    }
  }
}

For kildekoden til offisielle egenskapstillegg, se: ccseer/Seer-Properties.