مرجع / الأرشيف والتكاملات

Telegram · سطر الأوامر

البحث وقراءة السياق وحساب النشاط وتصدير الرسائل المحفوظة من البرامج النصية والوكلاء، مع إخراج بتنسيق --json ورموز خروج مستقرة ورموز مميزة مخصصة للقراءة فقط.

TgWitness / التوثيق

تكاملات الأرشيف

MCP للقراءة فقط · البحث عن النص الكامل · ويكي

معاينة. tgwitness search, context, messages, stats و export قراءة الملاحظات المحفوظة من أجل البرامج النصية وعوامل الذكاء الاصطناعي. ولا يمكنها إرسال أي شيء إلى Telegram، أو تغيير الإعدادات، أو تعديل السجل الموقّع.

مع --json، تنقل stdout مستند JSON واحدًا بالضبط (export تكتب أسطر JSON). يتم إرسال التقدم والتلميحات والأخطاء إلى stderr. رموز الخروج ثابتة:

الكود	المعنى
`0`	النجاح، بما في ذلك النتيجة الفارغة
`1`	الفشل: لوحة غير قابلة للوصول، بيانات غير قابلة للقراءة، توقف عملية التصدير
`2`	خطأ في الاستخدام أو طلب غير صالح: تاريخ غير صحيح، خيار غير معروف، فهرس البحث معطل
`3`	غير متاح حاليًا: مساحة العمل مفتوحة في لوحة قيد التشغيل، أو تطلب اللوحة إعادة المحاولة لاحقًا (حد السرعة، انتهاء المهلة)
`4`	رفض الوصول: رمز مميز مفقود أو منتهي الصلاحية أو تم إلغاؤه، أو محادثة خارج نطاقها، أو أداة لا تسمح بها

طريقتان للقراءة#

من خلال اللوحة (--url). يستخدم الأمر نفس واجهة برمجة التطبيقات (API) للأرشيف المحدود النطاق مثل MCP. قم بإنشاء اتصال في «التكاملات» → «MCP»: اختر مساحات العمل والدردشات، والأدوات وتاريخ انتهاء الصلاحية، ثم انسخ الرمز المميز مرة واحدة. الاتصال للقراءة فقط، ومقتصر على تلك الدردشات، ومحدد بمعدل 60 طلبًا في الدقيقة، ويمكن إلغاؤه أو تغييره في أي وقت. لا تعمل رموز تسجيل الدخول إلى اللوحة وبيانات اعتماد Telegram هنا.

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 بترتيب السجل

التواريخ هي 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).

تحدد الفترة وقت الرسالة الذي أبلغ عنه Telegram. يمكن أن تساعد أعداد الساعات وأيام الأسبوع في تقدير المنطقة الزمنية للمرسل؛ لكنها لا تحددها بشكل قاطع. يتم حساب الأرقام بناءً على طلب من السجل ولا يتم تخزينها. يحدد كل نتيجة عنوان السجل الذي يغطيه عندما يمتد وصولك إلى مساحة العمل. تتوقف القراءة بعد خمس ثوانٍ من خلال اللوحة، أو --timeout ثوانٍ محليًّا (الافتراضي 30)؛ ثم complete تكون القيمة «false» و 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 كيلوبايت، لذا لا يوفر MCP إمكانية التصدير بالجملة؛ حيث يقوم سطر الأوامر ببث البيانات. get_activity_stats متاح لكليهما.