Desarrollo e implementación de plugins

Plugins de barra de control

Los plugins de barra de control añaden botones de acción personalizados al lado izquierdo de la barra de control inferior en la ventana de vista previa, lo que permite operaciones rápidas e integraciones de herramientas externas para el archivo o carpeta activo.

Crear un plugin de barra de control con un agente de IA

Reemplace el marcador de posición a continuación y luego proporcione la instrucción completa a su agente de programación:

Lea y siga la guía de desarrollo de plugins de control de Seer en https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Trátela como la fuente de verdad para la arquitectura, plugin.json, implementación, validación y empaquetado. Si la guía no está disponible, deténgase e infórmelo antes de continuar.

Antes de realizar cualquier trabajo, inspeccione la Requirement a continuación. Si falta, es texto de marcador de posición sin cambios o es demasiado ambigua para implementarla, haga una pregunta aclaratoria y espere. No infiera el requisito faltante.

Una vez claro, implemente un plugin de control completo e instalable que cumpla con el contrato de proceso Canonical v1 en el espacio de trabajo actual. No modifique Seer ni se detenga en un plan o fragmentos de código.

Siga cada paso de validación aplicable de la guía e informe los resultados reales.

Requirement: [REEMPLACE ESTE MARCADOR DE POSICIÓN con el requisito de su plugin de control, p. ej., abrir VS Code en el directorio actual o copiar la ruta absoluta al portapapeles]

Arquitectura y contrato

• Modelo de proceso: Implementa el contrato de proceso Canonical v1 (backend: "process", capabilities: ["control"]). Seer ejecuta el programa auxiliar a través de la CLI.
• Estado de retorno y reporte de errores:
  • Éxito: El proceso finaliza con código 0 (o coincide con success_exit_codes). Si está configurado "close_after_success": true, Seer cierra automáticamente la ventana de vista previa tras una ejecución correcta.
  • Fallo: El proceso finaliza con un código distinto de cero. Todo lo que se escriba en el error estándar (stderr) es capturado por Seer y se muestra como una notificación Toast de fallo en la aplicación.
• Interfaz de usuario e interacción: Los plugins de barra de control no dibujan ventanas principales persistentes propias. Los programas auxiliares típicos ejecutan tareas en segundo plano, copian texto al portapapeles o invocan cuadros de diálogo nativos del sistema Windows (p. ej., Abrir con, Propiedades, Compartir).

Marcadores de posición de línea de comandos

Un programa auxiliar de control solo recibe la ruta de destino: ${input_file} más los marcadores universales (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) enumerados en la sección compartida Marcadores de posición y tokens de coincidencia a continuación.

Ejemplos de plugin.json (Control)

Ejemplo 1: Acción sobre carpetas (Terminal Here)

Configuración oficial 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
  ]
}

Ejemplo 2: Acción sobre archivos (Explorer Open With)

Configuración oficial 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
  ]
}

Para el código fuente oficial de los plugins de control, consulte: ccseer/Seer-Controls.

Plugins de propiedades

Los plugins de propiedades amplían el motor de inspección de metadatos de Seer. Cuando un usuario presiona Ctrl + I en un archivo o carpeta previsualizado (o abre la ventana Propiedades), los plugins de propiedades coincidentes extraen y muestran metadatos estructurados y gráficos/visores visuales.

Crear un plugin de propiedades con un agente de IA

Reemplace el marcador de posición a continuación y luego proporcione la instrucción completa a su agente de programación:

Lea y siga la guía de desarrollo de plugins de propiedades de Seer en https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Trátela como la fuente de verdad para la arquitectura, plugin.json, implementación, validación y empaquetado. Si la guía no está disponible, deténgase e infórmelo antes de continuar.

Antes de realizar cualquier trabajo, inspeccione la Requirement a continuación. Si falta, es texto de marcador de posición sin cambios o es demasiado ambigua para implementarla, haga una pregunta aclaratoria y espere. No infiera el requisito faltante.

Una vez claro, implemente un plugin de propiedades completo e instalable que cumpla con el contrato de proceso Canonical v1 y la especificación Schema 1 JSON en el espacio de trabajo actual. No modifique Seer ni se detenga en un plan o fragmentos de código.

Siga cada paso de validación aplicable de la guía e informe los resultados reales.

Requirement: [REEMPLACE ESTE MARCADOR DE POSICIÓN con el requisito de su plugin de propiedades, p. ej., extraer y mostrar los parámetros detallados de códec de audio/vídeo y la tasa de bits para archivos MP4]

Arquitectura y contrato

• Modelo de proceso: Implementa el contrato de proceso Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Invocación por CLI: El host pasa los argumentos de la siguiente manera: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Publicación de resultados:
  • El host expande ${output_file} a una ruta base sin extensión (p. ej., <requestDir>/<md5>).
  • El plugin debe escribir su resultado JSON en <output-base>.json (es decir, ${output_file}.json).
  • Los archivos adjuntos visuales (gráficos, histogramas, vectorescopios) deben guardarse en ${output_dir}.
  • Restricción: ${no_cache} está prohibido para plugins de propiedades.
• Política de códigos de salida:
  • Los resultados normales del dominio (p. ej., archivo no firmado, no es un repositorio git, metadatos vacíos) deben salir con el código 0 y describir el estado en el JSON.
  • Salir con un código distinto de cero únicamente ante errores fatales o invocaciones no válidas (las salidas distintas de cero hacen que el host borre el directorio de la solicitud).

Marcadores de posición de línea de comandos

Además de los marcadores universales enumerados en la sección compartida Marcadores de posición y tokens de coincidencia a continuación, que también describe los tokens de coincidencia ${type_*}. Se rechaza ${no_cache} para plugins de propiedades.

Especificación del resultado JSON (Schema 1)

El archivo de resultados ${output_file}.json debe ser un JSON UTF-8 válido que contenga result_schema: 1 y un objeto data:

1. Filas simples (Flat Rows)

Solo cuando el resultado completo es una única fila (p. ej., SHA-256):

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

2. Subgrupo con una matriz ordenada de objetos de clave única (Predeterminado)

Todo lo que produzca más de una fila debe publicarse como exactamente un subgrupo con el nombre del plugin: las filas sueltas de nivel superior colisionan con las filas de todos los demás plugins, que el Inspector muestra en una sola lista. El orden de la matriz es el orden de visualización, por lo que esta es la única forma que permite al plugin decidir la secuencia en la que aparecen las filas:

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

3. Subgrupo con un objeto de valor

value también puede ser un objeto simple, pero sus filas se muestran en el orden de las claves del objeto analizado, que el plugin no puede controlar. Úselo solo cuando el orden de las filas no importe:

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

4. Gráficos y representaciones visuales (Archivos adjuntos de imagen)

Guarde los gráficos PNG generados en ${output_dir} y declárelos 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" } }
      ]
    }
  }
}

Ejemplo de 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
      ]
    }
  }
}

Para el código fuente oficial de plugins de propiedades, consulte: ccseer/Seer-Properties.