Desenvolvimento e Implementação de Plugins

Plugins de barra de controle

Os plugins de barra de controle adicionam botões de ação personalizados ao lado esquerdo da barra de controle inferior na janela de pré-visualização, permitindo operações rápidas e integrações com ferramentas externas para o arquivo ou pasta ativo.

Criar um plugin de barra de controle com um agente de IA

Substitua o marcador de posição abaixo e forneça a instrução completa ao seu agente de codificação:

Leia e siga o guia de desenvolvimento de plugins de controle do Seer em https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Trate-o como a fonte da verdade para arquitetura, plugin.json, implementação, validação e empacotamento. Se o guia não estiver disponível, pare e relate isso antes de prosseguir.

Antes de iniciar qualquer trabalho, inspecione a Requirement abaixo. Se estiver ausente, mantiver o texto do marcador inalterado ou for muito ambígua para implementar, faça uma pergunta de esclarecimento e aguarde. Não deduza o requisito ausente.

Depois de esclarecido, implemente um plugin de controle completo e instalável em conformidade com o contrato de processo Canonical v1 no espaço de trabalho atual. Não modifique o próprio Seer nem pare em um plano ou trechos de código.

Siga todas as etapas de validação aplicáveis do guia e relate os resultados reais.

Requirement: [SUBSTITUA ESTE MARCADOR DE POSIÇÃO pelo requisito do seu plugin de controle, por exemplo, abrir o VS Code na pasta atual ou copiar o caminho absoluto para a área de transferência]

Arquitetura e contrato

• Modelo de processo: Implementa o contrato de processo Canonical v1 (backend: "process", capabilities: ["control"]). O Seer executa o utilitário auxiliar via CLI.
• Código de retorno e relatório de erros:
  • Sucesso: O processo é encerrado com o código 0 (ou corresponde a success_exit_codes). Se "close_after_success": true estiver configurado, o Seer fecha automaticamente a janela de pré-visualização após o sucesso da execução.
  • Falha: O processo é encerrado com um código diferente de zero. Tudo o que for gravado na saída de erro padrão (stderr) é capturado pelo Seer e exibido como uma notificação Toast de falha no aplicativo.
• Interface e interação: Os plugins de barra de controle não desenham janelas principais persistentes próprias. Os utilitários típicos executam tarefas em segundo plano, copiam texto para a área de transferência ou chamam caixas de diálogo nativas do sistema Windows (por exemplo, Abrir com, Propriedades, Compartilhar).

Marcadores de linha de comando

Um utilitário de controle recebe apenas o caminho de destino — ${input_file} mais os marcadores universais (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) listados na seção compartilhada Marcadores de posição e tokens de correspondência abaixo.

Exemplos de plugin.json (Control)

Exemplo 1: Ação em pasta (Terminal Here)

Configuração oficial do 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
  ]
}

Exemplo 2: Ação em arquivo (Explorer Open With)

Configuração oficial do 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 obter o código-fonte oficial de plugins de controle, consulte: ccseer/Seer-Controls.

Plugins de propriedades

Os plugins de propriedades expandem o mecanismo de inspeção de metadados do Seer. Quando o usuário pressiona Ctrl + I em um arquivo ou pasta pré-visualizado (ou abre a janela Propriedades), os plugins de propriedades correspondentes extraem e exibem metadados estruturados e gráficos/painéis visuais.

Criar um plugin de propriedades com um agente de IA

Substitua o marcador de posição abaixo e forneça a instrução completa ao seu agente de codificação:

Leia e siga o guia de desenvolvimento de plugins de propriedades do Seer em https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Trate-o como a fonte da verdade para arquitetura, plugin.json, implementação, validação e empacotamento. Se o guia não estiver disponível, pare e relate isso antes de prosseguir.

Antes de iniciar qualquer trabalho, inspecione a Requirement abaixo. Se estiver ausente, mantiver o texto do marcador inalterado ou for muito ambígua para implementar, faça uma pergunta de esclarecimento e aguarde. Não deduza o requisito ausente.

Depois de esclarecido, implemente um plugin de propriedades completo e instalável em conformidade com o contrato de processo Canonical v1 e com a especificação Schema 1 JSON no espaço de trabalho atual. Não modifique o próprio Seer nem pare em um plano ou trechos de código.

Siga todas as etapas de validação aplicáveis do guia e relate os resultados reais.

Requirement: [SUBSTITUA ESTE MARCADOR DE POSIÇÃO pelo requisito do seu plugin de propriedades, por exemplo, extrair e exibir parâmetros detalhados de codec de áudio/vídeo e taxa de bits para arquivos MP4]

Arquitetura e contrato

• Modelo de processo: Implementa o contrato de processo Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Invocação via CLI: O host passa os seguintes argumentos: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Publicação da saída:
  • O host expande ${output_file} para um caminho base sem extensão (por exemplo, <requestDir>/<md5>).
  • O plugin deve gravar o resultado JSON em <output-base>.json (ou seja, ${output_file}.json).
  • Anexos visuais (gráficos, histogramas, vetorscópios) devem ser salvos em ${output_dir}.
  • Restrição: ${no_cache} é proibido para plugins de propriedades.
• Política de código de saída:
  • Resultados esperados de domínio (por exemplo, arquivo não assinado, não é um repositório git, metadados vazios) devem sair com o código 0 e descrever o status no JSON.
  • Saia com código diferente de zero apenas em erros fatais ou invocações inválidas (saídas diferentes de zero fazem com que o host limpe o diretório de requisição).

Marcadores de linha de comando

Além dos marcadores universais listados na seção compartilhada Marcadores de posição e tokens de correspondência abaixo, que também descreve os tokens de correspondência ${type_*}. O uso de ${no_cache} é rejeitado para plugins de propriedades.

Especificação de resultado JSON (Schema 1)

O arquivo de resultado ${output_file}.json deve ser um JSON UTF-8 válido contendo result_schema: 1 e um objeto data:

1. Linhas simples (Flat Rows)

Somente quando o resultado inteiro é uma única linha (por exemplo, SHA-256):

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

2. Subgrupo com uma matriz ordenada de objetos de chave única (Padrão)

Tudo o que produzir mais de uma linha deve ser publicado como exatamente um subgrupo nomeado após o plugin — linhas soltas de nível superior colidem com as linhas de todos os outros plugins, que o Inspetor mostra em uma única lista. A ordem da matriz é a ordem de exibição, portanto esta é a única forma que permite ao plugin decidir a sequência em que as linhas aparecem:

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

3. Subgrupo com um objeto de valor

value também pode ser um objeto simples, mas suas linhas são renderizadas na ordem das chaves do objeto analisado, que o plugin não pode controlar. Use-o apenas quando a ordem das linhas não importar:

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

4. Gráficos e painéis visuais (Anexos de imagem)

Salve os gráficos PNG gerados em ${output_dir} e declare-os com {"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" } }
      ]
    }
  }
}

Exemplo 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 obter o código-fonte oficial de plugins de propriedades, consulte: ccseer/Seer-Properties.