Pengembangan & Implementasi Plugin

Plugin Kontrol

Plugin kontrol menambahkan tombol tindakan kustom ke sisi kiri Bilah Kontrol bawah di jendela pratinjau, memungkinkan operasi cepat dan integrasi alat eksternal untuk file atau folder yang aktif.

Membangun Plugin Kontrol dengan Agen AI

Ganti teks placeholder di bawah ini, lalu berikan instruksi lengkap ke agen pengkodean Anda:

Baca dan ikuti panduan pengembangan plugin kontrol Seer di https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Perlakukan itu sebagai sumber kebenaran tunggal untuk arsitektur, plugin.json, implementasi, validasi, dan pengemasan. Jika panduan tidak tersedia, hentikan dan laporkan sebelum melanjutkan.

Sebelum melakukan pekerjaan apa pun, periksa Requirement (Persyaratan) di bawah ini. Jika hilang, teks placeholder belum diubah, atau terlalu kabur untuk diimplementasikan, ajukan satu pertanyaan klarifikasi dan tunggu. Jangan mengira-ngira persyaratan yang hilang.

Setelah jelas, implementasikan plugin kontrol lengkap yang dapat diinstal yang mematuhi kontrak proses Canonical v1 di ruang kerja saat ini. Jangan mengubah Seer itu sendiri atau berhenti pada rencana atau cuplikan kode.

Ikuti setiap langkah validasi yang berlaku dalam panduan dan laporkan hasil sebenarnya.

Requirement: [GANTI PLACEHOLDER INI dengan persyaratan plugin kontrol Anda, mis. buka VS Code di direktori saat ini atau salin jalur absolut ke clipboard]

Arsitektur & Kontrak

• Model Proses: Mengimplementasikan kontrak proses Canonical v1 (backend: "process", capabilities: ["control"]). Seer mengeksekusi helper melalui CLI.
• Status Pengembalian & Pelaporan Kesalahan:
  • Berhasil: Proses keluar dengan kode 0 (atau cocok dengan success_exit_codes). Jika "close_after_success": true dikonfigurasi, Seer secara otomatis menutup jendela pratinjau setelah eksekusi berhasil.
  • Gagal: Proses keluar dengan kode non-nol. Apa pun yang ditulis ke standar error (stderr) akan ditangkap oleh Seer dan ditampilkan sebagai pemberitahuan kesalahan Toast dalam aplikasi.
• UI & Interaksi: Plugin kontrol tidak menggambar jendela utama permanen mereka sendiri. Helper pada umumnya menjalankan tugas latar belakang, menyalin teks ke clipboard, atau memanggil dialog sistem Windows native (mis. Buka dengan, Properti, Bagikan).

Placeholder Baris Perintah

Helper kontrol hanya menerima jalur target — ${input_file} ditambah placeholder universal (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) yang tercantum dalam bagian bersama Placeholder & Token Pencocokan di bawah ini.

Contoh plugin.json (Control)

Contoh 1: Tindakan Folder (Terminal Here)

Konfigurasi plugin Terminal Here resmi:

{
  "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
  ]
}

Contoh 2: Tindakan File (Explorer Open With)

Konfigurasi plugin Explorer Open With resmi:

{
  "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
  ]
}

Untuk kode sumber plugin kontrol resmi, lihat: ccseer/Seer-Controls.

Plugin Properti

Plugin properti memperluas mesin inspeksi metadata Seer. Saat pengguna menekan Ctrl + I pada file atau folder yang dipratinjau (atau membuka jendela Properti), plugin properti yang cocok mengekstrak dan menampilkan metadata terstruktur serta cakupan/bagan grafis.

Membangun Plugin Properti dengan Agen AI

Ganti teks placeholder di bawah ini, lalu berikan instruksi lengkap ke agen pengkodean Anda:

Baca dan ikuti panduan pengembangan plugin properti Seer di https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Perlakukan itu sebagai sumber kebenaran tunggal untuk arsitektur, plugin.json, implementasi, validasi, dan pengemasan. Jika panduan tidak tersedia, hentikan dan laporkan sebelum melanjutkan.

Sebelum melakukan pekerjaan apa pun, periksa Requirement (Persyaratan) di bawah ini. Jika hilang, teks placeholder belum diubah, atau terlalu kabur untuk diimplementasikan, ajukan satu pertanyaan klarifikasi dan tunggu. Jangan mengira-ngira persyaratan yang hilang.

Setelah jelas, implementasikan plugin properti lengkap yang dapat diinstal yang mematuhi kontrak proses Canonical v1 dan spesifikasi Schema 1 JSON di ruang kerja saat ini. Jangan mengubah Seer itu sendiri atau berhenti pada rencana atau cuplikan kode.

Ikuti setiap langkah validasi yang berlaku dalam panduan dan laporkan hasil sebenarnya.

Requirement: [GANTI PLACEHOLDER INI dengan persyaratan plugin properti Anda, mis. ekstrak dan tampilkan parameter codec audio/video terperinci dan bitrate untuk file MP4]

Arsitektur & Kontrak

• Model Proses: Mengimplementasikan kontrak proses Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Pemanggilan CLI: Host meneruskan: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Publikasi Output:
  • Host memperluas ${output_file} menjadi jalur dasar tanpa ekstensi (mis. <requestDir>/<md5>).
  • Plugin harus menulis hasil JSON-nya ke <output-base>.json (yaitu ${output_file}.json).
  • Lampiran visual (bagan, histogram, vectorscope) harus disimpan ke dalam ${output_dir}.
  • Batasan: ${no_cache} dilarang untuk plugin properti.
• Kebijakan Kode Keluar:
  • Hasil domain yang diharapkan (mis. file yang tidak ditandatangani, bukan repositori git, metadata kosong) harus keluar dengan kode 0 dan menjelaskan statusnya dalam JSON.
  • Keluar dengan kode non-nol hanya pada kesalahan fatal atau pemanggilan yang tidak valid (keluar non-nol menyebabkan host menghapus direktori permintaan).

Placeholder Baris Perintah

Ditambah placeholder universal dan token pencocokan ${type_*} yang tercantum dalam bagian bersama Placeholder & Token Pencocokan di bawah ini. ${no_cache} ditolak untuk plugin properti.

Spesifikasi Result JSON (Schema 1)

File hasil ${output_file}.json harus berupa JSON UTF-8 yang valid yang berisi result_schema: 1 dan objek data:

1. Baris Datar (Flat Rows)

Hanya ketika seluruh hasil berupa satu baris (mis. SHA-256):

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

2. Subgrup dengan Larik Berurutan dari Objek Kunci Tunggal (Bawaan)

Apa pun yang menghasilkan lebih dari satu baris harus dipublikasikan sebagai tepat satu subgrup yang dinamai sesuai plugin — baris longgar di tingkat atas akan bertabrakan dengan baris semua plugin lain, yang ditampilkan Pemeriksa dalam satu daftar. Urutan larik adalah urutan tampilan, jadi ini adalah satu-satunya bentuk yang memungkinkan plugin menentukan urutan kemunculan baris:

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

3. Subgrup dengan Objek Nilai

value juga bisa berupa objek biasa, tetapi barisnya dirender sesuai urutan kunci objek yang diurai, yang tidak dapat dikendalikan plugin. Gunakan hanya jika urutan baris tidak penting:

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

4. Bagan Grafis & Cakupan (Lampiran Gambar)

Simpan bagan PNG yang dihasilkan ke dalam ${output_dir}, dan deklarasikan dengan {"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" } }
      ]
    }
  }
}

Contoh 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
      ]
    }
  }
}

Untuk kode sumber plugin properti resmi, lihat: ccseer/Seer-Properties.