Telegram Dev

Telegram Dev

让 Telegram 机器人和 AI 编码 Agent 使用最新的 Bot API。

Telegram 每隔一两个月就会更新 Bot API，而代码和模型都会落后。Telegram Dev 包含三个部分：

• telegram-dev check 可读取 Python 机器人（aiogram、python-telegram-bot、pyTelegramBotAPI 或原始 HTTP 调用），并列出包含已弃用参数或无效值的 Bot API 调用。它可在终端、CI 中作为 GitHub Action，或作为 Agent 工具运行。
• 面向 Agent 的 Bot API 工具：方法和类型定义、请求检查器，以及按版本整理的变更日志，均基于官方页面构建。
• 面向 Claude Code、Codex 和 Cursor 的文档服务与技能：可搜索 Telegram 和 TON 官方文档（Bot API、Mini Apps、MTProto、TDLib、机器人库、TON Connect、Tolk），并自动刷新。

无需 Telegram 账号、机器人令牌或 API 密钥：所有内容均来自公开文档。

俄语版

检查机器人项目

telegram-dev check 一次运行即可检查 Python 机器人中的所有 Bot API 调用——包括 aiogram、python-telegram-bot、pyTelegramBotAPI，或对 api.telegram.org 的原始 HTTP 请求——并且只打印发现的问题：

uvx telegram-dev check ./my-bot

$ uvx telegram-dev check ./tutorial        # a popular open-source aiogram 3 tutorial
code/03_buttons/bot.py:79: warning: types.KeyboardButton: `request_user` was retired in Bot API 7.0: Renamed the field request_user in the class KeyboardButton to request_users. The old name will still work for backward compatibility. ...
code/08_inline_mode/handlers/inline_mode.py:48: warning: inline_query.answer: `switch_pm_text` was retired in Bot API 6.7: ... replacing the parameters switch_pm_text and switch_pm_parameter of the method answerInlineQuery with the parameter button of type InlineQueryResultsButton. ...
Bot API 10.4; 95 files with bot code; libraries: aiogram ==3.14.0 ==3.7.0 >=3.24.0 ...; 0 errors, 5 warnings

错误值会被视为错误，例如 InlineKeyboardButton(text="Delete", style="red") 会给出 style: must be one of danger, success, primary。

错误包括不在文档列出的值，以及原始 API 请求中的未知方法或参数。警告包括 Telegram 已弃用的参数（附带版本和替代它的变更日志条目）、既不是 Bot API 参数也不是已知库选项的关键字参数，以及没有对应 Bot API 方法的机器人方法。它只读取代码，不会运行代码，因此不会跟踪变量或检查必需参数。选项：--json、--exclude 'tests/*'、--strict（遇到警告时失败）、--format github。在 Agent 会话中，同样的检查可通过 check_telegram_project 工具执行（仅限本地 stdio 服务，因为它需要读取文件）。

在 GitHub 仓库中，可在每个拉取请求上运行此工具；发现的问题会作为注释显示在有改动的代码行上：

# .github/workflows/telegram.yml
on: [pull_request]
jobs:
  bot-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Kay0k1/[email protected]
        with:
          path: .
          exclude: "tests/*"

安装

你需要 uv。无需机器人令牌、Telegram 账号或 API 密钥：服务只读取公开文档。

一条命令安装 MCP 服务和技能

在你的项目目录中运行：

uvx telegram-dev install --agent claude    # or: codex, cursor

--agent	MCP 服务添加到	技能复制到
claude	.mcp.json	.claude/skills/telegram-dev
codex	.codex/config.toml	.agents/skills/telegram-dev
cursor	.cursor/mcp.json	.cursor/skills/telegram-dev

安装程序会保留你的其他设置，备份它修改的文件，并且绝不会覆盖已有的 Telegram Dev 配置。服务会固定到已安装的版本，因此除了 uv 缓存外，无需在磁盘上保留任何内容。之后请开启新的 Agent 会话，并在收到提示时批准项目 MCP 服务。Codex 只有在你信任项目目录后才会加载项目设置。

之后升级：uvx telegram-dev@latest install --agent claude --update。

Claude Code 插件

/plugin marketplace add Kay0k1/telegram-dev
/plugin install telegram-dev@telegram-dev-tools

这会为你的所有项目添加技能和 MCP 服务。请使用插件或安装程序中的一种，不要同时使用两者。

仅 MCP 服务

claude mcp add --scope user telegram-knowledge -- uvx telegram-dev serve

codex mcp add telegram-knowledge -- uvx telegram-dev serve

Cursor：

其他任何 MCP 客户端：

{
  "mcpServers": {
    "telegram-knowledge": { "command": "uvx", "args": ["telegram-dev", "serve"] }
  }
}

这些工具无需配合技能即可使用，但技能能让 Agent 始终如一地使用它们。

面向 Agent 的最新文档

Telegram 每隔一两个月就会发布一个新的 Bot API 版本。模型对它的了解会停留在训练截止时间，因此 Agent 会自信地使用已更改或从未存在过的字段编写代码。它们也常常混淆 Bot API、MTProto 和 TDLib，尽管三者的功能大不相同。

TON 的发展速度同样很快。当前的 TON 文档将该币称为 Gram，介绍 Telegram Money（内置于 Telegram 的钱包），并将 Tolk 视为主要合约语言，把 FunC 视为旧版语言。此外，Telegram 还有自己的规则：Mini Apps 中的区块链功能必须使用 TON 和 TON Connect，数字商品则以 Stars 出售。

使用 Telegram Dev 时，Agent 会在编写代码前先读取当前页面。以下是在全新项目中运行 uvx telegram-dev install --agent codex 后的一次真实 Codex CLI 运行示例（已删减工具调用）：

> Use the telegram-dev skill. In a python-telegram-bot project, I want the inline
  'Delete' button to be red and show a custom emoji. Which Bot API fields do this,
  what are the requirements, and what does the request JSON look like?

  get_telegram_corpus_status {}
  search_telegram_docs {"query": "style icon_custom_emoji_id", "area": "releases"}
  search_telegram_docs {"query": "InlineKeyboardButton icon_custom_emoji_id style", "area": "bot-api"}
  get_telegram_document {"url": "https://core.telegram.org/bots/api", "offset": 167594, "length": 10500}
  get_telegram_document {"url": "https://core.telegram.org/bots/api-changelog", "offset": 39089, "length": 6000}

Use these InlineKeyboardButton fields:
- style: "danger" makes the button red.
- icon_custom_emoji_id is a custom emoji ID shown before "Delete".
- callback_data is your action identifier, 1-64 bytes.

The custom emoji requires either a bot that bought additional usernames on Fragment,
or a Premium bot owner with the message sent by the bot to a private chat, group or
supergroup. PTB 22.7+ supports both fields. Older Telegram clients show the button
unstyled. Source: https://core.telegram.org/bots/api#inlinekeyboardbutton

{"chat_id": 123456789, "text": "Choose an action:",
 "reply_markup": {"inline_keyboard": [[{"text": "Delete", "callback_data": "delete:42",
   "style": "danger", "icon_custom_emoji_id": "YOUR_CUSTOM_EMOJI_ID"}]]}}

该技能也知道何时不该使用区块链。另一次真实的 Codex 运行：

> Use the telegram-dev skill. Our Telegram Mini App sells a premium in-game skin
  for 2 TON. I want a Buy button that connects the user's wallet and charges them.

  get_telegram_document {"url": "https://core.telegram.org/bots/payments-stars", "refresh": true}
  search_telegram_docs {"query": "createInvoiceLink answerPreCheckoutQuery successful_payment XTR", "area": "bot-api"}
  get_telegram_document {"url": "https://docs.ton.org/applications/ton-connect/overview", "refresh": true}
  get_telegram_document {"url": "https://core.telegram.org/bots/webapps", "offset": 40310}

Use Telegram Stars (XTR) through the Bot API. The skin is a digital good, so
Telegram requires Stars and prohibits cryptocurrency payment for this purchase.
For permitted wallet features, use the TON Connect SDK.
1. Validate initData on the backend and bind the order to the user.
2. createInvoiceLink with currency "XTR", open it with Telegram.WebApp.openInvoice.
3. Answer pre_checkout_query, grant the skin once on successful_payment,
   store telegram_payment_charge_id for refunds.

工具

工具	功能
search_telegram_docs	对已索引章节进行全文搜索，可选限定在某个领域：bot-api、mini-apps、telegram-api、tdlib、ton、releases、ton-releases、aiogram、python-telegram-bot、grammy 等。除非查询中提到了某个库，否则优先显示 Telegram 核心文档
get_telegram_document	分页读取官方页面，每页最多 40,000 个字符；如果页面缺失或超过 6 小时未更新，则会重新获取
get_telegram_corpus_status	查看已索引的内容、最新程度以及哪些来源获取失败
list_telegram_document_revisions	查看此安装所捕获页面的修订记录
list_telegram_sources	按 API 领域分组的 61 个官方入口
list_telegram_cached_pages	按领域查看本地缓存中已存储的页面及其最新程度
get_bot_api_definition	以结构化数据形式查看一个 Bot API 方法或类型：参数或字段、类型、必填标记、允许的值、长度限制，以及提及它的变更日志条目
check_bot_api_call	根据当前 Bot API 架构检查代码发送的请求：未知方法和参数（含建议）、缺少的必填项、错误类型、不在文档列表中的值，以及已弃用的参数和替代版本
list_bot_api_changes	以结构化版本记录的形式查看官方 Bot API 变更日志，可按版本（since_version="9.0"）或方法、类型或字段名称筛选
check_telegram_project	一次性检查本地 Python 机器人项目中的所有 Bot API 调用（参见检查机器人项目）；仅限本地 stdio 服务

检查 Bot API 调用

Bot API 工具根据缓存中的官方 API 页面和变更日志构建，因此会跟随 Telegram 当前版本（撰写本文时为 Bot API 10.4），而无需手写架构。例如，对以下内容运行 check_bot_api_call：

{"method": "sendMessage", "params": {"chat_id": 1, "text": "Delete?", "reply_to_message_id": 42,
  "reply_markup": {"inline_keyboard": [[{"text": "Delete", "callback_data": "del", "style": "red"}]]}}}

会针对 reply_markup.inline_keyboard[0][0].style 返回错误（必须是 danger、success、primary 之一），并警告 reply_to_message_id 已在 Bot API 7.0 中由 reply_parameters 取代。该工具不会调用 Telegram，因此权限、聊天状态和文件内容仍需通过实际测试确认。

缓存初始为空。Agent 首次读取页面时会获取页面并立即建立索引。要预先获取配置来源中所有可访问的内容：

uvx telegram-dev sync --max-pages 0
uvx telegram-dev search "sendVideoNote"
uvx telegram-dev status

该技能涵盖的内容

领域	Agent 检查的内容
Bot API	消息、键盘、更新、webhook、文件、权限
格式和表情符号	实体、UTF-16 偏移量、自定义表情符号及其使用权限
媒体和贴纸	语音消息、视频便笺、贴纸集、文件限制
Mini Apps	JS 桥接、启动参数、主题、服务端 initData 验证
MTProto 和 TDLib	用户与 Bot 授权、架构和层级、TDLib 版本
商业和支付	商业连接、Stars、订阅、礼物、付费媒体
群组和频道	管理员权限、论坛和话题、内容审核
TON	Telegram 关于 Mini Apps 的区块链规则、Stars 与加密货币的区别、TON Connect 和 ton_proof、支付处理、jetton 和 NFT（TEP）、Tolk 合约、先使用测试网、密钥安全
Bot 库	aiogram、python-telegram-bot 和 grammY：与已安装版本匹配的库文档，并与 Bot API 页面进行对比；会指出索引文档描述的是其他版本的情况
版本发布	Bot API 更新日志、API 层级、TDLib 更新日志、TON 节点和 Tolk 更新日志、官方公告

该技能位于 skills/telegram-dev，每个领域都有一个参考文件。

文档的新鲜度

• 读取超过 6 小时的页面时会重新获取。搜索最多会重新获取 6 个符合条件的过期页面。
• 服务运行期间，后台周期每 6 小时检查最多 120 个页面：入口页面、新发现的链接以及最旧的页面。
• 如果无法访问 Telegram 网站，会保留缓存文本并标记为过期，同时附上错误信息，让 Agent 知道自己读取的是旧副本。
• 每日 GitHub Action 会检查全部 61 个官方来源，并在 docs-status 分支发布哈希值和错误信息。

缓存路径（TELEGRAM_KNOWLEDGE_DB）和刷新间隔等设置见 docs/runtime.md。

帮助效果

使用 Codex CLI 对 11 个问题和 10 个编写代码任务进行测量（评估）：

• 使用 Codex 自带的网页访问功能时，无论是否使用 Telegram Dev，答案都同样准确：Agent 都能自行找到相同的官方页面。
• 无法访问网页时，借助 Telegram Dev，答案仍能反映最新情况（评分标准事实命中 45/47，而纯 Codex 为 38/47；代码检查通过 26/26，而纯 Codex 为 23/26）；纯 Codex 不知道最新的 Bot API 功能或 TON 当前使用的名称。

因此，当 Agent 无法浏览网页时，文档服务最为重要。项目检查会针对你的代码而非问题运行，因此无论如何都很有用。在 GitHub 上的开源 Bot 中运行时，它主要会发现 disable_web_page_preview 和 reply_to_message_id，这两项已在 Bot API 7.0 中弃用，但 Telegram 和各库仍为兼容性而接受它们。详情（包括误报审查）：docs/validation.md。

自托管

该服务也支持通过 Streamable HTTP 运行，因此团队可以共享同一个缓存。项目包含 Dockerfile 和带 HTTPS 的 Caddy 配置：docs/deployment.md。

uvx telegram-dev serve --transport streamable-http --port 8000

限制

• 搜索是本地全文搜索（SQLite FTS5），不是语义搜索。精确的方法名和英文术语效果最佳。内置少量俄语别名。
• 覆盖范围是从 61 个官方入口可以访问的内容。TON 页面来自 docs.ton.org 为 Agent 发布的 llms.txt 索引，因此新的 TON 页面会自动收录。
• Bot 库：aiogram 的指南和面向 Bot 的参考文档（latest，基于其主分支构建）、python-telegram-bot（stable 文档和官方 Wiki）以及 grammY（英文指南和插件），约 250 个页面。不会收录与 Bot API 对应的按类型生成的页面、grammY 的 /ref/ 和翻译版本；可以按需读取 aiogram 和 PTB 的已发布版本（/en/vX.Y.Z/）。不会收录 Telegraf、Telethon 和 Pyrogram。页面历史从你的安装首次获取该页面时开始。
• 此服务不会登录 Telegram、发送消息、访问聊天或持有钱包密钥。它只读取公开页面。
• 此技能能改善 Agent 的工作方式，但不能保证答案正确：发布前请对照 Telegram 检查代码。

开发

git clone https://github.com/Kay0k1/telegram-dev && cd telegram-dev
uv sync --frozen
uv run --frozen python -m unittest discover -s tests -v
uv run --frozen telegram-dev install --agent claude --project /path/to/test-project

CI 会在 Linux、macOS 和 Windows 上运行测试，并检查 Docker 镜像。docs/validation.md 列出了已手动验证和尚未验证的内容。欢迎提交问题和拉取请求；tests/behavioral-cases.json 中的 Agent 场景仍需在每个客户端中运行。

许可证

代码和技能采用 MIT 许可证。获取的 Telegram 和 TON 文档仍归其所有者所有；此软件包不包含这些文档（NOTICE）。这是一个独立项目，与 Telegram 或 TON Foundation 无关。