حوالہ / آرکائیو اور انضمامات

Telegram · کمانڈ لائن

تلاش کریں، سیاق و سباق پڑھیں، سرگرمی کی گنتی کریں اور اسکرپٹس اور ایجنٹس سے محفوظ شدہ پیغامات برآمد کریں، --json آؤٹ پٹ، مستحکم ایگزٹ کوڈز اور محدود دائرہ کار کے ریڈ-اونلی ٹوکنز کے ساتھ۔

ٹی جی وٹنس / دستاویزات

آرکائیو انٹیگریشنز

صرف پڑھنے کے لیے MCP · مکمل متن تلاش · ویکی

پریویو۔ tgwitness search, context, messages, stats اور export پڑھیں محفوظ شدہ مشاہدات اسکرپٹس اور AI ایجنٹس کے لیے۔ وہ ٹیلیگرام پر کچھ بھی بھیج نہیں سکتے، سیٹنگز تبدیل نہیں کر سکتے یا دستخط شدہ جرنل میں ترمیم نہیں کر سکتے۔

کے ساتھ --json، stdout بالکل ایک JSON دستاویز منتقل کرتا ہے (export JSON Lines لکھتا ہے). پیش رفت، اشارے اور غلطیاں stderr پر جاتی ہیں۔ ایگزٹ کوڈز مستحکم ہیں:

کوڈ	معنی
`0`	کامیابی، بشمول خالی نتیجہ
`1`	ناکامی: ناقابلِ رسائی پینل، ناقابلِ مطالعہ ڈیٹا، منقطع برآمد
`2`	استعمال میں غلطی یا غیر درست درخواست: غلط تاریخ، نامعلوم آپشن، تلاش کا انڈیکس درست نہیں
`3`	فی الحال دستیاب نہیں: ورک اسپیس ایک چلتی ہوئی پینل میں کھلا ہوا ہے، یا پینل بعد میں دوبارہ کوشش کرنے کو کہتا ہے (ریٹ لمیٹ، ٹائم آؤٹ)
`4`	رسائی سے انکار: ٹوکن غائب، ختم شدہ یا منسوخ شدہ، اس کے دائرہ اختیار سے باہر ایک چیٹ، ایک ایسا ٹول جس کی اجازت نہیں ہے۔

پڑھنے کے دو طریقے#

پینل کے ذریعے (--url). یہ کمانڈ MCP کی طرح اسی اسکوپڈ آرکائیو API کا استعمال کرتی ہے۔ Integrations → MCP میں ایک کنکشن بنائیں: ورک اسپیسز اور چیٹس، ٹولز اور میعادِ ختم ہونے کا وقت منتخب کریں، پھر ٹوکن ایک بار کاپی کریں۔ یہ کنکشن صرف پڑھنے کے لیے ہے، مخصوص چیٹس تک محدود ہے، فی منٹ 60 درخواستوں کی شرح سے محدود ہے اور کسی بھی وقت منسوخ یا روٹ کی جا سکتی ہے۔ پینل لاگ ان ٹوکنز اور ٹیلیگرام کریڈینشلز یہاں کام نہیں کریں گے۔

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پراکسی ماحول کے متغیرات کو نظر انداز کیا جاتا ہے اور ری ڈائریکٹس کو مسترد کر دیا جاتا ہے، لہٰذا ٹوکن صرف آپ کے دیے گئے پتے تک پہنچتا ہے۔

براہِ راست ایک روکے ہوئے ورک اسپیس (--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 وہ مشاہدے کا وقت منتخب کرتے ہیں۔ صفحات میں زیادہ سے زیادہ 50 ریکارڈز ہوتے ہیں: فالو کریں 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 سیکنڈز مقامی طور پر (ڈیفالٹ 30)؛ پھر complete غلط ہے اور partial پہلے ریکارڈ کا نام بتاتا ہے جو پڑھا نہیں گیا تھا۔ اس صورت میں صرف تازہ ترین ریکارڈز ہی گنے جاتے ہیں۔

ایکسپورٹ#

export ہر محفوظ شدہ مشاہدے کے لیے ایک JSON آبجیکٹ لکھتا ہے (نئے پیغامات، اسنیپ شاٹس، ترمیمات، بازیافت شدہ پیغامات، حذف کرنے کے نوٹس، missing_on_recheck اور محفوظ شدہ میڈیا ریکارڈز) جرنل کی ترتیب میں۔ ہر لائن میں دیگر نتائج کی طرح وہی فیلڈز ہوتے ہیں، مکمل متن کے ساتھ۔ کے ساتھ --output، فائل ایک کے تحت لکھی جاتی ہے .partial نام اور دوبارہ نام صرف پینل کے مکمل ریکارڈ کے بعد لکھا جاتا ہے؛ ایک منقطع ایکسپورٹ کوئی فائل نہیں چھوڑتا اور کوڈ کے ساتھ نکل جاتا ہے 1. --output موجودہ فائل کو کبھی اووررائٹ نہیں کرتا۔ کے ساتھ --output اور --json کے ساتھ، stdout ایک خلاصہ دکھاتا ہے: ریکارڈز کی تعداد، آخری جرنل ترتیب اور پورے ورک اسپیس تک رسائی کے لیے، جرنل ہیڈ۔

پینل کے ذریعے ایکسپورٹ کے لیے ایک ایسے کنکشن کی ضرورت ہوتی ہے جو پیغامات کو ایکسپورٹ کرنے کی اجازت دیتا ہو (صرف کمانڈ لائن)؛ یہ بطورِ ڈیفالٹ منتخب نہیں ہوتا۔ یہ فائل ایک کام کرنے والی کاپی ہے، ثبوت نہیں: تصدیق شدہ حوالگی کے لیے Exports میں موجود دستخط شدہ ایکسپورٹ استعمال کریں، جو python -m tgwitness.verifyچیک کرتا ہے۔

پینل ہر ریکارڈ کو جاری کرنے سے پہلے رسائی کی دوبارہ جانچ کرتا ہے، بشمول تکمیل ریکارڈ کے۔ منسوخ شدہ یا میعاد ختم شدہ رسائی ایک نامکمل برآمد چھوڑ دیتی ہے۔ سست صفحہ خوانی دیگر استفسارات کے ساتھ آرکائیو ورکر کی حد شیئر کرتی ہے اور اس کا انتظار محدود ہوتا ہے۔

ایجنٹ کی مہارت#

.agents/skills/tgwitness-cli/SKILL.md ایجنٹ کو بتاتا ہے کہ ان کمانڈز کو کیسے استعمال کرنا ہے، ریکارڈز کا حوالہ کیسے دینا ہے اور حاصل کردہ متن کے ساتھ کیسے پیش آنا ہے۔ ایجنٹس جو پڑھتے ہیں .agents/skills اسے ریپوزیٹری چیک آؤٹ سے لوڈ کریں۔ Claude Code کے لیے، کاپی کریں tgwitness-cli فولڈر میں .claude/skills/ اپنے پروجیکٹ میں ~/.claude/skills/.

MCP اور کمانڈ لائن#

دونوں ایک ہی کنکشنز، اسکوپ چیکس اور حدود استعمال کرتے ہیں۔ MCP کے نتائج ایک 64 KiB صفحے تک محدود ہیں، لہٰذا MCP کسی بھی بلک ایکسپورٹ کی سہولت فراہم نہیں کرتا؛ کمانڈ لائن اسے اسٹریم کرتی ہے۔ get_activity_stats دونوں کے لیے دستیاب ہے۔