プラグインの開発と実装

コントロールプラグイン

コントロールプラグインは、プレビューウィンドウの下部コントロールバーの左側にカスタムアクションボタンを追加し、アクティブなファイルまたはフォルダーに対するクイック操作や外部ツール連携を可能にします。

AI エージェントを使用したコントロールプラグインの構築

以下のプレースホルダーを置き換えてから、コーディングエージェントに完全な指示を与えてください：

https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md にある Seer コントロールプラグイン開発ガイドを読み、従ってください。これをアーキテクチャ、plugin.json、実装、検証、およびパッケージングの信頼できる唯一の情報源（Single Source of Truth）として扱ってください。ガイドが利用できない場合は、続行する前に停止して報告してください。

作業を行う前に、以下の Requirement（要件）を確認してください。欠落している場合、変更されていないプレースホルダーテキストである場合、または実装するには曖昧すぎる場合は、確認の質問を 1 つ行って待機してください。欠落している要件を推測しないでください。

明確になったら、現在のワークスペースで 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 エラー通知 として表示されます。
• UI と操作: コントロールプラグインは独自の常駐メインウィンドウを描画しません。一般的なヘルパーは、バックグラウンドタスクの実行、クリップボードへのテキストのコピー、またはネイティブ 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 を押す（またはプロパティウィンドウを開く）と、一致するプロパティプラグインが構造化メタデータや視覚的なスコープ/チャートを抽出して表示します。

AI エージェントを使用したプロパティプラグインの構築

以下のプレースホルダーを置き換えてから、コーディングエージェントに完全な指示を与えてください：

https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md にある Seer プロパティプラグイン開発ガイドを読み、従ってください。これをアーキテクチャ、plugin.json、実装、検証、およびパッケージングの信頼できる唯一の情報源（Single Source of Truth）として扱ってください。ガイドが利用できない場合は、続行する前に停止して報告してください。

作業を行う前に、以下の Requirement（要件）を確認してください。欠落している場合、変更されていないプレースホルダーテキストである場合、または実装するには曖昧すぎる場合は、確認の質問を 1 つ行って待機してください。欠落している要件を推測しないでください。

明確になったら、現在のワークスペースで 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} は拒否されます。

結果 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. 単一キーオブジェクトの順序付き配列を持つサブグループ (デフォルト)

複数の行を生成する結果は、プラグインにちなんだ名前のちょうど 1 つのサブグループとして公開しなければなりません。トップレベルに散在する行は他のすべてのプラグインの行と衝突し、インスペクターはそれらを 1 つのリストに表示します。配列の順序がそのまま表示順序になるため、行の表示順序をプラグイン自身が決められるのはこの形式だけです：

{
  "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。