插件开发与实现

控制栏插件 (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。