# Telegram · خط فرمان

Canonical page: https://phishdestroy.github.io/TgWitness/fa/docs/reference/cli/

جستجو، خواندن زمینه، شمارش فعالیت و صادر کردن پیام‌های ذخیره‌شده از اسکریپت‌ها و ایجنت‌ها، با خروجی --json، کدهای خروجی پایدار و توکن‌های محدودخوانی.

[Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.github.io/TgWitness/fa/llms.txt)

جستجو، خواندن زمینه، شمارش فعالیت و صادر کردن پیام‌های ذخیره‌شده از اسکریپت‌ها و ایجنت‌ها، با خروجی --json، کدهای خروجی پایدار و توکن‌های محدودخوانی.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [مستندسازی](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![یکپارچه‌سازی‌های آرشیو](https://phishdestroy.github.io/TgWitness/assets/chapter-integrations.svg)

[MCP فقط-خواندنی](https://phishdestroy.github.io/TgWitness/fa/docs/reference/mcp/) · [جستجوی متن کامل](https://phishdestroy.github.io/TgWitness/fa/docs/reference/search/) · [ویکی](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**پیش‌نمایش.** `tgwitness search`, `context`, `messages`, `stats` و `export` خواندن مشاهدات ذخیره شده برای اسکریپت‌ها و عامل‌های هوش مصنوعی. آنها نمی‌توانند هیچ چیزی را به تلگرام ارسال کنند، تنظیمات را تغییر دهند یا مجله امضا شده را اصلاح کنند.

با `--json`، stdout دقیقاً یک سند JSON را منتقل می‌کند (`export` خطوط JSON را می‌نویسد). پیشرفت، سرنخ‌ها و خطاها به stderr ارسال می‌شوند. کدهای خروجی پایدار هستند:

| کد | معنی |
| --- | --- |
| `0` | موفقیت، شامل یک نتیجهٔ خالی |
| `1` | خطا: پنل غیرقابل دسترسی، داده‌های غیرقابل خواندن، خروجی‌گیری قطع‌شده |
| `2` | خطای استفاده یا درخواست نامعتبر: تاریخ نامعتبر، گزینهٔ ناشناخته، نمایهٔ جستجو نامناسب |
| `3` | فعلاً در دسترس نیست: فضای کاری در یک پنل در حال اجرا باز است، یا پنل درخواست می‌کند بعداً دوباره تلاش کنید (محدودیت نرخ، اتمام زمان) |
| `4` | دسترسی رد شد: توکن مفقود، منقضی یا لغو شده، چتی خارج از محدودهٔ آن، ابزاری که اجازه نمی‌دهد |

## دو روش برای خواندن

**از طریق پنل (`--url`).** این فرمان از همان API آرشیو محدود (scoped archive API) که در MCP استفاده می‌شود بهره می‌برد. یک اتصال در **بخش** **Integrations → MCP** ایجاد کنید: فضاهای کاری و چت‌ها، ابزارها و یک تاریخ انقضا را انتخاب کرده و سپس توکن را یک‌بار کپی کنید. این اتصال فقط برای خواندن است، به همان چت‌ها محدود است، با نرخ ۶۰ درخواست در دقیقه محدود شده و می‌توان آن را در هر زمان لغو یا چرخاند. توکن‌های ورود به پنل و اطلاعات کاربری تلگرام در اینجا کار نمی‌کنند.

```
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` ([سینتکس](https://phishdestroy.github.io/TgWitness/fa/docs/reference/search/#search-syntax)) |
| `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` آنها زمان مشاهده را انتخاب می‌کنند. صفحات تا ۵۰ رکورد را در خود جای می‌دهند: دنبال کنید `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` ثانیه به‌صورت محلی (پیش‌فرض ۳۰)؛ سپس `complete` نابود و `partial` نام اولین رکوردی را که خوانده نشده است مشخص می‌کند. در این صورت فقط جدیدترین رکوردها شمرده می‌شوند.

### صادرات

`export` برای هر مشاهدهٔ ذخیره شده یک شی JSON می‌نویسد (پیام‌های جدید، اسنپ‌شات‌ها، ویرایش‌ها، پیام‌های بازیابی‌شده، اعلان‌های حذف، `missing_on_recheck` و رکوردهای رسانهٔ ذخیره شده) به ترتیب دفترچه خاطرات. هر خط دارای همان فیلدهای سایر نتایج است، به همراه متن کامل. با `--output`، فایل تحت یک `.partial` نام و نام‌گذاری مجدد تنها پس از ثبت رکورد تکمیل پنل انجام می‌شود؛ یک خروجی‌گیری ناتمام هیچ فایلی را باقی نمی‌گذارد و با کد `1`. `--output` هرگز یک فایل موجود را بازنویسی نمی‌کند. با `--output` و `--json`، خروجی استاندارد (stdout) یک خلاصه را در بر می‌گیرد: تعداد رکوردها، آخرین توالی ژورنال و، برای دسترسی به کل فضای کاری، سرژورنال.

صادرات از طریق پنل نیاز به ارتباطی دارد که امکان **«صادرات پیام‌ها» (فقط خط فرمان)** را فراهم کند؛ این گزینه به‌صورت پیش‌فرض انتخاب نشده است. این فایل یک نسخهٔ کاری است، نه مدرک: برای تحویل قابل تأیید، از صادرات امضا شده در **بخش** **«صادرات»** استفاده کنید، که `python -m tgwitness.verify`بررسی می‌کند.

پنل پیش از ارسال هر رکورد، از جمله رکورد تکمیل، دسترسی را مجدداً بررسی می‌کند. دسترسی لغو شده یا منقضی شده منجر به خروجی ناقص می‌شود. خوانش‌های تنبل صفحه، محدودیت کارگر بایگانی را با سایر پرس‌وجوها به اشتراک می‌گذارند و دارای زمان انتظار محدودی هستند.

## مهارت عامل

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) به یک عامل می‌گوید چگونه از این دستورات استفاده کند، چگونه به سوابق ارجاع دهد و چگونه با متن ضبط‌شده برخورد کند. عامل‌هایی که می‌خوانند `.agents/skills` آن را از یک چک‌اوت مخزن بارگذاری کنید. برای Claude Code، آن را کپی کنید `tgwitness-cli` پوشه `.claude/skills/` در پروژه خود کپی کنید یا `~/.claude/skills/`.

## MCP و خط فرمان

هر دو از اتصالات، بررسی‌های دامنه و محدودیت‌های یکسان استفاده می‌کنند. نتایج MCP به یک صفحه ۶۴ کیلوبایتی محدود است، بنابراین MCP هیچ‌گونه خروجی انبوهی ارائه نمی‌دهد؛ خط فرمان آن را استریم می‌کند. `get_activity_stats` برای هر دو در دسترس است.