Munjiz OS Controller (munjiz-os-controller) — v2.0

محرك توجيه هجين ثلاثي الطبقات (3-Layer Context-Aware Hybrid Execution Engine) وخادم بروتوكول سياق النماذج (MCP Server) مصمم خصيصاً لتمكين وكلاء تطبيق مُنجز (Munjiz) من التحكم الكامل والبصري في نظام التشغيل Windows والويب، مع تتبع حي لمؤشر الفأرة ودعم أصلي للكتابة باللغة العربية.

يستلهم هذا المشروع معماريته الهندسية من أقوى الأطر البحثية والعملية مفتوحة المصدر ليتجاوز قيود مشاريع النقر البصري التقليدية مثل Open Computer Use وSelf-Operating Computer، جامعاً بين واجهة الوكيل والحاسوب في Simular AI Agent-S ونظام الوكلاء الهجين لبيئة ويندوز في Microsoft UFO ومحرك الرؤية وتحليل عناصر الشاشة Microsoft OmniParser V2.

المعمارية الهجينة ثلاثية الطبقات (The 3-Layer Execution Engine)

يختار محرك munjiz-os-controller طبقة التنفيذ المثلى تلقائياً بناءً على سياق المهمة لتوفير أقصى سرعة وأقل استهلاك لتوكنز الصور:

Related MCP server: Extra

أبرز المزايا الهندسية في الإصدار 2.0

• المشاهدة المرئية الحية وتتبع مؤشر الماوس (capture_live_view): يعالج مشكلة اختفاء أيقونة الفأرة في لقطات الشاشة القياسية عبر قراءة موقع المؤشر الحقيقي (user32.GetCursorPos) ورسم مؤشر واضح (Crosshair + Halo) مع خط مسار الحركة (Trajectory) من موقع الماوس الحالي إلى العنصر المستهدف.

• الوميض البصري المباشر على شاشة المستخدم (show_live_click_ripple): يعرض حلقة ضوئية شفافة عابرة للنقرات (Click-Through HUD) فوق شاشة Windows في موضع نقر الوكيل ليشاهد المستخدم بالعين المجردة أين يتفاعل "مُنجز" لحظياً.

• دعم أصلي وكامل للغة العربية (keyboard_input): يتجاوز قصور دالة pyautogui.write() مع الحروف العربية عبر نسخ النص العربي برمجياً إلى الحافظة (pyperclip) وإرسال اختصار اللصق Ctrl+V، مع حفظ واستعادة محتوى حافظة المستخدم السابق تلقائياً.

• معالجة انحراف أبعاد الشاشة (Per-Monitor DPI Awareness V2): يضبط وعي العملية بدقة الشاشة الحقيقية فور التشغيل لمنع أي انحراف في إحداثيات النقر (X, Y) على الشاشات ذات التكبير 125% أو 150% أو 4K.

• التصعيد التلقائي الذكي (smart_interact): يحاول التفاعل مع العنصر بالاسم عبر الطبقة الثانية (Windows UI Automation) أولاً، وإذا كانت الواجهة مغلقة برمجياً ينتقل تلقائياً إلى الطبقة الثالثة لتحليل الشاشة بصرياً والنقر عبر رقم الصندوق box_id.

هيكل ملفات المستودع

munjiz-os-controller/
├── munjiz_os_controller.py   # المحرك الهجين الكامل وخادم FastMCP
├── pyproject.toml            # إعدادات الحزمة والاعتماديات ونقاط التشغيل
└── README.md                 # التوثيق المعماري ودليل الربط مع مُنجز

التثبيت والتجهيز السريع

1. تثبيت الحزمة الأساسية

git clone https://github.com/<your-org>/munjiz-os-controller.git
cd munjiz-os-controller
pip install -e .

لتثبيت دعم أتمتة المتصفح والويب الاختياري عبر browser-use وPlaywright:

pip install -e ".[web]"
playwright install chromium

2. تشغيل الاختبار التشخيصي الذاتي (Self-Test Demo)

يمكنك التحقق من عمل الطبقات الثلاث وتوليد لقطات الشاشة المرقمة وتتبع المؤشر عبر تشغيل وضع المحاكاة:

python munjiz_os_controller.py --mode demo

الربط مع تطبيق "مُنجز" عبر بروتوكول MCP

يعمل المحرك كخادم MCP قياسي عبر قناة stdio. لربطه مع وكلاء "مُنجز"، أضف الإعداد التالي إلى ملف تكوين جسور الأدوات (mcp_config.json):

{
  "mcpServers": {
    "munjiz-os-controller": {
      "command": "python",
      "args": [
        "C:/path/to/munjiz-os-controller/munjiz_os_controller.py",
        "--mode",
        "mcp"
      ],
      "env": {
        "MUNJIZ_OMNIPARSER_URL": "http://127.0.0.1:8000/parse",
        "MUNJIZ_LLM_MODEL": "gpt-4o"
      }
    }
  }
}

كما يمكنك تشغيله مباشرة بعد تثبيت الحزمة عبر أمر النظام المختصر munjiz-mcp --mode mcp.

دليل الأدوات المتاحة لوكلاء "مُنجز" (MCP Tools Reference)

الاستخدام البرمجي المباشر داخل نواة Python في "مُنجز"

بالإضافة إلى تشغيله كخادم MCP، يمكنك استيراد MunjizHybridRouter ومخطط أدوات get_openai_tools_schema() مباشرة داخل كود Python الخاص بنواة "مُنجز" وربطه مع نماذج Azure AI Foundry:

from munjiz_os_controller import (
    MUNJIZ_ACI_SYSTEM_PROMPT,
    MunjizHybridRouter,
    get_openai_tools_schema,
)

router = MunjizHybridRouter(omniparser_endpoint="http://127.0.0.1:8000/parse")

# 1. قراءة سريعة لملف إكسل عبر الطبقة الأولى (بدون فتح Excel بالماوس)
clients = router.cli_layer.read_tabular_file_fast("C:/Projects/clients.xlsx")

# 2. تفعيل نافذة النظام المحاسبي عبر الطبقة الثانية
router.uia_layer.window_manager(operation="focus", title_query="النظام المحاسبي")

# 3. فحص الشاشة التكيفي والتفاعل الذكي (طبقة 2 ثم تصعيد تلقائي للطبقة 3)
screen_state = router.inspect_screen(mode="auto")
router.smart_interact(
    target_label="اسم العميل",
    action="click",
    text_to_type="شركة آفاق التقنية المتقدمة",
    press_enter=True,
)

الرخصة

مرخص بموجب رخصة MIT.