Telegram Readonly
Use the installed telegram-readonly CLI 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.
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.
Installation preference
Prefer an installed CLI over hardcoded script paths.
Preferred install:
CODEBLOCK0
Fallback inside a repo checkout:
CODEBLOCK1
After install, use:
INLINECODE1
Commands
Show built-in help
CODEBLOCK2
Authenticate once
CODEBLOCK3
List chats
INLINECODE2 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.
CODEBLOCK4
Read recent messages
CODEBLOCK5
Search messages
CODEBLOCK6
Restrict search to one chat:
CODEBLOCK7
List recent unread chats
Default behavior is opinionated: exclude muted and archived chats.
CODEBLOCK8
Include muted and/or archived when needed:
CODEBLOCK9
List recent unread DMs only
CODEBLOCK10
Workflow
- 1. Read
references/setup-and-safety.md if setup, auth, or unread-state behavior matters. - Ensure the
telegram-readonly CLI is installed. - Ensure Telegram API credentials exist.
- Run
auth once to create the session. - Use
dialogs, messages, search, unread-dialogs, or unread-dms as needed. - Keep usage narrow and intentional.
Expected outputs
The wrapper returns JSON. Parse it instead of relying on fragile text scraping.
Dialog objects include:
- - INLINECODE15
- INLINECODE16
- INLINECODE17
- INLINECODE18
- INLINECODE19
- INLINECODE20
- unread counters
Files
- - Package repo: INLINECODE21
- Compatibility wrapper: INLINECODE22
- Setup notes: INLINECODE23
- Config storage: INLINECODE24
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
Telegram 只读模式
使用已安装的 telegram-readonly CLI 从用户个人账户读取Telegram信息。
此技能存在的理由是Telegram Bot API不适合读取真实个人账户。应改用基于Telethon的MTProto。
快速规则
- - 仅将此技能用于读取操作。
- 不要擅自执行写入操作。
- 除非用户明确要求，否则不要在封装器中添加发送/编辑/删除逻辑。
- 将Telethon会话视为高权限机密。
- 在真实聊天中测试前，默认未读状态保持为尽力而为。
安装偏好
优先使用已安装的CLI，而非硬编码脚本路径。
推荐安装方式：
bash
pipx install git+https://github.com/ropl-btc/telegram-readonly-cli.git
在仓库目录内的备用安装方式：
bash
pip install .
安装后使用：
telegram-readonly
命令
显示内置帮助
bash
telegram-readonly help
一次性认证
bash
export TELEGRAMAPIID=12345678
export TELEGRAMAPIHASH=yourapihash
telegram-readonly auth
列出聊天
dialogs --query 对 name、username 和 title 进行基于令牌的匹配，因此像 petros skynet 这样的查询即使完整字符串不作为单个子串存在也能生效。
bash
telegram-readonly dialogs --limit 50
读取最近消息
bash
telegram-readonly messages --chat @username --limit 50 --reverse
搜索消息
bash
telegram-readonly search invoice --limit 50
限制搜索范围至单个聊天：
bash
telegram-readonly search deadline --chat @username --limit 50
列出最近未读聊天
默认行为有倾向性：排除静音和归档的聊天。
bash
telegram-readonly unread-dialogs --limit 10
需要时包含静音和/或归档聊天：
bash
telegram-readonly unread-dialogs --limit 10 --include-muted --include-archived
仅列出最近未读私信
bash
telegram-readonly unread-dms --limit 10
工作流程
- 1. 如果设置、认证或未读状态行为重要，请阅读 references/setup-and-safety.md。
- 确保已安装 telegram-readonly CLI。
- 确保存在Telegram API凭证。
- 运行 auth 一次以创建会话。
- 根据需要使用 dialogs、messages、search、unread-dialogs 或 unread-dms。
- 保持使用范围狭窄且有目的性。
预期输出
封装器返回JSON。请解析JSON而非依赖脆弱的文本抓取。
对话对象包含：
- - isuser
- isgroup
- ischannel
- isbot
- archived
- muted
- 未读计数器
文件
- - 包仓库：https://github.com/ropl-btc/telegram-readonly-cli
- 兼容性封装器：scripts/telegram_readonly.py
- 设置说明：references/setup-and-safety.md
- 配置存储：~/.config/telegram-readonly/config.json
何时停止并询问
在以下情况前停止并询问：
- - 添加写入功能
- 启用任何后台监视器/守护进程
- 大规模导出聊天历史
- 更改密钥/会话存储方式
