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

Что проверено →

Часть страницы пока на английском: английский оригинал изменился после перевода.

Справочник / Архив и интеграции

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

Поиск, чтение контекста, подсчёт активности и экспорт сохраненных сообщений из скриптов и агентов с выводом в формате --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 архива с ограниченной областью действия, что и 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 Lines в порядке записей в журнале

Даты указаны 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 принимает значение false, а 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 ограничены одной страницей размером 64 КиБ, поэтому MCP не предоставляет возможности массового экспорта; командная строка передаёт данные потоком. get_activity_stats доступна для обоих.