zclaw

أصغر مساعد شخصي بالذكاء الاصطناعي ممكن لـ ESP32.

zclaw مكتوب بلغة C ويعمل على لوحات ESP32 بهدف صارم لميزانية البرنامج الثابت الكامل يبلغ <= 888 KiB في البناء الافتراضي. يدعم المهام المجدولة، والتحكم في GPIO، والذاكرة الدائمة، وتكوين الأدوات المخصصة من خلال اللغة الطبيعية.

الحد 888 KiB هو حجم البرنامج الثابت الكامل، وليس كود التطبيق فقط. يتضمن منطق zclaw بالإضافة إلى زمن تشغيل ESP-IDF/FreeRTOS، والشبكات/الواي فاي، وTLS/التشفير، وعبء حزمة الشهادات.

ممتع في الاستخدام، ممتع في الاختراق.

التوثيق الكامل

استخدم موقع التوثيق للحصول على أدلة ومراجع كاملة.

• التوثيق الكامل
• وحدة التحكم الإدارية المحلية
• حالات الاستخدام: مفيدة + ممتعة
• سجل التغييرات (ويب)
• ملف README الكامل (نص حرفي)

بداية سريعة

الإقلاع بسطر واحد (macOS/Linux):

bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)

هل قمت بالاستنساخ بالفعل؟

./install.sh

التثبيت غير التفاعلي:

./install.sh -y

أبرز الميزات

• الدردشة عبر Telegram أو مرحل الويب المستضاف
• جداول زمنية مدركة للمنطقة الزمنية (daily، periodic، ومرة واحدة once)
• أدوات مدمجة + أدوات يحددها المستخدم
• للحصول على إمكانيات مدمجة جديدة كلياً، أضف أداة برنامج ثابت (معالج C + إدخال السجل) من خلال توثيق Build Your Own Tool.
• تشخيصات وقت التشغيل عبر get_diagnostics (نطاقات quick/runtime/memory/rates/time/all)
• التحكم في GPIO و DHT و I2C مع حواجز حماية (بما في ذلك gpio_read_all و i2c_scan و i2c_read/i2c_write و dht_read)
• وحدة التحكم الإدارية المحلية عبر USB للاسترداد، والوضع الآمن، والتشغيل قبل الشبكة
• ذاكرة دائمة عبر عمليات إعادة التشغيل
• خيارات الشخصية: neutral، friendly، technical، witty

الأجهزة

الأهداف المختبرة: ESP32، ESP32-C3، ESP32-S3، و ESP32-C6. اللوحات الكلاسيكية ESP32-WROOM/ESP32 DevKit مدعومة. تقارير الاختبار لإصدارات ESP32 الأخرى مرحب بها جداً!

اللوحة المبدئية الموصى بها: Seeed XIAO ESP32-C3

التطوير المحلي والاختراق

الحلقة السريعة النموذجية:

./scripts/test.sh host
./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101
./scripts/monitor.sh /dev/cu.usbmodem1101

إعداد الملف الشخصي مرة واحدة، ثم إعادة الاستخدام:

./scripts/provision-dev.sh --write-template
# edit ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# if Telegram keeps replaying stale updates:
./scripts/telegram-clear-backlog.sh --show-config

مزيد من التفاصيل في دليل التطوير المحلي والاختراق.

نصوص مفيدة أخرى

وحدة التحكم الإدارية المحلية

عندما تكون اللوحة في الوضع الآمن، أو غير مزودة، أو مسار LLM غير متاح، لا يزال بإمكانك تشغيلها عبر USB التسلسلي بدون Wi-Fi أو رحلة ذهاب وإياب LLM.

./scripts/monitor.sh /dev/cu.usbmodem1101
# then type:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

الأوامر المحلية المتاحة:

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (مدمر؛ يمسح NVS ويعيد التشغيل)

المرجع الكامل: وحدة التحكم الإدارية المحلية

تفصيل الحجم

تفصيل esp32 الافتراضي الحالي (بايتات الصورة المجمعة من idf.py -B build size-components):

حجم الصورة الإجمالي من هذا البناء هو 853034 بايت؛ zclaw.bin المحشو هو 853184 بايت (~833.2 KiB)، ويترك 56128 بايت (~54.8 KiB) تحت حدود 888 KiB.

قياس أداء زمن الانتظار

قياس أداء مسار المرحل (يشمل معالجة مرحل الويب + رحلة ذهاب وإياب الجهاز):

./scripts/benchmark.sh --mode relay --count 20 --message "ping"

قياس أداء التسلسل المباشر (رحلة ذهاب وإياب المضيف + وقت الاستجابة الأول). إذا سجل البرنامج الثابت سطور METRIC request ...، فإن التقرير يتضمن أيضًا توقيت جانب الجهاز:

./scripts/benchmark.sh --mode serial --serial-port /dev/cu.usbmodem1101 --count 20 --message "ping"

الترخيص

MIT