شرح Agent Office 3D: حوّل وكيل البرمجة بالذكاء الاصطناعي لموظف فمكتب ثلاثي الأبعاد

شنو هو Agent Office 3D؟

Agent Office 3D هو مكتب ثلاثي الأبعاد منخفض التفاصيل كيخدم محلياً، وكيعرض وكلاء البرمجة بالذكاء الاصطناعي على شكل موظفين فالمكتب. تقدر تشوف بنظرة وحدة كل Agent واش خدام، ولا فحالة خمول، ولا سالى وكيتسنى، ولا عالق فإشعار ديال الصلاحيات خاصّو التأكيد.

المشروع كيستعمل بيانات تجريبية افتراضياً، وما كيحتاجش تربط حتى Agent من الأول. الموظفين اللي ما خدامينش كيحضّرو القهوة، كيشربو الما، كيستعملو جهاز الجري، كيمدّدو جسمهم، كينعسو شوية ولا كيلعبو ألعاب صغيرة مدمجة؛ ومنين كتفعّل Minecraft، كيقدرو الموظفين حتى يدخلو للعالم المحلي باستعمال روبوتات Mineflayer.

الموظفين والمهام والمشاريع والمبالغ اللي فالشاشة غير بيانات تجريبية، وماشي معلومات حقيقية ديال العمل.

الوظائف الرئيسية

• حالة الموظفين فالحين: كل Agent عندو بلاصتو الخاصة، وضو الحالة، وبطاقة الاسم؛ ومنين كيكون خاص التأكيد، كيبان التنبيه ببطاقة اسم حمرا وعلامة تعجب.
• واجهة طرفية للقراءة فقط: كليك على الموظف باش تشوف آخر مخرجات الطرفية، ولكن ما تقدرش تصيفط أوامر من واجهة المكتب.
• لوحة الإعلانات: كتعرض أهداف السنة، وKPI، وأهم نقاط هاد السيمانة، والتدفق النقدي، ولائحة المهام؛ وتقدر تعلم على المهام مباشرة.
• قاعدة بيانات المشاريع فرفوف الكتب: كل كتاب كيمثل مجلد مشروع، وتقدر تقرا وثائق Markdown ولقطات الشاشة.
• لائحة المهام: شوف من الجهة اليمنى الملفات والمحتوى الكامل ديالها فمجلد المهام.
• نشاط Minecraft فالراحة: الموظفين اللي ما خدامينش يقدرو يستعملو روبوتات Mineflayer ديالهم باش يحفرو، ويقطعو الشجر، ويبنو الديور، وكيبان المنظور من الشخص الأول فشاشة المكتب.

منين كتكليك على لوحة الإعلانات، كتتحل واجهة بكامل الشاشة باش تشوف معلومات الشركة والمهام.

رفوف الكتب كتوفر طريقة للقراءة فقط لتصفح المشاريع، ومناسبة باش تشوف بسرعة الوثائق ومواد المشروع.

متطلبات البيئة

• Node.js 20 أو أحدث: ضروري لتشغيل المكتب.
• Java 21 أو أحدث: مطلوب غير إلا فعّلت وظيفة Minecraft.
• متصفح كيدعم WebGL: Chrome وEdge وSafari وFirefox كاملين خدامين.

macOS وLinux هما المنصتان المدعومتان أساساً. Windows حالياً مدعوم بشكل تجريبي؛ صحيح أن CI كينفذ التثبيت وفحص الصياغة واختبارات الوضع التجريبي، ولكن المؤلف ما جرّبوش فبيئة Windows حقيقية، وMinecraft حتى هي ما تجرباتش على Windows.

تثبيت وتشغيل المكتب التجريبي

macOS وLinux

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

Windows PowerShell

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

من بعد التشغيل، البرنامج كيفتح http://127.0.0.1:4870/. الوضع الافتراضي هو demo، وحالة الموظفين كتتبدل أوتوماتيكياً، يعني ما كايناش حاجة توجد ولا تربط Agent من الأول. منين تسالي التجربة، ضغط على Ctrl+C فالطرفية باش توقف البرنامج.

التثبيت باستعمال AI Coding Agent

إلا كنت كتستعمل Claude Code أو Codex أو Cursor أو شي AI Coding Agent آخر، تقدر تحلو أولاً داخل مجلد المشروع، ومن بعد تلصق الأمر التالي:

قرا AGENTS.md ديال هاد repo، وعاونّي نثبّت Agent Office ونحل عرض Minecraft.

الـAgent غادي ينفذ npm run doctor حسب AGENTS.md، ويعاونك فالتثبيت وتشغيل العرض التجريبي، وغادي يسولك واش بغيتي تربط Herdr وكيفاش تخصص الشركة والموظفين. قبل ما يثبت برامج النظام بحال Node.js ولا Java غادي يسولك؛ أما Minecraft EULA خاصك تقراها وتدخل yes بنفسك، والـAI Agent ما غاديش يوافق بلاصتك. مستعملو Claude Code يقدرو حتى يدخلو /setup-office.

إعداد الشركة والموظفين ومصدر البيانات

نسخ ملف الإعدادات النموذجي أولاً:

cp office.config.example.json office.config.json

فـWindows PowerShell تقدر تستعمل:

Copy-Item office.config.example.json office.config.json

office.config.json ما كيدخلش فإدارة الإصدارات. إلا ما كانش الملف موجود، البرنامج كيستعمل الإعدادات النموذجية مباشرة. هادي هي الحقول الأكثر استعمالاً:

• port: منفذ اتصال الخدمة، والافتراضي هو 4870.
• openBrowser: واش يتحل المتصفح أوتوماتيكياً من بعد التشغيل.
• company.name: الاسم اللي كيستعمل فشريط العنوان ولافتة الشركة.
• company.currency: رمز العملة اللي كيبان فلوحة الإعلانات، بحال $ ولا NT$.
• company.logo وcompany.mark: مسارا الشعار العريض للشركة والأيقونة الصغيرة.
• owner.name وowner.title: اسم المدير والمسمى الوظيفي ديالو فمكتب المدير؛ مكتب المدير غير للزينة وما كيتوصلش بحالة Agent.
• cat.name: اسم قط المكتب.
• staff[]: لائحة الموظفين، وفيها id وtitle وcolor ديال الزي، وبحد أقصى 8 موظفين.
• source.type: مصدر الحالة، ويمكن يكون demo ولا herdr.
• data.board وdata.projects وdata.tasks: مواقع بيانات لوحة الإعلانات والمشاريع والمهام.

خاص staff[].id ديال الموظف يطابق اسم Agent فمصدر الحالة. تقدر ترجع لصيغة بيانات لوحة الإعلانات ورفوف الكتب فـdocs/board-format.md.

ربط Agent حقيقي: وضع Herdr

Herdr هو أداة تعدد طرفيات مخصصة لوكلاء البرمجة. باش تربط Herdr، شغّل Agent ديالك باستعمال Herdr أولاً، ومن بعد بدّل الإعدادات:

{
  "source": {
    "type": "herdr"
  },
  "staff": [
    {
      "id": "اسم Agent ديالك فـHerdr",
      "title": "المسمى الوظيفي",
      "color": "#4f8cff"
    }
  ]
}

من بعد نفذ:

npm start

المكتب غادي يستعمل غير أوامر Herdr للقراءة فقط: herdr agent list وherdr agent read. اللائحة البيضاء المدمجة كتمنع الأوامر الأخرى، لذلك المكتب ما غاديش يصيفط أزرار ولا يضغط مكانك على تأكيد الصلاحيات.

إلا بغيتي تربط أداة أخرى للحالات، زيد adapter فـlib/sources.js وخليه يرجع نفس الصيغة ديال لائحة الموظفين، وفيها الاسم والحالة وآخر أسطر من مخرجات الطرفية.

تفعيل عرض Minecraft

إلا كنت باغي غير تشوف بسرعة الموظفين التجريبيين كيلعبو Minecraft، نفذ:

npm run demo:minecraft

هاد الوظيفة كتحتاج Node.js 20 أو أحدث وJava 21 أو أحدث. فأول تشغيل غادي يتفحص Java، وغادي يطلب منك تقرا وتقبل Minecraft EULA، ومن بعد ينزل ملفات خادم الإصدار 1.21.4 من لائحة الإصدارات الرسمية ديال Mojang ويتحقق من SHA-1. إنشاء العالم كيحتاج غالباً تقريباً من 1 حتى 2 دقيقة.

خاصك تدخل yes بنفسك باش يتكتب eula=true. أي إدخال آخر غادي يلغي العملية، وما غادي يتهبط حتى ملف من Mojang. السبب هو أن الموافقة على EULA ديال برنامج خادم Minecraft خاصها تكون من الشخص اللي كيشغلو فعلياً.

إلا بغيتي تفعّل Minecraft فالوضع العادي ديال المكتب، نفذ أولاً:

npm run minecraft:setup

من بعد، بدّل minecraft.enabled فملف الإعدادات إلى true، ومن بعد نفذ npm start. خادم Minecraft غادي يرتبط بـ127.0.0.1 ويستعمل لائحة بيضاء لتقييد الاتصالات. منين كيرجع الموظف للخدمة، الروبوت المرتبط به كيوقف النشاط؛ والروبوتات كتخدم غير إلا كان الموظف فحالة خمول وشي واحد فاتح واجهة المكتب.

مشاهدة الموظفين من داخل لعبة Minecraft

إلا عندك نسخة Minecraft Java، تقدر تزيد اسم اللاعب ديالك فـminecraft.guests:

{
  "minecraft": {
    "guests": ["YourName"]
  }
}

وتقدر حتى تستعمل متغيرات البيئة:

MC_GUESTS=YourName npm run demo:minecraft

فـWindows PowerShell تقدر تستعمل:

$env:MC_GUESTS="YourName"; npm run demo:minecraft

1. حل Minecraft Java 1.21.4 فنفس الحاسوب.
2. دخل للعب الجماعي، اختار الاتصال المباشر، ودخل localhost:25570.
3. من بعد الدخول غادي يتحول تلقائياً لوضع المراقبة، وتقدر تطير وتدوز من الحيطان بلا ما تبدل العالم.
4. ضغط على زر الرقم 1 ولا استعمل زر الفأرة الأوسط باش تحل قائمة المراقبة، ومن بعد اختار الموظف اللي بغيتي تشوف.

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

أوامر التطوير والتشخيص

المشروع كيوفر شوية ديال الأوامر المناسبة لفحص البيئة والتحقق من التعديلات:

npm run doctor  # فحص البيئة للقراءة فقط
npm run check   # فحص صياغة JavaScript وتنسيق JSON
npm run smoke   # اختبار سريع للوضع التجريبي

npm run doctor كيرجع رمز الخروج 0 منين كتكون جميع العناصر واجدة؛ وكيرجع 2 إلا ما كانش Minecraft واجد؛ وكيرجع 1 إلا ما قدرش المكتب يخدم. زيد -- --json باش تخرج النتائج بصيغة JSON.

فوقت التطوير تقدر حتى تستعمل بارامترات ديال الرابط، بحال ?fast باش تسرّع الحركات، و?idle=coffee باش تخلي الموظفين اللي ما خدامينش يديرو حركة معيّنة، و?cat=nap باش تبدّل البرنامج ديال القط. سميات الحركات اللي ممكن تستعمل خاصك ترجع فيها لـ public/behavior.js.

ملاحظات السلامة

• المكتب كيقرا الخرج ديال Agent فالطرفية، واللي يقدر يكون فيه كود، مسارات ولا معلومات حساسة.
• السيرفر مربوط غير بـ 127.0.0.1 وكيتحقق من ترويسة Host؛ ما تعرّضش الخدمة عبر reverse proxy ولا tunnel ولا الشبكة العمومية.
• الوظيفة الوحيدة ديال الكتابة فالمكتب هي التعليم على مهام لوحة الإعلانات؛ باقي حالات Agent وبيانات الطرفية غير قابلة للقراءة فقط.
• الرفوف كيقراو غير المجلد اللي متحدد فالإعدادات، وكيمنعو تجاوز المسارات والروابط الرمزية اللي كتخرج من المجلد؛ ومع ذلك ما منصوحش تحط كلمات السر ولا token فمجلد المشروع.
• سيرفر Minecraft كيسمع غير محلياً ومفعّل فيه اللائحة البيضاء، عافاك ما تبدلوش باش يقبل الاتصالات من الخارج.

الخلاصة

Agent Office 3D كيحوّل حالة Agents اللي كانت متفرقة فالطرفية لمكتب ثلاثي الأبعاد ساهل الفهم. تقدر تبدا بـ npm start باش تجرّب وضع العرض، ومن بعد تخصّص الشركة والموظفين عبر office.config.json، وفالأخير تربطو بـ Herdr باش تشوف الحالة الحقيقية ديال Agents. إلا بغيتي تزيد التفاعل، استعمل npm run demo:minecraft باش تشوف الموظفين اللي ما خدامينش كيتحرّكو فعالم Minecraft المحلي.

تذكّر بلي هاد المشروع مرخّص برخصة MIT، وما عندو حتى علاقة بـ Mojang ولا Microsoft؛ ومنين كتستعمل Minecraft خاصك تقرا وتقبل EULA ديالها بوحدك.