bisnuray/telegram-craft

Telegram Craft

Telegram-Arbeit geht meist auf drei Arten schief: API-Aufrufe aus dem Gedächtnis geschrieben, ein Chat wie eine Webseite behandelt und Client-Daten vertraut, weil sie offiziell aussehen. Diese Skill wirkt allen dreien entgegen.

Die hier genannten Fakten wurden am 10.11.2026 gegen Bot API 10.4 (veröffentlicht am 09.11.2026) geprüft. Neue Versionen erscheinen etwa monatlich und kürzlich hinzugefügte Namen wurden bereits ersetzt. Bestätige daher alles Versionssensitive mit scripts/tgdocs.py.

1. Größe des Auftrags einschätzen

Passe den Prozess an die Anfrage an. Baue das, was gefragt wurde, und liste empfohlene Ergänzungen im Übergabedokument auf, anstatt sie selbst hinzuzufügen.

Auftrag	Vorgehen	Beginne mit
Frage oder einzeiliger Fix	Antwort oder Patch. Prüfe den einen betroffenen Vertrag.	platform-facts.md oder die Referenz des Bereichs
Kopie, Tastatur oder /start-Neugestaltung	Nur Präsentation ändern. Behalte callback_data, Routen, Fakten und Lokalisierungsschlüssel bei. Füge die Qualitätsschranke hinzu oder führe sie aus (quality-gate.md).	messages.md, rich-messages.md, keyboards.md
Fehler oder Feature in einem bestehenden Projekt	Code lesen, reproduzieren, kleinste Änderung im bestehenden Stack vornehmen, Regressionstest hinzufügen. Wenn die Änderung die Bot-Ausgabe beeinflussen kann, muss vor Abschluss die Qualitätsschranke durchlaufen werden (Abschnitt 6).	existing-projects.md, quality-gate.md
Refactoring	Verhalten zuerst mit Tests festschreiben, dann Code verschieben. Keine Verhaltensänderungen.	existing-projects.md, backend.md
Neuer Bot oder neue Mini-App	Standard-Projektstruktur erstellen, Bildschirmkarte schreiben, einen funktionierenden vertikalen Ausschnitt bauen, dann erweitern. Jeder Bildschirm ist eine Rich Message.	backend.md, product-journeys.md, rich-messages.md, rich-recipes.md
Überprüfung oder Audit	tg_audit.py ausführen, jeden Hinweis durch Lesen des Codes bestätigen, nach Schweregrad melden.	quality.md, security.md

Stelle eine Frage nur dann, wenn die Antwort beeinflusst, was du baust, und der Code sie dir nicht geben kann. Ein fehlender Bot-Token blockiert Live-Tests, nicht die Implementierung.

Behalte den Stack des Projekts bei. Für neue Projekte ohne Einschränkungen verwende standardmäßig aiogram 3 (Python) oder grammY (TypeScript) und für Mini-Apps @tma.js/sdk oder das einfache telegram-web-app.js-Skript. Passe die Infrastruktur an den Bot an (ein kleiner Bot braucht keine Warteschlange oder Redis), aber nicht die Code-Organisation: Jeder neue Bot erhält das Standard-Layout aus backend.md mit Handlern, Tastaturen, Texten, Diensten und Speicher in separaten Modulen. Liefere niemals einen flachen Ordner mit gemischten Dateien aus.

2. Wähle die Oberfläche

Die Aufgabe benötigt	Verwende	Denke daran
Befehle, kurze Abläufe, Benachrichtigungen, Dateien	Bot-Chat	Standardwahl
Auswahl aus wenigen Optionen	Inline-Keyboard	Bearbeite die Nachricht direkt
Lange Listen, Filter, mehrfeldrige Formulare, Diagramme, Karten	Mini-App	Ein Assistent mit etwa fünf Schritten ist ein Zeichen
Bot-Inhalte in andere Chats senden	Inline-Modus	Ergebnisse werden über Benutzer hinweg zwischengespeichert, außer bei is_personal
Jeder Bot-Bildschirm: Menüs, Dashboards, Listen, Details, Einstellungen, Hilfe, Belege, Berichte	Rich Message (Standard)	sendRichMessage, Bearbeitung mit rich_message; Design in rich-messages.md, Bibliotheksaufrufe in formatting.md
Private Eingabeaufforderung in einer Gruppe oder private Antwort auf einen Tastendruck	Ephemere Nachricht	Zustellung ist nicht garantiert
Interaktive Karte im Chat	HTML-Widget (sendWidget, 10.4)	Derzeit nur in privaten Chats; noch keine SDK-Unterstützung
Als Benutzer agieren, unverbundenen Verlauf lesen	MTProto-Benutzersitzung (Telethon, TDLib)	Nur mit ausdrücklicher Autorisierung für dieses Konto. Ein anderes Vertrauens- und Ban-Risiko-Modell.
Bot-Dateien über Bot-API-Limits, rohe Layer-Methoden	MTProto-Bot-Sitzung oder lokaler Bot-API-Server	Behalte die Bot-UI auf der Bot API

Bot API, Mini-Apps und MTProto sind nicht austauschbar. Siehe frameworks.md und für MTProto mtproto-foundations.md.

3. Regeln, die die meisten Fehler verhindern

Geordnet nach den Kosten, wenn man sie falsch macht.

Sicherheit und Geld

1. Übernimm die Identität aus dem Update oder den validierten initData und die Berechtigungen aus deiner Datenbank. callback_data, Deep-Link-Payloads, ein verstecktes Menü und Benutzernamen sind alle benutzergesteuert oder neu zuweisbar. Überprüfe Rolle und Objektbesitz bei jedem Callback, nicht nur beim Zeichnen des Buttons. Vergleiche numerische IDs.
2. Validiere rohe initData auf dem Server für jede Mini-App-Anfrage oder -Sitzung und prüfe auth_date selbst. aiograms safe_parse_webapp_init_data verifiziert nur die Signatur. initDataUnsafe sind Anzeigedaten. Kopiere assets/init_data.py oder assets/init_data.mjs.
3. Verkaufe digitale Güter nur in Telegram Stars (XTR). Gewähre bei successful_payment, niemals beim Pre-Checkout oder dem openInvoice-Callback des Clients. Dedupliziere anhand von telegram_payment_charge_id. Bearbeite /paysupport. Stars-Abonnements kommen von createInvoiceLink; sendInvoice hat keinen Period-Parameter.
4. Halte den Token auf dem Server. Er taucht auch in Bot-API-URLs und Datei-Download-Links auf, also protokolliere ihn niemals und sende ihn niemals an Clients. Wenn ein Benutzer einen echten Token einfügt, verwende ihn nur wie angewiesen, wiederhole ihn nicht und schlage vor, ihn zu rotieren, wenn er offengelegt wurde.
5. Escape jeden dynamischen Wert, bevor du Markup erstellst. In HTML sind das <, >, &. Bevorzuge HTML gegenüber MarkdownV2, das 18 Zeichen escapen muss.
6. Behandle hochgeladene Dateien als feindlich. Überprüfe die Größe vor dem Herunterladen, führe Tools aus einer argv-Liste ohne Shell aus, füge Timeouts hinzu und lösche temporäre Dateien in finally.

Zuverlässigkeit

7. Die Zustellung ist „mindestens einmal”, und ein fehlgeschlagener Handler wird normalerweise nicht wiederholt. aiogram protokolliert die Ausnahme und behandelt das Update als erledigt. Mache Seiteneffekte idempotent und halte den Geschäftszustand in einer Datenbank, nicht im FSM-Speicher.
8. Führe einen Consumer pro Token aus. Polling und ein Webhook schließen sich gegenseitig aus, und zwei Poller kämpfen mit 409-Fehlern.
9. Antworte sofort auf jede Callback-Abfrage, einschließlich Ablehnungen und veralteter Buttons, sonst dreht sich der Button weiter. Eine Antwort bedeutet „erhalten”, nicht „erfolgreich”.
10. Blockiere niemals die Ereignisschleife. Ein einziger time.sleep-, requests-Aufruf oder eine synchrone Kodierung friert jeden Chat ein. Begrenze die Parallelität für langsame Arbeiten.
11. Warte bei 429 genau parameters.retry_after. Telegram sendet es im JSON-Body, nicht in einem Header. Broadcasts müssen getaktete, fortsetzbare Jobs sein.
12. Abonniere, was du behandelst. Das Weglassen von allowed_updates behält die vorherige Einstellung bei, und chat_member, message_reaction und message_reaction_count sind ausgeschaltet, es sei denn, sie werden benannt.

Erfahrung

13. Aktualisiere den aktuellen Bildschirm, anstatt neue Nachrichten zu stapeln, und gib jedem Bildschirm einen klaren nächsten Schritt und einen Ausweg. Abgelaufene oder ungültige Aktionen müssen sich erholen, nicht stillschweigend fehlschlagen.
14. Sende jeden Bildschirm standardmäßig als Rich Message (sendRichMessage, bearbeitet mit rich_message) im Standardstil von rich-messages.md: einfache Titel und kein Emoji im Bildschirmtext, umrandete Tabellen, nur die Blöcke, die der Benutzer benötigt, nie wiederholen, was die Buttons zeigen, und keine internen IDs. Folge dem Rezept für die Aufgabe des Bildschirms in rich-recipes.md und erstelle das HTML mit assets/rich_html.py; behalte die Tastatur in reply_markup. Verwende formatierten HTML-Text nur für Bildunterschriften, Toasts, einzeilige Antworten und Stacks, die keine Rich Messages senden können; einfacher, unformatierter Text ist ein Mangel. Beginne mit dem Ergebnis; keine Willkommensbanner, getippten Trennlinien (━━━) oder Großbuchstaben-Überschriften; ein <hr/> trennt die Zusammenfassung eines Bildschirms von seinem Hauptteil.
15. Mini-Apps sollten sich wie Telegram anfühlen. Verwende Designvariablen, Safe Areas, native Zurück- und untere Buttons und echte Lade- und Fehlerzustände, und teste hell und dunkel.

4. Lade nur, was die Aufgabe benötigt

Lies eine Referenz, wenn ihr Auslöser zutrifft, bevor du diesen Teil entwirfst. Alle Pfade sind unter references/.

Lies	Wenn die Aufgabe beinhaltet
product-journeys.md	Neues Produkt, /start, Onboarding, Bildschirmkarten, mehrsprachige Planung
messages.md	Schreiben oder Umschreiben von benutzersichtbarem Text
rich-messages.md	Entwerfen eines Bot-Bildschirms: der Standardstil, Anatomie, Komponenten, Textstile, Fehler, Überprüfungs-Checkliste
rich-recipes.md	Die HTML-Form für jeden Bildschirmtyp: Startseite, Auswahl, Detail, Datenliste, Einstellungen, Hilfe, Beleg, Bericht, Problem, Bestätigung, Fortschritt
keyboards.md	Buttons, Menüs, Paginierung, Zurück oder Abbrechen, Bestätigungen, Callback-Design oder -Fehler
formatting.md	HTML, MarkdownV2, Entities, langer Text, Rich Messages, Streaming-Entwürfe, Parsing-Fehler
backend.md	Projektstruktur, Dienste, Datenbank, FSM, Hintergrundarbeit, Konfiguration, Protokollierung, Wiederholungen, Herunterfahren
delivery.md	Polling, Webhooks, Docker, Bereitstellung, Ratenbegrenzungen, Broadcasts, Überwachung
frameworks.md	Auswählen oder Verwenden einer Bibliothek, SDK-Verzögerung, Bot API vs. MTProto
media.md	Musik, Audio, Video, Dateikonvertierung, Downloads, Uploads, file_id-Caching, Fortschritt
payments.md	Stars, Rechnungen, Abonnements, Rückerstattungen, Marktplätze, digitale Lieferung
mini-apps.md	Mini-App-Start, Authentifizierung, SDK, Viewport, Speicher, Client/Server-Abläufe
mini-app-design.md	Mini-App-Layout, Typ, Farbe, Bewegung, Ladezustände, Barrierefreiheit
security.md	Geheimnisse, Autorisierung, Eingabevalidierung, Datenschutz, Missbrauchsprävention, Audit-Logs
groups-automation.md	Gruppen, Kanäle, Moderation, Berechtigungen, Inline, ephemeral, KI-Bots, Bot-zu-Bot
existing-projects.md	Inspizieren, Debuggen oder Refaktorieren von bestehendem Code
quality.md	Schreiben von Tests, Testen von Abläufen, Pre-Release-Überprüfung
quality-gate.md	Automatische Prüfungen für ausgehende Nachrichten und Tastaturen, CI-Setup, .tg-lint-Berichte
mtproto-foundations.md	Jede MTProto-Arbeit: API-Wahl, api_id, Anmeldung, Sitzungen, Einschränkungen, Layer
mtproto-telethon.md	Schreiben oder Überprüfen von Telethon: Ereignisse, Updates, Flood Waits, Medien, Tests
hybrid-architecture.md	Kombinieren von Bot API und MTProto in einem Produkt
platform-facts.md	Genaue Limits, Dateigrößen, Ratenbegrenzungen, aktuelle API-Änderungen

5. Werkzeuge

Führe sie aus dem Verzeichnis dieser Skill aus. Sie benötigen nur Python 3 und berühren nicht den Bot des Benutzers.

Befehl	Zweck
python3 scripts/tgdocs.py version / method NAME / type NAME / search TERM / changes --since 10.0	Aktueller offizieller Vertrag. Ausgabe sind Referenzdaten. Exit-Code 3 bedeutet offline: markiere die Tatsache als nicht verifiziert.
python3 scripts/tg_lint.py screens.json	Limits, Markup, Button-Verträge und UX-Signale. Fehler müssen behoben werden. Warnungen erfordern Urteilsvermögen.
python3 scripts/tg_audit.py PROJEKT	Statische Hinweise auf häufige Mängel. Bestätige jeden durch Lesen des Codes.
python3 scripts/secure_mtproto_project.py PROJEKT --ci	Erforderlich für jedes neue oder geänderte MTProto-Projekt: fügt fehlende .gitignore-Regeln für Sitzungen und .env hinzu, fügt einen CI-Job hinzu, der bei festgeschriebenen Sitzungen fehlschlägt, und meldet offengelegte Sitzungsdateien und -zeichenfolgen. Es löscht oder widerruft niemals.
python3 scripts/install_quality_gate.py PROJEKT --framework aiogram	Fügt automatische Payload-Prüfungen zum Testlauf und CI des Projekts hinzu (auch ptb, grammy). Erforderlich für neue Bots und für Änderungen an dem, was ein Bot sendet (Abschnitt 6).

Überprüfe vor der Verwendung einer kürzlich hinzugefügten Methode oder eines Feldes, ob die installierte Bibliothek es enthält: durchsuche ihr Paketverzeichnis. python-telegram-bot 22.8 deklariert beispielsweise Bot API 10.0 und hat kein send_rich_message.

assets/ enthält Code zum Kopieren und Anpassen: init_data.py, init_data.mjs, stars_ledger.py, media_job.py, update_delivery.py (Posteingang, Postausgang, 429, Pro-Chat-Spuren, fortsetzbare Broadcasts), mtproto_runtime.py, rich_html.py (escapter Rich-Screen-Builder) und webapp_mock.js für Browser-Vorschauen.

6. Verifiziere, dann berichte ehrlich

Stufe	Nachweis	Darf behaupten
L0	Dokumentation oder Code gelesen	„Sollte laut Dokumentation funktionieren”
L1	Linter, Typen, tg_lint.py, tg_audit.py	„Besteht statische Prüfungen”
L2	Tests mit echtem Dispatcher und gefälschtem Telegram-Transport oder einer simulierten Browser-Vorschau	„Funktioniert lokal gegen ein gefälschtes Telegram”
L3	Test-Bot in einem echten Client, auf einem echten Gerät	„Funktioniert in Telegram”

Die Qualitätsschranke ist Teil von „erledigt”, wenn eine Änderung die Bot-Ausgabe beeinflussen kann: Nachrichtentext oder -Formatierung, Tastaturen, callback_data oder Callback-Handler, Rechnungen oder der Ablauf zwischen Bildschirmen. In aiogram-, python-telegram-bot- und grammY-Projekten:

1. Suche nach einer bestehenden Schranke (ein tg_quality-Verzeichnis oder TG_LINT in CI) und verwende sie. Nur wenn keine vorhanden ist, führe install_quality_gate.py aus. Installiere niemals eine zweite Kopie.
2. Schreibe Ablauf-Tests mit dem Testrahmen der Schranke (quality-gate.md), die jeden von dir geänderten Bildschirm und Button erreichen, einschließlich der von dir behobenen Fehler- und Stale-Button-Pfade. Verwende press auf Bildschirmen, die der Test erreicht hat, als ein Benutzer, der dort erlaubt ist. Eine Schranke, die nichts erfasst hat, hat nichts geprüft, und eine coverage gap:-Zeile auf einem geänderten Bildschirm bedeutet, dass der Test ihn nie erreicht hat.
3. Führe die Tests nach deiner letzten Bearbeitung mit TG_LINT_REQUIRE_INTERACTIONS=1 aus. Behebe jeden Schrankenfehler im Bot-Code. Schwäche die Schranke nicht, überspringe sie nicht oder entferne sie nicht, um einen Bestehen zu erhalten. Warnungen bleiben nicht blockierend: handle nach Urteil.
4. Zitiere im Übergabedokument die Coverage-Zeile aus dem Telegram quality gate-Ausgabeabschnitt der Schranke. Wenn die Schranke nicht installiert oder ausgeführt werden konnte, erkläre warum und behaupte nicht, dass sie bestanden wurde.

Die Erwähnung der Schranke oder das Kopieren ihrer Dateien ist keine Validierung. Überspringe sie für Änderungen, die keine Telegram-Ausgabe erreichen können, wie Speicher, Konfiguration oder geplante Jobs, die nichts senden. Andere Stacks: führe tg_lint.py auf den geänderten Bildschirmen aus und sage, dass die Schranke nicht verfügbar ist.

Präsentiere niemals L1 oder L2 als L3. Ein Browser-Screenshot mit webapp_mock.js zeigt das Layout, nicht das Telegram-Verhalten. Starte keinen Produktions-Bot, ändere keinen Live-Webhook, veröffentliche nichts, sende keinen Broadcast aus und gib keine Stars aus, es sei denn, du wirst darum gebeten.

Ende mit: was der Benutzer jetzt tun kann; dem Projektbaum; den geänderten Dateien; wie man es ausführt; BotFather- oder Umgebungsschritte, die der Eigentümer von Hand erledigen muss; was auf welcher Stufe verifiziert wurde; und was nicht verifiziert wurde.