ClawBeat：基于Python与React的AI智能体信息聚合引擎架构解析

1. 项目概述：ClawBeat，一个为AI生态打造的智能信息聚合引擎

如果你和我一样，长期关注AI Agent、开源智能体这些前沿领域，肯定有过这样的烦恼：信息太散了。今天GitHub上冒出一个新项目，明天arXiv上挂了一篇重磅论文，后天某个社区又有个线上分享会。每天在十几个网站、Discord频道和RSS源之间反复横跳，效率低下不说，还容易错过真正重要的信号。ClawBeat这个项目，就是为了解决这个痛点而生的。它本质上是一个高度自动化的“情报中心”，专门为OpenClaw、Moltbot、Steinberger等AI智能体生态服务，通过Python脚本（它称之为“锻造炉”）每日自动抓取、清洗、评分并聚合来自新闻、论文、视频、代码库和社区活动等多个维度的信息，最终通过一个简洁的React前端呈现出来。

这个项目的核心价值在于“降噪提纯”。它不是一个简单的RSS阅读器，而是通过一套复杂的算法（包括语义向量聚类、命名实体识别、关键词密度检查等）来合并重复内容、识别高质量信源，并为每日最重要的信息打上“Lead Signal”（领先信号）的标签。对于开发者、研究者或是任何想紧跟AI智能体领域脉搏的人来说，这样一个工具能节省大量信息筛选的时间，让你把精力集中在消化和理解上，而不是寻找和过滤上。接下来，我会带你深入它的架构、实现细节，并分享我在复现和思考这个项目时的一些实操心得。

2. 系统架构与核心设计思路拆解

ClawBeat的架构清晰地区分了数据生产（后端锻造）和数据消费（前端展示）两个部分，中间通过Supabase这个PostgreSQL云服务作为数据枢纽。这种设计使得前后端可以独立开发和部署，非常符合现代Web应用的理念。

2.1 前后端分离与数据流设计

整个系统的数据流可以概括为：多个独立的Python数据采集脚本（Forge） -> Supabase数据库 -> 静态/动态前端页面。

后端（数据锻造层）： 这是项目的“发动机”。它由两个主要的Python脚本驱动：

1. forge.py：这是主力，负责抓取新闻、学术论文、YouTube视频和GitHub仓库。它每天自动运行，像一个不知疲倦的侦察兵，从互联网的各个角落搜集情报。
2. events_forge.py：专门负责挖掘社区活动信息。它的策略更有趣，分为两层：第一层从常规信息流（如Reddit、Hacker News）中嗅探出包含活动链接的内容；第二层则直接针对Luma、Meetup等特定活动平台进行精准抓取。

这些脚本做完数据采集后，并不会直接推给前端，而是将所有结构化的数据（标题、链接、摘要、分数、标签等）写入Supabase的对应表中。Supabase在这里不仅扮演了数据库的角色，其自带的RESTful API和实时订阅功能也为前端提供了极大的便利。

前端（展示层）： 前端采用了混合渲染策略，兼顾了动态交互和静态部署的便利性。

• 核心动态应用：主入口index.tsx是一个标准的React 19 + TypeScript + Vite应用，它负责渲染最核心的“Intel Feed”（情报动态）页面。这个页面是动态的，内容随数据库实时更新。
• 独立静态页面：项目巧妙地将“研究”、“媒体”、“代码库”、“活动日历”和“管理后台”这几个相对独立的部分，做成了放在public/目录下的纯HTML页面。这些页面通过esm.sh直接引入编译好的ES模块，无需构建步骤即可运行。这样做的好处是，你甚至可以直接用Nginx托管这些HTML文件，它们自己就能从Supabase拉取数据并完成渲染，极大地简化了部署复杂度。

这种架构选择体现了务实的工程思维：核心的、需要复杂状态交互的部分用现代框架搞定；而内容导向的、相对静态的部分则追求极致的轻量与可移植性。

2.2 技术栈选型背后的逻辑

为什么是这些技术？每一个选择都有其考量。

• Python作为采集语言：生态丰富是王道。feedparser处理RSS，yt-dlp下载视频信息，requests调用各种API，spaCy做实体识别，google-generativeai调用Gemini API。Python在数据抓取和预处理领域的库资源无人能及，快速原型和迭代能力极强。
• Supabase作为数据层：它提供了开箱即用的数据库、认证、存储和实时功能。对于这样一个个人或小团队项目，使用Supabase避免了自建数据库和维护API服务器的运维负担。其提供的JavaScript客户端库与React结合非常好用，简单的数据表CRUD操作几乎可以瞬间完成。
• React 19 + Vite + TypeScript作为前端核心：这是目前构建现代、高效、可维护Web应用的事实标准组合。Vite的快速冷启动和热更新提升了开发体验，TypeScript保证了大型应用下的代码安全性。React 19带来的新特性（如Actions）也为未来功能扩展留有余地。
• Gemini API用于语义去重：这是项目在“智能”层面的点睛之笔。传统的去重基于标题或URL，但Gemini的文本嵌入模型能将文章摘要转换为高维向量，通过计算余弦相似度，即使两篇报道措辞不同但核心内容一致，也能被识别为重复。设定0.82的相似度阈值是一个经验值，需要在召回率和准确率之间取得平衡（阈值越高，去重越严格）。

注意：使用Gemini API等商业服务会产生费用。项目中的gemini-embedding-001模型调用是计费的。在自部署时，你需要注册Google AI Studio并创建API密钥，同时务必关注用量和成本。对于纯个人使用，也可以考虑换用开源的句子嵌入模型（如all-MiniLM-L6-v2），通过Hugging Face Transformers本地运行，虽然效果可能略有差异，但可以做到零成本。

3. 核心模块深度解析与实操要点

理解了整体架构，我们深入到几个核心模块，看看它们是如何工作的，以及在实际操作中需要注意什么。

3.1 智能去重与内容聚合引擎 (forge.py)

这是整个项目最复杂、最核心的部分。它的工作流程可以细分为以下几个阶段：

第一阶段：数据抓取 (Fetching)脚本会并发或顺序地从多个信源拉取数据：

• 新闻：通过Google News RSS订阅特定关键词（如“OpenClaw”、“AI Agent”）。
• 视频：利用yt-dlp库，搜索YouTube上与核心品牌相关的视频。
• 代码库：调用GitHub REST API，搜索相关主题的仓库。
• 论文：从arXiv和Semantic Scholar的API获取预印本。

这里的一个关键技巧是设置合理的请求间隔和错误处理。对于公开API（如GitHub），务必遵守速率限制，并在代码中加入time.sleep()以避免被封。对于RSS源，要检查其更新频率，避免过于频繁的请求。

第二阶段：内容清洗与增强 (Cleaning & Enrichment)原始数据往往很“脏”，需要清洗。

1. 关键词密度检查：项目定义了一个CORE_BRANDS列表（如[‘OpenClaw’， ‘Moltbot’]）。它会检查文章摘要中这些关键词的出现频率。密度过低的内容可能只是泛泛而谈，相关性弱，会被过滤或降权。这保证了内容与主题的高度相关。
2. 命名实体识别 (NER)：使用spaCy的en_core_web_sm模型从文章摘要中提取人名、组织名、地点等实体作为标签。这些标签不仅用于前端展示和过滤，也为后续的内容理解提供了结构化信息。
3. 语义向量嵌入与聚类：这是去重的核心。将每篇文章的摘要通过Gemini Embedding API转换为一个768维（或其他维度）的向量。然后，计算新文章与数据库中已有文章向量的余弦相似度。如果相似度超过0.82，则认为内容重复。对于重复文章，脚本会执行“合并”操作：保留更早或来源更权威的那一篇，并将新文章的来源链接作为“更多报道”附加进去。这确保了信息流的整洁，同时保留了信息来源的多样性。

第三阶段：评分与持久化 (Scoring & Persistence)清洗后的数据会被赋予一个初始分数，并写入Supabase。

• 评分因素：包括来源是否在白名单内（whitelist.json）、是否有“更多报道”（表明事件受关注度高）、发布时间的新鲜度等。
• 持久化：使用Supabase的Python客户端库，将数据插入到对应的news_items、videos等表中。这里要注意数据格式的匹配，特别是日期字段，项目中使用MM-DD-YYYY和MM/DD/YYYY两种格式，在插入和查询时需要保持一致。

3.2 社区活动发现引擎 (events_forge.py)

活动信息的抓取比普通新闻更棘手，因为活动信息可能深藏在社区帖子、日历页面中，没有标准的API。

双层抓取策略解析：

• Layer 1 (链接发现)：从Google News、Reddit、Hacker News等通用信息流中，通过正则表达式或简单的字符串匹配，寻找指向已知活动平台（如lu.ma、meetup.com）的URL。这相当于撒下一张大网，捕捉所有可能的线索。
• Layer 2 (深度提取)：对于Layer 1发现的URL，启动对应的“平台爬虫”。例如，针对Luma平台，脚本可能需要模拟浏览器访问，解析页面HTML，提取活动标题、描述、时间、地点等结构化信息。项目提到禁用了Eventbrite，就是因为其数据可能通过JSON-LD注入，难以稳定抓取，这体现了在爬虫开发中“有所为有所不为”的务实态度。

验证与过滤：并非所有抓取到的活动都相关。脚本会强制要求活动标题或描述中必须包含“openclaw”字样。这是一个简单但有效的过滤器，确保了活动与目标生态强相关。

3.3 前端混合渲染策略的实现

前端的设计兼顾了用户体验和部署简便性。

动态核心 (index.tsx)： 这是标准的单页应用(SPA)。它使用Supabase的JavaScript客户端订阅news_items表的数据变化，实现实时或准实时的信息流更新。Lead Signal（领先信号）卡片会根据每日文章的评分动态选出前四名进行展示。管理员可以通过/admin.html后台手动覆盖这个自动选择，这为内容运营提供了灵活性。

独立页面 (public/*.html)： 这些页面是技术上的亮点。它们不经过Vite的构建流程，直接通过<script type=“module”>标签引入esm.sh上的React和Supabase客户端库。页面自身的逻辑写在同一个HTML文件内的<script>标签里。例如，research.html会直接查询Supabase的research_papers表并渲染列表。

<!-- 简化示例：public/research.html 的一部分 --> <div id=“root”></div> <script type=“module”> import { createRoot } from ‘https://esm.sh/react-dom/client‘; import { supa } from ‘./supabaseClient.js‘; // 一个封装了Supabase初始化的模块 function ResearchPage() { // 使用React状态和效应钩子获取数据 const [papers, setPapers] = React.useState([]); React.useEffect(() => { supa.from(‘research_papers‘).select(‘*‘).order(‘published_date‘, { ascending: false }).then(({ data }) => setPapers(data)); }, []); return ( <div> <h1>Research Papers</h1> {papers.map(paper => ( /* 渲染每篇论文 */ ))} </div> ); } const root = createRoot(document.getElementById(‘root‘)); root.render(<ResearchPage />); </script>

这种方式的巨大优势在于，你只需要将dist/目录（主SPA的构建产物）和public/目录一起扔到任何静态托管服务（如Netlify, Vercel, GitHub Pages, 甚至是一个简单的对象存储）上，整个网站就能运行。无需Node.js服务器，部署成本极低，且性能出色。

4. 本地开发与环境搭建全流程

要运行或修改ClawBeat，你需要搭建完整的本地开发环境。以下是步步为营的指南。

4.1 前端开发环境搭建

1. 克隆代码与安装依赖：

   git clone <repository-url> cd clawbeat npm install

   这一步会安装所有package.json中定义的依赖，包括React、TypeScript、Vite以及Supabase客户端库。

2. 启动开发服务器：

   npm run dev

   Vite会启动一个开发服务器，通常位于http://localhost:5173。此时打开浏览器，你会看到前端界面，但由于没有后端数据和正确的环境变量，页面可能为空或报错。

4.2 后端Python环境与数据锻造炉配置

这是让项目“活”起来的关键。

1. 创建虚拟环境与安装依赖：

   python -m venv .venv # 创建虚拟环境 # 激活虚拟环境 # 在Windows上: .venv\Scripts\activate # 在macOS/Linux上: source .venv/bin/activate pip install -r requirements.txt

   requirements.txt包含了requests,feedparser,yt-dlp,spacy,google-generativeai,supabase等所有必需的库。

2. 安装spaCy语言模型：

   python -m spacy download en_core_web_sm

   这是forge.py进行命名实体识别所必需的，务必执行。

3. 配置环境变量： 在项目根目录创建.env文件，填入以下关键信息：

   GEMINI_API_KEY=your_actual_gemini_api_key_here SUPABASE_URL=https://your-project-ref.supabase.co SUPABASE_SERVICE_KEY=your_supabase_service_role_key_here GITHUB_TOKEN=your_personal_github_token_optional

   • GEMINI_API_KEY：从 Google AI Studio 获取。这是语义去重的核心。
   • SUPABASE_URL & SUPABASE_SERVICE_KEY：在Supabase项目设置的API页面找到。Service Role密钥拥有最高权限，务必妥善保管，不要泄露到客户端。
   • GITHUB_TOKEN：在GitHub设置中生成一个Personal Access Token。非必须，但可以大幅提高GitHub API的请求速率限制（从60次/小时到5000次/小时）。

4. 初始化Supabase数据库： 项目没有直接提供SQL建表脚本。你需要根据README或代码中的schema描述，在Supabase的SQL编辑器中手动创建news_items、videos、github_projects、research_papers、events、feed_metadata、spotlight_overrides这些表，并设置好字段类型和索引。这是一个关键的实操步骤，表结构必须与Python脚本中的插入逻辑匹配。

5. 运行锻造脚本：

   # 确保虚拟环境已激活 python forge.py python events_forge.py

   首次运行可能会因为网络、API限制或数据格式问题报错。需要根据错误信息逐一调试。成功后，去Supabase的Table Editor查看，应该能看到数据被写入相应的表中。

4.3 前后端联调

1. 确保前端开发服务器 (npm run dev) 和后端数据（Supabase已填充）都已就绪。
2. 在前端代码（通常是src目录下的某个文件）中，配置Supabase客户端，使用SUPABASE_URL和一个对前端安全的ANON_KEY（在Supabase项目设置的API页面获取），而不是SERVICE_KEY。
3. 刷新前端页面，此时应该能看到从Supabase成功获取并渲染的数据。

5. 部署方案与性能优化考量

项目本身提供了极佳的静态部署基础。以下是几种可行的部署路径：

方案一：全静态托管 (推荐用于展示)

1. 构建前端：npm run build，生成dist目录。
2. 将dist目录下的所有文件，连同public目录下的所有.html文件，一起上传到Netlify、Vercel、Cloudflare Pages或任何静态托管服务。
3. 在托管平台的环境变量设置中，配置前端的SUPABASE_URL和SUPABASE_ANON_KEY。
4. 后端Python脚本（forge.py）需要单独运行。你可以使用一台云服务器（如AWS EC2、DigitalOcean Droplet），通过cron作业定时（例如每天凌晨2点）执行脚本。更优雅的方式是使用云函数（如AWS Lambda、Google Cloud Functions）或定时任务服务（如GitHub Actions的schedule trigger），这样无需维护服务器。

方案二：一体化部署 (适用于全功能复现)使用像Railway、Render或Heroku这样的平台，它们可以同时托管你的前端静态文件和运行定时任务（通过Procfile或Dockerfile定义）。你需要将Python锻造脚本也放入仓库，并配置好平台的定时任务调度器。

性能与优化提示：

• 数据库索引：务必在Supabase中为经常查询的字段建立索引，如news_items.date、news_items.score、events.start_date。这能极大提升前端页面的查询速度。
• 前端懒加载与分页：当前实现可能是一次性拉取所有数据。对于数据量增长的情况，应考虑在前端实现无限滚动或分页，避免首次加载过慢。
• 错误处理与日志：在生产环境中，锻造脚本必须有完善的错误处理（try-catch）和日志记录（写入文件或发送到日志服务），以便在出现问题时排查。
• 成本监控：密切关注Gemini API的调用量，设置预算警报。GitHub API如果使用token，也要注意速率限制。

6. 扩展思路与个性化定制

ClawBeat作为一个优秀的基础框架，有很大的扩展空间：

1. 信源扩展：修改forge.py，添加新的数据源。例如，抓取特定Subreddit（如r/MachineLearning）、Discord频道（通过Webhook或API，需谨慎）、Twitter/X列表（通过官方API或第三方服务）的内容。
2. 算法优化：
   • 评分模型：当前的评分规则可以更复杂。可以引入机器学习模型，根据用户的点击、停留时间等隐式反馈来动态调整文章评分，实现个性化推荐。
   • 去重阈值：0.82的相似度阈值可能不适合所有场景。可以设计一个A/B测试，调整阈值并观察对信息流质量和重复率的影响。
3. 功能增强：
   • 用户系统：集成Supabase Auth，让用户可以收藏文章、订阅特定标签、设置邮件摘要。
   • 搜索功能：利用Supabase的全文搜索或集成Algolia、Meilisearch等专业搜索服务。
   • 移动端应用：基于现有的React代码，用React Native或Capacitor可以相对容易地打包成移动App。
4. 主题切换：你不是只能做OpenClaw。修改CORE_BRANDS列表和抓取的关键词，这个框架可以快速适配到任何你感兴趣的垂直领域，比如“Web3”、“独立游戏开发”、“生物科技”等，打造你自己的垂直领域情报站。

7. 常见问题与故障排查实录

在复现和运行此类项目时，你几乎一定会遇到下面这些问题。这里是我的踩坑记录和解决方案。

Q1: 运行python forge.py时报错ModuleNotFoundError: No module named ‘google.generativeai‘A1: 这通常是因为没有在正确的Python环境中安装依赖。请确保你已经激活了虚拟环境（.venv），并且是在该环境下执行的pip install -r requirements.txt。在VS Code等编辑器中，务必在底部状态栏选择正确的Python解释器（指向.venv下的那个）。

Q2: Supabase 连接失败，提示Invalid API key或Failed to fetch。A2: 分前后端检查：

• 后端脚本：检查.env文件中的SUPABASE_SERVICE_KEY是否正确，并且拥有足够的数据库操作权限（通常是service_role密钥）。
• 前端页面：检查前端代码中初始化的Supabase客户端使用的SUPABASE_URL和SUPABASE_ANON_KEY是否正确。ANON_KEY和SERVICE_KEY是不同的，前端绝不应该使用SERVICE_KEY。确保这些密钥在部署平台的环境变量中已正确设置。

Q3: 锻造脚本能运行，但抓不到数据，或者抓到的数据都是空的。A3: 逐步排查：

1. 检查网络和API：首先确认你的服务器或本地网络可以访问外部API（如news.google.com， api.github.com）。可以写一个简单的测试脚本，用requests直接调用目标API，看返回是否正常。
2. 检查关键词：确认CORE_BRANDS和脚本中硬编码的搜索关键词是否准确、有效。有些RSS源对关键词格式有要求。
3. 查看日志：在脚本中添加详细的打印语句，输出每个阶段的结果，比如“正在抓取Google News RSS...”，“收到X条原始数据”，“经过关键词过滤后剩余Y条”。这是定位问题最直接的方法。
4. 检查数据清洗逻辑：可能是关键词密度过滤太严格，或者日期解析出错导致数据被误过滤。

Q4: 前端页面能打开，但列表为空，控制台显示Supabase查询错误。A4:

1. 打开浏览器开发者工具(F12)的“网络”(Network)选项卡，查看对Supabase的请求是否返回了4xx或5xx错误。错误信息会指明原因。
2. 检查Supabase表的行级安全策略(RLS)。默认情况下，新创建的表是启用RLS且没有任何策略的，这意味着前端（使用ANON_KEY）无法读取任何数据。你需要为每个表创建策略，例如：

   -- 在Supabase SQL编辑器中为 `news_items` 表创建允许匿名读取的策略 CREATE POLICY “允许所有人查看新闻” ON news_items FOR SELECT USING (true);

3. 确认查询的字段名与数据库中的列名完全一致，包括大小写。

Q5: 独立HTML页面 (public/*.html) 在本地直接打开时报跨域错误 (CORS)。A5: 这是预期行为。因为esm.sh和你的Supabase请求都是跨域的。本地直接通过file://协议打开HTML文件时，浏览器安全限制会导致失败。解决方案是：

• 通过开发服务器访问：使用npm run dev启动的服务（http://localhost:5173）来访问这些页面，例如http://localhost:5173/research.html。开发服务器会处理这些请求。
• 部署后测试：在真正的Web服务器（如Nginx、或Netlify等托管平台）上，跨域问题会由服务器配置或托管平台自动处理。

Q6: 如何定时自动运行Python锻造脚本？A6: 在生产环境中，推荐以下几种方式：

• Linux服务器Cron Job:crontab -e添加一行：0 2 * * * cd /path/to/clawbeat && /path/to/.venv/bin/python forge.py >> /path/to/logs/forge.log 2>&1(每天凌晨2点执行)。
• GitHub Actions: 在仓库的.github/workflows目录下创建YAML文件，使用schedule触发器，并在Job中配置Python环境、安装依赖、运行脚本。
• 云函数/定时任务: 如前面所述，使用AWS Lambda + CloudWatch Events，或Google Cloud Scheduler + Cloud Functions。

这个项目最吸引我的地方在于它完美地结合了“自动化”与“可解释性”。算法负责从海量信息中挖掘信号，但关键的排序和展示逻辑（如Lead Signal的选择规则、白名单机制）都清晰可见且易于调整。它没有试图用一个黑箱模型解决所有问题，而是构建了一个由规则、算法和人工审核（管理员覆盖）共同作用的透明系统。在实际操作中，最大的挑战往往不是代码本身，而是数据源的稳定性和反爬策略、各API的速率限制与成本控制，以及如何精细地调整内容过滤和评分规则以贴合你所在领域的真实需求。从这个项目出发，你完全可以打造一个属于自己领域的、高度定制化的信息中枢。