GitHub Star Tools

面向个人使用的 GitHub 仓库收藏管理器，以「Agent Skill」形式提供，可在 Claude Code / Codex / WorkBuddy 等 AI 工具中无缝使用。

当你在浏览网页、读文章、看教程时遇到好用的 GitHub 仓库，不必再随手点个 Star 然后永远忘记它。这个工具帮你把仓库结构化地收藏到本地数据库，按「一级分类 + 二级分类」整理（例如：视频 → 视频编辑 / 视频搬运 / 视频二创），并支持批量导入、按链接收藏、Trending 推荐、关键词检索。

所有脚本仅使用 Python 标准库（无 pip install），因此同一份代码可在任意装有 Python 3 的 AI 工具中直接运行；同一台机器上的多个工具还会共享同一份收藏数据（~/.github-star-tools/）。

功能特性

#	能力	一句话说明
1	初始化 `init_db.py`	第一次使用必做：创建本地数据库与配置（幂等，可安全重复执行）
2	批量导入 `import_repos.py`	从 Markdown / TXT（或 URL 列表）中提取 GitHub 链接，自动获取元信息、归类、入库
3	单仓库收藏 `add_repo.py`	给定一条仓库地址，自动分类并入库
4	趋势推荐 `trending_recommend.py`	基于 GitHub Trending 榜单，推荐 5–10 个你尚未收藏的仓库
5	搜索 `search.py`	按关键词/需求在本地库匹配并排序；支持「本地 + 远程」混合模式

附加能力：

两层分类：视频 / 编程 / AI / 小说阅读 / 图片 / 音频音乐 / 游戏 / 文档知识 / 设计 / 网络爬虫 / 安全 / 数据 / 工具 / 学习 / 移动，每个一级分类下细分 3–8 个二级分类（详见分类体系）。
一个仓库支持多个分类：自动归类最多返回 3 个（一级+二级）组合，也能手动用逗号一次指定多个（如 视频,AI）；分类以多对多方式存储（见数据存储）。
可编辑分类法：分类规则集中在 references/categories.json，你随时可增删分类、调整关键词，脚本自动生效。
中文简介：仓库默认简介取自 GitHub API，可联网获取后由 AI 用 update_repo.py 写入更贴合的中文介绍。
Markdown 报告：导入 / 搜索 / 推荐的结果都可导出为 Markdown 报告，便于归档与回看。

目录结构

github-star-tools/
├── SKILL.md                 # 技能说明（供 AI 工具读取，含跨工具指令）
├── README.md                # 本文档
├── LICENSE.txt              # 许可协议
├── scripts/                 # 全部使用 Python 标准库，无第三方依赖
│   ├── init_db.py           # 能力 1：初始化本地库
│   ├── import_repos.py      # 能力 2：批量导入
│   ├── add_repo.py          # 能力 3：单仓库收藏
│   ├── trending_recommend.py# 能力 4：趋势推荐
│   ├── search.py            # 能力 5：搜索
│   ├── update_repo.py       # 辅助：修正分类 / 简介 / 标签
│   ├── db.py                # 共享：配置、SQLite、URL 归一化、去重
│   ├── github_api.py        # 共享：GitHub REST API 与 Trending 抓取（urllib）
│   └── classify.py          # 共享：两级分类逻辑
└── references/
    ├── categories.json      # 分类法（一级 + 二级），可自由编辑
    └── schema.md            # 数据库表结构与评分规则参考

收藏数据存放在 ~/.github-star-tools/（不在技能包内，纯个人数据）：

~/.github-star-tools/
├── config.json              # 数据目录、GitHub Token、默认推荐数、分类法路径
├── repos.db                 # SQLite 收藏库
└── reports/                 # 导入/搜索/推荐导出的 Markdown 报告

安装与部署

本技能是跨工具通用的，无需安装任何依赖。把整个 github-star-tools/ 目录放到对应工具的 skills 目录即可：

工具	放置位置
Claude Code	项目的 `.claude/skills/` 或用户级 skills 目录
Codex	对应的 skills 目录
WorkBuddy	`~/.workbuddy/skills/`（用户级）或项目内 `.workbuddy/skills/`

也可直接使用仓库根目录的 github-star-tools.zip 分发包，解压后将目录拷入上述位置。

放置后，在对话中直接告诉 AI 你的意图（例如「把我这份笔记里的 GitHub 仓库收藏起来」「推荐几个今天 trending 的 AI 项目」），AI 会调用对应脚本完成。

快速开始

⚠️ 第一步必须先初始化，之后才能使用其他能力。

cd github-star-tools
python3 scripts/init_db.py

可选参数：

# 指定 GitHub Token（提升速率限制、启用远程搜索/混合模式）
python3 scripts/init_db.py --token ghp_xxx

# 修改默认推荐数量（5–10，默认 7）
python3 scripts/init_db.py --top 10

# 指定数据目录（默认 ~/.github-star-tools）
python3 scripts/init_db.py --data-dir /path/to/data

# 强制重建 config.json（已有配置会被覆盖）
python3 scripts/init_db.py --force

初始化成功后即生成 ~/.github-star-tools/config.json 与空的 repos.db。

使用指南

所有脚本都从技能目录运行，用 python3（Python 3.8+）。

能力 1 · 初始化（必做第一步）

见上方快速开始。

能力 2 · 从文件批量导入

支持从 .md / .txt 文件中正则提取 GitHub 链接，或从 URL 列表导入；每个仓库会自动获取元信息、按两级分类归库，并写入 Markdown 报告。

# 从 Markdown / TXT 文件导入
python3 scripts/import_repos.py --file notes.md

# 指定全部强制分类（逗号可多个；仅在你确信它们都属于这些类时使用）
python3 scripts/import_repos.py --file notes.md --category "视频,AI" --subcategory "视频编辑,图像生成"

# 从逗号分隔的 URL 列表导入
python3 scripts/import_repos.py --urls "https://github.com/owner/repo1,https://github.com/owner/repo2"

# 从一个 URL 文件导入（每行一个）
python3 scripts/import_repos.py --urls-file list.txt

# 覆盖更新已存在的仓库
python3 scripts/import_repos.py --file notes.md --overwrite

# 导出报告到指定路径
python3 scripts/import_repos.py --file notes.md --export report.md

自动归类会为每个仓库返回最多 3 个分类组合（例如一个 AI 视频编辑器可能同时归入「视频 / 视频编辑」与「AI / 图像生成」）。用 --category / --subcategory 的逗号列表可手动指定多个，二者按位置配对（--category "视频,AI" 对应 --subcategory "视频编辑,图像生成"）。

关于 PDF：纯标准库解析 PDF 不可靠，因此设计上由 AI 工具原生读取 PDF、提取其中的 GitHub 链接后，再通过 --urls 或 --urls-file 传入脚本，无需脚本解析 PDF。

导入后，仓库的 summary 默认取自 GitHub API 描述。如需更贴的中文介绍，见修改收藏。

能力 3 · 单个仓库收藏

python3 scripts/add_repo.py --url https://github.com/owner/repo

自动归类（最多 3 个分类组合）并入库。可覆盖自动分类与简介：

python3 scripts/add_repo.py \
  --url https://github.com/owner/repo \
  --category "视频,AI" --subcategory "视频编辑,图像生成" \
  --summary "一个基于 ffmpeg 的跨平台视频剪辑工具" \
  --tags "剪辑,开源"

已收藏的仓库会被跳过（不会重复入库）；想修改请用 update_repo.py。
若 GitHub 上仓库已改名/迁移，脚本会以 API 返回的规范名入库，保证 add / import / trending 三方的去重一致（例如 facebook/react 会存为 react/react）。

能力 4 · 趋势推荐

抓取 https://github.com/trending，过滤掉你已收藏的仓库，按 Star 数推荐 5–10 个。

# 每日榜（默认）
python3 scripts/trending_recommend.py --since daily

# 每周 / 每月榜
python3 scripts/trending_recommend.py --since weekly
python3 scripts/trending_recommend.py --since monthly

# 指定语言与推荐数量
python3 scripts/trending_recommend.py --language python --top 10

# 导出推荐报告
python3 scripts/trending_recommend.py --top 8 --export trending.md

网络兜底：GitHub 没有提供官方 Trending API，脚本靠抓取网页 HTML（选择器集中在 scripts/github_api.py 的 parse_trending 中，便于跟随改动）。若抓取失败，请让 AI 用 WebFetch 打开 https://github.com/trending?since=daily（可加 /<语言>），拿到链接后用 --urls 兜底：
python3 scripts/trending_recommend.py --urls "https://github.com/owner/repo1,https://github.com/owner/repo2"

推荐结果会为每条仓库附上建议的「一级 / 二级」分类，供你参考。

能力 5 · 搜索

# 本地按相关度搜索
python3 scripts/search.py "视频剪辑工具"

# 限制到某个一级 / 二级分类（"包含"匹配：仓库可有多分类）
python3 scripts/search.py "剪辑" --category 视频
python3 scripts/search.py "下载" --subcategory 视频搬运

# 本地 + 远程混合模式（需 GitHub Token 才能稳定调用远程搜索）
python3 scripts/search.py "video editor" --hybrid --token ghp_xxx

# 控制数量、导出报告
python3 scripts/search.py "AI 推理部署" --limit 5 --export search.md

本地模式：对每条收藏按加权相关度打分（见搜索原理），从高到低排序。
混合模式（--hybrid）：额外调用 GitHub 搜索 API，合并结果并去重，每条标注 [LOCAL]（本地已有）/ [REMOTE]（远程新发现）/ [已收藏]。
不传 query（空串）时按 Star 数排序返回。

修改已收藏的仓库

python3 scripts/update_repo.py \
  --url https://github.com/owner/repo \
  --category 游戏 --subcategory 游戏引擎 \
  --summary "Godot 是开源的 2D/3D 游戏引擎" \
  --tags "游戏引擎,开源"

分类会被整体替换：--category / --subcategory 会覆盖该仓库已有的分类。若想追加而不是替换，加 --append（逗号列表可一次加多个，按位置配对）：

# 在现有分类基础上，再追加「编程 / 框架库」
python3 scripts/update_repo.py --url https://github.com/owner/repo \
  --category 编程 --subcategory "框架/库" --append

不传 --category 时只打印当前分类、不做改动。
支持用原链接修改已改名/迁移的仓库（如 facebook/react 会以规范名 react/react 定位）。
可用于修正自动分类、补充中文简介或重设标签。

分类体系（两级）

分类法保存在 references/categories.json（唯一真源），采用 一级分类 + 二级分类 层级结构。脚本按 keywords 做子串匹配（中英文均不区分大小写）来分类；AI 也可用 --category / --subcategory 显式指定。

当前内置的 15 个一级分类及部分二级分类（节选）：

一级分类	二级分类（示例）
视频	视频创作、视频编辑、视频搬运、视频二创、视频转码处理、视频播放、直播推流、字幕配音
编程	编程语言/编译器、框架/库、CLI/终端、IDE/编辑器、构建/部署、代码质量
AI	大模型/LLM、Agent、RAG/知识库、图像生成、语音/音频AI、训练/微调、推理部署、提示词/调优
小说阅读	阅读器、小说下载/爬取、网文/轻小说、电子书管理
图片	图片处理、图片生成、图标/插画、OCR/识别
音频音乐	音频处理、音乐生成、语音/配音
游戏	游戏引擎、模组/工具、模拟器、独立游戏
文档知识	笔记、文档生成、思维导图/白板、幻灯片/PPT
设计	UI/UX、原型/设计稿、3D/建模、动效/动画
网络爬虫	爬虫/抓取、代理/翻墙、下载器、HTTP/API
安全	渗透/漏洞、密码学、鉴权/权限
数据	数据库、数据分析/可视化、ETL/管道
工具	效率/自动化、文件管理、系统工具、其他（兜底分类）
学习	教程/课程、面试题/刷题
移动	Android、iOS、跨平台

分类打分逻辑：一级分类得分 = 自身关键词命中数 + 0.5 × 其最佳二级分类命中数。因此即便只命中二级关键词（如「剪辑」），也能正确归到对应的一级分类（视频），再细到二级（视频编辑）。无匹配时落入兜底分类「工具 / 其他」。

一个仓库可归属多个分类：classify_multi() 会返回按得分排序、去重后的多个（一级, 二级）组合（默认最多 3 个）。所有分类以多对多方式存储在 repo_categories 表中（repos 表的 category / subcategory 仅保留第一个作为主分类用于快速展示）。因此搜索时命中仓库的任一分类都会提升相关度，--category 过滤也按「包含」语义工作。手动指定时用逗号分隔（--category "视频,AI"）即可一次写入多个。

自定义分类：直接编辑 references/categories.json 即可新增/删除一级或二级分类、调整 keywords，保存后立即对后续分类生效。

数据存储

配置 config.json 字段：

字段	说明
`data_dir`	数据目录（默认 `~/.github-star-tools`）
`github_token`	可选的 GitHub Token（提升速率、启用远程/混合搜索）
`default_top`	默认推荐条数（5–10，默认 7）
`taxonomy`	分类法文件路径（默认读取技能内 `references/categories.json`）

repos.db 的 repos 表核心字段：

字段	说明
`full_name`	仓库规范名 `owner/repo`（唯一键，用于去重）
`url`	规范仓库地址
`name` / `owner`	仓库名 / 拥有者
`description` / `topics`	原始描述 / 主题标签（JSON 数组）
`category` / `subcategory`	主分类（仅第一个分类，用于快速展示；该仓库的全部分类见 `repo_categories`）
`summary`	中文简介（可由 AI 经 `update_repo.py` 写入）
`stars` / `language`	Star 数 / 主语言
`created_at` / `pushed_at`	仓库创建 / 最近推送时间
`imported_at` / `source` / `tags`	入库时间 / 来源(add/import) / 自定义标签

此外还有 repo_categories 多对多表：(id, repo_id, category, subcategory)，保存每个仓库的全部分类组合（一个仓库可有多行）。repos.category / repos.subcategory 只是其中的第一个。相关辅助函数见 db.py：set_repo_categories / get_repo_categories / all_repo_categories / repo_full_names_with_category。

数据库通过 ALTER TABLE 与回填逻辑做向后兼容迁移：旧库（v1/v2）打开时会自动补上 subcategory 列，并把原有主分类回填进 repo_categories，无需手动处理。详见 references/schema.md。

搜索与推荐原理

分词：查询文本拆成「拉丁词（含数字与下划线）+ 单个汉字」，再用子串匹配判断每个 token 是否出现在字段中（无需中文分词器，召回合理但偏字面）。
加权打分（本地搜索）：name 3.0、topics 2.0、category（该仓库全部分类的一级名 + 二级名 + 两级关键词）2.0、description 1.5、summary 1.0、tags 1.0。同分时按 Star 数降序。
混合模式：本地匹配排在前面（按相关度），远程结果（GitHub 搜索 API，按 Star 排序）接在后，按 full_name 去重并标注来源。
推荐：Trending 抓取结果过滤掉本地已收藏项，按 Star 排序取前 N（5–10）。

配置与速率限制

匿名 GitHub API：限 60 次/小时（搜索 API 限 10 次/分钟）。个人收藏导入/搜索基本够用。
配置 Token：在 init_db.py --token <TOKEN> 时写入，或编辑 config.json 的 github_token 字段，或使用 search.py --token。Token 可提升速率并启用远程搜索与混合模式。
导入脚本在每次请求间有约 0.4s 的礼貌性间隔，避免频繁打 API。

注意事项与限制

Trending 抓取较脆弱：GitHub 无官方 Trending API，依赖网页 HTML，结构变动或网络受限时会失败；此时请用 WebFetch + --urls 兜底（见能力 4）。
中文搜索偏字面：采用「分词 + 子串」近似匹配（无分词器），召回合理但不如专用检索引擎精准。
收藏数据是个人数据：~/.github-star-tools/ 不在技能分包内，不会随技能分发；重装/迁移机器时需另行备份该目录。
PDF 由 AI 原生读取：脚本不解析 PDF，由 AI 工具读取后通过 --urls 传入链接。
脚本只依赖标准库：运行需 Python 3.8+，无需 pip install。

常见问题（FAQ）

Q：多个 AI 工具会共用同一份收藏吗？ A：会。只要它们在同一台机器上，且数据目录都指向默认的 ~/.github-star-tools/，收藏就会共享。

Q：我想加一个二级分类（比如「视频 / 虚拟主播」）怎么办？ A：编辑 references/categories.json，在「视频」的 subcategories 里加一项并填 keywords 即可，保存后自动生效。

Q：GitHub 上改了仓库名，会重复收藏吗？ A：不会。脚本统一以 API 返回的规范名入库，改名前后去重一致。

Q：Trending 抓取一直失败？ A：多为网络或页面结构变化。请让 AI 用 WebFetch 打开 https://github.com/trending，把候选链接整理后用 trending_recommend.py --urls "<链接1>,<链接2>" 兜底。

Q：搜索结果为空或不够准？ A：可换用更具体的关键词；需要更大范围时用 --hybrid 混合远程搜索；也可直接用 update_repo.py 给仓库补 tags 提升匹配。

许可

本项目以 MIT 风格许可分发，完整条款见 LICENSE.txt。

更新日志

v1.0.0：实现五大能力、SQLite 本地库、可编辑分类法、跨工具兼容（Claude Code / Codex / WorkBuddy）。
分类体系升级：从单级分类升级为「一级分类 + 二级分类」两级分类，repos 表新增 subcategory 列（向后兼容迁移）。
v1.1.0：支持一个仓库归属多个分类。新增 repo_categories 多对多表；classify_multi() 自动归类最多 3 个分类组合；--category/--subcategory 支持逗号分隔指定多个；update_repo.py 新增 --append 追加模式；搜索 --category/--subcategory 改为「包含」过滤。旧库自动迁移。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

GitHub Star Tools

功能特性

目录结构

安装与部署

快速开始

使用指南

能力 1 · 初始化（必做第一步）

能力 2 · 从文件批量导入

能力 3 · 单个仓库收藏

能力 4 · 趋势推荐

能力 5 · 搜索

修改已收藏的仓库

分类体系（两级）

数据存储

搜索与推荐原理

配置与速率限制

注意事项与限制

常见问题（FAQ）

许可

更新日志

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.workbuddy/memory		.workbuddy/memory
references		references
scripts		scripts
LICENSE.txt		LICENSE.txt
README.md		README.md
SKILL.md		SKILL.md

Folders and files

Latest commit

History

Repository files navigation

GitHub Star Tools

功能特性

目录结构

安装与部署

快速开始

使用指南

能力 1 · 初始化（必做第一步）

能力 2 · 从文件批量导入

能力 3 · 单个仓库收藏

能力 4 · 趋势推荐

能力 5 · 搜索

修改已收藏的仓库

分类体系（两级）

数据存储

搜索与推荐原理

配置与速率限制

注意事项与限制

常见问题（FAQ）

许可

更新日志

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages