telegram-reader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telegram News Skill (Read-Only)

Telegram新闻技能（只读模式）

Reads Telegram channels and groups for financial news and market research using tdl, a Telegram CLI tool.

This skill is read-only. It is designed for financial research: reading channel messages, monitoring financial news channels, and exporting message history. It does NOT support sending messages, joining/leaving channels, or any write operations.

使用Telegram CLI工具tdl读取Telegram频道和群组，获取金融新闻与市场研究信息。

本技能为只读模式，专为金融研究设计：可读取频道消息、监控金融新闻频道、导出消息历史。不支持发送消息、加入/退出频道或任何写入操作。

Step 1: Ensure tdl Is Installed

步骤1：确保已安装tdl

Current environment status:

!`(command -v tdl && tdl version 2>&1 | head -3 || echo "TDL_NOT_INSTALLED") 2>/dev/null`

If the status above shows a version number, tdl is installed — skip to Step 2.

TDL_NOT_INSTALLED

, install tdl based on the user's platform:

Platform	Install Command
macOS / Linux	`curl -sSL https://docs.iyear.me/tdl/install.sh \| sudo bash`
macOS (Homebrew)	`brew install telegram-downloader`
Linux (Termux)	`pkg install tdl`
Linux (AUR)	`yay -S tdl`
Linux (Nix)	`nix-env -iA nixos.tdl`
Go (any platform)	`go install github.com/iyear/tdl@latest`

Ask the user which installation method they prefer. Default to Homebrew on macOS, curl script on Linux.

当前环境状态：

!`(command -v tdl && tdl version 2>&1 | head -3 || echo "TDL_NOT_INSTALLED") 2>/dev/null`

如果上方状态显示版本号，说明tdl已安装——直接跳至步骤2。

如果显示

TDL_NOT_INSTALLED

，请根据用户的平台安装tdl：

平台	安装命令
macOS / Linux	`curl -sSL https://docs.iyear.me/tdl/install.sh \| sudo bash`
macOS（Homebrew）	`brew install telegram-downloader`
Linux（Termux）	`pkg install tdl`
Linux（AUR）	`yay -S tdl`
Linux（Nix）	`nix-env -iA nixos.tdl`
Go（任意平台）	`go install github.com/iyear/tdl@latest`

询问用户偏好的安装方式。macOS默认推荐Homebrew，Linux默认推荐curl脚本。

Step 2: Ensure tdl Is Authenticated

步骤2：确保tdl已完成身份验证

Current auth status:

!`(tdl chat ls --limit 1 2>&1 >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED") 2>/dev/null`

AUTH_OK

, skip to Step 3.

AUTH_NEEDED

, guide the user through login. Login requires interactive input — the user must enter their phone number and verification code manually.

当前身份验证状态：

!`(tdl chat ls --limit 1 2>&1 >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED") 2>/dev/null`

如果显示

AUTH_OK

，跳至步骤3。

如果显示

AUTH_NEEDED

，引导用户完成登录。登录需要交互式输入——用户必须手动输入手机号和验证码。

Login methods

登录方式

Method A: QR Code (recommended — fastest)

bash

tdl login -T qr

A QR code will be displayed in the terminal. The user scans it with their Telegram mobile app (Settings > Devices > Link Desktop Device).

Method B: Phone + Code

bash

tdl login -T code

The user enters their phone number, then the verification code sent to their Telegram app.

Method C: Import from Telegram Desktop

If the user has Telegram Desktop installed and logged in:

bash

tdl login

This imports the session from the existing desktop client. The desktop client must be from the official website, NOT from the App Store or Microsoft Store.

方式A：二维码（推荐——最快）

bash

tdl login -T qr

终端会显示二维码，用户使用Telegram移动端应用扫描（设置 > 设备 > 链接桌面设备）即可。

方式B：手机号+验证码

bash

tdl login -T code

用户输入手机号，然后输入Telegram应用发送的验证码。

方式C：从Telegram Desktop导入会话

如果用户已安装并登录Telegram Desktop：

bash

tdl login

此命令会从已有的桌面客户端导入会话。请注意，桌面客户端必须是官方网站下载的版本，而非应用商店或微软商店的版本。

Namespaces

命名空间

By default, tdl uses a

default

namespace. To manage multiple accounts:

bash

tdl login -n work -T qr      # Login to "work" namespace
tdl chat ls -n work           # Use "work" namespace for commands

默认情况下，tdl使用

default

命名空间。如需管理多个账号：

bash

tdl login -n work -T qr      # 登录到“work”命名空间
tdl chat ls -n work           # 使用“work”命名空间执行命令

Important login notes

登录重要说明

Login is a one-time operation. The session persists on disk after successful login.
If login fails, ask the user to check their internet connection and try again.
Never ask for or handle Telegram passwords/2FA codes programmatically — always let the user enter them interactively.

登录为一次性操作，成功登录后会话会持久化存储在本地磁盘。
如果登录失败，请让用户检查网络连接后重试。
切勿以编程方式请求或处理Telegram密码/两步验证码——始终让用户手动输入。

Step 3: Identify What the User Needs

步骤3：明确用户需求

Match the user's request to one of the read operations below.

User Request	Command	Key Flags
List all chats/channels	`tdl chat ls`	`-o json` , `-f "FILTER"`
List only channels	`tdl chat ls -f "Type contains 'channel'"`	`-o json`
Export recent messages	`tdl chat export -c CHAT -T last -i N`	`--all` , `--with-content`
Export messages by time range	`tdl chat export -c CHAT -T time -i START,END`	`--all` , `--with-content`
Export messages by ID range	`tdl chat export -c CHAT -T id -i FROM,TO`	`--all` , `--with-content`
Export from a topic/thread	`tdl chat export -c CHAT --topic TOPIC_ID`	`--all` , `--with-content`
Search for a channel by name	`tdl chat ls -f "VisibleName contains 'NAME'"`	`-o json`

将用户请求与以下只读操作匹配。

用户请求	命令	关键参数
列出所有聊天/频道	`tdl chat ls`	`-o json` , `-f "FILTER"`
仅列出频道	`tdl chat ls -f "Type contains 'channel'"`	`-o json`
导出近期消息	`tdl chat export -c CHAT -T last -i N`	`--all` , `--with-content`
导出指定时间范围的消息	`tdl chat export -c CHAT -T time -i START,END`	`--all` , `--with-content`
导出指定ID范围的消息	`tdl chat export -c CHAT -T id -i FROM,TO`	`--all` , `--with-content`
导出主题/线程中的消息	`tdl chat export -c CHAT --topic TOPIC_ID`	`--all` , `--with-content`
按名称搜索频道	`tdl chat ls -f "VisibleName contains 'NAME'"`	`-o json`

Chat identifiers

聊天标识符

The

-c

flag accepts multiple formats:

Format	Example
Username (with @)	`-c @channel_name`
Username (without @)	`-c channel_name`
Numeric chat ID	`-c 123456789`
Public link	`-c https://t.me/channel_name`
Phone number	`-c "+1 123456789"`
Saved Messages	`-c ""` (empty)

-c

参数支持多种格式：

格式	示例
用户名（带@）	`-c @channel_name`
用户名（不带@）	`-c channel_name`
数字聊天ID	`-c 123456789`
公开链接	`-c https://t.me/channel_name`
手机号	`-c "+1 123456789"`
已保存消息	`-c ""` （空值）

Step 4: Execute the Command

步骤4：执行命令

Listing chats

列出聊天

bash

undefined

bash

undefined

List all chats

列出所有聊天

tdl chat ls

JSON output for processing

输出JSON格式以便处理

tdl chat ls -o json

Filter for channels only

仅筛选频道

tdl chat ls -f "Type contains 'channel'"

Search by name

按名称搜索

tdl chat ls -f "VisibleName contains 'Bloomberg'"

undefined

tdl chat ls -f "VisibleName contains 'Bloomberg'"

undefined

Exporting messages

导出消息

Always use

--all --with-content

to get text messages (not just media):

bash

undefined

导出用于读取的消息时，务必添加

--all --with-content

参数（否则仅导出媒体消息）：

bash

undefined

Last 20 messages from a channel

导出频道最近20条消息

tdl chat export -c @channel_name -T last -i 20 --all --with-content -o /tmp/tdl-export.json

Messages from a time range (Unix timestamps)

导出指定时间范围的消息（Unix时间戳）

tdl chat export -c @channel_name -T time -i 1710288000,1710374400 --all --with-content -o /tmp/tdl-export.json

Messages by ID range

导出指定ID范围的消息

tdl chat export -c @channel_name -T id -i 100,200 --all --with-content -o /tmp/tdl-export.json

undefined

tdl chat export -c @channel_name -T id -i 100,200 --all --with-content -o /tmp/tdl-export.json

undefined

Key rules

核心规则

Check auth first — run
```
tdl chat ls --limit 1
```
before other commands to verify the session is valid
Always use
--all --with-content
when exporting messages for reading — without these flags, tdl only exports media messages
Use
-o FILE
to save exports to a file, then read the JSON — this is more reliable than parsing stdout
Start with small exports — use
```
-T last -i 20
```
unless the user asks for more
Use filters on
chat ls
to help users find the right channel before exporting
NEVER execute write operations — this skill is read-only; do not send messages, join channels, or modify anything
Convert timestamps — when the user gives dates, convert to Unix timestamps for the
```
-T time
```
filter

先验证身份——执行其他命令前，先运行
```
tdl chat ls --limit 1
```
确认会话有效
导出消息必加
--all --with-content
——无此参数时，tdl仅导出媒体消息
使用
-o FILE
保存导出结果——将结果保存到文件后读取JSON，比解析标准输出更可靠
先小范围导出——除非用户明确要求，否则默认使用
```
-T last -i 20
```
列出聊天时使用筛选器——帮用户找到目标频道后再执行导出
禁止执行写入操作——本技能为只读模式，不得发送消息、加入频道或修改任何内容
转换时间戳——用户提供日期时，需转换为Unix时间戳用于
```
-T time
```
筛选

Working with exported JSON

处理导出的JSON文件

After exporting, read the JSON file and extract the relevant information:

bash

undefined

导出完成后，读取JSON文件并提取相关信息：

bash

undefined

Export messages

导出消息

tdl chat export -c @channel_name -T last -i 20 --all --with-content -o /tmp/tdl-export.json

Read and process the export

读取并处理导出结果

cat /tmp/tdl-export.json


The export JSON contains message objects with fields like `id`, `date`, `message` (text content), `from_id`, `views`, and media metadata.

---

cat /tmp/tdl-export.json


导出的JSON包含消息对象，字段包括`id`、`date`、`message`（文本内容）、`from_id`、`views`及媒体元数据。

---

Step 5: Present the Results

步骤5：呈现结果

After fetching data, present it clearly for financial research:

Summarize key messages — highlight the most relevant news or market updates
Include timestamps — show when each message was posted
Group by topic — if multiple channels, organize by theme (macro, earnings, crypto, etc.)
Flag actionable information — note breaking news, price targets, earnings surprises
Provide channel context — mention which channel/group each message came from
For channel lists, show channel name, member count, and type

获取数据后，以清晰的格式呈现，适配金融研究需求：

提炼关键消息——突出最相关的新闻或市场动态
包含时间戳——显示每条消息的发布时间
按主题分组——若涉及多个频道，按主题分类（宏观经济、财报、加密货币等）
标记 actionable 信息——标注突发新闻、目标价、财报超预期等内容
提供频道背景——注明每条消息来自哪个频道/群组
列出频道时——显示频道名称、成员数及类型

Step 6: Diagnostics

步骤6：故障排查

If something isn't working:

Error	Cause	Fix
`not authorized` or session errors	Not logged in or session expired	Run `tdl login -T qr` to re-authenticate
`FLOOD_WAIT_X`	Rate limited by Telegram	Wait X seconds, then retry
`CHANNEL_PRIVATE`	No access to channel	User must join the channel in their Telegram app first
`tdl: command not found`	tdl not installed	Install using Step 1

若出现问题，参考以下方案：

错误	原因	解决方法
`not authorized` 或会话错误	未登录或会话过期	运行 `tdl login -T qr` 重新验证身份
`FLOOD_WAIT_X`	Telegram限制请求频率	等待X秒后重试
`CHANNEL_PRIVATE`	无频道访问权限	用户需先在Telegram应用中加入该频道
`tdl: command not found`	未安装tdl	按照步骤1安装tdl

Reference Files

参考文档

```
references/commands.md
```
— Complete tdl command reference for reading channels and exporting messages

Read the reference file when you need exact command syntax or detailed flag documentation.

```
references/commands.md
```
——读取频道与导出消息的完整tdl命令参考

需要精确的命令语法或详细参数说明时，可查阅该参考文档。