TgWitness / التوثيق

ما تم اختباره ←

لا تزال أجزاء من هذه الصفحة باللغة الإنجليزية: فقد تغير النص الأصلي باللغة الإنجليزية بعد ترجمته.

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

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

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

TgWitness / التوثيق

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

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). يتم إرسال التقدم والتلميحات والأخطاء إلى stderr. رموز الخروج ثابتة:

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

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

من خلال اللوحة (--url). يستخدم الأمر نفس واجهة برمجة تطبيقات الأرشيف المحددة النطاق مثل 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 [--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 بترتيب السجل

التواريخ هي 2026-10-01 (منتصف الليل بتوقيت UTC) أو التوقيت الدولي (ISO) مع تحديد المنطقة الزمنية، 2026-10-01T09:00+03:00. بالنسبة search, messages و export يختارون وقت الملاحظة. تستوعب الصفحات ما يصل إلى 50 سجلاً: اتبع 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).

تحدد الفترة وقت الرسالة الذي أبلغت عنه Telegram. تساعد أعداد الساعات وأيام الأسبوع في تقدير المنطقة الزمنية للمرسل. تُحسب الأرقام بناءً على طلب من السجل ولا يتم تخزينها. يحدد كل نتيجة عنوان السجل الذي يغطيه عندما يمتد وصولك إلى مساحة العمل. تتوقف القراءة بعد خمس ثوانٍ عبر اللوحة، أو بعد --timeout ثانيةً محليًّا (الافتراضي 30)؛ عندها تكون قيمة complete كاذبةً وتُسمي partial السجل الأول الذي لم يُقرأ. في هذه الحالة، يتم حساب السجلات الأحدث فقط.

تصدير#

export تكتب كائن JSON واحد لكل ملاحظة محفوظة (الرسائل الجديدة، اللقطات، التعديلات، الرسائل المستردة، إشعارات الحذف، missing_on_recheck وسجلات الوسائط المحفوظة) بترتيب السجل. يحتوي كل سطر على نفس الحقول الموجودة في النتائج الأخرى، مع النص الكامل. وعند --output، يُكتب الملف تحت .partial اسم معين ولا يُعاد تسميته إلا بعد اكتمال سجل اللوحة؛ ولا يترك التصدير المتوقف أي ملف ويخرج برمز 1. --output لا يقوم أبدًا بالكتابة فوق ملف موجود. باستخدام --output و --json، يعرض stdout ملخصًا: عدد السجلات، وآخر تسلسل في السجل، وعنوان السجل (للوصول إلى مساحة العمل بأكملها).

يتطلب التصدير عبر اللوحة اتصالاً يسمح بـتصدير الرسائل (سطر الأوامر فقط) ؛ وهو غير محدد افتراضيًا. هذا الملف هو نسخة عمل؛ وللتسليم القابل للتحقق ، استخدم التصدير الموقّع في التصدير (Exports) ، والذي يتحقق منه الأمر 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 كيلوبايت، لذا لا يوفر MCP إمكانية التصدير بالجملة؛ حيث يقوم سطر الأوامر ببث البيانات. get_activity_stats متاح لكليهما.