Kimi · Deal Scout

Vollständige Implementierungsdokumentation

Dokumentation des tatsächlich umgesetzten Fahrrad‑Schnäppchen‑Scouts: sichere Telegram‑Aufnahme, zweistufige Analyse, bildgestützte Modellidentifikation, forensische Prüfung hochpreisiger Kandidaten, persistente Verarbeitung, nachverfolgte Zustellung und Statistik. Stand: 14. September 2026.

Dienst aktiv · 0 Restarts256 Tests grünText: Luna → DeepSeek‑FallbackBild: Gemini → DeepSeek‑BackupAbholung · Rechnung positiv

1 · Ziel und Ergebnis

Der Scout verarbeitet neue, vom fest konfigurierten Kleinanzeigen‑Monitorbot gelieferte Anzeigen automatisch. Er filtert erst günstig über Text, untersucht nur Verdachtsfälle mit Bildern vertieft und meldet ausschließlich policy‑konforme Deals – oder konservative Fälle zur manuellen Prüfung – in diesen Telegram‑Chat.

Automatischer Eingang

Telegram‑Nachricht → validierter Ingress → kanonische Kleinanzeigen‑Anzeige → SQLite‑Inbox.

Zwei Stufen

Textfilter hält Kosten gering; Bild-/Tiefenanalyse wird nur bei promote ausgelöst.

Fail‑closed

Unklare, ungültige oder technisch unvollständige Daten führen nicht zu einem Schnäppchen‑Alert.

2 · Architektur und Vertrauensgrenzen

Wichtige Abweichung vom frühen Plan: Gemini 2.5 Flash ist das primäre Vision-Modell, weil es reale Kleinanzeigen-Bilder zuverlässiger einordnet. DeepSeek Vision dient ausschließlich als technisches Backup. Bilder ähnlicher Anzeigen werden vor der Analyse ausgeschlossen.

3 · Laufzeitablauf einer neuen Anzeige

Empfang und Grenze. Der User‑systemd‑Dienst nutzt eine kurzlebige Kopie der autorisierten Telethon‑Session. Er akzeptiert nur Nachrichten des fest konfigurierten Monitorbots; fremde Peer/Sender, ausgehende oder zu alte Nachrichten werden verworfen.
AP1–AP3: Ingress und Adapter. Der Nachrichtentext bleibt transient; gespeichert werden ein Hash, begrenzte Linkkandidaten und anschließend nur kanonische Kleinanzeigen‑Einzelanzeigen. Eindeutige Schlüssel verhindern doppelte Ingress‑ und Quellenobjekte.
Textabruf. Eine kanonische Listing‑URL wird begrenzt abgerufen. Der Textpfad extrahiert Titel, Beschreibung, Preis‑Hinweis und Ort für die Analyse. Eine Übergröße oder Transportabweichung endet fail‑closed.
Stufe 1: Textvorfilter. Der Agent scout bewertet den vollständigen Anzeigentext. Er lässt nur MTB, Rennrad und Gravel zu; Teile, Gesuche, falsche Kategorien und E‑Bikes werden verworfen. Generischer Titel, knapper Text oder VB können einen Verdacht (promote) auslösen.
Stufe 2: Tiefenanalyse. Nur promote ruft die Seite und maximal begrenzte First‑Party‑Bildkandidaten ab. Der scout-deep-Runner bewertet Text plus flüchtige Bilddateien nach dem Fachskill.
Persistenz und Entscheidung. Stufe‑1‑ und Stufe‑2‑Ergebnisse werden atomar aktualisiert. Das Policy‑Gate lässt nur begründete Ergebnisse weiter; vor Versand reserviert alert_dedupe genau einmal den Schlüssel.
Meldung. Ein alert wird als potenzielles Schnäppchen ausgeliefert. Ein abgeschlossener manual_review ohne rotes Risiko wird als klar gekennzeichnete Prüfmeldung ausgeliefert. Alle anderen Zustände lösen keine Nachricht aus.

4 · Persistenz und Datenvertrag

Die produktive Inbox ist SQLite mit aktivierten Foreign Keys und vorwärtsgerichteten Migrationen. Roh‑Telegram‑Text ist nicht Teil des Ingress‑Events. Anzeigentext wird nur dort gespeichert, wo er für die ausdrücklich gewünschte Textanalyse erforderlich ist.

Migration	Tabellen	Zweck
`0001`	`ingress_events`, `source_items`	Idempotenter, textfreier Nachrichteneingang und kanonische Quellen.
`0002`	`workflow_revisions`, `workflow_queue`, `workflow_runs`, `budget_ledger`, `alert_dedupe`	Workflow‑Grundlage: atomare Claims, Leases, Recovery/Reconcile, Ledger und einmalige Alert‑Reservierung.
`0003`	`listing_text`	Vollständiger Listing‑Text für die Stufe‑1‑Fachprüfung; Preis und Ort für die Analyse bzw. Darstellung.
`0004`	`screen_results`	Textfilter‑Entscheidung, Kategorie/Zustandsband und begrenzte Reason‑Codes.
`0005`	`deep_results`	Tiefenanalyse, Evidenzqualität, konservative Marge, Risiken und Reason‑Codes.

Keine Bildpersistenz: HTML und Bildbytes der Tiefenanalyse leben nur im Arbeitsspeicher bzw. in einem restriktiven temporären Verzeichnis und werden danach entfernt. Persistiert wird nur das validierte, begrenzte Ergebnis.

5 · Fachlogik und Modellkonfiguration

Stufe 1 · Textfilter

Agent: scout. Primärmodell: OpenAI GPT‑5.6 Luna über vorhandenes OAuth. Fallback: DeepSeek V4 Flash.

Input: vollständiger Anzeigentext mit Titel, Beschreibung, Preis und Ort, als explizit untrusted markierter Block. Generische Beschreibungen dürfen bei Schnäppchensignalen zur Bildanalyse weitergehen; harmlose überlange Reason-Listen werden normalisiert.

Stufe 2 · Bild-/Tiefenanalyse

Agent: scout-deep. Primär: Gemini 2.5 Flash. Backup: DeepSeek Vision nur bei einem technischen Gemini-Bildfehler.

Es werden nur Bilder der geöffneten Anzeige akzeptiert, nie Vorschauen ähnlicher Anzeigen. Ein fachlicher reject für MTB, Rennrad oder Gravel braucht Marktwert und konservative Marge; sichtbare strukturelle Schäden bleiben die Ausnahme. Abholung, Rechnung oder OVP-/Katalogbilder sind keine Betrugsindikatoren.

Marie-Profil für E-Rennrad/E-Gravel: Bei 168 cm dürfen nur XS/S, 47–51 cm oder eine dokumentierte Größenempfehlung, die 168 cm einschließt, als passend gelten. Eine fehlende Größe führt höchstens zu einer Prüfmeldung; ein Alert braucht neben bildbestätigten Scheibenbremsen den Befund marie_fit = confirmed. E-MTB sowie City-/Trekking-Pedelecs bleiben ausgeschlossen.

Entscheidungszustände

reject

Ausreichend geprüft, aber kein passendes Sportfahrrad oder kein attraktiver Deal.

uncertain

Stufe‑1‑Text reicht nicht für einen belastbaren Verdacht; keine Bildstufe.

promote

Textsignal für einen möglichen unterbewerteten Deal; löst Stufe 2 aus.

incomplete

Nur technische Analysehindernisse, z. B. Abruf oder Bildverarbeitung nicht möglich.

manual_review

Bilder/Analyse vorhanden, aber fachlich nicht sicher genug. Wird ohne rote Risiken als konservative Prüfmeldung ausgeliefert.

alert

Vollständige Analyse, mindestens mittlere Evidenz, konservativ positive Netto‑Marge und keine roten Risiken. Wird als potenzielles Schnäppchen gemeldet.

Korrektur aus dem Livebetrieb: Ein technischer Visionfehler – auch incomplete / images_missing – wird nicht als fachliches manual_review kaschiert. Gemini wird nach DeepSeek-Backup genau einmal mit frischem Seiten-, Bild- und Modellabruf wiederholt; danach wird ein sichtbarer terminaler Fehlerstatus gespeichert.

Finales Policy-Urteil: Die Statistikseite zeigt nicht bloß den Vorschlag der Bildanalyse. Wird ein vorgeschlagener alert durch eine harte Regel blockiert – etwa weil sichtbare Scheibenbremsen nicht bestätigt sind – steht dort klar „Alert blockiert“ samt Grund. Solche Fälle werden weder versendet noch als Alert gezählt.

6 · Policy, Dedupe und Telegram‑Meldungen

Alert‑Gate

Erfordert alert, abgeschlossene Analyse, positive konservative Netto‑Marge, Evidenz medium oder high und kein rotes Risiko.

Manual‑Review‑Gate

Erfordert manual_review, mindestens mittlere Evidenz, kein rotes Risiko und eine konkrete, vor dem Kauf klärbare Frage. Low‑Evidence- und rein technische Fälle werden nicht zugestellt.

Zustellstatus

Jede Reservierung wird nach dem Versand als sent, failed oder bei Timeout als ambiguous gespeichert. Nur bestätigte Fehler sind bei späterer Neubewertung erneut zustellbar; ein Timeout wird nicht blind doppelt versendet.

Die Meldung enthält Titel, Preis-/Ortseinordnung soweit validiert, Evidenz, Risiken/offene Punkte, Verkäuferfragen und den kanonischen Kleinanzeigen‑Link. Sie ist eine Kaufprüfung, keine Kauf- oder Kontaktaktion.

7 · Sicherheits- und Betriebsgrenzen

Bereich	Umsetzung
Telegram‑Session	Private Config und Umgebung außerhalb des Repositories; restriktive Rechte. Der Dauerlistener benutzt eine temporäre Kopie der Originalsession.
Quelle	Nur kanonische Kleinanzeigen‑Einzelanzeigen; HTTPS, Host-/Redirect‑Allowlist, harte Zeit‑ und Größenlimits; kein Login, CAPTCHA‑Bypass, Proxy oder Ersatzkandidat.
Untrusted Input	Beschreibung, Titel, Bilder und Links steuern niemals Skill, Tool, Empfänger, Pfad oder Modell. Schema‑Validatoren weisen Zusatzfelder und ungültige Enums ab.
Modelle	Dedizierte Agenten mit minimalem Toolprofil; keine Modelltools für Shell, Web, Datei oder Messaging.
Versand	Deterministische Policy plus Dedupe vor dem Senden. Keine automatische Kontaktaufnahme mit Verkäufern.
Not-Aus	`systemctl --user stop deal-scout-listener` stoppt die Aufnahme; Inbox und autorisierte Session bleiben erhalten.

8 · Umsetzungsgeschichte und Planabweichungen

Arbeitspaket	Ergebnis	Wichtige Erkenntnis / Abweichung
AP1–AP3	Ingress, Adapter, SQLite‑Inbox	Textfreier Erstkontakt, idempotente Speicherung und strikte Kleinanzeigen‑Normalisierung.
AP4	Telethon‑Owner‑Handoff, Session‑Sicherheit, begrenzter Empfang	Autorisierung, temporäre Sessionkopien und Monitorbot‑Bindung wurden vor Dauerbetrieb verifiziert.
AP5	Isolierter OpenClaw‑ACK‑Nachweis	Zeigte die sichere Modell‑Einbettung mit deny‑all Tooloberfläche; kein Fachlauf.
AP6	Workflow‑/Queue‑Fundament	Atomare Claims, Lease‑Recovery, Reconcile, Ledger und Alert‑Dedupe offline getestet.
AP7	Quellen-/Strukturspikes	Enge HTML-/JSON‑LD‑Extraktoren waren für reale Seiten zu fragil. Daraus entstand bewusst der pragmatische Pfad: begrenzter Abruf → vollständiger Text → Modellanalyse, statt breites Scraping.
AP8	Statisches Routing	Nur `bike → bike-deals-v1`; keine dynamisch durch Daten gesetzten Workflows.
AP9	Zweistufige Fahrradlogik	Vom ursprünglichen Terra‑Vorschlag zu Luna/OAuth als Textstandard; neuer allgemeiner Agent `scout` statt bikespezifischem Agentennamen.
Live‑Integration	Daemon, `scout-deep`, Gemini‑Vision und Versand	Gemini ist Bildprimärmodell; DeepSeek dient als technisches Backup. `manual_review` wird nur bei fachlich auflösbarem Potenzial ausgeliefert.
Statistik	Öffentliche, responsive Übersichtsseite	15‑Minuten‑Refresh, Zeitraumfilter, Timeline mit Titel, Link, Preis und vom Owner freigegebenem PLZ/Ort. Keine Rohtexte oder Verkäuferdaten in der Statistik.

9 · Betrieb, Beobachtung und UI

Dauerbetrieb

Der User‑Service deal-scout-listener startet den Listener mit UMask=0077 und Restart=on-failure. Aktueller Status: active/running · 0 Restarts.

Service-Status: systemctl --user status deal-scout-listener
Live-Logs: journalctl --user -u deal-scout-listener -f

Statistikseite

Deal Scout · Statistik öffnen

Generiert im 15‑Minuten‑Takt aus der Inbox, mit Filtern für Alle, Heute, Woche, Monat und Jahr. Die Timeline verlinkt bewusst auf die Anzeige und zeigt ihren gespeicherten Preis; andere Statistikbereiche bleiben aggregiert.

10 · Aktueller Verifikationsstand

Bestanden Tests & Dienst

256 Unit-/Integrations-/Contract‑Tests bestehen. Der systemd‑Dienst läuft aktiv ohne Neustarts.

Bestanden Eingang bis Deep‑Ergebnis

Telegram‑Eingang, Textanalyse, Bildpfad, Fallback, Persistenz und Dedupe wurden live mit begrenzten Kandidaten ausgeführt.

Bestanden Echter Deal‑Alert

Der Versandpfad ist aktiv und policy-konforme reale Alerts werden einmalig zugestellt.

Praktische Konsequenz: Neue Anzeigen laufen automatisch durch. Bei manual_review erhältst du eine konservative Prüfmeldung nur bei fachlich klärbarem Potenzial und mindestens mittlerer Evidenz; bei alert einen potenziellen Schnäppchentreffer. Bei reject, uncertain oder technischen Fehlern wird nicht gestört.

11 · Aktualisierung vom 7. September 2026

Stufe 2: technisch fehlertolerant

Gemini analysiert Bilder primär, DeepSeek dient nur als technisches Backup. Bei Timeout, Bild-/Transport- oder Modellprozessfehler folgt genau ein frischer Retry mit neuem Seitenabruf, Bilddownload und Modellprozess. Nach zwei technischen Fehlschlägen wird ein sichtbarer terminaler Fehlerstatus gespeichert; fachliche Entscheidungen und ungültige Modellinhalte werden nicht wiederholt.

Manuelle Prüfung und Zustellung

manual_review wird nur bei mindestens mittlerer Evidenz, ohne rotes Risiko und mit einer konkreten, vor der Abholung klärbaren Frage gesendet. Low‑Evidence- und rein technische Fälle bleiben intern. Telegram-Nachrichten erklären Modell, Preisvorteil, Marktwert, Spielraum und konkrete Prüfschritte in Klartext; technische Codes stehen nur auf der Statusseite.

Öffentliche Statusansicht

Die Statusseite wurde am 07.09.2026, 19:42 UTC soft zurückgesetzt. Anzeigenliste, Kennzahlen und Alerts zeigen nur neue Daten seit diesem Zeitpunkt; Datenbank, Dedupe, Fehlerhistorie und Listener bleiben unverändert. Stufe‑1- und Stufe‑2‑Verteilungen sind standardmäßig eingeklappt. Teststand dieser Änderung: 236/236 grün.

12 · Forensische Stufe 2

Pflicht bei hochpreisigen Kandidaten: Ab 1.000 € Angebotspreis wird vor Alert oder Review ein bildgestütztes Dossier erstellt: tatsächliche Modellidentität und Baujahr, Zustandsbefunde, Marktwertbasis, Risiko, damalige Hersteller-UVP und maximale Kaufgrenze. Bei sichtbaren Widersprüchen läuft es auch unterhalb der Schwelle. Telegram liefert das Kurzurteil; die Statistikseite zeigt das vollständige Dossier eingeklappt.

Robuster Bildabruf: Der Textpfad bleibt auf 256 KiB begrenzt. Stufe 2 kann für große Kleinanzeigen-Seiten bis 1 MiB streamen, behält aber kein HTML: Sie extrahiert dabei nur allowlist-geprüfte Bild-URLs der geöffneten Anzeige. Alle Bilddownloads bleiben separat begrenzt; darüber oder ohne eindeutige Struktur endet die Analyse weiterhin sicher mit einem sichtbaren technischen Status. Korrekt typisierte, aber zu lange Modelllisten werden vertragskonform gekürzt; rote Risiken bleiben erhalten und Forensik bei hochpreisigen Rädern bleibt Pflicht.