التوثيقالتثبيت بواسطة وكيلالبنيةأحداث الهوكأوامر البوت وواجهتهوضع الفريق والمجموعاتنموذج الأمانحل المشكلاتتقارير المشكلات

تقارير المشكلات: ما يحتويه التقرير

عندما يصادف aipager خللًا، يمكنك إرسال تقرير مشكلة إلى مطوّر aipager بضغطة واحدة. يظهر لك التقرير كاملًا قبل إرسال أي شيء، ولا يغادر شيء كمبيوترك قبل موافقتك، ولا يحتوي التقرير أبدًا على دردشاتك أو رسائلك أو الأسماء أو المسارات أو التوكنات. يُبنى فقط من قائمة ثابتة من الحقول: الإصدارات، والأعداد، والتواريخ، وإجابات نعم/لا، واختيارات من قوائم ثابتة، ومواضع في شيفرة aipager نفسه، وأسماء أخطائه التي تبدأ بـ ap1-‎، ومعها ملاحظة قصيرة فقط إذا كتبتها.

المصدر على GitHub ↖هذه الصفحة مترجمة عن الإنجليزية؛ إذا اختلفت النسختان، فالنسخة الإنجليزية هي الصحيحة. الإنجليزية

عندما يصادف aipager خللًا، يمكنك إرسال تقرير مشكلة إلى مطوّر aipager بضغطة واحدة. يظهر لك التقرير كاملًا قبل إرسال أي شيء، ولا يغادر شيء كمبيوترك قبل موافقتك، ولا يحتوي التقرير أبدًا على دردشاتك أو رسائلك أو الأسماء أو المسارات أو التوكنات. يُبنى فقط من قائمة ثابتة من الحقول: الإصدارات، والأعداد، والتواريخ، وإجابات نعم/لا، واختيارات من قوائم ثابتة، ومواضع في شيفرة aipager نفسه، وأسماء أخطائه التي تبدأ بـ ap1-‎، ومعها ملاحظة قصيرة فقط إذا كتبتها.

طريقة الإرسال#

لا يرسل التقرير من Telegram إلا مالك تثبيت aipager: الشخص الموجود في الدردشة الخاصة بالتثبيت نفسه مع البوت (مالك البوت؛ وإذا كانت هناك عدة دردشات كهذه دون مالك واحد، فلا زر «الإبلاغ عن مشكلة» ولا عرض تلقائي، ويبقى aipager report في الطرفية متاحًا). لـ Mini App صفحة تقرير خاصة بها؛ وكل طريق آخر من Telegram يفتح بطاقة المعاينة نفسها في دردشتك الخاصة مع البوت:

  • ‏‎/help: عندما يرسله المالك، يأتي نص المساعدة مع زر «🐞 الإبلاغ عن مشكلة». في المجموعة لا أثر إلا لضغطة المالك، وتُفتح المعاينة في الدردشة الخاصة للمالك، لا في المجموعة أبدًا.
  • ‏Mini App: في تبويب الإعدادات، يفتح «الإبلاغ عن مشكلة» (عندما يكون التطبيق مفتوحًا على دردشتك الخاصة) صفحة داخل التطبيق. ملاحظتك في الأعلى (اختيارية، حتى ٥٠٠ حرف، مع عدّاد). تحتها ملخص قصير للتقرير: الإصدارات، والإعداد، والأخطاء (ضغطة على خطأ تعرض مواضعه في الشيفرة)، وتفاصيل أكثر. يعرض عرض نص التقرير كما هو النص الذي سيُرسل بالضبط، وملاحظتك معه، ويتغير مع الكتابة. يرسل إرسال التقرير (زر Telegram في الأسفل) ذلك النص بالضبط، مرة واحدة، ثم تعرض الصفحة رقم المرجع مع زر نسخ. الرجوع لا يرسل شيئًا. إذا رتّب aipager ملاحظتك (مسافات في الطرفين، حروف مخفية، ما يتجاوز ٥٠٠ حرف)، تعرض الصفحة الملاحظة بعد الترتيب ولا يُرسل شيء حتى الضغط على «إرسال التقرير» مرة أخرى.
  • إشعار حد الذاكرة: عندما تنفد ذاكرة هوك aipager، يحمل الإشعار في الدردشة زر «🐞 الإبلاغ عن هذا».
  • عرض تلقائي: نادرًا ما يعرض aipager إرسال تقرير عن خلل لاحظه (يُنظر متى يعرض aipager إرسال تقرير).
  • في الطرفية: يطبع aipager report تقريرًا ويسأل Send this report? [y/N]. يحتوي الأنواع نفسها من الحقول، لكن بمعلومات أقل عن aipager الجاري (الوضع، والدردشات، والميزات، ومدة التشغيل، والجلسات، وتفاصيل Claude Code تبقى غير معروفة أو فارغة). يضيف aipager report --note "what you were doing"‎ ملاحظة. ودون طرفية (سكربت، أو أنبوب، أو طرفية جلسة Claude Code) يطبع التقرير ولا يرسله أبدًا.

تعرض بطاقة المعاينة التقرير كما سيُرسل بالضبط: JSON في كتلة مطوية يمكن فتحها، أو، حين يكون أطول من رسالة واحدة، ملف report.json ردًا على البطاقة. أزرارها:

  • 📤 إرسال: يرسل ذلك التقرير بالضبط، مرة واحدة. ثم تعرض البطاقة تم الإرسال. رقم المرجع: ap1-....
  • ✏️ إضافة ملاحظة: رسالتك التالية في تلك الدردشة خلال ١٠ دقائق تصبح ملاحظة التقرير (تُقص عند ٥٠٠ حرف)، وتعرض البطاقة التقرير مرة أخرى مع الملاحظة قبل الإرسال. أي إجراء آخر بدلًا من ذلك (أمر، أو زر آخر، أو صورة، أو إجراء في Mini App) يغلق سؤال الملاحظة دون إضافة ملاحظة، وبعد ١٠ دقائق تذهب رسالتك التالية إلى Claude كالمعتاد. للسؤال زر ‹ رجوع، الذي يعود إلى المعاينة دون ملاحظة، وزر إلغاء.
  • ✖️ إلغاء: لا يُرسل شيء.

تبقى المعاينة مفتوحة ٢٤ ساعة، وتبقى أحدث ٥ مفتوحة (فتح السادسة يغلق الأقدم). بعد إعادة تشغيل aipager، لا يمكن إرسال بطاقة قديمة: يمكنك فتح «الإبلاغ عن مشكلة» مرة أخرى لبطاقة جديدة. والتقرير المفتوح في Mini App يمكن إرساله خلال ٢٤ ساعة (أحدث ٣)؛ وبعد إعادة التشغيل تحمّل الصفحة تقريرًا جديدًا.

ما يحتويه التقرير#

كل جزء، بكلمات بسيطة. كل قيمة تُطابَق مع قائمة القيم المسموح بها قبل عرض المعاينة ومرة أخرى قبل الإرسال؛ وأي قيمة لا تطابق تُستبدل بـ ‎<invalid>‎ أو تُحذف، ولا تُرسل كما هي أبدًا.

عن التقرير

  • ‏schema: صيغة التقرير (aipager-report/1).
  • ‏trigger:‏ manual (فتحته بنفسك) أو auto (عرض تلقائي).
  • ‏day: التاريخ، بتوقيت UTC (دون ساعة).
  • ‏note: فقط إذا أضفت ملاحظة: كلماتك، كما عرضتها المعاينة بالضبط (٥٠٠ حرف على الأكثر، دون حروف مخفية).

‏aipager والكمبيوتر

  • ‏aipager: الإصدار؛ وطريقة التثبيت (pipx أو uv أو brew أو pip أو editable أو nix أو snap أو docker أو system أو foreign أو unknown)؛ ومن أين (فهرس الحزم، أو مجلد محلي، أو نسخة git)؛ وهل يستطيع aipager update تحديثه.
  • ‏python: إصدار Python، وهل هو CPython أم PyPy.
  • ‏os: النظام (linux أو darwin أو windows أو freebsd)، ونوع المعالج، وتوزيعة Linux من قائمة ثابتة مع رقم إصدارها، وإصدار النواة major.minor، ونوع الحاوية إن وُجدت (docker أو lxc أو wsl أو podman)، وهل aipager مُعدّ كخدمة systemd أو launchd.
  • ‏deps: إصدارات المكتبات التي يعتمد عليها aipager (python-telegram-bot وhttpx وaiohttp وPyYAML وrich وquestionary وdtach-bin).
  • ‏claude_code: إصدار Claude Code، وكم تثبيتًا لـ Claude Code عُثر عليه، وطريقة تسجيل دخوله (env أو file أو keychain، أو سبب تعذر معرفة ذلك). لا بيانات تسجيل الدخول نفسها أبدًا.

إعدادك، كأعداد

  • ‏config: الوضع (personal أو team أو scope)؛ وكم دردشة خاصة وكم مجموعة مضبوطة؛ وكم دورًا مخصصًا موجودًا (دون أسمائها)؛ وأي الميزات مفعّلة (Mini App ونوع نفقها، والرسائل الصوتية، ومعاينة التغييرات، والملخصات الغنية).
  • ‏runtime: منذ متى يعمل aipager، كنطاق (‎<10m و‎10m-1h و‎1-24h و‎1-7d و‎>7d)؛ وكم جلسة جارية وكم منها تعمل؛ وكم مرة توقف aipager فجأة خلال آخر ٧ أيام وكيف انتهى آخر مرة (clean أو crash أو reboot).
  • ‏doctor: نتائج (ok أو warn أو fail) قائمة ثابتة من فحوص السلامة، حين تكون متاحة دون إعادة تشغيل الفحوص (التقارير من البوت ومن الطرفية تترك هذا فارغًا).
  • ‏flood: حالة حدود السرعة في Telegram مجمّعة على كل الدردشات: مرات الحظر خلال آخر ٧ أيام، وهل هناك دردشة موقوف الإرسال إليها، أو في الوضع الأدنى، أو يُبطَّأ الإرسال إليها الآن، وحصة أكثر الدردشات انشغالًا من ميزانيتها في الساعة كنطاق. دون أي معرّف دردشة.

ما الذي حدث خطأ

  • ‏counters_24h: كم مرة حدث كل شيء في قائمة ثابتة خلال آخر ٢٤ ساعة (مثل إعادة تشغيل مراقب بطاقة العمل، أو فئة خطأ من Telegram، أو بلوغ الهوك حد ذاكرته، أو خطأ في الشبكة أو القرص). الأعداد فقط.
  • ‏log_digest_24h: لأكثر ١٥ موضعًا في شيفرة aipager كتبت تحذيرًا أو خطأً في السجل خلال آخر ٢٤ ساعة: الموضع (aipager/state.py:1234)، والمستوى، وعدد المرات. لا نص السجل أبدًا.
  • ‏errors: حتى ١٠ أخطاء سجّلها aipager، لكل منها:
    • ‏fingerprint: اسم ap1-‎ للخلل (بصمة لنوع الخطأ ولأسماء ما يصل إلى ٨ مواضع في شيفرة aipager، لا لأي نص أو بيانات أبدًا)؛
    • أين حدث (aipager، أو الهوك، أو سطر الحالة، أو أمر، أو Mini App)، وكيف التُقط، وهل هو خلل أم مجرد أمر غير معتاد (tier)؛
    • لخطأ سجّله aipager، اسم المسجِّل (logger) (وحدة من aipager، أو asyncio، أو جزء من telegram.ext)؛
    • اسم نوع الاستثناء (مثل builtins.KeyError، أو ‎<other>‎ لاستثناء من خارج قائمة ثابتة من الحزم)، وأنواع ما يصل إلى ثلاثة أسباب، واسم رقم الخطأ مثل ENOSPC؛
    • لخطأ في الهوك، حدث الهوك والأداة (أداة مدمجة باسمها، وأي أداة MCP كـ mcp)؛
    • كم مرة، وفي أي أيام، وعلى أي إصدارات من aipager حدث؛
    • ما يصل إلى ١٢ موضعًا في شيفرة aipager نفسه مرّ بها (الملف، والسطر، واسم الدالة)، وما يصل إلى ٨ أسماء لحزم خارجية مرّ بها، من قائمة ثابتة.

لا يُضمَّن أبدًا: دردشاتك، ورسائلك، وإجابات Claude، وأسماء الجلسات، ومسارات المجلدات أو الملفات، والتوكنات أو المفاتيح، ومعرّفات الدردشات أو المستخدمين، وأسماء المستخدمين، واسم الكمبيوتر، ونص أي رسالة خطأ، وأسطر السجل. الحقول أعلاه لا مكان فيها لهذه الأشياء، ويُطابَق التقرير مع تلك القائمة قبل عرضه وقبل إرساله.

إلى أين يذهب#

يذهب التقرير إلى صندوق الأخطاء الخاص بمطوّر aipager على Sentry دون اسمك: لا حساب ولا معرّف تثبيت. وككل طلب ويب، يأتي من عنوان الإنترنت لكمبيوترك، الذي يراه GitHub وSentry؛ والصندوق مضبوط على عدم تخزينه (خيار Sentry «Prevent Storing of IP Addresses»). يرسله aipager بنفسه في طلب HTTPS واحد (لا يستخدم مكتبة Sentry نفسها، التي تجمع أكثر بكثير): التقرير الذي رأيته يُرسل كمرفق report.json، بجانب ملخص قصير للتجميع (الإصدار، وطريقة التثبيت وهل هو تثبيت للتطوير، والنظام، وإصدارا Python وClaude Code، وسبب الإرسال، وبصمة الخطأ الأول ونوعه ومواضعه في الشيفرة). لا يذكر الطلب إلا aipager/<version>‎.

بعد الإرسال، تعرض البطاقة (أو الطرفية) رقم مرجع: بصمة ap1-‎ للخطأ الأول، أو، لتقرير بلا خطأ، معرّف الحدث المكوّن من ٣٢ حرفًا. إذا فتحت أيضًا issue على GitHub، يمكنك ذكر رقم المرجع ليجد المطوّر تقريرك. يُرجى عدم لصق السجلات ولا مخرجات aipager doctor في issue: ففيها معرّف دردشتك، ومسارات مجلدك الرئيسي، وبدايات رسائلك.

قبل الإرسال مباشرة، يقرأ aipager الملف report-endpoint.json من مستودع aipager على GitHub ليعرف إلى أين يرسل (يحتفظ aipager الجاري بنسخة سليمة ليوم واحد؛ والقراءة الفاشلة تُعاد عند الإرسال التالي، وكل aipager report يقرؤه من جديد). يتيح هذا للمطوّر تغيير مفتاح Sentry، أو إيقاف التقارير للجميع، أو منع الإصدارات الأقدم من رقم معيّن من الإرسال (البناء الذي لا يعرف إصداره يُعدّ أقدم منه)، دون إصدار جديد. إذا تعذّر الوصول إلى GitHub، أو كان الملف بصيغة لا يفهمها aipager، يستخدم aipager المفتاح المدمج في هذا الإصدار؛ أما الملف المقروء الذي يقول «إيقاف» فيُطاع دائمًا.

الحدود#

  • ٥ محاولات إرسال يوميًا على الأكثر (بتوقيت UTC) من كمبيوتر واحد، يدويةً وتلقائيةً معًا، والمحاولة الفاشلة تُحسب أيضًا. المحاولة التالية تقول من كل كمبيوتر يمكن إرسال ٥ تقارير يوميًا على الأكثر. يمكنك المحاولة غدًا.
  • لا تُعاد أي محاولة في الخلفية: إذا فشل الإرسال، تقول البطاقة تعذّر الإرسال الآن. لم يضع شيء؛ يمكنك المحاولة لاحقًا. وتُبقي زر الإرسال.

متى يعرض aipager إرسال تقرير#

يلاحظ aipager أخطاءه بنفسه، ونادرًا ما يعرض إرسال تقرير عنها في دردشتك الخاصة: واجه aipager خطأً داخليًا N مرة (TypeError في بطاقة العمل). يساعد التقرير على إصلاح المشكلة أسرع. ... مع معاينة التقرير وليس الآن وعدم السؤال عن هذا مجددًا. يفتح «معاينة التقرير» بطاقة المعاينة مع تلك الأخطاء وحدها؛ ولا يُرسل شيء حتى الضغط على «إرسال» هناك.

لا يأتي العرض إلا إذا تحقق كل ما يلي:

  • هو خلل حقيقي في aipager: خطأ في شيفرة aipager نفسه حدث مرتين على الأقل، بفاصل ١٠ دقائق على الأقل، أو فورًا عندما تعطّل aipager أثناء عمله كخدمة (أما aipager start في الواجهة الذي يُنهى، مثلًا بإغلاق طرفيته، فيُعدّ فقط). الأخطاء التي يبلغ عنها الهوك أو برنامج سطر الحالة أو أمر ما (ومنها نفاد ذاكرة الهوك) يجب أيضًا أن تكون قد حدثت على مدى يوم على الأقل، فلا يسبب خطأ واحد عرضًا أبدًا؛ ولهذه الأخطاء زر «الإبلاغ عن هذا» في الإشعار. الأمور التي ليست خطأ aipager (حدود Telegram، والشبكة، والقرص الممتلئ) لا تسبب عرضًا أبدًا؛ تُعدّ فقط من أجل تقرير يُرسل يدويًا.
  • عرض واحد على الأكثر كل ٣ أيام، يجمع كل ما ينتظر في ذلك العرض.
  • ليس في أول ٤٨ ساعة بعد أول تشغيل لـ aipager على هذا الكمبيوتر (التحديثات لا تعيد هذا العد)، وليس في الساعة الأولى بعد إعادة تشغيل aipager.
  • فقط عندما لا يعمل شيء ولا ينتظر شيء الإرسال لمدة دقيقتين، وكنت قد استخدمت دردشتك الخاصة مع البوت خلال آخر ٣٠ دقيقة. أبدًا في مجموعة، وأبدًا أثناء تقييد Telegram لتلك الدردشة.
  • يُعرض كل خلل مرة واحدة لكل إصدار من aipager. بعد أي إجابة لا يُعرض مجددًا على ذلك الإصدار؛ ويمكن أن يعود بعد التحديث، فقط إذا حدث مرة أخرى.
  • ليس الآن وعدم السؤال عن هذا مجددًا يُعدّان كلاهما «لا»، وكذلك العرض الذي لا يُجاب عنه خلال يوم. معاينة التقرير تعيد العد إلى الصفر، حتى لو ألغيت بعدها. «لا» مرتين متتاليتين توقف العروض التلقائية: حين تكون الثانية ضغطة، يخبرك بذلك سطر؛ وفي كل الأحوال يظهر ذلك في ‎/settings.
  • أبدًا لتثبيت تطوير (aipager مثبّت من مجلد محلي، أو نسخة git، أو في وضع editable).

لإيقاف العروض التلقائية: ‎/settings في دردشتك الخاصة: الإبلاغ عن المشكلات: إيقاف. وحين يوقفها «لا» مرتين، تحتوي الصفحة نفسها على تفعيل العروض مجددًا. وملف reports.json موجود لكنه غير مقروء يوقف العروض التلقائية أيضًا (لم يعد aipager يعرف بماذا أجبت سابقًا)؛ وتفعيل العروض مجددًا يزيل ذلك أيضًا. على كمبيوتر لا دردشة فيه للسؤال، يُضبط AIPAGER_REPORT_PROMPTS=0 في بيئة aipager. يبقى «الإبلاغ عن مشكلة» وaipager report متاحين دائمًا، مهما كانت هذه الإعدادات.

ما يُحفظ على كمبيوترك#

  • ‏‎~/.local/state/aipager/reports.json: الأخطاء التي سجّلها aipager (بالشكل المذكور أعلاه: أسماء الأنواع، والإصدارات، ومواضع الشيفرة، ٥٠ على الأكثر)، وأعداد كل ساعة لمدة ٨ أيام، وملخص السجل لمدة يومين، وكيف انتهت آخر مرات التوقف، وحالة العروض (متى كان آخر عرض، وعدد مرات «لا» المتتالية، وأي الأخطاء عُرضت على أي إصدار). لا يقرؤه أحد غيرك.
  • ‏‎~/.local/state/aipager/report-sends.json: كم تقريرًا أُرسل أو جُرّب إرساله اليوم.
  • ‏‎~/.local/share/aipager/install.json: متى بدأ aipager أول مرة على هذا الكمبيوتر (من أجل الـ ٤٨ ساعة أعلاه).
  • ‏‎~/.local/share/aipager/running.json: يُكتب أثناء عمل aipager (رقم عمليته، ووقت بدئه، وهل يعمل كخدمة، ومعرّف هذا الإقلاع)، للتمييز بين التعطل والإيقاف العادي.

لا يحتوي أي منها على دردشة أو رسالة أو اسم أو مسار أو توكن. يحتفظ بها aipager uninstall، مع بقية بيانات aipager، ليكمل التثبيت الجديد من حيث توقف؛ ويعرض ما يحتفظ به ويطبع الأمر الذي يحذفه (يُنظر aipager uninstall). لحذف هذه وحدها، تُحذف تلك الملفات الأربعة: حذف المجلد ‎~/.local/state/aipager كله يحذف أول ملفين (ومعهما حالة اللغة، languages.json)، لكن install.json وrunning.json يجب حذفهما بالاسم (دون حذف ‎~/.local/share/aipager، الذي يحتوي أيضًا على مجلدات جلسات aipager).

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