Agent Production-Ready

سأعطيك الآن الصورة الكاملة بكل التفاصيل المعمارية، مع الكود الأساسي لكل مكوّن، حتى تكون جاهزًا لبناء النظام كاملًا.

---

🏗️ المعمارية العامة للنظام

text

┌─────────────────────────────────────────────────────────────┐
│                    WordPress Admin UI                        │
│         (React Dashboard + REST API + WebSocket)             │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   Agent Orchestrator                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ Planner  │→ │Research  │→ │ Writer   │→ │ Critic   │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│         ↓            ↓             ↓             ↓          │
│  ┌─────────────────────────────────────────────────┐        │
│  │           Message Bus (MySQL/Redis)             │        │
│  └─────────────────────────────────────────────────┘        │
└──────────────────────┬──────────────────────────────────────┘
                       │
     ┌─────────────────┼─────────────────┐
     ▼                 ▼                 ▼
┌─────────┐      ┌──────────┐      ┌───────────┐
│ Memory  │      │Knowledge │      │  Tools    │
│ Qdrant  │      │  Graph   │      │  Registry │
│+MySQL   │      │  MySQL   │      │           │
└─────────┘      └──────────┘      └───────────┘
                       │
                       ▼
              ┌─────────────────┐
              │ Verification    │
              │     Loop        │
              └─────────────────┘
                       │
                       ▼
              ┌─────────────────┐
              │  LLM Providers  │
              │ OpenAI / Claude │
              └─────────────────┘

---

🔧 المكوّن 1: Core Agent + LLM Client (الأساس)

هيكل المجلدات

text

wp-content/plugins/zezo-ai-agents/
├── zezo-ai-agents.php
├── composer.json
├── src/
│   ├── Core/
│   │   ├── Agent.php
│   │   ├── AgentRegistry.php
│   │   ├── Orchestrator.php
│   │   └── MessageBus.php
│   ├── LLM/
│   │   ├── LLMClient.php
│   │   ├── OpenAIProvider.php
│   │   ├── ClaudeProvider.php
│   │   └── EmbeddingClient.php
│   ├── Tools/
│   │   ├── ToolInterface.php
│   │   ├── ToolRegistry.php
│   │   └── Tools/
│   │       ├── WpQueryTool.php
│   │       ├── SqlQueryTool.php
│   │       └── HttpTool.php
│   ├── Verification/
│   │   └── VerificationLoop.php
│   ├── Memory/
│   │   ├── MemoryStore.php
│   │   └── VectorClient.php
│   ├── Graph/
│   │   └── KnowledgeGraph.php
│   └── Admin/
│       ├── Dashboard.php
│       └── RestApi.php

composer.json

json

{
  "name": "zezo/ai-agents",
  "require": {
    "php": ">=8.1",
    "guzzlehttp/guzzle": "^7.8",
    "openai-php/client": "^0.8",
    "anthropic-ai/sdk": "^0.2"
  },
  "autoload": {
    "psr-4": { "Zezo\\AI\\": "src/" }
  }
}

src/LLM/LLMClient.php

php

<?php
namespace Zezo\AI\LLM;

interface LLMClient {
    public function chat(array $messages, array $options = []): array;
    public function embed(string $text): array;
    public function name(): string;
}

src/LLM/OpenAIProvider.php

php

<?php
namespace Zezo\AI\LLM;

use GuzzleHttp\Client;

class OpenAIProvider implements LLMClient {
    private Client $http;
    private string $apiKey;
    private string $model;
    private string $embedModel;

    public function __construct(string $apiKey, string $model = 'gpt-4o', string $embedModel = 'text-embedding-3-large') {
        $this->apiKey = $apiKey;
        $this->model = $model;
        $this->embedModel = $embedModel;
        $this->http = new Client(['base_uri' => 'https://api.openai.com/v1/', 'timeout' => 120]);
    }

    public function chat(array $messages, array $options = []): array {
        $payload = [
            'model' => $this->model,
            'messages' => $messages,
            'temperature' => $options['temperature'] ?? 0.3,
        ];
        if (!empty($options['tools'])) {
            $payload['tools'] = $options['tools'];
            $payload['tool_choice'] = $options['tool_choice'] ?? 'auto';
        }
        if (!empty($options['response_format'])) {
            $payload['response_format'] = $options['response_format'];
        }

        $res = $this->http->post('chat/completions', [
            'headers' => [
                'Authorization' => "Bearer {$this->apiKey}",
                'Content-Type' => 'application/json',
            ],
            'json' => $payload,
        ]);

        $body = json_decode($res->getBody()->getContents(), true);
        return [
            'content' => $body['choices'][0]['message']['content'] ?? '',
            'tool_calls' => $body['choices'][0]['message']['tool_calls'] ?? [],
            'usage' => $body['usage'] ?? [],
            'raw' => $body,
        ];
    }

    public function embed(string $text): array {
        $res = $this->http->post('embeddings', [
            'headers' => ['Authorization' => "Bearer {$this->apiKey}"],
            'json' => ['model' => $this->embedModel, 'input' => $text],
        ]);
        $body = json_decode($res->getBody()->getContents(), true);
        return $body['data'][0]['embedding'] ?? [];
    }

    public function name(): string { return 'openai:' . $this->model; }
}

src/LLM/ClaudeProvider.php

php

<?php
namespace Zezo\AI\LLM;

use GuzzleHttp\Client;

class ClaudeProvider implements LLMClient {
    private Client $http;
    private string $apiKey;
    private string $model;

    public function __construct(string $apiKey, string $model = 'claude-sonnet-4-5') {
        $this->apiKey = $apiKey;
        $this->model = $model;
        $this->http = new Client(['base_uri' => 'https://api.anthropic.com/v1/', 'timeout' => 120]);
    }

    public function chat(array $messages, array $options = []): array {
        // افصل system عن باقي الرسائل
        $system = '';
        $filtered = [];
        foreach ($messages as $m) {
            if ($m['role'] === 'system') $system .= $m['content'] . "\n";
            else $filtered[] = $m;
        }

        $payload = [
            'model' => $this->model,
            'max_tokens' => $options['max_tokens'] ?? 4096,
            'system' => trim($system),
            'messages' => $filtered,
        ];
        if (!empty($options['tools'])) {
            $payload['tools'] = $this->convertTools($options['tools']);
        }

        $res = $this->http->post('messages', [
            'headers' => [
                'x-api-key' => $this->apiKey,
                'anthropic-version' => '2023-06-01',
                'Content-Type' => 'application/json',
            ],
            'json' => $payload,
        ]);

        $body = json_decode($res->getBody()->getContents(), true);
        $content = '';
        $toolCalls = [];
        foreach ($body['content'] ?? [] as $block) {
            if ($block['type'] === 'text') $content .= $block['text'];
            if ($block['type'] === 'tool_use') $toolCalls[] = $block;
        }
        return [
            'content' => $content,
            'tool_calls' => $toolCalls,
            'usage' => $body['usage'] ?? [],
            'raw' => $body,
        ];
    }

    public function embed(string $text): array {
        // Claude لا يوفر embeddings → استخدم Voyage AI أو OpenAI
        return (new OpenAIProvider(get_option('zezo_openai_key')))->embed($text);
    }

    private function convertTools(array $tools): array {
        return array_map(fn($t) => [
            'name' => $t['function']['name'],
            'description' => $t['function']['description'],
            'input_schema' => $t['function']['parameters'],
        ], $tools);
    }

    public function name(): string { return 'claude:' . $this->model; }
}

src/Core/Agent.php — قلب النظام

php

<?php
namespace Zezo\AI\Core;

use Zezo\AI\LLM\LLMClient;
use Zezo\AI\Tools\ToolRegistry;
use Zezo\AI\Memory\MemoryStore;
use Zezo\AI\Verification\VerificationLoop;

class Agent {
    private string $id;
    private string $role;
    private string $systemPrompt;
    private LLMClient $llm;
    private ToolRegistry $tools;
    private MemoryStore $memory;
    private VerificationLoop $verifier;
    private int $maxIterations = 8;

    public function __construct(
        string $id,
        string $role,
        string $systemPrompt,
        LLMClient $llm,
        ToolRegistry $tools,
        MemoryStore $memory,
        VerificationLoop $verifier
    ) {
        $this->id = $id;
        $this->role = $role;
        $this->systemPrompt = $systemPrompt;
        $this->llm = $llm;
        $this->tools = $tools;
        $this->memory = $memory;
        $this->verifier = $verifier;
    }

    /**
     * تشغيل الوكيل على هدف معين مع حلقة Tool-Calling
     */
    public function run(string $goal, array $context = []): array {
        $messages = [
            ['role' => 'system', 'content' => $this->systemPrompt],
        ];

        // استرجاع ذاكرة ذات صلة
        $memories = $this->memory->search($goal, 5);
        if ($memories) {
            $messages[] = ['role' => 'system', 'content' => "Relevant memories:\n" . implode("\n", $memories)];
        }
        if ($context) {
            $messages[] = ['role' => 'system', 'content' => "Context:\n" . json_encode($context, JSON_UNESCAPED_UNICODE)];
        }
        $messages[] = ['role' => 'user', 'content' => $goal];

        $trace = [];
        for ($i = 0; $i < $this->maxIterations; $i++) {
            $response = $this->llm->chat($messages, [
                'tools' => $this->tools->asOpenAISchema(),
                'temperature' => 0.2,
            ]);

            $trace[] = ['step' => $i, 'type' => 'llm_response', 'content' => $response['content']];

            // لا يوجد tool calls → إجابة نهائية
            if (empty($response['tool_calls'])) {
                $final = $response['content'];

                // تحقق
                $verification = $this->verifier->verify($final, $goal, $context);
                if (!$verification['passed']) {
                    $messages[] = ['role' => 'assistant', 'content' => $final];
                    $messages[] = ['role' => 'user', 'content' =>
                        "التحقق فشل: {$verification['reason']}\nأعد المحاولة مع تصحيح المشكلة."];
                    continue;
                }

                // حفظ في الذاكرة
                $this->memory->store([
                    'agent' => $this->id,
                    'goal' => $goal,
                    'result' => $final,
                ]);

                return ['success' => true, 'output' => $final, 'trace' => $trace];
            }

            // نفّذ الأدوات
            $messages[] = ['role' => 'assistant', 'content' => $response['content'] ?? null, 'tool_calls' => $response['tool_calls']];

            foreach ($response['tool_calls'] as $call) {
                $name = $call['function']['name'] ?? $call['name'];
                $args = json_decode($call['function']['arguments'] ?? json_encode($call['input'] ?? []), true);
                $result = $this->tools->execute($name, $args);
                $trace[] = ['step' => $i, 'type' => 'tool_call', 'tool' => $name, 'args' => $args, 'result' => $result];

                $messages[] = [
                    'role' => 'tool',
                    'tool_call_id' => $call['id'] ?? null,
                    'content' => is_string($result) ? $result : json_encode($result, JSON_UNESCAPED_UNICODE),
                ];
            }
        }

        return ['success' => false, 'output' => null, 'reason' => 'max_iterations', 'trace' => $trace];
    }
}

---

🔧 المكوّن 2: Verification Loop الكامل

php

<?php
namespace Zezo\AI\Verification;

class VerificationLoop {
    private array $rules = [];

    public function addRule(callable $rule, string $name): self {
        $this->rules[$name] = $rule;
        return $this;
    }

    public function verify(string $output, string $goal, array $context = []): array {
        foreach ($this->rules as $name => $rule) {
            try {
                $result = $rule($output, $goal, $context);
                if ($result !== true) {
                    return ['passed' => false, 'reason' => "[$name] " . (is_string($result) ? $result : 'failed')];
                }
            } catch (\Throwable $e) {
                return ['passed' => false, 'reason' => "[$name] exception: " . $e->getMessage()];
            }
        }
        return ['passed' => true, 'reason' => 'ok'];
    }

    // ---- Rules جاهزة ----

    public static function schemaRule(array $schema): callable {
        return function ($output) use ($schema) {
            $data = json_decode($output, true);
            if (json_last_error() !== JSON_ERROR_NONE) return 'ليس JSON صالحًا';
            foreach ($schema['required'] ?? [] as $key) {
                if (!array_key_exists($key, $data)) return "الحقل المطلوب مفقود: $key";
            }
            return true;
        };
    }

    public static function lengthRule(int $min, int $max): callable {
        return fn($output) => (mb_strlen($output) >= $min && mb_strlen($output) <= $max)
            ? true : "الطول يجب أن يكون بين $min و $max";
    }

    public static function dbFactRule(callable $lookup): callable {
        return function ($output) use ($lookup) {
            $facts = $lookup(); // مصفوفة حقائق من DB
            foreach ($facts as $fact) {
                if (!str_contains($output, (string)$fact)) {
                    return "الحقيقة غير موجودة في الإجابة: $fact";
                }
            }
            return true;
        };
    }

    public static function selfConsistencyRule(callable $askLLM, int $samples = 3): callable {
        return function ($output, $goal) use ($askLLM, $samples) {
            $answers = [$output];
            for ($i = 1; $i < $samples; $i++) {
                $answers[] = $askLLM($goal);
            }
            $normalized = array_map(fn($a) => md5(strtolower(trim($a))), $answers);
            $unique = count(array_unique($normalized));
            return $unique === 1 ? true : "الإجابات غير متسقة ($unique/$samples مختلفة)";
        };
    }
}

---

🔧 المكوّن 3: Multi-Agent System + Message Bus

src/Core/MessageBus.php

php

<?php
namespace Zezo\AI\Core;

class MessageBus {
    private string $table;

    public function __construct() {
        global $wpdb;
        $this->table = $wpdb->prefix . 'agent_messages';
        $this->ensureTable();
    }

    private function ensureTable(): void {
        global $wpdb;
        $charset = $wpdb->get_charset_collate();
        $sql = "CREATE TABLE IF NOT EXISTS {$this->table} (
            id BIGINT AUTO_INCREMENT PRIMARY KEY,
            task_id VARCHAR(64),
            from_agent VARCHAR(64),
            to_agent VARCHAR(64),
            type VARCHAR(32),
            payload LONGTEXT,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            INDEX(task_id), INDEX(to_agent)
        ) $charset;";
        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
        dbDelta($sql);
    }

    public function send(string $taskId, string $from, string $to, string $type, array $payload): void {
        global $wpdb;
        $wpdb->insert($this->table, [
            'task_id' => $taskId,
            'from_agent' => $from,
            'to_agent' => $to,
            'type' => $type,
            'payload' => wp_json_encode($payload),
        ]);
    }

    public function receive(string $taskId, string $agent): array {
        global $wpdb;
        $rows = $wpdb->get_results($wpdb->prepare(
            "SELECT * FROM {$this->table} WHERE task_id=%s AND to_agent=%s ORDER BY id ASC",
            $taskId, $agent
        ), ARRAY_A);
        return array_map(fn($r) => [
            'from' => $r['from_agent'],
            'type' => $r['type'],
            'payload' => json_decode($r['payload'], true),
        ], $rows);
    }
}

src/Core/Orchestrator.php

php

<?php
namespace Zezo\AI\Core;

class Orchestrator {
    private array $agents = [];
    private MessageBus $bus;

    public function __construct(MessageBus $bus) {
        $this->bus = $bus;
    }

    public function register(string $id, Agent $agent): self {
        $this->agents[$id] = $agent;
        return $this;
    }

    /**
     * Pipeline خطي: Planner → Researcher → Writer → Critic → Executor
     */
    public function runPipeline(string $goal): array {
        $taskId = wp_generate_uuid4();
        $results = [];
        $context = ['goal' => $goal];

        // 1. Planner
        $plan = $this->agents['planner']->run("ضع خطة تنفيذية مفصلة للهدف: $goal");
        $results['planner'] = $plan;
        $context['plan'] = $plan['output'];

        // 2. Researcher
        $research = $this->agents['researcher']->run("اجمع المعلومات اللازمة حسب الخطة:\n{$plan['output']}", $context);
        $results['researcher'] = $research;
        $context['research'] = $research['output'];

        // 3. Writer
        $draft = $this->agents['writer']->run("اكتب المحتوى النهائي بناءً على البحث:\n{$research['output']}", $context);
        $results['writer'] = $draft;
        $context['draft'] = $draft['output'];

        // 4. Critic (loop حتى الرضا)
        $maxRounds = 3;
        for ($i = 0; $i < $maxRounds; $i++) {
            $critique = $this->agents['critic']->run("انتقد المسودة التالية بعمق:\n{$draft['output']}", $context);
            $results['critic_round_' . $i] = $critique;

            if (str_contains(strtolower($critique['output']), 'مقبول') ||
                str_contains(strtolower($critique['output']), 'approved')) {
                break;
            }
            $draft = $this->agents['writer']->run(
                "حسّن المسودة حسب الملاحظات:\n{$critique['output']}\n\nالمسودة:\n{$draft['output']}",
                $context
            );
            $results['writer_revision_' . $i] = $draft;
        }

        // 5. Executor (ينشر مثلًا)
        $execution = $this->agents['executor']->run(
            "نفّذ المهمة النهائية (انشر المحتوى كمسودة في WordPress):\n{$draft['output']}",
            $context
        );
        $results['executor'] = $execution;

        return ['task_id' => $taskId, 'results' => $results, 'final' => $execution];
    }
}

---

🔧 المكوّن 4: Memory Store + Vector Search

src/Memory/VectorClient.php (Qdrant)

php

<?php
namespace Zezo\AI\Memory;

use GuzzleHttp\Client;

class VectorClient {
    private Client $http;
    private string $collection;

    public function __construct(string $endpoint, string $collection, string $apiKey = '') {
        $headers = ['Content-Type' => 'application/json'];
        if ($apiKey) $headers['api-key'] = $apiKey;
        $this->http = new Client(['base_uri' => rtrim($endpoint, '/') . '/', 'headers' => $headers, 'timeout' => 60]);
        $this->collection = $collection;
        $this->ensureCollection();
    }

    private function ensureCollection(): void {
        try {
            $this->http->get("collections/{$this->collection}");
        } catch (\Throwable $e) {
            $this->http->put("collections/{$this->collection}", [
                'json' => [
                    'vectors' => ['size' => 3072, 'distance' => 'Cosine'],
                ],
            ]);
        }
    }

    public function upsert(string $id, array $vector, array $payload): void {
        $this->http->put("collections/{$this->collection}/points", [
            'json' => ['points' => [['id' => $id, 'vector' => $vector, 'payload' => $payload]]],
        ]);
    }

    public function search(array $vector, int $top = 5): array {
        $res = $this->http->post("collections/{$this->collection}/points/search", [
            'json' => ['vector' => $vector, 'limit' => $top, 'with_payload' => true],
        ]);
        return json_decode($res->getBody()->getContents(), true)['result'] ?? [];
    }
}

src/Memory/MemoryStore.php

php

<?php
namespace Zezo\AI\Memory;

use Zezo\AI\LLM\LLMClient;

class MemoryStore {
    private LLMClient $embedder;
    private VectorClient $vector;
    private string $table;

    public function __construct(LLMClient $embedder, VectorClient $vector) {
        global $wpdb;
        $this->embedder = $embedder;
        $this->vector = $vector;
        $this->table = $wpdb->prefix . 'agent_memory';
        $this->ensureTable();
    }

    private function ensureTable(): void {
        global $wpdb;
        $charset = $wpdb->get_charset_collate();
        $sql = "CREATE TABLE IF NOT EXISTS {$this->table} (
            id BIGINT AUTO_INCREMENT PRIMARY KEY,
            agent_id VARCHAR(64),
            goal LONGTEXT,
            result LONGTEXT,
            vector_id VARCHAR(64),
            metadata JSON,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            INDEX(agent_id), INDEX(vector_id)
        ) $charset;";
        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
        dbDelta($sql);
    }

    public function store(array $data): void {
        global $wpdb;
        $text = ($data['goal'] ?? '') . "\n" . ($data['result'] ?? '');
        $vector = $this->embedder->embed($text);
        $vectorId = wp_generate_uuid4();

        $this->vector->upsert($vectorId, $vector, [
            'agent' => $data['agent'] ?? 'unknown',
            'goal' => $data['goal'] ?? '',
            'result' => $data['result'] ?? '',
        ]);

        $wpdb->insert($this->table, [
            'agent_id' => $data['agent'] ?? '',
            'goal' => $data['goal'] ?? '',
            'result' => $data['result'] ?? '',
            'vector_id' => $vectorId,
            'metadata' => wp_json_encode($data['metadata'] ?? []),
        ]);
    }

    public function search(string $query, int $top = 5): array {
        $vector = $this->embedder->embed($query);
        $hits = $this->vector->search($vector, $top);
        return array_map(fn($h) => $h['payload']['result'] ?? '', $hits);
    }
}

---

🔧 المكوّن 5: Knowledge Graph على MySQL

src/Graph/KnowledgeGraph.php

php

<?php
namespace Zezo\AI\Graph;

class KnowledgeGraph {
    private string $nodesTable;
    private string $edgesTable;

    public function __construct() {
        global $wpdb;
        $this->nodesTable = $wpdb->prefix . 'kg_nodes';
        $this->edgesTable = $wpdb->prefix . 'kg_edges';
        $this->ensureSchema();
    }

    private function ensureSchema(): void {
        global $wpdb;
        $charset = $wpdb->get_charset_collate();
        require_once ABSPATH . 'wp-admin/includes/upgrade.php';

        dbDelta("CREATE TABLE IF NOT EXISTS {$this->nodesTable} (
            id BIGINT AUTO_INCREMENT PRIMARY KEY,
            type VARCHAR(50),
            label VARCHAR(255),
            properties JSON,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            INDEX(type), INDEX(label(100))
        ) $charset;");

        dbDelta("CREATE TABLE IF NOT EXISTS {$this->edgesTable} (
            id BIGINT AUTO_INCREMENT PRIMARY KEY,
            source_id BIGINT,
            target_id BIGINT,
            relation VARCHAR(100),
            weight FLOAT DEFAULT 1.0,
            properties JSON,
            INDEX(source_id), INDEX(target_id), INDEX(relation)
        ) $charset;");
    }

    public function addNode(string $type, string $label, array $props = []): int {
        global $wpdb;
        $wpdb->insert($this->nodesTable, [
            'type' => $type,
            'label' => $label,
            'properties' => wp_json_encode($props),
        ]);
        return (int)$wpdb->insert_id;
    }

    public function addEdge(int $src, int $dst, string $relation, float $weight = 1.0, array $props = []): void {
        global $wpdb;
        $wpdb->insert($this->edgesTable, [
            'source_id' => $src,
            'target_id' => $dst,
            'relation' => $relation,
            'weight' => $weight,
            'properties' => wp_json_encode($props),
        ]);
    }

    /** اجلب جيران عقدة */
    public function neighbors(int $nodeId, ?string $relation = null): array {
        global $wpdb;
        $sql = "SELECT n.*, e.relation, e.weight FROM {$this->edgesTable} e
                JOIN {$this->nodesTable} n ON n.id = e.target_id
                WHERE e.source_id = %d";
        $params = [$nodeId];
        if ($relation) { $sql .= " AND e.relation = %s"; $params[] = $relation; }
        return $wpdb->get_results($wpdb->prepare($sql, ...$params), ARRAY_A);
    }

    /** بحث multi-hop بسيط (BFS) */
    public function traverse(int $startId, int $depth = 2): array {
        $visited = [$startId => true];
        $frontier = [$startId];
        $graph = ['nodes' => [], 'edges' => []];

        for ($d = 0; $d < $depth; $d++) {
            $next = [];
            foreach ($frontier as $nid) {
                foreach ($this->neighbors($nid) as $n) {
                    $graph['edges'][] = ['from' => $nid, 'to' => $n['id'], 'rel' => $n['relation']];
                    if (!isset($visited[$n['id']])) {
                        $visited[$n['id']] = true;
                        $graph['nodes'][] = $n;
                        $next[] = $n['id'];
                    }
                }
            }
            $frontier = $next;
        }
        return $graph;
    }

    /** بناء KG من مقالات WordPress */
    public function buildFromPosts(int $limit = 100): int {
        $posts = get_posts(['numberposts' => $limit, 'post_status' => 'publish']);
        $count = 0;
        foreach ($posts as $post) {
            $postNode = $this->addNode('post', $post->post_title, [
                'wp_id' => $post->ID,
                'url' => get_permalink($post->ID),
            ]);
            $authorNode = $this->addNode('user', get_the_author_meta('display_name', $post->post_author), [
                'wp_id' => $post->post_author,
            ]);
            $this->addEdge($authorNode, $postNode, 'authored');

            foreach (wp_get_post_categories($post->ID) as $catId) {
                $cat = get_category($catId);
                if ($cat) {
                    $catNode = $this->addNode('category', $cat->name, ['wp_id' => $catId]);
                    $this->addEdge($postNode, $catNode, 'in_category');
                }
            }
            $count++;
        }
        return $count;
    }
}

---

🔧 المكوّن 6: Admin Dashboard متقدم

src/Admin/RestApi.php

php

<?php
namespace Zezo\AI\Admin;

class RestApi {
    public function register(): void {
        add_action('rest_api_init', function () {
            register_rest_route('zezo-ai/v1', '/agents', [
                'methods' => 'GET',
                'callback' => [$this, 'listAgents'],
                'permission_callback' => fn() => current_user_can('manage_options'),
            ]);
            register_rest_route('zezo-ai/v1', '/run', [
                'methods' => 'POST',
                'callback' => [$this, 'runTask'],
                'permission_callback' => fn() => current_user_can('manage_options'),
            ]);
            register_rest_route('zezo-ai/v1', '/tasks/(?P<id>[\w-]+)', [
                'methods' => 'GET',
                'callback' => [$this, 'getTask'],
                'permission_callback' => fn() => current_user_can('manage_options'),
            ]);
        });
    }

    public function listAgents(): array {
        return [
            ['id' => 'planner', 'role' => 'Planner', 'status' => 'idle'],
            ['id' => 'researcher', 'role' => 'Researcher', 'status' => 'idle'],
            ['id' => 'writer', 'role' => 'Writer', 'status' => 'idle'],
            ['id' => 'critic', 'role' => 'Critic', 'status' => 'idle'],
            ['id' => 'executor', 'role' => 'Executor', 'status' => 'idle'],
        ];
    }

    public function runTask(\WP_REST_Request $req): array {
        $goal = sanitize_text_field($req->get_param('goal'));
        // شغّل في الخلفية عبر Action Scheduler أو cron
        as_enqueue_async_action('zezo_ai_run_pipeline', ['goal' => $goal], 'zezo-ai');
        return ['queued' => true, 'goal' => $goal];
    }

    public function getTask(\WP_REST_Request $req): array {
        global $wpdb;
        $taskId = $req['id'];
        $rows = $wpdb->get_results($wpdb->prepare(
            "SELECT * FROM {$wpdb->prefix}agent_messages WHERE task_id=%s ORDER BY id ASC", $taskId
        ), ARRAY_A);
        return ['task_id' => $taskId, 'messages' => $rows];
    }
}

src/Admin/Dashboard.php

php

<?php
namespace Zezo\AI\Admin;

class Dashboard {
    public function register(): void {
        add_action('admin_menu', function () {
            add_menu_page(
                'Zezo AI Agents', 'Zezo AI', 'manage_options',
                'zezo-ai', [$this, 'render'], 'dashicons-buddicons-buddypress-logo', 30
            );
        });
        add_action('admin_enqueue_scripts', function ($hook) {
            if ($hook !== 'toplevel_page_zezo-ai') return;
            wp_enqueue_script('zezo-ai-admin', plugins_url('assets/admin.js', __DIR__ . '/../../zezo-ai-agents.php'), ['wp-element'], '1.0', true);
            wp_localize_script('zezo-ai-admin', 'ZezoAI', [
                'rest' => rest_url('zezo-ai/v1'),
                'nonce' => wp_create_nonce('wp_rest'),
            ]);
        });
    }

    public function render(): void {
        echo '<div id="zezo-ai-root"></div>';
    }
}

assets/admin.js (React مصغر)

jsx

const { render, useState, useEffect } = wp.element;

function Dashboard() {
  const [agents, setAgents] = useState([]);
  const [goal, setGoal] = useState('');
  const [trace, setTrace] = useState(null);

  useEffect(() => {
    fetch(ZezoAI.rest + '/agents', { headers: { 'X-WP-Nonce': ZezoAI.nonce } })
      .then(r => r.json()).then(setAgents);
  }, []);

  const run = async () => {
    const res = await fetch(ZezoAI.rest + '/run', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': ZezoAI.nonce },
      body: JSON.stringify({ goal })
    }).then(r => r.json());
    alert('تم جدولة المهمة: ' + res.goal);
  };

  return (
    <div className="wrap">
      <h1>Zezo AI Agents Dashboard</h1>
      <div style={{ display: 'flex', gap: 16, marginBottom: 24 }}>
        {agents.map(a => (
          <div key={a.id} style={{ padding: 16, border: '1px solid #ccc', borderRadius: 8, minWidth: 140 }}>
            <strong>{a.role}</strong><br />
            <span style={{ color: a.status === 'idle' ? 'green' : 'orange' }}>● {a.status}</span>
          </div>
        ))}
      </div>

      <h2>تشغيل مهمة جديدة</h2>
      <textarea value={goal} onChange={e => setGoal(e.target.value)}
        placeholder="اكتب الهدف هنا..." style={{ width: '100%', height: 100 }} />
      <button className="button button-primary" onClick={run}>Run Pipeline</button>
    </div>
  );
}

render(<Dashboard />, document.getElementById('zezo-ai-root'));

---

🎯 الملف الرئيسي zezo-ai-agents.php

php

<?php
/**
 * Plugin Name: Zezo AI Agents
 * Description: Multi-Agent LLM System for WordPress with Verification, Memory, and KG
 * Version: 1.0.0
 * Author: You
 */

require __DIR__ . '/vendor/autoload.php';

use Zezo\AI\LLM\OpenAIProvider;
use Zezo\AI\LLM\ClaudeProvider;
use Zezo\AI\Core\Agent;
use Zezo\AI\Core\MessageBus;
use Zezo\AI\Core\Orchestrator;
use Zezo\AI\Tools\ToolRegistry;
use Zezo\AI\Memory\MemoryStore;
use Zezo\AI\Memory\VectorClient;
use Zezo\AI\Verification\VerificationLoop;
use Zezo\AI\Admin\Dashboard;
use Zezo\AI\Admin\RestApi;

add_action('plugins_loaded', function () {
    $openai = new OpenAIProvider(get_option('zezo_openai_key', ''));
    $claude = new ClaudeProvider(get_option('zezo_claude_key', ''));

    $tools = (new ToolRegistry())
        ->register('wp_query', new \Zezo\AI\Tools\Tools\WpQueryTool())
        ->register('sql_query', new \Zezo\AI\Tools\Tools\SqlQueryTool());

    $vector = new VectorClient(get_option('zezo_qdrant_url', 'http://localhost:6333'), 'wp_agent_memory');
    $memory = new MemoryStore($openai, $vector);

    $verifier = (new VerificationLoop())
        ->addRule(VerificationLoop::lengthRule(10, 20000), 'length');

    $makeAgent = fn($id, $role, $prompt, $llm) =>
        new Agent($id, $role, $prompt, $llm, $tools, $memory, $verifier);

    $bus = new MessageBus();
    $orchestrator = (new Orchestrator($bus))
        ->register('planner', $makeAgent('planner', 'Planner', 'أنت مخطط خبير. فكك الأهداف لمهام فرعية.', $claude))
        ->register('researcher', $makeAgent('researcher', 'Researcher', 'أنت باحث. استخدم الأدوات لجمع الحقائق.', $openai))
        ->register('writer', $makeAgent('writer', 'Writer', 'أنت كاتب محترف بالعربية.', $claude))
        ->register('critic', $makeAgent('critic', 'Critic', 'أنت ناقد صارم. اذكر "مقبول" فقط عند الجودة العالية.', $openai))
        ->register('executor', $makeAgent('executor', 'Executor', 'أنت منفذ. انشر المحتوى في WordPress.', $openai));

    // Action Scheduler hook
    add_action('zezo_ai_run_pipeline', function ($goal) use ($orchestrator) {
        $orchestrator->runPipeline($goal);
    });

    (new Dashboard())->register();
    (new RestApi())->register();
});

---

📊 مقارنة سريعة بين المزوّدين

الميزة	OpenAI GPT-4o	Claude Sonnet 4.5
Tool calling	✅ ممتاز	✅ ممتاز
Embeddings	✅ مدمج	❌ (يحتاج Voyage/OpenAI)
JSON mode	✅ strict	✅ عبر tools
Context	128K	200K
الأفضل في	الأدوات والـ JSON	الكتابة والتحليل الطويل

التوصية: استخدم Claude للـ Planner/Writer وOpenAI للـ Researcher/Executor (لأنه يحتاج embeddings + JSON صارم).

---

⚠️ نقاط Production مهمة

1. Rate Limiting: خزّن عدد الـ tokens في wp_options وأوقف عند الحد.
2. Cost Tracking: سجّل usage من كل رد في جدول wp_agent_costs.
3. Async Execution: استخدم Action Scheduler (يأتي مع WooCommerce) أو wp_schedule_single_event.
4. Secrets: لا تخزن API keys في DB نصًا صريحًا — استخدم wp-config.php constants.
5. Kill Switch: wp_options.zezo_ai_enabled = false يوقف كل الوكلاء.
6. Logging: استخدم error_log أو Monolog إلى ملف في wp-content/uploads/zezo-ai-logs/.

---

🎬 الخطوة التالية — اختر واحدًا:

أ) أرسل لك الـ Plugin كامل جاهز للتنزيل؟

سأجمع كل الملفات في هيكل نهائي مع خطوات التثبيت (composer install → activate → إعداد المفاتيح).

ب) نبني مكوّنًا واحدًا بعمق أكبر؟

مثلًا:

• Verification Loop متقدم مع 8 أنواع تحقق مختلفة
• Memory System مع hierarchical + episodic + semantic
• Agent-to-Agent Protocol مع negotiation بين الوكلاء

ج) نبني حالة استخدام حقيقية؟

مثلًا:

• مدير محتوى ذكي: يكتب ويحرر وينشر مقالات WordPress تلقائيًا
• مساعد دعم عملاء: يقرأ تذاكر ويرد ويصعّد
• محلل SEO: يفحص المقالات ويقترح تحسينات وينفذها

---

قل لي:

1. أي مسار تريد (أ / ب / ج)؟
2. ما إصدار PHP و WordPress لديك؟
3. هل لديك مفاتيح OpenAI/Claude و Qdrant جاهزة؟

وسأكمل معك فورًا إلى الكود النهائي القابل للتشغيل. 🔥