Telegram Readonly 是一个通过本机脚本以受控、只读方式读取用户个人 Telegram 账号的技能。该技能存在的理由是：Telegram Bot API 不适合读取真实个人账号，因此改用 Telethon 走 MTProto 协议。
【用途】 仅用于读取用户个人 Telegram 账号。可用于检查聊天、列出对话、读取最近消息、搜索消息以及列出未读会话。技能明确限定为只读，不包含任何写入能力。
【主要能力】
- dialogs：列出对话，支持 --query 进行跨名称、用户名和标题的基于 token 的匹配。
- messages：读取指定聊天的最近消息，支持 --chat 与 --limit、--reverse。
- search：搜索消息，可全局搜索或通过 --chat 限定到单个聊天。
- unread-dialogs：列出最近未读会话，默认排除静音和归档聊天，可用 --include-muted、--include-archived 调整。
- unread-dms：仅列出最近未读私聊。
- auth：执行一次认证，成功后写入配置文件。
- help：显示内置帮助。
【使用方式】 优先使用技能本地脚本和技能本地虚拟环境，而非全局 CLI 安装。 先引导本地环境： <skill-path>/scripts/bootstrap_venv.sh 引导后使用： <skill-path>/scripts/telegram-readonly 若之后 .venv 缺失，重新运行引导脚本即可。 主配置路径： ~/.config/telegram-readonly/config.json 推荐的一次性设置：确保 api_id 与 api_hash 可用，然后运行： <skill-path>/scripts/telegram-readonly auth 登录成功后，配置文件会存储 api_id、api_hash 以及 Telegram 会话字符串，后续读取无需再导出 shell 变量。 认证示例： export TELEGRAM_API_ID='12345678' export TELEGRAM_API_HASH='your_api_hash' <skill-path>/scripts/telegram-readonly auth 列出对话： <skill-path>/scripts/telegram-readonly dialogs --limit 50 读取最近消息： <skill-path>/scripts/telegram-readonly messages --chat '@username' --limit 50 --reverse 搜索消息： <skill-path>/scripts/telegram-readonly search 'invoice' --limit 50 限定单个聊天搜索： <skill-path>/scripts/telegram-readonly search 'deadline' --chat '@username' --limit 50 列出最近未读会话： <skill-path>/scripts/telegram-readonly unread-dialogs --limit 10 包含静音与归档： <skill-path>/scripts/telegram-readonly unread-dialogs --limit 10 --include-muted --include-archived 仅列出未读私聊： <skill-path>/scripts/telegram-readonly unread-dms --limit 10
【适用场景】 需要以只读方式查看个人 Telegram 账号的对话、消息、未读情况，或按关键词检索消息时使用。保持使用范围狭窄且有明确意图。
【限制与注意事项】
- 仅用于读取；不要即兴添加写入操作。
- 除非用户明确要求，不要向包装器添加发送、编辑或删除逻辑。
- 将 Telethon 会话视为高权限机密。
- 在真实聊天上测试之前，未读状态的保留应视为尽力而为。
- 在添加写入能力、启用后台监听/守护进程、大规模导出大量聊天历史，或更改机密/会话存储方式之前，应先停下来询问。
- .env 仅为可选回退，不是首选的长期设置。
- .venv/ 是生成的本地状态，不属于技能本身，可用引导脚本重新创建。
- 输出为 JSON，应解析 JSON 而非依赖脆弱的文本抓取。对话对象包含 is_user、is_group、is_channel、is_bot、archived、muted 以及未读计数器等字段。
【文件】
- 包仓库：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
【分类】 该技能用于以只读方式访问个人 Telegram 账号、检索聊天与消息，属于办公与效率范畴的通用通信读取工具；若无法确定，可归为通用与其它。