1. 项目概述一个本地优先的AI摘要RSS阅读器如果你和我一样每天被海量的信息源淹没——十几个技术博客、几个新闻网站、还有社区动态光是挨个点开看标题就够呛更别说深度阅读了。传统的RSS阅读器解决了聚合问题但信息过载的痛点依然存在。最近我把自己的信息流管理工具换成了Feedclaw一个用 TypeScript 写的命令行 RSS/Atom 阅读器。它的核心卖点很直接不仅帮你把订阅源的文章抓取下来存进本地的 SQLite 数据库还能调用 Claude 或 GPT 的 API自动为这些文章生成一份精炼的 AI 摘要简报。这工具完美契合了“本地优先”和“AI增强”两个趋势。你的所有订阅数据和文章内容都躺在自己电脑的~/.feedclaw/目录下隐私和安全自己掌控。然后你可以命令它“把过去24小时‘AI’这个分类下的新文章用 Claude 总结成一份适合终端阅读的简报。” 它就会默默工作最后给你一份过滤掉噪音、提炼出核心的 digest。对于开发者、内容创作者或者任何需要高效摄入信息的人来说这相当于雇了一个不知疲倦的助理编辑。2. 核心设计思路与技术选型解析2.1 为什么是“本地SQLite 命令行CLI”Feedclaw 的架构选择反映了其清晰的产品哲学简单、可控、可脚本化。首先SQLite作为数据存储层是神来之笔。它无需任何外部数据库服务一个文件 (feedclaw.db) 搞定所有数据订阅源、文章、抓取状态。这带来了几个关键优势零部署成本用户安装即用没有数据库安装、配置的烦恼。极致便携整个数据目录可以轻松备份、迁移或同步比如用 Syncthing 或 Dropbox你的阅读历史完全属于你。开发友好Node.js 社区有better-sqlite3这样优秀的原生绑定库性能好同步API写起来也直观非常适合CLI工具这种“运行-结束”的生命周期。其次命令行接口 (CLI)是其灵魂。这并非简陋而是为了自动化和集成。通过 CLI你可以用cron或systemd timer在后台定时执行fetch和digest让信息摘要像收邮件一样成为日常流程。更重要的是--json输出标志让它可以无缝被其他脚本或 AI Agent比如其兄弟项目 OpenClaw调用成为更大自动化工作流中的一个可靠模块。2.2 条件抓取与摘要生成的工作流拆解整个工具的核心工作流可以拆解为两个松耦合的管道管道一抓取与存储订阅源管理支持通过add命令添加 RSS/Atom 链接或通过init加载预置的分类订阅包AI、开发、新闻等。智能抓取执行fetch时工具会为每个订阅源记录其ETag和Last-Modified头。下次抓取时会带上这些信息发起“条件请求”。如果服务器返回304 Not Modified则跳过该源极大节省了网络流量和抓取时间对服务器也友好。结构化存储抓取到的新文章会被解析标题、链接、发布时间、摘要或全文内容取决于订阅源提供情况等字段被规整化后存入 SQLite 数据库。每篇文章都有一个read状态标记初始为0未读。管道二过滤与摘要查询过滤当执行digest命令时工具会根据--since如24h、--category等参数从数据库中查询出符合条件的、未读的文章。内容组装将这些文章的标题、链接和内容摘要或截取的部分正文按一定格式组装成一份给 AI 的“提示词Prompt”。这里通常会有长度控制--max-articles以防 token 数超标。AI 处理将组装好的提示词通过配置的 APIAnthropic 或 OpenAI发送给指定模型如 Claude 3 Sonnet请求其生成一份连贯、精炼的摘要。输出与标记将 AI 返回的结果按指定格式终端、Markdown、HTML、JSON输出。成功后将涉及的文章标记为已读read1避免下次重复摘要。这个设计将“数据收集”和“信息消费”解耦非常灵活。你可以一天抓取多次但只在早上生成一次摘要也可以只为某个特定分类生成摘要。注意AI 摘要的质量和成本高度依赖于提示词工程和所选模型。Feedclaw 内置的提示词模板需要足够聪明能指导 AI 区分新闻、技术教程、观点文章等不同体裁并做出恰当归纳。这是项目隐含的核心竞争力之一。3. 从零开始的详细部署与配置指南3.1 环境准备与项目安装Feedclaw 要求 Node.js 版本 22 或更高并推荐使用pnpm作为包管理器。如果你还在用 npm 或 yarn我强烈建议趁此机会切换到pnpm它的磁盘空间和安装速度优势在管理 Monorepo 或需要大量依赖的项目时非常明显。# 1. 确保Node.js版本 node --version # 应 v22.0.0 # 2. 全局安装pnpm (如果尚未安装) npm install -g pnpm # 3. 克隆项目并安装依赖 git clone https://github.com/psandis/feedclaw.git cd feedclaw pnpm installWindows 用户特别注意因为依赖的better-sqlite3需要编译原生模块你必须安装Visual Studio Build Tools并确保包含“使用 C 的桌面开发”工作负载。这是一个常见的坑没有它pnpm install会在编译阶段失败。安装完成后需要构建 TypeScript 源码pnpm build这会在项目根目录生成dist文件夹里面是编译好的 JavaScript 可执行文件。3.2 核心配置API密钥与数据目录Feedclaw 的 AI 功能需要 API 密钥。它支持 Anthropic (Claude) 和 OpenAI (GPT) 两家。根据你的偏好和预算选择其一即可。1. 设置环境变量推荐这是最安全、最灵活的方式特别是当你打算设置定时任务时。# 如果你使用 Anthropic export ANTHROPIC_API_KEYsk-ant-xxxxxxxxxx # 或者如果你使用 OpenAI export OPENAI_API_KEYsk-xxxxxxxxxx为了让这个变量永久生效你可以把它加到 shell 的配置文件中如~/.bashrc,~/.zshrc或~/.bash_profile。2. 或者使用配置文件Feedclaw 会在数据目录 (~/.feedclaw/) 下寻找config.json文件。你可以手动创建并配置# 首先初始化数据目录运行任何cli命令都会自动创建 pnpm cli --help # 然后创建配置文件 cat ~/.feedclaw/config.json EOF { defaultProvider: anthropic, defaultModel: claude-3-5-sonnet-20241022, defaultFormat: terminal, digestSince: 24h } EOF关于数据目录所有数据数据库、配置、缓存默认存放在~/.feedclaw/。你可以通过设置FEEDCLAW_HOME环境变量来修改这个路径这在你想为不同项目或用途隔离数据时非常有用。export FEEDCLAW_HOME/path/to/my/feedclaw_data3.3 初始化订阅源与首次抓取项目贴心地提供了一组预分类的默认订阅源涵盖了 AI、开发、科技新闻等领域。这是快速上手的绝佳方式。# 1. 初始化添加所有默认订阅源ai, dev, news, openclaw pnpm cli init # 2. 也可以只初始化特定分类 pnpm cli init --bundle ai pnpm cli init --bundle dev,news # 3. 执行首次抓取获取文章 pnpm cli fetchinit命令执行后你会看到终端输出一系列成功添加的订阅源名称。此时这些源的信息URL、分类已经存入数据库。接着运行fetch工具会开始网络抓取。根据订阅源数量和网络状况首次抓取可能需要几十秒到几分钟。你会看到每个源的抓取状态和获取到的新文章数量。实操心得首次fetch后建议立刻运行pnpm cli list查看一下。你会发现之前只有 URL 的订阅源现在有了从 feed 中解析出来的正式名称。这个细节体现了工具的完整性——它不仅在后台干活还完善了数据展示。4. 日常使用命令详解与高效工作流4.1 订阅源管理增删改查基础的 CURD 操作是信息流的源头管理。查看订阅列表 (list)pnpm cli list这是最常用的命令之一用于概览所有订阅源。输出按分类分组并显示每个源的最后抓取时间、ID 和 URL。使用--category ai可以过滤只看某个分类。添加订阅源 (add)# 添加一个订阅源并指定分类 pnpm cli add https://blog.rust-lang.org/feed.xml --category dev # 添加但不指定分类会进入‘default’分类 pnpm cli add https://example.com/feed.xml添加成功后该源会获得一个唯一的数字 ID。记住URL 必须是有效的 RSS 或 Atom feed 地址。很多网站会在首页head部分通过link标签注明 feed 地址。移除订阅源 (remove)# 通过ID移除 pnpm cli remove 5 # 通过URL移除 pnpm cli remove https://example.com/feed.xml移除操作会从数据库中删除该订阅源及其所有历史文章请谨慎操作。导入/导出 OPML (opml-import/opml-export)这是迁移订阅列表的行业标准方式。你可以从 Feedly、Inoreader 等在线服务导出 OPML 文件然后用 Feedclaw 导入。# 导出当前所有订阅源到文件 pnpm cli opml-export my_feeds.opml # 从OPML文件导入订阅源 pnpm cli opml-import my_feeds.opml导入时工具会尝试解析 OPML 中的分类category信息。这是一个从其他阅读器无缝迁移过来的关键功能。4.2 核心操作抓取与生成摘要定时抓取 (fetch)信息更新的动力源。如前所述它利用条件请求非常高效。# 抓取所有订阅源 pnpm cli fetch # 只抓取特定ID或URL的订阅源 pnpm cli fetch --feed 3 pnpm cli fetch --feed https://blog.rust-lang.org/feed.xml我个人的习惯是在后台设置一个每小时的定时任务通过cron或launchd来运行fetch这样数据始终是最新的。生成AI摘要 (digest)这是整个工具的精华所在参数也最丰富。# 生成过去24小时内‘ai’分类的摘要输出到终端默认 pnpm cli digest --since 24h --category ai # 生成过去一周‘dev’分类的摘要输出为Markdown文件 pnpm cli digest --since 7d --category dev --format markdown weekly_dev_digest.md # 使用OpenAI的GPT-4模型生成摘要并限制最多20篇文章 pnpm cli digest --provider openai --model gpt-4 --max-articles 20 # 生成JSON格式的摘要供其他脚本处理 pnpm cli digest --format json --since 48h关键参数解析--since: 时间窗口。支持h(小时)、d(天)、w(周) 的单位组合如12h、3d、2w。它决定了摘要涵盖的文章时间范围。--max-articles:非常重要的安全阀。AI API 的调用有 token 数限制和成本考量。如果过去一段时间新文章太多这个参数可以防止提示词过长导致 API 调用失败或费用激增。默认值 50 是一个比较平衡的设置。--format: 输出格式。terminal适合在命令行快速阅读markdown和html适合保存或分享json则是为了程序化处理。注意事项digest命令只会处理未读 (read0) 的文章并且在成功生成摘要后会自动将这些文章标记为已读。这个设计保证了摘要的“新鲜度”你每次读到的都是新内容。如果你希望重新摘要某些文章目前需要在数据库层面手动重置read状态或者设计更复杂的工作流。4.3 构建自动化工作流命令行工具的威力在于自动化。下面是一个结合cron的每日摘要示例创建脚本~/scripts/daily_feedclaw.sh:#!/bin/bash export ANTHROPIC_API_KEYsk-ant-xxxxxxxxxx export PATH$PATH:/path/to/your/node_modules/.bin # 如果feedclaw未全局安装 cd /path/to/feedclaw # 抓取新文章 pnpm cli fetch # 生成AI摘要并保存为Markdown附带日期 TODAY$(date %Y-%m-%d) pnpm cli digest --since 24h --format markdown ~/Documents/feed_digests/digest_$TODAY.md # (可选) 生成特定分类的摘要 pnpm cli digest --since 24h --category ai --format terminal赋予执行权限chmod x ~/scripts/daily_feedclaw.sh添加到cron(crontab -e)# 每天上午9点运行 0 9 * * * /bin/bash /home/yourname/scripts/daily_feedclaw.sh这样每天上午你就能在指定目录下收到一份前24小时的新闻摘要Markdown文件同时在终端看到AI分类的简报。5. 高级集成作为OpenClaw技能与JSON APIFeedclaw 不仅仅是一个独立工具它被设计成OpenClaw 生态系统中的一个“技能”Skill。OpenClaw 是一个开源的 AI Agent 框架你可以把它想象成一个可编程的、本地的“AI助手操作系统”。5.1 如何作为OpenClaw技能运行首先你需要全局安装 Feedclaw以便 OpenClaw Agent 能直接调用它npm install -g feedclaw # 或使用你构建的本地版本 pnpm install -g ./feedclaw-1.0.0.tgz # 假设你打包了然后在你的 OpenClaw 工作区workspace中创建一个SKILL.md文件来描述这个技能--- name: feedclaw description: Fetch RSS feeds and generate AI news digests version: 1.0.0 requires_binaries: - feedclaw --- When the user asks about news, feeds, or digests, use the feedclaw CLI: - To check feeds: feedclaw --json fetch - To get a digest: feedclaw --json digest --format markdown - To add a feed: feedclaw --json add url当 OpenClaw Agent 运行时它会加载这个技能描述。之后你可以用自然语言对 Agent 说“帮我看看今天 AI 领域有什么新闻” Agent 会理解你的意图在后台执行类似feedclaw --json digest --since 24h --category ai --format markdown的命令获取结构化的摘要信息然后再用自然语言回复你。这就实现了通过对话来管理信息流。5.2 利用--json标志进行脚本集成即使你不使用 OpenClaw--json标志也极大地提升了 Feedclaw 的可编程性。几乎所有命令都支持这个标志它会将输出从人类可读的文本转换为结构化的 JSON。# 获取订阅源列表的JSON pnpm cli --json list # 获取抓取结果的JSON pnpm cli --json fetch # 获取摘要的JSON需要--format json pnpm cli --json digest --format json --since 12h这让你可以轻松地用 Python、Node.js 或其他任何语言编写脚本来消费 Feedclaw 的数据。例如你可以写一个脚本将每日摘要 JSON 中的重点内容提取出来自动发布到你的团队 Slack 频道或 Notion 页面。// 一个简单的Node.js脚本示例 const { execSync } require(child_process); const result execSync(feedclaw --json digest --format json --since 24h --category dev, { encoding: utf8 }); const digest JSON.parse(result); console.log(今日开发领域摘要 (${digest.generatedAt}):); digest.articles.forEach(article { console.log(- ${article.title}: ${article.summary}); });6. 故障排除与性能优化实践6.1 常见问题与解决方案在实际使用中你可能会遇到以下问题1. 抓取失败或超时现象fetch命令卡住或报错FetchError。排查网络连接检查你的网络是否能正常访问目标订阅源 URL。可以尝试用curl -I feed_url测试。订阅源格式确认 URL 是有效的 RSS/Atom。有些网站需要特定路径。尝试在浏览器中打开该 URL看返回的是否是 XML。服务器限制某些网站可能对频繁抓取有速率限制或需要 User-Agent。Feedclaw 使用的fetch库通常会设置合理的默认 UA但如果遇到问题可能需要查看其源码考虑修改请求头。解决对于不稳定的源可以考虑将其移除或寻找更稳定的镜像源。2. AI摘要生成失败或返回空现象digest命令执行后无输出或输出错误信息如Invalid API Key、Context length exceeded。排查API密钥首先确认ANTHROPIC_API_KEY或OPENAI_API_KEY环境变量已正确设置且未过期。可以用echo $ANTHROPIC_API_KEY简单验证。Token超限这是最常见的原因。如果--since时间窗口内未读文章太多即使有--max-articles限制所有文章的标题和内容摘要加起来仍可能超过模型上下文窗口。模型不可用检查config.json或命令行中指定的模型名称是否正确且你有权限访问例如你是否订阅了 Claude API 的相应模型层。解决缩短--since时间窗口如从7d改为24h。降低--max-articles的数量如从50改为20。分分类生成摘要而不是一次性生成所有分类。3. 数据库文件损坏或锁死现象任何命令都报 SQLite 相关错误如SQLITE_BUSY。解决关闭可能占用它的进程确保没有其他 Feedclaw 实例或工具在访问~/.feedclaw/feedclaw.db。备份与重置最彻底的方法是备份后重置。关闭所有相关进程然后cp ~/.feedclaw/feedclaw.db ~/.feedclaw/feedclaw.db.backup接着删除原文件rm ~/.feedclaw/feedclaw.db。再次运行pnpm cli init会创建新的空数据库。但你会丢失所有历史数据和订阅列表所以需谨慎。6.2 性能调优与使用建议1. 抓取频率优化不要过于频繁地运行fetch。对于新闻类订阅源每小时一次足矣对于技术博客每天一次甚至每周一次都可能没问题。过度抓取既浪费资源也可能触发目标网站的防爬机制。合理设置cron计划。2. 摘要生成成本控制AI API 调用是主要成本。务必合理使用--since和--max-articles。对于高产出的新闻源如 Hacker News建议单独为其设置更短的时间窗口和文章上限。你也可以考虑在非高峰时段如 API 费用较低的时段运行摘要生成任务。3. 数据目录管理定期检查~/.feedclaw/目录的大小。SQLite 数据库会随着时间增长。虽然文章内容通常不大但长期积累也可能达到几百MB。你可以考虑定期归档写一个脚本将超过一定时间如3个月的已读文章从主表中移动到归档表或导出为 JSON 后删除。清理未订阅源的文章当你移除一个订阅源时其历史文章可能仍留在数据库中。可以手动清理或等待工具未来提供更精细的数据管理功能。4. 自定义默认订阅源项目自带的feeds/default.json文件是预置订阅源的来源。你可以直接编辑这个文件添加你喜欢的源或者创建自己的 JSON 文件然后通过pnpm cli init --from my-feeds.json来初始化。这是打造个性化信息起点的最佳方式。