في هذه الصفحة

تطوير وتنفيذ الإضافات

يوفر Seer بنية إضافات معيارية تتيح للمطورين توسيع إمكاناته عبر عدة مساحات. حدد إمكانية الإضافة أدناه لاستكشاف مواصفات التطوير الخاصة بها:

إضافات المعاينة (Viewers)

تعمل إضافات المعاينة على توسيع نافذة معاينة شريط المسافة. وهي تدعم بنيتين للتنفيذ: إضافات التحويل (Convert Plugins) و إضافات DLL (SDK v3).

إنشاء إضافة معاينة باستخدام وكيل ذكاء اصطناعي

استبدل العنصر النائب أدناه، ثم أعطِ التعليمات الكاملة لوكيل البرمجة الخاص بك:

اقرأ واتبع دليل تطوير إضافات Seer على https://raw.githubusercontent.com/ccseer/Seer-Plugins/refs/heads/master/plugin_development_guide.md. اعتبره المصدر الوحيد للحقيقة للهندسة المعمارية، وplugin.json، والتنفيذ، والتحقق، والتغليف. إذا كان الدليل غير متاح، فتوقف وأبلغ عن ذلك قبل المتابعة.

قبل القيام بأي عمل، افحص Requirement (الشرط/المتطلب) أدناه. إذا كان مفقودًا، أو نصًا نائبًا لم يتغير، أو غامضًا جدًا بحيث لا يمكن تنفيذه، فاطرح سؤالاً توضيحيًا واحدًا وانتظر. لا تخمن المتطلب المفقود.

بمجرد أن يتضح الأمر، اختر Convert أو DLL وبرر الاختيار بإيجاز، ثم نفذ إضافة كاملة وقابلة للتثبيت في مساحة العمل الحالية. لا تعدل Seer نفسه ولا تتوقف عند خطة أو مقاطع برمجية.

اتبع كل خطوة تحقق واردة في الدليل وأبلغ عن النتائج الفعلية. قم بإجراء اختبار معاينة داخل تطبيق Seer عندما يكون ذلك ممكنًا؛ وإلا فاذكر بوضوح أنه لم يتم إجراء تحقق أثناء التشغيل.

Requirement: [استبدل هذا العنصر النائب بمتطلب إضافة المعاينة الخاصة بك، مثل: عرض مخططات mermaid في معاينة markdown]

إضافات التحويل (Convert)

يعامل Seer إضافات التحويل كمنفذين خارجيين لسطر الأوامر. عندما يضغط المستخدم على مسافة فوق ملف مدعوم، يشغل Seer البرنامج المكوّن، ممررًا مسارات الملفات عبر العناصر النائبة. يقوم البرنامج بتحويل الملف إلى تنسيق يدعمه Seer أصلاً (HTML أو JSON أو TXT أو صور أو غير ذلك)، حيث يقوم Seer بتحميله وعرضه بمجرد انتهاء العملية.

متغيرات العناصر النائبة

العنصر النائب الوصف مثال
${output_file} مسار ملف الإخراج الأساسي؛ ألحق الامتداد المستهدف في الوسيطات. ${output_file}.html
${no_cache} يعطل التخزين المؤقت للتحويل ويخزن الإخراج في دليل الحذف التلقائي، الذي يتم مسحه عند إغلاق نوافذ المعاينة. ${no_cache}

تقبل إضافات التحويل أيضًا العناصر النائبة العامة (${input_file} و ${use_backslash} و ${seer_dir} و ${seer_exe} و ${seerviewer_exe} و ${7z}) ولا تستخدم رموز المطابقة ${type_*}، لأنها تعلن عن مطابقتها في formats بدلاً من extensions. كلاهما مشروح في قسم العناصر النائبة ورموز المطابقة المشترك أدناه.

الملفات التنفيذية وبيئات تشغيل البرامج النصية المدعومة

  • البرامج النصية: نصوص PowerShell البرمجية (.ps1، مدعومة بشكل قياسي عبر PowerShell). بالنسبة إلى Python (.py) أو Node.js (.js) أو البرامج الدفعية (.bat)، قم بتجميعها في ملف .exe مستقل (باستخدام PyInstaller مثلاً) أو قم بتضمين المترجم داخل الحزمة.
  • الملفات الثنائية المخصصة: ملفات CLI تنفيذية مستقلة مجمعة من C/C++ أو Rust أو Go أو C#.

مثال plugin.json (Convert)

{
  "name": "ipynb",
  "version": "1.2.0",
  "type": "convert",
  "roles": [
    "viewer"
  ],
  "entry": "ipynb.ps1",
  "args": [
    "-i",
    "${input_file}",
    "-o",
    "${output_file}.html"
  ],
  "formats": [
    "ipynb"
  ],
  "appMinVersion": "4.1.3",
  "author": "ccseer"
}

إضافات DLL (SDK v3)

للحصول على أقصى أداء للعرض، أو تفاعلية عميقة، أو عروض التدفق، يدعم Seer مكتبات الارتباط الديناميكي الأصلية لـ C++/Qt التي يتم تحميلها مباشرة في إطار العرض عبر QPluginLoader.

  • المواصفات الفنية: C++17، وQt 6.8، وMSVC 2022 (x64)، وCMake 3.22+.
  • الواجهات الأساسية: يرث ViewerBase (تنفيذ عنصر واجهة المستخدم) وينفذ ViewerPluginInterface (بمعرف IID "seer.plugin.interface.preview/3").
  • الحد الأدنى لإصدار التطبيق: يجب أن تعلن إضافات SDK v3 عن "appMinVersion": "4.2.9".

مشاريع مرجعية

المشروع الغرض
F3DViewer عرض النماذج ثلاثية الأبعاد والرؤية البانورامية
OfficeViewer مستندات Office ورسومات CAD
FontViewer فحص أحرف الخطوط وعرضها
JsonTreeViewer شجرة JSON تفاعلية عالية الأداء
Collections جميع إضافات المعاينة الرسمية والمجتمعية

إضافات عناصر التحكم

تضيف إضافات عناصر التحكم أزرار إجراءات مخصصة إلى الجانب الأيسر من شريط التحكم السفلي في نافذة المعاينة، مما يتيح إجراء عمليات سريعة وتكامل أدوات خارجية للملف أو المجلد النشط.

إنشاء إضافة تحكم باستخدام وكيل ذكاء اصطناعي

استبدل العنصر النائب أدناه، ثم أعطِ التعليمات الكاملة لوكيل البرمجة الخاص بك:

اقرأ واتبع دليل تطوير إضافات التحكم في Seer على https://raw.githubusercontent.com/ccseer/Seer-Controls/refs/heads/main/plugin_development_guide.md. اعتبره المصدر الوحيد للحقيقة للهندسة المعمارية، وplugin.json، والتنفيذ، والتحقق، والتغليف. إذا كان الدليل غير متاح، فتوقف وأبلغ عن ذلك قبل المتابعة.

قبل القيام بأي عمل، افحص Requirement (الشرط/المتطلب) أدناه. إذا كان مفقودًا، أو نصًا نائبًا لم يتغير، أو غامضًا جدًا بحيث لا يمكن تنفيذه، فاطرح سؤالاً توضيحيًا واحدًا وانتظر. لا تخمن المتطلب المفقود.

بمجرد أن يتضح الأمر، نفذ إضافة تحكم كاملة وقابلة للتثبيت تلتزم باتفاقية عملية 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 داخل التطبيق.
  • واجهة المستخدم والتفاعل: لا ترسم إضافات التحكم نوافذ رئيسية دائمة خاصة بها. تقوم البرامج المساعدة النموذجية بتشغيل مهام الخلفية، أو نسخ النصوص إلى الحافظة، أو استدعاء مربعات حوار نظام Windows الأصلية (مثل: فتح باستخدام، الخصائص، مشاركة).

العناصر النائبة لسطر الأوامر

يتلقى المساعد مسار الهدف فقط — ${input_file} بالإضافة إلى العناصر النائبة العامة (${use_backslash} و ${seer_dir} و ${seer_exe} و ${seerviewer_exe} و ${7z}) المدرجة في قسم العناصر النائبة ورموز المطابقة المشترك أدناه.

يتم رفض ${output_dir} و ${output_file} و ${no_cache} في بيان التحكم. إذا كان عنصر التحكم يحتاج إلى موقع مؤقت، فيجب عليه حله بنفسه: دليل الملف التنفيذي الخاص به أولاً، ثم الدليل المؤقت للنظام.

أمثلة 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
  ]
}

لإغلاق نافذة المعاينة تلقائيًا بعد النجاح، اضبط "close_after_success": true في البيان.

للحصول على الشيفرة المصدرية الرسمية لإضافات التحكم، راجع: ccseer/Seer-Controls.

إضافات الخصائص

تعمل إضافات الخصائص على توسيع محرك فحص البيانات الوصفية في Seer. عندما يضغط المستخدم على Ctrl + I على ملف أو مجلد معاين (أو يفتح نافذة الخصائص)، تستخرج إضافات الخصائص المطابقة البيانات الوصفية المهيكلة والنطاقات/المخططات الرسومية وتعرضها.

إنشاء إضافة خصائص باستخدام وكيل ذكاء اصطناعي

استبدل العنصر النائب أدناه، ثم أعطِ التعليمات الكاملة لوكيل البرمجة الخاص بك:

اقرأ واتبع دليل تطوير إضافات الخصائص في Seer على https://raw.githubusercontent.com/ccseer/Seer-Properties/refs/heads/main/plugin_development_guide.md. اعتبره المصدر الوحيد للحقيقة للهندسة المعمارية، وplugin.json، والتنفيذ، والتحقق، والتغليف. إذا كان الدليل غير متاح، فتوقف وأبلغ عن ذلك قبل المتابعة.

قبل القيام بأي عمل، افحص Requirement (الشرط/المتطلب) أدناه. إذا كان مفقودًا، أو نصًا نائبًا لم يتغير، أو غامضًا جدًا بحيث لا يمكن تنفيذه، فاطرح سؤالاً توضيحيًا واحدًا وانتظر. لا تخمن المتطلب المفقود.

بمجرد أن يتضح الأمر، نفذ إضافة خصائص كاملة وقابلة للتثبيت تلتزم باتفاقية عملية 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.
    • اخرج برمز غير صفري فقط عند حدوث أخطاء فادحة أو استدعاءات غير صالحة (الخروج غير الصفري يجعل المضيف يمسح دليل الطلب).

العناصر النائبة لسطر الأوامر

العنصر النائب الوصف مثال
${output_file} المسار الأساسي المعين من قِبل المضيف بدون امتداد؛ يجب كتابة النتيجة في ${output_file}.json. C:\Users\...\request_dir\md5_hash
${output_dir} دليل الطلب المعين من قِبل المضيف للمرفقات (المخططات، الصور). C:\Users\...\request_dir

بالإضافة إلى العناصر النائبة العامة ورموز المطابقة ${type_*} المدرجة في قسم العناصر النائبة ورموز المطابقة المشترك أدناه. يُرفض ${no_cache} لإضافات الخصائص.

مواصفات Result JSON (Schema 1)

يجب أن يكون ملف النتيجة ${output_file}.json بتنسيق UTF-8 JSON صالحًا يحتوي على result_schema: 1 وكائن data:

1. صفوف مسطحة (Flat Rows)

فقط عندما تكون النتيجة الكاملة صفًا واحدًا (مثل SHA-256):

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

2. مجموعة فرعية مع مصفوفة مرتبة من كائنات ذات مفتاح فردي (افتراضي)

أي شيء ينتج أكثر من صف يجب نشره كمجموعة فرعية واحدة بالضبط تحمل اسم الإضافة — الصفوف المتفرقة في المستوى الأعلى تتعارض مع صفوف جميع الإضافات الأخرى، ويعرضها الفاحص (Inspector) في قائمة واحدة. ترتيب المصفوفة هو ترتيب العرض، لذا هذا هو الشكل الوحيد الذي يتيح للإضافة تحديد تسلسل ظهور الصفوف:

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

العناصر النائبة ورموز المطابقة

يقوم Seer بتوسيع هذه الرموز في arguments. يتم التحقق من العناصر النائبة التي يمكن لإمكانية استخدامها من قِبل المضيف عند تحميل البيان — يعد استخدام رمز غير مدعوم خطأً في تحميل البيان وليس مجرد تحذير أثناء التشغيل.

متاح لكل إمكانية

العنصر النائب الوصف مثال
${input_file} المسار المطلق للملف أو المجلد الذي تتم معاينته. C:\Docs\sample.pdf
${use_backslash} علامة اختيارية لتنسيق فواصل المسار باستخدام الشرطات المائلة العكسية لـ Windows (\). ${use_backslash}
${seer_dir} الدليل الذي يحتوي على Seer.exe. C:\Program Files\Seer
${seer_exe} المسار المطلق لملف Seer.exe. C:\Program Files\Seer\Seer.exe
${seerviewer_exe} المسار المطلق لملف SeerViewer.exe. C:\Program Files\Seer\SeerViewer.exe
${7z} المسار المطلق لملف 7z.exe المرفق مع Seer. C:\Program Files\Seer\plugins\7z.exe
${theme} السمة الحالية لـ Seer، وتُحوَّل إلى dark أو light. عنصر نائب للبيانات لا يمكن استخدامه كـ command كامل. dark
${lang} لغة Seer الحالية، وتُحوَّل بتنسيق BCP-47 (مثل en، zh-CN). عنصر نائب للبيانات لا يمكن استخدامه كـ command كامل. en
${screenshot} المسار المطلق للقطة شاشة PNG مؤقتة للعرض الحالي. C:\Users\Username\AppData\Local\Temp\Seer\screenshot\view_1.png

عناصر نائبة خاصة بكل إمكانية

العنصر النائب المعاينة (Preview) التحكم (Control) الخصائص (Property)
${output_file} مسار الإخراج الأساسي؛ ألحق الامتداد المستهدف، مثل ${output_file}.html غير مدعوم مسار أساسي بدون امتداد؛ يجب كتابة النتيجة في ${output_file}.json
${output_dir} غير مدعوم غير مدعوم دليل الطلب للمرفقات (المخططات، الصور)
${no_cache} يعطل التخزين المؤقت للتحويل ويخزن الإخراج في دليل الحذف التلقائي غير مدعوم غير مدعوم

يتلقى مساعد التحكم مسار الهدف فقط. إذا احتاج إلى موقع مؤقت، فيجب عليه حله بنفسه: دليل الملف التنفيذي الخاص به أولاً، ثم الدليل المؤقت للنظام.

رموز مطابقة extensions

بالإضافة إلى الامتدادات القياسية (مثل: ["png", "zip"])، يقبل extensions رموزًا تطابق فئات واسعة. تنطبق هذه الرموز على الإضافات التي تعلن عن extensions (التحكم والخصائص)؛ بينما تعلن إضافات التحويل عن formats بدلاً من ذلك ولا تستخدمها.

الرمز الوصف
${type_folder} يطابق الدلائل والمجلدات.
${type_file} يطابق جميع الملفات (بما في ذلك الملفات التي ليس لها امتداد).
${type_all} يطابق كل شيء (الملفات والمجلدات على حد سواء).
${type_image} يطابق الصور المدعومة بواسطة عارض الصور المدمج في Seer.
${type_media} يطابق تنسيقات الصوت والفيديو.
${type_web} يطابق ملفات الويب مثل HTML و Markdown.
${type_text} يطابق ملفات النصوص والشيفرات البرمجية والتكوينات.
${type_pdf} يطابق مستندات PDF.
${type_none} يطابق الملفات الخارجة عن الفئات أعلاه (مثل الأرشيفات والملفات التنفيذية).

التغليف والاختبار داخل التطبيق

بمجرد تطوير الإضافة، يجب تغليفها في أرشيف ZIP قياسي للتثبيت. ينطبق هذا على جميع إمكانيات الإضافات.

معايير التغليف

  1. توثيق الحزمة: يجب أن تتضمن كل حزمة مستقلة للتحكم أو الخصائص ملف PACKAGE_README.md (الوصف بالإضافة إلى جدول ## Options & Arguments)، ويتم وضعه كـ README.md في جذر الحزمة.
  2. تخطيط الجذر المسطح: بالنسبة لحزم التحكم والخصائص (Canonical v1)، يجب أن يتواجد plugin.json والملف التنفيذي/البرنامج النصي و README.md والتبعيات أثناء التشغيل مباشرة في جذر الأرشيف. لا تقم بتغليفها داخل مجلد إضافي، ولا تخلط أبدًا بين الإدخالات المسطحة والمتداخلة — يرفض المضيف الأرشيف الذي يحتوي على جذر حزمة غامض.

    تستخدم إضافات التحويل التقليدية المثبتة من الكتالوج عبر الإنترنت التخطيط المعاكس: مجلد مستوى أعلى باسم <archive-name>/ يغلف ملفات الحزمة. اتبع دليل إضافات التحويل لتلك الحالة؛ التخطيطان غير قابلين للتبادل.

  3. أقصى ضغط: يوصى باستخدام 7-Zip مع أقصى ضغط Deflate: powershell 7z a -tzip -mx=9 my-plugin-1.0.0.zip .\*

الاختبار المحلي داخل التطبيق

  1. افتح إعدادات Seer وانتقل إلى القسم المستهدف:
    • إضافات المعاينة: الإعدادات > الملحقات -> علامة التبويب المحلية
    • إضافات عناصر التحكم: الإعدادات > التحكم
    • إضافات الخصائص: الإعدادات > الخصائص
  2. انقر فوق + أسفل القائمة وحدد أرشيف .zip (أو plugin.json من مجلدك المحلي).
  3. يتحقق Seer تلقائيًا من الحزمة ويقوم بتحميلها. تحقق من الإعدادات وانقر فوق موافق للتفعيل.