TgWitness / ドキュメント

テスト済みの内容 →

このページの一部は依然として英語のままです。翻訳後に英語の原文が変更されたためです。

参考文献 / アーカイブと連携機能

Telegram · コマンドライン

スクリプトやエージェントからメッセージを検索、コンテキストの読み取り、アクティビティの集計、保存済みメッセージのエクスポートが可能で、--json 出力、安定した終了コード、スコープ付きの読み取り専用トークンをサポートしています。

TgWitness / ドキュメント

アーカイブとの連携

読み取り専用 MCP · 全文検索 · 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.

この場合 --json、stdoutにはJSONドキュメントが1つだけ出力されます(export JSON Lines形式で出力されます)。 進行状況、ヒント、エラーはstderrに出力されます。終了コードは安定しています:

コード 意味
0 成功(結果が空の場合も含む)
1 失敗:パネルにアクセスできない、データが読み取れない、エクスポートが中断された
2 使用上のエラーまたは無効なリクエスト:日付が不正、不明なオプション、検索インデックスがオフ
3 現在利用不可:ワークスペースが実行中のパネルで開かれているか、パネルから「後で再試行してください」というメッセージが表示されています(レート制限、タイムアウト)。
4 アクセス拒否:トークンの欠落、有効期限切れ、または失効、対象範囲外のチャット、許可されていないツール

読み方の2つの方法#

パネル経由(--url)。このコマンドは、 MCPと同じスコープ付きアーカイブAPIを使用します。「その他のツール」→「統合」→「MCP」で接続を作成します。ワークスペースとチャット、 ツール、有効期限を選択し、トークンを1回コピーしてください。この接続は読み取り専用で、 指定されたチャットに限定され、1分あたり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に限り、プレーンHTTPが受け入れられます。プロキシ環境変数は無視され、リダイレクトは 拒否されるため、トークンは指定したアドレスにのみ到達します。

停止中のワークスペースから直接実行(--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] 前後10件のメッセージID範囲内の保存済みメッセージ
tgwitness messages [--limit N] [--offset N] 閲覧可能なチャット
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] チャットの保存済みメッセージ(新しい順)
tgwitness messages CHAT_ID --message ID 1つのメッセージについて、保存されたすべてのバージョンおよび削除記録
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] 活動統計は以下の通りです。
tgwitness export [--chat ID] [--since] [--until] [--output FILE] 記録された観測データは、ジャーナルの順序に従って JSON Lines 形式で保存されます

日付は 2026-10-01 (UTC 0時)またはタイムゾーンを明記した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 、ワークスペース、チャットおよび メッセージID、ジャーナルのシーケンス、保存されたレコードのハッシュ、およびパネルリンクが含まれます。編集、 削除通知、およびmissing_on_recheck は個別のレコードとなります。stats のカバレッジは、検索結果が対象とする期間を示しています。

アクティビティ統計#

stats 対象範囲内の1つのチャット、1人の送信者、またはすべてのチャットについて、保存された観測データをカウントします:

  • UTC時間別および曜日別(月曜日を先頭)のメッセージ数、最も利用が集中する時間帯および曜日;
  • 編集、削除、および missing_on_recheck 共有;
  • 送信者、メッセージ数、および最初のメッセージと最後のメッセージの時刻;
  • 最も頻度の高いドメインおよび @handles、保存された各バージョンにおいて、メッセージごとに1回ずつカウントされた もの;
  • 対象範囲: coverage.gap 記録、およびワークスペース全体へのアクセスに関する、 コレクターのハートビートが接続されていない期間(collector_liveness).

期間には、Telegramが報告するメッセージの時刻が選択されます。 時間および曜日のカウントは、 送信者のタイムゾーンを推定するのに役立ちます。数値は ジャーナルからのリクエストに基づいて計算され、保存されることはありません。各結果は、 アクセスがワークスペースにまたがる場合、それが対象とするジャーナルの先頭を示します。パネル経由での読み取りは5秒後、 またはローカルで--timeout秒(デフォルトは30)経過すると停止します。その後、completeはfalseとなり、 partialには読み取られなかった最初のレコードが指定されます。その場合、 カウントされるのは最新のレコードのみです。

エクスポート#

export 保存された観測結果(新しいメッセージ、スナップショット、 編集、復元されたメッセージ、削除通知、 missing_on_recheck 保存されたメディア レコード)について、ジャーナルの順序に従って1つのJSONオブジェクトを書き出します。各行は他の結果と同じフィールドを持ち、 全文が含まれます。 --output、ファイルは .partial 名前で書き込まれ、 パネルの完了記録が記録された後にのみ名前が変更されます。エクスポートが中断された場合、 ファイルは残されず、コード 1. --output は、既存のファイルを上書きすることはありません。 --output および --jsonを指定した場合、標準出力には要約(レコード数、最後のジャーナル シーケンス、およびワークスペース全体へのアクセス時にはジャーナルの先頭)が表示されます。

パネル経由でのエクスポートには、「Export messages 」を許可する接続が必要です (コマンドラインのみ) 。これはデフォルトでは選択されていません。このファイルは作業用コピーです。検証可能な 引き渡しを行うには、「Exports」 にある署名付きエクスポートを使用してください。これは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 KiBのページ1つに制限されているため、MCPでは一括エクスポート機能は提供されていません。コマンドラインからストリーム出力されます。 get_activity_stats は両方で利用可能です。