mcpField
D
dump-channel

dump-channel

github.com/terrylica生产力164 次安装今天更新
代码仓库

关于 dump-channel

用于将 Telegram 频道、群组或聊天记录归档为 NDJSON，并可下载媒体文件，适合需要可查询消息记录和本地媒体的用户。

主要功能

  1. 01按时间顺序导出 NDJSON 消息
  2. 02下载照片、视频和文档
  3. 03使用参数跳过媒体下载
  4. 04通过跳过已有文件续传

适用场景

  1. 01归档频道以供后续分析
  2. 02查询消息文本和元数据
  3. 03继续中断的媒体下载

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/terrylica/cc-skills --skill dump-channel

安装后在 Claude Code 中输入/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

参数

参数类型说明
chatstring/int频道用户名（@name）或数字聊天 ID
outputpath输出目录（将在其中创建 messages.ndjson + media/）
--no-mediaflag跳过媒体下载，仅生成 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 对象：

字段类型说明
idintTelegram 消息 ID
datestringISO 8601 时间戳，包含时区
textstring/null完整消息文本（不截断）
has_mediabool消息是否包含媒体
media_typestring/nullGramJS 类名（MessageMediaPhoto 等）
media_filestring/nullmedia/ 目录中的文件名（例如 "6.jpg"）
viewsint/null查看次数（仅限频道）
forwardsint/null转发次数
reply_to_msg_idint/null回复所指向的父消息 ID
grouped_idint/null相册组 ID（同一相册中的消息共享此 ID）
edit_datestring/null最后编辑时间的 ISO 8601 时间戳
sender.idint发送者的 Telegram 用户／频道 ID
sender.namestring显示名称（频道标题或用户名字）
sender.usernamestring/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 会自动重新连接
  • 对于超大型频道（10k+ 条消息），下载媒体预计需要 10-15 分钟

推荐的存储方式

对于由 git 跟踪的项目，请将媒体文件夹添加到 gitignore：

# data/telegram/.gitignore
*/media/

这样可以将 NDJSON（元数据）保存在版本控制中，同时仅在本地保留较大的媒体文件。

反模式

  • 不要转储你未订阅的频道——GramJS 需要通过你的账户访问
  • 不要在同一 profile 上同时运行多个转储任务——会话文件会发生争用

执行后复盘

此技能执行完毕后，请在结束前检查：

  1. 命令是否成功？——如果没有，请修复导致失败的说明或错误表。
  2. 参数或输出是否发生变化？——如果 tg-cli.ts 的接口发生变化，请相应更新用法示例和参数表。
  3. 是否需要采用变通方案？——如果你不得不临时调整（使用不同的标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时再次遇到同样的问题。

仅在问题真实且可复现时进行更新，不要基于猜测更新。

评论

支持 Markdown