Initial commit with translated description

SKILL.md

@@ -0,0 +1,43 @@
+---
+name: telegram
+description: "OpenClaw技能，用于设计Telegram Bot API工作流和命令驱动对话，使用直接HTTPS请求（无需SDK）。"
+---
+
+# Telegram Bot Skill (Advanced)
+
+## Purpose
+Provide a clean, production-oriented guide for building Telegram bot workflows via the Bot API, focusing on command UX, update handling, and safe operations using plain HTTPS.
+
+## Best fit
+- You want a command-first bot that behaves professionally.
+- You need a reliable update flow (webhook or polling).
+- You prefer direct HTTP calls instead of libraries.
+
+## Not a fit
+- You require a full SDK or framework integration.
+- You need complex media uploads and streaming in-process.
+
+## Quick orientation
+- Read `references/telegram-bot-api.md` for endpoints, update types, and request patterns.
+- Read `references/telegram-commands-playbook.md` for command UX and messaging style.
+- Read `references/telegram-update-routing.md` for update normalization and routing rules.
+- Read `references/telegram-request-templates.md` for HTTP payload templates.
+- Keep this SKILL.md short and use references for details.
+
+## Required inputs
+- Bot token and base API URL.
+- Update strategy: webhook or long polling.
+- Command list and conversation tone.
+- Allowed update types and rate-limit posture.
+
+## Expected output
+- A clear command design, update flow plan, and operational checklist.
+
+## Operational notes
+- Prefer strict command routing: `/start`, `/help`, `/settings`, `/status`.
+- Always validate incoming update payloads and chat context.
+- Handle 429s with backoff and avoid message bursts.
+
+## Security notes
+- Never log tokens.
+- Use webhooks with a secret token header when possible.

_meta.json

@@ -0,0 +1,6 @@
+{
+  "ownerId": "kn7ehv4at8yekzag31spcarxm180bev0",
+  "slug": "telegram",
+  "version": "1.0.1",
+  "publishedAt": 1770028389996
+}

references/telegram-bot-api.md

@@ -0,0 +1,63 @@
+# Telegram Bot API Field Notes
+
+## 1) Base URL and request style
+- Base format: `https://api.telegram.org/bot<token>/<method>`
+- Use GET or POST with JSON or form-encoded payloads.
+- File uploads use `multipart/form-data` and `attach://` references.
+
+## 2) Updates and delivery models
+### Long polling
+- `getUpdates` delivers updates with an `offset` cursor and `timeout`.
+
+### Webhook
+- `setWebhook` switches the bot to webhook mode.
+- Webhook URLs must be HTTPS. Check the official docs for port restrictions.
+
+### Update types (examples)
+- `message`, `edited_message`, `channel_post`, `edited_channel_post`
+- `inline_query`, `chosen_inline_result`, `callback_query`
+- `shipping_query`, `pre_checkout_query`, `poll`, `poll_answer`
+
+Use `allowed_updates` to limit which updates you receive.
+
+## 3) High-traffic-safe patterns
+- Use `allowed_updates` to reduce noise.
+- Keep handlers idempotent (Telegram may retry).
+- Return quickly from webhooks; process heavy work async.
+
+## 4) Common methods (non-exhaustive)
+- `getMe`, `getUpdates`, `setWebhook`
+- `sendMessage`, `editMessageText`, `deleteMessage`
+- `sendPhoto`, `sendDocument`, `sendChatAction`
+- `answerCallbackQuery`, `answerInlineQuery`
+
+## 5) Common fields (non-exhaustive)
+### sendMessage
+- `chat_id`, `text`, `parse_mode`
+- `entities`, `disable_web_page_preview`
+- `reply_markup` (inline keyboard, reply keyboard)
+
+### reply_markup (inline keyboard)
+- `inline_keyboard`: array of button rows
+- Buttons can contain `text` + `callback_data` or `url`
+
+### callback_query
+- `id`, `from`, `message`, `data`
+
+### sendChatAction
+- `action`: `typing`, `upload_photo`, `upload_document`, `upload_video`, `choose_sticker`
+
+## 6) Command UX checklist
+- `/start`: greet, explain features, and show main commands.
+- `/help`: include short examples and support contact.
+- `/settings`: show toggles with inline keyboards.
+- `/status`: show recent job results or queue size.
+
+## 7) Error handling
+- `429`: back off and retry.
+- `400`: validate chat_id, message length, and formatting.
+- `403`: bot blocked or chat not accessible.
+
+## 8) Reference links
+- https://core.telegram.org/bots/api
+- https://core.telegram.org/bots/faq

references/telegram-commands-playbook.md

@@ -0,0 +1,26 @@
+# Telegram Command Playbook
+
+## Command set (professional baseline)
+- `/start`: greet, set expectations, and show main actions.
+- `/help`: short help + examples.
+- `/status`: show last job result, queue length, or uptime.
+- `/settings`: show toggles via inline keyboard.
+- `/about`: short bot description and support contact.
+
+## Command UX patterns
+- Acknowledge fast, then do heavy work asynchronously.
+- Prefer short replies with a single call-to-action.
+- Always include “what next?” in `/start` and `/help`.
+
+## Inline keyboard patterns
+- Use stable callback_data names (e.g., `settings:notifications:on`).
+- Keep callbacks idempotent.
+
+## Message style guidelines
+- Use MarkdownV2 or HTML consistently; avoid mixing.
+- If using MarkdownV2, escape reserved characters.
+- Keep single message length under safe limits; split when needed.
+
+## Examples (short)
+- `/start` reply: “Hi! I can publish posts and send alerts. Try /help.”
+- `/status` reply: “Queue: 2 jobs. Last run: success 2m ago.”

references/telegram-request-templates.md

@@ -0,0 +1,42 @@
+# Telegram Request Templates (HTTP)
+
+## sendMessage
+POST `/sendMessage`
+```json
+{
+  "chat_id": 123456789,
+  "text": "Hello",
+  "parse_mode": "HTML",
+  "disable_web_page_preview": true
+}
+```
+
+## editMessageText
+POST `/editMessageText`
+```json
+{
+  "chat_id": 123456789,
+  "message_id": 42,
+  "text": "Updated",
+  "parse_mode": "HTML"
+}
+```
+
+## answerCallbackQuery
+POST `/answerCallbackQuery`
+```json
+{
+  "callback_query_id": "1234567890",
+  "text": "Saved"
+}
+```
+
+## setWebhook
+POST `/setWebhook`
+```json
+{
+  "url": "https://example.com/telegram/webhook",
+  "secret_token": "your-secret",
+  "allowed_updates": ["message","callback_query"]
+}
+```

references/telegram-update-routing.md

@@ -0,0 +1,23 @@
+# Telegram Update Routing
+
+## Update normalization
+- Normalize inbound updates to a single envelope:
+  - `update_id`, `chat_id`, `user_id`, `message_id`, `text`, `callback_data`, `type`
+- This makes routing logic consistent across message types.
+
+## Routing rules
+- If `callback_query` exists, handle callbacks first.
+- Else if `message.text` starts with `/`, treat as command.
+- Else fall back to default handler (help or menu).
+
+## Safe defaults
+- Unknown command: reply with `/help` guidance.
+- Unknown callback: answerCallbackQuery with a short notice.
+
+## Idempotency
+- Keep a cache of processed `update_id` in case of retries.
+- Ensure handlers can be safely re-run.
+
+## Error handling
+- On 429: backoff and retry with jitter.
+- On 400: validate payload length and parse mode.