# @framers/agentos-ext-telegram 中文文档

规范地址：https://npmcn.com/package/%40framers/agentos-ext-telegram/

版本：1\.2\.4
npm 元数据更新时间：2026-11-11T07:56:24.883Z
中文译文更新时间：2026-11-15T12:04:30.191Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40framers/agentos-ext-telegram
原文对照：https://npmcn.com/package/%40framers/agentos-ext-telegram/?lang=original
项目主页：https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/integrations/telegram#readme
源码仓库：https://github.com/framerslab/agentos-extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：125 kB，40 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：@framers/agentos \>=0\.10\.40
- 首次发布：2026-02-06T12:58:05.738Z
- 最新版本发布：2026-11-11T07:56:24.406Z
- 近 30 天下载量：21739（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

Telegram Bot API 集成 AgentOS - 发送消息,管理组,处理回调

## 安装

```sh
npm install @framers/agentos-ext-telegram
```

也可以使用：`pnpm add @framers/agentos-ext-telegram`、`yarn add @framers/agentos-ext-telegram`、`bun add @framers/agentos-ext-telegram`

## README

# AgentOS 的电讯包扩展

AgentOS代理的专业Telegram Bot API集成.

## 特征

-   📤 **信件发送**: 有格式的文本、相片、文档
-   📊 **集团管理**: Pin 消息, 更改设置( 需要管理员)
-   🔍 **聊天信息**: 获取聊天细节和成员数
-   🎛️ **内置键盘**: 处理按钮的回调查询
-   🔐 **弹性 Auth**: 提供bot 令牌的多种方式
-   ⚡ **限制费率**自动队列管理
-   🔄 **网页浏览/投放**: 支持两种模式

## 安装

```bash
npm install @framers/agentos-ext-telegram
```

## 配置

### 环境变量

扩展支持多种方式提供您的 bot 符号 :

```bash
# .env file

# Method 1: Default environment variable
TELEGRAM_BOT_TOKEN=your-bot-token-here

# Method 2: Custom environment variable
MY_TELEGRAM_TOKEN=your-bot-token-here

# Method 3: Multiple bot support
TELEGRAM_MAIN_BOT=token1
TELEGRAM_SUPPORT_BOT=token2
```

### 用法实例

#### 基本设置

```typescript
import { createExtensionPack } from '@framers/agentos-ext-telegram';

// Auto-detect from environment
const telegramExt = createExtensionPack({
  options: {
    // Automatically reads TELEGRAM_BOT_TOKEN
  },
  logger: console
});

// Custom environment variable
const telegramExt = createExtensionPack({
  options: {
    botTokenEnv: 'MY_TELEGRAM_TOKEN'
  }
});

// Direct token (not recommended for production)
const telegramExt = createExtensionPack({
  options: {
    botToken: 'your-token-here'
  }
});
```

#### 高级配置

```typescript
const telegramExt = createExtensionPack({
  options: {
    // Webhook mode (for production)
    webhookUrl: 'https://your-domain.com/telegram-webhook',
    
    // Or polling mode (for development)
    pollingInterval: 300,
    
    // Message formatting
    defaultParseMode: 'Markdown', // or 'HTML'
    enableTypingAction: true,     // Show "typing..." indicator
    
    // Rate limiting
    rateLimit: {
      maxRequests: 30,  // Telegram's limit
      windowMs: 1000    // Per second
    }
  }
});
```

## 可用工具

### 1\. 发送信息

用可选键盘发送格式化的文本消息.

```typescript
const result = await telegramSendMessage.execute({
  chatId: '@mychannel',  // or numeric chat ID
  text: '*Bold* _italic_ `code`',
  parseMode: 'Markdown',
  replyMarkup: {
    inline_keyboard: [[
      { text: 'Button 1', callback_data: 'btn1' },
      { text: 'Button 2', callback_data: 'btn2' }
    ]]
  }
});
```

### 2\. 发送相片

发送带有标题的图像 .

```typescript
const result = await telegramSendPhoto.execute({
  chatId: '@mychannel',
  photo: 'https://example.com/image.jpg', // URL, file path, or base64
  caption: 'Check out this image!',
  parseMode: 'Markdown'
});
```

### 3\. 发送文档

发送任何类型的文件 .

```typescript
const result = await telegramSendDocument.execute({
  chatId: '@mychannel',
  document: './report.pdf', // URL, file path, or base64
  caption: 'Monthly Report',
  filename: 'Report_December_2024.pdf'
});
```

### 4\. 获取聊天信息

获取聊天信息 .

```typescript
const result = await telegramGetChatInfo.execute({
  chatId: '@mychannel',
  includeMemberCount: true
});

// Returns: { id, type, title, username, memberCount }
```

### 5\. 管理组

执行管理动作( 需要bot be admin) .

```typescript
// Pin a message
await telegramManageGroup.execute({
  chatId: -123456789,
  action: 'pinMessage',
  messageId: 42,
  disableNotification: false
});

// Set group description
await telegramManageGroup.execute({
  chatId: -123456789,
  action: 'setDescription',
  text: 'Welcome to our awesome group!'
});
```

### 6\. 回电处理

响应内置键盘按钮按下.

```typescript
const result = await telegramHandleCallback.execute({
  callbackQueryId: 'query123',
  text: 'Button clicked!',
  showAlert: true  // Shows as popup
});
```

## 机构整合

### 多GMI协作

```typescript
// Research GMI finds information
const researcher = await createGMI({
  tools: ['webSearch', 'factCheck']
});

// Communications GMI sends to Telegram
const communicator = await createGMI({
  tools: ['telegramSendMessage', 'telegramSendPhoto']
});

// Workflow orchestrates both
const workflow = {
  tasks: [
    {
      executor: 'researcher',
      tool: 'webSearch',
      inputs: { query: '{{topic}}' }
    },
    {
      executor: 'communicator',
      tool: 'telegramSendMessage',
      inputs: {
        chatId: '{{telegram_channel}}',
        text: '📊 Research Results:\n{{results.research}}'
      }
    }
  ]
};
```

## 处理错误

扩展处理常见的Telegram API出错 :

```typescript
try {
  const result = await tool.execute(args);
  if (!result.success) {
    console.error('Telegram error:', result.error);
    // Handle specific error codes
    if (result.details?.code === 403) {
      console.log('Bot was blocked by user');
    }
  }
} catch (error) {
  console.error('System error:', error);
}
```

## 限制费率

扩展自动管理利率限制 :

-   队列信件以尊重 Telegram 的 30 msg/ sec 限制
-   每个聊天限制的可配置率
-   以指数回放自动重试

## 安保最佳做法

1.  **永远不要硬码的机器人符号** - 使用环境变量
2.  **验证 webhook 签名** 生产
3.  **对用户输入进行保密** 发送前
4.  **使用 HTTPS** 用于网络用户
5.  **限制 Bot 权限** 至最低需求
6.  **虐待监测** 并执行用户费率限制

## 装瓶设置

1.  创建机器人 [@ 父爱 @ info](https://t.me/botfather)
2.  拿回你的宝物
3.  设置机器人命令( 可选) :

```
/start - Start the bot
/help - Show help
/status - Check status
```

4.  需要时配置隐私模式
5.  在有适当权限的组合/通道中添加机器人

## 测试

```typescript
// Mock the Telegram service for testing
const mockService = {
  sendMessage: jest.fn().mockResolvedValue({
    message_id: 1,
    chat: { id: 123 },
    date: Date.now(),
    text: 'Test'
  })
};

const tool = new SendMessageTool(mockService);
const result = await tool.execute({
  chatId: 123,
  text: 'Test message'
}, context);
```

## 解决问题

### 瓶子没有响应

-   检查bot 令牌正确
-   确保不封存机器人
-   验证网络连接
-   检查可访问的 Webhook URL

### 费率限制出错

-   减少消息频率
-   执行信件批量
-   使用队列管理

### 权限错误

-   确保 bot 管理组管理
-   检查频道发布权限
-   校验用户没有屏蔽机器人

## 资源

-   [Telegram Bot API 文档](https://core.telegram.org/bots/api)
-   [瓶装父亲](https://t.me/botfather) - 创建和管理波茨
-   [Telegram Bot 实例](https://github.com/telegram-bot-sdk/telegram-bot-sdk)

## 释放

新版本发表于 [架设层/剂-外延](https://github.com/framerslab/agentos-extensions) 由 GitHub Actions 通过 npm 信任的出版, 并附有出处声明 .

## 许可证

Apache-2.0 - 见 LICENSE 文件

## 常见问题

### @framers/agentos-ext-telegram 是什么？

Telegram Bot API 集成 AgentOS - 发送消息,管理组,处理回调

### 如何安装 @framers/agentos-ext-telegram？

在项目目录运行 npm install @framers/agentos-ext-telegram，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@framers/agentos（\>=0\.10\.40）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @framers/agentos-ext-telegram 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @framers/agentos-ext-telegram 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @framers/agentos-ext-telegram 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @framers/agentos-ext-telegram 可以商用吗？

@framers/agentos-ext-telegram 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @framers/agentos-ext-telegram 的下载量有多少？

根据 npm 官方下载统计，@framers/agentos-ext-telegram 在 2026/10/16 – 2026/11/14 这 30 天内被下载 21,739 次，日均约 725 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @framers/agentos-ext-telegram 还在维护吗？

最新版本 1\.2\.4 发布于 2026/11/11（4 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/02/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。