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 архіву з обмеженою областю дії, що й 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 доступна для обох.