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 密钥

适用于 macOS、Linux 和 Windows 的安装脚本会在当前用户尚未安装 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，安装锁定的运行时依赖，注册每用户登录服务，并重启该服务，以便重复安装时立即运行更新后的代码。安装后打开 。

配置

默认客户端模式

普通用户默认以 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。
远程客户端使用 processednews 读取 /api/server/sources；这些是
相互独立的端点，因此未设置 NEWS_AGENT_LOCAL_TOKEN 绝不会导致本地
页面请求共享新闻认证。

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

在本地 Web 控制台的模型和投递设置部分配置模型、端点、协议、API 密钥和投递 webhook。这些字段
会自动保存，并且可以就地测试模型连接。请将
控制台保持私密，因为它会显示已配置的机密值。

机密存储在 .env 中。模型设置、偏好和投递
计划通过经过验证的本地 API 存储在 config.json 中。.env
中的 LLM 密钥变量必须与 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/...

当使用另一个密钥变量时，例如 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，当令牌缺失时回退到其公共源。

重要设置：

- preferences：兴趣、排除项、源权重、语言偏好和多样性限制。
- llm：模型、端点、API 密钥环境变量和协议。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。客户端部署
从 server_url 读取已评分的条目，条件为 score >= 60；混合部署还会暴露
滚动共享新闻 API。server_api_token_name 携带共享 API 值
processednews；它与 NEWS_AGENT_LOCAL_TOKEN 无关。
- push：启用飞书、Discord 或自定义端点。

运行

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

uv sync                         # 安装开发依赖
uv run news-agent check         # 检查 LLM 连接
uv run news-agent fetch         # 抓取并评分一次
uv run news-agent push          # 生成并发送一份摘要
uv run news-agent serve         # 运行本地 Web/API 服务
uv run news-agent mcp           # 运行 stdio MCP 服务器
uv run news-agent service status

serve 命令会启动内置调度器和本地 API，地址为 。交互式 API 文档可在  查看。

共享混合服务器必须监听其客户端可访问的接口，例如：

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

在暴露混合服务器之前，请为其管理 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 工具包括来源管理、偏好和调度更新、手动抓取/推送任务、摘要预览、任务状态和最近日志。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 许可证 授权。