Розробка та реалізація плагінів

Плагіни панелі керування

Плагіни панелі керування додають власні кнопки дій у ліву частину нижньої панелі керування у вікні попереднього перегляду, забезпечуючи швидкі операції та інтеграцію із зовнішніми інструментами для активного файлу чи папки.

Створення плагіна панелі керування за допомогою AI-агента

Замініть наведений нижче плейсхолдер, після чого передайте повну інструкцію своєму агенту програмування:

Прочитайте та дотримуйтесь інструкцій посібника з розробки плагінів панелі керування Seer за адресою https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Вважайте його єдиним джерелом правди для архітектури, plugin.json, реалізації, перевірки та пакування. Якщо посібник недоступний, зупиніться та повідомте про це, перш ніж продовжувати.

Перш ніж виконувати будь-яку роботу, перевірте наведену нижче Requirement. Якщо вона відсутня, містить незмінений текст плейсхолдера або надто неоднозначна для реалізації, поставте одне уточнювальне запитання та зачекайте. Не намагайтеся вгадати відсутню вимогу.

Коли все буде зрозуміло, реалізуйте повний, придатний для встановлення плагін панелі керування, що відповідає контракту процесів Canonical v1, у поточному робочому просторі. Не змінюйте сам Seer і не зупиняйтеся на плані чи фрагментах коду.

Виконайте кожен застосовний крок перевірки з посібника та повідомте фактичні результати.

Requirement: [ЗАМІНІТЬ ЦЕЙ ПЛЕЙСХОЛДЕР своєю вимогою до плагіна панелі керування, наприклад: відкриття VS Code в поточному каталозі або копіювання абсолютного шляху в буфер обміну]

Архітектура та контракт

• Модель процесу: Реалізує контракт процесів Canonical v1 (backend: "process", capabilities: ["control"]). Seer запускає допоміжну програму через CLI.
• Статус повернення та звітування про помилки:
  • Успіх: Процес завершується з кодом 0 (або відповідає значенням із success_exit_codes). Якщо налаштовано "close_after_success": true, Seer автоматично закриває вікно попереднього перегляду після успішного виконання.
  • Помилка: Процес завершується з ненульовим кодом. Усе, що записано в стандартний потік помилок (stderr), перехоплюється Seer і відображається у вигляді спливаючого сповіщення про помилку (Toast) у додатку.
• Інтерфейс користувача та взаємодія: Плагіни панелі керування не створюють власних постійних головних вікон. Типові допоміжні програми виконують фонові завдання, копіюють текст у буфер обміну або викликають нативні системні діалогові вікна Windows (наприклад, «Відкрити за допомогою», «Властивості», «Поділитися»).

Плейсхолдери командного рядка

Допоміжна програма керування отримує лише цільовий шлях — ${input_file} плюс універсальні плейсхолдери (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}), зазначені в спільному розділі Плейсхолдери та токени зіставлення нижче.

Приклади plugin.json (Control)

Приклад 1: Дія для папки (Terminal Here)

Офіційна конфігурація плагіна 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
  ]
}

Приклад 2: Дія для файлу (Explorer Open With)

Офіційна конфігурація плагіна 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
  ]
}

Вихідний код офіційних плагінів керування див. на: ccseer/Seer-Controls.

Плагіни властивостей

Плагіни властивостей розширюють механізм перевірки метаданих Seer. Коли користувач натискає Ctrl + I на файлі або папці, що переглядається (або відкриває вікно «Властивості»), відповідні плагіни властивостей витягують і відображають структуровані метадані та графічні діаграми/гістограми.

Створення плагіна властивостей за допомогою AI-агента

Замініть наведений нижче плейсхолдер, після чого передайте повну інструкцію своєму агенту програмування:

Прочитайте та дотримуйтесь інструкцій посібника з розробки плагінів властивостей Seer за адресою https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Вважайте його єдиним джерелом правди для архітектури, plugin.json, реалізації, перевірки та пакування. Якщо посібник недоступний, зупиніться та повідомте про це, перш ніж продовжувати.

Перш ніж виконувати будь-яку роботу, перевірте наведену нижче Requirement. Якщо вона відсутня, містить незмінений текст плейсхолдера або надто неоднозначна для реалізації, поставте одне уточнювальне запитання та зачекайте. Не намагайтеся вгадати відсутню вимогу.

Коли все буде зрозуміло, реалізуйте повний, придатний для встановлення плагін властивостей, що відповідає контракту процесів Canonical v1 та специфікації Schema 1 JSON, у поточному робочому просторі. Не змінюйте сам Seer і не зупиняйтеся на плані чи фрагментах коду.

Виконайте кожен застосовний крок перевірки з посібника та повідомте фактичні результати.

Requirement: [ЗАМІНІТЬ ЦЕЙ ПЛЕЙСХОЛДЕР своєю вимогою до плагіна властивостей, наприклад: вилучення та відображення детальних параметрів аудіо/відеокодеків і бітрейту для файлів MP4]

Архітектура та контракт

• Модель процесу: Реалізує контракт процесів Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Виклик через CLI: Хост передає такі параметри: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Публікація результатів:
  • Хост розгортає ${output_file} у базовий шлях без розширення (наприклад, <requestDir>/<md5>).
  • Плагін повинен записати свій результат JSON у <output-base>.json (тобто ${output_file}.json).
  • Візуальні вкладення (графіки, гістограми, векторскопи) повинні зберігатися в ${output_dir}.
  • Обмеження: ${no_cache} заборонено для плагінів властивостей.
• Політика кодів виходу:
  • Очікувані доменні результати (наприклад, непідписаний файл, не є git-репозиторієм, порожні метадані) повинні виходити з кодом 0 та описувати статус у JSON.
  • Завершуйте роботу з ненульовим кодом лише у разі фатальних помилок або некоректних викликів (ненульовий вихід призводить до повного очищення хостом каталогу запиту).

Плейсхолдери командного рядка

А також універсальні плейсхолдери, перелічені в спільному розділі Плейсхолдери та токени зіставлення нижче, де також описано токени зіставлення ${type_*}. ${no_cache} відхиляється для плагінів властивостей.

Специфікація вихідного JSON (Schema 1)

Файл результатів ${output_file}.json повинен бути коректним UTF-8 JSON, що містить result_schema: 1 та об'єкт data:

1. Прості рядки (Flat Rows)

Тільки коли весь результат складається з одного рядка (наприклад, SHA-256):

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

2. Підгрупа з впорядкованим масивом об'єктів з одним ключем (за замовчуванням)

Усе, що дає більше одного рядка, має публікуватися як рівно одна підгрупа, названа за плагіном — окремі рядки верхнього рівня конфліктують із рядками всіх інших плагінів, які інспектор показує одним списком. Порядок масиву — це порядок відображення, тому це єдина форма, у якій плагін сам визначає послідовність рядків:

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

3. Підгрупа з об'єктом значення

value може бути й звичайним об'єктом, але його рядки відображаються в порядку ключів розібраного об'єкта, яким плагін керувати не може. Використовуйте лише тоді, коли порядок рядків не має значення:

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

4. Графічні діаграми та вимірювачі (Вкладення зображень)

Збережіть створені діаграми PNG у ${output_dir} та оголосіть їх за допомогою {"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 (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
      ]
    }
  }
}

Вихідний код офіційних плагінів властивостей див. на: ccseer/Seer-Properties.