seokhoonj/newswatcher

newswatcher — interroger et livrer le digest thématique

Exécutez collecter -> filtrer -> résumer -> livrer en une seule commande sur les sources configurées par l'utilisateur. La collecte, le filtrage, le résumé et la livraison sont pris en charge par le paquet newswatcher (sur PyPI) ; cette compétence n'est qu'une fine surcouche qui appelle son interface en ligne de commande et relaie le résultat. Un destinataire absent, un problème de clé LLM ou de crédit, une source inaccessible, etc. sont renvoyés par la CLI sous la forme d'une ligne newswatcher : <message> — relayer cette ligne telle quelle sans renvoyer de trace de pile à l'utilisateur.

newswatcher est un outil configuré : les sujets et les sources sont enregistrés une fois (dans topics.toml / sources.toml, ou via newswatcher add-topic / add-source), puis chaque réutilisation les utilise. Avant d'interroger, vérifiez donc qu'au moins un sujet et une source existent.

Prérequis

Ce plugin appelle la CLI newswatcher ; il faut donc l'installer d'abord :

pipx install newswatcher        # ou : pip install newswatcher

Cela place la commande newswatcher dans le PATH. newswatcher trouve sa propre clé — il lit la clé du fournisseur (GEMINI_API_KEY / OPENAI_API_KEY / CLAUDE_API_KEY) depuis ~/.config/newswatcher/credentials.json (ou l'environnement), donc cette compétence n'a jamais besoin d'extraire et de passer une clé. Le niveau gratuit de Gemini est le fournisseur par défaut. N'affichez jamais la valeur d'une clé où que ce soit.

La livraison a aussi besoin d'une destination : un destinataire e-mail (NEWSWATCHER_DIGEST_TO, ou --to) via le paquet mailmail, et/ou une route de chat (NEWSWATCHER_DIGEST_PUSH, ou --push) via le paquet pushpush. Les deux sont installés avec newswatcher ; une route pushpush se configure avec la propre CLI de pushpush.

Exécution

Appelez newswatcher depuis le PATH avec la sous-commande poll :

newswatcher poll [options]

Options (newswatcher poll --help fait foi pour les valeurs exactes par défaut) :

• --to ADRESSE — destinataire e-mail pour cette exécution (une adresse ou un alias mailmail). Remplace NEWSWATCHER_DIGEST_TO.
• --push ROUTE — livrer également vers une route de chat pushpush. Remplace NEWSWATCHER_DIGEST_PUSH.
• --no-mail — collecter, résumer et archiver mais NE PAS livrer (utilisez ceci pour simplement voir ce qui est nouveau).
• --no-store — ne pas archiver les articles collectés durant cette exécution.
• --no-heal — sauter la passe de réparation automatique des sélecteurs de crawl pour cette exécution.
• --provider claude|openai|gemini|... / --model <id> — remplacer le fournisseur/modèle LLM (gemini par défaut).

Procédure

1. Confirmer la configuration. Exécutez newswatcher topics et newswatcher sources. Si l'un des deux est vide, n'inventez PAS de sujets/sources — expliquez que newswatcher a besoin d'au moins un sujet et d'une source, et aidez l'utilisateur à les ajouter :

   newswatcher add-topic marchés --include stocks Fed "taux d'intérêt" résultats --exclude sports
   newswatcher add-source "BBC" https://feeds.bbci.co.uk/news/world/rss.xml --kind rss --topic marchés
   

   Les fichiers docs/korean-news-rss.md et docs/world-news-rss.md du dépôt contiennent des URL de flux vérifiées parmi lesquelles choisir. Les mots-clés correspondent dans la langue du flux (mots-clés anglais pour un flux anglais, coréens pour un flux coréen).

2. Décider de la livraison.

   • L'utilisateur souhaite que le digest soit livré (cas normal) : exécutez newswatcher poll. Cela nécessite une destination configurée (NEWSWATCHER_DIGEST_TO / --to, ou NEWSWATCHER_DIGEST_PUSH / --push) ; passez --to/--push si l'utilisateur en donne une.
   • L'utilisateur veut juste voir ce qui est nouveau ici, sans envoyer : exécutez newswatcher poll --no-mail, puis affichez l'archive fraîche avec newswatcher articles --since <date d'aujourd'hui, AAAA-MM-JJ> (titre / résumé / lien par entrée).

3. Lancer le poll et relayer le résultat : la ligne N nouvel(s) article(s), les lignes newswatcher : source <source> ignorée : <raison>, et si le digest a été livré. Un poll peut prendre un certain temps (il récupère chaque source et appelle le LLM par article) — c'est normal.

4. Gestion des erreurs. Quand la CLI se termine avec un code non nul, relayez la ligne newswatcher : <message> telle quelle. Cas fréquents :

   • command not found: newswatcher -> le paquet n'est pas installé. Dirigez l'utilisateur vers pipx install newswatcher (ou pip install newswatcher).
   • no digest destination ... -> aucun destinataire configuré. Proposez --to [email protected] ou un --push <route>, ou définissez NEWSWATCHER_DIGEST_TO / NEWSWATCHER_DIGEST_PUSH. (Ou exécutez avec --no-mail pour juste collecter.)
   • no API key / insufficient_quota / 429 -> la clé du fournisseur est absente de ~/.config/newswatcher/credentials.json, ou ses crédits sont épuisés. Dirigez l'utilisateur vers la console du fournisseur (Google AI Studio / OpenAI / Claude).
   • another poll is already running; skipping -> un poll planifié ou manuel détient le verrou d'instance unique. Pas une erreur — newswatcher se termine proprement sans double exécution.
   • NEWSWATCHER_DEDUP_THRESHOLD must be ... -> un paramètre de seuil de dédoublonnage mal formé ; il doit être un nombre dans [0, 1].

Ce que cette compétence ne fait pas

• Elle ne réimplémente pas la collecte, le filtrage par sujet, le résumé ou la livraison ici (le paquet s'en charge) ; elle appelle toujours la CLI.
• Elle n'affiche, ne journalise ni n'inclut jamais la valeur d'une clé API dans la sortie.
• Elle n'invente pas de sujets ou de sources — elle interroge ce que l'utilisateur a configuré, et les aide à en ajouter uniquement sur demande.

Voir aussi

• newswatcher recent <url> — prévisualiser les derniers articles d'un flux (sans stockage) avant de l'ajouter.
• newswatcher articles [--topic NOM] [--since DATE] [--until DATE] — interroger l'archive.
• newswatcher watch [--every N] — répéter le poll à intervalles réguliers en premier plan.
• newswatcher schedule install|status|remove [--every N] — enregistrer un poll récurrent avec le planificateur du système (cron sur Linux/macOS, schtasks sur Windows).
• newswatcher heal — vérifier et réparer les sélecteurs de crawl qui ne correspondent plus.