CLI для Telegram: поиск по архиву и экспорт JSONL

TgWitness / Документация

MCP только для чтения · Полнотекстовый поиск · Вики

Предварительный просмотр. tgwitness search, context, messages, stats а также export читать сохраненные наблюдения для скриптов и ИИ-агентов. Они не могут отправлять что-либо в Telegram, изменять настройки или модифицировать подписанный журнал.

При этом --json, stdout выводит ровно один документ JSON (export записывает строки JSON). Информация о ходе выполнения, подсказки и ошибки выводятся в stderr. Коды завершения являются стабильными:

Два способа чтения#

Через панель (--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 выводит список тех, которые вы можете читать.

Команды#

Даты указаны 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 выводится сводка: количество записей, последняя последовательность журнала и, при доступе ко всему рабочему пространству, начало журнала.

Для экспорта через панель требуется подключение, поддерживающее экспорт сообщений (только из командной строки); по умолчанию эта опция не выбрана. Данный файл является рабочей копией, а не доказательством: для проверяемой передачи данных используйте подписанный экспорт в разделе «Экспорт», который 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 доступна для обоих.