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（项目地址：https://github.com/iyear/tdl）读取Telegram频道和群组中的金融新闻与市场研究内容。

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

Step 1: Ensure tdl Is Installed

步骤1：确保已安装tdl

Before running any command, check if tdl is installed:

bash

command -v tdl && tdl version || echo "TDL_NOT_INSTALLED"

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.

在运行任何命令之前，先检查是否已安装tdl：

bash

command -v tdl && tdl version || echo "TDL_NOT_INSTALLED"

如果输出

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已完成认证

Check if the user is logged in:

bash

tdl chat ls --limit 1 2>&1 && echo "AUTH_OK" || echo "AUTH_NEEDED"

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.

检查用户是否已登录：

bash

tdl chat ls --limit 1 2>&1 && echo "AUTH_OK" || echo "AUTH_NEEDED"

如果输出

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

此命令会从已有的桌面客户端导入会话。注意：桌面客户端必须是官网下载版本（https://desktop.telegram.org/），而非App Store或Microsoft Store中的版本。

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

参数——否则tdl仅导出媒体消息：

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
```
在
chat ls
命令中使用筛选器——帮助用户在导出前找到正确的频道
切勿执行写入操作——本技能为只读模式；禁止发送消息、加入频道或修改任何内容
转换时间戳——当用户提供日期时，需转换为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`（消息ID）、`date`（发送时间）、`message`（文本内容）、`from_id`（发送者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

获取数据后，为金融研究场景清晰展示结果：

总结关键消息——突出最相关的新闻或市场动态
包含时间戳——显示每条消息的发布时间
按主题分组——如果涉及多个频道，按主题分类（宏观经济、财报、加密货币等）
标记可操作信息——标注突发新闻、目标价、财报超预期等内容
提供频道上下文——注明每条消息来自哪个频道/群组
对于频道列表——展示频道名称、成员数量和类型

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的方法安装

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命令参考，涵盖频道读取和消息导出相关内容

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