TgWitness / Documentation

Ce qui a été testé →

Certaines parties de cette page sont encore en anglais : le texte original en anglais a été modifié après sa traduction.

Référence / Archives et intégrations

Telegram · Ligne de commande

Rechercher, lire le contexte, compter les activités et exporter les messages enregistrés à partir de scripts et d'agents, avec une sortie au format --json, des codes de sortie stables et des jetons en lecture seule à portée limitée.

TgWitness / Documentation

Intégrations d'archives

MCP en lecture seule · Recherche en texte intégral · 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.

Avec --json, la sortie standard (stdout) contient exactement un document JSON (export écrit des lignes JSON). La progression, les conseils et les erreurs sont envoyés vers stderr. Les codes de sortie sont stables :

Code Signification
0 Succès, y compris en cas de résultat vide
1 Échec : panneau inaccessible, données illisibles, exportation interrompue
2 Erreur d'utilisation ou requête non valide : date incorrecte, option inconnue, index de recherche désactivé
3 Indisponible pour le moment : l'espace de travail est ouvert dans un panneau en cours d'exécution, ou le panneau demande de réessayer plus tard (limite de débit, délai d'attente)
4 Accès refusé : jeton manquant, expiré ou révoqué, discussion hors de son champ d'application, outil non autorisé

Deux façons de lire#

Via le panneau (--url). La commande utilise la même API d’archivage à portée que MCP. Créez une connexion dans Plus d’outils → Intégrations → MCP : choisissez des espaces de travail et des discussions, des outils et une date d’expiration, puis copiez le jeton une seule fois. La connexion est en lecture seule, limitée à ces discussions, plafonnée à 60 requêtes par minute et peut être révoquée ou renouvelée à tout moment. Les jetons de connexion au panneau et les identifiants Telegram ne fonctionnent pas ici.

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

Un panneau distant nécessite le protocole HTTPS ; le protocole HTTP simple n'est accepté que pour 127.0.0.1, localhost et ::1. Les variables d’environnement de proxy sont ignorées et les redirections sont refusées, de sorte que le jeton n’atteigne que l’adresse que vous indiquez.

Directement à partir d’un espace de travail arrêté (--data-dir). Lit le répertoire de données avec un accès local complet, sans jeton. À utiliser sur une copie d’un répertoire de données ou lorsque la collecte est arrêtée. Les enregistrements signés ne sont jamais modifiés ; comme dans le panneau, l’ouverture d’un espace de travail peut mettre à jour ses index dérivés. Lorsque le panneau a l’espace de travail ouvert, la commande se termine avec le code 3; lisez plutôt via le panneau. En l’absence de --data-dir, TGWITNESS_DATA, ./data/live ou le répertoire de données de l’installation exécutant la commande est utilisé.

--workspace ID sélectionne un espace de travail (par défaut default). tgwitness messages --workspaces affiche la liste de ceux que vous pouvez consulter.

Commandes#

Commande Résultat
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] Résultats les plus pertinents en premier, avec les formes des mots, les expressions exactes entre guillemets, les domaines et @username (syntaxe)
tgwitness search QUERY --exact [--before SEQ] Texte exact, du plus récent au plus ancien, sans l'index
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] Messages enregistrés dans un intervalle de dix identifiants de message de part et d'autre
tgwitness messages [--limit N] [--offset N] Discussions que vous pouvez lire
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] Messages enregistrés de la conversation, les plus récents en premier
tgwitness messages CHAT_ID --message ID Chaque version enregistrée et chaque enregistrement de suppression d'un message
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] Statistiques d'activité, ci-dessous
tgwitness export [--chat ID] [--since] [--until] [--output FILE] Observations enregistrées sous forme de lignes JSON dans l'ordre du journal

Les dates sont exprimées en 2026-10-01 (minuit UTC) ou exprimées selon le format ISO avec un fuseau horaire, 2026-10-01T09:00+03:00. Pour search, messages et export ils sélectionnent l'heure de l'observation. Les pages peuvent contenir jusqu'à 50 enregistrements : suivez next_offset (--offset) pour la recherche par classement et next_before (--before) ailleurs.

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.

Chaque résultat de message comporte untrusted_content: true , les identifiants de l’espace de travail, de la discussion et du message, la séquence du journal, le hachage de l’enregistrement sauvegardé et un lien vers le panneau. Les modifications, les notifications de suppression et missing_on_recheck constituent des enregistrements distincts. La couverture dans stats indique les périodes couvertes par un résultat de recherche.

Statistiques d'activité#

stats Compte le nombre d'observations enregistrées pour une conversation, un expéditeur ou toutes les conversations concernées :

  • messages par heure UTC et par jour de la semaine (en commençant par le lundi), heures et jours les plus chargés ;
  • modifiés, supprimés et missing_on_recheck partages ;
  • les expéditeurs avec le nombre de messages ainsi que les heures du premier et du dernier message ;
  • les domaines les plus fréquents et @handles, comptés une fois par message parmi ses versions enregistrées ;
  • Couverture : coverage.gap enregistrements et, pour l'accès à l'ensemble de l'espace de travail, périodes sans signal de présence du collecteur connecté (collector_liveness).

La période sélectionne l’heure du message indiquée par Telegram. Le nombre d’heures et de jours de la semaine permet d’estimer le fuseau horaire de l’expéditeur. Les chiffres sont calculés sur demande à partir du journal et ne sont pas stockés. Chaque résultat indique l’en-tête du journal qu’il couvre lorsque votre accès s’étend sur l’espace de travail. La lecture s’arrête après cinq secondes via le panneau, ou après --timeout secondes en local (30 par défaut) ; alors complete est faux et partial désigne le premier enregistrement qui n’a pas été lu. Seuls les enregistrements les plus récents sont pris en compte dans ce cas.

Exporter#

export Il génère un objet JSON par observation enregistrée (nouveaux messages, captures d’écran, modifications, messages récupérés, notifications de suppression, missing_on_recheck et les enregistrements de médias sauvegardés) dans l’ordre du journal. Chaque ligne comporte les mêmes champs que les autres résultats, avec le texte intégral. Avec --output, le fichier est enregistré sous un .partial nom et n'est renommé qu'après l'enregistrement de la fin du panneau ; une exportation interrompue ne laisse aucun fichier et se termine avec le code 1. --output ne remplace jamais un fichier existant. Avec --output et --json, stdout affiche un résumé : nombre d’enregistrements, dernière séquence du journal et, pour l’accès à l’ensemble de l’espace de travail, l’en-tête du journal.

Une exportation via le panneau nécessite une connexion autorisant les messages d’exportation (ligne de commande uniquement) ; cette option n’est pas sélectionnée par défaut. Ce fichier est une copie de travail ; pour un transfert vérifiable, utilisez l’exportation signée dans la section Exportations , que la commande python -m tgwitness.verify vérifie.

Le panneau vérifie à nouveau les droits d'accès avant d'émettre chaque enregistrement, y compris l'enregistrement de fin . Un accès révoqué ou expiré entraîne une exportation incomplète. Les lectures de pages différées partagent la limite du processeur d'archivage avec d'autres requêtes et sont soumises à un délai d'attente limité.

Index and backup#

These two commands read the data directory directly and take no token or --url.

Commande Résultat
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.

Compétences de l'agent#

.agents/skills/tgwitness-cli/SKILL.md explique à un agent comment utiliser ces commandes, comment citer les enregistrements et comment traiter le texte capturé. Les agents qui lisent .agents/skills le chargent à partir d’un dépôt de code. Pour Claude Code, copiez le tgwitness-cli dossier dans .claude/skills/ dans votre projet ou ~/.claude/skills/.

MCP et la ligne de commande#

Les deux utilisent les mêmes connexions, les mêmes vérifications de portée et les mêmes limites. Les résultats de MCP sont limités à une page de 64 KiB ; MCP ne propose donc pas d’exportation en masse ; la ligne de commande les transmet en continu. get_activity_stats est disponible pour les deux.