منبع / آرشیو و یکپارچه‌سازی‌ها

Telegram · خط فرمان

جستجو، خواندن زمینه، شمارش فعالیت و صادر کردن پیام‌های ذخیره‌شده از اسکریپت‌ها و ایجنت‌ها، با خروجی --json، کدهای خروجی پایدار و توکن‌های محدودخوانی.

TgWitness / مستندسازی

یکپارچه‌سازی‌های آرشیو

MCP فقط-خواندنی · جستجوی متن کامل · ویکی

پیش‌نمایش. tgwitness search, context, messages, stats و export خواندن مشاهدات ذخیره شده برای اسکریپت‌ها و عامل‌های هوش مصنوعی. آنها نمی‌توانند هیچ چیزی را به تلگرام ارسال کنند، تنظیمات را تغییر دهند یا مجله امضا شده را اصلاح کنند.

با --json، stdout دقیقاً یک سند JSON را منتقل می‌کند (export خطوط JSON را می‌نویسد). پیشرفت، سرنخ‌ها و خطاها به stderr ارسال می‌شوند. کدهای خروجی پایدار هستند:

کد	معنی
`0`	موفقیت، شامل یک نتیجهٔ خالی
`1`	خطا: پنل غیرقابل دسترسی، داده‌های غیرقابل خواندن، خروجی‌گیری قطع‌شده
`2`	خطای استفاده یا درخواست نامعتبر: تاریخ نامعتبر، گزینهٔ ناشناخته، نمایهٔ جستجو نامناسب
`3`	فعلاً در دسترس نیست: فضای کاری در یک پنل در حال اجرا باز است، یا پنل درخواست می‌کند بعداً دوباره تلاش کنید (محدودیت نرخ، اتمام زمان)
`4`	دسترسی رد شد: توکن مفقود، منقضی یا لغو شده، چتی خارج از محدودهٔ آن، ابزاری که اجازه نمی‌دهد

دو روش برای خواندن#

از طریق پنل (--url). این فرمان از همان API آرشیو محدود (scoped archive API) که در MCP استفاده می‌شود بهره می‌برد. یک اتصال در بخش Integrations → MCP ایجاد کنید: فضاهای کاری و چت‌ها، ابزارها و یک تاریخ انقضا را انتخاب کرده و سپس توکن را یک‌بار کپی کنید. این اتصال فقط برای خواندن است، به همان چت‌ها محدود است، با نرخ ۶۰ درخواست در دقیقه محدود شده و می‌توان آن را در هر زمان لغو یا چرخاند. توکن‌های ورود به پنل و اطلاعات کاربری تلگرام در اینجا کار نمی‌کنند.

export TGWITNESS_URL=https://panel.example.org      # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_...              # or --token-file path
tgwitness search 'перевод карта' --json

یک پنل از راه دور به HTTPS نیاز دارد؛ HTTP ساده تنها برای 127.0.0.1, localhost و ::1متغیرهای محیطی پروکسی نادیده گرفته می‌شوند و هدایت‌ها (redirects) رد می‌شوند، بنابراین توکن فقط به آدرسی که شما وارد می‌کنید می‌رسد.

مستقیماً از یک فضای کاری متوقف‌شده (--data-dir). دایرکتوری داده را با دسترسی کامل محلی، بدون توکن می‌خواند. از آن روی یک کپی از دایرکتوری داده یا زمانی که جمع‌آوری متوقف است استفاده کنید. رکوردهای امضا‌شده هرگز تغییر نمی‌کنند؛ مانند پنل، باز کردن یک فضای کاری ممکن است شاخص‌های مشتق‌شده آن را به‌روزرسانی کند. هنگامی که پنل فضای کاری را باز دارد، فرمان با کد 3؛ در عوض از طریق پنل بخوانید. بدون --data-dir, TGWITNESS_DATA, ./data/live یا از دایرکتوری داده نصبه‌ای که دستور را اجرا می‌کند استفاده می‌شود.

--workspace ID یک فضای کاری را انتخاب می‌کند (پیش‌فرض default). tgwitness messages --workspaces فهرست فضاهای کاری را که می‌توانید آن‌ها را بخوانید، نمایش می‌دهد.

دستورالعمل‌ها#

فرمان	نتیجه
`tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]`	مطابقت‌های برتر ابتدا، همراه با اشکال واژه‌ها، عبارات دقیق در گیومه، دامنه‌ها و `@username` (سینتکس)
`tgwitness search QUERY --exact [--before SEQ]`	متن دقیق، جدیدترین‌ها اول، بدون نمایه
`tgwitness context CHAT_ID MESSAGE_ID`	پیام‌های ذخیره شده در ده شناسه پیام در هر دو طرف
`tgwitness messages`	گفت‌وگوهایی که می‌توانید بخوانید
`tgwitness messages CHAT_ID [--since] [--until] [--before SEQ]`	پیام‌های ذخیره‌شده‌ی چت، جدیدترین‌ها اول
`tgwitness messages CHAT_ID --message ID`	هر نسخهٔ ذخیره‌شده و هر رکورد حذف یک پیام
`tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]`	آمار فعالیت، در زیر
`tgwitness export [--chat ID] [--since] [--until] [--output FILE]`	مشاهدات ذخیره شده به صورت JSON Lines در ترتیب دفترچه یادداشت

تاریخ‌ها هستند 2026-10-01 (نیمه‌شب به وقت UTC) یا زمان‌های ISO با منطقه زمانی، 2026-10-01T09:00+03:00. برای search, messages و export آنها زمان مشاهده را انتخاب می‌کنند. صفحات تا ۵۰ رکورد را در خود جای می‌دهند: دنبال کنید next_offset (--offset) برای جستجوی رتبه‌بندی‌شده و next_before (--before) در جاهای دیگر.

جستجوی رتبه‌بندی‌شده در 1,000 نتیجه متوقف می‌شود. صفحهٔ نهایی ممکن است کوتاه‌تر از --limit باشد؛ در صورتی که مشاهدات تطابق‌دار بیشتری وجود داشته باشد، عبارت جستجو، گفتگوی یا دورهٔ زمانی را محدود کنید.

هر نتیجه پیام شامل untrusted_content: true، فضای کاری، چت و شناسه پیام‌ها، توالی دفترچه، هش رکورد ذخیره شده و یک لینک پنل. ویرایش‌ها، اعلان‌های حذف و missing_on_recheck سوابق جداگانه‌ای هستند. عدم وجود یک سابقه، اثبات نمی‌کند که یک رویداد هرگز رخ نداده است.

آمار فعالیت#

stats شمارش مشاهدات ذخیره‌شده برای یک چت، یک فرستنده، یا همه چت‌های در محدوده:

پیام‌ها بر اساس ساعت جهانی (UTC) و روز هفته (دوشنبه اول)، شلوغ‌ترین ساعت‌ها و روزها؛
ویرایش‌شده، حذف‌شده و missing_on_recheck اشتراک‌گذاری‌ها؛
فرستندگان با تعداد پیام‌ها و زمان‌های ارسال اولین و آخرین پیام؛
پربازدیدترین دامنه‌ها و @handles، که در هر پیام یک بار در نسخه‌های ذخیره‌شدهٔ آن شمرده شده است؛
پوشش: coverage.gap ثبت و، برای دسترسی به کل فضای کاری، دوره‌هایی بدون ضربان قلب جمع‌آوری‌کننده متصل (collector_liveness).

این دوره، زمان پیام گزارش‌شده توسط تلگرام را انتخاب می‌کند. شمارش ساعت و روز هفته می‌تواند به تخمین منطقه زمانی فرستنده کمک کند؛ اما آن را تعیین نمی‌کند. اعداد در صورت درخواست از دفترچه یادداشت محاسبه می‌شوند و ذخیره نمی‌شوند. هر نتیجه، سربرگ دفترچه یادداشتی را که در صورت گستردگی دسترسی شما در فضای کاری پوشش می‌دهد، نام می‌برد. خواندن از طریق پنل پس از پنج ثانیه متوقف می‌شود، یا --timeout ثانیه به‌صورت محلی (پیش‌فرض ۳۰)؛ سپس complete نابود و partial نام اولین رکوردی را که خوانده نشده است مشخص می‌کند. در این صورت فقط جدیدترین رکوردها شمرده می‌شوند.

صادرات#

export برای هر مشاهدهٔ ذخیره شده یک شی JSON می‌نویسد (پیام‌های جدید، اسنپ‌شات‌ها، ویرایش‌ها، پیام‌های بازیابی‌شده، اعلان‌های حذف، missing_on_recheck و رکوردهای رسانهٔ ذخیره شده) به ترتیب دفترچه خاطرات. هر خط دارای همان فیلدهای سایر نتایج است، به همراه متن کامل. با --output، فایل تحت یک .partial نام و نام‌گذاری مجدد تنها پس از ثبت رکورد تکمیل پنل انجام می‌شود؛ یک خروجی‌گیری ناتمام هیچ فایلی را باقی نمی‌گذارد و با کد 1. --output هرگز یک فایل موجود را بازنویسی نمی‌کند. با --output و --json، خروجی استاندارد (stdout) یک خلاصه را در بر می‌گیرد: تعداد رکوردها، آخرین توالی ژورنال و، برای دسترسی به کل فضای کاری، سرژورنال.

صادرات از طریق پنل نیاز به ارتباطی دارد که امکان «صادرات پیام‌ها» (فقط خط فرمان) را فراهم کند؛ این گزینه به‌صورت پیش‌فرض انتخاب نشده است. این فایل یک نسخهٔ کاری است، نه مدرک: برای تحویل قابل تأیید، از صادرات امضا شده در بخش «صادرات» استفاده کنید، که python -m tgwitness.verifyبررسی می‌کند.

پنل پیش از ارسال هر رکورد، از جمله رکورد تکمیل، دسترسی را مجدداً بررسی می‌کند. دسترسی لغو شده یا منقضی شده منجر به خروجی ناقص می‌شود. خوانش‌های تنبل صفحه، محدودیت کارگر بایگانی را با سایر پرس‌وجوها به اشتراک می‌گذارند و دارای زمان انتظار محدودی هستند.

مهارت عامل#

.agents/skills/tgwitness-cli/SKILL.md به یک عامل می‌گوید چگونه از این دستورات استفاده کند، چگونه به سوابق ارجاع دهد و چگونه با متن ضبط‌شده برخورد کند. عامل‌هایی که می‌خوانند .agents/skills آن را از یک چک‌اوت مخزن بارگذاری کنید. برای Claude Code، آن را کپی کنید tgwitness-cli پوشه .claude/skills/ در پروژه خود کپی کنید یا ~/.claude/skills/.

MCP و خط فرمان#

هر دو از اتصالات، بررسی‌های دامنه و محدودیت‌های یکسان استفاده می‌کنند. نتایج MCP به یک صفحه ۶۴ کیلوبایتی محدود است، بنابراین MCP هیچ‌گونه خروجی انبوهی ارائه نمی‌دهد؛ خط فرمان آن را استریم می‌کند. get_activity_stats برای هر دو در دسترس است.