docs: align en/ structure with main README

- Simplify language badges (zh, en, more languages) - Add X badge @123olp - Reorganize prompts: 00-meta, 01-system, 02-coding, 03-user - Reorganize skills: 00-meta, 01-ai-tools, 02-databases, 03-crypto, 04-dev-tools - Update all path references
2026-08-22 15:28:05 +00:00 · 2025-12-19 17:14:13 +08:00
parent 34ebb432f2
commit aa6d2e89eb
206 changed files with 846 additions and 310 deletions
@@ -0,0 +1,760 @@
+---
+name: telegram-dev
+description: A full-stack guide to Telegram ecosystem development - covering Bot API, Mini Apps (Web Apps), and MTProto client development. Includes complete development resources for message handling, payments, inline mode, webhooks, authentication, storage, sensor APIs, and more.
+---
+
+# Telegram Ecosystem Development Skill
+
+A comprehensive guide to Telegram development, covering the full technology stack for Bot development, Mini Apps (Web Apps), and client development.
+
+## When to Use This Skill
+
+Use this skill when you need help with the following:
+- Developing a Telegram Bot (message bot)
+- Creating Telegram Mini Apps
+- Building a custom Telegram client
+- Integrating Telegram payments and business features
+- Implementing webhooks and long polling
+- Using Telegram authentication and storage
+- Handling messages, media, and files
+- Implementing inline mode and keyboards
+
+## Overview of the Telegram Development Ecosystem
+
+### Three Core APIs
+
+1.  **Bot API** - For creating bot programs
+    -   Simple to use HTTP interface
+    -   Automatically handles encryption and communication
+    -   Suitable for: chatbots, automation tools
+
+2.  **Mini Apps API** (Web Apps) - For creating web applications
+    -   JavaScript interface
+    -   Runs inside Telegram
+    -   Suitable for: mini-apps, games, e-commerce
+
+3.  **Telegram API & TDLib** - For creating clients
+    -   Full implementation of the Telegram protocol
+    -   Supports all platforms
+    -   Suitable for: custom clients, enterprise applications
+
+## Bot API Development
+
+### Quick Start
+
+**API Endpoint:**
+```
+https://api.telegram.org/bot<TOKEN>/METHOD_NAME
+```
+
+**Get a Bot Token:**
+1.  Talk to @BotFather
+2.  Send `/newbot`
+3.  Follow the prompts to set a name
+4.  Get the token
+
+**First Bot (Python):**
+```python
+import requests
+
+BOT_TOKEN = "your_bot_token_here"
+API_URL = f"https://api.telegram.org/bot{BOT_TOKEN}"
+
+# Send a message
+def send_message(chat_id, text):
+    url = f"{API_URL}/sendMessage"
+    data = {"chat_id": chat_id, "text": text}
+    return requests.post(url, json=data)
+
+# Get updates (long polling)
+def get_updates(offset=None):
+    url = f"{API_URL}/getUpdates"
+    params = {"offset": offset, "timeout": 30}
+    return requests.get(url, params=params).json()
+
+# Main loop
+offset = None
+while True:
+    updates = get_updates(offset)
+    for update in updates.get("result", []):
+        chat_id = update["message"]["chat"]["id"]
+        text = update["message"]["text"]
+        
+        # Reply to the message
+        send_message(chat_id, f"You said: {text}")
+        
+        offset = update["update_id"] + 1
+```
+
+### Core API Methods
+
+**Update Management:**
+- `getUpdates` - Get updates via long polling
+- `setWebhook` - Set a webhook
+- `deleteWebhook` - Delete a webhook
+- `getWebhookInfo` - Query webhook status
+
+**Message Operations:**
+- `sendMessage` - Send a text message
+- `sendPhoto` / `sendVideo` / `sendDocument` - Send media
+- `sendAudio` / `sendVoice` - Send audio
+- `sendLocation` / `sendVenue` - Send a location
+- `editMessageText` - Edit a message
+- `deleteMessage` - Delete a message
+- `forwardMessage` / `copyMessage` - Forward/copy a message
+
+**Interactive Elements:**
+- `sendPoll` - Send a poll (up to 12 options)
+- Inline Keyboard (InlineKeyboardMarkup)
+- Reply Keyboard (ReplyKeyboardMarkup)
+- `answerCallbackQuery` - Respond to a callback query
+
+**File Operations:**
+- `getFile` - Get file information
+- `downloadFile` - Download a file
+- Supports files up to 2GB (in local Bot API mode)
+
+**Payment Features:**
+- `sendInvoice` - Send an invoice
+- `answerPreCheckoutQuery` - Process a payment
+- Telegram Stars payment (up to 10,000 Stars)
+
+### Webhook Configuration
+
+**Set a Webhook:**
+```python
+import requests
+
+BOT_TOKEN = "your_token"
+WEBHOOK_URL = "https://yourdomain.com/webhook"
+
+requests.post(
+    f"https://api.telegram.org/bot{BOT_TOKEN}/setWebhook",
+    json={"url": WEBHOOK_URL}
+)
+```
+
+**Flask Webhook Example:**
+```python
+from flask import Flask, request
+import requests
+
+app = Flask(__name__)
+BOT_TOKEN = "your_token"
+
+@app.route('/webhook', methods=['POST'])
+def webhook():
+    update = request.get_json()
+    
+    chat_id = update["message"]["chat"]["id"]
+    text = update["message"]["text"]
+    
+    # Send a reply
+    requests.post(
+        f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
+        json={"chat_id": chat_id, "text": f"Received: {text}"}
+    )
+    
+    return "OK"
+
+if __name__ == '__main__':
+    app.run(port=5000)
+```
+
+**Webhook Requirements:**
+- Must use HTTPS
+- Supports TLS 1.2+
+- Ports: 443, 80, 88, 8443
+- Publicly accessible URL
+
+### Inline Keyboard
+
+**Create an Inline Keyboard:**
+```python
+def send_inline_keyboard(chat_id):
+    keyboard = {
+        "inline_keyboard": [
+            [
+                {"text": "Button 1", "callback_data": "btn1"},
+                {"text": "Button 2", "callback_data": "btn2"}
+            ],
+            [
+                {"text": "Open Link", "url": "https://example.com"}
+            ]
+        ]
+    }
+    
+    requests.post(
+        f"{API_URL}/sendMessage",
+        json={
+            "chat_id": chat_id,
+            "text": "Choose an option:",
+            "reply_markup": keyboard
+        }
+    )
+```
+
+**Handle Callbacks:**
+```python
+def handle_callback_query(callback_query):
+    query_id = callback_query["id"]
+    data = callback_query["data"]
+    chat_id = callback_query["message"]["chat"]["id"]
+    
+    # Respond to the callback
+    requests.post(
+        f"{API_URL}/answerCallbackQuery",
+        json={"callback_query_id": query_id, "text": f"You clicked {data}"}
+    )
+    
+    # Update the message
+    requests.post(
+        f"{API_URL}/editMessageText",
+        json={
+            "chat_id": chat_id,
+            "message_id": callback_query["message"]["message_id"],
+            "text": f"You chose: {data}"
+        }
+    )
+```
+
+### Inline Mode
+
+**Configure Inline Mode:**
+Talk to @BotFather and send `/setinline`
+
+**Handle Inline Queries:**
+```python
+def handle_inline_query(inline_query):
+    query_id = inline_query["id"]
+    query_text = inline_query["query"]
+    
+    # Create results
+    results = [
+        {
+            "type": "article",
+            "id": "1",
+            "title": "Result 1",
+            "input_message_content": {
+                "message_text": f"You searched for: {query_text}"
+            }
+        }
+    ]
+    
+    requests.post(
+        f"{API_URL}/answerInlineQuery",
+        json={"inline_query_id": query_id, "results": results}
+    )
+```
+
+## Mini Apps (Web Apps) Development
+
+### Initialize a Mini App
+
+**HTML Template:**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <script src="https://telegram.org/js/telegram-web-app.js"></script>
+    <title>My Mini App</title>
+</head>
+<body>
+    <h1>Telegram Mini App</h1>
+    <button id="mainBtn">Main Button</button>
+    
+    <script>
+        // Get the Telegram WebApp object
+        const tg = window.Telegram.WebApp;
+        
+        // Notify Telegram that the app is ready
+        tg.ready();
+        
+        // Expand to full screen
+        tg.expand();
+        
+        // Display user information
+        const user = tg.initDataUnsafe?.user;
+        if (user) {
+            console.log("Username:", user.first_name);
+            console.log("User ID:", user.id);
+        }
+        
+        // Configure the main button
+        tg.MainButton.text = "Submit";
+        tg.MainButton.show();
+        tg.MainButton.onClick(() => {
+            // Send data to the Bot
+            tg.sendData(JSON.stringify({action: "submit"}));
+        });
+        
+        // Add a back button
+        tg.BackButton.show();
+        tg.BackButton.onClick(() => {
+            tg.close();
+        });
+    </script>
+</body>
+</html>
+```
+
+### Mini App Core API
+
+**WebApp Object Main Properties:**
+```javascript
+// Initialization data
+tg.initData           // Raw initialization string
+tg.initDataUnsafe     // Parsed object
+
+// User and theme
+tg.initDataUnsafe.user       // User information
+tg.themeParams                // Theme colors
+tg.colorScheme                // 'light' or 'dark'
+
+// Status
+tg.isExpanded         // Whether it's full screen
+tg.isFullscreen       // Whether it's full screen
+tg.viewportHeight     // Viewport height
+tg.platform           // Platform type
+
+// Version
+tg.version            // WebApp version
+```
+
+**Main Methods:**
+```javascript
+// Window control
+tg.ready()            // Mark the app as ready
+tg.expand()           // Expand to full height
+tg.close()            // Close the Mini App
+tg.requestFullscreen() // Request full screen
+
+// Data sending
+tg.sendData(data)     // Send data to the Bot
+
+// Navigation
+tg.openLink(url)      // Open an external link
+tg.openTelegramLink(url) // Open a Telegram link
+
+// Dialogs
+tg.showPopup(params, callback)  // Show a popup
+tg.showAlert(message)           // Show an alert
+tg.showConfirm(message)         // Show a confirmation
+
+// Sharing
+tg.shareMessage(message)        // Share a message
+tg.shareUrl(url)                // Share a link
+```
+
+### UI Controls
+
+**Main Button (MainButton):**
+```javascript
+tg.MainButton.setText("Click Me");
+tg.MainButton.show();
+tg.MainButton.enable();
+tg.MainButton.showProgress();  // Show loading
+tg.MainButton.hideProgress();
+
+tg.MainButton.onClick(() => {
+    console.log("Main button clicked");
+});
+```
+
+**Secondary Button (SecondaryButton):**
+```javascript
+tg.SecondaryButton.setText("Cancel");
+tg.SecondaryButton.show();
+tg.SecondaryButton.onClick(() => {
+    tg.close();
+});
+```
+
+**Back Button (BackButton):**
+```javascript
+tg.BackButton.show();
+tg.BackButton.onClick(() => {
+    // Back logic
+});
+```
+
+**Haptic Feedback:**
+```javascript
+tg.HapticFeedback.impactOccurred('light');  // light, medium, heavy
+tg.HapticFeedback.notificationOccurred('success'); // success, warning, error
+tg.HapticFeedback.selectionChanged();
+```
+
+### Storage API
+
+**Cloud Storage:**
+```javascript
+// Save data
+tg.CloudStorage.setItem('key', 'value', (error, success) => {
+    if (success) console.log('Saved successfully');
+});
+
+// Get data
+tg.CloudStorage.getItem('key', (error, value) => {
+    console.log('Value:', value);
+});
+
+// Delete data
+tg.CloudStorage.removeItem('key');
+
+// Get all keys
+tg.CloudStorage.getKeys((error, keys) => {
+    console.log('All keys:', keys);
+});
+```
+
+**Local Storage:**
+```javascript
+// Normal local storage
+localStorage.setItem('key', 'value');
+const value = localStorage.getItem('key');
+
+// Secure storage (requires biometrics)
+tg.SecureStorage.setItem('secret', 'value', callback);
+tg.SecureStorage.getItem('secret', callback);
+```
+
+### Biometric Authentication
+
+```javascript
+const bioManager = tg.BiometricManager;
+
+// Initialize
+bioManager.init(() => {
+    if (bioManager.isInited) {
+        console.log('Supported type:', bioManager.biometricType);
+        // 'finger', 'face', 'unknown'
+        
+        if (bioManager.isAccessGranted) {
+            // Already authorized, can be used
+        } else {
+            // Request authorization
+            bioManager.requestAccess({reason: 'Need to verify identity'}, (success) => {
+                if (success) {
+                    console.log('Authorization successful');
+                }
+            });
+        }
+    }
+});
+
+// Perform authentication
+bioManager.authenticate({reason: 'Confirm action'}, (success, token) => {
+    if (success) {
+        console.log('Authentication successful, token:', token);
+    }
+});
+```
+
+### Location and Sensors
+
+**Get Location:**
+```javascript
+tg.LocationManager.init(() => {
+    if (tg.LocationManager.isInited) {
+        tg.LocationManager.getLocation((location) => {
+            console.log('Latitude:', location.latitude);
+            console.log('Longitude:', location.longitude);
+        });
+    }
+});
+```
+
+**Accelerometer:**
+```javascript
+tg.Accelerometer.start({refresh_rate: 100}, (started) => {
+    if (started) {
+        tg.Accelerometer.onEvent((event) => {
+            console.log('Acceleration:', event.x, event.y, event.z);
+        });
+    }
+});
+
+// Stop
+tg.Accelerometer.stop();
+```
+
+**Gyroscope:**
+```javascript
+tg.Gyroscope.start({refresh_rate: 100}, callback);
+tg.Gyroscope.onEvent((event) => {
+    console.log('Rotation speed:', event.x, event.y, event.z);
+});
+```
+
+**Device Orientation:**
+```javascript
+tg.DeviceOrientation.start({refresh_rate: 100}, callback);
+tg.DeviceOrientation.onEvent((event) => {
+    console.log('Orientation:', event.absolute, event.alpha, event.beta, event.gamma);
+});
+```
+
+### Payment Integration
+
+**Initiate a Payment (Telegram Stars):**
+```javascript
+tg.openInvoice('https://t.me/$invoice_link', (status) => {
+    if (status === 'paid') {
+        console.log('Payment successful');
+    } else if (status === 'cancelled') {
+        console.log('Payment cancelled');
+    } else if (status === 'failed') {
+        console.log('Payment failed');
+    }
+});
+```
+
+### Data Validation
+
+**Server-side Validation of initData (Python):**
+```python
+import hmac
+import hashlib
+from urllib.parse import parse_qs
+
+def validate_init_data(init_data, bot_token):
+    # Parse the data
+    parsed = parse_qs(init_data)
+    received_hash = parsed.get('hash', [''])[0]
+    
+    # Remove the hash
+    data_check_arr = []
+    for key, value in parsed.items():
+        if key != 'hash':
+            data_check_arr.append(f"{key}={value[0]}")
+    
+    # Sort
+    data_check_arr.sort()
+    data_check_string = '\n'.join(data_check_arr)
+    
+    # Calculate the secret key
+    secret_key = hmac.new(
+        b"WebAppData",
+        bot_token.encode(),
+        hashlib.sha256
+    ).digest()
+    
+    # Calculate the hash
+    calculated_hash = hmac.new(
+        secret_key,
+        data_check_string.encode(),
+        hashlib.sha256
+    ).hexdigest()
+    
+    return calculated_hash == received_hash
+```
+
+### Launching a Mini App
+
+**From a Keyboard Button:**
+```python
+keyboard = {
+    "keyboard": [[ 
+        {
+            "text": "Open App",
+            "web_app": {"url": "https://yourdomain.com/app"}
+        }
+    ]],
+    "resize_keyboard": True
+}
+
+requests.post(
+    f"{API_URL}/sendMessage",
+    json={
+        "chat_id": chat_id,
+        "text": "Click the button to open the app",
+        "reply_markup": keyboard
+    }
+)
+```
+
+**From an Inline Button:**
+```python
+keyboard = {
+    "inline_keyboard": [[
+        {
+            "text": "Launch App",
+            "web_app": {"url": "https://yourdomain.com/app"}
+        }
+    ]]
+}
+```
+
+**From the Menu Button:**
+Talk to @BotFather:
+```
+/setmenubutton
+→ Choose your Bot
+→ Provide URL: https://yourdomain.com/app
+```
+
+## Client Development (TDLib)
+
+### Using TDLib
+
+**Python Example (python-telegram):**
+```python
+from telegram.client import Telegram
+
+tg = Telegram(
+    api_id='your_api_id',
+    api_hash='your_api_hash',
+    phone='+1234567890',
+    database_encryption_key='changeme1234',
+)
+
+tg.login()
+
+# Send a message
+result = tg.send_message(
+    chat_id=123456789,
+    text='Hello from TDLib!'
+)
+
+# Get chat list
+result = tg.get_chats()
+result.wait()
+chats = result.update
+
+print(chats)
+
+tg.stop()
+```
+
+### MTProto Protocol
+
+**Features:**
+- End-to-end encryption
+- High performance
+- Supports all Telegram features
+- Requires API ID/Hash (from https://my.telegram.org)
+
+## Best Practices
+
+### Bot Development
+
+1.  **Error Handling**
+    ```python
+    try:
+        response = requests.post(url, json=data, timeout=10)
+        response.raise_for_status()
+    except requests.exceptions.RequestException as e:
+        print(f"Request failed: {e}")
+    ```
+
+2.  **Rate Limiting**
+    -   Group messages: max 20/minute
+    -   Private messages: max 30/second
+    -   Global limits: avoid being too frequent
+
+3.  **Use Webhooks instead of Long Polling**
+    -   More efficient
+    -   Lower latency
+    -   Better scalability
+
+4.  **Data Validation**
+    -   Always validate initData
+    -   Don't trust client-side data
+    -   Server-side validation for all operations
+
+### Mini Apps Development
+
+1.  **Responsive Design**
+    ```javascript
+    // Listen for theme changes
+    tg.onEvent('themeChanged', () => {
+        document.body.style.backgroundColor = tg.themeParams.bg_color;
+    });
+    
+    // Listen for viewport changes
+    tg.onEvent('viewportChanged', () => {
+        console.log('New height:', tg.viewportHeight);
+    });
+    ```
+
+2.  **Performance Optimization**
+    -   Minimize JavaScript bundle size
+    -   Use lazy loading
+    -   Optimize images and resources
+
+3.  **User Experience**
+    -   Adapt to dark/light themes
+    -   Use native UI controls (MainButton, etc.)
+    -   Provide haptic feedback
+    -   Respond quickly to user actions
+
+4.  **Security Considerations**
+    -   HTTPS is mandatory
+    -   Validate initData
+    -   Don't store sensitive information on the client
+    -   Use SecureStorage for secrets
+
+## Common Libraries and Tools
+
+### Python
+- `python-telegram-bot` - A powerful Bot framework
+- `aiogram` - An asynchronous Bot framework
+- `telethon` / `pyrogram` - MTProto clients
+
+### Node.js
+- `node-telegram-bot-api` - Bot API wrapper
+- `telegraf` - Modern Bot framework
+- `grammy` - Lightweight framework
+
+### Other Languages
+- PHP: `telegram-bot-sdk`
+- Go: `telegram-bot-api`
+- Java: `TelegramBots`
+- C#: `Telegram.Bot`
+
+## Reference Resources
+
+### Official Documentation
+- Bot API: https://core.telegram.org/bots/api
+- Mini Apps: https://core.telegram.org/bots/webapps
+- Mini Apps Platform: https://docs.telegram-mini-apps.com
+- Telegram API: https://core.telegram.org
+
+### GitHub Repositories
+- Bot API Server: https://github.com/tdlib/telegram-bot-api
+- Android Client: https://github.com/DrKLO/Telegram
+- Desktop Client: https://github.com/telegramdesktop/tdesktop
+- Official Organization: https://github.com/orgs/TelegramOfficial/repositories
+
+### Tools
+- @BotFather - Create and manage Bots
+- https://my.telegram.org - Get API ID/Hash
+- Telegram Web App test environment
+
+## Reference Files
+
+This skill includes a detailed index of Telegram development resources and complete implementation templates:
+
+- **index.md** - A complete index of resources and quick navigation
+- **Telegram_Bot_按钮和键盘实现模板.md** - An implementation guide for interactive buttons and keyboards (404 lines, 12 KB)
+  - Detailed explanation of three button types (Inline/Reply/Command Menu)
+  - Comparison of implementations with python-telegram-bot and Telethon
+  - Complete ready-to-use code examples and project structure
+  - Handler system, error handling, and deployment方案
+- **动态视图对齐实现文档.md** - A guide to data display in Telegram (407 lines, 12 KB)
+  - Intelligent dynamic alignment algorithm (three-step method, O(n×m) complexity)
+  - Perfect alignment solution for monospaced font environments
+  - Intelligent numerical formatting system (automatic B/M/K abbreviation)
+  - Professional display for leaderboards and data tables
+
+These concise guides provide core solutions for Telegram Bot development:
+- All implementation methods for button and keyboard interaction
+- Professional formatting and display of messages and data
+- Practical best practices and quick references
+
+---
+
+**Master full-stack development of the Telegram ecosystem with this skill!**