Back to Details

telegram-readonly

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Telegram Readonly

Telegram Readonly

Use the local skill script for Telegram reads from the user's personal account.
This skill exists because Telegram Bot API is the wrong tool for reading a real personal account. Use MTProto via Telethon instead.
使用本地 skill 脚本从用户个人账户读取 Telegram 内容。
开发这个 skill 的原因是 Telegram Bot API 并不适合读取真实个人账户的内容，我们改为通过 Telethon 使用 MTProto。

Quick rules

快速规则

  • Use this skill only for reads.
  • Do not improvise write actions.
  • Do not add send/edit/delete logic to the wrapper unless the user explicitly asks.
  • Treat the Telethon session like a high-privilege secret.
  • Assume unread preservation is best-effort until tested on a real chat.
  • 仅将该 skill 用于读取操作。
  • 不得随意新增写入操作。
  • 除非用户明确要求，否则不得在封装层添加发送/编辑/删除逻辑。
  • 将 Telethon 会话视为高权限机密信息。
  • 在真实聊天中测试完成前，默认未读状态保留功能为尽力而为模式。

Local setup

本地设置

Prefer the skill-local script and a skill-local virtual environment over any global CLI install. Prefer saved Telegram config over shell-exported environment variables once setup is complete. Treat 
.venv
as generated local state, not part of the skill itself. If the installer drops skill-local dotfiles, the bootstrap script recreates 
.gitignore
automatically.
Bootstrap the local environment:
bash
<skill-path>/scripts/bootstrap_venv.sh
After bootstrap, use:
bash
<skill-path>/scripts/telegram-readonly
If 
.venv
is missing later, just run the bootstrap script again.
Primary config path:
bash
~/.config/telegram-readonly/config.json
Recommended one-time setup:
  1. Make sure 
    api_id
    and 
    api_hash
    are available.
  2. Run:
bash
<skill-path>/scripts/telegram-readonly auth
After successful login, the config file stores 
api_id
, 
api_hash
, and the Telegram session string so future reads do not need exported shell variables.
优先使用 skill 本地脚本和 skill 本地虚拟环境，而非任何全局 CLI 安装。 设置完成后，优先使用保存的 Telegram 配置，而非 shell 导出的环境变量。 将 
.venv
视为生成的本地状态，不属于 skill 本身的一部分。 如果安装程序生成了 skill 本地的点文件，引导脚本会自动重新创建 
.gitignore
。
引导本地环境：
bash
<skill-path>/scripts/bootstrap_venv.sh
引导完成后，使用以下命令：
bash
<skill-path>/scripts/telegram-readonly
如果后续 
.venv
丢失，重新运行引导脚本即可。
主配置路径：
bash
~/.config/telegram-readonly/config.json
推荐的一次性设置流程：
  1. 确保已获取 
    api_id
    和 
    api_hash
    。
  2. 运行：
bash
<skill-path>/scripts/telegram-readonly auth
登录成功后，配置文件会存储 
api_id
、
api_hash
和 Telegram 会话字符串，后续读取操作无需再导出 shell 变量。

Commands

命令说明

Show built-in help

查看内置帮助

bash
<skill-path>/scripts/telegram-readonly help
bash
<skill-path>/scripts/telegram-readonly help

Authenticate once

单次身份验证

bash
export TELEGRAM_API_ID='12345678'
export TELEGRAM_API_HASH='your_api_hash'
<skill-path>/scripts/telegram-readonly auth
bash
export TELEGRAM_API_ID='12345678'
export TELEGRAM_API_HASH='your_api_hash'
<skill-path>/scripts/telegram-readonly auth

List chats

列出聊天

dialogs --query
does token-based matching across 
name
, 
username
, and 
title
, so queries like 
petros skynet
work even when the exact full string is not present as one substring.
bash
<skill-path>/scripts/telegram-readonly dialogs --limit 50
dialogs --query
会对 
name
、
username
和 
title
进行基于分词的匹配，因此即使查询词 
petros skynet
不是完整的连续子字符串也能匹配到对应结果。
bash
<skill-path>/scripts/telegram-readonly dialogs --limit 50

Read recent messages

读取近期消息

bash
<skill-path>/scripts/telegram-readonly messages --chat '@username' --limit 50 --reverse
bash
<skill-path>/scripts/telegram-readonly messages --chat '@username' --limit 50 --reverse

Search messages

搜索消息

bash
<skill-path>/scripts/telegram-readonly search 'invoice' --limit 50
Restrict search to one chat:
bash
<skill-path>/scripts/telegram-readonly search 'deadline' --chat '@username' --limit 50
bash
<skill-path>/scripts/telegram-readonly search 'invoice' --limit 50
限制搜索范围为单个聊天：
bash
<skill-path>/scripts/telegram-readonly search 'deadline' --chat '@username' --limit 50

List recent unread chats

列出近期未读聊天

Default behavior is opinionated: exclude muted and archived chats.
bash
<skill-path>/scripts/telegram-readonly unread-dialogs --limit 10
Include muted and/or archived when needed:
bash
<skill-path>/scripts/telegram-readonly unread-dialogs --limit 10 --include-muted --include-archived
默认逻辑经过设计：会排除静音和归档的聊天。
bash
<skill-path>/scripts/telegram-readonly unread-dialogs --limit 10
如有需要可包含静音和/或归档聊天：
bash
<skill-path>/scripts/telegram-readonly unread-dialogs --limit 10 --include-muted --include-archived

List recent unread DMs only

仅列出近期未读私信

bash
<skill-path>/scripts/telegram-readonly unread-dms --limit 10
bash
<skill-path>/scripts/telegram-readonly unread-dms --limit 10

Workflow

工作流程

  1. Read 
    references/setup-and-safety.md
    if setup, auth, or unread-state behavior matters.
  2. Ensure the skill-local virtual environment is bootstrapped.
  3. Ensure Telegram API credentials exist.
  4. Run 
    auth
    once to create the session and write 
    ~/.config/telegram-readonly/config.json
    .
  5. Use 
    dialogs
    , 
    messages
    , 
    search
    , 
    unread-dialogs
    , or 
    unread-dms
    as needed.
  6. Keep usage narrow and intentional.
  1. 如果关注设置、身份验证或未读状态行为相关的细节，请先阅读 
    references/setup-and-safety.md
    。
  2. 确保 skill 本地虚拟环境已完成引导。
  3. 确保已持有 Telegram API 凭证。
  4. 运行一次 
    auth
    命令创建会话并写入 
    ~/.config/telegram-readonly/config.json
    。
  5. 根据需求使用 
    dialogs
    、
    messages
    、
    search
    、
    unread-dialogs
    或 
    unread-dms
    命令。
  6. 保持使用场景窄而明确。

Expected outputs

预期输出

The wrapper returns JSON. Parse it instead of relying on fragile text scraping.
Dialog objects include:
  • is_user
  • is_group
  • is_channel
  • is_bot
  • archived
  • muted
  • unread counters
封装层返回 JSON 格式内容，请直接解析 JSON，不要依赖脆弱的文本爬取逻辑。
对话对象包含以下字段：
  • is_user
  • is_group
  • is_channel
  • is_bot
  • archived
  • muted
  • 未读计数

Files

文件说明

  • Package repo: 
    https://github.com/ropl-btc/telegram-readonly-cli
  • Launcher: 
    scripts/telegram-readonly
  • Python implementation: 
    scripts/telegram_readonly.py
  • Local bootstrap: 
    scripts/bootstrap_venv.sh
  • Setup notes: 
    references/setup-and-safety.md
  • Config storage: 
    ~/.config/telegram-readonly/config.json
  • .env
    is optional fallback only; it is not the preferred long-term setup.
  • .venv/
    is generated local state and can be recreated with 
    scripts/bootstrap_venv.sh
    .
  • 代码仓库：
    https://github.com/ropl-btc/telegram-readonly-cli
  • 启动器：
    scripts/telegram-readonly
  • Python 实现：
    scripts/telegram_readonly.py
  • 本地引导脚本：
    scripts/bootstrap_venv.sh
  • 设置说明：
    references/setup-and-safety.md
  • 配置存储路径：
    ~/.config/telegram-readonly/config.json
  • .env
    仅作为可选降级方案，不是推荐的长期设置方式。
  • .venv/
    是生成的本地状态，可通过 
    scripts/bootstrap_venv.sh
    重新生成。

When to stop and ask

需要停止并询问的场景

Stop and ask before:
  • adding write capabilities
  • enabling any background watcher/daemon
  • broad exporting of large chat histories
  • changing how secrets/session storage works
出现以下操作前请停止并询问用户：
  • 新增写入能力
  • 启用任何后台监听器/守护进程
  • 大量导出大规模聊天历史
  • 修改机密/会话存储的实现逻辑