dump-channel

Telegram チャンネル履歴のダンプ

Telegram チャンネル／グループ／チャット全体を、NDJSON とダウンロードしたメディアファイルにアーカイブします。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変わった、または回避策が必要だった場合は、先送りせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合のみ更新してください。

事前確認

1. セッションが存在している必要があります：~/.local/share/gramjs/<profile>.session
   • 存在しない場合は、最初に /tlg:setup を実行してください
2. ユーザーは対象のチャンネル／チャットに登録済み、またはメンバーである必要があります

使用方法

/usr/bin/env bash << 'EOF'
ROOT="$(cc-plugin-root tlg)"
SCRIPT="$ROOT/scripts/tg-cli.ts"

# Full dump: NDJSON + all media (photos, videos, documents)
bun "$SCRIPT" dump @ChannelName ./output/ChannelName

# NDJSON only (skip media downloads — much faster)
bun "$SCRIPT" dump @ChannelName ./output/ChannelName --no-media

# Dump by numeric chat ID
bun "$SCRIPT" dump -1001234567890 ./output/MyChannel

# Use a different profile
bun "$SCRIPT" -p personal dump @ChannelName ./output/ChannelName
EOF

パラメーター

パラメーター	型	説明
chat	string/int	チャンネルのユーザー名（@name）または数値のチャット ID
output	path	出力ディレクトリ（内部に messages.ndjson と media/ を作成）
--no-media	flag	メディアのダウンロードをスキップし、NDJSON のみを生成します

出力構造

output/ChannelName/
├── messages.ndjson   ← one JSON object per line, chronological (oldest first)
└── media/
    ├── 6.jpg         ← named by message ID for cross-referencing
    ├── 12.png
    ├── 45.mp4
    └── ...

NDJSON レコードのスキーマ

各行は、次のフィールドを持つ JSON オブジェクトです。

フィールド	型	説明
id	int	Telegram メッセージ ID
date	string	タイムゾーン付き ISO 8601 タイムスタンプ
text	string/null	メッセージ全文（切り詰めなし）
has_media	bool	メッセージにメディアが含まれるかどうか
media_type	string/null	GramJS のクラス名（MessageMediaPhoto など）
media_file	string/null	media/ ディレクトリ内のファイル名（例："6.jpg"）
views	int/null	閲覧数（チャンネルのみ）
forwards	int/null	転送数
reply_to_msg_id	int/null	返信の場合、親メッセージの ID
grouped_id	int/null	アルバムのグループ ID（アルバム内のメッセージ間で共通）
edit_date	string/null	最終編集時の ISO 8601 タイムスタンプ
sender.id	int	送信者の Telegram ユーザー／チャンネル ID
sender.name	string	表示名（チャンネル名またはユーザーの名）
sender.username	string/null	設定されている場合は @username

再開のサポート

同じコマンドを再実行すると、ダウンロード済みのメディアファイルはスキップされます（dest.exists() を確認します）。NDJSON は実行のたびにすべて書き換えられます。これにより、中断されたダウンロードを安全に再開できます。

出力のクエリ

# jq: find all GOLD BUY signals with chart screenshots
jq 'select(.text != null and (.text | test("GOLD.*BUY")) and .media_file != null)' messages.ndjson

# DuckDB: aggregate by date
duckdb -c "SELECT date::DATE as day, count(*) FROM read_ndjson('messages.ndjson') GROUP BY day ORDER BY day"

# Python/Polars
import polars as pl
df = pl.read_ndjson("messages.ndjson")

パフォーマンスに関する注意

• メッセージ約 3000 件とメディアファイル 1700 件の処理には、約 3～5 分かかります
• ダウンロード中に Telegram が一時的に切断されることがあります（Server closed the connection）。GramJS が自動的に再接続します
• 非常に大規模なチャンネル（メッセージ 1 万件以上）では、メディアも含めて 10～15 分かかる見込みです

推奨されるストレージパターン

Git で追跡するプロジェクトでは、メディアフォルダーを gitignore に追加してください。

# data/telegram/.gitignore
*/media/

これにより、大容量のメディアファイルをローカルのみに保ちながら、NDJSON（メタデータ）をバージョン管理できます。

避けるべきパターン

• 登録していないチャンネルをダンプしないでください — GramJS がアクセスするには、アカウント経由の権限が必要です
• 同じプロファイルで複数のダンプを同時に実行しないでください — セッションファイルが競合します

実行後の振り返り

このスキルの実行後、終了する前に確認してください。

1. コマンドは成功しましたか？ — 失敗した場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — tg-cli.ts のインターフェースに変更があった場合は、使用例とパラメーター表を実際の仕様に合わせて更新してください。
3. 回避策が必要でしたか？ — 異なるフラグや追加手順など、その場で対応が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に再現可能な場合のみ更新してください。推測に基づく更新はしないでください。