构建自进化AI项目导航站：自动化发现与智能评估实践-编程实验室

1. 项目概述：一个能自我进化的AI项目导航站

如果你和我一样，每天都会花不少时间在GitHub上“淘金”，寻找那些真正有用、高质量的AI开源项目，那你肯定也经历过这种痛苦：信息过载。每天都有成百上千个新仓库冒出来，标题个个都写着“革命性”、“SOTA”、“最强”，但点进去一看，要么是几个月没更新的“僵尸项目”，要么是文档稀烂、根本跑不起来的玩具。手动去筛选、分类、跟踪这些项目的活跃度，简直是个不可能完成的任务。

Hello-AI这个项目，就是冲着解决这个痛点来的。它不是一个靠人工维护的静态链接列表，而是一个由AI驱动的、能够自我发现、自我评估、自我更新的智能导航系统。你可以把它理解为一个7x24小时不间断工作的“AI猎头”，它的任务就是在GitHub的汪洋大海里，自动打捞那些真正有价值的“珍珠”，然后分门别类地摆在你面前。更关键的是，这个系统是开源的，你可以完全部署在自己的机器上，按照你的兴趣和需求，定制一个专属的AI项目知识库。

它的核心价值在于“自动化”和“智能化”。传统导航站依赖人工提交和审核，更新慢、覆盖面有限，且容易带有主观偏见。Hello-AI则通过一套精心设计的自动化流水线，结合大语言模型的判断力，实现了从项目发现、质量评估、分类归档到前端展示的全流程无人值守。它甚至能“学习”：当发现新的技术领域关键词时，会自动将其加入探索列表，让知识库的边界不断向外扩张。

2. 核心架构与执行逻辑拆解

要理解Hello-AI如何工作，我们需要把它拆解成几个核心的、环环相扣的自动化层。整个系统就像一个精密的数据工厂，原料是GitHub的海量数据，产品是结构清晰、质量可控的项目目录。

2.1 动态自进化发现层：永不停止的“探矿机”

这是整个流水线的起点，目标是源源不断地发现新的潜在优质项目。它的运作基于一个名为data/topics.json的“知识池”文件。

初始种子与探索策略：topics.json里预置了一系列初始的技术主题，比如“machine-learning”、“llm”、“rag”。系统会为每个主题记录一个“最后探索时间”和“质量分数”。脚本运行时，会根据配置的排序策略（--sort-topic-by参数）来决定先探索哪个主题。如果选择time策略，它会优先探索那些最久没被探索过的主题，确保覆盖的广度；如果选择quality策略，则会优先探索历史上产出优质项目多的主题，提高发现的“命中率”。

智能爬取与队列缓冲：针对选中的主题，脚本会调用GitHub的搜索API，按照星标数（默认>=500）进行过滤，一页一页地抓取项目。这里有两个关键设计：一是分页抓取有上限（通过MAX_PAGES_DEFAULT和MAX_PAGES_QUALITY控制），防止在某个过于宽泛的主题上陷入死循环；二是所有新发现的项目并不会直接进入核心数据库，而是被送入一个“待审核队列”——data/pending-projects.json。这个缓冲队列的设计至关重要，它将“发现”和“评估”两个高消耗环节解耦，使得系统更稳健。

知识池的自生长：这是“自进化”的精髓所在。当爬虫从一个项目里提取到topics.json中不存在的新技术标签（比如最近火起来的“moondream”或“function-calling”），系统会判断这个标签是否有价值（例如，出现频率是否够高）。如果有价值，它会被自动注册为新的二级探索目标，并赋予一个初始质量分。这意味着，Hello-AI的知识边界不是固定的，它会随着AI领域的发展而自动扩展，去探索那些它原先“不知道”但正在兴起的技术点。

2.2 本地/云端AI批量评估引擎：严格的“质检员”

待审核队列里的项目只是“候选人”，能否“转正”进入核心库，需要经过AI评估官的严格面试。这是整个系统智能化的核心。

批量并发处理：为了提高效率并节约API成本（无论是GitHub API还是LLM API都有频率限制），评估引擎不是一个个处理项目，而是批量进行。EVALUATE_BATCH_SIZE参数控制了一次从队列中取出多少个项目（比如10个），然后将这些项目的基本信息（名称、描述、README片段等）组合成一个大的提示词（Prompt），一次性提交给大语言模型。这种批处理设计能极大减少API调用次数，并充分利用LLM的上下文窗口。

动态分类路由：系统的分类体系不是硬编码在程序里的。每次评估时，脚本会动态地从已审核通过的核心数据库data/projects.json中读取当前所有有效的分类和子分类。然后，它在给LLM的指令中会明确列出这些分类，要求AI将当前批次的每个项目，分配到最合适的一个子分类下。这种设计带来了极大的灵活性：如果你想新增一个“AI for Science”的分类，只需要手动在projects.json里创建一个新的分类条目，后续AI评估时就会自动识别并使用这个新分类。

多维度评估与裁决：AI的任务不仅仅是分类。它需要完成多项工作：

生成优化描述：基于项目的原始描述和README，生成一段更精炼、更具信息量的中文简介。
提取关键标签：提炼出最能代表该项目技术特点的3-5个标签。
评估项目价值：判断该项目是否属于高质量的、值得收录的AI开源项目。
执行分类：将其归入动态获取的分类列表中的某一项。

AI的裁决是最终的。如果一个项目被判定为质量低下、与AI无关或无法归类，它不会被简单丢弃，而是会被移送到一个隔离区——data/rejected-projects/目录下，并生成一份带时间戳的审计日志。这既保证了核心库的纯净，也为后续回顾和调整AI评估标准提供了数据。

客观趋势榜单：为了对抗AI可能存在的“主观偏见”或“热点盲区”，系统还有一个独立的“🔥 Trending”榜单生成逻辑。它会定期（例如每天）对所有项目进行一次客观计算，筛选出近期更新（比如一个月内）且星标数最高的前30个项目，强制将它们放入趋势榜单。这确保了用户总能一眼看到社区当前最活跃、最受关注的项目。

2.3 自动化前端渲染与视图解耦

经过评估和分类的数据存储在projects.json这个JSON文件中，但这还不是最终用户看到的网页。需要有一个前端层将这些数据动态地、美观地呈现出来。

自适应路由呈现：Hello-AI的前端基于VitePress构建。传统的静态站点导航栏和侧边栏往往是硬编码的菜单项。但在这里，VitePress的配置被改写了。在构建时，有一个脚本会去读取projects.json，分析其中所有的分类和子分类结构，然后动态生成VitePress所需的导航和侧边栏配置。这意味着，数据结构的任何增删改查，都会自动、实时地反映在前端界面上，彻底避免了数据与UI不同步的“脏数据”问题。

智能Markdown折叠与陈旧项目清理：这是由npm run ai:generate-docs命令触发的关键步骤。这个脚本会遍历projects.json里的每一个分类和子分类，将属于同一子分类的项目聚合起来，生成一个独立的Markdown文档页面。在生成过程中，它还会执行一项重要的“保洁”工作：根据RECENCY_THRESHOLD_MONTHS（默认24个月）参数，检查每个项目的最后更新时间。如果某个项目超过两年没有更新，它会被标记为“陈旧”，并在生成的页面中被自动过滤掉，不再显示。这保证了导航站展示的始终是一个“活”的、有维护的项目生态，而不是一个包含大量死链的“项目墓地”。

2.4 完整的自动化流水线闭环

将上述所有层串联起来，就形成了一条完整的自动化流水线。你可以通过不同的npm脚本命令，来控制这个流水线的不同环节：

npm run ai:discover-eval：执行一次完整的“发现->评估”单次循环。
npm run ai:loop-eval：启动一个守护进程，以前台或后台方式，以固定的时间间隔（LOOP_INTERVAL_SECONDS）无限循环执行上述过程，实现7x24小时无人值守运行。
npm run ai:update-status：一个“静默”的后台进程，专门负责增量更新已收录项目的元数据，如最新的星标数、最后提交时间等，确保信息不过时。

这个闭环的设计，使得Hello-AI从一个需要手动维护的工具，转变为一个拥有“新陈代谢”能力的有机体。

3. 本地部署与实操指南

理论讲完了，我们来点实际的。把Hello-AI搬到你自己的机器上跑起来，并按照你的想法定制它，才是最有意思的部分。整个过程比想象中要简单。

3.1 环境准备与基础配置

首先，你需要一个Node.js环境，版本18或以上。克隆项目并安装依赖是标准操作：

git clone https://github.com/xxxily/hello-ai.git cd hello-ai npm install

接下来是核心环节——环境变量配置。复制模板文件并编辑它：

cp .env.example .env

打开.env文件，以下几个配置项决定了你的系统能跑多快、多稳：

GITHUB_TOKEN：强烈建议配置。没有Token时，GitHub API对匿名访问有非常严格的速率限制（每小时60次请求），爬几个页面就歇菜了。去GitHub个人设置里生成一个Token（不需要任何特殊权限，只读即可），填在这里，速率限制会大幅提升。
LLM_API_KEY与LLM_PROVIDER：这是AI评估引擎的动力源。系统支持任何兼容OpenAI API格式的模型服务。
- 云端服务：如果你使用OpenAI、MiniMax、DeepSeek等，需要填入对应的API Key，并设置LLM_PROVIDER为openai、minimax或deepseek。
- 本地模型：如果你想零成本运行，或者对数据隐私有要求，可以使用本地部署的Ollama。这时，你可以将LLM_API_KEY设为local-fallback，并将LLM_BASE_URL指向你的Ollama服务地址（如http://127.0.0.1:11434/v1），LLM_PROVIDER设为ollama，LLM_MODEL设为你想用的模型名（如llama3、qwen2.5）。

注意：使用本地小模型（如7B参数的Llama 3）进行评估时，分类和总结的准确性可能会比GPT-4等大模型稍差，可能出现“张冠李戴”的情况。建议初期可以用云端大模型跑通流程、积累一批种子数据，后期再用本地模型进行增量更新和维护，以平衡成本与效果。

批处理大小参数：DISCOVER_BATCH_SIZE（发现批次大小）、EVALUATE_BATCH_SIZE（评估批次大小）等参数，需要根据你的API速率限制和机器性能来调整。批次越大，单次处理效率越高，但消耗的Token也越多，且一旦某个请求失败，重试成本也高。对于刚开始，使用默认值是比较安全的选择。
RECENCY_THRESHOLD_MONTHS：这个参数我建议你根据关注领域来调整。对于发展日新月异的AI前沿领域（如Agent框架），可以设小一点（比如12个月），确保只保留最活跃的项目。对于一些相对稳定、迭代慢的基础设施或工具，可以设大一些（比如36个月）。

3.2 运行策略与高级技巧

配置好后，就可以启动流水线了。根据你的需求，有不同的启动方式：

试运行：执行npm run ai:discover-eval。这会执行一次完整的流程：从topics.json中选一个主题，爬取一批项目，评估，入库。适合初次测试环境是否通畅。
持续运行：执行npm run ai:loop-eval或npm run ai:loop-eval-tui。后者提供了一个终端交互界面，可以让你在每次循环前选择不同的排序策略等参数，更有掌控感。这个模式会让你的系统变成一个永动的“项目发现机器人”。
仅消费队列：如果你之前已经爬取了很多项目在pending-projects.json队列里，但还没来得及评估，可以运行npm run ai:consume-queue。这个命令会专注于清空队列，而不会触发新的GitHub搜索，非常适合在API限额用尽后离线处理已抓取的数据。
增量更新：npm run ai:update-status这个命令非常实用。你可以把它设置成一个每天定时运行的Cron Job。它只会去GitHub查询已入库项目的星标数和最后更新时间，并更新到projects.json中，消耗的API配额极少，却能保持你本地数据库的“新鲜度”。

高级CLI参数的使用场景：

npm run ai:discover-eval -- --sort-topic-by=quality --topic-order=desc：让系统优先探索历史上产出优质项目最多的主题，并且从质量分最高的开始。这是一种“精益”策略，旨在快速填充核心分类。
npm run ai:discover-eval -- --consume-only：当你怀疑GitHub API即将超限，或者只想处理本地队列时使用。
npm run ai:discover-eval -- --resume：如果上次运行意外中断，使用此参数可以从中断的点（记录在data/state.json中）继续探索，避免重复劳动。

3.3 生成静态站点与预览

当AI评估了一批项目，projects.json里有了数据之后，你就可以生成网站并预览了。

# 1. 根据 projects.json 生成分类Markdown文档 npm run ai:generate-docs # 2. 启动本地开发服务器，实时预览 npm run docs:dev

执行npm run ai:generate-docs后，你会发现在docs目录下，生成了以分类和子分类命名的.md文件，里面已经按格式排列好了项目列表。运行npm run docs:dev，浏览器打开http://localhost:5173（具体端口号看终端输出），一个完整的、导航清晰的AI项目导航站就呈现在你眼前了。你可以点击侧边栏，浏览AI为你整理好的各个技术领域的精华项目。

如果需要部署到线上，运行npm run docs:build会在docs/.vitepress/dist生成静态文件，你可以将其部署到任何静态托管服务上。

4. 定制化与深度玩法

Hello-AI的开源魅力在于，你完全可以把它改造成你自己的“私人AI项目雷达”。以下是一些进阶思路：

定制你的知识池：data/topics.json是你的探索起点。你可以大胆地修改它。比如，你只关心“计算机视觉”和“自动驾驶”，那就把其他无关的主题删掉，并添加更细分的标签如“object-detection”、“lane-detection”。你甚至可以导入一份你长期关注的GitHub用户列表，让系统去爬取这些用户Star过的项目，这往往是发现高质量项目的捷径。

调整AI评估标准：评估的逻辑主要在discover-and-evaluate.js中的Prompt定义部分。你可以修改发给LLM的指令。比如，你可以要求AI更关注项目的“文档完整性”或“近期提交频率”，而不仅仅是技术影响力。你还可以让AI为项目打一个1-5分的质量分，并在生成页面时，只展示高于某个分数的项目，从而进一步收紧收录标准。

扩展数据源：目前的发现层完全依赖于GitHub Search API。你可以编写新的“发现器”模块，从其他渠道获取项目信息，例如：

定期爬取Hacker News、Reddit的r/MachineLearning等社区的热门帖子。
订阅ArXiv等论文预印本网站，提取其中提到的官方代码仓库链接。
接入GitHub的Trending API，直接获取每日/每周趋势榜。

将这些来源的数据，统一格式后推入pending-projects.json队列，即可被现有的AI评估引擎处理。

打造专属前端：VitePress的主题和布局是可以高度定制的。你可以修改docs/.vitepress下的配置文件、主题组件，甚至重写整个首页。比如，增加一个“今日推荐”板块，随机展示一个高质量项目；或者增加高级筛选功能，让用户可以按编程语言、许可证类型、最近更新时间等多维度筛选项目。

5. 常见问题与避坑实录

在实际部署和运行Hello-AI的过程中，我踩过一些坑，也总结了一些让系统更稳定高效的经验。

5.1 GitHub API速率限制与优化策略

这是新手最容易遇到的问题。症状是脚本运行一会儿就报错停止，提示“API rate limit exceeded”。

根本原因：GitHub对未认证请求限制极严（每小时60次），即使使用Token，对于搜索API也有频率限制。
解决方案：
1. 必须配置GITHUB_TOKEN：这是底线。
2. 调整爬取策略：合理设置DISCOVER_BATCH_SIZE（比如从默认的30降到10）和MAX_PAGES_DEFAULT（从5降到2）。不要试图一口吃成胖子，慢即是快。
3. 利用LOOP_INTERVAL_SECONDS：在守护进程模式下，增加循环间隔时间（比如从60秒增加到300秒），给API限额恢复留出时间。
4. 善用--consume-only模式：在API限额紧张时，切换到纯队列消费模式，处理已抓取的数据。
5. 分布式爬取思路（高级）：如果你有多台服务器或多个Token，可以尝试修改发现脚本，让它们从topics.json中领取不同的主题进行探索，实现负载均衡。

5.2 LLM API成本与效果平衡

使用云端LLM API进行评估是主要成本来源。

成本控制：
1. 批处理是王道：务必确保EVALUATE_BATCH_SIZE设置合理（如5-10个一批）。将多个项目信息压缩到一个Prompt中，远比逐个调用便宜。
2. 选用性价比模型：评估任务不需要极强的推理能力。使用gpt-4o-mini、claude-3-haiku或国产模型的轻量版，效果足够且成本大幅降低。
3. 本地模型替代：长期运行且数据量巨大时，本地部署的Ollama几乎是零成本方案。虽然小模型可能在复杂分类上偶有失误，但通过后续的“重新评估”脚本（npm run ai:re-evaluate-all）可以修正。
效果提升：
1. 优化Prompt：仔细雕琢discover-and-evaluate.js中的系统指令和用户指令。明确告诉AI你的收录标准（例如，“不收集中小学教程类项目”、“不收录仅包含论文复现代码且无实际应用的项目”）。
2. 提供分类范例：在Prompt中，可以附上几个已经正确分类的项目作为示例（Few-Shot Learning），能显著提高AI分类的准确性。
3. 设置“拒绝”类别：明确告诉AI，如果遇到明显不符合要求的项目（如商业广告、非AI项目、空仓库），直接将其分类到“Reject”或一个特定的“垃圾”类别，便于后续统一处理。

5.3 数据维护与一致性保障

系统运行一段时间后，projects.json文件会变得很大，可能包含数千个项目。维护其健康度很重要。

定期运行陈旧项目清理：npm run ai:generate-docs命令在生成页面时会根据时间阈值过滤，但并不会从projects.json中删除这些项目。你可以定期手动检查，或写一个脚本，将超过RECENCY_THRESHOLD_MONTHS两倍时间的项目移到一个备份文件，保持核心库的紧凑。
处理分类漂移：技术领域在变化，项目的核心属性也可能变化。一个两年前被归类为“计算机视觉”的项目，现在可能更属于“多模态”。定期运行npm run ai:re-evaluate-all可以让所有已收录的项目重新经过最新AI模型的评估，使用最新的分类体系进行重新归类，确保导航的时效性。
备份与版本控制：data/目录下的所有JSON文件（projects.json,topics.json,pending-projects.json）是你的核心资产。建议用Git进行版本管理。每次大规模更新前后，进行提交，这样如果AI某次“抽风”误删了大量好项目，你可以轻松回滚。

5.4 初次运行可能遇到的“冷启动”问题

当你第一次运行npm run ai:discover-eval时，可能会发现评估速度很慢，或者分类不准。

问题：因为初始的projects.json是空的，AI在动态获取分类列表时，得不到任何有效的分类参考。
解决方案：“预热”你的数据库。你可以手动在projects.json里预先创建几个核心分类，并放入几个众所周知的标杆项目（例如，在“Foundation Models”下放入“llama”、“qwen”，在“Agents”下放入“langchain”、“autogen”）。这样，AI在第一次评估时就有可以参考的分类体系了。更简单的方法是，直接去项目的线上站 https://hello-ai.anzz.top 浏览，找到一些你认可的项目，然后参照其格式，手动添加到本地的projects.json文件中。有了几十个高质量的种子项目后，整个系统的运行就会顺畅很多。

运行这样一个自动化的AI项目导航系统，就像养了一个数字园丁。你需要定期“浇水”（补充API Key）、“修剪”（清理陈旧数据）、“施肥”（优化Prompt和分类）。但当你看到它源源不断地为你发现你从未听说过却又极具潜力的开源项目时，这种“开盲盒”般的惊喜感和效率提升，会让你觉得所有的投入都是值得的。它不仅仅是一个工具，更是一个能够伴随AI社区共同成长、不断扩展你认知边界的伙伴。