gramio

GramIO

GramIO 是一个面向 TypeScript 的现代、类型安全的 Telegram Bot API 框架。它可在 Node.js、Bun 和 Deno 上运行，全面支持 Bot API，提供可组合的插件系统，并具备一流的 TypeScript 支持。

何时使用此技能

• 创建或修改 Telegram 机器人
• 设置机器人命令、回调、内联查询或反应
• 构建键盘（回复、内联、移除、强制回复）
• 使用实体（粗体、斜体、代码、链接、提及）格式化消息
• 上传或下载文件和媒体
• 管理用户会话或多步骤对话流程（场景）
• 编写自定义插件
• 配置 Webhook 或长轮询
• 使用 Telegram Stars 处理付款
• 处理速率限制并广播消息
• 使用后端身份验证构建 Telegram Mini Apps（TMA）
• 使用 Docker 容器化机器人
• 使用独立的 @gramio/types 为自定义 Bot API 封装提供支持
• 编写并发布自定义插件
• 将机器人从 puregram、grammY、Telegraf 或 node-telegram-bot-api 迁移到 GramIO

GramIO 文档：安装软件包

在 GramIO VitePress 网站（docs/ 和 docs/ru/）中创建或编辑安装说明时，安装所有软件包时始终使用 ::: pm-add，包括 Wrappergram 和可选依赖项：

::: pm-add wrappergram
:::

保留现有的 pm-add 块。切勿将其替换为手动编写的 npm/yarn/pnpm/bun code-group 块或单独的安装命令：网站的软件包管理器插件会自动生成这些内容。英文和俄文文档均遵循此约定。此规则仅适用于文档网站；GitHub README 文件、终端命令和 Dockerfile 使用普通 shell 语法。

快速入门

npm create gramio bot-name
cd bot-name
npm run dev

基本模式

import { Bot } from "gramio";

const bot = new Bot(process.env.BOT_TOKEN as string)
    .command("start", (context) => context.send("Hello!"))
    .onStart(({ info }) => console.log(`@${info.username} started`))
    .onError(({ context, kind, error }) => console.error(`[${kind}]`, error));

bot.start();

内省工具

此技能包含 tools/ 下的四个 Node.js 脚本，可解析磁盘上已安装的 @gramio/* 和 gramio 软件包。优先使用这些脚本，而不是通过 URL 获取内容或加载 telegram-api-index；每次调用都会返回一个重点明确、与版本匹配的签名，而不是一大堆文档。

请在用户项目根目录（即 node_modules/ 所在位置）运行。工具将结果输出到 stdout；错误和自动更正提示会输出到 stderr。

工具	使用场景
tools/get-bot-api-method.mjs <name>	需要 Bot API 方法的签名时（例如 sendMessage、createChatInviteLink）——返回 @gramio/types 中的 JSDoc 及参数/返回类型。--list 显示所有方法，--search <term> 按名称/说明筛选。
tools/get-bot-api-type.mjs <name>	需要 Telegram 类型定义时（例如 Message、ChatInviteLink）。可接受简写名称（Message）或完整名称（TelegramMessage）。支持相同的 --list / --search 标志。
tools/get-context-getter.mjs <ClassName>	需要了解上下文公开了哪些 getter/方法时（MessageContext、CallbackQueryContext、User、Chat）。添加 --deep 可递归提取 mixin 和合并后的接口。--search <name> 可查找公开指定 getter/方法的所有类（例如 firstName 存在于 User、Chat、Contact 和 SharedUser 上）。
tools/get-plugin.mjs <name>	需要了解插件的入口函数签名及其在上下文中派生的内容时（例如 session、scenes、i18n）。--list 显示所有已安装的 @gramio/* 软件包。

node tools/get-bot-api-method.mjs sendMessage
node tools/get-bot-api-type.mjs InlineKeyboardMarkup
node tools/get-context-getter.mjs MessageContext --deep
node tools/get-context-getter.mjs --search chatId
node tools/get-plugin.mjs session

这些脚本会进行模糊匹配（sendMesage → sendMessage），并在未匹配时推荐替代项。它们需要安装相应的软件包；若未安装，会输出准确的 npm install 提示。

关键概念

1. 回调路由——绝不要手动解析回调数据。 CallbackData.pack() 会生成一个 6 字符的哈希前缀（架构名称的 sha1-base64url）以及序列化载荷——而不是像 "nav:" 这样的字面前缀。像 ctx.data.startsWith("nav:") 这样的检查在运行时总会失败。请根据数据的形态，从以下四种模式中选择一种：

   // Fixed string → exact string match
   bot.callbackQuery("refresh", (ctx) => ctx.answer("Refreshed"));
   
   // Pattern / variable slug → RegExp with capture groups
   bot.callbackQuery(/^user_(\d+)$/, (ctx) => {
       const [, id] = ctx.match!;
       ctx.answer(`User ${id}`);
   });
   
   // Structured data → CallbackData schema (preferred for multi-field payloads)
   import { CallbackData } from "gramio";
   const nav = new CallbackData("nav").enum("to", ["home", "history", "admin"]);
   bot.callbackQuery(nav, (ctx) => {
       ctx.queryData.to; // "home" | "history" | "admin" — fully typed
   });
   
   // Stale-safe unpack (when inline keyboard may outlive a schema change)
   const result = nav.safeUnpack(ctx.data!);
   if (!result.success) return ctx.answer("Button expired");
   result.data.to; // typed
   

   // ❌ NEVER — hashed prefix means string compare won't match,
   //    and you lose full type safety.
   if (ctx.data?.startsWith("nav:")) {
       const [, to] = ctx.data.slice(4).split(":");
       // ...
   }
   

   关于插件间处理器重叠时的行为，请参阅 callback-data 和 middleware-routing。

2. 方法链式调用 — 处理器、钩子和插件通过 .command()、.on()、.extend() 等方法链式调用。顺序很重要：当两个处理器匹配同一更新时，除非第一个调用 next()，否则由最先注册的处理器处理。请参阅 middleware-routing。

3. 类型安全的上下文 — 上下文会根据更新类型自动进行类型标注。在通用处理器中使用 context.is("message") 来缩小类型范围。调用 .derive()／.decorate()／.extend(plugin) 后，新字段会自动出现在推断出的上下文类型中——绝不要使用 ctx as unknown as { myField } 进行类型转换。导出机器人的上下文类型并重复使用（参见 context →「derive 后的上下文类型」）。

4. 上下文 getter — 始终使用 camelCase；绝不访问 ctx.payload 或 ctx.update.* — 每个 Telegram 字段都会以 camelCase getter 的形式公开（ctx.from、ctx.firstName、ctx.chatId、ctx.messageId、ctx.text、ctx.data、ctx.queryData）。ctx.payload 和 ctx.update 都是原始的 snake_case 内部对象——处理器代码中禁止访问。

5. 插件系统 — new Plugin("name").derive(() => ({ ... })) 会向上下文添加类型化属性。通过 bot.extend(plugin) 注册。

6. 钩子生命周期 — onStart →（带有 onError 的更新）→ onStop。API 调用：preRequest → call → onResponse/onResponseError。

7. 抑制错误 — bot.api.method({ suppress: true }) 会返回错误，而不是抛出错误。

8. 惰性插件 — 异步插件（不使用 await）会在 bot.start() 时加载。使用 await 可立即加载。

9. Derive 与 Decorate — .derive() 会按更新运行（计算属性），.decorate() 则只注入一次静态值。

10. 格式化 — 四条关键规则（编写任何消息文本前，请阅读 formatting）：

    • 绝不要使用 parse_mode — format 会生成 MessageEntity 数组，而不是 HTML/Markdown 字符串。添加 parse_mode: "HTML" 或 "MarkdownV2" 会导致消息出错。GramIO 会自动传递实体。
    • 绝不要对格式化值数组使用原生 .join() — 它会对每个 Formattable 调用 .toString()，悄无声息地破坏所有样式。始终使用 join 辅助函数：join(items, (x) => bold(x), "\n")。
    • **组合或复用样式内容时，始终将其包装在 format\`中** — 将Formattable嵌入普通模板字面量（``${boldx}``）会移除所有实体。应使用format`${bold`x`}``。
    • 绝不要对 FormattableString 调用 .toString() — 将它直接作为 send、editMessageText、editMessageCaption 等方法的 text:／caption: 参数传入。调用 .toString() 会移除所有实体。这是魔法链接和格式化实体在编辑后「失效」的首要原因。

11. 场景 — 步骤语义与更新类型筛选 — context.scene.step.go(N) 和 context.scene.step.next() 会立即运行场景的中间件链，但每个 .step(updateName, handler) 都会通过 context.is(updateName) 进行筛选。如果当前上下文是 callback_query，而下一步是 .step("message", …)，则不会触发——你必须在 return step.next() 前直接发送 UI、使用 .step(["message", "callback_query"], …)，或在 onEnter／当前步骤的回调处理器中呈现提示词。对于单值验证输入，优先使用 .ask("field", zodSchema, "prompt")。请参阅 scenes。

12. InlineQueryResult 构建器 — 对于内联结果，请使用 InlineQueryResult.article(id, title, InputMessageContent.text(...)) 等构建器方法。bot.inlineQuery(/regex/, handler) 会路由内联查询。请参阅 triggers。

13. 组合屏幕 — 优先使用 @gramio/views，而不是内联调用 ctx.send / ctx.editText — 对于屏幕不止两三个的机器人，请使用 @gramio/views 插件定义可复用的视图模板，并通过 context.render(view, params) 渲染。它会根据更新类型自动检测应发送还是编辑，集中管理文本/键盘/媒体（包括使用 {{param}} / {{$global}} 插值、通过适配器工厂实现 i18n 的 JSON 驱动模板），并消除在 ctx.send(...) 和 ctx.editText(...) 调用位置重复编写消息正文这一常见问题。对于简单的、仅包含菜单的机器人（2-3 个屏幕、没有媒体、没有 i18n），普通的渲染函数模式就足够了——除此之外，都应升级为使用 @gramio/views。@gramio/views 标记为正在开发中（辅助函数/适配器的细节可能会变化），但其核心形式（initViewsBuilder、.render(fn)、context.render(...)）是稳定的，也是 GramIO 推荐的视图组合方向。请参阅 views。

14. @gramio/prompt 仅存在于内存中——不具备持久性。任何多步骤/连接/引导流程都应使用 Scenes + .ask()。 context.prompt(...) / context.wait(...) 返回的 Promise 存在于当前 Node.js 进程中。进程一旦重启（部署、崩溃、容器重新调度、dyno 轮换），Promise 就会消失：用户的下一条消息不会被视为答案，不会抛出错误，机器人会悄悄“忘记”用户进行到哪一步。这对 OAuth 连接流程（Spotify/Last.fm 等）、引导向导、收款以及任何必须在部署后继续的提问序列来说都是致命的。相比之下，Scenes 会将步骤索引和已收集的答案持久化到已配置的存储中（Redis / Cloudflare / 自定义存储），并在收到下一次更新时恢复。**规则：**只有在重启时流程丢失也可以接受的单问题、进程内提示（例如一次性确认、调试辅助）才可以使用 @gramio/prompt。每个重要的提问序列，以及每个“提问 → 验证 → 再次提问”的连接流程，都应该放在 Scene 中，并使用 .ask("field", zodSchema, "prompt message")。.ask() 不仅能像 prompt 一样消除 firstTime 分支和验证重试样板代码，还能持久化。对于多步骤流程，不要将 @gramio/prompt 推荐为 Scenes 的简化替代方案；阻止这种错误推荐正是这个概念存在的目的。请参阅 scenes 和 prompt。

15. 子 Agent 委派 — 技能不会在子 Agent 会话中自动激活。生成将要编写机器人代码的子 Agent 时，请在 Agent 提示词中明确传入相关参考文件的路径（例如 skills/references/callback-data.md、skills/plugins/scenes.md、skills/references/formatting.md、skills/references/middleware-routing.md），或将关键规则直接写入提示词。

16. 示例中任何地方都不得使用 any — 不要在 skills/ 下的任何文件（示例、Markdown 代码块、插件文档）中编写 ctx: any、as any、<any> 或隐式 any 参数。技能示例是 AI 会原样复制到用户机器人的模板；此处每出现一个 any，就会在下游机器人的代码中成倍扩散。请通过 ContextType<typeof bot, "update_name">、CallbackQueryShorthandContext<typeof bot, typeof schema> 推导正确的类型，或导出 BotContext = typeof bot['_']['context'] 别名。如果某个值在系统边界处确实未知，请使用 unknown 并进行类型收窄。没有例外，即使是在“错误示范”代码片段中也不行——请在具体行上使用带注释的 @ts-expect-error，而不要使用宽泛的 any。

17. 以按钮为先的 UX——用户点击，不输入。 导航应使用内联键盘，而不是斜杠命令。/start 应是简短的主视觉内容（加粗标题 + 引用块描述），并配有包含主要操作的内联键盘——而不是列出 /help、/settings、/delete 的大段文字。嵌套菜单的标题中需要包含面包屑（⚙️ Settings · home › settings），每个非首页屏幕都需要有一个 ◀ Back 按钮，深度超过两层的任何位置都需要有 🏠 Home。点击导航按钮时应编辑当前消息（ctx.editText），绝不发送新消息——新消息用于事件（结果、通知），而不是导航。切换按钮应在标签中显示状态（✅ Notifications / ⬜ Notifications），并由一个处理器切换会话字段并重新渲染。执行破坏性操作前，始终先显示确认屏幕，并将安全选项放在左侧。每个回调处理器都应以 ctx.answer() 开头，以便立即停止加载动画——导航时可以留空，用于 Toast 反馈时提供简短文本，仅当错误需要用户确认时才使用 { show_alert: true }。命令用于发现（通过 setMyCommands 注册，使其显示在 Telegram 的菜单按钮中），而不是作为主要 UI。完整指南请参阅 ux-patterns，工作示例 examples/ux-menu.ts 涵盖了主视觉内容 /start、嵌套菜单、切换按钮和破坏性操作确认。

18. 完成任何技能编辑前，运行 bun run check:skills——对 skills/**/*.ts 或 skills/**/*.md 中的 TypeScript 代码块所做的任何更改，都必须通过当前已安装 gramio 版本的类型检查。check:skills 脚本会在严格模式下对 skills/examples/*.ts 运行 tsc --noEmit。如果报告错误，请修复后再提交。如果某个现有示例因 gramio API 更新而失效，请更新示例以匹配当前 API（检查 node_modules/gramio/dist/index.d.ts 和 node_modules/@gramio/*/dist/index.d.ts 中当前的签名）。

19. Rich Messages 是独立的发送方式——Markdown 通道使用 rich/markdownTable，原生结构化块使用 blocks/table，富文本 JSX 使用 @gramio/jsx/rich。富文本值会路由到 sendRichMessage，而不是 sendMessage。streamRichMessage 基于 Markdown 分块；原生块应直接通过 ctx.send / ctx.sendRichMessage 发送。上传可在 rich_message.blocks / .media 中递归处理，但禁止在 sendRichMessageDraft 中直接上传。使用 bot.on("stopped_message_generation", ...) 处理用户取消。请参阅 rich-messages。

官方插件

插件	包	用途
Session	@gramio/session	持久化存储每位用户的数据
Scenes	@gramio/scenes	多步骤对话流程
Onboarding	@gramio/onboarding	仅用于装饰 — 声明式教程／功能介绍。支持多流程并发、拒绝阶梯和感知范围的渲染。不是表单／向导工具 — 如需此类功能，请使用 Scenes
I18n	@gramio/i18n	国际化（原生支持 TS 或 Fluent）
Autoload	@gramio/autoload	基于文件的处理程序加载
Prompt	@gramio/prompt	单问题提示 — 仅存储于内存，不持久化。对于必须在重启后保留的内容，请使用 Scenes .ask()
Views	@gramio/views	推荐用于屏幕组合 — 可复用模板（编程式 + JSON）、自动发送／编辑、键盘、媒体、i18n
JSX	@gramio/jsx	用于格式化 + 键盘的 JSX 语法（不使用 React）
Pagination	@gramio/pagination	使用流式构建器创建分页内联键盘菜单
Auto Retry	@gramio/auto-retry	遇到 429 速率限制时重试
Media Cache	@gramio/media-cache	缓存 file_ids
Media Group	@gramio/media-group	处理相册消息
Split	@gramio/split	拆分长消息
Auto Answer CB	@gramio/auto-answer-callback-query	自动回复回调
PostHog	@gramio/posthog	分析 + 功能标志
OpenTelemetry	@gramio/opentelemetry	分布式追踪和 spans
Sentry	@gramio/sentry	错误追踪 + 性能监控

Telegram Bot API 参考页面

GramIO 文档为 Telegram Bot API 的每个方法和类型都提供了专门的参考页面：

• 方法：https://gramio.dev/telegram/methods/{methodName} — 例如 sendMessage、createChatInviteLink、answerCallbackQuery
• 类型：https://gramio.dev/telegram/types/{typeName} — 例如 Message、ChatInviteLink、InlineKeyboard

每个页面都包含：GramIO TypeScript 示例、参数详情、列出原因和解决方法的错误表、提示与注意事项，以及相关链接。当用户询问特定的 Telegram API 方法或类型时，你可以获取或参考对应页面，以准确了解 GramIO 专属用法。

给 LLM 的提示：在任意 GramIO 文档页面的 URL 末尾添加 .md，即可获取格式整洁的 Markdown： https://gramio.dev/telegram/methods/sendMessage.md — 获取整洁的 Markdown，而非 HTML。 这适用于文档的所有章节，不仅限于 API 页面。

默认情况下，本技能不包含这些页面 — 用户询问特定方法／类型时，再按需获取。

要快速查找有哪些方法 — 请使用预先构建的索引：telegram-api-index。该文件列出了所有 165+ 个 Bot API 方法及其简短说明。需要查找方法名称或在获取完整页面前确认方法是否存在时，请加载此索引。

参考资料

核心

主题	描述	参考
Bot 配置	构造函数、API 选项、代理、测试 DC、调试	bot-configuration
Bot API	调用方法、抑制、withRetries、类型辅助工具	bot-api
上下文与更新	derive、decorate、中间件、启动/停止、类型收窄	context
触发器	command、hears、callbackQuery、inlineQuery、reaction	triggers
过滤器	类型安全的上下文收窄 — 仅用于过滤的 .on()、filters.* 谓词、guard()	filters
中间件路由	处理器优先级、next()、重叠的 CallbackData、集中式路由	middleware-routing
Scene ↔ Composer 继承	共享命名的 .as("scoped") composer，在 bot 级处理器和 Scene 步骤之间派生；拆分文件以避免循环导入	scene-composer-inheritance
钩子	onStart、onStop、onError、preRequest、onResponse	hooks
更新与生命周期	启动/停止选项、优雅关闭（SIGINT/SIGTERM）	updates
故障排查	症状 → 原因 → 修复：409 冲突、格式错误、加载指示器卡住、缺少选择加入的更新、没有 session 的 scenes、snake_case 访问、未等待的 MediaUpload	troubleshooting

功能

主题	描述	参考
键盘	Keyboard、InlineKeyboard、布局辅助工具、样式	keyboards
格式化	entity 辅助工具、join（绝不要使用原生 .join()！）、变量组合、不使用 parse_mode	formatting
富媒体消息	Markdown/结构化块辅助工具、富 JSX、递归上传、草稿、停止生成更新	rich-messages
UX 模式	按钮优先导航、/start 结构、嵌套菜单、切换项、破坏性操作确认、空状态、格式层级、命令发现	ux-patterns
深层链接	所有 t.me/<bot>?... 链接类型 — ?start=、?startgroup=、?startchannel=、?startapp=、?startattach=、?game= — 及各自触发的处理器/上下文字段、负载编码规则、admin= 权限令牌、易踩的坑	deep-links
文件	MediaUpload、MediaInput、下载、Bun.file()	files
CallbackData	类型安全的回调数据 schema	callback-data
存储	内存、Redis、Cloudflare 适配器	storage
Telegram Stars	付款、发票、订阅、内联发票、退款、测试模式	telegram-stars
类型	@gramio/types、类型辅助工具、Proxy 包装器、声明合并	types

基础设施

主题	描述	参考
Webhook	框架集成、隧道、自定义处理器	webhook
速率限制	withRetries、广播、队列	rate-limits
Docker	Dockerfile、多阶段构建、Docker Compose	docker
本地 Bot API Server	自托管 telegram-bot-api、云端→本地迁移（logOut + api.baseURL）、2 GB 上传、无令牌文件下载	local-bot-api
tdlight (@gramio/tdlight)	userbot/user 模式、额外方法（searchMessages/getChats/votePoll）、调度、代理、额外对象字段；方法名称陷阱；Docker	tdlight
TMA	Mini Apps、mkcert HTTPS、@gramio/init-data 身份验证	tma
测试	事件驱动的 bot 测试、用户行为者、API 模拟	testing

迁移

当用户想将现有机器人迁移到 GramIO 时加载。

来源	描述	参考
grammY	Flavor 泛型 → derive/extend、命名 API 参数、conversations → scenes、检查清单	migration-from-grammy
puregram	符号映射、API 对比、puregram → GramIO 重构检查清单	migration-from-puregram
Telegraf	符号映射、上下文类型、Scenes/WizardScene、Webhook 差异、检查清单	migration-from-telegraf
node-telegram-bot-api	符号映射、中间件概念、键盘构建器、会话、检查清单	migration-from-ntba

跨 gramio/@gramio/* 版本升级现有 GramIO 项目（而非从其他框架迁移）→ 使用独立的 gramio-upgrade 技能（skills/gramio-upgrade/SKILL.md）。它会检测已安装的版本，查询其版本变更记录（skills/gramio-upgrade/MIGRATIONS.md）中当前版本与目标版本之间的破坏性变更／弃用项／新功能，并应用相应修改。

插件

插件	描述	参考
Session	按用户存储数据，支持 Redis	session
Scenes	多步骤流程、状态、导航	scenes
Onboarding	带有多流程并发的装饰性教程——表单可搭配 Scenes 使用	onboarding
I18n	原生支持 TS 和 Fluent 的国际化	i18n
Autoload	基于文件的处理程序发现	autoload
Prompt	发送并等待回复——仅限内存，重启后会丢失；持久化问题序列请使用 Scenes .ask()	prompt
Views	推荐模式——@gramio/views 插件（模板、JSON、i18n、自动发送／编辑）；简单机器人的备用方案是普通的 render-fn	views
JSX	用于格式化和键盘的 JSX 语法（无需 React 运行时）	jsx
Pagination	流畅的分页内联键盘（上一页／下一页／首页／末页、页码信息）	pagination
OpenTelemetry	分布式追踪、跨度、插桩	opentelemetry
Sentry	错误跟踪、性能监控	sentry
Others	auto-retry、media-cache、media-group、split、posthog	other
Plugin Development	编写自定义插件、derive/decorate/error、延迟加载	plugin-development

示例

示例	描述	文件
基础机器人	命令、钩子、错误处理	basic.ts
键盘	回复、内联、列、条件	keyboards.ts
UX 菜单	Hero /start、带面包屑和返回按钮的嵌套菜单、切换按钮、破坏性操作确认步骤	ux-menu.ts
CallbackData	类型安全的回调架构	callback-data.ts
格式化	实体类型、join 辅助函数、变量组合、parse_mode 反模式	formatting.ts
文件上传	路径、URL、缓冲区、媒体组	file-upload.ts
错误处理	自定义错误、抑制、限定作用域	error-handling.ts
Webhook	框架集成	webhook.ts
会话	计数器、设置、Redis	session.ts
场景	分步骤的注册流程	scenes.ts
向导场景	由回调驱动的场景、混合回调与消息步骤、全局退出	wizard-scene.ts
场景组合器继承	3 文件包：具名的限定作用域组合器 + Scene.extend + 拆分文件，形成可安全处理循环导入的布局	scene-composer-inheritance/
回调路由	集中式路由器，跨功能共享导航 CallbackData	callback-routing.ts
Telegram Stars	付款、发票、退款	telegram-stars.ts
TMA	Elysia 服务、init-data 身份验证、webhook	tma.ts
Docker	优雅关闭、webhook/轮询切换	docker.ts
测试	用户模拟、API 模拟、错误测试	testing.ts
深层链接	/start 载荷路由（推荐人 / 订单 / 不透明令牌 / 内联模式重定向）+ 针对 ?startchannel/?startgroup 链接的 my_chat_member 管理员权限验证	deep-links.ts