SuperDiagnosticTool

# SuperDiagnosticTool

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/11160/8b0da1a673733dc9731164bd4d4a3ecc6a137e583d070725852e8173311ef7fc.png" alt="أيقونة SuperDiagnosticTool" width="200"/>
</p>

<p align="center">
  <strong>أداة تشخيص وإصلاح لنظام Windows مدعومة بالذكاء الاصطناعي</strong>
</p>

<p align="center">
  <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases"><img src="https://img.shields.io/github/v/release/Guettaf-hossam/SuperDiagnosticTool?style=flat-square" alt="Release"></a>
  <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-GPL%20v3.0-blue.svg?style=flat-square" alt="License"></a>
  <a href="https://github.com/Guettaf-hossam/SuperDiagnosticTool/stargazers"><img src="https://img.shields.io/github/stars/Guettaf-hossam/SuperDiagnosticTool?style=flat-square" alt="Stars"></a>
</p>

تجمع SuperDiagnosticTool بيانات القياس عن بُعد الخاصة بالعتاد في الوقت الفعلي، وترسلها إلى واجهة Google Gemini API للتحليل، وتولّد نصوص PowerShell البرمجية للإصلاح لمعالجة المشكلات المكتشفة. وتتضمن طبقات تحقق متعددة يجب أن يجتازها أي نص برمجي مولّد قبل أن يُطلب من المستخدم تنفيذه.

---

## لقطات الشاشة

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/11160/eb10d4e2a86193e87d0face0e034418d7a5977df9057fb6fed97b0ea705e4442.png" alt="الواجهة الرئيسية" width="800"/>
</p>

*الواجهة الرئيسية تعرض اختيار وضع الفحص وإدخال وصف المشكلة*

---

## الميزات الرئيسية

### دعم عتاد شامل
- **التوسّع الديناميكي:** يتكيّف تلقائيًا مع أي تكوين لوحدة المعالجة المركزية (من نواة واحدة إلى أكثر من 128 نواة)
- **منطق مستقل عن العتاد:** يعمل على الأنظمة القديمة (Intel Pentium) وصولًا إلى محطات العمل عالية الأداء (AMD Threadripper، Intel Xeon)
- **آليات احتياطية آمنة:** تعامل آمن مع استعلامات العتاد غير المدعومة (تردد المعالج، البطارية، ذاكرة التبديل)
- **مُحسَّن للأجهزة منخفضة المواصفات:** تنفيذ خفيف لتجنّب الضغط على الموارد في الأجهزة المحدودة

### تحليل ذكي بالذكاء الاصطناعي
- **تكامل Google Gemini:** تحليل وتشخيص للنظام مدعوم بالذكاء الاصطناعي عبر واجهة Gemini API
- **توصيات واعية بالسياق:** تربط المشكلات التي يبلّغ عنها المستخدم ببيانات القياس عن بُعد المجمّعة من النظام
- **تدقيق أمني:** يفحص بحثًا عن العمليات المشبوهة وتسريبات الموارد ومؤشرات البرمجيات الخبيثة المحتملة
- **التحقق بعد الإصلاح:** يولّد تقارير إتمام تميّز بين الإصلاحات الآلية والعناصر التي تتطلب انتباهًا يدويًا

### بنية أمان متعددة الطبقات

تمر النصوص البرمجية التي يولّدها Gemini عبر أربعة فحوصات متتالية قبل أن يُطلب من المستخدم الموافقة على التنفيذ:

#### خط أنابيب التحقق
- **مطابقة قاعدة المعرفة:** تقارن حلول الذكاء الاصطناعي بمجموعة من أنماط الإصلاح المُختبرة والموثوقة
- **محاكاة التشغيل التجريبي:** تعرض معاينة لجميع التغييرات المقصودة (الخدمات، الملفات، السجل) قبل حدوث أي تعديل
- **التحقق من النص البرمجي (`ScriptValidator`):** فحص من ثلاثة مستويات — القائمة السوداء (حظر صارم للأنماط المدمّرة)، واكتشاف الأنماط المشبوهة (مع مراعاة الأسماء المستعارة والتعتيم)، وتقييم المخاطر على مقياس من 0 إلى 100
- **اعتراض المسارات الحرجة (`CriticalPathInterceptor`):** بوابة انعدام ثقة توقف أي نص برمجي يمس مفاتيح السجل HKLM/HKCU أو مسارات System32 حتى يؤكد المستخدم ذلك صراحةً

#### حدود الأمان
- **نقاط استعادة النظام:** تُنشأ تلقائيًا قبل أي تعديل
- **لقطات قبل التنفيذ وبعده:** التقاط كامل لحالة النظام لاكتشاف وتسجيل كل تغيير يتم إجراؤه
- **توليد التراجع:** يولّد تلقائيًا نصًا برمجيًا انتقائيًا للتراجع في حال فشل التنفيذ
- **تسجيل التنفيذ:** يتم تسجيل كل إجراء مع الطوابع الزمنية في `%TEMP%\superdiagnostic_execution_*.log`

#### تنفيذ PowerShell
- **التحقق من صلاحيات المسؤول:** تتحقق السكربتات من رفع الصلاحيات قبل المتابعة
- **تعقيم المتغيرات:** يحافظ الهروب القائم على التعبيرات النمطية على متغيرات `$env:` دون أخطاء في الصياغة
- **فحوصات سلامة الخدمات:** يتحقق من وجود الخدمة قبل أي عملية Start/Stop/Set
- **التنفيذ المراقَب:** تُشغَّل السكربتات عبر `subprocess.run` مع مهلة قصوى صارمة مدتها 5 دقائق، والتقاط كامل لمخرجات stdout/stderr، وتنظيف تلقائي للملفات المؤقتة. هذا تنفيذ مباشر على مستوى المضيف، وليس عزلاً عبر جهاز افتراضي أو حاوية. طبقات التحقق أعلاه هي الحد الأمني الأساسي.
- **معالجة الأخطاء:** يتضمن غلاف PowerShell كتل try/catch/finally مع الإبلاغ عن الأخطاء سطراً بسطر

### فحص شامل للنظام
- **مقاييس الأداء:** استخدام المعالج (الإجمالي + لكل نواة)، وتفصيل الذاكرة، وأكثر المستهلكين للموارد
- **استخبارات الشبكة:** الواجهات النشطة، وإعدادات DNS، وقوة إشارة Wi-Fi، واختبارات الاتصال
- **سلامة الأمان:** حالة مكافح الفيروسات، وملفات تعريف جدار الحماية، وسجل تحديثات Windows
- **صحة العتاد:** حالة SMART للأقراص، ومعلومات GPU، وحالة البطارية (الحواسيب المحمولة)
- **خدمات النظام:** تطبيقات بدء التشغيل، والخدمات الفاشلة، وسجلات الأحداث الحرجة
- **تدقيق العمليات:** يحدد العمليات ذات الاستخدام غير المعتاد للموارد أو مواقع الملفات

### تقارير تركز على الإنسان
- **تقارير HTML احترافية:** تقارير تشخيصية متجاوبة بسمة داكنة مع مقاييس مرئية
- **صياغة الإنجاز بصيغة الماضي:** تستخدم التقارير وسوم `[FIXED]` و`[CLEANED]` و`[DISABLED]` لتعكس الإجراءات المكتملة
- **قسم يتطلب انتباهاً يدوياً:** يفصل بوضوح بين الإصلاحات الآلية والعناصر التي تتطلب تدخل المستخدم
- **أرشيفات موقوتة:** تُحفظ جميع التقارير في `AI_Reports/` للتتبع التاريخي

---

## البدء السريع

### التنزيل

**[تنزيل SuperDiagnosticTool.exe](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases/latest)** — ملف تنفيذي مستقل (لا يتطلب Python)

> الملف التنفيذي غير موقَّع. سيعرض Windows SmartScreen تحذيراً عند التشغيل الأول. راجع [TRUST_GUIDE.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/TRUST_GUIDE.md) لمعرفة كيفية المتابعة. إذا كنت تفضل التحقق قبل التشغيل، فقم بالبناء من المصدر بدلاً من ذلك.

### المتطلبات

- Windows 10 أو Windows 11
- صلاحيات المسؤول (مطلوبة لبيانات النظام عن بُعد والمعالجة)
- مفتاح Google Gemini API ([احصل على مفتاح مجاني](https://aistudio.google.com/app/apikey))

### التشغيل الأول

1. نزّل `SuperDiagnosticTool.exe` وشغّله
2. أدخل مفتاح Google Gemini API الخاص بك عند المطالبة
3. صِف مشكلة نظامك
4. اختر وضع الفحص (سريع / عميق / كامل)
5. راجع تحليل الذكاء الاصطناعي وسكربت المعالجة المُنشأ
6. وافق على التنفيذ أو اعرض تقرير HTML المفصل

---

## التثبيت (للمطورين)

### المتطلبات الأساسية
- Python 3.8 أو أحدث
- مدير حزم pip

### تثبيت التبعيات

أنشئ بيئة افتراضية بحيث تبقى تبعيات الأداة معزولة عن
مشاريع Python الأخرى:

```bash
python -m venv .venv
```

فعّله في موجّه أوامر Windows، ثم ثبّت التبعيات المذكورة في المستودع:

```bat
.venv\Scripts\activate
pip install -r requirements.txt
```

في PowerShell، فعّل البيئة باستخدام:

```powershell
.\.venv\Scripts\Activate.ps1
```

إذا كان PowerShell يحظر سكربت التنشيط، فافتح PowerShell كمستخدمك وشغّل `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` مرة واحدة، ثم جرّب أمر التنشيط مرة أخرى.

### التشغيل من المصدر

```bash
python super_diagnose_v2.py
```

للتأكد من أن شجرة المصدر والاعتماديات جاهزة قبل بدء الفحص، شغّل:

```bash
python -m compileall src super_diagnose_v2.py
```

يجب أن ينتهي الأمر دون أخطاء. لا تزال الأداة تتطلب Windows
وصولاً إدارياً عند تشغيلها، لأن العديد من التشخيصات تستخدم
PowerShell ومعلومات النظام المحمية.

---

## الاستخدام

### إعداد مفتاح API

**الخيار أ: الإدخال التفاعلي (موصى به للاستخدام الأول)**
- تطالب الأداة بإدخال مفتاح API عند التشغيل الأول
- يُخزَّن المفتاح بشكل آمن عبر Windows DPAPI (`keyring`) عند توفره

**الخيار ب: متغير البيئة**
موجه الأوامر:
```bat
set GEMINI_API_KEY=your_api_key_here
```

PowerShell:
```powershell
$env:GEMINI_API_KEY = "your_api_key_here"
```

**الخيار C: ملف مفتاح يدوي**
أنشئ `gemini.key` في دليل الأداة:
```
your_api_key_here
```

### أوضاع الفحص

| الوضع | ما يفحصه | حالة الاستخدام |
|------|-------|----------|
| **فحص سريع** | CPU، RAM، معلومات أساسية | فحص سريع للأداء |
| **فحص عميق** | النظام، الشبكة، الأمان، السجلات، Bluetooth، العمليات | استكشاف شامل للأعطال |
| **فحص كامل** | كل ما سبق + صحة القرص، GPU، تطبيقات بدء التشغيل | تدقيق كامل للنظام |

### مثال على سير العمل

```
1. Run the tool
   > SuperDiagnosticTool.exe

2. Describe your issue
   > High CPU usage and slow performance

3. Select scan mode
   > 3 (Complete System Scan)

4. Wait for AI analysis
   [Scanning system layers...]
   [Processing telemetry...]

5. Review the generated remediation script
   > Execute? (y/n)

6. View the HTML report
   > Open detailed report? (y/n)
```

## التفاصيل التقنية

### بنية الكود
- تصميم معياري — كل فئة تشخيصية هي دالة معزولة
- معالجة شاملة للأخطاء باستخدام كتل try/except في جميع الأنحاء
- استعلامات مستقلة عن العتاد مع آليات احتياطية سلسة للميزات غير المدعومة
- سلاسل توثيق Python قياسية على جميع الفئات والطرق العامة

### توليد سكربت PowerShell
- التحقق من صلاحيات المسؤول قبل التنفيذ
- تهريب المتغيرات القائم على التعبيرات النمطية لمنع أخطاء الصياغة
- الحفاظ على متغيرات البيئة (`$env:TEMP`، `$env:PATH`) بشكل صحيح
- إدارة آمنة للخدمات مع فحوصات الوجود قبل كل عملية

### تكامل Gemini AI
- مطالبات منظمة بأقسام محددة (`[ANALYSIS_START]`، `[FIX_START]`) لتحليل مخرجات موثوق
- تحليل واعٍ بالسياق باستخدام لقطة القياسات التشخيصية للنظام التي تم جمعها
- اصطلاح الإبلاغ بصيغة الماضي لإجراءات المعالجة المكتملة

---

## الأمان والخصوصية

### ما يبقى على جهازك
- جميع عمليات فحص النظام وتحليله تعمل محليًا.
- لا يتم تخزين أي قياسات تشخيصية على خوادم خارجية بواسطة هذه الأداة.

### ما يتم إرساله خارجيًا
- لتوليد توصيات الذكاء الاصطناعي، يتم إرسال لقطة قياسات تشخيصية (حمل المعالج، الذاكرة، أسماء العمليات، إدخالات سجل الأحداث، حالة الشبكة) إلى **واجهة Gemini API من Google**.
- يتم تضمين مفتاح API الخاص بك مع كل طلب إلى Google.
- راجع [سياسة خصوصية Google](https://policies.google.com/privacy) لمعرفة كيفية معالجة هذه البيانات من جانبهم.

### خصائص أمان أخرى
- **تخزين مفتاح API:** يتم التخزين عبر Windows DPAPI (`keyring`) عند توفره. لا يتم إيداعه أبدًا في نظام التحكم بالإصدارات.
- **شفافية المسؤول:** يتم عرض كل سكربت معالجة بالكامل ويتطلب موافقة صريحة من المستخدم قبل التنفيذ.
- **غير مدمّر افتراضيًا:** تتطلب تعديلات السجل والملفات اجتياز `CriticalPathInterceptor` وتأكيدًا صريحًا من المستخدم.
- **مفتوح المصدر:** الكود المصدري الكامل متاح للمراجعة المستقلة بموجب GPL v3.0.

راجع [SECURITY.md](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/SECURITY.md) للحصول على وثائق أمان إضافية.

---

## استكشاف الأخطاء وإصلاحها

### خطأ "API Key Invalid"
- تحقق من أن المفتاح صحيح ونشط على [Google AI Studio](https://aistudio.google.com/app/apikey)
- تحقق من وجود مسافات بيضاء أو أحرف سطر جديد مخفية في المفتاح
- تأكد من أن المفتاح لديه وصول إلى Gemini API مفعّل

### "Not Running as Administrator"
- انقر بزر الماوس الأيمن على الملف التنفيذي واختر "Run as Administrator"
- أو اسمح لمطالبة UAC عندما تطلب الأداة رفع الصلاحيات

### خطأ "Module Not Found" (نسخة Python)
```bash
pip install --upgrade psutil google-generativeai rich
```

### فشل سكربت PowerShell
- تأكد من تثبيت Windows PowerShell 5.1 أو أحدث
- يُحفظ السكربت المُنشأ في `AI_Reports/remediation.ps1` — راجعه يدويًا بحثًا عن الأخطاء

---

## البناء من المصدر

### عمليات البناء الآلية (موصى بها)

يستخدم المشروع GitHub Actions لبناء ملفات Windows التنفيذية عند دفع وسم إصدار:

1. ادفع تغييراتك إلى الفرع الرئيسي
2. أنشئ وسم إصدار وادفعه:
   ```bash
   git tag -a v1.0.2 -m "Release notes" && git push origin v1.0.2
   ```
3. يقوم GitHub Actions ببناء ملف `.exe` وينشئ إصدارًا تلقائيًا
4. نزّل من [صفحة الإصدارات](https://github.com/Guettaf-hossam/SuperDiagnosticTool/releases)

راجع [`.github/workflows/release.yml`](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/.github/workflows/release.yml) للاطلاع على إعدادات سير عمل الإصدار.

### البناء اليدوي (للاختبار)

```bash
pip install pyinstaller
pip install -r requirements.txt
python build.py
```

يُنشئ هذا الملف `dist/SuperDiagnosticTool.exe` مع أيقونة وتبعيات مضمّنة.

### بنية الملفات

```
SuperDiagnosticTool/
├── super_diagnose_v2.py       # Main entry point and diagnostic logic
├── build.py                   # PyInstaller build script
├── icon.ico                   # Application icon
├── .github/workflows/
│   └── release.yml            # Automated build and release workflow
├── docs/
│   ├── icon.png
│   └── screenshot_main.png
├── src/
│   ├── safety/                # Script validation and monitored execution
│   │   ├── validator.py       # ScriptValidator + CriticalPathInterceptor
│   │   ├── sandbox.py         # SandboxExecutor (monitored subprocess runner)
│   │   ├── dry_run.py         # DryRunSimulator
│   │   ├── restore_point.py   # RestorePointManager
│   │   ├── enhanced_monitoring.py
│   │   └── knowledge_base.py
│   └── security/              # CredentialVault (DPAPI-backed key storage)
├── AI_Reports/                # Generated HTML reports and remediation scripts
├── README.md
├── SECURITY.md
├── TRUST_GUIDE.md
├── LICENSE                    # GPL-3.0
└── .gitignore
```

## إخلاء المسؤولية

تُنشئ هذه الأداة نصوص PowerShell البرمجية وتنفّذها، وهي نصوص تُعدّل خدمات النظام وإعداداته وقيم السجل. قبل الموافقة على أي نص برمجي للمعالجة:

- **اقرأ النص البرمجي كاملًا** — يُعرض قبل السماح بالتنفيذ
- **انسخ البيانات الحرجة احتياطيًا** قبل تشغيل المعالجة الآلية
- **اختبر على نظام غير حرج** إذا كان نطاق التغيير غير واضح

المؤلف غير مسؤول عن أي تلف في النظام أو فقدان للبيانات أو عواقب غير مقصودة تنتج عن استخدام هذه الأداة.

---

## المساهمة

المساهمات مرحّب بها. للمساهمة:

1. انسخ المستودع (Fork)
2. أنشئ فرعًا للميزة (`git checkout -b feature/improvement`)
3. ثبّت تغييراتك (`git commit -m 'Add improvement'`)
4. ادفع التغييرات إلى الفرع (`git push origin feature/improvement`)
5. افتح طلب سحب (Pull Request)

---

## الترخيص

هذا المشروع مرخّص بموجب **GNU General Public License v3.0** — راجع ملف [LICENSE](https://github.com/guettaf-hossam/superdiagnostictool/blob/main/LICENSE) للتفاصيل.

حقوق النشر (C) 2026 GUETTAF HOUSSEM EDDINE

---

## المؤلف

**Guettaf Houssem Eddine**
طالب هندسة إلكتروتقنية
جامعة أكلي محند أولحاج، البويرة، الجزائر
البريد الإلكتروني: [email protected]
GitHub: [@Guettaf-hossam](https://github.com/Guettaf-hossam)

---

## شكر وتقدير

- **Google Gemini AI** لقدرات تحليل النظام
- **psutil** لقياس عن بُعد للنظام عبر المنصات
- **Rich** لعرض واجهة الطرفية

---

<p align="center">
  <strong>الإصدار 1.0</strong> | آخر تحديث: أغسطس 2026
</p>

<p align="center">
  جامعة أكلي محند أولحاج، البويرة، الجزائر
</p>