Niektóre fragmenty tej strony są nadal w języku angielskim: angielski tekst źródłowy uległ zmianie po przetłumaczeniu.
Odniesienie / Archiwum i integracje
Telegram · Wiersz poleceń
Wyszukiwanie, odczytywanie kontekstu, zliczanie aktywności oraz eksportowanie zapisanych wiadomości ze skryptów i agentów, z wyjściem w formacie --json, stabilnymi kodami zakończenia oraz tokenami o ograniczonym zakresie dostępu, przeznaczonymi wyłącznie do odczytu.
MCP tylko do odczytu · Wyszukiwanie pełnotekstowe · Wiki
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.
Przy --json, stdout przekazuje dokładnie jeden dokument JSON (export zapisuje wiersze JSON).
Postęp, podpowiedzi i błędy są kierowane do stderr. Kody wyjścia są stałe:
| Kod | Znaczenie |
|---|---|
0 |
Pomyślny wynik, w tym wynik pusty |
1 |
Błąd: niedostępny panel, nieczytelne dane, przerwany eksport |
2 |
Błąd użytkowania lub nieprawidłowe żądanie: nieprawidłowa data, nieznana opcja, indeks wyszukiwania wyłączony |
3 |
Obecnie niedostępne: obszar roboczy jest otwarty w uruchomionym panelu lub panel prosi o ponowną próbę później (limit częstotliwości, przekroczenie limitu czasu) |
4 |
Odmowa dostępu: brakujący, wygasły lub unieważniony token, czat poza zakresem działania narzędzia, narzędzie, które tego nie zezwala |
Dwa sposoby czytania#
Poprzez panel (--url). Polecenie wykorzystuje ten sam API archiwum o ograniczonym zakresie, co
MCP. Utwórz połączenie w sekcji Więcej narzędzi → Integracje → MCP: wybierz obszary robocze i czaty,
narzędzia oraz okres ważności, a następnie skopiuj token jednokrotnie. Połączenie ma charakter wyłącznie do odczytu, jest ograniczone
do tych czatów, ma limit 60 żądań na minutę i może zostać cofnięte lub
odnowione w dowolnym momencie. Tokeny logowania do panelu oraz dane uwierzytelniające z Telegrama nie działają w tym przypadku.
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
Panel zdalny wymaga protokołu HTTPS; zwykły protokół HTTP jest akceptowany wyłącznie w przypadku 127.0.0.1,
localhost oraz ::1. Zmienne środowiskowe proxy są ignorowane, a przekierowania są
odrzucane, dzięki czemu token dociera wyłącznie pod podany przez Ciebie adres.
Bezpośrednio z zatrzymanego obszaru roboczego (--data-dir). Odczytuje katalog danych z
pełnym dostępem lokalnym, bez tokenu. Należy używać tej opcji na kopii katalogu danych lub gdy
gromadzenie danych jest zatrzymane. Podpisane rekordy nigdy nie są modyfikowane; podobnie jak w przypadku panelu, otwarcie
obszaru roboczego może spowodować aktualizację indeksów pochodnych. Gdy panel ma otwarty obszar roboczy, polecenie kończy działanie z
kodem 3; należy zamiast tego odczytywać dane za pośrednictwem panelu. W przypadku braku --data-dir, TGWITNESS_DATA,
./data/live lub wykorzystywany jest katalog danych instalacji, w której uruchomiono polecenie.
--workspace ID wybiera obszar roboczy (domyślnie default). tgwitness messages
--workspaces wyświetla listę tych, do których masz dostęp.
Polecenia#
| Polecenie | Wynik |
|---|---|
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] |
Najlepsze wyniki na początku, uwzględniając formy słów, dokładne frazy w cudzysłowie, domeny oraz @username (składnia) |
tgwitness search QUERY --exact [--before SEQ] |
Dokładny tekst, najnowsze wpisy na początku, bez indeksu |
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] |
Zapisane wiadomości w zakresie dziesięciu identyfikatorów wiadomości po obu stronach |
tgwitness messages [--limit N] [--offset N] |
Czat, który można przeczytać |
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] |
Zapisane wiadomości z czatu, najnowsze na początku |
tgwitness messages CHAT_ID --message ID |
Każda zapisana wersja i zapis usunięcia jednej wiadomości |
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] |
Statystyki aktywności poniżej |
tgwitness export [--chat ID] [--since] [--until] [--output FILE] |
Zapisane obserwacje w formacie JSON Lines w kolejności zgodnej z dziennikiem |
Daty podaje się jako 2026-10-01 (północ czasu UTC) lub w formacie ISO z podaniem strefy czasowej
2026-10-01T09:00+03:00. W przypadku search, messages i export wybierają
czas obserwacji. Strony mieszczą do 50 rekordów: postępuj zgodnie z next_offset (--offset) w celu
wyszukiwania według rankingu oraz next_before (--before) w innych miejscach.
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.
Każdy wynik wiadomości zawiera untrusted_content: true
, identyfikatory obszaru roboczego, czatu i
wiadomości, sekwencję dziennika, skrót zapisanego rekordu oraz link do panelu. Edycje,
powiadomienia o usunięciu oraz missing_on_recheck
są oddzielnymi rekordami. Zakres w stats
pokazuje okresy, których dotyczą wyniki wyszukiwania.
Statystyki aktywności#
stats zlicza zapisane obserwacje dla jednej rozmowy, jednego nadawcy lub wszystkich rozmów objętych zakresem:
- wiadomości według godziny UTC i dnia tygodnia (z poniedziałkiem na początku), godziny i dni o największym natężeniu ruchu;
- edytowane, usunięte i
missing_on_recheckudostępnienia; - nadawców wraz z liczbą wiadomości oraz czasem wysłania pierwszej i ostatniej wiadomości;
- najczęściej występujące domeny oraz
@handles, zliczane raz na wiadomość we wszystkich jej zapisanych wersjach; - zakres:
coverage.gapzapisy oraz, w celu uzyskania dostępu do całego obszaru roboczego, okresy bez sygnału kontrolnego z podłączonego kolektora (collector_liveness).
Okres określa czas wiadomości zgłoszony przez Telegram. Liczba godzin i dni tygodnia
pomaga oszacować strefę czasową nadawcy. Dane liczbowe są obliczane na
żądanie z dziennika i nie są przechowywane. Każdy wynik określa nagłówek dziennika, który
obejmuje, gdy dostęp rozciąga się na obszar roboczy. Odczyt zatrzymuje się po pięciu sekundach w
panelu lub po upływie --timeout sekund lokalnie (domyślnie 30); wówczas complete ma wartość false, a
partial wskazuje pierwszy rekord, który nie został odczytany. W takim przypadku liczone są
tylko najnowsze rekordy.
Eksportuj#
export tworzy jeden obiekt JSON na każdą zapisaną obserwację (nowe wiadomości, zrzuty ekranu,
edycje, odzyskane wiadomości, powiadomienia o usunięciu, missing_on_recheck oraz zapisanych plików multimedialnych
) w kolejności z dziennika. Każdy wiersz zawiera te same pola co pozostałe wyniki, wraz z
pełnym tekstem. W przypadku --output, plik jest zapisywany pod .partial nazwą i
jest przemianowywany dopiero po zapisaniu zakończenia działania panelu; przerwany eksport nie pozostawia żadnego
pliku i kończy działanie z kodem 1. --output nigdy nie nadpisuje istniejącego pliku. Przy użyciu opcji
--output i --json, stdout zawiera podsumowanie: liczbę rekordów, ostatnią sekwencję dziennika
oraz, w przypadku dostępu do całego obszaru roboczego, nagłówek dziennika.
Eksport za pośrednictwem panelu wymaga połączenia umożliwiającego wysyłanie komunikatów Export
(tylko z wiersza poleceń)
; opcja ta nie jest domyślnie zaznaczona. Niniejszy plik jest kopią roboczą; w celu weryfikowalnego
przekazania należy skorzystać z podpisanego eksportu w sekcji Exports
, który sprawdza polecenie python -m tgwitness.verify
.
Panel ponownie sprawdza uprawnienia dostępu przed wysłaniem każdego rekordu, w tym rekordu zakończenia. Cofnięte lub wygasłe uprawnienia powodują niekompletny eksport. Odroczone odczyty stron dzielą limit procesów archiwizujących z innymi zapytaniami i mają ograniczony czas oczekiwania.
Index and backup#
These two commands read the data directory directly and take no token or --url.
| Polecenie | Wynik |
|---|---|
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.
Umiejętności agenta#
.agents/skills/tgwitness-cli/SKILL.md
informuje agenta, jak korzystać z tych poleceń, jak cytować zapisy oraz jak postępować z
przechwyconym tekstem. Agenci, którzy .agents/skills pobierają go z repozytorium
po wygenerowaniu kopii roboczej. W przypadku Claude Code należy skopiować tgwitness-cli folder do .claude/skills/ w
swoim projekcie lub ~/.claude/skills/.
MCP i wiersz poleceń#
Oba korzystają z tych samych połączeń, kontroli zakresu i ograniczeń. Wyniki MCP są ograniczone do
jednej strony o rozmiarze 64 KiB, więc MCP nie oferuje eksportu zbiorczego; wiersz poleceń przesyła dane strumieniowo.
get_activity_stats jest dostępna dla obu.