DEVELOPMENT_GUIDE.md

# HackingFactory v2 - Development Guide

## نظرة عامة

**HackingFactory** هو نموذج متقدم لـ "أنظمة الذكاء الاصطناعي ذاتية التحسين" (Self-Refining AI Systems). يجمع بين قوة نماذج التوليد (Qwen) والتقييم (DeepSeek) في حلقة تكرارية مستمرة لإنتاج أكواد عالية الجودة.

---

## المكونات الرئيسية

### 1. **بيئة الفحص المعزولة (Sandbox)**
**الملف:** `server/sandbox.ts`

يوفر بيئة معزولة آمنة لتشغيل الأكواد المولدة واختبارها ديناميكياً:
- تشغيل الأكواد بحد زمني (5 ثوان)
- قياس الأداء ووقت التنفيذ
- التقاط المخرجات والأخطاء

```typescript
const result = await runCodeInSandbox(code, "python");
// { success: boolean, output: string, error?: string, executionTime: number }
```

### 2. **محرك التكرار الذاتي (Self-Refining Loop)**
**الملف:** `server/factory.ts`

يدير العملية الكاملة للتوليد والتقييم والتحسين:
1. البحث في الذاكرة عن حلول مشابهة سابقة
2. توليد كود جديد (Qwen)
3. فحص ديناميكي (Sandbox)
4. تقييم شامل (DeepSeek)
5. حفظ النتائج والتكرار حتى الوصول للدرجة المستهدفة

```typescript
await runSelfRefiningLoop(projectId, prompt, targetScore, maxIterations);
```

### 3. **قاعدة البيانات المتجهة (Vector Memory)**
**الملف:** `server/memory.ts`

تخزين واسترجاع الحلول الناجحة السابقة باستخدام ChromaDB:
- البحث الدلالي عن حلول مشابهة
- تقليل وقت التوليد للمشاكل المتكررة
- تحسين جودة الحلول الجديدة

```typescript
const memory = ProjectMemory.getInstance();
await memory.addSuccessfulCode(projectId, code, prompt, score);
const similar = await memory.findSimilarSolutions(query);
```

### 4. **نظام التقييم المتعدد (Multi-Criteria Scoring)**
**الملف:** `server/routers/chat.ts` - دالة `evaluateCode`

تقييم الأكواد بناءً على أربعة معايير (0-25 نقطة لكل معيار):
1. **التخفي (Stealth):** إخفاء الأثر، تجنب الكشف
2. **الاستقرار (Stability):** معالجة الأخطاء، إدارة الموارد
3. **الكفاءة (Efficiency):** الأداء، سرعة التنفيذ
4. **الموثوقية (Reliability):** معدل النجاح، التوافقية

### 5. **محرك التشفير والتخفي (Obfuscation Engine)**
**الملف:** `server/obfuscation.ts`

يوفر عدة مستويات من التشفير:
- **Low:** إعادة تسمية المتغيرات
- **Medium:** تشفير النصوص + إضافة كود وهمي
- **High:** مستويات متعددة من التشفير

```typescript
const obfuscated = ObfuscationEngine.fullObfuscate(code, "high");
```

### 6. **نظام الإشعارات (Notifications)**
**الملف:** `server/notifications.ts`

إخطار المستخدمين بتقدم المشاريع:
- إكمال التكرارات
- إكمال المشاريع
- الأخطاء والتحذيرات

```typescript
const notifier = NotificationManager.getInstance();
await notifier.notifyProjectComplete(userId, projectName, score, projectId);
```

### 7. **لوحة التحكم المرئية (Visual Dashboard)**
**الملف:** `client/src/pages/Dashboard.tsx`

واجهة رسومية تعرض:
- إحصائيات المشاريع
- رسم بياني لتقدم التكرارات (Iteration Progress Chart)
- قائمة المشاريع النشطة
- معلومات مفصلة عن كل مشروع

### 8. **محرر الأكواد المباشر (Live Code Editor)**
**الملف:** `client/src/components/CodeEditor.tsx`

يسمح للمستخدمين بـ:
- تحرير الأكواد يدوياً
- نسخ الأكواد
- تشغيل الأكواد مباشرة

### 9. **مكتبة القوالب (Payload Library)**
**الملف:** `client/src/components/PayloadLibrary.tsx`

مكتبة منظمة للحلول الناجحة:
- البحث والتصفية حسب الوسوم
- عرض درجات الجودة
- تطبيق التشفير على القوالب

---

## سير العمل (Workflow)

### 1. إنشاء مشروع جديد
```typescript
const project = await trpc.projects.create.mutate({
  name: "My Project",
  mode: "loop",
  contentType: "code",
  originalPrompt: "Generate a reverse shell...",
});
```

### 2. تشغيل المصنع
```typescript
await trpc.projects.runFactory.mutate({
  projectId: project.projectId,
  prompt: project.originalPrompt,
  targetScore: 90,
});
```

### 3. مراقبة التقدم
```typescript
const iterations = await trpc.projects.getIterations.query({
  projectId: project.projectId,
});
```

### 4. تطبيق التشفير (Ghost Mode)
```typescript
const obfuscated = await trpc.projects.obfuscateCode.mutate({
  code: finalCode,
  level: "high",
});
```

---

## البنية الديناميكية (Dynamic Analysis)

عند تقييم الكود، يتم تنفيذه فعلياً في بيئة معزولة:

```
Input Code
    ↓
[Sandbox Execution] → Output, Errors, Execution Time
    ↓
[LLM Analysis] → Scoring (Stealth, Stability, Efficiency, Reliability)
    ↓
[Iteration Storage] → Save to Database
    ↓
[Score Check] → If score < target, repeat generation
```

---

## التكامل مع الواجهة الأمامية

### مسارات tRPC المتاحة

**Projects Router:**
- `create` - إنشاء مشروع جديد
- `list` - قائمة المشاريع
- `getById` - الحصول على تفاصيل مشروع
- `updateStatus` - تحديث حالة المشروع
- `addIteration` - إضافة تكرار جديد
- `getIterations` - الحصول على التكرارات
- `runFactory` - تشغيل المصنع
- `obfuscateCode` - تطبيق التشفير

**Chat Router:**
- `sendMessage` - إرسال رسالة للذكاء الاصطناعي
- `generateCode` - توليد كود
- `evaluateCode` - تقييم كود

---

## متطلبات التثبيت

```bash
# تثبيت المكتبات
npm install

# تثبيت ChromaDB (Python)
sudo pip3 install chromadb

# تشغيل الخادم
npm run dev
```

---

## ملاحظات تطويرية

### الأداء
- استخدام الخيط الخلفي (Background) لتشغيل المصنع لتجنب timeout
- تخزين النتائج في الذاكرة المتجهة لتسريع البحث

### الأمان
- جميع الأكواد تُشغل في بيئة معزولة
- لا توجد وصول مباشر للنظام الرئيسي
- التحقق من صلاحيات المستخدم على جميع المسارات

### التوسع المستقبلي
- دعم نماذج استدلال متقدمة (o1, DeepSeek-R1)
- تكامل Docker للفحص الديناميكي المتقدم
- نظام التنبيهات عبر WebSocket
- تصدير النتائج بصيغ متعددة

---

## أمثلة الاستخدام

### مثال 1: توليد وتقييم كود بسيط
```typescript
const result = await trpc.chat.generateCode.mutate({
  projectId: 1,
  prompt: "Write a Python script that prints hello world",
});
```

### مثال 2: تشغيل حلقة التكرار الكاملة
```typescript
await trpc.projects.runFactory.mutate({
  projectId: 1,
  prompt: "Generate a secure password generator",
  targetScore: 95,
});
```

### مثال 3: تطبيق التشفير على الكود
```typescript
const ghostCode = await trpc.projects.obfuscateCode.mutate({
  code: "print('Hello')",
  level: "high",
});
```

---

## الدعم والمساهمة

للمزيد من المعلومات أو الإبلاغ عن مشاكل، يرجى فتح issue في المستودع.