seokhoonj/newswatcher

newswatcher — 轮询并投递主题摘要

一次性对用户配置的源执行 采集 → 匹配 → 摘要 → 投递 流程。 采集、匹配、摘要和投递功能全部实现在 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 会自行查找 API 密钥 —— 它从 ~/.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 [选项]

选项（请以 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 收录了经验证的 Feed URL 供选择。关键词匹配时使用 Feed 自身的语言（英文 Feed 使用英文关键词，韩文 Feed 使用韩文关键词）。

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: 跳过 <源>: <原因> 行，并说明摘要是否已投递。轮询可能需要一些时间（它会抓取每个源并对每篇文章调用 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 <url> — 预览 Feed 的最新条目（不存储），用于添加前评估。
• 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 — 检查并修复不再匹配的爬虫选择器。