Agents Guide To Telegram

The Agent's Guide to Telegram

**教 agent 使用 Telegram：发原生表格、LaTeX 公式、折叠块、真贴纸，让你在手机上看着它干活——外加一整本真机踩出来的坑谱。**

· MIT · 只依赖 `requests` 发现 bug 或者 Telegram 又更新了，欢迎开 issue / 提 PR。 （前名 `tg-rich-mcp`，旧链接与旧 git remote 均自动跳转。名字致敬你猜到的那本书—— 面对一个陌生星球的 API，手册比勇气有用，Don't Panic.）

Telegram 在 Bot API **10.1**（2026-06-11）加了 Rich Messages，10.2（07-14）补齐发送侧。 官方 telegram 插件的 `reply` 够不着这些，这个包直投 Bot API 把它接进来。

两件东西，可以只用一件：

文件	是什么	通用性
tg_rich_mcp.py	MCP server，六个工具：发 / 原地改 / 推草稿 / 贴纸挑发 / 贴纸入库 / 按钮选择题（实验性）	✅ 走握手式 MCP 的 host（Claude Code、Claude Desktop、Cursor、自己写的 agent）——协议版本见下
tg_sticker.py	贴纸车道：库 / 认领 / 交集挑选 / 各 bot 懒迁移 / 句内标记（挂在上面那个 server 里）	跟着走
tg_ask.py	按钮问答机制层：inline keyboard + getUpdates 同步等点击（挂在上面那个 server 里）	跟着走；⚠️ 要专用 bot，见「按钮问答要专用 bot」
tg_progress_hook.py	进度窗 hook：每次调工具前推一行	⚠️ 仅 Claude Code（靠它的 PreToolUse 钩子，别的 host 没有这个机制），且需要 Linux / macOS / WSL
tg_sticker_hook.py	入站贴纸识别 hook：认识的注入标签（agent 不用看图）、不认识的提醒归档	⚠️ 仅 Claude Code（UserPromptSubmit 钩子）；零网络、fail-silent
secret_redaction.py	密钥形态的单一真源，上面的都用它	跟着走，别单独删
test_*.py	148 个测试，python3 -m unittest discover -v，1 秒内、不发网络	—

外加一份 **[COOKBOOK.md](COOKBOOK.md)** —— Telegram 富消息**能玩什么**的全景清单： 行内公式、剧透、上下标、脚注、锚点跳转、任务清单、表格高级字段、地图、拼贴轮播、 按读者时区渲染的时间……包括你大概率用不上的那些。 列出来不是让你都用，是让你**知道有这条路**——不知道的能力等于不存在。

进度窗长这样，在手机上一行行自己长出来：

┌ 正在干活…
│ 📖 Read · server.py
│ 🔍 Grep · handleRequest
│ ⚡ Bash · 跑一遍测试
└ 已经做了 12 步

**它默认会把长得像密钥的摘要替换成「（内容隐去）」。不喜欢这种防御？ `TG_PROGRESS_REDACT=0` 一把关掉** —— 详见下面「安全闸，以及怎么关」。

**TL;DR (English)** — Teach your agent to use Telegram. An MCP server exposing Telegram's Rich Message API (native tables, LaTeX, collapsible blocks, in-place edits, streaming drafts, an emoji-indexed sticker lane the agent curates itself, plus experimental synchronous choice questions answered with one button tap) to any handshake-based stdio MCP host (protocol 202