# 格莱姆IO GramIO 是一个适用于 TypeScript 的现代、类型安全的 Telegram Bot API 框架。它在 **Node.js** 、 **Bun** 和 **Deno** 上运行，具有完整的 Bot API 覆盖、可组合的插件系统和一流的 TypeScript 支持。 ## 何时使用此技能 * 创建或修改 Telegram 机器人 * 设置机器人命令、回调、内联查询或反应 * 构建键盘（回复、内联、删除、强制回复） * 使用实体格式化消息（粗体、斜体、代码、链接、提及） * 上传/下载文件和媒体 * 管理用户会话或多步骤对话流（场景） * 编写自定义插件 * 配置网络钩子或长轮询 * 使用 Telegram Stars 处理付款 * 具有速率限制处理的广播消息 * 使用后端身份验证构建 Telegram Mini Apps (TMA) * 使用 Docker 将机器人容器化 * 使用独立的“@gramio/types”来定制 Bot API 包装器 * 编写和发布自定义插件 * 将机器人从 puregram、grammY、Telegraf 或 node-telegram-bot-api 迁移到 GramIO ## 快速入门 npm 创建 gramio 机器人名称 cd 机器人名称 npm 运行开发 ## 基本模式从“gramio”导入{Bot}； const bot = new Bot(process.env.BOT_TOKEN 作为字符串) .command("start", (context) => context.send("你好！")) .onStart(({ info }) => console.log(`@${info.username} 开始`)) .onError(({ context, kind, error }) => console.error(`[${kind}]`, error)); 机器人.start(); ## 关键概念 1. **方法链接** — 处理程序、挂钩和插件通过 `.command()`、`.on()`、`.extend()` 等进行链接。顺序很重要。 2. **类型安全上下文** — 上下文根据更新类型自动键入。使用 `context.is("message")` 在通用处理程序中缩小类型。 3. **插件系统** — `new Plugin("name").derive(() => ({ ... }))` 将类型化属性添加到上下文中。通过“bot.extend(plugin)”注册。 4. **Hooks 生命周期** — onStart →（使用 onError 更新）→ onStop。 API调用：preRequest → 调用 → onResponse/onResponseError。 5. **错误抑制** — `bot.api.method({ suggest: true })` 返回错误而不是抛出。 6. **惰性插件** — 异步插件（不带 `await`）在 `bot.start()` 处加载。使用“await”立即加载。 7. **Derive 与 Decorate** — `.derive()` 每次更新运行（计算），`.decorate()` 注入静态值一次。 8. **上下文 getter — 始终为驼峰式命名** — 所有 `ctx` 属性都是驼峰式命名的 getter（`ctx.from`、`ctx.firstName`、`ctx.chatId`、`ctx.messageId` 等）。 **永远不要访问`ctx.payload`** - 它是原始的snake_case内部Telegram对象。一切都使用类型化的驼峰式吸气剂。 9. **格式——三个关键规则**（在编写任何消息文本之前阅读[格式]()： * **永远不要使用 `parse_mode`** — `format` 生成 `MessageEntity` 数组，而不是 HTML/Markdown 字符串。添加 `parse_mode: "HTML"` 或 `"MarkdownV2"` 将破坏消息。 GramIO 自动传递实体。 * **永远不要在格式化值数组上使用 native`.join()`** — 它会在每个 `Formattable` 上调用 `.toString()`，默默地破坏所有样式。始终使用 `join` 帮助器：`join(items, (x) => bold(x), "\n")`。 * **在编写或重用时，始终将样式内容包装在 `format\```** 中 - 在普通模板文字中嵌入 `Formattable`（```${bold`x`}```）会删除所有实体。使用`format`${bold`x`}`` 代替。 ## 官方插件插件 |套餐 |目的 ---|---|--- 会议| `@gramio/session` |持久的每用户数据存储场景| `@gramio/场景` |多步骤对话流程国际化 | `@gramio/i18n` |国际化（TS-native 或 Fluent）自动加载 | `@gramio/自动加载` |基于文件的处理程序加载提示| `@gramio/提示` |交互式单问题提示意见 | `@gramio/views` |可重复使用的消息模板（编程 + JSON）自动重试 | `@gramio/自动重试` |重试 429 速率限制媒体缓存 | `@gramio/媒体缓存` |缓存 file_ids 媒体集团| `@gramio/媒体组` |处理相册消息分裂| `@gramio/split` |分割长消息自动应答 CB | `@gramio/自动应答回调查询` |自动应答回拨邮差猪 | `@gramio/posthog` |分析+功能标志开放遥测| `@gramio/opentelemetry` |分布式追踪和跨度哨兵| `@gramio/哨兵` |错误跟踪+性能监控 ## Telegram Bot API 参考页面 GramIO 文档包含 **每个** Telegram Bot API 方法和类型的专用参考页面： * **方法** ：`https://gramio.dev/telegram/methods/{methodName}` — 例如`sendMessage`、`createChatInviteLink`、`answerCallbackQuery` * **类型** ：`https://gramio.dev/telegram/types/{typeName}` — 例如`消息`、`ChatInviteLink`、`内联键盘` 每个页面包含：GramIO TypeScript 示例、参数详细信息、包含原因和修复的错误表、提示和问题以及相关链接。当用户询问特定的 Telegram API 方法或类型时，您可以获取或引用相应的页面以准确了解 GramIO 特定的用法。 > **LLM 提示：** 通过将 `.md` 附加到 URL：`https://gramio.dev/telegram/methods/sendMessage.md`，任何 GramIO 文档页面都可以作为干净的 Markdown 来获取 - 干净的 Markdown 而不是 HTML。这适用于文档的**所有**部分，而不仅仅是 API 页面。 > 默认情况下，这些页面**不**包含在该技能中 - 当用户询问特定方法/类型时按需获取它们。 **要快速查找存在哪些方法** - 使用预先构建的索引：[telegram-api-index]()。它在一个文件中列出了所有 165 多种 Bot API 方法以及简短说明。当您需要发现方法名称或在获取整页之前确认方法名称存在时，请加载它。 ## 参考文献 ### 核心主题 |描述 |参考 ---|---|--- 机器人配置|构造函数、API 选项、代理、测试 DC、调试 | [机器人配置]() 机器人 API |调用方法、抑制、withRetries、类型帮助程序 | [bot-api]() 背景和更新 |派生、装饰、中间件、启动/停止、类型缩小 | [上下文]() 触发器|命令、听到、callbackQuery、inlineQuery、反应 | [触发器]() 挂钩| onStart、onStop、onError、preRequest、onResponse | [钩子]() 更新和生命周期 |启动/停止选项，正常关闭（SIGINT/SIGTERM） | [更新]() ### 特点主题 |描述 |参考 ---|---|--- 键盘|键盘、内联键盘、布局助手、样式 | [键盘]() 格式化 |实体助手、`join`（绝不是原生的`.join()`！）、变量组合、无`parse_mode` | [格式]() 文件 | MediaUpload、MediaInput、下载、Bun.file() | [文件]() 回调数据 |类型安全的回调数据模式 | [回调数据]() 存储|内存、Redis、Cloudflare 适配器 | [存储]() 电报之星 |付款、发票、订阅、内联发票、退款、测试模式 | [telegram-stars]() 类型 | @gramio/types、类型帮助器、代理包装器、声明合并 | [类型]() ### 基础设施主题 |描述 |参考 ---|---|--- 网络钩子 |框架集成、隧道、自定义处理程序 | [webhook]() 速率限制 | withRetries、广播、队列 | [速率限制]() 码头工人 | Dockerfile、多阶段构建、Docker Compose | [docker]() TMA |迷你应用程序、mkcert HTTPS、@gramio/init-data auth | [tma]() 测试|事件驱动的机器人测试、用户参与者、API 模拟 | [测试]() ### 迁移当用户想要将现有机器人迁移到 GramIO 时加载。来自 |描述 |参考 ---|---|--- 纯格拉姆|符号映射、API 比较、puregram 检查表 → GramIO 重构 | [migration-from-puregram]() 电报|符号映射、上下文类型、场景/WizardScene、webhook 差异、清单 | [migration-from-telegraf]() 节点电报机器人 API |符号映射、中间件概念、键盘构建器、会话、清单 | [从 ntba 迁移]() ### 插件插件 |描述 |参考 ---|---|--- 会议|每用户数据，Redis 支持 | [会话]() 场景|多步骤流程、状态、导航 | [场景]() 国际化 | TS-原生及Fluent国际化| [i18n]() 自动加载 |基于文件的处理程序发现 | [自动加载]() 提示|发送+等待回复| [提示]() 意见 |可重用消息模板、JSON 适配器、i18n | [视图]() 开放遥测|分布式跟踪、跨度、检测 | [opentelemetry]() 哨兵|错误跟踪、性能监控 | [哨兵]() 其他 |自动重试、媒体缓存、媒体组、分割、posthog | [其他]() 插件开发 |编写自定义插件、派生/装饰/错误、延迟加载 | [插件开发]() ### 示例示例|描述 |文件 ---|---|--- 基本机器人 |命令、挂钩、错误处理 | [basic.ts]() 键盘|回复、内嵌、列、条件 | [keyboards.ts]() 回调数据 |类型安全的回调模式 | [callback-data.ts]() 格式化 |实体类型、连接助手、变量组合、parse_mode 反模式 | [formatting.ts]() 文件上传 |路径、URL、缓冲区、媒体组 | [文件上传.ts]() 错误处理 |自定义错误、抑制、范围 | [错误处理.ts]() 网络钩子 |框架整合| [webhook.ts]() 会议|计数器、设置、Redis | [session.ts]() 场景|注册流程及步骤 | [scenes.ts]() 电报之星 |付款、发票、退款 | [telegram-stars.ts]() TMA | Elysia 服务器、init-data auth、webhook | [tma.ts]() 码头工人 |正常关闭、webhook/轮询切换 | [docker.ts]() 测试|用户模拟、API 模拟、错误测试 | [testing.ts]()

格拉姆

包含技能