seokhoonj/newswatcher

newswatcher — 輪詢並遞送主題摘要

對使用者設定的來源執行一次 collect → match → summarize → deliver。 收集、比對、摘要與遞送功能都位於 newswatcher 套件中（在 PyPI 上）；此技能是薄薄的包裝器，負責呼叫其 CLI 並轉發結果。缺失的摘要收件人、LLM 金鑰/配額問題、無效的來源等情況，CLI 會以一行 newswatcher: <訊息> 回報——請照原樣轉發，不要向使用者拋出堆疊追蹤。

newswatcher 是一個已設定好的工具：主題與來源只需註冊一次（在 topics.toml / sources.toml 中，或透過 newswatcher add-topic / add-source），後續每次輪詢都會重複使用它們。因此，輪詢前請確認至少有一個主題與一個來源存在。

前置需求

此外掛程式會呼叫 newswatcher CLI，因此必須先安裝：

pipx install newswatcher        # 或：pip install newswatcher

這樣會將 newswatcher 命令加入 PATH。newswatcher 會自行尋找其金鑰——它會從 ~/.config/newswatcher/credentials.json（或環境變數）讀取提供者金鑰（GEMINI_API_KEY / OPENAI_API_KEY / CLAUDE_API_KEY），所以此技能無需擷取並傳遞金鑰。Gemini 的免費方案是預設提供者。切勿在任何地方印出金鑰值。

遞送也需要一個目的地：透過 mailmail 套件的電子郵件收件人（NEWSWATCHER_DIGEST_TO 或 --to），及/或透過 pushpush 套件的聊天路由（NEWSWATCHER_DIGEST_PUSH 或 --push）。兩者都會隨 newswatcher 安裝；pushpush 路由需使用 pushpush 自己的 CLI 設定。

執行

從 PATH 呼叫 newswatcher（加上 poll 子命令）：

newswatcher poll [options]

選項（newswatcher poll --help 為確切預設值的最終參考）：

• --to ADDRESS — 本次執行的電子郵件收件人（mailmail 地址或別名）。覆寫 NEWSWATCHER_DIGEST_TO。
• --push ROUTE — 同時遞送至 pushpush 聊天路由。覆寫 NEWSWATCHER_DIGEST_PUSH。
• --no-mail — 收集、摘要並歸檔但不遞送（用於僅查看新內容）。
• --no-store — 本次執行不歸檔已收集的文章。
• --no-heal — 本次執行跳過爬取選擇器的自我修復。
• --provider claude|openai|gemini|... / --model <id> — 覆寫 LLM 廠商/模型（預設 gemini）。

程序

1. 確認設定是否完整。 執行 newswatcher topics 與 newswatcher sources。如果任一為空，請勿自行發明主題/來源——應說明 newswatcher 需要至少一個主題與一個來源，並協助使用者新增：

   newswatcher add-topic markets --include stocks Fed "interest rate" earnings --exclude sports
   newswatcher add-source "BBC" https://feeds.bbci.co.uk/news/world/rss.xml --kind rss --topic markets
   

   儲存庫中的 docs/korean-news-rss.md 與 docs/world-news-rss.md 包含可供挑選的已驗證訂閱源網址。關鍵字比對會使用訂閱源本身的語言（英文訂閱源用英文關鍵字，韓文訂閱源用韓文關鍵字）。

2. 決定遞送方式。

   • 使用者希望遞送摘要（正常情況）：執行單純的 newswatcher poll。這需要已設定目的地（NEWSWATCHER_DIGEST_TO / --to，或 NEWSWATCHER_DIGEST_PUSH / --push）；如果使用者指定了，則傳入 --to/--push。
   • 使用者只想在此查看新內容（不發送）：執行 newswatcher poll --no-mail，然後用 newswatcher articles --since <今日日期，YYYY-MM-DD> 內嵌顯示新歸檔（每條目的標題/摘要/連結）。

3. 執行輪詢並轉發結果：N 篇新文章 行，任何 newswatcher: skipping <來源>: <原因> 行，以及摘要是否已遞送。輪詢可能需要一些時間（它會擷取每個來源並對每篇文章呼叫 LLM）——這是正常的。

4. 錯誤處理。 當 CLI 以非零值結束時，請將 newswatcher: <訊息> 一行照原樣轉發。常見的錯誤：

   • command not found: newswatcher -> 套件未安裝。引導使用者執行 pipx install newswatcher（或 pip install newswatcher）。
   • no digest destination ... -> 未設定收件人。提供 --to [email protected] 或 --push <路由>，或設定 NEWSWATCHER_DIGEST_TO / NEWSWATCHER_DIGEST_PUSH。（或使用 --no-mail 僅收集。）
   • no API key / insufficient_quota / 429 -> 提供者金鑰不存在於 ~/.config/newswatcher/credentials.json，或其配額已耗盡。引導使用者前往廠商控制台（Google AI Studio / OpenAI / Claude）。
   • another poll is already running; skipping -> 排程或手動輪詢持有單一實例鎖。這不是錯誤——newswatcher 會乾淨結束而非重複執行。
   • NEWSWATCHER_DEDUP_THRESHOLD must be ... -> 去重閾值設定錯誤；必須是 [0, 1] 之間的數字。

此技能不負責的事項

• 它不會重新實作收集、主題比對、摘要或遞送（這些由套件負責）；它總是呼叫 CLI。
• 它絕不會印出、記錄或在輸出中包含 API 金鑰值。
• 它不會自行發明主題或來源——它只會輪詢使用者已設定的項目，並僅在使用者要求時協助新增。

參見

• newswatcher recent <網址> — 在不儲存的情況下預覽訂閱源的最新項目。
• newswatcher articles [--topic NAME] [--since DATE] [--until DATE] — 查詢歸檔。
• newswatcher watch [--every N] — 在前景以間隔重複輪詢。
• newswatcher schedule install|status|remove [--every N] — 在作業系統排程器（Linux/macOS 上為 cron，Windows 上為 schtasks）中註冊週期性輪詢。
• newswatcher heal — 檢查並修復已停止匹配的爬取選擇器。