عن المشروع

تعتبر tg-cli (اسم الأمر tg) جسراً لـ Telegram مخصصاً لوكلاء البرمجة بالذكاء الاصطناعي. تتكون من جزأين: واجهة CLI صادرة يستدعيها الوكلاء لدفع التحديثات، وdaemon وارد يُسمى tg-ctl ينقل ردودك من الهاتف إلى جلسة الوكيل النشطة. الصادر: يرسل الوكلاء النصوص، وتقارير HTML، والصور والملفات. يتم اكتشاف وسوم HTML تلقائياً، ويُضاف بادئة emoji مميزة للوكيل المكتشف. يتم تحويل ملفات Markdown إلى PDF عبر pandoc وheadless Chrome قبل الرفع، مع العودة لإرسال الملف الأصلي في حال فشل التحويل. يتم اكتشاف مسارات الملفات المذكورة في نص الرسالة وإرفاقها تلقائياً عبر بحث متكرر في شجرة العمل، مع ترك المسار في الوصف. تعمل عدة حواجز حماية قبل الإرسال. يتم رفض الرسائل الطويلة جداً التي تتجزأ إلى أكثر من ست رسائل Telegram. لا يتم إرفاق الملفات السرية أبداً: مثل ملفات .env، ومفاتيح SSH الخاصة، وملفات pem/key/p12/pfx/ppk، وملفات rc الخاصة ببيانات الاعتماد، وسجلات shell، وtfvars، وcredentials.json وkubeconfig؛ حيث يتم تخطي الإشارات المكتشفة تلقائياً، بينما يؤدي تمرير ملف صريح كحجة إلى خطأ جسيم. يمنع حاجز "الرموز المشوهة" وجود رمز CJK وحيد داخل كلمة لاتينية أو سيريلية، والرموز التي تتغير لغتها مرتين أو أكثر، مع السماح بالنصوص ثنائية اللغة الحقيقية. يرفض حاجز لقطات الشاشة الرسائل التي تذكر لقطة شاشة دون إرفاق صورة. تقوم بوابة القاموس بمطابقة الكلمات المحظورة من ملف JSON يديره المستخدم مع عنوان وجسم ووصف كل إرسال، دون وجود خيار للتجاوز؛ ويفشل الملف المشوه في الإرسال. تقوم الروابط التلقائية بحل معرفات تذاكر Linear عبر linear CLI وأرقام PR/issue الخاصة بـ GitHub عبر gh، مع تخزين النتائج لمدة ساعة والعودة إلى النص العادي عند الفشل. يمكن إيقاف الميزات الفردية باستخدام علامة no-feature. الوارد: يبدأ tg-ctl تلقائياً عند أول إرسال صادر من نافذة tmux تحتوي على وكيل مكتشف. يتم حقن الردود النصية البسيطة من Telegram في نافذة ذلك الوكيل. عند الرد على رسالة باقتباس، يتم إرفاق مرساة اقتباس تسمي الرسالة المجاب عليها، ويمكن لأمر tg replies استعادة الأصل كاملاً. يقوم الأمر /agent بتوجيه الرسالة إلى وكيل محدد، باستخدام المطابقة التقريبية (والوعي باللغة السيريلية) لأسماء النوافذ، مع تقديم أزرار اختيار مجمعة حسب الجلسة عند وجود غموض، بينما يعطي الاستدعاء المجرد قائمة بالوكلاء. الوكيل الذي يبدأ خارج tmux ليس لديه نافذة؛ لذا يُدرج كغير قابل للوصول مع ذكر السبب، وبدلاً من ذلك يحصل على قناة ثانية عبر صندوق وارد Stop-hook، والذي يتم قراءته عند نهاية كل دورة. يوضح ملف README هذا القيد بوضوح: الوكيل الخامل يتلقى الرسالة المجدولة فقط عندما ينهي دورته التالية. يعرض أمر inbox في tg-ctl ما هو مجدول. تقوم ميزة Question-to-buttons بتوجيه أسئلة الوكيل ومطالبات الأذونات إلى Telegram كأزرار مضمنة، بحيث يمكنك الإجابة بالنقر ويتم حقن الإجابة مباشرة في النافذة. وهي تغطي أشكال أسئلة وأذونات Claude Code، وPermissionRequest في Codex، وأحداث question.asked وpermission.asked في opencode، ويتم ربطها بشكل متكرر (idempotently) عبر أمر install-hooks الذي يقوم بنسخ الإعدادات الموجودة والحفاظ عليها. يتم تأجيل الرسائل المرسلة أثناء انتظار إجابة على سؤال بدلاً من مقاطعة المطالبة، ويمكن الإجابة على بطاقة سؤال منتهية المهلة بنص بسيط. تشمل الأوامر: stop (لمقاطعة الدورة الحالية)، وkill، وstatus، وlimit (أحدث بيانات الاستخدام لكل وكيل)، وtasks (لوحة مهام قابلة للتصفية)، وagent، وdaily (تقرير العمل المنجز) وspend (استخدام الرموز والتكلفة). يتم تنزيل الصور والمستندات المرسلة من Telegram إلى دليل تخزين مؤقت محلي ويتم حقن المسار ليقرأه الوكيل. يمكن لبيانات الاستخدام الموجهة من Claude Code statusLine، وتعداد رموز Codex، وإحصائيات جلسة Pi أن تطلق تحذيراً غير مكرر عندما يصل الحد إلى 90 بالمائة. توجيه مواضيع المنتدى (Forum-topic routing) اختياري وتجريبي، مع وجود تحذيرات موثقة حول إنشاء موضوع يؤدي لتشغيل وكيل، وإعادة فتح موضوع نشط لا يعيد ربط وكيله. يمكن تعطيل التحكم في ملف التكوين. التثبيت: يقوم سكربت تثبيت من سطر واحد بتثبيت التبعيات عبر Bun، وربط tg في PATH وتسجيل مهارة الوكيل؛ كما يعمل الاستنساخ اليدوي مع symlink. يوجد التكوين في ملف dotenv تحت دليل config مع رمز bot ومعرف chat. يقوم الأمر الفرعي install-skill بكتابة ملف مهارة وإضافة تعليمات قصيرة إلى ملفات harness المكتشفة. نظرًا لأن السكربت المستخرج هو الملف الثنائي الذي يعمل، فلا توجد خطوة بناء، ويقوم سكربت deploy بتحديث الاستخراج، رافضاً سحب التغييرات المحلية؛ تتطلب تغييرات كود daemon إعادة تشغيل، وهو ما يكتشفه السكربت ويبلغ عنه. مطلوب رمز bot واحد لكل جهاز، لأن Telegram يسمح بمستهلك getUpdates واحد لكل رمز.