English | 中文
自动抓取 GitHub Stars，生成 AI 摘要，便于检索。
- 🤖 自动抓取 GitHub 账号 Star 的全部仓库
- 📝 为每个仓库读取 README，调用 AI 生成内容摘要和技术标签
- 🏷️ 标签智能治理：内置
TAG_MAPPING映射库，自动合并同义词、归一化技术栈（如 LLM -> AI 大模型），拒绝标签爆炸（可能效果也不好） - ⚡️ 高效率：支持并发调用 AI 接口，大幅提升处理大量新项目时的速度
- 🗃️ 数据驱动：运行时使用
data/stars.json，发布到gh-pages/data/stars.json，支持二次开发 - 🎨 模版驱动：使用 Jinja2 模版生成 Markdown 和 HTML 静态页面
- ⏭️ 智能增量：新项目调用 AI 总结，旧项目自动同步最新的 Star 数和元数据
- ⏰ GitHub Actions 定时自动运行，cron 表达式自由配置
- 🔄 可选：自动将生成的
stars_zh.md&stars_en.md推送到 Obsidian Vault 仓库 - 🌐 可选：自动同步到 GitHub Pages 分支，支持多语言 (ZH/EN) 切换与页面实时搜索
- 💻 支持任意 OpenAI 格式兼容接口（OpenAI / Azure / 本地 Ollama 等）
graph TD
Start([开始]) --> Trigger{触发方式}
Trigger -- "Actions (定时/手动)" --> Sync[运行 sync_stars.py]
Trigger -- "Local (本地运行)" --> Sync
Sync --> FetchGH[抓取 GitHub Stars]
FetchGH --> Filter{增量检查}
Filter -- "已处理项目" --> UpdateMeta[更新 Star 数/元数据]
Filter -- "新项目" --> FetchRD[获取 README]
FetchRD --> AI[AI 智能摘要/标签]
AI --> Norm[标签治理/归一化]
Norm --> Store[(data/stars.json)]
UpdateMeta --> Store
Store --> Render
Render[[Jinja2 模板渲染]] --> Output
subgraph Output [成果产出]
MD[Markdown 归档]
HTML[HTML 静态搜索页]
end
Output --> Dispatch{同步分发}
Dispatch -- "VAULT_SYNC" --> Obs[推送至 Obsidian Vault]
Dispatch -- "PAGES_SYNC" --> Pages[部署 GitHub Pages]
Obs --> End([完成])
Pages --> End
点击右上角 Fork，将本仓库复制到你自己的账号下。
本项目通过环境变量驱动，配置优先级：GitHub Secrets > .env 文件。
进入仓库的 Settings → Secrets and variables → Actions 进行配置：
🔐 必填项 (Required Secrets/Variables)
GH_USERNAME: 要抓取 Stars 的 GitHub 用户名。AI_API_KEY: 你的 AI 接口 API Key。
📋 可选项 (Optional Variables) 以下参数有内置默认值，通常无需配置：
AI_BASE_URL: AI 接口地址 (默认使用 OpenAI 官方地址)。AI_MODEL: 模型名称 (默认gpt-4o-mini)。OUTPUT_FILENAME: 生成文件的基准名 (默认stars)。VAULT_SYNC_PATH: Vault 里的存放目录 (默认GitHub-Stars/)。PAGES_SYNC_ENABLED: 是否同步到 Pages (默认true)。
Tip
关于 GitHub API 限制：
- 线上运行 (Actions)：工作流会自动注入
GITHUB_TOKEN，额度高达 1,000次/小时，抓取全量 Stars 无压力。 - 本地运行：若不配置
GH_TOKEN，API 限制为 60次/小时。若 Stars 较多，建议在.env中填入GH_TOKEN以提升额度至 5,000次/小时。
- 在仓库根目录，复制
.env.example并重命名为.env。 - 在
.env中填入必填项。
编辑 .github/workflows/sync.yml，修改 cron 表达式：
schedule:
- cron: "0 2 * * 1" # 示例：每周一凌晨 2 点运行进入 Actions → 🌟 GitHub Stars Index同步 → Run workflow，点击运行。
| 变量名 | 类型 | 说明 | 默认值 |
|---|---|---|---|
GH_USERNAME |
必填 | 要同步的 GitHub 用户名 | - |
AI_API_KEY |
必填 | AI 接口 Key | - |
AI_BASE_URL |
可选 | OpenAI 兼容接口地址 | https://api.openai.com/v1 |
AI_MODEL |
可选 | 使用的 AI 模型 | gpt-4o-mini |
OUTPUT_FILENAME |
可选 | 生成 MD/HTML 的文件名基准 | stars |
VAULT_SYNC_ENABLED |
可选 | 是否开启 Obsidian 同步 | false |
VAULT_REPO |
选填 | Vault 仓库 (owner/repo) |
- |
VAULT_SYNC_PATH |
可选 | Vault 同步的目录路径 | GitHub-Stars/ |
PAGES_SYNC_ENABLED |
可选 | 是否开启 GitHub Pages 部署 | true |
MAX_CONCURRENCY |
可选 | AI 并发处理数 (建议 1-10) | 1 |
GH_TOKEN |
建议 | 提升 API 额度，防止限速 | - |
该功能允许你将生成的 Stars 汇总自动推送到你的 Obsidian Vault (或任何其他) GitHub 仓库中，实现笔记软件内的自动更新。
本质是跨仓库自动同步：许多 Obsidian 用户使用 GitHub 仓库来存储和同步笔记。本项目通过 GitHub API，将生成的 Markdown 文件直接推送到你指定的另一个仓库中（你的 Vault 仓库）。
- 准备目标仓库: 确保你的 Obsidian Vault 已经托管在 GitHub 上。
- 创建权限 Token (PAT):
- 访问 Fine-grained PAT 配置页。
- Repository access: 选择 "Only select repositories"，并选中你的 Vault 仓库。
- Permissions: 在 "Repository permissions" 中，设置 Contents 为 Read and write。
- 生成 Token 后，将其存入本项目的 Settings -> Secrets -> Actions 中，命名为
VAULT_PAT。
- 开启同步配置:
- 在本项目的 Settings -> Variables -> Actions 中：
- 设置
VAULT_SYNC_ENABLED为true。 - 设置
VAULT_REPO为你的用户名/仓库名(例如iblogc/my-obsidian-vault)。 - 设置
VAULT_SYNC_PATH为你希望在 Vault 中存放的目录 (例如Reading/GitHub-Stars/)。
- 设置
- 在本项目的 Settings -> Variables -> Actions 中：
- 保存完成: 下次 Action 运行时，生成的
stars_zh.md和stars_en.md将会自动出现在你的 Vault 仓库中。
Tip
本地如何查收？
远程同步完成后，你只需在本地 Obsidian 中使用 Obsidian Git 插件执行拉取 (Pull)，或者手动在仓库目录下 git pull，最新的 Stars 摘要就会出现在你的笔记库中了。
本项目自动生成支持多语言、支持实时搜索的静态网页：
- 确保
PAGES_SYNC_ENABLED=true。 - 运行一次 Action 后，进入 Settings -> Pages。
- Branch 选择
gh-pages，目录选择/(root)，保存。
Important
数据源迁移说明（兼容 Fork）：
- 当前推荐的数据源为
gh-pages/data/stars.json。 main分支中的data/stars.json仅用于首次迁移兼容（例如 Fork 后第一次运行 Action 的回退读取）。- 常规运行不会再把
data/stars.json提交回main。
如果你希望在服务器上长期运行并自动同步，推荐使用 Docker Compose。
复制 .env.example 为 .env 并填写必要信息：
cp .env.example .env
# 编辑 .env 填入 GH_USERNAME、AI_API_KEY 和 GH_TOKENImportant
必须填写 GH_TOKEN：在 Docker 环境中请求 GitHub API 极易触发 Rate Limit。如果不配置 GH_TOKEN，API 限制为 60次/小时，抓取稍多 Stars 就会报错。配置后限额提升至 5,000次/小时。
使用 Docker Compose 一键启动：
docker compose up -d该命令会启动两个容器：
sync: 核心同步脚本。默认每 24 小时 自动抓取并生成一次。你可以在.env中设置SCHEDULE_HOURS来调整间隔。web: 基于 Nginx 的静态服务器，用于展示生成的索引页面。
打开浏览器访问：http://localhost:8080
# 查看同步日志
docker logs -f github-stars-sync
# 立即执行一次强制同步（不等待周期）
docker compose run --rm sync
# 仅更新页面渲染（不调用 AI）
docker compose run --rm sync --render-only# 克隆仓库并安装依赖
git clone https://github.com/iblogc/GithubStarsIndex.git
cd GithubStarsIndex
# 安装依赖
pip install -r requirements.txt
# 或者使用 uv (推荐)
uv pip install -r requirements.txt
# 使用 .env 进行配置
cp .env.example .env
# 编辑 .env 填入 AI_API_KEY 和 GH_USERNAME
# [常规运行] 获取原信息、调用 AI 总结并渲染页面
python scripts/sync_stars.py
# 或者
uv run scripts/sync_stars.py
# [仅渲染模式] 跳过抓取和 AI 总结，仅依据本地 stars.json 极速重新渲染 HTML/MD
python scripts/sync_stars.py --render-only| 文件 | 说明 |
|---|---|
data/stars.json |
运行时临时数据文件（兼容迁移入口） |
templates/ |
Jinja2 生成模版（Markdown/HTML） |
dist/ |
自动生成的本地成品（HTML / MD） |
scripts/sync_stars.py |
核心同步与生成脚本 |
.github/workflows/sync.yml |
GitHub Actions 定时工作流 |
.env.example |
配置示例文件 |
为了保证程序能够顺畅抓取你的全部 Stars，建议申请一个具有只读权限的人员访问令牌（Personal Access Token）。
- 访问 GitHub Fine-grained PAT 页面。
- Token name: 填写
Stars-Index-Sync(或任意你喜欢的名字)。 - Expiration: 建议选择
90 days或Custom。 - Resource owner: 选择你的个人账号。
- Repository access: 选择
Public Repositories (read-only)即可，或者选All repositories。 - Permissions: 无需额外特殊权限，默认的公共访问权限已足够抓取 Stars 列表。
- 点击 Generate token，立即复制并保存该 Token。
- 将此 Token 填入
.env文件的GH_TOKEN字段中。
Tip
如果你也开启了 Obsidian 同步 (Vault Sync)，可以直接复用具有写入权限的 VAULT_PAT 作为 GH_TOKEN。