Phát triển & Triển khai Plugin

Plugin Điều khiển

Plugin điều khiển thêm các nút hành động tùy chỉnh vào phía bên trái của Thanh điều khiển phía dưới trong cửa sổ xem trước, hỗ trợ các thao tác nhanh và tích hợp công cụ bên ngoài cho tệp hoặc thư mục đang hoạt động.

Xây dựng Plugin Điều khiển với Agent AI

Thay thế phần giữ chỗ bên dưới, sau đó cung cấp toàn bộ hướng dẫn cho agent lập trình của bạn:

Đọc và làm theo hướng dẫn phát triển plugin điều khiển Seer tại https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. Coi đây là nguồn sự thật duy nhất cho kiến trúc, plugin.json, triển khai, xác minh và đóng gói. Nếu hướng dẫn không khả dụng, hãy dừng lại và báo cáo trước khi tiếp tục.

Trước khi thực hiện bất kỳ công việc nào, hãy kiểm tra Requirement (Yêu cầu) bên dưới. Nếu nó thiếu, là văn bản giữ chỗ chưa thay đổi hoặc quá mơ hồ để triển khai, hãy đặt một câu hỏi làm rõ và chờ đợi. Không suy đoán yêu cầu bị thiếu.

Sau khi rõ ràng, hãy triển khai một plugin điều khiển hoàn chỉnh, có thể cài đặt tuân thủ theo hợp đồng tiến trình Canonical v1 trong không gian làm việc hiện tại. Không sửa đổi bản thân Seer hoặc dừng lại ở kế hoạch hay đoạn mã.

Làm theo từng bước xác minh áp dụng trong hướng dẫn và báo cáo kết quả thực tế.

Requirement: [THAY THẾ VĂN BẢN GIỮ CHỖ NÀY bằng yêu cầu plugin điều khiển của bạn, ví dụ: mở VS Code trong thư mục hiện tại hoặc sao chép đường dẫn tuyệt đối vào clipboard]

Kiến trúc & Hợp đồng

• Mô hình Tiến trình: Triển khai hợp đồng tiến trình Canonical v1 (backend: "process", capabilities: ["control"]). Seer thực thi chương trình trợ giúp qua CLI.
• Trạng thái Trả về & Báo cáo Lỗi:
  • Thành công: Tiến trình thoát với mã 0 (hoặc khớp với success_exit_codes). Nếu được cấu hình "close_after_success": true, Seer sẽ tự động đóng cửa sổ xem trước sau khi thực thi thành công.
  • Thất bại: Tiến trình thoát với mã khác không. Bất kỳ nội dung nào được ghi vào luồng lỗi chuẩn (stderr) sẽ được Seer ghi nhận và hiển thị dưới dạng thông báo lỗi Toast trong ứng dụng.
• Giao diện người dùng & Tương tác: Plugin điều khiển không tự vẽ cửa sổ chính thường trú. Các trình trợ giúp thông thường thực hiện tác vụ ngầm, sao chép văn bản vào clipboard, hoặc gọi hộp thoại hệ thống Windows gốc (ví dụ: Mở bằng, Thuộc tính, Chia sẻ).

Trình giữ chỗ Dòng lệnh

Trình trợ giúp điều khiển chỉ nhận đường dẫn đối tượng — ${input_file} cộng với các biến giữ chỗ chung (${use_backslash}, ${seer_dir}, ${seer_exe}, ${seerviewer_exe}, ${7z}) được liệt kê trong phần chung Trình giữ chỗ & Mã khớp bên dưới.

Ví dụ plugin.json (Control)

Ví dụ 1: Hành động Thư mục (Terminal Here)

Cấu hình plugin Terminal Here chính thức:

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

Ví dụ 2: Hành động Tệp (Explorer Open With)

Cấu hình plugin Explorer Open With chính thức:

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

Để xem mã nguồn plugin điều khiển chính thức, hãy xem: ccseer/Seer-Controls.

Plugin Thuộc tính

Plugin thuộc tính mở rộng công cụ kiểm tra siêu dữ liệu của Seer. Khi người dùng nhấn Ctrl + I trên tệp hoặc thư mục đang xem trước (hoặc mở cửa sổ Thuộc tính), các plugin thuộc tính phù hợp sẽ trích xuất và hiển thị siêu dữ liệu có cấu trúc cùng các biểu đồ/phạm vi trực quan.

Xây dựng Plugin Thuộc tính với Agent AI

Thay thế phần giữ chỗ bên dưới, sau đó cung cấp toàn bộ hướng dẫn cho agent lập trình của bạn:

Đọc và làm theo hướng dẫn phát triển plugin thuộc tính Seer tại https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. Coi đây là nguồn sự thật duy nhất cho kiến trúc, plugin.json, triển khai, xác minh và đóng gói. Nếu hướng dẫn không khả dụng, hãy dừng lại và báo cáo trước khi tiếp tục.

Trước khi thực hiện bất kỳ công việc nào, hãy kiểm tra Requirement (Yêu cầu) bên dưới. Nếu nó thiếu, là văn bản giữ chỗ chưa thay đổi hoặc quá mơ hồ để triển khai, hãy đặt một câu hỏi làm rõ và chờ đợi. Không suy đoán yêu cầu bị thiếu.

Sau khi rõ ràng, hãy triển khai một plugin thuộc tính hoàn chỉnh, có thể cài đặt tuân thủ theo hợp đồng tiến trình Canonical v1 và đặc tả JSON Schema 1 trong không gian làm việc hiện tại. Không sửa đổi bản thân Seer hoặc dừng lại ở kế hoạch hay đoạn mã.

Làm theo từng bước xác minh áp dụng trong hướng dẫn và báo cáo kết quả thực tế.

Requirement: [THAY THẾ VĂN BẢN GIỮ CHỖ NÀY bằng yêu cầu plugin thuộc tính của bạn, ví dụ: trích xuất và hiển thị các tham số codec âm thanh/video chi tiết cùng bitrate cho tệp MP4]

Kiến trúc & Hợp đồng

• Mô hình Tiến trình: Triển khai hợp đồng tiến trình Canonical v1 (backend: "process", capabilities: ["property"], result_schema: 1).
• Gọi CLI: Máy chủ lưu trữ truyền: --input "${input_file}" --output "${output_file}" --output-dir "${output_dir}"
• Xuất bản Đầu ra:
  • Máy chủ lưu trữ mở rộng ${output_file} thành đường dẫn cơ sở không có phần mở rộng (ví dụ: <requestDir>/<md5>).
  • Plugin phải ghi kết quả JSON của mình vào <output-base>.json (tức là ${output_file}.json).
  • Các tệp đính kèm trực quan (biểu đồ, biểu đồ tần suất histogram, vectorscope) phải được lưu vào ${output_dir}.
  • Ràng buộc: ${no_cache} bị nghiêm cấm đối với plugin thuộc tính.
• Chính sách Mã Thoát:
  • Các kết quả miền thông thường (ví dụ: tệp chưa ký, không phải kho lưu trữ git, siêu dữ liệu trống) phải thoát với mã 0 và mô tả trạng thái trong JSON.
  • Chỉ thoát với mã khác không khi xảy ra lỗi nghiêm trọng hoặc lệnh gọi không hợp lệ (thoát khác không khiến máy chủ lưu trữ xóa sạch thư mục yêu cầu đó).

Trình giữ chỗ Dòng lệnh

Cùng với các biến giữ chỗ chung và mã khớp ${type_*} được liệt kê trong phần chung Trình giữ chỗ & Mã khớp bên dưới. ${no_cache} bị từ chối đối với các plugin thuộc tính.

Đặc tả Result JSON (Schema 1)

Tệp kết quả ${output_file}.json phải là JSON UTF-8 hợp lệ chứa result_schema: 1 và một đối tượng data:

1. Hàng phẳng (Flat Rows)

Chỉ khi toàn bộ kết quả là một hàng duy nhất (ví dụ: SHA-256):

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

2. Nhóm con với mảng có thứ tự của các đối tượng khóa đơn (Mặc định)

Bất kỳ thứ gì tạo ra nhiều hơn một hàng đều phải được xuất bản dưới dạng đúng một nhóm con được đặt tên theo plugin — các hàng rời rạc ở cấp cao nhất sẽ xung đột với các hàng của mọi plugin khác, mà Trình kiểm tra hiển thị trong một danh sách. Thứ tự của mảng là thứ tự hiển thị, vì vậy đây là hình thức duy nhất cho phép plugin quyết định trình tự xuất hiện của các hàng:

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

3. Nhóm con với đối tượng giá trị

value cũng có thể là một đối tượng thuần túy, nhưng các hàng của nó được hiển thị theo thứ tự khóa của đối tượng đã phân tích, mà plugin không thể kiểm soát. Chỉ sử dụng khi thứ tự các hàng không quan trọng:

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

4. Biểu đồ & Đồ thị trực quan (Tệp đính kèm hình ảnh)

Lưu biểu đồ PNG đã tạo vào ${output_dir} và khai báo chúng bằng {"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" } }
      ]
    }
  }
}

Ví dụ 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
      ]
    }
  }
}

Để xem mã nguồn plugin thuộc tính chính thức, hãy xem: ccseer/Seer-Properties.