संदर्भ / संग्रह और एकीकरण

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 का उपयोग करती है। इंटीग्रेशन्स → MCP में एक कनेक्शन बनाएँ: वर्कस्पेस और चैट, टूल्स और एक समाप्ति तिथि चुनें, फिर टोकन को एक बार कॉपी करें। कनेक्शन केवल-पठन (read-only) है, उन चैट तक सीमित है, प्रति मिनट 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 रिकॉर्ड तक रख सकते हैं: follow 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 प्रत्येक सहेजे गए अवलोकन (नए संदेश, स्नैपशॉट, संपादन, पुनर्प्राप्त संदेश, हटाने की सूचनाएं, 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 परिणाम एक 64 KiB पेज तक सीमित हैं, इसलिए MCP कोई थोक निर्यात प्रदान नहीं करता है; कमांड लाइन इसे स्ट्रीम करती है। get_activity_stats दोनों के लिए उपलब्ध है।