البنية

‏aipager برنامج asyncio يعمل في الخلفية في عملية واحدة. يربط بين ثلاثة عوالم: دردشتك في Telegram، وعمليات Claude Code التي تعمل تحت dtach، ونظام الهوكات في Claude Code. كل شيء يمر عبر حلقة أحداث واحدة (event loop): لا مجموعات خيوط عاملة، ولا قواعد بيانات، ولا طوابير بين العمليات.

مخطط الأجزاء#

كل ما في المخطط يعمل على هذا الكمبيوتر، باستثناء Telegram. يتصل aipager أيضًا ببضعة خوادم أخرى: نفق Cloudflare الخاص بـ Mini App (وGitHub مرة واحدة، من أجل cloudflared)، وtelegram.org لجلب سكربت Mini App، وفحص الإصدارات عند طلب تحديث، وتنزيل نموذج التعرف على الكلام عند أول استخدام للرسائل الصوتية، وعنوان استقبال تقارير المشكلات عند إرسال تقرير. كلها مذكورة في نموذج الأمان ← الاتصالات الشبكية.

بنية العملية#

استدعاء واحد لـ asyncio.run في aipager/cli/daemon.py يشغّل كل شيء. وفي داخله:

• ‏TelegramBot (aipager/bot/): يملك Application من python-telegram-bot. يستقبل التحديثات من Telegram، ويوزعها على معالجات الرسائل والأزرار والرسائل الصوتية، ويُبقي بطاقات العمل وشريط الحالة المثبّت والإجابات محدّثة.
• ‏HookReceiver (aipager/dtach/hook_receiver.py): يفتح مقبس datagram من نوع Unix في ‎$XDG_RUNTIME_DIR/aipager.sock، ويقرأ JSON الذي يرسله aipager-hook وaipager-statusline، ويوزع العمل بحسب hook_event_name (أو type لرسائل aipager نفسه؛ يُنظر أحداث الهوك).
• ‏SessionMonitor (aipager/session_monitor.py): يستيقظ كل ثانيتين ليفحص ‎/tmp/claude-dtach-*.sock، ويطابق الجلسات التي يجدها مع قائمة الجلسات، ويشغّل المراقبات: بطاقة عمل توقفت عن الحركة، ورسالة لم يأخذها Claude Code أبدًا، وطلب إذن بلا أخبار منذ ٥ دقائق تُظهر المحادثة المحفوظة أنه انتهى (AIPAGER_INTERACTIVE_TIMEOUT)، ومهمة فاتت لحظة انتهائها.
• ‏SessionRegistry (aipager/state.py): كائنات TrackedSession مفهرسة بالاسم. تُحفظ في ‎~/.claude/aipager-sessions.json (بشكل ذري) عند الإيقاف وكلما تغيّر شيء يجب أن يبقى بعد إعادة التشغيل.
• خادم Mini App (aipager/miniapp/server.py): تطبيق aiohttp على 127.0.0.1 في المنفذ MINIAPP_PORT (الافتراضي 8765)، ويُتاح لـ Telegram عبر نفق Cloudflare مُدار ما دام مفعّلًا (وهو مفعّل افتراضيًا). يقدّم لوحة ‎/app.

كل هذه الأجزاء تعمل كمهام على الحلقة نفسها. والعمل الذي قد يعطّل الحلقة يجري في خيوط منفصلة: تحويل الرسائل الصوتية إلى نص، وبناء تقرير المشكلة وإرساله، وفحص التحديثات وتخطيط إعادة التشغيل، وتنزيل سكربت Mini App وcloudflared، وفحص تسجيل الدخول عند البدء.

تسلسل الإقلاع#

من aipager/cli/daemon.py:

1. نقل الإعداد القديم (config.env وteam.yaml) إلى aipager.yaml، مرة واحدة، وإحالة الملفات القديمة إلى التقاعد.
2. رفض البدء إذا كان aipager آخر يجيب على المقبس، ثم أخذ قفل aipager (~/.local/share/aipager/daemon.lock).
3. التحقق من توكن البوت لدى Telegram (getMe).
4. إصلاح ملفات Claude Code نفسه: إضافة أي هوك أو سطر حالة لـ aipager ينقص إلى ‎~/.claude/settings.json، والإجابة عن أسئلة التشغيل الأول التي لا يستطيع مستخدم Telegram الإجابة عنها (يُنظر الأمان).
5. ‏SessionRegistry.load()‎: يقرأ ‎~/.claude/aipager-sessions.json. إذا كان الملف غير موجود أو غير مقروء، تبدأ القائمة فارغة.
6. تحديد عنوان Mini App (عنوانك الخاص، أو Tailscale)، ثم bot.start()‎: بدء استقبال التحديثات من Telegram.
7. ‏HookReceiver.start()‎: يحذف ملف مقبس قديمًا متبقيًا، ثم bind، ثم الاستماع.
8. ‏bot.recover_sessions()‎: يعيد البطاقات والطلبات للجلسات التي كانت تعمل أو تنتظر عندما توقف aipager (يُنظر الأوامر ← الإجابات).
9. ‏SessionMonitor.start()‎: يبدأ الفحص كل ثانيتين.
10. يبدأ خادم Mini App، ثم النفق (حين لا يكون هناك عنوان خاص بك)، وتُنشر أزرار ‎📱 App.
11. ينتظر aipager الإشارات: SIGINT أو SIGTERM يوقفه، وSIGUSR1 يعيد تحميل الدردشات والقواعد (المجموعات ← إعادة التحميل دون إعادة تشغيل).

تسلسل الإيقاف#

1. ‏SIGINT أو SIGTERM يضبط الحدث stop.
2. يُمنح ‎/update الجاري مهلة قصيرة، ثم يُوقف المثبّت الخاص به (يُنظر الأوامر ← التحديث).
3. registry.save()‎.
4. يتوقف النفق، ثم خادم Mini App.
5. ‏session_monitor.stop()‎، وhook_receiver.stop()‎ (يغلق المقبس ويحذف ملفه).
6. ‏bot.stop()‎: يلغي الحركات ويوقف Application.
7. ‏registry.save()‎ مرة أخرى، لبطاقة لم يكتمل إرسالها بعد.

تعتمد إعادة التشغيل الذاتية من Telegram على اكتمال هذا المسار كله قبل أن يربط البديلُ المقبس. ما يظهر أثناء ذلك موصوف في أوامر البوت ← إعادة التشغيل.

أماكن الملفات والمقابس#

إلى جانب ذلك، ينشئ aipager مجلد جلسة جديدًا عند طلبه (مجلد جديد في ‎/new أو في Mini App)، وتكتب المثبّتات ونموذج الصوت ملفاتها الخاصة عند التحديث أو استخدام الرسائل الصوتية. كل ذلك داخل مجلدك الرئيسي، أو في ‎/tmp، أو بجانب مقبس التحكم. لا يرفع aipager صلاحياته أبدًا؛ يُنظر الأمان.

نسخة معزولة (للاختبار)#

عند ضبط AIPAGER_INSTANCE_DIR على مجلد مطلق مملوك لك، تنتقل إليه كل الملفات المشتركة المذكورة أعلاه: مقبس التحكم (ومقابس الرد وملفات إشارات حدود السرعة وعلامة تبديل النموذج التي بجانبه)، ومقابس claude-dtach-*‎، وملفات claude-policy-*‎ وclaude-notes-*‎ وclaude-status-*‎ وclaude-reply-*‎، وملف الحد الأدنى، ومجلد التنزيلات aipager-files، وسجل إعادة التشغيل الذاتية. الجلسات التي تبدؤها هذه النسخة ترث الإعداد، فلا تتحدث هوكاتها إلا مع تلك النسخة، وتحمي قواعد الأمان الملفات المنقولة بالطريقة نفسها. لا تقرأ هذه النسخة ملف ‎.env من نسخة الشيفرة.

الملفات الموجودة في مجلدك الرئيسي لا تنتقل، لذا يلزم توجيه HOME أيضًا إلى مجلد منفصل. يرفض aipager start العمل عندما يكون مجلد النسخة مضبوطًا وHOME هو مجلدك الرئيسي الحقيقي، أو عندما لا يكون المجلد مسارًا مطلقًا إلى مجلد مملوك لك، أو عندما يكون أطول من أن يصلح مسارًا لمقبس.

‏‎/update و‎/restart غير معزولين: يعملان على حزمة aipager المثبّتة وعلى الخدمة aipager.service، فلا ينبغي إرسالهما أبدًا إلى نسخة اختبار.

يرسل AIPAGER_TELEGRAM_API_BASE (مثلًا http://127.0.0.1:41234) كل طلب Bot API وكل تنزيل ملف إلى ذلك العنوان بدل https://api.telegram.org. يجب أن يكون هذا العنوان هو هذا الكمبيوتر (localhost أو عنوان loopback) ما لم يُضبط AIPAGER_TELEGRAM_API_ALLOW_REMOTE=1، حتى لا يرسل خطأ مطبعي توكن البوت إلى مكان آخر.

يوجد هذان الإعدادان كي تشغّل الاختبارات الشاملة aipager ثانيًا مقابل بديل محلي لـ Telegram بجانب aipager الحقيقي. ومن دونهما، كل مسار وعنوان هو المذكور في الجدول أعلاه.

لماذا dtach#

يعطي dtach كل جلسة Claude Code طرفية حقيقية (PTY) دون ربطها بطرفية يجب أن تبقى مفتوحة. يبدأ aipager الجلسة بـ dtach -n ويكتب فيها بـ dtach -p (الرسائل، وEscape، والمفاتيح التي تجيب عن مربع حوار)؛ ولا يقرأ الشاشة أبدًا، لأن الهوكات وسجل المحادثة يخبرانه بما يحدث. يمكنك الاتصال تفاعليًا من أي طرفية عبر aipager session <name>‎ للوصول المباشر. هذا الاتصال يتبع الجلسة عبر إعادة تشغيل من Telegram (‎/mode إلى الوصول الكامل أو منه، و‎/restart، وإعادة التشغيل): عندما يختفي مقبس الجلسة، ينتظر حتى ١٥ ثانية لعودة المقبس نفسه ثم يعيد الاتصال وحده. الجلسة التي انتهت فعلًا تعيدك إلى الطرفية بعد الانتظار (Ctrl-C ينهي الانتظار أسرع). يعمل الاتصال ومفتاح الفصل في dtach معطّل، فيذهب Ctrl-\‎ إلى Claude؛ وللخروج يكفي إغلاق الطرفية أو لوحة tmux، وتستمر الجلسة في العمل.

النتيجة: يعمل Claude Code كما لو كانت الكتابة في طرفية عادية، لكن تلك الطرفية يمكن أن تأتي وتذهب دون إزعاج الجلسة الجارية. يكتشف aipager الجلسات بفحص ‎/tmp/claude-dtach-*.sock في كل دورة مراقبة كل ثانيتين. الجلسة المكتشفة تخص الدردشة التي صُنع اسمها لها، أما الجلسة التي بدأت في الطرفية فتخص، في تثبيت فيه دردشة خاصة ومجموعة، الدردشة الخاصة للمالك.

صفحات ذات صلة#

• أحداث الهوك: ما يدخل عبر مقبس التحكم.
• أوامر البوت: ما يدخل من Telegram.
• نموذج الأمان: حدود الصلاحيات، والأسرار، والتدقيق.
• حل المشكلات: مرجع aipager doctor.