外掛開發與實現

控制列外掛 (Control Plugins)

控制列外掛在預覽視窗底部控制列左側新增自訂操作按鈕，針對當前啟用的檔案或資料夾啟用快捷操作及外部工具連動。

使用 AI 助手構建控制列外掛

取代下方的需求預留位置，然後向您的程式設計助手傳送完整指令：

請閱讀並遵循位於 https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md 的 Seer 控制列外掛開發指南。將其視為架構、plugin.json、實現、驗證和打包的唯一事實來源。如果該指南不可用，請在繼續之前停止並回報。

在開始任何工作之前，請檢查下方的 Requirement（需求）。如果其缺失、為未變更的預留位置文字或過於模糊而無法實現，請提出一個澄清問題並等待。請勿推測缺失的需求。

明確後，在當前工作區中實現一個完整的、符合 Canonical v1 行程協定的可安裝控制列外掛。請勿修改 Seer 本身，也不要僅停留在計畫或程式碼片段上。

遵循指南中所有適用的驗證步驟並回報實際結果。

Requirement: [將此預留位置取代為控制列外掛需求，例如：在當前資料夾開啟 VS Code 或複製絕對路徑到剪貼簿]

架構與協定

• 處理序模型：實現 Canonical v1 行程協定（backend: "process", capabilities: ["control"]）。Seer 透過命令列執行對應輔助程式。
• 傳回狀態與錯誤回報：
  • 成功：處理序以結束代碼 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。

屬性外掛 (Property Plugins)

屬性外掛用於擴充 Seer 的中繼資料檢查引擎。當使用者對預覽的檔案或資料夾按下 Ctrl + I（或開啟屬性視窗）時，相符的屬性外掛將擷取並顯示結構化中繼資料和視覺化圖表。

使用 AI 助手構建屬性外掛

取代下方的需求預留位置，然後向您的程式設計助手傳送完整指令：

請閱讀並遵循位於 https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md 的 Seer 屬性外掛開發指南。將其視為架構、plugin.json、實現、驗證和打包的唯一事實來源。如果該指南不可用，請在繼續之前停止並回報。

在開始任何工作之前，請檢查下方的 Requirement（需求）。如果其缺失、為未變更的預留位置文字或過於模糊而無法實現，請提出一個澄清問題並等待。請勿推測缺失的需求。

明確後，在當前工作區中實現一個完整的、符合 Canonical v1 行程協定與 Schema 1 JSON 規範的可安裝屬性外掛。請勿修改 Seer 本身，也不要僅停留在計畫或程式碼片段上。

遵循指南中所有適用的驗證步驟並回報實際結果。

Requirement: [將此預留位置取代為屬性外掛需求，例如：擷取並顯示 MP4 檔案的詳細音訊/視訊轉碼器參數與位元速率]

架構與協定

• 處理序模型：實現 Canonical v1 行程協定（backend: "process", capabilities: ["property"], result_schema: 1）。
• 命令列叫用：宿主傳遞參數如下： --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 必須是包含 result_schema: 1 和 data 物件的合法 UTF-8 JSON：

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。