گزارش مشکل: چه چیزهایی در آن هست

وقتی aipager به یک باگ می‌خورد، می‌توانید با یک دکمه گزارش مشکل را برای سازندهٔ aipager بفرستید. قبل از اینکه چیزی فرستاده شود کل گزارش را می‌بینید، تا خودتان نگویید چیزی از کامپیوترتان بیرون نمی‌رود، و گزارش هیچ‌وقت چت‌ها، پیام‌ها، اسم‌ها، مسیرها یا توکن‌هایتان را ندارد. گزارش فقط از یک فهرست ثابت فیلد ساخته می‌شود: نسخه‌ها، تعدادها، تاریخ‌ها، جواب‌های بله/نه، گزینه‌هایی از فهرست‌های ثابت، جاهایی در کد خود aipager و اسم‌های ap1-‎ باگ‌هایش، و فقط اگر خودتان بنویسید، یک توضیح کوتاه.

چطور یک گزارش بفرستید#

از تلگرام فقط مالک این نصبِ aipager می‌تواند گزارش بفرستد: کسی که در چت خصوصی خود این نصب با ربات است (همان کسی که aipager را راه انداخته؛ اگر چند چت این‌طوری باشد و یک مالک مشخص نباشد، نه دکمهٔ «گزارش مشکل» هست و نه پیشنهاد خودکار، ولی aipager report در ترمینال باز هم کار می‌کند). Mini App صفحهٔ گزارش خودش را دارد؛ بقیهٔ راه‌ها در تلگرام همان کارت پیش‌نمایش را در چت خصوصی شما با ربات باز می‌کنند:

• ‏‎/help: وقتی مالک آن را می‌فرستد، متن راهنما یک دکمهٔ «🐞 گزارش مشکل» دارد. در گروه فقط زدن مالک کاری می‌کند و پیش‌نمایش در چت خصوصی مالک باز می‌شود، هیچ‌وقت در خود گروه.
• ‏Mini App: در تب تنظیمات، «گزارش مشکل» (وقتی اپ روی چت خصوصی شما باز است) یک صفحه داخل خود اپ باز می‌کند. توضیحتان بالای صفحه می‌آید (اختیاری، تا ۵۰۰ حرف، با شمارنده). زیرش خلاصهٔ کوتاهی از گزارش است: نسخه‌ها، تنظیمات، خطاها (روی هر خطا بزنید تا جاهایش در کد را ببینید) و جزئیات بیشتر. نمایش متن دقیق گزارش همان متنی را نشان می‌دهد که فرستاده می‌شود، با توضیح شما، و همراه تایپ شما عوض می‌شود. ارسال گزارش (دکمهٔ پایین خود تلگرام) دقیقاً همان را یک بار می‌فرستد و بعد صفحه کد پیگیری را با دکمهٔ کپی نشان می‌دهد. برگشتن چیزی نمی‌فرستد. اگر aipager توضیحتان را مرتب کند (فاصله‌های اول و آخر، حرف‌های نامرئی، هر چیزی بعد از ۵۰۰ حرف)، صفحه توضیح مرتب‌شده را نشان می‌دهد و تا دوباره «ارسال گزارش» را نزنید چیزی فرستاده نمی‌شود.
• اعلان سقف حافظه: وقتی حافظهٔ هوک aipager تمام می‌شود، اعلانی که در چت می‌آید دکمهٔ «🐞 گزارشش کن» دارد.
• پیشنهاد خودکار: گاهی aipager پیشنهاد می‌کند دربارهٔ باگی که دیده گزارشی بفرستد (aipager کی گزارش پیشنهاد می‌دهد را ببینید).
• در ترمینال: aipager report گزارش را چاپ می‌کند و می‌پرسد Send this report? [y/N]. همان نوع فیلدها را دارد، ولی اطلاعات کمتری از aipager در حال اجرا (مود، چت‌ها، قابلیت‌ها، مدت روشن بودن، سشن‌ها و جزئیات Claude Code نامعلوم یا خالی می‌مانند). aipager report --note "what you were doing"‎ یک توضیح اضافه می‌کند. بدون ترمینال (یک اسکریپت، یک pipe،‏ shell یک سشن 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)؛ از کجا (فهرست پکیج‌ها، یک پوشهٔ محلی، یک checkout از 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، نوع تونلش، ویس، پیش‌نمایش diff، خلاصه‌های غنی).
• ‏runtime:‏ aipager چه مدت روشن بوده، به‌شکل یک بازه (‎<10m،‏ ‎10m-1h،‏ ‎1-24h،‏ ‎1-7d،‏ ‎>7d)؛ چند سشن روشن و چندتا در حال کار است؛ aipager در ۷ روز گذشته چند بار ناگهان متوقف شده و دفعهٔ قبل چطور بسته شد (clean،‏ crash،‏ reboot).
• ‏doctor: نتیجهٔ (ok،‏ warn،‏ fail) یک فهرست ثابت از بررسی‌های سلامت، وقتی بدون اجرای دوبارهٔ بررسی‌ها در دسترس باشد (گزارش‌های ربات و ترمینال این را خالی می‌گذارند).
• ‏flood: وضعیت محدودیت سرعت تلگرام، جمع همهٔ چت‌ها: تعداد بن‌ها در ۷ روز گذشته، اینکه الان چتی ساکت شده، در مود حداقلی است یا سرعتش را کم کرده، و سهم شلوغ‌ترین چت از سهمیهٔ ساعتی‌اش به‌شکل یک بازه. بدون هیچ آیدی چتی.

چه چیزی خراب شد

• ‏counters_24h: هر کدام از یک فهرست ثابت از اتفاق‌ها در ۲۴ ساعت گذشته چند بار رخ داده (مثلاً ری‌استارت شدن نگهبان کارت در حال کار، یک دسته از خطاهای تلگرام، رسیدن هوک به سقف حافظه، یک خطای شبکه یا دیسک). فقط تعدادها.
• ‏log_digest_24h: برای ۱۵ جای پرکار در کد aipager که در ۲۴ ساعت گذشته هشدار یا خطا لاگ کرده‌اند، خود آن جا (aipager/state.py:1234)، سطح و تعداد دفعات. هیچ‌وقت متن لاگ.
• ‏errors: تا ۱۰ خطایی که aipager ثبت کرده، هر کدام با:
  • ‏fingerprint: یک اسم ap1-‎ برای باگ (هش نوع خطا و اسم حداکثر ۸ جا در کد aipager، هیچ‌وقت هش متن یا داده)؛
  • جایی که رخ داد (خود aipager، هوک، خط وضعیت، یک دستور، Mini App)، چطور گرفته شد، و اینکه باگ است یا فقط چیزی غیرعادی (tier)؛
  • برای خطایی که خود aipager لاگ کرده، اسم لاگر (یک ماژول aipager،‏ asyncio یا بخشی از telegram.ext)؛
  • اسم نوع exception (مثلاً builtins.KeyError، یا ‎<other>‎ برای نوعی از بیرون یک فهرست ثابت از پکیج‌ها)، نوع حداکثر سه علتش، و اسم یک شمارهٔ خطا مثل ENOSPC؛
  • برای خطای هوک، رویداد هوک و ابزار (ابزار داخلی با اسمش، هر ابزار MCP به‌شکل mcp)؛
  • چند بار، در چه روزهایی و در چه نسخه‌هایی از aipager رخ داد؛
  • حداکثر ۱۲ جا در کد خود aipager که از آن‌ها گذشت (فایل، خط، اسم تابع)، و حداکثر ۸ اسم از پکیج‌های بیرونی که از آن‌ها گذشت، از یک فهرست ثابت.

هیچ‌وقت در گزارش نیست: چت‌هایتان، پیام‌ها، جواب‌های Claude، اسم سشن‌ها، مسیر پوشه‌ها یا فایل‌ها، توکن‌ها یا کلیدها، آیدی چت یا کاربر، یوزرنیم‌ها، اسم کامپیوتر، متن هر پیام خطا، و خط‌های لاگ. فیلدهای بالا جایی برای آن‌ها ندارند و گزارش قبل از نشان داده شدن و قبل از ارسال با همین فهرست چک می‌شود.

کجا ارسال می‌شود#

گزارش بی‌نام به صندوق خصوصی خطاهای سازندهٔ aipager روی Sentry ارسال می‌شود: بدون حساب کاربری و بدون شناسهٔ نصب. مثل هر درخواست وب، از آدرس اینترنتی کامپیوترتان می‌آید که GitHub و Sentry می‌توانند ببینند؛ صندوق طوری تنظیم شده که آن را ذخیره نکند (گزینهٔ «Prevent Storing of IP Addresses» در Sentry). خود aipager آن را با یک درخواست HTTPS می‌فرستد (از کتابخانهٔ خود Sentry استفاده نمی‌کند، که خیلی بیشتر جمع می‌کند): گزارشی که دیدید به‌شکل پیوست report.json ارسال می‌شود، کنار یک خلاصهٔ کوتاه برای دسته‌بندی (نسخه، روش نصب و اینکه نصب توسعه‌دهنده است یا نه، سیستم‌عامل، نسخهٔ Python و Claude Code، اینکه گزارش چطور باز شد، و fingerprint، نوع و جاهای کد اولین خطا). درخواست فقط aipager/<version>‎ را به‌عنوان اسم خودش می‌گوید.

بعد از ارسال، کارت (یا ترمینال) یک کد پیگیری نشان می‌دهد: fingerprint ap1-‎ اولین خطا، یا برای گزارشی بدون خطا، شناسهٔ ۳۲ حرفی رویداد. اگر در GitHub یک issue هم باز کردید، کد پیگیری را بنویسید تا سازندهٔ aipager گزارشتان را پیدا کند. لاگ یا خروجی aipager doctor را در issue نگذارید: آیدی چت، مسیرهای پوشهٔ خانه و اول پیام‌هایتان در آن‌هاست.

درست قبل از ارسال، aipager فایل report-endpoint.json را از ریپوی aipager در GitHub می‌خواند تا بداند گزارش را کجا بفرستد (aipager در حال اجرا یک نسخهٔ سالم را یک روز نگه می‌دارد؛ خواندن ناموفق در ارسال بعدی دوباره امتحان می‌شود، و هر aipager report آن را از نو می‌خواند). این‌طوری سازندهٔ aipager می‌تواند کلید Sentry را عوض کند، گزارش‌ها را برای همه خاموش کند یا جلوی ارسال از نسخه‌های پایین‌تر از یک شماره را بگیرد (نسخه‌ای که نسخهٔ خودش را نمی‌داند پایین‌تر حساب می‌شود)، بدون اینکه نسخهٔ جدیدی منتشر کند. اگر GitHub در دسترس نباشد یا فایل چیزی نباشد که aipager بفهمد، aipager از کلیدی استفاده می‌کند که در خود این نسخه هست؛ فایل قابل خواندنی که بگوید خاموش، همیشه رعایت می‌شود.

محدودیت‌ها#

• حداکثر ۵ بار تلاش برای ارسال در روز (به وقت UTC) از یک کامپیوتر، دستی و خودکار با هم، و تلاش ناموفق هم حساب می‌شود. بعدی می‌گوید از هر کامپیوتر روزی حداکثر ۵ گزارش می‌شود فرستاد. فردا دوباره امتحان کنید.
• هیچ چیزی در پس‌زمینه دوباره امتحان نمی‌شود: اگر ارسال ناموفق باشد، کارت می‌گوید الان فرستاده نشد. چیزی از دست نرفته؛ بعداً دوباره امتحان کنید. و دکمهٔ ارسالش سر جایش می‌ماند.

aipager کی گزارش پیشنهاد می‌دهد#

‏aipager باگ‌های خودش را می‌بیند و گاهی در چت خصوصی شما پیشنهاد می‌کند گزارشی درباره‌شان بفرستد: aipager N بار به خطای داخلی خورد (TypeError در کارت در حال کار). با یک گزارش، این مشکل زودتر درست می‌شود. ... با دکمه‌های دیدن گزارش، فعلاً نه و دیگر نپرس. «دیدن گزارش» کارت پیش‌نمایش را فقط با همان خطاها باز می‌کند؛ تا آنجا «ارسال» را نزنید چیزی فرستاده نمی‌شود.

پیشنهاد فقط وقتی می‌آید که همهٔ این‌ها برقرار باشد:

• یک باگ واقعی در aipager باشد: خطایی در کد خود aipager که دست‌کم دو بار، با دست‌کم ۱۰ دقیقه فاصله، رخ داده باشد، یا وقتی aipager به‌شکل سرویس اجرا می‌شده و کرش کرده، همان لحظه (یک aipager start در ترمینال که بسته شود، مثلاً با بستن ترمینالش، فقط شمرده می‌شود). خطاهایی که هوک، خط وضعیت یا یک دستور به aipager خبر می‌دهند (از جمله تمام شدن حافظهٔ هوک) باید در دست‌کم یک روز هم رخ داده باشند، پس یک بار هیچ‌وقت باعث پیشنهاد نمی‌شود؛ دکمهٔ «گزارشش کن» در اعلان برای همین‌هاست. چیزهایی که تقصیر aipager نیست (محدودیت‌های تلگرام، شبکه، دیسک پر) هیچ‌وقت باعث پیشنهاد نمی‌شوند؛ فقط برای گزارشی که خودتان می‌فرستید شمرده می‌شوند.
• حداکثر هر ۳ روز یک پیشنهاد، با همهٔ موارد منتظر در همان یک پیشنهاد.
• نه در ۴۸ ساعت اولی که aipager روی این کامپیوتر روشن شده (آپدیت این را از نو شروع نمی‌کند)، و نه در یک ساعت اول بعد از ری‌استارت aipager.
• فقط وقتی ۲ دقیقه هیچ کاری در جریان نباشد و چیزی منتظر ارسال نباشد، و شما در ۳۰ دقیقهٔ گذشته از چت خصوصی‌تان با ربات استفاده کرده باشید. هیچ‌وقت در گروه، و هیچ‌وقت وقتی تلگرام آن چت را محدود کرده.
• هر باگ در هر نسخهٔ aipager یک بار پیشنهاد می‌شود. بعد از هر جوابی، در همان نسخه دوباره پیشنهاد نمی‌شود؛ بعد از آپدیت فقط اگر دوباره رخ دهد ممکن است برگردد.
• فعلاً نه و دیگر نپرس هر دو «نه» حساب می‌شوند، و پیشنهادی هم که تا یک روز جوابش را ندهید. دیدن گزارش شمارش را صفر می‌کند، حتی اگر بعد لغو کنید. دو «نه» پشت هم پیشنهادهای خودکار را خاموش می‌کند: اگر دومی با زدن دکمه باشد، یک خط این را می‌گوید؛ در هر حال ‎/settings نشانش می‌دهد.
• هیچ‌وقت برای نصب توسعه‌دهنده (aipager نصب‌شده از یک پوشهٔ محلی، یک checkout از 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 هم آنجاست).

این‌ها را هم ببینید#

• رفع مشکل: خطاهای رایج و راه‌حلشان.
• مدل امنیتی: aipager به چه چیزهایی دست می‌زند و چه چیزهایی از راه شبکه ارسال می‌شود.
• فرمان‌های ربات: ‎/help،‏ ‎/settings و دستورهای خط فرمان.