1. 为什么我要折腾 GitHub 收藏夹自动整理这件事GitHub 的 Star 功能大概是所有开发者用得最频繁、也最容易被忽视的一个功能。你看到一篇不错的开源项目点个 Star刷到某个工具库觉得以后可能用得上点个 Star同事在群里甩了个链接顺手也 Star 一下。一年下来收藏夹里躺着三五百个项目是常态多的上千也不稀奇。问题是这些 Star 一旦攒起来基本就等于进了黑洞。GitHub 自带的 Star 列表只支持按时间排序顶多给你一个搜索框你想按语言筛选、按用途分类、按活跃度排序统统做不到。更别提很多人 Star 完就再也没打开过等到真正需要某个轮子的时候翻半天翻不到最后只能重新去搜搜到的还是同一个项目然后再 Star 一次——收藏夹里出现重复项这种事我干过不止一回。我自己的账号里当时有 800 多个 Star横跨前端、后端、运维、AI、爬虫、各种乱七八糟的工具。每次想找点东西都得靠记忆去搜关键词效率极低。后来我试过手动整理建了几个 List分了大概几十个项目就放弃了——太累了而且新 Star 的项目还是会源源不断地堆进来手动维护根本跟不上。所以我就想能不能用 AI Agent 把这活儿自动化掉。核心思路很简单定时拉取我的 Star 列表让 AI 读每个项目的描述和 README自动打标签、分类、生成摘要然后写回 GitHub 的 List 或者输出成一份结构化的 Markdown 清单。这样我既不用手动整理又能随时按分类找到想要的项目。这篇文章就是我把这套东西从零搭起来、踩了一堆坑之后的完整记录。适合有基本 Python 能力、用过 GitHub API、对 AI Agent 有初步了解的读者。如果你只是想找个现成工具用那可能得再等等目前我没看到特别成熟的方案但如果你想自己搭一套或者想理解 AI Agent 在真实场景里怎么落地这篇应该能给你不少参考。2. 整体方案设计与技术选型思路2.1 需求拆解到底要自动化哪些环节在动手写代码之前我先把整个流程拆成了几个独立的环节每个环节单独考虑用什么方案最合适。第一个环节是数据获取。需要从 GitHub 拿到我所有的 Star 项目包括项目名、描述、主要语言、Star 数、最后更新时间、Topics 等元信息。这部分用 GitHub 官方的 REST API 就能搞定不需要 AI 介入。第二个环节是内容理解。光靠项目描述那一句话很多时候判断不出这个项目到底是干嘛的。比如一个项目描述写的是 A fast build tool你根本不知道它是给前端用的还是给 Rust 用的。所以需要抓取 README 的前若干行让 AI 结合描述和 README 一起判断。第三个环节是分类与打标。这是 AI 真正发挥价值的地方。我需要它根据项目内容给出一个主分类比如前端框架、数据库、AI 工具、若干标签比如TypeScript、CLI、轻量级以及一句话的中文摘要。第四个环节是结果落地。整理好的数据要能被我方便地使用。我最终选择了两个输出一个是写回 GitHub 的 List这样在 GitHub 网页上就能直接看到分类另一个是生成一份 Markdown 文件方便本地搜索和备份。2.2 为什么选 AI Agent 而不是传统脚本有人可能会问分类打标这种事写一堆 if-else 规则不就行了比如描述里出现 react 就归到前端出现 database 就归到数据库。我一开始也这么想过试了之后发现根本行不通。原因有几个一是项目描述千奇百怪同一个概念有无数种表达方式规则覆盖不全二是很多项目是跨领域的比如一个用 Rust 写的 Web 框架你按关键词匹配可能同时命中Rust和Web到底归哪类三是规则维护成本高每次遇到新类型都得加规则加到最后规则本身就成了一个难以维护的怪物。AI Agent 的优势在于它能理解语义而不是匹配关键词。你给它一段描述它能判断出这个项目的本质用途哪怕描述里一个关键词都没提到。而且它还能处理模糊情况比如一个项目既可以算工具也可以算框架它会根据你的分类体系给出最合理的选择。当然AI 也不是万能的。它会有幻觉会给出不存在的分类会漏掉重要信息。所以我在方案里加了一层校验和兜底逻辑这个后面会详细讲。2.3 技术栈选择与理由最终我用的技术栈是这样的组件选型理由语言Python 3.11GitHub API 生态成熟AI SDK 支持好GitHub 交互PyGithub封装完善省去手写 HTTP 请求AI 调用OpenAI 兼容接口通用性强方便切换不同模型数据存储SQLite轻量单文件方便本地跑定时调度cron简单可靠不需要额外服务输出Markdown GitHub List兼顾线上查看和本地搜索这里重点说一下为什么用 SQLite 而不是直接每次重新拉取。因为 AI 调用是有成本的而且同一个项目没必要反复分析。我把每个项目的分析结果缓存到本地数据库里下次运行时如果项目没更新就直接用缓存只有新 Star 的或者 README 有变化的才重新调 AI。这样既省钱又提速。另外AI 接口我特意选了 OpenAI 兼容格式而不是绑定某一家。因为这类任务对模型能力要求不算特别高用便宜的小模型也能跑哪天想换模型改个 base_url 和 model 名字就行代码不用动。3. 核心环节的细节拆解与实操要点3.1 GitHub Star 数据怎么高效拉取GitHub 的 Star 列表接口是GET /user/starred支持分页每页最多 100 条。这里有几个坑要注意。第一个坑是认证方式。匿名请求有严格的速率限制每小时只有 60 次根本不够用。必须用 Personal Access TokenPAT认证认证后每小时 5000 次基本够用。PAT 的权限只需要public_repo或者更小的read:user就够了不要图省事给全权限。第二个坑是分页处理。800 个 Star 就是 8 页你得循环拉取。而且要注意Star 列表是按 Star 时间倒序排列的如果你在拉取过程中又 Star 了新项目可能会导致分页错位。我的做法是先一次性把所有 Star 拉完存到本地再统一处理避免边拉边处理。第三个坑是README 获取。不是所有项目都有 README有些 README 是图片有些是超长文档。我的策略是只取 README 的前 2000 个字符超过部分截断。因为对于分类判断来说开头部分的信息量已经足够了全文拉取既慢又浪费 token。from github import Github import time def fetch_all_stars(token): g Github(token) user g.get_user() stars [] page 0 while True: batch user.get_starred().get_page(page) if not batch: break for repo in batch: stars.append({ full_name: repo.full_name, description: repo.description or , language: repo.language or , stars: repo.stargazers_count, topics: repo.get_topics(), updated_at: repo.updated_at.isoformat(), }) page 1 time.sleep(0.5) # 避免触发速率限制 return stars注意get_page这个方法在 PyGithub 里是懒加载的如果你直接对它做切片操作可能会触发额外的请求。建议老老实实用循环别耍小聪明。3.2 让 AI 稳定输出结构化分类的提示词设计这是整个项目里最考验功夫的部分。AI 分类的准确率八成取决于提示词写得好不好。我一开始的提示词很随意大概就是请给这个项目分类并打标签。结果 AI 返回的东西五花八门有时候是纯文本有时候是 JSON有时候分类名跟我预想的完全不一样。后来我改成了严格的 JSON 输出格式并且给了明确的分类体系和示例效果才稳定下来。我的提示词结构是这样的你是一个开源项目分类助手。请根据以下项目信息输出一个 JSON 对象。 项目名称{name} 项目描述{description} 主要语言{language} README 摘要{readme_snippet} 请严格按照以下 JSON 格式输出不要输出任何其他内容 { category: 从下面列表中选择一个最合适的分类, tags: [标签1, 标签2, 标签3], summary: 用一句中文概括这个项目是做什么的不超过 50 字 } 可选分类列表 - 前端框架 - 后端框架 - 数据库 - DevOps 工具 - AI 与机器学习 - 命令行工具 - 学习资源 - 其他 标签要求2 到 5 个用英文反映项目的技术栈或特点。这里有几个关键点。一是分类列表要固定不能让 AI 自由发挥否则它会给你造出Web 开发相关工具这种模棱两可的分类。二是要求纯 JSON 输出方便后续解析。三是给 summary 加字数限制不然 AI 会写一大段。即便如此AI 偶尔还是会不听话比如在 JSON 外面加一句好的以下是结果。所以解析的时候必须做容错处理用正则把 JSON 部分抠出来再解析。3.3 缓存与增量更新机制前面提到过AI 调用是有成本的。假设你有 800 个 Star每个项目调一次 AI按现在的价格算下来也得几块钱。如果每天都全量跑一遍一个月就是上百块完全没必要。我的做法是用 SQLite 存每个项目的分析结果key 用full_namevalue 存分类、标签、摘要外加一个updated_at字段记录项目最后更新时间。每次运行时先拉取最新的 Star 列表然后逐个对比如果项目在数据库里不存在或者项目的updated_at变了就重新分析否则直接用缓存。import sqlite3 def get_cached(conn, full_name, updated_at): cur conn.execute( SELECT category, tags, summary FROM projects WHERE full_name? AND updated_at?, (full_name, updated_at) ) row cur.fetchone() if row: return {category: row[0], tags: row[1].split(,), summary: row[2]} return None这样跑下来第一次全量分析可能要十几分钟之后每天增量更新通常只有几个新项目几十秒就搞定了。实操心得updated_at这个字段其实不太准因为有些项目只是改了个 README 的错别字updated_at也会变。如果你特别在意成本可以改成对比 README 内容的 hash只有内容真的变了才重新分析。我图省事没做这么细反正增量更新的量不大。4. 完整实操流程与关键代码实现4.1 环境准备与依赖安装先把环境搭起来。我假设你已经装了 Python 3.10 以上版本并且有一个 GitHub 账号。第一步创建一个虚拟环境别把依赖装到全局去python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate第二步安装依赖pip install PyGithub openai requests第三步准备两个凭证。一个是 GitHub 的 Personal Access Token在 GitHub 设置里的 Developer settings 里生成勾选read:user权限即可。另一个是 AI 服务的 API Key我用的是 OpenAI 兼容接口你换成任何一家支持这个格式的都行。把这两个凭证放到环境变量里别硬编码在代码里export GITHUB_TOKENghp_xxxxxxxx export AI_API_KEYsk-xxxxxxxx export AI_BASE_URLhttps://api.openai.com/v1 export AI_MODELgpt-4o-mini4.2 主流程代码逐段解析整个主流程分四步拉取 Star、对比缓存、调用 AI、输出结果。我把核心代码拆开讲。先看 AI 调用部分。这里的关键是构造一个稳定的请求并且处理各种异常情况from openai import OpenAI import json import re client OpenAI( api_keyos.environ[AI_API_KEY], base_urlos.environ[AI_BASE_URL], ) def analyze_project(project): prompt build_prompt(project) try: resp client.chat.completions.create( modelos.environ[AI_MODEL], messages[{role: user, content: prompt}], temperature0.2, ) text resp.choices[0].message.content return parse_json_safely(text) except Exception as e: print(f分析失败 {project[full_name]}: {e}) return None def parse_json_safely(text): # 先尝试直接解析 try: return json.loads(text) except json.JSONDecodeError: pass # 失败则用正则抠出 JSON 部分 match re.search(r\{.*\}, text, re.DOTALL) if match: try: return json.loads(match.group()) except json.JSONDecodeError: return None return Nonetemperature设成 0.2 是为了让输出更稳定别让 AI 太有创造力。分类这种任务不需要创意需要的是确定性。再看主循环。这里要注意的是AI 调用最好加个并发不然 800 个项目串行跑太慢了。我用concurrent.futures开了 5 个并发实测下来既不会触发速率限制速度也快了不少from concurrent.futures import ThreadPoolExecutor def process_all(stars, conn): results [] to_analyze [] for s in stars: cached get_cached(conn, s[full_name], s[updated_at]) if cached: results.append({**s, **cached}) else: to_analyze.append(s) with ThreadPoolExecutor(max_workers5) as executor: futures {executor.submit(analyze_project, p): p for p in to_analyze} for future in futures: project futures[future] result future.result() if result: save_to_db(conn, project, result) results.append({**project, **result}) return results4.3 输出成 Markdown 和写回 GitHub List结果落地我做了两个输出。Markdown 输出很简单按分类分组每个项目一行def export_markdown(results, pathstars.md): by_category {} for r in results: by_category.setdefault(r[category], []).append(r) with open(path, w, encodingutf-8) as f: for cat, items in sorted(by_category.items()): f.write(f## {cat}\n\n) for item in sorted(items, keylambda x: -x[stars]): f.write(f- [{item[full_name]}](https://github.com/{item[full_name]}) f- {item[summary]} {,.join(item[tags])}\n) f.write(\n)写回 GitHub List 稍微麻烦一点。GitHub 的 List 功能目前没有公开的 REST API只有 GraphQL API 支持。你需要用 GraphQL 的createUserList和updateUserList这两个 mutation。这块代码比较长我就不全贴了核心思路是先创建 List然后批量把项目加进去。注意GitHub List 有数量限制一个账号最多创建 32 个 List每个 List 最多 1000 个项目。如果你 Star 特别多可能需要合并一些分类。4.4 定时任务配置最后用 cron 配一个每天跑一次的定时任务0 3 * * * cd /path/to/project /path/to/venv/bin/python main.py run.log 21凌晨 3 点跑避开白天用网高峰也不影响你白天用电脑。日志重定向到文件方便出问题的时候排查。5. 常见问题与排查技巧实录5.1 AI 分类结果不稳定怎么办这是最常见的问题。同一个项目今天跑出来是后端框架明天跑出来是DevOps 工具。原因通常是提示词不够明确或者模型本身对某些领域理解有偏差。我的解决办法有三个。一是降低 temperature从默认的 1.0 降到 0.2输出会稳定很多。二是在提示词里给示例比如一个用 Go 写的 HTTP 框架应该归到后端框架而不是命令行工具给几个边界案例AI 的判断会准很多。三是加一层校验如果 AI 返回的分类不在预设列表里就强制归到其他并且记录下来方便后续人工复查。5.2 GitHub API 速率限制怎么破即使认证了每小时 5000 次也不是无限的。如果你 Star 特别多加上 README 拉取很容易撞上限。我的经验是拉取 Star 列表本身消耗不大800 个项目也就 8 次请求真正消耗大的是拉 README每个项目一次800 个就是 800 次。解决办法是只对没有缓存的项目拉 README有缓存的直接跳过。另外README 拉取可以延迟处理比如今天拉 200 个明天拉 200 个分几天跑完。反正整理收藏夹不是紧急任务没必要一次性搞定。5.3 项目描述为空或全是英文怎么办有些项目描述是空的有些是纯英文还有些描述写得极其抽象比如 The missing piece of your stack。这种项目 AI 也很难判断。我的处理策略是描述为空时优先看 README 的前几行README 也没有时看项目的 Topics 和主要语言用这些信息兜底。如果实在判断不出来就归到其他并且在摘要里标注信息不足建议人工查看。这样至少不会误分类。5.4 常见问题速查表问题现象可能原因解决方法AI 返回非 JSON提示词不够严格加只输出 JSON约束解析时用正则兜底分类结果飘忽temperature 太高降到 0.2并在提示词里给示例API 报 403Token 权限不足或过期重新生成 PAT确认勾选 read:user拉取速度慢串行请求用线程池并发但别超过 5 个重复分析同一项目缓存 key 不对用 full_name updated_at 做联合 keyList 写不进去GraphQL 权限问题确认 PAT 有userscope5.5 几个我踩过的坑第一个坑是别用repo.get_readme()直接拿内容。这个方法返回的是一个ContentFile对象内容是 base64 编码的你得先解码。我一开始直接把它当字符串用结果 AI 收到的是一堆乱码。第二个坑是并发数别开太大。我一开始开了 20 个并发结果 GitHub API 直接给我返回 429整个任务卡死。后来降到 5 个稳定运行。第三个坑是别在提示词里塞太多 README。我一开始把整个 README 都塞进去结果 token 消耗巨大而且 AI 反而抓不住重点。后来改成只取前 2000 字符效果反而更好。6. 这套方案还能怎么扩展跑通基础版本之后我又想了几个可以继续优化的方向这里也分享一下给想深入折腾的朋友一点参考。第一个方向是加一个 Web 界面。现在的结果是 Markdown 文件和 GitHub List查看还行但搜索和筛选不方便。可以用 FastAPI 加一个简单的页面支持按分类、标签、语言筛选还能全文搜索摘要。这样用起来就顺手多了。第二个方向是接入项目活跃度判断。现在只做了分类但收藏夹里其实有很多项目已经停止维护了。可以定期检查项目的最后提交时间如果超过一年没更新就在摘要里标注可能已停止维护提醒自己别踩坑。第三个方向是做相似项目去重。收藏夹里经常有功能重复的项目比如好几个 JSON 解析库。可以让 AI 对比项目描述找出功能高度重叠的合并展示避免选择困难。第四个方向是支持多账号。如果你有多个 GitHub 账号或者想帮团队整理共享收藏可以把 token 和数据库都做成可配置的一套代码跑多个账号。这些扩展我自己也只做了一部分Web 界面还在写活跃度判断已经加上了。整体来说这套方案的核心价值不在于技术多复杂而在于它真的解决了一个日常痛点。以前我找项目靠记忆和搜索现在打开 Markdown 文件按分类一翻就找到了效率提升非常明显。如果你也在被收藏夹混乱困扰建议先跑一个最小可用版本把拉取和分类跑通再慢慢加功能。别一上来就想着做完美先让它能用再让它好用。