telegram

Telegram 消息工具

通过灵活的筛选和输出选项，获取、搜索、下载、发送和发布 Telegram 消息。

前提条件

必须在 ~/.telegram_dl/ 中配置身份验证。运行 setup 命令以检查状态或获取说明：

python3 scripts/telegram_fetch.py setup

如果尚未配置，请按以下步骤操作：

1. 从 https://my.telegram.org/auth 获取 API 凭据
2. 克隆 telegram_dl：https://github.com/glebis/telegram_dl
3. 运行 python telegram_dl.py 并按照交互式提示操作
4. 运行 python3 scripts/telegram_fetch.py setup 验证

快速开始

使用相应命令运行 scripts/telegram_fetch.py 脚本：

# List available chats
python3 scripts/telegram_fetch.py list

# Get recent messages
python3 scripts/telegram_fetch.py recent --limit 20

# Search messages
python3 scripts/telegram_fetch.py search "meeting"

# Get unread messages
python3 scripts/telegram_fetch.py unread

命令

列出聊天

查看可用的 Telegram 聊天：

python3 scripts/telegram_fetch.py list
python3 scripts/telegram_fetch.py list --limit 50
python3 scripts/telegram_fetch.py list --search "AI"
python3 scripts/telegram_fetch.py list --search "claude code глеб + саши" --exact

选项：

• --search "text"：按子字符串匹配筛选（不区分大小写）
• --exact：要求名称完全匹配，而非子字符串匹配（与 --search 配合使用）
• --limit N：最多获取的聊天数（默认值：30，如果未找到聊天，请增大此值）

重要： 如果要按确切名称查找特定聊天，但未找到，请将 --limit 增大到 100 或 200，因为该聊天可能不在最近 30 个聊天中。

返回包含聊天 ID、名称、类型和未读数的 JSON。

获取最近消息

获取最近的消息：

# From all chats (last 50 messages across top 10 chats)
python3 scripts/telegram_fetch.py recent

# From specific chat
python3 scripts/telegram_fetch.py recent --chat "Tool Building Ape"
python3 scripts/telegram_fetch.py recent --chat-id 123456789

# With limits
python3 scripts/telegram_fetch.py recent --limit 100
python3 scripts/telegram_fetch.py recent --days 7

搜索消息

搜索消息内容：

# Global search across all chats
python3 scripts/telegram_fetch.py search "project deadline"

# Search in specific chat
python3 scripts/telegram_fetch.py search "meeting" --chat-id 123456789

# Limit results
python3 scripts/telegram_fetch.py search "important" --limit 20

获取未读消息

仅获取未读消息：

python3 scripts/telegram_fetch.py unread
python3 scripts/telegram_fetch.py unread --chat-id 123456789

发送消息

向聊天发送消息：

# Send to existing chat by name
python3 scripts/telegram_fetch.py send --chat "John Doe" --text "Hello!"

# Send to username (works even without prior conversation)
python3 scripts/telegram_fetch.py send --chat "@username" --text "Hello!"

# Reply to a specific message (use message ID from recent/search output)
python3 scripts/telegram_fetch.py send --chat "Tool Building Ape" --text "Thanks!" --reply-to 12345

# Send to a forum topic (for groups with topics enabled)
python3 scripts/telegram_fetch.py send --chat "Group Name" --text "Hello topic!" --topic 12

# Send with markdown formatting (converts **bold**, _italic_, [links](url) to Telegram HTML)
python3 scripts/telegram_fetch.py send --chat "@username" --text "**Bold** and _italic_ text" --markdown

格式（--markdown 标志）：

• 不使用 --markdown：按原样发送文本（纯文本，不带格式）
• 使用 --markdown：将 Markdown 转换为 Telegram HTML（**bold** -> 粗体，_italic_ -> 斜体，[text](url) -> 链接，## Header -> 粗体，* item -> 箭头列表）
• 重要： 发送包含 Markdown 格式的草稿内容时，务必使用 --markdown
• publish 命令会自动处理 Markdown 转换；除非指定 --markdown，否则 send 命令不会处理

发送文件

发送图片、文档或视频：

# Send an image
python3 scripts/telegram_fetch.py send --chat "John Doe" --file "/path/to/image.jpg"

# Send document with caption
python3 scripts/telegram_fetch.py send --chat "@username" --file "report.pdf" --text "Here's the report"

# Reply with media
python3 scripts/telegram_fetch.py send --chat "Group" --file "screenshot.png" --reply-to 12345

聊天解析顺序：

1. @username - 直接解析 Telegram 用户名
2. 数字 ID - 按 Telegram ID 解析聊天
3. 名称匹配 - 在现有对话中进行模糊搜索

返回包含发送状态、解析出的聊天名称、消息 ID 和文件信息（媒体文件）的 JSON。

编辑消息

编辑已有消息：

# Edit a message by ID
python3 scripts/telegram_fetch.py edit --chat "@mentalhealthtech" --message-id 76 --text "Updated text"

# Edit in a group/channel
python3 scripts/telegram_fetch.py edit --chat "Mental health tech" --message-id 123 --text "Corrected content"

注意： 只能编辑自己发送的消息。Telegram 格式（粗体 等）会保留。

返回包含编辑状态和消息 ID 的 JSON。

下载附件

从聊天中下载媒体文件：

# Download last 5 attachments from a chat (default)
python3 scripts/telegram_fetch.py download --chat "Tool Building Ape"

# Download last 10 attachments
python3 scripts/telegram_fetch.py download --chat "Project Group" --limit 10

# Download to custom directory
python3 scripts/telegram_fetch.py download --chat "@username" --output "/path/to/folder"

# Download from specific message
python3 scripts/telegram_fetch.py download --chat "John Doe" --message-id 12345

默认输出： ~/Downloads/telegram_attachments/

返回包含下载结果（文件名、路径、大小）的 JSON。

获取论坛主题消息

获取特定论坛主题（群组中的话题）内的消息：

# Fetch from thread 174 in Claude Code Lab
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174

# Fetch with custom limit
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --limit 50

# Save to file
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 -o ~/thread.md

# Append to daily note
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --to-daily

# JSON output
python3 scripts/telegram_fetch.py thread --chat-id -1003237581133 --thread-id 174 --json

消息按最新优先排序（时间倒序）。

查找主题 ID 的方法：

• 论坛主题 ID 显示在主题 URL 中：https://t.me/c/CHAT_ID/THREAD_ID
• 在聊天中使用 recent 命令，查看主题中的消息 ID

返回包含指定主题所有消息的 Markdown 或 JSON。

将草稿发布到频道

要将 klodkot 频道中的草稿发布到 Telegram：

# Dry run (preview without sending)
python3 scripts/telegram_fetch.py publish --draft "Channels/klodkot/drafts/20260122-anthropic-consciousness-question.md" --dry-run

# Publish to channel
python3 scripts/telegram_fetch.py publish --draft "Channels/klodkot/drafts/20260122-anthropic-consciousness-question.md"

工作流：

1. 解析草稿的 frontmatter 和正文
2. 验证 channel 字段（必须为 "klodkot"）
3. 从 frontmatter 的 video: 字段和维基链接中提取媒体引用
4. 在 Channels/klodkot/attachments/ 或 Sources/ 中解析媒体路径
5. 移除草稿标题（例如，“# Title - Telegram Draft”）
6. 如果没有页脚，则添加：“КЛОДКОТ — Claude Code и другие агенты: инструменты, кейсы, вдохновение”
7. 发送到 @klodkot 频道（多项媒体作为相册发送）
8. 使用 published_date、telegram_message_id 更新 frontmatter
9. 将文件从 drafts/ 移至 published/
10. 在频道索引顶部添加新条目

媒体处理：

• Frontmatter：video: filename.mp4
• 维基链接：[[filename.mp4]]、[[image.png|alt text]]
• 多项媒体会作为 Telegram 相册发送

安全性：

• --dry-run 会显示预览，不会发送
• 发送前进行验证
• 发送失败时回滚（不移动文件）
• 发布后发生错误时发出警告（文件已发送，但移动文件或更新索引失败）

**返回：**包含发布状态、消息 ID 和警告（如有）的 JSON

输出选项

默认（Markdown 输出到 stdout）

默认情况下，输出格式化的 Markdown，适合 Claude 阅读和总结。

JSON 格式

添加 --json 标志以获取结构化数据：

python3 scripts/telegram_fetch.py recent --json

追加到 Obsidian 每日日志

将消息添加到知识库中今天的每日日志：

python3 scripts/telegram_fetch.py recent --to-daily
python3 scripts/telegram_fetch.py search "project" --to-daily

追加到 ~/Brains/brain/Daily/YYYYMMDD.md

追加到个人笔记

将消息添加到指定人物的笔记中：

python3 scripts/telegram_fetch.py recent --chat "John Doe" --to-person "John Doe"

创建或追加到 ~/Brains/brain/{PersonName}.md

保存到文件（节省令牌）

将消息直接保存到文件，不占用上下文令牌：

# Save 100 messages to markdown file
python3 scripts/telegram_fetch.py recent --chat "AGENCY: Community" --limit 100 -o ~/chat_archive.md

# Save with media files downloaded to same folder
python3 scripts/telegram_fetch.py recent --chat "Project Group" --limit 50 -o ~/project/archive.md --with-media

# Save search results to file
python3 scripts/telegram_fetch.py search "meeting" -o ~/meetings.md

返回包含保存状态（文件路径、消息数量、媒体下载结果）的 JSON——令牌用量极少。

用户请求示例

用户提出以下请求时：

• “显示我最近的 Telegram 消息” -> recent --limit 20
• “我今天收到了哪些 Telegram 消息？” -> recent --days 1
• “在 Telegram 中搜索有关该项目的消息” -> search "project"
• “获取来自 Tool Building Ape 的未读消息” -> unread + 筛选输出
• “将我的 Telegram 消息添加到每日日志” -> recent --to-daily
• “我在 Telegram 上有哪些聊天？” -> list
• “查找名称为 X 的确切聊天” -> list --search "X" --exact --limit 200
• “在 Telegram 上给 John 发送 hello” -> send --chat "John" --text "Hello!"
• “在 Telegram 上给 @username 发消息” -> send --chat "@username" --text "..."
• “回复那条消息并表示感谢” -> send --chat "..." --text "Thanks!" --reply-to <id>
• “把这张图片发给 John” -> send --chat "John" --file "/path/to/image.jpg"
• “发送 report.pdf 并附上说明” -> send --chat "..." --file "report.pdf" --text "Here's the report"
• “发送到 Group 中的主题 12” -> send --chat "Group" --text "..." --topic 12
• “下载来自 Tool Building Ape 的附件” -> download --chat "Tool Building Ape"
• “从 Project Group 下载最近的 10 个文件” -> download --chat "Project Group" --limit 10
• “将 AGENCY 的最近 100 条消息保存到文件” -> recent --chat "AGENCY: Community" --limit 100 -o ~/agency.md
• “将聊天及其媒体归档” -> recent --chat "Group" -o ~/archive.md --with-media
• “编辑那条消息” -> edit --chat "..." --message-id <id> --text "new text"
• “修正消息 123 中的拼写错误” -> edit --chat "..." --message-id 123 --text "corrected text"
• “Telegram 配置好了吗？” -> setup
• “如何设置 Telegram？” -> setup（如果尚未配置，则返回说明）
• “将这份草稿发布到 klodkot” -> publish --draft "Channels/klodkot/drafts/...md"
• “发布前预览这份草稿” -> publish --draft "..." --dry-run

速率限制

该脚本内置速率限制（消息间隔 0.1 秒），并会自动处理 Telegram 的 FloodWaitError，采用退避机制。

依赖项

需要安装以下 Python 包：

• telethon - Telegram API 客户端
• pyyaml - 用于解析草稿前置内容的 YAML

安装命令：pip install telethon pyyaml