1. 从收藏夹吃灰说起这个项目到底要解决什么GitHub 的 Star 功能大概是程序员用得最多、也最容易被忽视的一个按钮。看到有意思的项目随手点个星日积月累下来收藏夹里躺着几百上千个仓库真到要用的时候却一个都想不起来。我自己就有这个毛病收藏夹里从前端框架到数据库工具从爬虫脚本到机器学习教程什么都有但每次需要找某个具体工具时还是习惯性地去搜索引擎重新搜一遍——收藏夹等于白收藏了。这个项目的核心思路很直接用 AI Agent 自动整理 GitHub 收藏夹。具体来说就是让一个智能体定期读取你 Star 过的仓库列表抓取每个仓库的描述、语言、主题标签、Star 数、最近更新时间等元信息然后自动完成分类、打标签、生成摘要、识别过时项目、甚至给出“这个项目值不值得深入看”的判断。最终输出一份结构化的清单你可以按分类浏览也可以直接搜索关键词找到对应的仓库。它解决的是三个层面的问题。第一层是信息过载收藏夹本质是一个无序列表GitHub 官方只提供了按语言和按 Star 时间排序没有自定义分类能力。第二层是记忆衰减你收藏一个项目时的上下文——当时为什么觉得它有用、打算用它做什么——过两周就忘干净了。第三层是维护成本手动整理几百个仓库光是逐个点开看描述就要花掉一整个下午没人愿意干这种活。适合看这篇内容的人有三类。一是收藏夹已经超过 200 个仓库、明显感到管理失控的开发者二是想学 AI Agent 实战、但苦于找不到真实可用场景的人三是平时用 GitHub 做技术调研、需要定期梳理技术选型清单的团队技术负责人。哪怕你只是想给自己的收藏夹做个“体检”这套方法也能直接抄作业。2. 整体方案设计为什么这样搭2.1 核心架构选型与理由整个系统拆成四层数据采集层、AI 处理层、存储层、展示层。这个分层不是拍脑袋定的而是根据实际约束倒推出来的。数据采集层负责从 GitHub 拉取收藏列表和仓库详情。这里有个关键决策用 GitHub 官方的 REST API 还是 GraphQL API。REST API 的/user/starred端点返回的是仓库的基本信息但如果你想要每个仓库的 topics、README 摘要、最近提交时间就得对每个仓库再发一次请求N 个仓库就是 N1 次调用。GraphQL API 可以在一次请求里把仓库列表和每个仓库的详细字段一起拿回来对于收藏夹这种“批量读取”场景GraphQL 明显更合适。我实测下来500 个仓库用 GraphQL 分页拉取大概 10 次请求就能搞定而 REST 方式要发 500 次以上光是等网络往返就要好几分钟。AI 处理层是核心。这里的选择是用大模型做分类和摘要而不是用规则引擎。原因很简单规则引擎需要你预先定义好所有分类标签但收藏夹里的项目类型是开放式的今天收藏一个 Rust 写的 CLI 工具明天收藏一个用 Python 做的数据分析库规则根本覆盖不全。大模型的优势在于它能理解仓库描述的自然语言含义自动归纳出合理的分类比如“前端框架”“数据库驱动”“DevOps 工具”“学习资源”这些标签不需要你提前枚举。存储层用 SQLite 就够了。收藏夹的数据量级在几百到几千条SQLite 单文件存储、零配置、支持全文搜索完全够用。没必要上 PostgreSQL 或 MongoDB那是过度设计。展示层可以是一个静态 HTML 页面也可以是一个简单的命令行工具甚至直接输出 Markdown 文件。我倾向于生成 Markdown因为可以直接丢进 Obsidian 或 Notion 里做二次整理。2.2 为什么用 Agent 而不是一次性脚本有人可能会问这不就是一个脚本干的事吗为什么要套个 Agent 的壳区别在于决策的灵活性。一次性脚本的逻辑是固定的拉数据、调模型、写文件。但实际整理收藏夹时你会遇到各种需要判断的情况。比如某个仓库已经三年没更新了脚本只能标记“过时”但 Agent 可以进一步判断这个项目是已经完成使命的稳定库比如一个不再需要新功能的工具还是真的被废弃了再比如两个仓库功能高度重叠Agent 可以识别出来并建议你保留哪个、归档哪个。Agent 的另一个价值是可扩展的工具调用。整理收藏夹不只是分类还可能涉及检查仓库是否有安全漏洞、对比同类项目的 Star 增长趋势、生成学习路线建议。这些任务需要调用不同的工具比如漏洞数据库查询、趋势数据 APIAgent 架构天然支持动态选择工具而脚本要做到这一点就得写一大堆 if-else。2.3 数据流与处理流程完整的数据流是这样的首先通过 GitHub GraphQL API 拉取当前用户的所有 Star 仓库字段包括名称、描述、主要语言、topics、Star 数、fork 数、创建时间、最后推送时间、是否归档、README 前 500 字。然后对每个仓库做预处理清洗描述文本、提取关键词、计算“活跃度分数”综合最后推送时间和 Star 增长。接着把预处理后的数据分批送给大模型让模型输出分类标签和一句话摘要。最后把结果写入 SQLite并生成一份按分类组织的 Markdown 清单。这里有个细节值得展开为什么要分批而不是一次性把所有仓库丢给模型。大模型的上下文窗口虽然大但一次塞几百个仓库的描述不仅 token 成本高而且模型在长上下文里的分类一致性会下降——前面分类用了一个标签后面可能换了个近义词。分批处理每批 20 到 30 个仓库可以保证同一批内的分类标准一致同时通过 prompt 里携带“已有分类列表”来维持跨批次的一致性。3. 核心细节解析从 API 调用到 Prompt 设计3.1 GitHub 数据采集的关键参数用 GraphQL 拉取收藏列表时有几个参数直接决定了后续处理的效率。第一个是分页大小GitHub GraphQL 单次请求最多返回 100 条记录所以first: 100是标配。第二个是字段选择不要贪多只取后续需要的字段。我试过把 README 全文拉下来结果 500 个仓库的响应体超过了 10MB解析起来很慢。后来改成只取 README 的前 500 个字符足够模型判断项目类型了。第三个是速率限制的处理。GitHub API 对未认证请求限制很严认证后 GraphQL 的配额是每小时 5000 个点。每个仓库查询大概消耗 1 到 2 个点所以 500 个仓库一次拉取完全在配额内。但如果你频繁运行就需要做缓存——把已经拉取过的仓库数据存到本地下次只拉取新增的 Star。判断新增的方式是记录上次拉取的时间戳只查询starredAt晚于该时间戳的仓库。# GraphQL 查询示例简化版 query { viewer { starredRepositories(first: 100, after: %s, orderBy: {field: STARRED_AT, direction: DESC}) { pageInfo { hasNextPage endCursor } edges { starredAt node { nameWithOwner description primaryLanguage { name } repositoryTopics(first: 10) { nodes { topic { name } } } stargazerCount forkCount createdAt pushedAt isArchived object(expression: HEAD:README.md) { ... on Blob { text } } } } } } } 注意README 的获取方式在不同仓库里可能不同有的用 README.md有的用 README.rst还有的放在 docs 目录下。稳妥的做法是先查HEAD:README.md如果返回空再尝试其他常见路径。不过对于分类任务来说仓库描述加上 topics 已经提供了足够的信息README 只是锦上添花。3.2 Prompt 设计的核心要点Prompt 的质量直接决定了分类的准确率。我踩过的坑是一开始只给模型一句“请对这些 GitHub 仓库进行分类”结果模型返回的分类五花八门有的按编程语言分有的按用途分还有的按 Star 数分完全没有统一标准。后来改成结构化 Prompt包含四个部分角色定义、分类体系说明、输出格式要求、示例。角色定义让模型知道自己是一个“技术项目分类助手”分类体系说明里给出推荐的分类维度如“前端开发”“后端框架”“数据库”“DevOps”“机器学习”“学习资源”“工具软件”等但允许模型在遇到无法归类的项目时创建新分类输出格式要求用 JSON每个仓库包含category、tags、summary、maturity四个字段示例给出一到两个完整的输入输出对让模型模仿。这里的关键是maturity字段的设计。我把它定义为一个枚举值active最近半年有更新、stable一年内有更新但功能已完善、stale超过一年未更新、archived已归档。这个字段比单纯的“最后更新时间”更有信息量因为它结合了项目的实际状态。模型在判断时会参考仓库描述里是否有“deprecated”“no longer maintained”等关键词也会看 Star 数和 fork 数的比例——如果一个项目 Star 很高但 fork 很少通常说明它是个资源列表或教程而不是代码库。3.3 分类一致性的保障机制分批处理带来的最大问题是分类不一致。比如第一批里模型把某个项目归为“Web 框架”第二批里类似的项目却被归为“后端开发”。解决这个问题有两个手段。第一个手段是维护一个动态分类列表。每批处理前把当前已经确定的分类列表附在 prompt 里并明确告诉模型“优先使用已有分类只有在确实无法归类时才创建新分类”。这个列表随着批次推进不断增长后续批次的分类会自然向已有分类靠拢。第二个手段是后处理归一化。所有批次处理完后把所有分类名拿出来做一次聚类把语义相近的分类合并。比如“前端框架”和“Web 前端”可以合并“机器学习”和“ML”可以合并。这一步可以用简单的字符串相似度算法也可以再调一次模型做判断。我实测下来经过这两步处理分类的一致性可以做到 90% 以上剩下的 10% 主要是那些本身就跨领域的项目归到哪个分类都说得通。4. 实操过程从零搭建你的收藏夹整理 Agent4.1 环境准备与依赖安装先明确技术栈Python 3.10 以上、GitHub 个人访问令牌、一个大模型 APIOpenAI、Claude 或国内可用的模型服务都行、SQLite。Python 依赖主要是requests或httpx用于发 HTTP 请求sqlite3是标准库自带tqdm用于显示进度条。GitHub 令牌的获取路径是GitHub 设置 → Developer settings → Personal access tokens → Tokens (classic) → Generate new token。需要的权限范围是read:user和public_repo。如果你收藏了私有仓库还需要repo权限。令牌生成后存到环境变量里不要硬编码在代码中。# 设置环境变量Linux/macOS export GITHUB_TOKENghp_xxxxxxxxxxxx export LLM_API_KEYsk-xxxxxxxxxxxx # Windows PowerShell $env:GITHUB_TOKENghp_xxxxxxxxxxxx $env:LLM_API_KEYsk-xxxxxxxxxxxx提示令牌一旦生成就要妥善保管不要提交到 Git 仓库。建议在项目根目录加一个.env文件用python-dotenv加载同时把.env加入.gitignore。4.2 数据拉取与本地缓存实现数据拉取模块的核心逻辑是先查本地数据库里已有的仓库列表和最后更新时间然后只向 GitHub 请求新增的 Star。这样第一次运行会慢一些要拉全部后续运行就很快了。import sqlite3 import requests import os from datetime import datetime def init_db(): conn sqlite3.connect(stars.db) conn.execute( CREATE TABLE IF NOT EXISTS repos ( full_name TEXT PRIMARY KEY, description TEXT, language TEXT, topics TEXT, stars INTEGER, forks INTEGER, created_at TEXT, pushed_at TEXT, is_archived INTEGER, starred_at TEXT, category TEXT, tags TEXT, summary TEXT, maturity TEXT, updated_at TEXT ) ) conn.commit() return conn def fetch_starred(cursorNone): token os.environ[GITHUB_TOKEN] headers {Authorization: fBearer {token}} query ... # 上面定义的 GraphQL 查询 variables {cursor: cursor} resp requests.post( https://api.github.com/graphql, json{query: query, variables: variables}, headersheaders, timeout30 ) resp.raise_for_status() return resp.json()拉取的时候要注意分页。GraphQL 返回的pageInfo.hasNextPage为 true 时把endCursor作为下一次请求的cursor继续拉直到hasNextPage为 false。每拉一页就写入数据库这样即使中途失败下次也能从断点继续。4.3 AI 分类与摘要生成分类模块的核心是把仓库数据组织成模型能理解的格式然后解析模型返回的 JSON。我用的 prompt 模板大致如下PROMPT_TEMPLATE 你是一个技术项目分类助手。请对以下 GitHub 仓库进行分类和摘要。 已有分类列表{existing_categories} 对每个仓库输出以下字段 - category: 从已有分类中选择或创建新分类 - tags: 3-5 个关键词标签 - summary: 一句话中文摘要不超过 50 字 - maturity: active / stable / stale / archived 之一 仓库列表 {repos_json} 请以 JSON 数组格式返回不要包含其他内容。 repos_json里每个仓库只保留必要字段名称、描述、语言、topics、Star 数、最后推送时间、是否归档。描述如果太长就截断到 200 字。模型返回的 JSON 要做校验如果解析失败就重试一次重试时在 prompt 里加上“上次返回的格式有误请确保返回合法的 JSON 数组”。4.4 结果存储与 Markdown 生成所有仓库处理完后从数据库里按分类查询生成 Markdown 文件。每个分类一个二级标题下面用表格列出仓库名称、摘要、标签、成熟度。表格的好处是信息密度高一眼能扫完。def generate_markdown(conn): categories conn.execute( SELECT DISTINCT category FROM repos WHERE category IS NOT NULL ORDER BY category ).fetchall() lines [# GitHub 收藏夹整理\n] for (cat,) in categories: lines.append(f## {cat}\n) lines.append(| 仓库 | 摘要 | 标签 | 状态 |) lines.append(|------|------|------|------|) rows conn.execute( SELECT full_name, summary, tags, maturity FROM repos WHERE category ?, (cat,) ).fetchall() for name, summary, tags, maturity in rows: lines.append(f| [{name}](https://github.com/{name}) | {summary} | {tags} | {maturity} |) lines.append() with open(stars_report.md, w, encodingutf-8) as f: f.write(\n.join(lines))生成的 Markdown 可以直接在 GitHub 上预览也可以导入到笔记软件里。我习惯把它放到 Obsidian 的 vault 里配合 Dataview 插件做动态查询比如“列出所有 maturity 为 stale 的仓库”方便定期清理。5. 常见问题与排查技巧实录5.1 API 调用失败的排查思路最常见的问题是 GitHub API 返回 401 或 403。401 通常是令牌无效或过期检查环境变量是否设置正确。403 一般是速率限制GraphQL 的响应头里会有X-RateLimit-Remaining和X-RateLimit-Reset前者为 0 时说明配额用尽后者是配额重置的时间戳。处理方式是等待重置或者用多个令牌轮换但要注意不要违反 GitHub 的使用条款。另一个坑是网络超时。国内访问 GitHub API 有时会遇到连接超时尤其是在拉取大量数据时。解决办法是设置合理的超时时间比如 30 秒并加重试逻辑。重试时用指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒最多重试 3 次。如果还是失败就把当前进度保存下来下次从断点继续。5.2 模型输出格式不稳定的处理大模型返回的 JSON 偶尔会带 markdown 代码块标记比如json 和或者在中途插入解释性文字。解析前先做清洗去掉代码块标记找到第一个[和最后一个]截取中间部分再解析。如果解析还是失败就把原始返回内容存到日志里人工检查是什么问题。还有一种情况是模型返回的仓库数量和输入不一致。比如输入 20 个仓库模型只返回了 18 个。这通常是因为模型在长列表里“偷懒”了。解决办法是减小批次大小从 30 降到 20 甚至 15。批次越小模型遗漏的概率越低但总调用次数会增加。我实测下来每批 20 个是比较平衡的选择。5.3 分类结果不符合预期的调整方法如果发现模型把明显该归为一类的项目分到了不同类别先检查 prompt 里的分类列表是否足够清晰。比如“工具”这个分类太宽泛模型可能会把 CLI 工具、GUI 工具、在线工具都往里塞。改成“命令行工具”“桌面软件”“在线服务”这样更具体的分类模型的判断会准确很多。另一个调整手段是在 prompt 里加入负向示例。比如告诉模型“不要把教程类项目归入框架类教程类项目应该归入学习资源”。负向示例比正向示例更能纠正模型的系统性偏差。5.4 常见问题速查表问题现象可能原因解决方法API 返回 401令牌无效或未设置检查环境变量重新生成令牌API 返回 403速率限制用尽等待重置或减少请求频率请求超时网络不稳定增加超时时间加重试逻辑模型返回非 JSON输出格式不稳定清洗返回内容重试并强调格式要求分类不一致批次间标准漂移维护动态分类列表后处理归一化仓库遗漏批次过大减小批次大小到 15-20README 拉取失败文件路径不标准只依赖描述和 topics跳过 README实操心得第一次运行建议先用 20 个仓库做小规模测试确认整个流程跑通、模型输出格式稳定后再扩大到全量收藏夹。这样即使出问题排查成本也低得多。6. 进阶玩法让 Agent 真正“下地干活”6.1 自动识别重复与相似项目收藏夹里经常有功能重叠的项目比如同时收藏了三四个 JSON 解析库。Agent 可以通过对比仓库描述和 topics 来识别相似项目并在报告里标注“与 XXX 功能相似建议二选一”。实现方式是在分类完成后对同一分类下的仓库做两两相似度计算可以用简单的 Jaccard 相似度基于 topics 集合也可以再调一次模型做语义判断。6.2 生成学习路线建议对于学习资源类的收藏Agent 可以根据仓库的难度标签和内容类型生成一条建议的学习顺序。比如先看入门教程再看实战项目最后看源码解析。这个功能需要在 prompt 里让模型额外输出一个difficulty字段beginner / intermediate / advanced然后按难度排序。6.3 定期自动运行与变更通知把整个流程封装成一个脚本用系统的定时任务Linux 的 cron 或 Windows 的任务计划程序每周运行一次。每次运行后对比上次的结果如果有新增仓库或分类变化就生成一份变更摘要。变更摘要可以输出到控制台也可以发到自己的笔记软件或消息工具里。这样收藏夹就变成了一个“活”的知识库而不是一个只进不出的黑洞。6.4 与笔记软件的深度集成生成的 Markdown 文件可以直接放到 Obsidian 的 vault 里配合 Dataview 插件做动态查询。比如TABLE summary, tags, maturity FROM github-stars WHERE maturity stale SORT stars DESC这条查询会列出所有标记为 stale 的仓库按 Star 数排序方便你决定哪些可以取消收藏。如果你用 Notion也可以通过 Notion API 把数据同步过去做成一个可交互的数据库视图。7. 一些踩坑之后的个人体会这套方案我从去年开始用前后迭代了四五个版本最大的体会是不要追求一次做到完美。第一版只要能拉取数据、能分类、能生成 Markdown 就够了。用起来之后你自然会发现问题比如分类不够细、摘要太长、某些仓库被遗漏然后再针对性优化。如果一开始就想设计一个完美的分类体系大概率会卡在“分类到底怎么定”这一步迟迟无法落地。另一个体会是模型的选择比 prompt 的优化更重要。我试过用不同规模的模型跑同一套 prompt小模型在分类一致性上明显差一截经常出现同一批里类似项目分到不同类别的情况。如果预算允许建议用中等规模以上的模型做分类任务省下来的调试时间远比模型费用值钱。最后说一个容易被忽视的点收藏夹整理不是目的用起来才是。整理完之后我给自己定了个规矩每周花 10 分钟浏览一遍新生成的报告挑一个之前收藏但一直没看的项目花半小时快速过一遍它的 README 和示例代码。这样收藏夹才真正变成了一个持续产生价值的知识库而不是一个自我安慰的“稍后阅读”坟场。