chore: migrate repository to standard knowledge base layout

2026-08-18 21:38:05 +00:00 · 2026-05-02 03:29:06 +08:00
parent 40a721c24d
commit 628a3bc832
565 changed files with 687 additions and 711 deletions
@@ -0,0 +1,139 @@
+---
+name: telegram-dev
+description: "Telegram development skill: Bot API, Mini Apps/Web Apps, webhooks, long polling, inline/reply keyboards, payments, initData validation, TDLib/MTProto, message formatting, and deployment troubleshooting."
+---
+
+# telegram-dev Skill
+
+Use this skill to build Telegram bots, Mini Apps, and client integrations with explicit security boundaries around tokens, webhooks, and user data.
+
+## When to Use This Skill
+
+Trigger when any of these applies:
+- Creating or debugging a Telegram Bot with Bot API methods, long polling, webhooks, commands, messages, media, files, or payments.
+- Building Telegram Mini Apps/Web Apps with `window.Telegram.WebApp`, buttons, theme params, storage, sensors, or `initData` validation.
+- Implementing inline keyboards, reply keyboards, callback queries, command menus, or dynamic aligned message views.
+- Working with TDLib/MTProto client development or API ID/hash based integrations.
+- Troubleshooting webhook TLS/port issues, bot token errors, callback handling, formatting, or deployment.
+
+## Not For / Boundaries
+
+- Not for spam, unauthorized scraping, account abuse, or bypassing Telegram platform rules.
+- Never commit or print bot tokens, API hash, API ID plus phone session data, payment secrets, or user private data.
+- Webhook examples require HTTPS and public reachability; local-only servers need a tunnel or local Bot API server setup.
+- Required inputs: Bot vs Mini App vs TDLib scope, language/framework, token/auth status, update payload, deployment URL, and exact error.
+- Telegram APIs evolve; verify current method parameters and limits in official docs when precision matters.
+
+## Quick Reference
+
+### Common Patterns
+
+**Bot API endpoint shape**
+```text
+https://api.telegram.org/bot<TOKEN>/<METHOD_NAME>
+```
+
+**Send a message**
+```python
+import requests
+
+requests.post(
+    f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
+    json={"chat_id": chat_id, "text": "Hello"},
+    timeout=10,
+)
+```
+
+**Long polling**
+```python
+updates = requests.get(
+    f"https://api.telegram.org/bot{BOT_TOKEN}/getUpdates",
+    params={"offset": offset, "timeout": 30},
+    timeout=35,
+).json()
+```
+
+**Set a webhook**
+```python
+requests.post(
+    f"https://api.telegram.org/bot{BOT_TOKEN}/setWebhook",
+    json={"url": "https://example.com/webhook"},
+    timeout=10,
+)
+```
+
+**Inline keyboard**
+```python
+reply_markup = {
+    "inline_keyboard": [[
+        {"text": "Open", "url": "https://example.com"},
+        {"text": "Action", "callback_data": "action:1"},
+    ]]
+}
+```
+
+**Answer a callback query**
+```python
+requests.post(
+    f"https://api.telegram.org/bot{BOT_TOKEN}/answerCallbackQuery",
+    json={"callback_query_id": callback_query_id, "text": "OK"},
+)
+```
+
+**Initialize a Mini App**
+```javascript
+const tg = window.Telegram.WebApp;
+tg.ready();
+tg.expand();
+```
+
+**Send Mini App data back to the bot**
+```javascript
+tg.sendData(JSON.stringify({ action: "submit" }));
+```
+
+**Validate Mini App initData server-side**
+```text
+Parse initData -> remove hash -> sort key=value pairs -> HMAC with WebAppData-derived secret -> compare hash.
+```
+
+## Examples
+
+### Example 1: Echo Bot with Long Polling
+
+- Input: bot token and a private test chat.
+- Steps:
+  1. Call `getUpdates` with an offset.
+  2. Extract `message.chat.id` and `message.text`.
+  3. Reply with `sendMessage` and advance offset.
+- Expected output / acceptance: each user message gets one reply and old updates are not processed repeatedly.
+
+### Example 2: Webhook Deployment
+
+- Input: HTTPS URL `https://example.com/webhook`.
+- Steps:
+  1. Deploy an endpoint that accepts POST JSON updates.
+  2. Call `setWebhook` with the public URL.
+  3. Use `getWebhookInfo` to verify status and last error.
+- Expected output / acceptance: Telegram delivers updates to the endpoint and webhook info has no current delivery error.
+
+### Example 3: Mini App Button Flow
+
+- Input: web app URL and bot chat.
+- Steps:
+  1. Send a reply or inline keyboard button with `web_app.url`.
+  2. In the Mini App, call `ready()` and validate `initData` on the backend.
+  3. Send final data with `sendData` or a backend API call.
+- Expected output / acceptance: Mini App opens inside Telegram, backend authenticates the user, and bot receives structured data.
+
+## References
+
+- `references/index.md`: Telegram ecosystem navigation and official links.
+- `references/Telegram_Bot_按钮和键盘实现模板.md`: button and keyboard implementation templates.
+- `references/动态视图对齐实现文档.md`: aligned data display and dynamic message formatting.
+
+## Maintenance
+
+- Sources: local Telegram reference files plus official links listed in `references/index.md`.
+- Last updated: 2026-04-28
+- Known limits: API methods, limits, and Mini App capabilities are version-sensitive; verify against official Telegram docs for production releases.