新闻聚合助手 huawolf/news-agent

News Agent

News Agent 是本地个人新闻服务。它把 RSS 源、Hacker News 和内置信号源汇总成一个带评分的新闻池，再加上 GitHub Trending 摘要，然后用兼容 OpenAI 的 LLM 做排序、摘要，并推送到飞书或 Discord。

它能在 macOS、Windows 和 Linux 上运行。本地 Web 控制台、HTTP API 和 stdio MCP 服务器管理同一套配置和任务。

News Agent 概览

功能

- 把 RSS 源、Hacker News、Product Hunt、Reddit、App Store 新应用、V2EX、36Kr、少数派、OSChina、即刻话题和其他内置源汇总成一个新闻池，同时生成 GitHub Trending。
- 用 LLM 对内容排序、过滤、去重、摘要。
- 从 Web 控制台、API 或 MCP 添加、更新、验证、删除 RSS 源。
- 设置兴趣、排除项、源权重、推送时间、条目上限。
- 定时抓取和推送，也可以手动触发。
- 推送到飞书、Discord 或自定义 HTTP 端点。
- 把配置、日志和任务历史保存在本地用户数据目录。
- 本地控制面默认绑定 127.0.0.1:12301。

环境要求

- macOS、Windows 或 Linux
- uv
- 一个 OpenAI Chat、OpenAI Responses 或 Anthropic Messages 端点的 API key

macOS、Linux 和 Windows 的安装脚本会在 uv 不可用时，自动为当前用户安装 uv。

安装

不用先克隆仓库，一条终端命令就能安装 News Agent：

macOS 或 Linux：

curl -fsSL https://raw.githubusercontent.com/huawolf/news-agent/main/scripts/install.sh | bash

Windows PowerShell：

iwr -useb https://raw.githubusercontent.com/huawolf/news-agent/main/scripts/install.ps1 | iex

安装脚本会从 .env.example 生成 .env，安装锁定版本的运行时依赖，注册一个当前用户的登录服务，并重启该服务，这样重复安装会立刻运行更新后的代码。安装完成后打开 <http://127.0.0.1:12301>。

配置

默认客户端模式

普通用户默认以 client 模式运行。共享服务器抓取并评分公共源目录一次；每个客户端拉取最近 24 小时、评分不低于 60 的已处理条目，以及最近一次成功的 GitHub 摘要，只添加并评分自己的私有自定义 RSS 源，然后用各自的偏好、时间表、语言、条目上限、LLM 和推送渠道来挑选、摘要、发送日报。

默认连接是：

"mode_settings": {
"mode": "client",
"server_url": "http://13.158.182.33:12301",
"server_api_token_name": "processednews"
}

processednews 是共享新闻 API 的值，不保护本地配置页面。NEWS_AGENT_LOCAL_TOKEN 是另一个可选的私有密码，只用于本地 Web/配置 API。绝不要用其中一个替换另一个。
本地页面在可选的本地控制规则下读取 /api/news-sources。
远程客户端读取 /api/server/sources，使用 processednews；这是两个独立端点，所以未设置 NEWS_AGENT_LOCAL_TOKEN 时，本地页面绝不会请求共享新闻认证。

运行共享服务的运维人员使用 mix 模式。Mix 模式执行服务端抓取与评分工作，保留滚动 24 小时内存缓存，暴露共享新闻端点，也能运行自己的投递工作流。手动运行和定时运行都会处理全部已启用源集合以及 GitHub；投递计划只控制时间和最终新闻条数。
没有 mode_settings 的配置会收到与普通用户相同的 client 默认值。只有自托管运行时，才需要显式设置 standalone 或 mix。

在本地 Web 控制台的 Model and delivery settings 区域配置模型、端点、协议、API key 和投递 webhook。字段会自动保存，模型连接可以就地测试。请保持控制台私密，因为它会显示已配置的密钥值。

密钥存放在 .env。模型设置、偏好和投递计划通过经过校验的本地 API 存入 config.json。.env 中的 LLM key 变量必须与 llm.apiKeyName 一致；默认配置使用 OPENAI_API_KEY。

OPENAI_API_KEY=your_llm_api_key
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

使用其他 key 变量时，比如 DEEPSEEK_API_KEY 或 ANTHROPIC_API_KEY，要通过本地 API 把 llm.apiKeyName 设为同一个名字。
直接编辑 .env 后，在项目目录下重启服务：

uv run news-agent service restart

服务首次启动时，会从 config.json.example 创建 config.json。请使用 Web 控制台或本地 API 管理模型设置、源、偏好和计划，不要替换正在使用的配置文件。

可选的源集成也可以使用 .env 凭据。例如 Product Hunt，配置后使用 PH_TOKEN，token 缺失时回退到它的公开源。

重要设置：

- preferences：兴趣、排除项、源权重、语言偏好和多样性限制。
- llm：模型、端点、API-key 环境变量和协议。Web 控制台会从端点和模型名识别 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages，允许手动覆盖，并能保存和测试当前连接。
- sections.signals：内置信号适配器，覆盖 Product Hunt、Reddit fallback、GitHub 变体、V2EX、RSSHub 主题、App Store 区域和国内 RSS 源。
- schedule.fetch_lookback_minutes：抓取回溯窗口；默认 1440 分钟，所以内置信号只保留最近 24 小时，GitHub Trending 这类每日排行榜页面除外。
- log.retention_days：保留多少天的日志目录；默认 30 天。
- delivery.schedules：cron 调度，以及每次投递统一的新闻 max_items 上限。每次运行都会处理完整的新闻源池和 GitHub；不会按调度挑选新闻源。
不显式指定调度时，投递默认在每天 10:00 和 20:00 进行，每次最多 10 条新闻。
- delivery.immediate：高分提醒阈值和每日上限。
- mode_settings：选择 standalone、mix 或 client。client 部署从 server_url 读取已评分的条目，条件是 score >= 60；mix 部署还会开放滚动共享新闻 API。server_api_token_name 携带共享 API 值 processednews；它与 NEWS_AGENT_LOCAL_TOKEN 无关。
- push：启用飞书、Discord 或自定义端点。

运行

所有命令都用 uv run news-agent：

uv sync # Install development dependencies
uv run news-agent check # Check LLM connectivity
uv run news-agent fetch # Fetch and score once
uv run news-agent push # Generate and send one digest
uv run news-agent serve # Run the local web/API service
uv run news-agent mcp # Run the stdio MCP server
uv run news-agent service status

serve 命令会启动内置调度器和本地 API，地址是 <http://127.0.0.1:12301>。交互式 API 文档在 <http://127.0.0.1:12301/docs>。

共享 mix 服务器必须监听客户端能访问到的网卡，例如：

uv run news-agent serve --host 0.0.0.0 --port 12301

对外暴露 mix 服务器之前，先为它的管理 API 设置一个私有的 NEWS_AGENT_LOCAL_TOKEN。客户端读取共享新闻时仍然只用 processednews。

只卸载登录服务、不删除数据：

./scripts/uninstall.sh

Windows 上：

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1

本地 API 与 MCP

本地 API 支持配置、新闻源、投递、任务和日志操作。
在 .env 里设置 NEWS_AGENT_LOCAL_TOKEN，用来保护这些本地管理请求。它不是共享服务器值 processednews，也从不用于客户端到服务器的新闻获取。

MCP 服务器面向本地智能体进程：

{
"command": "uv",
"args": ["run", "news-agent", "mcp"],
"cwd": "/path/to/news-agent"
}

可用的 MCP 工具包括新闻源管理、偏好与调度更新、手动 fetch/push 任务、摘要预览、任务状态和最近日志。run_push 需要显式确认。

执行安装或初始配置的 AI 智能体应遵循 News Agent Operator skill。它定义了非浏览器工作流，涵盖密钥处理、API 配置、服务重启、健康检查、模型测试、预览和确认投递。

数据与日志

运行时数据默认存放在项目目录下：

| 类型 | 目录 |
| 新闻数据 | news-data/ |
| 日志 | logs/ |
| 任务记录 | runs/ |

用 NEWS_AGENT_DATA_DIR 或 NEWS_AGENT_CONFIG 覆盖这些路径。应用日志使用轮转文件；项目不依赖系统日志。

Mix 服务器和独立服务器会把最近一次成功的 GitHub 板块保留在 news-data/github-latest.md；共享客户端通过 /api/server/github-trending 读取它。

安全

News Agent 默认绑定回环地址。普通客户端应保持这个默认值。Mix 服务器可能为共享新闻客户端开放端口 12301；请用 NEWS_AGENT_LOCAL_TOKEN 保护它的本地管理路由，并在可行的情况下限制网络访问。公开的 processednews 值不是管理密码。不要把 .env、webhook URL 和 API 密钥纳入版本控制。

贡献

欢迎提交 issue 和 pull request。请保持改动聚焦，为行为变更补充测试，并在配置或面向用户的行为发生变化时更新相关文档。

许可证

本项目基于 MIT License 授权。