mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-07-30 12:17:44 +00:00
471 lines
10 KiB
Markdown
471 lines
10 KiB
Markdown
|
# Telegram 生态开发资源索引
|
|||
|
|
|
|||
|
|
## 官方文档
|
|||
|
|
|
|||
|
|
### Bot API
|
|||
|
|
**主文档:** https://core.telegram.org/bots/api
|
|||
|
|
**描述:** Telegram Bot API 完整参考文档
|
|||
|
|
|
|||
|
|
**核心功能：**
|
|||
|
|
- 消息发送和接收
|
|||
|
|
- 媒体文件处理
|
|||
|
|
- 内联模式
|
|||
|
|
- 支付集成
|
|||
|
|
- Webhook 配置
|
|||
|
|
- 游戏和投票
|
|||
|
|
|
|||
|
|
### Mini Apps (Web Apps)
|
|||
|
|
**主文档:** https://core.telegram.org/bots/webapps
|
|||
|
|
**完整平台:** https://docs.telegram-mini-apps.com
|
|||
|
|
**描述:** Telegram 小程序开发文档
|
|||
|
|
|
|||
|
|
**核心功能：**
|
|||
|
|
- WebApp API
|
|||
|
|
- 主题和 UI 控件
|
|||
|
|
- 存储（Cloud/Device/Secure）
|
|||
|
|
- 生物识别认证
|
|||
|
|
- 位置和传感器
|
|||
|
|
- 支付集成
|
|||
|
|
|
|||
|
|
### Telegram API & MTProto
|
|||
|
|
**主文档:** https://core.telegram.org
|
|||
|
|
**描述:** 完整的 Telegram 协议和客户端开发
|
|||
|
|
|
|||
|
|
**核心功能：**
|
|||
|
|
- MTProto 协议
|
|||
|
|
- TDLib 客户端库
|
|||
|
|
- 认证和加密
|
|||
|
|
- 文件操作
|
|||
|
|
- Secret Chats
|
|||
|
|
|
|||
|
|
## 官方 GitHub 仓库
|
|||
|
|
|
|||
|
|
### Bot API 服务器
|
|||
|
|
**仓库:** https://github.com/tdlib/telegram-bot-api
|
|||
|
|
**描述:** Telegram Bot API 服务器实现
|
|||
|
|
**特点:**
|
|||
|
|
- 本地模式部署
|
|||
|
|
- 支持大文件（最高 2000 MB）
|
|||
|
|
- C++ 实现
|
|||
|
|
- TDLib 基础
|
|||
|
|
|
|||
|
|
### Android 客户端
|
|||
|
|
**仓库:** https://github.com/DrKLO/Telegram
|
|||
|
|
**描述:** 官方 Android 客户端源代码
|
|||
|
|
**特点:**
|
|||
|
|
- 完整的 Android 实现
|
|||
|
|
- Material Design
|
|||
|
|
- 可自定义编译
|
|||
|
|
|
|||
|
|
### Desktop 客户端
|
|||
|
|
**仓库:** https://github.com/telegramdesktop/tdesktop
|
|||
|
|
**描述:** 官方桌面客户端 (Windows, macOS, Linux)
|
|||
|
|
**特点:**
|
|||
|
|
- Qt/C++ 实现
|
|||
|
|
- 跨平台支持
|
|||
|
|
- 完整功能
|
|||
|
|
|
|||
|
|
### 官方组织
|
|||
|
|
**组织页面:** https://github.com/orgs/TelegramOfficial/repositories
|
|||
|
|
**包含:**
|
|||
|
|
- Beta 版本
|
|||
|
|
- 支持工具
|
|||
|
|
- 示例代码
|
|||
|
|
|
|||
|
|
## API 方法分类
|
|||
|
|
|
|||
|
|
### 更新管理
|
|||
|
|
- `getUpdates` - 长轮询
|
|||
|
|
- `setWebhook` - 设置 Webhook
|
|||
|
|
- `deleteWebhook` - 删除 Webhook
|
|||
|
|
- `getWebhookInfo` - Webhook 信息
|
|||
|
|
|
|||
|
|
### 消息操作
|
|||
|
|
**发送消息：**
|
|||
|
|
- `sendMessage` - 文本消息
|
|||
|
|
- `sendPhoto` - 图片
|
|||
|
|
- `sendVideo` - 视频
|
|||
|
|
- `sendDocument` - 文档
|
|||
|
|
- `sendAudio` - 音频
|
|||
|
|
- `sendVoice` - 语音
|
|||
|
|
- `sendLocation` - 位置
|
|||
|
|
- `sendVenue` - 地点
|
|||
|
|
- `sendContact` - 联系人
|
|||
|
|
- `sendPoll` - 投票
|
|||
|
|
- `sendDice` - 骰子/飞镖
|
|||
|
|
|
|||
|
|
**编辑消息：**
|
|||
|
|
- `editMessageText` - 编辑文本
|
|||
|
|
- `editMessageCaption` - 编辑标题
|
|||
|
|
- `editMessageMedia` - 编辑媒体
|
|||
|
|
- `editMessageReplyMarkup` - 编辑键盘
|
|||
|
|
- `deleteMessage` - 删除消息
|
|||
|
|
|
|||
|
|
**其他操作：**
|
|||
|
|
- `forwardMessage` - 转发消息
|
|||
|
|
- `copyMessage` - 复制消息
|
|||
|
|
- `sendChatAction` - 发送动作（输入中...）
|
|||
|
|
|
|||
|
|
### 文件操作
|
|||
|
|
- `getFile` - 获取文件信息
|
|||
|
|
- 文件下载 URL: `https://api.telegram.org/file/bot<token>/<file_path>`
|
|||
|
|
- 文件上传：支持 multipart/form-data
|
|||
|
|
- 最大文件：50 MB (标准), 2000 MB (本地 Bot API)
|
|||
|
|
|
|||
|
|
### 内联模式
|
|||
|
|
- `answerInlineQuery` - 响应内联查询
|
|||
|
|
- 结果类型：article, photo, gif, video, audio, voice, document, location, venue, contact, game, sticker
|
|||
|
|
|
|||
|
|
### 回调查询
|
|||
|
|
- `answerCallbackQuery` - 响应按钮点击
|
|||
|
|
- 可显示通知或警告
|
|||
|
|
|
|||
|
|
### 支付
|
|||
|
|
- `sendInvoice` - 发送发票
|
|||
|
|
- `answerPreCheckoutQuery` - 预结账
|
|||
|
|
- `answerShippingQuery` - 配送查询
|
|||
|
|
- 支持提供商：Stripe, Yandex.Money, Telegram Stars
|
|||
|
|
|
|||
|
|
### 游戏
|
|||
|
|
- `sendGame` - 发送游戏
|
|||
|
|
- `setGameScore` - 设置分数
|
|||
|
|
- `getGameHighScores` - 获取排行榜
|
|||
|
|
|
|||
|
|
### 群组管理
|
|||
|
|
- `kickChatMember` / `unbanChatMember` - 封禁/解封
|
|||
|
|
- `restrictChatMember` - 限制权限
|
|||
|
|
- `promoteChatMember` - 提升管理员
|
|||
|
|
- `setChatTitle` / `setChatDescription` - 设置信息
|
|||
|
|
- `setChatPhoto` - 设置头像
|
|||
|
|
- `pinChatMessage` / `unpinChatMessage` - 置顶消息
|
|||
|
|
|
|||
|
|
## Mini Apps API 详解
|
|||
|
|
|
|||
|
|
### 初始化
|
|||
|
|
```javascript
|
|||
|
|
const tg = window.Telegram.WebApp;
|
|||
|
|
tg.ready();
|
|||
|
|
tg.expand();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 主要对象
|
|||
|
|
- **WebApp** - 主接口
|
|||
|
|
- **MainButton** - 主按钮
|
|||
|
|
- **SecondaryButton** - 次要按钮
|
|||
|
|
- **BackButton** - 返回按钮
|
|||
|
|
- **SettingsButton** - 设置按钮
|
|||
|
|
- **HapticFeedback** - 触觉反馈
|
|||
|
|
- **CloudStorage** - 云存储
|
|||
|
|
- **BiometricManager** - 生物识别
|
|||
|
|
- **LocationManager** - 位置服务
|
|||
|
|
- **Accelerometer** - 加速度计
|
|||
|
|
- **Gyroscope** - 陀螺仪
|
|||
|
|
- **DeviceOrientation** - 设备方向
|
|||
|
|
|
|||
|
|
### 事件系统
|
|||
|
|
40+ 事件包括：
|
|||
|
|
- `themeChanged` - 主题改变
|
|||
|
|
- `viewportChanged` - 视口改变
|
|||
|
|
- `mainButtonClicked` - 主按钮点击
|
|||
|
|
- `backButtonClicked` - 返回按钮点击
|
|||
|
|
- `settingsButtonClicked` - 设置按钮点击
|
|||
|
|
- `invoiceClosed` - 支付完成
|
|||
|
|
- `popupClosed` - 弹窗关闭
|
|||
|
|
- `qrTextReceived` - 扫码结果
|
|||
|
|
- `clipboardTextReceived` - 剪贴板文本
|
|||
|
|
- `writeAccessRequested` - 写入权限请求
|
|||
|
|
- `contactRequested` - 联系人请求
|
|||
|
|
|
|||
|
|
### 主题参数
|
|||
|
|
```javascript
|
|||
|
|
tg.themeParams = {
|
|||
|
|
bg_color, // 背景色
|
|||
|
|
text_color, // 文本色
|
|||
|
|
hint_color, // 提示色
|
|||
|
|
link_color, // 链接色
|
|||
|
|
button_color, // 按钮色
|
|||
|
|
button_text_color, // 按钮文本色
|
|||
|
|
secondary_bg_color, // 次要背景色
|
|||
|
|
header_bg_color, // 头部背景色
|
|||
|
|
accent_text_color, // 强调文本色
|
|||
|
|
section_bg_color, // 区块背景色
|
|||
|
|
section_header_text_color, // 区块头文本色
|
|||
|
|
subtitle_text_color, // 副标题色
|
|||
|
|
destructive_text_color // 危险操作色
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 开发工具
|
|||
|
|
|
|||
|
|
### @BotFather 命令
|
|||
|
|
创建和管理 Bot 的核心工具：
|
|||
|
|
|
|||
|
|
**Bot 管理：**
|
|||
|
|
- `/newbot` - 创建新 Bot
|
|||
|
|
- `/mybots` - 管理我的 Bots
|
|||
|
|
- `/deletebot` - 删除 Bot
|
|||
|
|
- `/token` - 重新生成 token
|
|||
|
|
|
|||
|
|
**设置命令：**
|
|||
|
|
- `/setname` - 设置名称
|
|||
|
|
- `/setdescription` - 设置描述
|
|||
|
|
- `/setabouttext` - 设置关于文本
|
|||
|
|
- `/setuserpic` - 设置头像
|
|||
|
|
|
|||
|
|
**功能配置：**
|
|||
|
|
- `/setcommands` - 设置命令列表
|
|||
|
|
- `/setinline` - 启用内联模式
|
|||
|
|
- `/setinlinefeedback` - 内联反馈
|
|||
|
|
- `/setjoingroups` - 允许加入群组
|
|||
|
|
- `/setprivacy` - 隐私模式
|
|||
|
|
|
|||
|
|
**支付和游戏：**
|
|||
|
|
- `/setgamescores` - 游戏分数
|
|||
|
|
- `/setpayments` - 配置支付
|
|||
|
|
|
|||
|
|
**Mini Apps：**
|
|||
|
|
- `/newapp` - 创建 Mini App
|
|||
|
|
- `/myapps` - 管理 Mini Apps
|
|||
|
|
- `/setmenubutton` - 设置菜单按钮
|
|||
|
|
|
|||
|
|
### API ID 获取
|
|||
|
|
访问 https://my.telegram.org
|
|||
|
|
1. 登录账号
|
|||
|
|
2. 进入 API development tools
|
|||
|
|
3. 创建应用
|
|||
|
|
4. 获取 API ID 和 API Hash
|
|||
|
|
|
|||
|
|
## 常用 Python 库
|
|||
|
|
|
|||
|
|
### python-telegram-bot
|
|||
|
|
```bash
|
|||
|
|
pip install python-telegram-bot
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**特点：**
|
|||
|
|
- 完整的 Bot API 包装
|
|||
|
|
- 异步和同步支持
|
|||
|
|
- 丰富的扩展
|
|||
|
|
- 活跃维护
|
|||
|
|
|
|||
|
|
**基础示例：**
|
|||
|
|
```python
|
|||
|
|
from telegram import Update
|
|||
|
|
from telegram.ext import Application, CommandHandler, ContextTypes
|
|||
|
|
|
|||
|
|
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
|
|||
|
|
await update.message.reply_text('你好！')
|
|||
|
|
|
|||
|
|
app = Application.builder().token("TOKEN").build()
|
|||
|
|
app.add_handler(CommandHandler("start", start))
|
|||
|
|
app.run_polling()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### aiogram
|
|||
|
|
```bash
|
|||
|
|
pip install aiogram
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**特点：**
|
|||
|
|
- 纯异步
|
|||
|
|
- 高性能
|
|||
|
|
- FSM 状态机
|
|||
|
|
- 中间件系统
|
|||
|
|
|
|||
|
|
### Telethon / Pyrogram
|
|||
|
|
MTProto 客户端库：
|
|||
|
|
```bash
|
|||
|
|
pip install telethon
|
|||
|
|
pip install pyrogram
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**用途：**
|
|||
|
|
- 自定义客户端
|
|||
|
|
- 用户账号自动化
|
|||
|
|
- 完整 Telegram 功能
|
|||
|
|
|
|||
|
|
## 常用 Node.js 库
|
|||
|
|
|
|||
|
|
### node-telegram-bot-api
|
|||
|
|
```bash
|
|||
|
|
npm install node-telegram-bot-api
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Telegraf
|
|||
|
|
```bash
|
|||
|
|
npm install telegraf
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**特点：**
|
|||
|
|
- 现代化
|
|||
|
|
- 中间件架构
|
|||
|
|
- TypeScript 支持
|
|||
|
|
|
|||
|
|
### grammY
|
|||
|
|
```bash
|
|||
|
|
npm install grammy
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**特点：**
|
|||
|
|
- 轻量级
|
|||
|
|
- 类型安全
|
|||
|
|
- 插件生态
|
|||
|
|
|
|||
|
|
## 部署选项
|
|||
|
|
|
|||
|
|
### Webhook 托管
|
|||
|
|
**推荐平台：**
|
|||
|
|
- Heroku
|
|||
|
|
- AWS Lambda
|
|||
|
|
- Google Cloud Functions
|
|||
|
|
- Azure Functions
|
|||
|
|
- Vercel
|
|||
|
|
- Railway
|
|||
|
|
- Render
|
|||
|
|
|
|||
|
|
**要求：**
|
|||
|
|
- HTTPS 支持
|
|||
|
|
- 公网可访问
|
|||
|
|
- 支持的端口：443, 80, 88, 8443
|
|||
|
|
|
|||
|
|
### 长轮询托管
|
|||
|
|
**推荐平台：**
|
|||
|
|
- VPS (Vultr, DigitalOcean, Linode)
|
|||
|
|
- Raspberry Pi
|
|||
|
|
- 本地服务器
|
|||
|
|
|
|||
|
|
**优点：**
|
|||
|
|
- 无需 HTTPS
|
|||
|
|
- 简单配置
|
|||
|
|
- 适合开发测试
|
|||
|
|
|
|||
|
|
## 安全最佳实践
|
|||
|
|
|
|||
|
|
1. **Token 安全**
|
|||
|
|
- 不要提交到 Git
|
|||
|
|
- 使用环境变量
|
|||
|
|
- 定期轮换
|
|||
|
|
|
|||
|
|
2. **数据验证**
|
|||
|
|
- 验证 initData
|
|||
|
|
- 服务器端验证
|
|||
|
|
- 不信任客户端
|
|||
|
|
|
|||
|
|
3. **权限控制**
|
|||
|
|
- 检查用户权限
|
|||
|
|
- 管理员验证
|
|||
|
|
- 群组权限
|
|||
|
|
|
|||
|
|
4. **速率限制**
|
|||
|
|
- 实现请求限制
|
|||
|
|
- 防止滥用
|
|||
|
|
- 监控异常
|
|||
|
|
|
|||
|
|
## 调试技巧
|
|||
|
|
|
|||
|
|
### Bot 调试
|
|||
|
|
```python
|
|||
|
|
import logging
|
|||
|
|
logging.basicConfig(level=logging.DEBUG)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Mini App 调试
|
|||
|
|
```javascript
|
|||
|
|
// 开启调试模式
|
|||
|
|
tg.showAlert(JSON.stringify(tg.initDataUnsafe, null, 2));
|
|||
|
|
|
|||
|
|
// 控制台日志
|
|||
|
|
console.log('WebApp version:', tg.version);
|
|||
|
|
console.log('Platform:', tg.platform);
|
|||
|
|
console.log('Theme:', tg.colorScheme);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Webhook 测试
|
|||
|
|
使用 ngrok 本地测试：
|
|||
|
|
```bash
|
|||
|
|
ngrok http 5000
|
|||
|
|
# 将生成的 https URL 设置为 webhook
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 社区资源
|
|||
|
|
|
|||
|
|
- **Telegram 开发者群组**: @BotDevelopers
|
|||
|
|
- **Telegram API 讨论**: @TelegramBots
|
|||
|
|
- **Mini Apps 讨论**: @WebAppChat
|
|||
|
|
|
|||
|
|
## 更新日志
|
|||
|
|
|
|||
|
|
**最新功能：**
|
|||
|
|
- Paid Media (付费媒体)
|
|||
|
|
- Checklist Tasks (检查列表任务)
|
|||
|
|
- Gift Conversion (礼物转换)
|
|||
|
|
- Business Features (商业功能)
|
|||
|
|
- Poll 选项增加到 12 个
|
|||
|
|
- Story 发布和编辑
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 完整实现模板 (新增)
|
|||
|
|
|
|||
|
|
### Telegram Bot 按钮和键盘实现指南
|
|||
|
|
**文件:** `Telegram_Bot_按钮和键盘实现模板.md`
|
|||
|
|
**行数:** 404 行
|
|||
|
|
**大小:** 12 KB
|
|||
|
|
**语言:** 中文
|
|||
|
|
|
|||
|
|
精简实用的 Telegram Bot 交互式功能实现指南：
|
|||
|
|
|
|||
|
|
**核心内容：**
|
|||
|
|
- 三种按钮类型详解（Inline/Reply/Command Menu）
|
|||
|
|
- python-telegram-bot 和 Telethon 双实现对比
|
|||
|
|
- 完整的代码示例（即拿即用）
|
|||
|
|
- 项目结构和模块化设计
|
|||
|
|
- Handler 优先级和事件处理
|
|||
|
|
- 生产环境部署方案
|
|||
|
|
- 安全和错误处理最佳实践
|
|||
|
|
|
|||
|
|
**特色：**
|
|||
|
|
- 核心代码精简，去除冗余示例
|
|||
|
|
- 聚焦常用场景和实用技巧
|
|||
|
|
- 完整的快速参考表
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 动态视图对齐 - 数据展示指南
|
|||
|
|
**文件:** `动态视图对齐实现文档.md`
|
|||
|
|
**行数:** 407 行
|
|||
|
|
**大小:** 12 KB
|
|||
|
|
**语言:** 中文
|
|||
|
|
|
|||
|
|
专业的等宽字体数据对齐和格式化方案：
|
|||
|
|
|
|||
|
|
**核心功能：**
|
|||
|
|
- 智能动态视图对齐算法（三步法）
|
|||
|
|
- 自动计算列宽，无需硬编码
|
|||
|
|
- 智能对齐规则（文本左，数字右）
|
|||
|
|
- 完整的格式化系统：
|
|||
|
|
- 交易量智能缩写（B/M/K）
|
|||
|
|
- 价格智能精度（自适应小数位）
|
|||
|
|
- 涨跌幅格式化（+/- 符号）
|
|||
|
|
- 资金流向智能显示
|
|||
|
|
|
|||
|
|
**应用场景：**
|
|||
|
|
- 排行榜、数据表格、实时行情
|
|||
|
|
- 任何需要专业数据展示的 Telegram Bot
|
|||
|
|
|
|||
|
|
**技术特点：**
|
|||
|
|
- O(n×m) 线性复杂度，高效实用
|
|||
|
|
- 1000 行数据处理仅需 5-10ms
|
|||
|
|
- 支持中文字符宽度扩展
|
|||
|
|
|
|||
|
|
**视觉效果示例：**
|
|||
|
|
```
|
|||
|
|
1. BTC $1.23B $45,000 +5.23%
|
|||
|
|
2. ETH $890.5M $2,500 +3.12%
|
|||
|
|
3. SOL $567.8M $101 +8.45%
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**这些模板提供了从基础到生产级别的完整 Telegram Bot 开发解决方案！**
|