Tworzenie i implementacja wtyczek

Wtyczki kontrolek

Wtyczki kontrolek dodają niestandardowe przyciski akcji po lewej stronie dolnego paska sterowania w oknie podglądu, umożliwiając szybkie operacje i integrację z zewnętrznymi narzędziami dla aktywnego pliku lub folderu.

Tworzenie wtyczki kontrolek za pomocą agenta AI

Zastąp poniższy symbol zastępczy, a następnie przekaż pełną instrukcję swojemu agentowi kodującemu:

Przeczytaj i postępuj zgodnie z przewodnikiem tworzenia wtyczek kontrolek Seer dostępnym pod adresem https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Traktuj go jako jedyne źródło prawdy w zakresie architektury, plugin.json, implementacji, walidacji i pakowania. Jeśli przewodnik jest niedostępny, zatrzymaj się i zgłoś to przed kontynuowaniem.

Przed rozpoczęciem jakichkolwiek prac sprawdź poniższe Requirement (Wymaganie). Jeśli brakuje go, jest niezmienionym tekstem zastępczym lub jest zbyt niejednoznaczne do zaimplementowania, zadaj jedno pytanie uściślające i poczekaj. Nie domyślaj się brakującego wymagania.

Po wyjaśnieniu zaimplementuj kompletną, możliwą do zainstalowania wtyczkę kontrolek zgodną z kontraktem procesowym Canonical v1 w bieżącym obszarze roboczym. Nie modyfikuj samego Seera ani nie zatrzymuj się na planie lub fragmentach kodu.

Postępuj zgodnie z każdym mającym zastosowanie krokiem walidacji w przewodniku i zgłoś rzeczywiste wyniki.

Requirement: [ZASTĄP TEN SYMBOL ZASTĘPCZY wymaganiem dotyczącym wtyczki kontrolek, np. otwórz VS Code w bieżącym katalogu lub skopiuj ścieżkę bezwzględną do schowka]

Architektura i kontrakt

• Model procesu: Implementuje kontrakt procesowy Canonical v1 (backend: "process", capabilities: ["control"]). Seer wykonuje program pomocniczy przez CLI.
• Status zakończenia i raportowanie błędów:
  • Sukces: Proces kończy się z kodem 0 (lub pasującym do success_exit_codes). Jeśli skonfigurowano "close_after_success": true, Seer automatycznie zamyka okno podglądu po pomyślnym wykonaniu.
  • Błąd: Proces kończy się z kodem różnym od zera. Wszystko zapisane do standardowego strumienia błędów (stderr) jest przechwytywane przez Seer i wyświetlane jako powiadomienie Toast o niepowodzeniu w aplikacji.
• Interfejs użytkownika i interakcja: Wtyczki kontrolek nie tworzą własnych trwałych okien głównych. Typowe programy pomocnicze uruchamiają zadania w tle, kopiują tekst do schowka lub wywołują natywne okna dialogowe systemu Windows (np. Otwórz za pomocą, Właściwości, Udostępnij).

Symbole zastępcze wiersza poleceń

Program pomocniczy kontrolki otrzymuje wyłącznie ścieżkę docelową — ${input_file} oraz uniwersalne symbole zastępcze (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) wymienione we wspólnej sekcji Symbole zastępcze i znaczniki dopasowania poniżej.

Przykłady plugin.json (Control)

Przykład 1: Akcja folderu (Terminal Here)

Konfiguracja oficjalnej wtyczki 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
  ]
}

Przykład 2: Akcja pliku (Explorer Open With)

Konfiguracja oficjalnej wtyczki 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
  ]
}

Kod źródłowy oficjalnych wtyczek kontrolek można znaleźć pod adresem: ccseer/Seer-Controls.

Wtyczki właściwości

Wtyczki właściwości rozszerzają mechanizm inspekcji metadanych Seer. Gdy użytkownik naciśnie Ctrl + I na podglądanym pliku lub folderze (lub otworzy okno Właściwości), pasujące wtyczki właściwości wyodrębniają i wyświetlają ustrukturyzowane metadane oraz graficzne wykresy/oscyloskopy.

Tworzenie wtyczki właściwości za pomocą agenta AI

Zastąp poniższy symbol zastępczy, a następnie przekaż pełną instrukcję swojemu agentowi kodującemu:

Przeczytaj i postępuj zgodnie z przewodnikiem tworzenia wtyczek właściwości Seer dostępnym pod adresem https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Traktuj go jako jedyne źródło prawdy w zakresie architektury, plugin.json, implementacji, walidacji i pakowania. Jeśli przewodnik jest niedostępny, zatrzymaj się i zgłoś to przed kontynuowaniem.

Przed rozpoczęciem jakichkolwiek prac sprawdź poniższe Requirement (Wymaganie). Jeśli brakuje go, jest niezmienionym tekstem zastępczym lub jest zbyt niejednoznaczne do zaimplementowania, zadaj jedno pytanie uściślające i poczekaj. Nie domyślaj się brakującego wymagania.

Po wyjaśnieniu zaimplementuj kompletną, możliwą do zainstalowania wtyczkę właściwości zgodną z kontraktem procesowym Canonical v1 i specyfikacją Schema 1 JSON w bieżącym obszarze roboczym. Nie modyfikuj samego Seera ani nie zatrzymuj się na planie lub fragmentach kodu.

Postępuj zgodnie z każdym mającym zastosowanie krokiem walidacji w przewodniku i zgłoś rzeczywiste wyniki.

Requirement: [ZASTĄP TEN SYMBOL ZASTĘPCZY wymaganiem dotyczącym wtyczki właściwości, np. wyodrębnij i wyświetl szczegółowe parametry kodeków audio/wideo oraz szybkość transmisji bitów dla plików MP4]

Architektura i kontrakt

• Model procesu: Implementuje kontrakt procesowy Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Wywołanie CLI: Host przekazuje: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Publikacja danych wyjściowych:
  • Host rozwija ${output_file} do ścieżki podstawowej bez rozszerzenia (np. <requestDir>/<md5>).
  • Wtyczka musi zapisać swój wynik JSON do <output-base>.json (czyli ${output_file}.json).
  • Załączniki wizualne (wykresy, histogramy, wektroskopy) muszą być zapisywane w ${output_dir}.
  • Ograniczenie: Zmienna ${no_cache} jest zabroniona we wtyczkach właściwości.
• Zasady dotyczące kodów wyjścia:
  • Oczekiwane wyniki domenowe (np. niepodpisany plik, brak repozytorium git, puste metadane) muszą kończyć się kodem 0 i opisywać status w formacie JSON.
  • Kod różny od zera należy zwracać tylko w przypadku błędów krytycznych lub nieprawidłowych wywołań (zakończenie z kodem niezerowym powoduje usunięcie katalogu żądania przez hosta).

Symbole zastępcze wiersza poleceń

Oraz uniwersalne symbole zastępcze wymienione we wspólnej sekcji Symbole zastępcze i znaczniki dopasowania poniżej, która obejmuje również znaczniki dopasowania ${type_*}. Symbol ${no_cache} jest odrzucany dla wtyczek właściwości.

Specyfikacja wynikowego formatu JSON (Schema 1)

Plik wynikowy ${output_file}.json musi być poprawnym formatem JSON zakodowanym w UTF-8, zawierającym result_schema: 1 oraz obiekt data:

1. Płaskie wiersze (Flat Rows)

Tylko gdy cały wynik to pojedynczy wiersz (np. SHA-256):

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

2. Podgrupa z uporządkowaną tablicą obiektów z jednym kluczem (Domyślnie)

Wynik zawierający więcej niż jeden wiersz musi zostać opublikowany jako dokładnie jedna podgrupa nazwana od wtyczki — luźne wiersze najwyższego poziomu kolidują z wierszami wszystkich innych wtyczek, które Inspektor pokazuje na jednej liście. Kolejność tablicy to kolejność wyświetlania, więc jest to jedyna forma, która pozwala wtyczce zdecydować o kolejności wierszy:

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

3. Podgrupa z obiektem wartości

value może być także zwykłym obiektem, ale jego wiersze są renderowane w kolejności kluczy przetworzonego obiektu, której wtyczka nie może kontrolować. Używaj tylko wtedy, gdy kolejność wierszy nie ma znaczenia:

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

4. Wykresy graficzne i oscyloskopy (Załączniki graficzne)

Zapisuj wygenerowane wykresy PNG w katalogu ${output_dir} i deklaruj je jako {"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" } }
      ]
    }
  }
}

Przykład 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
      ]
    }
  }
}

Kod źródłowy oficjalnych wtyczek właściwości można znaleźć pod adresem: ccseer/Seer-Properties.