TgWitness / दस्तावेज़ीकरण

क्या परीक्षण किया गया है →

इस पृष्ठ के कुछ हिस्से अभी भी अंग्रेज़ी में हैं: अंग्रेज़ी मूल अनुवाद के बाद बदल दिया गया था।

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

Telegram · कमांड लाइन

खोजें, संदर्भ पढ़ें, गतिविधि गिनें और स्क्रिप्ट्स व एजेंट्स से सहेजे गए संदेशों को --json आउटपुट, स्थिर एग्जिट कोड्स और स्कोप्ड रीड-ओनली टोकन्स के साथ एक्सपोर्ट करें।

टीजीविटनेस / दस्तावेज़ीकरण

एकीकरण संग्रह

केवल-पठनीय MCP · पूर्ण-पाठ खोज · विकी

Preview. tgwitness search, context, messages, stats and export read saved observations for scripts and AI agents. They cannot send anything to Telegram, change settings or modify the signed journal. tgwitness index and tgwitness backup (below) work on a local data directory and need no token.

के साथ --json, stdout ठीक एक JSON दस्तावेज़ ले जाता है (export JSON Lines लिखता है)। प्रगति, संकेत और त्रुटियाँ stderr पर जाती हैं। एक्जिट कोड स्थिर हैं:

कोड अर्थ
0 सफलता, जिसमें एक खाली परिणाम शामिल है
1 विफलता: पहुँच से बाहर पैनल, अपठनीय डेटा, रुका हुआ निर्यात
2 उपयोग त्रुटि या अमान्य अनुरोध: गलत तारीख, अज्ञात विकल्प, खोज अनुक्रमणिका गलत
3 अभी अनुपलब्ध: कार्यक्षेत्र एक चल रहे पैनल में खुला है, या पैनल बाद में फिर से प्रयास करने के लिए कहता है (रेट लिमिट, टाइमआउट)
4 पहुँच अस्वीकार: टोकन अनुपस्थित, समाप्त या रद्द, उसके दायरे से बाहर की चैट, ऐसा टूल जिसे यह अनुमति नहीं देता

पढ़ने के दो तरीके#

पैनल के माध्यम से (--url)। यह कमांड उसी स्कोप्ड आर्काइव API का उपयोग करती है जैसे MCP। More tools → Integrations → 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 [--limit N] [--before SEQ] दोनों ओर दस मैसेज आईडी के भीतर सहेजे गए संदेश
tgwitness messages [--limit N] [--offset N] आप पढ़ सकते हैं चैट्स
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--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) अन्यत्र।

Ranked search stops at 1,000 results. The final page may be shorter than --limit. When more observations match, the last page says so (truncated: true with --json); narrow the query, chat or period.

प्रत्येक संदेश परिणाम में untrusted_content: true , वर्कस्पेस, चैट और संदेश आईडी, जर्नल अनुक्रम, सहेजा गया रिकॉर्ड हैश और एक पैनल लिंक होता है। संपादन, हटाने की सूचनाएं और missing_on_recheck अलग-अलग रिकॉर्ड हैं। stats में कवरेज उन अवधियों को दिखाता है जिनके लिए एक खोज परिणाम बोलता है।

गतिविधि सांख्यिकी#

stats एक चैट, एक प्रेषक, या दायरे में आने वाली हर चैट के लिए सहेजे गए अवलोकनों की गिनती:

  • संदेशों को UTC घंटे और सप्ताह के दिन (पहले सोमवार) के अनुसार, सबसे व्यस्त घंटे और दिन;
  • संपादित, हटाए गए और missing_on_recheck साझा;
  • संदेशों की संख्या वाले प्रेषक और पहला तथा अंतिम संदेश का समय;
  • सबसे बार-बार आने वाले डोमेन और @handles, इसके सहेजे गए संस्करणों में प्रत्येक संदेश में एक बार गिना गया;
  • कवरेज: coverage.gap रिकॉर्ड करता है और, पूरे वर्कस्पेस तक पहुंच के लिए, कनेक्टेड कलेक्टर हार्टबीट के बिना अवधियोंcollector_liveness).

यह अवधि टेलीग्राम द्वारा रिपोर्ट किए गए संदेश के समय को चुनती है। घंटे और सप्ताह के दिन की गिनती भेजने वाले के टाइम ज़ोन का अनुमान लगाने में मदद करती है। आँकड़े जर्नल से अनुरोध पर गणना किए जाते हैं और संग्रहीत नहीं किए जाते हैं। प्रत्येक परिणाम उस जर्नल हेड का नाम बताता है जिसे यह कवर करता है जब आपकी पहुँच कार्यक्षेत्र में फैली होती है। पैनल के माध्यम से पाँच सेकंड के बाद पढ़ना बंद हो जाता है, या स्थानीय रूप से --timeout सेकंड (डिफ़ॉल्ट 30); फिर complete false होता है और partial पहले ऐसे रिकॉर्ड का नाम बताता है जिसे नहीं पढ़ा गया था। उस स्थिति में केवल सबसे हालिया रिकॉर्ड ही गिने जाते हैं।

निर्यात#

export प्रत्येक सहेजे गए अवलोकन (नए संदेश, स्नैपशॉट, संपादन, पुनर्प्राप्त संदेश, हटाने की सूचनाएं, missing_on_recheck और सहेजे गए मीडिया रिकॉर्ड) जर्नल क्रम में लिखे जाते हैं। प्रत्येक पंक्ति में अन्य परिणामों की तरह ही फ़ील्ड होते हैं, जिसमें पूरा पाठ शामिल होता है। के साथ --output, फ़ाइल एक के तहत लिखी जाती है .partial नाम और नाम केवल पैनल के पूर्ण होने के रिकॉर्ड के बाद ही बदला जाता है; एक रुका हुआ एक्सपोर्ट कोई फ़ाइल नहीं छोड़ता है और कोड के साथ बाहर निकलता है 1. --output कभी भी मौजूदा फ़ाइल को ओवरराइट नहीं करता है। के साथ --output और --json, stdout एक सारांश ले जाता है: रिकॉर्ड की संख्या, अंतिम जर्नल अनुक्रम और, पूरे कार्यक्षेत्र तक पहुंच के लिए, जर्नल हेड।

पैनल के माध्यम से एक्सपोर्ट के लिए एक कनेक्शन की आवश्यकता होती है जो एक्सपोर्ट संदेशों की अनुमति देता है (केवल कमांड लाइन) ; यह डिफ़ॉल्ट रूप से चयनित नहीं होता है। यह फ़ाइल एक वर्किंग कॉपी है; एक सत्यापनीय हैंडओवर के लिए एक्सपोर्ट्स में साइन किए गए एक्सपोर्ट का उपयोग करें, जिसे python -m tgwitness.verify जांचता है।

पैनल प्रत्येक रिकॉर्ड, जिसमें पूर्णता रिकॉर्ड भी शामिल है, को उत्सर्जित करने से पहले एक्सेस की पुनः जाँच करता है। रद्द की गई या समाप्त हो चुकी एक्सेस एक अधूरा एक्सपोर्ट छोड़ देती है। लेज़ी पेज रीड्स अन्य क्वेरीज़ के साथ आर्काइव वर्कर सीमा साझा करते हैं और उनकी प्रतीक्षा सीमित होती है।

Index and backup#

These two commands read the data directory directly and take no token or --url.

कमांड परिणाम
tgwitness index status [--workspace ID] [--data-dir DIR] [--json] Search index state of one workspace or, by default, every workspace: mode, ready, building or not built, indexed and journal head sequence. Works while the panel runs
tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json] Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code 3 while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off
tgwitness backup FOLDER [--data-dir DIR] [--json] Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes backup-manifest.json with every file's SHA-256 and the journal heads

index accepts --workspace default or a workspace ID; the default is all. The backup skips temporary exports, SQLite sidecar files and lock files. The folder holds the Telegram session and signing keys, so keep it as private as the data directory. Backup, restore, and capacity describes restoring and what the next start records.

एजेंट कौशल#

.agents/skills/tgwitness-cli/SKILL.md एक एजेंट को बताता है कि इन कमांड्स का उपयोग कैसे करें, रिकॉर्ड का हवाला कैसे दें और कैप्चर किए गए टेक्स्ट को कैसे संभालें। एजेंट जो पढ़ते हैं .agents/skills इसे एक रिपॉजिटरी चेकआउट से लोड करें। Claude Code के लिए, कॉपी करें tgwitness-cli फ़ोल्डर में .claude/skills/ अपने प्रोजेक्ट मेंफ़ोल्डर को कॉपी करें या ~/.claude/skills/.

MCP और कमांड लाइन#

दोनों समान कनेक्शन, स्कोप जांच और सीमाओं का उपयोग करते हैं। MCP परिणाम एक 64 KiB पेज तक सीमित हैं, इसलिए MCP कोई थोक निर्यात प्रदान नहीं करता है; कमांड लाइन इसे स्ट्रीम करती है। get_activity_stats दोनों के लिए उपलब्ध है।