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). این دستور از همان API آرشیو محدود (scoped) استفاده می‌کند که MCP. در More tools → 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متغیرهای محیطی پروکسی نادیده گرفته می‌شوند و هدایت‌ها (redirects) رد می‌شوند، بنابراین توکن فقط به آدرسی که شما وارد می‌کنید می‌رسد.

مستقیماً از یک فضای کاری متوقف‌شده (--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 آنها زمان مشاهده را انتخاب می‌کنند. صفحات تا ۵۰ رکورد را در خود جای می‌دهند: دنبال کنید 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 نادرست است و partial اولین رکوردی را که خوانده نشده نام می‌برد. در این حالت فقط جدیدترین رکوردها شمارش می‌شوند.

صادرات#

export برای هر مشاهدهٔ ذخیره شده یک شی JSON می‌نویسد (پیام‌های جدید، اسنپ‌شات‌ها، ویرایش‌ها، پیام‌های بازیابی‌شده، اعلان‌های حذف، 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 به یک صفحه ۶۴ کیلوبایتی محدود است، بنابراین MCP هیچ‌گونه خروجی انبوهی ارائه نمی‌دهد؛ خط فرمان آن را استریم می‌کند. get_activity_stats برای هر دو در دسترس است.