دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

دليل تطوير ZCode: بناء ورشة برمجة بالذكاء الاصطناعي لسطح المكتب والويب والطرفية

كيشرح هاد الدليل كيفاش تجهّز بيئة تطوير ZCode، وتشغّل نسخة Electron لسطح المكتب، وورشة الويب، وAgent CLI، ومن بعد تهيّأ الموارد البعيدة، والمصادقة على الولوج، وحزم التوزيع.

حوالي 24 دقايق ديال القراية
دليل تطوير ZCode: ورشة برمجة بالذكاء الاصطناعي لسطح المكتب والويب والطرفية

تعرّف على ZCode

شعار مشروع ZCode

ZCode هي منصّة عمل للبرمجة بالذكاء الاصطناعي، وكتوفّر تطبيق سطح المكتب Electron، وواجهة فالمتصفح، وAgent فالترمينال. المستودع منظم بصيغة workspace، وكيجمع صيانة كليان، وخدمات الخلفية، وواجهة المستخدم المشتركة، وAgent CLI، وTUI، وكود المصدر ديال وقت التشغيل.

المشروع كيوفّر ثلاثة مداخل رئيسية للتطوير:

  • Desktop: تطبيق Electron لسطح المكتب، كيتشغّل بـ pnpm dev:desktop.
  • Web: كيشغّل فـ نفس الوقت منصّة العمل فالمتصفح والخلفية المحلية، بـ pnpm dev:web.
  • Agent CLI: للتطوير المباشر ديال Agent فالترمينال أو TUI، بـ pnpm --filter @zcode/cli dev.

وزيد على هاد الشي، ZCode تقدر تتبنّى فحزمة موحّدة للتوزيع عبر سطر الأوامر. من بعد التثبيت، نفّذ zcode باش تدخل لـ TUI، أو zcode --web باش تشغّل منصّة العمل المحلية فالويب.

الخصائص الرئيسية

  • كتوفّر ثلاث طرق للاستعمال: سطح المكتب، المتصفح، والترمينال.
  • الواجهة الأمامية ديال الويب، وخلفية HTTP/WebSocket، وAgent يقدرو يشكّلو سلسلة عمل كاملة فالجهاز المحلي.
  • Desktop وWeb كيتشاركو نفس وقت تشغيل Agent CLI.
  • كتدعم التطوير فمساحات عمل بعيدة عبر SSH وWSL.
  • كتشارك مكوّنات React، وhooks، وحالة Zustand، وأنواع البروتوكولات، وإطار RPC، وSDK ديال Agent.
  • يمكن بناء حزم تثبيت مستقلة لسطح المكتب وحزمة توزيع موحّدة لأوامر ZCode.
  • منين كيتفتح Web للوصول الخارجي، يقدر يولّد تلقائيا رمز ولوج، أو يمكن ضبط رمز مصادقة بشكل صريح.

تحضير بيئة التطوير

تثبيت الأدوات الضرورية

قبل ما تبدا، وجّد الأدوات التالية. الإصدارات المضبوطة كاينة فـ mise.toml فالجذر ديال المستودع:

  • Git
  • Node.js 24.14.0
  • pnpm 10.33.2

من بعد ما تنسخ المستودع وتدخل للجذر ديالو، نفّذ أمر التهيئة الموصى به:

pnpm bootstrap

pnpm bootstrap كيثبّت اعتماديات workspace، وكيحضّر موارد التشغيل المحلية ديال سطح المكتب، وكيشغّل build:bootstrap. Agent CLI ووقت التشغيل راه موجودين فـ apps/zcode-cli/، وما كايناش حاجة لتهيئة Git submodule إضافي.

الـ bootstrap الافتراضي كيتجاوز تحضير الموارد البعيدة، وهاد الشي مناسب أكثر لتطوير سطح المكتب محليا. غير إلا كنت محتاج SSH أو WSL أو موارد التوزيع البعيدة، خاصك تشغّل أوامر الموارد البعيدة.

اختيار أمر التهيئة حسب الحاجة

  • pnpm install: تثبيت الاعتماديات فقط.
  • pnpm prepare:desktop-runtime: تحضير موارد تشغيل سطح المكتب، وكيشمل افتراضيا تحضير الموارد البعيدة.
  • pnpm prepare:remote-assets: تحضير موارد التشغيل البعيدة بوحدها.
  • pnpm bootstrap:with-remote: تهيئة الاعتماديات والموارد المحلية والبعيدة، وبناء الحزم المعنية بالتتابع، مع تجاوز bundle ديال تطبيق سطح المكتب.
  • pnpm build: تنفيذ سكريبتات البناء ديال جميع حزم workspace بشكل递归، بما فيها خطوات تحضير الموارد داخل الحزم.

تشغيل نسخة سطح المكتب

من بعد ما تكمل التهيئة، شغّل تطبيق Electron لسطح المكتب من جذر المستودع:

pnpm dev:desktop

pnpm dev:desktop كيعادل افتراضيا pnpm dev:desktop:prod، وكيستعمل إعدادات خدمات الإنتاج. سكريبت التشغيل كيحضّر موارد التشغيل المحلية، وكيبني Agent ديال سطح المكتب، ومن بعد كيشغّل Electron ومراقبة تغييرات المصدر.

إلا بغيتي تستعمل بيئة الاختبار، شغّل:

pnpm dev:desktop:test

عزل بيانات التطوير

باش ما تخلطش بيانات التطوير مع البيانات ديال الاستعمال اليومي، تقدر تحدد مجلد أساسي مستقل للبيانات عبر ZCODE_DATA_BASE_DIR. بيانات التطبيق غادي تتكتب فـ .zcode/ داخل داك المجلد:

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

هاد الطريقة خدامة فـ macOS وLinux.

تشغيل منصّة العمل Web

منين كتعدّل فمصدر الواجهة الأمامية أو الخلفية ديال Web، من الأحسن تستعمل نمط التطوير المشترك:

pnpm dev:web

هاد الأمر كيشغّل فـ نفس الوقت:

  • خادم تطوير Web، والعنوان الافتراضي ديالو هو http://localhost:5173.
  • الخلفية المحلية، والعنوان الافتراضي ديالها هو http://localhost:3030.

خاص المتصفح يدخل لعنوان الواجهة الأمامية. خادم التطوير كيحوّل طلبات /ws وطلبات /api العادية للخلفية المحلية؛ أما /api/v1/oauth/token فكيتحوّل بوحدو لخدمة المنتج المضبوطة حاليا.

تحديد مساحة عمل الخلفية

فـ macOS أو Linux، تقدر تحدد مجلد المشروع اللي غادي تستعملو خلفية Web عبر متغير بيئي:

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

إلا عدّلت فمصدر Agent، خاصك تعاود تبني CLI والاعتماديات ديال workspace ديالو، ومن بعد تعاود تشغّل الخدمة:

pnpm --filter @zcode/cli... build

تطوير Agent CLI وTUI

إلا كان التركيز ديالك على واجهة الترمينال أو Agent، تقدر تشغّل مدخل المصدر مباشرة:

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

من بعد بناء CLI والاعتماديات ديالو، تقدر حتى تشغّل مباشرة ملف CommonJS الناتج:

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

مدخل المصدر هادا كيشغّل Agent CLI مباشرة، وما كينفّذش التوجيه --web ديال أمر التوزيع الموحّد. لتطوير Web استعمل pnpm dev:web؛ ولاختبار أمر zcode الموحّد، خاصك تبني حزمة التوزيع عبر سطر الأوامر وتفك ضغطها.

استعمال نسخة ZCode عبر سطر الأوامر

حزمة التوزيع عبر سطر الأوامر كتجمع TUI وWeb والخلفية وAgent، وكتشغّلهم كاملين عبر zcode. ما كتحتاجش Electron، ولكن وقت التشغيل باقي محتاج Node.js مطابق للمتطلبات الموجودة فـ mise.toml.

الأوامر الأساسية

# الدخول لواجهة التفاعل فالترمينال
zcode

# تشغيل منصّة العمل Web
zcode --web

# تحديد المشروع والمنفذ، ومنع فتح المتصفح تلقائيا
zcode --web --workspace /path/to/project --port 3030 --no-open

# عرض المساعدة
zcode --help
zcode --web --help

نمط Web كيستعمل افتراضيا المجلد الحالي كمجلد عمل، وكيسمع على 127.0.0.1، وكيختار تلقائيا منفذا فارغا وكيحل المتصفح. افتراضيا ما كيتفعّلش رمز الولوج. من بعد ما تسالي، ضغط Ctrl+C فالترمينال باش توقف الخدمة.

الولوج من الشبكة المحلية

إلا بغيتي تخلي أجهزة أخرى تدخل، بدّل عنوان الاستماع لـ 0.0.0.0:

zcode --web --host 0.0.0.0

منين كيسمع ZCode على عنوان ماشي محلي، كينشئ افتراضيا رمز ولوج. استعمل الرابط اللي فيه الرمز واللي كيبان فخرج الترمينال للدخول للخدمة. وتقدر حتى تحدد الرمز عبر --token، أو تسد مصادقة الرمز عبر --no-token.

منين كتشغّل مباشرة مدخل HTTP ديال خدمة Web العامة، تقدر تضبط مصادقة API وWebSocket عبر ZCODE_SERVER_AUTH_TOKEN؛ ومنين كتنشئ الخدمة عبر واجهة برمجية، استعمل الخيار authToken.

ضبط المتغيرات البيئية

الملف .env.example الموجود فـ جذر المستودع كيوفّر أمثلة لعناوين الخدمات وإعدادات البناء. تقدر تنسخو حسب الحاجة لـ .env، وتحط إعدادات التجاوز الخاصة بالاستعمال المحلي فقط فـ .env.local.

  • ZCODE_DATA_BASE_DIR: المجلد الأساسي لبيانات التطبيق، والبيانات كتتكتب فـ .zcode/ داخلو.
  • ZCODE_SERVER_WORKSPACE: تحديد مسار مساحة عمل خلفية Web.
  • ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: تحديد ملف إعداد Provider المحلي؛ إلا ما تحددش، كتستعمل الإعدادات المدمجة.
  • ZCODE_DIST_BASE_URL: العنوان الأساسي للتحميل اللي كيستعملو سكريبت تثبيت سطر الأوامر.

تقدر حتى تحط هاد المتغيرات ديال وقت التشغيل مباشرة فبيئة أمر التشغيل. أما إعدادات خدمة تطوير Desktop فكتتحدد عبر dev:desktop:test وdev:desktop:prod.

تطوير خصائص SSH وWSL البعيدة

قبل تطوير خصائص مساحات العمل البعيدة، حضّر الموارد البعيدة أولا:

pnpm bootstrap:with-remote
pnpm dev:desktop

منين كتربط بمشروع بعيد، اختار الموارد “تنزيل محلي ثم رفع”. بيئة التطوير كتجيب الموارد من packages/desktop/mock-cdn المحلي ومن نواتج البناء المحلية، ومن بعد كترفعها للمضيف البعيد عبر SFTP، وما كتوصلش لـ CDN.

بناء حزمة تثبيت سطح المكتب

شغّل الأمر التالي لبناء نسخة سطح المكتب:

pnpm bundle:desktop

الهدف الافتراضي هو macOS arm64، ومجلد الإخراج هو packages/desktop/dist/. وتقدر حتى تحدد نظام التشغيل ومعمارية CPU:

pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help

--os كيدعم mac وwin وlinux، و--arch كيدعم x64 وarm64. عملية الحزم والتوقيع الفعلية باقي كتحتاج الأدوات والإعدادات الخاصة بالمنصّة المستهدفة.

فـ macOS، تقدر تفتح DMG الناتج وتهز ZCode لمجلد “التطبيقات”. إلا حبس النظام أول تشغيل ديال بناء محلي ما موقّعش، نفّذ:

sudo xattr -rd com.apple.quarantine /Applications/ZCode.app

بناء حزمة التوزيع عبر سطر الأوامر

مدخل بناء حزمة التوزيع عبر سطر الأوامر هو pnpm build:zcode. قبل البناء، خاصك تضبط العنوان الأساسي للتحميل ZCODE_DIST_BASE_URL، وتقدر حتى تمرّرو مباشرة عبر --base-url:

pnpm build:zcode --base-url https://downloads.example.com/zcode/

# ملي كتكون ZCODE_DIST_BASE_URL مهيّأة
pnpm build:zcode

# عاود استعمل ناتج البناء الموجود، غير عاود جمع الحزمة
pnpm build:zcode --skip-build

# شوف المعاملات المتاحة
pnpm build:zcode --help

عنوان التحميل اللي فالمثال غير تجريبي، وفوقت النشر الرسمي خاصّو يتبدّل بعنوان الاستضافة الفعلي. سكريبت البناء كيعالج بالتتابع CLI/TUI، والواجهة الخلفية، وWeb، وكيجمع المكتبات الأصلية، وworker، والاعتماديات ديال وقت التشغيل، ومن بعد كيركّب حزمة التوزيع.

الإصدار الافتراضي كيجّي من package.json اللي فالجذر، ومجلد الإخراج هو dist/zcode/، وكيشمل:

  • releases/<version>/zcode-<version>.tar.gz: حزمة التشغيل.
  • releases/<version>/sha256.txt: ملخّص التحقّق.
  • latest.json: فهرس الإصدارات.
  • install.sh: سكريبت التثبيت.

سكريبت التثبيت كيثبّت افتراضياً وقت التشغيل فـ ~/.zcode/runtime، وكيصايب الأمر zcode فـ ~/.local/bin. تقدر تبدّل هاد الجوج المواقع باستعمال ZCODE_DIST_HOME وZCODE_DIST_BIN_DIR كل واحد بوحدو.

التحقّق محلياً من حزمة التوزيع

ما كايناش حاجة ترفع الملفات ولا تنفّذ سكريبت التثبيت؛ تقدر تفكّ الضغط وتشغّل ناتج البناء مباشرة:

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
  -C dist/zcode/debug

# شغّل TUI
node dist/zcode/debug/zcode/bin/zcode.mjs

# شغّل Web
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

من بعد سير لـ http://127.0.0.1:3030 باش تتحقّق من المسار الكامل اللي فيه نفس الواجهة الخلفية كتستضيف صفحات Web وAgent. خاصّ المنفذ يكون خالي؛ إلا كان pnpm dev:web مستعمل داك المنفذ، استعمل منفذاً آخر بواسطة --port.

نصائح متقدّمة للتطوير

  1. استعمل المدخل المناسب أولاً: وظائف سطح المكتب باستعمال dev:desktop، والتكامل بين الواجهة الخلفية والأمامية باستعمال dev:web، وAgent وTUI باستعمال الأمر dev ديال CLI workspace.
  2. عاود البناء من بعد تعديل Agent: خدمة Web ما كتستافدش أوتوماتيكياً من جميع نتائج بناء Agent؛ من بعد التعديل خاصّك تنفّذ pnpm --filter @zcode/cli... build وتعاود تشغّل الخدمة.
  3. عزل بيانات الاختبار: استعمل ZCODE_DATA_BASE_DIR باش تدير مجلدات بيانات مستقلة لسيناريوهات التطوير المختلفة.
  4. خلي المصادقة مفعّلة ملي كتستمع للاتصالات الخارجية: من بعد استعمال --host 0.0.0.0، من الأفضل تخلي الرمز اللي كيتولّد أوتوماتيكياً ولا تعيّن صراحةً --token.
  5. تأكّد من مصدر الأمر: pnpm build:zcode غير كينشئ حزمة التوزيع، وما كيبدّلش zcode الموجود من قبل فـ PATH ديال النظام. فـ macOS وLinux تقدر تشغّل command -v zcode، وفـ Windows تقدر تشغّل where.exe zcode.
  6. فرّق بين التحقّق ديال التطوير والتوزيع: pnpm dev:web مناسب للتطوير المتواصل ديال المصدر؛ أما bin/zcode.mjs من بعد فكّ الضغط فأنسب للتحقّق من الأمر الموحّد النهائي ومن مسار التوزيع الكامل.

نظرة سريعة على بنية المستودع

  • packages/desktop: Electron Main وHost وRenderer وتجميع تطبيق سطح المكتب.
  • packages/web: عميل Web.
  • packages/server: خدمات HTTP وWebSocket والاتصالات عن بُعد.
  • packages/zcode-server-cli: تشغيل Server المستقل وتدبير العمليات.
  • packages/ui: مكوّنات React المشتركة وhooks وحالة Zustand.
  • packages/services: خدمات الأعمال والتخزين الدائم.
  • packages/shared وpackages/rpc وpackages/client: البروتوكولات والأنواع المشتركة، وإطار RPC، وSDK ديال عميل Agent.
  • packages/provider وpackages/provider-node: الوظائف العامة ديال Provider والتنفيذ ديال Node.js.
  • apps/zcode-cli: CLI ديال Agent، وTUI، ووقت التشغيل، والأدوات.
  • scripts وconfig وthird-party: سكريبتات صيانة البناء، والإعدادات المضمّنة، ومواد التصريحات ديال الأطراف الثالثة.

الخلاصة

ZCode كيدمج تطبيق سطح المكتب وWeb والواجهة الخلفية وCLI ديال Agent فـ workspace واحد. فالتطوير لأول مرة تقدر تبدا بـ pnpm bootstrap، ومن بعد تختار حسب الهدف pnpm dev:desktop أو pnpm dev:web أو مدخل كود المصدر ديال CLI. إلا بغيتي تختبر workspace عن بُعد ولا تدير نشر رسمي، حضّر الموارد عن بُعد وبنِ حزمة التثبيت المناسبة لسطح المكتب ولا لسطر الأوامر.