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

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

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

Создание плагина панели управления с помощью ИИ-агента

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

Прочитайте и следуйте руководству по разработке плагинов панели управления 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 для просматриваемого файла или папки (или открывает окно «Свойства»), соответствующие плагины свойств извлекают и отображают структурированные метаданные и графические осциллограммы/диаграммы.

Создание плагина свойств с помощью ИИ-агента

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

Прочитайте и следуйте руководству по разработке плагинов свойств 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} отклоняется для плагинов свойств.

Спецификация формата Result JSON (Schema 1)

Файл результата ${output_file}.json должен быть корректным JSON в кодировке UTF-8, содержащим 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.